lyon
110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# 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.
|