DEV-A4 zowietek: ground workmode-convergence streamplay protocol + enable index-scoped convergence

[aperim-agent]

Context

PR #139 made the zowietek workmode-convergence path fail-safe: converge_mode now requires an explicit DecodeIndex and refuses (ConvergenceUngrounded) rather than ever emitting a global, un-indexed streamplay/stop (the prior behavior — confirmed dangerous by the readiness audit wc3tvqa4w, since a global stop would halt the operator's production decode).

The index-scoped convergence wire path is implemented and unit-tested, but convergence_index() returns None everywhere, so convergence is currently refused until grounded. This is a deliberate safety posture, not a silent partial-ship — the blocker is real and external: there is no ZowieTek SDK on the build box to ground the invented streamplay opts.

The open work (requires the vendor SDK + a spare ZowieBox)

Per docs/research/managed-devices.md §3.3, the workmode-switch protocol is currently modeled on un-probed, invented opts (streamplay/opt=stop with data=Null, streamplay/opt=start with a fabricated {"mode":...} body). To enable live convergence:

1. Ground the protocol against the operator's ZowieTek SDK: capture the real workmode-switch / decode-control calls — confirm or replace the streamplay stop/start opts and bodies.
2. Determine stop scope: confirm whether streamplay/stop is global or per-decode-index, and wire convergence_index() to return a real spare decode-table index (never the production index).
3. Validate on a spare unit / spare decode index ONLY (never the production ZowieBox) per the hardware-validation runbook — confirm the 00004 wrong-workmode rejection behavior live, and that stop/start are scoped.
4. Once grounded + validated, enable convergence_index() so set-mode actually converges.

Safety gate

Until this lands, the driver cannot issue a workmode mutating call (it refuses). Do NOT remove the ConvergenceUngrounded guard or hardcode an index without SDK grounding + spare-unit validation. See the hardware-validation runbook + the zowietek production-safety posture.

Blocks: DEV-A4 live workmode set/convergence on hardware (the read-only status path is unaffected and works today).

[aperim-agent]

Protocol GROUNDED on real hardware (2026-06-14)

Probed both ZowieBox test units live (from the on-subnet jump host) and extracted the authoritative call shapes from the device's own web-UI JS bundle, then validated them against the boxes. The workmode-switch + decode protocol the convergence path needs is now grounded:

Workmode (/system):

• read: {"group":"workmode","opt":"get_workmode_id"} → {"workmode_id":N} (encoder=0, decoder=1)
• switch: {"group":"workmode","opt":"change_workmode","data":{"workmode_id":N}}

Decode table (/streamplay):

• enumerate: {"group":"streamplay","opt":"streamplay_get_all"} → data:[{index,name,switch,streamplay_status,url,...}] (our driver used opt:"streamplay" — WRONG, returns empty data)
• decoder state: {"group":"streamplay","opt":"get_decoder_state"}
• index-scoped switch: {"group":"streamplay","opt":"streamplay_switch","data":{"index":N,"switch":0|1}}
• modify/add/del: streamplay_modify / streamplay_add / streamplay_del

CRITICAL finding — the decoder is SINGLE-ACTIVE. Even the index-scoped streamplay_switch{index, switch:1} makes that index the sole active decode and implicitly stops whatever index was playing; switch:0 on the active index leaves nothing playing. So on a decoder, "switch the decode target" inherently replaces/stops the current decode — there is no truly non-disruptive per-index enable. The convergence model must reflect this: switching a decoder's target is a Class-2-style disruptive change to the current decode, surfaced as such. (Validated by toggling spare index 3, which stopped production index 2; production decode was then restored.)

Driver corrections this unblocks:

1. enumerate with streamplay_get_all (not streamplay)
2. read workmode via get_workmode_id (not the venc probe — venc getinfo returns an empty body)
3. convergence uses streamplay_switch{index, switch} against a specific index (the fail-safe refusal can be lifted once the driver carries a concrete decode index), with the single-active disruption surfaced honestly
4. change_workmode{workmode_id} is the real workmode switch

Next: wire these grounded shapes into the driver (replace the invented opts), keep the convergence index-scoped + surface the single-active disruption, then re-validate on the spare index.