@ultimat3/schema 25.0.0 → 25.2.0

package/CLAUDE.md

@@ -15,8 +15,9 @@ Tier 0. **Imports no `@ultimat3/*` package — not even `@ultimat3/core`.**
 | 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 → validators →
-discriminated-union → provider → t` (`node-fits` and `json-schema` read `json-value` too).
+`char-count → describe-value → node → builder → money-value → json-value → array-schema →
+validators → discriminated-union → provider → t` (`node-fits` and `json-schema` read `json-value`
+too).
 `char-count.ts` is imported by BOTH `validators.ts` (which rejects on length) and
 `describe-value.ts` (which renders the length in the same message), because they disagreed: the
 rule counted code points and the message counted UTF-16 units, so `t.string.min(3)` refused `'👍a'`
@@ -47,6 +48,11 @@ else, in CHARACTERS (`char-count.ts`) — the unit the rule that rejected it cou
 re-enables the echo — one misconfigured environment is the same breach, and a dev
 overlay already holds the raw body. `describe-value.test.ts` is the enforcement.
 
+`t.array(items, { min, max })` (`array-schema.ts`) carries its bounds as `minItems`/`maxItems` ON
+the node — JSON Schema's names — and `json-schema.ts` and `wire-schema.ts` publish both;
+`@ultimat3/action`'s `sampleFor` samples `minItems` items. A bound no count meets is
+`X_SCHEMA_BOUNDS_INVALID` where it is declared, the same rule as the discriminant below.
+
 `X_SCHEMA_DISCRIMINANT_INVALID` is thrown where a `discriminatedUnion` is BUILT, not where a value
 is parsed. A member with no literal at the discriminant, or a second member claiming a tag the
 first already owns, can never be routed to — so it is wrong for every input, and the first import

package/README.md

@@ -27,7 +27,7 @@ export const publishPost = t.object({
   postId:   t.uuid,
   notify:   t.boolean.default(true),
   title:    t.string.min(3).max(80),
-  tags:     t.array(t.slug),
+  tags:     t.array(t.slug, { max: 10 }),  // inclusive item-count bounds, both optional
   price:    t.money,                 // { minor: 1999, currency: 'EUR' } — never a float
                                      // { minor: 2, currency: 'USD', scale: 6 } is $0.000002
   timeZone: t.timezone,              // real IANA validation, not an annotation
@@ -55,6 +55,7 @@ Refused at the boundary rather than guessed at (`As of 2026-10`):
 | `t.url` | leading / trailing spaces and C0 controls, a tab or newline anywhere | the URL parser strips them in silence and the validator returns the string as written. Trim before parsing |
 | `t.object` `t.record` `t.money` | anything whose prototype is not `Object.prototype` or `null` — a `Map`, a `Date`, a class instance | none has the own keys the schema declared, so it parsed to `{}` |
 | `.default(v)` | a `v` the schema itself rejects — `X_SCHEMA_DEFAULT_INVALID`, thrown where it is declared | an omitted field parsed to a value the same schema refuses when sent |
+| `t.array(items, { min, max })` | fewer than `min` or more than `max` items, before any item is read; at declaration, a bound that is not a whole number from 0 up, or `min > max` — `X_SCHEMA_BOUNDS_INVALID` | the bounds sit on the array node, so OpenAPI and the MCP tool schema publish them as `minItems`/`maxItems` — a `t.refine` count was prose no generated client could enforce |
 
 ### `t.json()` — a payload whose shape is somebody else's
 
@@ -184,6 +185,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
+| `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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/schema",
-  "version": "25.0.0",
+  "version": "25.2.0",
   "description": "Ultimate's validation seam: Standard Schema interface, the t namespace, JSON Schema output",
   "license": "MIT",
   "type": "module",

package/src/array-schema.ts

