@ghostry/fabricator 0.0.1 → 0.0.3

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

@@ -1,13 +1,12 @@
 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.
+ * 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.
+ * 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 = {
@@ -25,9 +24,9 @@ export declare namespace Distribution {
         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.
+     * 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;
@@ -38,8 +37,8 @@ export declare namespace Distribution {
         exponent: number;
     };
     /**
-     * Power curve. `exponent > 1` biases toward `min`, `exponent < 1`
-     * biases toward `max`, and `exponent === 1` is uniform.
+     * Power curve. `exponent > 1` biases toward `min`, `exponent < 1` biases
+     * toward `max`, and `exponent === 1` is uniform.
      */
     const skew: (exponent: number) => Distribution;
     type Triangular = {
@@ -56,10 +55,9 @@ export declare namespace Distribution {
         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.
+     * 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 = {
@@ -70,11 +68,10 @@ export declare namespace 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.
+     * 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;
@@ -85,73 +82,69 @@ export declare namespace Distribution {
         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.
+     * 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.
+ * 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.
+ * 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`.
+ * `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.
+ * 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.
+ * 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
+ * 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`/
+ * 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`.
+ * 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.
+ * 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

@@ -2,32 +2,32 @@ 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`/
+ * 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.
+ * Two derived salts — one per API — each composed from the _effective_ source's
+ * salt (`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`). Each build pins that
+ * salt via `new Fabricator(schema, { salt })` (see `Constructor.ts`'s
+ * `construct()`) — a pin, not a fork — so every rebuild of one schema draws
+ * from the same universe, distinct from anything built under the instance's own
+ * salt.
+ *
+ * `ordinal: null` is pinned alongside it, and is not incidental: a salt says
+ * nothing about ordering, so without this pin each lazy rebuild would take the
+ * next ordinal from the effective source's counter — advancing it for every
+ * later construction, and giving each pass over the `Iterable` a different
+ * ordinal. A pinned ordinal is taken verbatim, so the counter is untouched,
+ * every iteration rebuilds from the same explicit identity, and the `null` can
+ * never coincide with a counted construction.
  */
 export declare function enumerables(source: RandomSource, limits: Limits, stack: Stack): {
     combinatorial: Enumerable;

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

@@ -7,38 +7,34 @@ type Planning = {
     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.
+ * 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.
+ * 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.
+ * (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.
+ * 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

@@ -3,38 +3,35 @@ 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.
+ * 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.
+ * 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.
+ * 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;
@@ -47,35 +44,33 @@ export type Pin = undefined | {
     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.
+ * 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
+ * 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`.
+ * 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 = {