Repository navigation
Vocabulary: decide where the catalog lives and its format #220
Description
Part of #219, proposal ComlineProject/docs#162 (The catalog → Where it lives).
Decide where the vocabulary lives and in what format, before anything consumes it. The proposal's options:
| Its own repository | In core |
In docs |
|
|---|---|---|---|
| Dependency order | sits below core, runtime and the generators | no new edges, but runtime would pin core just for names | needs a published artifact |
| Cost | one more repository, rev and CI | lowest | low, but odd for code to depend on |
The proposal suggests its own repository, holding CUE sources (as the conformance specs already use) and generated outputs: a no_std Rust crate, a TypeScript module, and JSON. The generated outputs are checked in CI, the way comline.h is.
Also to settle here:
- How far relations go: plain references only (establishes, keeps, gives up, applies to), with value logic such as
fitkept in code. - How catalog versions relate to conformance spec versions and to the IR format (IR and config formats stable, or versioned with readers for older ones #146).
Leanings (discussion of 2026-11-09)
-
Home: a spec repository. Third parties never edit the catalog; they declare their own entries in
config.idp. What they need is what they implement against, which is the spec. So the catalog goes in one repository with:- the conformance specs (
profile.cue,features.json) and vectors, moved out ofruntime/conformance; - compiler conformance cases;
- generated outputs (a
no_stdRust crate, a TypeScript module, JSON).
It's versioned as the spec. Everyone, this project included, pins it like a third party would. The Rust conformance engine and reference stay in
runtime. - the conformance specs (
-
Format: CUE as the source.
-
Relations: plain references only (establishes, keeps, gives up, applies to, scopes). Logic that compares values (
fit) stays in code that reads the catalog.
Next: create the spec repository (name to choose), then seed it from profile.cue, core's Guarantee and the official encodings.
Settled:
- The repository is named
specification. - Versioning: the spec version and the IR format version stay independent.
- Each frozen version records the spec version it was frozen against.
- The spec is append-only for anything frozen: wire names never change; guarantees, facts and values can be added and deprecated, never removed or redefined.
- This is what lets a newer release read an older one's IR after 1.0 (IR and config formats stable, or versioned with readers for older ones #146).
Activity
Kinflou commentedon Nov 9, 2026
Stage 1 done. ComlineProject/specification is set up with the conformance corpus (specs, vectors, profiles, benches,
features.json) extracted fromruntime/conformanceat2ac8480, with its history. It has a README (the spec, moved from the corpus's README), aVERSIONfile (0.10) and CI (specs/check.sh --check, green). It's the authority from now on.Next, stage 2: runtime, comline-typescript, cli, the Observatory and core repoint to it (vendored at a pinned rev, checked in CI). Stage 3 adds the catalog.
Kinflou commentedon Nov 9, 2026
Stage 2: the consumers now read the corpus from
specification.runtime/conformance/spec/, pinned byspec/REVand checked in CI.SPEC_VERSIONis read from the spec'sVERSION.specification.--corpusdocs and hints.specification(SPEC_REV), with the core at runtime0dffa7a.Next, stage 3: the catalog.
Kinflou commentedon Nov 9, 2026
Stage 2 done: comline-typescript#153 merged, so every consumer now vendors
specification.Stage 3: ComlineProject/specification#1 adds the catalog. It covers the guarantees, the facts and their values, the official encodings with their aliases and frozen spellings, the features, and sets computed from them.
profile.cueandfeatures.jsonare now derived from it, andcatalog/gen/catalog.jsonexports it. CI passes. When runtime re-vendors it,conformance/check.shmust runcuefrom insidespec/, because the CUE module moved to the repository root.Kinflou commentedon Nov 9, 2026
Stage 3 done: specification#1 (the catalog) merged at
f219852, and runtime#114 vendors it (merged,a2d6fe5). Next in the proposal's rollout is core reading the catalog: guarantees, facts and their values, aliases, and the official encodings.Kinflou commentedon Nov 12, 2026
Decided and done:
ComlineProject/specificationrepository.comline-catalogRust crate andcatalog/gen/catalog.json).Stages 1–3 are merged (specification#1, runtime#113/#114, observatory#20, cli#144, comline-typescript#153), and core pins
comline-catalogfrom the spec. Guarantee scopes are incatalog/guarantees.cue, which unblocks #222.