@ghostry/fabricator 0.0.4 → 0.0.6

package/dist/esm/Error/index.js

@@ -201,7 +201,7 @@ class Error_FabricatorError extends Error {
         constructor(){
             super();
             this.name = "HarnessingProviderError";
-            this.message = "The `fabricator` provider was called outside its integration's `around`, so there is no per-test scope to provide. A composer must run each integration's providers inside that integration's `around` frame, as `@ghostry/harness` does.";
+            this.message = "The `fabricator` provider was called outside its integration's frame, so there is no per-test scope to provide. A composer must run each integration's providers inside the frame it opened, passing forward what that frame's wrapper established, as `@ghostry/harness` does.";
         }
     }
     FabricatorError.HarnessingProviderError = HarnessingProviderError;

package/dist/esm/Harnessing/Core.js

@@ -2,28 +2,19 @@ import { FabricatorError } from "../Error/index.js";
 import { layer as index_js_layer } from "../Random/index.js";
 import { saltFor } from "./Salt.js";
 function integration(instance) {
-    let scope;
     return {
         name: "@ghostry/fabricator",
         provides: {
-            fabricator: ()=>{
-                if (void 0 === scope) throw new FabricatorError.HarnessingProviderError();
-                return scope;
+            fabricator: ({ established: instance })=>{
+                if (void 0 === instance) throw new FabricatorError.HarnessingProviderError();
+                return instance;
             }
         },
-        around (identity, body) {
+        *frame ({ identity }) {
             const salt = index_js_layer(saltFor(identity));
-            return instance.wrap({
-                salt
-            }, (entered)=>{
-                const previous = scope;
-                scope = entered;
-                try {
-                    return body();
-                } finally{
-                    scope = previous;
-                }
-            });
+            yield (body)=>instance.context.scope().wrap({
+                    salt
+                }, body);
         }
     };
 }

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

@@ -7,7 +7,7 @@ import type { PlainObject } from "../Utility/Types";
  * is the cartesian product — width is the product of every child's width;
  * `at(index)` mixed-radix decodes to a full combination (`combinatorial`).
  * `"cycle"` (`coverage`) takes the widest child as the composite's width,
- * cycling narrower children to fill it — see CLAUDE.md's "sum vs product" note
+ * cycling narrower children to fill it — see AGENTS.md's "sum vs product" note
  * for why cycling only ever applies to `object`/`tuple` and never to a sum node
  * (`choice`, the presence wrappers), which always total their children's widths
  * regardless of strategy.
@@ -17,7 +17,7 @@ export type Strategy = "product" | "cycle";
  * A fresh, reproducible permutation of `0..width-1` each call — one per
  * width-`>1` node `plan()` visits, in walk order, so two nodes of the same
  * width never receive the same permutation (which would otherwise iterate them
- * in lockstep — see CLAUDE.md's note on why a constant phase offset isn't
+ * in lockstep — see AGENTS.md's note on why a constant phase offset isn't
  * enough). Only consulted under `"cycle"`; `"product"`'s mixed-radix decode
  * already visits every combination, so permuting there would only reorder
  * identical output. Built in `Enumerate.ts` (which can reach `Random/`), then

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

@@ -540,14 +540,15 @@ export declare namespace FabricatorError {
     /**
      * The `fabricator` provider of `integration(instance)`
      * (`@ghostry/fabricator/harnessing`) was called outside that integration's
-     * own `around`.
+     * own frame.
      *
-     * 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.
+     * The provider hands back the per-test scope the frame's wrapper established,
+     * which reaches it as the provider's second argument, so there is no scope
+     * for it to return anywhere else. `@ghostry/harness` never does this — it
+     * runs each provider inside the frame it opened and passes that scope forward
+     * — 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/Harnessing/Core.d.ts

@@ -2,42 +2,59 @@ 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`
+ * Decorate an existing `Instance` as a `@ghostry/harness` integration. The
+ * whole of it is `context.scope().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.
+ * `frame` is a generator so that `yield` can be both where the body runs and
+ * where this hook waits. There is nothing after the `yield` here: fabricator
+ * has no teardown, and the `AsyncLocalStorage` carrier keeps the ambient frame
+ * alive across the body's `await`s on its own. What the `yield` carries is the
+ * wrapper, because the ambient frame has to _enclose_ the body rather than
+ * merely precede it. On the synchronous carrier an async body still raises
+ * `SynchronousStackError` from `wrap`.
  *
- * `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
+ * `body` is handed to `wrap` directly rather than called inside a closure.
+ * `wrap(overlay, block)` already takes `(scope) => $Return`, which is exactly
+ * the wrapper's own `(established) => $Return`, so the scope `wrap` opens _is_
+ * the established value with nothing in between to adapt it.
+ *
+ * `context.scope()`, not `instance`, is the receiver. A plain `instance.wrap`
+ * lays its overlay over the instance it was called on, and that receiver is
+ * bound before any test runs — so an integration composed _inside_ another
+ * library's fabricator scope would restate from the configured instance and
+ * drop that enclosing scope entirely, silently, while still landing innermost
+ * and therefore governing every draw. `context.scope()` is the frame in effect,
+ * or the instance itself when there is none, which is this integration's
+ * contract in both cases with no branch. Called fresh here rather than hoisted:
+ * `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.
+ *
+ * `provides.fabricator` is then that scope — the instance `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. Nothing mediates
+ * between the two: the wrapper hands the scope forward and the provider
+ * receives it. A provider reached with no established scope is a composer
+ * running providers outside the frame it opened, 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.
+ * Nothing here 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` — the frame in effect's included:
+ * 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>>;
+export declare function integration<$Registry extends PlainObject>(instance: Instance<$Registry>): Integration<FabricatorTestContext<$Registry>, Instance<$Registry>>;

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/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/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/harnessing.d.ts

@@ -11,20 +11,32 @@
  * package's contract this integration uses, satisfied structurally, so neither
  * depends on the other.
  *
+ * **Mirrors the integration contract of `@ghostry/harness` 0.0.4.** Structural
+ * satisfaction is what keeps the two packages independent, and it is also what
+ * leaves nothing to check the pairing at install time: neither manifest names
+ * the other, so a mismatched pair is caught by `tsc` at the point a consumer
+ * passes `integration(instance)` to `initialize`, with an error about shapes
+ * rather than about versions. This line is the only record of which version the
+ * copy tracks, so move it whenever that contract does — the types below are
+ * where the drift actually lives.
+ *
  * @module
  */
 /**
  * Decorate an existing `Instance` as a `@ghostry/harness` integration — `{
- * name, provides, around }`. Takes an instance rather than minting one: the
+ * name, provides, frame }`. Takes an instance rather than minting one: the
  * caller owns `initialize(...)` (and in particular the suite-wide `clock`), and
  * this only wraps each test body in that instance's per-identity `wrap`.
  */
 export { integration } from "./Harnessing/Core";
 /**
  * `Identity` is what identifies one registered test or suite; `Integration` is
- * the `{ name, provides, around }` shape `integration(instance)` returns —
- * `provides` is a `Provides<$Context>`, one `Provider` per context key;
- * `FabricatorTestContext` is the `{ fabricator }` slice of the test context
- * this integration contributes.
+ * the `{ name, provides, frame }` shape `integration(instance)` returns —
+ * `provides` is a `Provides<$Context, $Established>`, one `Provider` per
+ * context key, each handed what the frame's wrapper established; `Frame` is the
+ * generator `frame` returns and `Wrapper` the optional value it yields; both
+ * hooks take a single object — `FrameArgs` for `frame`, and `ProviderArgs`, the
+ * same thing plus `established`, for a provider; `FabricatorTestContext` is the
+ * `{ fabricator }` slice of the test context this integration contributes.
  */
-export type { FabricatorTestContext, Identity, Integration, Provider, Provides, } from "./Harnessing/Types";
+export type { FabricatorTestContext, Frame, FrameArgs, Identity, Integration, Provider, ProviderArgs, Provides, Wrapper, } from "./Harnessing/Types";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostry/fabricator",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "license": "MIT",
   "description": "Fabricate typed data from composable schemas.",
   "keywords": [
@@ -64,6 +64,9 @@
     "access": "public",
     "provenance": true
   },
+  "devDependencies": {
+    "@ghostry/harness": "^0.0.4"
+  },
   "scripts": {
     "build:reset": "rm -rf ./dist",
     "build:compile": "bunx --no-install --bun rslib build --config ./rslib.config.ts",