---
phase: 01-foundation
plan: "03"
subsystem: schema
tags: [typescript, zod, validation, registry, tdd, vitest]

# Dependency graph
requires:
  - 01-02 (BACKEND_REGISTRY, BackendType, FieldDef — src/schemas/registry.ts)
provides:
  - BACKEND_SCHEMAS constant with Zod schemas for azureblob, s3, s3-compatible (src/schemas/index.ts)
  - BackendFormValues<T> utility type inferring TypeScript type from schema
affects:
  - Phase 3 (form validation — useForm resolver will use BACKEND_SCHEMAS[backendType])
  - Phase 2 (type-safe form data via BackendFormValues before config generation)

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Programmatic schema derivation: loop over BACKEND_REGISTRY to build z.object() — never hardcode field names in Zod schemas"
    - "Registry-as-truth invariant: adding a field to BACKEND_REGISTRY automatically adds it to runtime validation"

key-files:
  created:
    - src/schemas/index.ts
  modified: []

key-decisions:
  - "buildZodSchema loops over BACKEND_REGISTRY[backendType] — field names never appear in Zod code, only in the registry"
  - "required: true fields map to z.string().min(1) with label-based error message; optional fields map to z.string().optional()"
  - "BACKEND_SCHEMAS exported as const object — TypeScript can narrow to the specific backend's schema type at call sites"

patterns-established:
  - "Schema-from-registry pattern: all Zod shape derivation goes through buildZodSchema(backendType)"

requirements-completed: []

# Metrics
duration: 1min
completed: 2026-03-26
---

# Phase 01 Plan 03: Zod Schema Builder Summary

**Programmatic Zod schema builder that derives all validation from BACKEND_REGISTRY — adding a registry field automatically adds it to runtime validation, with no hardcoded field names in Zod code**

## Performance

- **Duration:** ~1 min
- **Started:** 2026-03-26T09:20:32Z
- **Completed:** 2026-03-26T09:21:21Z
- **Tasks:** 1
- **Files modified:** 1

## Accomplishments

- `buildZodSchema(backendType)` derives a `z.object()` shape entirely from `BACKEND_REGISTRY[backendType]` — no field names appear in `index.ts` itself
- Required fields become `z.string().min(1, '{label} is required')`, optional fields become `z.string().optional()`
- `BACKEND_SCHEMAS` exported as a const with typed entries for all three backends
- `BackendFormValues<T>` utility type infers the TypeScript type from the appropriate schema via `z.infer`
- All 8 tests in `index.test.ts` pass GREEN; `registry.test.ts` (7 tests) remains GREEN — full 15-test count

## Task Commits

Each task was committed atomically:

1. **Task 1: Implement schema builder and BACKEND_SCHEMAS** - `eaeae32` (feat)

**Plan metadata:** _(committed after SUMMARY.md — see final commit)_

_Note: TDD — RED confirmed ("Cannot find module './index'"), then GREEN in single implementation commit._

## Files Created/Modified

- `src/schemas/index.ts` — buildZodSchema function, BACKEND_SCHEMAS constant, BackendFormValues type

## Decisions Made

- Used `z.string().min(1, ...)` for required fields rather than plain `z.string()` — provides a user-facing error message that includes the field label, useful when this schema is wired to react-hook-form in Phase 3
- `as const` on BACKEND_SCHEMAS enables TypeScript to narrow the exact schema type per backend key (no `ZodObject<any>` widening)

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None. The only full-suite "failure" (`reducer.test.ts`) is the intentional Wave 0 RED stub from Plan 02, documented there — not a regression.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- `src/schemas/index.ts` ready for Plan 04 context and Phase 3 form wiring
- `BACKEND_SCHEMAS[backendType]` can be passed directly to `zodResolver()` from `@hookform/resolvers/zod`
- `BackendFormValues<T>` provides the type-safe form data shape for Phase 2 config generation
- Only remaining RED stub: `src/store/reducer.test.ts` — addressed in Plan 04

---
*Phase: 01-foundation*
*Completed: 2026-03-26*