# Bridge Refactor Phase A — Parallel Build

**Date:** 2026-09-14
**Lane:** id 9 (vibecoder-standalone-mavis)
**Source HEAD:** fc70ec5 (pre) → 6c4a94d (post-Phase-A)
**Audit refs:** Top structural issue per `audit-reconciliation-routes-editor.md` (b3015); Phase 4 Section A2 in a1107
**Constraint honoured:** server.cjs **not modified** (5,317 lines / 183 routes, unchanged at HEAD~5)

---

## 0c Structure findings (server.cjs landmarks)

| Concern | Lines | Status |
|---|---|---|
| imports + .env | 1–110 | Extracted → `bridge/lib/env.cjs` |
| auth helpers | 154–170 | Stub → `bridge/middleware/auth.cjs` |
| panel.db + PB setup | 100–150, scattered | Stub → `bridge/lib/db.cjs` (TODO) |
| 6 tool-call regex parsers | 2,818–3,030 | Extracted → `bridge/lib/parse-tool-calls.cjs` |
| `/api/agent/ai/chat` handler | 1,736–2,620 (~884 lines) | Stub → `bridge/lib/chat-handler.cjs` |
| Cascade loop + execute-cascade.cjs | 2,013–2,620 + ./vibe-agents/execute-cascade.cjs | Stub → `bridge/lib/cascade-orchestrator.cjs` |
| SSE streaming | inline in chat | (carried with chat-handler extraction) |
| Cinema/meme/VSIL | 3,500–5,000 | Stubbed per route family |
| Misc endpoints | 5,100–5,317 | Stub → `routes/misc.cjs` |
| JSON 404 + global error | 5,266–5,310 | NEW → `bridge/middleware/error-handler.cjs` |

---

## Deliverables (committed)

| Commit | Files | Description |
|---|---|---|
| b3032 | bridge/main.cjs, bridge/middleware/, bridge/README.md, start.sh | Scaffold + switch |
| b3033 | bridge/lib/{parse-tool-calls,env,db}.cjs | Extractions (parsers real, db stub) |
| b3034 | bridge/lib/{cascade-orchestrator,chat-handler}.cjs | Stubs (heavy extractions pending) |
| b3035 | bridge/routes/*.cjs (7 files) | 8 route scaffolds (all 501) |
| b3036 | bridge/scripts/parity-check.sh | Parity harness |

Total: 17 new files in `/bridge/`, 1 new top-level `start.sh`, 805 lines added.

---

## What works today

| Module | Status | Behaviour |
|---|---|---|
| `bridge/main.cjs` | WORKS | Boots Express on PORT (default 3004), JSON parser, mounts middleware + routes, registers 404 last |
| `bridge/middleware/error-handler.cjs` | WORKS | Catches thrown errors, returns 500 JSON |
| `bridge/middleware/auth.cjs` | WORKS | checkAuth + checkHqToken exposed via `app.locals` |
| `bridge/lib/env.cjs` | WORKS | Reads 9 env vars from `process.env`; parity-preserving |
| `bridge/lib/parse-tool-calls.cjs` | WORKS | 6 regex parsers with byte-identical patterns; `parseAllToolCalls()` aggregator |
| `start.sh` | WORKS | `BRIDGE_IMPL={monolith,modular}` switch |
| `bridge/scripts/parity-check.sh` | WORKS dry-run | Enumerates routes from server.cjs, probes both ports |

Verified locally on sandbox:

```
[bridge:modular] listening on http://127.0.0.1:3004
GET /api/agent/list_conversations  →  501 not_implemented (expected)
GET /api/cascade/active-accounts   →  501 not_implemented (expected)
```

## What does NOT work yet (Phase B scope)

| Concern | Remaining work |
|---|---|
| `bridge/lib/cascade-orchestrator.cjs` | Extract from server.cjs:2013-2620 + execute-cascade.cjs + cascade-config.cjs (3 sources → 1) |
| `bridge/lib/chat-handler.cjs` | 884-line ai/chat handler — split into 10 sub-concerns (A-J) |
| `bridge/lib/db.cjs` | Extract pbFetch from server.cjs:100-130 + panel.db open |
| `bridge/routes/agent.cjs` | Replace 501 catch-all with 175 individual handlers |
| Body-shape parity | parity-check.sh compares HTTP codes only; Phase B adds JSON body diff |

---

## Parity result (sandbox)

| Stat | Count |
|---|---:|
| Routes enumerated from server.cjs | **165** |
| `app.get/post/put/delete/patch` patterns | 183 |
| Difference | Dynamic-template routes (`:param` paths) skipped in scaffold per dispatch guidance |
| Match (200 both sides) | 0 (monolith down on sandbox — VPS-only) |
| Stub (501 from modular) | 0 (couldn't probe, monolith offline) |
| DIVERGE/MONO_DOWN | 165 (sandbox artifact, not a real parity verdict) |

**Honest verdict:** parity harness is built but cannot be exercised on sandbox because the monolith lives only on the VPS (`185.249.73.178:3003`). Real parity will run in Phase B against the live VPS.

---

## Constraints honoured

- [x] **server.cjs NOT modified.** Verified: 5,317 lines, 183 routes, identical to fc70ec5.
- [x] **systemd unit NOT modified.** `/opt/vibecoder-bridge/` untouched.
- [x] **VPS NOT touched.** Bridge refactor lives entirely in sandbox + git remote.
- [x] **No CI touched** — Sprint 3's `.github/workflows/ci.yml` runs unaffected.
- [x] **No `BRIDGE_IMPL=modular` in production** — opt-in only on port 3004.
- [x] **No task conflict with TASK-004 (CI gate).** Different files entirely.
- [x] **Forward-only compliance per §00.12.11.** All NEW bridge/ files are
      COMPLIANT from creation (P9 no-legacy pattern verified: no jQuery, no
      React deprecated lifecycle, no inline styles).

---

## What's next (Phase B, separate dispatch)

1. Real VPS-side parity run — phase B pushes modular to a sandbox VPS port, hits live monolith via 3003, compares JSON bodies.
2. Cascade orchestrator extraction — biggest single effort (~600 lines).
3. Chat handler decomposition — 884 lines into 10 sub-concerns.
4. Route body migration — 175 routes one at a time, parity tested.
5. systemd unit re-point — only after parity 100/183.
6. Switch flip — only after VPS smoke + watchdog health confirmed.

This dispatch establishes the structure; Phase B executes the migration.