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