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

OpenSpec Change: enterprise-validation

• Change ID: enterprise-validation
• Package: @suaveplan/validation
• Category: universal
• Target path: packages/universal/validation
• Status: IN PROGRESS
• Date: 2026-04-18
• Reference spec: /mnt/s/web/suaveplan/enterprise/validation.md

Summary

Greenfield implementation of @suaveplan/validation for the genesis branch. The existing main-branch validation package provides the baseline public-API surface to preserve; this change delivers a runtime schema-validation library with a Zod-compatible API surface, exhaustive schema types (string, number, boolean, date, array, object, union, intersection, literal, enum, nullable, optional, record, tuple, coerce), async refinements, hooks, structured errors, property-based tests, and benchmarks. The library is entirely self-contained — it does NOT depend on Zod; it is its own parser, used alongside Zod at the monorepo level for other packages.

Current-state audit (genesis)

The package does not exist on genesis yet — this is a fresh build.

Available workspace deps on genesis

Package	Available
@suaveplan/error	✅
@suaveplan/types	✅
@suaveplan/events	✅
@suaveplan/opentelemetry	❌ not yet built — use @opentelemetry/api directly
@suaveplan/feature-flags	❌ not yet built — skip
@suaveplan/schema-registry	❌ not yet built — skip

External deps (via catalog):

• @opentelemetry/api → catalog:observability
• tslib → catalog:build

Dev deps (via catalog):

• vitest, @vitest/coverage-istanbul → catalog:testing
• fast-check → catalog:testing
• mitata → catalog:testing

Preserved public API surface (from main branch)

Core

• BaseSchema<TInput, TOutput> — abstract base class with .parse(input), .safeParse(input), .parseAsync(input), .safeParseAsync(input), .refine(fn, msg?), .transform(fn), .optional(), .nullable(), .describe(description)

Types

• AnySchema, SchemaInput<S>, SchemaOutput<S> — utility type extractors
• Infer<S>, InferInput<S> — schema type inference helpers
• ParseResult<T> — ParseSuccess<T> | ParseFailure
• ParseSuccess<T> — { success: true; data: T }
• ParseFailure — { success: false; error: ValidationError }
• ParseContext — internal traversal context
• ValidationIssue — { code: ValidationCode; path: (string | number)[]; message: string; input?: unknown }
• ValidationCode — string union of all built-in issue codes
• FlattenedErrors — { formErrors: string[]; fieldErrors: Record<string, string[]> }
• RefineFn<T>, AsyncRefineFn<T>, TransformFn<T, U>, CustomRule<T>
• StringRuleOptions, NumberRuleOptions, ObjectShape

Errors

• ValidationError extends SuaveplanError — .flatten(), .issues getter, .format()
• ValidationErrorOptions — constructor options
• FlattenedErrors — return type of .flatten()

Schema factories

• string() → StringSchema — .min(n), .max(n), .length(n), .regex(r), .email(), .url(), .uuid(), .startsWith(s), .endsWith(s), .includes(s), .trim(), .toLowerCase(), .toUpperCase()
• number() → NumberSchema — .min(n), .max(n), .int(), .positive(), .negative(), .multipleOf(n), .finite()
• boolean() → BooleanSchema
• date() → DateSchema — .min(d), .max(d)
• array(schema) → ArraySchema — .min(n), .max(n), .length(n), .nonempty()
• object(shape) → ObjectSchema — .strict(), .passthrough(), .strip(), .pick(keys), .omit(keys), .partial(), .required(), .extend(shape), .merge(other)
• union(schemas) → UnionSchema
• intersection(a, b) → IntersectionSchema
• literal(value) → LiteralSchema
• enumeration(values) → EnumSchema
• nullable(schema) → NullableSchema
• optional(schema) → OptionalSchema
• record(schema) → RecordSchema
• tuple(schemas) → TupleSchema

Coerce utilities

• coerce(schema) → CoercedSchema — wraps any schema with string→type coercion
• coerceString(input) → string
• coerceNumber(input) → number
• coerceBoolean(input) → boolean
• coerceDate(input) → Date
• CoercedSchema<T> (type)

Compose utilities

• mergeResults(results) — merges multiple ParseResult arrays into one
• pipe(schema, ...transforms) — sequential schema pipeline

Hook types

• ValidationHookMap — lifecycle hooks: beforeValidate, afterValidate, onError
• ValidationHookData<T> — data passed to each hook
• ValidationValidatingHandler — handler signature

New additions for genesis

Structured errors

• ValidationError extends SuaveplanError with codes under VALIDATION.* namespace
• Codes: VALIDATION.STRING.*, VALIDATION.NUMBER.*, VALIDATION.ARRAY.*, VALIDATION.OBJECT.*, VALIDATION.UNION.NO_MATCH, VALIDATION.CUSTOM.REFINEMENT

OTel instrumentation

• Counters: validation.parse.success, validation.parse.failure
• Histogram: validation.parse.duration_ms (per schema type label)

Property-based tests (fast-check)

• Round-trip: schema.parse(schema.parse(x)) === schema.parse(x) (idempotency)
• Error propagation: any invalid input to .parse() always returns ParseFailure (never throws)
• Union exhaustiveness: input matching none of the union arms always fails

Benchmarks (mitata)

• object(shape).parse(data) for 10-field object — 100k iterations
• array(string()).parse(arr) for 1 000-element array
• union with 10 arms — best-case and worst-case branch

Impact

• Adds one new package: packages/universal/validation
• Adds one new spec capability: validation
• No existing package consumers on genesis yet