refactor(phase-2-d): sibling-orchestrator import → import type (6 sites)

Phase 2-D executes the audit's #1 blocker for the sibling-orchestrator
boundary, applying the same proven mechanical pattern as Phase 2-B.

Original audit framing predicted a 3-hour "extract nominal interfaces"
structural refactor. Post-2-C survey found that most consumer sites
already use the orchestrator class only as a type annotation —
TypeScript's structural typing means `import type { AIChatService }`
IS the interface. No nominal `IAIChatService` extraction needed.
Scope shrunk from 3 hours to 50 minutes (6 lines source change).

Converted (6 files):
- src/server.ts                              — AIChatService (ServerOptions field type)
- src/api/ai.ts                              — AIChatService (3 cast sites)
- src/api/other.ts                           — AIChatService (1 cast site)
- src/services/gateway/ChannelBridge.ts      — AIChatService + CompleteRequest
- src/services/ContentIntelligenceService.ts — AIChatService (field + ctor)
- src/api/boson.ts                           — BosonService (return-type annotation)

Documented "keep concrete" exceptions (6 sites, intentional value-use
at architectural boundaries): src/index.ts bootstrap instantiations
(AIChatService, BosonService), internal sibling instantiations
(BosonService→IdentityService, AgentKitExecutor→ParticleWalletProvider,
ToolExecutor→AgentKitExecutor), and api/wallet.ts static-method
consumer (deferred — would need ProposalStore service extraction).

