@ghostry/fabricator 0.0.1

package/dist/types/Adapter/Core.d.ts

@@ -0,0 +1,64 @@
+import { Adaptation } from "../Types";
+import type { Adaptations, AdaptationsOf, Adapter, Adapting, WithAdaptations } from "./Types";
+type OverrideSchemaAdaptation<$Schema extends object, $Map extends Adaptations> = Omit<$Schema, typeof Adaptation> & {
+    readonly [Adaptation]?: WithAdaptations<AdaptationsOf<$Schema>, $Map>;
+};
+/**
+ * One adapter's entry, keyed by `$Adapter["key"]`. Written as a mapped
+ * type rather than built inline: a computed key in an object literal
+ * (`{ [adapter.key]: produce }`) widens to a `string` index signature,
+ * which no adapter's literal-keyed dispatch matches.
+ */
+export type AdaptationEntry<$Adapter extends Adapter, $Returnable> = {
+    readonly [$K in $Adapter["key"]]: (schema: any) => $Returnable;
+};
+/**
+ * A copy of `schema` carrying `produce` as `adapter`'s adaptation:
+ * that adapter's prior entry is replaced (via {@link layer}), every
+ * other adapter's is carried forward. Every kind's `.adapt(...)` is a
+ * call to this, re-typed to that kind's own
+ * `Schema<..., WithAdaptations<...>>`.
+ *
+ * Takes the adapter and producer separately rather than a prebuilt map
+ * so the key stays a literal, per {@link AdaptationEntry}. The return
+ * type mirrors the merge (rather than handing back `$Schema`) so call
+ * sites need no cast: `AdaptationsOf<$Schema>` recovers the prior map
+ * from whichever kind's `Core` was passed in.
+ */
+export declare function withAdaptations<const $Schema extends object, const $Adapter extends Adapter, $Returnable>(schema: $Schema, adapter: $Adapter, produce: (adapting: Adapting<any>) => $Returnable): OverrideSchemaAdaptation<$Schema, AdaptationEntry<$Adapter, $Returnable>>;
+/**
+ * {@link withAdaptations} at the map level, for a kind that keeps its
+ * adaptations beside its schema rather than on it — `object`, whose
+ * `extend`/`refine`/`override` each rebuild the schema from scratch, so
+ * `Registry.ts`'s `make` has to thread the map through explicitly (see
+ * its `adapt`).
+ *
+ * `undefined` rather than an empty map when there is nothing to carry,
+ * for the same reason `patched` drops the symbol: an absent map and an
+ * empty one mean the same thing, and only one of them should exist at
+ * runtime.
+ */
+export declare function mergeAdaptations<$Prior extends Adaptations, const $Adapter extends Adapter, $Returnable>(prior: $Prior | undefined, adapter: $Adapter, produce: (adapting: Adapting<any>) => $Returnable): WithAdaptations<$Prior, AdaptationEntry<$Adapter, $Returnable>> | undefined;
+/**
+ * Walk `schema` with `adapter`, resolving each node to its external
+ * counterpart. Every adapter's entry point is a call to this.
+ *
+ * The adaptation lookup lives here, ahead of the adapter's own
+ * per-kind dispatch, so an explicit adaptation wins over the kind's
+ * mapping — and here rather than in each adapter so it applies at
+ * *every* node the walk reaches, not just the one it started from.
+ * That is why an adapter recurses through the {@link Recurse} it is
+ * handed rather than calling its own `convert` again: a nested
+ * `object` field, `array` element, or `choice` option gets the same
+ * treatment as the root.
+ *
+ * Paired with {@link layer}: together they make `toTypeBox(schema)`
+ * *inside* an adaptation resolve to the layer that adaptation replaced
+ * instead of re-entering itself. This reads the entry; `layer` already
+ * substituted the previous one into the argument. Splitting the two
+ * across packages is how they drift.
+ */
+export declare function drive<$Context, $Returnable>(adapter: Adapter<string, $Context, $Returnable>, schema: {
+    [Adaptation]?: Adaptations;
+}, context: $Context): $Returnable;
+export {};

package/dist/types/Adapter/Types.d.ts

