Context reuse and final admission
Prepare context once, retain its short-lived reuse proof, and validate the exact bytes before each model request and complete response delivery. Configure a target and privacy mode using Inference privacy protection. Callers that require complete privacy checks must use enforcing mode. The caller owns model execution and delivery; a check does not execute a model or authorize spending.
Before upgrading a Server with this API, follow the coordinated SDK/CLI upgrade requirements. Older clients reject the new capability field even when protection is disabled.
Prepare once, validate each use
The default POST /v1/context/prepare response remains schema, status, content, and content_bytes.
Add include_reuse: true for:
{
"schema": "powercontext.prepared-context-with-reuse.v1",
"context": {
"schema": "powercontext.prepared-context.v1",
"status": "ready",
"content": "<complete prepared historical context>",
"content_bytes": 38
},
"reuse": {
"schema": "powercontext.context-reuse.v1",
"constraints": {
"preserve": ["content", "citations", "trust", "order"],
"refresh_on": ["permission_change", "source_ineligible", "context_boundary"]
},
"expires_at": "2026-10-26T12:05:00Z",
"binding": "<opaque encrypted binding>"
}
}Add include_receipt: true to request a bounded, content-free preparation receipt. With both options enabled,
the receipt is included in context.receipt; it does not change the injected content or replace the reuse proof.
The angle-bracket values, byte count, and time above are documentation examples, not a runtime masking format.
Use the exact returned content and binding. The Python
client returns either PreparedContext or PreparedContextWithReuse; narrow that union before reading its fields.
In process, use runtime.context.for_scope(scope_id).prepare(request). Its validate_reuse operation checks the
retained proof without retrieval or embedding; embedded applications supply their own current authorization context.
The reuse profile supports a single Scope, selected Atomic Memory, and code evidence (include_code: true), without
context references. For Atomic Memory it records selected current revisions, lifecycle versions, and complete bounded historical dependencies. Exact
historical ancestors of a merge remain valid evidence when their owning domain permits them. Revised or forgotten
roots, revoked access, changed reference policy, expired bindings, and ineligible Sources stop reuse.
Other selected families are explicitly rejected for this option; ordinary preparation remains supported.
For code evidence it records each cited file's repository path and SHA-256 digest, with the index fingerprint for the record. Validation reads only the cited files from the Scope's current worktree, with the same path and exclusion rules as indexing. A changed, removed, or no-longer-indexable cited file, or an unavailable repository, stops reuse. An edit to a file that was not cited, or a rebuilt index, does not. Code files and Atomic Memory dependencies share the dependency limit.
Bindings are authenticated and encrypted, expire after five minutes, and are limited to 64 dependencies and eight ancestry levels. They do not grant access. Server bindings use the existing signing-secret material with a separate cryptographic purpose and persistent Server identity; processes sharing that deployment must share the secret. An embedded Runtime's default key is ephemeral. There is no stored prompt or response cache.
Check the actual final payload
Call POST /v1/context/check, operation check_context, at two distinct points:
before_send: after native provider rendering and cache settings, before writing any model request.before_release: after collecting the complete raw response, before exposing content, tool arguments, or errors.
Both use root scope_id, current authentication/delegation, and current Scope/resource authorization.
scope.read does not grant model spending or tool execution. Request fields cannot turn off deployment policy.
The optional X-PowerContext-Resolve-Target: true header is reserved for an authenticated
service principal with gateway.invoke and scope.read on the chosen Scope. On an allowed
before_send only, the check also returns target_endpoint and target_protocol from Core's
trusted profile; ordinary checks and blocked decisions never disclose the endpoint. Python
callers may opt in with PowerContextClient.check_context(request, resolve_target=True);
an allowed response without target fields is rejected by the client. Gateway
must send the exact approved bytes to this endpoint before valid_until, and require a new
check after a definite no-send. Missing target fields, an unsupported protocol, or Core
unavailable before admission must result in zero sends. An already issued admission remains
usable until valid_until; neither a Core outage nor a configuration change retroactively revokes
it. UDS alone is not authentication; remote Core access carrying this
privileged credential requires HTTPS (loopback HTTP is allowed). This is an endpoint binding, not
a claim about the provider account or region behind independently supplied credentials. The
Gateway client key must be distinct from its Core service credential; this single service identity
does not provide per-client Scope authorization.
The versioned JSON carrier contains the original JSON text, not a reconstructed object:
{
"scope_id": "<existing Scope>",
"phase": "before_send",
"target_profile": "coding",
"payload": {
"schema": "powercontext.model-json-payload.v1",
"headers": {"content-type": "application/json"},
"body": "{\"model\":\"approved-model\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"
},
"prepared_contexts": []
}For each retained prepared block, include its binding and a powercontext.model-json-text-location.v1 location:
JSON pointer, start_byte, and end_byte. Offsets address decoded UTF-8 text with half-open bounds. The whole exact
block must remain in a supported user-message text position, preserving its historical-data trust wrapper and order.
System/developer promotion, changed text, overlapping/reordered locations, and unbound prepared markers are rejected.
A target requiring prepared context cannot silently downgrade to a pure check.
Admission does not redact text or restore placeholders. Replacing a name, path, address, or other value inside a prepared block changes its content and invalidates its exact reuse proof; even a reversible replacement is not the prepared value. A gateway must not mask an approved request or restore values into an approved response and reuse that approval for the changed bytes. A changed payload needs its own admission; this API supplies no placeholder mapping or authorization to reverse a privacy transformation.
Callers requiring complete privacy checks accept only allow with coverage.complete=true. block and withhold return HTTP
200 because a decision was made, but neither permits execution. Invalid carriers/locators return 422; authorization
failure returns 401/403; an oversized payload returns 413. If the required check is unavailable, do not send or release.
In disabled, shadow, and advisory modes, Core can return allow with a binding after validating authorization
and context reuse, but reports coverage.complete=false. Disabled skips privacy inspection; shadow and advisory
observe requests without blocking and do not inspect responses. Enforcing retains request and response enforcement.
Gateway accepts incomplete privacy coverage only when its trusted Core capability discovery explicitly reports
enforcing=false; it still requires an allowed decision, a valid binding, and an unexpired deadline. Discovery failure
does not enable this behavior. Restart Gateway after changing the Core privacy mode to refresh its startup discovery.
The reference external executor continues to require complete privacy coverage.
An allowed send returns a payload-, target-, policy-, identity-, and Scope-bound permit. Its 60-second send deadline
is separate from its five-minute response-correlation deadline. Pass it as request_binding to
before_release, with the complete response carrier and completion: "complete".
Current policy, identity, and retained context dependencies are checked again. A release permit cannot authorize a
new request, and correlation never extends the send deadline. These permits do not provide exactly-once execution.
The public carrier currently supports complete JSON. The local protected transport also supports OpenAI Chat SSE
with a single choice and explicit allow_streaming=true. Other streaming profiles are withheld. It buffers the
complete stream before release with byte, timeout, and concurrency limits. Do not wrap an SSE
summary in the JSON carrier and call it a complete original response. Strict buffering delays first content.
HTTP over a Unix domain socket and remote HTTP(S) use the same DTOs. UDS does not replace bearer authentication.
The reference examples/context_protection/external_executor.py shows how an external executor uses these decisions
to control one exact JSON request and response, including byte limits, cancellation, deadlines, and local binding correlation.
The execution adapter must preserve the approved bytes, honor deadlines, stop on refusal, propagate cancellation,
and account for uncertain/failed sends. No concrete third-party gateway plugin or Rust gateway is installed by this
feature. The executor must retain each call's corresponding request binding locally; stateless Core cannot prove
which approved request an arbitrary external executor actually sent. An opaque upstream gateway limits protection to the observed endpoint; it cannot prove hidden routing,
retention, account/region isolation, or internal retries.
Boundaries and cost
The caller retains and refreshes reuse metadata. Reusing a prepared value can avoid repeated retrieval and assembly within its validity period; it does not create a server-side context cache or a provider KV cache. Compare repeated preparation and exact reuse against an existing once-prepared baseline before claiming task-level savings. The API verifies current authorization and exact payload identity, but cannot prove that an external executor actually sent or released the approved bytes.
An allowed response is not a guarantee that the model understood its evidence or chose the correct action. Literal template markers remain ordinary content; the API neither invents missing values nor certifies that they are executable arguments. The application still validates the proposed action, target, and authorization before running a tool or persisting a generated fact. Restoring a real path after a model chose the wrong operation would not make that operation correct.

