@databehave/schema 0.1.3 → 0.2.0

package/dist/generator/engine.d.ts

@@ -0,0 +1,69 @@
+import type { GenContext } from '../foundation/axes.js';
+import type { Rng } from '../foundation/prng.js';
+import type { Schema, Infer } from '../foundation/types.js';
+import type { TraceCollector } from './trace.js';
+/**
+ * Per-leaf stable-seed hook.
+ *
+ * Called for every leaf-value sampling (string/number/decimal/boolean/enum/domain).
+ * Return a non-empty string to deterministically reseed *just this leaf*
+ * (path-scoped) — useful for snapshot/CI runs where a subset of rows must
+ * stay identical regardless of the outer `seed`.
+ * Return `null`/`undefined`/`''` to fall back to the shared rng (normal random).
+ *
+ * Composite kinds (object/array/tuple/union) are unaffected; their children
+ * re-enter this hook with their own path.
+ */
+export type StableByFn = (ctx: GenContext) => string | null | undefined;
+/**
+ * Per-modifier probabilities for random injection during generation.
+ *
+ * These are opt-in. With the default `{ default: 0, optional: 0, nullable: 0 }`
+ * `mock()` always samples a real value for the underlying type and never
+ * silently substitutes the modifier short-circuit. Set a non-zero probability
+ * to exercise the `undefined` / `null` / default-value paths.
+ */
+export type ModifierProbs = {
+    /** Probability that `.default(v)` returns `v` instead of sampling. */
+    readonly default?: number;
+    /** Probability that `.optional()` returns `undefined`. */
+    readonly optional?: number;
+    /** Probability that `.nullable()` returns `null`. */
+    readonly nullable?: number;
+};
+export type MockOptions = {
+    /** Override the deterministic seed. Either a string or unsigned 32-bit int. */
+    readonly seed?: string | number;
+    /** Caller-supplied context channel exposed to derived/invariants as `ctx.input`. */
+    readonly input?: Readonly<Record<string, unknown>>;
+    /** Top-level row index (used by `mockDataset` so per-row derived can read `ctx.index`). */
+    readonly index?: number;
+    /** Optional trace collector — receives one entry per resolved field. */
+    readonly trace?: TraceCollector;
+    /** Reseed leaf sampling deterministically from a caller-chosen key. */
+    readonly stableBy?: StableByFn;
+    /**
+     * Probabilities used for modifier short-circuits during sampling.
+     *
+     * Defaults are **all zero** — modifiers do not inject randomness unless you
+     * explicitly opt in. This makes `mock()` exercise the underlying type by
+     * default (e.g. `mock(str().optional())` always returns a string).
+     */
+    readonly modifierProbs?: ModifierProbs;
+    /**
+     * Override the PRNG factory used when `seed` is a number.
+     *
+     * Defaults to `mulberry32`. When `seed` is a string the seed is
+     * first hashed (`seedFromString`) and then handed to this factory.
+     *
+     * Useful for tests that need to inject a constant or recorded RNG to
+     * exercise probability-driven branches deterministically. Production
+     * callers should leave this unset — `mulberry32` is the seeded default
+     * the determinism contract is calibrated against, and swapping it
+     * perturbs the output sequence.
+     */
+    readonly prng?: (seed: number) => Rng;
+};
+/** Generate using the explicit standard preset. Custom schemas use their composed runtime. */
+export declare const mock: <S extends Schema>(schema: S, options?: MockOptions) => Infer<S>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/generator/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/generator/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAA;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;AAEvE;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAClD,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAA;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAA;IACtC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,CAAA;CACtC,CAAA;AAED,8FAA8F;AAC9F,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAS,WAAgB,KAAG,KAAK,CAAC,CAAC,CAA0C,CAAA"}

package/dist/generator/engine.js

@@ -0,0 +1,4 @@
+import { standardRuntime } from '../standard/runtime.js';
+/** Generate using the explicit standard preset. Custom schemas use their composed runtime. */
+export const mock = (schema, options = {}) => standardRuntime.mock(schema, options);
+//# sourceMappingURL=engine.js.map

package/dist/generator/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/generator/engine.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAmExD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,IAAI,GAAG,CAAmB,MAAS,EAAE,UAAuB,EAAE,EAAY,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA"}

