context layer protocol

draft technical specification v0.2#

change log#

• 2026.08.17 · v0.2 draft · purpose codes, lite profile, expires_at unification

abstract#

the context layer is an application-layer protocol for exchanging purpose-bound context between a user-controlled context vault & external applications, agents, models, discovery systems & user interfaces. it defines source & provenance records, context requests, policy decisions, scoped context bundles, proposed memory updates & operation receipts.

the protocol's central invariant is that a consumer receives an approved bundle rather than unrestricted raw-vault access. the specification is transport-neutral. an HTTP binding & adapter guidance are defined as profiles; existing transports & domain protocols retain their own semantics.

this document defines the target contract. the current project is an interactive demonstrator & does not yet implement the complete protocol.

1. requirements language#

the key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY & OPTIONAL in this document are to be interpreted as described in BCP 14 when & only when, they appear in all capitals.

normative requirements apply only to an implementation claiming conformance with the named profile. descriptive text & examples are informative unless explicitly labeled normative.

2. status & scope#

2.1 in scope#

this draft specifies:

• the trust boundary between a context vault & a context consumer
• stable envelopes for source events, derived claims, context requests, policy decisions, scoped context bundles, discovery results, proposed memory updates & receipts
• the lifecycle for outbound context, inbound discovery & memory writeback
• minimum policy inputs & disclosure constraints
• provenance & expiry requirements
• a transport-neutral core & an optional HTTP binding
• conformance roles & failure behavior
• security & privacy requirements that are specific to context movement

2.2 protocol boundary#

context layer governs the context exchange: purpose-bound requests, policy decisions, scoped bundles, receipts & proposed writeback. it composes with deployment-selected transport, identity, authentication, cryptography, storage, source authorization & payment systems.

a conforming deployment MUST preserve source permissions & select identity, encryption, key-management, storage, audit & redaction controls appropriate to its threat model. conformance does not imply legal compliance or correct model output.

3. design goals & invariants#

a conforming implementation MUST preserve these invariants:

1. no ambient raw-vault access. a context consumer MUST NOT receive an unrestricted vault query interface as the default exchange mechanism.
2. purpose-bound requests. every disclosure MUST be tied to an authenticated requester, declared purpose, recipient, requested scope & validity window.
3. reducible scope. a policy engine MUST be able to grant a strict subset of a request.
4. provenance continuity. every disclosed derived claim MUST contain or reference enough provenance to identify its supporting source records within the authority boundary.
5. expiry. every scoped bundle MUST have an explicit expiration time or a single-use constraint. the CL-Core-Lite profile requires both a finite expires_at & single_use: true.
6. non-escalation. a consumer MUST NOT infer permission for fields, tools, actions, retention, or onward disclosure that are absent from a bundle.
7. proposed writeback. agent-generated memory MUST enter as a proposal unless an explicit policy grants automatic commit for that exact proposal class.
8. receipted sensitive operations. a required receipt path MUST be available before a sensitive operation begins. an implementation MUST NOT report success until its completion receipt is durable.
9. minimum reveal for discovery. external matching MUST return only policy-approved result fields & MUST NOT expose private match features or scores unless explicitly granted.
10. native-protocol preservation. adapters MUST preserve security-relevant semantics from the source protocol rather than flattening them into unauthenticated text.

4. architecture#

4.1 components#

one process MAY implement several components, but logical responsibilities & authorization checks MUST remain separable & testable.

4.2 trust zones#

the minimum deployment model contains three zones:

1. vault zone: raw sources, private claims, identity bindings, policy & keys.
2. controlled exchange zone: policy engine, proxies, bundle issuer & receipt writer.
3. consumer or untrusted zone: external apps, remote agents, public discovery systems, relays, models & UI plug-ins.

the consumer MAY be locally operated & still be treated as a separate trust zone. process locality is not proof of authorization.

4.3 core flow#

native source
  -> capture + source tagging
  -> normalize + deduplicate
  -> extract claims + provenance
  -> user-controlled vault
  -> authenticated ContextRequest
  -> PolicyDecision
  -> semantic or discovery proxy
  -> ScopedContextBundle or MinimumRevealResponse
  -> consumer action
  -> Receipt
  -> optional MemoryUpdateProposal
  -> validation + approval + commit receipt

5. terminology#

subject the person, organization, project, device, or other principal whose context is governed. the subject may be represented by a deployment-local pseudonymous identifier.

source event an immutable or versioned record of an observed native event plus origin metadata. it is evidence, not automatically a fact.

claim a typed statement derived from one or more source events. a claim has provenance, confidence, validity & status.

vault the authority boundary that stores & governs source events, claims, summaries, identities, policies & receipts. "user-owned" refers to control & delegation, not necessarily physical device location.

