Repository navigation
spec(kipc): worker-owned single-link blocking host CALL transport for Bun roles (Design B, selected by PANEL-P1 #418) #527
Description
Activity
This was generated by AI during triage.
Triage Notes
What we've established so far:
- The slice is specified in the issue body (what to build, binary acceptance criteria, negative controls, ownership and gates).
- Milestone
first-proof; tracker of record as stated in the body.
What we still need from you (@0monish):
- Resolve PANEL-P1 (decided 2026-10-07): worker-owned single link (arm B) passes the link-drain gate #418
PANEL-P1— S0 link-drain gate: worker-owned single-link transport prototype (arms A current, B worker+SAB/Atomics, C host credit frames, E revoke-during-park). Its answer can change this ticket's acceptance criteria.
Once those resolve, this ticket moves to
ready-for-agentwith an Agent Brief.This was generated by AI during triage.
Agent Brief
Category: enhancement
Summary: spec(kipc): worker-owned single-link blocking host CALL transport for Bun roles — the PANEL-P1 follow-on specCurrent behavior:
FACT (park-probe receipt, scratchpad; not re-run here): a Bun main thread parked in a blocking wait stops draining its app link, and the link stalls once the host writer fills the 8 KiB kernel buffer. The Bun kipc client has no blocking CALL.Desired behavior:
Write the approved spec PANEL-P1 says follows a passing arm (its text: 'B passing makes the worker-owned transport a KEL-80/KEL-97 spec with wire-protocol + public-API gates'): (a) the arm PANEL-P1 selects (B: a Worker owns the role's one socket, shared-memory ring and Atomics wait/notify; or C: host credit frames over the existing Grant frame kind), its PANEL-P1 evidence record and the rejected arms; (b) the blocking host CALL from the Bun main thread: deadline semantics, wake with a typed error on link close or role generation retire, never a fabricated result; (c) host events that arrive during a park are retained in issue order and replayed after wake, with a retained-bytes bound and its typed overflow; (d) exactly one link and one principal per role — a second link per role is refused; (e) the link handle's owner moves from the main thread to the worker, which is a handle-ownership (architecture) change, so arch 02 is amended in the same PR; (f) consumers: F06-T7 (showMessageBoxSync, first proof), F02-T11 and F06-T14 (next). The renderer sendSync lane is not this spec (F04-A5, F04-T15).Key interfaces:
- none named beyond the acceptance criteria
Acceptance criteria:
- The spec is approved and merged with the arch 02 transport sentences amended in the same PR
- The spec names the PANEL-P1 arm it adopts and cites that arm's recorded pass result
- The spec states one link and one principal per role and the typed wake errors for link close and generation retire
- No performance number is a pass criterion; any RTT figure appears only as a diagnostic under a registered X05 metric id or is omitted
-
just llms-checkpasses on the final diff - Negative control: A draft that opens a second link per role to avoid the stall is rejected at the wire-protocol review gate
Out of scope:
- The showMessageBoxSync facade and its re-entrancy behaviour (F06-T7, PANEL-D22); renderer sendSync (F04-A5, F04-T15); any RTT threshold.
Tracker of record and claim location: see "Ownership and gates" in the issue body.
- changed the title
[-]spec(kipc): worker-owned single-link blocking host CALL transport for Bun roles — the PANEL-P1 follow-on spec[/-][+]spec(kipc): worker-owned single-link blocking host CALL transport for Bun roles (Design B, selected by PANEL-P1 #418)[/+]on Oct 7, 2026 This was generated by AI during triage.
Agent Brief
Category: enhancement
Summary: spec(kipc): worker-owned single-link blocking host CALL transport for Bun roles (Design B, selected by PANEL-P1 #418)Current behavior:
FACT (park-probe receipt, scratchpad; not re-run here): a Bun main thread parked in a blocking wait stops draining its app link, and the link stalls once the host writer fills the 8 KiB kernel buffer. The Bun kipc client has no blocking CALL.Desired behavior:
Write the approved spec for Design B, which PANEL-P1 #418 selected (resolution comment 6035712580; evidence on research/electron-compat-map at 46e5907): (a) a Worker owns the role's one socket, a bounded shared-memory ring and Atomics wait/notify; Grant credit frames (arm C) are specified only as optional host-side backpressure for that ring, not as a transport alternative; arms A and C are recorded as rejected transports with their #418 evidence; (b) the blocking host CALL from the Bun main thread: deadline semantics, wake with a typed error on link close or role generation retire, never a fabricated result; Worker death or a wedged Worker while the main thread is parked wakes the caller immediately with a typed error, never only at the call deadline.; (c) host events that arrive during a park are retained in issue order and replayed after wake, with a retained-bytes bound and its typed overflow. On wake, mirror state facts held in the ring are applied in issue order before the blocking call returns, so synchronous getters are current. Listener events from the ring are then dispatched in issue order as ordinary tasks after user code resumes; no app JS runs while the main thread is parked.; (d) exactly one link and one principal per role — a second link per role is refused; (e) the link handle's owner moves from the main thread to the worker, which is a handle-ownership (architecture) change, so arch 02 is amended in the same PR; (f) consumers: F06-T7 (showMessageBoxSync, first proof), F02-T11 and F06-T14 (next), and the F02-T2 mirror (#449), whose zero-round-trip getters rely on the ring rule above. The renderer sendSync lane is not this spec (F04-A5, F04-T15).Key interfaces:
- none named beyond the acceptance criteria
Acceptance criteria:
- The spec is approved and merged with the arch 02 transport sentences amended in the same PR
- The spec adopts Design B and cites PANEL-P1 (decided 2026-10-07): worker-owned single link (arm B) passes the link-drain gate #418's recorded pass result; Grant credit appears only as ring backpressure, and no text leaves the transport choice open
- The spec states one link and one principal per role and the typed wake errors for link close and generation retire
- No performance number is a pass criterion; any RTT figure appears only as a diagnostic under a registered X05 metric id or is omitted
-
just llms-checkpasses on the final diff - The spec makes Worker death or a wedged Worker during a park wake the caller immediately with a typed error and registers that error code
- The spec states the wake-time ring rule: mirror state facts applied in order before the blocking call returns, listener events dispatched in order as tasks after user code resumes, no app JS while parked
- Negative control: A draft that opens a second link per role to avoid the stall is rejected at the wire-protocol review gate
- Negative control: A draft whose Worker-death case wakes the caller only at its call deadline is rejected at review against PANEL-P1 (decided 2026-10-07): worker-owned single link (arm B) passes the link-drain gate #418 risk 1
- Negative control: A draft that dispatches ring listener events before the blocking call returns (re-entrant user code) is rejected against PANEL-P2 PANEL-P2 (decided 2026-10-07): async AppKit veto hooks match Electron 44.4.5 with six facade rules #419's E3 transcript
Out of scope:
- The showMessageBoxSync facade and its re-entrancy behaviour (F06-T7, PANEL-D22); renderer sendSync (F04-A5, F04-T15); any RTT threshold.
Tracker of record and claim location: see "Ownership and gates" in the issue body.
16 remaining items
- added 13 commits that reference this issue
on Oct 7, 2026
Parent
Epic #463 · Map #391 · Unit F04 · Kind:
spec· Tier: Tier 1 · Maturity target: L1 · Size: M · Milestone:first-proofWhat to build
Write the approved spec for Design B, which PANEL-P1 #418 selected (resolution comment 6035712580; evidence on research/electron-compat-map at 46e5907): (a) a Worker owns the role's one socket, a bounded shared-memory ring and Atomics wait/notify; Grant credit frames (arm C) are specified only as optional host-side backpressure for that ring, not as a transport alternative; arms A and C are recorded as rejected transports with their #418 evidence; (b) the blocking host CALL from the Bun main thread: deadline semantics, wake with a typed error on link close or role generation retire, never a fabricated result; Worker death or a wedged Worker while the main thread is parked wakes the caller immediately with a typed error, never only at the call deadline.; (c) host events that arrive during a park are retained in issue order and replayed after wake, with a retained-bytes bound and its typed overflow. On wake, mirror state facts held in the ring are applied in issue order before the blocking call returns, so synchronous getters are current. Listener events from the ring are then dispatched in issue order as ordinary tasks after user code resumes; no app JS runs while the main thread is parked.; (d) exactly one link and one principal per role — a second link per role is refused; (e) the link handle's owner moves from the main thread to the worker, which is a handle-ownership (architecture) change, so arch 02 is amended in the same PR; (f) consumers: F06-T7 (showMessageBoxSync, first proof), F02-T11 and F06-T14 (next), and the F02-T2 mirror (#449), whose zero-round-trip getters rely on the ring rule above. The renderer sendSync lane is not this spec (F04-A5, F04-T15).
Acceptance criteria
just llms-checkpasses on the final diffNegative controls (each names the one mutation that must fail)
External predecessors (outside this tracker)
Ownership and gates
docs/agents/workflow.md§ Tracker issue (rule lands with docs(agents): record the #517 tracker-of-record rule in root AGENTS.md and the workflow claim protocol #520). Linear reference: KEL-80 (Backlog) carries a link to this issue.The authoritative agent contract is the latest Agent Brief comment on this issue (triage skill); this body is the planning record.
Out of scope
The showMessageBoxSync facade and its re-entrancy behaviour (F06-T7, PANEL-D22); renderer sendSync (F04-A5, F04-T15); any RTT threshold.
Notes
Decided: PANEL-P1 #418 selected Design B; PANEL-P2 #419 confirmed that Electron runs no main-process JS during a sync modal and delivers queued work in order afterwards, which is the ring rule this spec writes down.
Change log (doctrine-audit repair, 2026-10-07)