package/dist/generator/replay.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Replay / snapshot helpers — thin layer over `mock()` for tests.
+ *
+ * `replay(schema, opts)` returns a function bound to a fixed (seed, input)
+ * pair. Calling it twice always returns deep-equal values; the function is
+ * the canonical way to assert determinism in test suites.
+ *
+ * `expectStable(schema, opts)` runs the generator twice and throws if the
+ * outputs differ — surfaces non-determinism introduced by misuse of
+ * `derivedFrom` (e.g. reading `Date.now()`).
+ */
+import type { RuntimeReplay } from '../runtime/runtime.js';
+import { type MockOptions } from './engine.js';
+import type { Infer, Schema } from '../foundation/types.js';
+/** A reusable standard-runtime generator with frozen options and contract identities. */
+export type Replay<S extends Schema> = RuntimeReplay<S>;
+/** Bind the standard composition; custom schemas use runtime.replay. */
+export declare const replay: <S extends Schema>(schema: S, options?: MockOptions) => Replay<S>;
+/**
+ * Run the generator twice with identical inputs and assert deep equality.
+ * Returns the produced value on success; throws on divergence.
+ *
+ * **This is a diagnostic, not a determinism guarantee.** It runs the
+ * schema *twice* with the same seed and compares the outputs
+ * structurally — useful for catching obvious non-determinism (a
+ * `derivedFrom` reading `Date.now()`, a stray `Math.random()`,
+ * iteration over a `Set`), but two iterations cannot prove the entire
+ * RNG sequence is fixed. The strong contract is {@link replay}, which
+ * binds a (seed, input) pair and lets the caller pin the value at the
+ * snapshot site.
+ *
+ * Treat `expectStable` as the equivalent of a smoke test: cheap to
+ * keep in a regression suite, fast to fail loudly when a callback
+ * goes off-piste, but not a substitute for `replay`-backed snapshots
+ * for surfaces that must round-trip across releases.
+ */
+export declare const expectStable: <S extends Schema>(schema: S, options?: MockOptions) => Infer<S>;
+//# sourceMappingURL=replay.d.ts.map

package/dist/generator/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/generator/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAE3D,yFAAyF;AACzF,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,MAAM,IAAI,aAAa,CAAC,CAAC,CAAC,CAAA;AAEvD,wEAAwE;AACxE,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAS,WAAgB,KAAG,MAAM,CAAC,CAAC,CAA4C,CAAA;AAEpI;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAS,WAAgB,KAAG,KAAK,CAAC,CAAC,CAU5F,CAAA"}

package/dist/generator/replay.js

@@ -0,0 +1,44 @@
+/**
+ * Replay / snapshot helpers — thin layer over `mock()` for tests.
+ *
+ * `replay(schema, opts)` returns a function bound to a fixed (seed, input)
+ * pair. Calling it twice always returns deep-equal values; the function is
+ * the canonical way to assert determinism in test suites.
+ *
+ * `expectStable(schema, opts)` runs the generator twice and throws if the
+ * outputs differ — surfaces non-determinism introduced by misuse of
+ * `derivedFrom` (e.g. reading `Date.now()`).
+ */
+import { isDeepStrictEqual } from 'node:util';
+import { standardRuntime } from '../standard/runtime.js';
+import { mock } from './engine.js';
+/** Bind the standard composition; custom schemas use runtime.replay. */
+export const replay = (schema, options = {}) => standardRuntime.replay(schema, options);
+/**
+ * Run the generator twice with identical inputs and assert deep equality.
+ * Returns the produced value on success; throws on divergence.
+ *
+ * **This is a diagnostic, not a determinism guarantee.** It runs the
+ * schema *twice* with the same seed and compares the outputs
+ * structurally — useful for catching obvious non-determinism (a
+ * `derivedFrom` reading `Date.now()`, a stray `Math.random()`,
+ * iteration over a `Set`), but two iterations cannot prove the entire
+ * RNG sequence is fixed. The strong contract is {@link replay}, which
+ * binds a (seed, input) pair and lets the caller pin the value at the
+ * snapshot site.
+ *
+ * Treat `expectStable` as the equivalent of a smoke test: cheap to
+ * keep in a regression suite, fast to fail loudly when a callback
+ * goes off-piste, but not a substitute for `replay`-backed snapshots
+ * for surfaces that must round-trip across releases.
+ */
+export const expectStable = (schema, options = {}) => {
+    const a = mock(schema, options);
+    const b = mock(schema, options);
+    if (!isDeepStrictEqual(a, b)) {
+        throw new Error('expectStable: generator produced different values for identical seed/input — ' +
+            'likely a non-deterministic derivedFrom callback (e.g. Date.now, Math.random, network).');
+    }
+    return a;
+};
+//# sourceMappingURL=replay.js.map