@@ -0,0 +1,145 @@
+import type { Adaptation, Meta } from "../Types";
+/**
+ * One adapter's override for one schema, *as stored* in `[Adaptation]` —
+ * the loosest signature the mechanism needs. An adapter states its real
+ * return type on {@link Adapter.convert}, and `.adapt(...)` checks a
+ * supplied adaptation against that; nothing here reads either end.
+ *
+ * Not the shape a caller writes: a kind's `.adapt(...)` takes a producer
+ * of {@link Adapting}, which `Adapter/Core.ts`'s `withAdaptations`/
+ * `mergeAdaptations` wrap into this one entry point-side. The stored
+ * form stays schema-taking so `patched`/`layer` treat an incoming
+ * producer and a prior layered entry as one type, and so
+ * `AdaptationEntry`'s `(schema: any) => $Returnable` is an accurate
+ * account of what a schema carries.
+ */
+export type SchemaAdaptation = (schema: any) => unknown;
+/**
+ * What a kind's `.adapt(adapter, produce)` hands its producer: the schema
+ * being adapted, and that schema's `[Meta]` — one object rather than two
+ * parameters, so destructuring picks whichever half is needed and neither
+ * is reachable only through a well-known symbol.
+ *
+ * `schema` carries whichever adaptation for this same adapter it
+ * replaced, absent at the bottom of the stack (see `Adapter/Core.ts`'s
+ * `layer`) — so `toTypeBox(schema)` inside a producer resolves to the
+ * previous layer, or to the kind's ordinary mapping when there is none.
+ * `meta` is read off that same substituted schema, so the two keys
+ * describe one object.
+ *
+ * `meta`'s shape is the kind's own config blob, derived by indexed
+ * access rather than named separately so no kind states its own `Meta`
+ * twice in an `adapt` signature. **Readable but not stabilized**: an
+ * adaptation may read it; a kind stays free to restructure it — nothing
+ * outside a kind's own files should *interpret* another kind's `[Meta]`.
+ *
+ * A kind with no bare-form default carries no `[Meta]` at runtime until
+ * configured (`string`/`bigint`'s registry exports — see "Anatomy of a
+ * primitive"), so `meta` can be `undefined` there despite this type.
+ * Same imprecision `Schema<$Meta>` already states, and why the TypeBox
+ * adapter reads `[Meta]` defensively for those kinds.
+ */
+export type Adapting<$Schema extends {
+    [Meta]: unknown;
+}> = {
+    readonly schema: $Schema;
+    readonly meta: $Schema[typeof Meta];
+};
+/**
+ * What a Schema's `[Adaptation]` holds: each adapter's override, under
+ * that adapter's own key.
+ *
+ * Open rather than a closed registry of known libraries: an adapter is
+ * a value (see {@link Adapter}), not a name this package knows. Nothing
+ * has to be declared for a third party's adapter to work, and two
+ * adapters for different versions of the same library collide with
+ * nothing.
+ */
+export type Adaptations = {
+    readonly [key: string]: SchemaAdaptation;
+};
+/**
+ * An {@link Adaptations} update as `withAdaptations` accepts it. Identical
+ * except that an explicitly-`undefined` entry *removes* that adapter's
+ * override — how the layering hands an adaptation the schema it is
+ * adapting with its own entry replaced by the previous one, or absent
+ * at the bottom of the stack.
+ *
+ * Not what a kind's `.adapt(...)` accepts: removal is an internal need
+ * of the layering, and letting a caller express it would produce a
+ * `[Adaptation]` type that `exactOptionalPropertyTypes` rejects against
+ * {@link Adaptations}.
+ */
+export type Patch = {
+    readonly [key: string]: SchemaAdaptation | undefined;
+};
+/**
+ * How an adapter recurses into a nested schema — handed to
+ * {@link Adapter.convert} by `Adapter/Core.ts`'s `drive` rather than
+ * being the adapter's own private recursion, so every nested node goes
+ * back through the adaptation lookup, not only the outermost one.
+ *
+ * `$Context` is the adapter's own, and opaque here: an adapter that
+ * needs to carry something down its recursion (the enclosing
+ * `T.recursive`'s placeholder, say) threads it through unchanged.
+ * `$Returnable` is likewise the adapter's own — stated so a nested
+ * node's result drops straight into a composite
+ * (`Type.Array(recurse(element, context))`) with no cast at any call
+ * site.
+ */
+export type Recurse<$Context, $Returnable> = (schema: any, context: $Context) => $Returnable;
+/**
+ * An adapter to one external schema library: a plain value, imported
+ * directly by whoever adapts a schema (`schema.adapt(typebox, ...)`)
+ * and by whoever converts one. Nothing to register — no global
+ * interface to declaration-merge, and no name chosen anywhere but here.
+ *
+ * `key` is the adapter's `[Adaptation]` namespace. Read off the value
+ * as a literal type, so a wrong one is an import error rather than an
+ * entry nothing looks up. Give it something collision-proof — a package
+ * specifier, versioned when a library's major rewrite means two
+ * adapters can coexist.
+ *
+ * `convert`'s declared return type is this adapter's external bound:
+ * the type every `.adapt(...)` against it must produce, and why an
+ * adaptation that returns the wrong thing fails at the call site.
+ *
+ * Deliberately *not* carrying the adapter's type-level mapping. An
+ * adapter package declares its own conversion entry point with its own
+ * return type (`toTypeBox<$S>(schema: $S): ToTypeBox<$S>`), so nothing
+ * has to compute a type-level mapping out of a stored value — which
+ * would need the interface-member-lookup encoding `ValueOf`'s
+ * `$Bindings` uses, for no gain.
+ */
+export interface Adapter<$Key extends string = string, $Context = unknown, $Returnable = unknown> {
+    readonly key: $Key;
+    convert(schema: any, recurse: Recurse<$Context, $Returnable>, context: $Context): $Returnable;
+}
+/**
+ * The adaptations a Schema (or a built Fabricator, which carries them
+ * identically) declares, or `{}` for one that declares none.
+ *
+ * The two steps — extract the map, then match against it — are
+ * load-bearing, and why no adapter matches
+ * `{ [Adaptation]?: Record<Key, ...> }` directly. Every kind's `Core`
+ * declares `[Adaptation]` as *optional*, and a conditional matching an
+ * optional property against a schema that lacks it entirely still
+ * *succeeds*, inferring `unknown` (the same behavior `ValueOf` relies
+ * on for `[Produces]`) — so a direct match would resolve every
+ * unadapted schema to whatever the adapter's adaptation branch
+ * produces. Constraining the `infer` sends that case here, to `{}`,
+ * which then fails each adapter's `Record<Key, ...>` check as it
+ * should.
+ */
+export type AdaptationsOf<$Schema> = $Schema extends {
+    [Adaptation]?: infer $Adaptations extends Adaptations;
+} ? $Adaptations : {};
+/**
+ * `$Prior` with `$Map` applied: an adapter named in `$Map` takes its new
+ * entry; one it doesn't name is carried forward. `Omit` first (rather
+ * than a plain `$Prior & $Map`) so a replaced entry is genuinely
+ * replaced — intersecting two call signatures for the same adapter
+ * would produce an overload, from which an adapter's `infer` would
+ * read whichever member TypeScript happens to resolve last.
+ */
+export type WithAdaptations<$Prior extends Adaptations, $Map extends Adaptations> = Omit<$Prior, keyof $Map> & $Map;

