feat(errors): StandardSchemaV1 runtime validation + message-as-function (RFC 0001)

[martyy-code]

Implements RFC 0001. Closes #32. The new API promotes the existing StandardSchemaV1 type to runtime validation and replaces the implicit message template with an explicit function form. The legacy template path keeps working in 1.x and emits a single deprecation warning per call site (silence with DEESSEJS_ERRORS_LEGACY_TEMPLATES=1).

Before / After

Defining an error

const ValidationError = error<{ field: string; reason: string }>({
  name: "ValidationError",
  message: "Field "{field}" is invalid: {reason}",
});

const err = ValidationError({ field: 42, reason: "not a string" });
// err.fields.field is typed string but actually 42. No runtime check.
// err.message is the unrendered template.

const ValidationError = error({
  name: "ValidationError",
  fields: z.object({
    field: z.string(),
    reason: z.string(),
  }),
  message: (data) => `Field "${data.field}" is invalid: ${data.reason}`,
});

const err = ValidationError({ field: 42, reason: "not a string" });
// Throws ArgsValidationError (vendor: "zod") before the message function runs.

Handling the failure

try {
  raise(ValidationError({ field: "" as string }));
} catch (err) {
  // err is a plain Error. No vendor info. No issues. The unrendered
  // template is the only signal that something went wrong.
  if (err instanceof Error) {
    console.log(err.message);
  }
}

try {
  raise(ValidationError({ field: "" }));
} catch (err) {
  if (err instanceof ArgsValidationError) {
    console.log(err.vendor); // "zod" or "valibot" or "arktype"
    console.log(err.issues); // raw validator failure
    console.log(err.source); // factory name
  }
}

What landed

• Runtime validation: error() now calls ~standard-schema/validate at instantiation when fields is provided. Invalid inputs throw ArgsValidationError carrying the validator's issues and vendor.
• Message-as-function: when fields is supplied, message must be a function (data) => string receiving the parsed (post-transform) data. The legacy string template still works and is deprecated.
• ArgsValidationError: new exported class with source, vendor, issues. Re-exported from src/index.ts so consumers can instanceof-check.
• ErrorFactory.schema removed (decision A from the RFC). The duplication between fields and schema is gone.
• Test matrix: zod 4, valibot 1, @ark/type 2. CI runs the standard test-run against Node 20, 22, 24.

API surface

• error(config): name required, fields optional StandardSchemaV1, message optional string | (data) => string, inherits optional.
• ArgsValidationError(name, issues, vendor): constructor signature.
• is(err, factory): type guard unchanged.
• raise(err): unchanged.
• causes(err): unchanged.
• StandardSchemaV1: re-exported from @standard-schema/spec.

Test coverage (137 tests across 13 files)

• tests/error.test.ts, tests/from.test.ts, tests/is.test.ts, tests/raise.test.ts, tests/causes.test.ts: existing unit tests, all pass.
• tests/standard-schema.test.ts: legacy and standard mode with mock schema.
• tests/types/error-type.test.ts: expectTypeOf against zod, valibot, arktype. Verifies inference of z.coerce.number(), z.brand, instance core shape, addNote/from chainability, ArgsValidationError contract.
• tests/edge-cases.test.ts: async validators, throwing validators, non-conformant issues, circular values, call count, legacy template, deprecation gate.
• tests/snapshots/exports.test.ts: public API surface locked (5 runtime exports: ArgsValidationError, causes, error, is, raise).
• tests/integration/{zod,valibot,arktype}/vendor.test.ts: cross-vendor parity.
• tests/integration/contract-parity.test.ts: it.each across the three vendors on ~standard conformance.
• tests/perf/instantiate.bench.ts: vitest bench for no-fields, schema-validated, and legacy forms. Excluded from test:run via vitest.config.ts; run with pnpm exec vitest bench.

Documentation

• apps/web/content/docs/{message-templates,fields-schema,error-factory,api-reference}.mdx: updated to the new API. Valibot and ArkType examples corrected (the previous versions imported from non-existent paths).
• README.md: refreshed to match the shared template; npm page now reflects the new description and SEO fields.
• apps/web/content/docs/recipes.mdx: still uses the older generic form; left for a follow-up PR to keep this one focused.

Design doc in this PR

• docs/internal/engineering/rfcs/0001-standard-schema-fields.md: full design doc with Q1-Q4 decisions. The "Decisions locked by review" section replaces the "Open questions" section.

Issues opened for follow-up

• [BUG] release: workflow reports success on no-op when no changeset in merge #55: workflow no-op silent when no changeset in merge.
• [Refactor]: release: detect manual version bumps as a publish trigger #56: detect manual version bumps as a publish trigger.
• [Chore]: docs(release): add recovery playbook for missing-changeset merges #57: recovery playbook for missing-changeset merges.

CI matrix

Both tests.yml and types.yml run against Node 20, 22, 24 with fail-fast: false. Verified locally:

• pnpm test:run: 137 passed
• type-check: clean
• build: clean
• apps/web build: 55 static pages generated

All four CI jobs are green on the latest commit.

Out of scope

• Codemod migration (decision F in the RFC): no users yet, manual search-and-replace is fine for now.
• ErrorGroup typed error union (issue [FEATURE] Add typed ErrorGroup with split() and exhaustive match() #33): depends on this RFC landing; will be a follow-up PR.
• Doc updates for recipes.mdx, index.mdx: queued as a follow-up.

Checklist

• RFC 0001 reviewed, Q1-Q4 decisions locked
• StandardSchemaV1 inference from zod, valibot, arktype
• Message-as-function receives parsed data
• ArgsValidationError with vendor + issues
• Type tests locked with expectTypeOf
• Cross-vendor integration tests in tests/integration/<vendor>/
• CI matrix Node 20, 22, 24
• Documentation aligned to new API
• Legacy path deprecated with one-shot console.warn

Co-Authored-By: Claude Fable 5 noreply@anthropic.com