# Schema Drift Map

This document records the naming drift between the protocol schemas, the L1
cloud-core migration skeleton, the audit chain, the evidence chain, and the
deploy manifest example. It is a closure artifact for M0 audit work only.

## Scope

- protocol: `protocol/schemas/*.json`
- DB migration: `internal/db/migrations/0001_cloud_core_skeleton.sql`
- audit event: `protocol/schemas/audit-event.schema.json`
- evidence chain: `protocol/evidence-chain.md`
- evidence record: `protocol/schemas/evidence-record.schema.json`
- deploy manifest: `deploy/deploy.json`
- deploy schema: `deploy/deploy.schema.json`

The source of truth for machine checks is `protocol/schema-drift-map.json`.
This page is the human summary.

## Aligned Fields

The following IDs are already aligned at the protocol layer and are carried
through the current examples:

- `projectId`
- `operationId`
- `auditId`
- `traceId`
- `evidenceId`
- `serviceId`
- `environment`
- `resourceId`
- `sessionId` family: `gatewaySessionId`, `agentSessionId`, `workerSessionId`
- evidence chain roots: `chainId`, `schemaVersion`, `scenario`, `title`
- evidence chain collections: `hardwareOperation`, `auditEvents`, `traceEvents`, `evidenceRecords`

## Known Gaps

These are the places where the L1 skeleton still drifts from protocol naming
and needs a real persistence fix before production data is written:

- `audit_events.request_id` should become `traceId`
- `audit_events.actor` should split into `actorType` and `actorId`
- `audit_events.source` should become `actorId`
- `audit_events.operation` should become `action`
- `audit_events.target` should split into `targetType` and `targetId`
- `audit_events.timestamp` should become `occurredAt`
- `evidence_records.evidence_type` should become `kind`
- `evidence_records.metadata_json.sha256` needs a first-class persisted target
- `hardware_operations.operation_json.resourceId` needs a tested mapping path
- `hardware_operations.operation_json.capabilityId` needs a tested mapping path

## Evidence Chain

The evidence chain fixture set is already internally coherent. It binds the
root IDs to the protocol schemas without changing the storage model:

- `chainId` anchors the fixture
- `operationId` ties hardware, audit, trace, and evidence together
- `traceId` threads through audit and trace events and is copied into evidence
  metadata
- `gatewaySessionId`, `agentSessionId`, and `workerSessionId` stay consistent
  where they appear
- `hardwareOperation`, `auditEvents`, `traceEvents`, and `evidenceRecords`
  each point back to their schema counterparts

## Impact

The current examples and validators are sufficient for audit evidence and MVP
closure, but they are not a persistence contract. The drift map is intentionally
read-only so later implementation work can pick one of two paths:

1. rename the real storage columns to match the protocol, or
2. keep the current skeleton and add a tested mapping layer before writes.

## Validation

Run:

```sh
node --check scripts/validate-schema-drift-map.mjs
node scripts/validate-schema-drift-map.mjs
```