Skip to content

framing fact protocol: whether a frame names the protocol (0.11) - #9

Merged
Kinflou merged 1 commit into
mainfrom
catalog/framing-protocol-fact
Nov 13, 2026
Merged

Kinflou merged 1 commit into
mainfrom
catalog/framing-protocol-fact

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 13, 2026

Copy link
Copy Markdown
Member

Adds the framing fact protocol (spec 0.11): whether a request's frame names the protocol it calls into.

Serves ComlineProject/generation#137 step 2: codegen will put a protocol on a connection by default when the framing's directions is both and protocol is named, and otherwise only when it's client-provided. jsonrpc@1 and datagram@2 are both directions: both, and no existing fact told them apart. Core, runtime, generation and cli follow.

The fact

  • named: it does, by number or wire id, so several protocols can share one transport
  • unnamed: it doesn't: a call names only its function
framing value proven by
datagram@1 unnamed framing-datagram/request, request-large-id
datagram@2 named framing-datagram2/request-two-byte-protocol
datagram@3 named framing-datagram3/request-two-byte-protocol (new)
jsonrpc@1 unnamed framing-jsonrpc/request, request-large-id

JSON-RPC's qualified method names are a parameter of the framing, not of its profile, so jsonrpc@1 stays unnamed (noted in the changes entry).

Proof

Reused cases except one. New: framing-datagram3/request-two-byte-protocol, a request with protocol 300, call_id 1, method ping, params [], request_id 5, bytes 00ac020105000000000000005b5d. The existing datagram@3 cases give the protocol and the call the same number (or 0), so their bytes can't show which is which. Its bytes are datagram@2's case of the same name (00ac02010005000000000000005b5d) with the call id written as datagram@3 writes it, a varint 01, instead of two bytes 0100; the layout matches framing-datagram3/request-two-byte-numbers. The Rust reference must produce it for vectors_are_current. No existing frame's bytes change.

I couldn't use a pair differing only in protocol for unnamed: decoding gives the input back, so an unnamed frame's case can't carry a protocol input.

The check

The existing calls/directions rules are enforced by the runtime's fact_shown (described in the README), not by specs/check.sh, so this adds specs/protocol.jq, run by specs/check.sh on each framing profile. Each cited case must exist, be an exact request of that framing, and:

  • named: have a protocol of 128 or more that isn't its call_id, and its bytes hold that number's LEB128 varint from a byte boundary;
  • unnamed: have no protocol in its input (decoding its bytes gives that input back, so the frame carries none).

The README's description of how facts are shown gains the same rule, for the runtime's fact_shown to follow.

Regenerated

catalog/gen/catalog.json, rust/src/catalog.rs (spec version 0.11, the fact, FRAMING_FACTS) and specs/gen/profile.schema.json. features.json is unchanged. VERSION 0.11, rust/Cargo.toml 0.11.0. specs/check.sh and --check pass locally, cargo test in rust/ passes (14 tests).

Downstream

A framing profile without protocol is refused, so core's Profile::parse and the runtime's vendored conformance break on this spec until they update: the runtime must vendor 0.11, add the new datagram@3 case to its reference's vectors, and judge protocol in fact_shown by the rule above. Core must read the new fact.

A framing states whether a request's frame names the protocol it calls
into: datagram@2 and datagram@3 do (named), datagram@1 and jsonrpc@1 don't
(unnamed). specs/protocol.jq holds each profile to the cases it names. One
new case, framing-datagram3/request-two-byte-protocol; no frame's bytes
change.
@Kinflou
Kinflou marked this pull request as ready for review November 13, 2026 01:57
@Kinflou
Kinflou merged commit 8335ab8 into main Nov 13, 2026
7 checks passed
@Kinflou
Kinflou deleted the catalog/framing-protocol-fact branch November 13, 2026 01:57
Kinflou added a commit to ComlineProject/core that referenced this pull request Nov 13, 2026
* Pin the specification at 0.11: the framing fact `protocol`

Pin comline-catalog and the vendored tests/spec/REV at the head of
ComlineProject/specification#9 (69882e9), and take its four framing
profiles into the embedded official package: each now states `protocol`
(`named` for datagram@2 and datagram@3, `unnamed` for datagram@1 and
jsonrpc@1). The profile hashes in official_units.json follow.

Profile gains `names_protocol()` and `both_directions()`, typed readers
of the two facts for generation and the CLI. The hand-written profiles
in tests state `protocol` too, as a framing must.

* dependency_pin: the golden pin follows its fixture's framing gaining `protocol`

The fixture declares its own framing, and spec 0.11 has every framing profile
state `protocol`. That changes the frozen `Encoding` unit the pin covers, so
the pin moves with its input. CONTENT_HASH_SCHEME is unchanged: official
encodings are looked up, never frozen into a package's config, so pins of
packages without a framing of their own don't move.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant