Skip to content

Proposals: a shared vocabulary, and granular @unverified - #162

Merged
Kinflou merged 4 commits into
mainfrom
proposals/shared-vocabulary
Nov 12, 2026
Merged

Kinflou merged 4 commits into
mainfrom
proposals/shared-vocabulary

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

Two accepted proposals under Proposals → A shared vocabulary:

  • The catalog: one catalog of the names several programs agree on: encodings and handshakes, guarantees, facts with their value domains, conformance features, annotations, settings keys, diagnostic codes, and fuzz, bench and report targets. Sets are queries over it, and core, the runtimes, the generators, the language server, the Observatory, CI and the docs all read it. It covers the entry model, which kinds are worth covering, relations (establishes, keeps, gives up), where the catalog lives, and how each consumer reads it.
  • Granular @unverified: keeps @unverified = "reason", and adds an optional keyed form. It names each guarantee with its own reason, at the scope that guarantee has, for example bounded_size on a single argument. Core still computes the set and checks the keyed form against it. This revisits only the part of the guarantee-marker decision that it leaves open.

The overview page (index.md) lists the names duplicated today, the rules that hold whatever the details (wire names never change, third parties are first-class, nothing new at run time), and a staged rollout.

What changed in this round (status is now accepted, 2026-11-12, linking core#219 and core#222):

  • Catalog home and format decided (core#220): ComlineProject/specification, CUE, generated outputs (the comline-catalog crate and catalog/gen/catalog.json). The vocabulary-only repository and core are marked rejected.
  • Relations: plain references only is decided. How far they go beyond that stays open.
  • Versioning: spec version and IR format version independent, decided. Granular @unverified is IR format 4.
  • Scopes per guarantee, stated in the catalog entry (catalog/guarantees.cue).
  • Outer markers cover inner ones by default; annotations.unverified.strict = true requires the keyed form at the innermost scope.
  • Chains acknowledged once per package, never inherited, pinned to the chain; the frozen record is (guarantee, scope path, chain, reason).
  • Acceptance stays per protocol; fail closed; package-default causes acknowledged next to the setting; a newer spec re-asks; @unverified for both forms.
  • Options tables mark the chosen and rejected options. The rollout notes stages 1 to 3 as done, and the proposals index shows both pages as accepted.

mkdocs build --strict is checked in CI.

Tracked in ComlineProject/core#219: where the catalog lives is core#220, core consuming it is core#221, granular @unverified is core#222, plus runtime#112, observatory#19 and language-server#102.

A catalog of the names several programs agree on (encodings, guarantees,
facts and their values, conformance features, annotations, diagnostic
codes, CI targets), with sets as queries over it. And an optional keyed
@Unverified that names each guarantee with its own reason, at the scope
the guarantee has, checked against what core computes. Both draft.
The catalog lives in a spec repository with the conformance specs and
vectors, in CUE, with relations as plain references. Granular @Unverified
gets scopes per guarantee, outer-covers-inner with a strict opt-in,
acknowledgement once per package along a chain, pinned to the chain,
acceptance per protocol, failing closed, and the tests that prove the
invariant.
Package-default causes are acknowledged in config.idp next to the
setting, covering only that cause. A loss found by a newer spec asks
again without a false major change. The spec and IR format versions stay
independent, each frozen version recording its spec version, with the spec
append-only. @Unverified for both forms. The repository is named
specification.
@Kinflou
Kinflou merged commit 5ee4b98 into main Nov 12, 2026
8 checks passed
@Kinflou
Kinflou deleted the proposals/shared-vocabulary branch November 12, 2026 17:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant