Repository navigation
Description
Part of #219, proposal ComlineProject/docs#162 (Granular @unverified). Revisits part of the decision in #121.
@unverified = "reason" stays valid and keeps acknowledging whatever core computes. Add an optional keyed form that names guarantees, at the scope each one has:
@unverified(encoding_conformance = "com.acme.f@1 ships no vectors yet")
protocol Billing {
function upload(@unverified(bounded_size = "legacy blob") data: bytes);
}
- Grammar: keyed annotation values (Typed annotation values: lists, calls and references for any annotation #124), and markers on arguments and fields.
- Check against the computed set:
- a computed guarantee that isn't named is an error;
- a named guarantee that isn't given up is a warning;
- an unknown key is an error, with spellings suggested from the vocabulary.
- Scopes from the vocabulary: handshake guarantees at protocol or package scope;
bounded_sizedown to an argument, field or type. A marker at the wrong scope is an error. - Freeze each given-up guarantee with its scope and reason, so diff and compat see narrowing and widening.
- Diagnostics name the exact cause. Today
bounded_sizesays only "a string, list or nesting it reaches has no maximum".
Open (in the proposal): acceptance by scope, package-level defaults, inheritance, and an optional settings switch that requires the keyed form.
Leanings (discussion of 2026-11-09)
The rule everything serves: if a package compiles, every guarantee given up anywhere a protocol reaches, through any chain of types and packages, has been acknowledged in that package and accepted by every consumer, and each acknowledgement and acceptance is pinned to the exact causes it covered.
-
Scopes per guarantee, stated in its catalog entry:
- handshake guarantees at package or protocol scope;
encoding_conformanceat package or protocol scope;bounded_sizedown to a function, argument, field or type.
A marker at a scope its guarantee doesn't allow is an error.
-
Outer covers inner by default, as today, with tooling suggesting the narrower placement.
annotations.unverified.strict = truerequires the keyed form at the innermost scope. -
Chains: once per package, never inherited. A marker never subtracts from what's computed. Each package whose types or protocols reach a cause acknowledges it once, anywhere on its path. A's reason travels as the origin, but A's marker satisfies only A.
-
Pinned to the chain. An acknowledgement or acceptance records each guarantee with the chain to each cause. A new cause, or a swapped type upstream, asks again at every hop.
-
Frozen: (guarantee, scope path, chain, reason). Narrowing a marker isn't a major change; widening one or adding a cause is.
-
Acceptance stays per protocol, pinned the same way.
-
Fail closed: a build that can't see a dependency's declarations or IR counts the guarantee as given up.
-
Diagnostics,
inspect, hover and generated docs show the full chain.
Safety tests land with it: #223, #224, #225.
Also settled:
- Package-default causes (e.g.
handshake = "none"inconfig.idp) are acknowledged next to that setting:unverified = { schema_agreement = "…", … }. The marker covers only the causes from that setting, and only for protocols inheriting it. Each covered protocol's record shows it was acknowledged at package scope. It's pinned. A blanket package marker is ruled out. - A newer spec that finds an existing loss asks the author and every consumer again, because their pinned sets no longer match.
diffrecomputes both versions under the newer spec, so the version comparison reports no false major change. - The word:
@unverifiedfor both the plain and keyed forms. - The frozen shape changes (scopes, chains), so this is IR format 4 (see Vocabulary: decide where the catalog lives and its format #220, Versioning).
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDesign
Activity
Kinflou commentedon Nov 15, 2026
Audit 2026-11-16: ticked what is merged. Keyed form and markers on arguments, fields, functions and types: core#265 (66feecb). The check against the computed set (missing marker, needless marker, unknown key): core#239 and core#241. Scopes from the catalog, with unverified::wrong-scope: specification#3 and core#241. Strict mode (annotations.unverified.strict): core#267. Package-default causes acknowledged beside the setting: core#241. Fail closed: core#256. Still open: freezing each guarantee with its scope path and chain (and the narrow/widen rule in the diff, see diff.rs near the @Unverified scopes key), diagnostics naming the exact cause, chains once per package, pinning to chains, acceptance pinned per protocol, a newer spec re-asking, and showing chains in inspect, hover and docs. This is IR format 4 under #268.