@ghostry/fabricator 0.0.2 → 0.0.4

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

@@ -1,6 +1,6 @@
 import type { RandomSource } from "../Random/Types";
 import type { PlainObject } from "../Utility/Types";
-import type { Config, Instance, Overlay, Stack } from "./Types";
+import type { Ancestry, Config, Instance, Overlay, Stack } from "./Types";
 /**
  * `combinatorial`'s default limit — `2**10`, so it admits ten independent
  * binary axes before requiring the caller to raise it explicitly. Each
@@ -11,36 +11,19 @@ export declare const DEFAULT_COMBINATORIAL_LIMIT = 1024;
 /**
  * The single place a `Config` inherits from a base — `initialize` lays its own
  * config over an empty `{}` base (nothing to inherit, so every field falls
- * through to a hardcoded default: an empty seed, wall-clock `clock`, the
- * built-in algorithm, `resolveAttribution(undefined)`'s `"call site"`
- * resolution, the default registry, the default combinatorial limit), and
- * `fork` lays its overlay over the instance it was called on (a full,
+ * through to a hardcoded default: an empty salt, wall-clock `clock`, the
+ * built-in algorithm, the default registry, the default combinatorial limit),
+ * and `fork` lays its overlay over the instance it was called on (a full,
  * already-resolved `Config`, so every field has a real value to fall back to).
  * `base` is typed `Partial<Config<PlainObject>>` rather than `Config`
  * specifically so both calls go through the same function.
  *
- * `seed` composes onto the base rather than replacing it only when tagged with
- * `layer(...)` (`{@link isLayered}`) — a bare `seed` (the ordinary meaning
+ * `salt` composes onto the base rather than replacing it only when tagged with
+ * `layer(...)` (`{@link isLayered}`) — a bare `salt` (the ordinary meaning
  * everywhere else in this library) replaces the base's outright, and an omitted
- * `seed` inherits the base's unchanged (or, at the root, an empty mixer via
- * `normalizeSeed(undefined)`, unless an env var supplies one). Wall-clock
- * `clock` is the default entropy; `seed` is an optional mixer.
- *
- * `attribution` resolves through `resolveAttribution` at most once per call,
- * and only when it's actually needed:
- *
- * - an explicit `over.attribution` always wins (resolved fresh, so `fork({
- *   attribution: { kind: "call site" } })` roots at _that_ call);
- * - otherwise an already-resolved `base.attribution` is reused as-is — never
- *   re-resolved, which keeps a fork from silently re-rooting `"call site"` at
- *   wherever `fork()` itself happens to be called (`resolveCallerFile()` skips
- *   this library's own frames, so calling it from here still lands on the
- *   user's call site either way);
- * - only when neither is available (the root case, `base.attribution` absent)
- *   does this fall back to resolving the `"call site"` default. That also keeps
- *   `initialize({ attribution: { kind: "none" } })` — or any other explicit
- *   override — from paying for a stack walk whose result would be immediately
- *   discarded.
+ * `salt` inherits the base's unchanged (or, at the root, an empty mixer via
+ * `normalizeSalt(undefined)`, unless an env var supplies one). Wall-clock
+ * `clock` is the default entropy; `salt` is an optional mixer.
  *
  * `algorithm`/`types`: wholesale replacement when given, matching how
  * `initialize({ types })` already behaves — no deep merge;
@@ -49,13 +32,13 @@ export declare const DEFAULT_COMBINATORIAL_LIMIT = 1024;
  * inherited, or defaulted), so a bad limit fails at `fork()`/`initialize()`
  * time rather than at first use. `clock` follows the given → inherited →
  * default shape `algorithm` does, but stays _unresolved_ only for the explicit
- * `"seeded"` sentinel: an explicit `Date` and the unconfigured wall-clock
+ * `"derived"` sentinel: an explicit `Date` and the unconfigured wall-clock
  * default are stored as epoch milliseconds (a stated instant, inherited as-is
- * from then on), while `"seeded"` is left as the sentinel rather than collapsed
- * to a number, so `resolveClock` can re-derive it from whichever `seed` is
- * actually in effect at read time. An omitted `clock` on a `fork`/`wrap` whose
- * seed changed therefore keeps the parent's instant unless that parent was
- * itself `"seeded"`.
+ * from then on), while `"derived"` is left as the sentinel rather than
+ * collapsed to a number, so `resolveClock` can re-derive it from whichever
+ * `salt` is actually in effect at read time. An omitted `clock` on a
+ * `fork`/`wrap` whose salt changed therefore keeps the parent's instant unless
+ * that parent was itself `"derived"`.
  */
 export declare function overlay<$Registry extends PlainObject>(base: Partial<Config<PlainObject>>, over: Overlay<$Registry>): Config<$Registry>;
 /**
@@ -68,12 +51,23 @@ export declare function overlay<$Registry extends PlainObject>(base: Partial<Con
  * than each independently re-deriving one from the same config (and so silently
  * diverging/duplicating construction ordinals).
  *
- * `stack` is threaded straight through to `Constructor`/`enumerables` — this
- * function never reads or writes it itself, only passes it along so every built
- * `Fabricator`/`combinatorial`/`coverage` can consult whichever frame is active
- * _at the moment each is called_, not at this moment.
+ * `stack` and `ancestry` are threaded straight through to
+ * `Constructor`/`enumerables` — this function never reads the stack itself,
+ * only passes both along so every built `Fabricator`/`combinatorial`/`coverage`
+ * can consult whichever frame is visible to _this_ instance _at the moment each
+ * is called_, not at this moment.
+ *
+ * `parent` describes the instance this one is derived from, and its absence is
+ * the single marker of a root: `initialize` passes none, every `fork`/`wrap`
+ * passes the receiver's.
+ *
+ * A fresh token is minted either way, so no two instances share an identity,
+ * and the `ancestry` built here is _this_ instance's: the parent's plus one.
  */