package/dist/types/Bound.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Canonical endpoint stored on `[Meta].whereby`. Call sites still accept a
+ * scalar (inclusive) via {@link InputBound}; `.whereby()` runs {@link toBound}
+ * so adapters always see this shape — never a scalar/object union.
+ */
+export type Bound<$T> = {
+    value: $T;
+    exclusive: boolean;
+};
+/**
+ * What `.whereby({ min, max })` accepts: a scalar is inclusive, an object
+ * names an endpoint policy. `exclusive` is required on the object form so
+ * that form exists only to state one.
+ */
+export type InputBound<$T> = $T | Bound<$T>;
+/**
+ * Collapse a call-site bound to the stored shape. A `Date` is a scalar here
+ * (`isPlainObject` rejects it); only a `{ value, exclusive }` literal is
+ * already canonical.
+ */
+export declare function toBound<$T>(input: InputBound<$T>): Bound<$T>;
+/**
+ * Inclusive integer interval implied by a discrete Bound pair. Exclusive min
+ * is `value + 1`, exclusive max is `value - 1` — the same unit the length/
+ * integer/bigint draws already use. Empty iff `min > max`.
+ */
+export declare function effectiveDiscrete(min: Bound<number>, max: Bound<number>): {
+    min: number;
+    max: number;
+};
+export declare function effectiveDiscreteBigint(min: Bound<bigint>, max: Bound<bigint>): {
+    min: bigint;
+    max: bigint;
+};
+export declare function assertNonemptyDiscrete(label: string, min: Bound<number>, max: Bound<number>): void;
+export declare function assertNonemptyDiscreteBigint(label: string, min: Bound<bigint>, max: Bound<bigint>): void;
+/**
+ * Continuous emptiness: inverted bounds, a point range with either end
+ * exclusive, or both ends exclusive with no float strictly between them.
+ * Sampling still uses the closed interval and {@link constrainContinuous}
+ * steps off an exclusive endpoint — this check is what makes that step
+ * always have somewhere to land.
+ */
+export declare function assertNonemptyContinuous(label: string, min: Bound<number>, max: Bound<number>): void;
+/**
+ * One ulp toward `toward` from `value`. Approximate, and enough to leave
+ * an exclusive endpoint without rejection-looping a truncated distribution
+ * that clamped onto it.
+ */
+export declare function towardInterior(value: number, toward: number): number;
+/**
+ * After a closed-interval draw: if the result equals an exclusive endpoint,
+ * step one ulp toward the interior. Does not resample — a truncated
+ * distribution's mass on the bound would otherwise loop.
+ */
+export declare function constrainContinuous(next: () => number, min: Bound<number>, max: Bound<number>): () => number;
+export declare function epochBound(bound: Bound<Date>): Bound<number>;
+/**
+ * Array/string `length`: a bare number is an exact count; an omitted `min`
+ * is inclusive `0`. Always stored as a Bound pair so adapters have one path.
+ */
+export declare function toLengthRange(length: number | {
+    max: InputBound<number>;
+    min?: InputBound<number> | undefined;
+}, label: string): {
+    min: Bound<number>;
+    max: Bound<number>;
+};

