Repository navigation
Open
Labels
1.0-blockerMust be done before the 1.0 announcement (docs conduct/readiness.md)Must be done before the 1.0 announcement (docs conduct/readiness.md)P2SoonSoondesignNeeds a design decisionNeeds a design decisiontoolingCLI, language server, editorCLI, language server, editor
Milestone
Description
Tracks the proposal A shared vocabulary (ComlineProject/docs#162, accepted and merged 2026-11-12): one catalog of the names that several programs agree on, with sets as queries over it, plus an optional granular @unverified that refers to guarantees by name.
Why. Names are string literals copied across repositories. Each repo keeps its own lists of the sets they belong to, and nothing checks that the copies agree:
packed@1andcomline@2are written in runtime (~46 files), core, docs and the language server.- Fact names and their values are listed in core's
encodings/profile.rs, in runtime's conformanceprofile.rsand inprofile.cue. - Guarantee names are matched by hand in core's
Guarantee, and repeated in the language server. - Fuzz targets are listed in
fuzz.ymltwice, inCargo.toml, in the README and in the seed generator.
Stages (each useful on its own):
- Accept the proposal (Proposals: a shared vocabulary, and granular @unverified docs#162), with the catalog's home and format decided (leaning: a spec repo, CUE, plain references): Vocabulary: decide where the catalog lives and its format #220
- Create the spec repository; move the conformance specs and vectors in from
runtime/conformance(see Vocabulary: decide where the catalog lives and its format #220, Vocabulary: runtime names, conformance facts and CI target sets from the catalog runtime#112) - Core reads the vocabulary: guarantees, facts and their domains, official encodings and aliases, annotations, settings keys and diagnostic codes: Vocabulary: core reads guarantees, facts, encodings, annotations and settings keys from it #221
- Runtime and conformance read it, and the CI matrices are generated from its sets: Vocabulary: runtime names, conformance facts and CI target sets from the catalog runtime#112
- The Observatory's expected reports come from vocabulary sets: Expected reports from vocabulary sets observatory#19
- Granular
@unverified: plain or keyed form, scopes, acknowledged once per package along a chain, pinned to the chain, failing closed: Granular @unverified: name guarantees, per-guarantee reasons, narrower scopes #222- Safety: property test against an oracle, and a fuzz target: Guarantee safety: property test against an oracle, and a fuzz target, across package graphs #223
- Compiler conformance cases: Compiler conformance cases for given-up guarantees #224
- Audit every path that judges guarantees (incl. compat and diff don't see a dependency's encoding declarations #206): Audit: no path may judge a guarantee with a partial view #225
- The language server's completion, hover and deprecations come from the vocabulary: Completion, hover and deprecations from the vocabulary language-server#102
- Generated
@unverifieddocs name each guarantee's reason: Generated @unverified docs can't name a third-party encoding's cause generation#93
Rules that hold throughout:
- A published wire name never changes; a rename is a new entry with the old one deprecated.
- Third-party declarations have the same shape and are judged by the same rules.
- Nothing new on the runtime call path.
Related: #121 (the guarantee-marker decision), #124 (keyed annotation values), #146 (IR and config format stability), #171 and #178 (unknown names ignored).
Metadata
Metadata
Assignees
Labels
1.0-blockerMust be done before the 1.0 announcement (docs conduct/readiness.md)Must be done before the 1.0 announcement (docs conduct/readiness.md)P2SoonSoondesignNeeds a design decisionNeeds a design decisiontoolingCLI, language server, editorCLI, language server, editor
Type
Projects
- StatusShow more project fieldsDesign
Activity
Kinflou commentedon Nov 9, 2026
Rollout stage 2 (core reads the catalog) done:
comline-catalog, the catalog as ano_stdRust crate whose data is generated from the CUE.Guarantee's names and descriptions come from the catalog. The enum stays hand-written, and a test holds it to the catalog exactly.ProfileKind::facts, the fact names indiff,compat,unverifiedandfreezing, and the values that logic relies on all come from or are checked against the catalog.SPELLINGS, and the encoding constants are the catalog's.Next in the rollout: the runtime and conformance read it (fact names, features, fuzz and bench target sets). Refusing unknown annotations, settings keys and diagnostic codes (#171, #178) waits until the catalog holds those kinds.
Kinflou commentedon Nov 9, 2026
Rollout stage 3 (the runtime reads the catalog) done:
69d8832and takescomline-catalogas a path dependency on the vendoredspec/rust, so the crate always matchesspec/REV.comline-runtime's wire-name constants stay literal, with no dependency, and a dev-dependency test holds each one to the catalog.[[bin]]s the one list of fuzz targets.fuzz.yml's matrix and the report'sexpectare built from it, and CI checks that the README table matches it.Left in the rollout:
@unverifieddocs (generation#93), and the docs tables.@unverified(Granular @unverified: name guarantees, per-guarantee reasons, narrower scopes #222), which needs keyed annotation values (Typed annotation values: lists, calls and references for any annotation #124).Kinflou commentedon Nov 15, 2026
Audit 2026-11-16: ticked what is done. Stage 1 (docs#162 accepted and merged 2026-11-12; #220 closed), stage 2 of the spec repository (it exists), stage 3 (runtime reads the catalog: runtime#116 and runtime#117; note runtime#112 is still open with a stale 'Blocked on core#220' and its boxes not updated), #224 (core#243, specification#5) and #225 (all findings fixed). Not ticked: core reads the vocabulary (#221 is partly done: guarantees, facts, official encodings by core#236; annotations, settings keys and diagnostic codes need catalog kinds that don't exist yet), granular @Unverified (#222: inner scopes core#265, strict core#267, reasons core#239 and #263 done; chains, pins and IR format 4 are not), #223 (oracle and fuzz target core#244 done; chain and pin cases come with #222), observatory#19, language-server#102, generation#93.