Collapse the duplicated declarations before the fleet store adds a fifth #176

Closed
opened 2026-09-18 07:48:31 +02:00 by lz · 0 comments
Owner

A simplification audit of the two MCP specs found ~290 lines removable today, independent of either spec, of which ~175 is pure declaration collapse at near-zero risk. This issue is that work.

It is sequenced first deliberately. The fleet status layer adds a fifth declaration of the workspace and session shapes, a fifth spelling of the healthy | unhealthy | unknown union (already written four times), and a new SSE wire shape. Collapsing afterwards means editing five copies instead of one, and every parity test that would otherwise have to be written is a test that cannot exist once there is a single declaration.

A1 — the server re-declares the wire shapes (~−82)

lib/api/types.ts is canonical and browser-safe, and has zero imports (verified; positive control: lib/attention.ts has 2). The server already imports from it at runtime — db/schema.ts, and mcp/projection.ts pulls WORKER_STATUSES/SESSION_STATUSES as values.

Duplicates to delete, each replaced by an import:

  • lib/server/workers/service.ts:48 WorkerDTO
  • lib/server/workers/service.ts:686 WorkerHealthReport (canonical: WorkerHealthDTO)
  • lib/server/sessions/service.ts:21 SessionDTO
  • lib/server/sessions/service.ts:1079
  • lib/server/previews/types.ts:5 PreviewDTO vs lib/api/types.ts:172 — unguarded by any parity test, so confirm they are actually identical before collapsing

Then delete lib/api/worker-dto-parity.test.ts.

The duplication's stated justification is false. That test's docblock claims "neither can import the other". Only one direction is illegal. Server importing a browser-safe module is legal and shipped; the reverse is also shipped — eight client files import type from $lib/server/artifacts/types, which is why ArtifactDTO is declared once while everything else is declared twice.

Do not touch MountSpec / MOUNT_KINDS / DEFAULT_NFS_OPTIONS, the token scope set, McpStatusDTO, CimdClientDTO — AGENTS.md names those as deliberate, and their canonical copies are under $lib/server and/or are runtime values the browser needs.

The gate is pnpm typecheck (svelte-check), NOT pnpm build. vite.config.ts carries only sveltekit() and scripts/build-server.mjs is a bare esbuild bundle; both strip types without checking. A green build over a broken DTO reads as success. Negative control: add a field to the canonical WorkerDTO, confirm pnpm typecheck goes red inside workerRowToDTO.

A2 — one sessionBasePath(kind, worktreeName) (~−40)

The worktree path formula is written out eight times outside sessions/service.ts — six server routes, plus the client copy at lib/components/main-page/scope.ts:45 whose own comment already complains it "was written out identically in four places".

New src/lib/session-path.ts, outside $lib/server (the git-ref.ts / cimd-url.ts / workspace-state.ts precedent) so scope.ts consumes the same implementation.

Hazard to preserve: the call sites do not agree on how they ask. Five test worktreeName === 'workspace' (a NAME test); submit/+server.ts tests sess.kind === 'workspace_shell' (a KIND test). They agree only because createSession reserves the name workspace. Take the kind as the parameter and pin that a kind='session' row named workspace is impossible.

A3 — ATTENTION_STATES declared twice (~−37)

lib/server/sessions/attention.ts:14 and lib/api/types.ts:130, pinned by a parity test. Server becomes a one-line re-export; the parity test goes. hooks-parity.test.ts and the z.enum(ATTENTION_STATES) on POST /api/agent/events must keep resolving and keep proving the set.

A4 — five private readJsonBody copies (~−35)

lib/server/lib/http.ts exports it and 17+ routes import it. Byte-identical private copies in settings/mounts, workers, workers/[id]/sessions, auth/setup, connections. Verify each is genuinely identical first.

Cheap prerequisites worth folding in

  • Delete the dead WorkerHealthDTO fields — containerState, tmuxRunning, recentLogs have zero .svelte readers (positive control: degraded hits six components). This also removes a tailLogs call per poll. Do it before the fleet store: if they survive into the store they also reach GET /api/workers, which is mapped in TOKEN_ROUTES and is projected by mcp/projection.ts — an API-visible removal instead of an internal one.
  • Share execProbe and the 20-iteration exit-code poll (execProbe exists twice; the poll four times) so the fleet layer's residual prober inherits one copy.

