smokin 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to `smokin` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-25
+
+Initial public release.
+
+### Added
+
+- Schema DSL: `str`, `num`, `int`, `bool`, `null_`, `decimal(precision, scale)`,
+  `obj`, `arr`, `tuple`, `union`, `literal`, `enum_`, `discriminated`.
+- Modifiers: `.nullable()`, `.optional()`, `.default(v)`, `.describe(s)`.
+- Eight data-schema axes:
+  1. `.weighted(pairs)` — non-uniform discrete sampling.
+  2. `.in(values)` / `.in({ kind: 'lookup', ... })` — closed domain.
+  3. `.derivedFrom(ctx => ...)` — computed fields.
+  4. `.invariant(fn)` / `.correlate(fn)` on `obj({...})` — predicates.
+  5. `discriminated(key, map)` — conditional shape.
+  6. `mockDataset({ name, schema, identity, n })` — dataset abstraction.
+  7. Identity caching via `identity` key tuple.
+  8. `.occasionally(value, p)` and `.eventually(every, value)` overrides.
+- Generator: `mock(schema, opts)` with deterministic mulberry32 PRNG seeded
+  by mulberry32 + sha256 over path + identity tuple.
+- Validator: `parse(schema, value)` (throws `ConformError`) and
+  `safeParse(schema, value)` (discriminated result).
+- Cross-dataset FK: `relate(rows, field, opts)` for `.derivedFrom(...)`.
+- Snapshot helpers: `replay(schema, opts)`, `expectStable(schema, opts)`.
+- Debug: `createTrace()` — per-axis decision audit.
+- Extensibility API: `walkSchema`, `fromIR`, `mulberry32`, `rngFromString`,
+  `seedFromString`, public IR types (`SchemaNode`, `Modifiers`, `Axes`).
+- TypeScript types throughout; `Infer<typeof schema>` returns the exact shape.
+
+### Requirements
+
+- Node.js ≥ 18.17.
+- Zero runtime dependencies (uses only `node:crypto`).
+
+[Unreleased]: https://github.com/ochairo/smokin/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ochairo/smokin/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smok contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,366 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<div align="center">
+
+# smokin
+
+**Library for describing and generating data.**
+
+[![npm version](https://img.shields.io/npm/v/smokin.svg)](https://www.npmjs.com/package/smokin)
+[![CI](https://github.com/ochairo/smokin/actions/workflows/test.yml/badge.svg)](https://github.com/ochairo/smokin/actions/workflows/test.yml)
+[![Node.js](https://img.shields.io/badge/node-%E2%89%A518.17-brightgreen)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+</div>
+
+`smokin` lets you describe **how data behaves** — distributions, identity,
+derived values, invariants, business domains — not just **what shape** it has.
+One schema acts as your TypeScript type, your runtime validator, and your
+sample-data generator.
+
+It is intentionally small. It does one thing — *data schemas* — and tries to
+do it carefully. There is no HTTP server, no CLI, and no framework adapter
+baked in; you wire it into the tools you already use.
+
+## Why you might like it
+
+- **Zero runtime dependencies.** Only `node:crypto` from the standard library.
+- **TypeScript-first.** `Infer<typeof schema>` gives you a precise type back.
+- **Deterministic.** Same seed → same output, on every machine, every run.
+- **One schema, three uses.** API mocks, test fixtures, and seed data from a
+  single source of truth.
+- **Small surface area.** A pure data-schema DSL — no HTTP layer, no hidden
+  global state, no surprise transitive deps.
+
+> `v0.1.0` — early but ready for use within its scope. Breaking changes will
+> follow semver and be noted in [CHANGELOG.md](CHANGELOG.md).
+
+## Install
+
+```sh
+npm install smokin
+# or: pnpm add smokin
+# or: yarn add smokin
+```
+
+Requires Node.js ≥ 18.17. No transitive dependencies.
+
+## A 60-second tour
+
+```ts
+import { obj, str, int, decimal, arr, mock, parse, type Infer } from 'smokin'
+
+const Product = obj({
+  sku:   str().pattern(/^[A-Z]{3}-\d{4}$/),
+  price: decimal(10, 2)
+    .min('0.01').max('9999.99')
+    .typically(10, 200)             // most prices cluster in this range
+    .occasionally('0.99', 0.02),    // 2% are loss-leaders
+  stock: int().min(0).max(1000),
+})
+
+const Catalog = obj({
+  region: str().in(['us', 'eu', 'jp']),
+  items:  arr(Product).length(10),
+})
+
+type CatalogT = Infer<typeof Catalog>          // inferred TS type
+const sample: CatalogT = mock(Catalog, { seed: 'demo' })
+parse(Catalog, sample)                          // throws on shape mismatch
+```
+
+Run the same code twice with the same seed and you get the same value back.
+
+## Documentation
+
+- [docs/design.md](docs/design.md) — architecture, axis priority, the
+  determinism model.
+- [docs/axes.md](docs/axes.md) — full reference for every axis and modifier.
+- [docs/recipes.md](docs/recipes.md) — practical patterns: FK, cadence, lookup
+  domains, snapshot tests.
+- [docs/extending.md](docs/extending.md) — plugin author guide.
+- [CHANGELOG.md](CHANGELOG.md) — release notes.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — local development workflow.
+- [SECURITY.md](SECURITY.md) — how to report a vulnerability.
+
+## How smokin fits next to other tools
+
+Other libraries in this space are excellent at what they do; `smokin` simply
+covers a different corner.
+
+| Tool | Best at | Where `smokin` adds something |
+| --- | --- | --- |
+| `zod` + `zod-fixture` | Type validation | Distributions, identity, and derived values — not only shape |
+| `@faker-js/faker` | Rich value primitives | Values stay linked to your schema and domain rules |
+| `msw` | Request interception | Pair them — `msw` for transport, `smokin` for response bodies |
+| `prism` | OpenAPI-driven mocking | Deterministic, programmable values without a spec file |
+
+If your need is "validate this object," reach for `zod`. If it is "give me a
+realistic name," reach for `faker`. If it is "give me a coherent, repeatable
+dataset that obeys my domain rules," `smokin` may be a good fit.
+
+## The 8 axes
+
+`smokin` lets you express things a plain table schema cannot:
+
+```ts
+// 1. Distribution — where values concentrate, not just the bounds
+decimal(10, 2).min('0').max('1000').typically(100, 300)
+
+// 2. Domain — closed candidate set, optionally keyed off a sibling
+str().in(['us', 'eu', 'jp'])
+str().in({ kind: 'lookup', fromField: 'region',
+           map: { us: ['CA', 'NY'], eu: ['DE', 'FR'] } })
+
+// 3. Derived — computed from other fields, never sampled
+int().derivedFrom(ctx => (ctx.parent.qty as number) * (ctx.parent.price as number))
+
+// 4. Invariants — predicates the value must satisfy (rejection sampling)
+int().min(0).max(100).invariant(v => (v as number) % 2 === 0)
+
+// 5. Occasionally — rare overrides stacked before sampling
+int().min(0).max(10).occasionally(-1, 0.01)
+
+// 6. Discriminated — conditional shape switched by a literal field
+discriminated('kind', {
+  digital:  obj({ kind: literal('digital'),  downloadUrl: str() }),
+  physical: obj({ kind: literal('physical'), weightKg: decimal(6, 2) }),
+})
+
+// 7. Identity — same identity tuple → same record across endpoints
+mockDataset({
+  name: 'Products',
+  schema: Product,
+  identity: ['sku'],
+  n: 100,
+})
+
+// 8. Weighted choice — non-uniform discrete sampling
+enum_(['A', 'B', 'C']).weighted([['A', 0.7], ['B', 0.2], ['C', 0.1]])
+```
+
+When two axes overlap, the priority is well-defined and traceable — see
+[docs/design.md](docs/design.md).
+
+## Going deeper
+
+These features build on the 8 axes for cases where they help most —
+determinism, identity, multi-field rules.
+
+### `.eventually(every, value)` — periodic events
+
+Sets `value` deterministically every N rows, driven by `ctx.index`. Useful
+for scheduled outages, weekly resets, or monthly billing edges.
+
+```ts
+const dailyTotal = decimal(10, 2).min('0').max('10000')
+  .typically(1_000, 3_000)
+  .eventually(30, '0')                  // every 30th day is a zero
+```
+
+`occasionally` is probabilistic and i.i.d.; `eventually` is deterministic and
+periodic. They can be combined.
+
+### `.correlate(fn)` — multi-field invariants
+
+Available on `obj({...})`. The predicate receives the fully-assembled object
+with full type information, and the generator rejection-samples until it
+holds.
+
+```ts
+const DateRange = obj({
+  start: int().min(0).max(100),
+  end:   int().min(0).max(100),
+}).correlate(r => r.start <= r.end)
+```
+
+### `relate(rows, field)` — cross-dataset FK
+
+Pick a foreign-key value from a previously-generated dataset. Selection is
+deterministic per seed; modes include `random` (default), `index` (per-row),
+or a custom `(ctx) => number` resolver.
+
+```ts
+import { mockDataset, obj, str, int, arr, relate, mock } from 'smokin'
+
+const customers = mockDataset({
+  name: 'customers',
+  schema: obj({ id: str() }),
+  identity: ['id'],
+  n: 5,
+})
+
+const Order = obj({
+  orderId:    int(),
+  customerId: str().derivedFrom(relate(customers, 'id')),
+})
+
+mock(arr(Order).length(10), { seed: 's' })   // each order references a real customer
+```
+
+### `createTrace()` — see which axis fired where
+
+Audits every decision the generator made. Helpful when output surprises you,
+or when you want to confirm the intended axis won.
+
+```ts
+import { mock, createTrace } from 'smokin'
+
+const trace = createTrace()
+mock(schema, { seed: 'demo', trace })
+
+console.log(trace.format())
+// /              type
+// /price         distribution
+// /customerId    derived
+// /flag          occasionally
+```
+
+### `replay()` and `expectStable()`
+
+Snapshot-style helpers for tests. `replay` returns a callable bound to a
+fixed `(seed, input)` pair; `expectStable` runs the generator twice and
+throws if results diverge — useful for catching accidental `Date.now()` or
+`Math.random()` calls inside `derivedFrom`.
+
+```ts
+import assert from 'node:assert/strict'
+import { replay, expectStable } from 'smokin'
+
+const gen = replay(Schema, { seed: 'fix-1' })
+assert.deepEqual(gen(), gen())                // stable
+
+expectStable(Schema, { seed: 'fix-1' })       // throws if non-deterministic
+```
+
+Works with any assertion library — the example above uses `node:test`'s
+built-in `assert`; substitute `expect(...).toEqual(...)` (Jest/Vitest) or
+`t.deepEqual(...)` (AVA) as needed.
+
+## Wiring into an HTTP framework
+
+`smokin` ships no server — you bring the framework. A few lines of glue is
+usually enough. Here is a Fastify example:
+
+```ts
+import Fastify from 'fastify'
+import { obj, int, decimal, mockDataset } from 'smokin'
+
+const Item = obj({
+  id:    int().min(1),
+  price: decimal(10, 2).min('0').max('10000'),
+})
+
+const app = Fastify()
+app.get('/items', async (req) => {
+  const seed = `GET:/items:${JSON.stringify(req.query)}`
+  return {
+    result: mockDataset({
+      name: 'items', schema: Item, identity: ['id'], n: 10, seedPrefix: seed,
+    }),
+  }
+})
+await app.listen({ port: 8000 })
+```
+
+The same pattern works for Express, Hono, `msw`, or raw `node:http`.
+
+## Determinism guarantee
+
+Given the same `seed`, `smokin` produces identical output on every run and
+every machine — which makes tests, replays, diffs, and offline demos
+predictable. For HTTP, a common pattern is `sha256(method + path + sorted
+query string)` so the response is a pure function of the request. You can
+override per call with `mock(schema, { seed: 'explicit' })` or per dataset
+via `seedPrefix`.
+
+## Intentional non-goals
+
+Things `smokin` deliberately does *not* try to do, to stay small and
+predictable:
+
+- No constraint solver — when axes cannot all be satisfied, you get a
+  `SchemaConflictError` rather than silent guessing.
+- No circular field dependencies in `derivedFrom`.
+- No `Math.random()` or `Date.now()` inside generation (they would break
+  determinism).
+- No float-equality invariants — use `decimal()` for money.
+- No implicit time-of-day in defaults — pass `ctx.input.now` when you need
+  "today".
+- No HTTP server, no CLI, no OpenAPI ingestion — these belong in external
+  packages.
+
+## Extending smokin (for library authors)
+
+`smokin` exposes the minimum surface needed to build adapters and codegen
+tools on top of it:
+
+| Export | Use case |
+| --- | --- |
+| `walkSchema(node, { enter, leave })` | Codegen: OpenAPI, JSON Schema, SQL DDL, docs |
+| `fromIR(node)` | Reconstruct a typed `Schema` builder from raw IR |
+| `SchemaNode`, `Modifiers`, `Axes` (types) | Type-safe IR consumption |
+| `mulberry32`, `rngFromString`, `seedFromString` | Plugins that need their own deterministic RNG branch |
+| `MockOptions.trace` | Hook into per-axis decisions |
+
+A minimal codegen plugin:
+
+```ts
+import { walkSchema, type Schema } from 'smokin'
+
+export const toJsonSchema = (schema: Schema): unknown => {
+  const stack: unknown[] = []
+  walkSchema(schema, {
+    enter(node) {
+      // map a smokin kind → JSON Schema fragment, push onto stack
+    },
+    leave() {
+      // fold children into parent
+    },
+  })
+  return stack[0]
+}
+```
+
+Plugin authors do not subclass `Schema`; they produce IR (or compose existing
+builders) and call `fromIR` to get a typed builder back.
+
+## Project layout
+
+```text
+src/
+  foundation/   # IR, types, prng, sha256, errors, axes, walk
+  schema/       # primitives, decimal, composites, discriminated
+  generator/    # sampling engine, trace, replay
+  validator/    # parse / safeParse
+  dataset/      # dataset + identity cache + relate
+  index.ts      # public surface
+test/           # tests run with node:test against tsc-compiled output
+```
+
+## Contributing
+
+Issues, questions, and pull requests are welcome. The library is small on
+purpose, so changes that grow the surface area will be discussed before
+merging — please open an issue first for anything non-trivial.
+
+```sh
+git clone https://github.com/ochairo/smokin.git
+cd smokin
+corepack enable          # uses the pnpm version pinned in package.json
+pnpm install
+pnpm test                # compiles test/ with tsc, runs node:test
+pnpm typecheck
+pnpm build
+```
+
+The test runner is `node --test` against tsc-compiled output — no `tsx`, no
+`ts-node`, no bundler. Please keep it that way; the lack of build tooling is
+a feature.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow and
+[SECURITY.md](SECURITY.md) for vulnerability reports.
+
+## License
+
+MIT © 2026 smokin contributors. See [LICENSE](LICENSE).

package/dist/dataset/dataset.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Dataset abstraction (Z_PLAN §0.5.2).
+ *
+ * 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 is implemented as a per-(datasetName, identityValues) seed:
+ *   seed = sha256(datasetName + "|" + sorted_kv_pairs_of_K).slice(0, 16)
+ * The same identity tuple always yields the same record, regardless of which
+ * endpoint asks for it.
+ */
+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. Records sharing identity values are cached in `cache` and
+ * deduplicated automatically.
+ */
+export declare const mockDataset: <S extends Schema<unknown>>(opts: DatasetOptions<S>) => Infer<S>[];
+/**
+ * Produce the deterministic identity key for a record. Two records with the
+ * same identity values produce the same key (and thus collapse in the cache).
+ */
+export declare const identityFor: (datasetName: string, identityKeys: readonly string[], row: Record<string, unknown>) => string;
+//# 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;;;;;;;;;;;;;GAaG;AAKH,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;AAID;;;;GAIG;AACH,eAAO,MAAM,WAAW,oCAA4B,eAAe,CAAC,CAAC,KAAG,MAAM,CAAC,CAAC,EAgC/E,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,gBACT,MAAM,gBACL,SAAS,MAAM,EAAE,OAC1B,OAAO,MAAM,EAAE,OAAO,CAAC,KAC3B,MAIF,CAAA"}

package/dist/dataset/dataset.js

@@ -0,0 +1,63 @@
+/**
+ * Dataset abstraction (Z_PLAN §0.5.2).
+ *
+ * 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 is implemented as a per-(datasetName, identityValues) seed:
+ *   seed = sha256(datasetName + "|" + sorted_kv_pairs_of_K).slice(0, 16)
+ * The same identity tuple always yields the same record, regardless of which
+ * endpoint asks for it.
+ */
+import { SchemaConflictError } from '../foundation/errors.js';
+import { identityKey } from '../foundation/hash.js';
+import { mock } from '../generator/engine.js';
+const MAX_DATASET_ATTEMPTS = 1;
+/**
+ * Generate `n` records that conform to the schema and satisfy all aggregate
+ * invariants. Records sharing identity values are cached in `cache` and
+ * deduplicated automatically.
+ */
+export const mockDataset = (opts) => {
+    const cache = new Map();
+    for (let attempt = 0; attempt <= MAX_DATASET_ATTEMPTS; attempt += 1) {
+        const rows = [];
+        for (let i = 0; i < opts.n; i += 1) {
+            // For non-identity-aware production, sub-seed each row with index.
+            // The identity key is computed AFTER generation; if a collision occurs
+            // the cached value is returned to honour the identity uniqueness rule.
+            const rowSeed = `${opts.seedPrefix ?? opts.name}:row:${i}:attempt:${attempt}`;
+            const row = mock(opts.schema, {
+                seed: rowSeed,
+                index: i,
+                ...(opts.input !== undefined ? { input: opts.input } : {}),
+            });
+            const key = identityFor(opts.name, opts.identity, row);
+            const existing = cache.get(key);
+            if (existing !== undefined) {
+                rows.push(existing);
+                continue;
+            }
+            cache.set(key, row);
+            rows.push(row);
+        }
+        const invariants = opts.invariants ?? [];
+        if (invariants.every((j) => j(rows)))
+            return rows;
+    }
+    throw new SchemaConflictError(`dataset "${opts.name}": aggregate invariants unsatisfied after ${MAX_DATASET_ATTEMPTS + 1} attempts`, [opts.name], 'narrow per-record distribution or relax aggregate invariants');
+};
+/**
+ * Produce the deterministic identity key for a record. Two records with the
+ * same identity values produce the same key (and thus collapse in the cache).
+ */
+export const identityFor = (datasetName, identityKeys, row) => {
+    const parts = {};
+    for (const k of identityKeys)
+        parts[k] = JSON.stringify(row[k] ?? null);
+    return identityKey('DATASET', datasetName, parts);
+};
+//# 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":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAA;AAoB7C,MAAM,oBAAoB,GAAG,CAAC,CAAA;AAE9B;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAmB,IAAuB,EAAc,EAAE;IACnF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAA;IACzC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,oBAAoB,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,GAAe,EAAE,CAAA;QAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,mEAAmE;YACnE,uEAAuE;YACvE,uEAAuE;YACvE,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,QAAQ,CAAC,YAAY,OAAO,EAAE,CAAA;YAC7E,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;gBAC5B,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,CAAC;gBACR,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC3D,CAAC,CAAA;YACF,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,GAA8B,CAAC,CAAA;YACjF,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC/B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;gBACnB,SAAQ;YACV,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;YACnB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAChB,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,6CAA6C,oBAAoB,GAAG,CAAC,WAAW,EACrG,CAAC,IAAI,CAAC,IAAI,CAAC,EACX,8DAA8D,CAC/D,CAAA;AACH,CAAC,CAAA;AAED;;;GAGG;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;QAAE,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAA;IACvE,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 (A1) — 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 Bases = mockDataset({ name: 'bases', schema: Base, identity: ['base_code'], n: 5 })
+ *
+ * const Tank = obj({
+ *   tank_no:    str(),
+ *   base_code:  str().derivedFrom(relate(Bases, 'base_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 keyof R>(rows: readonly R[], field: K, opts?: RelateOptions) => DerivedFn;
+//# 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,+DACX,SAAS,CAAC,EAAE,SACX,CAAC,SACF,aAAa,KAClB,SAoBF,CAAA"}

package/dist/dataset/relate.js

@@ -0,0 +1,46 @@
+/**
+ * Cross-dataset FK identity (A1) — 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 Bases = mockDataset({ name: 'bases', schema: Base, identity: ['base_code'], n: 5 })
+ *
+ * const Tank = obj({
+ *   tank_no:    str(),
+ *   base_code:  str().derivedFrom(relate(Bases, 'base_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 "${String(field)}")`);
+    }
+    const strategy = opts.pickBy ?? 'random';
+    return (ctx) => {
+        let idx;
+        if (strategy === 'index') {
+            idx = (ctx.index ?? 0) % rows.length;
+        }
+        else if (typeof strategy === 'function') {
+            idx = strategy(ctx) % rows.length;
+            if (idx < 0)
+                idx += rows.length;
+        }
+        else {
+            // Deterministic uniform: derive a sub-RNG from the path-bound seed.
+            const rng = mulberry32(seedFromString(`${ctx.seed}|relate|${String(field)}`));
+            idx = Math.floor(rng.next() * rows.length);
+        }
+        const row = rows[idx];
+        return row === undefined ? undefined : row[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,EACb,EAAE;IACb,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,UAAU,CAAC,6CAA6C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACtF,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAA;IACxC,OAAO,CAAC,GAAe,EAAW,EAAE;QAClC,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,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAA;YACjC,IAAI,GAAG,GAAG,CAAC;gBAAE,GAAG,IAAI,IAAI,CAAC,MAAM,CAAA;QACjC,CAAC;aAAM,CAAC;YACN,oEAAoE;YACpE,MAAM,GAAG,GAAG,UAAU,CAAC,cAAc,CAAC,GAAG,GAAG,CAAC,IAAI,WAAW,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;YAC7E,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;QACrB,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IACnD,CAAC,CAAA;AACH,CAAC,CAAA"}