package/dist/types/Distribution/index.d.ts

@@ -0,0 +1,157 @@
+import type { Stream } from "../Random/Types";
+/**
+ * How randomly generated values cluster within a `{ min, max }` range.
+ * Without one, generation is uniform — every value in the range is
+ * equally likely.
+ *
+ * Each variant is a tagged object so distributions stay
+ * introspectable and serializable. The `custom` variant is the escape
+ * hatch: a shaping function `(u) => p` mapping a uniform draw in
+ * `[0, 1)` to a position in `[0, 1)` within the range.
+ */
+export type Distribution = Distribution.Uniform | Distribution.Normal | Distribution.Skew | Distribution.Triangular | Distribution.Logarithmic | Distribution.Multi | Distribution.Custom;
+export type Range = {
+    min: number;
+    max: number;
+};
+export declare namespace Distribution {
+    type Uniform = {
+        kind: "uniform";
+    };
+    const uniform: () => Uniform;
+    type Normal = {
+        kind: "normal";
+        mean?: number | undefined;
+        spread?: number | undefined;
+    };
+    /**
+     * Bell curve truncated to the range. `mean` defaults to the range's
+     * center; `spread` (standard deviation) defaults to a sixth of the
+     * span, placing the bounds at roughly ±3σ before truncation.
+     */
+    const normal: (params?: {
+        mean?: number;
+        spread?: number;
+    }) => Normal;
+    type Skew = {
+        kind: "skew";
+        exponent: number;
+    };
+    /**
+     * Power curve. `exponent > 1` biases toward `min`, `exponent < 1`
+     * biases toward `max`, and `exponent === 1` is uniform.
+     */
+    const skew: (exponent: number) => Distribution;
+    type Triangular = {
+        kind: "triangular";
+        mode?: number | undefined;
+    };
+    /**
+     * Linear ramps peaking at `mode` (defaults to the range's center).
+     */
+    const triangular: (params?: {
+        mode?: number;
+    }) => Distribution;
+    type Logarithmic = {
+        kind: "logarithmic";
+    };
+    /**
+     * Log-uniform (reciprocal): density proportional to `1/x`, so values
+     * spread evenly across orders of magnitude and cluster toward `min`.
+     * Requires a strictly positive range — the logarithm is undefined at
+     * or below zero.
+     */
+    const logarithmic: () => Distribution;
+    type Multi = {
+        kind: "multi";
+        components: ReadonlyArray<{
+            weight: number;
+            distribution: Distribution;
+        }>;
+    };
+    /**
+     * A weighted blend of component distributions, each drawn over the
+     * same range. Localized components with distinct centers (e.g. two
+     * `normal`s at different means) produce the separate peaks of a
+     * multimodal distribution. Weights are relative — they need not sum
+     * to 1.
+     */
+    const multi: (components: ReadonlyArray<{
+        weight: number;
+        distribution: Distribution;
+    }>) => Distribution;
+    type Custom = {
+        kind: "custom";
+        shape: (u: number) => number;
+    };
+    /**
+     * Escape hatch: `shape` maps a uniform draw in `[0, 1)` to a
+     * position in `[0, 1)` within the range (an inverse CDF). The output
+     * is clamped to `[0, 1]` so the result always lands within the
+     * bounds.
+     */
+    const custom: (shape: (u: number) => number) => Distribution;
+}
+/**
+ * Build a sampler that draws values within `range` following
+ * `distribution`. Each call consumes one fresh uniform draw and, by
+ * construction, returns a value within `[min, max]` — distributions
+ * with mass outside the range (e.g. a normal's tails) are truncated
+ * via their inverse CDF rather than rejected or clamped.
+ */
+export declare function sampler(distribution: Distribution, range: Range, stream: Stream): () => number;
+export declare function sample<$T>(list: ReadonlyArray<$T>, stream: Stream): $T;
+/**
+ * Fisher–Yates (Durstenfeld) shuffle: a new array holding `items` in a
+ * uniformly random order — every permutation is equally likely. Does
+ * not mutate `items`, matching `sample`/`weighted`'s read-only
+ * convention.
+ */
+export declare function shuffle<$T>(items: ReadonlyArray<$T>, stream: Stream): $T[];
+/**
+ * `weighted()`'s own inclusion rule: whether this entry stays in the
+ * draw table. `0` is valid and disables the outcome; negative/`NaN`
+ * are rejected earlier by {@link isValidWeight}. Exposed so
+ * `Enumeration/Plan.ts` and the construction guards share one
+ * definition of "will this be drawn" rather than each writing
+ * `weight > 0`.
+ */
+export declare function isDrawable(weight: number): boolean;
+/**
+ * Whether a weight is *expressible* at all, as opposed to whether it is
+ * drawable. `0` is valid and disables the outcome; a negative weight or
+ * `NaN` is a mistake. `Infinity` is rejected because it cannot be summed
+ * into a usable draw table — every cumulative bound becomes `Infinity`,
+ * so `weighted()`'s `x < weight` scan matches nothing.
+ */
+export declare function isValidWeight(weight: number): boolean;
+/**
+ * Outcomes that still have a positive weight after applying the
+ * baseline of `1` for any unspecified (missing or explicitly
+ * `undefined`) key. The one home of that `?? 1` default, so
+ * `assertDrawableKeyedWeights` and `Enumeration/Plan.ts` cannot drift.
+ */
+export declare function drawableOutcomes<$Outcome extends string>(outcomes: ReadonlyArray<$Outcome>, weights: Readonly<Record<string, number | undefined>> | undefined): ReadonlyArray<$Outcome>;
+/**
+ * Two-stage guard for a `[weight, item]` list (`enum`/`choice`'s
+ * `.weighted()` registries). Stage 1 rejects any entry that is not
+ * {@link isValidWeight}; stage 2 rejects a list with no
+ * {@link isDrawable} entry left. `label` names the call site
+ * (`"T.enum.weighted"`/`"T.choice.weighted"`), `noun` the kind of
+ * entry (`"member"`/`"option"`).
+ */
+export declare function assertDrawableWeights(label: string, noun: string, items: ReadonlyArray<readonly [number, unknown]>): void;
+/**
+ * The same two-stage guard as {@link assertDrawableWeights}, for the
+ * kinds whose `.weighted(...)` weighs a *fixed, named* outcome set
+ * (`boolean`'s `true`/`false`; `nullable`/`nullish`/`undefinable`/
+ * `object.omittable`/`object.optional`'s presence outcomes) rather than a
+ * caller-supplied list. Stage 2 must see the kind's **full** outcome list
+ * — an omitted key still defaults to `1` — hence `outcomes`.
+ *
+ * An explicitly-`undefined` value means "unspecified" — `Weights`'
+ * keys are all optional and fall back to a baseline of `1` — so it is
+ * skipped in stage 1 and defaulted in stage 2.
+ */
+export declare function assertDrawableKeyedWeights<$Outcome extends string>(label: string, outcomes: ReadonlyArray<$Outcome>, weights: Readonly<Record<string, number | undefined>>): void;
+export declare function weighted<const $Item>(weights: ReadonlyArray<readonly [number, $Item]>, stream: Stream, label: string): () => $Item;