context request a request for specific context for a named purpose, recipient, task, retention period & action set.

policy decision the versioned outcome of evaluating a request against identity, consent, sensitivity, purpose, recipient, action, expiry & receipt rules.

semantic proxy the outbound enforcement component that produces the least-context representation allowed by policy.

discovery proxy the inbound enforcement component that evaluates an external query against private context & returns a minimum-reveal result.

scoped context bundle an immutable, expiring packet of approved context, provenance, instructions, capabilities, restrictions & receipt requirements.

receipt a logically append-only record of a request, decision, transform, disclosure, model call, tool call, external action, or memory operation.

memory update proposal a candidate addition, change, contradiction, or retraction that has not yet been committed as durable context.

6. common representation rules#

6.1 serialization#

the core representation is JSON encoded as UTF-8.

every top-level object MUST contain:

identifiers SHOULD be opaque URIs such as urn:cl:bundle:019.... identifiers MUST NOT embed email addresses, names, access tokens, raw content, or other unnecessary private data.

timestamps MUST use RFC 3339 format & SHOULD be normalized to UTC. implementations MUST preserve the original timestamp & timezone when they are material to the source.

6.2 media type#

this draft uses application/vnd.context-layer+json as an experimental media-type string. it is not IANA registered. production interoperability work MUST either register an appropriate media type or negotiate a deployment-specific type without misrepresenting registration status.

6.3 extension fields#

the five CL-Core-Lite object schemas in this draft are closed: implementations MUST reject unknown top-level fields. version 0.2-draft does not define portable extensions or required_extensions members.

an experimental profile MAY publish a derived schema with a collision-resistant namespace, but an object using that profile is not a core 0.2-draft object unless the profile is explicitly negotiated. a future specification revision may define optional & required extension negotiation; implementations MUST NOT silently treat unknown fields as authorized extensions before then.

6.4 integrity#

objects MAY include an integrity object with a digest, canonicalization method & signature reference. a signature MUST cover the protocol version, object type, identifier, issuer, timestamps & all security-relevant fields.

this draft does not mandate a signing suite. deployments MUST define canonical serialization & key verification before claiming cryptographically verifiable receipts or bundles.

7. core data objects#

the examples in this section use synthetic values & omit optional fields for readability.

7.1 source_event#

a source_event records evidence captured from a native source.

required fields:

• subject_ref
• occurred_at or an explicit occurred_at_unknown: true
• captured_at
• source.adapter
• source.native_id_ref or source.native_id_digest
• payload_ref
• classification
• provenance

{
  "spec_version": "context-layer/0.2-draft",
  "type": "source_event",
  "id": "urn:cl:event:evt_1042",
  "created_at": "2026-08-12T14:31:04Z",
  "issuer": { "id": "urn:cl:adapter:email-local" },
  "subject_ref": "vault://subjects/primary",
  "occurred_at": "2026-08-12T14:30:55Z",
  "captured_at": "2026-08-12T14:31:04Z",
  "source": {
    "adapter": "email",
    "account_ref": "vault://accounts/work-mail",
    "native_id_digest": "sha256:EXAMPLE"
  },
  "payload_ref": {
    "ref": "vault://objects/message-1042",
    "media_type": "message/rfc822"
  },
  "classification": ["private", "communications"],
  "provenance": [{ "kind": "direct_capture", "confidence": 1.0 }]
}

the event envelope SHOULD reference raw payload stored inside the vault rather than duplicate sensitive payload into every index. a capture adapter MUST preserve native signatures, event identifiers, authorization context & deletion markers when the source protocol provides them.

7.2 context_claim#

a context_claim is a typed statement supported by source events or other claims.

required fields:

• subject_ref
• predicate
• object
• status
• confidence
• provenance_refs
• validity

{
  "spec_version": "context-layer/0.2-draft",
  "type": "context_claim",
  "id": "urn:cl:claim:deadline-1042",
  "created_at": "2026-08-12T14:31:10Z",
  "issuer": { "id": "urn:cl:extractor:commitments-v2" },
  "subject_ref": "vault://projects/launch",
  "predicate": "requested_delivery_date",
  "object": { "value": "2026-08-14", "datatype": "date" },
  "status": "derived",
  "confidence": 0.93,
  "validity": { "from": "2026-08-12T14:30:55Z", "expires_at": null },
  "provenance_refs": ["urn:cl:event:evt_1042"]
}

valid status values are asserted, derived, disputed, superseded & retracted. a contradiction MUST NOT be resolved by silently deleting the losing branch. the resolution SHOULD identify which claim supersedes another & why.

7.3 context_request#

a context_request asks the vault to release or use context.

required fields:

• subject_ref
• requester
• recipient
• purpose_code
• task
• selectors
• requested_actions
• retention
• receipt_requirement
• expires_at

{
  "spec_version": "context-layer/0.2-draft",
  "type": "context_request",
  "id": "urn:cl:request:req_701",
  "created_at": "2026-08-12T14:33:00Z",
  "issuer": { "id": "urn:agent:reply-drafter" },
  "subject_ref": "vault://subjects/primary",
  "requester": {
    "principal": "urn:agent:reply-drafter",
    "authenticated_by": "oauth2",
    "client_instance": "urn:device:local-workstation"
  },
  "recipient": {
    "principal": "urn:model:configured-drafting-model",
    "onward_disclosure": "forbidden"
  },
  "purpose_code": "draft.response",
  "purpose": "draft a response to the launch-timeline request",
  "task": { "kind": "draft_only", "user_visible": true },
  "selectors": [
    { "predicate": "requested_delivery_date" },
    { "predicate": "requesting_stakeholder" }
  ],
  "requested_actions": ["model.generate_text", "email.create_draft"],
  "retention": { "mode": "ephemeral", "max_seconds": 86400 },
  "receipt_requirement": { "level": "operation", "required": true },
  "expires_at": "2026-08-12T14:38:00Z"
}

in request & decision receipt requirements, level & required MUST agree: none requires required: false, while decision & operation require required: true. all other pairings are invalid.

purpose_code is the normative policy input. optional purpose text is informative & MUST NOT broaden authorization beyond the registered code. a request MUST NOT use wildcards for selectors or actions unless a separate policy explicitly permits that wildcard for the requester & subject.

7.3.1 purpose code registry#

the v0.2 core registry is deliberately small:

core codes are lowercase dotted names. deployment extensions MUST use a collision-resistant lowercase namespace beginning with x., for example x.example.review.contract. an unknown code MUST be denied unless policy lists the exact code. implementations MUST NOT authorize a purpose by prefix matching, semantic similarity, or inference from optional purpose text.

7.4 policy_decision#

a policy_decision records the result of evaluating a context request.

required fields:

• request_ref
• decision
• policy_snapshot
• granted_selectors
• denied_selectors
• granted_actions
• denied_actions
• transform_requirements
• retention
• onward_disclosure
• receipt_requirement
• expires_at
• reason_codes

valid decisions are:

• allow
• allow_with_reductions
• deny
• needs_approval

{
  "spec_version": "context-layer/0.2-draft",
  "type": "policy_decision",
  "id": "urn:cl:decision:dec_701",
  "created_at": "2026-08-12T14:33:01Z",
  "issuer": { "id": "urn:cl:policy-engine:local" },
  "request_ref": "urn:cl:request:req_701",
  "decision": "allow_with_reductions",
  "policy_snapshot": {
    "version": "personal-policy/42",
    "digest": "sha256:d12c2f24d4cb6a6b45014e3d355ad50a2e1492670635c9c2783e81e3684283bb"
  },
  "granted_selectors": [
    { "predicate": "requested_delivery_date" },
    { "predicate": "requesting_stakeholder" }
  ],
  "denied_selectors": [{ "predicate": "confidential-budget" }],
  "granted_actions": ["model.generate_text", "email.create_draft"],
  "denied_actions": ["email.send"],
  "transform_requirements": ["redact:confidential-budget", "compress:task-facts"],
  "retention": { "mode": "ephemeral", "max_seconds": 86400 },
  "onward_disclosure": "forbidden",
  "receipt_requirement": { "level": "operation", "required": true },
  "expires_at": "2026-08-12T14:38:00Z",
  "reason_codes": ["PURPOSE_ALLOWED", "SCOPE_REDUCED", "SEND_NOT_APPROVED"]
}

a decision MUST reference the exact policy snapshot evaluated. a later policy change MUST NOT silently broaden an already-issued decision or bundle.

7.5 scoped_context_bundle#

a scoped_context_bundle is the only standard object through which a general context consumer receives disclosed context.

required fields:

• subject_alias
• request_ref
• decision_ref
• recipient
• purpose_code
• issued_at
• expires_at
• single_use with the exact value true for CL-Core-Lite
• context
• provenance
• instructions
• capabilities
• restrictions
• receipt_contract

