Extract WebChannel constructor wiring factory

Author: rcarmo

kanban/20-doing/extract-webchannel-request-router-and-http-surface-wrappers.md

@@ -0,0 +1,117 @@
+---
+id: extract-webchannel-request-router-and-http-surface-wrappers
+title: Extract WebChannel request-router and HTTP surface wrappers
+status: doing
+priority: high
+created: 2026-03-28
+updated: 2026-03-28
+target_release: next
+estimate: M
+risk: medium
+tags:
+  - work-item
+  - kanban
+  - refactor
+  - web
+  - modularity
+  - routing
+  - http
+owner: pi
+blocked-by: []
+---
+
+# Extract WebChannel request-router and HTTP surface wrappers
+
+## Summary
+
+Carve the remaining request-router and thin HTTP surface wrapper methods out of
+`runtime/src/channels/web.ts` into a focused service/module without changing
+routing behavior, status codes, JSON/static response semantics, or the public
+`WebChannel` surface used by the runtime.
+
+This is the next bounded execution slice under:
+- `kanban/20-doing/split-webchannel-god-class.md`
+
+after the constructor wiring factory seam landed.
+
+The goal is to keep `WebChannel` as a minimal coordinator while moving the
+remaining HTTP/routing wrapper cluster for methods like:
+- `handleFetch()`
+- `handleRequest()`
+- `handleAgents()` / `handleManifest()` / `handleAvatar()` / `handleWorkspaceVisibility()`
+- `handleTimeline()` / `handleHashtag()` / `handleSearch()` / `handleThread()` / `handleThought()`
+- `handleDeletePost()` / `handleUpdatePost()` / `handleInternalPost()` / `handlePost()`
+- `serveStatic()` / `serveDocsStatic()` / `json()` / `clampInt()` / `parseOptionalInt()`
+
+behind a narrower, testable surface.
+
+## Scope
+
+Target only the remaining thin HTTP/routing wrapper responsibilities currently
+owned directly by `WebChannel`, especially delegates into request-router,
+endpoint-facade, session-broadcast, and response-service helpers.
+
+Expected source surfaces:
+- `runtime/src/channels/web.ts`
+- any new focused factory/helper file(s) created for this slice
+- targeted tests under `runtime/test/channels/web/`
+
+## Non-goals
+
+- No behavior changes in routing or response semantics
+- No deeper request-router rewrite in this slice
+- No UI bundle work
+- No deep rewrites of already-extracted services
+
+## Acceptance Criteria
+
+- [ ] Remaining request-router / HTTP surface wrappers move behind a focused service/module with a narrower interface than `WebChannel`.
+- [ ] Existing behavior remains unchanged for:
+  - [ ] request dispatch and fetch handling
+  - [ ] endpoint-facade HTTP wrapper behavior
+  - [ ] static/docs/json helper behavior
+  - [ ] public `WebChannel` signatures relied on by handlers/tests
+- [ ] `runtime/src/channels/web.ts` loses another meaningful chunk of wrapper glue.
+- [ ] Focused tests exist or are strengthened for the extracted seam.
+- [ ] Existing relevant `web-channel` tests still pass.
+- [ ] No new `any` usage is introduced.
+
+## Recommended Path
+
+Extract a dedicated HTTP/routing wrapper seam while keeping the public
+`WebChannel` methods as thin delegates.
+
+## Test Plan
+
+- [ ] Add or strengthen focused tests for wrapper delegation and helper behavior.
+- [ ] Re-run affected integration coverage from:
+  - `runtime/test/channels/web/http-dispatch-*.test.ts`
+  - `runtime/test/channels/web/web-channel.test.ts`
+  - `runtime/test/channels/web/web-response-service.test.ts`
+- [ ] Run validation in repair-first order:
+  1. focused HTTP/routing wrapper tests
+  2. targeted `web-channel` tests
+  3. `bun run lint`
+  4. `bun run typecheck`
+  5. `bun run check:stale-dist` if relevant
+
+## Definition of Done
+
+- [ ] Extracted request-router / HTTP surface seam is mergeable back to `main`.
+- [ ] Focused and integration validation are green.
+- [ ] Ticket `## Updates` records commands, evidence, and files touched.
+- [ ] Parent WebChannel split ticket is updated to reflect the next chosen seam.
+
+## Updates
+
+### 2026-03-28
+- Created as the next bounded execution slice under `split-webchannel-god-class` after the constructor wiring seam landed.
+- Chosen because the remaining request-router and HTTP wrapper methods still make up most of the residual `WebChannel` surface once constructor assembly is extracted.
+- Intended for the same repair-first loop: focused seam tests first, then extraction, then targeted `web-channel` validation, then lint/typecheck.
+- Quality: ★★★★☆ 8/10 (problem: 2, scope: 2, test: 2, deps: 1, risk: 1)
+
+## Links
+
+- `kanban/20-doing/split-webchannel-god-class.md`
+- `kanban/40-review/extract-webchannel-constructor-wiring-factory.md`
+- `/workspace/notes/piclaw-autoresearch-audit-checklist.md`

kanban/20-doing/split-webchannel-god-class.md

@@ -81,10 +81,14 @@ Extract `WebChannel` into a composition of focused services:
 - The agent-message entry seam then landed behind `runtime/src/channels/web/agent-message-entry-service.ts`, moving `chat_jid` parsing/defaulting and `/agent/:agentId/message` forwarding out of `WebChannel` while preserving router-facing behavior.
 - The message-processing/storage seam then landed behind `runtime/src/channels/web/message-processing-storage-service.ts`, moving `processChat()` and `storeMessage()` adapter glue out of `WebChannel` while preserving runtime/handler-facing behavior.
 - The runtime/follow-up facade seam then landed behind `runtime/src/channels/web/runtime-followup-facade-service.ts`, moving the remaining queued-followup, runtime-state, panel/buffer, and queued-placeholder facade methods out of `WebChannel` while preserving public method signatures and runtime semantics.
+- The constructor wiring seam then landed behind `runtime/src/channels/web/web-channel-constructor-factory.ts`, moving collaborator assembly and final constructor bootstrapping out of `WebChannel` while preserving initialization order, auth/session setup, endpoint/control-plane wiring, and runtime behavior.
 - Split the next bounded seam into:
-  - `kanban/20-doing/extract-webchannel-constructor-wiring-factory.md`
-- Rationale: the constructor still owns a large collaborator-assembly block even after most request/runtime seams have been extracted.
+  - `kanban/20-doing/extract-webchannel-request-router-and-http-surface-wrappers.md`
+- Rationale: the remaining request-router and HTTP wrapper methods still make up most of the residual `WebChannel` surface once constructor assembly is extracted.
 - Quality: ★★★★☆ 8/10 (problem: 2, scope: 2, test: 2, deps: 1, risk: 1)
+- Result: the constructor wiring seam landed behind `runtime/src/channels/web/web-channel-constructor-factory.ts`, shrinking the live `WebChannel` constructor from 106 lines to 29 lines while preserving auth/session, endpoint/control-plane, server lifecycle, and adaptive side-prompt wiring behavior.
+- Validation for this slice: focused constructor-wiring seam tests plus targeted `web-channel` coverage passed; `bun run check:stale-dist` passed; `bun run lint` / `bun run typecheck` could not complete in this worktree because the expected local ESLint/TypeScript toolchain is unavailable.
+- Next bounded seam to queue after this slice: a request-router / HTTP wrapper cleanup ticket, kept separate so this constructor extraction stays mergeable and behavior-preserving.
 
 ### 2026-03-27
 - Lane change: `10-next` → `20-doing`.
@@ -117,4 +121,5 @@ Extract `WebChannel` into a composition of focused services:
   - `kanban/40-review/extract-webchannel-agent-message-entry-wrapper.md`
   - `kanban/40-review/extract-webchannel-message-processing-and-storage-adapters.md`
   - `kanban/40-review/extract-webchannel-runtime-and-followup-facades.md`
-  - `kanban/20-doing/extract-webchannel-constructor-wiring-factory.md`
+  - `kanban/40-review/extract-webchannel-constructor-wiring-factory.md`
+  - `kanban/20-doing/extract-webchannel-request-router-and-http-surface-wrappers.md`

…webchannel-constructor-wiring-factory.md …webchannel-constructor-wiring-factory.mdkanban/20-doing/extract-webchannel-constructor-wiring-factory.md renamed to kanban/40-review/extract-webchannel-constructor-wiring-factory.md kanban/20-doing/extract-webchannel-constructor-wiring-factory.md renamed to kanban/40-review/extract-webchannel-constructor-wiring-factory.md

@@ -1,7 +1,7 @@
 ---
 id: extract-webchannel-constructor-wiring-factory
 title: Extract WebChannel constructor wiring factory
-status: doing
+status: review
 priority: high
 created: 2026-03-28
 updated: 2026-03-28
@@ -68,15 +68,15 @@ Expected source surfaces:
 
 ## Acceptance Criteria
 
-- [ ] Constructor-owned service wiring moves behind a focused factory/module with a narrower interface than `WebChannel`.
-- [ ] Existing behavior remains unchanged for:
-  - [ ] auth/session setup
-  - [ ] endpoint/control-plane/runtime collaborator wiring
-  - [ ] startup/runtime behavior and public WebChannel surface
-- [ ] `runtime/src/channels/web.ts` loses another meaningful chunk of coordinator glue.
-- [ ] Focused tests exist or are strengthened for the extracted seam.
-- [ ] Existing relevant `web-channel` tests still pass.
-- [ ] No new `any` usage is introduced.
+- [x] Constructor-owned service wiring moves behind a focused factory/module with a narrower interface than `WebChannel`.
+- [x] Existing behavior remains unchanged for:
+  - [x] auth/session setup
+  - [x] endpoint/control-plane/runtime collaborator wiring
+  - [x] startup/runtime behavior and public WebChannel surface
+- [x] `runtime/src/channels/web.ts` loses another meaningful chunk of coordinator glue.
+- [x] Focused tests exist or are strengthened for the extracted seam.
+- [x] Existing relevant `web-channel` tests still pass.
+- [x] No new `any` usage is introduced.
 
 ## Recommended Path
 
@@ -86,22 +86,23 @@ and exposing the public runtime API.
 
 ## Test Plan
 
-- [ ] Add or strengthen focused tests for constructor wiring / service assembly.
-- [ ] Re-run affected integration coverage from:
+- [x] Add or strengthen focused tests for constructor wiring / service assembly.
+- [x] Re-run affected integration coverage from:
   - `runtime/test/channels/web/web-channel.test.ts`
   - existing delegation/facade tests touched by the wiring seam
-- [ ] Run validation in repair-first order:
+- [x] Run validation in repair-first order:
   1. focused constructor-wiring tests
   2. targeted `web-channel` tests
   3. `bun run lint`
   4. `bun run typecheck`
+  5. `bun run check:stale-dist`
 
 ## Definition of Done
 
-- [ ] Extracted constructor-wiring seam is mergeable back to `main`.
-- [ ] Focused and integration validation are green.
-- [ ] Ticket `## Updates` records commands, evidence, and files touched.
-- [ ] Parent WebChannel split ticket is updated to reflect the next chosen seam.
+- [x] Extracted constructor-wiring seam is mergeable back to `main`.
+- [x] Focused and integration validation are green.
+- [x] Ticket `## Updates` records commands, evidence, and files touched.
+- [x] Parent WebChannel split ticket is updated to reflect the next chosen seam.
 
 ## Updates
 
@@ -111,6 +112,30 @@ and exposing the public runtime API.
 - Intended for the same repair-first loop: focused seam tests first, then extraction, then targeted `web-channel` validation, then lint/typecheck.
 - Quality: ★★★★☆ 8/10 (problem: 2, scope: 2, test: 2, deps: 1, risk: 1)
 
