Repository navigation
Protocol: declare a chain of instances run in one worker, with crash quarantine (for omx-clap-core#104) #101
Description
What is missing. The protocol has no way to say "these instances are one chain, in this order". omx-clap-core#104 makes omx-clap-host run a chain of plugins in one JACK client (one graph node, one wake-up per cycle instead of one per plugin), and it needs plugin-hostd to declare the chain and to route it to one worker.
Ruled 2026-10-19 (by recommendation, coordinator decision log row 00:55, omx-clap-core#104). The protocol gets a chain declaration that lists instances in order. A member that crashes is quarantined to a worker of its own, and the chain rejoins around it: crash isolation is plugin-hostd's purpose, and one plugin must never take its neighbours down.
Where it plugs in. protocol/plugin-hostd.json and its schema, include/plugin-hostd/protocol.h (generated, check-generated), src/verbs.c and src/supervisor.c (one worker per chain; on a member's crash, restart the chain without it and give the crashed member a worker of its own), tests/verbs_contract.py, and a tests/daemon_test.py scenario with the fake host.
Done when.
- A chain verb declares an ordered list of existing instances. An unknown instance, a duplicate, or an instance already in another chain is refused with a named code. Removing a chain gives each member back its own worker.
- With the fake host, a chain of three is started as one worker. When the middle member is made to crash, the chain restarts with the other two in order, the crashed one runs alone in a worker of its own, and an event names the quarantine.
- Bypass, latency and parameter verbs still address each instance by its own id inside a chain.
- Every guard has been broken once and went red (
make sabotage).
Blocks omx-clap-core#104. Part of FreeMixer/openmixer#2041 (plugin hosts: full LV2 and CLAP support), P2.
PRIORITY + BASE 2026-10-21 (operator: multiple plugins in one process is a selling point)
P1, start now. BASE: branch off origin/wave/contract-one-pass (the contract one-pass wave, J2 H1-H5 are on it), NOT main; open the PR into wave/contract-one-pass. Do not touch the tables or describe verb J2 added; the chain verb is new. Commit after every working step. Unblocks omx-clap-core#104.
SCOPE ADDITION 2026-10-21 (Zynthian + console need live chain edits; from the chain-model comparison)
Done-when additions, to be judged at hand-back (the r2 build branch cluster/plugin-hostd-101-r2-cluster was briefed before this):
- Adding a member to, or moving a member within, a running chain is a LIVE edit (no fresh worker for the surviving members); removing already is.
- A chain read-back verb: members in order, and which are quarantined; worker_list lists a chain's members.
- A worker that does not know the chain line is NOT killed (supervisor.c on_death on a non-RPC_OK reply: confirm).
- Zynthian: one Zynthian chain maps to one chain here (ordered members, per-member bypass/params). The console maps each trip (a run of adjacent isolated plugins) to one chain.
If the build branch lacks these, they become a follow-up lane on this issue, not a reason to restart.
Activity
linuxnow commentedon Oct 20, 2026
Operator 2026-10-21: this chain verb is also how plugin-hostd implements Zynthian chains (an ordered list of plugins per chain, one worker, crash quarantine). The Zynthian engine (devel/zynthian, zynthian_engine_plugind.py) should map one Zynthian chain to one plugin-hostd chain; keep the verb's shape usable from that engine (ordered members, per-member bypass/params, add/remove a member without rebuilding the chain). A follow-up lane wires the engine once this lands.
protocol: chain and chain_clear, the chain's error codes and chain_fo…
supervisor: chain gathers its members in one worker in order, a crash…
daemon_test: a chain of three in one worker, its refusals, the quaran…
verbs_contract: every verb a controller sends is answered by handle()…
daemon_test: a member's state is saved before it leaves its worker, a…
sabotage: every chain guard broken once goes red; SABOTAGE_ONLY runs …
packaging: 0.7.0 carries chain and chain_clear (#101)
linuxnow commentedon Oct 20, 2026
Finding from the chain-model comparison (read at build branch cluster/plugin-hostd-101-r2-cluster a30b4a3, tests not run): re-declaring a chain runs chain_form, which starts a fresh worker, so adding or moving a member rebuilds the worker; only removing a member is a live edit. The Zynthian and console use cases need add/move as live edits plus a chain read-back verb. Also check: chain_tell and replay call on_death when the reply is not RPC_OK (supervisor.c:938-943, 1524), while the design note says a worker's refusal of the chain line is no failure: confirm a worker that does not know 'chain' is not killed; and whether worker_list lists a chain's members. These are plugin-hostd's own words, not omx-contract's, so the vocabulary freeze does not block them.
supervisor: the chain helpers sit before sup_call, so the sabotage ar…
daemon_test: a chain's scenarios wait for the declaration's chain_for…
docs/design: chains, the open question of an LV2 chain while require_…
7 remaining items
daemon_test: a chain of three in one worker, its refusals, the quaran…
verbs_contract: every verb a controller sends is answered by handle()…
daemon_test: a member's state is saved before it leaves its worker, a…
sabotage: every chain guard broken once goes red; SABOTAGE_ONLY runs …
packaging: 0.7.0 carries chain and chain_clear (#101)
supervisor: the chain helpers sit before sup_call, so the sabotage ar…
daemon_test: a chain's scenarios wait for the declaration's chain_for…
docs/design: chains, the open question of an LV2 chain while require_…
docs/design: chains, the protocol has no latency verb to route (#101)
Merge pull request #130 from FreeMixer/cluster/plugin-hostd-101-r2-cl…
ci and sabotage: the devel RPM's expected files name the three contra…
sabotage: the probe arm's scratch tree carries what the Makefile's pr…
linuxnow commentedon Oct 22, 2026
Done and published: the chain verb with crash quarantine (PR #130 into the wave, #132) is in plugin-hostd v0.7.0: chain and chain_clear, codes -518 to -522, a member that dies is quarantined into a worker of its own and the chain rejoins; floor 1 and the verb table followed in PR #133 (main). What is left is tracked elsewhere: the union-narrowed LV2 world and the Zynthian gap verbs (#131), omx-clap-host speaking the chain line (omx-clap-core#104, after the library chain object #311). Closing 2026-10-22.
packaging: 0.8.0 changelog names the lv2_worker default (#101)