@ultimat3/schema 29.4.0 → 30.1.0

package/src/sample-draw.ts

@@ -0,0 +1,118 @@
+/**
+ * The choices a sample walk delegates, and the minimal answer to each. One walker (`sample.ts`)
+ * takes a `Draw`, so the contract step's generated inputs and the policy assertion's single sample
+ * share every rule about what a node accepts; only the choices differ.
+ */
+
+import type { SchemaFormat, SchemaNode } from './node';
+
+/** Every choice a walk makes that its node leaves open. Answers stay inside the node's own bounds. */
+export interface Draw {
+  /** An unformatted string within `minLength`/`maxLength` (formats are `BY_FORMAT`'s, never drawn). */
+  string(node: SchemaNode): string;
+  /** A number within `minimum`/`maximum`, whole when `integer`. */
+  number(node: SchemaNode): number;
+  boolean(): boolean;
+  /** Whether an optional or defaulted key is sent at all. */
+  include(key: string): boolean;
+  /** How many items an array sample holds, never below what `minItems` owes. */
+  items(node: SchemaNode): number;
+  /** One of an enum's values or a union's members; `undefined` only for an empty list. */
+  member<T>(choices: readonly T[]): T | undefined;
+  /** Whether a nullable node answers `null`. */
+  nullable(node: SchemaNode): boolean;
+}
+
+/** Version 4, variant 1 — the shape `t.uuid` insists on, and no byte of it means anything. */
+const SAMPLE_UUID = '00000000-0000-4000-8000-000000000000';
+
+/** Short, and valid under `t.slug`'s and `t.cursor`'s patterns as well as bare `t.string`. */
+export const SAMPLE_STRING = 'sample';
+
+/**
+ * One entry per `SchemaFormat`, exhaustively — a new format is a type error here rather than a
+ * silent `'sample'` that fails its own validator. The ONE table both draws read: a mutated uuid
+ * tests nothing but the validator, so a seeded draw never varies a format value.
+ */
+export const BY_FORMAT: Readonly<Record<SchemaFormat, string>> = {
+  uuid: SAMPLE_UUID,
+  email: 'sample@example.test',
+  uri: 'https://example.test/sample',
+  'date-time': '2020-01-01T00:00:00.000Z',
+  slug: SAMPLE_STRING,
+  timezone: 'UTC',
+  locale: 'en',
+  cursor: SAMPLE_STRING,
+};
+
+/**
+ * The value a formatted string node gets, or `undefined` for an unformatted one.
+ * `Object.hasOwn`, never the read alone: `node.format` comes from a provider's IR, and
+ * `BY_FORMAT['constructor']` is the `Object` function off the prototype chain.
+ */
+export function formatValue(node: SchemaNode): string | undefined {
+  if (node.format === undefined) return undefined;
+  return Object.hasOwn(BY_FORMAT, node.format) ? BY_FORMAT[node.format] : SAMPLE_STRING;
+}
+
+/**
+ * The most items a sample will hold. `minItems` past this is an input the framework does not
+ * invent — `2 ** 32` made `Array.from` throw. Such an array is a GAP (`sampleGaps`), reported as
+ * `X_CONTRACT_DRIFT` with the instruction to pass the input, never silently under-sampled.
+ */
+export const SAMPLE_ITEMS_MAX = 1000;
+
+/**
+ * The `minItems` an array sample owes, or `undefined` when none can be built: past the ceiling,
+ * or not a count at all. The builtin `t.array` refuses a bad bound at declaration, but this IR
+ * may come from a swapped provider.
+ */
+export function owedItems(node: SchemaNode): number | undefined {
+  const min = node.minItems;
+  if (min === undefined) return 0;
+  return Number.isSafeInteger(min) && min >= 0 && min <= SAMPLE_ITEMS_MAX ? min : undefined;
+}
+
+/** `'sample'`, padded to `minLength` and cut to `maxLength`. */
+export function minimalString(node: SchemaNode): string {
+  const min = node.minLength ?? 0;
+  const padded = SAMPLE_STRING.length >= min ? SAMPLE_STRING : SAMPLE_STRING.padEnd(min, 'x');
+  return node.maxLength === undefined ? padded : padded.slice(0, node.maxLength);
+}
+
+/** The lower bound, rounded inward for an integer, or the upper one when the lower overshoots. */
+export function minimalNumber(node: SchemaNode): number {
+  const low = node.minimum ?? 0;
+  const value = node.integer === true ? Math.ceil(low) : low;
+  if (node.maximum === undefined || value <= node.maximum) return value;
+  return node.integer === true ? Math.floor(node.maximum) : node.maximum;
+}
+
+/**
+ * Whether `value` satisfies the node's own `pattern`. An uncompilable pattern is a gap, not a
+ * throw: only a foreign provider's IR can produce one, and a generated contract test must not die
+ * on the way to reporting what it needs.
+ */
+export function satisfiesPattern(node: SchemaNode, value: unknown): boolean {
+  if (node.pattern === undefined) return true;
+  if (typeof value !== 'string') return false;
+  try {
+    return new RegExp(node.pattern, node.patternFlags ?? '').test(value);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The smallest value each choice allows: `null` where nullable, no optional key, the fewest
+ * items, the first member. The policy assertion's sample, byte for byte what it always was.
+ */
+export const minimalDraw: Draw = Object.freeze({
+  string: minimalString,
+  number: minimalNumber,
+  boolean: () => false,
+  include: () => false,
+  items: (node: SchemaNode) => owedItems(node) ?? 0,
+  member: <T>(choices: readonly T[]): T | undefined => choices[0],
+  nullable: () => true,
+});

package/src/sample-seeded.ts

@@ -0,0 +1,147 @@
+/**
+ * `seededDraw(seed, run)`: the generated inputs the contract step's exercise assertion sends.
+ * A number in, the same values out — never `Math.random`, never the clock — so a red run replays
+ * from the test's name alone. Runs 0-3 sit on the IR's bounds; later runs draw inside them.
+ */
+
+import type { SchemaNode } from './node';
+import type { Draw } from './sample-draw';
+import {
+  minimalNumber,
+  minimalString,
+  owedItems,
+  SAMPLE_ITEMS_MAX,
+  satisfiesPattern,
+} from './sample-draw';
+
+/** Runs below this one are boundaries, not draws. */
+export const BOUNDARY_RUNS = 4;
+
+/**
+ * Multibyte on purpose: the text a handler mishandles is the text a test never typed. Every entry
+ * is one code point, the unit `minLength`/`maxLength` count in (`char-count.ts`), and none is a
+ * control character or a lone surrogate, which a validator or a database refuses on its own.
+ */
+const ALPHABET = [
+  'a',
+  'z',
+  'Q',
+  '0',
+  '7',
+  ' ',
+  '-',
+  '_',
+  'é',
+  'ß',
+  'ж',
+  'ع',
+  '漢',
+  '字',
+  '🙂',
+  '👍',
+];
+
+/** An unbounded string's length is this past its floor; a bound past the cap is clamped to it. */
+const STRING_SPAN = 24;
+const STRING_CAP = 4096;
+
+/** An unbounded number's range, both directions. A whole number stays a 32-bit one. */
+const NUMBER_SPAN = 1_000_000;
+const INTEGER_HIGH = 2 ** 31 - 1;
+
+/** An array draws at most this many items past what `minItems` owes. */
+const ITEMS_SPAN = 4;
+
+/** mulberry32: 32 bits of state, a uniform float in [0, 1) per call. */
+function generator(state: number): () => number {
+  let s = state >>> 0;
+  return () => {
+    s = (s + 0x6d2b79f5) >>> 0;
+    let x = s;
+    x = Math.imul(x ^ (x >>> 15), x | 1);
+    x ^= x + Math.imul(x ^ (x >>> 7), x | 61);
+    return ((x ^ (x >>> 14)) >>> 0) / 4_294_967_296;
+  };
+}
+
+/** Which side of every bound a boundary run takes, and whether it reaches for the optional parts. */
+interface Boundary {
+  readonly high: boolean;
+  readonly optional: boolean;
+  readonly nulls: boolean;
+}
+
+const BOUNDARIES: readonly Boundary[] = [
+  { high: false, optional: false, nulls: false },
+  { high: true, optional: true, nulls: false },
+  { high: false, optional: true, nulls: true },
+  { high: true, optional: false, nulls: false },
+];
+
+const whole = (n: number, integer: boolean, up: boolean): number =>
+  integer ? (up ? Math.ceil(n) : Math.floor(n)) : n;
+
+function numberRange(node: SchemaNode): readonly [number, number] {
+  const integer = node.integer === true;
+  const low = whole(node.minimum ?? (integer ? -INTEGER_HIGH : -NUMBER_SPAN), integer, true);
+  const high = whole(node.maximum ?? (integer ? INTEGER_HIGH : NUMBER_SPAN), integer, false);
+  return [low, high];
+}
+
+function lengthRange(node: SchemaNode): readonly [number, number] {
+  const low = Math.min(node.minLength ?? 0, STRING_CAP);
+  const high = Math.min(node.maxLength ?? low + STRING_SPAN, STRING_CAP);
+  return [low, Math.max(low, high)];
+}
+
+/**
+ * The draw for one run of one seed. `seed` is the caller's: `@ultimat3/action` and
+ * `@ultimat3/query` hand it `fnv1a(<name>)`, which this tier cannot import.
+ */
+export function seededDraw(seed: number, run: number): Draw {
+  const next = generator((seed ^ Math.imul(run + 1, 0x9e3779b1)) >>> 0);
+  const between = (low: number, high: number): number =>
+    low + Math.floor(next() * (high - low + 1));
+  const edge = run >= 0 && run < BOUNDARY_RUNS ? BOUNDARIES[run] : undefined;
+
+  const text = (node: SchemaNode): string => {
+    const [low, high] = lengthRange(node);
+    const length = edge === undefined ? between(low, high) : edge.high ? high : low;
+    const chars = Array.from({ length }, () => ALPHABET[between(0, ALPHABET.length - 1)] ?? 'a');
+    const value = chars.join('');
+    // A regex cannot be inverted: a drawn value that misses it would test only the validator, so
+    // the one value the walk can build for it stands in (and `sampleGaps` reports when it cannot).
+    return satisfiesPattern(node, value) ? value : minimalString(node);
+  };
+
+  const number = (node: SchemaNode): number => {
+    const [low, high] = numberRange(node);
+    if (low > high) return minimalNumber(node);
+    if (edge !== undefined) return edge.high ? high : low;
+    if (node.integer === true) return between(low, high);
+    // Two decimals, clamped: a float draw must not step past the bound it was drawn under.
+    const drawn = Math.round((low + next() * (high - low)) * 100) / 100;
+    return Math.min(high, Math.max(low, drawn));
+  };
+
+  return {
+    string: text,
+    number,
+    boolean: () => (edge === undefined ? next() < 0.5 : edge.high),
+    include: () => (edge === undefined ? next() < 0.5 : edge.optional),
+    items: (node) => {
+      const owed = owedItems(node) ?? 0;
+      const cap = Math.max(
+        owed,
+        Math.min(node.maxItems ?? owed + ITEMS_SPAN, owed + ITEMS_SPAN * 2, SAMPLE_ITEMS_MAX),
+      );
+      if (edge !== undefined) return edge.high ? cap : owed;
+      return between(owed, Math.min(cap, owed + ITEMS_SPAN));
+    },
+    member: <T>(choices: readonly T[]): T | undefined =>
+      choices.length === 0
+        ? undefined
+        : choices[edge === undefined ? between(0, choices.length - 1) : run % choices.length],
+    nullable: () => (edge === undefined ? next() < 0.25 : edge.nulls),
+  };
+}

package/src/sample.ts

@@ -0,0 +1,161 @@
+/**
+ * `@ultimat3/schema/sample`, off the barrel: a value an input schema accepts, derived from that
+ * schema's own IR. One walker, parameterised by a `Draw` — `minimalDraw` is the policy assertion's
+ * single sample, `seededDraw` the contract step's generated inputs. Never in `t`'s bundle graph.
+ */
+
+import type { SchemaNode } from './node';
+import { requiredKeys } from './node';
+import { tryIntrospect } from './provider';
+import type { Draw } from './sample-draw';
+import {
+  BY_FORMAT,
+  formatValue,
+  minimalDraw,
+  owedItems,
+  SAMPLE_STRING,
+  satisfiesPattern,
+} from './sample-draw';
+import { seededDraw } from './sample-seeded';
+import type { StandardSchemaV1 } from './standard';
+
+export type { Draw } from './sample-draw';
+export { minimalDraw, SAMPLE_ITEMS_MAX } from './sample-draw';
+export { BOUNDARY_RUNS, seededDraw } from './sample-seeded';
+
+/**
+ * `Object.create(null)`, the shape the object parser already builds: on a `{}` literal
+ * `sample['__proto__'] = value` reaches `Object.prototype`'s SETTER, so a required field named
+ * `__proto__` replaced the sample's prototype and the payload failed the schema it came from.
+ * Required keys always; an optional or defaulted one only when the draw includes it.
+ */
+function sampleObject(node: SchemaNode, draw: Draw): Record<string, unknown> {
+  const properties = node.properties ?? {};
+  const required = new Set(requiredKeys(node));
+  const sample: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Object.keys(properties)) {
+    const child = Object.hasOwn(properties, key) ? properties[key] : undefined;
+    if (child === undefined) continue;
+    if (required.has(key) || draw.include(key)) sample[key] = sampleFor(child, draw);
+  }
+  return sample;
+}
+
+function sampleString(node: SchemaNode, draw: Draw): string {
+  // A format value is already the exact shape its validator wants; padding or drawing it would
+  // break the only thing that makes it valid.
+  return formatValue(node) ?? draw.string(node);
+}
+
+/** The walk itself. Every choice the node leaves open is the draw's. */
+function sampleFor(node: SchemaNode, draw: Draw): unknown {
+  if (node.nullable === true && draw.nullable(node)) return null;
+  switch (node.kind) {
+    case 'string':
+      return sampleString(node, draw);
+    case 'number':
+      return draw.number(node);
+    case 'boolean':
+      return draw.boolean();
+    case 'date':
+      return BY_FORMAT['date-time'];
+    case 'enum':
+      return draw.member(node.values ?? []) ?? SAMPLE_STRING;
+    case 'literal':
+      return node.literal ?? null;
+    // Items are walked one by one, so a seeded draw varies them; the minimal one repeats.
+    case 'array':
+      return Array.from({ length: draw.items(node) }, () =>
+        node.items === undefined ? null : sampleFor(node.items, draw),
+      );
+    case 'union': {
+      const member = draw.member(node.anyOf ?? []);
+      return member === undefined ? null : sampleFor(member, draw);
+    }
+    case 'record':
+      return {};
+    case 'money':
+      return {
+        minor: draw.number({ kind: 'number', integer: true, minimum: 0, maximum: 1_000_000 }),
+        currency: 'USD',
+      };
+    case 'object':
+      return sampleObject(node, draw);
+    default:
+      // `unknown`, `json`, and any kind a third-party provider emits that this build has never
+      // heard of. Not `assertNever`: a swapped provider must not turn a contract test into a crash.
+      return null;
+  }
+}
+
+/**
+ * The minimal value `schema` accepts — best effort, and honest about it: a provider refinement the
+ * IR does not carry yields a value the schema rejects, which the caller reports as
+ * `X_CONTRACT_DRIFT`. The one constraint the IR DOES carry is `pattern`, and `sampleGaps` reads it.
+ */
+export function sampleInput(schema: StandardSchemaV1): unknown {
+  const node = tryIntrospect(schema);
+  return node === undefined ? {} : sampleFor(node, minimalDraw);
+}
+
+/** Where in the replayable sequence a value comes from: the caller's seed and the run index. */
+export interface ArbitraryOptions {
+  readonly seed: number;
+  readonly run: number;
+}
+
+/** A generated value under `schema`'s IR: the same `{ seed, run }`, the same value, every time. */
+export function arbitrary(schema: StandardSchemaV1, options: ArbitraryOptions): unknown {
+  const node = tryIntrospect(schema);
+  return node === undefined ? {} : sampleFor(node, seededDraw(options.seed, options.run));
+}
+
+/** The root's name in a gap path — a bare `t.string` input has no field to point at. */
+const ROOT_PATH = '(the input)';
+
+/**
+ * Dotted paths of every sampled field whose own `pattern` the minimal value cannot satisfy — what
+ * this schema needs that the framework cannot invent. It walks the SAMPLED shape, so an optional
+ * key, which the minimal sample omits, owes nothing.
+ */
+export function sampleGaps(schema: StandardSchemaV1): readonly string[] {
+  const node = tryIntrospect(schema);
+  return node === undefined ? [] : gapsIn(node, '');
+}
+
+function gapsIn(node: SchemaNode, path: string): string[] {
+  if (node.nullable === true) return [];
+  if (node.kind === 'object') {
+    const properties = node.properties ?? {};
+    const out: string[] = [];
+    for (const key of requiredKeys(node)) {
+      const child = Object.hasOwn(properties, key) ? properties[key] : undefined;
+      if (child !== undefined) out.push(...gapsIn(child, path === '' ? key : `${path}.${key}`));
+    }
+    return out;
+  }
+  const unbuildable = node.kind === 'array' && owedItems(node) === undefined;
+  if (!unbuildable && satisfiesPattern(node, sampleFor(node, minimalDraw))) return [];
+  return [path === '' ? ROOT_PATH : path];
+}
+
+/** `orderRef` -> `orderRef (must match ^ORD-\d{4}$)`, for a cause a reader can act on. */
+export function describeSampleGap(schema: StandardSchemaV1, path: string): string {
+  const node = nodeAt(tryIntrospect(schema), path);
+  if (node?.kind === 'array' && node.minItems !== undefined && owedItems(node) === undefined) {
+    return `${path} (needs at least ${node.minItems} items)`;
+  }
+  const pattern = node?.pattern;
+  return pattern === undefined ? path : `${path} (must match ${pattern})`;
+}
+
+function nodeAt(node: SchemaNode | undefined, path: string): SchemaNode | undefined {
+  if (node === undefined) return undefined;
+  if (path === '' || path === ROOT_PATH) return node;
+  const [head, ...rest] = path.split('.');
+  // `path` is the caller's, so the own-property read the format table takes.
+  const properties = node.properties ?? {};
+  const child =
+    head === undefined || !Object.hasOwn(properties, head) ? undefined : properties[head];
+  return child === undefined ? undefined : nodeAt(child, rest.join('.'));
+}

package/src/schema-rules.ts

@@ -0,0 +1,65 @@
+// Single responsibility: the closed vocabulary an issue's `rule` names, and the one reader that
+// lifts `rule`/`params` off an issue nobody in this process built. A translator keys on these, so
+// the values are contract like an `X_*` code: add one, never rename one.
+
+/** Every rule a builtin validator refuses with, in declaration order. */
+export const SCHEMA_RULES = /* @__PURE__ */ Object.freeze([
+  'required',
+  'type',
+  'string.min',
+  'string.max',
+  'string.pattern',
+  'string.format',
+  'number.min',
+  'number.max',
+  'number.integer',
+  'enum',
+  'literal',
+  'array.min',
+  'array.max',
+  'union',
+  'record.key',
+  'json',
+  'money',
+  'refine',
+] as const);
+
+export type SchemaRule = (typeof SCHEMA_RULES)[number];
+
+/**
+ * What a translator interpolates: `{ min: 3 }`, `{ format: 'uuid' }`. Scalars only, and only facts
+ * the schema author declared — never the rejected value, for `describe-value.ts`'s reason.
+ */
+export type SchemaIssueParams = Readonly<Record<string, string | number>>;
+
+/** The two members, as they ride beside `message` and `path`. Both absent for a foreign issue. */
+export interface IssueRuleFacts {
+  readonly rule?: string;
+  readonly params?: SchemaIssueParams;
+}
+
+const isScalar = (value: unknown): boolean =>
+  typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value));
+
+/**
+ * `rule` and `params` off an issue, member by member, never spread: the issue may be a foreign
+ * library's or a wire document's. A non-string `rule` is dropped, and `params` travels only beside
+ * a `rule` and only when EVERY value is a scalar — a partly-kept `params` is a sentence rendered
+ * with a hole in it. Total: a getter that throws is an issue with neither. Small on purpose: it is
+ * in every browser bundle that decodes a refusal.
+ */
+export function issueRuleFacts(issue: unknown): IssueRuleFacts {
+  try {
+    const { rule, params } = issue as { readonly rule?: unknown; readonly params?: unknown };
+    if (typeof rule !== 'string' || rule === '') return {};
+    // Object spread defines own properties, so a `__proto__` key stays a key.
+    return typeof params === 'object' &&
+      params !== null &&
+      !Array.isArray(params) &&
+      Object.values(params).every(isScalar)
+      ? { rule, params: { ...(params as SchemaIssueParams) } }
+      : { rule };
+  } catch {
+    return {};
+  }
+}

