Declare each wire shape and each row vocabulary once #180

Merged
lz merged 11 commits from refactor/collapse-declarations into main 2026-09-21 19:10:01 +02:00
Owner

Closes #176. Closes #181.

A simplification audit of the two MCP specs found the same wire shapes declared twice — once in the browser-safe lib/api/types.ts and again under $lib/server. This collapses them, plus three smaller duplications, before the fleet status layer (#177) adds a fifth declaration of each and a new SSE wire shape.

Rebased onto main after #174 merged, and extended to absorb #181 rather than leave a second pass over the same files.

What changed

commit net
b9dcbad declare each wire shape once, on the browser-safe side −120
1790abe derive a session's root directory in one place +28
feb3ef8 enumerate the attention states once −27
dbecd31 import readJsonBody rather than re-declaring it −35
92e20aa review fixes: restore displaced rationale, sweep orphans +7
deb7081 assert the worktree root as a literal, not through the constant under test +3
8019648 correct the call-site census; make the agent-artifacts fixture carry a kind +18
d4a773e (#181) declare each row vocabulary once, and read it from every side +44
5e0ad81 (#181) correct the import rule both docblocks stated backwards +14
c23eabe (#181) pin every session mark against its app.css rule +39
c83cd97 review fixes: fold that guard into the block that already existed, collapse a seventh copy, correct six claims −28

The second commit is net-positive and that is the honest result. The new module and its test are 68 lines against ~53 removed. It is here for correctness, not size: it collapses eight call sites that derived a session's base path three different ways.

The #181 half

The duplication was worse than #181 reported — partly because #174 added a copy after the issue was written, partly because the issue undercounted, and partly because this branch's own first census undercounted too. Final figures, re-derived with git grep -F at the branch base:

vocabulary copies where
SessionKind 5 schema.ts, the DTO inline, mcp/projection.ts's z.enum, and two test fixtures that restated the union
ProviderKind 4 schema.ts, providers/types.ts, the DTO inline, the connections route's z.enum
PreviewScheme 7 schema.ts, api/types.ts, client.ts's signature, two route z.enums, Previews.svelte's $state, and the <option> values in that same component's markup
PreviewStatus / PreviewSource 2 each schema.ts, api/types.ts

Each is now one as const array in $lib/api/types, type derived from it. The request schemas and the scheme picker read the array, so a hand-written pair is no longer expressible where one used to be. The two test fixtures matter more than they look: under the old form a rename turned production red while they stayed green, still minting a kind the schema no longer knew — both are now among the files a rename takes down.

Why the browser-safe module, honestly. An earlier revision of this description (and of d4a773e's message) said a const array in $lib/server "could never back the client's $state<PreviewScheme> or the DTO". That is false — both are type positions, erased before the bundle. At that point no client module read any of the five arrays at runtime; they sat with their siblings because that is where this app's vocabulary is declared, not because a rule forced it. Making the picker iterate PREVIEW_SCHEMES has since given them one genuine client-side reader. The array that always had to live there is ATTENTION_STATES, which $lib/attention spreads into SESSION_MARKS in the browser.

The rule two docblocks stated is false in both directions (#181 item 3): server code imports $lib/api/types throughout, and nine browser-shipped modules import type from $lib/server/artifacts/types, which is legal because a type import is erased before SvelteKit's own illegal-import plugin sees it (@sveltejs/kit/src/exports/vite/index.js, whose error text says as much). Both copies are corrected in one commit, because fixing one leaves the survivor looking authoritative. mcp-dto-parity.test.ts stays — its duplication is live and its assertion still fails on real drift; only the stated reason was wrong.

#181 item 4 was already wrong when it was filed, and this branch repeated it before catching it. attention.test.ts:115 has had a describe('attention CSS parity') since 2026-09-05 that reads app.css, loops the same SESSION_MARKS, and requires a rule that actually paints — strictly stronger than the selector grep this branch briefly added in a new file. Only the reverse direction was ever missing: a stale .status-dot.<mark> for a mark that no longer exists. That single assertion now lives in the existing block, stripping CSS comments first, and the new file is gone.

Why deleting two parity tests is legitimate

worker-dto-parity.test.ts was itself type-level only, so the gate did not weaken — the file was removed from under the same gate. vitest.config.ts sets no test.typecheck, so vitest never executed those two assignability assertions; pnpm typecheck was already their sole enforcement. That is a stronger argument than "typecheck replaces the test", and it is measured rather than reasoned.

The duplication it guarded is gone: there is one WorkerDTO, and workerRowToDTO constructs it as an object literal with a declared return type, so missing-field and excess-property checking now enforce both drift directions at compile time. The same protection extends to SessionDTO, PreviewDTO and both health DTOs, none of which ever had a parity test.

pnpm build does not type-check, and this was measured, not inferred: injecting bogus_field_that_does_not_exist: 42 into the workerRowToDTO literal and running vite build emitted both bundles with no error, and the field is present in the output chunk. vite.config.ts carries only sveltekit(); scripts/build-server.mjs is a bare esbuild bundle. eslint is not a second gate either — eslint.config.js uses tseslint.configs.recommended with no project/projectService, so it is not type-aware. CI runs all four gates as separate steps, so pnpm typecheck does gate merges.

For session-attention-parity.test.ts, only its first assertion becomes impossible. A rename is still forced through hooks-parity.test.ts (which pins the set against worker/plugins/nexus/hooks/hooks.json in both directions), attention.test.ts (which asserts the four literals through the re-export, and now both CSS directions), and four typecheck-red literal sites in lib/attention.ts.

The name→kind switch is a behaviour change on old databases, and it corrects them

On main the base path was derived three ways: five sites keyed on worktree_name === 'workspace'; two keyed on kind === 'workspace_shell' (checkSessionHealth and the artifact submit route); and scope.ts tested neither, always returning the worktree path.

A row with kind='session' and worktree_name='workspace' is constructible on a database predating 2caa986. Before that commit createSession had no name reservation and the workspace shell was not a sessions row at all, so workspace was an ordinary legal session name; worktree_name has existed since migration 0002; and 0006_workspace_shell_session.ts adds kind as notNull().defaultTo('session') with no backfill pass, so such a row becomes kind='session'.

For that row the truth is "a regular session with a worktree at /workspace/.nexus/worktrees/workspace". The old name test resolved its artifacts against /workspace; the kind test resolves them against the worktree. So on real legacy data the five switched sites go from wrong to right. The reverse direction is unconstructible — openWorkspaceSession is the only writer of workspace_shell and sets both fields to workspace.

Nobody would have noticed, because on such a worker openWorkspaceSession has always been unable to insert its own row anyway: uq_sessions_worker_name on (worker_id, name) from migration 0002 already holds the name. The shell is broken there independently.

Separately, the client's sessionScope previously computed the shell's path wrongly, but no caller could reach it — all four call sites plus the indirect RailHoverCard path filter to kind === 'session' first. That fixes nothing observable; what changes is that sessionScope's correctness no longer depends on those filters.

Verification

Each gate its own command, output redirected, $? read before the log — never piped to tail.

gate on the rebase final
typecheck 5177 files, 0 errors 5177 files, 0 errors
vitest 200 files, 2236 tests 200 files, 2237 tests
lint 0 0
build 0 0

The rebase replayed seven commits with no conflict and all four gates were green before any new work — so nothing in #174 (which added mcp/projection.ts and mcp-dto-parity.test.ts, both consumers of the shapes collapsed here) conflicted semantically with this branch.

Two timeouts on later runs, neither this branch's, and worth recording as a suite property. oauth/provider-cross-bundle.test.ts (builds two oidc-provider instances) and session-path.test.ts each exceeded vitest's 10s default on a loaded host — different tests on different runs. Both pass in isolation (the second at 4.8s, i.e. half the budget when the host is quiet), and the first reproduces on plain origin/main in a separate worktree. Several tests sit close enough to the default that a busy machine flips them; a per-test testTimeout on the slow ones would remove the ambiguity.

Negative controls. Every mutation was diffed against a cp backup before its result was believed, and restored from that backup rather than git checkout:

mutation result
field added to the canonical WorkerDTO typecheck red inside workerRowToDTO — the direction the deleted test guarded
createSession's name reservation disabled session-path reservation test red
fifth attention state appended hooks-parity.test.ts red
WORKTREES_ROOT → /wrong/root session-path.test.ts red (it was not, before deb7081)
sessionBasePath loses its shell arm session-path.test.ts and the new agent-artifacts shell case red
predicate reverted to the name test only session-path.test.ts:10 dies — the single guard for the switch
SESSION_KINDS member renamed 26 errors across 12 files at the final tree (24/11 before the last call sites were collapsed — both true of their tree)
a .status-dot rule for a mark that does not exist the relocated reverse assertion, alone
a mark's rule deleted, its name left in a comment three assertions, including the pre-existing one — rulesFor demands a real {…} block
ended → ended_v2 the pre-existing paints assertion, so the two directions do not overlap into a gap
base .status-dot.working deleted, @media override kept the pre-existing assertion — the case the deleted file SURVIVED

Review

Four agents reviewed the first seven commits; three more reviewed the #181 commits. Ten findings changed the code.

From the first round: a false comment justifying session-path.ts's location, which had also displaced a true one; a test whose expectation was built from the constant under test and so could not fail; a wrong call-site census; and a fixture that under-specified what the route reads.

From the second round, every one of these was a claim of mine that turned out to be false:

  • app.css was never unguarded — the new test file is deleted and only its reverse assertion kept.
  • "a const array in $lib/server could never back the client's $state" — type positions are erased, and at the time no client module read these arrays at runtime.
  • "eleven client modules" — nine browser-shipped, plus two test files that are not evidence. Inherited from #181 and not re-derived, in the commit whose subject was docblock accuracy.
  • "Every vocabulary a row shares with the wire is declared once" — false of schema.ts itself, where ArtifactKind, ArtifactSource and ArtifactCommentStatus are declared and travel the other way.
  • The duplication census undercounted its own diff — SessionKind five sites, not three; PreviewScheme seven, not five.
  • A seventh copy of the scheme pair was left behind in the picker's <option> markup; it now iterates the array.

Plus two small ones: the illegal-import check is SvelteKit's plugin, not Vite's; and types.ts pointed at mcp-status-parity.test.ts, which does not exist.

Confirmed unaffected: mounts/ and tokens/ are untouched and both parity tests pass, so facts #22 and #24 stand; the five vocabularies collapse to identically ordered tuples, so the four z.enum sites build identical schemas and identical error text; the re-exports are export type only, so no runtime value leaves $lib/server; and $lib/api/types.ts imports nothing, so there is no cycle in either bundle (fact #31).

Worth recording: every collapsed vocabulary also has a database CHECK backstop — migrations/0006 for kind, 0008 for scheme, 0001 for the provider kind — so a future widening fails loudly at the row rather than silently on the wire. PROVIDER_KINDS carries a second guard on top, SUPPORTED_KINDS, which is why github parses and then 400s.

Deliberately not done

  • MountSpec and the token scopes stay duplicated with their parity tests. AGENTS.md facts #22 and #24 name that duplication deliberate; this branch only makes the stated reasons true. AGENTS.md itself needed no edit — grep with a positive control shows it never carried the false import rule.
  • PREVIEW_STATUSES and PREVIEW_SOURCES still have no runtime reader; they exist only as the source of their type aliases. A plain type alias would collapse the duplication equally well, but making two of the three preview vocabularies a different shape from the third buys nothing.
  • #186 carries the two rename anchors this does not reach: the :global(.needs-you) tints in SessionRow.svelte and WorkspaceRail.svelte, which a rename leaves dead with every gate green, and a parity test pinning each array against the migration CHECK behind it.
  • Four widened selects have no test file at all ([sessionId]/artifacts/+server.ts, [artifactId]/+server.ts, raw/+server.ts, [artifactId]/+page.server.ts). Pre-existing; the compiler still catches a dropped kind there, because those selects feed the annotated AuthorizedAgentSession.

One consequence worth stating rather than fixing: workerRowToDTO now assigns the server's MountSpec[] into the canonical one, adding a one-directional compile-time check between two declarations AGENTS.md requires to stay separate. The duplication is not weakened — it picked up a free partial guard on top of mount-parity.test.ts.

Closes #176. Closes #181. A simplification audit of the two MCP specs found the same wire shapes declared twice — once in the browser-safe `lib/api/types.ts` and again under `$lib/server`. This collapses them, plus three smaller duplications, **before** the fleet status layer (#177) adds a fifth declaration of each and a new SSE wire shape. Rebased onto `main` after #174 merged, and extended to absorb #181 rather than leave a second pass over the same files. ## What changed | commit | | net | |---|---|---| | `b9dcbad` | declare each wire shape once, on the browser-safe side | −120 | | `1790abe` | derive a session's root directory in one place | **+28** | | `feb3ef8` | enumerate the attention states once | −27 | | `dbecd31` | import `readJsonBody` rather than re-declaring it | −35 | | `92e20aa` | review fixes: restore displaced rationale, sweep orphans | +7 | | `deb7081` | assert the worktree root as a literal, not through the constant under test | +3 | | `8019648` | correct the call-site census; make the agent-artifacts fixture carry a `kind` | +18 | | `d4a773e` | **(#181)** declare each row vocabulary once, and read it from every side | +44 | | `5e0ad81` | **(#181)** correct the import rule both docblocks stated backwards | +14 | | `c23eabe` | **(#181)** pin every session mark against its app.css rule | +39 | | `c83cd97` | **review fixes:** fold that guard into the block that already existed, collapse a seventh copy, correct six claims | −28 | **The second commit is net-positive and that is the honest result.** The new module and its test are 68 lines against ~53 removed. It is here for correctness, not size: it collapses eight call sites that derived a session's base path three different ways. ## The #181 half **The duplication was worse than #181 reported** — partly because #174 added a copy after the issue was written, partly because the issue undercounted, and partly because this branch's own first census undercounted too. Final figures, re-derived with `git grep -F` at the branch base: | vocabulary | copies | where | |---|---|---| | `SessionKind` | 5 | `schema.ts`, the DTO inline, **`mcp/projection.ts`'s `z.enum`**, and two test fixtures that restated the union | | `ProviderKind` | 4 | `schema.ts`, `providers/types.ts`, the DTO inline, the connections route's `z.enum` | | `PreviewScheme` | 7 | `schema.ts`, `api/types.ts`, `client.ts`'s signature, **two** route `z.enum`s, `Previews.svelte`'s `$state`, and the `<option>` values in that same component's markup | | `PreviewStatus` / `PreviewSource` | 2 each | `schema.ts`, `api/types.ts` | Each is now one `as const` array in `$lib/api/types`, type derived from it. The request schemas and the scheme picker read the array, so a hand-written pair is no longer expressible where one used to be. The two test fixtures matter more than they look: under the old form a rename turned production red while they stayed green, still minting a kind the schema no longer knew — both are now among the files a rename takes down. **Why the browser-safe module, honestly.** An earlier revision of this description (and of `d4a773e`'s message) said a const array in `$lib/server` "could never back the client's `$state<PreviewScheme>` or the DTO". That is false — both are type positions, erased before the bundle. At that point **no client module read any of the five arrays at runtime**; they sat with their siblings because that is where this app's vocabulary is declared, not because a rule forced it. Making the picker iterate `PREVIEW_SCHEMES` has since given them one genuine client-side reader. The array that always had to live there is `ATTENTION_STATES`, which `$lib/attention` spreads into `SESSION_MARKS` in the browser. **The rule two docblocks stated is false in both directions** (#181 item 3): server code imports `$lib/api/types` throughout, and **nine** browser-shipped modules `import type` from `$lib/server/artifacts/types`, which is legal because a type import is erased before SvelteKit's own illegal-import plugin sees it (`@sveltejs/kit/src/exports/vite/index.js`, whose error text says as much). Both copies are corrected in one commit, because fixing one leaves the survivor looking authoritative. `mcp-dto-parity.test.ts` stays — its duplication is live and its assertion still fails on real drift; only the stated reason was wrong. **#181 item 4 was already wrong when it was filed, and this branch repeated it before catching it.** `attention.test.ts:115` has had a `describe('attention CSS parity')` since 2026-09-05 that reads `app.css`, loops the same `SESSION_MARKS`, and requires a rule that actually *paints* — strictly stronger than the selector grep this branch briefly added in a new file. Only the **reverse** direction was ever missing: a stale `.status-dot.<mark>` for a mark that no longer exists. That single assertion now lives in the existing block, stripping CSS comments first, and the new file is gone. ## Why deleting two parity tests is legitimate **`worker-dto-parity.test.ts` was itself type-level only, so the gate did not weaken — the file was removed from under the same gate.** `vitest.config.ts` sets no `test.typecheck`, so vitest never executed those two assignability assertions; `pnpm typecheck` was already their sole enforcement. That is a stronger argument than "typecheck replaces the test", and it is measured rather than reasoned. The duplication it guarded is gone: there is one `WorkerDTO`, and `workerRowToDTO` constructs it as an object literal with a declared return type, so missing-field *and* excess-property checking now enforce both drift directions at compile time. The same protection extends to `SessionDTO`, `PreviewDTO` and both health DTOs, none of which ever had a parity test. **`pnpm build` does not type-check, and this was measured, not inferred:** injecting `bogus_field_that_does_not_exist: 42` into the `workerRowToDTO` literal and running `vite build` emitted both bundles with no error, and the field is present in the output chunk. `vite.config.ts` carries only `sveltekit()`; `scripts/build-server.mjs` is a bare esbuild bundle. **eslint is not a second gate either** — `eslint.config.js` uses `tseslint.configs.recommended` with no `project`/`projectService`, so it is not type-aware. CI runs all four gates as separate steps, so `pnpm typecheck` does gate merges. For `session-attention-parity.test.ts`, only its *first* assertion becomes impossible. A rename is still forced through `hooks-parity.test.ts` (which pins the set against `worker/plugins/nexus/hooks/hooks.json` in both directions), `attention.test.ts` (which asserts the four literals through the re-export, and now both CSS directions), and four typecheck-red literal sites in `lib/attention.ts`. ## The name→kind switch is a behaviour change on old databases, and it corrects them On main the base path was derived **three** ways: five sites keyed on `worktree_name === 'workspace'`; two keyed on `kind === 'workspace_shell'` (`checkSessionHealth` and the artifact submit route); and `scope.ts` tested neither, always returning the worktree path. A row with `kind='session'` and `worktree_name='workspace'` **is** constructible on a database predating `2caa986`. Before that commit `createSession` had no name reservation and the workspace shell was not a `sessions` row at all, so `workspace` was an ordinary legal session name; `worktree_name` has existed since migration 0002; and `0006_workspace_shell_session.ts` adds `kind` as `notNull().defaultTo('session')` with no backfill pass, so such a row becomes `kind='session'`. For that row the truth is "a regular session with a worktree at `/workspace/.nexus/worktrees/workspace`". The old name test resolved its artifacts against `/workspace`; the kind test resolves them against the worktree. So on real legacy data the five switched sites go from wrong to right. The reverse direction is unconstructible — `openWorkspaceSession` is the only writer of `workspace_shell` and sets both fields to `workspace`. Nobody would have noticed, because on such a worker `openWorkspaceSession` has always been unable to insert its own row anyway: `uq_sessions_worker_name` on `(worker_id, name)` from migration 0002 already holds the name. The shell is broken there independently. Separately, the client's `sessionScope` previously computed the shell's path wrongly, but **no caller could reach it** — all four call sites plus the indirect `RailHoverCard` path filter to `kind === 'session'` first. That fixes nothing observable; what changes is that `sessionScope`'s correctness no longer *depends* on those filters. ## Verification Each gate its own command, output redirected, `$?` read before the log — never piped to `tail`. | gate | on the rebase | final | |---|---|---| | typecheck | 5177 files, 0 errors | 5177 files, 0 errors | | vitest | 200 files, 2236 tests | 200 files, 2237 tests | | lint | 0 | 0 | | build | 0 | 0 | The rebase replayed seven commits with no conflict and all four gates were green *before* any new work — so nothing in #174 (which added `mcp/projection.ts` and `mcp-dto-parity.test.ts`, both consumers of the shapes collapsed here) conflicted semantically with this branch. **Two timeouts on later runs, neither this branch's, and worth recording as a suite property.** `oauth/provider-cross-bundle.test.ts` (builds two oidc-provider instances) and `session-path.test.ts` each exceeded vitest's 10s default on a loaded host — different tests on different runs. Both pass in isolation (the second at 4.8s, i.e. half the budget when the host is quiet), and the first reproduces on plain `origin/main` in a separate worktree. Several tests sit close enough to the default that a busy machine flips them; a per-test `testTimeout` on the slow ones would remove the ambiguity. Negative controls. Every mutation was diffed against a `cp` backup before its result was believed, and restored from that backup rather than `git checkout`: | mutation | result | |---|---| | field added to the canonical `WorkerDTO` | typecheck red inside `workerRowToDTO` — the direction the deleted test guarded | | `createSession`'s name reservation disabled | `session-path` reservation test red | | fifth attention state appended | `hooks-parity.test.ts` red | | `WORKTREES_ROOT` → `/wrong/root` | `session-path.test.ts` red (it was **not**, before `deb7081`) | | `sessionBasePath` loses its shell arm | `session-path.test.ts` **and** the new agent-artifacts shell case red | | predicate reverted to the name test | only `session-path.test.ts:10` dies — the single guard for the switch | | `SESSION_KINDS` member renamed | **26 errors across 12 files** at the final tree (24/11 before the last call sites were collapsed — both true of their tree) | | a `.status-dot` rule for a mark that does not exist | the relocated reverse assertion, alone | | a mark's rule deleted, its name left in a comment | three assertions, including the pre-existing one — `rulesFor` demands a real `{…}` block | | `ended` → `ended_v2` | the **pre-existing** paints assertion, so the two directions do not overlap into a gap | | base `.status-dot.working` deleted, `@media` override kept | the pre-existing assertion — the case the deleted file SURVIVED | ## Review Four agents reviewed the first seven commits; three more reviewed the #181 commits. Ten findings changed the code. From the first round: a false comment justifying `session-path.ts`'s location, which had also displaced a true one; a test whose expectation was built from the constant under test and so could not fail; a wrong call-site census; and a fixture that under-specified what the route reads. From the second round, every one of these was a claim of mine that turned out to be false: - **`app.css` was never unguarded** — the new test file is deleted and only its reverse assertion kept. - **"a const array in `$lib/server` could never back the client's `$state`"** — type positions are erased, and at the time no client module read these arrays at runtime. - **"eleven client modules"** — nine browser-shipped, plus two test files that are not evidence. Inherited from #181 and not re-derived, in the commit whose subject was docblock accuracy. - **"Every vocabulary a row shares with the wire is declared once"** — false of `schema.ts` itself, where `ArtifactKind`, `ArtifactSource` and `ArtifactCommentStatus` are declared and travel the *other* way. - **The duplication census undercounted its own diff** — `SessionKind` five sites, not three; `PreviewScheme` seven, not five. - **A seventh copy of the scheme pair was left behind** in the picker's `<option>` markup; it now iterates the array. Plus two small ones: the illegal-import check is SvelteKit's plugin, not Vite's; and `types.ts` pointed at `mcp-status-parity.test.ts`, which does not exist. Confirmed unaffected: `mounts/` and `tokens/` are untouched and both parity tests pass, so facts #22 and #24 stand; the five vocabularies collapse to identically **ordered** tuples, so the four `z.enum` sites build identical schemas and identical error text; the re-exports are `export type` only, so no runtime value leaves `$lib/server`; and `$lib/api/types.ts` imports nothing, so there is no cycle in either bundle (fact #31). Worth recording: every collapsed vocabulary also has a **database `CHECK` backstop** — `migrations/0006` for `kind`, `0008` for `scheme`, `0001` for the provider kind — so a future widening fails loudly at the row rather than silently on the wire. `PROVIDER_KINDS` carries a second guard on top, `SUPPORTED_KINDS`, which is why `github` parses and then 400s. ## Deliberately not done - `MountSpec` and the token scopes stay duplicated with their parity tests. AGENTS.md facts #22 and #24 name that duplication deliberate; this branch only makes the *stated reasons* true. AGENTS.md itself needed no edit — `grep` with a positive control shows it never carried the false import rule. - `PREVIEW_STATUSES` and `PREVIEW_SOURCES` still have no runtime reader; they exist only as the source of their type aliases. A plain type alias would collapse the duplication equally well, but making two of the three preview vocabularies a different shape from the third buys nothing. - **#186** carries the two rename anchors this does not reach: the `:global(.needs-you)` tints in `SessionRow.svelte` and `WorkspaceRail.svelte`, which a rename leaves dead with every gate green, and a parity test pinning each array against the migration `CHECK` behind it. - Four widened selects have no test file at all (`[sessionId]/artifacts/+server.ts`, `[artifactId]/+server.ts`, `raw/+server.ts`, `[artifactId]/+page.server.ts`). Pre-existing; the compiler still catches a dropped `kind` there, because those selects feed the annotated `AuthorizedAgentSession`. One consequence worth stating rather than fixing: `workerRowToDTO` now assigns the server's `MountSpec[]` into the canonical one, adding a one-directional compile-time check between two declarations AGENTS.md requires to stay separate. The duplication is not weakened — it picked up a free partial guard on top of `mount-parity.test.ts`.
lz added this to the MCP support (#140) milestone 2026-09-18 10:05:01 +02:00
lz added 5 commits 2026-09-18 10:05:02 +02:00
`$lib/api/types` has zero imports and is already the canonical declaration:
the server imports it for values today (`db/schema.ts`, `mcp/projection.ts`
read `WORKER_STATUSES`). Five server-side restatements are deleted and the
canonical types imported instead — `WorkerDTO`, `WorkerHealthReport`
(→ `WorkerHealthDTO`), `SessionDTO`, `SessionHealthReport`
(→ `SessionHealthDTO`), and `previews/types.ts`'s `PreviewDTO`, which was
field-for-field identical to the canonical one and guarded by nothing.

The justification the deleted parity test carried was false. It claimed
"neither can import the other ($lib/api/types is reachable from the browser,
$server is not)"; only one direction is illegal. Server → browser-safe is
shipped in 13 files, and the reverse is shipped too — ten client modules
`import type` from `$lib/server/artifacts/types`.

`worker-dto-parity.test.ts` is deleted because the drift it checked is now
unconstructible, not merely untested: it asserted mutual assignability between
two declarations, and there is one. A field added to `WorkerDTO` now fails
`workerRowToDTO` directly — verified by adding one and watching svelte-check
report `service.ts:96:3`, the object literal it returns.

`pnpm build` is not the gate for this: both `vite build` and the esbuild
server bundle strip types without checking them, so a broken DTO builds clean.
`pnpm typecheck` is.
`/workspace/.nexus/worktrees/<name>`, with `/workspace` for the workspace
shell, was re-derived in nine places: six route/page modules, `scope.ts` on the
client (whose own comment already said it "was written out identically in four
places"), and three spellings inside `sessions/service.ts`. `$lib/session-path`
now owns the formula and `WORKTREES_ROOT`, outside `$lib/server` like
`git-ref.ts` and `cimd-url.ts` so the dock's scope builder runs the same
implementation the endpoints it calls resolve with.

The call sites did not agree on how they asked. Five tested
`worktree_name === 'workspace'`; `submit/+server.ts` tested
`kind === 'workspace_shell'`. `sessionBasePath` takes the KIND — the fact
actually being asked about — so the five now select `kind` alongside
`worktree_name`, and `AuthorizedAgentSession` widens by the same column.

The two spellings agree only because `createSession` refuses the name
`workspace`, which is what makes the collapse safe rather than merely tidy.
`session-path.test.ts` pins that: it drives `createSession` with that name and
demands the rejection. Verified by disabling the reservation and watching the
named test die.

No behaviour change for the client: every `sessionScope` caller already
filtered to `kind === 'session'` (`Sessions.svelte`'s `userSessions`,
`WorkspaceRail`'s `sessionsOf`, both `palette-index` sites), so the shell
branch it gained is unreachable from there and the path it returns is
unchanged.
`$server/sessions/attention` re-exports `ATTENTION_STATES` from
`$lib/api/types` instead of declaring its own copy. Server-side consumers keep
importing it from where they already do — the Zod enum on
POST /api/agent/events, `db/schema.ts`, hooks-parity.test.ts — so nothing else
moves. The type is imported separately as well as re-exported, because a
re-export does not bind the name in the module body and `recordAttention`
takes it as a parameter.

`session-attention-parity.test.ts` is deleted. Its premise ("the client cannot
import server modules, so the set is genuinely written twice") had it
backwards: the illegal direction is client → server, and this is server →
client, which `db/schema.ts` has done for these same types all along. With one
array there is no second copy to drift.

What that test actually protected — that the set the hooks send and the set the
endpoint accepts are the same — was never its job and is unaffected:
hooks-parity.test.ts still reads the array and still checks it against
worker/plugins/nexus/hooks/hooks.json. Verified by appending a fifth state to
the canonical array: `covers every state at least once` fails, and the
endpoint's `rejects a state the hooks never send` still passes on the
unmutated set.
Five routes carried a private copy while 17 others imported the one in
`$server/lib/http`. All five were byte-identical to it — same signature, same
`try { return await request.json() } catch { return null }`, no docblock — so
each becomes an import and a deletion, with no behaviour to check.
refactor: keep the rationale the collapse displaced, and sweep its orphans
Some checks failed
ci / images (pull_request) Has been cancelled
ci / nexus (pull_request) Has been cancelled
c2c6b23e74
Review found the new comment justifying session-path.ts living outside
$lib/server was false: it claimed the server resolves the same path with the
same implementation, when provider.ts puts basePath on the query string and the
files endpoints take `base` verbatim. Nothing server-side re-derives it. The
comment it displaced was true and said the useful thing — the formula has to
agree with what createSession made on disk — so that is what it says now, plus
the string-concat-not-path.join note that lost its last home in the collapse.

Three notes deleted with the server twins are restored onto the canonical
declarations: the frozen-at-create invariant on mounts, the non-browser reader
of host_url, and why pid is on the wire.

Orphans this branch created: previews/types.ts re-exported three unions only
for the deleted PreviewDTO; WorkerHealth's export lost its second consumer;
schema.ts pointed at sessions/attention.ts as the vocabulary's source when it
is now a re-export; and mcp-dto-parity.test.ts cross-referenced a test this
branch deletes.
test: assert the worktree root as a literal, not through the constant under test
Some checks failed
ci / images (pull_request) Has been cancelled
ci / nexus (pull_request) Has been cancelled
7f79d648c7
session-path.test.ts built its expectation from WORKTREES_ROOT, imported from
the module it tests, so the root itself was unfalsifiable there. Measured:
changing it to /wrong/root left both tests green while killing 12 elsewhere.
Now the same mutation kills this test, which is where a reader would look.
fix: correct the call-site census, and make the agent-artifacts fixture carry a kind
All checks were successful
ci / nexus (pull_request) Successful in 9m48s
ci / images (pull_request) Successful in 11m27s
3be43ee3cd
The census in session-path.ts and its test said five sites keyed on the name
and one on the kind. Measured against main: five derived the path from the
name, TWO from the kind (checkSessionHealth and the artifact submit route),
and scope.ts tested neither and always returned the worktree path.

The test docblock also claimed to license the whole name/kind agreement. It
pins one direction — no kind='session' row can be named workspace. The other,
that openWorkspaceSession writes worktree_name: WORKSPACE_WINDOW, rests on it
being the single writer and is not pinned here.

sessionFound() omitted kind, so sess.kind was undefined, sessionBasePath took
the else branch, and the assertion passed whether the route keyed on the name
or the kind. The fixture now carries it and a shell case covers the branch the
route had no coverage of. Both die if sessionBasePath loses its shell arm.
lz force-pushed refactor/collapse-declarations from 3be43ee3cd
All checks were successful
ci / nexus (pull_request) Successful in 9m48s
ci / images (pull_request) Successful in 11m27s
to c23eabe4de
Some checks failed
ci / nexus (pull_request) Failing after 11m21s
ci / images (pull_request) Has been skipped
2026-09-21 16:58:52 +02:00
Compare
lz changed title from Declare each wire shape once, before the fleet store adds a fifth to Declare each wire shape and each row vocabulary once 2026-09-21 16:59:46 +02:00
fix(test): fold the CSS guard into the parity block that already existed
Some checks failed
ci / nexus (pull_request) Has been cancelled
ci / images (pull_request) Has been cancelled
485a7400a1
Review fixes. Three claims this branch shipped were false, and one of them had
a whole test file resting on it.

**`app.css` was never unguarded.** `attention.test.ts:115` has carried a
`describe('attention CSS parity')` since 2026-09-05 — twelve days before #181
item 4 said nothing checked it — and that block is STRONGER than the file this
commit deletes: it loops the same `SESSION_MARKS` and demands a rule that
actually PAINTS, filtering out `animation: none` overrides, where the new one
only grepped for the selector. Measured: deleting the base
`.status-dot.working` rule while its `@media (prefers-reduced-motion)`
override survives — a realistic partial rename, and a case the deleted file's
own mutation testing found it SURVIVING — fails the pre-existing assertion.

So only the reverse direction was ever new: a stale `.status-dot.<mark>` for a
mark that no longer exists, which nothing checked and which is how the next
rename gets a false all-clear. That single `it` moves into the existing block,
which already reads the stylesheet, and `attention-css.test.ts` is deleted —
there is no `attention-css.ts` for it to sit beside, and two files reading
`app.css` for marks would have to be kept in sync by hand.

It strips CSS comments before scanning, which the deleted version did not: a
selector inside a comment styles nothing, so it would have been reported as a
mark that no longer exists. That also closes the other survivor the mutation
pass found — a rule deleted with its name left behind in a comment.

**The count was wrong.** "Eleven client modules import type from
`$lib/server/artifacts/types`" is nine browser-shipped modules, plus two test
files that are not evidence for the claim, since a test never goes through the
client build. Taken from #181 and not re-derived — in a commit whose subject
was docblock accuracy. (Re-derived here with `grep -F`: the regex form returns
zero because `$` is not literal, which is the absence-grep trap.)

**"Every vocabulary a row shares with the wire is declared once"** is false of
schema.ts itself: `ArtifactKind`, `ArtifactSource` and `ArtifactCommentStatus`
are declared IN that file, reach the wire through `ArtifactDTO`, and are
imported by client components — the opposite direction, which is exactly the
point the paragraph was making. Corrected to say so rather than overclaim.

Negative controls, each diffed against a `cp` backup and restored from it: a
rule for a mark that does not exist kills the new assertion alone; a rule
deleted with its name left in a comment now kills three; `ended` → `ended_v2`
is killed by the pre-existing assertion, so the two directions do not overlap
into a gap.
lz force-pushed refactor/collapse-declarations from 485a7400a1
Some checks failed
ci / nexus (pull_request) Has been cancelled
ci / images (pull_request) Has been cancelled
to 60f0e5d4c7
Some checks failed
ci / images (pull_request) Has been cancelled
ci / nexus (pull_request) Has been cancelled
2026-09-21 17:58:34 +02:00
Compare
lz force-pushed refactor/collapse-declarations from 60f0e5d4c7
Some checks failed
ci / images (pull_request) Has been cancelled
ci / nexus (pull_request) Has been cancelled
to c83cd97ec1
All checks were successful
ci / nexus (pull_request) Successful in 8m12s
ci / images (pull_request) Successful in 38m38s
pr-image-cleanup / delete-pr-images (pull_request) Successful in 25s
2026-09-21 18:14:02 +02:00
Compare
lz merged commit 2b8e12f5eb into main 2026-09-21 19:10:01 +02:00
lz deleted branch refactor/collapse-declarations 2026-09-21 19:10:02 +02:00
Sign in to join this conversation.
No reviewers
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!180
No description provided.