Repository navigation
Description
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 becomeClient::new_unverified/Server::serve_unverified. Where@uncheckedappears 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:
- 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). - 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).
- 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).
- Skipping checks at runtime: the hand-wired paths without a handshake are renamed
*_uncheckedin 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 = falsein the built-in defaults, the same mechanism@framinguses. A package turns it on in itssettings; 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
@uncheckedis an error.@uncheckedon something fully checked is a warning (like an unusedunsafe). - 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
- Frozen IR: the marker and its reason.
- Build output, editor hover (and a semantic-token modifier), generated docs, and generated code (a doc comment on the client and dispatcher) all show it.
- Version comparison (Compatibility rules: what a version bump means (what's left: #117, #155, generation#67, cli#80) #119): making a protocol unchecked is major, since it removes a guarantee peers relied on. Removing the marker (becoming checked) is minor.
Open
- How exactly the package-level marker and the per-protocol acknowledgement read in
config.idp. - Whether
uncheckedshould also be adiagnosticscode family, so an organisation can raise or lower the warnings.
Activity
[-]Unchecked: an explicit, opt-in way to give up peer guarantees[/-][+]Giving up a peer guarantee: an explicit, opt-in marker (name open)[/+][-]Giving up a peer guarantee: an explicit, opt-in marker (name open)[/-][+]@unverified: an explicit, opt-in marker for giving up a peer guarantee[/+]Kinflou commentedon Oct 20, 2026
Decided 2026-10-20 (recorded in ComlineProject/docs#64):
unverified = "reason"on the encoding's declaration inconfig.idp.comline release --lower … --reason), stored on the release record, not inconfig.idp.accept_unverified = { Billing = ["schema_agreement"] }under the dependency; the list is a snapshot of the accepted set. Written by a quick fix orcomline accept billing::Billing, not by hand.unverified::schema-agreement, …) underdiagnostics.<code>.level; the "not accepted" error can't be lowered.Kinflou commentedon Oct 31, 2026
Done:
@unverified, the frozen guarantee set andaccept_unverifiedshipped in core#132; the language-server quick fix and core#131 followed.Kinflou commentedon Nov 9, 2026
Follow-up: ComlineProject/docs#162 proposes an optional keyed form,
@unverified(guarantee = "reason"), with narrower scopes (e.g.bounded_sizeon a single argument), checked against the set core computes. The plain form stays as decided here. Tracked in #222 (part of #219).