@ghostry/fabricator 0.0.3 → 0.0.5

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

@@ -38,34 +38,77 @@ export type Identity = {
 /**
  * One context key's value, as a function of the test's `Identity` rather than a
  * fixed value.
+ *
+ * `established` is whatever this integration's own wrapper handed forward. For
+ * this integration that is the scoped `Instance` `wrap` opened, which is the
+ * whole of what `provides.fabricator` returns — so the value travels from the
+ * wrapper to the provider directly, with no mutable slot written on the way in
+ * and read on the way out.
+ */
+export type Provider<$Value, $Established = void> = (args: ProviderArgs<$Established>) => $Value;
+/**
+ * What `@ghostry/harness` hands {@link Integration.frame}: one object, never
+ * positional arguments, so a field added to the contract later is a key an
+ * existing hook ignores rather than a parameter it has to thread past.
  */
-export type Provider<$Value> = (identity: Identity) => $Value;
+export type FrameArgs = {
+    readonly identity: Identity;
+};
+/**
+ * What it hands each provider: everything {@link FrameArgs} carries, plus what
+ * this integration's own wrapper established — for this integration, the scoped
+ * `Instance` that `wrap` opened.
+ */
+export type ProviderArgs<$Established = void> = FrameArgs & {
+    readonly established: $Established;
+};
 /**
  * The keys an integration contributes, and how each is produced. Homomorphic
  * over `$Context`, so the context an integration contributes is read back out
  * of this object's shape with no separate key declaration to keep in sync.
  */
-export type Provides<$Context extends object> = {
-    readonly [$Key in keyof $Context]: Provider<$Context[$Key]>;
+export type Provides<$Context extends object, $Established = void> = {
+    readonly [$Key in keyof $Context]: Provider<$Context[$Key], $Established>;
 };
+/**
+ * How an integration runs the body when the body must run _inside_ something.
+ * Here that is fabricator's own `wrap`, whose block parameter is already this
+ * shape — the scoped `Instance` it opens is what reaches `body`, and therefore
+ * what reaches the providers.
+ *
+ * Generic in its return and must hand the body's value back unchanged: that is
+ * what keeps a synchronous test synchronous and what lets frames nest.
+ */
+export type Wrapper<$Established = void> = <$Return>(body: (established: $Established) => $Return) => $Return;
+/**
+ * What {@link Integration.frame} returns: a generator with **one** suspension
+ * point. Everything before the `yield` is setup, the body runs at the `yield`,
+ * and everything after it is teardown, resumed when the body _settles_.
+ *
+ * `@ghostry/harness` accepts an `AsyncGenerator` here too. This declares only
+ * the synchronous half, because that is the half this integration uses and the
+ * narrower type still satisfies the wider one — the same reason `frame` is
+ * required below though it is optional there. Opening a fabricator scope is
+ * synchronous, and declaring the async arm would invite an integration that
+ * promotes every test in the suite to a promise for no reason.
+ */
+export type Frame<$Established = void> = Generator<Wrapper<$Established> | void, void, unknown>;
 /**
  * What `integration(instance)` is, as `@ghostry/harness`'s `initialize` sees
  * it. The subset of that package's contract this integration actually uses, not
- * a copy of all of it: `@ghostry/harness` also accepts an optional `setup`,
- * which fabricator has no teardown to put in, and an object lacking an optional
- * member still satisfies the contract structurally. `around` is required here,
- * though optional there, because this integration always declares it.
+ * a copy of all of it: an object lacking an optional member still satisfies the
+ * contract structurally, so `frame` is required here though optional there,
+ * because this integration always declares it.
  *
  * `provides` is the _only_ source of context keys; `initialize` rejects a
  * collision across integrations by reading `Object.keys(provides)`. Each
- * provider runs inside its integration's `around`. `around` is generic in its
- * return and must return the body's value unchanged: that is what makes async
- * work and what lets frames nest.
+ * provider runs _inside_ that frame and receives the same `$Established` the
+ * wrapper handed to the body.
  */
-export type Integration<$Context extends object> = {
+export type Integration<$Context extends object, $Established = void> = {
     readonly name: string;
-    readonly provides: Provides<$Context>;
-    around<$Return>(identity: Identity, body: () => $Return): $Return;
+    readonly provides: Provides<$Context, $Established>;
+    frame(args: FrameArgs): Frame<$Established>;
 };
 /**
  * The slice of the test context `integration(instance)` contributes — one key,

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
@@ -51,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

@@ -47,27 +47,77 @@ export type Overlay<$Registry extends PlainObject> = Partial<Omit<Config<$Regist
     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 = {
     /**
@@ -80,24 +130,71 @@ 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 salt: ReadonlyArray<string>;
     readonly algorithm: Algorithm;
     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
@@ -109,6 +206,49 @@ export type Context = {
 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 salt for whichever leaves actually need
@@ -147,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.salt: layer(...)` accumulates with
-     * nesting depth while a bare `salt` 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;
     /**
@@ -161,3 +310,4 @@ export interface Instance<$Registry extends PlainObject> extends Pick<RandomSour
      */
     readonly context: Context;
 }
+export {};

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

@@ -26,6 +26,6 @@ export type Fabricator<$Schema extends {
  * shared across every element. The weighted pick happens on this field's
  * private stream; only the chosen option's `fabricate()` is called, so an
  * unpicked option never advances its stream (safe for the same reason skipping
- * `object.omittable`'s inner draw is — see CLAUDE.md's "Randomness").
+ * `object.omittable`'s inner draw is — see AGENTS.md's "Randomness").
  */
 export declare function Fabricator<$Items extends Items>(context: FabricatorContext<Schema<$Items>>, weightings: ReadonlyArray<readonly [number, NaiveFabricator<any>]>): Fabricator<Schema<$Items>>;

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

@@ -24,7 +24,7 @@ export type Fabricator<$Schema extends {
  * `source` is already dispatched into its own independent stream by
  * `Constructor.ts` regardless of this roll, skipping its draw here can never
  * perturb any other field's reproducibility (see
- * `object/omittable/Fabricator.ts`, and CLAUDE.md's "Randomness"). 50/50 by
+ * `object/omittable/Fabricator.ts`, and AGENTS.md's "Randomness"). 50/50 by
  * default; `.weighted(...)` (`Schema.ts`) reweights either outcome relative to
  * that same default of `1`.
  */

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

@@ -24,12 +24,12 @@ export type Fabricator<$Schema extends {
  * by default; not achievable by composing `nullable(T.undefinable(inner))`'s
  * two independent 50/50 rolls (that is 50/25/25, not 33/33/33), hence the
  * dedicated three-way `weighted()` here — see `object/optional/Fabricator.ts`
- * and CLAUDE.md's "Why `T.optional` isn't `omittable(undefinable(inner))`".
+ * and AGENTS.md's "Why `T.optional` isn't `omittable(undefinable(inner))`".
  * `.weighted(...)` (`Schema.ts`) reweights individual outcomes relative to that
  * same default of `1`; an unspecified outcome keeps it. Skipping `source`'s
  * draw on the two non-"value" outcomes is safe for the same reason as
  * `object/omittable/Fabricator.ts`: `source` already has its own independent
- * stream, minted at build time regardless of this roll (see CLAUDE.md's
+ * stream, minted at build time regardless of this roll (see AGENTS.md's
  * "Randomness").
  */
 export declare function Fabricator<$Definition extends Definition>(context: FabricatorContext<Schema<$Definition>>, source: BaseFabricator<any>): Fabricator<Schema<$Definition>>;

package/dist/types/Primitive/object/optional/Fabricator.d.ts

@@ -32,12 +32,12 @@ export declare function isObjectOptionalFabricator(candidate: BaseFabricator<unk
  * Uniform (1/3 each) by default; not achievable by composing
  * `object.omittable(T.undefinable(inner))`'s two independent 50/50 rolls (that
  * is 50/25/25, not 33/33/33), hence the dedicated three-way `weighted()` here —
- * see CLAUDE.md's "Why `T.optional` isn't `omittable(undefinable(inner))`"
+ * see AGENTS.md's "Why `T.optional` isn't `omittable(undefinable(inner))`"
  * under "Compound / field-only kinds". `.weighted(...)` (`Schema.ts`) reweights
  * individual outcomes relative to that same default of `1`; an unspecified
  * outcome keeps it. Skipping `source`'s draw on the two non-"value" outcomes is
  * safe for the same reason as `object/omittable/Fabricator.ts`: `source`
  * already has its own independent stream, minted at build time regardless of
- * this roll (see CLAUDE.md's "Randomness").
+ * this roll (see AGENTS.md's "Randomness").
  */
 export declare function Fabricator<$Definition extends Definition>(context: FabricatorContext<Schema<$Definition>>, source: BaseFabricator<any>): Fabricator<Schema<$Definition>>;

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` salted from this node's draw, and each
- * `fabricateAt` resolves an ordinary construction root on it
- * (`RandomSource.toRoot`), 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.
+ * 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

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

@@ -6,7 +6,7 @@ import { Produces, type Adaptation, type Kind, type Meta } from "../../Types";
  * `TS2456` ("`RecursiveValue` circularly references itself") — legal _only_
  * because `ValueOf`'s second argument is read through an interface member
  * (`this["bindings"]` on every composite `Core`), which TypeScript defers. Do
- * not rewrite as a conditional; that reintroduces the error. See `CLAUDE.md`'s
+ * not rewrite as a conditional; that reintroduces the error. See `AGENTS.md`'s
  * "`ValueOf`'s `$Bindings`".
  *
  * Wherever `self` sits in `$Body` (nested through `array`/`object`/`tuple`/

package/dist/types/Primitive/recursive/self/Types.d.ts

@@ -15,7 +15,7 @@ export type Fabricated<$Bindings extends unknown[] = []> = $Bindings[0];
 export type Meta = Record<string, never>;
 /**
  * An `interface`, not a `type` alias, so `this["bindings"]` resolves — the
- * entire mechanism this kind exists for. See `CLAUDE.md`'s "`ValueOf`'s
+ * entire mechanism this kind exists for. See `AGENTS.md`'s "`ValueOf`'s
  * `$Bindings`" section for why threading requires this.
  */
 export interface Core<$Adaptations extends Adaptations = {}> {

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

@@ -24,7 +24,7 @@ export type Fabricator<$Schema extends {
  * since `source` is already dispatched into its own independent stream by
  * `Constructor.ts` regardless of this roll, skipping its draw here can never
  * perturb any other field's reproducibility (see
- * `object/omittable/Fabricator.ts`, and CLAUDE.md's "Randomness"). 50/50 by
+ * `object/omittable/Fabricator.ts`, and AGENTS.md's "Randomness"). 50/50 by
  * default; `.weighted(...)` (`Schema.ts`) reweights either outcome relative to
  * that same default of `1`.
  */

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

@@ -68,8 +68,8 @@ export type Trace = {
 };
 /**
  * Caller-supplied overrides for the construction-owned {@link Trace} slots
- * {@link RandomSource.toRoot} resolves. `path`/`kind` are the only slots absent:
- * they are per-node and applied in `construct()`, not here.
+ * {@link RandomSource.toConstructionTrace} resolves. `path`/`kind` are the only
+ * slots absent: they are per-node and applied in `construct()`, not here.
  *
  * `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
@@ -82,17 +82,17 @@ export type Trace = {
  * 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 = {
+export type ConstructionPins = {
     salt?: ReadonlyArray<string> | undefined;
     clock?: number | undefined;
     ordinal?: number | null | undefined;
 };
 /**
- * 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.
+ * Every {@link Trace} slot fixed once per construction, before a leaf supplies
+ * its own `path`/`kind`. `RandomSource.toConstructionTrace` resolves this once;
+ * 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">;
 /**
@@ -173,9 +173,9 @@ export type Options = {
  * 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
+ * {@link RandomSource.toConstructionTrace} 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.
@@ -205,20 +205,22 @@ export type ConstructorOptions = {
  */
 export type RandomSource = {
     /**
-     * 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
-     * construction-ordinal bump serves the whole construction.
+     * Resolve this source's `salt`/`clock` and the next construction ordinal,
+     * each overridable by {@link ConstructionPins}. Called once per `new
+     * Fabricator(...)` (or per lazy expansion of a `T.recursive` schema, each of
+     * which resolves its own construction trace 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 construction-ordinal bump serves the whole
+     * construction.
      */
-    toRoot(pins?: RootPins): ConstructionTrace;
+    toConstructionTrace(pins?: ConstructionPins): 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 (the construction counter).
+     * the free function `toStreamFromTrace(algorithm, trace)`.
+     * `toConstructionTrace` is the only stateful member (the construction
+     * counter).
      */
     readonly algorithm: Algorithm;
     /**