package/dist/types/Enumeration/Enumerate.d.ts

@@ -0,0 +1,35 @@
+import type { Stack } from "../Instance/Types";
+import type { RandomSource } from "../Random/Types";
+import type { Enumerable, Limits } from "./Types";
+/**
+ * Typed `combinatorial`/`coverage` boundary, closing over one
+ * instance's `source` and its already-validated `limits` — same shape
+ * as `Constructor(source, stack)`. No separate `clock`: `source`
+ * already carries its resolved clock (`Random/Types.ts`'s
+ * `Options.clock`), so `Constructor`'s `toConstructionContext` reads
+ * it off whichever root a construction resolves against. `plan`/
+ * `resolve` (`./Plan.ts`) do the untyped recursive work; this is the
+ * one precisely-typed layer, mirroring `Constructor.ts`'s `make`/
+ * `construct` split.
+ *
+ * Two derived seeds — one per API — each an independent, deterministic
+ * fork off the *effective* source's seed (`effectiveSource()` below —
+ * the active `wrap` frame's, or this instance's `source`; read fresh
+ * on every `combinatorial(...)`/`coverage(...)` call, not once when
+ * `enumerables()` was built, so the same `combinatorial` reference
+ * behaves differently inside an active `wrap`).
+ * `new Fabricator(schema, { seed })` (see `Constructor.ts`'s
+ * `construct()`) forks a fully isolated `RandomSource` and opens an
+ * `"unattributed"` scope, so `resolveCallerFile()` is never called —
+ * the lazy-generator attribution hazard a plain `function*` would
+ * invite simply doesn't arise — the instance's construction counters
+ * are never touched, and the same seed reproduces regardless of which
+ * file `combinatorial(...)`/`coverage(...)` is called from. Each
+ * `fork()` starts from a fresh source, so reusing one seed across many
+ * builds (different schemas, or the same schema rebuilt per iteration)
+ * never lets one build's draws leak into another's.
+ */
+export declare function enumerables(source: RandomSource, limits: Limits, stack: Stack): {
+    combinatorial: Enumerable;
+    coverage: Enumerable;
+};

