Skip to content

@unverified: an explicit, opt-in marker for giving up a peer guarantee #121

Closed

Description

@Kinflou

Decided (docs#51): the marker is @unverified = "reason": one marker with a mandatory reason. Core works out which guarantees are given up (schema agreement, encoding agreement, encoding conformance, version honesty) and freezes that set with the reason. A consumer's acceptance records the set, so giving up one more asks for a new acceptance. Call-site skips become Client::new_unverified / Server::serve_unverified. Where @unchecked appears below, read @unverified.

Part of #120 (extensibility). Proposed (decided with the user 2026-10-19), open for discussion; nothing implemented.

Some implementers need to give up guarantees Comline otherwise gives peers, for example to talk to a legacy system with its own hello or none at all. Today the only way is a call-site skip (Client::new / Server::serve, "misaligned mode") that nothing in the schema shows. This proposes an explicit, audited opt-out, playing the role of Rust's unsafe in Comline terms: unchecked.

What is unchecked

Anything that turns off a check Comline would otherwise make between peers, where the author vouches for what replaced it:

  1. A handshake that doesn't establish schema or encoding agreement: none, or a custom handshake that doesn't do Comline's checks (it may do other things, such as authentication).
  2. An unproven encoding: a format or framing whose profile is declared by a dependency without vectors, or that has no profile at all (instead of today's strictest-profile fallback plus a warning).
  3. A version-rule override: accepting a breaking change without a major bump (the escape hatch left open in Compatibility rules: what a version bump means (what's left: #117, #155, generation#67, cli#80) #119).
  4. Skipping checks at runtime: the hand-wired paths without a handshake are renamed *_unchecked in the runtimes (runtime issue linked below).

Marking it: @unchecked = "reason"

  • An annotation with a mandatory reason, for example @unchecked = "speaks the 2009 billing gateway's own hello". The reason is frozen into the IR and shown to every consumer.
  • Off by default: annotations.unchecked.allowed = false in the built-in defaults, the same mechanism @framing uses. A package turns it on in its settings; cross-package settings let an organisation forbid it.
  • Required where it applies: a protocol whose handshake doesn't establish those guarantees or an unproven encoding without @unchecked is an error. @unchecked on something fully checked is a warning (like an unused unsafe).
  • The marker's place for package-level cases (an unproven format declared in config.idp, a version-rule override) is open; it should read the same way.

Consumers acknowledge it, per protocol

A package that depends on, or imports, an unchecked protocol from another package must name it in its own config.idp, under that dependency. Until it does, the build fails. A dependency update that makes another protocol unchecked stops the build again until that one is acknowledged too. Using one is always a choice made in writing.

Visibility and versioning

Open

  • How exactly the package-level marker and the per-protocol acknowledgement read in config.idp.
  • Whether unchecked should also be a diagnostics code family, so an organisation can raise or lower the warnings.

Activity

  1. changed the title [-]Unchecked: an explicit, opt-in way to give up peer guarantees[/-] [+]Giving up a peer guarantee: an explicit, opt-in marker (name open)[/+] on Oct 18, 2026
  2. changed the title [-]Giving up a peer guarantee: an explicit, opt-in marker (name open)[/-] [+]@unverified: an explicit, opt-in marker for giving up a peer guarantee[/+] on Oct 19, 2026
  3. Kinflou commented on Oct 20, 2026

    @Kinflou
    MemberAuthor

    Decided 2026-10-20 (recorded in ComlineProject/docs#64):

    • Encoding without vectors: unverified = "reason" on the encoding's declaration in config.idp.
    • Lowering a bump: made at release (comline release --lower … --reason), stored on the release record, not in config.idp.
    • Consumer acceptance: accept_unverified = { Billing = ["schema_agreement"] } under the dependency; the list is a snapshot of the accepted set. Written by a quick fix or comline accept billing::Billing, not by hand.
    • Diagnostics: own code family (unverified::schema-agreement, …) under diagnostics.<code>.level; the "not accepted" error can't be lowered.
  4. Kinflou commented on Oct 31, 2026

    @Kinflou
    MemberAuthor

    Done: @unverified, the frozen guarantee set and accept_unverified shipped in core#132; the language-server quick fix and core#131 followed.

  5. Kinflou commented on Nov 9, 2026

    @Kinflou
    MemberAuthor

    Follow-up: ComlineProject/docs#162 proposes an optional keyed form, @unverified(guarantee = "reason"), with narrower scopes (e.g. bounded_size on a single argument), checked against the set core computes. The plain form stays as decided here. Tracked in #222 (part of #219).

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

    configPackages, config.idp, settingsenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions