@databehave/schema 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+Upcoming package version: **0.2.0**. This section describes planned release contents, not a published release.
+
+### Breaking changes
+
+- Require Node.js 24 or 26; support and test majors 24 and 26. Drop Node.js 18, 20 and 22.
+- Replace the closed IR node union with open `SchemaNode` and built-in `StandardSchemaNode` contracts. Serialized IR
+  version 2 records exact kind/behavior contracts; version 1 requires explicit migration.
+- Allow plugin-defined issue codes and enforce primitive invariants during validation.
+
+### Added
+
+- Sealed instance-local kind and behavior registries, typed descriptors, scoped sampling and runtime methods for
+  nested generation, validation, datasets, traversal, replay and serialization.
+- `/runtime`, `/standard` and optional `/plugin` entry points. Standard convenience builders/functions remain available.
+- Public plugin, runtime support and migration guides, plus runnable public API examples.
+
+See [migration](../../MIGRATION.md) and [release procedures](../../docs/releasing.md).
+
 ## [0.1.0] - 2026-06-03
 
 Initial public release of `@databehave/schema`.

package/README.md

@@ -8,7 +8,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@databehave/schema.svg)](https://www.npmjs.com/package/@databehave/schema)
 [![CI](https://github.com/ochairo/databehave/actions/workflows/ci.yml/badge.svg)](https://github.com/ochairo/databehave/actions/workflows/ci.yml)
-[![Node.js](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-24%20%7C%2026-brightgreen)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 </div>
@@ -17,6 +17,9 @@ Most schema libraries describe what shape your data has. @databehave/schema desc
 
 ## Install
 
+The upcoming release requires Node.js 24 or 26; supported majors are 24 and 26.
+See the [workspace documentation](../../docs/index.md) and [runnable schema example](../../examples/schema.mjs).
+
 ```sh
 npm install @databehave/schema
 # or: pnpm add @databehave/schema
@@ -108,3 +111,11 @@ const Tier = enum_(['A', 'B', 'C']).weighted([['A', 0.7], ['B', 0.2], ['C', 0.1]
 © 2026-present ochairo. See [LICENSE](LICENSE)
 
 </div>
+
+### Composable schema runtime
+
+Use `createSchemaRuntime({ kinds, behaviors })` for explicit plugin composition. The `standardKinds` and
+`standardBehaviors` groups use the same public descriptors as external kinds and behaviors. Runtime operations,
+including nested generation, validation, traversal, datasets, replay and versioned serialization, retain the selected
+registry. See [schema plugins](docs/extending.md) for authoring and migration details. The standalone runtime needs no
+application host or HTTP transport.

package/dist/dataset/dataset.d.ts

@@ -0,0 +1,6 @@
+import type { Infer, Schema } from '../foundation/types.js';
+import { type DatasetOptions } from './generate.js';
+export { identityFor, type DatasetOptions } from './generate.js';
+/** Standard convenience composition; runtime.mockDataset binds a selected registry. */
+export declare const mockDataset: <S extends Schema>(options: DatasetOptions<S>) => Infer<S>[];
+//# sourceMappingURL=dataset.d.ts.map

package/dist/dataset/dataset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../../src/dataset/dataset.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAE3D,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AACpE,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAChE,uFAAuF;AACvF,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,CAAC,EAAoC,CAAA"}

package/dist/dataset/dataset.js

@@ -0,0 +1,6 @@
+import { mock } from '../generator/engine.js';
+import { generateDataset } from './generate.js';
+export { identityFor } from './generate.js';
+/** Standard convenience composition; runtime.mockDataset binds a selected registry. */
+export const mockDataset = (options) => generateDataset(options, mock);
+//# sourceMappingURL=dataset.js.map

package/dist/dataset/dataset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.js","sourceRoot":"","sources":["../../src/dataset/dataset.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAuB,MAAM,eAAe,CAAA;AACpE,OAAO,EAAE,WAAW,EAAuB,MAAM,eAAe,CAAA;AAChE,uFAAuF;AACvF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAmB,OAA0B,EAAc,EAAE,CAAC,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA"}

package/dist/dataset/generate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Dataset abstraction.
+ *
+ * A Dataset is a collection of records that share:
+ *   - a per-record schema `S`
+ *   - identity keys `K` (same identity → same value, cross-endpoint)
+ *   - a record count `N`
+ *   - aggregate invariants `J` (predicates over the full record list)
+ *
+ * Identity uniqueness contract:
+ *   The dataset will not silently return two rows with the same identity
+ *   tuple. When generation produces a colliding identity, the row is
+ *   re-sampled with a fresh sub-seed up to `DEDUP_ATTEMPTS_PER_ROW` times;
+ *   if still colliding, a `SchemaConflictError` is thrown (your identity
+ *   domain is too small for `n`).
+ */
+import type { SchemaRuntime } from '../runtime/runtime.js';
+import type { Infer, Schema } from '../foundation/types.js';
+export type DatasetOptions<S extends Schema> = {
+    /** Unique dataset name (participates in the identity seed). */
+    readonly name: string;
+    /** Record-level schema. */
+    readonly schema: S;
+    /** Field names whose tuple defines a record's identity. */
+    readonly identity: readonly string[];
+    /** Number of records to generate per `mockDataset` call. */
+    readonly n: number;
+    /** Aggregate invariants — applied to the full record list, with bounded retries. */
+    readonly invariants?: readonly ((rows: readonly Infer<S>[]) => boolean)[];
+    /** Caller-supplied context channel exposed to derived/invariants as `ctx.input`. */
+    readonly input?: Readonly<Record<string, unknown>>;
+    /** Optional seed prefix; if omitted, the dataset name is used. */
+    readonly seedPrefix?: string;
+};
+/**
+ * Generate `n` records that conform to the schema and satisfy all aggregate
+ * invariants. Each row carries a unique identity tuple (collisions are
+ * re-sampled; if the identity domain is exhausted, `SchemaConflictError`
+ * is thrown).
+ */
+/** Dataset policy receives the selected runtime's generator. */
+export declare const generateDataset: <S extends Schema>(opts: DatasetOptions<S>, generate: SchemaRuntime["mock"]) => Infer<S>[];
+/**
+ * Produce the deterministic identity key for a record. Two records with the
+ * same identity values produce the same key. `null` and `undefined` are
+ * distinguished from each other.
+ */
+export declare const identityFor: (datasetName: string, identityKeys: readonly string[], row: Record<string, unknown>) => string;
+//# sourceMappingURL=generate.d.ts.map

package/dist/dataset/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/dataset/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAE3D,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,CAAA;IACzE,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAClD,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAYD;;;;;GAKG;AACH,gEAAgE;AAChE,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,EAAE,MAAM,cAAc,CAAC,CAAC,CAAC,EAAE,UAAU,aAAa,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,CAAC,CAAC,EA6CpH,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,aAAa,MAAM,EACnB,cAAc,SAAS,MAAM,EAAE,EAC/B,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,MAUF,CAAA"}

package/dist/dataset/generate.js

@@ -0,0 +1,96 @@
+/**
+ * Dataset abstraction.
+ *
+ * A Dataset is a collection of records that share:
+ *   - a per-record schema `S`
+ *   - identity keys `K` (same identity → same value, cross-endpoint)
+ *   - a record count `N`
+ *   - aggregate invariants `J` (predicates over the full record list)
+ *
+ * Identity uniqueness contract:
+ *   The dataset will not silently return two rows with the same identity
+ *   tuple. When generation produces a colliding identity, the row is
+ *   re-sampled with a fresh sub-seed up to `DEDUP_ATTEMPTS_PER_ROW` times;
+ *   if still colliding, a `SchemaConflictError` is thrown (your identity
+ *   domain is too small for `n`).
+ */
+import { SchemaConflictError } from '../foundation/errors.js';
+import { identityKey } from '../foundation/hash.js';
+/**
+ * Number of full dataset re-rolls on top of the initial attempt. Each retry
+ * uses a *different* per-row seed (the loop variable is folded into the seed
+ * string), so retries can absorb aggregate-invariant rejection without the
+ * user having to widen the schema. Raise this only after verifying that the
+ * declared invariants are satisfiable for the chosen `n`.
+ */
+const MAX_DATASET_RETRIES = 1;
+const DEDUP_ATTEMPTS_PER_ROW = 8;
+/**
+ * Generate `n` records that conform to the schema and satisfy all aggregate
+ * invariants. Each row carries a unique identity tuple (collisions are
+ * re-sampled; if the identity domain is exhausted, `SchemaConflictError`
+ * is thrown).
+ */
+/** Dataset policy receives the selected runtime's generator. */
+export const generateDataset = (opts, generate) => {
+    const totalAttempts = MAX_DATASET_RETRIES + 1;
+    for (let attempt = 0; attempt < totalAttempts; attempt += 1) {
+        const seen = new Set();
+        const rows = [];
+        let collided = false;
+        for (let i = 0; i < opts.n; i += 1) {
+            let row;
+            let key = '';
+            for (let dedup = 0; dedup < DEDUP_ATTEMPTS_PER_ROW; dedup += 1) {
+                const rowSeed = `${opts.seedPrefix ?? opts.name}:row:${i}:attempt:${attempt}:dedup:${dedup}`;
+                const candidate = generate(opts.schema, {
+                    seed: rowSeed,
+                    index: i,
+                    ...(opts.input !== undefined ? { input: opts.input } : {}),
+                });
+                const k = identityFor(opts.name, opts.identity, candidate);
+                if (!seen.has(k)) {
+                    row = candidate;
+                    key = k;
+                    break;
+                }
+            }
+            if (row === undefined) {
+                collided = true;
+                break;
+            }
+            seen.add(key);
+            rows.push(row);
+        }
+        if (collided) {
+            // Try next dataset-level attempt with a different seed family.
+            continue;
+        }
+        const invariants = opts.invariants ?? [];
+        if (invariants.every((j) => j(rows)))
+            return rows;
+    }
+    throw new SchemaConflictError(`dataset "${opts.name}": could not satisfy identity uniqueness or aggregate invariants ` +
+        `after ${MAX_DATASET_RETRIES + 1} dataset attempt(s) ` +
+        `× ${DEDUP_ATTEMPTS_PER_ROW} dedup retries`, [opts.name], 'widen the identity domain, lower n, or relax aggregate invariants');
+};
+/**
+ * Produce the deterministic identity key for a record. Two records with the
+ * same identity values produce the same key. `null` and `undefined` are
+ * distinguished from each other.
+ */
+export const identityFor = (datasetName, identityKeys, row) => {
+    const parts = {};
+    for (const k of identityKeys) {
+        const v = row[k];
+        // Distinguish "missing" / "explicit null" / "explicit undefined".
+        if (v === undefined)
+            parts[k] = '__undef__';
+        else if (v === null)
+            parts[k] = '__null__';
+        else
+            parts[k] = JSON.stringify(v);
+    }
+    return identityKey('DATASET', datasetName, parts);
+};
+//# sourceMappingURL=generate.js.map

package/dist/dataset/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../src/dataset/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAqBnD;;;;;;GAMG;AACH,MAAM,mBAAmB,GAAG,CAAC,CAAA;AAC7B,MAAM,sBAAsB,GAAG,CAAC,CAAA;AAEhC;;;;;GAKG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAmB,IAAuB,EAAE,QAA+B,EAAc,EAAE;IACxH,MAAM,aAAa,GAAG,mBAAmB,GAAG,CAAC,CAAA;IAC7C,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;QAC9B,MAAM,IAAI,GAAe,EAAE,CAAA;QAC3B,IAAI,QAAQ,GAAG,KAAK,CAAA;QACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,IAAI,GAAyB,CAAA;YAC7B,IAAI,GAAG,GAAG,EAAE,CAAA;YACZ,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,sBAAsB,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC/D,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,QAAQ,CAAC,YAAY,OAAO,UAAU,KAAK,EAAE,CAAA;gBAC5F,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE;oBACtC,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,CAAC;oBACR,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC3D,CAAC,CAAA;gBACF,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAoC,CAAC,CAAA;gBACrF,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;oBACjB,GAAG,GAAG,SAAS,CAAA;oBACf,GAAG,GAAG,CAAC,CAAA;oBACP,MAAK;gBACP,CAAC;YACH,CAAC;YACD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,QAAQ,GAAG,IAAI,CAAA;gBACf,MAAK;YACP,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACb,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAChB,CAAC;QACD,IAAI,QAAQ,EAAE,CAAC;YACb,+DAA+D;YAC/D,SAAQ;QACV,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,CAAA;QACxC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,IAAI,CAAA;IACnD,CAAC;IACD,MAAM,IAAI,mBAAmB,CAC3B,YAAY,IAAI,CAAC,IAAI,mEAAmE;QACtF,SAAS,mBAAmB,GAAG,CAAC,sBAAsB;QACtD,KAAK,sBAAsB,gBAAgB,EAC7C,CAAC,IAAI,CAAC,IAAI,CAAC,EACX,mEAAmE,CACpE,CAAA;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,WAAmB,EACnB,YAA+B,EAC/B,GAA4B,EACpB,EAAE;IACV,MAAM,KAAK,GAA2B,EAAE,CAAA;IACxC,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAA;QAChB,kEAAkE;QAClE,IAAI,CAAC,KAAK,SAAS;YAAE,KAAK,CAAC,CAAC,CAAC,GAAG,WAAW,CAAA;aACtC,IAAI,CAAC,KAAK,IAAI;YAAE,KAAK,CAAC,CAAC,CAAC,GAAG,UAAU,CAAA;;YACrC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;IACnC,CAAC;IACD,OAAO,WAAW,CAAC,SAAS,EAAE,WAAW,EAAE,KAAK,CAAC,CAAA;AACnD,CAAC,CAAA"}

package/dist/dataset/relate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cross-dataset FK identity — declarative foreign-key lookup.
+ *
+ * `relate(rows, field)` returns a `DerivedFn` suitable for `.derivedFrom(...)`
+ * that picks one row from a previously-generated dataset and returns its
+ * `field` value. Selection is deterministic, driven by the generator seed,
+ * so re-runs with the same seed produce the same FK assignments.
+ *
+ * ```ts
+ * const Groups = mockDataset({ name: 'groups', schema: Group, identity: ['group_code'], n: 5 })
+ *
+ * const Item = obj({
+ *   item_id:    str(),
+ *   group_code: str().derivedFrom(relate(Groups, 'group_code')),  // FK
+ * })
+ * ```
+ *
+ * For ad-hoc cross-row selection (e.g. by index or condition), use the
+ * `pickBy` option.
+ */
+import type { DerivedFn, GenContext } from '../foundation/axes.js';
+export type RelateOptions = {
+    /**
+     * Strategy to pick a row.
+     *   - `'random'` (default): seeded uniform sample
+     *   - `'index'`            : `rows[ctx.index % rows.length]`
+     *   - `(ctx) => number`    : custom index resolver
+     */
+    readonly pickBy?: 'random' | 'index' | ((ctx: GenContext) => number);
+};
+export declare const relate: <R extends Record<string, unknown>, K extends Extract<keyof R, string>>(rows: readonly R[], field: K, opts?: RelateOptions) => DerivedFn<R[K]>;
+//# sourceMappingURL=relate.d.ts.map

package/dist/dataset/relate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relate.d.ts","sourceRoot":"","sources":["../../src/dataset/relate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAGlE,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,CAAC,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,CAAC,CAAA;CACrE,CAAA;AAED,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAC1F,MAAM,SAAS,CAAC,EAAE,EAClB,OAAO,CAAC,EACR,OAAM,aAAkB,KACvB,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAqBhB,CAAA"}

package/dist/dataset/relate.js

@@ -0,0 +1,46 @@
+/**
+ * Cross-dataset FK identity — declarative foreign-key lookup.
+ *
+ * `relate(rows, field)` returns a `DerivedFn` suitable for `.derivedFrom(...)`
+ * that picks one row from a previously-generated dataset and returns its
+ * `field` value. Selection is deterministic, driven by the generator seed,
+ * so re-runs with the same seed produce the same FK assignments.
+ *
+ * ```ts
+ * const Groups = mockDataset({ name: 'groups', schema: Group, identity: ['group_code'], n: 5 })
+ *
+ * const Item = obj({
+ *   item_id:    str(),
+ *   group_code: str().derivedFrom(relate(Groups, 'group_code')),  // FK
+ * })
+ * ```
+ *
+ * For ad-hoc cross-row selection (e.g. by index or condition), use the
+ * `pickBy` option.
+ */
+import { mulberry32, seedFromString } from '../foundation/prng.js';
+export const relate = (rows, field, opts = {}) => {
+    if (rows.length === 0) {
+        throw new RangeError(`relate: empty dataset (cannot pick field "${field}")`);
+    }
+    const strategy = opts.pickBy ?? 'random';
+    return (ctx) => {
+        let idx;
+        if (strategy === 'index') {
+            idx = (ctx.index ?? 0) % rows.length;
+        }
+        else if (typeof strategy === 'function') {
+            // `((x % n) + n) % n` normalises negative results into [0, n)
+            // without the cost of `Math.abs` (which also changes magnitude).
+            const n = rows.length;
+            idx = ((strategy(ctx) % n) + n) % n;
+        }
+        else {
+            // Deterministic uniform: derive a sub-RNG from the path-bound seed.
+            const rng = mulberry32(seedFromString(`${ctx.seed}|relate|${field}`));
+            idx = Math.floor(rng.next() * rows.length);
+        }
+        return rows[idx][field];
+    };
+};
+//# sourceMappingURL=relate.js.map

package/dist/dataset/relate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relate.js","sourceRoot":"","sources":["../../src/dataset/relate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAYlE,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,IAAkB,EAClB,KAAQ,EACR,OAAsB,EAAE,EACP,EAAE;IACnB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,UAAU,CAAC,6CAA6C,KAAK,IAAI,CAAC,CAAA;IAC9E,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAA;IACxC,OAAO,CAAC,GAAe,EAAQ,EAAE;QAC/B,IAAI,GAAW,CAAA;QACf,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;YACzB,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAA;QACtC,CAAC;aAAM,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;YAC1C,8DAA8D;YAC9D,iEAAiE;YACjE,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAA;YACrB,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;QACrC,CAAC;aAAM,CAAC;YACN,oEAAoE;YACpE,MAAM,GAAG,GAAG,UAAU,CAAC,cAAc,CAAC,GAAG,GAAG,CAAC,IAAI,WAAW,KAAK,EAAE,CAAC,CAAC,CAAA;YACrE,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,CAAC;QACD,OAAQ,IAAI,CAAC,GAAG,CAAO,CAAC,KAAK,CAAC,CAAA;IAChC,CAAC,CAAA;AACH,CAAC,CAAA"}

package/dist/foundation/axes.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Data-schema axes.
+ *
+ * Each axis is optional metadata attached to a schema node via `Modifiers.axes`.
+ * The generator inspects axes during sampling; the validator inspects only
+ * `domain` (since distribution is a sampling hint, not a conformance constraint).
+ *
+ * Generation order: modifiers; derived; eventually; occasionally; bounded
+ * invariants around domain/distribution/kind sampling. Short-circuit values
+ * bypass invariants. Dataset identity is handled by the dataset policy.
+ */
+/** A generation context exposed to derived functions and invariants. */
+export type GenContext = {
+    /** Root value being built, accessible by JSON-pointer-like path. */
+    readonly root: unknown;
+    /** Sibling object for the current field (the immediate parent object's data). */
+    readonly parent: Readonly<Record<string, unknown>>;
+    /** Nearest enclosing array index. `undefined` when no array is in scope. */
+    readonly index?: number;
+    /** Caller-supplied context channel (free-form key/value, never sampled). */
+    readonly input?: Readonly<Record<string, unknown>>;
+    /** Stable seed string for this node (derived from path + identity). */
+    readonly seed: string;
+};
+/** A single-record predicate. Returns true if the value is acceptable. */
+export type InvariantFn = (value: unknown, ctx: GenContext) => boolean;
+/**
+ * A pure function computing a field's value from sibling/root data.
+ *
+ * The generic parameter is the produced value type. It defaults to
+ * `unknown` so call sites that do not annotate (most plugin code) keep
+ * working unchanged. Builders such as `relate(rows, field)` propagate
+ * the inferred field type through this parameter so that
+ * `int().derivedFrom(relate(stringRows, 'sku'))` becomes a TS error
+ * (`string` is not assignable to `number`).
+ */
+export type DerivedFn<T = unknown> = (ctx: GenContext) => T;
+/** A weighted distribution over discrete enum values. */
+export type WeightedDistribution = {
+    readonly kind: 'weighted';
+    /** Map of value → weight (relative; need not sum to 1). */
+    readonly weights: ReadonlyArray<readonly [string | number | boolean, number]>;
+};
+/** A normal (Gaussian) distribution for numbers. */
+export type NormalDistribution = {
+    readonly kind: 'normal';
+    readonly mean: number;
+    readonly stddev: number;
+};
+/** A typical-range distribution (uniform within [from, to], reachable subset of [min, max]). */
+export type TypicalDistribution = {
+    readonly kind: 'typical';
+    readonly from: number;
+    readonly to: number;
+};
+/**
+ * An "occasionally" override: with probability `p`, the produced value is
+ * forced to `value`. Stacks before the base distribution.
+ */
+export type OccasionalOverride = {
+    readonly value: unknown;
+    readonly p: number;
+};
+/**
+ * An "eventually" override: every `every` rows the produced value is
+ * forced to `value`, deterministically driven by `ctx.index`.
+ *
+ * Stacks before `occasionally`. Skipped when `ctx.index` is undefined.
+ */
+export type EventuallyOverride = {
+    readonly value: unknown;
+    readonly every: number;
+    readonly offset?: number;
+};
+export type Distribution = WeightedDistribution | NormalDistribution | TypicalDistribution;
+/** A closed candidate set the value must belong to (`D` in the formal model). */
+export type DomainConstraint = {
+    readonly kind: 'values';
+    readonly values: readonly unknown[];
+} | {
+    readonly kind: 'lookup';
+    readonly fromField: string;
+    readonly map: Readonly<Record<string, readonly unknown[]>>;
+};
+/** All axis metadata attached to a schema node. */
+export type Axes = {
+    readonly distribution?: Distribution;
+    readonly occasionally?: readonly OccasionalOverride[];
+    readonly eventually?: readonly EventuallyOverride[];
+    readonly derived?: DerivedFn;
+    readonly invariants?: readonly InvariantFn[];
+    readonly domain?: DomainConstraint;
+};
+/** Merge standard axes through their owning behavior descriptors. */
+export declare const mergeAxes: (a: Axes | undefined, b: Axes) => Axes;
+//# sourceMappingURL=axes.d.ts.map

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

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

package/dist/foundation/axes.js

@@ -0,0 +1,16 @@
+import { standardBehaviors } from '../standard/behaviors.js';
+/** Merge standard axes through their owning behavior descriptors. */
+export const mergeAxes = (a, b) => {
+    if (a === undefined)
+        return b;
+    let node = { kind: 'metadata', mods: { axes: a ?? {} } };
+    for (const [id, incoming] of Object.entries(b)) {
+        const descriptor = standardBehaviors.find((behavior) => behavior.id === id);
+        if (descriptor === undefined)
+            throw new TypeError(`missing schema behavior ${id}`);
+        const previous = descriptor.read(node);
+        node = descriptor.write(node, previous === undefined ? incoming : descriptor.merge(previous, incoming));
+    }
+    return node.mods?.axes ?? {};
+};
+//# sourceMappingURL=axes.js.map

package/dist/foundation/axes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"axes.js","sourceRoot":"","sources":["../../src/foundation/axes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAqG5D,qEAAqE;AACrE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAmB,EAAE,CAAO,EAAQ,EAAE;IAC9D,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAA;IAC7B,IAAI,IAAI,GAAiC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,CAAA;IACtF,KAAK,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,MAAM,UAAU,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;QAC3E,IAAI,UAAU,KAAK,SAAS;YAAE,MAAM,IAAI,SAAS,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAA;QAClF,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACtC,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAA;IACzG,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAA;AAC9B,CAAC,CAAA"}

package/dist/foundation/errors.d.ts

@@ -0,0 +1,101 @@
+/**
+ * databehave error hierarchy. All errors carry a JSON-pointer style `path` so that
+ * deeply nested failures can be reported precisely.
+ *
+ * ```
+ *               Error
+ *                 └── DataBehaveError (abstract)
+ *                       ├── ConformError       (runtime input did not conform)
+ *                       └── SchemaConflictError (schema is unsatisfiable / misused)
+ * ```
+ *
+ * Catch `DataBehaveError` to filter library-originated failures from generic
+ * `Error`s (e.g. callback bugs in `derivedFrom`/`invariant` are not wrapped).
+ */
+/**
+ * Stable, machine-matchable identifier for a conformance failure.
+ *
+ * The standard catalog is **snapshot-locked** by
+ * `test/foundation/issue-codes.test.ts`. Each value is a kebab-case,
+ * dot-segmented identifier (`'<bucket>.<reason>'` or a bare token
+ * for cross-cutting issues) and is part of the SemVer contract:
+ *
+ * Plugins may add namespaced string codes through their registered validators.
+ *
+ * - Adding a new standard code is `MINOR` (the snapshot test must be updated
+ *   in the same commit).
+ * - Renaming, removing, or changing the meaning of an existing code
+ *   is `MAJOR`.
+ *
+ * `Issue.message` is **not** part of the contract — wording may
+ * change in any release. See `docs/stability.md` ("Issue messages
+ * are diagnostic-only").
+ */
+export type IssueCode = 'array.expected' | 'array.length-mismatch' | 'array.too-long' | 'array.too-short' | 'boolean.expected' | 'decimal.expected' | 'decimal.not-numeric' | 'decimal.scale-exceeded' | 'derived.callback-threw' | 'derived.mismatch' | 'discriminated.expected-object' | 'discriminated.missing-tag' | 'discriminated.unknown-tag' | 'domain.lookup-mismatch' | 'domain.not-in-values' | 'enum.not-member' | 'invariant.callback-threw' | 'invariant.failed' | 'literal.not-equal' | 'null.expected' | 'number.expected' | 'number.not-integer' | 'number.too-large' | 'number.too-small' | 'object.expected' | 'required' | 'string.expected' | 'string.pattern-mismatch' | 'string.too-long' | 'string.too-short' | 'tuple.expected-array' | 'tuple.length-mismatch' | 'unexpected-null' | 'union.no-match' | (string & {});
+export type Issue = {
+    readonly path: readonly (string | number)[];
+    /**
+     * Stable, machine-matchable identifier. Use this — together with
+     * {@link Issue.path} — for programmatic assertions and runtime
+     * branching. See {@link IssueCode} for the standard catalog and extension contract.
+     */
+    readonly code: IssueCode;
+    /**
+     * Human-readable diagnostic. **Not** part of the SemVer contract:
+     * wording may change in any release. For machine matching, use
+     * {@link Issue.code} and {@link Issue.path}.
+     */
+    readonly message: string;
+    readonly expected?: string;
+    readonly received?: unknown;
+};
+/**
+ * Abstract root of all errors thrown by databehave itself.
+ *
+ * @remarks
+ *   Callbacks supplied by the user (e.g. `derivedFrom`, `invariant`) are
+ *   reported as {@link Issue}s rather than wrapped: the original `Error` is
+ *   surfaced in the issue's `message` and re-thrown only at the boundary.
+ */
+export declare abstract class DataBehaveError extends Error {
+    /** JSON-pointer style location where the error originated. */
+    abstract readonly path: readonly (string | number)[];
+    /** Optional recovery hint, surfaced in the message and as a property. */
+    abstract readonly hint?: string;
+}
+/**
+ * Thrown by {@link parse} when a value does not conform to a schema.
+ * Use {@link safeParse} to receive a result rather than an exception.
+ */
+export declare class ConformError extends DataBehaveError {
+    readonly issues: readonly Issue[];
+    /** Root-relative — issues carry their own per-field paths. */
+    readonly path: readonly (string | number)[];
+    readonly hint?: string;
+    constructor(issues: readonly Issue[]);
+}
+/**
+ * Thrown when an axis combination is unsatisfiable
+ * (e.g. invariants conflict with distribution, derived returns an
+ * out-of-domain value, or primitive bounds are impossible such as
+ * `int().min(10).max(5)`).
+ *
+ * Also thrown at schema-build time when a modifier does not apply to the
+ * schema kind (e.g. `obj({...}).weighted([...])`). See the capability
+ * matrix in `docs/stability.md`.
+ */
+export declare class SchemaConflictError extends DataBehaveError {
+    readonly path: readonly (string | number)[];
+    readonly hint?: string;
+    /**
+     * Optional, machine-matchable identifier for cross-cutting failures
+     * raised outside the conform pipeline (e.g. `'serialize.closure-axis'`
+     * thrown by `serializeSchema` when an axis carries a non-JSON
+     * function value). Free-form `'<bucket>.<reason>'` slugs; not part of
+     * the closed {@link IssueCode} catalog because they describe builder /
+     * codec misuse rather than runtime conformance.
+     */
+    readonly code?: string;
+    constructor(message: string, path?: readonly (string | number)[], hint?: string, code?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/foundation/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,SAAS,GACjB,gBAAgB,GAChB,uBAAuB,GACvB,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,GAClB,qBAAqB,GACrB,wBAAwB,GACxB,wBAAwB,GACxB,kBAAkB,GAClB,+BAA+B,GAC/B,2BAA2B,GAC3B,2BAA2B,GAC3B,wBAAwB,GACxB,sBAAsB,GACtB,iBAAiB,GACjB,0BAA0B,GAC1B,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,GACf,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,GACjB,UAAU,GACV,iBAAiB,GACjB,yBAAyB,GACzB,iBAAiB,GACjB,kBAAkB,GAClB,sBAAsB,GACtB,uBAAuB,GACvB,iBAAiB,GACjB,gBAAgB,GAChB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjB,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED;;;;;;;GAOG;AACH,8BAAsB,eAAgB,SAAQ,KAAK;IACjD,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IACpD,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAChC;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,eAAe;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAK;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;gBAEV,MAAM,EAAE,SAAS,KAAK,EAAE;CASrC;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;gBAGpB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAO,EACvC,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM;CAQhB"}

package/dist/foundation/errors.js

@@ -0,0 +1,91 @@
+/**
+ * databehave error hierarchy. All errors carry a JSON-pointer style `path` so that
+ * deeply nested failures can be reported precisely.
+ *
+ * ```
+ *               Error
+ *                 └── DataBehaveError (abstract)
+ *                       ├── ConformError       (runtime input did not conform)
+ *                       └── SchemaConflictError (schema is unsatisfiable / misused)
+ * ```
+ *
+ * Catch `DataBehaveError` to filter library-originated failures from generic
+ * `Error`s (e.g. callback bugs in `derivedFrom`/`invariant` are not wrapped).
+ */
+/**
+ * Abstract root of all errors thrown by databehave itself.
+ *
+ * @remarks
+ *   Callbacks supplied by the user (e.g. `derivedFrom`, `invariant`) are
+ *   reported as {@link Issue}s rather than wrapped: the original `Error` is
+ *   surfaced in the issue's `message` and re-thrown only at the boundary.
+ */
+export class DataBehaveError extends Error {
+}
+/**
+ * Thrown by {@link parse} when a value does not conform to a schema.
+ * Use {@link safeParse} to receive a result rather than an exception.
+ */
+export class ConformError extends DataBehaveError {
+    issues;
+    /** Root-relative — issues carry their own per-field paths. */
+    path = [];
+    hint;
+    constructor(issues) {
+        const summary = issues.length === 1
+            ? formatIssue(issues[0])
+            : `${issues.length} issues:\n${issues.map((i) => '  - ' + formatIssue(i)).join('\n')}`;
+        super(summary);
+        this.name = 'ConformError';
+        this.issues = issues;
+    }
+}
+/**
+ * Thrown when an axis combination is unsatisfiable
+ * (e.g. invariants conflict with distribution, derived returns an
+ * out-of-domain value, or primitive bounds are impossible such as
+ * `int().min(10).max(5)`).
+ *
+ * Also thrown at schema-build time when a modifier does not apply to the
+ * schema kind (e.g. `obj({...}).weighted([...])`). See the capability
+ * matrix in `docs/stability.md`.
+ */
+export class SchemaConflictError extends DataBehaveError {
+    path;
+    hint;
+    /**
+     * Optional, machine-matchable identifier for cross-cutting failures
+     * raised outside the conform pipeline (e.g. `'serialize.closure-axis'`
+     * thrown by `serializeSchema` when an axis carries a non-JSON
+     * function value). Free-form `'<bucket>.<reason>'` slugs; not part of
+     * the closed {@link IssueCode} catalog because they describe builder /
+     * codec misuse rather than runtime conformance.
+     */
+    code;
+    constructor(message, path = [], hint, code) {
+        super(hint ? `${message} (hint: ${hint})` : message);
+        this.name = 'SchemaConflictError';
+        this.path = path;
+        if (hint !== undefined)
+            this.hint = hint;
+        if (code !== undefined)
+            this.code = code;
+    }
+}
+const formatIssue = (i) => {
+    const p = i.path.length === 0 ? '(root)' : i.path.map((s) => String(s)).join('.');
+    const expected = i.expected !== undefined ? ` expected=${i.expected}` : '';
+    const received = 'received' in i
+        ? ` received=${safeStringify(i.received)}`
+        : '';
+    return `${p}: ${i.message}${expected}${received}`;
+};
+const safeStringify = (v) => {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+};
+//# sourceMappingURL=errors.js.map