Context Provenance (Operator)

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Context provenance explains which memory rows, retrieved chunks, and evidence references influenced a single assistant turn, and why. The operator tier is the full diagnostics view: it adds the audit linkage, the forensic hashes, and the complete per-candidate decision list on top of the user-tier surface. It is a read-only governance surface — it never edits memory, never changes a strategy, and never returns the model’s raw prompt.

The detailed cross-surface contract — record shapes, redaction rules, inclusion-reason mapping, persistence model, and audit actions — is in docs/reference/assistant-context-provenance.md.

When to use the operator tier

Use the user tier (the panel described in Assistant Home & Memory) when you want the plain “what influenced this response” answer. Reach for the operator tier when you are investigating why the runtime made the decisions it did:

• You need the full decisions[] — every candidate’s bounded reason code, not the user-friendly summary.
• You need the audit linkage: the governance_events.event_id, the prefix fingerprint, the evidence-refs digest, and the effective recall-policy and context-budget hashes for forensic reconstruction.
• You need to confirm whether the strict overlay was caller-driven or server-classified (isHighConsequenceCallerHint vs. isHighConsequenceServerClassified).
• You need to verify that a redacted row was correctly concealed: the operator tier shows the existence of redacted rows (load-bearing for the audit trail) but still carries <redacted> as the preview and drops sourceRef / evidenceRefs.

Reading operator-tier provenance for a turn

curl "http://localhost:8000/v1/executions/{execution_id}/turns/{turn_id}/provenance:operator"

The same operator-tier read is available through the CLI:

orqestractl --format json provenance operator {execution_id} {turn_id}

The response is the operator-tier record: all user-tier fields plus auditEventId, auditPrefixFingerprint, auditEvidenceRefsDigest, effectiveRecallPolicyHash, effectiveContextBudgetHash, userOverrideAxes, the high-consequence provenance flags, the full decisions[], the memoryRecallSummary, and the budgetSummary. A successful read emits a context.provenance_read.operator audit row.

For a fail-closed turn (one whose context.assembly_rejected audit row exists), the projection has no included memory, actionClassification is null, and the operator tier additionally exposes the rejectionCode and rejectionAxis.

Audit-event lookup

When you are reading the audit trail and want to jump from a context-assembly audit event to the provenance it produced, use the audit-link route. The path parameter event_id is the governance_events.event_id UUID from the context.assembled (or context.assembly_rejected) row — not the int-keyed hash-chain audit_id.

curl "http://localhost:8000/v1/workspaces/{workspace_id}/provenance/audit-event/{event_id}"

The CLI exposes the same audit-link lookup:

orqestractl --format json provenance audit-event --workspace-id {workspace_id} {event_id}

The route loads the audit event, extracts its turn and prefix fingerprint, and returns the operator-tier provenance for that turn (scoped to the URL’s workspace). The typical flow is: an operator clicks an audit row in the audit viewer, the UI calls this route with the row’s event_id, and the operator-tier provenance for that exact turn is displayed.

This route returns a uniform 404 for every non-success cause — a cross-workspace event_id, a missing event_id, a missing provenance row, or a missing operator permission. The status deliberately cannot distinguish “this event exists in another workspace” from “this event does not exist”, which would otherwise leak the existence of cross-workspace event IDs.

The explicit permission requirement

Both the operator-tier read route and the audit-link route require Permission.CONTEXT_PROVENANCE_OPERATOR in addition to Permission.MEMORY_READ.

• The permission is not default-granted to WORKSPACE_MANAGE. Holding a broad workspace-management role does not grant operator-tier provenance — that would be a silent privilege expansion.
• After this feature ships, existing operator roles must be granted CONTEXT_PROVENANCE_OPERATOR explicitly via the standard role-grant flow. There is no implicit upgrade.
• The tier is a property of the route, not of the caller’s permissions. Calling the user-tier route always returns the user tier, even for a caller who holds CONTEXT_PROVENANCE_OPERATOR.

Current limitations

• Retrieval content is deferred. includedRetrieval is empty until the upstream retrieval client lands; the schema and refs are in place, but read-time content re-fetch is not yet wired.
• Cache-metadata enrichment is upstream-pending. Until the context-engine enriches cache_metadata with the full provenance payload, the included memory/retrieval refs persist empty, so the included set projects empty even though the routes, tiers, and redaction behave correctly.

Security coverage

The operator-tier and audit-link trust boundaries are pinned by the context provenance probe family ORQ-A-API-CONTEXT-PROVENANCE-001..022, covering tier strictness (operator route without the permission returns 403), redacted-content non-leak on the operator tier, the read-time audit-link join (including cache-reuse disambiguation by turn_id), and the audit-link 403/404 unification.