Skip to content

Spec 0.3.0-draft: version tiers (0.1/0.2/0.3), 0.2 hardening, spec-leads-code gate#1

Merged
koishore merged 2 commits into
mainfrom
spec-0.3-draft-lead
Jun 3, 2026
Merged

Spec 0.3.0-draft: version tiers (0.1/0.2/0.3), 0.2 hardening, spec-leads-code gate#1
koishore merged 2 commits into
mainfrom
spec-0.3-draft-lead

Conversation

@koishore

@koishore koishore commented Jun 3, 2026

Copy link
Copy Markdown
Member

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.

  • §2.1 Protocol versions matrix + the rule reference __protocol_version__ ≤ spec version.
  • 0.2 (now reference-backed): §7 approvals bound to intent_hash and 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 (draft — not yet in reference): §4.2 query-string-bound fingerprint (closes the confused-deputy gap where the query is excluded); §9 token retagged.
  • 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.0 and implements the 0.2 behaviour).

CI note: the conformance job installs the reference from delego@main; it goes green once the paired delego PR merges (until then main is the 0.1 reference and the resolve vectors fail — that is the drift detection working as intended).

AI assistance disclosure (required)

  • AI-generated, human-reviewed. Authored with Claude Code (Opus 4.8); the human author has reviewed every line and is accountable for it.

Kind of change

  • Normative change (approval binding, audit-chain verification, fingerprint roadmap).

Checklist

  • Branch PR (off main).
  • python validate.py is green.
  • python conformance.py is green against the paired reference.

For a normative change (additionally)

  • Added CTK vectors (resolve.json) regenerated from the reference.
  • Updated the §2.1 version matrix and tagged new clauses (since 0.2) / (0.3, draft).
  • Spec leads the reference; __protocol_version__ (0.2.0) ≤ spec (0.3.0-draft).
  • No receipt-field/canonicalization change in 0.2 (the §4.2 query-string change is 0.3, draft); CHANGELOG.md updated.

koishore and others added 2 commits June 4, 2026 01:42
…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 koishore left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 / denied lifecycle match the reference exactly; resolve.json vectors 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__ ≤ spec rule 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 gateconformance.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.

@koishore koishore merged commit 31304e2 into main Jun 3, 2026
3 of 4 checks passed
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