work-hub-server/openspec/changes/archive/2026-06-04-swap-superstruct-valibot/proposal.md

Why

The schema package currently duplicates validation logic: Superstruct schemas mirror Drizzle table definitions by hand. This is error-prone (they can drift) and requires maintaining a separate validation/ and types/ module. Drizzle provides first-class Valibot integration (drizzle-orm/valibot) that derives insert/update/select schemas directly from table definitions, eliminating duplication entirely. Valibot is also tree-shakeable, which benefits the web app's bundle.

What Changes

• BREAKING: Replace Superstruct with Valibot across @workspace/schema
• Remove packages/schema/src/validation/ module (hand-written Superstruct schemas)
• Remove packages/schema/src/types/ module (manual type re-exports no longer needed)
• Add Valibot-derived schemas via createInsertSchema and createUpdateSchema from drizzle-orm/valibot
• Add valibot dependency; remove superstruct dependency
• Update main barrel export in src/index.ts
• Validation schemas for enum fields (status, priority) will use picklist() refinements derived from the existing constant arrays in drizzle/enums.ts

Capabilities

New Capabilities

None — this is a modification of existing capabilities.

Modified Capabilities

• validation: Hand-written Superstruct schemas → auto-derived Valibot schemas from Drizzle tables
• shared-types: Manually maintained Infer types → inferred automatically from Valibot schemas via v.InferOutput

Impact

• packages/schema/package.json — replace superstruct with valibot in dependencies
• packages/schema/src/validation/ — entire directory removed
• packages/schema/src/types/ — entire directory removed
• packages/schema/src/index.ts — exports change to drizzle tables + valibot schemas only
• apps/api and apps/web import from @workspace/schema — no import path changes, but consumers may need to adapt to new API if they used Superstruct directly