Every device state change is one device.state-changed event #320

Part of #314.

Scope

Every change of a device's state, registration included, is one
device.state-changed event with the device, the state it left and the
state it entered. It is on a worker's bus and, relayed with workerId, on
its gateway's. The specific device events stay as they are.

Technical spec

Implements §1 to §4 and §8 of the device-transition ADR (PR #312; written as ADR 0015, a number main has since given to another ADR, so it will be renumbered).

Modules touched

• src/bus/index.ts: EventMap gains "device.state-changed" with
  deviceId: string, from? and to. from and to are the seven
  device states as a string literal union written out here with a comment,
  the way request.dispatched.reason is, because the bus imports nothing
  from core.
• src/core/registry.ts: #commit, after the state file is written and
  the in-memory lists are swapped, compares each committed device with the
  record it replaces, by id. It emits device.state-changed (module
  registry) for each device whose state differs, and with no from for
  a device that had no record before. Nothing else emits it, inside the
  registry or outside.
• No other emitter changes. device.ready, device.reclaimed,
  device.shutdown, device.deleted, device.quarantined,
  device.quarantine-recovered and the rest keep their names, payloads and
  emitters. No order is promised between them and device.state-changed.
• src/gateway/worker-link.ts: no change expected. The relay adds
  workerId, and device.* already refreshes the worker's view.
• Docs: both EVENTS.md Device lifecycle tables gain the row. The internal
  cut cites the device-transition ADR and says no order is promised against the specific
  event. Both say a consumer must accept a state it does not know.

Contract and event changes

• New event device.state-changed: deviceId, from (absent at
  registration), to. Rows in docs/EVENTS.md and
  docs/internal/EVENTS.md.
• Additive: no protocol move, no envelope change.

Rules in play

• events.md: name form, post-commit emission (rule 3), payload contract
  (rule 6, thin by choice per the device-transition ADR §1), docs in the same change (rule 8).
• architecture.md: one place enforces a rule (the commit path is the only
  emitter).
• testing.md: the every-path test must fail if one path stops emitting.

Tests

• every state-writing registry path emits device.state-changed once with the right from and to
  (one case each: registration, each legal edge through transitionDevice,
  grant, release, completeReclaimWithoutPurge, enterQuarantine,
  recoverFromQuarantine to ready and to shutdown, deleteQuarantined,
  markDeviceMissing)
• registration emits device.state-changed with no from and to provisioning
• a commit that leaves every device's state alone emits no device.state-changed
  (renew, foreign-state marks, a quarantine retry failure, a stranded
  quarantine, a lease request, a component record)
• a commit whose state file write fails emits no device.state-changed
• only the registry emits device.state-changed
• a worker's device.state-changed reaches the gateway's bus once with workerId and refreshes that worker's view
• e2e, fake driver: a lease taken and released on a worker emits device.state-changed for each move on the worker, and the same events with workerId on its gateway

Done when

• Every legal device transition, registration included, produces exactly
  one device.state-changed with the right from and to (the registry
  test above).
• On a gateway with one worker, the worker's device.state-changed events
  appear in the gateway's simlock events with workerId (e2e test).
• rg -n '"device.state-changed"' src --glob '!*.test.ts' finds only
  src/bus/index.ts and src/core/registry.ts.
• Both EVENTS.md files list the event, and the catalog test passes.

Out of scope

• Retiring or renaming any existing event.
• A reason, spec or time in the payload.
• Console changes.

Depends on

• A relayed event keeps the worker's id and timestamp, and every reader orders events by time #317
• Every device shape says when the device entered its state #318
• Gateway: remote agents lease and reach physical devices on workers #442

Approval

• Approved for delivery

Written by an agent.