# HWLAB Protocol Contract

The L0 protocol contract defines the common language between cloud services,
gateway services, simulated boxes, agent workers, CLI tooling, and future
hardware integrations.

All MVP implementations must preserve these invariants:

- Use JSON-RPC 2.0 envelopes for command-style API calls unless a later
  service contract explicitly narrows the transport.
- Emit auditable records for user, system, gateway, worker, and hardware
  actions that mutate state or produce evidence.
- Describe box hardware through capabilities, resource state, and wiring
  constraints instead of service-specific ad hoc fields.
- Treat DEV as the only MVP acceptance environment.
- Keep service identities within the frozen service ID list in the root
  README.

## Frozen Tables

The database contract is intentionally named here before migrations exist so
parallel MVP work shares stable terminology:

- `projects`
- `gateway_sessions`
- `box_resources`
- `box_capabilities`
- `wiring_configs`
- `patch_panel_status`
- `hardware_operations`
- `audit_events`
- `agent_sessions`
- `worker_sessions`
- `agent_trace_events`
- `evidence_records`

## Schema Status

Schemas in `protocol/schemas` are draft-2020-12 JSON Schemas. They define L0
field names, identities, relationships, timestamps, and state enums. Later
service work may tighten validation, but must not silently rename these L0
contract fields.

## Runtime Notes

- `wiring.md` defines the L3 patch-panel runtime loading, reload, diagnostics,
  and supported sync families.
- `box-simu-internal.md` defines the simulator ports and `/ports/write`
  behavior used by local L2/L3 smoke tests.
