Scaffold 0.4 (draft) — adoption-first, fully additive#13
Open
koishore wants to merge 1 commit into
Open
Conversation
Moves the document to 0.4 (draft). 0.4 is adoption-first and ENTIRELY ADDITIVE on the 0.3 preimage (changes no hashed or signed bytes; MAY be adopted by a 0.3 implementation). The one breaking item considered for 0.4 — folding request headers/body into the action_fingerprint — is deferred to avoid a re-integration tax. The reference still implements 0.3; these clauses are spec-led (draft, not yet in reference). New sections: - §2.2 Broker interface (the PEP contract) + separated-gateway profile (schema/broker-gateway.json): one contract a third party can implement against instead of reverse-engineering the reference. - §7.2 Approval lifecycle & routing metadata (reason, routing, expiry; expiry fails closed). Advisory; never settable by the Agent. - §7.3 Approval notification & callback protocol — approvals out of the local console onto any surface, Agent out of the loop (schema/approval-callback.json). Approval principal separate from the Agent; unverifiable/replayed callback leaves the approval pending. - §8.4 Receipt context (optional, UNSIGNED) — correlation metadata outside the signed payload; ignored by §8.1; never authorization- relevant. schema/receipt.json gains optional context. - §10 adds a '0.4 — additive (adoption)' conformance block; §11 adds security notes (callback authenticity/replay, broker idempotency, unsigned context). New examples + validate.py wiring. No CTK vector changes; conformance.py unaffected (reference 0.3 <= spec 0.4). validate.py + conformance.py green; all spec.md anchors resolve. Stacked on the spec-prose fix (#12) — that base supplies the corrected §2.1/§10 text these clauses build on.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Scaffolds 0.4 (draft) of the wire spec. 0.4 is adoption-first: the goal is to make the protocol consumable by the ICP (platform/security-eng teams shipping action-taking agents) and to give the buyer an approval+audit story — not to deepen the protocol.
Key decision: 0.4 is entirely additive. Every clause changes no hashed or signed bytes and MAY be adopted by a 0.3 implementation. The one breaking item considered for 0.4 — folding request headers/body into the
action_fingerprintpreimage — is deferred (a breaking preimage change invalidates parked approvals and forces re-integration; that's an adoption tax). The reference still implements 0.3; these clauses are spec-led (draft — not yet in reference).New sections
schema/broker-gateway.json). Consolidates the Broker's transport-agnostic obligations (reconstruct from the authorized action only · refuse what it can't reconstruct · verify a token per §9.1 if required · execute at most once · report outcome) so a third party can write a conformant broker without reverse-engineering the reference. A gateway must distinguish a refusal from an upstream result.reason,routing_group/required_approvers,expires_at(expiry fails closed →deny). Advisory only; on the approval record, not the fingerprint/receipt; never settable by the Agent; MUST NOT affect the §7 guards.schema/approval-callback.json). Outbound notification + signed single-use decision callback; the approval principal MUST be separate from the Agent; an unverifiable/replayed callback leaves the approvalpending(fail-closed). The callback carries no action, so the §7 P1/P2 guards still bind the action at release time.contextobject outside the signed payload for correlating receipts to operational identity (agent/session/trace/principal) without a breaking receipt change. Not tamper-evident; ignored by §8.1; MUST NOT carry authorization-relevant data.schema/receipt.jsongains an optionalcontext.v0.4-draft.New files
schema/approval-callback.json,schema/broker-gateway.json,examples/approval-callback.json,examples/broker-gateway.json— all wired intovalidate.py.Verification
validate.pygreen (incl. the four new example shapes).conformance.pygreen — no CTK vector changes;reference 0.3 <= spec 0.4.spec.md#anchors across the repo resolve.Merge order (stacked PR)
Based on
fix/spec-status-prose-0.3(#12), which supplies the corrected §2.1/§10 text these clauses build on. Merge #12 first. On squash-merge of #12 with branch delete, GitHub retargets this PR tomain; if the diff then shows #12's changes, rebase withgit rebase --onto main fix/spec-status-prose-0.3 draft/0.4-adoption-scaffoldto detach.Scope
Spec + schemas + examples + validator + docs only. No delego implementation changes (these are draft/spec-led). Landing is deliberately untouched — we don't publish a draft spec to the public site.