@ghostry/fabricator 0.0.2 → 0.0.4

package/dist/esm/Random/index.js

@@ -1,85 +1,53 @@
-import { FabricatorError } from "../Error/index.js";
 import { Layer, MAX_TIME } from "../Types.js";
-import { inline } from "../Utility/Core.js";
 import { cyrb128 } from "../Utility/Digest.js";
-import { directoryOf, normalizeLocation, relativize, resolveCallerFile } from "./CallSite.js";
 import { sfc32 } from "./Generator/sfc32.js";
 function defaultAlgorithm(seed) {
     return sfc32(...cyrb128(seed));
 }
-function randomSeed() {
+function randomSalt() {
     return (0x100000000 * Math.random() >>> 0).toString(10);
 }
-function deriveClock(algorithm, seed) {
+function deriveClock(algorithm, salt) {
     const stream = toStream(algorithm, JSON.stringify([
-        seed,
+        salt,
         "clock"
     ]));
     return Math.trunc((2 * stream.next() - 1) * MAX_TIME);
 }
-function envSeed() {
-    var _ref, _ref1;
+function envSalt() {
     const env = "object" == typeof process ? process.env : void 0;
-    return null != (_ref = null != (_ref1 = null == env ? void 0 : env["FABRICATOR_SEED"]) ? _ref1 : null == env ? void 0 : env["SEED"]) ? _ref : null == env ? void 0 : env["RANDOM_SEED"];
+    return null == env ? void 0 : env["FABRICATOR_SALT"];
 }
 function encode(trace) {
     return JSON.stringify([
-        trace.seed,
+        trace.salt,
         trace.clock,
-        trace.root,
-        trace.file,
         trace.path,
         trace.kind,
         trace.ordinal
     ]);
 }
-function normalizeSeed(seed) {
-    if (void 0 === seed) {
-        const fromEnv = envSeed();
+function normalizeSalt(salt) {
+    if (void 0 === salt) {
+        const fromEnv = envSalt();
         return void 0 === fromEnv ? [] : [
             fromEnv
         ];
     }
-    return "string" == typeof seed ? [
-        seed
+    return "string" == typeof salt ? [
+        salt
     ] : [
-        ...seed
+        ...salt
     ];
 }
-function Random_layer(seed) {
+function Random_layer(salt) {
     return {
-        [Layer]: seed
+        [Layer]: salt
     };
 }
 function isLayered(value) {
     return "object" == typeof value && null !== value && Layer in value;
 }
-function resolveAttribution(attribution) {
-    const policy = null != attribution ? attribution : {
-        kind: "call site"
-    };
-    switch(policy.kind){
-        case "none":
-            return policy;
-        case "rooted":
-            {
-                const root = normalizeLocation(policy.root);
-                if (!root.startsWith("/")) throw new FabricatorError.InvalidAttributionRootError(policy.root);
-                return toRooted(root);
-            }
-        case "call site":
-            {
-                const root = directoryOf(resolveCallerFile());
-                return toRooted(root);
-            }
-    }
-}
-function toRooted(root) {
-    return {
-        kind: "rooted",
-        root: root.endsWith("/") ? root : `${root}/`
-    };
-}
 function toStream(algorithm, seed) {
     const generator = algorithm(seed);
     let iterations = 0;
@@ -99,53 +67,30 @@ function toStreamFromTrace(algorithm, trace) {
 }
 function toRandomSource(options) {
     var _options_algorithm;
-    let seed = normalizeSeed(options.seed);
+    let salt = normalizeSalt(options.salt);
     let algorithm = null != (_options_algorithm = options.algorithm) ? _options_algorithm : defaultAlgorithm;
-    let attribution = resolveAttribution(options.attribution);
     const clock = options.clock;
-    let constructionOrdinals = new Map();
-    function nextConstructionOrdinal(file) {
-        var _constructionOrdinals_get;
-        const ordinal = null != (_constructionOrdinals_get = constructionOrdinals.get(file)) ? _constructionOrdinals_get : 0;
-        constructionOrdinals.set(file, ordinal + 1);
-        return ordinal;
-    }
-    function toRoot(kind, pins = {}) {
-        var _pins_root, _pins_clock;
-        const replaying = void 0 !== pins.root;
-        const root = null != (_pins_root = pins.root) ? _pins_root : kind;
-        const file = replaying || void 0 !== pins.file ? pins.file : resolveRootFile(kind);
-        const ordinal = inline(()=>{
-            if (replaying || void 0 !== pins.ordinal) return pins.ordinal;
-            if ("unattributed" === root) return;
-            return nextConstructionOrdinal(file);
-        });
+    let constructionOrdinal = 0;
+    function toConstructionTrace(pins = {}) {
+        var _pins_salt, _pins_clock;
         return {
-            seed,
+            salt: null != (_pins_salt = pins.salt) ? _pins_salt : salt,
             clock: null != (_pins_clock = pins.clock) ? _pins_clock : clock,
-            root,
-            file,
-            ordinal
+            ordinal: void 0 !== pins.ordinal ? pins.ordinal : constructionOrdinal++
         };
     }
-    function resolveRootFile(kind) {
-        if ("attributed" !== kind) return;
-        if ("none" === attribution.kind) return;
-        return relativize(attribution.root, resolveCallerFile());
-    }
-    function fork(childSeed) {
+    function fork(childSalt) {
         return toRandomSource({
-            seed: childSeed,
+            salt: childSalt,
             algorithm,
-            attribution,
             clock
         });
     }
     return {
-        toRoot,
+        toConstructionTrace,
         algorithm,
-        seed,
+        salt,
         fork
     };
 }
-export { Random_layer as layer, defaultAlgorithm, deriveClock, encode, isLayered, normalizeSeed, randomSeed, resolveAttribution, toRandomSource, toStream, toStreamFromTrace };
+export { Random_layer as layer, defaultAlgorithm, deriveClock, encode, isLayered, normalizeSalt, randomSalt, toRandomSource, toStream, toStreamFromTrace };

package/dist/esm/adapting.js

@@ -0,0 +1,2 @@
+export { walk } from "./Adapter/Core.js";
+export { Adaptation } from "./Types.js";

package/dist/esm/harnessing.js

@@ -0,0 +1 @@
+export { integration } from "./Harnessing/Core.js";

package/dist/esm/index.js

@@ -4,10 +4,9 @@ function initialize(config) {
     var _ref;
     return instantiate(overlay({}, null != config ? config : {}), null != (_ref = null == config ? void 0 : config.stack) ? _ref : toStack()).instance;
 }
-export { Adaptation, Omitted } from "./Types.js";
+export { Omitted } from "./Types.js";
 export { layer } from "./Random/index.js";
 export { FabricatorError } from "./Error/index.js";
-export { drive } from "./Adapter/Core.js";
 export { registry } from "./Schema/Registry.js";
 export { effectiveDiscrete, toBound } from "./Bound.js";
 export { initialize };

package/dist/esm/internal.js

@@ -1,6 +1,5 @@
 export { Children, Kind, Meta, Produces } from "./Types.js";
 export { isPlainObject } from "./Utility/Core.js";
 export { plan, resolve } from "./Enumeration/Plan.js";
-export { defaultAlgorithm, encode, randomSeed, toRandomSource, toStream, toStreamFromTrace } from "./Random/index.js";
-export { directoryOf, normalizeLocation, relativize, resolveCallerFile } from "./Random/CallSite.js";
+export { defaultAlgorithm, encode, randomSalt, toRandomSource, toStream, toStreamFromTrace } from "./Random/index.js";
 export { toStack as toSynchronousStack } from "./Instance/Stack/Sync.js";

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

@@ -55,7 +55,7 @@ export declare function mergeAdaptations<$Prior extends Adaptations, const $Adap
  * previous one into the argument. Splitting the two across packages is how they
  * drift.
  */
-export declare function drive<$Context, $Returnable>(adapter: Adapter<string, $Context, $Returnable>, schema: {
+export declare function walk<$Context, $Returnable>(adapter: Adapter<string, $Context, $Returnable>, schema: {
     [Adaptation]?: Adaptations;
 }, context: $Context): $Returnable;
 export {};

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

@@ -70,7 +70,7 @@ export type Patch = {
 };
 /**
  * How an adapter recurses into a nested schema — handed to
- * {@link Adapter.convert} by `Adapter/Core.ts`'s `drive` rather than being the
+ * {@link Adapter.convert} by `Adapter/Core.ts`'s `walk` rather than being the
  * adapter's own private recursion, so every nested node goes back through the
  * adaptation lookup, not only the outermost one.
  *

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

@@ -1,33 +1,35 @@
-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 seeds — one per API — each an independent, deterministic fork off
- * the _effective_ source's seed (`effectiveSource()` below — the active `wrap`
- * frame's, or this instance's `source`; read fresh on every
+ * Two derived salts — one per API — each composed from the _effective_ source's
+ * 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 an
- * active `wrap`). `new Fabricator(schema, { seed })` (see `Constructor.ts`'s
- * `construct()`) forks a fully isolated `RandomSource` and opens an
- * `"unattributed"` scope, so `resolveCallerFile()` is never called — the
- * lazy-generator attribution hazard a plain `function*` would invite simply
- * doesn't arise — the instance's construction counters are never touched, and
- * the same seed reproduces regardless of which file
- * `combinatorial(...)`/`coverage(...)` is called from. Each `fork()` starts
- * from a fresh source, so reusing one seed across many builds (different
- * schemas, or the same schema rebuilt per iteration) never lets one build's
- * draws leak into another's.
+ * 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
+ * next ordinal from the effective source's counter — advancing it for every
+ * later construction, and giving each pass over the `Iterable` a different
+ * ordinal. A pinned ordinal is taken verbatim, so the counter is untouched,
+ * 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/Error/index.d.ts

@@ -45,25 +45,6 @@ export declare namespace FabricatorError {
          */
         limit: unknown);
     }
-    /**
-     * `initialize({ attribution: { kind: "rooted", root } })` when `root` is not
-     * an absolute path or a `file://` URL. A relative root can never prefix a
-     * resolved caller file, so `relativize` would leave every file unchanged —
-     * the option would look configured while silently doing nothing. Thrown
-     * eagerly at `initialize()`, not deferred to wherever that would first become
-     * observable.
-     */
-    class InvalidAttributionRootError extends FabricatorError {
-        /**
-         * The rejected root, as given.
-         */
-        readonly root: string;
-        constructor(
-        /**
-         * The rejected root, as given.
-         */
-        root: string);
-    }
     /**
      * A `self` placeholder resolved with no `T.recursive` expanding around it —
      * only reachable by holding a `self` reference outside the `T.recursive(...)`
@@ -556,4 +537,19 @@ export declare namespace FabricatorError {
     class SynchronousStackError extends FabricatorError {
         constructor();
     }
+    /**
+     * The `fabricator` provider of `integration(instance)`
+     * (`@ghostry/fabricator/harnessing`) was called outside that integration's
+     * own `around`.
+     *
+     * The provider hands back the per-test scope `around` just entered, so there
+     * is no scope for it to return anywhere else. `@ghostry/harness` never does
+     * this — it runs each provider inside its integration's `around` — so this
+     * means a composer that breaks the contract. Raised rather than returning the
+     * base instance, which would draw plausible data from the wrong configuration
+     * with no signal.
+     */
+    class HarnessingProviderError extends FabricatorError {
+        constructor();
+    }
 }

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";
@@ -11,9 +11,9 @@ import { type AsFabricator } from "./Types";
  * `function` that explicitly returns an object, so `new construct(schema)`
  * behaves identically to `construct(schema)` — a `new` call's returned object
  * always replaces the freshly-created `this`. The construct signature lets
- * callers spell `new T.Fabricator(schema)` — or `new Fabricator(schema, { seed
- * })` to pin this one build to an explicit seed, independent of the file it's
- * constructed in (see `construct()` for what `options.seed` does).
+ * callers spell `new T.Fabricator(schema)` — or `new Fabricator(schema, { salt
+ * })` to pin this one build's salt slot, leaving every other slot to resolve as
+ * usual (see `construct()` for what `options.salt` does).
  */
 export type Constructor = {
     new <const $Schema extends Buildable>(schema: $Schema, options?: ConstructorOptions): AsFabricator<$Schema>;
@@ -23,19 +23,22 @@ export type Constructor = {
  * internal `convert(schema: any)` — and the precisely-typed `construct()`
  * boundary around it, both closed over a single instance's `source` so every
  * fabricator this `construct()` produces draws from that instance's own
- * seed/streams and never another instance's.
+ * 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/Harnessing/Core.d.ts

@@ -0,0 +1,43 @@
+import type { Instance } from "../Instance/Types";
+import type { PlainObject } from "../Utility/Types";
+import type { FabricatorTestContext, Integration } from "./Types";
+/**
+ * Decorate an existing `Instance` as a `@ghostry/harness` integration.
+ * `around(identity, body)` is `instance.wrap({ salt: layer(saltFor(identity))
+ * })` — one line of real work. Construction ordinals therefore restart per test
+ * (each `wrap` re-instantiates), which is what makes `.only`, filters, shards,
+ * and `.concurrent` unable to shift a neighbor's data. That per-test
+ * partitioning is also why the salt needs no file in it; see `saltFor`
+ * (`Harnessing/Salt.ts`).
+ *
+ * `around`, not `setup`: the ambient frame has to enclose the body, and only
+ * `around` does. Its `finally` running at the call boundary rather than at test
+ * settlement costs nothing here — there is no teardown, and the
+ * `AsyncLocalStorage` carrier keeps the frame alive across the body's `await`s
+ * regardless of when `wrap` returns. On the synchronous carrier an async body
+ * still raises `SynchronousStackError` from `wrap`. Declaring no `setup` also
+ * keeps `@ghostry/harness` on its uninstrumented path, where a synchronous
+ * assertion failure is reported at the user's own line.
+ *
+ * `provides.fabricator` hands back the scope `wrap` gave its block, not the
+ * base instance, so `context.fabricator.salt` is the per-test salt and
+ * `.fork()` forks from the test's configuration. The two calls meet through
+ * `scope`: set just before `body()`, read by the provider, restored in a
+ * `finally`. That is safe under `.concurrent` because `@ghostry/harness` runs a
+ * provider synchronously inside its own integration's `around` — no other test
+ * can enter between the write and the read, and the context object already
+ * holds the scope by the body's first `await`. Restoring rather than clearing
+ * keeps a nested `around` from dropping its parent's scope. A provider reached
+ * with no scope is a composer breaking that contract, and raises
+ * `HarnessingProviderError` rather than quietly providing the base instance.
+ *
+ * Nothing here reads `instance.context`. The integration is a pure function of
+ * the `Identity` it is handed and the instance it decorates, and never sets
+ * `clock`. A pinned `Date` (the recommended setup) and the wall-clock default
+ * are already concrete numbers by the time `overlay()` sees them, so they
+ * inherit through every `wrap` unchanged: salt varies per test, "now" does not.
+ * `clock: "derived"` is left alone on purpose — that policy's documented
+ * meaning is that the salt _is_ the reproducibility unit, so per-test clocks
+ * are the request honored, not a bug to override.
+ */
+export declare function integration<$Registry extends PlainObject>(instance: Instance<$Registry>): Integration<FabricatorTestContext<$Registry>>;

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

@@ -0,0 +1,31 @@
+import type { Identity } from "./Types";
+/**
+ * The salt `integration` layers onto the instance for one `Identity`.
+ *
+ *     [ <kind>, ...<describe names>, <name>, <row?> ]
+ *
+ * **No file, deliberately.** Every test body runs inside its own
+ * `instance.wrap`, which builds a fresh `RandomSource` with a fresh
+ * construction counter, so constructions are already partitioned per test.
+ * Identity comes from a path, never from an execution counter or a location
+ * that moves when a file does.
+ *
+ * The accepted cost: two tests with the same `kind`, describe path, and name in
+ * _different files_ share a salt and therefore draw the same data. Each is
+ * still deterministic. That is the same trade already made in dropping
+ * duplicate-path detection, and the fix is the ordinary one — give them
+ * distinguishable names.
+ *
+ * `kind` leads. Without it, an empty-named test collides with its enclosing
+ * suite scope: `path` never carries a leaf's own name, only its describes, and
+ * `name` is `""` for both a `"suite"` identity (by design — see `Identity`) and
+ * any test a user happens to name `""`, so at the same `path` the two arrays
+ * would otherwise be identical. `kind` does not disambiguate two suite
+ * identities that share a `path` (a `beforeAll` and an `afterAll` in one
+ * `describe`, say) — that collision is intentional, a suite's setup and
+ * teardown sharing one deterministic scope, and a caller who wants otherwise
+ * already has `instance.wrap(...)` inside the hook body.
+ *
+ * The row is appended only for `.each`.
+ */
+export declare function saltFor(identity: Identity): ReadonlyArray<string>;

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

@@ -0,0 +1,79 @@
+import type { Instance } from "../Instance/Types";
+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.
+ *
+ * Declared here rather than imported from `@ghostry/harness`, so neither
+ * package depends on the other — the same arrangement `Adapter`/`walk` already
+ * uses for schema adapters. Satisfied structurally.
+ *
+ * **Carries no file, deliberately.** Nothing here identifies where the test was
+ * registered, which is what lets `@ghostry/harness` skip stack walking entirely
+ * — see `saltFor` (`Harnessing/Salt.ts`) for why the file turned out to be
+ * redundant against per-test `wrap` partitioning. The consequence for the
+ * contract: an integration that genuinely needs the registering file cannot get
+ * it from here, and adding it back means solving the frame-skip problem for
+ * every wrapper between the user's `it(...)` and the integration. Worth
+ * revisiting only against a real requirement, not speculatively.
+ */
+export type Identity = {
+    /**
+     * Disambiguates an empty-named test from its enclosing suite scope — `name`
+     * is `""` for both, and `path` never carries a leaf's own name. Two suite
+     * identities that share a `path` (`beforeAll` and `afterAll` in one
+     * `describe`) are not disambiguated by this: that collision is intentional
+     * (see `saltFor`, `Harnessing/Salt.ts`).
+     */
+    readonly kind: "test" | "suite";
+    /** Enclosing describe names, outer → inner. */
+    readonly path: ReadonlyArray<string>;
+    /** The test name; empty for a suite-scoped callback. */
+    readonly name: string;
+    /** `.each` row index (0-based), `undefined` when the test is not from `.each`. */
+    readonly row: number | undefined;
+};
+/**
+ * One context key's value, as a function of the test's `Identity` rather than a
+ * fixed value.
+ */
+export type Provider<$Value> = (identity: Identity) => $Value;
+/**
+ * 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]>;
+};
+/**
+ * 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.
+ *
+ * `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.
+ */
+export type Integration<$Context extends object> = {
+    readonly name: string;
+    readonly provides: Provides<$Context>;
+    around<$Return>(identity: Identity, body: () => $Return): $Return;
+};
+/**
+ * The slice of the test context `integration(instance)` contributes — one key,
+ * `fabricator`, holding the per-test scoped `Instance`. The same instance is
+ * also ambient for the body's duration (`instance.wrap`), so a body that
+ * ignores this and uses the caller's own `instance` still sees the per-test
+ * salt.
+ */
+export type FabricatorTestContext<$Registry extends PlainObject = PlainObject> = {
+    readonly fabricator: Instance<$Registry>;
+};