package/src/sensitive.ts

@@ -0,0 +1,137 @@
+// Single responsibility: the two readers of `.sensitive()` — the mask a walker that holds a schema
+// applies before writing a value down, and the refusal of a flag reachable from an output. Its own
+// file so `t`, which is in every bundle graph, carries neither.
+
+import { SensitiveOutputError } from './errors';
+import { isSchemaNode, type SchemaNode } from './node';
+import { tryIntrospect } from './provider';
+
+/** Whether anything under a node is flagged. Memoised per node: an unflagged action pays one read. */
+const flagged = new WeakMap<SchemaNode, boolean>();
+
+function children(node: SchemaNode): readonly SchemaNode[] {
+  return [
+    ...Object.values(node.properties ?? {}),
+    ...(node.items === undefined ? [] : [node.items]),
+    ...(node.valueNode === undefined ? [] : [node.valueNode]),
+    ...(node.anyOf ?? []),
+  ];
+}
+
+function holdsSensitive(node: SchemaNode): boolean {
+  const known = flagged.get(node);
+  if (known !== undefined) return known;
+  // Seeded false before the walk, so a node graph that reaches itself terminates.
+  flagged.set(node, false);
+  const answer = node.sensitive === true || children(node).some(holdsSensitive);
+  flagged.set(node, answer);
+  return answer;
+}
+
+function nodeFor(schema: unknown): SchemaNode | undefined {
+  if (isSchemaNode(schema)) return schema;
+  try {
+    return tryIntrospect(schema);
+  } catch {
+    return undefined;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** A shallow copy with the masked keys replaced — `defineProperty`, so `__proto__` stays a key. */
+function withKeys(value: Record<string, unknown>, masked: ReadonlyMap<string, unknown>) {
+  const out: Record<string, unknown> = {};
+  for (const [name, held] of Object.entries(value)) {
+    Object.defineProperty(out, name, {
+      value: masked.has(name) ? masked.get(name) : held,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return out;
+}
+
+function maskRecord(node: SchemaNode, value: Record<string, unknown>, replacement: string) {
+  const masked = new Map<string, unknown>();
+  for (const [key, child] of Object.entries(node.properties ?? {})) {
+    if (holdsSensitive(child) && Object.hasOwn(value, key)) {
+      masked.set(key, mask(child, value[key], replacement));
+    }
+  }
+  const entries = node.valueNode;
+  if (entries !== undefined && holdsSensitive(entries)) {
+    for (const [key, entry] of Object.entries(value)) {
+      masked.set(key, mask(entries, masked.has(key) ? masked.get(key) : entry, replacement));
+    }
+  }
+  return masked.size === 0 ? value : withKeys(value, masked);
+}
+
+function mask(node: SchemaNode, value: unknown, replacement: string): unknown {
+  if (!holdsSensitive(node) || value === undefined) return value;
+  if (node.sensitive === true) return replacement;
+  let out: unknown = value;
+  if (isRecord(out)) out = maskRecord(node, out, replacement);
+  const items = node.items;
+  if (items !== undefined && Array.isArray(out)) {
+    out = out.map((entry: unknown) => mask(items, entry, replacement));
+  }
+  // Every branch's mask, in turn, and no branch resolution: a value the walker misreads as the
+  // wrong branch must still lose the keys the right one flags. Fail closed.
+  for (const branch of node.anyOf ?? []) out = mask(branch, out, replacement);
+  return out;
+}
+
+/**
+ * `value` with every `.sensitive()` field `schema` reaches replaced by `replacement` — a copy,
+ * never an edit. The same reference back when nothing is flagged (or nothing can describe the
+ * schema), so the walk costs an unflagged action one map read.
+ *
+ * Reach: what the framework writes down from a value it holds WITH its schema — the audit record,
+ * `x jobs show`. Not an app's own log line: that carries no schema, and stays `redactKeys`.
+ */
+export function maskSensitive(schema: unknown, value: unknown, replacement: string): unknown {
+  const node = nodeFor(schema);
+  return node === undefined ? value : mask(node, value, replacement);
+}
+
+function sensitivePath(node: SchemaNode, at: string): string | undefined {
+  if (!holdsSensitive(node)) return undefined;
+  if (node.sensitive === true) return at;
+  for (const [key, child] of Object.entries(node.properties ?? {})) {
+    const found = sensitivePath(child, at === '' ? key : `${at}.${key}`);
+    if (found !== undefined) return found;
+  }
+  const nested = [
+    ...(node.items === undefined ? [] : [[node.items, `${at}[]`] as const]),
+    ...(node.valueNode === undefined ? [] : [[node.valueNode, `${at}{}`] as const]),
+    ...(node.anyOf ?? []).map((branch) => [branch, at] as const),
+  ];
+  for (const [child, path] of nested) {
+    const found = sensitivePath(child, path);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+/**
+ * Refuse a `.sensitive()` field reachable from an output — an action's `output`, a query's
+ * `rows`. An output leaves the server, which `writeOnly` forbids. A schema nothing can describe is
+ * passed: the check reads the IR, and a provider without one has no flag to find.
+ */
+export function assertNoSensitiveOutput(owner: string, schema: unknown): void {
+  const node = nodeFor(schema);
+  if (node === undefined) return;
+  const path = sensitivePath(node, '');
+  if (path === undefined) return;
+  const at = path === '' ? '(the root)' : path;
+  throw new SensitiveOutputError({
+    cause: `${owner} reaches the .sensitive() field ${at}, and an output is sent back to the caller`,
+    fix: `x verify   # after deleting .sensitive() at ${at} in ${owner}, or dropping that field from the output`,
+    meta: { owner, path: at },
+  });
+}

package/src/standard.ts

@@ -3,6 +3,7 @@
 // Zod and Valibot are all first-class without a line of adapter code.
 
 import { SchemaUnsupportedError, ValidationFailedError, type ValidationIssue } from './errors';
+import { issueRuleFacts, type SchemaIssueParams } from './schema-rules';
 
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
   readonly '~standard': StandardSchemaProps<Input, Output>;
@@ -39,6 +40,13 @@ export interface StandardPathSegment {
 export interface StandardIssue {
   readonly message: string;
   readonly path?: readonly (PropertyKey | StandardPathSegment)[] | undefined;
+  /**
+   * Ultimate's extension: which rule refused, from `SCHEMA_RULES` (`string.min`). Optional, since
+   * a conforming library has none — a translator keys on it, never on the English `message`.
+   */
+  readonly rule?: string | undefined;
+  /** The declared facts the rule names (`{ min: 3 }`), for the translator to interpolate. */
+  readonly params?: SchemaIssueParams | undefined;
 }
 
 export type InferInput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['input'];
@@ -93,6 +101,7 @@ export function toValidationIssues(issues: readonly StandardIssue[]): readonly V
     expected: issue.message,
     received: '',
     message: issue.message,
+    ...issueRuleFacts(issue),
   }));
 }