pikasTech-HWLAB/protocol/evidence-chain.md

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:

node scripts/validate-evidence-chain.mjs