@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/fixture.js

@@ -0,0 +1,197 @@
+/**
+ * Schema-driven fixture generation: the discriminating cohort.
+ *
+ * Valid-random data cannot test a query engine: `ilike` needs a substring, `order` needs a total
+ * order, escaping needs metacharacters. The API tester seeds a *cohort* — one record per variant, each shaped
+ * so some query assertion has signal — and derives everything from a seed so a failing run is
+ * exactly reproducible.
+ *
+ * The values themselves come from `generate.ts`, the one place the API tester invents data, from the request
+ * schema as `spec/schema.ts` normalizes it. Every body is checked against that schema before it
+ * leaves; one that cannot be made valid is a gap naming the operation and the field, never a
+ * request the document forbids.
+ */
+import { identityNames } from "./accounts/identity.js";
+import { normalizeSchema } from "../spec/schema.js";
+import {} from "./generate/types.js";
+import { generate } from "./generate/generate.js";
+import { isVacuous } from "./generate/algebra.js";
+import { instanceErrors } from "./validate.js";
+import { messageOf } from "../errors/message.js";
+export { isVacuous } from "./generate/algebra.js";
+export const COHORT = [
+    "baseline",
+    "lexical-first",
+    "lexical-last",
+    "null-heavy",
+    "unicode",
+    "metacharacter",
+    "boundary",
+];
+/** Deterministic PRNG — same seed, same cohort, every run. */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Thrown when no valid body can be built for an operation. The pointer names the field; the
+ * reason says why — and the fix is `hooks.resolveInput`, which can supply what the schema cannot.
+ */
+export class FixtureOverflow extends Error {
+    operationId;
+    pointer;
+    reason;
+    constructor(operationId, pointer, reason) {
+        super(reason === undefined
+            ? `fixture generation overflow on ${operationId} (${pointer})`
+            : `cannot generate a valid body for ${operationId} at ${pointer}: ${reason} — supply one with hooks.resolveInput`);
+        this.operationId = operationId;
+        this.pointer = pointer;
+        this.reason = reason;
+        this.name = "FixtureOverflow";
+    }
+}
+export function overflowFrom(error, operationId, pointer = "/") {
+    if (error instanceof FixtureOverflow) {
+        return new FixtureOverflow(operationId, error.pointer === "/" ? pointer : error.pointer, error.reason);
+    }
+    return new FixtureOverflow(operationId, pointer);
+}
+export function isOverflowError(error) {
+    if (error instanceof FixtureOverflow)
+        return true;
+    return error instanceof RangeError;
+}
+export function ordinaryRequestSchema(schema) {
+    return typeof schema === "object" && schema !== null
+        ? normalizeSchema(schema, { direction: "request", ordinary: true })
+        : schema;
+}
+/* The request schema as generation reads it; one that cannot even be read is an overflow naming why. */
+function readable(schema, operationId) {
+    try {
+        return ordinaryRequestSchema(schema);
+    }
+    catch (error) {
+        throw new FixtureOverflow(operationId, "/", `the schema could not be read: ${messageOf(error)}`);
+    }
+}
+/** One body per variant, each valid for the schema — or a `FixtureOverflow` naming what is not. */
+export function buildCohort(bodySchema, seed, options = {}) {
+    const { operationId = "unknown", variants = COHORT } = options;
+    const schema = readable(bodySchema, operationId);
+    const distinct = new Set([...(options.distinct ?? []), ...identityNames(schema)]);
+    return variants.map((variant, index) => {
+        const result = generate(schema, {
+            ...(options.defs === undefined ? {} : { defs: options.defs }),
+            ...(distinct.size === 0 ? {} : { distinct }),
+            ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
+            index,
+            rand: mulberry32(seed + index * 7919),
+            variant,
+        });
+        if (!result.ok)
+            throw new FixtureOverflow(operationId, result.pointer, result.reason);
+        const body = isObject(result.value) ? result.value : {};
+        /* The self-check: a body the API tester invented must satisfy the document before it is sent. */
+        if (typeof schema === "object" && !isVacuous(schema)) {
+            const errors = instanceErrors(schema, body, options.defs);
+            if (errors.length > 0)
+                throw new FixtureOverflow(operationId, "/", errors.slice(0, 3).join("; "));
+        }
+        return { body, variant };
+    });
+}
+/**
+ * One body, with the required fields that could not be made rather than an exception — for
+ * callers that report each gap themselves. Optional fields that cannot be made are left out.
+ */
+export function generateBody(bodySchema, draw) {
+    const schema = ordinaryRequestSchema(bodySchema);
+    const { index, rand, variant } = draw;
+    const result = generate(schema, { index, rand, variant });
+    if (result.ok)
+        return { body: isObject(result.value) ? result.value : {}, missingRequired: [] };
+    /*
+     * Without the failing field, the rest may still be made: drop it from `required` and retry. Only a
+     * field this level declares can be dropped; one required through `allOf` would fail the same way
+     * on every retry. (A required field nothing declares is always made, so it never fails here.)
+     */
+    const field = result.pointer.split("/")[1];
+    if (field !== undefined &&
+        typeof schema === "object" &&
+        isObject(schema.properties) &&
+        Object.hasOwn(schema.properties, field)) {
+        const required = Array.isArray(schema.required) ? schema.required.filter((name) => name !== field) : [];
+        const properties = { ...schema.properties };
+        delete properties[field];
+        const rest = generateBody({ ...schema, properties, required }, draw);
+        return { body: rest.body, missingRequired: [result.pointer, ...rest.missingRequired] };
+    }
+    return { body: {}, missingRequired: [result.pointer] };
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function ensureDistinctUniqueValues(members, sets, { schema, ...options }) {
+    if (sets.length === 0 || members.length <= 1)
+        return { gap: null, members };
+    const normalized = ordinaryRequestSchema(schema);
+    const properties = typeof normalized === "object" && isObject(normalized.properties) ? normalized.properties : {};
+    const kept = [];
+    for (const member of members) {
+        const body = distinctBody(member, sets, { kept, options, properties });
+        if (body !== undefined)
+            kept.push({ body, variant: member.variant });
+    }
+    /* The first member is always kept: there is nothing before it to collide with. */
+    if (kept.length === members.length)
+        return { gap: null, members: kept };
+    return { gap: uniqueDistinctGap(sets), members: kept };
+}
+/** `member`'s body made distinct from every kept member on every set, or `undefined` if it cannot be. */
+function distinctBody(member, sets, redraw) {
+    const body = { ...member.body };
+    for (const set of sets) {
+        redrawSet(body, set, redraw);
+        if (collides(redraw.kept, body, set))
+            return undefined;
+    }
+    return body;
+}
+/** Redraws one column of `set` in `body`, at most 16 times, until no kept member shares its tuple. */
+function redrawSet(body, set, { kept, options, properties }) {
+    for (let attempt = 0; collides(kept, body, set) && attempt < 16; attempt++) {
+        const col = set.find((name) => Object.hasOwn(body, name) && isObject(properties[name]));
+        if (col === undefined)
+            return;
+        const redrawn = generate({ properties: { [col]: properties[col] }, required: [col], type: "object" }, {
+            ...(options.defs === undefined ? {} : { defs: options.defs }),
+            distinct: new Set([col]),
+            index: kept.length * 17 + attempt + 1,
+            nonce: `${options.nonce ?? ""}${attempt}`,
+        });
+        if (!redrawn.ok)
+            return;
+        body[col] = redrawn.value[col];
+    }
+}
+function collides(kept, body, set) {
+    return kept.some((prior) => sameUniqueTuple(prior.body, body, set));
+}
+function uniqueDistinctGap(sets) {
+    const shown = sets.map((set) => `[${set.join(", ")}]`).join("; ");
+    return `x-unique cannot express distinct values for ${shown} within the schema; extra variants skipped`;
+}
+function sameUniqueTuple(a, b, set) {
+    const cols = set.filter((col) => Object.hasOwn(a, col) || Object.hasOwn(b, col));
+    if (cols.length === 0)
+        return false;
+    return cols.every((col) => JSON.stringify(a[col]) === JSON.stringify(b[col]));
+}
+//# sourceMappingURL=fixture.js.map

package/dist/api/runtime/generate/algebra.d.ts

@@ -0,0 +1,14 @@
+/** Schema algebra: what a schema admits at a glance, and `allOf` folded into one schema. */
+import type { JsonSchema } from "../../spec/types.ts";
+export declare function isObject(value: unknown): value is JsonSchema;
+/** `{}`, `true`, or annotations alone: any value at all. */
+export declare function isVacuous(schema: unknown): boolean;
+/**
+ * Folds `base`'s `allOf` branches into one schema: properties merged, bounds intersected, every pattern kept. `pointer` is the
+ * value being generated, `path` the `allOf` within its schema; one that is not a list of schemas
+ * admits nothing anyone could construct.
+ */
+export declare function mergeAll(base: JsonSchema, pointer: string, path?: string): JsonSchema;
+export declare function merge(a: JsonSchema, b: JsonSchema): JsonSchema;
+export declare function typesOf(schema: JsonSchema): string[];
+//# sourceMappingURL=algebra.d.ts.map

package/dist/api/runtime/generate/algebra.js

@@ -0,0 +1,112 @@
+/** Schema algebra: what a schema admits at a glance, and `allOf` folded into one schema. */
+import { Unconstructible } from "./unconstructible.js";
+export function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const ANNOTATIONS = /* @__PURE__ */ new Set([
+    "description",
+    "title",
+    "deprecated",
+    "examples",
+    "readOnly",
+    "writeOnly",
+    "default",
+    "$comment",
+    "$schema",
+    "$id",
+    "$anchor",
+    "contentMediaType",
+    "contentEncoding",
+]);
+/** `{}`, `true`, or annotations alone: any value at all. */
+export function isVacuous(schema) {
+    if (schema === true)
+        return true;
+    if (!isObject(schema))
+        return false;
+    return Object.keys(schema).every((key) => ANNOTATIONS.has(key) || key.startsWith("x-"));
+}
+/**
+ * Folds `base`'s `allOf` branches into one schema: properties merged, bounds intersected, every pattern kept. `pointer` is the
+ * value being generated, `path` the `allOf` within its schema; one that is not a list of schemas
+ * admits nothing anyone could construct.
+ */
+export function mergeAll(base, pointer, path = "allOf") {
+    const branches = base.allOf;
+    if (!Array.isArray(branches))
+        throw new Unconstructible(`${path} is not a list of schemas`, pointer);
+    let out = { ...base };
+    delete out.allOf;
+    for (const [index, branch] of branches.entries()) {
+        if (!isObject(branch))
+            continue;
+        const nested = branch.allOf === undefined ? branch : mergeAll(branch, pointer, `${path}/${index}/allOf`);
+        out = merge(out, nested);
+    }
+    return out;
+}
+const larger = (existing, value) => Math.max(Number(existing), Number(value));
+const smaller = (existing, value) => Math.min(Number(existing), Number(value));
+function bothTypes(existing, value) {
+    const left = Array.isArray(existing) ? existing : [existing];
+    const right = Array.isArray(value) ? value : [value];
+    const both = left.filter((type) => right.includes(type) || (type === "integer" && right.includes("number")));
+    return both.length === 1 ? both[0] : both;
+}
+/** How a keyword both schemas set combines; any other keyword merges as a schema or is overwritten. */
+const COMBINE = {
+    enum: (existing, value) => existing.filter((item) => value.some((other) => JSON.stringify(other) === JSON.stringify(item))),
+    exclusiveMaximum: smaller,
+    exclusiveMinimum: larger,
+    maxItems: smaller,
+    maxLength: smaller,
+    maximum: smaller,
+    minItems: larger,
+    minLength: larger,
+    minimum: larger,
+    properties: (existing, value) => ({ ...existing, ...value }),
+    required: (existing, value) => [...new Set([...existing, ...value])],
+    type: bothTypes,
+};
+/* Two patterns both hold, and one schema object holds one `pattern`: a second one is carried as an `allOf` branch. */
+function withPattern(out, pattern) {
+    const residual = Array.isArray(out.allOf) ? out.allOf : [];
+    if (out.pattern === pattern || residual.some((branch) => isObject(branch) && branch.pattern === pattern))
+        return;
+    out.allOf = [...residual, { pattern }];
+}
+export function merge(a, b) {
+    const out = { ...a };
+    for (const [key, value] of Object.entries(b)) {
+        const existing = out[key];
+        if (existing === undefined) {
+            out[key] = value;
+            continue;
+        }
+        if (key === "pattern")
+            withPattern(out, value);
+        else if (key === "allOf" && Array.isArray(existing) && Array.isArray(value))
+            out.allOf = [...existing, ...value];
+        else if (Object.hasOwn(COMBINE, key))
+            out[key] = COMBINE[key](existing, value);
+        else
+            out[key] = isObject(existing) && isObject(value) ? merge(existing, value) : value;
+    }
+    return out;
+}
+export function typesOf(schema) {
+    const type = schema.type;
+    if (typeof type === "string")
+        return [type];
+    if (Array.isArray(type))
+        return type.filter((item) => typeof item === "string");
+    if (schema.properties !== undefined || schema.required !== undefined)
+        return ["object"];
+    if (schema.items !== undefined || schema.prefixItems !== undefined)
+        return ["array"];
+    if (["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"].some((k) => k in schema)) {
+        return ["number"];
+    }
+    return ["string"];
+}
+//# sourceMappingURL=algebra.js.map

package/dist/api/runtime/generate/array.d.ts

@@ -0,0 +1,4 @@
+import type { JsonSchema } from "../../spec/types.ts";
+import type { At, Walk } from "./types.ts";
+export declare function arrayFor(schema: JsonSchema, at: At, walk: Walk): unknown[];
+//# sourceMappingURL=array.d.ts.map

package/dist/api/runtime/generate/array.js

@@ -0,0 +1,45 @@
+import { Unconstructible } from "./unconstructible.js";
+function itemBounds(schema, pointer) {
+    const min = typeof schema.minItems === "number" ? schema.minItems : 0;
+    const max = typeof schema.maxItems === "number" ? schema.maxItems : Number.POSITIVE_INFINITY;
+    if (min > max)
+        throw new Unconstructible(`minItems ${min} exceeds maxItems ${max}`, pointer);
+    return { max, min };
+}
+export function arrayFor(schema, at, walk) {
+    const { ctx, pointer } = at;
+    const { min, max } = itemBounds(schema, pointer);
+    const prefix = Array.isArray(schema.prefixItems) ? schema.prefixItems : [];
+    const out = prefix.map((item, position) => walk(item, { ctx: { ...ctx, index: ctx.index + position }, distinct: false, pointer: `${pointer}/${position}` }));
+    /* One element where the schema allows it: an empty array fails `minItems` on exactly the
+     * collections most worth testing, and one element is what a cohort needs to filter on. */
+    const want = Math.min(Math.max(min, prefix.length, 1), max);
+    const items = schema.items;
+    if (items === false || out.length >= want)
+        return out;
+    const seen = new Set(out.map((value) => JSON.stringify(value)));
+    for (let attempt = 0; out.length < want && attempt < want + 8; attempt++) {
+        let value;
+        try {
+            value = walk(items ?? true, {
+                ctx: { ...ctx, index: ctx.index + attempt },
+                distinct: false,
+                pointer: `${pointer}/${out.length}`,
+            });
+        }
+        catch (error) {
+            if (error instanceof Unconstructible && out.length >= min)
+                break;
+            throw error;
+        }
+        const key = JSON.stringify(value);
+        if (schema.uniqueItems === true && seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(value);
+    }
+    if (out.length < min)
+        throw new Unconstructible(`cannot make ${min} distinct items`, pointer);
+    return out;
+}
+//# sourceMappingURL=array.js.map

package/dist/api/runtime/generate/branches.d.ts

@@ -0,0 +1,12 @@
+/** The keywords that pick among schemas: a `$ref` into the document's defs, a union, an enum. */
+import type { JsonSchema } from "../../spec/types.ts";
+import type { At, Context, Walk } from "./types.ts";
+/** The value `schema.$ref` names, with the schema's sibling keywords applied. */
+export declare function viaRef(schema: JsonSchema, at: At, walk: Walk): unknown;
+/**
+ * A union keeps its base: `{properties: {kind}, oneOf: [...]}` needs `kind` whichever branch. The
+ * index picks the branch to start from, as it picks an enum value, so a cohort makes every branch.
+ */
+export declare function unionOf(schema: JsonSchema, at: At, walk: Walk): unknown;
+export declare function enumOf(values: unknown[], ctx: Context, pointer: string): unknown;
+//# sourceMappingURL=branches.d.ts.map

package/dist/api/runtime/generate/branches.js

@@ -0,0 +1,63 @@
+/** The keywords that pick among schemas: a `$ref` into the document's defs, a union, an enum. */
+import { DEFS_ID } from "../../spec/load/defs.js";
+import { isObject, merge } from "./algebra.js";
+import { Unconstructible } from "./unconstructible.js";
+/** How many times one recursive schema may nest inside itself before generation stops descending. */
+const RECURSION_BOUND = 2;
+/** The value `schema.$ref` names, with the schema's sibling keywords applied. */
+export function viaRef(schema, at, walk) {
+    const { ctx, pointer } = at;
+    const ref = schema.$ref;
+    const name = ref.startsWith(`${DEFS_ID}#/$defs/`) ? ref.slice(`${DEFS_ID}#/$defs/`.length) : undefined;
+    const target = name === undefined ? undefined : ctx.defs[name];
+    if (name === undefined || target === undefined) {
+        throw new Unconstructible(`cannot follow ${ref}`, pointer);
+    }
+    if (ctx.refs.filter((seen) => seen === name).length >= RECURSION_BOUND) {
+        throw new Unconstructible(`recursion through ${name} is bounded at depth ${RECURSION_BOUND}`, pointer);
+    }
+    const { $ref: _ref, ...siblings } = schema;
+    const inner = { ...ctx, refs: [...ctx.refs, name] };
+    return walk(Object.keys(siblings).length === 0 ? target : merge(target, siblings), { ...at, ctx: inner });
+}
+const isNull = (branch) => isObject(branch) && branch.type === "null";
+/**
+ * A union keeps its base: `{properties: {kind}, oneOf: [...]}` needs `kind` whichever branch. The
+ * index picks the branch to start from, as it picks an enum value, so a cohort makes every branch.
+ */
+export function unionOf(schema, at, walk) {
+    const union = (schema.oneOf ?? schema.anyOf);
+    const { oneOf: _o, anyOf: _a, ...base } = schema;
+    if (at.ctx.variant === "null-heavy" && union.some(isNull))
+        return null;
+    const options = union.filter((candidate) => !isNull(candidate));
+    /* With no options the start is NaN, and `slice` reads NaN as 0. */
+    const start = at.ctx.index % options.length;
+    const failures = [];
+    for (const branch of [...options.slice(start), ...options.slice(0, start)]) {
+        const candidate = isObject(branch) ? merge(base, branch) : branch;
+        try {
+            return walk(candidate, at);
+        }
+        catch (error) {
+            if (!(error instanceof Unconstructible))
+                throw error;
+            failures.push(error.reason);
+        }
+    }
+    if (union.some(isNull))
+        return null;
+    throw new Unconstructible(`no branch of the union can be generated: ${failures.join("; ")}`, at.pointer);
+}
+export function enumOf(values, ctx, pointer) {
+    const options = values.filter((item) => item !== null);
+    if (ctx.variant === "null-heavy" && values.includes(null))
+        return null;
+    if (options.length === 0) {
+        if (values.includes(null))
+            return null;
+        throw new Unconstructible("the enum is empty", pointer);
+    }
+    return options[ctx.index % options.length];
+}
+//# sourceMappingURL=branches.js.map

package/dist/api/runtime/generate/expand.d.ts

@@ -0,0 +1,3 @@
+/** Expands the common regex subset — classes, escapes, quantifiers, groups — to one example. */
+export declare function expand(pattern: string, index: number): string | undefined;
+//# sourceMappingURL=expand.d.ts.map

package/dist/api/runtime/generate/expand.js

@@ -0,0 +1,66 @@
+/** Expands the common regex subset — classes, escapes, quantifiers, groups — to one example. */
+function classAtom(source, index) {
+    const close = source.indexOf("]", 1);
+    if (close < 0)
+        return undefined;
+    const body = source.slice(1, close).replace(/^\^/, "");
+    let atom = body.startsWith("\\d") ? String(index % 10) : body.startsWith("\\w") ? "a" : (body[0] ?? "a");
+    /* A range: its first character, which is there since the dash follows it. */
+    if (body[1] === "-" && body[2] !== undefined)
+        atom = body[0];
+    return { atom, rest: source.slice(close + 1) };
+}
+function escapeAtom(source, index) {
+    const next = source[1] ?? "";
+    const atom = next === "d" ? String(index % 10) : next === "w" ? "a" : next === "s" ? " " : next;
+    return { atom, rest: source.slice(2) };
+}
+function groupAtom(source, index) {
+    const close = source.indexOf(")");
+    if (close < 0)
+        return undefined;
+    /* `split` always yields at least one alternative. */
+    const inner = source.slice(1, close).replace(/^\?:/, "").split("|")[0];
+    return { atom: expand(inner, index) ?? "", rest: source.slice(close + 1) };
+}
+/** The next atom; `undefined` for a pattern this cannot expand, `null` where the expansion stops. */
+function atomAt(source, index) {
+    const ch = source[0];
+    if (ch === "[")
+        return classAtom(source, index);
+    if (ch === "\\")
+        return escapeAtom(source, index);
+    if (ch === "(")
+        return groupAtom(source, index);
+    if (ch === ".")
+        return { atom: "a", rest: source.slice(1) };
+    if (ch === "|" || ch === ")")
+        return null;
+    return { atom: ch, rest: source.slice(1) };
+}
+function quantity(source) {
+    const q = source[0];
+    if (q === "+" || q === "*" || q === "?")
+        return { count: q === "+" ? 2 : 1, rest: source.slice(1) };
+    const braces = /^\{(\d+)(,(\d*))?\}/.exec(source);
+    if (braces !== null)
+        return { count: Number(braces[1]), rest: source.slice(braces[0].length) };
+    return { count: 1, rest: source };
+}
+export function expand(pattern, index) {
+    let source = pattern.replace(/^\^/, "").replace(/\$$/, "");
+    let out = "";
+    let guard = 0;
+    while (source.length > 0 && guard++ < 512) {
+        const step = atomAt(source, index);
+        if (step === undefined)
+            return undefined;
+        if (step === null)
+            break;
+        const repeat = quantity(step.rest);
+        source = repeat.rest;
+        out += step.atom.repeat(repeat.count);
+    }
+    return out;
+}
+//# sourceMappingURL=expand.js.map

package/dist/api/runtime/generate/format.d.ts

@@ -0,0 +1,7 @@
+/** A value for each string `format` the API tester knows, deterministic in the variant, index and nonce. */
+import type { Context } from "./types.ts";
+/** A deterministic v4-shaped UUID from a salt. */
+export declare function uuidFrom(salt: string): string;
+/** A value for each `format` the API tester knows; `undefined` for one it does not. */
+export declare function formatted(format: string, ctx: Context, distinct: boolean): string | undefined;
+//# sourceMappingURL=format.d.ts.map

package/dist/api/runtime/generate/format.js

@@ -0,0 +1,61 @@
+/** A value for each string `format` the API tester knows, deterministic in the variant, index and nonce. */
+import { slug } from "./text.js";
+/** A deterministic v4-shaped UUID from a salt. */
+export function uuidFrom(salt) {
+    let h = 0x811c9dc5;
+    const hex = [];
+    for (let round = 0; hex.join("").length < 32; round++) {
+        for (const ch of `${salt}:${round}`)
+            h = Math.imul(h ^ ch.charCodeAt(0), 0x01000193) >>> 0;
+        hex.push(h.toString(16).padStart(8, "0"));
+    }
+    const s = hex.join("").slice(0, 32);
+    /* Four rounds of eight hex digits: the string is 32 long, so position 16 is there. */
+    const variant = "89ab"[Number.parseInt(s[16], 16) % 4];
+    return `${s.slice(0, 8)}-${s.slice(8, 12)}-4${s.slice(13, 16)}-${variant}${s.slice(17, 20)}-${s.slice(20, 32)}`;
+}
+function pad(n) {
+    return String(n).padStart(2, "0");
+}
+function partsOf(ctx, distinct) {
+    const i = ctx.index;
+    const first = ctx.variant === "lexical-first" || ctx.variant === "boundary";
+    const last = ctx.variant === "lexical-last";
+    const year = first ? 2000 : last ? 2099 : 2024;
+    const month = first ? 1 : last ? 12 : (i % 12) + 1;
+    const day = first ? 1 : last ? 28 : (i % 28) + 1;
+    return {
+        date: `${year}-${pad(month)}-${pad(day)}`,
+        i,
+        salt: `${ctx.variant}:${i}${distinct ? `:${ctx.nonce ?? ""}` : ""}`,
+        slug: slug(ctx.variant),
+        tail: distinct && ctx.nonce !== undefined ? `-${ctx.nonce}` : "",
+        time: `${pad(10 + (i % 12))}:${pad((i * 7) % 60)}:00Z`,
+    };
+}
+const email = (p) => `testing-${p.slug}-${p.i}${p.tail}@example.test`;
+const uri = (p) => `https://example.test/${p.slug}-${p.i}${p.tail}`;
+const hostname = (p) => `host-${p.i}${p.tail}.example.test`;
+const FORMATS = {
+    byte: (p) => Buffer.from(`testing ${p.i}`).toString("base64"),
+    date: (p) => p.date,
+    "date-time": (p) => `${p.date}T${p.time}`,
+    email,
+    hostname,
+    "idn-email": email,
+    "idn-hostname": hostname,
+    ipv4: (p) => `192.0.2.${(p.i % 250) + 1}`,
+    ipv6: (p) => `2001:db8::${(p.i % 250) + 1}`,
+    iri: uri,
+    "iri-reference": uri,
+    time: (p) => p.time,
+    uri,
+    "uri-reference": uri,
+    url: uri,
+    uuid: (p) => uuidFrom(p.salt),
+};
+/** A value for each `format` the API tester knows; `undefined` for one it does not. */
+export function formatted(format, ctx, distinct) {
+    return Object.hasOwn(FORMATS, format) ? FORMATS[format](partsOf(ctx, distinct)) : undefined;
+}
+//# sourceMappingURL=format.js.map

package/dist/api/runtime/generate/generate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Values from schemas — the one place the API tester invents data.
+ *
+ * Seeding a cohort and probing a check both need values: a record to create, a second value to
+ * patch to, an identifier that is well-formed and absent, a value just outside an enum. They used
+ * to be invented in two places plus a dozen string literals in the checks (`"the API tester patched value"`,
+ * `"<id>-testing-absent"`), and the literals were wrong exactly where it mattered: not a UUID where the
+ * API takes UUIDs, not a date where it takes dates. Everything comes from here now, from the
+ * normalized schema (see `spec/schema.ts`), and anything that cannot be constructed says so rather
+ * than sending something the document forbids.
+ *
+ * Generation is deterministic in its inputs. Distinctness across runs comes from a per-run nonce,
+ * never from suffix arithmetic that ignores `maximum`, `multipleOf`, `enum` or `format`.
+ */
+import type { GenerateOptions, Generated } from "./types.ts";
+/** One value valid for `schema`, or why none can be made. */
+export declare function generate(schema: unknown, options?: GenerateOptions): Generated;
+//# sourceMappingURL=generate.d.ts.map

package/dist/api/runtime/generate/generate.js

@@ -0,0 +1,43 @@
+/**
+ * Values from schemas — the one place the API tester invents data.
+ *
+ * Seeding a cohort and probing a check both need values: a record to create, a second value to
+ * patch to, an identifier that is well-formed and absent, a value just outside an enum. They used
+ * to be invented in two places plus a dozen string literals in the checks (`"the API tester patched value"`,
+ * `"<id>-testing-absent"`), and the literals were wrong exactly where it mattered: not a UUID where the
+ * API takes UUIDs, not a date where it takes dates. Everything comes from here now, from the
+ * normalized schema (see `spec/schema.ts`), and anything that cannot be constructed says so rather
+ * than sending something the document forbids.
+ *
+ * Generation is deterministic in its inputs. Distinctness across runs comes from a per-run nonce,
+ * never from suffix arithmetic that ignores `maximum`, `multipleOf`, `enum` or `format`.
+ */
+import { instance } from "./instance.js";
+import { Unconstructible } from "./unconstructible.js";
+import { messageOf } from "../../errors/message.js";
+/** One value valid for `schema`, or why none can be made. */
+export function generate(schema, options = {}) {
+    const ctx = {
+        defs: options.defs ?? {},
+        depth: 0,
+        distinct: options.distinct ?? new Set(),
+        index: options.index ?? 0,
+        nonce: options.nonce,
+        optional: options.optional ?? "all",
+        rand: options.rand ?? (() => 0.5),
+        refs: [],
+        variant: options.variant ?? "baseline",
+    };
+    try {
+        return { ok: true, value: instance(schema, { ctx, distinct: false, pointer: "" }) };
+    }
+    catch (error) {
+        if (error instanceof Unconstructible)
+            return { ok: false, pointer: error.pointer || "/", reason: error.reason };
+        if (error instanceof RangeError)
+            return { ok: false, pointer: "/", reason: "the schema nests too deeply to generate" };
+        /* Anything else is a schema generation could not even read: a reason, never a crash. */
+        return { ok: false, pointer: "/", reason: `generation failed: ${messageOf(error)}` };
+    }
+}
+//# sourceMappingURL=generate.js.map