Knowledge catalog, approvals and grounded answers

cttiR ships an immutable, revision-scoped knowledge catalog. It records public exports, statically resolved signatures, S3/S4/S7 declarations, documentation inventories and reviewed workflow approvals for exact package revisions. Generated project code may call only APIs covered by an approval of the revision the project pins.

What is cataloged

inventory <- cttiR::packages()
nrow(inventory)
#> [1] 64
table(inventory$provider)
#> 
#>    CTTIR     imbi standard 
#>       30        1       33
head(inventory[inventory$approved > 0, c("package", "version", "approved", "approved_roles")], 8)
#>                package version approved       approved_roles
#> 1            DescrTab2  2.1.16        1   describe_descrtab2
#> 2               Matrix   1.7-6        1            seurat_v5
#> 3         RColorBrewer   1.1-3        2   figures_accessible
#> 4            S4Vectors  0.50.2        1 bioc_s4,se_tidy_view
#> 5               Seurat   5.5.1        1            seurat_v5
#> 6         SeuratObject   5.4.0       19            seurat_v5
#> 7 SingleCellExperiment  1.34.0        9    bioc_s4,seurat_v5
#> 8 SummarizedExperiment  1.42.0        5 bioc_s4,se_tidy_view

CTTIR packages are indexed from verified public revisions. The standard workflow family (tidyverse components, DescrTab2, ggplot2/patchwork, palettes, model engines, broom, rendering, pipeline and environment tools, Bioconductor containers and Seurat) is indexed from verified CRAN/Bioconductor source archives and the R 4.6.1 distribution.

Evidence levels

Level	Meaning
`static_api_verified`	A literal function definition was parsed; nothing was executed.
`installed_api_verified`	Formals were read from the identical installed version in an isolated process (used where static parsing cannot resolve a constructor-built function).
`reexport_declared`	The export belongs to another package; it is approved only through its owner.
`static_declaration_only`	A literal S4/S7 declaration; dispatch is shown by fixtures, not by parsing.
`workflow_approved`	Covered by a complete reviewed approval of this exact revision.

An approval names the package revision (source_hash), the workflow role and adapter version, the required callables, S3 methods and documented objects, the stored reference topics and package documents, and the passing fixture tests. Any change to the source, including documentation only, produces a new revision that needs a new review; older projects keep their pinned approvals.

approved <- cttiR::search("nlme::lme")
approved[, c("symbol", "verification", "approved")]
#>                    symbol           verification approved
#> 4               nlme::lme      workflow_approved     TRUE
#> 5       nlme::lme.formula    static_api_verified    FALSE
#> 6        nlme::lme.lmList    static_api_verified    FALSE
#> 7        nlme::lmeControl    static_api_verified    FALSE
#> 8         nlme::lmeStruct    static_api_verified    FALSE
#> 1     nlme/S3/lme/formula static_method_verified    FALSE
#> 2 nlme/S3/lme/groupedData static_method_verified    FALSE
#> 3      nlme/S3/lme/lmList static_method_verified    FALSE

The bundled corpus stores the topics and package documents that approvals require. Other documents of the same revision are inventoried with their hashes as indexed_not_bundled; a local cttiR::update() with a reviewed documentation_rights basis can store them.

Grounded answers

ask() reads a question as data, matches it to registered capabilities and exact package::export names, and returns steps, prerequisites, the approved package revisions, citations and a reviewed snippet that validates against the approved function table. It never runs code or calls a model.

