From 875dece4d254aa47806701938cbb6f4cb462e915 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Tue, 10 Nov 2026 03:19:16 +0800 Subject: [PATCH] catalog: guarantee scopes, where an @unverified marker may sit A guarantee says which of package, protocol, function, argument, field and type may acknowledge it, from where its cause is. The schema holds the scopes to their order and to the guarantee's origin; the comline-catalog crate gains Scope, Guarantee::scopes and Guarantee::allows_scope. --- catalog/gen/catalog.json | 41 +++++++++++++++++++--- catalog/guarantees.cue | 5 +++ catalog/readme.md | 9 +++++ catalog/rust.cue | 12 ++++++- catalog/schema.cue | 21 +++++++++++ catalog/sets.cue | 2 ++ rust/src/catalog.rs | 8 ++++- rust/src/lib.rs | 76 ++++++++++++++++++++++++++++++++++++++++ 8 files changed, 167 insertions(+), 7 deletions(-) diff --git a/catalog/gen/catalog.json b/catalog/gen/catalog.json index 6c6a477..2fe64cc 100644 --- a/catalog/gen/catalog.json +++ b/catalog/gen/catalog.json @@ -4,31 +4,54 @@ "status": "stable", "title": "schema agreement", "description": "Both ends were built from compatible schemas, which the handshake checks.", - "comes_from": "handshake" + "comes_from": "handshake", + "scopes": [ + "package", + "protocol" + ] }, "encoding_agreement": { "status": "stable", "title": "encoding agreement", "description": "Both ends use the same format and framing, which the handshake checks.", - "comes_from": "handshake" + "comes_from": "handshake", + "scopes": [ + "package", + "protocol" + ] }, "encoding_conformance": { "status": "stable", "title": "encoding conformance", "description": "An implementation encodes what its name promises, proven by conformance vectors.", - "comes_from": "encoding" + "comes_from": "encoding", + "scopes": [ + "package", + "protocol" + ] }, "version_honesty": { "status": "stable", "title": "version honesty", "description": "A version bump says what the change breaks, as the version comparison works it out.", - "comes_from": "policy" + "comes_from": "policy", + "scopes": [ + "package", + "protocol" + ] }, "bounded_size": { "status": "stable", "title": "bounded size", "description": "Every value has a maximum size, so a decoder refuses an oversized one before allocating it.", - "comes_from": "type" + "comes_from": "type", + "scopes": [ + "protocol", + "function", + "argument", + "field", + "type" + ] } }, "facts": { @@ -375,6 +398,14 @@ "version_honesty", "bounded_size" ], + "scopes": [ + "package", + "protocol", + "function", + "argument", + "field", + "type" + ], "formats": [ "packed@1", "json@1", diff --git a/catalog/guarantees.cue b/catalog/guarantees.cue index c9af68f..5b1bb6c 100644 --- a/catalog/guarantees.cue +++ b/catalog/guarantees.cue @@ -5,25 +5,30 @@ guarantees: { title: "schema agreement" description: "Both ends were built from compatible schemas, which the handshake checks." comes_from: "handshake" + scopes: ["package", "protocol"] } encoding_agreement: { title: "encoding agreement" description: "Both ends use the same format and framing, which the handshake checks." comes_from: "handshake" + scopes: ["package", "protocol"] } encoding_conformance: { title: "encoding conformance" description: "An implementation encodes what its name promises, proven by conformance vectors." comes_from: "encoding" + scopes: ["package", "protocol"] } version_honesty: { title: "version honesty" description: "A version bump says what the change breaks, as the version comparison works it out." comes_from: "policy" + scopes: ["package", "protocol"] } bounded_size: { title: "bounded size" description: "Every value has a maximum size, so a decoder refuses an oversized one before allocating it." comes_from: "type" + scopes: ["protocol", "function", "argument", "field", "type"] } } diff --git a/catalog/readme.md b/catalog/readme.md index 245b52a..9dd7d64 100644 --- a/catalog/readme.md +++ b/catalog/readme.md @@ -23,6 +23,15 @@ What an entry may say, and the rules across entries, are in (`frozen_as`: `jsonrpc`, `datagram`), that spelling is an alias too. - A reference (`establishes`, `feature`) names an entry that exists. - A handshake's facts are booleans. +- A guarantee's `scopes` say where an `@unverified` marker acknowledging it + may sit: any of `package`, `protocol`, `function`, `argument`, `field` and + `type`, outermost to innermost, each at most once. They follow from where + its cause is: what the handshake, a policy or the encoding gives up + (`schema_agreement`, `version_honesty`, `encoding_conformance`, ...) is + settled for a package or a protocol, so those are its scopes; what a type + gives up (`bounded_size`) can also be acknowledged on a function, an + argument, a field or the type itself, and must include `type`. The schema + checks both, and `sets.scopes` lists the vocabulary. - `since` is the spec version that introduced an entry, where the changelog names one. diff --git a/catalog/rust.cue b/catalog/rust.cue index 6289daa..d2f498b 100644 --- a/catalog/rust.cue +++ b/catalog/rust.cue @@ -34,6 +34,14 @@ _rust: { #in: "format" | "framing" | "handshake" out: {format: "Kind::Format", framing: "Kind::Framing", handshake: "Kind::Handshake"}[#in] } + scope: { + #in: #Scope + out: {package: "Scope::Package", protocol: "Scope::Protocol", function: "Scope::Function", argument: "Scope::Argument", field: "Scope::Field", type: "Scope::Type"}[#in] + } + scopes: { + #in: [...#Scope] + out: "&[" + strings.Join([for s in #in {(scope & {#in: s}).out}], ", ") + "]" + } status: { #in: "stable" | "experimental" | "deprecated" out: {stable: "Status::Stable", experimental: "Status::Experimental", deprecated: "Status::Deprecated"}[#in] @@ -80,7 +88,7 @@ _set: { rust_catalog: """ // Generated from the catalog's CUE by `specs/check.sh`: don't edit by hand. - use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Status, Value}; + use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Scope, Status, Value}; pub const SPEC_VERSION: &str = \((_rust.str & {#in: _spec_version}).out); @@ -92,6 +100,7 @@ rust_catalog: """ title: \((_rust.str & {#in: g.title}).out), description: \((_rust.str & {#in: g.description}).out), comes_from: \({handshake: "Origin::Handshake", encoding: "Origin::Encoding", policy: "Origin::Policy", type: "Origin::Type"}[g.comes_from]), + scopes: \((_rust.scopes & {#in: g.scopes}).out), \((_rust.lifecycle & {#in: g}).out) }, """}], "\n")) @@ -165,6 +174,7 @@ rust_catalog: """ /// The catalog's sets. pub mod sets { \((_set & {#name: "GUARANTEES", #in: sets.guarantees}).out) + \((_set & {#name: "SCOPES", #in: sets.scopes}).out) \((_set & {#name: "FORMATS", #in: sets.formats}).out) \((_set & {#name: "FRAMINGS", #in: sets.framings}).out) \((_set & {#name: "HANDSHAKES", #in: sets.handshakes}).out) diff --git a/catalog/schema.cue b/catalog/schema.cue index ac9282c..34de17a 100644 --- a/catalog/schema.cue +++ b/catalog/schema.cue @@ -13,6 +13,12 @@ import "list" } } +// Where an `@unverified` marker may sit, outermost to innermost: the +// package, a protocol in it, a function of the protocol, one of its +// arguments, a field of a type, a type. +#Scopes: ["package", "protocol", "function", "argument", "field", "type"] +#Scope: or(#Scopes) + // A guarantee Comline gives between peers, which a protocol can give up // with `@unverified`. Its id is the name written in `accept_unverified`, // diagnostics and generated docs. @@ -23,6 +29,9 @@ import "list" // What gives it up: the handshake, the format and framing, a handshake // policy, or a type. comes_from!: "handshake" | "encoding" | "policy" | "type" + // Where an `@unverified` marker acknowledging it may sit, which follows + // from where its cause is. In `#Scopes` order, each at most once. + scopes!: [#Scope, ...#Scope] }) // A fact an encoding's profile states, with every value it may take and @@ -74,6 +83,18 @@ facts: {[=~#SnakeId]: #Fact, [!~#SnakeId]: _|_} encodings: {[=~#EncodingId]: #Encoding, [!~#EncodingId]: _|_} features: {[=~#FeatureId]: #Feature, [!~#FeatureId]: _|_} +// A guarantee's scopes follow from where it comes from: what a type gives +// up can be acknowledged on the type, or on whatever uses it, down from the +// protocol; what the handshake, the policies and the encoding give up is +// settled by the package and its protocols, never below a protocol. +_scope_rank: {for i, s in #Scopes {(s): i}} +_scopes_are_ordered: [for id, g in guarantees + let ranks = [for s in g.scopes {_scope_rank[s]}] + if len([for i, r in ranks if i > 0 if r <= ranks[i-1] {i}]) > 0 {id}] & [] +_scopes_follow_origin: [for id, g in guarantees + let inner = [for s in g.scopes if _scope_rank[s] >= _scope_rank["function"] {s}] + if (g.comes_from == "type" && !list.Contains(g.scopes, "type")) || (g.comes_from != "type" && len(inner) > 0) {id}] & [] + // A handshake's facts are booleans. _boolean_handshake_facts: [for id, f in facts if f.applies_to == "handshake" if [for v, _ in f.values {v}] != ["true", "false"] {id}] & [] diff --git a/catalog/sets.cue b/catalog/sets.cue index 6932211..07b2b64 100644 --- a/catalog/sets.cue +++ b/catalog/sets.cue @@ -4,6 +4,8 @@ package catalog // label that names a top-level field is quoted, so it doesn't shadow it. sets: { "guarantees": [for id, _ in guarantees {id}] + // Where an `@unverified` marker may sit, outermost to innermost. + scopes: #Scopes formats: [for id, e in encodings if e.kind == "format" {id}] framings: [for id, e in encodings if e.kind == "framing" {id}] handshakes: [for id, e in encodings if e.kind == "handshake" {id}] diff --git a/rust/src/catalog.rs b/rust/src/catalog.rs index 69f777b..7dd334a 100644 --- a/rust/src/catalog.rs +++ b/rust/src/catalog.rs @@ -1,6 +1,6 @@ // Generated from the catalog's CUE by `specs/check.sh`: don't edit by hand. -use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Status, Value}; +use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Scope, Status, Value}; pub const SPEC_VERSION: &str = r#"0.10"#; @@ -11,6 +11,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"schema agreement"#, description: r#"Both ends were built from compatible schemas, which the handshake checks."#, comes_from: Origin::Handshake, + scopes: &[Scope::Package, Scope::Protocol], status: Status::Stable, replaced_by: None, since: None, @@ -20,6 +21,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"encoding agreement"#, description: r#"Both ends use the same format and framing, which the handshake checks."#, comes_from: Origin::Handshake, + scopes: &[Scope::Package, Scope::Protocol], status: Status::Stable, replaced_by: None, since: None, @@ -29,6 +31,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"encoding conformance"#, description: r#"An implementation encodes what its name promises, proven by conformance vectors."#, comes_from: Origin::Encoding, + scopes: &[Scope::Package, Scope::Protocol], status: Status::Stable, replaced_by: None, since: None, @@ -38,6 +41,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"version honesty"#, description: r#"A version bump says what the change breaks, as the version comparison works it out."#, comes_from: Origin::Policy, + scopes: &[Scope::Package, Scope::Protocol], status: Status::Stable, replaced_by: None, since: None, @@ -47,6 +51,7 @@ pub const GUARANTEES: &[Guarantee] = &[ title: r#"bounded size"#, description: r#"Every value has a maximum size, so a decoder refuses an oversized one before allocating it."#, comes_from: Origin::Type, + scopes: &[Scope::Protocol, Scope::Function, Scope::Argument, Scope::Field, Scope::Type], status: Status::Stable, replaced_by: None, since: None, @@ -503,6 +508,7 @@ pub mod feature { /// The catalog's sets. pub mod sets { pub const GUARANTEES: &[&str] = &[r#"schema_agreement"#, r#"encoding_agreement"#, r#"encoding_conformance"#, r#"version_honesty"#, r#"bounded_size"#]; + pub const SCOPES: &[&str] = &[r#"package"#, r#"protocol"#, r#"function"#, r#"argument"#, r#"field"#, r#"type"#]; pub const FORMATS: &[&str] = &[r#"packed@1"#, r#"json@1"#, r#"msgpack@1"#]; pub const FRAMINGS: &[&str] = &[r#"jsonrpc@1"#, r#"datagram@1"#, r#"datagram@2"#, r#"datagram@3"#]; pub const HANDSHAKES: &[&str] = &[r#"comline@1"#, r#"comline@2"#, r#"none"#]; diff --git a/rust/src/lib.rs b/rust/src/lib.rs index cd3531b..375ddf1 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -52,6 +52,38 @@ pub enum Origin { Type, } +/// Where an `@unverified` marker may sit, outermost to innermost. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum Scope { + /// The whole package. + Package, + /// A protocol in it. + Protocol, + /// A function of a protocol. + Function, + /// An argument of a function. + Argument, + /// A field of a type. + Field, + /// A type. + Type, +} + +impl Scope { + /// As the catalog writes it: `package`, `protocol`, `function`, + /// `argument`, `field`, `type`. + pub const fn as_str(self) -> &'static str { + match self { + Scope::Package => "package", + Scope::Protocol => "protocol", + Scope::Function => "function", + Scope::Argument => "argument", + Scope::Field => "field", + Scope::Type => "type", + } + } +} + /// Where an entry stands. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Status { @@ -69,12 +101,23 @@ pub struct Guarantee { pub title: &'static str, pub description: &'static str, pub comes_from: Origin, + /// Where an `@unverified` marker acknowledging it may sit, outermost to + /// innermost. + pub scopes: &'static [Scope], pub status: Status, pub replaced_by: Option<&'static str>, /// The spec version that introduced it, where the changelog names one. pub since: Option<&'static str>, } +impl Guarantee { + /// Whether an `@unverified` marker acknowledging this guarantee may sit + /// at `scope`. + pub fn allows_scope(&self, scope: Scope) -> bool { + self.scopes.contains(&scope) + } +} + /// One value a fact may take, and what it means. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct Value { @@ -226,6 +269,39 @@ mod tests { } } + #[test] + fn every_guarantee_has_scopes_in_order() { + let rank = |s: &Scope| sets::SCOPES.iter().position(|id| *id == s.as_str()).unwrap(); + for g in GUARANTEES { + assert!(!g.scopes.is_empty(), "{}", g.id); + assert!(g.scopes.windows(2).all(|w| rank(&w[0]) < rank(&w[1])), "{}", g.id); + assert_eq!(g.comes_from == Origin::Type, g.allows_scope(Scope::Type), "{}", g.id); + } + } + + #[test] + fn a_type_guarantee_reaches_below_the_protocol() { + let bounded = guarantee(guarantee::BOUNDED_SIZE).unwrap(); + assert!(bounded.allows_scope(Scope::Field)); + assert!(!bounded.allows_scope(Scope::Package)); + let agreement = guarantee(guarantee::SCHEMA_AGREEMENT).unwrap(); + assert!(agreement.allows_scope(Scope::Package) && agreement.allows_scope(Scope::Protocol)); + assert!(!agreement.allows_scope(Scope::Field)); + } + + #[test] + fn scopes_match_their_set() { + let all = [ + Scope::Package, + Scope::Protocol, + Scope::Function, + Scope::Argument, + Scope::Field, + Scope::Type, + ]; + assert!(all.iter().map(|s| s.as_str()).eq(sets::SCOPES.iter().copied())); + } + #[test] fn the_spec_version_is_a_version() { let (major, minor) = SPEC_VERSION.split_once('.').unwrap();