# Evidence Chain Contract

The evidence chain contract fixes the MVP relationship between L1 audit records
and L4 agent or worker evidence without changing either implementation surface.
It is a fixture-level contract for now: services may persist the records in their
existing tables, while the chain example binds the identities that must not
split later.

## Minimal ID Relationship

Every MVP evidence chain has one `operationId`, one `traceId`, one or more
`auditId` values, and one or more `evidenceId` values.

- `operationId` is the workflow anchor. It must match the
  `hardwareOperation.operationId`, every chain `auditEvents[].operationId`,
  every `traceEvents[].operationId`, and every
  `evidenceRecords[].operationId`.
- `traceId` is the request and execution correlation ID. It must match every
  `auditEvents[].traceId` and every `traceEvents[].traceId`. Because the L0
  `evidence-record` schema does not carry `traceId` at the top level, MVP
  evidence records must copy it to `evidenceRecords[].metadata.traceId`.
- `auditId` is unique per audit event in a chain. Each evidence record must set
  `metadata.producedByAuditId` to an audit event in the same fixture. The audit
  event that records evidence must target that evidence record with
  `targetType: "evidence_record"` and `targetId: <evidenceId>`.
- `evidenceId` is the stable artifact record ID. It must be unique in a chain,
  belong to the same `projectId`, `operationId`, and `environment`, and point to
  a content-addressed artifact through `uri`, `sha256`, and optional
  `sizeBytes`.

The same relationship applies whether the producer is a hardware trusted loop
or an agent automation loop. Agent and worker IDs are optional for hardware-only
chains, but when present they must be carried consistently by the operation,
trace events, and evidence records.

## MVP Required Fields

The fixture root is not a database table. It exists to verify cross-record
relationships and must include:

- `chainId`
- `schemaVersion`
- `scenario`
- `projectId`
- `operationId`
- `traceId`
- `environment`
- `hardwareOperation`
- `auditEvents`
- `traceEvents`
- `evidenceRecords`

`hardwareOperation` must satisfy the L0 hardware operation required fields:
`operationId`, `projectId`, `gatewaySessionId`, `resourceId`, `capabilityId`,
`requestedBy`, `status`, `environment`, `requestedAt`, and `updatedAt`.

Each MVP `auditEvents[]` entry must satisfy the L0 audit event required fields
and additionally include `projectId`, `operationId`, and `outcome` so the audit
stream can be joined back to the operation without service-specific inference.

Each MVP `traceEvents[]` entry must satisfy the L0 trace event required fields
and additionally include `operationId`.

Each MVP `evidenceRecords[]` entry must satisfy the L0 evidence record required
fields and additionally include:

- `metadata.traceId`
- `metadata.producedByAuditId`

Agent automation chains must also include `agentSessionId` and
`workerSessionId` at the fixture root, on the hardware operation, on trace
events, and on evidence records.

## Future Enhancements

The first version intentionally avoids heavier guarantees. Later contracts may
add:

- canonical chain hashing, previous-record links, and signatures
- attestation data from real hardware roots of trust
- retention policy, storage tier, and artifact redaction metadata
- richer OpenTelemetry or JSON-LD correlation fields
- multiple operations under one trace with explicit parent-child edges
- policy decision records for agent authorization and remediation

Those additions must preserve the MVP identity bindings above.

## Fixtures

The MVP fixture set lives under `protocol/examples/evidence-chain`:

- `fixtures/hardware-trusted-loop.json`
- `fixtures/agent-automation-loop.json`
- `artifacts/hardware-trusted-measurement.json`
- `artifacts/agent-automation-report.json`

Validate the examples with:

```sh
node scripts/validate-evidence-chain.mjs
```