@ghostry/fabricator 0.0.3 → 0.0.4

package/dist/esm/Enumeration/Enumerate.js

@@ -1,14 +1,15 @@
 import { shuffle } from "../Distribution/index.js";
 import { FabricatorError } from "../Error/index.js";
 import { Constructor } from "../Fabricator/Constructor.js";
+import { toInnermostFrame } from "../Instance/Stack/Visible.js";
 import { toStreamFromTrace } from "../Random/index.js";
 import { plan, resolve } from "./Plan.js";
-function enumerables(source, limits, stack) {
-    const Fabricator = Constructor(source, stack);
+function enumerables(source, limits, stack, ancestry) {
+    const Fabricator = Constructor(source, stack, ancestry);
     function effectiveSource() {
         var _ref;
-        var _stack_current;
-        return null != (_ref = null == (_stack_current = stack.current()) ? void 0 : _stack_current.source) ? _ref : source;
+        var _toInnermostFrame;
+        return null != (_ref = null == (_toInnermostFrame = toInnermostFrame(stack, ancestry)) ? void 0 : _toInnermostFrame.source) ? _ref : source;
     }
     function iterable(rebuild) {
         return {
@@ -90,9 +91,9 @@ function enumerables(source, limits, stack) {
 }
 function orderer(source, salt) {
     const forked = source.fork(salt);
-    const root = forked.toRoot();
+    const trace = forked.toConstructionTrace();
     const stream = toStreamFromTrace(forked.algorithm, {
-        ...root,
+        ...trace,
         path: [],
         kind: "order"
     });

package/dist/esm/Fabricator/Constructor.js

@@ -1,10 +1,11 @@
 import { FabricatorError } from "../Error/index.js";
+import { toInnermostFrame } from "../Instance/Stack/Visible.js";
 import { Primitive } from "../Primitive/index.js";
 import { isLayered, normalizeSalt } from "../Random/index.js";
 import { toSchema } from "../Schema/Core.js";
 import { Adaptation, Fixed, Kind, Layer, Meta } from "../Types.js";
 import { inline } from "../Utility/Core.js";
-function Constructor(source, stack) {
+function Constructor(source, stack, ancestry) {
     function make(schema, path, context) {
         schema = toSchema(schema);
         const kind = schema[Kind];
@@ -280,7 +281,7 @@ function Constructor(source, stack) {
     function construct(schema, options = {}) {
         var _options_path;
         if ("string" == typeof options.kind && options.kind !== schema[Kind]) throw new FabricatorError.TraceKindMismatchError(schema[Kind], options.kind);
-        const context = toConstructionContext(source, options, stack);
+        const context = toConstructionContext(source, options, stack, ancestry);
         const made = make(schema, null != (_options_path = options.path) ? _options_path : [], context);
         const adaptations = schema[Adaptation];
         return adaptations ? {
@@ -290,21 +291,21 @@ function Constructor(source, stack) {
     }
     return construct;
 }
-function toConstructionContext(source, options, stack) {
-    const { source: rooted, root: construction } = resolveScope(source, options, stack);
+function toConstructionContext(source, options, stack, ancestry) {
+    const { source: resolved, trace } = resolveScope(source, options, stack, ancestry);
     return {
         toTrace: (path, kind)=>({
-                ...construction,
+                ...trace,
                 path,
                 kind
             }),
-        algorithm: rooted.algorithm
+        algorithm: resolved.algorithm
     };
 }
-function resolveScope(source, options, stack) {
+function resolveScope(source, options, stack, ancestry) {
     var _ref;
-    const frame = stack.current();
-    const base = null != (_ref = null == frame ? void 0 : frame.source) ? _ref : source;
+    var _toInnermostFrame;
+    const base = null != (_ref = null == (_toInnermostFrame = toInnermostFrame(stack, ancestry)) ? void 0 : _toInnermostFrame.source) ? _ref : source;
     const salt = inline(()=>{
         if (!options.salt) return;
         if (isLayered(options.salt)) return [
@@ -320,7 +321,7 @@ function resolveScope(source, options, stack) {
     };
     return {
         source: base,
-        root: base.toRoot(pins)
+        trace: base.toConstructionTrace(pins)
     };
 }
 export { Constructor };

package/dist/esm/Instance/Core.js

@@ -5,6 +5,7 @@ import { defaultAlgorithm, deriveClock, isLayered, normalizeSalt, toRandomSource
 import { registry } from "../Schema/Registry.js";
 import { Layer } from "../Types.js";
 import { inline, isThenable, noop } from "../Utility/Core.js";
+import { toInnermostFrame } from "./Stack/Visible.js";
 const DEFAULT_COMBINATORIAL_LIMIT = 1024;
 function resolveCombinatorialLimit(limit) {
     if (void 0 === limit) return DEFAULT_COMBINATORIAL_LIMIT;
@@ -14,6 +15,9 @@ function resolveCombinatorialLimit(limit) {
 function resolveClock(config) {
     return "number" == typeof config.clock ? config.clock : deriveClock(config.algorithm, normalizeSalt(config.salt));
 }
+function mint() {
+    return Symbol("fabricator.instance");
+}
 function overlay(base, over) {
     var _ref, _over_algorithm, _ref1, _over_types, _over_limits;
     var _this;
@@ -41,26 +45,40 @@ function overlay(base, over) {
         }
     };
 }
-function instantiate(config, stack) {
+function instantiate(config, stack, parent) {
+    const ancestry = void 0 === parent ? [
+        mint()
+    ] : [
+        ...parent.ancestry,
+        mint()
+    ];
     const source = toRandomSource({
         salt: config.salt,
         algorithm: config.algorithm,
         clock: resolveClock(config)
     });
-    const Fabricator = Constructor(source, stack);
-    const { combinatorial, coverage } = enumerables(source, config.limits, stack);
+    const Fabricator = Constructor(source, stack, ancestry);
+    const { combinatorial, coverage } = enumerables(source, config.limits, stack, ancestry);
+    function derive(over) {
+        const derived = overlay(config, over);
+        return {
+            ...instantiate(derived, stack, {
+                ancestry,
+                root: instance.root
+            }),
+            config: derived
+        };
+    }
     function fork(forkOverlay = {}) {
-        return instantiate(overlay(config, forkOverlay), stack).instance;
+        return derive(forkOverlay).instance;
     }
     function wrap(wrapOverlay, block) {
-        var _ref;
-        var _stack_current;
-        const base = null != (_ref = null == (_stack_current = stack.current()) ? void 0 : _stack_current.config) ? _ref : config;
-        const scopedConfig = overlay(base, wrapOverlay);
-        const scoped = instantiate(scopedConfig, stack);
+        const scoped = derive(wrapOverlay);
         const result = stack.enter({
-            config: scopedConfig,
-            source: scoped.source
+            config: scoped.config,
+            source: scoped.source,
+            instance: scoped.instance,
+            ancestry
         }, ()=>block(scoped.instance));
         if (!stack.asynchronous && isThenable(result)) {
             result.then(noop, noop);
@@ -68,25 +86,41 @@ function instantiate(config, stack) {
         }
         return result;
     }
+    function visibleFrame() {
+        return toInnermostFrame(stack, ancestry);
+    }
     const context = {
         get salt () {
             var _ref;
-            var _stack_current;
-            return normalizeSalt((null != (_ref = null == (_stack_current = stack.current()) ? void 0 : _stack_current.config) ? _ref : config).salt);
+            var _visibleFrame;
+            return normalizeSalt((null != (_ref = null == (_visibleFrame = visibleFrame()) ? void 0 : _visibleFrame.config) ? _ref : config).salt);
         },
         get algorithm () {
             var _ref1;
-            var _stack_current1;
-            return (null != (_ref1 = null == (_stack_current1 = stack.current()) ? void 0 : _stack_current1.config) ? _ref1 : config).algorithm;
+            var _visibleFrame1;
+            return (null != (_ref1 = null == (_visibleFrame1 = visibleFrame()) ? void 0 : _visibleFrame1.config) ? _ref1 : config).algorithm;
         },
         get clock () {
             var _ref2;
-            var _stack_current2;
-            return resolveClock(null != (_ref2 = null == (_stack_current2 = stack.current()) ? void 0 : _stack_current2.config) ? _ref2 : config);
+            var _visibleFrame2;
+            return resolveClock(null != (_ref2 = null == (_visibleFrame2 = visibleFrame()) ? void 0 : _visibleFrame2.config) ? _ref2 : config);
+        },
+        scope: ()=>{
+            var _ref;
+            var _visibleFrame;
+            return null != (_ref = null == (_visibleFrame = visibleFrame()) ? void 0 : _visibleFrame.instance) ? _ref : instance;
+        },
+        get depth () {
+            return stack.visible(ancestry).length;
         }
     };
     const instance = {
         T: config.types,
+        ancestry,
+        get root () {
+            var _ref3;
+            return null != (_ref3 = null == parent ? void 0 : parent.root) ? _ref3 : instance;
+        },
         Fabricator,
         combinatorial,
         coverage,

package/dist/esm/Instance/Stack/Async.js

@@ -1,10 +1,18 @@
 import { AsyncLocalStorage } from "async_hooks";
+import { toVisible } from "./Visible.js";
 function toStack() {
     const store = new AsyncLocalStorage();
+    const getFrames = ()=>{
+        var _store_getStore;
+        return null != (_store_getStore = store.getStore()) ? _store_getStore : [];
+    };
     return {
         asynchronous: true,
-        current: ()=>store.getStore(),
-        enter: (frame, block)=>store.run(frame, block)
+        visible: (ancestry)=>toVisible(getFrames(), ancestry),
+        enter: (frame, block)=>store.run([
+                ...getFrames(),
+                frame
+            ], block)
     };
 }
 export { toStack };

package/dist/esm/Instance/Stack/Sync.js

@@ -1,8 +1,9 @@
+import { toVisible } from "./Visible.js";
 function toStack() {
     const frames = [];
     return {
         asynchronous: false,
-        current: ()=>frames[frames.length - 1],
+        visible: (ancestry)=>toVisible(frames, ancestry),
         enter: (frame, block)=>{
             frames.push(frame);
             try {

package/dist/esm/Instance/Stack/Visible.js

@@ -0,0 +1,13 @@
+function onDirectLine(a, b) {
+    const shared = Math.min(a.length, b.length);
+    for(let index = 0; index < shared; index++)if (a[index] !== b[index]) return false;
+    return true;
+}
+function toVisible(frames, ancestry) {
+    return frames.filter((frame)=>onDirectLine(frame.ancestry, ancestry));
+}
+function toInnermostFrame(stack, ancestry) {
+    const frames = stack.visible(ancestry);
+    return frames[frames.length - 1];
+}
+export { toInnermostFrame, toVisible };

package/dist/esm/Primitive/recursive/Fabricator.js

@@ -10,7 +10,7 @@ function Fabricator(context, forkSource, make) {
     function fabricateAt(depth) {
         const atMax = depth >= meta.depth.max;
         const target = atMax ? meta.terminal : meta.body;
-        const construction = privateSource.toRoot();
+        const construction = privateSource.toConstructionTrace();
         const context = {
             toTrace: (path, kind)=>({
                     ...construction,

package/dist/esm/Random/index.js

@@ -71,7 +71,7 @@ function toRandomSource(options) {
     let algorithm = null != (_options_algorithm = options.algorithm) ? _options_algorithm : defaultAlgorithm;
     const clock = options.clock;
     let constructionOrdinal = 0;
-    function toRoot(pins = {}) {
+    function toConstructionTrace(pins = {}) {
         var _pins_salt, _pins_clock;
         return {
             salt: null != (_pins_salt = pins.salt) ? _pins_salt : salt,
@@ -87,7 +87,7 @@ function toRandomSource(options) {
         });
     }
     return {
-        toRoot,
+        toConstructionTrace,
         algorithm,
         salt,
         fork

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

@@ -1,25 +1,25 @@
-import type { Stack } from "../Instance/Types";
+import type { Ancestry, Stack } from "../Instance/Types";
 import type { RandomSource } from "../Random/Types";
 import type { Enumerable, Limits } from "./Types";
 /**
  * Typed `combinatorial`/`coverage` boundary, closing over one instance's
  * `source` and its already-validated `limits` — same shape as
- * `Constructor(source, stack)`. No separate `clock`: `source` already carries
+ * `Constructor(source, stack, ancestry)`. No separate `clock`: `source` carries
  * its resolved clock (`Random/Types.ts`'s `Options.clock`), so `Constructor`'s
- * `toConstructionContext` reads it off whichever root a construction resolves
- * against. `plan`/ `resolve` (`./Plan.ts`) do the untyped recursive work; this
- * is the one precisely-typed layer, mirroring `Constructor.ts`'s `make`/
- * `construct` split.
+ * `toConstructionContext` reads it off the resolved `ConstructionTrace`.
+ * `plan`/ `resolve` (`./Plan.ts`) do the untyped recursive work; this is the
+ * one precisely-typed layer, mirroring `Constructor.ts`'s `make`/`construct`
+ * split.
  *
  * Two derived salts — one per API — each composed from the _effective_ source's
- * salt (`effectiveSource()` below — the active `wrap` frame's, or this
- * instance's `source`; read fresh on every `combinatorial(...)`/`coverage(...)`
- * call, not once when `enumerables()` was built, so the same `combinatorial`
- * reference behaves differently inside an active `wrap`). Each build pins that
- * salt via `new Fabricator(schema, { salt })` (see `Constructor.ts`'s
- * `construct()`) — a pin, not a fork — so every rebuild of one schema draws
- * from the same universe, distinct from anything built under the instance's own
- * salt.
+ * salt (`effectiveSource()` below — the innermost visible `wrap` frame's, or
+ * this instance's `source`; read fresh on every
+ * `combinatorial(...)`/`coverage(...)` call, not once when `enumerables()` was
+ * built, so the same `combinatorial` reference behaves differently inside a
+ * `wrap` this instance can see). Each build pins that salt via `new
+ * Fabricator(schema, { salt })` (see `Constructor.ts`'s `construct()`) — a pin,
+ * not a fork — so every rebuild of one schema draws from the same universe,
+ * distinct from anything built under the instance's own salt.
  *
  * `ordinal: null` is pinned alongside it, and is not incidental: a salt says
  * nothing about ordering, so without this pin each lazy rebuild would take the
@@ -29,7 +29,7 @@ import type { Enumerable, Limits } from "./Types";
  * every iteration rebuilds from the same explicit identity, and the `null` can
  * never coincide with a counted construction.
  */
-export declare function enumerables(source: RandomSource, limits: Limits, stack: Stack): {
+export declare function enumerables(source: RandomSource, limits: Limits, stack: Stack, ancestry: Ancestry): {
     combinatorial: Enumerable;
     coverage: Enumerable;
 };

package/dist/types/Fabricator/Constructor.d.ts

@@ -1,4 +1,4 @@
-import type { Stack } from "../Instance/Types";
+import type { Ancestry, Stack } from "../Instance/Types";
 import type { ConstructorOptions, RandomSource } from "../Random/Types";
 import { type Buildable } from "../Types";
 import { type AsFabricator } from "./Types";
@@ -25,17 +25,20 @@ export type Constructor = {
  * fabricator this `construct()` produces draws from that instance's own
  * salt/streams and never another instance's.
  *
- * `stack` is the instance's own lineage-wide ambient stack
- * (`Instance/Core.ts`'s `toStack()`) — passed straight through to
+ * `stack` is the ambient carrier and `ancestry` is this instance's position in
+ * its lineage (`Instance/Core.ts`) — both passed straight through to
  * `resolveScope` on every `construct()` call, never read here directly, so a
- * build reached inside an active `wrap` resolves against that frame
- * automatically, with nothing threaded through by the caller.
+ * build reached inside a `wrap` this instance can see resolves against that
+ * frame automatically, with nothing threaded through by the caller. `ancestry`
+ * is what decides "can see": a frame entered on a sibling instance is not one
+ * this `construct()` will ever resolve against.
  *
  * No separate `clock` parameter: `source` already carries its own resolved
  * clock intrinsically (`Random/Types.ts`'s `Options.clock`, baked in when the
  * source was built), and `resolveScope`'s chosen source — the active `wrap`
  * frame's, or this one — is exactly the source whose clock a construction
  * should resolve "now" against. `toConstructionContext` reads it straight off
- * the resolved root rather than threading a second value alongside `source`.
+ * the resolved construction trace rather than threading a second value
+ * alongside `source`.
  */
-export declare function Constructor(source: RandomSource, stack: Stack): Constructor;
+export declare function Constructor(source: RandomSource, stack: Stack, ancestry: Ancestry): Constructor;

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

@@ -14,19 +14,20 @@ import type { PlainObject } from "../Utility/Types";
  * `toTrace` records this node's {@link Trace} — a plain object literal, no
  * hashing. Hashing is paid only where a kind actually calls
  * `toStreamFromTrace(algorithm, trace)`. Bound once in `construct()` to this
- * one construction's already-resolved `RandomSource`/ `ConstructionTrace` pair
+ * one construction's already-resolved `RandomSource`/`ConstructionTrace` pair
  * (see `Constructor.ts`'s `resolveScope`) — every leaf calls `toTrace` with
  * only its own structural `path` and kind, never re-resolving the
- * construction's root itself. `T.recursive` is the one kind that rebinds
- * `toTrace`: each lazy expansion opens its own scope on the node's own private
- * forked `RandomSource` (see `recursive/Fabricator.ts`), so a data-dependent
- * expansion count can never perturb, or be perturbed by, anything else built
- * from the same `initialize()` instance — `RandomSource.fork`
- * (`Random/Types.ts`) is the isolation primitive.
+ * construction-owned slots itself. `T.recursive` is the one kind that rebinds
+ * `toTrace`: each lazy expansion resolves its construction trace on the node's
+ * own private forked `RandomSource` (see `recursive/Fabricator.ts`), so a
+ * data-dependent expansion count can never perturb, or be perturbed by,
+ * anything else built from the same `initialize()` instance —
+ * `RandomSource.fork` (`Random/Types.ts`) is the isolation primitive.
  *
  * `algorithm` rather than the `RandomSource` itself: stream derivation depends
- * on no per-source state, and a leaf has no business with `toRoot`/`fork`.
- * `clock` is not a field of its own — it is always `trace.clock`.
+ * on no per-source state, and a leaf has no business with
+ * `toConstructionTrace`/`fork`. `clock` is not a field of its own — it is
+ * always `trace.clock`.
  *
  * `self` is what makes `case "recursive.self"` resolve to "recurse one level
  * deeper, right now" — absent outside any active recursion, which is how `case
@@ -47,11 +48,11 @@ export type ConstructionContext = {
  * `toStreamFromTrace(algorithm, trace)`. The guard is the call site's own `if
  * (meta.produce)` branch (or the equivalent drawing path), not an unevaluated
  * closure. `algorithm` rather than the `RandomSource`: derivation depends on no
- * per-source state, and a leaf has no business with `toRoot`/`fork`. No
- * `clock`: it is `trace.clock`, always. A kind-specific extra — an array's
- * `element`, an object's `fields`, a choice's `weightings` — still follows as
- * its own trailing parameter: those vary per kind and were never part of the
- * shared prefix this replaces.
+ * per-source state, and a leaf has no business with
+ * `toConstructionTrace`/`fork`. No `clock`: it is `trace.clock`, always. A
+ * kind-specific extra — an array's `element`, an object's `fields`, a choice's
+ * `weightings` — still follows as its own trailing parameter: those vary per
+ * kind and were never part of the shared prefix this replaces.
  */
 export type FabricatorContext<$Schema> = {
     schema: $Schema;

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/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/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;
     /**

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

@@ -63,7 +63,7 @@ export declare function toStream(algorithm: Algorithm, seed: string): Stream;
  * `toStream(algorithm, encode(trace)).seed === stream.seed`. Not a
  * {@link RandomSource} member: derivation depends on no per-source state (a
  * fork shares only the algorithm), so it is a free function of `(algorithm,
- * trace)`. `toRoot` is the only stateful member.
+ * trace)`. `toConstructionTrace` is the only stateful member.
  *
  * {@link deriveClock} cannot route through this: a {@link Trace} carries
  * `clock`, and `deriveClock` is what produces it. That circularity is why
@@ -76,7 +76,7 @@ export declare function toStreamFromTrace(algorithm: Algorithm, trace: Trace): S
  * single `initialize()` instance owns for its lifetime. `options.clock` is
  * 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.
+ * is ever built, so every construction trace this source resolves carries the
+ * identical instant, and `fork` threads it forward unchanged.
  */
 export declare function toRandomSource(options: Options): RandomSource;

package/dist/types/index.d.ts

@@ -50,7 +50,10 @@ export declare function initialize<const $Registry extends PlainObject = typeof
     clock?: Date | "derived";
     /**
      * The ambient carrier backing `wrap` for this lineage — override only to
-     * force a specific one.
+     * force a specific one. A choice of carrier and nothing more: lineage
+     * identity is the instance's own `ancestry[0]`, so handing the same carrier
+     * to two `initialize()` calls does not join them — neither one's reads ever
+     * resolve the other's frames.
      *
      * Left unset (the norm), the `#stack` package import picks it: every
      * runtime with `node:async_hooks` — Node, Bun, Deno — gets the
@@ -149,5 +152,11 @@ export type { Trace } from "./Random/Types";
  * parameter is a `Partial` of; `Overlay` is what `fork`/`wrap` accept;
  * `Context` is `instance.context`'s own type, so a caller writing a helper that
  * reads it can name the parameter.
+ *
+ * `Ancestry` comes with `Stack`, whose `visible` takes one, so anyone
+ * implementing a carrier can name the parameter. `Token` is deliberately _not_
+ * exported: a chain is opaque, its elements are comparable only by identity,
+ * and the ordinary "same lineage?" question is `a.root === b.root` rather than
+ * anything a caller needs to name.
  */
-export type { Config, Context, Overlay, Stack } from "./Instance/Types";
+export type { Ancestry, Config, Context, Overlay, Stack, } from "./Instance/Types";

package/dist/types/internal.d.ts

@@ -63,7 +63,7 @@ export type { Axis, Enumerable, Pin, Resolvable } from "./Enumeration/Types";
  * directly, beneath the level `initialize()` itself exposes.
  */
 export { defaultAlgorithm, encode, randomSalt, toRandomSource, toStream, toStreamFromTrace, } from "./Random";
-export type { Algorithm, ConstructionTrace, ConstructorOptions, RootPins, Salt, Trace, } from "./Random/Types";
+export type { Algorithm, ConstructionPins, ConstructionTrace, ConstructorOptions, Salt, Trace, } from "./Random/Types";
 /**
  * The synchronous ambient carrier. `#stack` (`package.json`) selects it only
  * where there is no `node:async_hooks` — in practice a browser bundle — so on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostry/fabricator",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "license": "MIT",
   "description": "Fabricate typed data from composable schemas.",
   "keywords": [