answer <- cttiR::ask("Fit a mixed model for repeated measures and get confidence intervals")
answer
#> Supported with approved adapters: std.model.lme, std.effects.broom. 
#> - model: Random-intercept linear mixed model for clustered or longitudinal continuous outcomes [std.model.lme; nlme, stats]
#> - effects: Tidy effect estimates with confidence intervals [std.effects.broom; broom, broom.mixed] 
#> Data requirements (supply user placeholders before execution):
#>  block        capability   role    object   column
#>      1     std.model.lme  input tidy_data         
#>      1     std.model.lme  input tidy_data response
#>      1     std.model.lme  input tidy_data       x1
#>      1     std.model.lme  input tidy_data  subject
#>      1     std.model.lme output       fit         
#>      2 std.effects.broom  input       fit         
#>                                                                                                      expected_class
#>  data.frame with typed columns renamed to the declared aliases; not produced by the import or role-selection blocks
#>                                                                                          numeric continuous outcome
#>                                                                         numeric or factor; reference level reviewed
#>                                                                factor or character identifying the repeated subject
#>                                                                                                                 lme
#>                                        reviewed fitted lm, glm, coxph or lme object with a class-appropriate tidier
#>           placeholder      provided_by
#>  <typed-aliased-data> user placeholder
#>             <outcome> user placeholder
#>           <predictor> user placeholder
#>          <subject-id> user placeholder
#>                          std.model.lme
#>        <fitted-model>    std.model.lme
#> 
#> # INPUT placeholder: supply tidy_data as a typed, aliased data.frame before this block.
#> # Random-intercept mixed model; subject identifies the repeated unit.
#> fit <- nlme::lme(response ~ x1, data = tidy_data, random = ~ 1 | subject, method = "REML",
#>   na.action = stats::na.fail)
#> nlme::fixef(fit)
#> nlme::getVarCov(fit)
#> 
#> # Fixed-effect estimates for a fitted nlme model; cell/group units must be reviewed.
#> broom.mixed::tidy(fit, effects = "fixed", conf.int = TRUE)
#> 5 citations; see $evidence
answer$evidence[, c("package", "export", "verification", "approval")]
#>       package    export                        verification
#> 1        nlme       lme            workflow_approved_export
#> 2       stats   na.fail            workflow_approved_export
#> 3        nlme     fixef            workflow_approved_export
#> 4        nlme getVarCov            workflow_approved_export
#> 5 broom.mixed      tidy workflow_approved_reexport:generics
#>                       approval
#> 1       nlme:3.1-170:model_lme
#> 2        stats:4.6.1:model_lme
#> 3       nlme:3.1-170:model_lme
#> 4       nlme:3.1-170:model_lme
#> 5 generics:0.1.4:effects_broom

Unsupported procedures return a gap and the nearest approved alternatives instead of invented code:

cttiR::ask("Run a Bayesian network meta-analysis with brms")$gaps
#> [[1]]
#> [1] "unsupported_method:bayesian (Bayesian models): no reviewed adapter in this release, so no code is returned; registry candidates: std.model.bayesian; nearest reviewed alternatives (context only, not a substitute): std.model.lm (frequentist fit without priors), std.model.glm_binomial (frequentist fit without priors), std.model.lme (frequentist fit without priors), std.model.coxph (frequentist fit without priors)"
#> 
#> [[2]]
#> [1] "unsupported_method:meta_analysis (meta-analysis and evidence synthesis): no reviewed adapter in this release, so no code is returned; registry candidates: std.synthesis.meta; no reviewed alternative covers this method"
#> 
#> [[3]]
#> [1] "std.model.bayesian (Bayesian regression models): candidate_gap; nearest approved alternatives: std.model.lm, std.model.glm_binomial, std.model.lme, std.model.coxph"
#> 
#> [[4]]
#> [1] "std.synthesis.meta (Evidence synthesis and meta-analysis): candidate_gap; nearest approved alternatives: std.model.lm, std.model.glm_binomial, std.model.lme, std.model.coxph"
cttiR::ask("Does dplyr::old_removed_function exist?")$gaps
#> [[1]]
#> [1] "dplyr::old_removed_function: not in the pinned catalog revision"

The bundled benchmark (inst/benchmarks/ask-cases.json) checks citation correctness, code validity, abstention and injection resistance. Keyword matching is safe but limited on unseen phrasing; the held-out results are recorded in inst/benchmarks/ask-heldout.json.

Updating and rolling back

update() refreshes registered sources into new immutable snapshots and activates them with one pointer change; it never installs packages or changes project pins. Registrations can be local directories, public GitHub repositories, CRAN or Bioconductor packages (remote mode only) or a local R distribution tree. Previews use disposable storage.

options(cttiR.sources = list(
  list(id = "cran-patchwork", cran = "patchwork", documentation_rights = "<reviewed basis>")
))
preview <- cttiR::update(mode = "remote", dry_run = TRUE)
preview$api_diff
preview$approval_diff
applied <- cttiR::update(mode = "remote")
cttiR::rollback_knowledge(applied$previous_id, dry_run = TRUE)

A refreshed revision whose source differs from an approved one keeps no approval until it is reviewed; approval_diff reports such invalidations. Removed exports never fall back to older bundled revisions.