HWLAB Code Queue
102 lines
3.9 KiB
Markdown
102 lines
3.9 KiB
Markdown
# 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
|
|
```
|