package/dist/generator/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/generator/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAE7C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EAAE,IAAI,EAAoB,MAAM,aAAa,CAAA;AAMpD,wEAAwE;AACxE,MAAM,CAAC,MAAM,MAAM,GAAG,CAAmB,MAAS,EAAE,UAAuB,EAAE,EAAa,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEpI;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAmB,MAAS,EAAE,UAAuB,EAAE,EAAY,EAAE;IAC/F,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,IAAI,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,+EAA+E;YAC7E,wFAAwF,CAC3F,CAAA;IACH,CAAC;IACD,OAAO,CAAC,CAAA;AACV,CAAC,CAAA"}

package/dist/generator/trace.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Trace collector — records which axis fired at each path during a
+ * single `mock()` call.
+ *
+ * The trace is a read-only audit of the generator's decisions: every
+ * produced value is annotated with the axis that won.
+ *
+ * Usage:
+ *
+ *   const trace = createTrace()
+ *   const value = mock(schema, { seed: 's', trace })
+ *   console.log(trace.entries)  // → TraceEntry[]
+ */
+/**
+ * Which axis decided a value at a given path.
+ *
+ *   - `default`        : pure value (`undefined` slot in optional/default)
+ *   - `optional-skip`  : optional field rolled `undefined`
+ *   - `nullable-null`  : nullable field rolled `null`
+ *   - `derived`        : produced by `derivedFrom(...)`
+ *   - `occasionally`   : forced by an `occasionally(...)` override
+ *   - `eventually`     : forced by an `eventually(...)` override (modulo `index`)
+ *   - `invariant-pass` : sampled then accepted by all `invariant(...)`
+ *   - `invariant-fail` : retry exhausted before invariants held
+ *   - `domain`         : sampled from `in([...])` candidate set
+ *   - `distribution`   : sampled via `weighted|normal|typically`
+ *   - `type`           : fell through to type-default sampling
+ */
+export type TraceAxis = 'default' | 'optional-skip' | 'nullable-null' | 'derived' | 'occasionally' | 'eventually' | 'invariant-pass' | 'invariant-fail' | 'domain' | 'distribution' | 'type';
+export type TraceEntry = {
+    readonly path: readonly (string | number)[];
+    readonly axis: TraceAxis;
+    /** Attempts taken before invariants accepted (only meaningful when invariants run). */
+    readonly attempts?: number;
+    /** Free-form annotation (e.g. distribution kind, picked literal). */
+    readonly note?: string;
+    /** Contracts involved in this node, captured by the selected runtime. */
+    readonly contracts?: {
+        readonly kind: import('../runtime/runtime.js').SchemaContract;
+        readonly behaviors: readonly import('../runtime/runtime.js').SchemaContract[];
+    };
+};
+export type TraceCollector = {
+    /** Append a single entry. Called by the engine — do not call from user code. */
+    readonly emit: (entry: TraceEntry) => void;
+    /** Read-only view of entries collected so far. */
+    readonly entries: readonly TraceEntry[];
+    /** All paths where a specific axis fired. */
+    readonly axisFiredAt: (axis: TraceAxis) => readonly (readonly (string | number)[])[];
+    /** Pretty multi-line dump (one entry per line, JSON-pointer-style paths). */
+    readonly format: () => string;
+};
+export declare const createTrace: () => TraceCollector;
+//# sourceMappingURL=trace.d.ts.map

package/dist/generator/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/generator/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,eAAe,GACf,eAAe,GACf,SAAS,GACT,cAAc,GACd,YAAY,GACZ,gBAAgB,GAChB,gBAAgB,GAChB,QAAQ,GACR,cAAc,GACd,MAAM,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IAC3C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,uBAAuB,EAAE,cAAc,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,OAAO,uBAAuB,EAAE,cAAc,EAAE,CAAA;KAAE,CAAA;CACtK,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IAC1C,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IACvC,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;IACpF,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAA;CAC9B,CAAA;AAED,eAAO,MAAM,WAAW,QAAO,cAuB9B,CAAA"}

package/dist/generator/trace.js

