Skip to content

Granular @unverified: name guarantees, per-guarantee reasons, narrower scopes #222

Open

Description

@Kinflou

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_size down 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_size says 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_conformance at package or protocol scope;
    • bounded_size down 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 = true requires 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" in config.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. diff recomputes both versions under the newer spec, so the version comparison reports no false major change.
  • The word: @unverified for 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).

Activity

  1. added
    P2Soon
    versioningVersions and compatibility
    designNeeds a design decision
    blockedWaiting on something else
    and removed
    blockedWaiting on something else
    on Nov 9, 2026
  2. moved this from Todo to Design in Comline Development Roadmapon Nov 15, 2026
  3. Kinflou commented on Nov 15, 2026

    @Kinflou
    MemberAuthor

    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.

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

    P2SooncompilerParser, IR, CASdesignNeeds a design decisionversioningVersions and compatibility

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions