summaryrefslogtreecommitdiffhomepage
path: root/backend-handoff.md
diff options
context:
space:
mode:
authorAdam Malczewski <[email protected]>2026-06-06 23:43:43 +0900
committerAdam Malczewski <[email protected]>2026-06-06 23:43:43 +0900
commitfac44794432928d0341728642fd70eef87837da4 (patch)
tree53445547f98bf5e798966efb339ce67cd8ebd20b /backend-handoff.md
parentf1409cd46d5a3cfb9002cbcdfd4ab947ac6846aa (diff)
downloaddispatch-web-fac44794432928d0341728642fd70eef87837da4.tar.gz
dispatch-web-fac44794432928d0341728642fd70eef87837da4.zip
Slice 2 unblock: pin wire + transport-contract; mirror contracts
- pin @dispatch/wire + @dispatch/transport-contract (+ ui-contract) as file: deps @0.1.0; overrides{} workaround for their workspace:* deps (bun can't resolve workspace: from outside the monorepo) - add fake-indexeddb (dev) for the upcoming IndexedDB adapter tests - mirror wire + transport-contract into .dispatch/*.reference.md for headless agents; point package-agent.md at all three references - backend-handoff.md: convert to a living FE<->backend seam doc Verified green: svelte-check 0/0, vitest 91, biome clean, build ok; contract import smoke-test passes.
Diffstat (limited to 'backend-handoff.md')
-rw-r--r--backend-handoff.md67
1 files changed, 67 insertions, 0 deletions
diff --git a/backend-handoff.md b/backend-handoff.md
new file mode 100644
index 0000000..eef9a78
--- /dev/null
+++ b/backend-handoff.md
@@ -0,0 +1,67 @@
+# Backend handoff — LIVING doc (FE ⇄ backend, couriered by the user)
+
+> **Purpose:** the single rolling document the FE orchestrator keeps current so the user can hand off
+> the whole FE↔backend seam at any time — on completion OR at a roadblock. Updated continuously.
+> **From:** dispatch-web orchestrator · **To:** arch-rewrite orchestrator · **Courier:** the user.
+> `lsp` does NOT span the repos (ORCHESTRATOR §5) — every cross-repo ask flows through here.
+
+_Last updated: 2026-06-06 — Slice 2 kicked off (unit summons in flight)._
+
+---
+
+## 1. Current FE status
+
+| Slice | State |
+|---|---|
+| **Slice 1** — surface system + WS + composition root | ✅ DONE, committed, green (svelte-check 0/0, 91 vitest, biome clean, build ok). |
+| **Slice 2** — conversation transcript: cache + delta streaming (design §6) | 🔧 IN PROGRESS — contracts pinned + mirrored; FE units being built (see §4). |
+
+## 2. Pinned backend contracts (consumed by the FE)
+
+All three pinned as `file:` deps at **`@0.1.0`** and live-verified consumable (import smoke-test passes):
+
+| Package | Used for |
+|---|---|
+| `@dispatch/ui-contract` | surfaces + surface WS protocol (Slice 1) |
+| `@dispatch/wire` | chat wire types: `Chunk`/`StoredChunk`(+`seq`)/`ChatMessage`/`AgentEvent`/`TurnSealedEvent`/`Usage` |
+| `@dispatch/transport-contract` | HTTP endpoints + `ChatRequest`/`ModelsResponse`/`ConversationHistoryResponse` + WS chat ops + unified `WsClientMessage`/`WsServerMessage` |
+
+Backend endpoints in use (port **24203** HTTP, **24205** WS, CORS wildcard `*` — all confirmed live):
+`POST /chat` (NDJSON), `GET /models`, `GET /conversations/:id?sinceSeq=<n>`, WS `chat.send`→`chat.delta`.
+Confirmed invariants C1–C4 (raw seq-ordered history slice · one path-agnostic WS multiplexing surface+chat · `turn-sealed` fires post-persist = cache-commit · live deltas carry no `seq`).
+
+Mirrored in-repo for headless agents: `.dispatch/ui-contract.reference.md`, `.dispatch/wire.reference.md`,
+`.dispatch/transport-contract.reference.md` (regenerated on any contract bump).
+
+## 3. Open items FOR THE BACKEND
+
+### 3.1 Resolved / answered
+- ✅ Wire-types split, per-chunk `seq`, history endpoint, WS chat multiplexing, CORS — all delivered
+ (backend commit `812621c`).
+
+### 3.2 FYI — non-blocking gotcha (no action required unless you publish externally)
+- **`workspace:*` breaks external `file:` consumption under bun.** `transport-contract`'s deps are
+ `@dispatch/ui-contract`/`@dispatch/wire` at `workspace:*`; `bun install` from dispatch-web could not
+ resolve them ("Workspace dependency not found"). **Worked around FE-side** with a `package.json`
+ `overrides` block mapping both to their `file:` paths — no backend change needed now. If you ever
+ publish these to a registry, prefer real semver ranges over `workspace:*` for out-of-monorepo
+ consumers.
+
+### 3.3 Pending asks / roadblocks
+- _(none open)_ — Slice 2 has all the backend contracts it needs.
+
+## 4. Looking ahead — FE Slice 2 unit map (no backend dependency)
+
+Pure-core / injected-shell decomposition, built by single-owner agents in this repo:
+`core/chunks` (the one transcript reducer) · `core/wire` (contract-conformance type-tests) ·
+`adapters/ws` (extend for `chat.send`/`chat.delta`) · `features/conversation-cache`
+(pure `reconcileCache`/`selectEvictions` + IndexedDB port) · `adapters/idb` (IndexedDB impl) ·
+`features/chat` (view-model + UI) · `app` (wiring). None require backend changes.
+
+## 5. Likely NEXT backend asks (heads-up, not yet requested)
+
+These belong to **later** FE slices (design §7 "later slice") — flagged early so they're on your radar:
+- `GET /conversations` — conversation list / sidebar (FE history explorer / conversation switcher).
+- `POST /conversations/:id/cancel` — "stop generating".
+
+When the FE reaches those slices, the concrete request will be filed here in §3.3.