@databehave/schema 0.1.3 → 0.1.4

package/dist/foundation/ir.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Internal Representation (IR) of a databehave schema.
+ *
+ * Every schema builder compiles to one of these serializable nodes.
+ * The generator and validator operate on IR — never on builder classes —
+ * so IR can be inspected, logged, transformed, or transported.
+ */
+export type StringFormat = 'plain' | 'uuid' | 'email' | 'url' | 'ipv4' | 'ipv6' | 'date' | 'datetime' | 'time';
+export type NumberKind = {
+    readonly kind: 'number';
+    readonly int: boolean;
+    readonly bits?: 8 | 16 | 32 | 64;
+    readonly unsigned?: boolean;
+    readonly min?: number;
+    readonly max?: number;
+};
+export type StringKind = {
+    readonly kind: 'string';
+    readonly format: StringFormat;
+    readonly min?: number;
+    readonly max?: number;
+    readonly pattern?: string;
+};
+export type DecimalKind = {
+    readonly kind: 'decimal';
+    readonly precision: number;
+    readonly scale: number;
+    readonly min?: string;
+    readonly max?: string;
+};
+export type BooleanKind = {
+    readonly kind: 'boolean';
+};
+export type NullKind = {
+    readonly kind: 'null';
+};
+export type LiteralKind = {
+    readonly kind: 'literal';
+    readonly value: string | number | boolean | null;
+};
+export type EnumKind = {
+    readonly kind: 'enum';
+    readonly values: readonly (string | number)[];
+};
+export type ArrayKind = {
+    readonly kind: 'array';
+    readonly item: SchemaNode;
+    readonly length?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+};
+export type ObjectKind = {
+    readonly kind: 'object';
+    readonly fields: Readonly<Record<string, SchemaNode>>;
+};
+export type TupleKind = {
+    readonly kind: 'tuple';
+    readonly items: readonly SchemaNode[];
+};
+export type UnionKind = {
+    readonly kind: 'union';
+    readonly options: readonly SchemaNode[];
+};
+/**
+ * A discriminated union — selects exactly one branch by the value of `key`.
+ *
+ * Each entry in `branches` must be an object-kind schema whose `key` field is
+ * a `literal(...)` matching the map key. Generator and validator both use
+ * the discriminator for O(1) branch selection.
+ */
+export type DiscriminatedKind = {
+    readonly kind: 'discriminated';
+    readonly key: string;
+    readonly branches: Readonly<Record<string, SchemaNode>>;
+};
+import type { Axes } from './axes.js';
+export type Modifiers = {
+    readonly nullable?: boolean;
+    readonly optional?: boolean;
+    readonly hasDefault?: boolean;
+    readonly defaultValue?: unknown;
+    readonly description?: string;
+    readonly axes?: Axes;
+};
+export type SchemaCore = NumberKind | StringKind | DecimalKind | BooleanKind | NullKind | LiteralKind | EnumKind | ArrayKind | ObjectKind | TupleKind | UnionKind | DiscriminatedKind;
+export type SchemaNode = SchemaCore & {
+    readonly mods?: Modifiers;
+};
+/** Helper: produce a fresh node with merged modifiers. `axes` are deep-merged. */
+export declare const withMods: (node: SchemaNode, patch: Partial<Modifiers>) => SchemaNode;
+//# sourceMappingURL=ir.d.ts.map

package/dist/foundation/ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../../src/foundation/ir.ts"],"names":[],"mappings":"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"}

package/dist/foundation/ir.js

@@ -0,0 +1,16 @@
+/**
+ * Internal Representation (IR) of a databehave schema.
+ *
+ * Every schema builder compiles to one of these serializable nodes.
+ * The generator and validator operate on IR — never on builder classes —
+ * so IR can be inspected, logged, transformed, or transported.
+ */
+import { mergeAxes } from './axes.js';
+/** Helper: produce a fresh node with merged modifiers. `axes` are deep-merged. */
+export const withMods = (node, patch) => {
+    const prev = node.mods ?? {};
+    const mergedAxes = patch.axes !== undefined ? mergeAxes(prev.axes, patch.axes) : prev.axes;
+    const next = mergedAxes !== undefined ? { ...prev, ...patch, axes: mergedAxes } : { ...prev, ...patch };
+    return { ...node, mods: next };
+};
+//# sourceMappingURL=ir.js.map

package/dist/foundation/ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.js","sourceRoot":"","sources":["../../src/foundation/ir.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwFH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AA6BrC,kFAAkF;AAClF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAgB,EAAE,KAAyB,EAAc,EAAE;IAClF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAA;IAC5B,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAA;IAC1F,MAAM,IAAI,GAAc,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,CAAA;IAClH,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAChC,CAAC,CAAA"}

package/dist/foundation/prng.d.ts

@@ -0,0 +1,27 @@
+/**
+ * mulberry32 — tiny, fast, deterministic 32-bit PRNG.
+ *
+ * Zero-dependency. Identical seed → identical sequence on every machine.
+ * Period ≈ 2^32, ample for mock generation.
+ *
+ * Reference: https://gist.github.com/tommyettinger/46a3a48c0d7fe27ea3aaa5fa8f1ba0e8
+ */
+export type Rng = {
+    /** Next uniformly-distributed float in `[0, 1)`. */
+    next(): number;
+    /** Next integer in `[min, max]` (inclusive). */
+    int(min: number, max: number): number;
+    /** Pick one element of `items` uniformly. */
+    pick<T>(items: readonly T[]): T;
+};
+/**
+ * Create a deterministic PRNG seeded by a 32-bit unsigned integer.
+ *
+ * For string seeds, use {@link rngFromString}.
+ */
+export declare const mulberry32: (seed: number) => Rng;
+/** Derive a 32-bit unsigned seed from an arbitrary string (FNV-1a 32-bit). */
+export declare const seedFromString: (s: string) => number;
+/** Convenience: build an Rng from a string seed. */
+export declare const rngFromString: (s: string) => Rng;
+//# sourceMappingURL=prng.d.ts.map

package/dist/foundation/prng.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prng.d.ts","sourceRoot":"","sources":["../../src/foundation/prng.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,GAAG,GAAG;IAChB,oDAAoD;IACpD,IAAI,IAAI,MAAM,CAAA;IACd,gDAAgD;IAChD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;IACrC,6CAA6C;IAC7C,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAAA;CAChC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,GA8BzC,CAAA;AAED,8EAA8E;AAC9E,eAAO,MAAM,cAAc,GAAI,GAAG,MAAM,KAAG,MAO1C,CAAA;AAED,oDAAoD;AACpD,eAAO,MAAM,aAAa,GAAI,GAAG,MAAM,KAAG,GAAoC,CAAA"}

package/dist/foundation/prng.js

@@ -0,0 +1,56 @@
+/**
+ * mulberry32 — tiny, fast, deterministic 32-bit PRNG.
+ *
+ * Zero-dependency. Identical seed → identical sequence on every machine.
+ * Period ≈ 2^32, ample for mock generation.
+ *
+ * Reference: https://gist.github.com/tommyettinger/46a3a48c0d7fe27ea3aaa5fa8f1ba0e8
+ */
+/**
+ * Create a deterministic PRNG seeded by a 32-bit unsigned integer.
+ *
+ * For string seeds, use {@link rngFromString}.
+ */
+export const mulberry32 = (seed) => {
+    // Force u32.
+    let state = seed >>> 0;
+    const next = () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    return {
+        next,
+        int(min, max) {
+            if (!Number.isFinite(min) || !Number.isFinite(max)) {
+                throw new RangeError(`rng.int requires finite bounds, got [${min}, ${max}]`);
+            }
+            if (min > max)
+                throw new RangeError(`rng.int: min (${min}) > max (${max})`);
+            const lo = Math.ceil(min);
+            const hi = Math.floor(max);
+            return lo + Math.floor(next() * (hi - lo + 1));
+        },
+        pick(items) {
+            if (items.length === 0)
+                throw new RangeError('rng.pick: empty array');
+            const idx = Math.floor(next() * items.length);
+            // Safe: idx ∈ [0, items.length-1]
+            return items[idx];
+        },
+    };
+};
+/** Derive a 32-bit unsigned seed from an arbitrary string (FNV-1a 32-bit). */
+export const seedFromString = (s) => {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i += 1) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+};
+/** Convenience: build an Rng from a string seed. */
+export const rngFromString = (s) => mulberry32(seedFromString(s));
+//# sourceMappingURL=prng.js.map

package/dist/foundation/prng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prng.js","sourceRoot":"","sources":["../../src/foundation/prng.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAO,EAAE;IAC9C,aAAa;IACb,IAAI,KAAK,GAAG,IAAI,KAAK,CAAC,CAAA;IAEtB,MAAM,IAAI,GAAG,GAAW,EAAE;QACxB,KAAK,GAAG,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;QAClC,IAAI,CAAC,GAAG,KAAK,CAAA;QACb,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;QACpC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAA;QACzC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,UAAU,CAAA;IAC9C,CAAC,CAAA;IAED,OAAO;QACL,IAAI;QACJ,GAAG,CAAC,GAAG,EAAE,GAAG;YACV,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnD,MAAM,IAAI,UAAU,CAAC,wCAAwC,GAAG,KAAK,GAAG,GAAG,CAAC,CAAA;YAC9E,CAAC;YACD,IAAI,GAAG,GAAG,GAAG;gBAAE,MAAM,IAAI,UAAU,CAAC,iBAAiB,GAAG,YAAY,GAAG,GAAG,CAAC,CAAA;YAC3E,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YACzB,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;YAC1B,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAA;QAChD,CAAC;QACD,IAAI,CAAI,KAAmB;YACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,UAAU,CAAC,uBAAuB,CAAC,CAAA;YACrE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;YAC7C,kCAAkC;YAClC,OAAO,KAAK,CAAC,GAAG,CAAM,CAAA;QACxB,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAS,EAAU,EAAE;IAClD,IAAI,CAAC,GAAG,UAAU,CAAA;IAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;QACpB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CAAA;IAC9B,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,CAAA;AAChB,CAAC,CAAA;AAED,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAS,EAAO,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/foundation/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Phantom-typed schema builder + Infer<>.
+ *
+ * Every builder carries:
+ *   - `_node`: serializable IR (runtime)
+ *   - `_type`: phantom TS type parameter for inference (compile-time only)
+ *
+ * Modifiers (.nullable / .optional / .default / .describe) return a *new*
+ * builder with updated phantom type and updated IR.
+ */
+import type { Axes, DerivedFn, Distribution, DomainConstraint, InvariantFn } from './axes.js';
+import type { Modifiers, SchemaNode } from './ir.js';
+/**
+ * Module-private capability marker symbol keys.
+ *
+ * Schemas opt into a capability by `declare`ing the corresponding bracketed
+ * property as the literal `true`. Methods like `.weighted` / `.normal` /
+ * `.typically` then gate themselves with a `this:` constraint that requires
+ * the marker. Symbols (rather than string keys like `_capDiscrete`) keep the
+ * markers out of consumer IntelliSense and out of any `Object.keys` loop.
+ *
+ * Three caps are required to mirror the runtime allow-list cleanly:
+ *
+ *   - `Discrete`   — values are enumerable; `.weighted` is meaningful.
+ *                    Carried by `str / int / bool / literal / enum`.
+ *   - `Numeric`    — values are bounded numerics; `.typically(from, to)` is
+ *                    meaningful (the generator clamps and, for integers,
+ *                    rounds). Carried by `num / int / decimal`.
+ *   - `Continuous` — values are real-valued; `.normal(mean, σ)` is
+ *                    meaningful (Gaussian on integers would silently lose
+ *                    σ to rounding, so int is excluded). Carried by
+ *                    `num / decimal`.
+ *
+ * The symbols are real runtime values so subclass files can `import` them
+ * to redeclare the marker. They are NOT re-exported from the package root
+ * or from `@databehave/schema/internal`; the package's `exports` field
+ * limits deep-path imports to those two entries.
+ */
+export declare const Discrete: unique symbol;
+export declare const Numeric: unique symbol;
+export declare const Continuous: unique symbol;
+/** Base builder. Subclasses (StringSchema, NumberSchema, …) extend this. */
+export declare class Schema<T = unknown> {
+    readonly _type: T;
+    readonly _node: SchemaNode;
+    readonly [Discrete]: boolean;
+    readonly [Numeric]: boolean;
+    readonly [Continuous]: boolean;
+    constructor(node: SchemaNode);
+    nullable(): Schema<T | null>;
+    optional(): Schema<T | undefined>;
+    default(value: T): Schema<T>;
+    describe(text: string): this;
+    /** Weighted distribution over discrete values. Weights are relative. */
+    weighted(this: this & {
+        readonly [Discrete]: true;
+    }, weights: ReadonlyArray<readonly [T & (string | number | boolean), number]>): this;
+    /** Normal (Gaussian) distribution for numeric schemas. */
+    normal(this: this & {
+        readonly [Continuous]: true;
+    }, mean: number, stddev: number): this;
+    /** Typical range — values concentrate uniformly inside [from, to]. */
+    typically(this: this & {
+        readonly [Numeric]: true;
+    }, from: number, to: number): this;
+    /** Force `value` with probability `p` (stacks before base distribution). */
+    occasionally(value: T, p: number): this;
+    /**
+     * Force `value` every `every` rows (deterministic, driven by `ctx.index`).
+     *
+     * Useful for periodic rare events that must hit at a guaranteed cadence
+     * (e.g. a recurring reset every N rows). Skipped when `ctx.index` is undefined.
+     */
+    eventually(every: number, value: T, opts?: {
+        readonly offset?: number;
+    }): this;
+    /**
+     * Field is computed from sibling/root context — generator skips sampling.
+     *
+     * The generic `U extends T` ensures the function's return type is
+     * assignable to the schema's value type. Combined with `relate(rows, field)`
+     * (which propagates `R[K]` through `DerivedFn<R[K]>`), this catches
+     * FK-type mismatches at compile time
+     * (e.g. `int().derivedFrom(relate(rowsWithStringSku, 'sku'))`).
+     */
+    derivedFrom<U extends T>(fn: DerivedFn<U>): this;
+    /** Single-record predicate. Generator retries up to MAX_ATTEMPTS to satisfy. */
+    invariant(fn: InvariantFn): this;
+    /** Restrict to a closed candidate set or a lookup-by-sibling-field map. */
+    in(constraint: DomainConstraint | readonly unknown[]): this;
+    /**
+     * Re-apply a complete `Axes` record to this schema. Public so that
+     * IR-reconstruction helpers (e.g. `fromIR`) can replay axes without
+     * reaching through a protected method via casts. Prefer the fluent axis
+     * builders (`.weighted`, `.in`, `.derivedFrom`, ...) in user code.
+     *
+     * Note: this is a low-level escape hatch — it does NOT run the
+     * capability allow-list that `.weighted` / `.normal` / `.typically`
+     * apply. Callers that round-trip IR are trusted to keep the IR coherent.
+     */
+    _applyAxes(axes: Axes): this;
+    protected withAxes(axes: Axes): this;
+    protected withModsPreserveType(patch: Partial<Modifiers>): this;
+}
+/**
+ * Infer the TypeScript type a schema generates / accepts.
+ *
+ * ```ts
+ * const User = obj({ id: int(), name: str() })
+ * type User = Infer<typeof User>  // { id: number; name: string }
+ * ```
+ */
+export type Infer<S> = S extends Schema<infer T> ? T : never;
+/** Re-export modifier shape for advanced consumers. */
+export type { Distribution, DomainConstraint, Modifiers, SchemaNode };
+//# sourceMappingURL=types.d.ts.map

package/dist/foundation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/foundation/types.ts"],"names":[],"mappings":"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"}

package/dist/foundation/types.js

@@ -0,0 +1,188 @@
+/**
+ * Phantom-typed schema builder + Infer<>.
+ *
+ * Every builder carries:
+ *   - `_node`: serializable IR (runtime)
+ *   - `_type`: phantom TS type parameter for inference (compile-time only)
+ *
+ * Modifiers (.nullable / .optional / .default / .describe) return a *new*
+ * builder with updated phantom type and updated IR.
+ */
+import { SchemaConflictError } from './errors.js';
+import { withMods } from './ir.js';
+/**
+ * Module-private capability marker symbol keys.
+ *
+ * Schemas opt into a capability by `declare`ing the corresponding bracketed
+ * property as the literal `true`. Methods like `.weighted` / `.normal` /
+ * `.typically` then gate themselves with a `this:` constraint that requires
+ * the marker. Symbols (rather than string keys like `_capDiscrete`) keep the
+ * markers out of consumer IntelliSense and out of any `Object.keys` loop.
+ *
+ * Three caps are required to mirror the runtime allow-list cleanly:
+ *
+ *   - `Discrete`   — values are enumerable; `.weighted` is meaningful.
+ *                    Carried by `str / int / bool / literal / enum`.
+ *   - `Numeric`    — values are bounded numerics; `.typically(from, to)` is
+ *                    meaningful (the generator clamps and, for integers,
+ *                    rounds). Carried by `num / int / decimal`.
+ *   - `Continuous` — values are real-valued; `.normal(mean, σ)` is
+ *                    meaningful (Gaussian on integers would silently lose
+ *                    σ to rounding, so int is excluded). Carried by
+ *                    `num / decimal`.
+ *
+ * The symbols are real runtime values so subclass files can `import` them
+ * to redeclare the marker. They are NOT re-exported from the package root
+ * or from `@databehave/schema/internal`; the package's `exports` field
+ * limits deep-path imports to those two entries.
+ */
+export const Discrete = Symbol('databehave.cap.discrete');
+export const Numeric = Symbol('databehave.cap.numeric');
+export const Continuous = Symbol('databehave.cap.continuous');
+/**
+ * Allow-list for which IR kinds may legally carry each axis distribution.
+ *
+ * Mirrors the type-system `this:` gating on `.weighted` / `.normal` /
+ * `.typically`. Used by the runtime guard in those methods to fail-loud
+ * when a caller bypasses TypeScript (`as any`, plain JS, `// @ts-ignore`).
+ *
+ * Stays in sync with `docs/stability.md` "capability matrix".
+ */
+const CAP_BY_OP = {
+    // .weighted: discrete-valued kinds. For `kind:'number'` it is allowed only
+    // when `int === true` (further check below).
+    weighted: new Set(['number', 'string', 'literal', 'enum', 'boolean']),
+    // .normal: continuous-numeric kinds. For `kind:'number'` it is allowed
+    // only when `int === false` (further check below).
+    normal: new Set(['number', 'decimal']),
+    // .typically: any numeric kind (int or float or decimal — for ints the
+    // generator clamps and rounds).
+    typically: new Set(['number', 'decimal']),
+};
+const checkAxisAllowed = (op, node) => {
+    if (!CAP_BY_OP[op].has(node.kind)) {
+        throw new SchemaConflictError(`.${op}() is not applicable to schema kind '${node.kind}'`, [], `see docs/stability.md (capability matrix)`);
+    }
+    // Number-kind is split between `int()` (discrete) and `num()` (continuous).
+    if (node.kind === 'number') {
+        const isInt = node.int === true;
+        if (op === 'weighted' && !isInt) {
+            throw new SchemaConflictError(`.weighted() is not applicable to num() (continuous); use int().weighted([...]) for discrete numeric weighting`, [], `see docs/stability.md (capability matrix)`);
+        }
+        if (op === 'normal' && isInt) {
+            throw new SchemaConflictError(`.normal() is not applicable to int() (discrete); use num().normal(...) for a continuous Gaussian`, [], `see docs/stability.md (capability matrix)`);
+        }
+    }
+};
+/** Base builder. Subclasses (StringSchema, NumberSchema, …) extend this. */
+export class Schema {
+    _node;
+    constructor(node) {
+        this._node = node;
+    }
+    nullable() {
+        return new Schema(withMods(this._node, { nullable: true }));
+    }
+    optional() {
+        return new Schema(withMods(this._node, { optional: true }));
+    }
+    default(value) {
+        return new Schema(withMods(this._node, { hasDefault: true, defaultValue: value }));
+    }
+    describe(text) {
+        return this.withModsPreserveType({ description: text });
+    }
+    // ── data-schema axes ──────────────────────────────────────────────────────
+    /** Weighted distribution over discrete values. Weights are relative. */
+    weighted(weights) {
+        checkAxisAllowed('weighted', this._node);
+        return this.withAxes({
+            distribution: {
+                kind: 'weighted',
+                weights: weights,
+            },
+        });
+    }
+    /** Normal (Gaussian) distribution for numeric schemas. */
+    normal(mean, stddev) {
+        checkAxisAllowed('normal', this._node);
+        return this.withAxes({ distribution: { kind: 'normal', mean, stddev } });
+    }
+    /** Typical range — values concentrate uniformly inside [from, to]. */
+    typically(from, to) {
+        checkAxisAllowed('typically', this._node);
+        return this.withAxes({ distribution: { kind: 'typical', from, to } });
+    }
+    /** Force `value` with probability `p` (stacks before base distribution). */
+    occasionally(value, p) {
+        if (!(p >= 0 && p <= 1))
+            throw new RangeError(`occasionally: p must be in [0,1], got ${p}`);
+        const override = { value, p };
+        return this.withAxes({ occasionally: [override] });
+    }
+    /**
+     * Force `value` every `every` rows (deterministic, driven by `ctx.index`).
+     *
+     * Useful for periodic rare events that must hit at a guaranteed cadence
+     * (e.g. a recurring reset every N rows). Skipped when `ctx.index` is undefined.
+     */
+    eventually(every, value, opts) {
+        if (!Number.isInteger(every) || every < 1) {
+            throw new RangeError(`eventually: every must be a positive integer, got ${every}`);
+        }
+        const override = {
+            value,
+            every,
+            ...(opts?.offset !== undefined ? { offset: opts.offset } : {}),
+        };
+        return this.withAxes({ eventually: [override] });
+    }
+    /**
+     * Field is computed from sibling/root context — generator skips sampling.
+     *
+     * The generic `U extends T` ensures the function's return type is
+     * assignable to the schema's value type. Combined with `relate(rows, field)`
+     * (which propagates `R[K]` through `DerivedFn<R[K]>`), this catches
+     * FK-type mismatches at compile time
+     * (e.g. `int().derivedFrom(relate(rowsWithStringSku, 'sku'))`).
+     */
+    derivedFrom(fn) {
+        return this.withAxes({ derived: fn });
+    }
+    /** Single-record predicate. Generator retries up to MAX_ATTEMPTS to satisfy. */
+    invariant(fn) {
+        return this.withAxes({ invariants: [fn] });
+    }
+    /** Restrict to a closed candidate set or a lookup-by-sibling-field map. */
+    in(constraint) {
+        const dom = Array.isArray(constraint)
+            ? { kind: 'values', values: constraint }
+            : constraint;
+        return this.withAxes({ domain: dom });
+    }
+    // ── internal helpers ──────────────────────────────────────────────────────
+    /**
+     * Re-apply a complete `Axes` record to this schema. Public so that
+     * IR-reconstruction helpers (e.g. `fromIR`) can replay axes without
+     * reaching through a protected method via casts. Prefer the fluent axis
+     * builders (`.weighted`, `.in`, `.derivedFrom`, ...) in user code.
+     *
+     * Note: this is a low-level escape hatch — it does NOT run the
+     * capability allow-list that `.weighted` / `.normal` / `.typically`
+     * apply. Callers that round-trip IR are trusted to keep the IR coherent.
+     */
+    _applyAxes(axes) {
+        return this.withModsPreserveType({ axes });
+    }
+    withAxes(axes) {
+        return this.withModsPreserveType({ axes });
+    }
+    withModsPreserveType(patch) {
+        const next = Object.create(Object.getPrototypeOf(this));
+        Object.assign(next, this, {
+            _node: withMods(this._node, patch),
+        });
+        return next;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/foundation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/foundation/types.ts"],"names":[],"mappings":"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"}

package/dist/foundation/walk.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Extensibility API — IR walker and IR-to-builder reconstruction.
+ *
+ * databehave intentionally ships no CLI, no OpenAPI ingestion, no zod adapter,
+ * no GUI — these belong in *external* packages. This module exposes the
+ * minimum surface those packages need:
+ *
+ *   - `walkSchema(node, visitor)` : pre/post-order traversal with paths
+ *   - `fromIR(node)`              : reconstruct a `Schema` builder from IR
+ *
+ * Combined with the already-public `SchemaNode`, `Modifiers`, `Axes`,
+ * `mock`, `parse`, `mockDataset`, `createTrace`, and `seedFromString` /
+ * `rngFromString`, this is the full extension contract.
+ *
+ * Extension authors do NOT subclass `Schema`. They build IR (or compose
+ * existing builders) and call `fromIR` to obtain a typed builder back.
+ */
+import { Schema } from './types.js';
+import type { SchemaNode } from './ir.js';
+export type WalkPath = readonly (string | number)[];
+export type SchemaVisitor = {
+    /** Called before descending into a node's children. Return false to skip subtree. */
+    readonly enter?: (node: SchemaNode, path: WalkPath) => void | boolean;
+    /** Called after all children have been visited. */
+    readonly leave?: (node: SchemaNode, path: WalkPath) => void;
+};
+/**
+ * Depth-first pre/post-order traversal of a schema IR tree.
+ *
+ * The visitor receives every node (including composites) with its
+ * JSON-pointer-style path. Use this to power codegen (OpenAPI, zod, SQL DDL,
+ * documentation) without coupling to the builder classes.
+ */
+export declare const walkSchema: (schemaOrNode: Schema | SchemaNode, visitor: SchemaVisitor) => void;
+/**
+ * Reconstruct a `Schema` builder from an IR node.
+ *
+ * Modifiers (`nullable`, `optional`, `default`, `describe`, axes) are
+ * preserved. Returns `Schema<unknown>` — extension authors that know the shape
+ * statically can cast to a more precise type.
+ */
+export declare const fromIR: (node: SchemaNode) => Schema<unknown>;
+/** Current IR contract version. Bumped on every MAJOR release. */
+export declare const IR_VERSION: 1;
+/** Envelope produced by {@link serializeSchema}. */
+export interface SchemaEnvelope {
+    /** Reserved for forward compatibility; do not vary. */
+    readonly $databehaveVersion: typeof IR_VERSION;
+    readonly node: SchemaNode;
+}
+/**
+ * Wrap a schema's IR in a versioned envelope safe for serialisation
+ * (JSON, disk, IPC). Pair with {@link deserializeSchema} on the
+ * receiving end.
+ *
+ * Throws {@link SchemaConflictError} (`code: 'serialize.closure-axis'`)
+ * when any node in the tree carries a closure-bearing axis — `derived`,
+ * `invariants`, or an `occasionally` override whose `value` is a
+ * function. Closures cannot survive a JSON round-trip, so encoding such
+ * a schema would silently drop the axis on the receiving end and
+ * produce subtly wrong values. The check is loud at the encode site so
+ * callers reach for {@link replay} or hand-coded carriers instead.
+ */
+export declare const serializeSchema: (schema: Schema<unknown>) => SchemaEnvelope;
+/**
+ * Inverse of {@link serializeSchema}. Throws when the envelope was
+ * produced by an incompatible MAJOR version — the failure is loud
+ * because silently loading a node with a renamed or removed field
+ * would manifest as a subtle generation/parse bug far from the cause.
+ */
+export declare const deserializeSchema: (envelope: unknown) => Schema<unknown>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/foundation/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../src/foundation/walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAcH,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;AAEnD,MAAM,MAAM,aAAa,GAAG;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAA;IACrE,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAA;CAC5D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GACrB,cAAc,MAAM,GAAG,UAAU,EACjC,SAAS,aAAa,KACrB,IAGF,CAAA;AAkCD;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,UAAU,KAAG,MAAM,CAAC,OAAO,CAGvD,CAAA;AA2FD,kEAAkE;AAClE,eAAO,MAAM,UAAU,EAAG,CAAU,CAAA;AAEpC,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,kBAAkB,EAAE,OAAO,UAAU,CAAA;IAC9C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,CAAC,OAAO,CAAC,KAAG,cAMzD,CAAA;AA+DD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,OAAO,KAAG,MAAM,CAAC,OAAO,CAmBnE,CAAA"}