Strongest validation outcome possible: BYTE-IDENTICAL compiled JS for
every modified file. SHA-256 hashes of all 6 dist/*.js files are
literally the same pre vs post. TypeScript was already eliding the
unused-as-value imports; adding `import type` makes the intent
explicit in source and future-proofs against verbatimModuleSyntax: true.

This is stronger than Phase 2-B's spot-check proof (every modified
file matched, not just samples).

Why bother if the JS is identical?
1. Explicit intent in source where reviewers/audits can see it
2. Resilience to future TypeScript flag changes (verbatimModuleSyntax)
3. Audit machine-readability: grep `^import {.*ClassName}` no longer
   matches these 6 sites — blocker is gone in source, not just compiled

After this commit, the audit's mechanical-pattern blockers (#1
concrete-class consumer imports + #2 ambient global singletons) are
functionally exhausted for consumer modules in pc2-node/src.
Remaining audit-derived work is architectural (mega-orchestrator
splits, mutable-global lifecycle), not mechanical.

Validation:
- tsc --noEmit clean
- npm run build:backend clean
- npm run test:unit 7/7 in 53.8ms
- ReadLints zero errors on 6 modified files
- SHA-256 byte-identical for all 6 dist/*.js files

Held behind Mac launcher 48-72h soak gate before release-branch merge.
See PHASE-2-D-SIBLING-ORCHESTRATOR-TYPE-ONLY.md for the full execution
log and CAPSULE_READINESS_REPORT.md §5.8 for audit-score impact.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: SashaMIT

.cursor/tasks/OPTIMISATION-AND-REFACTORING-2026-05/AUDIT_EXECUTIVE_SUMMARY.md

@@ -9,7 +9,9 @@
 > **Phase 2-B executed (2026-05-18)**: concrete-class → type-only refactor landed on feature branch. 40 `import` → `import type` conversions across 29 files for DatabaseManager / FilesystemManager / IPFSStorage. Validated with `tsc --noEmit`, `build:backend`, `test:unit`, ReadLints — and proven **byte-identical compiled JS** via SHA-256 on 5 spot-checked files. TypeScript compiler caught the one classification edge-case (`IPFSStorage.PinErrorType` static-member access in `api/public.ts`) instantly; reverted that one file. Methodology lesson captured for Phase 2-C. Shipping held behind Mac launcher soak gate. See `PHASE-2-B-CONCRETE-CLASS-TYPE-ONLY.md` + audit report §5.5.
 >
 > **Phase 2-C executed (2026-05-18)**: global-singleton purge landed on feature branch. **27 of 37 audited ambient-singleton sites fully purged (73%)** across `getDatabase()` (15/17), `getWASMRuntime()` (5/13), `getUpdateService()` (7/7). The remaining 10 sites are either static methods (2, no `this`) or deep multi-layer WASM/dDRM helpers (8) — all explicitly marked with `Phase 2-C` or `Phase 2-D (deferred)` comments rather than left silently ambient. A previously-planned 4th cluster (`pc2Config` global) was promoted out into its own ticket once investigation revealed it's a 4-file pattern with runtime mutation. Validation: `tsc` clean, `build:backend` clean, `test:unit` 7/7, ReadLints zero errors on 14 modified files, **live dev-server `/api/health` returns identical pre-change `version: "1.2.7.14"`** proving the converted `req.app.locals.updateService.getCurrentVersion()` is exact behavior-equivalent. TypeScript caught two real errors during execution (static-method `this.db` access; optional-undefined narrowing) — validating the methodology a second time. Held behind Mac launcher soak gate. See `PHASE-2-C-SINGLETON-PURGE.md` "Execution log" + audit report §5.7.
-> **Updated**: 2026-05-18.
+>
+> **Phase 2-D executed (2026-05-18 morning)**: sibling-orchestrator type-only conversions landed on feature branch. Original audit framing predicted a 3-hour "extract interfaces" structural job; post-2-C survey found that **most consumer sites already use the orchestrator class only as a type annotation** — TypeScript's structural typing means `import type { AIChatService }` IS the interface, no nominal `IAIChatService` extraction needed. Scope shrunk to **6 mechanical keyword changes across 6 files** (`server.ts`, `api/ai.ts`, `api/other.ts`, `gateway/ChannelBridge.ts`, `ContentIntelligenceService.ts`, `api/boson.ts`). **Result**: every modified file's compiled JS is **literally byte-identical** pre vs post (strongest validation outcome — stronger than 2-B's spot-check proof because every modified file matched, not just spot-checks). All gates green: `tsc` clean, `build:backend` clean, `test:unit` 7/7, ReadLints zero errors. The audit's mechanical-pattern blockers (#1 concrete-class consumer imports + #2 ambient global singletons) are now functionally exhausted for consumer modules in `pc2-node/src` — remaining work is architectural (mega-orchestrator splits, mutable-global lifecycle redesign), not mechanical. Held behind Mac launcher soak gate. See `PHASE-2-D-SIBLING-ORCHESTRATOR-TYPE-ONLY.md` "Execution log" + audit report §5.8.
+> **Updated**: 2026-05-18 morning.
 
 ---
 

.cursor/tasks/OPTIMISATION-AND-REFACTORING-2026-05/CAPSULE_READINESS_REPORT.md

@@ -1049,6 +1049,66 @@ Net: ~10-14 score points moved across pc2-node. Remaining `getDatabase`/`getWASM
 
 **Shipping**: held behind Mac-launcher 48-72h soak per `PHASE-2-PLAN.md` shipping gate.
 
+### 5.8 Phase 2-D executed (2026-05-18 morning) — sibling-orchestrator type-only conversions (completes audit blocker #1)
+
+**Status**: shipped to feature branch `feat/t-1-telemetry-and-support`, awaiting CI green + review + Mac soak before release-branch merge.
+
+**The audit predicted this would be a 3-hour structural refactor — it actually took 50 minutes**
+
+The audit's original "Phase 2-D" framing said "extract small interfaces from sibling-orchestrator classes" — implying a multi-hour structural job to define `IAIChatService`, `IBosonService`, etc. and refactor all consumers to depend on the interface.
+
+The post-2-C survey discovered that this framing was an artefact of the audit being written before 2-C completed. After 2-C purged ambient singletons and 2-B converted storage-class imports, the actual remaining sibling-orchestrator imports were ALREADY type-only-in-spirit — used as field type, function parameter type, or cast target, never as a value. TypeScript's structural typing means **`import type { AIChatService }` IS the interface** at the type level; no nominal `IAIChatService` extraction is required to resolve the audit's blocker.
+
+So Phase 2-D collapsed into a 6-line mechanical keyword change.
+
+**What landed**:
+- 6 mechanical `import` → `import type` conversions across 6 files:
+  - `pc2-node/src/server.ts` — `ServerOptions.aiService` type annotation
+  - `pc2-node/src/api/ai.ts` — 3 cast sites
+  - `pc2-node/src/api/other.ts` — 1 cast site
+  - `pc2-node/src/services/gateway/ChannelBridge.ts` — `AIChatService` + `CompleteRequest`, both type-only
+  - `pc2-node/src/services/ContentIntelligenceService.ts` — field annotation + ctor param
+  - `pc2-node/src/api/boson.ts` — return-type annotation
+- 6 documented "keep concrete" exceptions for value-use sites at architectural boundaries (bootstrap, internal sibling instantiation, static-method consumer)
+
+**Validation outcome — strongest possible**:
+
+| Gate | Result |
+|---|---|
+| `tsc --noEmit` | ✅ clean |
+| `npm run build:backend` | ✅ clean |
+| `npm run test:unit` | ✅ 7/7 in 53.8 ms |
+| `ReadLints` on 6 modified files | ✅ 0 errors |
+| **SHA-256 byte-identical compiled JS** | ✅ literally identical for **all 6** modified `dist/*.js` files (every byte matches pre vs post) |
+
+This is **stronger than Phase 2-B's proof** — in 2-B we spot-checked 5 files for byte-identical-JS; in 2-D every modified file is byte-identical, not just samples.
+
+**Why the JS came out fully identical, not just "minus a require line"**:
+
+The original ticket prediction expected the compiled JS to differ by exactly one removed `require('...')` per file. The actual result is more interesting: TypeScript's default emitter (`importsNotUsedAsValues: 'remove'`) was **already eliding the unused-as-value imports**. The compiled output already had no `require` for AIChatService / BosonService in any of these 6 consumers, because the compiler detected the type-only nature automatically.
+
+So at the runtime level, Phase 2-D is a **zero-bytes-changed change**. Why bother then?
+1. **Explicit intent in source code** — `import type` declares "I depend on this only as a type" *where reviewers and audits can see it*, not just where the compiler infers it.
+2. **Resilience to future tsconfig changes** — if `verbatimModuleSyntax: true` is ever enabled (recommended by the TS team, likely default in future versions), only `import type` would erase. Plain `import` would not.
+3. **Audit machine-readability** — the audit's "concrete-class consumer import" pattern is detected by grep'ing `^import {.*ClassName}`. After 2-D, these 6 sites no longer match — blocker is gone in source code, not just in compiled output.
+
+**This completes the audit's mechanical-pattern blockers for consumer modules**:
+
+- Pattern #1 (concrete-class consumer imports): storage classes done by 2-B (40 sites in 29 files); sibling-orchestrator classes done by 2-D (6 sites in 6 files).
+- Pattern #2 (ambient global singletons): route layer done by 2-C (27 sites purged, 10 explicitly deferred with markers).
+
+Remaining audit-derived work in `pc2-node/src` is no longer mechanical — it requires architectural decisions:
+- **Phase 2-E**: split the 3 C-class mega-orchestrators (`ConnectivityService`, `api/index.ts`, `api/storage.ts`) — structural refactor.
+- **`pc2Config` mutable-global ticket** (promoted out of 2-C): design the full lifecycle for a 4-file pattern with runtime mutation.
+- **AgentKitExecutor ProposalStore extraction**: structural — would resolve the static-method-consumer pattern in `api/wallet.ts`.
+- **Phase 2-D-helpers** (8 deep WASM/dDRM/IPFS helper sites deferred from 2-C): would thread `wasmRuntime` through 5+ layers; significant effort, modest audit benefit.
+
+After Phase 2-E and the structural tickets above, any remaining work moves into capsule-boundary definition and runtime capability tokens — i.e., the AGENTIC-PC2-MONETISATION migration design itself.
+
+**Score impact**: ~6 score points across 6 consumer modules (each promoted by ~1 band). Smaller absolute number than 2-C, but it's the **completion of the audit's #1 mechanical blocker** for consumer modules. Combined with 2-B's 40 sites and 2-C's 27 sites, the total mechanical-blocker cleanup since 2026-05-17 is 73 sites in ~5.5 hours of focused work — high signal-to-noise refactor work.
+
+**Shipping**: held behind Mac-launcher 48-72h soak per `PHASE-2-PLAN.md` shipping gate.
+
 ### 5.6 What this audit tells us about the AGENTIC-PC2-MONETISATION strategy
 
 After 160 modules across 11 batches (audit functionally complete at 98.2% coverage), the strategic picture is now stable and final:

.cursor/tasks/OPTIMISATION-AND-REFACTORING-2026-05/PHASE-2-D-CHEAT-SHEET.md

@@ -0,0 +1,89 @@
+# Phase 2-D Cheat Sheet (2-minute read)
+
+> Companion to `PHASE-2-D-SIBLING-ORCHESTRATOR-TYPE-ONLY.md`. This is what you need to read to sign off.
+
+## What is it (in one sentence)
+
+Add the word `type` to 6 import statements across 6 files so that consumer modules don't carry a runtime dependency on AIChatService / BosonService just to use them as type annotations.
+
+## What does NOT change
+
+- **Zero UX impact**. Every endpoint behaves identically.
+- **Zero API contract change**. No request/response shapes change.
+- **Zero config change**. No env vars, no flags.
+- **No new code**. We're deleting one keyword worth of "implicit value-import behavior" per file — adding 4 letters (`type `) to 6 lines.
+- **No new files**. Just edits to existing imports.
+
+## What does change
+
+For each of the 6 modified files, the compiled JavaScript will lose **exactly one line**: the `require('./services/ai/AIChatService.js')` (or similar) at the top of the file. That `require` exists today only to satisfy a non-existent runtime need — the consumer modules use the symbol only as a TypeScript type, which is erased at compile time. Removing the `require` is the actual audit-resolution we're after.
+
+Everything else in those 6 files compiles identically — same machine code, same execution.
+
+## Why now / why this matters
+
+Same logic as Phase 2-B and 2-C: every `import { ConcreteClass }` in a consumer module is a "compile-time dependency on the implementation" that capsule code in the Runtime can't have. After Phase 2-D, six more files become capsule-ready in their orchestrator dependency declarations. Combined with 2-A, 2-B, 2-C, this completes the mechanical audit-pattern cleanup for consumer modules.
+
+## Comparison to recent phases
+
+| Phase | What it did | Files touched | Risk | Outcome |
+|---|---|---|---|---|
+| **2-A** | Extracted shared types into `types.ts` modules | ~10 | Very low | ✅ shipped, CI green |
+| **2-B** | `import { Storage }` → `import type { Storage }` (DatabaseManager, FilesystemManager, IPFSStorage) | 29 | Very low (byte-identical JS proven) | ✅ shipped, CI green |
+| **2-C** | Purged ambient global singletons from route handlers (`getDatabase()`, `getWASMRuntime()`, `getUpdateService()`) | 14 | Low (compiled JS does change; tested via behavior equivalence) | ✅ shipped, CI green |
+| **2-D** (this ticket) | `import { Orchestrator }` → `import type { Orchestrator }` (AIChatService, BosonService) | 6 | Very low (byte-identical JS expected, except the erased `require`) | TBD |
+
+Phase 2-D is the **smallest** of the four mechanical Phase 2 tickets and lowest-risk after 2-A. Total scope: 6 lines of source change. Expected execution time: ~50 min including validation.
+
+## Why it's so small (it wasn't supposed to be)
+
+The original audit predicted Phase 2-D would be a 3-hour interface-extraction job (define `IAIChatService`, refactor consumers to depend on the interface, etc.). After Phase 2-C completed and I surveyed the actual import surface, I found that:
+
+- **Most consumer imports are already type-only-in-spirit** — they use `AIChatService` as a field type, function parameter, or cast target, never as a value (no `new AIChatService(...)`, no static method calls).
+- **TypeScript's structural typing means `import type { AIChatService }` *is* the interface** — there's no need to extract a nominal `IAIChatService` interface separately. The class declaration itself is the structural contract that consumers depend on.
+
+So the audit's blocker resolves cleanly with a keyword change instead of an architectural refactor. Honest scope shrink, not scope creep.
+
+## Files involved
+
+**Will be modified (6)**:
+- `pc2-node/src/server.ts` — `ServerOptions.aiService` type annotation
+- `pc2-node/src/api/ai.ts` — 3 cast sites
+- `pc2-node/src/api/other.ts` — 1 cast site
+- `pc2-node/src/services/gateway/ChannelBridge.ts` — 2 symbols (AIChatService + CompleteRequest), both type-only
+- `pc2-node/src/services/ContentIntelligenceService.ts` — field + constructor type
+- `pc2-node/src/api/boson.ts` — return-type annotation
+
+**Will NOT be modified (documented in ticket)**:
+- `src/index.ts` — bootstrap instantiation is allowed to know concrete classes
+- `services/boson/BosonService.ts` — internal sibling instantiation (IdentityService is tightly coupled, lives in same subtree)
+- `services/ai/tools/AgentKitExecutor.ts` — internal sibling instantiation (ParticleWalletProvider tightly coupled)
+- `services/ai/tools/ToolExecutor.ts` — internal sibling instantiation + function value import
+- `api/wallet.ts` — uses `AgentKitExecutor.staticMethod()` and `pendingProposals` Map (value-uses); already documented in Phase 2-C deferral
+
+## Risk in one number
+
+Lines of source code that could possibly behave differently after this PR: **0**.
+
+Lines of compiled JavaScript that change: **6 deleted `require` statements** (one per modified file), exactly matching the audit-resolution intent.
+
+Lines of code that could cause a runtime failure: **0** — TypeScript's `import type` erasure is a well-defined language feature; the failure mode is "compile error", not "wrong runtime behavior".
+
+## The 3 sign-off questions
+
+1. **Approve the scope shrink** from "extract nominal interfaces" (~3 hours) to "6 mechanical keyword changes" (~50 min) — do you want the smaller mechanical version that resolves the same audit blocker, or do you want nominal `IAIChatService` / `IBosonService` interfaces extracted regardless? (Recommendation: ship mechanical now; revisit nominal interfaces only if a future capsule-boundary requirement demands it.)
+2. **Bundle with the 2-C-deferred WASM helpers** (8 deep-helper sites marked `Phase 2-D (deferred)` for `getWASMRuntime()`)? They use the `Phase 2-D` label but are a *different pattern* (singleton purge, not import-keyword change). (Recommendation: keep them as a separate `Phase 2-D-helpers` ticket; this ticket is import-keyword-only.)
+3. **Execute now on feature branch, ship after Mac soak** — same model as 2-B and 2-C; coding gate is open, shipping gate is closed until Mac launcher is stable. Recommendation: yes.
+
+## Expected outcome of execution
+
+- 6 files modified, ~6 lines source change.
+- `tsc --noEmit` clean, `build:backend` clean, `test:unit` 7/7 pass, `ReadLints` zero errors.
+- SHA-256 of 3+ spot-checked compiled `dist/*.js` files: each file's compiled JS changes only in losing one `require()` line — every other byte identical.
+- Dev server `/api/health`, `/api/ai/chat`, `/api/boson/status` behave identically pre/post.
+- CI green on 4-platform matrix in ~10 min.
+- 6 consumer modules promoted by ~1 score band each in the audit; mechanical-pattern audit blockers are now functionally exhausted for consumer modules in pc2-node/src.
+
+---
+
+If you say "ok lets do it", I'll execute, validate, commit, push, and post the CI-green confirmation. Same workflow as 2-B, 2-C.