@ghostry/fabricator 0.0.1 → 0.0.3

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>;
+};

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

@@ -2,95 +2,59 @@ import type { RandomSource } from "../Random/Types";
 import type { PlainObject } from "../Utility/Types";
 import type { 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 enumerated instance costs a full build and
- * fabricate, so this is as much a wall-clock guard as a combinatorial
- * one.
+ * `combinatorial`'s default limit — `2**10`, so it admits ten independent
+ * binary axes before requiring the caller to raise it explicitly. Each
+ * enumerated instance costs a full build and fabricate, so this is as much a
+ * wall-clock guard as a combinatorial one.
  */
 export declare const DEFAULT_COMBINATORIAL_LIMIT = 1024;
 /**
- * The single place a `Config` inherits from a base — `initialize` lays
- * its own config over an empty `{}` base (nothing to inherit, so every
- * field falls through to a hardcoded default: an empty seed, wall-clock
- * `clock`, the built-in algorithm, `resolveAttribution(undefined)`'s
- * `"call site"` resolution, the default registry, the default
- * combinatorial limit), and `fork` lays its overlay over the instance
- * it was called on (a full, already-resolved `Config`, so every field
- * has a real value to fall back to). `base` is typed
- * `Partial<Config<PlainObject>>` rather than `Config` specifically so
- * both calls go through the same function.
+ * The single place a `Config` inherits from a base — `initialize` lays its own
+ * config over an empty `{}` base (nothing to inherit, so every field falls
+ * through to a hardcoded default: an empty salt, wall-clock `clock`, the
+ * built-in algorithm, the default registry, the default combinatorial limit),
+ * and `fork` lays its overlay over the instance it was called on (a full,
+ * already-resolved `Config`, so every field has a real value to fall back to).
+ * `base` is typed `Partial<Config<PlainObject>>` rather than `Config`
+ * specifically so both calls go through the same function.
  *
- * `seed` composes onto the base rather than replacing it only when
- * tagged with `layer(...)` (`{@link isLayered}`) — a bare `seed` (the
- * ordinary meaning everywhere else in this library) replaces the
- * base's outright, and an omitted `seed` inherits the base's unchanged
- * (or, at the root, an empty mixer via `normalizeSeed(undefined)`,
- * unless an env var supplies one). Wall-clock `clock` is the default
- * entropy; `seed` is an optional mixer.
- *
- * `attribution` resolves through `resolveAttribution` at most once per
- * call, and only when it's actually needed:
- * - an explicit `over.attribution` always wins (resolved fresh, so
- *   `fork({ attribution: { kind: "call site" } })` roots at *that*
- *   call);
- * - otherwise an already-resolved `base.attribution` is reused as-is
- *   — never re-resolved, which keeps a fork from silently re-rooting
- *   `"call site"` at wherever `fork()` itself happens to be called
- *   (`resolveCallerFile()` skips this library's own frames, so calling
- *   it from here still lands on the user's call site either way);
- * - only when neither is available (the root case, `base.attribution`
- *   absent) does this fall back to resolving the `"call site"`
- *   default.
- * That also keeps `initialize({ attribution: { kind: "none" } })` — or
- * any other explicit override — from paying for a stack walk whose
- * result would be immediately discarded.
+ * `salt` composes onto the base rather than replacing it only when tagged with
+ * `layer(...)` (`{@link isLayered}`) — a bare `salt` (the ordinary meaning
+ * everywhere else in this library) replaces the base's outright, and an omitted
+ * `salt` inherits the base's unchanged (or, at the root, an empty mixer via
+ * `normalizeSalt(undefined)`, unless an env var supplies one). Wall-clock
+ * `clock` is the default entropy; `salt` is an optional mixer.
  *
  * `algorithm`/`types`: wholesale replacement when given, matching how
  * `initialize({ types })` already behaves — no deep merge;
  * `registry.extend(...)` is the existing tool for that. `limits` is
  * re-validated through `resolveCombinatorialLimit` whenever given (or
- * inherited, or defaulted), so a bad limit fails at
- * `fork()`/`initialize()` time rather than at first use. `clock`
- * follows the given → inherited → default shape `algorithm` does, but
- * stays *unresolved* only for the explicit `"seeded"` sentinel: an
- * explicit `Date` and the unconfigured wall-clock default are stored
- * as epoch milliseconds (a stated instant, inherited as-is from then
- * on), while `"seeded"` is left as the sentinel rather than collapsed
- * to a number, so `resolveClock` can re-derive it from whichever
- * `seed` is actually in effect at read time. An omitted `clock` on a
- * `fork`/`wrap` whose seed changed therefore keeps the parent's
- * instant unless that parent was itself `"seeded"`.
+ * inherited, or defaulted), so a bad limit fails at `fork()`/`initialize()`
+ * time rather than at first use. `clock` follows the given → inherited →
+ * default shape `algorithm` does, but stays _unresolved_ only for the explicit
+ * `"derived"` sentinel: an explicit `Date` and the unconfigured wall-clock
+ * default are stored as epoch milliseconds (a stated instant, inherited as-is
+ * from then on), while `"derived"` is left as the sentinel rather than
+ * collapsed to a number, so `resolveClock` can re-derive it from whichever
+ * `salt` is actually in effect at read time. An omitted `clock` on a
+ * `fork`/`wrap` whose salt changed therefore keeps the parent's instant unless
+ * that parent was itself `"derived"`.
  */
 export declare function overlay<$Registry extends PlainObject>(base: Partial<Config<PlainObject>>, over: Overlay<$Registry>): Config<$Registry>;
-/**
- * Builds a `Stack`: closes over a private `Frame[]`, pushing on `enter`
- * and popping in a `finally` — correct even around a `throw` from
- * `block`. One per root `initialize()`, threaded — never re-created —
- * through every `fork`/`wrap` descended from it, so it stays
- * per-lineage rather than module-level: two unrelated `initialize()`
- * calls each get their own stack and can never perturb each other,
- * while every instance sharing one stack (a fork included, no matter
- * where in the lineage it was created) resolves against the same
- * active frame.
- */
-export declare function toStack(): Stack;
 /**
  * The shared body `initialize` and `fork` both reduce to: build a
  * `RandomSource` from an already-resolved `Config`, then everything an
- * `Instance` exposes off of it. Returns the `RandomSource` alongside
- * the `Instance` — `initialize`/`fork` discard it, `wrap` keeps it to
- * stash on the `Frame` it pushes, so implicit (ambient) and explicit
- * (`scope.Fabricator`) construction inside one `wrap` resolve against
- * the very same source rather than each independently re-deriving one
- * from the same config (and so silently diverging/duplicating
- * construction ordinals).
+ * `Instance` exposes off of it. Returns the `RandomSource` alongside the
+ * `Instance` — `initialize`/`fork` discard it, `wrap` keeps it to stash on the
+ * `Frame` it pushes, so implicit (ambient) and explicit (`scope.Fabricator`)
+ * construction inside one `wrap` resolve against the very same source rather
+ * 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` 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.
  */
 export declare function instantiate<$Registry extends PlainObject>(config: Config<$Registry>, stack: Stack): {
     instance: Instance<$Registry>;

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

@@ -0,0 +1,14 @@
+import type { Stack } from "../Types";
+/**
+ * The asynchronous carrier, and the **only** module in this package importing
+ * anything from `node:`. Nothing imports it directly: `Instance/Core.ts`
+ * imports `#stack`, whose `node`/`bun`/`deno` conditions (`package.json`)
+ * resolve here while `default` resolves to `./sync.ts`. That is what keeps the
+ * package importable on a runtime with no `node:async_hooks` while every
+ * runtime that has one gets async-safe `wrap` with nothing to configure.
+ *
+ * `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.
+ */
+export declare function toStack(): Stack;

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

@@ -0,0 +1,14 @@
+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`.
+ *
+ * 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.
+ * Both are why `asynchronous` is `false` and `wrap` refuses an async block here
+ * rather than resolving it against the base instance with no signal.
+ */
+export declare function toStack(): Stack;

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

@@ -1,85 +1,85 @@
 import type { Enumerable, Limits } from "../Enumeration/Types";
 import type { Constructor } from "../Fabricator/Constructor";
-import type { Algorithm, Attribution, Layered, RandomSource, Seed } from "../Random/Types";
+import type { Algorithm, Layered, RandomSource, Salt } from "../Random/Types";
 import type { PlainObject } from "../Utility/Types";
 /**
- * A fully resolved instance configuration — every field present, nothing
- * left to default. `Overlay` is what `fork` accepts; `overlay()`
+ * A fully resolved instance configuration — every field present, nothing left
+ * to default. `Overlay` is what `fork` accepts; `overlay()`
  * (`Instance/Core.ts`) is the only thing producing a complete `Config`.
  *
- * Two fields are declared at their caller-facing type but always hold
- * their resolved form once `overlay()` has run: `seed` is `Seed` because
- * that is what a caller may supply, but always holds the normalized
- * array (`Instance.seed` is the authoritative read); `attribution` is
- * `Attribution` for the same reason but always holds a
- * `ResolvedAttribution`, a subtype. `clock` is different from both:
- * unlike `seed`/`attribution`, it holds *either* a resolved instant
- * (epoch milliseconds) or the unresolved `"seeded"` policy — never
- * collapsed to a number by `overlay()` when `"seeded"`, because that
- * policy must re-derive whenever the seed it composes changes (a
- * `fork({ seed: layer(...) })`). The unconfigured default is a wall-
- * clock number, inherited as-is like an explicit `Date`. `resolveClock`
- * (`Instance/Core.ts`) is the one place that resolves `"seeded"` to a
- * number, called fresh wherever the clock actually matters
- * (`instantiate`, the `context.clock` getter) rather than once here.
+ * `salt` is declared at its caller-facing `Salt` type but always holds the
+ * normalized array once `overlay()` has run (`Instance.salt` is the
+ * authoritative read). `clock` holds _either_ a resolved instant (epoch
+ * milliseconds) or the unresolved `"derived"` policy — never collapsed to a
+ * number by `overlay()` when `"derived"`, because that policy must re-derive
+ * whenever the salt it composes changes (a `fork({ salt: layer(...) })`). The
+ * unconfigured default is a wall- clock number, inherited as-is like an
+ * explicit `Date`. `resolveClock` (`Instance/Core.ts`) is the one place that
+ * resolves `"derived"` to a number, called fresh wherever the clock actually
+ * matters (`instantiate`, the `context.clock` getter) rather than once here.
  */
 export type Config<$Registry extends PlainObject> = {
-    readonly seed: Seed;
+    readonly salt: Salt;
     readonly algorithm: Algorithm;
-    readonly attribution: Attribution;
     readonly types: $Registry;
     readonly limits: Limits;
-    readonly clock: number | "seeded";
+    readonly clock: number | "derived";
 };
 /**
- * What `fork` accepts — a `Config` to lay over a base, every field
- * optional. Identical to `Partial<Config>` but for `seed`, which
- * additionally accepts a {@link Layered}: a bare `Seed` replaces the
- * base's seed outright (what `seed` means everywhere else in this
- * library), `layer(seed)` appends onto it (`[...base.seed, ...seed]`)
- * — the shape a wrapping integration wants, and what
- * `ConstructorOptions`' layered form is for a single construction.
- * Omitting `seed` inherits the base's unchanged. `clock` similarly
- * accepts the caller-facing `Date | "seeded"` rather than `Config`'s
- * own resolved `number | "seeded"`, so a caller can hand in a literal
- * instant without converting it to epoch milliseconds themselves.
- * `"seeded"` is the explicit opt-in that derives "now" from the
- * instance seed; omitting `clock` at the root captures wall-clock time
- * instead.
+ * What `fork` accepts — a `Config` to lay over a base, every field optional.
+ * Identical to `Partial<Config>` but for `salt`, which additionally accepts a
+ * {@link Layered}: a bare `Salt` replaces the base's salt outright (what `salt`
+ * means everywhere else in this library), `layer(salt)` appends onto it
+ * (`[...base.salt, ...salt]`) — the shape a wrapping integration wants, and
+ * what `ConstructorOptions`' layered form is for a single construction.
+ * Omitting `salt` inherits the base's unchanged. `clock` similarly accepts the
+ * caller-facing `Date | "derived"` rather than `Config`'s own resolved `number
+ * | "derived"`, so a caller can hand in a literal instant without converting it
+ * to epoch milliseconds themselves. `"derived"` is the explicit opt-in that
+ * derives "now" from the instance salt; omitting `clock` at the root captures
+ * wall-clock time instead.
  *
- * `initialize`'s own parameter keeps a plain `seed?: Seed`, so passing
- * `layer(...)` there is a compile error: there is no base to layer onto
- * at the root.
+ * `initialize`'s own parameter keeps a plain `salt?: Salt`, so passing
+ * `layer(...)` there is a compile error: there is no base to layer onto at the
+ * root.
  */
-export type Overlay<$Registry extends PlainObject> = Partial<Omit<Config<$Registry>, "seed" | "clock">> & {
-    readonly seed?: Seed | Layered;
-    readonly clock?: Date | "seeded" | undefined;
+export type Overlay<$Registry extends PlainObject> = Partial<Omit<Config<$Registry>, "salt" | "clock">> & {
+    readonly salt?: Salt | Layered;
+    readonly clock?: Date | "derived" | undefined;
 };
 /**
- * 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 (`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.
+ * 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
+ * (`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.
  */
 export type Frame = {
     readonly config: Config<PlainObject>;
     readonly source: RandomSource;
 };
 /**
- * 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 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.
  */
 export type Stack = {
+    /**
+     * Whether a frame survives an `await` inside the block it was entered for.
+     *
+     * `false` means the carrier is a plain LIFO whose frame unwinds at the
+     * block's first suspension point — correct for synchronous use, and the
+     * reason `wrap` (`Instance/Core.ts`) rejects an async block outright rather
+     * than letting a build after the `await` silently resolve against the base
+     * 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
@@ -88,80 +88,76 @@ export type Stack = {
     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."
+ * 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."
  */
 export type Context = {
-    readonly seed: ReadonlyArray<string>;
+    readonly salt: ReadonlyArray<string>;
     readonly algorithm: Algorithm;
-    readonly attribution: Attribution;
     readonly clock: number;
 };
 /**
- * A single initialized library instance: the registry it was given, and
- * a `construct()` bound to its own isolated randomness — its own seed,
- * builder, and per-file overrides/streams, held internally and never
- * shared with any other `initialize()` call. Independently initialized
- * instances (e.g. parallel tests) can never perturb each other.
+ * A single initialized library instance: the registry it was given, and a
+ * `construct()` bound to its own isolated randomness — its own salt, builder,
+ * and construction counter/streams, held internally and never shared with any
+ * other `initialize()` call. Independently initialized instances (e.g. parallel
+ * tests) can never perturb each other.
  */
-export interface Instance<$Registry extends PlainObject> extends Pick<RandomSource, "seed"> {
+export interface Instance<$Registry extends PlainObject> extends Pick<RandomSource, "salt"> {
     /** The registry of type definers this instance was initialized with. */
     readonly T: $Registry;
     /**
      * Turn a Schema built from `T` into a live Fabricator, deriving fresh
-     * randomness from this instance's own seed for whichever leaves
-     * actually need it.
+     * randomness from this instance's own salt for whichever leaves actually need
+     * it.
      */
     Fabricator: Constructor;
     /**
-     * Every combination of every enumerable node in `schema` — every enum
-     * member, both sides of an optional field, and so on — as a cartesian
-     * product, lazily. Throws eagerly, before producing anything, if the
-     * count exceeds `limits.combinatorial` (see `initialize`'s config).
+     * Every combination of every enumerable node in `schema` — every enum member,
+     * both sides of an optional field, and so on — as a cartesian product,
+     * lazily. Throws eagerly, before producing anything, if the count exceeds
+     * `limits.combinatorial` (see `initialize`'s config).
      */
     combinatorial: Enumerable;
     /**
-     * The minimum set of instances such that every option of every
-     * enumerable node in `schema` appears at least once — count equal to
-     * the *widest* single axis, not the product, with narrower axes
-     * cycling to fill it. Unbounded: its count can never exceed the
-     * schema as written, so unlike `combinatorial` it carries no limit.
+     * The minimum set of instances such that every option of every enumerable
+     * node in `schema` appears at least once — count equal to the _widest_ single
+     * axis, not the product, with narrower axes cycling to fill it. Unbounded:
+     * its count can never exceed the schema as written, so unlike `combinatorial`
+     * it carries no limit.
      */
     coverage: Enumerable;
     /**
      * Derive a new instance laid over this one: anything the overlay names
-     * overrides, anything it omits inherits. A bare `seed` replaces this
-     * instance's seed; `seed: layer(...)` appends onto it. A peer of an
-     * `initialize()` return value in every respect, including its own
-     * `fork`.
+     * overrides, anything it omits inherits. A bare `salt` replaces this
+     * instance's salt; `salt: layer(...)` appends onto it. A peer of an
+     * `initialize()` return value in every respect, including its own `fork`.
      */
     fork<const $ForkRegistry extends PlainObject = $Registry>(overlay?: Overlay<$ForkRegistry>): Instance<$ForkRegistry>;
     /**
-     * `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 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 — a build reached
-     * after an `await` inside `block` sees this instance's own
+     * `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
+     * 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
+     * — 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.seed: layer(...)`
-     * accumulates with nesting depth while a bare `seed` still replaces
-     * outright, discarding every enclosing layer.
+     * 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.
      */
     wrap<$Return, const $WrapRegistry extends PlainObject = $Registry>(overlay: Overlay<$WrapRegistry>, block: (scope: Instance<$WrapRegistry>) => $Return): $Return;
     /**
-     * The configuration in effect right now: the innermost active `wrap`
-     * frame's, or this instance's own outside any `wrap`. A live view, not
-     * a snapshot — reflects whichever frame is active at the moment each
-     * property is read, since one `Instance` outlives any number of
-     * `wrap`s.
+     * The configuration in effect right now: the innermost active `wrap` frame's,
+     * or this instance's own outside any `wrap`. A live view, not a snapshot —
+     * reflects whichever frame is active at the moment each property is read,
+     * since one `Instance` outlives any number of `wrap`s.
      */
     readonly context: Context;
 }

package/dist/types/Primitive/always/Schema.d.ts

@@ -2,17 +2,17 @@ import { type AdaptationEntry } from "../../Adapter/Core";
 import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
 import type { Core, Value } from "./Types";
 /**
- * A fixed value, so unlike every other kind there is no `.as()` — nothing
- * left to override about producing it. `adapt` still applies: what a value
- * *means* to an external schema library is a separate question from what it
- * fabricates to, and for a value TypeBox cannot pin exactly (a `symbol`, or
- * any value's *static* type — see `Adapter/TypeBox`'s `toConst`) it is the
- * only way to close the gap.
+ * A fixed value, so unlike every other kind there is no `.as()` — nothing left
+ * to override about producing it. `adapt` still applies: what a value _means_
+ * to an external schema library is a separate question from what it fabricates
+ * to, and for a value TypeBox cannot pin exactly (a `symbol`, or any value's
+ * _static_ type — see `Adapter/TypeBox`'s `toConst`) it is the only way to
+ * close the gap.
  */
 export interface Schema<$Value extends Value = Value, $Adaptations extends Adaptations = {}> extends Core<$Value, $Adaptations> {
     /**
-     * Override what this schema maps to in one or more external schema
-     * libraries — see `string/Schema.ts`'s `adapt` for the full contract.
+     * Override what this schema maps to in one or more external schema libraries
+     * — see `string/Schema.ts`'s `adapt` for the full contract.
      */
     adapt: <const $Adapter extends Adapter, $Returnable extends ReturnType<$Adapter["convert"]>>(adapter: $Adapter, produce: (adapting: Adapting<Schema<$Value, $Adaptations>>) => $Returnable) => Schema<$Value, WithAdaptations<$Adaptations, AdaptationEntry<$Adapter, $Returnable>>>;
 }