@@ -0,0 +1,38 @@
+/**
+ * Trace collector — records which axis fired at each path during a
+ * single `mock()` call.
+ *
+ * The trace is a read-only audit of the generator's decisions: every
+ * produced value is annotated with the axis that won.
+ *
+ * Usage:
+ *
+ *   const trace = createTrace()
+ *   const value = mock(schema, { seed: 's', trace })
+ *   console.log(trace.entries)  // → TraceEntry[]
+ */
+export const createTrace = () => {
+    const entries = [];
+    return {
+        emit(entry) {
+            entries.push(entry);
+        },
+        get entries() {
+            return entries;
+        },
+        axisFiredAt(axis) {
+            return entries.filter((e) => e.axis === axis).map((e) => e.path);
+        },
+        format() {
+            return entries
+                .map((e) => {
+                const ptr = '/' + e.path.map((p) => String(p)).join('/');
+                const attempts = e.attempts !== undefined ? ` attempts=${e.attempts}` : '';
+                const note = e.note !== undefined ? ` (${e.note})` : '';
+                return `${ptr.padEnd(40)} ${e.axis}${attempts}${note}`;
+            })
+                .join('\n');
+        },
+    };
+};
+//# sourceMappingURL=trace.js.map

package/dist/generator/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/generator/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoDH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAmB,EAAE;IAC9C,MAAM,OAAO,GAAiB,EAAE,CAAA;IAChC,OAAO;QACL,IAAI,CAAC,KAAK;YACR,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACrB,CAAC;QACD,IAAI,OAAO;YACT,OAAO,OAAO,CAAA;QAChB,CAAC;QACD,WAAW,CAAC,IAAI;YACd,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAClE,CAAC;QACD,MAAM;YACJ,OAAO,OAAO;iBACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACT,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;gBACxD,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;gBAC1E,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;gBACvD,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,QAAQ,GAAG,IAAI,EAAE,CAAA;YACxD,CAAC,CAAC;iBACD,IAAI,CAAC,IAAI,CAAC,CAAA;QACf,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * databehave — Zero-dependency data schema DSL.
+ *
+ * Public surface:
+ *   - schema DSL (primitives, composites, decimal, conditional)
+ *   - data-schema axes (distribution, derived, invariants, domain,
+ *     discriminated unions, dataset with identity, eventually, correlate)
+ *   - generator (`mock`) + validator (`parse`/`safeParse`)
+ *   - debug / determinism (`createTrace`, `replay`, `expectStable`)
+ *   - cross-dataset FK (`relate`)
+ *   - extensibility (`walkSchema`, `fromIR`, low-level PRNG, IR types) for
+ *     third-party packages (CLI, OpenAPI ingestion, zod adapters, …)
+ *
+ * databehave intentionally ships NO HTTP/server/framework integration. Wire it
+ * into your transport of choice (Fastify/Express/msw/node:http) in ~80 LOC.
+ */
+export { str, num, int, bool, null_, StringSchema, NumberSchema, IntSchema, BooleanSchema, NullSchema, } from './schema/primitives.js';
+export { decimal, DecimalSchema } from './schema/decimal.js';
+export { obj, arr, tuple, union, literal, enum_, ObjectSchema, ArraySchema, TupleSchema, UnionSchema, LiteralSchema, EnumSchema, } from './schema/composites.js';
+export { discriminated } from './schema/conditional.js';
+export { mock, type MockOptions, type ModifierProbs, type StableByFn } from './generator/engine.js';
+export type { Rng } from './foundation/prng.js';
+export { parse, safeParse, type SafeParseResult } from './validator/parse.js';
+export { createTrace, type TraceAxis, type TraceCollector, type TraceEntry, } from './generator/trace.js';
+export { replay, expectStable, type Replay } from './generator/replay.js';
+export { mockDataset, identityFor, type DatasetOptions } from './dataset/dataset.js';
+export { relate, type RelateOptions } from './dataset/relate.js';
+export { Schema, type Infer, type Modifiers, type SchemaNode } from './foundation/types.js';
+export type { Axes, DerivedFn, Distribution, DomainConstraint, EventuallyOverride, GenContext, InvariantFn, NormalDistribution, OccasionalOverride, TypicalDistribution, WeightedDistribution, } from './foundation/axes.js';
+export { DataBehaveError, ConformError, SchemaConflictError, type Issue, type IssueCode, } from './foundation/errors.js';
+export { createSchemaRuntime, IR_VERSION, type SchemaRuntime, type SchemaRuntimeOptions, type SchemaContract, type SchemaEnvelope, type SchemaVisitor, type WalkPath, type RuntimeReplay } from './runtime/runtime.js';
+export { defineKind, defineBehavior, type KindDescriptor, type KindDefinition, type TypedKind, type BehaviorDescriptor, type BehaviorDefinition, type TypedBehavior, type BehaviorPhase, type SchemaChild, type GenerationContext, type GenerationNext, type SamplingContext, type ValidationContext } from './runtime/contracts.js';
+export { standardKinds } from './standard/kinds.js';
+export { standardBehaviors } from './standard/behaviors.js';
+export { standardRuntime } from './standard/runtime.js';
+export type { StandardSchemaNode } from './foundation/ir.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACL,GAAG,EACH,GAAG,EACH,GAAG,EACH,IAAI,EACJ,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,aAAa,EACb,UAAU,GACX,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,EACL,GAAG,EACH,GAAG,EACH,KAAK,EACL,KAAK,EACL,OAAO,EACP,KAAK,EACL,YAAY,EACZ,WAAW,EACX,WAAW,EACX,WAAW,EACX,aAAa,EACb,UAAU,GACX,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAGvD,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACnG,YAAY,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,EACL,WAAW,EACX,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,GAChB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAGzE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGhE,OAAO,EAAE,MAAM,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAC3F,YAAY,EACV,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EACL,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,KAAK,KAAK,EACV,KAAK,SAAS,GACf,MAAM,wBAAwB,CAAA;AAG/B,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACtN,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AACpU,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -0,0 +1,40 @@
+/**
+ * databehave — Zero-dependency data schema DSL.
+ *
+ * Public surface:
+ *   - schema DSL (primitives, composites, decimal, conditional)
+ *   - data-schema axes (distribution, derived, invariants, domain,
+ *     discriminated unions, dataset with identity, eventually, correlate)
+ *   - generator (`mock`) + validator (`parse`/`safeParse`)
+ *   - debug / determinism (`createTrace`, `replay`, `expectStable`)
+ *   - cross-dataset FK (`relate`)
+ *   - extensibility (`walkSchema`, `fromIR`, low-level PRNG, IR types) for
+ *     third-party packages (CLI, OpenAPI ingestion, zod adapters, …)
+ *
+ * databehave intentionally ships NO HTTP/server/framework integration. Wire it
+ * into your transport of choice (Fastify/Express/msw/node:http) in ~80 LOC.
+ */
+// ── schema DSL ────────────────────────────────────────────────────────────
+export { str, num, int, bool, null_, StringSchema, NumberSchema, IntSchema, BooleanSchema, NullSchema, } from './schema/primitives.js';
+export { decimal, DecimalSchema } from './schema/decimal.js';
+export { obj, arr, tuple, union, literal, enum_, ObjectSchema, ArraySchema, TupleSchema, UnionSchema, LiteralSchema, EnumSchema, } from './schema/composites.js';
+export { discriminated } from './schema/conditional.js';
+// ── generator + validator ─────────────────────────────────────────────────
+export { mock } from './generator/engine.js';
+export { parse, safeParse } from './validator/parse.js';
+export { createTrace, } from './generator/trace.js';
+export { replay, expectStable } from './generator/replay.js';
+// ── dataset ───────────────────────────────────────────────────────────────
+export { mockDataset, identityFor } from './dataset/dataset.js';
+export { relate } from './dataset/relate.js';
+// ── foundation types & axes ───────────────────────────────────────────────
+export { Schema } from './foundation/types.js';
+// ── errors ────────────────────────────────────────────────────────────────
+export { DataBehaveError, ConformError, SchemaConflictError, } from './foundation/errors.js';
+// Instance-local schema composition and extension contracts.
+export { createSchemaRuntime, IR_VERSION } from './runtime/runtime.js';
+export { defineKind, defineBehavior } from './runtime/contracts.js';
+export { standardKinds } from './standard/kinds.js';
+export { standardBehaviors } from './standard/behaviors.js';
+export { standardRuntime } from './standard/runtime.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,6EAA6E;AAC7E,OAAO,EACL,GAAG,EACH,GAAG,EACH,GAAG,EACH,IAAI,EACJ,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,aAAa,EACb,UAAU,GACX,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,EACL,GAAG,EACH,GAAG,EACH,KAAK,EACL,KAAK,EACL,OAAO,EACP,KAAK,EACL,YAAY,EACZ,WAAW,EACX,WAAW,EACX,WAAW,EACX,aAAa,EACb,UAAU,GACX,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAEvD,6EAA6E;AAC7E,OAAO,EAAE,IAAI,EAAyD,MAAM,uBAAuB,CAAA;AAEnG,OAAO,EAAE,KAAK,EAAE,SAAS,EAAwB,MAAM,sBAAsB,CAAA;AAC7E,OAAO,EACL,WAAW,GAIZ,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAe,MAAM,uBAAuB,CAAA;AAEzE,6EAA6E;AAC7E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAuB,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAE,MAAM,EAAsB,MAAM,qBAAqB,CAAA;AAEhE,6EAA6E;AAC7E,OAAO,EAAE,MAAM,EAA+C,MAAM,uBAAuB,CAAA;AAe3F,6EAA6E;AAC7E,OAAO,EACL,eAAe,EACf,YAAY,EACZ,mBAAmB,GAGpB,MAAM,wBAAwB,CAAA;AAE/B,6DAA6D;AAC7D,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAkJ,MAAM,sBAAsB,CAAA;AACtN,OAAO,EAAE,UAAU,EAAE,cAAc,EAAmQ,MAAM,wBAAwB,CAAA;AACpU,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/internal.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @databehave/schema/internal — low-level extensibility surface.
+ *
+ * Re-exports the IR walker, the IR discriminants, the axis types, and
+ * seeded PRNG primitives that exist for third-party packages (CLI tools,
+ * OpenAPI ingestion, zod adapters, …) to build on. These are versioned
+ * more loosely than the main DSL:
+ *
+ *   • SchemaNode / IR shape changes are MAJOR (see docs/stability.md).
+ *   • PRNG output is deterministic across PATCH/MINOR for a given seed.
+ *
+ * **Do not import from `@databehave/schema/internal` in application code.**
+ * Prefer the high-level `mock()` / `parse()` / `safeParse()` from the package
+ * root. Importing internals couples you to the IR and bypasses fail-loud guards.
+ */
+export { walkSchema, fromIR, serializeSchema, deserializeSchema, IR_VERSION, type SchemaEnvelope, type SchemaVisitor, type WalkPath, } from './foundation/walk.js';
+export { mulberry32, rngFromString, seedFromString, type Rng, } from './foundation/prng.js';
+export { Schema } from './foundation/types.js';
+export type { Infer } from './foundation/types.js';
+export type { ArrayKind, BooleanKind, DecimalKind, DiscriminatedKind, EnumKind, LiteralKind, Modifiers, NullKind, NumberKind, ObjectKind, SchemaCore, SchemaNode, StandardSchemaNode, StringFormat, StringKind, TupleKind, UnionKind, } from './foundation/ir.js';
+export type { Axes, DerivedFn, Distribution, DomainConstraint, EventuallyOverride, GenContext, InvariantFn, NormalDistribution, OccasionalOverride, TypicalDistribution, WeightedDistribution, } from './foundation/axes.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,UAAU,EACV,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,QAAQ,GACd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,UAAU,EACV,aAAa,EACb,cAAc,EACd,KAAK,GAAG,GACT,MAAM,sBAAsB,CAAA;AAS7B,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAC9C,YAAY,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAElD,YAAY,EAEV,SAAS,EACT,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,SAAS,EACT,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,SAAS,GACV,MAAM,oBAAoB,CAAA;AAE3B,YAAY,EAEV,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAA"}

package/dist/internal.js

@@ -0,0 +1,25 @@
+/**
+ * @databehave/schema/internal — low-level extensibility surface.
+ *
+ * Re-exports the IR walker, the IR discriminants, the axis types, and
+ * seeded PRNG primitives that exist for third-party packages (CLI tools,
+ * OpenAPI ingestion, zod adapters, …) to build on. These are versioned
+ * more loosely than the main DSL:
+ *
+ *   • SchemaNode / IR shape changes are MAJOR (see docs/stability.md).
+ *   • PRNG output is deterministic across PATCH/MINOR for a given seed.
+ *
+ * **Do not import from `@databehave/schema/internal` in application code.**
+ * Prefer the high-level `mock()` / `parse()` / `safeParse()` from the package
+ * root. Importing internals couples you to the IR and bypasses fail-loud guards.
+ */
+export { walkSchema, fromIR, serializeSchema, deserializeSchema, IR_VERSION, } from './foundation/walk.js';
+export { mulberry32, rngFromString, seedFromString, } from './foundation/prng.js';
+// ── extension-author types ─────────────────────────────────────────
+//
+// Surfaced so extension code (codegen, IR transforms, OpenAPI adapters)
+// can name the IR discriminants and the `_applyAxes` argument shape
+// without reaching into deep paths. Type-only re-exports — they emit
+// no runtime JS.
+export { Schema } from './foundation/types.js';
+//# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,UAAU,EACV,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,UAAU,GAIX,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,UAAU,EACV,aAAa,EACb,cAAc,GAEf,MAAM,sBAAsB,CAAA;AAE7B,sEAAsE;AACtE,EAAE;AACF,wEAAwE;AACxE,oEAAoE;AACpE,qEAAqE;AACrE,iBAAiB;AAEjB,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/plugin.d.ts

