Orchestrator.mjs masterclass-reference: 4-way Service-DI classification + Neo.util.Env substrate + 2-value chain

Epic Origin

Graduated from Discussion #11828 (Cycle-3.3 [GRADUATION_APPROVED by @neo-gpt @ DC_kwDODSospM4BA-Ic] at body anchor 2026-05-23T10:58:31Z).

Originating empirical anchor: operator-triggered substrate-quality crisis 2026-05-23. Operator framing: "current version: not maintainable, bloats your context window... this is the worst code i have seen in over a year. junior cowboy coding SHIT. quality scale 1 to 100 => a 5. neo standards is 90+. let us turn the orchestrator into a masterclass elegant solution." PR #11825 closed Drop+Supersede; #11827 captured only ~5% of the actual anti-pattern stack.

Concept

Redesign ai/daemons/Orchestrator.mjs as a masterclass-reference implementation of the Neo daemon config substrate. Eliminates the layered anti-pattern stack (~30 cargo-cult reactive configs, configure() shadow-resolver, 6-value fallback chains, DEFAULT_X constants in TaskDefinitions.mjs, domain-class env-parser ownership). Then propagate the pattern to ~6+ sibling daemon files.

Tier classification

Tier-2 (substrate-architecture, touches core/Base.mjs consumption pattern + propagation to ~6+ daemon files + sets cross-substrate config contract).

Acceptance Criteria

1. AC1 — No cargo-cult _-suffix configs: Orchestrator.mjs has no _-suffix reactive config unless the PR introduces real beforeGet* / beforeSet* / afterSet* hook for that property. Legitimate reactive collaborators (e.g., cadenceEngine_) keep _-suffix with hooks + ClassSystemUtil.beforeSetInstance(value, DefaultClass, defaults) — DefaultClass passed DIRECTLY as 2nd arg (NOT via {module: DefaultClass} config). NO beforeGet* + NO manual backing assignment; reactive setter handles defaulting naturally.
2. AC2 — 2-value policy chain: Operator-tunable daemon values resolve through exactly two policy sources: canonical env var OR AiConfig. No options.X, no DEFAULT_X constant fallback, no env-alias chain.
3. AC3 — Explicit env decoding: Env decoding handles unset, empty string, zero, invalid numeric values, and boolean false explicitly. Invalid env operator-visible (warn-and-undefined per Neo.util.Env semantics).
4. AC4 — 4-way Service-DI classification: (A) class-system-managed utility collaborators with hooks + ClassSystemUtil; (B) parent-configured child collaborators with creation hooks + parent afterSet* propagation hooks (covers processSupervisorService_; explicit removal of processSupervisorService.set({...this...}) context-replay block in start()); (C) simple direct-import instance-fields ONLY when no class-system conversion / no parent-child propagation / no lifecycle side effect; (D) operator policy values via lazy getter + 2-value chain. Mis-classification = Tier-2 revalidation trigger. Logger function passed to child services must be a stable function seam (not per-call .bind(this) allocation).
5. AC5 — configure() removed: REMOVED as runtime-policy resolver. start(options) may keep narrow boot-wrapper seams for paths/process/test harnesses, but not as a second default system for intervals/toggles/services.
6. AC6 — Thin daemon wrapper: orchestrator-daemon.mjs remains a thin process wrapper (PID, cleanup, local config loading, start invocation). NOT new policy-translation dumping ground.
7. AC7 — Test coverage of real surfaces: Unit tests prove config precedence through real surfaces: env over AiConfig, gitignored config mutation via AiConfig.data, service override by instance field, singleton leak prevention, source-level invariants for removed anti-patterns. Tests must prove parent-config mutations on Orchestrator propagate to ProcessSupervisorService via afterSet* hooks (NOT via start() context replay).
8. AC8 — Tier-2 liveness + revalidationTrigger: Gemini benched on this convergence pass → Epic carries ## Unresolved Liveness + revalidationTrigger AC. Revalidation triggers if implementation chooses eager snapshotting / keeps configure() as policy resolver / reintroduces env aliases / adds shared helper that knows fallback policy / places env-parser on a domain class.
9. AC9 — Neo.util.Env substrate primitive: Lives at src/util/Env.mjs, mirrors Neo.util.String static-class precedent. API: parseNumber, parseBool, parsePort, parseUrl, parseString, applyEnvBindings, setDeep. Availability: added to src/util/_export.mjs barrel AND consumers use direct import Env from '<path>/src/util/Env.mjs'. Boolean compatibility: parseBool MUST preserve PrimaryRepoSyncService.parseEnabledFlag token semantics ('0', 'false', 'no', 'off' → false) OR Epic explicitly declares hard-cut behavior change with tests + env-var migration notes. All env-parser surfaces at lower tiers (EnvConfig.mjs, CadenceEngine.parseInterval, PrimaryRepoSyncService.parseEnabledFlag) retire or rewire through Neo.util.Env. No env-parser methods on domain classes. Test surface: test/playwright/unit/util/Env.spec.mjs.

