@ultimat3/schema 30.9.0 → 31.1.0

package/CLAUDE.md

@@ -11,13 +11,18 @@ Tier 0. **Imports no `@ultimat3/*` package — not even `@ultimat3/core`.**
 | **Issue messages** | the shape of the rejected value, **never its content** — see `describe-value.ts` |
 | **Issue paths** | framework-chosen segments only. A `t.object` segment is a DECLARED field name; a `t.record` KEY is the caller's, so `recordSchema` names a failing entry by POSITION (`meta[3]`) |
 | Coercion | HTTP boundary only — never call it from actions, jobs or MCP |
-| Exports | explicit in `src/index.ts`; no `export *`; a namespace member and its free function ship together (`t.nullable`/`nullableSchema`) |
+| Exports | explicit in `src/index.ts`; no `export *`; a composer ships once, as its `t` member — its free twin (`arraySchema`, `discriminatedUnionSchema`, `enumSchema`, `nullableSchema`, `optionalSchema`, `refineSchema`, `unionSchema`) stays internal; `jsonSchema`, `recordSchema`, `literalSchema`, `objectSchema` stay exported; provider accessors on `./adapter` (`src/adapter.ts`) |
 | Re-exports | `action`, `query`, `jobs`, `entity` re-export `t` verbatim so an authoring file imports one package — never let them wrap or copy it |
 
 Module order (no cycles):
 `char-count → describe-value → node → builder → money-value → json-value → array-schema →
 validators → record-schema → discriminated-union → provider → t` (`node-fits` and `json-schema` read
 `json-value` too). `record-schema.ts` (`t.record`) split from `validators.ts` at the ceiling.
+`issue-cap.ts` is a leaf (type-only `standard`) read by `builder`, `standard` and every collecting
+loop: **a loop that collects issues asks `stopCollecting(count, hasMore)` after each member**, and a
+union that discards member issues restores `issuesStopped()`. `standard.large.test.ts` pins 10k bad
+items → 100 issues, `issuesTruncated`, ≤ 100 item checks (a work count, never wall time). The cap is ambient module state because builtin
+validation is synchronous; `withIssueCap` is re-entrant and only the outermost run reports.
 `schema-rules.ts` is a leaf (`SCHEMA_RULES`, `issueRuleFacts`), imported by `standard.ts`,
 `errors.ts` (type only) and `builder.ts`. `sensitive.ts` reads `provider.ts` and is not in `t`'s graph.
 

package/README.md

@@ -13,9 +13,10 @@ type, a JSON Schema, an OpenAPI body, an MCP tool `inputSchema` and HTTP query c
 | the introspectable IR every generator walks | `node.ts` |
 | `Schema` factory, `Infer` machinery, `.refine()` | `builder.ts` |
 | how a rejected value is described — its shape, never its content | `describe-value.ts` |
-| `JsonValue`, `t.json()` / `jsonSchema()`, `JSON_MAX_DEPTH` | `json-value.ts` |
+| `JsonValue`, `t.json()` / `jsonSchema()`, the 256-level nesting cap | `json-value.ts` |
 | a union routed by one literal key | `discriminated-union.ts` |
 | `configureSchemaProvider()` — the swap point | `provider.ts` |
+| `@ultimat3/schema/adapter`, off the barrel: `builtinProvider`, `schemaProvider()` (the active one), `resetSchemaProvider()` — for a provider author and test teardown | `adapter.ts` |
 | schema → JSON Schema (OpenAPI + MCP) | `json-schema.ts` |
 | HTTP-boundary coercion, kept out of validation | `coerce.ts` |
 | `X_VALIDATION_FAILED` with path-annotated issues | `errors.ts` |
@@ -47,8 +48,11 @@ type PublishPost = Infer<typeof publishPost>;
 | `string` `number` `boolean` `date` `uuid` `email` `url` | `object` `array` `enum` `literal` `union` `discriminatedUnion` `record` `optional` `nullable` `refine` | `.default(v)` `.optional()` `.nullable()` `.describe(s)` `.sensitive()` `.refine(r)` |
 | `money` `timezone` `locale` `slug` `cursor` `json()` | `object(...).extend/.pick/.omit` | `string.min/.max/.pattern`, `number.min/.max/.int` |
 
-`nullable` is a value the row holds; `optional` is the caller omitting the key. Both ship as a
-namespace member (`t.nullable`) and a free function (`nullableSchema`) — symmetrically.
+`nullable` is a value the row holds; `optional` is the caller omitting the key. Every composer
+ships once, as a `t` member (`t.nullable`, `t.refine`, …); since v31 its free twin is internal —
+`arraySchema`, `discriminatedUnionSchema`, `enumSchema`, `nullableSchema`, `optionalSchema`,
+`refineSchema`, `unionSchema`. `jsonSchema`, `recordSchema`, `literalSchema` and `objectSchema` stay
+exported beside `t`.
 
 Unknown object keys are **dropped**, never forwarded — an action cannot be mass-assigned.
 
@@ -215,6 +219,13 @@ bound where it is narrower.
 `formatIssues()` renders one line per issue for the dev overlay. `validate()` never throws and
 returns the Standard Schema result. Async libraries: `parseAsync()` / `validateAsync()`.
 
+**A refusal is bounded.** Every door — `validate()`, `parse()`, `safeParse()`, `~standard.validate`
+— stops collecting at `MAX_ISSUES` (100): a builtin array, object, record or `t.json()` leaves the
+rest unchecked, and the result carries `issuesTruncated: true` (`ValidationFailedError.issuesTruncated`,
+and `meta.issuesTruncated`). A foreign library's list is cut to the cap. `validate(schema, value,
+{ maxIssues })` / `validateAsync(…, { maxIssues })` narrow or widen it; below 1 is
+`X_SCHEMA_ISSUE_CAP_INVALID`. A `SchemaError` cause is cut at 4 KiB, as core's is.
+
 This package is tier 0 and cannot import `@ultimat3/core`, so `SchemaError` reproduces
 `UltimateError` structurally and carries the same `Symbol.for('ultimate.error')` brand —
 `isUltimateError()` from core matches it. Register the codes once from any package that imports
@@ -230,8 +241,10 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `BoundsInvalidError` (extends `SchemaError`) | `X_SCHEMA_BOUNDS_INVALID` | `src/errors.ts` |
 | `DefaultInvalidError` (extends `SchemaError`) | `X_SCHEMA_DEFAULT_INVALID` | `src/errors.ts` |
 | `DiscriminantInvalidError` (extends `SchemaError`) | `X_SCHEMA_DISCRIMINANT_INVALID` | `src/errors.ts` |
-| `SchemaError` | any schema code; the base of the four that extend it. Extends `Error`, not core's `UltimateError` — schema imports nothing — and carries the same `Symbol.for('ultimate.error')` brand so `isUltimateError` answers `true` | `src/errors.ts` |
+| `IssueCapInvalidError` (extends `SchemaError`) | `X_SCHEMA_ISSUE_CAP_INVALID` | `src/errors.ts` |
+| `SchemaError` | any schema code; the base of every class that extends it. Extends `Error`, not core's `UltimateError` — schema imports nothing — and carries the same `Symbol.for('ultimate.error')` brand so `isUltimateError` answers `true` | `src/errors.ts` |
 | `SchemaUnsupportedError` (extends `SchemaError`) | `X_SCHEMA_UNSUPPORTED` | `src/errors.ts` |
+| `SensitiveOutputError` (extends `SchemaError`) | `X_SCHEMA_SENSITIVE_OUTPUT` | `src/errors.ts` |
 | `ValidationFailedError` (extends `SchemaError`) | `X_VALIDATION_FAILED` | `src/errors.ts` |
 
 ## Swapping the library

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/schema",
-  "version": "30.9.0",
+  "version": "31.1.0",
   "description": "Ultimate's validation seam: Standard Schema interface, the t namespace, JSON Schema output",
   "keywords": [
     "ultimate",
@@ -26,6 +26,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts",
     "./sample": "./src/sample.ts"
   },
   "files": [

package/src/adapter.ts

@@ -0,0 +1,5 @@
+// `@ultimat3/schema/adapter` — what a schema provider author reads: the built-in provider and the
+// active-provider accessor and reset. Never the `.` barrel: an app installs a provider with
+// `configureSchemaProvider()`, so the only callers here are a provider author and test teardown.
+
+export { builtinProvider, resetSchemaProvider, schemaProvider } from './provider';

package/src/array-schema.ts

@@ -14,6 +14,7 @@ import {
 } from './builder';
 import { describeValue, expected } from './describe-value';
 import { BoundsInvalidError } from './errors';
+import { stopCollecting } from './issue-cap';
 import type { SchemaNode } from './node';
 import type { InferInput, InferOutput, StandardIssue } from './standard';
 
@@ -84,7 +85,11 @@ export function arraySchema<S extends AnySchema>(
     for (const [index, member] of value.entries()) {
       const result = itemCheck(member, [...path, index]);
       if (result.ok) out.push(result.value);
-      else issues.push(...result.issues);
+      else {
+        issues.push(...result.issues);
+        // At the issue cap the rest is not read: 10k bad items cost a hundred checks, not 10k.
+        if (stopCollecting(issues.length, index < value.length - 1)) break;
+      }
     }
     if (issues.length > 0) return failWith(issues);
     return pass(out as InferOutput<S>[]);

package/src/builder.ts

@@ -8,6 +8,7 @@ import {
   ValidationFailedError,
   type ValidationIssue,
 } from './errors';
+import { cappedFailure, MAX_ISSUES, withIssueCap } from './issue-cap';
 import type { SchemaNode, SchemaRefinement } from './node';
 import { issueRuleFacts, type SchemaIssueParams, type SchemaRule } from './schema-rules';
 import {
@@ -230,8 +231,8 @@ function withoutDefault(node: SchemaNode): SchemaNode {
   return rest;
 }
 
-function toIssues(result: CheckErr): readonly ValidationIssue[] {
-  return result.issues.map((issue) => ({
+function toIssues(issues: readonly StandardIssue[]): readonly ValidationIssue[] {
+  return issues.map((issue) => ({
     path: formatPath(issue.path),
     expected: issue.message,
     received: '',
@@ -240,25 +241,37 @@ function toIssues(result: CheckErr): readonly ValidationIssue[] {
   }));
 }
 
+/**
+ * One whole validation: the check under the issue cap (`issue-cap.ts`), its failure held to it.
+ * Every door into a builtin schema goes through here, so none of them is unbounded — a nested
+ * call (a composite reading a member through `checkOf`) joins its caller's cap.
+ */
+function capped<Out>(check: Check<Out>, value: unknown): StandardResult<Out> {
+  const run = withIssueCap(MAX_ISSUES, () => check(value, []));
+  return run.value.ok
+    ? { value: run.value.value }
+    : cappedFailure(run.value.issues, run.cap, run.stopped);
+}
+
 export function makeSchema<In, Out>(node: SchemaNode, check: Check<Out>): Schema<In, Out> {
   const schema: Schema<In, Out> = {
     '~standard': {
       version: 1,
       vendor: VENDOR,
-      validate: (value: unknown): StandardResult<Out> => {
-        const result = check(value, []);
-        return result.ok ? { value: result.value } : { issues: result.issues };
-      },
+      validate: (value: unknown): StandardResult<Out> => capped(check, value),
     },
     node,
     parse(value: unknown, root = 'value'): Out {
-      const result = check(value, []);
-      if (result.ok) return result.value;
-      throw new ValidationFailedError(toIssues(result), root);
+      const result = capped(check, value);
+      if (result.issues === undefined) return result.value;
+      throw new ValidationFailedError(
+        toIssues(result.issues),
+        root,
+        result.issuesTruncated === true,
+      );
     },
     safeParse(value: unknown): StandardResult<Out> {
-      const result = check(value, []);
-      return result.ok ? { value: result.value } : { issues: result.issues };
+      return capped(check, value);
     },
     optional(): Schema<In | undefined, Out | undefined> {
       return makeSchema<In | undefined, Out | undefined>(

package/src/error-codes.ts

@@ -29,4 +29,5 @@ export const SCHEMA_ERROR_CODES: Readonly<Record<string, SchemaErrorCodeDeclarat
     X_SCHEMA_DEFAULT_INVALID: { title: 'a schema default fails its own schema' },
     X_SCHEMA_BOUNDS_INVALID: { title: 'an array bound no array can satisfy' },
     X_SCHEMA_SENSITIVE_OUTPUT: { title: 'a sensitive field is reachable from an output' },
+    X_SCHEMA_ISSUE_CAP_INVALID: { title: 'a validation issue cap no list can meet' },
   });

package/src/errors.ts

@@ -37,6 +37,22 @@ const singleLine = (text: string): string =>
     (char) => ESCAPES[char] ?? `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`,
   );
 
+/**
+ * The same cap `@ultimat3/core`'s `boundedCause` applies. **Keep in sync** — read the reason there;
+ * briefly: a cause describes a refusal and is copied into `message`, the log line and the problem
+ * `detail`, so a 10k-issue validation cause (3.6 MiB) became four copies of a request body.
+ * Copied for `singleLine`'s reason; `single-line-pin.test.ts` in core pins the two cut identically.
+ */
+const MAX_CAUSE_LENGTH = 4096;
+function boundedCause(text: string): string {
+  if (text.length <= MAX_CAUSE_LENGTH) return text;
+  const reserve = `... (${text.length} more characters)`.length;
+  let keep = MAX_CAUSE_LENGTH - reserve;
+  const last = text.charCodeAt(keep - 1);
+  if (last >= 0xd800 && last <= 0xdbff) keep -= 1;
+  return `${text.slice(0, keep)}... (${text.length - keep} more characters)`;
+}
+
 /**
  * The same one URL `@ultimat3/core`'s `ERROR_DOCS_URL` holds. **Keep in sync**, and read the
  * reason there — briefly: `wiki/` is the only public documentation surface, codes live on that
@@ -116,7 +132,7 @@ export class SchemaError extends Error {
     // `@ultimat3/action`'s `IRREGULAR[word]`.
     const declared = Object.hasOwn(TITLES, init.code) ? TITLES[init.code] : undefined;
     const title = singleLine(declared ?? humanize(init.code));
-    const cause = singleLine(init.cause);
+    const cause = boundedCause(singleLine(init.cause));
     // The cause is in `message` for the reason `UltimateError`'s constructor gives: `message` is
     // the ONLY field a runtime prints when an error escapes uncaught — a worker log, a CI
     // transcript, a stack trace — and `code: title` alone names which rule fired but not which
@@ -169,17 +185,25 @@ export class ValidationFailedError extends SchemaError {
   override readonly name = 'ValidationFailedError';
   readonly issues: readonly ValidationIssue[];
 
-  constructor(issues: readonly ValidationIssue[], root = 'value') {
-    const cause = issues
+  /**
+   * `true` when validation stopped at its issue cap (`MAX_ISSUES`): `issues` is a prefix, and
+   * correcting every one of them may surface more.
+   */
+  readonly issuesTruncated: boolean;
+
+  constructor(issues: readonly ValidationIssue[], root = 'value', issuesTruncated = false) {
+    const listed = issues
       .map((issue) => `${issue.path === '' ? root : issue.path}: ${issue.message}`)
       .join('; ');
+    const cause = issuesTruncated ? `${listed}; (stopped after ${issues.length} issues)` : listed;
     super({
       code: ValidationFailedError.code,
       cause,
       fix: `send ${root} with the field(s) named in cause corrected to the expected type`,
-      meta: { issues },
+      meta: issuesTruncated ? { issues, issuesTruncated: true } : { issues },
     });
     this.issues = issues;
+    this.issuesTruncated = issuesTruncated;
   }
 
   /** One line per issue — what the dev overlay and `x test --json` render. */
@@ -240,6 +264,16 @@ export class SensitiveOutputError extends SchemaError {
   }
 }
 
+/** Thrown where `validate(…, { maxIssues })` is CALLED: a cap no list can meet bounds nothing. */
+export class IssueCapInvalidError extends SchemaError {
+  static readonly code = 'X_SCHEMA_ISSUE_CAP_INVALID';
+  override readonly name = 'IssueCapInvalidError';
+
+  constructor(init: Omit<SchemaErrorInit, 'code'>) {
+    super({ ...init, code: IssueCapInvalidError.code });
+  }
+}
+
 export class SchemaUnsupportedError extends SchemaError {
   static readonly code = 'X_SCHEMA_UNSUPPORTED';
   override readonly name = 'SchemaUnsupportedError';

package/src/index.ts

@@ -1,7 +1,6 @@
 // Single responsibility: the public API of @ultimat3/schema. Explicit named exports only.
 
 export type { ArrayBounds } from './array-schema';
-export { arraySchema } from './array-schema';
 export type {
   AnySchema,
   Check,
@@ -26,7 +25,6 @@ export { charCount } from './char-count';
 export type { QuerySource } from './coerce';
 export { coerceInput, coerceNode, coerceQuery, numeric } from './coerce';
 export { describeValue, expected } from './describe-value';
-export { discriminatedUnionSchema } from './discriminated-union';
 export { ULTIMATE_ERROR_BRAND } from './error-brand';
 export type { SchemaErrorCodeDeclaration } from './error-codes';
 export { SCHEMA_ERROR_CODES } from './error-codes';
@@ -40,6 +38,7 @@ export {
   BoundsInvalidError,
   DefaultInvalidError,
   DiscriminantInvalidError,
+  IssueCapInvalidError,
   isSchemaError,
   SchemaError,
   SchemaUnsupportedError,
@@ -48,6 +47,9 @@ export {
 } from './errors';
 // Exported for `@ultimat3/time`'s `fromIso`: one ISO-shape rule, whichever door a date comes in by.
 export { isIsoDateTime } from './iso-date';
+export type { IssueCapOptions } from './issue-cap';
+// The cap every validation stops at, and the bound `@ultimat3/action`'s `issuesFromWire` reads to.
+export { MAX_ISSUES } from './issue-cap';
 export type {
   JsonSchema,
   JsonSchemaDialect,
@@ -57,7 +59,7 @@ export type {
 } from './json-schema';
 export { nodeToJsonSchema, toJsonSchema } from './json-schema';
 export type { JsonValue } from './json-value';
-export { JSON_MAX_DEPTH, jsonSchema } from './json-value';
+export { jsonSchema } from './json-value';
 export type { MoneyValue } from './money-value';
 export {
   CURRENCY_CODE_PATTERN,
@@ -68,16 +70,9 @@ export {
 export type { SchemaFormat, SchemaKind, SchemaNode, SchemaRefinement } from './node';
 export { isSchemaNode, nodeOf, requiredKeys } from './node';
 export type { SchemaProvider } from './provider';
-export {
-  builtinProvider,
-  configureSchemaProvider,
-  introspect,
-  resetSchemaProvider,
-  schemaProvider,
-  tryIntrospect,
-} from './provider';
+export { configureSchemaProvider, introspect, tryIntrospect } from './provider';
 export { recordSchema } from './record-schema';
-export type { IssueRuleFacts, SchemaIssueParams, SchemaRule } from './schema-rules';
+export type { IssueRuleFacts, SchemaIssueParams } from './schema-rules';
 export { issueRuleFacts, SCHEMA_RULES } from './schema-rules';
 export { assertNoSensitiveOutput, maskSensitive } from './sensitive';
 export type {
@@ -106,21 +101,7 @@ export {
 export type { Infer } from './t';
 export { t } from './t';
 export { isIanaZoneName } from './time-zone-name';
-export type {
-  NumberSchema,
-  ObjectSchema,
-  StringSchema,
-  TNamespace,
-} from './validators';
-export {
-  builtinT,
-  enumSchema,
-  literalSchema,
-  nullableSchema,
-  objectSchema,
-  optionalSchema,
-  refineSchema,
-  unionSchema,
-} from './validators';
+export type { NumberSchema, ObjectSchema, StringSchema, TNamespace } from './validators';
+export { literalSchema, objectSchema } from './validators';
 export type { WireJsonSchema } from './wire-schema';
 export { toWireOutputSchema, toWireSchema } from './wire-schema';

package/src/issue-cap.ts

@@ -0,0 +1,108 @@
+// Single responsibility: the bound on how many issues one validation collects. A public action's
+// body is the attack surface: 10k invalid items cost 289 ms of sync CPU and a 7.2 MiB problem
+// document before this, for a list no client renders past `MAX_ISSUES` (`@ultimat3/action`'s
+// `wire-issues.ts` refuses a longer one on arrival).
+
+import type { StandardIssue } from './standard';
+
+/**
+ * The default cap, and the bound the typed client's `issuesFromWire` imports: a list longer than
+ * this is not a form's worth of rejections, it is a body meant to be expensive.
+ */
+export const MAX_ISSUES = 100;
+
+export interface IssueCapOptions {
+  /** Stop collecting at this many issues. Default `MAX_ISSUES`; a whole number from 1 up. */
+  readonly maxIssues?: number | undefined;
+}
+
+/**
+ * The cap of the validation in flight, `undefined` between validations. Module state, not a
+ * parameter on every check: `Check` is a public signature, and builtin validation is synchronous,
+ * so exactly one validation is ever in flight on this thread while a check runs.
+ */
+let active: number | undefined;
+/** Set when a loop left input unchecked because the cap was reached. */
+let stopped = false;
+
+/**
+ * Why `maxIssues` is no cap, or `undefined` when it is one. The refusal is thrown by `standard.ts`,
+ * which already imports `errors.ts`: this module stays a leaf so `builder.ts` can read it.
+ */
+export function issueCapFault(maxIssues: number): string | undefined {
+  return Number.isSafeInteger(maxIssues) && maxIssues >= 1
+    ? undefined
+    : 'maxIssues must be a whole number from 1 up';
+}
+
+/**
+ * Has a loop collected enough? Asked after each member a builtin composite checks; outside any
+ * validation (a `Check` called directly) the default cap applies, so no door is unbounded.
+ */
+export function issueCapReached(count: number): boolean {
+  return count >= (active ?? MAX_ISSUES);
+}
+
+/**
+ * The question every collecting loop asks after a member: stop here? `true` once `count` has
+ * reached the cap — and when input is left unchecked (`hasMore`), the result is marked a prefix.
+ */
+export function stopCollecting(count: number, hasMore: boolean): boolean {
+  if (!issueCapReached(count)) return false;
+  if (hasMore) stopped = true;
+  return true;
+}
+
+/** A loop is leaving input unchecked: the result says so (`issuesTruncated`). */
+export function markIssuesStopped(): void {
+  stopped = true;
+}
+
+/**
+ * `markIssuesStopped`'s flag as it stands, and a way to put it back. A union tries members and
+ * DISCARDS a failing member's issues, so a member that stopped early must not mark the result.
+ */
+export function issuesStopped(): boolean {
+  return stopped;
+}
+
+export function restoreIssuesStopped(previous: boolean): void {
+  stopped = previous;
+}
+
+export interface CappedRun<T> {
+  readonly value: T;
+  readonly cap: number;
+  /** Only the OUTERMOST run reports: a nested validation is part of its caller's. */
+  readonly stopped: boolean;
+}
+
+/** Run one validation under a cap. Re-entrant: a nested call joins the outer run's cap. */
+export function withIssueCap<T>(cap: number, run: () => T): CappedRun<T> {
+  if (active !== undefined) return { value: run(), cap: active, stopped: false };
+  active = cap;
+  stopped = false;
+  try {
+    const value = run();
+    return { value, cap, stopped };
+  } finally {
+    active = undefined;
+    stopped = false;
+  }
+}
+
+/**
+ * A failure result held to `cap`. `issuesTruncated: true` when issues were dropped here OR a loop
+ * stopped checking — either way the list is a prefix, and a reader must not treat it as complete.
+ */
+export function cappedFailure(
+  issues: readonly StandardIssue[],
+  cap: number,
+  stoppedEarly: boolean,
+): { readonly issues: readonly StandardIssue[]; readonly issuesTruncated?: true } {
+  const over = issues.length > cap;
+  // A nested validation cut here is its caller's truncation too: the flag the outermost run reads.
+  if (over) stopped = true;
+  const kept = over ? issues.slice(0, cap) : issues;
+  return over || stoppedEarly ? { issues: kept, issuesTruncated: true } : { issues: kept };
+}

package/src/json-value.ts

@@ -12,6 +12,7 @@ import {
   type Schema,
 } from './builder';
 import { expected } from './describe-value';
+import { stopCollecting } from './issue-cap';
 import type { SchemaNode } from './node';
 import type { StandardIssue } from './standard';
 import { unstorable } from './unstorable-text';
@@ -132,6 +133,8 @@ function walkArray(
   // An index loop, never `entries()` on a sparse array alone: a hole reads `undefined` and is
   // refused at its index, where `JSON.stringify` would have written `null` in silence.
   for (let index = 0; index < items.length; index += 1) {
+    // At the issue cap the rest is not walked (`issue-cap.ts`); issues already exist, so this fails.
+    if (stopCollecting(state.issues.length, true)) return null;
     const step = walk(items[index], { parent: at, segment: index }, depth + 1, state);
     if (step === null) ok = false;
     else {
@@ -156,6 +159,7 @@ function walkObject(
   // The entry's POSITION is its path segment, never its key — the rule `recordSchema` states:
   // a key is caller data, and an issue path reaches the problem document and the log line.
   for (const [index, key] of Object.keys(source).entries()) {
+    if (stopCollecting(state.issues.length, true)) return null;
     const link: At = { parent: at, segment: index };
     const reason = unstorable(key);
     if (reason !== undefined) {

package/src/record-schema.ts

@@ -13,6 +13,7 @@ import {
   type Schema,
 } from './builder';
 import { expected } from './describe-value';
+import { stopCollecting } from './issue-cap';
 import type { SchemaNode } from './node';
 import { isPrototypeKey, PROTOTYPE_KEYS } from './prototype-keys';
 import type { InferInput, InferOutput, StandardIssue } from './standard';
@@ -30,7 +31,10 @@ export function recordSchema<S extends AnySchema>(
         return mistyped(path, expected('an object', value), value, 'record');
       const issues: StandardIssue[] = [];
       const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-      for (const [index, [key, entry]] of Object.entries(value).entries()) {
+      const entries = Object.entries(value);
+      for (const [index, [key, entry]] of entries.entries()) {
+        // At the issue cap the rest is not read (`issue-cap.ts`): a 10k-key body is a hundred.
+        if (stopCollecting(issues.length, true)) break;
         // The entry's POSITION, never its key. `describe-value.ts`'s absolute is stated about the
         // rejected value, and a record's KEY is the caller's data just as much: the path travels
         // `formatIssue` -> `bodyInvalid`'s `cause` -> the problem document AND the log line, and

package/src/standard.ts

@@ -2,7 +2,19 @@
 // This is the swap point: every Ultimate primitive accepts any conforming schema, so ArkType,
 // Zod and Valibot are all first-class without a line of adapter code.
 
-import { SchemaUnsupportedError, ValidationFailedError, type ValidationIssue } from './errors';
+import {
+  IssueCapInvalidError,
+  SchemaUnsupportedError,
+  ValidationFailedError,
+  type ValidationIssue,
+} from './errors';
+import {
+  cappedFailure,
+  type IssueCapOptions,
+  issueCapFault,
+  MAX_ISSUES,
+  withIssueCap,
+} from './issue-cap';
 import { issueRuleFacts, type SchemaIssueParams } from './schema-rules';
 
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
@@ -29,6 +41,11 @@ export interface StandardSuccessResult<Output> {
 
 export interface StandardFailureResult {
   readonly issues: readonly StandardIssue[];
+  /**
+   * Ultimate's extension: `true` when validation stopped at its issue cap (`MAX_ISSUES`, or
+   * `validate(…, { maxIssues })`), so `issues` is a prefix of what is wrong, never all of it.
+   */
+  readonly issuesTruncated?: true | undefined;
 }
 
 export type StandardResult<Output> = StandardSuccessResult<Output> | StandardFailureResult;
@@ -130,21 +147,54 @@ function assertSync<Output>(
   return result;
 }
 
-/** Validate against ANY conforming schema. Never throws on invalid input. */
+function capOf(options: IssueCapOptions | undefined): number {
+  const max = options?.maxIssues;
+  if (max === undefined) return MAX_ISSUES;
+  const fault = issueCapFault(max);
+  if (fault === undefined) return max;
+  throw new IssueCapInvalidError({
+    cause: `${fault}; got ${Number.isFinite(max) ? String(max) : typeof max}`,
+    fix: 'validate(schema, value, { maxIssues: 100 })   # or omit maxIssues for the default MAX_ISSUES',
+    meta: { maxIssues: max },
+  });
+}
+
+/** A failure held to its cap; a success passes through untouched. */
+function bounded<Output>(
+  result: StandardResult<Output>,
+  cap: number,
+  stopped: boolean,
+): StandardResult<Output> {
+  if (result.issues === undefined) return result;
+  return cappedFailure(result.issues, cap, stopped || result.issuesTruncated === true);
+}
+
+/**
+ * Validate against ANY conforming schema. Never throws on invalid input. At most `maxIssues`
+ * (default `MAX_ISSUES`) issues come back: a builtin schema STOPS checking there, so a hostile
+ * 10k-item body costs a hundred refusals, not ten thousand; a foreign library's list is cut.
+ */
 export function validate<S extends StandardSchemaV1>(
   schema: S,
   value: unknown,
+  options?: IssueCapOptions,
 ): StandardResult<InferOutput<S>> {
   const props = schema['~standard'];
-  return assertSync(props.validate(value), props.vendor) as StandardResult<InferOutput<S>>;
+  const run = withIssueCap(capOf(options), () => props.validate(value));
+  const result = assertSync(run.value, props.vendor) as StandardResult<InferOutput<S>>;
+  return bounded(result, run.cap, run.stopped);
 }
 
 export async function validateAsync<S extends StandardSchemaV1>(
   schema: S,
   value: unknown,
+  options?: IssueCapOptions,
 ): Promise<StandardResult<InferOutput<S>>> {
-  const result = await schema['~standard'].validate(value);
-  return result as StandardResult<InferOutput<S>>;
+  // The cap spans the SYNCHRONOUS part of the call — all of a builtin schema's work. A library
+  // that validates asynchronously finishes outside it, and its list is cut below instead.
+  const run = withIssueCap(capOf(options), () => schema['~standard'].validate(value));
+  const result = (await run.value) as StandardResult<InferOutput<S>>;
+  return bounded(result, run.cap, run.stopped);
 }
 
 /** Validate or throw `X_VALIDATION_FAILED` with a path-annotated issue list. */
@@ -155,7 +205,11 @@ export function parse<S extends StandardSchemaV1>(
 ): InferOutput<S> {
   const result = validate(schema, value);
   if (result.issues === undefined) return result.value;
-  throw new ValidationFailedError(toValidationIssues(result.issues), root);
+  throw new ValidationFailedError(
+    toValidationIssues(result.issues),
+    root,
+    result.issuesTruncated === true,
+  );
 }
 
 export async function parseAsync<S extends StandardSchemaV1>(
@@ -165,7 +219,11 @@ export async function parseAsync<S extends StandardSchemaV1>(
 ): Promise<InferOutput<S>> {
   const result = await validateAsync(schema, value);
   if (result.issues === undefined) return result.value;
-  throw new ValidationFailedError(toValidationIssues(result.issues), root);
+  throw new ValidationFailedError(
+    toValidationIssues(result.issues),
+    root,
+    result.issuesTruncated === true,
+  );
 }
 
 export function isStandardSchema(value: unknown): value is StandardSchemaV1 {

package/src/validators.ts

@@ -24,6 +24,7 @@ import { charCount } from './char-count';
 import { expected } from './describe-value';
 import { discriminatedUnionSchema } from './discriminated-union';
 import { isIsoDateTime, isZonelessDateTime } from './iso-date';
+import { issuesStopped, restoreIssuesStopped, stopCollecting } from './issue-cap';
 import { type JsonValue, jsonSchema } from './json-value';
 import { type MoneyValue, moneySchema } from './money-value';
 import type { SchemaNode } from './node';
@@ -216,6 +217,7 @@ export function objectSchema<S extends Shape>(shape: S): ObjectSchema<S> {
     // back off a value nobody sent.
     const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
     for (const [key, memberCheck] of checks) {
+      if (stopCollecting(issues.length, true)) break;
       // `Object.hasOwn`, never a raw index — the guard `coerce.ts` already applies to the same
       // read. `value['toString']` answered the INHERITED function for an input that carried no
       // such key, so a field named after a prototype member was unsatisfiable for every input,
@@ -292,11 +294,18 @@ export function unionSchema<S extends readonly [AnySchema, ...AnySchema[]]>(
   const node: SchemaNode = { kind: 'union', anyOf: members.map((member) => member.node) };
   return makeSchema<InferInput<S[number]>, InferOutput<S[number]>>(node, (value, path) => {
     const reasons: string[] = [];
+    // A member's issues are DISCARDED here, so a member that stopped at the cap must not mark the
+    // result a prefix: the union answers one issue of its own, which is the whole of it.
+    const stoppedBefore = issuesStopped();
     for (const memberCheck of checks) {
       const result = memberCheck(value, path);
-      if (result.ok) return pass(result.value as InferOutput<S[number]>);
+      if (result.ok) {
+        restoreIssuesStopped(stoppedBefore);
+        return pass(result.value as InferOutput<S[number]>);
+      }
       reasons.push(result.issues.map((issue) => issue.message).join(', '));
     }
+    restoreIssuesStopped(stoppedBefore);
     return rejected(path, `no union member matched (${reasons.join(' | ')})`, 'union');
   });
 }