@@ -0,0 +1,7 @@
+import { type Capability, type Plugin } from '@databehave/core';
+import { type SchemaRuntime, type SchemaRuntimeOptions } from './runtime/runtime.js';
+/** Optional application capability; standalone schema imports never load the host. */
+export declare const schemaCapability: Capability<SchemaRuntime>;
+/** Compose a new synchronous schema registry during each host's setup phase. */
+export declare const schemaPlugin: (options: SchemaRuntimeOptions) => Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAuB,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAEzG,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,EAAE,UAAU,CAAC,aAAa,CAGtD,CAAA;AAED,gFAAgF;AAChF,eAAO,MAAM,YAAY,GAAI,SAAS,oBAAoB,KAAG,MAO3D,CAAA"}

package/dist/plugin.js

@@ -0,0 +1,14 @@
+import { capability } from '@databehave/core';
+import { createSchemaRuntime } from './runtime/runtime.js';
+/** Optional application capability; standalone schema imports never load the host. */
+export const schemaCapability = capability('databehave.schema.runtime', 1);
+/** Compose a new synchronous schema registry during each host's setup phase. */
+export const schemaPlugin = (options) => ({
+    id: 'databehave.schema',
+    apiVersion: 1,
+    provides: [schemaCapability],
+    setup(context) {
+        context.provide(schemaCapability, createSchemaRuntime(options));
+    },
+});
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAgC,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAE,mBAAmB,EAAiD,MAAM,sBAAsB,CAAA;AAEzG,sFAAsF;AACtF,MAAM,CAAC,MAAM,gBAAgB,GAA8B,UAAU,CACnE,2BAA2B,EAC3B,CAAC,CACF,CAAA;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAA6B,EAAU,EAAE,CAAC,CAAC;IACtE,EAAE,EAAE,mBAAmB;IACvB,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC,gBAAgB,CAAC;IAC5B,KAAK,CAAC,OAAO;QACX,OAAO,CAAC,OAAO,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAA;IACjE,CAAC;CACF,CAAC,CAAA"}

