feat: add patch panel runtime sync

2026-05-21 18:36:39 +00:00
parent eba24b72c0
commit b1f4e6e52d
14 changed files with 1583 additions and 45 deletions
@@ -40,3 +40,10 @@ 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.
@@ -0,0 +1,43 @@
+# Box Simulator Internal Runtime Contract
+
+`hwlab-box-simu` is the local simulator endpoint used by L2/L3 smoke tests. It
+is not a substitute for real DEV hardware.
+
+## Ports
+
+The simulator exposes these ports through `GET /status`:
+
+| Port | Direction | Value Type |
+| --- | --- | --- |
+| `uart0` | bidirectional | string |
+| `eth0` | bidirectional | object |
+| `gpio0` | bidirectional | boolean |
+| `DO1` | output | boolean |
+| `DI1` | input | boolean |
+| `AO1` | output | number |
+| `AI1` | input | number |
+| `FREQ_OUT1` | output | number |
+| `FREQ_IN1` | input | number |
+
+The L3 patch-panel sync loop uses `DO1`, `DI1`, `AO1`, `AI1`, `FREQ_OUT1`, and
+`FREQ_IN1`. Cross-device propagation must be `patch-panel-only`; local loopback
+is not accepted as a substitute.
+
+## Write Contract
+
+`POST /ports/write` accepts:
+
+```json
+{
+  "port": "DI1",
+  "value": true,
+  "source": "res_boxsimu_runtime_1",
+  "sourcePort": "DO1",
+  "propagatedBy": "hwlab-patch-panel"
+}
+```
+
+The response always includes whether the write was accepted, the box id, the
+port, the stored value, and the patch-panel propagation constraints. When the
+write came through `hwlab-patch-panel`, `GET /status` preserves
+`source`, `sourcePort`, and `propagatedBy` on the target port.
@@ -0,0 +1,48 @@
+# Wiring Runtime Contract
+
+Wiring configs remain the L0 `wiring_configs` contract described by
+`protocol/schemas/wiring-config.schema.json`. The L3 patch-panel runtime applies
+one active config and owns cross-box signal propagation.
+
+## Runtime Config
+
+`hwlab-patch-panel` loads a runtime config from `HWLAB_WIRING_CONFIG_PATH` when
+the variable is set. The file contains:
+
+- `wiringConfig`: an L0 wiring config object.
+- `endpointMap`: an object keyed by `resourceId` with HTTP base URLs for
+  writable `hwlab-box-simu` instances.
+
+The service also supports:
+
+- `GET /wiring` for the applied wiring config.
+- `GET /status` for L0 patch-panel status plus config/evidence summary.
+- `GET /diagnostics` for readable config, endpoint, and sync diagnostics.
+- `POST /wiring/apply` to apply an inline runtime config.
+- `POST /wiring/reload` to reload `body.path` or `HWLAB_WIRING_CONFIG_PATH`.
+- `POST /signals/route` to route one source signal.
+- `POST /sync/tick` to route a batch of source signals.
+
+## Supported Sync Families
+
+The minimal L3 runtime supports these directed signal families:
+
+| Source | Target | Value |
+| --- | --- | --- |
+| `DO*` | `DI*` | boolean |
+| `AO*` | `AI*` | number |
+| `FREQ_OUT*` | `FREQ_IN*` | number |
+
+Typed signal wiring is directional. For example, `DI1 -> DO1` is rejected with
+`source_port_not_output`, and `AO1 -> DI1` is rejected with
+`unsupported_signal_wiring`.
+
+Untyped legacy MVP fixture ports such as `uart0` and `gpio0` may still be routed
+as recorded deliveries for M1 compatibility, but they are not part of the L3
+sync loop.
+
+## Evidence Boundary
+
+This runtime records only config application and evidence summary fields in
+`/status` and `/diagnostics`. It does not write tick audit records. Live DEV or
+PROD deployment is outside this local runtime contract.