package/dist/types/Enumeration/Plan.d.ts

@@ -0,0 +1,44 @@
+import type { Axis, Orderer, Pin, Resolvable } from "./Types";
+type Planning = {
+    strategy: "product";
+    orderer?: Orderer | undefined;
+} | {
+    strategy: "cycle";
+    orderer: Orderer;
+};
+/**
+ * Enumerable shape of a built Fabricator tree: how many distinct
+ * combinations, and how to reproduce the `index`-th as a `Pin`.
+ * Exhaustive kind dispatch lives in `axisFor`; this wrapper applies
+ * `"cycle"` permutation uniformly, once, to whatever axis `axisFor`
+ * computes — so every recursive call (`axisFor` cases call back into
+ * `plan`, never `axisFor` directly) gets its *own* independent
+ * permutation, decorrelating equal-width siblings without any
+ * per-kind case needing to know strategy beyond `Strategy`'s own
+ * widen/narrow rules.
+ *
+ * Width is a function of schema shape *and* weights: a zero-weighted
+ * outcome is not fabricable, so `axisFor` filters through `isDrawable`
+ * / `drawableOutcomes` rather than treating the declared branch set as
+ * the axis. Without that, `coverage()` would pin a value `fabricate()`
+ * can never produce. Defaulting of unspecified keyed weights goes
+ * through `drawableOutcomes` so the `?? 1` baseline is never
+ * re-implemented here.
+ *
+ * Skipped for width-1 axes (nothing to permute) and under `"product"`
+ * (mixed-radix decode already visits every combination, so permuting
+ * would only reorder identical output — see `Orderer`). `orders` is
+ * therefore only ever read when `strategy === "cycle"` and is safe to
+ * omit otherwise.
+ */
+export declare function plan(node: Resolvable, planning: Planning): Axis;
+/**
+ * Reproduce the value a `Pin` describes against the built Fabricator
+ * it was planned from. `pin === undefined` is universal — `plan()`
+ * gave this node a width-1 axis, so there is nothing to pin and it
+ * fabricates normally. Every other case only arises for kinds
+ * `plan()` treats as enumerable axes, so this switch does not need to
+ * be exhaustive the way `plan()`'s is.
+ */
+export declare function resolve(node: Resolvable, pin: Pin): unknown;
+export {};