Rejected, recorded so it is not reproposed

  • Per-entity Workspace / Session classes. Nothing is deleted by it, and the natural implementation is a module-level registry keyed by id — which exists twice, once per bundle, with neither build warning (facts #25, #31).
  • Deleting lib/workspace-state.ts and computing running/ready server-side. Makes projection.test.ts's generated equivalence suite vacuous (w.running === w.running).
  • Deleting SessionHealthDTO.windowPresent. SettingsPanel.svelte:263 reads it; without it a normally-exited agent paints red.
  • Collapsing the config parameter to a singletons import. Breaks the DI at retry.test.ts:57 and spawn-mounts-dto.test.ts, and adds a cross-bundle cycle surface. Worth recording that 4 of 6 sites are pure pass-through so it is not rediscovered.

Done when

One declaration per shape, pnpm typecheck proven to catch a divergence by negative control, and every deleted test accompanied by a statement of why the property it protected is now structurally impossible rather than merely untested.

A simplification audit of the two MCP specs found ~290 lines removable **today**, independent of either spec, of which ~175 is pure declaration collapse at near-zero risk. This issue is that work. It is sequenced **first** deliberately. The fleet status layer adds a fifth declaration of the workspace and session shapes, a fifth spelling of the `healthy | unhealthy | unknown` union (already written four times), and a new SSE wire shape. Collapsing afterwards means editing five copies instead of one, and every parity test that would otherwise have to be written is a test that cannot exist once there is a single declaration. ## A1 — the server re-declares the wire shapes (~−82) `lib/api/types.ts` is canonical and browser-safe, and has **zero imports** (verified; positive control: `lib/attention.ts` has 2). The server already imports from it at runtime — `db/schema.ts`, and `mcp/projection.ts` pulls `WORKER_STATUSES`/`SESSION_STATUSES` as values. Duplicates to delete, each replaced by an import: - `lib/server/workers/service.ts:48` `WorkerDTO` - `lib/server/workers/service.ts:686` `WorkerHealthReport` (canonical: `WorkerHealthDTO`) - `lib/server/sessions/service.ts:21` `SessionDTO` - `lib/server/sessions/service.ts:1079` - `lib/server/previews/types.ts:5` `PreviewDTO` vs `lib/api/types.ts:172` — **unguarded by any parity test**, so confirm they are actually identical before collapsing Then delete `lib/api/worker-dto-parity.test.ts`. **The duplication's stated justification is false.** That test's docblock claims "neither can import the other". Only one direction is illegal. Server importing a browser-safe module is legal and shipped; the reverse is *also* shipped — eight client files `import type` from `$lib/server/artifacts/types`, which is why `ArtifactDTO` is declared once while everything else is declared twice. **Do not touch** `MountSpec` / `MOUNT_KINDS` / `DEFAULT_NFS_OPTIONS`, the token scope set, `McpStatusDTO`, `CimdClientDTO` — AGENTS.md names those as deliberate, and their canonical copies are under `$lib/server` and/or are runtime values the browser needs. **The gate is `pnpm typecheck` (svelte-check), NOT `pnpm build`.** `vite.config.ts` carries only `sveltekit()` and `scripts/build-server.mjs` is a bare esbuild bundle; both strip types without checking. A green build over a broken DTO reads as success. Negative control: add a field to the canonical `WorkerDTO`, confirm `pnpm typecheck` goes red inside `workerRowToDTO`. ## A2 — one `sessionBasePath(kind, worktreeName)` (~−40) The worktree path formula is written out eight times outside `sessions/service.ts` — six server routes, plus the client copy at `lib/components/main-page/scope.ts:45` whose own comment already complains it "was written out identically in four places". New `src/lib/session-path.ts`, **outside `$lib/server`** (the `git-ref.ts` / `cimd-url.ts` / `workspace-state.ts` precedent) so `scope.ts` consumes the same implementation. **Hazard to preserve:** the call sites do not agree on how they ask. Five test `worktreeName === 'workspace'` (a NAME test); `submit/+server.ts` tests `sess.kind === 'workspace_shell'` (a KIND test). They agree only because `createSession` reserves the name `workspace`. Take the kind as the parameter and pin that a `kind='session'` row named `workspace` is impossible. ## A3 — `ATTENTION_STATES` declared twice (~−37) `lib/server/sessions/attention.ts:14` and `lib/api/types.ts:130`, pinned by a parity test. Server becomes a one-line re-export; the parity test goes. `hooks-parity.test.ts` and the `z.enum(ATTENTION_STATES)` on `POST /api/agent/events` must keep resolving and keep proving the set. ## A4 — five private `readJsonBody` copies (~−35) `lib/server/lib/http.ts` exports it and 17+ routes import it. Byte-identical private copies in `settings/mounts`, `workers`, `workers/[id]/sessions`, `auth/setup`, `connections`. Verify each is genuinely identical first. ## Cheap prerequisites worth folding in - **Delete the dead `WorkerHealthDTO` fields** — `containerState`, `tmuxRunning`, `recentLogs` have zero `.svelte` readers (positive control: `degraded` hits six components). This also removes a `tailLogs` call per poll. **Do it before the fleet store**: if they survive into the store they also reach `GET /api/workers`, which *is* mapped in `TOKEN_ROUTES` and *is* projected by `mcp/projection.ts` — an API-visible removal instead of an internal one. - **Share `execProbe` and the 20-iteration exit-code poll** (`execProbe` exists twice; the poll four times) so the fleet layer's residual prober inherits one copy. ## Rejected, recorded so it is not reproposed - **Per-entity `Workspace` / `Session` classes.** Nothing is deleted by it, and the natural implementation is a module-level registry keyed by id — which exists twice, once per bundle, with neither build warning (facts #25, #31). - **Deleting `lib/workspace-state.ts` and computing `running`/`ready` server-side.** Makes `projection.test.ts`'s generated equivalence suite vacuous (`w.running === w.running`). - **Deleting `SessionHealthDTO.windowPresent`.** `SettingsPanel.svelte:263` reads it; without it a normally-exited agent paints red. - **Collapsing the `config` parameter to a `singletons` import.** Breaks the DI at `retry.test.ts:57` and `spawn-mounts-dto.test.ts`, and adds a cross-bundle cycle surface. Worth recording that 4 of 6 sites are pure pass-through so it is not rediscovered. ## Done when One declaration per shape, `pnpm typecheck` proven to catch a divergence by negative control, and every deleted test accompanied by a statement of why the property it protected is now structurally impossible rather than merely untested.
lz added this to the MCP support (#140) milestone 2026-09-18 07:48:31 +02:00
lz closed this issue 2026-09-21 19:10:02 +02:00
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus#176
No description provided.