Evidence Ingest

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

Execution evidence is written through the control-plane evidence ingest pipeline. Runtime-gateway sends bounded evidence artifacts as part of execution recording; the control plane validates each artifact, canonicalizes JSON payloads, records integrity metadata, and groups rows by ingest batch.

Evidence ingest is the write boundary for runtime artifacts that need to survive execution replay, audit review, release intelligence, and compliance reporting. It is intentionally stricter than a generic log sink: malformed, oversized, or unknown-retention artifacts are rejected before any side effect is committed.

What Is Recorded

Each evidence row carries:

artifact kind
payload reference or bounded payload
canonical payload hash
payload byte count
ingest batch ID and sequence
organization, namespace, and workspace context

The pipeline records one bounded latency sample per batch through orqestra_evidence_ingest_duration_seconds{outcome}.

Common runtime artifact kinds include:

Artifact kind	Produced by
`policy_decision`	Runtime policy enforcement.
`guardrail_event`	Guardrail and content safety checks.
`hook_evaluation`	Hook warnings, advisories, or failed hooks.
`agent_reasoning_trace`	Bounded agent reasoning summaries.
`agent_reasoning_trace_full`	Optional full trace artifact with separate retention.
`subagent_spawn`	Multi-agent child flow execution.
`tool_certification_event`	Tool certification enforcement.
`retrieval_entitlement_denial`	Knowledge entitlement denial.
`output_redaction_applied`	Post-execution redaction obligation.

Lifecycle Boundary

All evidence writes route through a single EvidenceLifecycleService boundary. The service enforces:

Retention class normalization — unknown classes are rejected rather than persisted with a null expiry.
Size caps — canonical-JSON-encoded summary (default 64 KiB) and payload (default 1 MiB) are rejected before any side effect.
Per-artifact governance audit — every successful write appends a v1.governance.evidence_persisted row. Audit failure rolls back the just-written object.

Operator-facing settings for rate limits are in .env.example under ORQESTRA_EVIDENCE_WRITE_RATE_LIMIT_PER_MINUTE and ORQESTRA_EVIDENCE_WRITE_RATE_LIMIT_WINDOW_SECONDS.

Size And Rate Limits

Control	Default / behavior
Summary JSON cap	64 KiB canonical JSON.
Payload JSON cap	1 MiB canonical JSON.
Write rate key	Organization-scoped evidence ingest rate key.
Rate-limit failure posture	Fails closed when the limiter cannot decide.
Metrics labels	Bounded `outcome` labels only.

Large payloads should be stored in object storage and referenced from the evidence row. Do not place raw prompt transcripts, secret values, or unbounded tool payloads directly into evidence JSON.

Ingest Flow


runtime evidence artifacts
  -> canonical JSON serialization
  -> retention class normalization
  -> rate limit check
  -> object write for payload-backed artifacts
  -> database row creation
  -> governance audit append
  -> batch metadata returned to execution record

If any artifact in a batch fails validation, the batch does not partially commit. If object writes succeeded before a later failure, the cleanup path best-effort deletes those objects.

Retention And Archive

Retention sweeps archive eligible hot rows before deletion. The archive path covers execution records, evidence artifacts, retrieval events, checkpoints, and governance snapshots. Backing payload objects are deleted only after the archive transaction commits.

Archive and cleanup actions also append hash-chained audit rows:

v1.governance.evidence_archived
v1.governance.evidence_archive_cleaned

Operator Workflow

Use POST /v1/admin/retention/purge for an operator-triggered sweep. The route requires retention purge permission and returns structured archive/delete counters.

Verify the result by checking:

evidence archive counters in the response
archive records in the control plane
hash-chain audit rows for archive and cleanup actions
object-store delete counters after the database archive transaction commits

Troubleshooting

Symptom	Likely cause	Fix
Evidence write rejected	Payload or summary exceeds size cap	Store bulky data externally and persist a bounded ref.
Unknown retention class	Artifact supplied a class outside the canonical set	Use the retention classes from the audit/compliance guide.
Evidence write rate limit exceeded	Organization exceeded ingest quota	Reduce artifact volume or raise the configured quota.
Audit write failure rolls back row	Governance audit append failed	Investigate audit writer before retrying evidence writes.
Archive sweep deletes no object data	Archive transaction did not commit or no objects were eligible	Check archive counters and object delete metrics.