@ghostry/fabricator 0.0.6 → 0.0.7

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

@@ -1,10 +1,10 @@
-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;
+function governs(receiver, reader) {
+    if (reader.length > receiver.length) return false;
+    for(let index = 0; index < reader.length; index++)if (reader[index] !== receiver[index]) return false;
     return true;
 }
 function toVisible(frames, ancestry) {
-    return frames.filter((frame)=>onDirectLine(frame.ancestry, ancestry));
+    return frames.filter((frame)=>governs(frame.ancestry, ancestry));
 }
 function toInnermostFrame(stack, ancestry) {
     const frames = stack.visible(ancestry);

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

@@ -34,12 +34,15 @@ import type { FabricatorTestContext, Integration } from "./Types";
  * `scope` is a function so that capturing it captures the lookup, where a
  * captured result would pin one frame.
  *
- * The frame that `wrap` pushes is keyed on the receiver's ancestry, so under
- * composition the per-test frame belongs to the enclosing scope's line: a
- * collateral `fork()` taken inside a test resolves against the outermost frame
- * on its own line instead. That is the ordinary ancestry rule — siblings never
- * see each other's frames, and the outward walk supplies the outer ones — not a
- * special case here.
+ * The per-test wrap is entered on `context.scope()`, so it governs that
+ * instance and its ancestors: the integrated instance when nothing encloses
+ * it, and that instance as an ancestor of the enclosing scope when something
+ * does. It does not govern forks of the integrated instance. Per-test data
+ * therefore comes from the instance handed to `integration(...)`, from
+ * `context.fabricator`, or from a fork of that scope — a module-level fork of
+ * the integrated instance draws the same data in every test, and because its
+ * construction counter runs across tests, which values a test gets depends on
+ * which tests ran before it.
  *
  * `provides.fabricator` is then that scope — the instance `wrap` gave its
  * block, not the base instance — so `context.fabricator.salt` is the per-test

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

@@ -3,8 +3,8 @@ import type { PlainObject } from "../Utility/Types";
 /**
  * What identifies one registered test or suite — the material a salt is derived
  * from. Named to match how this codebase already talks about the concept:
- * fabricator's own reproducibility guide reaches for `layer(...)` for "a tenant
- * id, a test's own name" — this is that identity, structured.
+ * fabricator's own reproducibility guide reaches for `layer(...)` for "a test's
+ * own name" — this is that identity, structured.
  *
  * Declared here rather than imported from `@ghostry/harness`, so neither
  * package depends on the other — the same arrangement `Adapter`/`walk` already

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

@@ -5,12 +5,16 @@ import type { Ancestry, Frame, Stack } from "../Types";
  * 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.
  *
+ * A wrap governs the instance it was called on and that instance's ancestors,
+ * never its descendants: `governs` is a prefix test in that one direction.
  * 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.
+ *
+ * It filters the whole chain rather than walking in from the innermost frame
+ * and stopping at the first that does not govern the reader, because a
+ * governing frame can sit beneath one that does not: with `B`'s wrap open and
+ * `C`'s nested inside it, `B` must pass over `C`'s frame and still resolve
+ * against its own.
  */
 export declare function toVisible(frames: ReadonlyArray<Frame>, ancestry: Ancestry): ReadonlyArray<Frame>;
 /**

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

@@ -69,19 +69,19 @@ export type Token = symbol & {
  * 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.
+ * {@link Stack.visible} tests whether the reader is the wrap's receiver or one
+ * of that receiver's ancestors — the reader's chain a prefix of the frame's. A
+ * parent's constructions resolve against a wrap entered on a child; a child's
+ * constructions do not resolve against a wrap entered on a parent. Two siblings
+ * resolve against neither's. The relation 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 on the origin's ancestral line consulting the frame) or explicitly
+ * build reached inside that `wrap` shares, whether reached implicitly (the
+ * receiver and its ancestors 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 —
@@ -93,11 +93,12 @@ export type Ancestry = readonly [Token, ...ReadonlyArray<Token>];
  * 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.
+ * scope's, and {@link Stack.visible} governs that origin and its ancestors. Not
+ * load-bearing for who is governed: keyed on the scope, the frame would govern
+ * the same instances plus the scope itself, which resolves against this very
+ * `source` either way. What it decides is the scope's own `context.depth` — 0,
+ * since the scope is a descendant of the origin and not among those the frame
+ * governs.
  */
 export type Frame = {
     readonly config: Config<PlainObject>;
@@ -132,23 +133,21 @@ export type Stack = {
     readonly asynchronous: boolean;
     /**
      * 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`.
+     * whose receiver this instance is, or is an ancestor of — this chain a prefix
+     * of the frame's. 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.
+     * 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.
+     * correctly even if `block` throws. Appends rather than replaces: nested
+     * wraps are a chain, and {@link visible} reports every frame this reader is
+     * governed by, not only the innermost.
      */
     enter<$Return>(frame: Frame, block: () => $Return): $Return;
 };
@@ -188,11 +187,13 @@ export type Context = {
      */
     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.
+     * How many frames currently govern this instance — 0 outside any. Genuine
+     * dynamic nesting depth, counted off the carrier rather than inferred from
+     * {@link Ancestry}: a wrap entered on a descendant is counted (this instance
+     * is an ancestor of that receiver), a wrap entered on a sibling or an
+     * ancestor is not, and entering two `wrap`s on one instance reads as 2 even
+     * though neither deepened anyone's ancestry. A wrap's own `scope` is a
+     * descendant of the receiver, so its depth inside that wrap is 0.
      */
     readonly depth: number;
 };
@@ -280,7 +281,7 @@ export interface Instance<$Registry extends PlainObject> extends Pick<RandomSour
     /**
      * `fork(overlay)`, made ambient for the synchronous extent of `block`: every
      * `new Fabricator(...)`, `combinatorial(...)`, and `coverage(...)` reached
-     * inside — on this instance or any other in the same lineage — resolves
+     * inside — on this instance, and on this instance's ancestors — resolves
      * against the fork instead, with nothing threaded through. The fork is also
      * passed to `block`: use it explicitly where that reads better, and
      * _necessarily_ for any async work, which the ambient frame does not survive
@@ -294,11 +295,11 @@ export interface Instance<$Registry extends PlainObject> extends Pick<RandomSour
      * 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
+     * While the block runs, calls on this instance and its ancestors resolve
+     * against the scope. Calls on a descendant — a fork of this instance, or the
+     * wrap's own scope — draw that instance's own configuration; so does a
+     * sibling. The scope still shares one `RandomSource` with this instance
+     * inside the wrap, so ambient and explicit construction agree. See
      * {@link Ancestry}.
      */
     wrap<$Return, const $WrapRegistry extends PlainObject = $Registry>(overlay: Overlay<$WrapRegistry>, block: (scope: Instance<$WrapRegistry>) => $Return): $Return;

package/package.json

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