# Refactor Changelog — Input/Output Unification + Presenter + Error Middleware + Public-Surface Cleanup **Started:** 2026-05-06 **Spec:** [2026-05-06-input-output-unification-design.md](../specs/2026-05-06-input-output-unification-design.md) **Plan:** [2026-05-06-plan-9-io-unification.md](../plans/2026-05-06-plan-9-io-unification.md) **Branch:** feature/io-unification This document captures every architectural change made during Plan 9 execution, organized by category. After the plan is merged, use the "Doc update checklist" at the bottom to update external docs in a single follow-up pass — combined with the still-pending Plan 8 doc-update items so docs are written once for the post-Plan-9 state. --- ## Summary **Completed:** 2026-05-06 **Branch:** main (or feature/io-unification per execution choice) **Total commits:** 15 (Tasks 1–9, including the R6 fix-up + auth code-review tightening + blog style sweep + 2× refactor-log catch-up commits) **Net test count change:** 325 → 360 (+35 tests, +11%) | Category | Count | |---|---| | Files added | 5 × procedures.ts + 5 × ui/index.ts + 1 × define-error-middleware{.ts,.test.ts} + 1 × ADR + 1 × changelog = 14 (approx; some ui/index.ts replace existing query.ts) | | Files modified | 12 use cases + 12 controllers + 5 routers + 5 src/index.ts + 5 package.json + 5 router tests + ~25 test files = ~70 | | New tRPC error codes mapped | 5 (BAD_REQUEST, NOT_FOUND, UNAUTHORIZED, FORBIDDEN, plus tRPC built-in BAD_REQUEST from zod) | ### Tasks completed | Task | Commit | Description | |---|---|---| | 1 | `61baaae` | Refactor changelog scaffold | | 2 | `e25b1f7`, `aac37fd` | core-shared defineErrorMiddleware + t export + jsdoc fix | | 3 | `2bbec70`, `5b61674`, `70c7b7d` | auth migration + changelog §6.3 + test tightening | | 4 | `86070b2`, `614c901` | blog migration + style dividers | | 5 | `f4adf31` | marketing-pages migration | | R6 | `9663c82`, `aff0ce0` | this.name in all error classes + changelog §7 | | 6 | `27c79e6` | navigation migration | | 7 | `2b67964` | media migration | | 8 | `2df137c` | final verification + app caller stragglers + changelog | | 9 | (this commit) | ADR-013 + changelog summary | ### Conformance verification (Task 8) Spec acceptance criteria §8: all met. - Every use case exports xInputSchema; non-void use cases also export xOutputSchema. - Every non-void controller has a top-level presenter and uses ReturnType. - Every feature has procedures.ts with feature-scoped error map. - core-shared/trpc/define-error-middleware.ts is the only plumbing in core-shared; no central name→code registry. - Per-feature package.json has ./ui subpath; root index.ts no longer exports query builders. - R25 (output-validation) test exists per non-void use case. - R26 (router error-mapping) test exists per feature. - pnpm typecheck && pnpm lint && pnpm test && pnpm turbo boundaries && pnpm build all green. --- ## 1. Files added - packages/core-shared/src/trpc/define-error-middleware.ts — middleware factory mapping [ErrorCtor, TRPC_CODE] tuples to TRPCError translation - packages/core-shared/src/trpc/define-error-middleware.test.ts — 4 tests covering mapped translation, multiple codes, unmapped passthrough (verifies INTERNAL_SERVER_ERROR + cause preservation), cause preservation - packages/auth/src/integrations/api/procedures.ts — authProcedure with feature error map (InputParse → BAD_REQUEST, Auth/Unauthenticated → UNAUTHORIZED, Unauthorized → FORBIDDEN) - packages/auth/src/ui/index.ts — placeholder UI surface (no queries today; mutations only) - packages/blog/src/integrations/api/procedures.ts — blogProcedure with feature error map (InputParseError → BAD_REQUEST, ArticleNotFoundError → NOT_FOUND) - packages/blog/src/ui/index.ts — re-exports articleBySlugQuery and listArticlesQuery from ./query (moved from feature root index) - packages/marketing-pages/src/integrations/api/procedures.ts — marketingPagesProcedure with feature error map (InputParseError → BAD_REQUEST, PageNotFoundError → NOT_FOUND) - packages/marketing-pages/src/ui/index.ts — re-exports pageBySlugQuery and siteSettingsQuery from ./query (moved from feature root index) - packages/navigation/src/integrations/api/procedures.ts — navigationProcedure with feature error map (InputParseError → BAD_REQUEST, HeaderNotFoundError → NOT_FOUND) - packages/navigation/src/ui/index.ts — re-exports headerQuery from ./query (moved from feature root index) - packages/media/src/integrations/api/procedures.ts — mediaProcedure with feature error map (InputParseError → BAD_REQUEST, MediaNotFoundError → NOT_FOUND) - packages/media/src/ui/index.ts — placeholder UI surface (no queries today; media has no React Query option builders) - packages/media/src/integrations/api/router.test.ts — R26 router error-mapping tests ## 2. Files modified - packages/core-shared/src/trpc/init.ts — `t` instance now exported (was internal const) so feature procedures.ts can do `t.procedure.use(...)` - packages/core-shared/package.json — added "./trpc/define-error-middleware" subpath export - packages/core-shared/tsconfig.json — set `rootDir: "."` and added `@/*` path alias so test files using `@/` resolve correctly under `tsc --noEmit` - packages/auth/src/application/use-cases/sign-in.use-case.ts — input + output schemas; output.parse before return; SignInInput/SignInOutput types exported - packages/auth/src/application/use-cases/sign-up.use-case.ts — input + output schemas (with confirmPassword refine); output.parse; types exported; removed user from output (presenter extracts cookie) - packages/auth/src/application/use-cases/sign-out.use-case.ts — input schema only (void output, no presenter); SignOutInput exported; takes { sessionId } object instead of raw string - packages/auth/src/interface-adapters/controllers/sign-in.controller.ts — presenter returning cookie; unknown input; ReturnType return type - packages/auth/src/interface-adapters/controllers/sign-up.controller.ts — presenter returning cookie; unknown input - packages/auth/src/interface-adapters/controllers/sign-out.controller.ts — no presenter (void); unknown input; Promise return - packages/auth/src/integrations/api/router.ts — uses authProcedure, .input(xInputSchema) - packages/auth/src/index.ts — schemas + types now exported from feature root - packages/auth/package.json — added ./ui subpath - packages/auth/tests/sign-in-flow.feature.test.ts — updated to match new presenter shapes (cookie return, void sign-out, object input) - All affected auth use-case + controller tests updated for new contracts - packages/blog/src/application/use-cases/get-articles.use-case.ts — getArticlesInputSchema + getArticlesOutputSchema; status narrowed to articleStatusSchema; output.parse; types exported - packages/blog/src/application/use-cases/create-article.use-case.ts — createArticleInputSchema + createArticleOutputSchema; output.parse; types exported - packages/blog/src/application/use-cases/get-article-by-slug.use-case.ts — getArticleBySlugInputSchema + getArticleBySlugOutputSchema; output.parse; types exported - packages/blog/src/interface-adapters/controllers/get-articles.controller.ts — identity presenter; unknown input; imports getArticlesInputSchema from use-case - packages/blog/src/interface-adapters/controllers/create-article.controller.ts — identity presenter; unknown input; imports createArticleInputSchema from use-case - packages/blog/src/interface-adapters/controllers/get-article-by-slug.controller.ts — identity presenter; unknown input; imports getArticleBySlugInputSchema from use-case - packages/blog/src/integrations/api/router.ts — uses blogProcedure + .input(xInputSchema) for all 3 procedures - packages/blog/src/index.ts — removed articleBySlugQuery/listArticlesQuery re-exports; added schemas + types + IUseCase/IController aliases - packages/blog/package.json — added ./ui subpath export - All affected blog use-case + controller tests updated for new contracts - packages/marketing-pages/src/application/use-cases/get-page-by-slug.use-case.ts — getPageBySlugInputSchema + getPageBySlugOutputSchema; output.parse (returns undefined for missing page per existing behavior); types exported - packages/marketing-pages/src/application/use-cases/get-site-settings.use-case.ts — getSiteSettingsInputSchema (z.object({}).strict() per R5) + getSiteSettingsOutputSchema; output.parse; types exported; _input parameter (void input) - packages/marketing-pages/src/interface-adapters/controllers/get-page-by-slug.controller.ts — identity presenter; unknown input; returns undefined for missing page - packages/marketing-pages/src/interface-adapters/controllers/get-site-settings.controller.ts — identity presenter; unknown input; imports getSiteSettingsInputSchema from use-case - packages/marketing-pages/src/integrations/api/router.ts — uses marketingPagesProcedure + .input(xInputSchema) for both procedures; siteSettings now uses .input(getSiteSettingsInputSchema) - packages/marketing-pages/src/index.ts — removed pageBySlugQuery/siteSettingsQuery re-exports; added schemas + types + IUseCase/IController aliases - packages/marketing-pages/package.json — added ./ui subpath export - All affected marketing-pages use-case + controller tests updated for new contracts - packages/navigation/src/application/use-cases/get-header.use-case.ts — getHeaderInputSchema (z.object({}).strict()) + getHeaderOutputSchema (= headerSchema); _input parameter; output.parse; types exported - packages/navigation/src/interface-adapters/controllers/get-header.controller.ts — identity presenter; unknown input; imports getHeaderInputSchema from use-case; ReturnType return type - packages/navigation/src/integrations/api/router.ts — uses navigationProcedure + .input(getHeaderInputSchema); ctrl called with input - packages/navigation/src/index.ts — removed headerQuery re-export (moved to ./ui); exports getHeaderInputSchema, getHeaderOutputSchema, GetHeaderInput, GetHeaderOutput, IGetHeaderUseCase, IGetHeaderController; added HeaderNotFoundError + InputParseError re-exports - packages/navigation/package.json — added ./ui subpath export - packages/navigation/src/integrations/api/router.test.ts — updated to call caller.header({}); added R26 describe block; uses beforeEach/afterEach to rebind container - packages/media/src/application/use-cases/get-media.use-case.ts — getMediaInputSchema + getMediaOutputSchema (= mediaSchema); output.parse; types exported - packages/media/src/application/use-cases/list-media.use-case.ts — listMediaInputSchema (limit/offset strict object) + listMediaOutputSchema (z.array(mediaSchema)); output.parse; types exported - packages/media/src/application/use-cases/delete-media.use-case.ts — deleteMediaInputSchema (void output — no xOutputSchema); types exported; input now typed DeleteMediaInput - packages/media/src/interface-adapters/controllers/get-media.controller.ts — identity presenter; unknown input; imports getMediaInputSchema from use-case - packages/media/src/interface-adapters/controllers/list-media.controller.ts — identity presenter; unknown input; imports listMediaInputSchema from use-case - packages/media/src/interface-adapters/controllers/delete-media.controller.ts — no presenter (void); unknown input; imports deleteMediaInputSchema from use-case - packages/media/src/integrations/api/router.ts — uses mediaProcedure + .input(xInputSchema) for all 3 procedures; no more publicProcedure or local schema redefinitions - packages/media/src/index.ts — exports schemas (getMediaInputSchema/Output, listMediaInputSchema/Output, deleteMediaInputSchema) + types + IUseCase/IController aliases - packages/media/package.json — added ./ui subpath export ## 3. Pattern changes (code-level) ### 3.1 Use-case files — input + output schemas + runtime parse auth migrated: all 3 use cases. signIn and signUp export xInputSchema + xOutputSchema + types; signOut exports xInputSchema only (void output). All non-void use cases end with `xOutputSchema.parse(result)` before returning. blog migrated: all 3 use cases. getArticles, createArticle, getArticleBySlug each export xInputSchema + xOutputSchema + XInput + XOutput types. getArticlesInputSchema narrows status to articleStatusSchema (not loose string). All 3 end with `xOutputSchema.parse(result)` before returning. marketing-pages migrated: both use cases. getPageBySlug exports getPageBySlugInputSchema + getPageBySlugOutputSchema + types; returns undefined for missing page (preserving existing semantics) — parse only called when page found. getSiteSettings exports getSiteSettingsInputSchema (z.object({}).strict() — void input per R5) + getSiteSettingsOutputSchema + types; takes `_input: GetSiteSettingsInput` to satisfy uniform input contract. navigation migrated: single use case (getHeader). Exports getHeaderInputSchema (z.object({}).strict() — void input per R5) + getHeaderOutputSchema (= headerSchema) + types; takes `_input: GetHeaderInput`; throws HeaderNotFoundError when repository returns falsy (existing behavior preserved); ends with `getHeaderOutputSchema.parse(header)`. media migrated: all 3 use cases. getMedia exports getMediaInputSchema + getMediaOutputSchema (= mediaSchema) + types; ends with getMediaOutputSchema.parse(media). listMedia exports listMediaInputSchema (strict object with optional int limit/offset) + listMediaOutputSchema (z.array(mediaSchema)) + types; ends with listMediaOutputSchema.parse(result). deleteMedia exports deleteMediaInputSchema only (void output per R12); no xOutputSchema. ### 3.2 Controller files — presenter + unknown input + view return type auth migrated: all 3 controllers. signIn/signUp have `function presenter(value: XOutput)` returning `value.cookie`; return type is `ReturnType`. signOut has no presenter (void). All controllers accept `unknown` input and safeparse with the use-case schema. blog migrated: all 3 controllers. All 3 (getArticles, createArticle, getArticleBySlug) have `function presenter(value: XOutput)` that is identity (`return value`); return type is `ReturnType`. All accept `unknown` input and safeparse with the imported use-case schema. marketing-pages migrated: both controllers. getPageBySlug has identity presenter; return type is `ReturnType | undefined` (preserves missing-page semantics). getSiteSettings has identity presenter; return type is `ReturnType`. Both accept `unknown` input and safeparse with the imported use-case schema. navigation migrated: single controller (getHeaderController). Identity presenter; return type `ReturnType`. Accepts `unknown` input and safeparses with getHeaderInputSchema imported from use-case file. media migrated: all 3 controllers. getMediaController and listMediaController have `function presenter(value: XOutput)` that is identity (`return value`); return type is `ReturnType`. deleteMediaController has no presenter (void return); return type is `Promise`. All 3 accept `unknown` input and safeparse with the imported use-case schema. ### 3.3 tRPC integration — feature-scoped procedures, schema reuse from use cases auth migrated: authProcedure in procedures.ts wraps defineErrorMiddleware with 4-tuple error map. Router uses `authProcedure.input(xInputSchema)` for all 3 procedures — no more local schema redefinition. blog migrated: blogProcedure in procedures.ts wraps defineErrorMiddleware with 2-tuple map (InputParseError → BAD_REQUEST, ArticleNotFoundError → NOT_FOUND). Router uses `blogProcedure.input(xInputSchema)` for all 3 procedures. marketing-pages migrated: marketingPagesProcedure in procedures.ts wraps defineErrorMiddleware with 2-tuple map (InputParseError → BAD_REQUEST, PageNotFoundError → NOT_FOUND). Router uses `marketingPagesProcedure.input(xInputSchema)` for both procedures. siteSettings now uses `.input(getSiteSettingsInputSchema)` (was a no-input `.query()`). navigation migrated: navigationProcedure in procedures.ts wraps defineErrorMiddleware with 2-tuple map (InputParseError → BAD_REQUEST, HeaderNotFoundError → NOT_FOUND). Router uses `navigationProcedure.input(getHeaderInputSchema)` (was a no-input `.query()` with publicProcedure). media migrated: mediaProcedure in procedures.ts wraps defineErrorMiddleware with 2-tuple map (InputParseError → BAD_REQUEST, MediaNotFoundError → NOT_FOUND). Router uses `mediaProcedure.input(xInputSchema)` for all 3 procedures — getMedia (query), listMedia (query), deleteMedia (mutation). ## 4. Error-middleware adoption - core-shared infrastructure landed; feature routers will adopt in Tasks 3-7. - Discriminator: `instanceof Ctor` (not error name string), so duck-typing is impossible — features pass their own class constructors. - Cause preservation: TRPCError carries the original domain error in `.cause` for client structured-error inspection. - Note on tRPC v11 behavior: unmapped errors still surface as `TRPCError(code: INTERNAL_SERVER_ERROR)` because tRPC's `createCaller` wraps all procedure errors. Our middleware does not interfere — the original error is preserved as `.cause` for inspection. ## 5. Public-API surface ### 5.1 ./ui subpath added per feature auth: `./ui` subpath added to package.json exports; `src/ui/index.ts` placeholder created (auth has no query builders — all procedures are mutations). blog: `./ui` subpath added to package.json exports; `src/ui/index.ts` created re-exporting articleBySlugQuery and listArticlesQuery from ./query. marketing-pages: `./ui` subpath added to package.json exports; `src/ui/index.ts` created re-exporting pageBySlugQuery and siteSettingsQuery from ./query. navigation: `./ui` subpath added to package.json exports; `src/ui/index.ts` created re-exporting headerQuery from ./query (moved from feature root index). media: `./ui` subpath added to package.json exports; `src/ui/index.ts` placeholder created (media has no query builders today — no existing UI to migrate). ### 5.2 Feature root index.ts cleanup auth: root `src/index.ts` now exports all use-case schemas (signInInputSchema, signInOutputSchema, signUpInputSchema, signUpOutputSchema, signOutInputSchema) and types (SignInInput/Output, SignUpInput/Output, SignOutInput, ISignInUseCase, ISignUpUseCase, ISignOutUseCase) plus controller type aliases. blog: root `src/index.ts` removed articleBySlugQuery/listArticlesQuery re-exports (moved to ./ui); now exports getArticlesInputSchema/Output, createArticleInputSchema/Output, getArticleBySlugInputSchema/Output, all XInput/XOutput types, IUseCase aliases, and IController aliases. marketing-pages: root `src/index.ts` removed pageBySlugQuery/siteSettingsQuery re-exports (moved to ./ui); now exports getPageBySlugInputSchema/Output, getSiteSettingsInputSchema/Output, all XInput/XOutput types, IUseCase aliases, and IController aliases. navigation: root `src/index.ts` removed headerQuery re-export (moved to ./ui); now exports getHeaderInputSchema, getHeaderOutputSchema, GetHeaderInput, GetHeaderOutput, IGetHeaderUseCase, IGetHeaderController; also exports HeaderNotFoundError and InputParseError. media: root `src/index.ts` kept existing Media type + MediaNotFoundError + InputParseError + MediaRouter re-exports; added getMediaInputSchema/Output, listMediaInputSchema/Output, deleteMediaInputSchema and all XInput/XOutput types; added IUseCase/IController type aliases. No query builders to remove (media had no UI exports). ## 6. Test additions ### 6.1 R25 — output-validation tests (use case) auth: signIn and signUp each have 2 new R25 tests — one verifying that a malformed service response throws (Zod parse error), one verifying the output schema parses a valid shape. signOut is void — no R25 test. blog: getArticles, createArticle, getArticleBySlug each have 2 new R25 tests — one verifying that a repository returning a malformed object throws ZodError (instanceof), one verifying the output schema parses a valid shape. marketing-pages: getPageBySlug has 1 R25 test verifying that a repository returning a malformed page object throws ZodError (instanceof). getSiteSettings has 1 R25 test using an inline malformed repository mock that returns `{ siteName: "" }` (fails min(1) constraint) to assert ZodError (instanceof). navigation: getHeader has 1 R25 test using an inline malformed repository mock that returns `{ items: [{ label: "", href: "/", external: false }] }` (label fails min(1) constraint) to assert ZodError (instanceof). media: getMedia has 2 R25 tests — one verifying getMediaOutputSchema parses a valid media object, one verifying that a repository returning a malformed object (missing filesize/filename/mimeType) throws ZodError (instanceof). listMedia has 2 R25 tests — same pattern using listMediaOutputSchema. deleteMedia is void — no R25 test. ### 6.2 R26 — router error-mapping tests auth: 2 new R26 tests in router.test.ts — UNAUTHORIZED on missing user (AuthenticationError translation), BAD_REQUEST on Zod schema failure (schema validation at procedure boundary). blog: 2 new R26 tests in router.test.ts — NOT_FOUND on articleBySlug with missing slug (ArticleNotFoundError translation via blogProcedure), BAD_REQUEST on articleBySlug with empty input ({} as { slug: string }) (schema validation at tRPC procedure boundary). marketing-pages: 2 new R26 tests in router.test.ts — BAD_REQUEST on pageBySlug with empty input ({} as { slug: string }) (schema validation at tRPC procedure boundary); undefined return for missing slug confirmed (use case returns undefined rather than throwing PageNotFoundError, so NOT_FOUND mapping does not apply for this use case). navigation: 2 new R26 tests in router.test.ts — BAD_REQUEST on header with extra fields (strict() z.object({}) rejects unknown keys via InputParseError); NOT_FOUND on header when a NullHeaderRepository (inline @injectable class) causes HeaderNotFoundError (container rebound inline for the test). media: 4 new R26 tests in router.test.ts — NOT_FOUND on getMedia with nonexistent id (MediaNotFoundError translation via mediaProcedure); BAD_REQUEST on getMedia with empty input ({} as { id: string }) (schema validation at tRPC procedure boundary); NOT_FOUND on deleteMedia with nonexistent id; NOT_FOUND via NullMediaRepository inline rebind confirming mediaProcedure error map applies. ### 6.3 R27/R28 — presenter shape tests - auth (Task 3): sign-in and sign-up controllers reshape `{ session, cookie }` → `cookie`. Controller tests assert cookie shape (`result.name`, `result.value`, etc.) — not the full use-case output — proving the presenter ran. Same assertions in `tests/sign-in-flow.feature.test.ts`. sign-out controller has no presenter (void return), so no view-shape test applies. ## 7. Open issues / deferred decisions - 2026-05-06 / R6 fix-up (commit `9663c82`): Plan 8 left every feature's domain error class with a constructor that did NOT set `this.name`. Plan 9 spec R6 explicitly requires it. Caught by spec reviewer during Task 6 (navigation). Fixed across all 10 error files (auth × 4, blog × 2, marketing-pages × 2, navigation × 2, media × 2). Functionally a no-op (defineErrorMiddleware uses `instanceof`), but ensures correct serialization, stack-trace labels, and JSON inspectability. ### Post-Plan-9: dev-seed binders (2026-05-06, commits `e6560bc`, `10479c4`, `68e934c`, `61dde18`, `6bf19f3`) User-driven addition. Symmetric to `bind-production.ts` — every feature now also exports `./di/bind-dev-seed` so the running app can be populated with realistic mock data (without Payload running). Per-feature additions: - `src/__seeds__/dev.ts` — lazy `buildDev()` function that uses the feature's existing factory for sensible defaults; only overrides the fields that make data look "real" (e.g. `slug: "welcome"`, `status: "published"`). - `src/di/bind-dev-seed.ts` — `bindDevSeed()` async function: unbinds the repo symbol (or symbols, for marketing-pages with two repos), constructs `MockXRepository`, awaits `createX(...)` per seed entity, rebinds via `.toConstantValue(repo)`. Idempotent. - `src/di/bind-dev-seed.test.ts` — 3 tests per feature (populated, reachable by id/slug, idempotent). - `package.json` — `./di/bind-dev-seed` subpath added to `exports`. App-level wiring (`apps/web-next/src/server/bind-production.ts`) gained: - `bindAllDevSeed()` — calls all 5 `bindDevSeed*()` binders. - `bindAll()` — dispatcher with three-rule resolution: 1. `USE_DEV_SEED === "true"` → dev seed (explicit override; works in any `NODE_ENV` — staging preview, design review). 2. `NODE_ENV === "production"` → real Payload via `bindAllProduction(config)`. 3. otherwise → dev seed (developer default; `pnpm dev` boots without Payload). - All page/route callers (page.tsx, about/page.tsx, blog/[slug]/page.tsx, api/trpc/[trpc]/route.ts) updated from `bindAllProduction` → `bindAll`. Tests: - `bind-production.test.ts` grew from 3 to 8 tests covering the dispatcher matrix (USE_DEV_SEED override, NODE_ENV branching, default). - Per-feature: 3 tests each × 5 features = +15 tests. - Total monorepo test count: 360 (Plan 9 final) → ~378. Turbo: `USE_DEV_SEED` declared in root `turbo.json`'s `globalEnv` so cache keys differentiate seed mode from production. Docs: - `CLAUDE.md` Key Conventions — new "Three binding modes per feature" entry. - `AGENTS.md` (root) — `exports` list + Per-feature public-API surface table + `bindAll()` dispatcher example. - `docs/architecture/vertical-feature-spec.md` §6 — file shape now includes `bind-dev-seed.ts` + `__seeds__/`. - `docs/architecture/data-flow-explainer.html` — anatomy tree gains `__seeds__/`; LAYERS.di + new LAYERS.seeds entries; public-surface card expanded to six subpaths; cross-link to the new di-explainer.html. - `docs/architecture/di-explainer.html` — NEW dedicated page covering the six files in `di/`, lifecycle, three binding kinds, three-mode picker, conditions table. ### Plan 9 final verification (Task 8, 2026-05-06) - pnpm typecheck / lint / test / turbo boundaries / build: all green after fixing 2 Plan 9 regressions in app callers (see stragglers below). - Total tests: 360 across 15 test suites. Net delta vs pre-Plan-9 baseline of 325 (post-Plan-8): +35 tests, +11% (Plan 9 added R25 output-validation + R26 router error-mapping + R27/R28 presenter shape tests across all 5 features). - Spec §8 acceptance criteria sweep: - All non-test use cases export xInputSchema. ✓ - Non-void use cases also export xOutputSchema (void exempt: sign-out, delete-media). ✓ - All non-void controllers have `function presenter`; void controllers (sign-out, delete-media) return Promise. ✓ - 5 procedures.ts files (one per feature). ✓ - 5 ./ui subpath entries in package.json. ✓ - All error classes set this.name (R6 satisfied after `9663c82`). ✓ - R26 router error-mapping tests pass for all 5 features (4–6 tests each). ✓ - Stragglers fixed in this task (Plan 9 regressions, NOT pre-existing): - `apps/web-tanstack/src/routes/index.tsx` — `queryOptions()` → `queryOptions({})` for siteSettings and header (both procedures now require `{}` input after Plan 9 added `.input(z.object({}).strict())`). - `apps/web-next/src/app/page.tsx` — `caller.marketingPages.siteSettings()` → `caller.marketingPages.siteSettings({})` and `caller.navigation.header()` → `caller.navigation.header({})` (same root cause). - Pre-existing items (NOT introduced by Plan 9): none. --- ## Doc update checklist (deferred — combined with paused Plan 8 doc pass) After Plan 9 lands, the still-pending Plan 8 doc-update items resume and now also pick up Plan 9 rules. Each item below covers BOTH plans' material so we touch every file once. - [x] `CLAUDE.md` — Key Conventions: append schema-in-use-case rule, presenter rule, controller `unknown` input rule, `./ui` subpath rule, schema-export-from-root rule - [x] `AGENTS.md` (root) — Per-Package Conventions: document `./ui` subpath, schema reachability from feature root, factory-bound use cases / controllers (carry-over from Plan 8) - [x] `docs/guides/adding-a-feature.md` — restructure to use the Plan-9 use-case template (with input + output schemas + parse), the Plan-9 controller template (with presenter), and the new `procedures.ts` step (per-feature error map) - [x] `docs/guides/tdd-workflow.md` — update mock decision tree + worked example to factory injection (Plan 8) + R25 output-validation test pattern (Plan 9) + R26 router-error-mapping test pattern (Plan 9) - [x] `docs/guides/testing-strategy.md` — Mocking section: direct factory injection (Plan 8); R25/R26/R27/R28 test obligations (Plan 9) - [x] `docs/architecture/vertical-feature-spec.md` — §6 file shape: schemas + presenter + procedures.ts; §10 testing: R25/R26/R27/R28 - [x] `docs/architecture/overview.md` — data-flow box: add input schema, output schema, presenter, error-middleware lanes - [x] `docs/architecture/dependency-flow.md` — verify (no expected change beyond a `./ui` mention) - [x] `docs/decisions/adr-012-lazar-conformance.md` — append note that input/output unification + presenter + error middleware land in ADR-013 - [x] `docs/decisions/adr-013-input-output-unification.md` — created in this plan's final task (Task 9); link from prior ADRs - [x] Per-feature `AGENTS.md` (auth/blog/media/marketing-pages/navigation) — Plan 8 file paths + Plan 9 schema/presenter/procedures patterns - [x] `packages/core-testing/AGENTS.md` — note R25/R26 test patterns - [x] `packages/core-shared/AGENTS.md` — document `defineErrorMiddleware` and the `t` re-export - [x] Plan 8 plan/spec — add a one-line annotation that some controller/router patterns shifted in Plan 9; link to this changelog --- ## Notes for the doc-update pass author When updating external docs, apply these substitutions globally: | Old reference | New reference | |---|---| | Use case takes `{ x }` directly typed | Use case takes `XInput` (`z.infer`); schema lives in same file | | Use case returns `Promise` | Use case returns `Promise` validated by `xOutputSchema.parse(...)` | | Controller imports `z` and defines local `inputSchema` | Controller imports `xInputSchema` from the use-case file | | Controller input typed `Partial>` | Controller input typed `unknown` | | Controller returns `Promise` | Controller has `function presenter(value: XOutput)`; returns `Promise>` (or `Promise` for void use cases) | | Router uses `publicProcedure` from `core-shared/trpc/init` | Router uses feature's `xProcedure` from `./procedures` | | Router redefines input schema as `z.object({...})` in `.input(...)` | Router uses `.input(xInputSchema)` imported from the use-case file | | Domain error reaches the wire as a generic `TRPCError({ code: "INTERNAL_SERVER_ERROR" })` | Domain error mapped to specific code by `defineErrorMiddleware` in `procedures.ts` | | Frontend imports `articleBySlugQuery` from `@repo/blog` | Frontend imports from `@repo/blog/ui` |