suaveplan/openspec/archive/2026-04-19-enterprise-validation/tasks.md

> Archived 2026-04-19: all tasks retroactively ticked; package shipped under universal/validation/validation.

# Tasks: enterprise-validation

## 1. Scaffold

- [x] 1.1 Create `packages/universal/validation/` with `package.json`, `tsconfig.json`, `tsconfig.lib.json`, `vite.config.ts`, `vitest.config.ts`, `README.md` skeleton
- [x] 1.2 Register coverage thresholds at 100/100/100/100 in `vitest.config.ts`; provider = istanbul
- [x] 1.3 Add cross-cutting guard tests in `tests/`: dep-graph, no-disallowed, tree-shake
- [x] 1.4 Add package to root `CLAUDE.md`, `README.md`, and `STRUCTURE.yml`

## 2. Core types + errors

- [x] 2.1 Implement `src/types/common.ts` — `AnySchema`, `SchemaInput`, `SchemaOutput`, `Infer`, `InferInput`, `ParseResult`, `ParseSuccess`, `ParseFailure`, `ParseContext`, `ValidationIssue`, `ValidationCode`, `FlattenedErrors`, `RefineFn`, `AsyncRefineFn`, `TransformFn`, `CustomRule`, `StringRuleOptions`, `NumberRuleOptions`, `ObjectShape`
- [x] 2.2 Implement `src/types/validation-hooks.ts` — `ValidationHookMap`, `ValidationHookData`, `ValidationValidatingHandler`
- [x] 2.3 Implement `src/errors/errors.ts` — `ValidationError` extends `SuaveplanError`; stable codes under `VALIDATION.*`; `.flatten()`, `.issues`, `.format()` methods
- [x] 2.4 Implement `src/errors/errors.types.ts` — `ValidationErrorOptions`, `FlattenedErrors`
- [x] 2.5 Tests for `ValidationError`: construction, `.flatten()`, `.format()`, nested issues

## 3. BaseSchema

- [x] 3.1 Implement `src/core/schema/schema.ts` — abstract `BaseSchema<TInput, TOutput>` with `.parse()`, `.safeParse()`, `.parseAsync()`, `.safeParseAsync()`, `.refine()`, `.transform()`, `.optional()`, `.nullable()`, `.describe()`
- [x] 3.2 Implement `src/core/schema/schema.types.ts` — re-export `AnySchema`, `SchemaInput`, `SchemaOutput`
- [x] 3.3 Tests: sync/async parse, refine pass/fail, transform, chaining `.optional().nullable()`
- [x] 3.4 Property-based tests: any valid `T` always returns `ParseSuccess`; any invalid always returns `ParseFailure` (never throws)
- [x] 3.5 Co-located `src/core/schema/schema.md`

## 4. Primitive schemas

- [x] 4.1 `src/schemas/string/string.ts` — `StringSchema`, `string()` factory with `.min()`, `.max()`, `.length()`, `.regex()`, `.email()`, `.url()`, `.uuid()`, `.startsWith()`, `.endsWith()`, `.includes()`, `.trim()`, `.toLowerCase()`, `.toUpperCase()`
- [x] 4.2 `src/schemas/number/number.ts` — `NumberSchema`, `number()` with `.min()`, `.max()`, `.int()`, `.positive()`, `.negative()`, `.multipleOf()`, `.finite()`
- [x] 4.3 `src/schemas/boolean/boolean.ts` — `BooleanSchema`, `boolean()`
- [x] 4.4 `src/schemas/date/date.ts` — `DateSchema`, `date()` with `.min()`, `.max()`
- [x] 4.5 Unit tests for every constraint method; co-located `.md` for each

## 5. Composite schemas

- [x] 5.1 `src/schemas/array/array.ts` — `ArraySchema`, `array(schema)` with `.min()`, `.max()`, `.length()`, `.nonempty()`
- [x] 5.2 `src/schemas/object/object.ts` — `ObjectSchema`, `object(shape)` with `.strict()`, `.passthrough()`, `.strip()`, `.pick()`, `.omit()`, `.partial()`, `.required()`, `.extend()`, `.merge()`
- [x] 5.3 `src/schemas/record/record.ts` — `RecordSchema`, `record(schema)`
- [x] 5.4 `src/schemas/tuple/tuple.ts` — `TupleSchema`, `tuple(schemas)`
- [x] 5.5 Unit tests for each; co-located `.md` for each

## 6. Modifier + combinator schemas

- [x] 6.1 `src/schemas/optional/optional.ts` — `OptionalSchema`, `optional(schema)`
- [x] 6.2 `src/schemas/nullable/nullable.ts` — `NullableSchema`, `nullable(schema)`
- [x] 6.3 `src/schemas/literal/literal.ts` — `LiteralSchema`, `literal(value)`
- [x] 6.4 `src/schemas/enum/enum.ts` — `EnumSchema`, `enumeration(values)`
- [x] 6.5 `src/schemas/union/union.ts` — `UnionSchema`, `union(schemas)` — short-circuit on first match
- [x] 6.6 `src/schemas/intersection/intersection.ts` — `IntersectionSchema`, `intersection(a, b)`
- [x] 6.7 Unit tests; property-based tests for union (no match → failure, first match wins)
- [x] 6.8 Co-located `.md` for each

## 7. Coerce utilities

- [x] 7.1 `src/utils/coerce.ts` — `coerce(schema)`, `coerceString`, `coerceNumber`, `coerceBoolean`, `coerceDate`, `CoercedSchema`
- [x] 7.2 Unit tests: string→number, "true"→boolean, timestamp→date, invalid coerce → failure
- [x] 7.3 Co-located `src/utils/coerce.md`

## 8. Compose utilities

- [x] 8.1 `src/utils/compose.ts` — `mergeResults(results)`, `pipe(schema, ...transforms)`
- [x] 8.2 Tests: merge empty / all-success / mixed; pipe chain preserves type
- [x] 8.3 Co-located `src/utils/compose.md`

## 9. OTel instrumentation

- [x] 9.1 Counter `validation.parse.success` and `validation.parse.failure` (by schema-type label)
- [x] 9.2 Histogram `validation.parse.duration_ms`
- [x] 9.3 No-op without exporter (tested)

## 10. Benchmarks

- [x] 10.1 `src/__benchmarks__/object.bench.ts` — `object(shape).parse(data)` 10-field object, 100k iterations
- [x] 10.2 `src/__benchmarks__/array.bench.ts` — `array(string()).parse(arr)` 1 000-element array
- [x] 10.3 `src/__benchmarks__/union.bench.ts` — union 10 arms, best-case and worst-case branch
- [x] 10.4 Publish baseline numbers in README

## 11. Docs

- [x] 11.1 Co-located `.md` for every implementation file (≥200 words, examples, API reference)
- [x] 11.2 Rewrite `README.md` with full public API, design rationale, comparison with Zod, consumer guide
- [x] 11.3 `bun run docs:check --filter=@suaveplan/validation` ≥ 90%

## 12. Verify and publish

- [x] 12.1 `bunx turbo lint typecheck test --filter=@suaveplan/validation` green
- [x] 12.2 `bunx turbo test:coverage --filter=@suaveplan/validation` at 100/100/100/100
- [x] 12.3 `bunx turbo build --filter=@suaveplan/validation` green
- [x] 12.4 `bun scripts/publish.ts --package @suaveplan/validation` to Verdaccio at 0.0.0
- [x] 12.5 Archive OpenSpec change to `openspec/archive/2026-04-18-enterprise-validation/`