package/dist/types/Enumeration/Types.d.ts

@@ -0,0 +1,86 @@
+import type { Kind as SchemaKind } from "../Primitive";
+import type { AnySchema, ValueOf } from "../Schema/Types";
+import type { Children, Kind, Meta } from "../Types";
+import type { PlainObject } from "../Utility/Types";
+/**
+ * How a composite with more than one child combines their widths.
+ * `"product"` is the cartesian product — width is the product of every
+ * child's width; `at(index)` mixed-radix decodes to a full combination
+ * (`combinatorial`). `"cycle"` (`coverage`) takes the widest child as
+ * the composite's width, cycling narrower children to fill it — see
+ * CLAUDE.md's "sum vs product" note for why cycling only ever applies
+ * to `object`/`tuple` and never to a sum node (`choice`, the presence
+ * wrappers), which always total their children's widths regardless of
+ * strategy.
+ */
+export type Strategy = "product" | "cycle";
+/**
+ * A fresh, reproducible permutation of `0..width-1` each call — one
+ * per width-`>1` node `plan()` visits, in walk order, so two nodes of
+ * the same width never receive the same permutation (which would
+ * otherwise iterate them in lockstep — see CLAUDE.md's note on why a
+ * constant phase offset isn't enough). Only consulted under `"cycle"`;
+ * `"product"`'s mixed-radix decode already visits every combination,
+ * so permuting there would only reorder identical output. Built in
+ * `Enumerate.ts` (which can reach `Random/`), then threaded through
+ * `plan()` as data — `Plan.ts` stays a total function and never
+ * imports randomness.
+ */
+export type Orderer = (width: bigint) => ReadonlyArray<bigint>;
+/**
+ * Recipe for one enumerated combination against a built Fabricator
+ * tree: `undefined` for a drawn (not chosen) node — fabricate
+ * normally; `{ value }` for a literal (enum member, boolean, `null`,
+ * `undefined`, `Omitted`); `{ slots }`/`{ fields }` for a
+ * tuple/object, recursing per position/key; `{ branch, inner }` for a
+ * choice's chosen option, or a presence wrapper's "present" arm,
+ * recursing into whichever child was picked.
+ */
+export type Pin = undefined | {
+    value: unknown;
+} | {
+    slots: ReadonlyArray<Pin>;
+} | {
+    fields: Record<string, Pin>;
+} | {
+    branch: number;
+    inner: Pin;
+};
+/**
+ * One enumerable dimension: how many distinct outcomes, and the `Pin`
+ * for the `index`-th (`0 <= index < width`). Widths are `bigint` so a
+ * schema with many combined axes can be counted exactly — a `number`
+ * would silently lose precision past `Number.MAX_SAFE_INTEGER` and
+ * eventually overflow to `Infinity`, which would make a combinatorial
+ * limit's error message state a false count.
+ */
+export type Axis = {
+    readonly width: bigint;
+    readonly at: (index: bigint) => Pin;
+};
+/**
+ * Resolved, already-validated enumeration limits — `initialize()` is
+ * where `limits.combinatorial` is defaulted and checked
+ * (`Number.isSafeInteger(limit) && limit >= 1`), so `Enumerate()`
+ * always receives a value it can trust without re-validating.
+ * `coverage` carries no limit here: its count is the widest single
+ * axis, linear in the schema as written rather than a product, so
+ * there is nothing for a limit to protect against.
+ */
+export type Limits = {
+    combinatorial: number;
+};
+/**
+ * The shape both `combinatorial` and `coverage` share — strategy and
+ * limit differ internally, neither visible here. Takes a Schema, not
+ * a built Fabricator: `AnySchema` excludes `Fabricator<any>` (which
+ * carries no `[Produces]`), so `ValueOf` can't silently degrade to
+ * `unknown`.
+ */
+export type Enumerable = <const $Schema extends AnySchema>(schema: $Schema) => Iterable<ValueOf<$Schema>>;
+export type Resolvable = {
+    [Kind]: SchemaKind;
+    [Meta]: PlainObject<any>;
+    [Children]: any;
+    fabricate: (...params: any[]) => unknown;
+};