-export declare function instantiate<$Registry extends PlainObject>(config: Config<$Registry>, stack: Stack): {
+export declare function instantiate<$Registry extends PlainObject>(config: Config<$Registry>, stack: Stack, parent?: {
+    ancestry: Ancestry;
+    root: Instance<PlainObject>;
+}): {
     instance: Instance<$Registry>;
     source: RandomSource;
 };

package/dist/types/Instance/Stack/Async.d.ts

@@ -7,6 +7,13 @@ import type { Stack } from "../Types";
  * package importable on a runtime with no `node:async_hooks` while every
  * runtime that has one gets async-safe `wrap` with nothing to configure.
  *
+ * The store holds the whole open chain, not one `Frame`: `run` _replaces_ the
+ * store for the duration of `block`, so `enter` rebuilds the chain with the new
+ * frame appended. A fresh array per `enter` is also what isolates concurrent
+ * `wrap`s — each async context keeps the chain it entered with, and an inner
+ * `enter` cannot mutate an outer one's view. Chains are at nesting depth, so
+ * copying one costs nothing worth avoiding.
+ *
  * `AsyncLocalStorage.run` returns whatever `block` returns, so this satisfies
  * `enter`'s sync-preserving `<$Return>` signature exactly as the sync carrier
  * does — a synchronous `wrap` is unaffected by which carrier is in play.

package/dist/types/Instance/Stack/Sync.d.ts

@@ -1,13 +1,15 @@
 import type { Stack } from "../Types";
 /**
  * The synchronous carrier: a private `Frame[]`, pushed on `enter` and popped in
- * a `finally` — correct even around a `throw` from `block`.
+ * a `finally` — correct even around a `throw` from `block`. Already in
+ * outermost-first order, which is the order `visible` reports, so it hands the
+ * array straight to `toVisible` and does no filtering of its own.
  *
  * Selected by the `#stack` `default` condition (`package.json`), i.e. on any
  * runtime without `node:async_hooks` — in practice a browser bundle. Its frame
  * cannot survive an `await`: `enter` returns `block()` without awaiting, so an
- * async block's frame unwinds at the block's first suspension point, and a
- * shared LIFO could not represent two overlapping scopes even if it did await.
+ * async block's frame unwinds at the block's first suspension point, and one
+ * shared array could not represent two overlapping scopes even if it did await.
  * Both are why `asynchronous` is `false` and `wrap` refuses an async block here
  * rather than resolving it against the base instance with no signal.
  */

package/dist/types/Instance/Stack/Visible.d.ts

@@ -0,0 +1,22 @@
+import type { Ancestry, Frame, Stack } from "../Types";
+/**
+ * The frames in `frames` that `ancestry` may resolve against, outermost first —
+ * the single definition of {@link Stack.visible}'s rule, which both carriers
+ * delegate to so neither can drift from the other. A carrier's own job is
+ * reduced to holding the chain in whatever way its runtime allows.
+ *
+ * Order is preserved rather than reduced to the innermost match, because the
+ * count is `context.depth` and the innermost is just the last element.
+ * Skipping, rather than stopping at, the first invisible frame is the outward
+ * walk: with a parent's `wrap` open and a child's nested inside it, that
+ * child's sibling must pass over the inner frame and still resolve against the
+ * outer one.
+ */
+export declare function toVisible(frames: ReadonlyArray<Frame>, ancestry: Ancestry): ReadonlyArray<Frame>;
+/**
+ * The one frame a read resolves against: the innermost frame visible to
+ * `ancestry`, or `undefined` outside any. Every consumer — `resolveScope`,
+ * `effectiveSource`, the `context` getters — goes through here rather than
+ * indexing `visible()` itself, so "innermost visible" has one definition.
+ */
+export declare function toInnermostFrame(stack: Stack, ancestry: Ancestry): Frame | undefined;

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

@@ -1,78 +1,123 @@
 import type { Enumerable, Limits } from "../Enumeration/Types";
 import type { Constructor } from "../Fabricator/Constructor";
-import type { Algorithm, Attribution, Layered, RandomSource, Seed } from "../Random/Types";
+import type { Algorithm, Layered, RandomSource, Salt } from "../Random/Types";
 import type { PlainObject } from "../Utility/Types";
 /**
  * A fully resolved instance configuration — every field present, nothing left
  * to default. `Overlay` is what `fork` accepts; `overlay()`
  * (`Instance/Core.ts`) is the only thing producing a complete `Config`.
  *
- * Two fields are declared at their caller-facing type but always hold their
- * resolved form once `overlay()` has run: `seed` is `Seed` because that is what
- * a caller may supply, but always holds the normalized array (`Instance.seed`
- * is the authoritative read); `attribution` is `Attribution` for the same
- * reason but always holds a `ResolvedAttribution`, a subtype. `clock` is
- * different from both: unlike `seed`/`attribution`, it holds _either_ a
- * resolved instant (epoch milliseconds) or the unresolved `"seeded"` policy —
- * never collapsed to a number by `overlay()` when `"seeded"`, because that
- * policy must re-derive whenever the seed it composes changes (a `fork({ seed:
- * layer(...) })`). The unconfigured default is a wall- clock number, inherited
- * as-is like an explicit `Date`. `resolveClock` (`Instance/Core.ts`) is the one
- * place that resolves `"seeded"` to a number, called fresh wherever the clock
- * actually matters (`instantiate`, the `context.clock` getter) rather than once
- * here.
+ * `salt` is declared at its caller-facing `Salt` type but always holds the
+ * normalized array once `overlay()` has run (`Instance.salt` is the
+ * authoritative read). `clock` holds _either_ a resolved instant (epoch
+ * milliseconds) or the unresolved `"derived"` policy — never collapsed to a
+ * number by `overlay()` when `"derived"`, because that policy must re-derive
+ * whenever the salt it composes changes (a `fork({ salt: layer(...) })`). The
+ * unconfigured default is a wall- clock number, inherited as-is like an
+ * explicit `Date`. `resolveClock` (`Instance/Core.ts`) is the one place that
+ * resolves `"derived"` to a number, called fresh wherever the clock actually
+ * matters (`instantiate`, the `context.clock` getter) rather than once here.
  */
 export type Config<$Registry extends PlainObject> = {
-    readonly seed: Seed;
+    readonly salt: Salt;
     readonly algorithm: Algorithm;
-    readonly attribution: Attribution;
     readonly types: $Registry;
     readonly limits: Limits;
-    readonly clock: number | "seeded";
+    readonly clock: number | "derived";
 };
 /**
  * What `fork` accepts — a `Config` to lay over a base, every field optional.
- * Identical to `Partial<Config>` but for `seed`, which additionally accepts a
- * {@link Layered}: a bare `Seed` replaces the base's seed outright (what `seed`
- * means everywhere else in this library), `layer(seed)` appends onto it
- * (`[...base.seed, ...seed]`) — the shape a wrapping integration wants, and
+ * Identical to `Partial<Config>` but for `salt`, which additionally accepts a
+ * {@link Layered}: a bare `Salt` replaces the base's salt outright (what `salt`
+ * means everywhere else in this library), `layer(salt)` appends onto it
+ * (`[...base.salt, ...salt]`) — the shape a wrapping integration wants, and
  * what `ConstructorOptions`' layered form is for a single construction.
- * Omitting `seed` inherits the base's unchanged. `clock` similarly accepts the
- * caller-facing `Date | "seeded"` rather than `Config`'s own resolved `number |
- * "seeded"`, so a caller can hand in a literal instant without converting it to
- * epoch milliseconds themselves. `"seeded"` is the explicit opt-in that derives
- * "now" from the instance seed; omitting `clock` at the root captures
+ * Omitting `salt` inherits the base's unchanged. `clock` similarly accepts the
+ * caller-facing `Date | "derived"` rather than `Config`'s own resolved `number
+ * | "derived"`, so a caller can hand in a literal instant without converting it
+ * to epoch milliseconds themselves. `"derived"` is the explicit opt-in that
+ * derives "now" from the instance salt; omitting `clock` at the root captures
  * wall-clock time instead.
  *
- * `initialize`'s own parameter keeps a plain `seed?: Seed`, so passing
+ * `initialize`'s own parameter keeps a plain `salt?: Salt`, so passing
  * `layer(...)` there is a compile error: there is no base to layer onto at the
  * root.
  */
-export type Overlay<$Registry extends PlainObject> = Partial<Omit<Config<$Registry>, "seed" | "clock">> & {
-    readonly seed?: Seed | Layered;
-    readonly clock?: Date | "seeded" | undefined;
+export type Overlay<$Registry extends PlainObject> = Partial<Omit<Config<$Registry>, "salt" | "clock">> & {
+    readonly salt?: Salt | Layered;
+    readonly clock?: Date | "derived" | undefined;
 };
+declare const Brand: unique symbol;
+/**
+ * One instance's identity — minted fresh by every `instantiate`
+ * (`Instance/Core.ts`) and never equal to any other. Branded, and the brand key
+ * is module-private, so a token cannot be forged from outside this package: the
+ * only way to hold one is to have been handed an `Instance`.
+ */
+export type Token = symbol & {
+    readonly [Brand]: "Instance";
+};
+/**
+ * Where an instance sits in its lineage: every token from the root down to and
+ * including its own, so `ancestry[0]` is the lineage identity (`a.ancestry[0]
+ * === b.ancestry[0]` answers "same root?") and the last element is the instance
+ * itself. Non-empty by construction — a root `initialize()` mints one token
+ * before there is anything to inherit.
+ *
+ * Derived from the _receiver_: `fork` and `wrap` alike append to the ancestry
+ * of the instance they were called on, exactly as they both lay their overlay
+ * over that instance's `config`. One rule, so an instance's position and its
+ * configuration always agree about who its parent is.
+ *
+ * Two chains describe instances on the same ancestral line when either is a
+ * prefix of the other, which is what {@link Stack.visible} tests. That relation
+ * decides whose calls resolve against whose frames: a parent's calls resolve
+ * against a child's frame and a child's against a parent's, while two siblings
+ * resolve against neither's. Note this never crosses lineages, and not for want
+ * of identity — two roots hold two separate carriers, so a `wrap` on one pushes
+ * where the other's reads never look.
+ */
+export type Ancestry = readonly [Token, ...ReadonlyArray<Token>];
 /**
  * One active `wrap` — its resolved config plus the single `RandomSource` every
  * build reached inside that `wrap` shares, whether reached implicitly (any
- * instance in the lineage consulting the active frame) or explicitly
+ * instance on the origin's ancestral line consulting the frame) or explicitly
  * (`scope.Fabricator`, the `Instance` passed to the block). Storing the scope's
  * own already-built `source` here, rather than each consumer re-deriving one
  * from `config`, keeps the two routes resolving against the _same_ source —
  * sharing one set of construction-ordinal counters — instead of each silently
  * starting its own.
+ *
+ * `instance` is that same scope, kept so `context.scope()` can hand back the
+ * configuration in effect as a usable `Instance` rather than only as its
+ * separate `salt`/`algorithm`/`clock` fields.
+ *
+ * `ancestry` is the **origin's** — the instance `wrap` was called on — not the
+ * scope's. The scope is a fresh child of the origin, so keying on it would make
+ * every `fork` taken off that origin a _sibling_ of the scope, and calls on
+ * those forks would stop resolving against the frame. Keying on the origin
+ * keeps everything on the origin's own line resolving against it, which is the
+ * whole point of entering one.
  */
 export type Frame = {
     readonly config: Config<PlainObject>;
     readonly source: RandomSource;
+    readonly instance: Instance<PlainObject>;
+    readonly ancestry: Ancestry;
 };
 /**
- * The per-lineage ambient stack. Created once at a root `initialize()` and
- * threaded — never re-created — through every `fork`/`wrap` descended from it
- * (see `instantiate`, `Instance/Core.ts`). Two unrelated `initialize()` calls
- * stay fully isolated; one lineage's `wrap` reaches every instance in that
- * lineage — its `Fabricator`, `combinatorial`, and `coverage` alike —
- * regardless of where in the lineage that instance was itself created.
+ * The ambient frame carrier. Created once at a root `initialize()` and threaded
+ * — never re-created — through every `fork`/`wrap` descended from it (see
+ * `instantiate`, `Instance/Core.ts`).
+ *
+ * A carrier holds a chain of open frames and nothing else; which of them any
+ * given reader may see is {@link Ancestry}'s business, resolved by
+ * {@link visible}. Two unrelated `initialize()` calls hold separate carriers
+ * and so stay fully isolated — and because a reader is now gated on ancestry
+ * rather than on carrier identity, handing the _same_ carrier to two
+ * `initialize()` calls does not join them either: their roots mint unrelated
+ * tokens, so neither one's reads ever resolve the other's frames. `initialize({
+ * stack })` is therefore purely a choice of carrier.
  */
 export type Stack = {
     /**
@@ -85,39 +130,128 @@ export type Stack = {
      * instance. See `Instance/Stack/Sync.ts` and `Instance/Stack/Async.ts`.
      */
     readonly asynchronous: boolean;
-    current(): Frame | undefined;
     /**
-     * Push `frame`, run `block`, pop — in a `finally`, so a frame unwinds
-     * correctly even if `block` throws.
+     * Every open frame `ancestry` may resolve against, outermost first: those
+     * whose own `ancestry` is a prefix of this one or has this one as a prefix.
+     * The innermost visible frame — what a build or a `context` read actually
+     * resolves against — is the last element, and the count is `context.depth`.
+     *
+     * Filtering, rather than simply reporting the innermost frame, is what makes
+     * the outward walk possible: with a parent's `wrap` open and a child's nested
+     * inside it, the child's _sibling_ must skip the inner frame and still find
+     * the outer one. Callers never filter themselves — `toVisible`
+     * (`Instance/Stack/Visible.ts`) is the single definition both carriers
+     * delegate to, so the rule cannot drift between them.
+     */
+    visible(ancestry: Ancestry): ReadonlyArray<Frame>;
+    /**
+     * Append `frame`, run `block`, remove it in a `finally`, so a frame unwinds
+     * correctly even if `block` throws. Appends rather than replaces: the chain
+     * has to stay intact for {@link visible} to walk outward past a frame this
+     * reader cannot see.
      */
     enter<$Return>(frame: Frame, block: () => $Return): $Return;
 };
 /**
- * The configuration in effect _right now_ — the innermost active `wrap` frame,
- * or this instance's own when there is none. Distinct from
- * `ConstructionContext` (`Fabricator/Types.ts`), which is one construction's
- * internal dispatch plumbing; this is the caller-facing "what configuration is
- * in effect."
+ * What is in effect _right now_ — the innermost `wrap` frame this instance's
+ * calls can resolve against, or the instance itself when there is none.
+ *
+ * The four value properties are getters, so they are a live view only while
+ * this stays an object: destructuring one, or spreading the object, calls that
+ * getter once and freezes the result.
+ *
+ * {@link Context.scope} is deliberately a **function** rather than another
+ * getter: it is the one member a caller _acts through_ rather than reads, so
+ * freezing it would yield correct-looking code deriving from the wrong base. As
+ * a function it survives destructuring — `const { scope } = instance.context`,
+ * then `scope()`, still resolves live. Distinct from `ConstructionContext`
+ * (`Fabricator/Types.ts`), which is one construction's internal dispatch
+ * plumbing; this is the caller-facing "what is in effect."
  */
 export type Context = {
-    readonly seed: ReadonlyArray<string>;
+    readonly salt: ReadonlyArray<string>;
     readonly algorithm: Algorithm;
-    readonly attribution: Attribution;
     readonly clock: number;
+    /**
+     * The configuration in effect as an `Instance` — the visible frame's own
+     * scope, or this instance outside any. This is how to compose deliberately
+     * against whatever is active: `context.scope().wrap({ salt: layer("x") },
+     * ...)` lays over the frame in effect, where a plain `wrap` lays over the
+     * instance it was called on. Unlike rebuilding an overlay out of `salt` by
+     * hand, it carries `types`, `limits`, `algorithm` and `clock` across too.
+     *
+     * A function, not a getter, so capturing it captures the _lookup_ rather than
+     * one answer (see this type's own note above). What it returns is an ordinary
+     * `Instance`, fixed like any other — so holding the **result** across a frame
+     * change is a caller stating they wanted that one, while holding `scope`
+     * itself stays live.
+     */
+    scope(): Instance<PlainObject>;
+    /**
+     * How many frames are currently visible to this instance — 0 outside any.
+     * Genuine dynamic nesting depth, counted off the carrier rather than inferred
+     * from {@link Ancestry}: a frame a sibling cannot see is not counted for that
+     * sibling, and entering two `wrap`s on one instance reads as 2 even though
+     * neither deepened anyone's ancestry.
+     */
+    readonly depth: number;
 };
 /**
  * A single initialized library instance: the registry it was given, and a
- * `construct()` bound to its own isolated randomness — its own seed, builder,
- * and per-file overrides/streams, held internally and never shared with any
+ * `construct()` bound to its own isolated randomness — its own salt, builder,
+ * and construction counter/streams, held internally and never shared with any
  * other `initialize()` call. Independently initialized instances (e.g. parallel
  * tests) can never perturb each other.
  */
-export interface Instance<$Registry extends PlainObject> extends Pick<RandomSource, "seed"> {
+export interface Instance<$Registry extends PlainObject> extends Pick<RandomSource, "salt"> {
     /** The registry of type definers this instance was initialized with. */
     readonly T: $Registry;
+    /**
+     * This instance's position in its lineage — see {@link Ancestry}. Exposed so a
+     * caller can reason about which frames a given instance's calls resolve
+     * against; the tokens themselves are opaque and comparable only by identity.
+     * For the ordinary "same lineage?" question, compare {@link root} instead.
+     */
+    readonly ancestry: Ancestry;
+    /**
+     * The instance at the head of this lineage — the one `initialize()` returned.
+     * A root's own `root` is itself, so this is never `undefined` and no caller
+     * handles absence.
+     *
+     * Its job is identity: `a.root === b.root` answers "same lineage?", which is
+     * what `fork`/`wrap` descent preserves and what two separate `initialize()`
+     * calls never share — even when handed the same `stack`.
+     *
+     * It is **not** a way to reach "the ambient instance": every instance in a
+     * lineage resolves against the frames on its own line, so there is nothing to
+     * reach for. Nor is it a configuration to build against in preference to this
+     * one — `root`'s config is the lineage's starting point, not whatever is
+     * currently in effect. For that, see {@link Context.scope}.
+     *
+     * Typed at `PlainObject`, which is a deliberate shortcut rather than a
+     * necessity — unlike {@link Context.scope}, whose registry depends on which
+     * instance entered the innermost visible frame and so cannot be known
+     * statically at all.
+     *
+     * A root's registry is fixed at `initialize` and nothing later disturbs it: a
+     * `fork({ types })` mints a _new_ instance with a different registry and
+     * leaves the root exactly as it was. What is lost is the descendant's ability
+     * to name it — after such a fork this instance's `$Registry` is the fork's,
+     * so the root's is no longer recoverable from it. Typing this
+     * `Instance<$Registry>` would therefore be wrong if someone overrode
+     * `types`.
+     *
+     * Recovering it would mean threading a second parameter (`Instance<$Registry,
+     * $Root>`) through `fork` and `wrap`, which is a poor trade for an accessor
+     * whose job is identity: if you mean to _build_, you want the registry of the
+     * instance you are holding, not the one the lineage started from. So `root.T`
+     * is untyped, while `root.Fabricator` is unaffected since it carries no
+     * registry parameter.
+     */
+    readonly root: Instance<PlainObject>;
     /**
      * Turn a Schema built from `T` into a live Fabricator, deriving fresh
-     * randomness from this instance's own seed for whichever leaves actually need
+     * randomness from this instance's own salt for whichever leaves actually need
      * it.
      */
     Fabricator: Constructor;
@@ -138,8 +272,8 @@ export interface Instance<$Registry extends PlainObject> extends Pick<RandomSour
     coverage: Enumerable;
     /**
      * Derive a new instance laid over this one: anything the overlay names
-     * overrides, anything it omits inherits. A bare `seed` replaces this
-     * instance's seed; `seed: layer(...)` appends onto it. A peer of an
+     * overrides, anything it omits inherits. A bare `salt` replaces this
+     * instance's salt; `salt: layer(...)` appends onto it. A peer of an
      * `initialize()` return value in every respect, including its own `fork`.
      */
     fork<const $ForkRegistry extends PlainObject = $Registry>(overlay?: Overlay<$ForkRegistry>): Instance<$ForkRegistry>;
@@ -153,10 +287,19 @@ export interface Instance<$Registry extends PlainObject> extends Pick<RandomSour
      * — a build reached after an `await` inside `block` sees this instance's own
      * configuration again, not the wrap's.
      *
-     * A nested `wrap` lays over whichever frame is currently active, not over the
-     * instance it was called on — so `overlay.seed: layer(...)` accumulates with
-     * nesting depth while a bare `seed` still replaces outright, discarding every
-     * enclosing layer.
+     * The overlay lays over _this instance's_ config, exactly as `fork`'s does,
+     * whether or not a frame is already open. So a nested `wrap` accumulates when
+     * it is called on the enclosing scope — `wrap(a, (scope) => scope.wrap(b,
+     * ...))` — and restates from this instance when it is called on a receiver
+     * bound outside, as a destructured `wrap` is. To compose onto whatever is
+     * active regardless of receiver, go through `context.scope().wrap(...)`.
+     *
+     * While the block runs, calls made on this instance's ancestral line resolve
+     * against the scope — its forks, their forks, and its own ancestors up to the
+     * root. Calls on a _sibling_ do not: a frame entered on one `fork` is not one
+     * that another `fork` of the same parent can resolve against, which keeps two
+     * unrelated derivations from drawing each other's data. See
+     * {@link Ancestry}.
      */
     wrap<$Return, const $WrapRegistry extends PlainObject = $Registry>(overlay: Overlay<$WrapRegistry>, block: (scope: Instance<$WrapRegistry>) => $Return): $Return;
     /**
@@ -167,3 +310,4 @@ export interface Instance<$Registry extends PlainObject> extends Pick<RandomSour
      */
     readonly context: Context;
 }
+export {};

package/dist/types/Primitive/opaque/Registry.d.ts

@@ -6,7 +6,7 @@ import { Schema } from "./Schema";
  * `T.opaque((random) => new Map<string, number>())` needs no annotation.
  *
  * `produce` receives this schema's own seeded stream, so an opaque value still
- * replays from a seed; see `Types.ts`'s `Produce`. No bare form and no `.as()`
+ * replays from a salt; see `Types.ts`'s `Produce`. No bare form and no `.as()`
  * — `produce` is the whole schema.
  */
 export default function <$T>(produce: Produce<$T>): Schema<$T>;

package/dist/types/Primitive/recursive/Fabricator.d.ts

@@ -28,14 +28,13 @@ export type Fabricator<$Schema extends {
  * how deep this `fabricate()` goes — so no structural path distinguishes
  * sibling expansions at the same depth (an `array` of three `self` children
  * calls `fabricateAt` three times on one shared element Fabricator; the schema
- * does not tell them apart). Each expansion gets its own _root_: `forkSource`
- * mints an isolated `RandomSource` seeded from this node's draw, and each
- * `fabricateAt` opens a `"counted"` scope on it (`Random/Types.ts`'s `RootKind`
- * — recorded on each expansion's `trace`, not chosen at `ConstructorOptions`).
- * The private source's construction counter orders expansions; nothing to
- * increment here. Isolation also keeps this node's data-dependent draws from
- * perturbing (or being perturbed by) an unrelated Fabricator from the same
- * `initialize()` instance.
+ * does not tell them apart). `forkSource` mints an isolated `RandomSource`
+ * salted from this node's draw, and each `fabricateAt` resolves a
+ * `ConstructionTrace` on it (`RandomSource.toConstructionTrace`), recorded on
+ * each expansion's `trace`. The private source's construction counter orders
+ * expansions; nothing to increment here. Isolation also keeps this node's
+ * data-dependent draws from perturbing (or being perturbed by) an unrelated
+ * Fabricator from the same `initialize()` instance.
  *
  * Each `self` gets its own independently-dispatched expansion — calling
  * `context.self` twice (two array slots) is two `fabricateAt` calls, each with
@@ -43,4 +42,4 @@ export type Fabricator<$Schema extends {
  * shared-element one. Sibling tree branches therefore draw independently, not a
  * correlated shared sequence.
  */
-export declare function Fabricator<$Body>(context: FabricatorContext<Schema<$Body>>, forkSource: (seed: string) => RandomSource, make: (schema: unknown, path: ReadonlyArray<string>, context: ConstructionContext) => NaiveFabricator<unknown>): Fabricator<Schema<$Body>>;
+export declare function Fabricator<$Body>(context: FabricatorContext<Schema<$Body>>, forkSource: (salt: string) => RandomSource, make: (schema: unknown, path: ReadonlyArray<string>, context: ConstructionContext) => NaiveFabricator<unknown>): Fabricator<Schema<$Body>>;