{
  "spec_version": "context-layer/0.2-draft",
  "type": "scoped_context_bundle",
  "id": "urn:cl:bundle:ctxb_209",
  "created_at": "2026-08-12T14:33:02Z",
  "issuer": { "id": "urn:cl:bundle-issuer:local" },
  "subject_alias": "urn:cl:alias:subject-for-req-701",
  "request_ref": "urn:cl:request:req_701",
  "decision_ref": "urn:cl:decision:dec_701",
  "recipient": "urn:model:configured-drafting-model",
  "purpose_code": "draft.response",
  "purpose": "draft a response to the launch-timeline request",
  "issued_at": "2026-08-12T14:33:02Z",
  "expires_at": "2026-08-12T14:38:00Z",
  "single_use": true,
  "context": [
    {
      "claim": "The launch timeline was requested by Friday.",
      "predicate": "requested_delivery_date",
      "value": "2026-08-14",
      "confidence": 0.93,
      "provenance_handles": ["prov_1"]
    }
  ],
  "provenance": {
    "prov_1": {
      "kind": "opaque_vault_reference",
      "ref": "urn:cl:provenance:opaque-1042"
    }
  },
  "instructions": ["Draft only", "Do not send", "Do not infer budget status"],
  "capabilities": ["model.generate_text", "email.create_draft"],
  "restrictions": {
    "onward_disclosure": "forbidden",
    "memory_write": "proposal_only",
    "raw_vault_resolution": "forbidden",
    "retention_seconds": 300
  },
  "receipt_contract": {
    "required": true,
    "required_operations": ["bundle.consume", "model.call", "email.create_draft"]
  }
}

the bundle MUST NOT contain resolvable raw-vault credentials. a provenance handle exposed to a consumer SHOULD be opaque & SHOULD require a separate authorized request to resolve. consumers MUST stop using a bundle after expiry & SHOULD delete cached material according to the retention contract.

bundles SHOULD be immutable. a change in scope, context, actions, or expiry SHOULD create a new bundle with a reference to the prior bundle.

7.6 minimum_reveal_response#

a discovery proxy returns a minimum_reveal_response.

required fields:

• request_ref
• result
• reveal
• requires_user_approval
• query_budget_state
• expires_at

{
  "spec_version": "context-layer/0.2-draft",
  "type": "minimum_reveal_response",
  "id": "urn:cl:discovery-result:mr_88",
  "created_at": "2026-08-12T15:00:00Z",
  "issuer": { "id": "urn:cl:discovery-proxy:local" },
  "request_ref": "urn:cl:discovery-request:dr_88",
  "result": "possible_match",
  "reveal": {
    "statement": "Available for a paid prototype engagement",
    "contact_route": "approval_required"
  },
  "requires_user_approval": true,
  "query_budget_state": { "remaining": 4, "window_ends_at": "2026-08-12T16:00:00Z" },
  "expires_at": "2026-08-12T15:15:00Z"
}

the response MUST NOT expose private match features, raw similarity scores, or negative evidence unless policy explicitly grants them. implementations MUST rate-limit & correlate semantically similar queries, not only byte-identical requests.

7.7 memory_update_proposal#

a memory_update_proposal carries a candidate change without granting durable truth status.

required fields:

• subject_ref
• operation
• proposed_claims
• provenance_refs
• rationale
• submitted_by
• status
• approval_requirement
• expires_at

{
  "spec_version": "context-layer/0.2-draft",
  "type": "memory_update_proposal",
  "id": "urn:cl:proposal:mup_17",
  "created_at": "2026-08-12T15:12:00Z",
  "issuer": { "id": "urn:agent:reply-drafter" },
  "subject_ref": "vault://projects/launch",
  "operation": "add_or_contradict",
  "proposed_claims": [
    {
      "predicate": "requested_delivery_date",
      "object": { "value": "2026-08-13", "datatype": "date" },
      "confidence": 0.55
    }
  ],
  "provenance_refs": [],
  "rationale": "The latest conversation may imply Thursday, but no source was captured.",
  "submitted_by": "urn:agent:reply-drafter",
  "status": "pending_validation",
  "approval_requirement": ["source_required", "user_confirm"],
  "expires_at": "2026-08-13T15:12:00Z"
}

an implementation MUST NOT commit a proposal lacking required provenance or approval. rejection & expiry MUST be recorded without deleting the proposal's audit history when policy requires that history.

7.8 receipt#

a receipt records a security-relevant operation.

required fields:

• operation
• actor
• subject_ref or a policy-approved alias
• request_ref &/or decision_ref when applicable
• bundle_ref when applicable
• started_at
• completed_at
• outcome
• policy_snapshot
• input_digest
• output_digest
• user_summary

