ai/ Neo namespace bootstrap hygiene: entry-point-only Neo+core+InstanceManager imports

Context

Operator architectural clarification 2026-05-09 (post-PR-#11044 Cycle 2): import Neo from 'src/Neo.mjs' belongs ONLY in process entry points (executable files — the node X.mjs target), NEVER in consumed-class files. Plus all process entry points need import InstanceManager from 'src/manager/Instance.mjs' to enable Neo.find / Neo.findFirst / Neo.get aliases + consume the pre-singleton Neo.idMap + set Base.instanceManagerAvailable = true.

Damage mechanism (multi-import beyond style-smell):

1. Architectural invariant violation: per src/Neo.mjs:52-55 doc, namespace assembly is entry-point's responsibility. Non-entry-point importing Neo violates layer-of-responsibility.
2. Direct-load brittleness: if a consumed-class file is loaded without going through its entry point (e.g., test bootstrap, isolated import), globalThis.Neo is partially populated (no Util/Compare augmentation, no InstanceManager bootstrap) and Neo.setupClass(...) may silently fail or work-then-break.
3. InstanceManager-missing damage (src/manager/Instance.mjs:31-37): without import InstanceManager in entry point, Base.instanceManagerAvailable stays false, Neo.find/Neo.findFirst/Neo.get aliases never bind, and Neo.idMap accumulates without being consumed (pre-singleton brittleness).

Empirical Audit (ai/ folder)

Class files that should NOT import Neo (consumed by entry points — SMELL):

Entry point scripts that need Neo + core/_export + InstanceManager additions:

Already correct (verified):

Prescription

Two-direction cleanup with single coherent substrate concern (entry-point invariant alignment):

Direction 1: Remove Neo imports from class files (3 files)

- import Neo from '../../src/Neo.mjs';   // [or relative variant]
- import * as core from '../../src/core/_export.mjs';   // [if present]

Files:

• ai/daemons/Orchestrator.mjs
• ai/daemons/SwarmHeartbeatService.mjs
• ai/daemons/services/SummarizationCoordinatorService.mjs

Neo.setupClass(...) at file end works via globalThis.Neo populated by entry-point bootstrap (matches DreamService.mjs:349 precedent).

Direction 2: Verify and add Neo + core + InstanceManager to entry points

For each entry-point script (audit per file):

+ import Neo             from '../../src/Neo.mjs';   // [or relative variant]
+ import * as core       from '../../src/core/_export.mjs';
+ import InstanceManager from '../../src/manager/Instance.mjs';

Files to audit:

• ai/scripts/orchestrator-daemon.mjs (confirmed MISSING all 3)
• ai/scripts/bridge-daemon.mjs
• All ai/scripts/*.mjs operator scripts not already covered
• Spawned-child scripts: ai/scripts/summarize-sessions.mjs, buildScripts/ai/syncKnowledgeBase.mjs, buildScripts/ai/backup.mjs

Acceptance Criteria

• AC1 — ai/daemons/Orchestrator.mjs, ai/daemons/SwarmHeartbeatService.mjs, ai/daemons/services/SummarizationCoordinatorService.mjs no longer import Neo or core/_export; class-file canonical pattern (matches DreamService.mjs precedent)
• AC2 — ai/scripts/orchestrator-daemon.mjs imports Neo + core/_export + InstanceManager; daemon process bootstrap is complete (not relying on consumed-class imports)
• AC3 — Audit + fix all ai/scripts/*.mjs entry points for missing Neo/core/InstanceManager imports
• AC4 — Audit + fix spawned-child entry points (summarize-sessions.mjs, syncKnowledgeBase.mjs, backup.mjs) — each child Node process needs own bootstrap since orchestrator spawns separate Node processes via spawn()
• AC5 — Audit + fix ai/scripts/bridge-daemon.mjs per same criterion
• AC6 — Existing tests pass (canonical Orchestrator.spec.mjs + service-level specs); new test substrate not required (refactor preserves behavior)
• AC7 — Cross-family review per pull-request §6.1 (substrate-shaped change touching daemon entry points)

Avoided Traps

• ❌ Bundle with broader /tech-debt-radar systematic audit — keep this ticket scope-restraint compliant per feedback_substrate_scope_restraint; broader audit can be separate Ideation Sandbox if useful
• ❌ Forget spawned-child entry points — orchestrator's spawn(nodeBin, [scriptPath]) pattern means each spawned script is its own Node process needing own bootstrap; not visible from in-process import-graph
• ❌ Manual one-by-one without audit-first — verify each file's current state via grep -nE "^import Neo\b" ai/scripts/*.mjs before editing; some entry points may already have full bootstrap

Provenance

• Operator clarification 2026-05-09: "Neo as an import belongs ONLY into entry point files. Inside the left hemisphere e.g. worker.App or Main. A Neo import NEVER belongs into imports of entry point files themselves."
• Operator follow-up 2026-05-09: "i would go into the other direction: process entry points NEED import InstanceManager from ...manager/Instance.mjs => enables Neo.get(), and removes the instance maps => proper collection."
• Operator entry-point-criterion clarification 2026-05-09: "is there an executable file or not." + child-process framing: orchestrator spawns child Node processes; each child = own entry point needing own bootstrap
• Empirical anchor: src/Neo.mjs:52-55 doc note on namespace augmentation by core modules; src/manager/Instance.mjs:31-37 Neo.find/findFirst/get aliases + Base.instanceManagerAvailable flag
• Sister precedent: ai/daemons/DreamService.mjs:349 (canonical class-file pattern without Neo import); ai/mcp/server/*/mcp-server.mjs (entry-point pattern with all 3)
• PR #11044 Cycle 2 caught the smell on TaskStateService + ProcessSupervisorService; this ticket extends the cleanup to remaining ai/ surfaces

Cross-Discussion Links

• Discussion #11026 — Flat Peer-Team paradigm anchor (architectural primitive that v2 InstanceManager direction extends)
• PR #11044 Cycle 2 — Neo-import-as-entry-point-only canonical form first established for daemon-tier services

Self-Identification: @neo-opus-4-7 (Claude Opus 4.7, Claude Code) — chief-architect lane, post-Round-3 quick-win cleanup. Open lane for self-selection.