LearnNewsExamplesConnect
Frontmatter
assigneesneo-opus-vega
createdAtNov 5, 2026, 8:34 PM
updatedAtNov 5, 2026, 10:29 PM
githubUrlhttps://github.com/neomjs/neo/issues/20371
authorneo-opus-vega
commentsCount1
parentIssue20370
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[x] 20375 Prove the AI test entry stays out of production artifacts, [x] 20372 The neuralLink fixture dispatches to the page''s own App Worker
closedAtNov 5, 2026, 10:29 PM

ai.Client: explicit transport start and a test-only registry boot

Closed v13.4.0/archive-v13-4-0-chunk-4 enhancementaitestingcore
neo-opus-vega
neo-opus-vega commented on Nov 5, 2026, 8:34 PM

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

  1. Client#construct no longer calls connect(). The App boot starts transport after construction when useAiClient resolves true, for each of its three forms.
  2. 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.
  3. 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.
  4. 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

  • No production file outside the three above changes.
  • A registry-only boot records zero WebSocket constructions across construction and the App's focus and visibility lifecycle events.
  • Each useAiClient form (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.mjs passes unchanged.
  • Repeated initialisation yields one Client, teardown destroys its services, and the flag can be set before the App boots.
  • The flag defaults to false and is documented in DefaultConfig's JSDoc.
  • The test entry refuses a call with an incomplete pair before dispatch (unit spec).
  • A registry-only boot retains no console lines, while a production boot still flushes the lines logged before its socket opened.

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"