agentic-dev/docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md

Refactor Changelog — Input/Output Unification + Presenter + Error Middleware + Public-Surface Cleanup

Started: 2026-05-06 Spec: 2026-05-06-input-output-unification-design.md Plan: 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.

---

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)

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

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.

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<typeof presenter>. 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<typeof presenter>. 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<typeof presenter> | undefined (preserves missing-page semantics). getSiteSettings has identity presenter; return type is ReturnType<typeof presenter>. Both 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()).

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.

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.

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).

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).

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

(populated as encountered)

---

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.

• CLAUDE.md — Key Conventions: append schema-in-use-case rule, presenter rule, controller unknown input rule, ./ui subpath rule, schema-export-from-root rule
• AGENTS.md (root) — Per-Package Conventions: document ./ui subpath, schema reachability from feature root, factory-bound use cases / controllers (carry-over from Plan 8)
• 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)
• 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)
• docs/guides/testing-strategy.md — Mocking section: direct factory injection (Plan 8); R25/R26/R27/R28 test obligations (Plan 9)
• docs/architecture/vertical-feature-spec.md — §6 file shape: schemas + presenter + procedures.ts; §10 testing: R25/R26/R27/R28
• docs/architecture/overview.md — data-flow box: add input schema, output schema, presenter, error-middleware lanes
• docs/architecture/dependency-flow.md — verify (no expected change beyond a ./ui mention)
• docs/decisions/adr-012-lazar-conformance.md — append note that input/output unification + presenter + error middleware land in ADR-013
• docs/decisions/adr-013-input-output-unification.md — created in this plan's final task (Task 9); link from prior ADRs
• Per-feature AGENTS.md (auth/blog/media/marketing-pages/navigation) — Plan 8 file paths + Plan 9 schema/presenter/procedures patterns
• packages/core-testing/AGENTS.md — note R25/R26 test patterns
• packages/core-shared/AGENTS.md — document defineErrorMiddleware and the t re-export
• 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<typeof xInputSchema>); schema lives in same file
Use case returns Promise<Entity>	Use case returns Promise<XOutput> validated by xOutputSchema.parse(...)
Controller imports z and defines local inputSchema	Controller imports xInputSchema from the use-case file
Controller input typed Partial<z.infer<...>>	Controller input typed unknown
Controller returns Promise<Entity>	Controller has function presenter(value: XOutput); returns Promise<ReturnType<typeof presenter>> (or Promise<void> 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