Skip to content

conformance: handshake profiles state schema and encoding agreement - #70

Merged
Kinflou merged 2 commits into
mainfrom
conformance/handshake-profile-facts
Oct 31, 2026
Merged

Kinflou merged 2 commits into
mainfrom
conformance/handshake-profile-facts

Conversation

@Kinflou

@Kinflou Kinflou commented Oct 31, 2026 •

Copy link
Copy Markdown
Member

Part of ComlineProject/core#147: handshake profiles state what a handshake establishes.

Profile schema

  • ProfileKind::Handshake now has two facts, schema_agreement and encoding_agreement, with values true / false. They're written as JSON booleans ("value": true); Fact.value still holds them as the strings "true" / "false", so the API doesn't change.
  • A handshake profile may leave a fact out (ProfileKind::states_every_fact), which reads as false. A fact stated false claims nothing, so it names no cases (proven_by defaults to empty).
  • fact_shown shows true with handshake_check cases: one where the peer agrees, accepted, and for each thing the fact covers a peer frame that differs in only that, refused. schema_agreement covers the IR hash; encoding_agreement covers the format and the framing.

Vectors

  • New op handshake_check (decode only, Op::decode_only): the input is one end's {ir_hash, wire_format, framing, capabilities}, and bytes is the peer's comline@1 frame. It accepts and returns the input when the IR hash, format and framing agree (capability bits may differ), and refuses otherwise.
  • vectors/handshake.json gains handshake/check-agree, check-reject-ir-hash, check-reject-format and check-reject-framing. They are byte-exact, generated by reference_cases, and run by the Rust harness. The existing handshake cases only encode or decode a frame and never check one against another, so none of them could prove either fact.
  • profiles/comline@1.json is new and states both facts as true. profiles_are_proven now checks it, and the runner test expects 7 profiles.

Spec 0.1 → 0.2. The case format changed (a new op, boolean fact values, optional handshake facts), so runner::SPEC_VERSION is now 0.2, and the README has a changelog. The ops protocol stays at 1, since the new op is an addition.

Other harnesses in this repo

  • The FFI export has a new line, handshake_check ID exact|reject OURS PEER. The Rust (tests/vectors.rs), C and Node harnesses replay it with comline_handshake_check.
  • comline-reference lists the op, and core/tests/async_handshake.rs (which reads handshake.json directly) replays the check cases over the async exchange.

comline-typescript must re-vendor. Its vendored vectors/handshake.json gains four handshake_check cases. Its harness needs to handle that op, which takes about ten lines: encode the input's frame, call checkBytes on the peer bytes, and accept with the input or refuse. If it doesn't, its handshake claim will fail as supported.

Local runs: cargo test for the workspace, CONFORMANCE_BLESS=1 (the vectors and reports/rust.json are regenerated), the C harness (static and cdylib), and the Node vectors harness all pass. The ASan build and poison.test.mjs can't run here because libasan and the test-hooks wasm are missing, so CI covers them.

A handshake profile now states two boolean facts, `schema_agreement` and
`encoding_agreement`: what the handshake establishes between the two ends.
One it leaves out, or states `false`, isn't established, and core makes a
protocol using the handshake give it up (`@unverified`, core#147).

- New op `handshake_check` (decode only): one end's declaration against
  the frame its peer sent, accepted when the fingerprint, format and
  framing agree. Four cases in vectors/handshake.json prove the facts.
- `profiles/comline@1.json` states both facts, proven by them, and
  `profiles_are_proven` and the runner check it.
- A fact's value may be a JSON boolean; a fact stated `false` names no
  cases.
- The FFI export, its Rust, C and Node harnesses replay the new cases with
  `comline_handshake_check`; the reference lists the op.
- Spec 0.1 -> 0.2: the case format and profile schema changed.
@Kinflou
Kinflou merged commit 64505b4 into main Oct 31, 2026
24 checks passed
@Kinflou
Kinflou deleted the conformance/handshake-profile-facts branch October 31, 2026 19:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant