# 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:

```sh
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.