## Purpose

An evidence packet collects the material needed to judge a proposed result. It
contains a manifest, references to artifacts, provenance for each check, and an
explicit account of missing or partial verification. It gives an evaluator a
bounded input instead of asking it to reconstruct a run from chat history and
temporary logs.

The packet records observations. It does not decide whether those observations
are good enough. That decision belongs to an evaluator or approval checkpoint.

## When to use

Build an evidence packet whenever work will be evaluated outside the process
that produced it. This includes proposed code changes, release candidates,
infrastructure plans, generated reports, migrations, and automated incident
responses.

For a low-risk local edit, the packet can be a small manifest with a diff and
one test result. For a production change, it may include build output, focused
and regression checks, artifact digests, policy decisions, screenshots, and a
list of checks that could not run.

## Inputs and outputs

Inputs:

- the intent brief reference and workflow run identifier;
- the exact proposed artifact or change digest;
- test, build, lint, security, or evaluation results;
- logs and visual captures needed to support an acceptance check;
- tool names, versions, commands, timestamps, and execution environments;
- known gaps, skipped checks, warnings, and operator notes.

Outputs:

- an immutable packet manifest with its own digest;
- content-addressed references to included artifacts;
- a mapping from acceptance checks to supporting evidence;
- a completeness status such as `complete`, `partial`, or `blocked`;
- explicit declarations for absent evidence.

## Smallest useful interface

```ts
type EvidenceItem = {
  id: string;
  kind: "change" | "check" | "log" | "capture" | "decision";
  uri: string;
  digest: string;
  producedBy: string;
  producedAt: string;
  exitStatus?: number;
};

type EvidencePacket = {
  runId: string;
  intentRef: string;
  subjectDigest: string;
  status: "complete" | "partial" | "blocked";
  items: EvidenceItem[];
  acceptanceMap: Record<string, string[]>;
  gaps: string[];
};

function sealEvidence(packet: EvidencePacket): {
  packetRef: string;
  packetDigest: string;
};
```

Sealing should reject an item without provenance or a referenced artifact that
cannot be read. The packet digest should cover the manifest and the digests of
its artifacts.

## Example

```yaml
runId: run-1842
intentRef: checkout-timeout-fix@1
subjectDigest: sha256:41de...
status: partial
items:
  - id: change
    kind: change
    uri: artifact://run-1842/checkout.patch
    digest: sha256:41de...
    producedBy: implementation-worker@3
    producedAt: 2026-08-13T09:14:00Z
  - id: timeout-test
    kind: check
    uri: artifact://run-1842/timeout-test.txt
    digest: sha256:21a7...
    producedBy: test-runner/node-24
    producedAt: 2026-08-13T09:18:00Z
    exitStatus: 0
acceptanceMap:
  timeout-response:
    - timeout-test
  successful-checkout-regression: []
gaps:
  - The full checkout integration suite could not reach its container registry.
```

The packet is useful even though it is partial. It supports the timeout claim
and makes the missing regression evidence visible. An evaluator can return an
`insufficient-evidence` verdict instead of treating the successful focused test
as proof of the whole intent.

## Failure modes

- **The packet contains only a prose summary.** Reviewers cannot inspect the
  source material. Include artifact references and digests.
- **A passing exit code has no command or environment.** The result cannot be
  interpreted or repeated. Record the producer, version, invocation, and
  relevant environment identity.
- **Logs are dumped without a manifest.** Important failures get buried and the
  evaluator must infer which log supports which claim. Map evidence to each
  acceptance check.
- **Missing checks disappear.** A packet looks complete because skipped work is
  absent. List gaps and derive status from required evidence.
- **Evidence refers to a different change.** Bind every packet to the exact
  subject digest and reject a packet when the artifact changes.
- **The worker labels its own interpretation as fact.** Separate observations,
  such as command output, from worker notes and inferred explanations.
- **Secrets enter the packet.** Redact credentials and sensitive payloads before
  storage. Keep a record that redaction occurred without preserving the secret.

## What it does not solve

An evidence packet does not prove that a test is well designed, that an
environment matches production, or that a screenshot shows the right user
flow. It does not make the producer independent. It also does not replace the
source systems that enforce access and retention. The packet gives evaluation
a stable input; it cannot supply judgment that the workflow never defined.

## Related reading

- [Intent brief](/components/intent-brief)
- [Independent evaluator](/components/independent-evaluator)
- [Human approval checkpoint](/components/human-approval-checkpoint)
- [A passing test is not a good result](/notes/control-loop/a-passing-test-is-not-a-good-result)