@amritk/generate-examples 0.4.4 → 0.5.0

package/README.md

@@ -32,8 +32,11 @@ An `index.ts` barrel re-exports everything.
 
 > [!NOTE]
 > The generated arbitraries import `fast-check`, so consumers need it installed
-> (`npm i -D fast-check`). The static `fooExample` values have no runtime
-> dependencies.
+> (`npm i -D fast-check`). An arbitrary whose schema uses a keyword no `fc.*`
+> combinator captures on its own (`if`/`then`/`else`, `not`, exclusive `oneOf`,
+> and the presence-gated object keywords) also imports `@amritk/runtime-validators`
+> for a post-generation validating filter; files that need no such filter don't.
+> The static `fooExample` values have no runtime dependencies.
 
 ---
 
@@ -125,10 +128,14 @@ const res = await fetch('/users', { method: 'POST', body: JSON.stringify(userExa
 `required`, `items`, `minItems`/`maxItems`, `uniqueItems`,
 `minLength`/`maxLength`, `pattern`, `format` (`email`, `uuid`, `uri`/`url`,
 `date`, `date-time`, `time`, `hostname`, `ipv4`, `ipv6`), `minimum`/`maximum`,
-`exclusiveMinimum`/`exclusiveMaximum`, `multipleOf`, `enum`, `const`,
-`oneOf`/`anyOf`, `$ref`, and the `x-mjst` extension (`Date`, `bigint`).
-Unsupported constructs degrade to `fc.anything()` in arbitraries and `null` in
-static examples.
+`exclusiveMinimum`/`exclusiveMaximum`, `multipleOf`, `enum` (filtered by sibling
+constraints), `const`, `minProperties`/`maxProperties`, `patternProperties`,
+`propertyNames`, `dependentRequired`, `dependentSchemas`, `contains`,
+`oneOf`/`anyOf`, `if`/`then`/`else`, `not`, `$ref`, and the `x-mjst` extension
+(`Date`, `bigint`). `if`/`then`/`else`, `not`, and `oneOf` exclusivity are
+enforced by validating generated candidates against the schema and
+retrying/rejecting. Unsupported constructs degrade to `fc.anything()` in
+arbitraries and `null` in static examples.
 
 > [!TIP]
 > A static example constrained only by `pattern` is not guaranteed to match the

package/dist/generators/build-schema.js

@@ -1,5 +1,6 @@
 import { generateIndexBarrel } from '@amritk/helpers/generate-index-barrel';
 import { walkRefGraph } from '@amritk/helpers/walk-ref-graph';
+import { findSchemaCycles } from './find-schema-cycles.js';
 import { generateExampleFile } from './generate-files.js';
 /**
  * Builds all TypeScript example files from a JSON Schema by traversing all
@@ -27,15 +28,22 @@ import { generateExampleFile } from './generate-files.js';
  */
 export const buildExampleSchema = async (rootSchema, rootTypeName, typeSuffix = '') => {
     const files = [];
+    // Cross-file `$ref` cycles (A→B→A across modules) must emit lazy references
+    // for their cycle edges; eager top-level references would crash with a
+    // circular-ESM TDZ error at import. Detect the cycles up front so each file
+    // knows which siblings to defer.
+    const cycles = findSchemaCycles(rootSchema, rootTypeName, typeSuffix);
     walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
         // `index` is reserved for the barrel below, so never let a definition of
         // that name overwrite it.
         if (node.filename === 'index')
             return;
+        const lazyRefFilenames = cycles.get(node.filename);
         const content = generateExampleFile(node.schema, node.typeName, {
             rootSchema: node.rootSchema,
             typeSuffix,
             ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
+            ...(lazyRefFilenames !== undefined ? { lazyRefFilenames } : {}),
         });
         files.push({ filename: `${node.filename}.ts`, content });
     });

package/dist/generators/collect-example-imports.js

@@ -1,7 +1,7 @@
 import { refToFilename } from '@amritk/helpers/ref-to-filename';
 import { refToName } from '@amritk/helpers/ref-to-name';
 import { resolveRef } from '@amritk/helpers/resolve-ref';
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasItems, hasOneOf, hasRef } from '@amritk/helpers/schema-guards';
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasOneOf, hasProperties, hasRef, isSchemaObject, } from '@amritk/helpers/schema-guards';
 /**
  * Generates an import statement for a single $ref, importing both the generated
  * type and its arbitrary from the ref's generated file.
@@ -13,43 +13,54 @@ const buildImport = (ref, suffix) => {
     return `import { type ${typeName}, ${typeName}Arbitrary } from './${filename}.js'`;
 };
 /**
- * Walks one level of the schema and yields all direct $ref strings that should
- * become imports: properties, additionalProperties, items, and union branches.
+ * Recursively collects every `$ref` string reachable through the schema surface
+ * that the type and arbitrary generators traverse. A generated file's single
+ * import block must cover every ref those generators emit, so this walks the
+ * *same* nested surface `arbitraryExpr` (generate-arbitrary.ts) descends into —
+ * combinator branches, object `properties`/`patternProperties`/
+ * `additionalProperties`, and array `items`/`prefixItems` (both the single-schema
+ * and tuple array forms) — not just the top level. Missing any of these emits a
+ * bare `XxxArbitrary` identifier (or a bare `Xxx` type) with no matching import,
+ * producing TypeScript that fails to compile.
+ *
+ * `$ref` nodes short-circuit (matching `arbitraryExpr`, which resolves a `$ref`
+ * and ignores sibling keywords), so recursion is bounded by the schema's own
+ * structural nesting and cannot loop on a self-referential ref.
  */
-const collectDirectRefs = (schema) => {
-    if (typeof schema === 'boolean' || schema === null)
+const collectRefs = (schema) => {
+    if (!isSchemaObject(schema))
         return [];
+    if (hasRef(schema))
+        return [schema.$ref];
     const refs = [];
-    if (hasRef(schema)) {
-        refs.push(schema.$ref);
-        return refs;
-    }
-    const propSchemas = 'properties' in schema && typeof schema.properties === 'object' && schema.properties !== null
-        ? Object.values(schema.properties)
-        : [];
-    for (const prop of propSchemas) {
-        if (hasRef(prop))
-            refs.push(prop.$ref);
-        if (hasItems(prop) && hasRef(prop.items))
-            refs.push(prop.items.$ref);
-        if (hasAdditionalProperties(prop) && hasRef(prop.additionalProperties)) {
-            refs.push(prop.additionalProperties.$ref);
-        }
-    }
-    if (hasItems(schema) && hasRef(schema.items)) {
-        refs.push(schema.items.$ref);
-    }
-    if (hasAdditionalProperties(schema) && hasRef(schema.additionalProperties)) {
-        refs.push(schema.additionalProperties.$ref);
+    const visit = (sub) => {
+        refs.push(...collectRefs(sub));
+    };
+    if (hasOneOf(schema))
+        schema.oneOf.forEach(visit);
+    if (hasAnyOf(schema))
+        schema.anyOf.forEach(visit);
+    if (hasAllOf(schema))
+        schema.allOf.forEach(visit);
+    if (hasProperties(schema))
+        Object.values(schema.properties).forEach(visit);
+    const raw = schema;
+    const patternProperties = raw['patternProperties'];
+    if (typeof patternProperties === 'object' && patternProperties !== null) {
+        Object.values(patternProperties).forEach(visit);
     }
-    for (const branch of [
-        ...(hasOneOf(schema) ? schema.oneOf : []),
-        ...(hasAnyOf(schema) ? schema.anyOf : []),
-        ...(hasAllOf(schema) ? schema.allOf : []),
-    ]) {
-        if (hasRef(branch))
-            refs.push(branch.$ref);
+    if (hasAdditionalProperties(schema) && isSchemaObject(schema.additionalProperties)) {
+        visit(schema.additionalProperties);
     }
+    const prefixItems = raw['prefixItems'];
+    if (Array.isArray(prefixItems))
+        prefixItems.forEach(visit);
+    const items = raw['items'];
+    // `items` is either a tuple (draft-07 array form) or a single item schema.
+    if (Array.isArray(items))
+        items.forEach(visit);
+    else if (isSchemaObject(items))
+        visit(items);
     return refs;
 };
 /**
@@ -67,7 +78,7 @@ export const collectExampleImports = (schema, options) => {
     const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
     const rootSchema = options?.rootSchema;
     const typeSuffix = options?.typeSuffix ?? '';
-    const refs = collectDirectRefs(schema);
+    const refs = collectRefs(schema);
     const seen = new Set();
     const imports = [];
     for (const ref of refs) {

package/dist/generators/derive-example.js

@@ -1,6 +1,7 @@
 import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension';
 import { resolveRef } from '@amritk/helpers/resolve-ref';
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasDefault, hasEnum, hasExamples, hasExclusiveMaximum, hasExclusiveMinimum, hasFormat, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMinProperties, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasDefault, hasDependentRequired, hasDependentSchemas, hasEnum, hasExamples, hasExclusiveMaximum, hasExclusiveMinimum, hasFormat, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMaxProperties, hasMinItems, hasMinimum, hasMinLength, hasMinProperties, hasMultipleOf, hasOneOf, hasPattern, hasPatternProperties, hasProperties, hasPropertyNames, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { makeInstanceCheck, needsValidationFilter } from './schema-validation.js';
 /** Lowercases the first character of a name. e.g. "User" → "user" */
 const lowerFirst = (name) => name.charAt(0).toLowerCase() + name.slice(1);
 /** Derives the example const name from a type name. e.g. "User" → "userExample" */
@@ -220,6 +221,16 @@ const exampleString = (schema) => {
  * pattern — use the generated arbitrary when pattern fidelity matters.
  */
 export const deriveExample = (schema, rootSchema, seen = new Set()) => {
+    if (!isSchemaObject(schema))
+        return null;
+    const base = deriveBase(schema, rootSchema, seen);
+    // Keywords the structural deriver can't fully honour (`if`/`then`/`else`,
+    // `not`, `oneOf` exclusivity) are reconciled by validating candidates against a
+    // real validator and picking the first that passes.
+    return needsValidationFilter(schema) ? refineExample(schema, base, rootSchema, seen) : base;
+};
+/** Structural derivation for a node, before any validating refinement. */
+const deriveBase = (schema, rootSchema, seen) => {
     if (!isSchemaObject(schema))
         return null;
     if (hasConst(schema))
@@ -267,6 +278,50 @@ export const deriveExample = (schema, rootSchema, seen = new Set()) => {
     }
     return null;
 };
+/** The applicator keywords whose satisfaction is reconciled by {@link refineExample}. */
+const REFINED_APPLICATORS = ['if', 'then', 'else', 'not', 'oneOf'];
+/** A shallow copy of `schema` with the refined applicator keywords removed. */
+const structuralOnly = (schema) => {
+    const clone = { ...schema };
+    for (const key of REFINED_APPLICATORS)
+        delete clone[key];
+    return clone;
+};
+/**
+ * Reconciles keywords the structural deriver can't satisfy on its own
+ * (`if`/`then`/`else`, `not`, `oneOf` exclusivity). It validates the structural
+ * `base` against the full schema and, if it fails, tries alternative candidates —
+ * each `oneOf` branch, and the `then`/`else` branches merged with the structural
+ * siblings — returning the first that validates. Falls back to `base` when none
+ * do (a best-effort for schemas that can't be satisfied structurally, e.g. an
+ * adversarial `not`).
+ */
+const refineExample = (schema, base, rootSchema, seen) => {
+    const check = makeInstanceCheck(schema, rootSchema);
+    if (check(base))
+        return base;
+    const raw = schema;
+    const structural = structuralOnly(schema);
+    const combine = (branch) => deriveExample({ allOf: [structural, branch] }, rootSchema, seen);
+    const candidates = [];
+    if (hasOneOf(schema)) {
+        for (const branch of schema.oneOf)
+            if (branch !== undefined)
+                candidates.push(combine(branch));
+    }
+    if ('if' in raw) {
+        if (raw['then'] !== undefined)
+            candidates.push(combine(raw['then']));
+        if (raw['else'] !== undefined)
+            candidates.push(combine(raw['else']));
+        // `if` failing (so neither `then` nor a matched `else` applies) is also valid.
+        candidates.push(deriveExample(structural, rootSchema, seen));
+    }
+    for (const candidate of candidates)
+        if (check(candidate))
+            return candidate;
+    return base;
+};
 /**
  * True when a candidate value (e.g. an `enum`/`const` member) satisfies the
  * node's simple string-length and numeric-range constraints. Used to pick an
@@ -307,40 +362,164 @@ const deriveForType = (type, schema, rootSchema, seen) => {
             return null;
         case 'array':
             return deriveArray(schema, rootSchema, seen);
-        case 'object': {
-            const out = {};
-            if (hasProperties(schema)) {
-                for (const [key, propSchema] of Object.entries(schema.properties)) {
-                    out[key] = deriveExample(propSchema, rootSchema, seen);
-                }
-            }
-            const additional = hasAdditionalProperties(schema) ? schema.additionalProperties : false;
-            const additionalSchema = isSchemaObject(additional) ? additional : undefined;
-            // Extra keys are allowed unless `additionalProperties: false` forbids them.
-            const extrasAllowed = !(hasAdditionalProperties(schema) && schema.additionalProperties === false);
-            // A required key with no `properties` entry still needs a value. Use the
-            // `additionalProperties` schema when one constrains it, else a null.
-            if (hasRequired(schema)) {
-                for (const key of schema.required) {
-                    if (key in out)
-                        continue;
-                    out[key] = additionalSchema ? deriveExample(additionalSchema, rootSchema, seen) : null;
-                }
+        case 'object':
+            return deriveObject(schema, rootSchema, seen);
+        default:
+            return null;
+    }
+};
+/**
+ * Builds an object value honouring `properties`/`required`/`additionalProperties`
+ * plus the presence-gated and key-shaped keywords: `patternProperties` and
+ * `additionalProperties` pick the value schema for synthesized keys,
+ * `propertyNames` constrains those keys, `dependentRequired`/`dependentSchemas`
+ * add keys once their trigger is present, and `minProperties`/`maxProperties`
+ * bound the key count.
+ */
+const deriveObject = (schema, rootSchema, seen) => {
+    const out = {};
+    const patternEntries = hasPatternProperties(schema)
+        ? Object.entries(schema.patternProperties).flatMap(([source, sub]) => {
+            try {
+                return [[new RegExp(source), sub]];
             }
-            // Synthesize filler keys to reach `minProperties` when extras are allowed.
-            if (hasMinProperties(schema) && extrasAllowed) {
-                let n = 0;
-                while (Object.keys(out).length < schema.minProperties) {
-                    const key = `extra${n++}`;
-                    if (key in out)
-                        continue;
-                    out[key] = additionalSchema ? deriveExample(additionalSchema, rootSchema, seen) : null;
-                }
+            catch {
+                return [];
             }
-            return out;
+        })
+        : [];
+    const additional = hasAdditionalProperties(schema) ? schema.additionalProperties : false;
+    const additionalSchema = isSchemaObject(additional) ? additional : undefined;
+    const additionalClosed = hasAdditionalProperties(schema) && schema.additionalProperties === false;
+    // With `additionalProperties: false`, extra keys are still allowed when they
+    // match a `patternProperties` entry; only a fully closed object forbids all.
+    const extrasAllowed = !additionalClosed || patternEntries.length > 0;
+    const nameCheck = hasPropertyNames(schema) ? makeInstanceCheck(schema.propertyNames, rootSchema) : undefined;
+    // The value schema for a key not declared in `properties`: the matching
+    // `patternProperties` (intersected when several match), else `additionalProperties`.
+    const valueSchemaFor = (key) => {
+        const matches = patternEntries.filter(([re]) => re.test(key)).map(([, sub]) => sub);
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length > 1)
+            return { allOf: matches };
+        return additionalSchema;
+    };
+    const addKey = (key) => {
+        const sub = valueSchemaFor(key);
+        out[key] = sub !== undefined ? deriveExample(sub, rootSchema, seen) : null;
+    };
+    if (hasProperties(schema)) {
+        for (const [key, propSchema] of Object.entries(schema.properties)) {
+            out[key] = deriveExample(propSchema, rootSchema, seen);
         }
-        default:
-            return null;
+    }
+    // A required key with no `properties` entry still needs a value.
+    if (hasRequired(schema)) {
+        for (const key of schema.required)
+            if (!(key in out))
+                addKey(key);
+    }
+    // `dependentRequired`: once a trigger key is present, its dependencies must be too.
+    if (hasDependentRequired(schema)) {
+        for (const [trigger, deps] of Object.entries(schema.dependentRequired)) {
+            if (!(trigger in out))
+                continue;
+            for (const dep of deps)
+                if (!(dep in out))
+                    addKey(dep);
+        }
+    }
+    // `dependentSchemas`: once a trigger key is present, the object must also
+    // satisfy the dependency subschema — apply its `properties`/`required`.
+    if (hasDependentSchemas(schema)) {
+        for (const [trigger, sub] of Object.entries(schema.dependentSchemas)) {
+            if (trigger in out && isSchemaObject(sub))
+                applyDependentSchema(out, sub, rootSchema, seen);
+        }
+    }
+    // Synthesize filler keys to reach `minProperties` when extras are allowed.
+    if (hasMinProperties(schema) && extrasAllowed) {
+        let n = 0;
+        let guard = 0;
+        while (Object.keys(out).length < schema.minProperties && guard++ < schema.minProperties + 50) {
+            const key = synthKey(n++, patternEntries, schema, nameCheck);
+            if (key === undefined || key in out)
+                continue;
+            addKey(key);
+        }
+    }
+    // Enforce `maxProperties` by dropping keys that aren't required (directly or via
+    // a present `dependentRequired` trigger) until the count fits.
+    if (hasMaxProperties(schema))
+        enforceMaxProperties(out, schema, schema.maxProperties);
+    return out;
+};
+/** Applies a `dependentSchemas` branch's object shape (`properties`/`required`) in place. */
+const applyDependentSchema = (out, sub, rootSchema, seen) => {
+    if (hasProperties(sub)) {
+        for (const [key, propSchema] of Object.entries(sub.properties)) {
+            if (!(key in out))
+                out[key] = deriveExample(propSchema, rootSchema, seen);
+        }
+    }
+    if (hasRequired(sub)) {
+        const propSchemas = hasProperties(sub) ? sub.properties : {};
+        for (const key of sub.required) {
+            if (key in out)
+                continue;
+            const propSchema = propSchemas[key];
+            out[key] = propSchema !== undefined ? deriveExample(propSchema, rootSchema, seen) : null;
+        }
+    }
+};
+/**
+ * Produces a candidate key name for the i-th synthesized property. Prefers a key
+ * matching a `patternProperties` entry (so the entry supplies its value schema),
+ * then one matching `propertyNames`, then a plain `extraN`. Returns `undefined`
+ * when the candidate can't satisfy a `propertyNames` constraint.
+ */
+const synthKey = (i, patternEntries, schema, nameCheck) => {
+    // Distinct keys are produced by *repeating* a base seed (`x-` → `x-x-`) rather
+    // than appending a digit: repetition is far likelier to keep matching a key
+    // pattern (`^[a-z]+$`, `^x-`) that a digit suffix would break.
+    const vary = (seed) => seed.repeat(i + 1);
+    const seeds = [];
+    for (const [re] of patternEntries) {
+        const sampled = sampleFromPattern(re.source, 0);
+        if (sampled !== undefined && sampled.length > 0)
+            seeds.push(vary(sampled));
+    }
+    const propertyNames = isSchemaObject(schema) && hasPropertyNames(schema) ? schema.propertyNames : undefined;
+    if (propertyNames !== undefined && isSchemaObject(propertyNames) && hasPattern(propertyNames)) {
+        const sampled = sampleFromPattern(propertyNames.pattern, 0);
+        if (sampled !== undefined && sampled.length > 0)
+            seeds.push(vary(sampled));
+    }
+    seeds.push(vary('extra'));
+    for (const seed of seeds) {
+        if (!nameCheck || nameCheck(seed))
+            return seed;
+    }
+    return undefined;
+};
+/** Drops non-required keys until `out` has at most `max` properties. */
+const enforceMaxProperties = (out, schema, max) => {
+    if (Object.keys(out).length <= max)
+        return;
+    const protectedKeys = new Set(hasRequired(schema) ? schema.required : []);
+    if (hasDependentRequired(schema)) {
+        for (const [trigger, deps] of Object.entries(schema.dependentRequired)) {
+            if (trigger in out)
+                for (const dep of deps)
+                    protectedKeys.add(dep);
+        }
+    }
+    for (const key of Object.keys(out)) {
+        if (Object.keys(out).length <= max)
+            break;
+        if (!protectedKeys.has(key))
+            delete out[key];
     }
 };
 /**

package/dist/generators/find-schema-cycles.d.ts

@@ -0,0 +1,27 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Maps each generated filename to the set of *other* filenames sharing its
+ * strongly connected component (SCC) in the `$ref` graph. A non-empty set means
+ * the file takes part in a cross-file reference cycle (e.g. `a → b → a`), so any
+ * reference it emits to one of those siblings must be lazy: two modules that
+ * eagerly read each other's top-level `const` at import time crash with a
+ * circular-ESM TDZ `ReferenceError`.
+ *
+ * A file that only references *itself* is a single-node SCC and never appears
+ * here — that recursion is already tied lazily via `fc.letrec` inside
+ * {@link generateArbitrary}.
+ */
+export type SchemaCycles = ReadonlyMap<string, ReadonlySet<string>>;
+/**
+ * Detects cross-file `$ref` cycles in a schema's ref graph.
+ *
+ * Walks the graph via {@link walkRefGraph}, groups files into strongly connected
+ * components, and returns — for every file inside a multi-file component — the
+ * sibling files it must reference lazily to avoid a circular-ESM TDZ crash.
+ * Files not involved in any cross-file cycle are absent from the result.
+ *
+ * @param rootSchema - The root JSON Schema being built.
+ * @param rootTypeName - The name for the root type (e.g. `'Document'`).
+ * @param typeSuffix - Suffix appended to every `$ref`-derived name (default `''`).
+ */
+export declare const findSchemaCycles: (rootSchema: JSONSchema, rootTypeName: string, typeSuffix?: string) => SchemaCycles;

package/dist/generators/find-schema-cycles.js

@@ -0,0 +1,124 @@
+import { extractRefs } from '@amritk/helpers/extract-refs';
+import { refToFilename } from '@amritk/helpers/ref-to-filename';
+import { walkRefGraph } from '@amritk/helpers/walk-ref-graph';
+/**
+ * Collects the ref graph as an adjacency map of filename → referenced
+ * filenames, restricted to nodes that are actually generated as files. Self
+ * edges are dropped (they are `fc.letrec` recursion, not cross-file cycles).
+ */
+const buildRefGraph = (rootSchema, rootTypeName, typeSuffix) => {
+    const schemas = new Map();
+    walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
+        // `index` is reserved for the barrel and never generated as a definition.
+        if (node.filename === 'index')
+            return;
+        if (!schemas.has(node.filename))
+            schemas.set(node.filename, node.schema);
+    });
+    const graph = new Map();
+    for (const [filename, schema] of schemas) {
+        const targets = new Set();
+        for (const ref of extractRefs(schema)) {
+            const target = refToFilename(ref);
+            // Only edges to other generated files matter — an unresolved/external ref
+            // never becomes an eager cross-module reference.
+            if (target !== filename && schemas.has(target))
+                targets.add(target);
+        }
+        graph.set(filename, targets);
+    }
+    return graph;
+};
+/**
+ * Tarjan's strongly-connected-components algorithm, iterative so a deep ref
+ * graph cannot overflow the call stack. Returns one array of filenames per SCC.
+ */
+const stronglyConnectedComponents = (graph) => {
+    let counter = 0;
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    for (const start of graph.keys()) {
+        if (index.has(start))
+            continue;
+        const callStack = [{ node: start, iter: (graph.get(start) ?? new Set()).values() }];
+        index.set(start, counter);
+        lowlink.set(start, counter);
+        counter++;
+        stack.push(start);
+        onStack.add(start);
+        while (callStack.length > 0) {
+            const frame = callStack[callStack.length - 1];
+            const node = frame.node;
+            let descended = false;
+            let next = frame.iter.next();
+            while (!next.done) {
+                const child = next.value;
+                if (!index.has(child)) {
+                    index.set(child, counter);
+                    lowlink.set(child, counter);
+                    counter++;
+                    stack.push(child);
+                    onStack.add(child);
+                    callStack.push({ node: child, iter: (graph.get(child) ?? new Set()).values() });
+                    descended = true;
+                    break;
+                }
+                if (onStack.has(child)) {
+                    lowlink.set(node, Math.min(lowlink.get(node), index.get(child)));
+                }
+                next = frame.iter.next();
+            }
+            if (descended)
+                continue;
+            // All successors visited: close this node.
+            if (lowlink.get(node) === index.get(node)) {
+                const scc = [];
+                let member;
+                do {
+                    member = stack.pop();
+                    onStack.delete(member);
+                    scc.push(member);
+                } while (member !== node);
+                sccs.push(scc);
+            }
+            callStack.pop();
+            const parent = callStack[callStack.length - 1];
+            if (parent) {
+                lowlink.set(parent.node, Math.min(lowlink.get(parent.node), lowlink.get(node)));
+            }
+        }
+    }
+    return sccs;
+};
+/**
+ * Detects cross-file `$ref` cycles in a schema's ref graph.
+ *
+ * Walks the graph via {@link walkRefGraph}, groups files into strongly connected
+ * components, and returns — for every file inside a multi-file component — the
+ * sibling files it must reference lazily to avoid a circular-ESM TDZ crash.
+ * Files not involved in any cross-file cycle are absent from the result.
+ *
+ * @param rootSchema - The root JSON Schema being built.
+ * @param rootTypeName - The name for the root type (e.g. `'Document'`).
+ * @param typeSuffix - Suffix appended to every `$ref`-derived name (default `''`).
+ */
+export const findSchemaCycles = (rootSchema, rootTypeName, typeSuffix = '') => {
+    const graph = buildRefGraph(rootSchema, rootTypeName, typeSuffix);
+    const cycles = new Map();
+    for (const scc of stronglyConnectedComponents(graph)) {
+        // A single-file component is either an isolated node or pure self-recursion;
+        // neither needs cross-file lazy references.
+        if (scc.length < 2)
+            continue;
+        const members = new Set(scc);
+        for (const member of scc) {
+            const siblings = new Set(members);
+            siblings.delete(member);
+            cycles.set(member, siblings);
+        }
+    }
+    return cycles;
+};

package/dist/generators/generate-arbitrary.d.ts

@@ -1,4 +1,17 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Local alias the generated file binds `@amritk/runtime-validators`' `validate`
+ * to. Namespaced (leading underscores) so it can't collide with a schema-derived
+ * type name. {@link generateArbitrary} emits references to it; the file assembler
+ * adds the matching import when any arbitrary uses it.
+ */
+export declare const VALIDATE_IMPORT_NAME = "__mjstValidate";
+/**
+ * The import line the generated file needs when an arbitrary embeds a validating
+ * filter. Emitted by the file assembler only when {@link VALIDATE_IMPORT_NAME}
+ * appears in the generated source.
+ */
+export declare const VALIDATE_IMPORT_STATEMENT = "import { validate as __mjstValidate } from '@amritk/runtime-validators'";
 /**
  * Generates a `fast-check` arbitrary that produces schema-valid values.
  *
@@ -6,10 +19,14 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * tied lazily — a plain `const NodeArbitrary = fc.record({ next: NodeArbitrary })`
  * would throw a TDZ `ReferenceError` the moment the module is imported.
  *
+ * `lazyRefFilenames` names the sibling files this type shares a cross-file `$ref`
+ * cycle with; references to those are deferred so mutually recursive modules do
+ * not read each other's `const` before it is initialized (see {@link ExprCtx}).
+ *
  * @example
  * ```typescript
  * generateArbitrary({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, 'Info')
  * // export const InfoArbitrary: fc.Arbitrary<Info> = fc.record({ "name": fc.string() })
  * ```
  */
-export declare const generateArbitrary: (schema: JSONSchema, typeName: string, suffix?: string) => string;
+export declare const generateArbitrary: (schema: JSONSchema, typeName: string, suffix?: string, lazyRefFilenames?: ReadonlySet<string>, rootSchema?: Record<string, unknown>) => string;

package/dist/generators/generate-arbitrary.js

@@ -1,12 +1,35 @@
 import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension';
+import { refToFilename } from '@amritk/helpers/ref-to-filename';
 import { refToName } from '@amritk/helpers/ref-to-name';
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasFormat, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasContains, hasDependentRequired, hasDependentSchemas, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasFormat, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMaxProperties, hasMinItems, hasMinimum, hasMinLength, hasMinProperties, hasMultipleOf, hasOneOf, hasPattern, hasPatternProperties, hasProperties, hasPropertyNames, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject, } from '@amritk/helpers/schema-guards';
 import { mergeAllOf } from './derive-example.js';
+import { needsValidationFilter, withResolvableDefs } from './schema-validation.js';
 /**
  * Derives the arbitrary const name from a type name.
  * e.g. "User" → "UserArbitrary"
  */
 const arbitraryName = (typeName) => `${typeName}Arbitrary`;
+/**
+ * Local alias the generated file binds `@amritk/runtime-validators`' `validate`
+ * to. Namespaced (leading underscores) so it can't collide with a schema-derived
+ * type name. {@link generateArbitrary} emits references to it; the file assembler
+ * adds the matching import when any arbitrary uses it.
+ */
+export const VALIDATE_IMPORT_NAME = '__mjstValidate';
+/**
+ * The import line the generated file needs when an arbitrary embeds a validating
+ * filter. Emitted by the file assembler only when {@link VALIDATE_IMPORT_NAME}
+ * appears in the generated source.
+ */
+export const VALIDATE_IMPORT_STATEMENT = `import { validate as ${VALIDATE_IMPORT_NAME} } from '@amritk/runtime-validators'`;
+/**
+ * Wraps a cross-module arbitrary reference so the imported binding is read at
+ * generation time rather than at module-init time. `fc.constant(null).chain`
+ * stores the thunk and only invokes it when a value is generated — by which
+ * point every module in the cycle has finished initializing — so the otherwise
+ * eager identifier never touches a `const` in its TDZ.
+ */
+const lazyRef = (arbName) => `fc.constant(null).chain(() => ${arbName})`;
 /** The letrec key used for a type's own (self-referential) arbitrary. */
 const SELF_KEY = 'self';
 /** Builds a `fc.string({ ... })` expression honouring format and length constraints. */
@@ -78,8 +101,77 @@ const integerExpr = (schema) => {
     const base = opts.length > 0 ? `fc.integer({ ${opts.join(', ')} })` : 'fc.integer()';
     return hasMultipleOf(schema) ? `${base}.filter((n) => n % ${schema.multipleOf} === 0)` : base;
 };
+/**
+ * Builds a multiple-of-respecting number arbitrary analytically: pick an integer
+ * `k` whose multiple `k * multipleOf` lands inside the (possibly exclusive)
+ * bounds, then emit that product. Random doubles essentially never satisfy
+ * `n % m === 0`, so a `.filter` here starves fast-check ("too many filtered
+ * values") at sample time; deriving the multiple directly cannot fail. This
+ * mirrors the static path's `deriveNumber`.
+ *
+ * The trailing `.map` clamps `k * m` back inside the finite bounds to absorb
+ * floating-point drift (e.g. `3 * 0.1 === 0.30000000000000004`, which would
+ * otherwise slip just past a `maximum` of `0.3`).
+ */
+const numberMultipleOfExpr = (schema) => {
+    const m = Number(schema.multipleOf);
+    const EPS = 1e-9;
+    // Effective lower bound: the tighter (larger) of minimum / exclusiveMinimum,
+    // tracking whether the binding bound is exclusive.
+    let lo = Number.NEGATIVE_INFINITY;
+    let loExclusive = false;
+    if (hasMinimum(schema))
+        lo = Number(schema.minimum);
+    if (hasExclusiveMinimum(schema) && Number(schema.exclusiveMinimum) >= lo) {
+        lo = Number(schema.exclusiveMinimum);
+        loExclusive = true;
+    }
+    // Effective upper bound: the tighter (smaller) of maximum / exclusiveMaximum.
+    let hi = Number.POSITIVE_INFINITY;
+    let hiExclusive = false;
+    if (hasMaximum(schema))
+        hi = Number(schema.maximum);
+    if (hasExclusiveMaximum(schema) && Number(schema.exclusiveMaximum) <= hi) {
+        hi = Number(schema.exclusiveMaximum);
+        hiExclusive = true;
+    }
+    // Translate value bounds into integer-`k` bounds, where the emitted value is
+    // `k * m`. An exclusive bound must be strictly cleared, so a `k` landing exactly
+    // on it is nudged one step inward; `EPS` keeps a mathematically-integer ratio
+    // (e.g. `0.3 / 0.1`) from being mis-rounded by floating-point error.
+    let kMin;
+    let kMax;
+    if (Number.isFinite(lo)) {
+        const raw = lo / m;
+        kMin = loExclusive ? Math.floor(raw + EPS) + 1 : Math.ceil(raw - EPS);
+    }
+    if (Number.isFinite(hi)) {
+        const raw = hi / m;
+        kMax = hiExclusive ? Math.ceil(raw - EPS) - 1 : Math.floor(raw + EPS);
+    }
+    // An unsatisfiable range (no multiple fits) would make `fc.integer` throw on
+    // `min > max`; collapse to a single best-effort value instead.
+    if (kMin !== undefined && kMax !== undefined && kMin > kMax)
+        kMax = kMin;
+    const kOpts = [];
+    if (kMin !== undefined)
+        kOpts.push(`min: ${kMin}`);
+    if (kMax !== undefined)
+        kOpts.push(`max: ${kMax}`);
+    const k = kOpts.length > 0 ? `fc.integer({ ${kOpts.join(', ')} })` : 'fc.integer()';
+    let value = `k * ${m}`;
+    if (Number.isFinite(lo))
+        value = `Math.max(${value}, ${lo})`;
+    if (Number.isFinite(hi))
+        value = `Math.min(${value}, ${hi})`;
+    return `${k}.map((k) => ${value})`;
+};
 /** Builds a `fc.double({ ... })` expression honouring range and multiple-of constraints. */
 const numberExpr = (schema) => {
+    // A positive `multipleOf` is satisfied analytically rather than by filtering
+    // random doubles, which would starve fast-check at sample time.
+    if (hasMultipleOf(schema) && schema.multipleOf > 0)
+        return numberMultipleOfExpr(schema);
     const opts = ['noNaN: true', 'noDefaultInfinity: true'];
     if (hasMinimum(schema))
         opts.push(`min: ${schema.minimum}`);
@@ -89,8 +181,7 @@ const numberExpr = (schema) => {
         opts.push(`max: ${schema.maximum}`);
     else if (hasExclusiveMaximum(schema))
         opts.push(`max: ${schema.exclusiveMaximum}`, 'maxExcluded: true');
-    const base = `fc.double({ ${opts.join(', ')} })`;
-    return hasMultipleOf(schema) ? `${base}.filter((n) => n % ${schema.multipleOf} === 0)` : base;
+    return `fc.double({ ${opts.join(', ')} })`;
 };
 /** Builds a `fc.array(...)` / `fc.uniqueArray(...)` / `fc.tuple(...)` expression for an array schema. */
 const arrayExpr = (schema, ctx) => {
@@ -109,42 +200,133 @@ const arrayExpr = (schema, ctx) => {
         const exprs = tuple.map((item) => arbitraryExpr(item, ctx));
         return `fc.tuple(${exprs.join(', ')})`;
     }
-    const items = hasItems(schema) && isSchemaObject(schema.items) ? arbitraryExpr(schema.items, ctx) : 'fc.anything()';
+    // With no `items`, a `contains` subschema is the only element constraint, so
+    // generate from it (and guarantee at least one such element via `minLength`) —
+    // otherwise an empty array would fail `contains`.
+    const containsSchema = hasContains(schema) && isSchemaObject(schema.contains) ? schema.contains : undefined;
+    const items = hasItems(schema) && isSchemaObject(schema.items)
+        ? arbitraryExpr(schema.items, ctx)
+        : containsSchema
+            ? arbitraryExpr(containsSchema, ctx)
+            : 'fc.anything()';
+    const minContains = containsSchema !== undefined && typeof raw['minContains'] === 'number' ? raw['minContains'] : 1;
+    const minLength = Math.max(hasMinItems(schema) ? schema.minItems : 0, containsSchema !== undefined ? Math.max(1, minContains) : 0);
     const opts = [];
-    if (hasMinItems(schema))
-        opts.push(`minLength: ${schema.minItems}`);
+    if (minLength > 0)
+        opts.push(`minLength: ${minLength}`);
     if (hasMaxItems(schema))
         opts.push(`maxLength: ${schema.maxItems}`);
     const fn = hasUniqueItems(schema) && schema.uniqueItems === true ? 'fc.uniqueArray' : 'fc.array';
     return opts.length > 0 ? `${fn}(${items}, { ${opts.join(', ')} })` : `${fn}(${items})`;
 };
+/** The arbitrary for keys of the open-map (extra-property) part of an object. */
+const extraKeyArb = (schema, firstPatternSource) => {
+    // Keys must satisfy `patternProperties` (so the value schema applies) or, failing
+    // that, a `propertyNames` pattern. Both map onto `fc.stringMatching`.
+    if (firstPatternSource !== undefined)
+        return `fc.stringMatching(new RegExp(${JSON.stringify(firstPatternSource)}))`;
+    const propertyNames = hasPropertyNames(schema) ? schema.propertyNames : undefined;
+    if (propertyNames !== undefined && isSchemaObject(propertyNames) && hasPattern(propertyNames)) {
+        return `fc.stringMatching(new RegExp(${JSON.stringify(propertyNames.pattern)}))`;
+    }
+    return 'fc.string()';
+};
 /** Builds a `fc.record(...)` / `fc.dictionary(...)` expression for an object schema. */
 const objectExpr = (schema, ctx) => {
     // The `additionalProperties` value schema (when it constrains extra keys with a
     // real subschema rather than the boolean true/false form).
     const additional = hasAdditionalProperties(schema) ? schema.additionalProperties : false;
     const additionalArb = isSchemaObject(additional) ? arbitraryExpr(additional, ctx) : undefined;
-    if (!hasProperties(schema)) {
-        // A map-style object (no declared properties) with a typed `additionalProperties`
-        // is a dictionary of that value type; otherwise fall back to a free-form object.
-        return additionalArb ? `fc.dictionary(fc.string(), ${additionalArb})` : 'fc.object()';
+    const additionalClosed = hasAdditionalProperties(schema) && schema.additionalProperties === false;
+    // The first `patternProperties` entry drives the open-map value/key shape.
+    const patternEntries = hasPatternProperties(schema) ? Object.entries(schema.patternProperties) : [];
+    const firstPattern = patternEntries[0];
+    const patternValueArb = firstPattern && isSchemaObject(firstPattern[1]) ? arbitraryExpr(firstPattern[1], ctx) : undefined;
+    // Extra keys are allowed unless a fully closed object (no `additionalProperties`
+    // and no `patternProperties` outlet) forbids them.
+    const extrasAllowed = !additionalClosed || patternEntries.length > 0;
+    const extraValueArb = additionalArb ?? patternValueArb;
+    const keyArb = extraKeyArb(schema, firstPattern?.[0]);
+    const minProps = hasMinProperties(schema) ? schema.minProperties : undefined;
+    const maxProps = hasMaxProperties(schema) ? schema.maxProperties : undefined;
+    const dictKeyOpts = (minKeys, maxKeys) => {
+        const opts = [];
+        if (minKeys !== undefined && minKeys > 0)
+            opts.push(`minKeys: ${minKeys}`);
+        if (maxKeys !== undefined)
+            opts.push(`maxKeys: ${maxKeys}`);
+        return opts.length > 0 ? `, { ${opts.join(', ')} }` : '';
+    };
+    // Each declared key maps to the arbitrary that generates its value.
+    const propArbs = new Map();
+    if (hasProperties(schema)) {
+        for (const [key, propSchema] of Object.entries(schema.properties))
+            propArbs.set(key, arbitraryExpr(propSchema, ctx));
     }
     const required = new Set(hasRequired(schema) ? schema.required : []);
-    const keys = Object.keys(schema.properties);
-    const entries = Object.entries(schema.properties).map(([key, propSchema]) => `${JSON.stringify(key)}: ${arbitraryExpr(propSchema, ctx)}`);
-    if (entries.length === 0)
-        return 'fc.record({})';
+    // The value arbitrary for a key not declared in `properties` (a dependency key).
+    const openValueArb = extraValueArb ?? 'fc.anything()';
+    // Fold presence-gated dependency keywords into the always-present set. Requiring
+    // a dependency (or a `dependentSchemas` shape) unconditionally is stricter than
+    // the keyword — but a value that always carries the dependency is always valid,
+    // and it keeps the generated candidate from being rejected by the filter.
+    if (hasDependentRequired(schema)) {
+        for (const [, deps] of Object.entries(schema.dependentRequired)) {
+            for (const dep of deps) {
+                if (!propArbs.has(dep))
+                    propArbs.set(dep, openValueArb);
+                required.add(dep);
+            }
+        }
+    }
+    if (hasDependentSchemas(schema)) {
+        for (const [, sub] of Object.entries(schema.dependentSchemas)) {
+            if (!isSchemaObject(sub))
+                continue;
+            if (hasProperties(sub)) {
+                for (const [key, propSchema] of Object.entries(sub.properties)) {
+                    if (!propArbs.has(key))
+                        propArbs.set(key, arbitraryExpr(propSchema, ctx));
+                }
+            }
+            if (hasRequired(sub))
+                for (const key of sub.required)
+                    required.add(key);
+        }
+    }
+    // A `dependentSchemas`/`dependentRequired` key may be required without a declared
+    // value schema; give it the open-map value arbitrary.
+    for (const key of required)
+        if (!propArbs.has(key))
+            propArbs.set(key, openValueArb);
+    const keys = [...propArbs.keys()];
+    // A map-style object (no declared keys) is a dictionary; its bounds come from
+    // `min`/`maxProperties` and its value/key shape from `additionalProperties` /
+    // `patternProperties` / `propertyNames`.
+    if (keys.length === 0) {
+        if (extraValueArb)
+            return `fc.dictionary(${keyArb}, ${extraValueArb}${dictKeyOpts(minProps, maxProps)})`;
+        if (minProps !== undefined || maxProps !== undefined) {
+            return `fc.dictionary(${keyArb}, fc.anything()${dictKeyOpts(minProps, maxProps)})`;
+        }
+        return 'fc.object()';
+    }
+    const entries = keys.map((key) => `${JSON.stringify(key)}: ${propArbs.get(key)}`);
     const model = `{ ${entries.join(', ')} }`;
     // fc.record treats all keys as required by default. Only emit requiredKeys
     // when at least one property is optional.
     const record = keys.every((key) => required.has(key))
         ? `fc.record(${model})`
         : `fc.record(${model}, { requiredKeys: [${[...required].map((key) => JSON.stringify(key)).join(', ')}] })`;
-    // When both declared properties and a typed `additionalProperties` are present,
-    // fold in a dictionary of extra keys so the value exercises the open-map part of
-    // the schema too. The declared keys win on collision (merged last).
-    if (additionalArb) {
-        return `fc.tuple(${record}, fc.dictionary(fc.string(), ${additionalArb})).map(([base, extra]) => ({ ...extra, ...base }))`;
+    // Fold in a dictionary of extra keys when the open-map part is typed, or when
+    // `minProperties` needs more keys than the declared set guarantees. `minKeys`
+    // fills only the gap above the always-present (required) keys so the floor is met
+    // without overshooting. Declared keys win on collision (merged last).
+    const needExtras = extrasAllowed && (extraValueArb !== undefined || (minProps !== undefined && minProps > required.size));
+    if (needExtras) {
+        const valueArb = extraValueArb ?? 'fc.anything()';
+        const minKeys = minProps !== undefined ? Math.max(0, minProps - required.size) : undefined;
+        return `fc.tuple(${record}, fc.dictionary(${keyArb}, ${valueArb}${dictKeyOpts(minKeys, undefined)})).map(([base, extra]) => ({ ...extra, ...base }))`;
     }
     return record;
 };
@@ -174,6 +356,37 @@ const scalarExpr = (type, schema, ctx) => {
             return 'fc.anything()';
     }
 };
+/** True when an `enum` member satisfies the node's sibling length/range/pattern constraints. */
+const enumMemberFits = (schema, value) => {
+    if (typeof value === 'string') {
+        if (hasMinLength(schema) && value.length < schema.minLength)
+            return false;
+        if (hasMaxLength(schema) && value.length > schema.maxLength)
+            return false;
+        if (hasPattern(schema)) {
+            try {
+                if (!new RegExp(schema.pattern).test(value))
+                    return false;
+            }
+            catch {
+                // An invalid pattern can't reject anything.
+            }
+        }
+    }
+    else if (typeof value === 'number') {
+        if (hasMinimum(schema) && value < schema.minimum)
+            return false;
+        if (hasMaximum(schema) && value > schema.maximum)
+            return false;
+        if (hasExclusiveMinimum(schema) && value <= schema.exclusiveMinimum)
+            return false;
+        if (hasExclusiveMaximum(schema) && value >= schema.exclusiveMaximum)
+            return false;
+        if (hasMultipleOf(schema) && schema.multipleOf > 0 && value % schema.multipleOf !== 0)
+            return false;
+    }
+    return true;
+};
 /**
  * Recursively builds the fast-check arbitrary expression for a schema node.
  * `$ref`s resolve to the referenced file's exported arbitrary; a self-`$ref`
@@ -191,12 +404,24 @@ const arbitraryExpr = (schema, ctx) => {
             ctx.usedTie.value = true;
             return `tie(${JSON.stringify(SELF_KEY)})`;
         }
+        // A reference to a sibling this type shares a cross-file cycle with is the
+        // same TDZ hazard one module over, and `tie` cannot reach across modules —
+        // defer the imported binding until generation time instead.
+        if (ctx.lazyRefFilenames.has(refToFilename(schema.$ref))) {
+            return lazyRef(name);
+        }
         return name;
     }
     if (hasConst(schema))
         return `fc.constant(${JSON.stringify(schema.const)})`;
     if (hasEnum(schema)) {
-        const values = schema.enum.map((value) => JSON.stringify(value)).join(', ');
+        // Drop enum members that violate a sibling length/range/pattern constraint so
+        // the arbitrary never emits an out-of-range member. Keep all when none fit
+        // (an unsatisfiable schema) rather than emitting an empty `constantFrom`.
+        const members = schema.enum;
+        const fitting = members.filter((value) => enumMemberFits(schema, value));
+        const chosen = fitting.length > 0 ? fitting : members;
+        const values = chosen.map((value) => JSON.stringify(value)).join(', ');
         return `fc.constantFrom(${values})`;
     }
     const instanceOf = getMjstInstanceOf(schema);
@@ -235,18 +460,32 @@ const arbitraryExpr = (schema, ctx) => {
  * tied lazily — a plain `const NodeArbitrary = fc.record({ next: NodeArbitrary })`
  * would throw a TDZ `ReferenceError` the moment the module is imported.
  *
+ * `lazyRefFilenames` names the sibling files this type shares a cross-file `$ref`
+ * cycle with; references to those are deferred so mutually recursive modules do
+ * not read each other's `const` before it is initialized (see {@link ExprCtx}).
+ *
  * @example
  * ```typescript
  * generateArbitrary({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, 'Info')
  * // export const InfoArbitrary: fc.Arbitrary<Info> = fc.record({ "name": fc.string() })
  * ```
  */
-export const generateArbitrary = (schema, typeName, suffix = '') => {
+export const generateArbitrary = (schema, typeName, suffix = '', lazyRefFilenames = new Set(), rootSchema) => {
     const selfArbName = arbitraryName(typeName);
-    const ctx = { suffix, selfArbName, usedTie: { value: false } };
+    const ctx = { suffix, selfArbName, usedTie: { value: false }, lazyRefFilenames };
     const expr = arbitraryExpr(schema, ctx);
-    if (ctx.usedTie.value) {
-        return `export const ${selfArbName}: fc.Arbitrary<${typeName}> = fc.letrec<{ ${SELF_KEY}: ${typeName} }>((tie) => ({\n  ${SELF_KEY}: ${expr},\n})).${SELF_KEY}`;
+    const body = ctx.usedTie.value
+        ? `fc.letrec<{ ${SELF_KEY}: ${typeName} }>((tie) => ({\n  ${SELF_KEY}: ${expr},\n})).${SELF_KEY}`
+        : expr;
+    // Keywords no `fc.*` combinator captures on its own (`if`/`then`/`else`, `not`,
+    // `oneOf` exclusivity, the presence-gated object keywords) are enforced by a
+    // post-generation filter: the arbitrary samples a candidate and rejects it
+    // unless a runtime validator built from the same schema accepts it.
+    if (needsValidationFilter(schema)) {
+        const validatorName = `${selfArbName}Validator`;
+        const embedded = JSON.stringify(withResolvableDefs(schema, rootSchema));
+        return (`const ${validatorName} = ${VALIDATE_IMPORT_NAME}(${embedded})\n` +
+            `export const ${selfArbName}: fc.Arbitrary<${typeName}> = (${body}).filter((value) => ${validatorName}(value) === true)`);
     }
-    return `export const ${selfArbName}: fc.Arbitrary<${typeName}> = ${expr}`;
+    return `export const ${selfArbName}: fc.Arbitrary<${typeName}> = ${body}`;
 };

package/dist/generators/generate-files.d.ts

@@ -18,6 +18,12 @@ type GenerateExampleFileOptions = {
      * Defaults to `''` (no suffix).
      */
     readonly typeSuffix?: string;
+    /**
+     * Filenames of the other types this file shares a cross-file `$ref` cycle
+     * with. References to them are emitted lazily so mutually recursive modules
+     * do not crash with a circular-ESM TDZ error at import. Defaults to empty.
+     */
+    readonly lazyRefFilenames?: ReadonlySet<string>;
 };
 /**
  * Generates a complete TypeScript example file from a JSON Schema.

package/dist/generators/generate-files.js

@@ -1,7 +1,7 @@
 import { generateTypeDefinition } from '@amritk/helpers/generate-type-definition';
 import { collectExampleImports } from './collect-example-imports.js';
 import { generateExampleConst } from './derive-example.js';
-import { generateArbitrary } from './generate-arbitrary.js';
+import { generateArbitrary, VALIDATE_IMPORT_NAME, VALIDATE_IMPORT_STATEMENT } from './generate-arbitrary.js';
 /**
  * Generates a complete TypeScript example file from a JSON Schema.
  *
@@ -29,9 +29,14 @@ export const generateExampleFile = (schema, typeName, options) => {
         typeSuffix,
     });
     const typeDefinition = generateTypeDefinition(schema, typeName, { typeSuffix });
-    const arbitrary = generateArbitrary(schema, typeName, typeSuffix);
+    const arbitrary = generateArbitrary(schema, typeName, typeSuffix, options?.lazyRefFilenames, options?.rootSchema);
     const example = generateExampleConst(schema, typeName, options?.rootSchema);
     let result = `import * as fc from 'fast-check'\n`;
+    // The arbitrary embeds a runtime validator only for schemas whose keywords no
+    // `fc.*` combinator captures; import it just for those files.
+    if (arbitrary.includes(`${VALIDATE_IMPORT_NAME}(`)) {
+        result += VALIDATE_IMPORT_STATEMENT + '\n';
+    }
     for (const imp of refImports) {
         result += imp + '\n';
     }

package/dist/generators/schema-validation.d.ts

@@ -0,0 +1,20 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * True when `schema` (anywhere in its applied subschema tree) uses a keyword the
+ * direct generators can't guarantee, so the generated value must be run through a
+ * validating filter. `$ref`s are not followed — a referenced definition is emitted
+ * as its own self-validating file.
+ */
+export declare const needsValidationFilter: (schema: JSONSchema) => boolean;
+/**
+ * Returns `schema` augmented with the root document's `$defs`/`definitions` so its
+ * local `$ref`s (`#/$defs/…`) resolve when it is validated in isolation. The
+ * schema's own definitions win on collision.
+ */
+export declare const withResolvableDefs: (schema: JSONSchema, rootSchema?: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Compiles a boolean validator for `schema` (with the root document's definitions
+ * spliced in so local `$ref`s resolve). Used at generation time to accept/reject
+ * candidate example values for keywords the deriver can't satisfy structurally.
+ */
+export declare const makeInstanceCheck: (schema: JSONSchema, rootSchema?: Record<string, unknown>) => ((value: unknown) => boolean);

package/dist/generators/schema-validation.js

@@ -0,0 +1,83 @@
+import { isSchemaObject } from '@amritk/helpers/schema-guards';
+import { validateGuard } from '@amritk/runtime-validators';
+/**
+ * Keywords the direct generators can't fully honour on their own, so a value they
+ * produce must be re-checked against a real validator. `oneOf` is included because
+ * neither path enforces its *exactly-one* exclusivity; `anyOf`/`allOf` are not,
+ * since a single satisfied branch (already how they are generated) is enough.
+ */
+const FILTER_KEYWORDS = new Set([
+    'if',
+    'then',
+    'else',
+    'not',
+    'oneOf',
+    'patternProperties',
+    'propertyNames',
+    'dependentRequired',
+    'dependentSchemas',
+    'dependencies',
+    'minProperties',
+    'maxProperties',
+    'contains',
+]);
+/**
+ * Keys whose values are *data* (or reference targets), not applied subschemas, so
+ * a `not`/`if`/… appearing inside them must not be mistaken for an applicator.
+ * `$defs`/`definitions` hold *unapplied* definitions — a hard keyword there only
+ * matters once referenced, and each referenced def gets its own generated file.
+ */
+const SKIP_RECURSE = new Set(['enum', 'const', 'examples', 'default', '$ref', 'required', '$defs', 'definitions']);
+/**
+ * True when `schema` (anywhere in its applied subschema tree) uses a keyword the
+ * direct generators can't guarantee, so the generated value must be run through a
+ * validating filter. `$ref`s are not followed — a referenced definition is emitted
+ * as its own self-validating file.
+ */
+export const needsValidationFilter = (schema) => {
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.some(walk);
+        if (node === null || typeof node !== 'object')
+            return false;
+        const obj = node;
+        for (const key of Object.keys(obj)) {
+            if (FILTER_KEYWORDS.has(key))
+                return true;
+        }
+        for (const [key, value] of Object.entries(obj)) {
+            if (SKIP_RECURSE.has(key))
+                continue;
+            if (walk(value))
+                return true;
+        }
+        return false;
+    };
+    return walk(schema);
+};
+/**
+ * Returns `schema` augmented with the root document's `$defs`/`definitions` so its
+ * local `$ref`s (`#/$defs/…`) resolve when it is validated in isolation. The
+ * schema's own definitions win on collision.
+ */
+export const withResolvableDefs = (schema, rootSchema) => {
+    const base = isSchemaObject(schema) ? { ...schema } : { const: schema };
+    if (!rootSchema)
+        return base;
+    for (const key of ['$defs', 'definitions']) {
+        const rootDefs = rootSchema[key];
+        if (rootDefs && typeof rootDefs === 'object') {
+            base[key] = { ...rootDefs, ...(base[key] ?? {}) };
+        }
+    }
+    return base;
+};
+/**
+ * Compiles a boolean validator for `schema` (with the root document's definitions
+ * spliced in so local `$ref`s resolve). Used at generation time to accept/reject
+ * candidate example values for keywords the deriver can't satisfy structurally.
+ */
+export const makeInstanceCheck = (schema, rootSchema) => {
+    const guard = validateGuard(withResolvableDefs(schema, rootSchema));
+    return (value) => guard(value) === true;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-examples",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Generate fast-check arbitraries and example values from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -47,7 +47,8 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.11.0"
+    "@amritk/helpers": "0.13.0",
+    "@amritk/runtime-validators": "0.7.0"
   },
   "devDependencies": {
     "ajv": "^8.17.1"