boocode/docs/research/cross-app-contract-ssot.md

Research: Long-term fix for BooCode's hand-synced cross-app type contracts

How to eliminate the duplicated, hand-synced TypeScript wire contracts shared across apps/server ↔ apps/web ↔ apps/coder (a single source of truth), and which approach to choose. Evidence mode: strict (default — sourced claims only; the recommendation rests on corroborated or codebase evidence, never reasoning alone).

Summary

The textbook fix is real and well-understood: put each shared type in one place that all three apps import, instead of keeping two or three hand-copied versions in sync. The strongest version of that is a small shared package (e.g. @boocode/contracts) where each contract is defined once — and for the contracts that are already validation schemas, define the schema once and derive the type from it so the validator and the type literally cannot disagree. This is the mainstream industry pattern and it is technically possible here: the project already does exactly this between two of its apps (apps/coder imports a built @boocode/server package).

But "do it now" did not survive scrutiny. The team already looked at this and deliberately chose not to build the shared package at its current (solo/small) scale, judging it "not worth the Docker/build-order risk," and that decision is the most recent word on the matter. The web app — the hardest consumer — has never imported a workspace package, so the path is unproven for it specifically. And the real duplication is messier than a clean "move five types" job: there is a live, undetected mismatch in one contract today, a whole extra copy of types in a second web app nobody counted, and a Zod-version tension lurking. So the honest answer is staged, not a single big-bang migration.