{
  "spec_version": "context-layer/0.2-draft",
  "type": "receipt",
  "id": "urn:cl:receipt:rcpt_812",
  "created_at": "2026-08-12T15:13:02Z",
  "issuer": { "id": "urn:cl:receipt-writer:local" },
  "operation": "semantic_proxy.redact",
  "actor": "urn:cl:semantic-proxy:local",
  "subject_ref": "urn:cl:alias:subject-for-req-701",
  "request_ref": "urn:cl:request:req_701",
  "decision_ref": "urn:cl:decision:dec_701",
  "bundle_ref": "urn:cl:bundle:ctxb_209",
  "started_at": "2026-08-12T15:13:01Z",
  "completed_at": "2026-08-12T15:13:02Z",
  "outcome": "success",
  "policy_snapshot": "sha256:d12c2f24d4cb6a6b45014e3d355ad50a2e1492670635c9c2783e81e3684283bb",
  "input_digest": "sha256:9236d81bdff6b52fd2a51b455332f2454feff22544471d57bd1e928498cb56b7",
  "output_digest": "sha256:64983d082c66338e0231cca68110160043e79ef13f792c1ff6c043846fedea09",
  "user_summary": "Removed confidential budget context before creating the drafting bundle.",
  "payload_included": false
}

receipts MUST NOT contain secrets, raw authorization headers, model API keys, full private prompts, or raw source payloads. the receipt contract exposes an optional nullable supersedes_ref field. a correction MUST be represented by a new receipt with supersedes_ref set to the exact receipt URN of the prior record. a non-correction receipt MAY omit supersedes_ref or set it to null.

8. protocol lifecycles#

8.1 ingestion lifecycle#

1. authenticate or classify the native source.
2. capture a source event & native integrity metadata.
3. classify sensitivity before broad indexing.
4. normalize into stable event fields.
5. deduplicate while retaining every provenance path.
6. extract claims with confidence & validity.
7. detect contradictions & preserve branches.
8. store source & derived records under vault policy.
9. write ingestion receipts where policy requires them.

an untrusted source MUST NOT be promoted to a trusted claim solely because a model summarized it confidently.

8.2 outbound context lifecycle#

1. authenticate the requester & bind it to a client instance where possible.
2. validate the request schema, expiry, purpose, recipient & requested actions.
3. evaluate policy against a versioned snapshot.
4. obtain human approval when required.
5. resolve only granted selectors.
6. apply required redaction, aliasing, compression & routing.
7. assemble & optionally sign an immutable bundle.
8. deliver the bundle to the named recipient.
9. receive operation receipts from the consumer or trusted gateway.
10. expire & revoke the bundle according to policy.

any change to recipient, purpose, action, or requested scope MUST trigger a new decision.

8.3 inbound discovery lifecycle#

1. authenticate or classify the requester.
2. enforce request, identity, semantic & time-window rate limits.
3. validate that the query purpose is eligible for private matching.
4. evaluate the query inside the vault or controlled exchange zone.
5. apply minimum-reveal policy.
6. require approval before exposing a contact route or sensitive attribute.
7. return an expiring response.
8. write a receipt including query class, requester, decision & reveal class.

discovery systems SHOULD add noise, thresholds, batching, or other privacy defenses when repeated aggregate results could reveal private features. this draft does not mandate one privacy-preserving matching algorithm.

8.4 memory writeback lifecycle#

1. accept a proposal, not a direct mutation, from a consumer.
2. validate schema & submitter authority.
3. require source references for factual claims unless policy marks the claim type as subjective or explicitly source-free.
4. compare with current claims & detect contradictions.
5. calculate any required confidence or trust signals.
6. obtain approval according to claim sensitivity & automation policy.
7. commit, reject, or expire the proposal.
8. write a receipt & preserve supersession links.

automatic commit MAY be enabled only for narrowly defined, low-risk proposal classes with explicit policy & rollback behavior.

9. policy evaluation#

9.1 mandatory policy inputs#

the policy engine MUST evaluate at least:

• authenticated requester & client instance
• subject & delegated authority
• recipient & onward-disclosure status
• registered purpose_code & task class, plus optional explanatory purpose text
• requested selectors & sensitivity labels
• requested actions & side-effect class
• retention & bundle expiry
• applicable consent or approval state
• source trust & claim confidence where material
• receipt availability & required receipt level
• current rate limits & anomaly state

9.2 decision properties#

policy decisions MUST be deterministic with respect to their recorded inputs & policy snapshot, except for explicitly identified external signals such as risk scores. when nondeterministic or time-varying signals are used, the decision MUST record their values or stable references.

policies SHOULD deny by default when:

• requester identity cannot be verified to the required assurance level
• purpose_code is absent, unknown, or not authorized for the requester
• recipient is ambiguous
• requested scope uses an unauthorized wildcard
• consent or approval is missing
• retention exceeds policy
• a required receipt service is unavailable
• the request or bundle has expired
• an untrusted discovery requester exceeds its query budget

9.3 human approval#

an approval surface MUST show, in user-readable form:

• who is asking
• what context categories will be disclosed
• why they are requested
• which recipient will receive them
• which actions may occur
• how long access lasts
• whether onward disclosure is permitted
• what evidence will be written