Sub-decomposition (6 subs)

Sub 6 is the substrate-prerequisite; Sub 1 depends on Sub 6; Subs 2-5 parallel after Sub 1.

1. Orchestrator masterclass-reference refactor — primary lane; DEPENDS ON Sub 6.
2. Test-fixture + invariant coverage for the new config substrate.
3. Removal/narrowing of DEFAULT_* / parser surfaces (subsumes #11827).
4. Sibling daemon propagation (SwarmHeartbeatService, KbAlertingService, KbReconciliationService, KbGarbageCollectionService, GapInferenceEngine).
5. External-user configurability audit — forks, npx neo-app workspaces, non-Neo-team clients.
6. Neo.util.Env THIN substrate primitive — create + register + Orchestrator-needed parser surface + EnvConfig.mjs consumer rewire + test surface. Full 61-file consumer migration decomposes into Sub 6a/6b/6c follow-up tickets.

Avoided Traps

• Defense-in-depth fallback layers (2 values max per operator).
• Keeping _-suffix configs for "future hooks" (YAGNI; cargo-cult).
• Treating configure() as a Neo-class idiom (it isn't).
• Placing env-parser methods on domain classes (Cycle-3 anti-pattern; Tier-1 Neo substrate is the correct landing).
• Making the full 61-file env-var migration a Sub-1 prerequisite (Sub 6 stays THIN).
• Manual backing-assignment + beforeGet* defaulting for reactive configs (Cycle-3.2 lesson; reactive setter handles defaulting through ClassSystemUtil.beforeSetInstance directly).
• Citing non-existent import paths in body authority snippets (Cycle-3.3 lesson; V-B-A import paths against actual file tree before body-finalization).

Unresolved Liveness

• gemini (@neo-gemini-pro): participationStatus: operator_benched since 2026-05-18T00:00:00.000Z. reactivationTrigger per ai/graph/identityRoots.mjs. STATUS: pending Gemini reactivation; Epic carries revalidationTrigger AC per §6.2(c) Tier-2 requirement (AC8 explicitly). Sub #11803 mechanism (npm run ai:revalidation-sweep -- --family gemini) notifies Gemini at reactivation.

Related substrate anchors

• Originating Discussion: #11828 (Cycle-3.3 [GRADUATION_APPROVED] at body updatedAt 2026-05-23T10:58:31Z)
• src/core/Base.mjs:64-93 — reactive vs non-reactive config primitive documentation
• src/util/ClassSystem.mjs:23-60 — beforeSetInstance(value, DefaultClass, defaults) API (V-B-A: file exists; sibling consumers Breadcrumb.mjs:1, Loop.mjs:3, Database.mjs:2)
• src/util/String.mjs — substrate-utility static-class precedent for Neo.util.Env
• src/toolbar/Breadcrumb.mjs:38-126 — store_ reactive-config-with-hooks precedent (Service-DI Class A)
• src/grid/Container.mjs:520-540 — parent-store-propagation precedent (Service-DI Class B)
• ai/config.template.mjs — canonical defaults substrate
• ai/mcp/server/shared/helpers/EnvConfig.mjs — 95% correct env-parser surface at wrong (T2) tier; lifts to Neo.util.Env
• ai/daemons/services/CadenceEngine.mjs / ProcessSupervisorService.mjs — singleton: true examples (named-class import required for ClassSystemUtil)
• #11825 — closed Drop+Supersede (~5% capture)
• #11827 — narrow audit-record (subsumed by Sub 3)
• #11075 — original "exploration: migrate orchestrator magic numbers" ticket

Discussion Cycle History (compressed)

• Cycle-1: original 5-layer proposal
• Cycle-2 [GRADUATION_APPROVED] (superseded): env-decoder substrate correction per GPT node -e falsification — Number(undefined) === NaN, NaN ?? fallback === NaN
• Cycle-2.5: CadenceEngine reactive correction per @tobiu — class-system-managed collaborator with hooks
• Cycle-3 (STRONG VETO from @tobiu): env-parser primitive lifted Tier-3 → Tier-1 (Neo.util.Env); Epic 5→6 subs
• Cycle-3.1: 8 body-anchor fixups per GPT
• Cycle-3.2: CadenceEngine direct-class-arg pattern
• Cycle-3.3 [GRADUATION_APPROVED]: 3 narrow snippet-authority fixes (import path, semantics callout, ProcessSupervisorService symmetric correction)

Authored by: [Claude Opus 4.7] (Claude Code)