feat(consent): egress-scope vocabulary + append-only consent receipts

[macanderson]

Completes the receipt semantics noted missing in #25.

PR #32 landed the boolean consent gate — ConsentRecord (provider_id, data_flow, granted_scope, granted_at), ConsentStore (record/revoke/get/is_consented/permits), and host rejection of unconsented egress. That answers "is this provider allowed, right now, in this process?" It does not answer the question the issue was actually about: "what left the machine, to whom, who agreed, and when?", asked months later against a durable artifact.

This PR adds the two pieces that make consent an artifact rather than an event.

The egress-scope vocabulary

contextgraph-types/src/scope.rs introduces EgressScope — the four normative base classes as a real type:

Scope	Wire string	Off-machine?
LocalOnly	local-only	no
OrgTenant	org-tenant	yes
ThirdPartyIndex	third-party-index	yes
ThirdPartyModel	third-party-model	yes

Extensible by namespaced Custom("vendor:scope-name") scopes, which MUST carry a : with non-empty sides so a custom scope can never collide with — or be spelled as — a base class. Everything but local-only is off-machine, including an unrecognized custom scope: the conservative default is that an unknown destination leaves, so a host never under-gates something it doesn't recognize.

Providers declare scopes in the new DataFlow.egress_scopes. The field is #[serde(default, skip_serializing_if = "Vec::is_empty")], so a provider that declares no scopes produces byte-identical wire output to before — the change is strictly additive and every existing provider keeps working under the legacy boolean gate.

DataFlow::scopes_consistent() holds a provider to a truthful declaration: an off-machine scope alongside egress: false is a contradiction (claiming local posture while naming a destination that leaves), and a non-namespaced custom scope is malformed.

Consent receipts

ConsentReceipt records provider_id, scope, provider_name/provider_version pinned at grant time (so a later rename can't retroactively rewrite what was agreed), grantor (Human(id) | Policy(id) — a named party, not an anonymous "yes"), granted_at, and optional expires_at.

Receipts live in an append-only ledger (ConsentStore::record_receipt): a new grant never edits or erases an old one, so the history of consent is the audit trail. Expiry never prunes it either — an expired receipt stops being live but stays on the record, which is what makes the window of authorized egress itself auditable.

The runtime gate is deliberately presence-based and clock-free (has_receipt), so a query decision never depends on wall-time. Expiry is a first-class property (ConsentReceipt::is_live) that a host enforcing it consults via ConsentStore::live_receipt against its own now.

Host enforcement

ConsentStore::evaluate returns a typed ConsentDecision:

• off-machine scopes declared → permitted only when every such scope has a receipt; otherwise NeedsReceipts(scopes) naming exactly what lacks one. A boolean ConsentRecord does not satisfy a scope gate — there's a test pinning that specifically.
• boolean egress only → the pre-scope legacy gate, unchanged.
• purely local → permitted.

Refusal surfaces as HostError::ConsentScopeRequired { id, scopes }, naming exactly the scopes that would have leaked, and the query payload is never transmitted — the host test asserts the provider was never even called.

Conformance

Both sides of the issue's requirement:

• Provider declaration — a new consent-scope check validates declared scopes against data_flow.egress, driven by a real --misbehave scope-lie fixture mode that declares third-party-index alongside egress: false. The test asserts the handshake still passes and only the scope check catches the lie, so it's proven to be that check doing the work.
• Host enforcement — a host test drives a scoped provider through refusal (payload not transmitted, typed error names the scope) and then through acceptance after a receipt is recorded.

Audit scenario

docs/context-reuse.md §3 adds the worked scenario the issue asked for — an auditor asking six months later whether repository snippets reached an external model, answered field-by-field from the persisted ledger with no live process — plus normative requirements C5 (truthful declaration) and C6 (host rejection). schema/contextgraph-envelope.schema.json and examples/reference-messages.json are kept in sync with the types, mirroring how #32 handled it.

Notes for adjacent issues

• Structured error codes on the wire #9 (typed error codes): ConsentScopeRequired carries an inline note that its stable code string slots in alongside ConsentRequired when Structured error codes on the wire #9 lands. Not assigned here, to avoid inventing a code Structured error codes on the wire #9 will have to reconcile.
• Receipt placement: both the scope vocabulary and ConsentReceipt/Grantor live in contextgraph-types. A receipt never appears on the wire, but it follows UsageReport (Usage report envelope: a normative per-request roll-up of frame costs for metering and billing export #24) — whose own module doc calls it "a host-side artifact, not a wire message" and which lives in types anyway, because it is a protocol-defined shape. ConsentStore/ConsentDecision, the ledger and gate that consume receipts, stay in contextgraph-host.
• Zero new dependencies.

Verification

cargo fmt --all -- --check     # clean
cargo clippy --workspace --all-targets -- -D warnings   # clean
cargo test --workspace         # all green

https://claude.ai/code/session_01BvcuRRNHvpFSYLVhow4HGb

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery