Part of #20370 (linked natively); graduated from D#18775, option F. The epic carries the shared rationale.
Context
Loading the AI stack today means opening a socket: construct() builds the six services and then calls connect() (src/ai/Client.mjs:155). This leaf separates the two inside the one registered Client, with no new class, so a test boot can host the dispatcher with no transport.
The Architectural Reality
src/worker/App.mjs:782 imports ai/Client.mjs when useAiClient is true, an environment array containing config.environment, or an environment string, and never on GitHub Pages.
handleRequest reaches dispatchServiceMethod (src/ai/Client.mjs:212) without the socket. D#18775 measured this at 0eec51e5: a trapped socket saw zero reads across reads, an enforced write and its undo.
allowVdomUpdatesInTests (src/DefaultConfig.mjs:244) is the precedent for a test-only flag.
test/playwright/e2e/core/AiClientLateBridge.spec.mjs pins late-bridge recovery.
The Fix
Client#construct no longer calls connect(). The App boot starts transport after construction when useAiClient resolves true, for each of its three forms.
- A test-only
DefaultConfig flag (name open, for example allowAiClientInTests), default false. When it is true, the App boot constructs the Client without starting transport and exposes a test dispatch entry on the App Worker.
- The test entry refuses a call whose context lacks a complete
{agentId, sessionId} pair (parseAgentEnvelope's shape) before dispatchServiceMethod. The legacy null context, which admits a write without a lock, is unreachable from it.
- Console lines are buffered only for a started transport.
src/worker/Base.mjs:interceptConsole pushes into client.logs whenever the client is not connected, so a registry-only boot, which never connects, would retain every line. The Client owns that answer (no transport, nothing to flush to), so the change stays in Client.mjs.
Contract Ledger
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
Neo.ai.Client#construct |
src/ai/Client.mjs:155 |
builds the services, starts no transport |
none |
JSDoc |
zero-socket unit spec |
| App boot transport start |
src/worker/App.mjs:782 |
starts transport iff useAiClient resolves true, all three forms |
unchanged without the flag |
JSDoc |
one spec per form |
| test-only flag (new) |
src/DefaultConfig.mjs |
default false; true boots the registry without transport and exposes the test entry |
flag off: no test entry |
DefaultConfig JSDoc |
spec |
| test dispatch entry (new) |
App Worker |
refuses an incomplete pair before dispatch, else calls handleRequest(method, params, context) |
none |
JSDoc |
refusal unit spec |
Discussion Criteria Mapping & Leaf Slice
OQ4 (useAiClient keeps its meaning; the flag defaults to false), OQ2's refusal mechanism, option F's five falsifiers, and STEP_BACK points 4 and 6. The production touchpoints are exactly:
src/ai/Client.mjs
src/worker/App.mjs
src/DefaultConfig.mjs
Acceptance Criteria
Out of Scope
The harness adapter, the contract spec suite, CI selection and the artifact check (sibling leaves); SharedWorker apps.
Decision Record
Decision Record: Not needed (D#18775); the reopening condition is on the epic.
Decision Record impact: aligned-with neomjs/neo#adr:extended-nl-multi-writer-write-enforcement.
Origin Session ID: 0c8e30ea-3ef2-41c6-9d56-139ec7d52392
Retrieval Hint: "ai.Client construct connect seam test-only flag registry boot"
Part of #20370 (linked natively); graduated from D#18775, option F. The epic carries the shared rationale.
Context
Loading the AI stack today means opening a socket:
construct()builds the six services and then callsconnect()(src/ai/Client.mjs:155). This leaf separates the two inside the one registered Client, with no new class, so a test boot can host the dispatcher with no transport.The Architectural Reality
src/worker/App.mjs:782importsai/Client.mjswhenuseAiClientistrue, an environment array containingconfig.environment, or an environment string, and never on GitHub Pages.handleRequestreachesdispatchServiceMethod(src/ai/Client.mjs:212) without the socket. D#18775 measured this at0eec51e5: a trapped socket saw zero reads across reads, an enforced write and its undo.allowVdomUpdatesInTests(src/DefaultConfig.mjs:244) is the precedent for a test-only flag.test/playwright/e2e/core/AiClientLateBridge.spec.mjspins late-bridge recovery.The Fix
Client#constructno longer callsconnect(). The App boot starts transport after construction whenuseAiClientresolves true, for each of its three forms.DefaultConfigflag (name open, for exampleallowAiClientInTests), defaultfalse. When it is true, the App boot constructs the Client without starting transport and exposes a test dispatch entry on the App Worker.{agentId, sessionId}pair (parseAgentEnvelope's shape) beforedispatchServiceMethod. The legacy null context, which admits a write without a lock, is unreachable from it.src/worker/Base.mjs:interceptConsolepushes intoclient.logswhenever the client is not connected, so a registry-only boot, which never connects, would retain every line. The Client owns that answer (no transport, nothing to flush to), so the change stays inClient.mjs.Contract Ledger
Neo.ai.Client#constructsrc/ai/Client.mjs:155src/worker/App.mjs:782useAiClientresolves true, all three formssrc/DefaultConfig.mjsfalse;trueboots the registry without transport and exposes the test entryDefaultConfigJSDochandleRequest(method, params, context)Discussion Criteria Mapping & Leaf Slice
OQ4 (
useAiClientkeeps its meaning; the flag defaults tofalse), OQ2's refusal mechanism, option F's five falsifiers, and STEP_BACK points 4 and 6. The production touchpoints are exactly:src/ai/Client.mjssrc/worker/App.mjssrc/DefaultConfig.mjsAcceptance Criteria
useAiClientform (true, an environment array, an environment string) still connects in a production boot, and a boot without the flag exposes no test entry.AiClientLateBridge.spec.mjspasses unchanged.falseand is documented inDefaultConfig's JSDoc.Out of Scope
The harness adapter, the contract spec suite, CI selection and the artifact check (sibling leaves); SharedWorker apps.
Decision Record
Decision Record:Not needed (D#18775); the reopening condition is on the epic. Decision Record impact: aligned-withneomjs/neo#adr:extended-nl-multi-writer-write-enforcement.Origin Session ID: 0c8e30ea-3ef2-41c6-9d56-139ec7d52392
Retrieval Hint: "ai.Client construct connect seam test-only flag registry boot"