Spec 0.3.0-draft: version tiers (0.1/0.2/0.3), 0.2 hardening, spec-leads-code gate#1
Conversation
…nance Document the protocol in versioned tiers so the specification leads the reference implementation rather than trailing it. Protocol versions (new §2.1): - 0.1.0 — baseline, reference-complete, CTK-backed. - 0.2.0 — approval & audit hardening, now reference-backed and CTK-tested: §7 approvals bound to intent_hash and made single-use (full resolution algorithm + status lifecycle); §5/§8 approved-action receipts carry their parking rule so rate_limit counts them, and an unevaluable rate_limit denies; §8.1 a malformed/partial receipt is a verification failure, not a crash. - 0.3.0 (draft — not yet in reference): §4.2 query-string-bound fingerprint (closes the confused-deputy gap where the query is excluded), §9 token. Conformance & governance: - ctk/vectors/resolve.json — authoritative §7 resolution vectors (fingerprint guard, intent guard, single-use replay); ctk/README documents them. - conformance.py + a CI job replay every CTK vector against the installed reference and assert reference __protocol_version__ <= spec version, so the code can never silently drift ahead of the spec. - CONTRIBUTING: "the spec leads the reference"; fork-and-PR; and an AI-assisted-contributions policy (disclose, stricter review, human accountable). - PR template with the AI disclosure and a normative-change checklist. - CHANGELOG added; §6 determinism note names evaluation time as an input. The reference reproduces all hashing, decision, resolve, and chain vectors. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ing) Replace the banking (BFSI) example with a neutral generic HTTP/JSON API across the spec prose and the whole Conformance Test Kit, so the protocol's examples don't read as bank-specific. - examples/policy.example.yaml: api.example.com, place-order (POST /orders, USD amount cap + destination allow_list); kept byte-identical to the reference. - spec.md §4.1 worked-example hashes, §4.2 query example, §5 policy block: generic. - CTK regenerated from the reference: hashing, decisions, resolve, and a fresh-key chain (+ tampered) — new signing_key.pub, expected files updated. - authorization-token example: generic place-order fpr/iht + rule. validate.py and conformance.py both green against the reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
koishore
left a comment
There was a problem hiding this comment.
Review — specification #1
Reviewed the full diff; ran validate.py (green) and conformance.py against the paired reference (green locally).
0.2 normative additions
- §7 resolution algorithm (fingerprint → intent → status) and the
pending → approved → consumed/deniedlifecycle match the reference exactly;resolve.jsonvectors cover all seven branches including single-use replay. - §5 rule-attribution + fail-closed
rate_limit, §8.1 malformed-receipt-is-a-failure: all reproduced by the reference. - §2.1 version matrix + the
__protocol_version__ ≤ specrule are clear and enforceable.
0.3 frontier (draft, not in reference) — §4.2 query-string-bound fingerprint and §9 token are correctly fenced as draft; they don't claim reference backing.
Conformance gate — conformance.py replays hashing/decisions/resolve/chain and asserts reference ≤ spec. The CI conformance job currently fails as designed because it installs delego@main (still 0.1); it will go green once the paired delego PR merges and the job re-runs.
Genericization — example + all CTK vectors regenerated from the reference (fresh chain signing key); validate.py green; example policy byte-identical to the reference's.
Verdict: looks good — merge after delego#1 lands, then re-run the conformance job so it's green before merging.
What & why
Document the protocol in versioned tiers (0.1 / 0.2 / 0.3) so the specification leads the reference implementation rather than trailing it, and lock that ordering in with a conformance gate.
reference __protocol_version__ ≤ spec version.intent_hashand single-use (full resolution algorithm + status lifecycle); §5/§8 approved-action receipts carry their parking rule sorate_limitcounts them, and an unevaluablerate_limitdenies; §8.1 a malformed/partial receipt is a verification failure, not a crash.ctk/vectors/resolve.json— authoritative §7 vectors (fingerprint guard, intent guard, single-use replay).conformance.py+ CI job — replays every CTK vector against the installed reference and asserts the spec leads it.CHANGELOG.md; CONTRIBUTING (spec-leads, fork-and-PR, AI policy); PR template.Pairs with delego PR (exposes
__protocol_version__ = 0.2.0and implements the 0.2 behaviour).AI assistance disclosure (required)
Kind of change
Checklist
main).python validate.pyis green.python conformance.pyis green against the paired reference.For a normative change (additionally)
resolve.json) regenerated from the reference.__protocol_version__(0.2.0) ≤ spec (0.3.0-draft).CHANGELOG.mdupdated.