@@ -0,0 +1,79 @@
+// Single responsibility: `t.array(items, { min, max })` — the list validator and its item-count
+// bounds. Its own file because the bounds are a declaration-time refusal as well as a parse rule,
+// and `validators.ts` was at the line ceiling.
+
+import { type AnySchema, checkOf, fail, failWith, makeSchema, pass, type Schema } from './builder';
+import { describeValue, expected } from './describe-value';
+import { BoundsInvalidError } from './errors';
+import type { SchemaNode } from './node';
+import type { InferInput, InferOutput, StandardIssue } from './standard';
+
+/**
+ * Item-count bounds, inclusive. ON the array node, never an element rule or a `t.refine`: the node
+ * is what OpenAPI, the MCP tool schema and the contract sampler read, so a bound kept anywhere
+ * else is one every projection omits.
+ */
+export interface ArrayBounds {
+  readonly min?: number | undefined;
+  readonly max?: number | undefined;
+}
+
+const items = (count: number): string => `${count} item${count === 1 ? '' : 's'}`;
+
+/** A bound is a whole count from zero up — anything else matches no array, or every array. */
+function boundFault(name: 'min' | 'max', bound: number | undefined): string | undefined {
+  if (bound === undefined || (Number.isSafeInteger(bound) && bound >= 0)) return undefined;
+  // `describeValue` for the shape, the value whole in `meta`: the house rule for a cause.
+  return `t.array's ${name} must be a whole number from 0 up; got ${describeValue(bound)}`;
+}
+
+function assertBounds(bounds: ArrayBounds): void {
+  const { min, max } = bounds;
+  const fault =
+    boundFault('min', min) ??
+    boundFault('max', max) ??
+    (min !== undefined && max !== undefined && min > max
+      ? `t.array's min (${min}) is above its max (${max}), so no array satisfies it`
+      : undefined);
+  if (fault === undefined) return;
+  throw new BoundsInvalidError({
+    cause: fault,
+    fix: 't.array(items, { min: 1, max: 20 })   # whole numbers, 0 <= min <= max; omit a bound to leave that side open',
+    meta: { min, max },
+  });
+}
+
+export function arraySchema<S extends AnySchema>(
+  item: S,
+  bounds: ArrayBounds = {},
+): Schema<readonly InferInput<S>[], InferOutput<S>[]> {
+  assertBounds(bounds);
+  const { min, max } = bounds;
+  const itemCheck = checkOf(item);
+  const node: SchemaNode = {
+    kind: 'array',
+    items: item.node,
+    ...(min === undefined ? {} : { minItems: min }),
+    ...(max === undefined ? {} : { maxItems: max }),
+  };
+  return makeSchema<readonly InferInput<S>[], InferOutput<S>[]>(node, (value, path) => {
+    if (!Array.isArray(value)) return fail(path, expected('an array', value));
+    // The count before the items: an over-long array is refused without reading a member, so a
+    // caller's 10,000-element body costs one comparison, not 10,000 item checks.
+    if (min !== undefined && value.length < min) {
+      return fail(path, expected(`an array of at least ${items(min)}`, value));
+    }
+    if (max !== undefined && value.length > max) {
+      return fail(path, expected(`an array of at most ${items(max)}`, value));
+    }
+    const issues: StandardIssue[] = [];
+    const out: unknown[] = [];
+    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);
+    }
+    if (issues.length > 0) return failWith(issues);
+    return pass(out as InferOutput<S>[]);
+  });
+}

package/src/error-codes.ts

@@ -27,4 +27,5 @@ export const SCHEMA_ERROR_CODES: Readonly<Record<string, SchemaErrorCodeDeclarat
       title: 'a schema default cannot be copied per parse',
     },
     X_SCHEMA_DEFAULT_INVALID: { title: 'a schema default fails its own schema' },
+    X_SCHEMA_BOUNDS_INVALID: { title: 'an array bound no array can satisfy' },
   });

package/src/errors.ts

@@ -210,6 +210,19 @@ export class DefaultInvalidError extends SchemaError {
   }
 }
 
