pikasTech-HWLAB/protocol/README.md

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.