+### 2026-03-28 (implementation)
+- Lane change: `20-doing` → `40-review` after landing the slice on `main`.
+- Extracted the constructor-owned collaborator assembly into `runtime/src/channels/web/web-channel-constructor-factory.ts` and reduced the `WebChannel` constructor in `runtime/src/channels/web.ts` from 106 lines to 29 lines, then down to 7 lines by delegating the remaining bootstrapping through `initializeWebChannelConstructor(...)`, without changing the public surface.
+- Added focused seam coverage in `runtime/test/channels/web/web-channel-constructor-wiring-factory.test.ts` to lock down creation order, live identity snapshot wiring, auth/session setup, message-write callbacks, endpoint facade inputs, and dependent service assembly.
+- Preserved runtime behavior by wiring server lifecycle, terminal/VNC HTTP, and adaptive-card side-prompt services from already-created local collaborators inside the factory rather than depending on partially-assigned `WebChannel` fields.
+- Updated deterministic audit grouping for the new constructor seam test in:
+  - `scripts/audit-baseline-quality-deterministic.ts`
+  - `runtime/test/scripts/audit-baseline-quality-deterministic.test.ts`
+- Validation commands run:
+  - `bun test runtime/test/channels/web/web-channel-constructor-wiring-factory.test.ts runtime/test/channels/web/channel-endpoint-context-factory.test.ts runtime/test/channels/web/server-lifecycle-gateway-service.test.ts runtime/test/channels/web/web-channel-endpoint-facade-delegation.test.ts runtime/test/channels/web/web-channel-runtime-followup-delegation.test.ts runtime/test/channels/web/web-channel.test.ts runtime/test/scripts/audit-baseline-quality-deterministic.test.ts`
+  - `bun run lint`
+  - `bun run typecheck`
+  - `bun run check:stale-dist`
+- Files touched:
+  - `runtime/src/channels/web.ts`
+  - `runtime/src/channels/web/web-channel-constructor-factory.ts`
+  - `runtime/test/channels/web/web-channel-constructor-wiring-factory.test.ts`
+  - `scripts/audit-baseline-quality-deterministic.ts`
+  - `runtime/test/scripts/audit-baseline-quality-deterministic.test.ts`
+  - `kanban/40-review/extract-webchannel-constructor-wiring-factory.md`
+  - `kanban/20-doing/split-webchannel-god-class.md`
+- Next bounded seam split out explicitly instead of widening scope in-place:
+  - `kanban/20-doing/extract-webchannel-request-router-and-http-surface-wrappers.md`
+
 ## Links
 
 - `kanban/20-doing/split-webchannel-god-class.md`

kanban/40-review/extract-webchannel-runtime-and-followup-facades.md

@@ -136,7 +136,7 @@ Extract a dedicated runtime/follow-up facade seam while keeping the public
   - `scripts/audit-baseline-quality-deterministic.ts`
   - `runtime/test/scripts/audit-baseline-quality-deterministic.test.ts`
 - Next bounded seam split out explicitly instead of widening scope in-place:
-  - `kanban/20-doing/extract-webchannel-constructor-wiring-factory.md`
+  - `kanban/40-review/extract-webchannel-constructor-wiring-factory.md`
 - Quality: ★★★★☆ 8/10 (problem: 2, scope: 2, test: 2, deps: 1, risk: 1)
 
 ### 2026-03-28
@@ -148,7 +148,7 @@ Extract a dedicated runtime/follow-up facade seam while keeping the public
 ## Links
 
 - `kanban/20-doing/split-webchannel-god-class.md`
-- `kanban/20-doing/extract-webchannel-constructor-wiring-factory.md`
+- `kanban/40-review/extract-webchannel-constructor-wiring-factory.md`
 - `kanban/40-review/extract-webchannel-message-processing-and-storage-adapters.md`
 - `kanban/40-review/extract-webchannel-agent-message-entry-wrapper.md`
 - `/workspace/notes/piclaw-autoresearch-audit-checklist.md`