package/dist/runtime/contracts.d.ts

@@ -0,0 +1,101 @@
+import type { GenContext } from '../foundation/axes.js';
+import type { Issue } from '../foundation/errors.js';
+import type { SchemaNode } from '../foundation/ir.js';
+import type { Rng } from '../foundation/prng.js';
+import { Schema } from '../foundation/types.js';
+import type { ModifierProbs } from '../generator/engine.js';
+import type { TraceEntry } from '../generator/trace.js';
+/** A structural child and its traversal path segment. */
+export interface SchemaChild {
+    readonly key: string | number;
+    readonly node: SchemaNode;
+}
+/** Candidate sampling scoped to one downstream generation continuation. */
+export interface SamplingContext {
+    readonly candidates: readonly unknown[];
+    readonly fallback: () => unknown;
+}
+/** Continue with the current sampling scope, or override it for this call only. */
+export type GenerationNext = (sampling?: SamplingContext) => unknown;
+/** Services scoped to one generation call; recursion retains its runtime. */
+export interface GenerationContext extends GenContext {
+    readonly sampling?: SamplingContext;
+    readonly path: readonly (string | number)[];
+    readonly rng: Rng;
+    readonly leafRng: () => Rng;
+    readonly modifierProbs: Required<ModifierProbs>;
+    readonly isDeferred: (node: SchemaNode) => boolean;
+    readonly generate: (node: SchemaNode, path: readonly (string | number)[], parent: Readonly<Record<string, unknown>>) => unknown;
+    readonly emit: (entry: TraceEntry) => void;
+}
+/** Validation services scoped to a node; plugins report issues or recurse. */
+export interface ValidationContext extends GenContext {
+    readonly path: readonly (string | number)[];
+    readonly issues: Issue[];
+    readonly describe: (node: SchemaNode) => string;
+    readonly isDeferred: (node: SchemaNode) => boolean;
+    readonly check: (node: SchemaNode, value: unknown, path: readonly (string | number)[], issues: Issue[], root: unknown, parent: Readonly<Record<string, unknown>> | undefined) => unknown;
+}
+/** A kind owns its complete structural and value contract. */
+export interface KindDescriptor {
+    readonly id: string;
+    readonly version: number;
+    readonly describe?: (node: SchemaNode, describeChild: (node: SchemaNode) => string) => string;
+    readonly checkMetadata: (node: unknown) => SchemaNode;
+    readonly generate: (node: SchemaNode, context: GenerationContext) => unknown;
+    readonly validate: (node: SchemaNode, value: unknown, context: ValidationContext) => unknown;
+    readonly children: (node: SchemaNode) => readonly SchemaChild[];
+    readonly rebuild: (node: SchemaNode, children: readonly SchemaChild[]) => SchemaNode;
+}
+/** Fixed phase barriers; composition order determines order within each phase. */
+export type BehaviorPhase = 'modifier' | 'derived' | 'cadence' | 'invariant' | 'sample';
+/** Behavior policy uses middleware so short circuits and bounded retries are explicit. */
+export interface BehaviorDescriptor {
+    readonly id: string;
+    readonly version: number;
+    readonly phase: BehaviorPhase;
+    readonly read: (node: SchemaNode) => unknown;
+    readonly write: (node: SchemaNode, metadata: unknown) => SchemaNode;
+    readonly checkMetadata: (metadata: unknown) => unknown;
+    readonly appliesTo: (node: SchemaNode, metadata: unknown) => boolean;
+    readonly merge: (previous: unknown, next: unknown) => unknown;
+    readonly generate: (metadata: unknown, node: SchemaNode, context: GenerationContext, next: GenerationNext) => unknown;
+    readonly validate: (metadata: unknown, node: SchemaNode, value: unknown, context: ValidationContext, next: () => unknown) => unknown;
+    readonly serialize: (metadata: unknown) => unknown;
+}
+/** Typed public kind authoring; the parser validates every untrusted node. */
+export interface KindDefinition<T, N extends SchemaNode> {
+    readonly id: N['kind'];
+    readonly version: number;
+    readonly describe?: (node: N, describeChild: (node: SchemaNode) => string) => string;
+    readonly checkMetadata: (node: unknown) => N;
+    readonly generate: (node: N, context: GenerationContext) => T;
+    readonly validate: (node: N, value: unknown, context: ValidationContext) => unknown;
+    readonly children: (node: N) => readonly SchemaChild[];
+    readonly rebuild: (node: N, children: readonly SchemaChild[]) => N;
+}
+/** Kind descriptor with a type-safe builder; no builder subclass is required. */
+export interface TypedKind<T, N extends SchemaNode> extends KindDescriptor {
+    readonly schema: (metadata: Omit<N, 'kind'>) => Schema<T>;
+}
+/** Erase only the validated metadata type at the registry boundary. */
+export declare const defineKind: <T, N extends SchemaNode>(definition: KindDefinition<T, N>) => TypedKind<T, N>;
+/** Typed behavior authoring with the common instance-independent metadata carrier. */
+export interface BehaviorDefinition<M> {
+    readonly id: string;
+    readonly version: number;
+    readonly phase: BehaviorPhase;
+    readonly checkMetadata: (metadata: unknown) => M;
+    readonly appliesTo: (node: SchemaNode, metadata: M) => boolean;
+    readonly merge: (previous: M, next: M) => M;
+    readonly generate: (metadata: M, node: SchemaNode, context: GenerationContext, next: GenerationNext) => unknown;
+    readonly validate: (metadata: M, node: SchemaNode, value: unknown, context: ValidationContext, next: () => unknown) => unknown;
+    readonly serialize: (metadata: M) => unknown;
+}
+/** Behavior descriptor with a typed metadata attachment helper. */
+export interface TypedBehavior<M> extends BehaviorDescriptor {
+    readonly apply: <T>(schema: Schema<T>, metadata: M) => Schema<T>;
+}
+/** Adapt typed metadata to the public behavior contract. */
+export declare const defineBehavior: <M>(definition: BehaviorDefinition<M>) => TypedBehavior<M>;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/runtime/contracts.d.ts.map

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