approval identifiers MUST be single-use or bound to the exact request digest. a changed request MUST invalidate the prior approval.

9.4 writeback isolation#

consumer writeback MUST enter the authority boundary as a memory_update_proposal. a core consumer MUST NOT receive a direct raw-vault mutation capability. validation, contradiction handling, approval, commit & the resulting receipt remain distinct authority-side operations. a future companion profile MAY define those authority-side operations, but it MUST preserve proposal-only submission at the consumer boundary.

10. optional HTTP binding#

the context layer core is transport-neutral. this section defines an experimental HTTP profile using HTTP semantics.

10.1 transport requirements#

• production endpoints MUST use HTTPS with current TLS guidance.
• clients & servers MUST authenticate according to the deployment's identity profile.
• OAuth deployments SHOULD follow OAuth 2.0 security best current practice, RFC 9700.
• bearer tokens MUST be audience-restricted & least-privilege.
• credentials MUST NOT appear in URLs.
• mutating requests SHOULD support an Idempotency-Key header.
• requests MUST include Context-Layer-Version: 0.2-draft or negotiate an equivalent version.
• request & response bodies use application/vnd.context-layer+json for this experimental profile.

10.2 capability document#

an implementation MAY expose a capability document at:

GET /.well-known/context-layer

this path is an unregistered draft convention. the response should list protocol versions, roles, endpoint URLs, supported object types, auth metadata, extensions, receipt capabilities, maximum bundle lifetime & conformance report location.

10.3 suggested resource endpoints#

these paths are a draft binding, not globally registered endpoints.

the following minimal OpenAPI 3.1 fragment is informative. it illustrates schema reuse without defining authentication or deployment-specific error policy:

openapi: 3.1.0
info:
  title: Context Layer Core Lite
  version: 0.2-draft
paths:
  /context/v1/requests:
    post:
      operationId: submitContextRequest
      requestBody:
        required: true
        content:
          application/vnd.context-layer+json:
            schema:
              $ref: https://sierracatalina.com/context-layer/implementation/context-request.schema.json
      responses:
        "201":
          description: Policy decision recorded
          content:
            application/vnd.context-layer+json:
              schema:
                $ref: https://sierracatalina.com/context-layer/implementation/policy-decision.schema.json

10.4 status & error behavior#

recommended HTTP statuses:

• 200 OK: synchronous successful read or decision result
• 201 Created: request, bundle, proposal, or receipt created
• 202 Accepted: asynchronous evaluation or approval pending
• 400 Bad Request: invalid syntax or schema
• 401 Unauthorized: authentication absent or invalid
• 403 Forbidden: authenticated principal lacks permission
• 404 Not Found: unknown object or intentionally concealed existence
• 409 Conflict: idempotency conflict, stale policy, or contradictory state transition
• 410 Gone: expired or revoked bundle
• 413 Content Too Large: payload exceeds limits
• 415 Unsupported Media Type: unsupported representation
• 422 Unprocessable Content: valid syntax with invalid protocol semantics
• 429 Too Many Requests: rate or query budget exceeded
• 503 Service Unavailable: required policy, approval, vault, or receipt component unavailable

error bodies MUST use a stable machine code & a safe user message. they MUST NOT expose policy internals, private match features, secrets, stack traces, or raw upstream responses.

{
  "spec_version": "context-layer/0.2-draft",
  "type": "error",
  "id": "urn:cl:error:err_44",
  "created_at": "2026-08-12T16:00:00Z",
  "issuer": { "id": "urn:cl:gateway:local" },
  "code": "BUNDLE_EXPIRED",
  "message": "The scoped context bundle is no longer valid.",
  "retryable": false
}

10.5 CL-Core-Lite profile#

CL-Core-Lite is the smallest v0.2 implementation profile intended for interoperable experiments. a conforming implementation MUST:

• validate the v0.2 context_request, policy_decision, scoped_context_bundle, memory_update_proposal & receipt contracts
• support allow, allow_with_reductions, deny & needs_approval
• authorize the exact registered or explicitly extended purpose_code; optional purpose text is never an authorization input
• require every scoped bundle to carry a finite expires_at & single_use: true & reject expired or replayed bundles
• bind every decision to the exact policy snapshot & every bundle to its request, decision & recipient
• keep raw vault objects & resolvable vault credentials outside consumer bundles
• accept consumer memory writeback only as a proposal
• produce the receipts required by the request & decision before reporting success

lite conformance does not imply production security, adoption as a standard, or conformance with the optional discovery, adapter, signature, or network deployment profiles.

11. security & privacy requirements#

11.1 authentication & authorization#

authentication proves a principal; policy authorizes a context use. implementations MUST keep those decisions distinct.

