[Kinflou]

Stage 3 of ComlineProject/core#220, and the first stage of the rollout in the shared vocabulary proposal (core#219).

What's in it

catalog/, in CUE:

	Entries	Seeded from
guarantees.cue	the 5 guarantees, with what gives each up	core's Guarantee
facts.cue	13 facts, each value with its meaning, and establishes for the handshake facts	specs/profile.cue, core's ProfileKind::facts
encodings.cue	the 10 official names, none included, with aliases and frozen_as	runtime's contract/names.rs, core's official.rs SPELLINGS
features.cue	the 12 wire features	features.json
sets.cue	formats, framings, handshakes, profiled, *_facts, features, aliases, ...	queries over the above

schema.cue holds the rules:

• ids match their kind's pattern;
• an alias resolves to exactly one encoding and is never a wire name;
• frozen_as is also an alias;
• references (establishes, feature) name existing entries;
• handshake facts are booleans;
• deprecated needs replaced_by.

I confirmed each rule refuses a case written to break it.

What reads it now

• specs/profile.cue generates each kind's fact fields and value domains from the catalog. gen/profile.schema.json is unchanged apart from its description, and all nine profiles vet.

• features.json is generated from it. The content is equal to the hand-written file; only the formatting changes (cue export).

• catalog/gen/catalog.json exports everything, for readers without CUE.

• check.sh also checks that:

  • profiles/ holds exactly sets.profiled;
  • each profile is of its encoding's kind and named for its file;
  • vectors/ holds exactly sets.features.

  I confirmed it fails on an extra or missing profile, a kind mismatch, a misnamed profile, an extra vectors file and a hand-edited features.json.

Choices worth a look

• cue.mod/ moves to the repository root, so specs can import catalog, and the module path becomes github.com/comlineproject/specification@v0. A consumer that runs cue on a vendored copy must now run it from inside that copy. Runtime's conformance/check.sh does it from outside, so it needs a cd when runtime re-vendors.
• VERSION stays 0.10. No vector, profile or case format changes meaning, so implementations have nothing new to do.
• since is set only where the changelog names the version: 0.2, 0.4, 0.7 and 0.10. Elsewhere it's left out rather than guessed.
• Left out for now:
  • guarantee scopes, which arrive with granular @unverified (core#222);
  • annotations, settings keys, diagnostic codes and CI targets, which come in later PRs per the proposal;
  • compiler defaults (DEFAULT_FRAMING and so on), which are compiler policy rather than shared names.