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

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

3. Pattern changes (code-level)

3.1 Use-case files — input + output schemas + runtime parse

(populated when use cases are migrated)

3.2 Controller files — presenter + unknown input + view return type

(populated when controllers are migrated)

3.3 tRPC integration — feature-scoped procedures, schema reuse from use cases

(populated when routers are migrated)

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

(populated as features adopt the subpath)

5.2 Feature root index.ts cleanup

(populated as features clean up their root exports)

6. Test additions

6.1 R25 — output-validation tests (use case)

(populated when use cases gain malformed-input "repo lied" tests)

6.2 R26 — router error-mapping tests

(populated when feature routers gain TRPCError-translation tests)

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