+/**
+ * Thrown where `t.array(items, { min, max })` is WRITTEN: a bound no item count meets refuses every
+ * input, and the first import of the authoring file is the earliest honest place to say so.
+ */
+export class BoundsInvalidError extends SchemaError {
+  static readonly code = 'X_SCHEMA_BOUNDS_INVALID';
+  override readonly name = 'BoundsInvalidError';
+
+  constructor(init: Omit<SchemaErrorInit, 'code'>) {
+    super({ ...init, code: BoundsInvalidError.code });
+  }
+}
+
 export class SchemaUnsupportedError extends SchemaError {
   static readonly code = 'X_SCHEMA_UNSUPPORTED';
   override readonly name = 'SchemaUnsupportedError';

package/src/index.ts

@@ -1,5 +1,7 @@
 // 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,
@@ -35,6 +37,7 @@ export type {
   ValidationIssue,
 } from './errors';
 export {
+  BoundsInvalidError,
   DefaultInvalidError,
   DiscriminantInvalidError,
   isSchemaError,
@@ -105,7 +108,6 @@ export type {
   TNamespace,
 } from './validators';
 export {
-  arraySchema,
   builtinT,
   enumSchema,
   literalSchema,

package/src/json-schema.ts

@@ -54,6 +54,8 @@ export interface JsonSchema {
   /** Negation. Emitted only inside `propertyNames`, to publish a closed set of refused keys. */
   readonly not?: JsonSchema;
   readonly items?: JsonSchema;
+  readonly minItems?: number;
+  readonly maxItems?: number;
   readonly anyOf?: readonly JsonSchema[];
   readonly discriminator?: JsonSchemaDiscriminator;
   readonly title?: string;
@@ -227,6 +229,8 @@ function convert(node: SchemaNode): JsonSchema {
       return annotate({
         type: 'array',
         items: node.items === undefined ? {} : convert(node.items),
+        ...(node.minItems === undefined ? {} : { minItems: node.minItems }),
+        ...(node.maxItems === undefined ? {} : { maxItems: node.maxItems }),
       });
     case 'union':
       return annotate({

package/src/node.ts

@@ -71,6 +71,9 @@ export interface SchemaNode {
   readonly integer?: boolean | undefined;
   readonly properties?: Readonly<Record<string, SchemaNode>> | undefined;
   readonly items?: SchemaNode | undefined;
+  /** An array's inclusive item-count bounds — JSON Schema's `minItems`/`maxItems`, by the same name. */
+  readonly minItems?: number | undefined;
+  readonly maxItems?: number | undefined;
   readonly values?: readonly (string | number)[] | undefined;
   readonly literal?: string | number | boolean | null | undefined;
   readonly anyOf?: readonly SchemaNode[] | undefined;

package/src/t.ts

@@ -2,6 +2,7 @@
 // Every member delegates to the active provider, so `configureSchemaProvider()` takes effect
 // even for modules that captured `t` at import time.
 
+import type { ArrayBounds } from './array-schema';
 import type { AnySchema, Refinement, Schema, Shape } from './builder';
 import type { JsonValue } from './json-value';
 import type { MoneyValue } from './money-value';
@@ -61,8 +62,15 @@ export const t: TNamespace = {
   object<S extends Shape>(shape: S): ObjectSchema<S> {
     return provider().object(shape);
   },
-  array<S extends AnySchema>(items: S): Schema<readonly InferInput<S>[], InferOutput<S>[]> {
-    return provider().array(items);
+  /**
+   * `t.array(t.uuid, { min: 1, max: 20 })` — inclusive item-count bounds on the array itself, so
+   * OpenAPI and the MCP tool schema publish them as `minItems`/`maxItems`. Omitted, any length.
+   */
+  array<S extends AnySchema>(
+    items: S,
+    bounds?: ArrayBounds,
+  ): Schema<readonly InferInput<S>[], InferOutput<S>[]> {
+    return provider().array(items, bounds);
   },
   enum<const V extends readonly [string, ...string[]]>(values: V): Schema<V[number], V[number]> {
     return provider().enum(values);

package/src/validators.ts

@@ -3,6 +3,7 @@
 // Standard Schema surface are what the rest of the framework actually depends on.
 
 import { isAbsoluteUrl } from './absolute-url';
+import { type ArrayBounds, arraySchema } from './array-schema';
 import {
   type AnySchema,
   type Check,
@@ -230,25 +231,6 @@ export function objectSchema<S extends Shape>(shape: S): ObjectSchema<S> {
   };
 }
 
-export function arraySchema<S extends AnySchema>(
-  items: S,
-): Schema<readonly InferInput<S>[], InferOutput<S>[]> {
-  const itemCheck = checkOf(items);
-  const node: SchemaNode = { kind: 'array', items: items.node };
-  return makeSchema<readonly InferInput<S>[], InferOutput<S>[]>(node, (value, path) => {
-    if (!Array.isArray(value)) return fail(path, expected('an array', value));
-    const issues: StandardIssue[] = [];
-    const out: unknown[] = [];
-    for (const [index, item] of value.entries()) {
-      const result = itemCheck(item, [...path, index]);
-      if (result.ok) out.push(result.value);
-      else issues.push(...result.issues);
-    }
-    if (issues.length > 0) return failWith(issues);
-    return pass(out as InferOutput<S>[]);
-  });
-}
-
 export function enumSchema<const V extends readonly [string, ...string[]]>(
   values: V,
 ): Schema<V[number], V[number]> {
@@ -416,7 +398,11 @@ export interface TNamespace {
   /** Any JSON value, bounded in depth — a payload whose shape is somebody else's. */
   json(): Schema<JsonValue, JsonValue>;
   object<S extends Shape>(shape: S): ObjectSchema<S>;
-  array<S extends AnySchema>(items: S): Schema<readonly InferInput<S>[], InferOutput<S>[]>;
+  /** `t.array(items, { min, max })` — inclusive item-count bounds, both optional. */
+  array<S extends AnySchema>(
+    items: S,
+    bounds?: ArrayBounds,
+  ): Schema<readonly InferInput<S>[], InferOutput<S>[]>;
   enum<const V extends readonly [string, ...string[]]>(values: V): Schema<V[number], V[number]>;
   /** Variadic `enum`; the blessed spelling at call sites. */
   enumerated<const V extends readonly [string, ...string[]]>(

package/src/wire-schema.ts

@@ -18,6 +18,8 @@ export interface WireJsonSchema {
   readonly required?: readonly string[];
   readonly additionalProperties?: boolean;
   readonly items?: WireJsonSchema;
+  readonly minItems?: number;
+  readonly maxItems?: number;
   readonly enum?: readonly (string | number | boolean | null)[];
   readonly const?: string | number | boolean | null;
   readonly default?: unknown;
@@ -76,6 +78,8 @@ function narrow(source: JsonSchema): WireJsonSchema {
       ? {}
       : { additionalProperties: source.additionalProperties !== false }),
     ...(source.items === undefined ? {} : { items: narrow(source.items) }),
+    ...(source.minItems === undefined ? {} : { minItems: source.minItems }),
+    ...(source.maxItems === undefined ? {} : { maxItems: source.maxItems }),
     ...(source.enum === undefined ? {} : { enum: source.enum }),
     ...(source.const === undefined ? {} : { const: source.const }),
     ...(source.default === undefined ? {} : { default: source.default }),