pikasTech-HWLAB/docs/m0-contract-audit.md

M0 Contract Audit

This audit independently reviews whether the L0 skeleton is enough for M0 contract work under the issue constraints supplied for pikasTech/HWLAB#19 and the referenced #7/#11/#12/#16 guardrails.

Applied constraints:

• MVP acceptance is DEV only at http://74.48.78.17:16667.
• PROD is reserved and must not be deployed for this audit.
• HWLAB runtime services must keep their frozen service IDs and must not be replaced by UniDesk services.
• This audit does not modify L1-L6 service implementation directories and does not create or claim the L5 deploy manifest.

Audit Result

Status: conditionally passes M0 after this audit patch.

The repository already contains the L0 contract skeleton needed by parallel MVP work:

• Root README freezes MVP scope, DEV endpoint, service IDs, and repository layout.
• internal/protocol/index.mjs centralizes DEV endpoint, frozen service IDs, table names, JSON-RPC version, and HWLAB error codes.
• protocol/*.md documents JSON-RPC envelopes, error codes, audit fields, capability model, topology constraints, and the sequence-level MVP flow.
• protocol/schemas/*.json names the key protocol records and uses draft-2020-12 JSON Schema shape files.
• deploy/deploy.schema.json names the deploy manifest fields and reuses the frozen service ID list.
• scripts/validate-contract.mjs already checks protocol constants against the common and deploy schemas.

This patch adds M0 examples under protocol/examples/m0-contract/ and a lightweight executable check in scripts/validate-m0-contract.mjs so the audit is not document-only.

Coverage Matrix

Contract area	Current L0 source	Added M0 sample/check	Result
Frozen service IDs	README.md, internal/protocol/index.mjs, protocol/schemas/common.json, deploy/deploy.schema.json	service-ids.json, deploy sample, exact list comparison	Covered
JSON-RPC request/response	protocol/json-rpc.md, json-rpc-envelope.schema.json, runtime validators	json-rpc-request.json, json-rpc-response.json	Covered
Error envelope	protocol/errors.md, runtime ERROR_CODES	json-rpc-error.json, reserved code and stable error.data fields	Covered
Audit fields	protocol/audit.md, audit-event.schema.json	audit-event.json, required field and ID checks	Covered
Capability and topology	protocol/capabilities.md, protocol/topology.md, related schemas	capability-topology.json, cross-reference checks	Covered for M0
Deploy schema fields	deploy/deploy.schema.json, deploy/README.md	deploy-manifest.dev.json, DEV-only example checks	Covered without L5 manifest changes

Rework Risk Register

Blocker: persisted schema naming drift before L1/L4/L6 integration. internal/db/migrations/0001_cloud_core_skeleton.sql uses placeholder columns such as request_id, actor, source, operation, result, operation_type, and evidence_type, while the protocol schemas use auditId, traceId, actorType, serviceId, action, outcome, capabilityId, and kind. Before services persist real records, L1 must either align the migration with the protocol names or provide an explicit mapping layer that is tested.

Blocker: schema files are parseable but not fully enforced at runtime. The existing validators and the new M0 check intentionally avoid heavyweight dependencies and do not evaluate all JSON Schema references. L1-L6 service entry points need a shared validator such as Ajv or a generated equivalent before accepting untrusted API, gateway, or agent payloads.

Blocker: topology constraints are partly prose-only. M0 can verify that examples cross-reference known resources, capabilities, and sessions. M1-M3 need a real topology validator for cycle detection, active resource-group exclusivity, patch-panel override behavior, and gateway/box ownership.

Blocker: deploy schema allows future prod profile shape. That is acceptable for L0 compatibility, but L5 must keep MVP execution DEV-only and reject any real PROD deploy path until a later milestone explicitly changes the acceptance target.

Enhancement: RPC method catalog is not yet complete. M0 freezes envelope shape, method naming, and representative hardware.operation.request. Later milestones should add a method registry with params/result schemas for project, gateway, patch-panel, worker, evidence, and cleanup flows.

Enhancement: capability constraints are generic JSON objects. This keeps M0 flexible, but hardware-facing work should add typed constraint profiles for common operations such as voltage ranges, serial settings, firmware flashing, and measurement tolerances.

Enhancement: evidence integrity is structural only. The sample checks SHA-256 format but does not hash referenced artifacts. M4/M5 should verify artifact existence, size, content hash, and retention policy.

Enhancement: service ID drift checks are duplicated. Current validation compares runtime constants with schema enums. A later cleanup could generate schema enums and docs from one registry.

Validation

Run:

npm run check
node --check scripts/validate-m0-contract.mjs
node scripts/validate-m0-contract.mjs

The M0 script parses all JSON files in protocol/examples/m0-contract/, checks the audit Markdown headings, and verifies the representative cross-document invariants needed for M0.