pikasTech-HWLAB/docs/schema-drift-map.md

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:

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