• every network requester MUST be authenticated or explicitly assigned an untrusted_anonymous class.
• tokens MUST be validated for issuer, audience, expiry & required scope.
• a service MUST NOT pass a client token through to an unrelated downstream service.
• local HTTP servers SHOULD bind to loopback & require a per-launch authorization token or equivalent process boundary.
• browser endpoints MUST validate origin & CSRF defenses where credentials or session creation are involved.
• static public assets MUST be separated from credential-bearing session endpoints in production.

11.2 secret handling#

• long-lived provider credentials MUST remain server-side or in platform-appropriate secure storage.
• credentials MUST NOT be embedded in bundles, receipts, HTML, mobile binaries, source-control archives, logs, prompts, or query strings.
• client-facing realtime or model sessions SHOULD use short-lived, narrowly scoped client credentials when the provider supports them.
• credential rotation & revocation MUST be operationally documented.

11.3 data minimization#

• source payloads SHOULD remain inside the vault.
• bundles MUST contain only fields granted by the decision.
• provenance exposed outside the vault SHOULD use opaque handles.
• logs & metrics MUST avoid raw context unless separately authorized.
• receipts SHOULD use digests & categories rather than duplicate sensitive content.

11.4 prompt & content injection#

captured content is untrusted data, even when it came from a known account. implementations MUST prevent source content from becoming executable agent instructions merely because it appears in retrieved context.

bundles SHOULD separate:

• facts & source quotations
• system or policy instructions
• user instructions
• tool manifests
• untrusted content

consumers MUST NOT allow a source document to expand its own permissions, tools, retention, or recipient list.

11.5 semantic transformation risk#

redaction & summarization can fail. high-risk deployments SHOULD combine deterministic field-level policy with semantic transforms & MUST test for under-redaction, indirect identifiers, reconstruction & context leakage.

the semantic proxy SHOULD report which transformations ran & their confidence. a policy MAY require human review when a transform cannot establish sufficient confidence.

11.6 discovery inference#

rate limiting by requester IP alone is insufficient. discovery implementations SHOULD account for requester identity, semantic similarity, target subject, result pattern, time window & coordinated clients.

negative responses can reveal information. deployments MAY return uniform responses, add delay, batch approvals, or use privacy-preserving matching techniques according to threat model.

11.7 revocation & deletion#

bundle revocation cannot guarantee deletion by an already-compromised recipient. implementations MUST state this limitation. revocation MUST prevent future authorized retrieval & use within conforming components.

source deletion MUST propagate according to legal, user & provenance requirements. receipts MAY need to retain non-content evidence after source deletion, but such retention MUST be explicit & minimized.

11.8 receipt privacy#

receipts create a second sensitive dataset. they can reveal relationships, timing, tools, models & behavior even when payloads are omitted. receipt access MUST have independent policy, retention, export & deletion rules.

11.9 availability & fail-closed behavior#

when the policy engine, approval surface, key verifier, or required receipt store is unavailable before an operation, sensitive disclosure MUST fail closed. implementations MAY permit explicitly defined low-risk offline operations using a cached, unexpired policy snapshot.

if an irreversible external side effect succeeds but its completion receipt cannot be stored, the implementation MUST report the result as indeterminate, retry the receipt idempotently & block dependent actions. it MUST NOT claim that the external side effect was rolled back merely because receipt persistence failed.

12. interoperability rules#

adapters MUST:

• declare the native protocol & adapter version
• preserve native identifiers or collision-resistant digests
• preserve original & capture timestamps
• preserve signatures, verification status, deletion markers & authorization context when available
• map source trust & visibility explicitly
• avoid converting untrusted content into trusted instructions
• document lossy transformations
• support deterministic export fixtures for conformance testing

consumers MUST:

• validate bundle version, issuer, recipient, expiry & integrity before use
• enforce capability & action allowlists
• treat missing permissions as denied
• isolate untrusted context from control instructions
• produce required receipts
• delete or make inaccessible expired context according to the retention contract
• submit proposed memory updates through the protocol rather than direct vault writes

see implementation & interoperability profiles for protocol-specific mappings.

13. conformance profiles#

an implementation may claim one or more roles.

13.1 CL-Core-Issuer#

must implement:

• context_request validation
• versioned policy_decision
• scope reduction
• scoped_context_bundle issuance
• expiry & recipient binding
• required receipt contract
• raw-vault isolation tests

13.2 CL-Core-Consumer#

must implement:

• bundle validation
• capability & restriction enforcement
• expiry handling
• required receipts
• proposal-only memory writeback
• context deletion or inaccessibility after expiry

13.3 CL-Discovery#

must implement:

