@ghostry/fabricator 0.0.2 → 0.0.3

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

@@ -37,25 +37,14 @@ export type Algorithm = (seed: string) => NumberGenerator;
  *
  * Slots, in encoded order:
  *
- * - `seed` — the _instance's_ seed, normalized to its parts
- *   ({@link RandomSource.seed}), not anything derived per leaf.
+ * - `salt` — the _instance's_ salt, normalized to its parts
+ *   ({@link RandomSource.salt}), not anything derived per leaf.
  * - `clock` — this construction's resolved "now," epoch milliseconds
  *   (`Instance/Types.ts`'s `Config.clock`). Second, not after the per-leaf
- *   slots: blast radius matches `seed` — both are instance-level and perturb
- *   every leaf, unlike `file`/`path`/`kind`/`ordinal`, which narrow to one
- *   leaf. Never `undefined` (unlike `file`/`ordinal`): clock is always a
- *   concrete instant before any leaf dispatches (`RandomSource`'s
- *   `Options.clock`).
- * - `root` — how `file` and `ordinal` were resolved ({@link RootKind}). Sits
- *   immediately before `file` because that is what it explains. Distinguishes
- *   the three situations that all produce `file: undefined` (`{ kind: "none" }`
- *   attributed, an unattributed seeded construction, a counted recursive
- *   expansion), so a captured trace can be replayed faithfully via `new
- *   Fabricator(schema, trace)`.
- * - `file` — the file this node's _construction_ (not the node) was attributed
- *   to, relative to the instance's {@link Attribution} root (absolute only if
- *   outside that root). `undefined` under `"counted"` / `"unattributed"`, or
- *   `"attributed"` with `{ kind: "none" }` — {@link RootKind} says which.
+ *   slots: blast radius matches `salt` — both are instance-level and perturb
+ *   every leaf, unlike `path`/`kind`/`ordinal`, which narrow to one leaf. Never
+ *   `undefined`: clock is always a concrete instant before any leaf dispatches
+ *   (`RandomSource`'s `Options.clock`).
  * - `path` — structural position within the construction: field name, tuple slot,
  *   choice option, one segment per nesting level (`Constructor.ts`'s `make`).
  *   Distinguishes two leaves of the same kind in one construction. Stable under
@@ -63,50 +52,55 @@ export type Algorithm = (seed: string) => NumberGenerator;
  *   identifies it.
  * - `kind` — schema kind the node was constructed as. Redundant given a unique
  *   `path`, but changing a field's kind must change its data.
- * - `ordinal` — which construction among those sharing this `file` this node
- *   belongs to. `undefined` for `"unattributed"`, already unique by its forked
- *   seed.
+ * - `ordinal` — which construction on this source this node belongs to: the next
+ *   value of the source's one counter, or a pinned value
+ *   (`ConstructorOptions.ordinal`), which is how a replay avoids advancing that
+ *   counter. `null` for a build that deliberately takes no ordinal — a
+ *   `combinatorial`/`coverage` rebuild. `null`, not absent: a pin counts when
+ *   it is defined, so only a defined "no ordinal" survives being replayed.
  */
 export type Trace = {
-    readonly seed: ReadonlyArray<string>;
+    readonly salt: ReadonlyArray<string>;
     readonly clock: number;
-    readonly root: RootKind;
-    readonly file: string | undefined;
     readonly path: ReadonlyArray<string>;
     readonly kind: string;
-    readonly ordinal: number | undefined;
+    readonly ordinal: number | null;
 };
 /**
  * Caller-supplied overrides for the construction-owned {@link Trace} slots
- * {@link RandomSource.toRoot} resolves. `seed` is not among them: it is the
- * {@link RandomSource}'s own identity (forked via {@link ConstructorOptions.seed}
- * when replaying), not something `toRoot` substitutes. `path`/`kind` are
- * per-node and applied in `construct()`, not here.
+ * {@link RandomSource.toRoot} resolves. `path`/`kind` are the only slots absent:
+ * they are per-node and applied in `construct()`, not here.
  *
- * Definedness, not `in`: `root` is present exactly when a trace is being
- * replayed and is never `undefined` on a real {@link Trace}.
+ * `salt` is a pin like the rest — it substitutes into that trace slot and does
+ * nothing else. It does not fork, so it neither resets nor sidesteps this
+ * source's construction counter: a salted build takes the next ordinal exactly
+ * as an unsalted one does. A caller who wants an isolated source, with its own
+ * counters, forks — that is what `fork`/`wrap` are for. Already normalized to
+ * parts here, since {@link Trace} carries the array form.
+ *
+ * Definedness, not `in`: a defined `ordinal` — a number, or `null` for "no
+ * ordinal" — is taken verbatim and does not advance the counter. That is all a
+ * replay needs, since every real {@link Trace} carries a defined ordinal.
  */
 export type RootPins = {
+    salt?: ReadonlyArray<string> | undefined;
     clock?: number | undefined;
-    root?: RootKind | undefined;
-    file?: string | undefined;
-    ordinal?: number | undefined;
+    ordinal?: number | null | undefined;
 };
 /**
- * A construction's root: every {@link Trace} slot a {@link RootKind} resolution
- * fixes, before a leaf supplies its own `path`/`kind`. `RandomSource.toRoot`
- * resolves this once per construction; callers spread it into a full
- * {@link Trace} per leaf and hand that to `toStreamFromTrace`. One stack walk,
- * one construction-ordinal bump — reused across every leaf that construction
- * dispatches.
+ * A construction's root: every {@link Trace} slot a construction fixes, before a
+ * leaf supplies its own `path`/`kind`. `RandomSource.toRoot` resolves this once
+ * per construction; callers spread it into a full {@link Trace} per leaf and
+ * hand that to `toStreamFromTrace`. One construction-ordinal bump is reused
+ * across every leaf that construction dispatches.
  */
 export type ConstructionTrace = Omit<Trace, "path" | "kind">;
 /**
  * What a producer is told about the fabrication it is running inside. One
  * object, not a positional list: this is the only channel a producer has, and a
  * future addition must not change every kind's `.as(...)` arity. Curated, not
- * the whole instance `Config` — a producer has no business reading `seed` or
- * `attribution`, and `random` already carries this leaf's own derived seed.
+ * the whole instance `Config` — a producer has no business reading `salt`, and
+ * `random` already carries this leaf's own derived seed.
  */
 export type ProduceContext = {
     /** This leaf's own seeded stream, keyed by its structural path. */
@@ -115,7 +109,7 @@ export type ProduceContext = {
      * This construction's resolved "now," epoch milliseconds — the active `wrap`
      * frame's `Config.clock` if one is active, else the instance's
      * (`Instance/Types.ts`'s `Config.clock`). Defaults to an instant derived from
-     * the instance's seed, not `Date.now()`, so a producer that reads it replays
+     * the instance's salt, not `Date.now()`, so a producer that reads it replays
      * like one that only reads `random`. A number, not a `Date`: the instant is
      * fixed once resolved, and a `Date` handed to every producer would be a
      * shared mutable — the same footgun `T.always([])` sharing one array
@@ -125,238 +119,124 @@ export type ProduceContext = {
 };
 /**
  * A kind's opaque custom producer — `.as(produce)` — given a
- * {@link ProduceContext} so its output replays under a seed like every other
+ * {@link ProduceContext} so its output replays under a salt like every other
  * primitive's draws. A zero-argument function (`() => $T`) is still assignable,
  * so every existing `.as(() => ...)` call compiles.
  */
 export type Produce<$T> = (context: ProduceContext) => $T;
 /**
- * How one _construction_ (a single `new Fabricator(...)` call) is rooted,
- * before any of its leaves are dispatched — resolved once, not per leaf, at
- * `Constructor.ts`'s `construct()`. Every leaf then derives its stream from
- * this root plus its own structural path, so inserting or reordering a sibling
- * field can never shift another field onto a different stream.
- *
- * Each variant is a decision about the two {@link Trace} slots a construction
- * owns — `file` and `ordinal` — and nothing else:
- *
- * | variant          | `file`                  | `ordinal`              |
- * | ---------------- | ----------------------- | ---------------------- |
- * | `"attributed"`   | resolved from the stack | next ordinal for it    |
- * | `"counted"`      | `undefined`             | next file-less ordinal |
- * | `"unattributed"` | `undefined`             | `undefined`            |
- *
- * `"attributed"` walks the live call stack once (`resolveCallerFile()`) and
- * relativizes it under the instance's `Attribution` root — or, under `{ kind:
- * "none" }`, resolves no file — then assigns the next ordinal for that file.
- * Two constructions in the same file diverge by default; a lone construction
- * stays reproducible across however many times its file is imported or re-run.
- * `ConstructorOptions.file` without `root` pins that file and draws the next
- * ordinal for it (the wrapping- integration case). A replay (`pins.root` given)
- * takes `file` and `ordinal` verbatim, including `undefined`.
- * `test/fixtures/checkout-a`/`checkout-b` stand in for two checkouts using real
- * frames instead.
- *
- * `"counted"` indexes without attributing. Under `{ kind: "none" }` an
- * `"attributed"` scope resolves to precisely this, and the two share the one
- * file-less bucket — reachable only if both kinds of scope were opened on a
- * single source, which nothing does. `"counted"` is not a variant you choose
- * when building — it is recorded on a node's {@link Trace} (and replayed) for
- * expansions inside `T.recursive`, whose private fork uses it so each lazy
- * expansion gets an ordinal (see `recursive/Fabricator.ts`). An identity that
- * isn't a stack frame but should still vary with the instance's seed is
- * `ConstructorOptions.seed`'s layered form (`{@link Layered}`, via
- * `layer(...)`) — see `ConstructorOptions`.
- *
- * `"unattributed"` fixes neither slot — used only by a source already isolated
- * for one construction (an explicitly seeded `new Fabricator(schema, { seed
- * })`, which forks a new `RandomSource` for that one build). A layered seed
- * (`{@link Layered}`, via `layer(...)`) still opens this same scope: composing
- * onto a base seed is a statement about _what_ the fork's seed is, not how the
- * fork itself should be rooted.
- *
- * A plain string union, not a discriminant object: none of the three variants
- * carries data of its own. Caller-supplied overrides go through
- * {@link RootPins} on {@link RandomSource.toRoot}, not through this union. A `{
- * kind: RootKind }` wrapper would invite a field an object shape can carry and
- * a switch can silently ignore.
- */
-export type RootKind = "attributed" | "counted" | "unattributed";
-/**
- * A seed as a caller supplies it: one string, or several — several lets a
+ * A salt as a caller supplies it: one string, or several — several lets a
  * caller compose independent parts (user id, session id, scenario label)
  * without joining them first. Always normalized internally to
- * `ReadonlyArray<string>` (`toRandomSource`'s `normalizeSeed`); a single string
+ * `ReadonlyArray<string>` (`toRandomSource`'s `normalizeSalt`); a single string
  * is the one-element case.
  */
-export type Seed = string | ReadonlyArray<string>;
+export type Salt = string | ReadonlyArray<string>;
 /**
- * A {@link Seed} tagged as composing onto whatever base is in effect, rather
- * than replacing it — what `layer(seed)` (`Random/index.ts`) produces. Tagged
+ * A {@link Salt} tagged as composing onto whatever base is in effect, rather
+ * than replacing it — what `layer(salt)` (`Random/index.ts`) produces. Tagged
  * with `[Layer]` exactly as `replace()` (`Utility/Core.ts`) tags a merge
  * operand with `[Replace]`, so a caller never names the symbol and no ordinary
- * `Seed` — string or array — can be mistaken for one.
+ * `Salt` — string or array — can be mistaken for one.
  */
 export type Layered = {
-    readonly [Layer]: Seed;
+    readonly [Layer]: Salt;
 };
 /**
- * How an instance normalizes a construction's resolved file before it becomes
- * part of that construction's root — set once via `initialize({ attribution
- * })`.
- *
- * `"rooted"` expresses every file relative to `root`, so a checkout at a
- * different absolute path on a different machine derives the same seeds. `root`
- * accepts an absolute path or a `file://` URL (e.g. `new URL("..",
- * import.meta.url).href`, which needs no `node:path`), and is a normalization
- * parameter only — it never enters the hashed material, so moving the root
- * without moving the files under it changes nothing. A file outside `root` is
- * expressed with a leading `..` run rather than left absolute, so it stays
- * stable too, as long as both locations move together under the same checkout
- * (see `relativize`, `Random/CallSite.ts`).
- *
- * `"call site"`, the default, is `"rooted"` at the directory of whichever file
- * called `initialize()` — resolved once, at that call, from the live stack. Two
- * `initialize()` calls in different files that share a seed and happen to
- * produce the same file's-worth of relative paths (a symmetric monorepo layout
- * — this repo's `pkg/fabricator` and `pkg/fabricator-adapter-typebox-v0` test
- * suites) will collide; use `"rooted"` at a shared repository root instead.
- *
- * `"none"` attributes nothing: every construction in the instance draws its
- * root from one shared, file-less counter. Maximally portable — no path can
- * influence a seed — at the cost of every construction sharing one counter, so
- * adding, removing, or reordering a _construction_ anywhere in the instance
- * shifts every later one. Individual fields within one construction are
- * unaffected: they're keyed by structural path, not dispatch order.
- */
-export type Attribution = {
-    kind: "rooted";
-    root: string;
-} | {
-    kind: "call site";
-} | {
-    kind: "none";
-};
-/**
- * {@link Attribution} after `"call site"` has been resolved against the live
- * stack and `root` normalized — what actually drives construction-root
- * resolution. This, not the caller-facing `Attribution`, is what
- * `RandomSource.fork` threads through: re-resolving `"call site"` inside a fork
- * would read the stack at whatever moment the fork happens to run (an
- * explicitly seeded build, an enumeration's rebuild) and root the child
- * somewhere unrelated to the instance that spawned it.
- */
-export type ResolvedAttribution = {
-    kind: "rooted";
-    root: string;
-} | {
-    kind: "none";
-};
-/**
- * `clock` is required, unlike `seed`/`algorithm`/`attribution` — by the time a
- * `RandomSource` is built, both the wall-clock default and the `"seeded"`
- * policy (`Instance/Types.ts`'s `Config.clock`) have already been resolved to a
+ * `clock` is required, unlike `salt`/`algorithm` — by the time a `RandomSource`
+ * is built, both the wall-clock default and the `"derived"` policy
+ * (`Instance/Types.ts`'s `Config.clock`) have already been resolved to a
  * concrete epoch-millisecond instant (`Instance/Core.ts`'s `resolveClock`), so
  * `toRandomSource` has no default left to supply.
  */
 export type Options = {
-    seed?: Seed | undefined;
+    salt?: Salt | undefined;
     algorithm?: Algorithm | undefined;
-    attribution?: Attribution | undefined;
     clock: number;
 };
 /**
  * `new Fabricator(schema, options)`'s own option shape — not `Options`.
  * {@link Trace} is assignable to this (every slot optional here, required
- * there, and `file`/`ordinal` are `T | undefined` on both so `{ ...trace }`
- * typechecks under `exactOptionalPropertyTypes`), which is what makes `new
- * Fabricator(schema, trace)` a legal replay.
- *
- * A bare `seed` is a statement about _attribution_: it forks an isolated
- * `RandomSource` from exactly that value, sidestepping both the default
- * call-site logic and the instance's own seed. The same seed reproduces the
- * same result regardless of which file it's constructed from, which instance
- * built it, or how that instance was itself seeded — useful for a fixture that
- * should never change no matter how the surrounding run is reseeded.
- *
- * `seed: layer(...)` (via `layer()`, `Random/index.ts`) is the same fork, but
- * composed onto the instance's own seed (`[...instance.seed, ...seed]`) instead
- * of replacing it — the construction still varies when the instance is
- * reseeded, which the bare form does not (see {@link RootKind}'s `"counted"`
- * paragraph). This is `fork`/`wrap`'s own `Overlay.seed` mechanism one level
- * down: the instance itself is the base, so no separate instance is needed just
- * to pin an identity that should still track the instance's seed.
- *
- * `clock` / `root` / `file` / `ordinal` pin the construction-owned
- * {@link Trace} slots {@link RandomSource.toRoot} would otherwise resolve.
- * Definedness, not `in`: `root` given means this is a replay (`file` and
- * `ordinal` taken verbatim, `undefined` included, no stack walk and no counter
- * bump). `root` absent but `file` given pins that file and draws `ordinal` from
- * _that file's_ counter — the wrapping-integration case. Neither given resolves
- * as an ordinary construction. A seeded construction is not, by default, asking
- * for a different "now"; a replayed trace whose `clock` is present explicitly
- * is.
+ * there), which is what makes `new Fabricator(schema, trace)` a legal replay.
+ *
+ * Every field here pins one {@link Trace} slot, `salt` included — it is not a
+ * special case, and it does not fork. A bare `salt` replaces the instance's own
+ * for this build; `salt: layer(...)` (via `layer()`, `Random/index.ts`)
+ * composes onto whichever base is in effect (`[...instance.salt, ...salt]`), so
+ * the construction still varies when the instance is re-salted, which the bare
+ * form does not. That is `fork`/`wrap`'s own `Overlay.salt` parity, one level
+ * down.
+ *
+ * Pinning a salt says nothing about anything else. The build takes the next
+ * ordinal on its source and inherits the instance's clock, exactly as an
+ * unsalted build does — so it shifts, and is shifted by, neighbouring
+ * constructions like any other. Two same-salt builds therefore diverge.
+ *
+ * `clock` / `ordinal` pin the construction-owned {@link Trace} slots
+ * {@link RandomSource.toRoot} would otherwise resolve. Definedness, not `in`: a
+ * given `ordinal` — a number, or `null` for "no ordinal" — is taken verbatim
+ * with no counter bump, which is all a replay needs; without it, the
+ * construction takes the source counter's next value. A salted construction is
+ * not, by default, asking for a different "now"; a replayed trace whose `clock`
+ * is present explicitly is.
  *
  * `path` is the base structural path `make` extends for descendants, so
  * replaying a nested node's trace reproduces its subtree at the positions it
  * originally occupied. `kind`, when a string, must match `schema`'s own
  * `[Kind]` or `construct()` throws `TraceKindMismatchError`.
  *
- * No per-build algorithm override: it complicates root resolution for a
- * capability nobody asked for, unlike `seed`, which is a real statement about
- * attribution. Only `initialize({ seed, algorithm })` — instance-wide, via
- * `Options` — sets the algorithm.
+ * No per-build algorithm override: unlike `salt`, the algorithm is not a trace
+ * slot. Only `initialize({ salt, algorithm })` — instance-wide, via `Options` —
+ * sets it.
  */
 export type ConstructorOptions = {
-    seed?: Seed | Layered | undefined;
+    salt?: Salt | Layered | undefined;
     clock?: number | undefined;
-    root?: RootKind | undefined;
-    file?: string | undefined;
     path?: ReadonlyArray<string> | undefined;
     kind?: string | undefined;
-    ordinal?: number | undefined;
+    ordinal?: number | null | undefined;
 };
 /**
  * An isolated source of randomness: everything a single `initialize()` instance
  * needs to derive private, reproducible seeds for the fabricators it builds.
- * Each instance owns its own seed, builder, and per-construction counters —
+ * Each instance owns its own salt, builder, and per-construction counters —
  * nothing here is shared module-level state, so independently initialized
  * instances (e.g. parallel tests) can never perturb each other.
  */
 export type RandomSource = {
     /**
-     * Resolve one construction's root — see {@link RootKind}. Called once per `new
-     * Fabricator(...)` (or per lazy expansion of a `T.recursive` schema, each of
-     * which resolves its own root on a private forked source), never per leaf:
-     * the returned {@link ConstructionTrace} is what every leaf beneath it
+     * Resolve one construction's root: this source's own `salt`/`clock` and the
+     * next construction ordinal, each overridable by {@link RootPins}. Called once
+     * per `new Fabricator(...)` (or per lazy expansion of a `T.recursive` schema,
+     * each of which resolves its own root on a private forked source), never per
+     * leaf: the returned {@link ConstructionTrace} is what every leaf beneath it
      * completes into a full {@link Trace} and hands to `toStreamFromTrace`. One
-     * stack walk and construction-ordinal bump serves the whole construction.
+     * construction-ordinal bump serves the whole construction.
      */
-    toRoot(kind: RootKind, pins?: RootPins): ConstructionTrace;
+    toRoot(pins?: RootPins): ConstructionTrace;
     /**
      * The algorithm this source (and every fork of it) hashes with. Stream
      * derivation is _not_ a member: it depends on no per-source state, so it is
      * the free function `toStreamFromTrace(algorithm, trace)`. `toRoot` is the
-     * only stateful member (per-file ordinal counters).
+     * only stateful member (the construction counter).
      */
     readonly algorithm: Algorithm;
     /**
-     * The seed this instance currently derives every stream from, normalized to
+     * The salt this instance currently derives every stream from, normalized to
      * its parts — a single string becomes a one-element array. Always an array so
-     * a caller reading it back (e.g. `initialize({ seed: instance.seed })`)
-     * round-trips through the same `Seed`-accepting surface it came from.
+     * a caller reading it back (e.g. `initialize({ salt: instance.salt })`)
+     * round-trips through the same `Salt`-accepting surface it came from.
      */
-    readonly seed: ReadonlyArray<string>;
+    readonly salt: ReadonlyArray<string>;
     /**
-     * Create a new, fully isolated `RandomSource` — its own private per-file
-     * construction counters, sharing only the algorithm — seeded independently
-     * from this one. For a build whose randomness must stay entirely
-     * self-contained (an explicitly seeded `new Fabricator(schema, { seed })`, or
-     * `T.recursive`, whose expansion count is data-dependent, unlike every other
-     * kind's fixed, schema-determined dispatch count): forking means its internal
-     * draws can never perturb, or be perturbed by, anything else built from the
-     * same `initialize()` instance, no matter how many times or how deeply it
-     * expands.
+     * Create a new, fully isolated `RandomSource` — its own private construction
+     * counters, sharing only the algorithm — salted independently from this one.
+     * For a build whose randomness must stay entirely self-contained
+     * (`T.recursive`, whose expansion count is data-dependent, unlike every other
+     * kind's fixed, schema-determined dispatch count; and `coverage`'s
+     * permutation stream): forking means its internal draws can never perturb, or
+     * be perturbed by, anything else built from the same `initialize()` instance,
+     * no matter how many times or how deeply it expands.
      */
-    fork(seed: Seed): RandomSource;
+    fork(salt: Salt): RandomSource;
 };

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

@@ -1,79 +1,61 @@
-import type { Algorithm, Attribution, Layered, NumberGenerator, Options, RandomSource, ResolvedAttribution, Seed, Stream, Trace } from "./Types";
+import type { Algorithm, Layered, NumberGenerator, Options, RandomSource, Salt, Stream, Trace } from "./Types";
 /**
- * Build the library's built-in PRNG from a seed. The same seed always yields
- * the same stream. Seeds may be numbers or strings; both are stringified and
- * hashed to fully seed sfc32's state.
+ * Build the library's built-in PRNG from a seed — the genuine article, not a
+ * caller-supplied {@link Salt}: by the time anything reaches here the salt is
+ * one slot of an `encode`d {@link Trace}, and this string is that whole
+ * encoding. The same seed always yields the same stream, and `cyrb128` hashes
+ * it to fully seed sfc32's 128 bits of state.
  */
 export declare function defaultAlgorithm(seed: string): NumberGenerator;
 /**
- * Mint a fresh seed value — a uint32 label. Not used as `initialize()`'s
- * default (an omitted seed is empty; wall-clock `clock` is the default
+ * Mint a fresh salt value — a uint32 label. Not used as `initialize()`'s
+ * default (an omitted salt is empty; wall-clock `clock` is the default
  * entropy); kept for callers that want a generated mixer, and for tests that
  * need one.
  */
-export declare function randomSeed(): string;
+export declare function randomSalt(): string;
 /**
- * Derive the explicit `"seeded"` clock — an epoch-millisecond instant, drawn
+ * Derive the explicit `"derived"` clock — an epoch-millisecond instant, drawn
  * across the full representable `Date` span — from an instance's own
- * `algorithm`/`seed`. The unconfigured default is wall-clock time
- * (`Instance/Core.ts`'s `overlay`); this is the opt-in that makes `seed` alone
+ * `algorithm`/`salt`. The unconfigured default is wall-clock time
+ * (`Instance/Core.ts`'s `overlay`); this is the opt-in that makes `salt` alone
  * the reproducibility unit, at the cost of an implausible "now". A throwaway
- * two-element encoding (`JSON.stringify([seed, "clock"])`), _not_ routed
+ * two-element encoding (`JSON.stringify([salt, "clock"])`), _not_ routed
  * through `RandomSource`/`Trace`: after the clock is folded into stream
  * derivation, a forked source's own stream derivation requires a clock, so
  * deriving the clock from a fork would be circular. Kept below that layer,
  * which also keeps this collision-free with every leaf's `encode(trace)` — that
- * encoding is always seven elements, this is always two, and the two can never
+ * encoding is always five elements, this is always two, and the two can never
  * produce the same JSON array. `Math.trunc`ed because a `Date`'s precision is
  * whole milliseconds.
  */
-export declare function deriveClock(algorithm: Algorithm, seed: ReadonlyArray<string>): number;
+export declare function deriveClock(algorithm: Algorithm, salt: ReadonlyArray<string>): number;
 /**
  * Collapse a {@link Trace} into one string to hash — and, since
  * `toStreamFromTrace` hashes exactly this output, the _definition_ of that
  * leaf's stream seed. Concatenating fields with a delimiter would collide when
- * a path/kind/seed part contains that delimiter (`file="a b", kind="c"` vs
- * `file="a", kind="b c"`) — silently: two leaves that should draw independently
- * would share one stream. `JSON.stringify` as an array makes every field's and
- * slot's boundaries unambiguous regardless of content or nesting depth.
- * `undefined` (`file`, `ordinal`) is the right "this slot doesn't apply" rather
- * than a sentinel string: `JSON.stringify` writes it as `null` in an array
- * position, one unambiguous value, with no chance of colliding with a real file
- * path or index.
+ * a path/kind/salt part contains that delimiter — silently: two leaves that
+ * should draw independently would share one stream. `JSON.stringify` as an
+ * array makes every field's and slot's boundaries unambiguous regardless of
+ * content or nesting depth.
  */
 export declare function encode(trace: Trace): string;
 /**
- * Normalize a caller-supplied {@link Seed} to its parts: a single string becomes
- * a one-element array, an array passes through unchanged, and a missing seed is
- * empty — unless {@link envSeed} supplies one. No generated fallback: an omitted
- * seed is not a second source of entropy beside the instance clock.
+ * Normalize a caller-supplied {@link Salt} to its parts: a single string becomes
+ * a one-element array, an array passes through unchanged, and a missing salt is
+ * empty — unless {@link envSalt} supplies one. No generated fallback: an omitted
+ * salt is not a second source of entropy beside the instance clock.
  */
-export declare function normalizeSeed(seed: Seed | undefined): ReadonlyArray<string>;
+export declare function normalizeSalt(salt: Salt | undefined): ReadonlyArray<string>;
 /**
- * Tag a seed as composing onto whatever base is in effect, rather than
- * replacing it — the reading a bare `seed` has everywhere else in this library.
+ * Tag a salt as composing onto whatever base is in effect, rather than
+ * replacing it — the reading a bare `salt` has everywhere else in this library.
  * Mirrors `replace()`'s `[Replace]` tagging: the `[Layer]` directive is read
- * (and, at every level that accepts one, consumed) by whoever resolves the seed
+ * (and, at every level that accepts one, consumed) by whoever resolves the salt
  * against its base, so a caller never names the symbol.
  */
-export declare function layer(seed: Seed): Layered;
+export declare function layer(salt: Salt): Layered;
 export declare function isLayered(value: unknown): value is Layered;
-/**
- * Collapse a caller-facing {@link Attribution} to the
- * {@link ResolvedAttribution} the stream machinery uses. `"call site"` must
- * resolve _here_, and only here: `resolveCallerFile()` reads the live stack,
- * and `toRandomSource` runs synchronously inside `initialize()`, so this is the
- * one moment the first external frame genuinely is the file that called
- * `initialize()`. Resolving lazily — on first construction, or again inside
- * `fork` — would capture whichever file happened to call `new Fabricator(...)`,
- * or whichever internal mechanism happened to trigger a fork.
- *
- * A directory, not the file itself, becomes the root: rooting at the file would
- * relativize that one file to `""` while every sibling still carried a full
- * relative path from a directory one level up, an arbitrary asymmetry with no
- * reason to prefer it.
- */
-export declare function resolveAttribution(attribution: Attribution | undefined): ResolvedAttribution;
 export declare function toStream(algorithm: Algorithm, seed: string): Stream;
 /**
  * A leaf's stream: `toStream(algorithm, encode(trace))`. This is the
@@ -86,13 +68,13 @@ export declare function toStream(algorithm: Algorithm, seed: string): Stream;
  * {@link deriveClock} cannot route through this: a {@link Trace} carries
  * `clock`, and `deriveClock` is what produces it. That circularity is why
  * `deriveClock` stays below the `RandomSource`/`Trace` layer, with a
- * two-element encoding that can never collide with `encode`'s seven.
+ * two-element encoding that can never collide with `encode`'s five.
  */
 export declare function toStreamFromTrace(algorithm: Algorithm, trace: Trace): Stream;
 /**
  * Create a fresh, self-contained {@link RandomSource} — the randomness state a
  * single `initialize()` instance owns for its lifetime. `options.clock` is
- * baked in here, once, as a plain number — the `"seeded"` policy is already
+ * baked in here, once, as a plain number — the `"derived"` policy is already
  * resolved by the caller (`Instance/Core.ts`'s `resolveClock`) before a source
  * is ever built, so every root this source resolves carries the identical
  * instant, and `fork` threads it forward unchanged.

package/dist/types/Types.d.ts

@@ -6,11 +6,11 @@ export declare const Produces: unique symbol;
 export declare const Replace: unique symbol;
 export declare const Fixed: unique symbol;
 /**
- * Tags a `Seed` as composing onto whatever base is in effect, rather than
- * replacing it — the reading a bare `seed` has everywhere else in this library.
+ * Tags a `Salt` as composing onto whatever base is in effect, rather than
+ * replacing it — the reading a bare `salt` has everywhere else in this library.
  * `layer()` (`Random/index.ts`) is the only producer; a caller never names this
  * symbol, mirroring `[Replace]`. Unlike every other symbol in this file, it
- * tags a config value (a `Seed`), not a Schema or Fabricator — see
+ * tags a config value (a `Salt`), not a Schema or Fabricator — see
  * `Random/Types.ts`'s `Layered`.
  */
 export declare const Layer: unique symbol;

package/dist/types/adapting.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The `@ghostry/fabricator/adapting` package export — what implementing a
+ * schema adapter (e.g. `@ghostry/fabricator-adapter-typebox-v0`) is built from.
+ * Named for the activity, not the noun (`Adapter` is one export among several
+ * here) — the same pattern `@ghostry/fabricator/harnessing` follows for
+ * supplying a test-framework integration.
+ *
+ * Deliberately separate from the `.` export: `.` is for using fabricator,
+ * `./internal` is the structural-walking tools an adapter needs (`Kind`,
+ * `Meta`, `Primitive`, `Buildable`), and this is the contract an adapter
+ * declares and drives. `Adapting` — the parameter type of every kind's
+ * `.adapt(adapter, produce)` producer — stays on `.` instead, despite the name
+ * overlap with this module: calling `.adapt()` is an ordinary caller's
+ * business, not an adapter author's, the same reason `Stream`/`ProduceContext`
+ * live there for `.as(produce)`.
+ *
+ * This package names no external schema library and depends on none: every
+ * mapping, and every dependency it needs, belongs to the adapter.
+ *
+ * @module
+ */
+export { walk } from "./Adapter/Core";
+/**
+ * `Adapter`/`Recurse` are what an adapter declares; `AdaptationsOf` is how it
+ * reads what a Schema declared at the type level, keyed by its own `key`.
+ */
+export type { Adaptations, AdaptationsOf, Adapter, Recurse, } from "./Adapter/Types";
+/**
+ * What `[Adaptation]` holds at runtime — a per-adapter map of overrides, read
+ * only by an adapter.
+ */
+export { Adaptation } from "./Types";

package/dist/types/harnessing.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `@ghostry/fabricator/harnessing` package export — what supplying a
+ * `@ghostry/harness` integration is built from. Named for the activity, the
+ * same pattern `@ghostry/fabricator/adapting` follows.
+ *
+ * Deliberately separate from the `.` export: `.` is for using fabricator,
+ * `./adapting` is implementing a schema adapter, `./internal` is the
+ * structural-walking tools an adapter needs, and this is the contract a
+ * test-framework wrapping library drives. Fabricator declares no dependency and
+ * no peer on `@ghostry/harness`; the types here describe the part of that
+ * package's contract this integration uses, satisfied structurally, so neither
+ * depends on the other.
+ *
+ * @module
+ */
+/**
+ * Decorate an existing `Instance` as a `@ghostry/harness` integration — `{
+ * name, provides, around }`. Takes an instance rather than minting one: the
+ * caller owns `initialize(...)` (and in particular the suite-wide `clock`), and
+ * this only wraps each test body in that instance's per-identity `wrap`.
+ */
+export { integration } from "./Harnessing/Core";
+/**
+ * `Identity` is what identifies one registered test or suite; `Integration` is
+ * the `{ name, provides, around }` shape `integration(instance)` returns —
+ * `provides` is a `Provides<$Context>`, one `Provider` per context key;
+ * `FabricatorTestContext` is the `{ fabricator }` slice of the test context
+ * this integration contributes.
+ */
+export type { FabricatorTestContext, Identity, Integration, Provider, Provides, } from "./Harnessing/Types";