Recommended: do the cheap, high-value cleanup now (close the actual drift gaps — including the one that's already broken — and extend the existing guard-rails); treat the full shared-package unification as a deliberate, de-risked investment gated behind a small proof-of-concept, not a foregone conclusion. Whether to spend that larger effort now is a judgment call about your scale that only you can make.

• Confidence: Medium

Research Results

The end-state the industry converges on is a shared package, ideally schema-first. Across independent sources, the portable way to share types across a pnpm monorepo that mixes a Node app (NodeNext resolution) and a browser app (Vite/Bundler resolution) is a workspace package whose package.json exports map points at compiled dist/ with a types condition listed before default (A11, A12, A14, A15). For contracts that are also runtime validators, the schema-first pattern — define a Zod schema once and derive the static type via z.infer — makes type/validator drift structurally impossible, because the type and the validator are the same definition; z.discriminatedUnion infers a correct narrowing union, which is exactly the shape of a WS-frame contract (A18, A19). This is the dominant production pattern (T3/tRPC-style packages/contracts) (A19).

This is technically feasible in BooCode — the "blocker" is narrower than it looks. The codebase already proves the built-package path: apps/coder consumes a compiled @boocode/server via workspace:*, and apps/server ships a package.json exports map with types+default conditions per subpath (including ./ws-frames) (A3). The TS6307 error cited in the code as "structurally blocking" cross-import (A5) applies to importing another app's raw source file — not a properly built node_modules package. And contrary to a claim in the codebase inventory, moduleResolution: "Bundler" (what apps/web uses) does honor exports maps and the types condition per the TypeScript primary docs (A11) — so a built @boocode/contracts is, in principle, consumable by all three apps.

But the codebase — the authoritative record of current intent — pushes back on doing it now. The most recent explicit decision (CHANGELOG, v2.5.12) records that a shared package was "considered and declined (drift is already prevented; not worth the Docker/build-order risk at solo scale)" (A2). The prior design note (DEFERRED-WORK.md §3) recommended the lightweight options (Zod-inferred, or a parity test) "unless planning a broader shared-types initiative," with full packages/types "justified when a third consumer appears or WS frame duplication becomes painful" (A1). Critically, that "third consumer" trigger is not cleanly met: each duplicated contract still has exactly two hand-synced consumers — apps/coder already consumes the server's frames as a built package, not as a third hand-copy [validation V1].

The real duplication surface is wider and messier than a clean five-type list. Codebase evidence found, beyond the six enumerated contracts: a live, uncaught drift — AgentSessionConfig is model?/modeId?/thinkingOptionId? (all optional) on the coder side but model: string; modeId: string | null; … (required/nullable) on the web side, and it is not in the parity test's coverage (A7) [validation V3, confirmed]; a fourth duplication site, apps/coder/web/src/api/types.ts, a fallback SPA with its own WsFrame/Message/ToolCall copies and no parity guard (A8) [V4, confirmed]; and the web's hand-written WsFrame union in types.ts is already partially superseded by the Zod-inferred type and is missing at least one frame type (session_renamed) (A10) [V6]. The web app has also never consumed a workspace package (apps/web/package.json has no @boocode/* dependency), so the build-tooling path is unproven for the hardest consumer (A9) [V2].

If unification is deferred, the lightweight guard-rails have documented prior art. A structural type-parity test (expectTypeOf().toEqualTypeOf() / Expect<Equal<>>, run under vitest --typecheck) catches add/remove/rename drift between two copies with no new toolchain (A20) — this is the same family as the project's existing parity tests, and the natural way to close the AgentSessionConfig-style gaps. Generated-copy approaches (OpenAPI/Orval/Zod codegen) exist but trade the duplication for a schema artifact and a codegen pipeline (A23).

One source conflict worth flagging: Zod v4's browser bundle size is reported inconsistently — ~5.36 KB gzipped (official) vs ~14 KB (independent), likely core-only vs realistic-usage measurement (A21, single-source on each figure). It does not bear on the recommendation (server/web already pin Zod v3.23.8), but a contracts package shipping Zod schemas to the browser would make this a real number to measure, and would add a third Zod-version-sync site against the latent v3→v4 pressure from the claude-agent-sdk (A21) [V8].

Options to Consider

O1: Shared compiled workspace package — @boocode/contracts (full unification)

• What it is: A new packages/contracts package built like @boocode/server (declaration:true, exports map with types+default per subpath). All three apps depend on it via workspace:*. Zod-backed contracts (ws-frames, provider-config) live there as the single schema (z.infer for types); plain-type contracts move there as plain TS. Hand-synced copies and parity tests are deleted.
• Trade-offs: Eliminates drift by construction — the strongest guarantee. Costs: a new workspace package + inverted build order (contracts must build before server/web/coder; today the root script builds web→server) and a Docker-build change; an unproven web-consumer path (composite + noEmit + Bundler reading a built .d.ts via exports has no in-repo precedent); a third Zod-version-pin site; and it does not, by itself, address the apps/coder/web SPA copy or the web types.ts-vs-ws-frames.ts dual WsFrame representation. Explicitly declined at v2.5.12 for solo-scale cost.
• Rests on: (A1, A2, A3, A4, A11, A18, A19) corroborated; web-consumer feasibility (A11) is primary-source but unexercised here.
• Evidence status: corroborated as an end-state; "proven for web" is refuted as currently unproven (V2).

O2: Schema-first SSOT for the Zod-backed contracts only (partial unification)

• What it is: A narrower O1 — share only the already-Zod contracts (the WS-frame schema, the provider-config schema) as single Zod definitions in a small shared package; leave the plain-type contracts under parity tests. Targets the highest-pain, lowest-friction subset (ws-frames is already byte-identical-maintained Zod in two files).
• Trade-offs: Captures most of the drift-elimination value (the WS frames are the most painful duplicate) while touching fewer types and deferring the plain-type migration. Still needs the shared-package build wiring and the web-consumer proof; still leaves plain-type contracts duplicated (but guarded).
• Rests on: (A3, A6, A11, A18) corroborated; (A19) pattern.
• Evidence status: corroborated; the same unproven-web-path caveat applies (V2, V5).

O3: Extend the status quo — parity tests + the new coding standard (close the gaps)

• What it is: Keep hand-synced copies; (1) fix the live AgentSessionConfig drift, (2) add structural type-parity tests for the currently-unguarded contracts (AgentSessionConfig, MessageMetadata, WorktreeRiskReport, ProviderOverride/CoderProvidersFile, the interface WsFrame union), (3) decide the fate of the apps/coder/web SPA copy. Pairs with the cross-app-contract-parity coding standard already written.
• Trade-offs: Lowest cost and risk; matches the recorded v2.5.12 decision; closes real, demonstrated holes (including one already broken). Does not eliminate duplication — it makes drift loud rather than impossible, and the guard-rail is only as good as remembering to add new types to the names arrays (the exact gap that let AgentSessionConfig drift).
• Rests on: (A1, A2, A7, A20) corroborated; (A7) is a confirmed live defect.
• Evidence status: corroborated; matches the authoritative codebase decision.

O4: Codegen from a canonical schema (generated copies)

• What it is: A canonical schema (Zod source, or OpenAPI) generates the per-app type files; CI regenerates and git diff --exit-code fails on staleness.
• Trade-offs: Strong drift guarantee without a runtime shared import; but adds a schema artifact + codegen pipeline, and the guarantee degrades to "CI must run the generator." Heaviest setup for the least fit here — most BooCode contracts are not described by an OpenAPI spec, and the server is TypeScript (so a TS-source SSOT, i.e. O1/O2, dominates codegen).
• Rests on: (A23) corroborated as a pattern.
• Evidence status: corroborated, but weakly fit to this codebase.

Recommendation

• Recommendation: No single big-bang winner survives scrutiny — take the staged path. (1) Now, regardless of the larger decision (O3): close the demonstrated gaps — fix the live AgentSessionConfig mismatch and bring the unguarded contracts under parity coverage (or the new cross-app-contract-parity standard), and explicitly decide whether apps/coder/web is retired or guarded. This is low-risk, matches the recorded decision, and fixes something that is already broken. (2) The long-term unification you asked for (O2 → O1) is the right end-state but is a deliberate investment, not a proven drop-in. Gate it behind a tracer-bullet proof-of-concept: stand up a minimal @boocode/contracts, wire it into apps/web first (the unproven consumer), migrate only the ws-frames Zod schema, and verify that tsc, Vite dev (HMR), and vite build all resolve the built .d.ts/.js through the exports map. If green → proceed to migrate the rest and delete the copies/tests (O1). If it hits the composite/noEmit/Vite-resolution wall → fall back to the extended O3. Preconditions for O1/O2: pin Zod in contracts to the workspace version, invert the build order (contracts first) and update the Docker build, resolve the web types.ts-vs-ws-frames.ts dual WsFrame representation, and handle apps/coder/web.

• Evidence basis: The end-state (shared package, schema-first for Zod contracts) rests on corroborated web evidence (TypeScript primary docs A11; multiple independent monorepo/Zod sources A12–A19) plus codebase precedent (@boocode/server consumed by apps/coder, A3). The decision not to treat full unification as proven/justified-now rests on codebase evidence, which is authoritative on current state: the explicit v2.5.12 decline (A2), the unmet "third consumer" trigger (A1, V1), the absent web workspace-package precedent (A9, V2), and the live AgentSessionConfig drift (A7, V3 — confirmed by direct inspection). The immediate O3 action rests on the confirmed defect (A7) and the recorded decision (A1, A2). No part of the recommendation rests on reasoning alone. The one judgment that is genuinely yours: whether the WS-frame byte-sync pain is now "painful enough" to spend the O1/O2 investment despite the solo-scale cost the team previously weighed — the evidence frames that trade-off but cannot settle it for you.

Validation

V1: Is the "third consumer" deferral trigger met?

• Strategy: Challenge the Evidence
• Investigation: Read DEFERRED-WORK.md §3 trigger and enumerated actual consumers; apps/coder consumes @boocode/server (built package), not a third hand-copy.
• Result: Refuted (trigger not met — still two hand-synced consumers per contract).
• Impact: Removed "the trigger is now met" from the rationale; the case for O1 now rests on WS-frame pain judged on its own merit, not a satisfied precondition.

V2: Is the built-package path proven for the web consumer?

• Strategy: Challenge the Evidence
• Investigation: apps/web/package.json has no @boocode/* dependency; no @boocode import anywhere in apps/web/src. Coder→server (NodeNext) is proven; web (Bundler + composite + noEmit) is not.
• Result: Partially Refuted (NodeNext path proven; web path unproven).
• Impact: Reframed O1/O2 as gated behind a tracer-bullet probe; removed the "proven for web too" claim.

V3: Is the parity-test safety net complete?

• Strategy: Challenge the Evidence
• Investigation: AgentSessionConfig differs between coder (all optional) and web (required/nullable) and is absent from the parity test names array — directly verified.
• Result: Confirmed (a live, uncaught drift exists today).
• Impact: Promoted "fix this now" into the recommendation's immediate action; weakens the "drift is already prevented" basis of the v2.5.12 decision.

V4: Is the duplication scope fully enumerated?

• Strategy: Challenge the Evidence
• Investigation: apps/coder/web/src/api/types.ts (12 exported types, no parity test) is a fourth duplication site not in the inventory.
• Result: Confirmed (uncounted site).
• Impact: Added "decide the fate of apps/coder/web" as an explicit scope item / precondition.

V5: Does the web tsconfig flag combo break package consumption?

• Strategy: Challenge the Fix
• Investigation: composite:true+noEmit:true+allowImportingTsExtensions:true+Bundler reading a dist/*.d.ts via exports is feasible but unexercised; Vite must resolve the JS at runtime, not just tsc the types.
• Result: Partially Refuted (feasible, under-specified).
• Impact: Made the probe verify tsc + Vite dev + vite build explicitly; added build-order/Docker preconditions.

V6: Is the interface WsFrame union a simple plain-type move?

• Strategy: Challenge the Assumptions
• Investigation: Web types.ts WsFrame is missing session_renamed and is already partially superseded by the Zod-inferred type from ws-frames.ts.
• Result: Confirmed (more complex than a move).
• Impact: Added "resolve the web dual-WsFrame representation" as an O1 precondition.

V7: Is the prior decision stale, or authoritative?

• Strategy: Challenge the Evidence-Gathering Integrity
• Investigation: CHANGELOG v2.5.12 explicitly declined a shared package — more recent than DEFERRED-WORK.md and consistent with it (option C was chosen).
• Result: Partially Refuted (the "pending decision awaiting triggers" framing was wrong; it was an explicit rejection).
• Impact: Recommendation now states O1 needs new justification over a recorded "declined," not just "triggers met."

V8: Any hidden version/coupling cost?

• Strategy: Challenge the Fix
• Investigation: Server/web pin Zod ^3.23.8; claude-agent-sdk exerts latent v4 pressure; a contracts package adds a third Zod-version-sync site.
• Result: Confirmed (manageable, underspecified).
• Impact: Added "pin Zod in contracts to the workspace version" as a precondition.

Adjustments Made

The original recommendation ("build @boocode/contracts now; the path is proven") did not survive and was rewritten into the staged / no-single-winner form above: an evidence-backed immediate action (O3 gap-closing, including the confirmed AgentSessionConfig defect) plus full unification (O2→O1) reframed as a deliberate, probe-gated investment with explicit preconditions.

Confidence Assessment

• Confidence: Medium
• Remaining Risks: The web build-tooling path (composite + noEmit + Bundler consuming a built workspace package) is unproven in-repo — a failed probe is the main scope risk. The "is WS-frame pain worth the investment now" decision is a solo-scale judgment the evidence cannot settle. Web bundle-size of shipping Zod schemas to the browser is unmeasured (A21 conflict). Scope is wider than first enumerated (coder/web SPA, dual WsFrame, latent Zod v4) — discovery may not be complete (the AgentSessionConfig miss is evidence the inventory can lag reality).

Sources

ID	Source	Link / location	Retrieved	Trust class	Summary (one line)	Evidence status
A1	DEFERRED-WORK §3 — prior options A/B/C	docs/DEFERRED-WORK.md:160-225	n/a	codebase	Weighed Zod-inferred / shared packages/types / parity test; "A or C unless broader initiative; full package when 3rd consumer or WS pain"	recommendation-bearing
A2	CHANGELOG v2.5.12 decline note	CHANGELOG.md (~:99)	n/a	codebase	Shared package "considered and declined… not worth the Docker/build-order risk at solo scale"	recommendation-bearing
A3	@boocode/server built-package precedent	apps/server/package.json (exports), apps/coder/package.json (workspace:*), apps/coder/src/index.ts:19	n/a	codebase	Coder consumes a compiled server package via exports map + NodeNext; build server first	recommendation-bearing
A4	Web build constraints	apps/web/tsconfig.app.json	n/a	codebase	composite:true, moduleResolution:"Bundler", noEmit:true, allowImportingTsExtensions:true, include:["src"]	recommendation-bearing
A5	TS6307 cross-import block (raw source)	apps/coder/src/services/__tests__/provider-types-parity.test.ts:11-19	n/a	codebase	Web-side import of coder's source file blocked by TS6307 on the composite project	corroborated by A11
A6	WS-frame Zod byte-identical pair	apps/server/src/types/ws-frames.ts ↔ apps/web/src/api/ws-frames.ts (test …/ws-frames.test.ts)	n/a	codebase	The most-painful duplicate; already Zod; byte-parity test	single source (codebase)
A7	Live AgentSessionConfig drift	apps/coder/src/services/provider-types.ts:56 vs apps/web/src/api/types.ts:310; absent from parity names	n/a	codebase	Optional (coder) vs required/nullable (web), uncaught	recommendation-bearing
A8	Uncounted 4th duplication site	apps/coder/web/src/api/types.ts	n/a	codebase	Fallback SPA, 12 exported types incl. own WsFrame/Message, no parity test	single source (codebase)
A9	Web has no workspace-package dep	apps/web/package.json	n/a	codebase	No @boocode/* dependency — built-package consumption unexercised for web	recommendation-bearing
A10	Web dual WsFrame representation	apps/web/src/api/types.ts:560-622 vs ws-frames.ts	n/a	codebase	Interface union partially superseded by the Zod type; missing session_renamed	single source (codebase)
A11	TypeScript Modules Reference	https://www.typescriptlang.org/docs/handbook/modules/reference.html	2026-06-02	web	bundler AND node16/nodenext honor exports+types condition; node10/classic don't	recommendation-bearing (primary)
A12	Live Types in a TS Monorepo (C. McDonnell)	https://colinhacks.com/essays/live-types-typescript-monorepo	2026-06-02	web	Five sharing strategies; custom export conditions for source-pointing dev	corroborated by A11, A14
A13	TypeScript Project References (docs)	https://www.typescriptlang.org/docs/handbook/project-references.html	2026-06-02	web	composite/declaration/declarationMap; tsc -b build ordering	corroborated by A14
A14	Minimal TS monorepo lib (manzt gist)	https://gist.github.com/manzt/222c8e8f4ed35e74514eb756e4ba09bc	2026-06-02	web	publishConfig flip; source-pointing exports; nodenext authoring	corroborated by A12, A15
A15	Sharing types React/NestJS pnpm (lico)	https://dev.to/lico/step-by-step-guide-sharing-types-and-values-between-react-esm-and-nestjs-cjs-in-a-pnpm-monorepo-2o2j	2026-06-02	web	Dual ESM/CJS exports map; verbatimModuleSyntax needs import type	corroborated by A11
A16	TS6307 issue / tsup repro	https://github.com/microsoft/TypeScript/issues/27887 ; https://github.com/egoist/tsup/issues/1364	2026-06-02	web	TS6307 on composite transitive re-exports; surfaces via bundler tools too	corroborated by A5
A17	Vite TS Monorepo RFC / vite-tsconfig-paths	https://github.com/vitejs/vite-ts-monorepo-rfc ; https://www.npmjs.com/package/vite-tsconfig-paths	2026-06-02	web	Vite source-consumption gap; paths-alias workaround for HMR	single-source on the RFC stats
A18	Zod v4 — z.infer / z.discriminatedUnion	https://zod.dev/v4 ; https://zod.dev/api	2026-06-02	web	One schema yields a narrowing discriminated-union type; validator+type can't drift	recommendation-bearing
A19	Shared-Zod monorepo pattern (T3/tRPC)	https://calmops.com/programming/web/type-safe-fullstack-trpc-zod-monorepo/ ; https://www.ruthvikdev.com/blog/3-shared-zod-schemas	2026-06-02	web	packages/contracts Zod shared by server+client; version-pin caveat	corroborated
A20	Structural type-parity testing	https://vitest.dev/guide/testing-types ; https://www.totaltypescript.com/how-to-test-your-types	2026-06-02	web	expectTypeOf().toEqualTypeOf() / Expect<Equal<>> catches drift in CI, no new tooling	recommendation-bearing
A21	Zod v4 size/perf + alternatives	https://zod.dev/v4 ; https://pockit.tools/blog/zod-valibot-arktype-comparison-2026/ ; https://www.pkgpulse.com/blog/zod-vs-typebox-2026	2026-06-02	web	Zod v4 ~5.36 KB (official) vs ~14 KB (independent); Valibot smaller, ArkType faster	single-source per figure; conflict flagged
A22	Standard Schema	https://standardschema.dev/schema	2026-06-02	web	Common interface across Zod/Valibot/ArkType; reduces library lock-in	corroborated by A21
A23	OpenAPI/Zod codegen (generated copies)	https://openapi-ts.dev/ ; https://www.npmjs.com/package/ts-to-zod	2026-06-02	web	Generate type/validator copies from one source; guarantee = CI must regenerate	corroborated

A1: DEFERRED-WORK §3 — prior options and recommendation — recommendation-bearing

• Link / location: docs/DEFERRED-WORK.md:160-225
• Retrieved: n/a (codebase)
• Trust class: codebase (trusted current-state anchor)
• Summary: The project's own prior analysis of this exact question. Lays out option A (Zod + inferred types), B (shared packages/types), C (status-quo parity test), with a trade-off table, and recommends "Start with A or C unless planning a broader shared-types initiative. Full packages/types is justified when a third consumer appears or WS frame duplication becomes painful again."
• Evidence status: authoritative on intent; corroborated by A2.

A2: CHANGELOG v2.5.12 decline note — recommendation-bearing

• Link / location: CHANGELOG.md (~line 99, v2.5.12 provider-lifecycle entry)
• Retrieved: n/a (codebase)
• Trust class: codebase
• Summary: The most recent explicit decision: "a shared package was considered and declined (drift is already prevented; not worth the Docker/build-order risk at solo scale)." Records that option C was chosen.
• Evidence status: authoritative; the "drift is already prevented" premise is weakened by A7.

A3: @boocode/server built-package precedent — recommendation-bearing

• Link / location: apps/server/package.json (exports map with types+default per subpath, incl. ./ws-frames), apps/coder/package.json ("@boocode/server": "workspace:*"), apps/coder/src/index.ts:19
• Retrieved: n/a (codebase)
• Trust class: codebase
• Summary: Demonstrates the exact built-package mechanism a @boocode/contracts would use, working today for a NodeNext consumer (coder). apps/server has declaration:true; build order is server-first.
• Evidence status: proves the NodeNext path; does not prove the Bundler/web path (A9, V2).

A4: Web build constraints — recommendation-bearing

• Link / location: apps/web/tsconfig.app.json
• Retrieved: n/a (codebase)
• Trust class: codebase
• Summary: composite:true, moduleResolution:"Bundler", noEmit:true, allowImportingTsExtensions:true, include:["src"]. These permit consuming a built node_modules package (Bundler honors exports, A11) but the combination is unexercised against a workspace package here.
• Evidence status: feasibility is primary-source (A11) but unexercised (V2, V5).

A7: Live AgentSessionConfig drift — recommendation-bearing

• Link / location: apps/coder/src/services/provider-types.ts:56-61 vs apps/web/src/api/types.ts:310-315; not in apps/coder/src/services/__tests__/provider-types-parity.test.ts names
• Retrieved: n/a (codebase)
• Trust class: codebase
• Summary: Coder: model?/modeId?/thinkingOptionId? (optional). Web: model: string; modeId: string | null; thinkingOptionId: string | null (required/nullable). Structurally incompatible and uncaught by any parity test — a live defect.
• Evidence status: confirmed by direct inspection (V3); the concrete immediate action.

A11: TypeScript Modules Reference — recommendation-bearing (primary)

• Link / location: https://www.typescriptlang.org/docs/handbook/modules/reference.html
• Retrieved: 2026-06-02
• Trust class: web (primary source — TypeScript team)
• Summary: moduleResolution: bundler and node16/nodenext both resolve package.json exports and match the types condition; node10/classic ignore exports. This is why a built @boocode/contracts is consumable by the Vite (Bundler) web app — and corrects the codebase-inventory claim that "Bundler ignores exports."
• Evidence status: primary source; corroborated by A12, A14.

A18: Zod v4 — z.infer / z.discriminatedUnion — recommendation-bearing

• Link / location: https://zod.dev/v4 ; https://zod.dev/api
• Retrieved: 2026-06-02
• Trust class: web
• Summary: z.infer<typeof Schema> over a z.discriminatedUnion yields a correct narrowing TypeScript discriminated union; the validator and the static type are one definition, so they cannot drift. This is the schema-first SSOT mechanism for the WS-frame and provider-config contracts (which are already Zod).
• Evidence status: corroborated by A19; directly applicable since A6 shows ws-frames is already Zod.

A20: Structural type-parity testing — recommendation-bearing

• Link / location: https://vitest.dev/guide/testing-types ; https://www.totaltypescript.com/how-to-test-your-types
• Retrieved: 2026-06-02
• Trust class: web
• Summary: expectTypeOf().toEqualTypeOf() / Expect<Equal<A,B>> under vitest --typecheck asserts structural identity (not just assignability) between two copies and fails CI on drift, with no new tooling beyond what the repo already runs. The natural mechanism for O3's gap-closing (e.g. guarding AgentSessionConfig).
• Evidence status: corroborated (Vitest docs + Total TypeScript).