• authenticated or explicitly classified discovery requests
• query budgets & semantic probe correlation
• private evaluation
• minimum-reveal responses
• approval escalation
• discovery receipts

13.4 CL-Memory#

must implement:

• source events & derived claims
• provenance continuity
• contradiction & supersession handling
• memory update proposals
• approval & commit receipts

13.5 CL-Receipt-Store#

must implement:

• logical append-only semantics
• correction by supersession
• integrity & ordering strategy
• independent receipt access policy
• secret & payload minimization
• export & verification tooling

13.6 CL-Adapter#

must document:

• native protocol & version
• inbound & outbound mapping
• authentication boundary
• lossy fields
• trust & visibility mapping
• deletion & edit behavior
• test fixtures

14. required conformance tests#

every claimed role MUST publish machine-readable test results for applicable cases.

minimum tests include:

1. reject an expired request.
2. reject a bundle addressed to another recipient.
3. reduce a request containing one allowed & one denied selector.
4. prove that denied source payload text is absent from the serialized bundle.
5. preserve provenance for each disclosed derived claim.
6. reject an unauthorized action even when an instruction string asks for it.
7. fail closed when a required receipt path is unavailable before execution; report & recover an indeterminate outcome when an irreversible action succeeds but completion-receipt persistence fails.
8. reject replay of a single-use bundle.
9. keep a memory update as pending when required provenance is missing.
10. preserve contradictory claims rather than overwrite them silently.
11. rate-limit semantically equivalent discovery probes.
12. ensure errors & receipts contain no credentials or raw private payloads.
13. round-trip each adapter fixture without losing documented security-relevant fields.
14. verify that logs do not contain access tokens, API keys, or raw vault objects.

a test that merely confirms valid JSON is insufficient evidence of policy or privacy conformance.

15. versioning#

objects carry an explicit spec_version. implementations MUST reject unsupported major versions. a compatible minor version MUST NOT change the meaning of existing required fields or weaken an invariant.

draft identifiers are unstable. production data SHOULD NOT be committed to 0.2-draft schemas without a migration plan.

schema evolution rules:

• additive optional fields MAY be introduced in a compatible minor version.
• required fields MUST NOT be added without a new major version or negotiated required extension.
• enum values MAY be added only where consumers are required to handle unknown values safely.
• security-sensitive default changes require a major version.
• deprecation MUST include an alternative & a migration window.

16. implementation status of this repository#

as of 2026-08-21, the public project provides:

• five v0.2 JSON schemas for requests, decisions, bundles, memory proposals & receipts
• a dependency-free reference module with deterministic reduction, validation, transforms & minimized receipts
• an experimental single-user local core with an AES-256-GCM vault, four-state policy evaluation, HMAC-authenticated bundle envelopes & an authenticated append-only receipt log
• one narrow UTF-8 files adapter & one local-agent consumer as conformance evidence
• synthetic positive & negative fixtures, a minimized demo & SHA-bound test vectors
• a reviewed v0.2 technical specification & informative implementation profiles
• an unsubmitted Nostr interoperability discussion draft

it does not currently provide:

• a production context vault
• a production policy engine or approval service
• a portable third-party signature suite, managed key custody, or hostile-administrator protection
• production source adapters or consumer integrations for the listed external protocols
• an independent conformance program or security certification
• a hardened multi-user network service
• a completed iOS client

the local HMAC envelope & receipt anchor demonstrate integrity inside the tested single-user profile; they are not portable signatures or a hardware-rooted audit system. the files adapter, local consumer & HTML demo use synthetic data & MUST NOT be treated as production integrations.

17. open design questions#

the next specification revision needs decisions on:

• canonical JSON & signature suite
• identifier & pseudonym rotation strategy
• standard sensitivity & purpose vocabularies
• policy language & delegation model
• receipt ordering, transparency & selective disclosure
• bundle revocation & consumer attestation
• privacy-preserving discovery algorithms & leakage budgets
• portable encrypted provenance references
• cross-device vault sync & recovery
• deletion propagation across derived claims & receipts
• user-readable consent & receipt UX requirements
• registration of media types & well-known metadata
• governance, change control & an independent conformance process

18. normative & informative references#

18.1 normative foundations for this draft#

• BCP 14: RFC 2119 & RFC 8174
• RFC 8259: JSON
• RFC 3339: internet timestamps
• RFC 9110: HTTP semantics
• RFC 8446: TLS 1.3
• RFC 9700: OAuth 2.0 security best current practice

18.2 informative interoperability references#

• ActivityPub
• AT protocol
• Nostr NIP-01
• Matrix specification
• model context protocol specification
• MCP security best practices
• Agent2Agent protocol
• IPFS concepts
• IPFS privacy & encryption
• OpenAI realtime API with WebRTC
• x402 documentation