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)

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

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.

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.

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.

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

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.

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.

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

6.3 R27/R28 — presenter shape tests

(populated when controllers with non-identity presenters add view-shape assertions)

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