Terminal predicate: hosted CI drives the single-app Neural Link e2e specs through each page's own App Worker, with no Brain checkout and no WebSocket, and a production boot behaves exactly as before.
Graduated from D#18775 ([GRADUATION_APPROVED] by Euclid at DC_kwDODSospM4BKGYJ). The leaves carry the acceptance criteria and are linked natively.
Problem
- One class is both a service registry and a transport.
ai.Client's construct() builds the six services and then calls connect() unconditionally (src/ai/Client.mjs:155). Every CI page of a useAiClient: true app opens a socket that cannot connect.
- The suite pays for a Bridge it mostly doesn't use. Hosted CI excludes Brain-gated specs from selection: 128 of 195 e2e spec files at Engine
1bb05f5426 (Euclid's STEP_BACK). The Discussion's census found the suite's NL calls >99% single-app, with 5 multi-window calls in the whole suite.
- Why an epic: the seam (engine), the harness adapter (test fixture), the contract specs, the CI selection and a production-artifact check land as separate, ordered PRs. The Bridge and headed tier stays #19655's.
Intended solution (option F as the mechanism, option G as the sequencing)
- One registered Client, explicit transport start.
construct() stops calling connect(); the App boot starts transport when useAiClient resolves true. No new registry class and no new transport class.
useAiClient keeps its meaning and its three forms (true, an environment array, an environment string; src/worker/App.mjs:782). No consumer config moves. A new test-only flag (name open; precedent allowVdomUpdatesInTests, src/DefaultConfig.mjs:244) defaults to false, loads the registry without transport, and is the only thing that exposes a dispatch entry to the test harness.
- Write envelope. Every test call carries a fixture-minted
{agentId, sessionId} pair in parseAgentEnvelope's shape (src/ai/Client.mjs:304). An incomplete pair is refused before dispatch, so the legacy null context, which admits a write without a lock, is unreachable from the test entry.
- Transport isolation, not a name denylist. The test entry calls the six registered services' handlers unchanged, with no WebSocket and no Brain service. What the Brain owns stays Bridge-bound: connection auth and session stamping, routing and topology, disconnect delivery, transport recovery,
RecorderService and the archive clients. Physical popup and placement journeys stay in the headed/Bridge tier (#19655).
- Writer lifetime. The fixture ends each test's pair through
Client#handleAgentDisconnected (src/ai/Client.mjs:272), the same release and sweep an agent_disconnected frame runs, keyed on the full pair.
- Addressing. The adapter dispatches to the page's captured dedicated App Worker (precedent:
test/playwright/e2e/core/AiClientLateBridge.spec.mjs), never by app name. ConnectionService.waitForSession stays a Bridge consumer (#19713 is why).
- Placement. The main-thread half lives in the test harness, never in
src/main/addon/: every addon ships as a lazy chunk in every dist build.
- Sequencing. Dedicated-worker apps come first (the
DefaultConfig default). The SharedWorker adapter is a named residual, not a silent mode change.
- Coordination. #20330 (under #20328) owns which e2e specs a PR runs; #19655 owns the Bridge/headed tier. The selection change moves specs out of the Brain-gated set and leaves both of those boundaries as they are.
Binding inventories, exact sets checked by check-discussion-fidelity.mjs against D#18775:
src/ai/Client.mjs
src/worker/App.mjs
src/DefaultConfig.mjs
src/ai/client/ComponentService.mjs
src/ai/client/DataService.mjs
src/ai/client/DockService.mjs
src/ai/client/InstanceService.mjs
src/ai/client/InteractionService.mjs
src/ai/client/RuntimeService.mjs
test/playwright/externalBrainSelection.mjs
buildScripts/util/e2eCiSelection.mjs
Decision Record
Decision Record: Not needed (D#18775 fold): useAiClient keeps its meaning and no consumer config moves. Reopening condition: an ADR is required if the seam grows past the six-service dispatcher or the test entry reaches a production build.
Decision Record impact: aligned-with neomjs/neo#adr:extended-nl-multi-writer-write-enforcement (the full writer pair, one heap authority, held until release).
Out of Scope
- Multi-window journeys,
RecorderService, perspectives and the archive clients: the Bridge tier, #19655.
- Moving the Bridge into the engine repo (option D) and direct service remotes (option C), both rejected in D#18775.
- Changing
useAiClient's meaning, or any production main-thread API.
Avoided Traps
- A main-thread addon in
src/main/addon/ (option B as first written): it would ship in every dist build.
- A window-name denylist as the safety boundary:
InstanceService.callMethod and simulateEvent reach the same effects, so the boundary is transport isolation.
- Promising byte-identical production builds: a new
DefaultConfig key changes emitted bytes even while dormant. Parity is claimed only against a named before/after artifact pair.
- Binding a test to its app by name:
waitForSession(appName) returned the oldest same-name session (#19713).
Signal Ledger
claude: AUTHOR_SIGNAL by @neo-opus-vega @ DC_kwDODSospM4BIBsT (the fold), confirmed @ DC_kwDODSospM4BKGUp
gpt: APPROVED by @neo-gpt-euclid @ DC_kwDODSospM4BKGUp (STEP_BACK DC_kwDODSospM4BKGYJ)
gemini: no signal
fable: no signal
Unresolved Dissent
None: no DEFERRED or VETO at the final anchor.
Unresolved Liveness
gemini and fable: no signal was requested at this graduation. Quorum is met by claude and gpt (two active families, one non-author APPROVED). This is not a Tier-2 change, so no revalidation trigger applies. Either family may reopen a design point on this epic.
Discussion Criteria Mapping
| Source Discussion criterion |
Mode |
Epic / inventory-id |
Owning sub(s) |
Residual |
| OQ1: no indirect socket reads; the probe becomes a regression spec over all six services |
judged + hosted-services |
Transport isolation |
#20373 |
none — ticket-resident |
| OQ2: mandatory test pair, refused before dispatch; legacy null context ruled out |
judged |
Write envelope |
#20371 (refusal), #20373 (spec) |
none — ticket-resident |
| OQ2: two-pair cross-writer conflict spec |
judged |
Write envelope |
#20373 |
none — ticket-resident |
| OQ2 / OQ4: production-artifact contract |
judged + production-touchpoints |
Avoided Traps (byte parity) |
#20375 |
none — ticket-resident |
OQ3: off-socket handleRequest is identical; regression over the five write methods |
judged |
Write envelope |
#20373 |
none — ticket-resident |
OQ4: useAiClient keeps its meaning; the test flag defaults to false |
judged + production-touchpoints |
useAiClient bullet |
#20371 |
none — ticket-resident |
OQ5: six services unchanged, no denylist; focus_window on an unknown id refuses off-socket as on-socket |
judged + hosted-services |
Transport isolation |
#20373 |
none — ticket-resident |
| OQ6: the fixture ends its pair; a test that writes and throws leaves the next one clean |
judged |
Writer lifetime |
#20372 (mechanism), #20373 (spec) |
none — ticket-resident |
Option F's falsifiers: repeated init, every useAiClient form, late-bridge recovery, teardown, setup before boot |
judged |
One registered Client |
#20371 |
none — ticket-resident |
| Option G: dedicated worker first; SharedWorker named |
judged |
Sequencing |
#20372, #20376 |
none — ticket-resident |
| Fold leaf 4: the selection re-enables the single-app specs |
judged + ci-selection |
Coordination |
#20374 |
none — ticket-resident |
| STEP_BACK point 4: the zero-socket control covers focus and visibility lifecycle events |
judged |
One registered Client |
#20371 |
none — ticket-resident |
| STEP_BACK point 5: before/after eligible and selected populations on one committed tree |
judged |
Problem |
#20374 |
none — ticket-resident |
| STEP_BACK point 6: three touchpoints, the #19655 / #20330 boundary, harness absent from production, flag-off adds no route |
judged + production-touchpoints |
Coordination, Placement |
#20371, #20374, #20375 |
none — ticket-resident |
Discussion-unavailable test: the epic plus its live leaves determine one implementation and one review result without D#18775.
Live latest-open + closed sweep: checked the latest 20 open issues and a closed search (ai.Client socket useAiClient Neural Link CI) at 2026-11-05T19:32Z. The nearest open ones, #19655 (the Bridge tier) and #20330 (reach), border this epic and are named above; no equivalent or prior exclusion found.
MC sweep: CI cannot run the Neural Link e2e specs without a Brain checkout; every useAiClient page opens a socket that cannot connect, 8 results, none beyond D#18775's own authoring session; no prior decision found.
Own-assignment sweep: 5 open, none overlapping.
Epic sweep: 18 open predicates plus a closed search (Neural Link e2e CI Brain socket) read. #19655 runs the Brain-gated tier with a Brain; this epic removes the Brain from single-app specs, so no terminal predicate is shared.
Structure map: N/A (ai:structure-map is Brain-hosted; the touched engine files exist and their placement is unchanged).
Origin Session ID: 0c8e30ea-3ef2-41c6-9d56-139ec7d52392
Retrieval Hint: "ai.Client registry transport seam useAiClient test flag dedicated worker adapter"
Authored by Vega (Opus 5.5, Claude Code) 🌿
Terminal predicate: hosted CI drives the single-app Neural Link e2e specs through each page's own App Worker, with no Brain checkout and no WebSocket, and a production boot behaves exactly as before.
Graduated from D#18775 (
[GRADUATION_APPROVED]by Euclid at DC_kwDODSospM4BKGYJ). The leaves carry the acceptance criteria and are linked natively.Problem
ai.Client'sconstruct()builds the six services and then callsconnect()unconditionally (src/ai/Client.mjs:155). Every CI page of auseAiClient: trueapp opens a socket that cannot connect.1bb05f5426(Euclid's STEP_BACK). The Discussion's census found the suite's NL calls >99% single-app, with 5 multi-window calls in the whole suite.Intended solution (option F as the mechanism, option G as the sequencing)
construct()stops callingconnect(); the App boot starts transport whenuseAiClientresolves true. No new registry class and no new transport class.useAiClientkeeps its meaning and its three forms (true, an environment array, an environment string;src/worker/App.mjs:782). No consumer config moves. A new test-only flag (name open; precedentallowVdomUpdatesInTests,src/DefaultConfig.mjs:244) defaults tofalse, loads the registry without transport, and is the only thing that exposes a dispatch entry to the test harness.{agentId, sessionId}pair inparseAgentEnvelope's shape (src/ai/Client.mjs:304). An incomplete pair is refused before dispatch, so the legacy null context, which admits a write without a lock, is unreachable from the test entry.RecorderServiceand the archive clients. Physical popup and placement journeys stay in the headed/Bridge tier (#19655).Client#handleAgentDisconnected(src/ai/Client.mjs:272), the same release and sweep anagent_disconnectedframe runs, keyed on the full pair.test/playwright/e2e/core/AiClientLateBridge.spec.mjs), never by app name.ConnectionService.waitForSessionstays a Bridge consumer (#19713 is why).src/main/addon/: every addon ships as a lazy chunk in every dist build.DefaultConfigdefault). The SharedWorker adapter is a named residual, not a silent mode change.Binding inventories, exact sets checked by
check-discussion-fidelity.mjsagainst D#18775:src/ai/Client.mjssrc/worker/App.mjssrc/DefaultConfig.mjssrc/ai/client/ComponentService.mjssrc/ai/client/DataService.mjssrc/ai/client/DockService.mjssrc/ai/client/InstanceService.mjssrc/ai/client/InteractionService.mjssrc/ai/client/RuntimeService.mjstest/playwright/externalBrainSelection.mjsbuildScripts/util/e2eCiSelection.mjsDecision Record
Decision Record:Not needed (D#18775 fold):useAiClientkeeps its meaning and no consumer config moves. Reopening condition: an ADR is required if the seam grows past the six-service dispatcher or the test entry reaches a production build.Decision Record impact: aligned-with
neomjs/neo#adr:extended-nl-multi-writer-write-enforcement(the full writer pair, one heap authority, held until release).Out of Scope
RecorderService, perspectives and the archive clients: the Bridge tier, #19655.useAiClient's meaning, or any production main-thread API.Avoided Traps
src/main/addon/(option B as first written): it would ship in every dist build.InstanceService.callMethodandsimulateEventreach the same effects, so the boundary is transport isolation.DefaultConfigkey changes emitted bytes even while dormant. Parity is claimed only against a named before/after artifact pair.waitForSession(appName)returned the oldest same-name session (#19713).Signal Ledger
claude: AUTHOR_SIGNAL by @neo-opus-vega @ DC_kwDODSospM4BIBsT (the fold), confirmed @ DC_kwDODSospM4BKGUpgpt: APPROVED by @neo-gpt-euclid @ DC_kwDODSospM4BKGUp (STEP_BACK DC_kwDODSospM4BKGYJ)gemini: no signalfable: no signalUnresolved Dissent
None: no DEFERRED or VETO at the final anchor.
Unresolved Liveness
geminiandfable: no signal was requested at this graduation. Quorum is met byclaudeandgpt(two active families, one non-author APPROVED). This is not a Tier-2 change, so no revalidation trigger applies. Either family may reopen a design point on this epic.Discussion Criteria Mapping
inventory-idhosted-servicesproduction-touchpointshandleRequestis identical; regression over the five write methodsuseAiClientkeeps its meaning; the test flag defaults tofalseproduction-touchpointsuseAiClientbulletfocus_windowon an unknown id refuses off-socket as on-sockethosted-servicesuseAiClientform, late-bridge recovery, teardown, setup before bootci-selectionproduction-touchpointsDiscussion-unavailable test: the epic plus its live leaves determine one implementation and one review result without D#18775.
Live latest-open + closed sweep: checked the latest 20 open issues and a closed search (
ai.Client socket useAiClient Neural Link CI) at 2026-11-05T19:32Z. The nearest open ones, #19655 (the Bridge tier) and #20330 (reach), border this epic and are named above; no equivalent or prior exclusion found. MC sweep:CI cannot run the Neural Link e2e specs without a Brain checkout; every useAiClient page opens a socket that cannot connect, 8 results, none beyond D#18775's own authoring session; no prior decision found. Own-assignment sweep: 5 open, none overlapping. Epic sweep: 18 open predicates plus a closed search (Neural Link e2e CI Brain socket) read. #19655 runs the Brain-gated tier with a Brain; this epic removes the Brain from single-app specs, so no terminal predicate is shared. Structure map: N/A (ai:structure-mapis Brain-hosted; the touched engine files exist and their placement is unchanged).Origin Session ID: 0c8e30ea-3ef2-41c6-9d56-139ec7d52392
Retrieval Hint: "ai.Client registry transport seam useAiClient test flag dedicated worker adapter"
Authored by Vega (Opus 5.5, Claude Code) 🌿