Skip to content

A shared vocabulary: one catalog of names, and granular @unverified #219

Open

Description

@Kinflou

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@1 and comline@2 are 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 conformance profile.rs and in profile.cue.
  • Guarantee names are matched by hand in core's Guarantee, and repeated in the language server.
  • Fuzz targets are listed in fuzz.yml twice, in Cargo.toml, in the README and in the seed generator.

Stages (each useful on its own):

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).

Activity

  1. added
    P2Soon
    toolingCLI, language server, editor
    designNeeds a design decision
    on Nov 9, 2026
  2. Kinflou commented on Nov 9, 2026

    @Kinflou
    MemberAuthor

    Rollout stage 2 (core reads the catalog) done:

    • Add the comline-catalog Rust crate specification#2 adds comline-catalog, the catalog as a no_std Rust crate whose data is generated from the CUE.
    • Read guarantees, facts and spellings from the specification's catalog #236 makes core read it:
      • 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 in diff, compat, unverified and freezing, and the values that logic relies on all come from or are checked against the catalog.
      • Aliases and frozen spellings replace SPELLINGS, and the encoding constants are the catalog's.
      • The official declarations are checked against the catalog.

    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.

  3. Kinflou commented on Nov 9, 2026

    @Kinflou
    MemberAuthor

    Rollout stage 3 (the runtime reads the catalog) done:

    • Hold the runtime's names to the specification's catalog runtime#116 re-vendors the spec at 69d8832 and takes comline-catalog as a path dependency on the vendored spec/rust, so the crate always matches spec/REV.
      • The conformance crate's typed facts and values are held to the catalog, as is every official profile's set of facts.
      • comline-runtime's wire-name constants stay literal, with no dependency, and a dev-dependency test holds each one to the catalog.
    • fuzz: one list of targets, the fuzz crate's [[bin]]s runtime#117 makes the fuzz crate's [[bin]]s the one list of fuzz targets. fuzz.yml's matrix and the report's expect are built from it, and CI checks that the README table matches it.

    Left in the rollout:

  4. moved this from Todo to Design in Comline Development Roadmapon Nov 15, 2026
  5. Kinflou commented on Nov 15, 2026

    @Kinflou
    MemberAuthor

    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.

  6. added
    1.0-blockerMust be done before the 1.0 announcement (docs conduct/readiness.md)
    on Nov 15, 2026
  7. added this to the 1.0 milestone on Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    1.0-blockerMust be done before the 1.0 announcement (docs conduct/readiness.md)P2SoondesignNeeds a design decisiontoolingCLI, language server, editor

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions