@effected/workspaces 0.23.0 → 0.24.1

package/index.d.ts

@@ -894,11 +894,13 @@ export declare class ChangeDetector extends ChangeDetector_base {
  * replayed hook returns `{ allowedVersions, ignoreMissing, allowAny }` intact,
  * needing no reshaping.
  *
- * Two keys are **carried but not yet consumed**. `ignoreMissing` and
- * `allowAny` are separate suppression axes that have not been measured, and an
- * unmeasured suppression is precisely what produced the false positives this
- * seam exists to remove — so they travel through the seam and no kit code acts
- * on them. Only `allowedVersions` is consumed today.
+ * All three axes are consumed by `PeerCheck`, each established by measurement
+ * against `pnpm peers check` with a firing control. `ignoreMissing` and
+ * `allowAny` are lists of **peer-name patterns** in pnpm's `@pnpm/matcher`
+ * grammar (`*` wildcard, leading `!` negation) — not `parent>peer` keys, which
+ * match nothing on those two axes. `ignoreMissing` hides only a required peer
+ * that resolved to nothing; `allowAny` hides only a peer that resolved outside
+ * its wanted range; the two never cross.
  *
  * `allowedVersions` keys come in two spellings in the wild, and both must be
  * handled: parent-versioned (`"@effect/ai-anthropic@4.0.0-rc.109>effect"`, as
@@ -910,9 +912,9 @@ export declare class ChangeDetector extends ChangeDetector_base {
 interface PeerDependencyRules {
   /** `parent>peer` → the peer version or range the rule permits. */
   readonly allowedVersions: Readonly<Record<string, string>>;
-  /** Peer names whose absence pnpm does not report. Carried, not consumed. */
+  /** Peer-name patterns whose absence pnpm does not report (a required peer that resolved to nothing). */
   readonly ignoreMissing: ReadonlyArray<string>;
-  /** Peer names for which any version is accepted. Carried, not consumed. */
+  /** Peer-name patterns for which any resolved version is accepted. */
   readonly allowAny: ReadonlyArray<string>;
 }
 /**
@@ -930,6 +932,34 @@ interface PeerDependencyRules {
  * @public
  */
 export declare const NoPeerDependencyRules: PeerDependencyRules;
+/**
+ * Where a replayed config dependency's declared version was found: the
+ * `node_modules/.pnpm-config` copy, the pnpm store's `links/` tree, or a
+ * {@link ConfigDependencyHooks.layerFrom} entry.
+ *
+ * @public
+ */
+type HookReplaySource = "installed" | "store" | "supplied";
+/**
+ * Which version of a config dependency a replay actually loaded, and where
+ * that version came from.
+ *
+ * @remarks
+ * Recorded per dependency so a consumer diffing two refs can tell not just
+ * WHAT the hooks injected but which pinned version injected it — the
+ * evidence that a "range moved" row came from a config-dependency bump and
+ * not from a hook edit. `installed` is the `node_modules/.pnpm-config` copy,
+ * `store` the pnpm store's `links/` tree, `supplied` a
+ * {@link ConfigDependencyHooks.layerFrom} entry.
+ *
+ * @public
+ */
+interface HookReplay {
+  /** The declared version that was resolved and replayed. */
+  readonly version: string;
+  /** Which resolution rung answered. */
+  readonly source: HookReplaySource;
+}
 /**
  * The result of replaying a workspace's `configDependencies` hooks: the catalogs
  * the hooks yield, and the release-age gate contribution they leave on the
@@ -967,6 +997,13 @@ interface HookInjection {
    * overwrites for pnpm too — so do not "repair" it into a merger.
    */
   readonly peerDependencyRules: PeerDependencyRules;
+  /**
+   * Which version each declared config dependency was replayed from, keyed
+   * by name — every dependency the layer resolved, including one that ships
+   * no pnpmfile (resolved, contributed nothing). `{}` under
+   * {@link ConfigDependencyHooks.layerNoop}, which resolves nothing.
+   */
+  readonly replays: Readonly<Record<string, HookReplay>>;
 }
 /**
  * The {@link ConfigDependencyHooks} service shape.
@@ -1000,9 +1037,12 @@ interface ConfigDependencyHooksShape {
    * `hooks`-source `CatalogAssemblyError`, never a silent skip.
    *
    * @param root - The workspace root; config dependencies resolve under
-   *   `<root>/node_modules/.pnpm-config/<name>`.
+   *   `<root>/node_modules/.pnpm-config/<name>` when that holds the declared
+   *   version, else through the pnpm store.
    * @param configDependencies - The `configDependencies` map (name →
-   *   version+integrity) declared in `pnpm-workspace.yaml`.
+   *   `<version>+<integrity>`, or a bare `<version>`) declared in the
+   *   `pnpm-workspace.yaml` being read — the live one, or the one at a ref.
+   *   The replaying layers load the pnpmfile of the DECLARED version.
    * @param seed - The inline catalogs, as `catalog name → dependency → range`.
    * @param rules - The workspace file's `peerDependencyRules`, seeded into the
    *   threaded config so hooks merge onto them rather than replacing them.
@@ -1018,12 +1058,21 @@ declare const ConfigDependencyHooks_base: Context.ServiceClass<ConfigDependencyH
  * assembly.
  *
  * @remarks
- * A contract-only service: it declares the shape and ships two layers, never a
+ * A contract-only service: it declares the shape and ships layers, never a
  * baked-in default. {@link ConfigDependencyHooks.layerNoop} executes no
  * config-dependency code (it returns the seed untouched) and is what the default
  * {@link WorkspaceCatalogs} layer wires; {@link ConfigDependencyHooks.layerLive}
- * dynamically imports each `pnpmfile.cjs` and replays it, and is wired only by the
- * explicit `WorkspaceCatalogs.layerWithConfigDependencies` opt-in.
+ * dynamically imports each pnpmfile and replays it, and is wired only by the
+ * explicit `WorkspaceCatalogs.layerWithConfigDependencies` opt-in;
+ * {@link ConfigDependencyHooks.layerSubprocess} is its bundler-safe twin; and
+ * {@link ConfigDependencyHooks.layerFrom} is the hermetic test seam that
+ * replays caller-supplied files with no resolution.
+ *
+ * Every replaying layer replays the pnpmfile of the version each
+ * `configDependencies` entry **declares** — `layerLive` and `layerSubprocess`
+ * resolve it through `node_modules/.pnpm-config` and then the pnpm store,
+ * failing closed when neither holds that version — so a snapshot read at a
+ * past ref replays that ref's pinned hook, not today's.
  *
  * @public
  */
@@ -1035,22 +1084,76 @@ export declare class ConfigDependencyHooks extends ConfigDependencyHooks_base {
    */
   static readonly layerNoop: Layer.Layer<ConfigDependencyHooks>;
   /**
-   * The live layer: dynamically imports each config dependency's `pnpmfile.cjs`
-   * (in process, no subprocess) and replays its `updateConfig` hook over the
-   * seed, in declaration order. A dependency without a `pnpmfile.cjs` contributes
-   * nothing; a dependency whose file fails to load or replay fails typed with a
-   * `hooks`-source `CatalogAssemblyError`, never a silent skip.
+   * The live layer: resolves each config dependency to the pnpmfile of its
+   * **declared** version, dynamically imports it (in process, no subprocess)
+   * and replays its `updateConfig` hook over the seed, in declaration order.
+   * A dependency that ships no pnpmfile contributes nothing; a dependency
+   * whose declared version is installed nowhere, or whose file fails to load
+   * or replay, fails typed with a `hooks`-source `CatalogAssemblyError`, never
+   * a silent skip.
    *
    * @remarks
-   * Runtime-coupled by design, not node-exclusive. The `import()` below loads
+   * Resolution is a ladder, fail-closed, with no registry fetch ever:
+   * `<root>/node_modules/.pnpm-config/<name>` when its `package.json`
+   * `version` equals the declared version (the text before the first `+` of
+   * the `configDependencies` value), else the pnpm store's
+   * `links/<name>/<declared>/*\/node_modules/<name>` (the store is located
+   * from `node_modules/.modules.yaml`, the realpath of any `.pnpm-config`
+   * entry, then `$PNPM_HOME` / `$XDG_DATA_HOME` / the platform default), else
+   * a typed error naming the package, the declared version, what is
+   * installed, the stores searched, and the remediation
+   * (`pnpm add --config <name>@<version>` in a throwaway workspace). In the
+   * chosen directory the first of `pnpmfile.mjs`, `pnpmfile.cjs`,
+   * `pnpmfile.js` present in one directory listing is loaded; a listed but
+   * unreadable file fails typed at import time, never as "ships no hook".
+   *
+   * Runtime-coupled by design, not node-exclusive. The `import()` loads
    * **and executes** a config dependency's pnpmfile in-process — code execution,
-   * not IO, so no `FileSystem` / `Path` service abstracts it. The `node:path` and
-   * `node:url` imports (`join`, `pathToFileURL`) exist only to build the URL that
-   * `import()` consumes; node and bun both implement those builtins and dynamic
-   * import, so this layer runs on either runtime. Only ever wired by
-   * `WorkspaceCatalogs.layerWithConfigDependencies`.
+   * not IO, so no `FileSystem` / `Path` service abstracts it — and the ladder
+   * reads the real disk through `node:fs` for the same reason: the store it
+   * searches is real even when the caller's `FileSystem` is virtual. Only ever
+   * wired by `WorkspaceCatalogs.layerWithConfigDependencies` and the
+   * `Workspaces` composites of the same name.
    */
   static readonly layerLive: Layer.Layer<ConfigDependencyHooks>;
+  /**
+   * The hermetic layer: replays caller-supplied pnpmfiles, keyed
+   * `"<name>@<version>"` → absolute path, with **no resolution** — it consults
+   * neither `node_modules/.pnpm-config` nor the pnpm store, and never the
+   * effect `FileSystem` service, so it works unchanged under an
+   * `@effected/memfs` volume.
+   *
+   * @remarks
+   * The test seam for anything that replays hooks: a suite can pin what
+   * `at(ref)` replays for a ref declaring `plugin@1.0.0` versus one declaring
+   * `plugin@2.0.0` by mapping both keys to fixture files, with no store on
+   * disk. The version half of the key is the declared version — the text
+   * before the first `+` of the `configDependencies` value — so a
+   * `<version>+<integrity>` spec and a bare `<version>` spec look up the same
+   * entry.
+   *
+   * Same typed semantics as {@link ConfigDependencyHooks.layerLive} past the
+   * lookup: the same in-process `import()`, the same hook-locator shapes, the
+   * same tolerant threading, the same `hooks`-source attribution. A declared
+   * `(name, version)` with no entry fails closed, the same shape as an
+   * uninstalled version under `layerLive`; an empty `configDependencies`
+   * returns the seed untouched. A `..` segment in a name is refused before
+   * any lookup.
+   *
+   * @param entries - `"<name>@<version>"` → the absolute path of the pnpmfile
+   *   to replay for that declared version.
+   *
+   * @example
+   * ```ts
+   * import { ConfigDependencyHooks } from "@effected/workspaces";
+   *
+   * const hooks = ConfigDependencyHooks.layerFrom({
+   *   "@scope/plugin@1.0.0": "/fixtures/plugin-1/pnpmfile.mjs",
+   *   "@scope/plugin@2.0.0": "/fixtures/plugin-2/pnpmfile.mjs",
+   * });
+   * ```
+   */
+  static readonly layerFrom: (entries: Readonly<Record<string, string>>) => Layer.Layer<ConfigDependencyHooks>;
   /**
    * The subprocess layer: replays each config dependency's pnpmfile in a `node`
    * child process instead of an in-process dynamic `import()`, with identical
@@ -1064,24 +1167,26 @@ export declare class ConfigDependencyHooks extends ConfigDependencyHooks_base {
    * consumer, a GitHub Action above all, the in-process replay is unreachable.
    * This layer keeps every computed load out of the bundle graph: the replay
    * program is a **static** string constant passed via argv
-   * (`node --input-type=module -e <script> <root> <seed> <...names>`), and the
+   * (`node --input-type=module -e <script> <seed> <rules> <entries>`), and the
    * child process performs the computed imports where no bundler rewrote them.
    * A subprocess also keeps config-dependency code out of the consumer's own
    * process.
    *
-   * The contract's semantics are unchanged, not the downstream fail-open shape:
-   * an empty `configDependencies` returns the seed without spawning anything; a
-   * `..` path segment in a dependency name fails typed **before** any spawn; a
-   * missing pnpmfile (neither `.mjs` nor `.cjs`) is the one legitimate skip,
-   * discriminated inside the child by `err.url` equality exactly as
-   * `layerLive` discriminates in process; any other load failure — a syntax
-   * error, a throwing top level, an `ERR_MODULE_NOT_FOUND` for a module the
-   * pnpmfile itself imports — and a hook that throws when called are serialized
-   * back per-name and surface typed as a `hooks`-source `CatalogAssemblyError`
-   * naming that dependency. A hook's returned *data* stays tolerantly threaded
-   * (last well-formed write wins), never fatal. Spawn and transport failures —
-   * `node` absent, a non-zero exit without a result payload, unparseable
-   * output — fail typed too, never a defect and never a silent skip.
+   * The declared-version resolution is the PARENT's: the same ladder as
+   * `layerLive` (`.pnpm-config` when it holds the declared version, else the
+   * pnpm store, else a typed fail-closed error) runs here, and the child
+   * receives the resolved `[name, fileUrl]` pairs as one JSON argv
+   * argument. An empty `configDependencies`, or one whose dependencies all
+   * ship no pnpmfile, returns the seed without spawning anything; a `..` path
+   * segment in a dependency name fails typed **before** any spawn; a
+   * load failure in the child — a syntax error, a throwing top level, an
+   * `ERR_MODULE_NOT_FOUND` for a module the pnpmfile itself imports — and a
+   * hook that throws when called are serialized back per-name and surface
+   * typed as a `hooks`-source `CatalogAssemblyError` naming that dependency.
+   * A hook's returned *data* stays tolerantly threaded (last well-formed write
+   * wins), never fatal. Spawn and transport failures — `node` absent, a
+   * non-zero exit without a result payload, unparseable output — fail typed
+   * too, never a defect and never a silent skip.
    *
    * Two bounds this layer imposes that `layerLive` cannot: the replay is
    * given thirty seconds (a pnpmfile that loops or awaits forever fails typed
@@ -1829,9 +1934,9 @@ export declare class LockfileReader extends LockfileReader_base {
  *   so pnpm's post-hoc suppression could not be replicated and some reported
  *   rows may be ones pnpm hides. **Omitting the option always produces this**,
  *   because "nobody looked" and "I looked and there are none" are different
- *   facts. Supplied rules with a non-empty `ignoreMissing` or `allowAny` also
- *   produce it: only `allowedVersions` is applied, so an unimplemented axis
- *   degrades to fail-closed rather than to a wrong answer.
+ *   facts. Supplied rules never produce it: all three axes —
+ *   `allowedVersions`, `ignoreMissing` and `allowAny` — are applied with
+ *   pnpm's measured semantics.
  * - `"unresolvedEdge"` — some instance records an edge this model could not
  *   name (`ResolvedPackage.unresolvedEdges`), so a peer that edge satisfies
  *   cannot be verified either way.
@@ -1853,10 +1958,11 @@ type UnverifiedReason = "peerRulesNotApplied" | "unresolvedEdge";
  * different results, because a gate must be able to tell "clean" from
  * "unchecked".
  *
- * **Only `allowedVersions` is applied.** Rules whose `ignoreMissing` or
- * `allowAny` is non-empty describe a suppression policy this module does not
- * implement, so they also yield `"peerRulesNotApplied"` — the unimplemented
- * axes fail closed instead of being silently ignored.
+ * **All three axes of the supplied rules are applied**, each with the
+ * semantics measured against pnpm (see {@link PeerCheck.run}): `allowedVersions`
+ * permits a resolved version by range, `ignoreMissing` hides a required peer
+ * nothing resolved for, and `allowAny` hides a peer that resolved outside its
+ * range. The two list axes are name patterns, never `parent>peer` keys.
  *
  * @public
  */
@@ -2736,10 +2842,8 @@ interface WorkspaceCatalogsShape {
    *
    * A consumer needs these to avoid **reporting** what pnpm suppresses: pnpm
    * computes the same peer violations and then hides the ones a rule allows,
-   * so a checker without them reports findings pnpm calls clean.
-   *
-   * `ignoreMissing` and `allowAny` are carried but unmeasured — no kit code
-   * acts on them today.
+   * so a checker without them reports findings pnpm calls clean. `PeerCheck`
+   * applies all three axes.
    */
   readonly peerDependencyRules: () => Effect.Effect<PeerDependencyRules, CatalogAssemblyFailure>;
   /**
@@ -2755,6 +2859,18 @@ interface WorkspaceCatalogsShape {
    * nothing rather than failing.
    */
   readonly importerVersions: () => Effect.Effect<ImporterVersions, CatalogAssemblyFailure>;
+  /**
+   * Which version each declared config dependency was replayed from, keyed
+   * by name — off the same single memoized assemble pass as `set()`.
+   *
+   * @remarks
+   * Every dependency the hooks layer resolved when a `pnpm-workspace.yaml`
+   * was read — `{}` when it declares no config dependencies or under the
+   * no-op layer, which resolves nothing. Config dependencies are a pnpm
+   * feature, so the bun / `package.json` path yields `{}` too, exactly as
+   * `importerVersions` does.
+   */
+  readonly hookReplays: () => Effect.Effect<Readonly<Record<string, HookReplay>>, CatalogAssemblyFailure>;
   /**
    * Discard the memoized assembly so the **next** read re-assembles — the same
    * single read and hook replay as the first, over the workspace as it stands
@@ -2818,6 +2934,26 @@ declare const WorkspaceCatalogs_base: Context.ServiceClass<WorkspaceCatalogs, "@
 export declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
   /** Builds the service. */
   static readonly make: (options?: WorkspaceCatalogsOptions) => Effect.Effect<WorkspaceCatalogsShape, never, WorkspaceRoot | LockfileReader | ConfigDependencyHooks | FileSystem.FileSystem | Path.Path>;
+  /**
+   * The service over an explicit {@link ConfigDependencyHooks} layer — the
+   * one builder every `layer*` static and the `Workspaces` composites
+   * delegate to, so the hooks layer is provided to {@link WorkspaceCatalogs.make}
+   * in exactly one place.
+   *
+   * @remarks
+   * Reach for it when the hooks layer is chosen elsewhere — a composite that
+   * must hand ONE hooks reference to both this service and
+   * `WorkspaceSnapshots` (layers memoize by reference, so two references
+   * would replay twice and could run two policies), or a test wiring
+   * {@link ConfigDependencyHooks.layerFrom}. The three `layer*` statics are
+   * this with the hooks layer fixed. `R` is the hooks layer's own
+   * requirement (the subprocess variant's `ChildProcessSpawner`), threaded
+   * through. Parameterized, so bind it to a `const` and reuse it.
+   *
+   * @param hooks - The {@link ConfigDependencyHooks} layer to replay through.
+   * @param options - The same options the other layer statics take.
+   */
+  static readonly layerWithHooks: <R = never>(hooks: Layer.Layer<ConfigDependencyHooks, never, R>, options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path | R>;
   /**
    * The live layer — the default, which **never executes config-dependency
    * code**: it wires {@link ConfigDependencyHooks.layerNoop}, whose hooks return
@@ -2875,9 +3011,10 @@ export declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
    * `resolveSpecifier` answers from that `CatalogSet`'s own
    * {@link CatalogSet.resolveSpecifier} — exactly what the live service runs
    * over its assembled set — so the two stay consistent by construction.
-   * `releaseAgeGate` and `importerVersions` are **not** derivable from a
-   * catalog set (the gate comes from release-age keys and hook contributions,
-   * the importer index from the lockfile's importer blocks — neither is in a
+   * `releaseAgeGate`, `importerVersions` and `hookReplays` are **not**
+   * derivable from a catalog set (the gate comes from release-age keys and
+   * hook contributions, the importer index from the lockfile's importer
+   * blocks, the replay record from the hooks layer — none is in a
    * `CatalogSet`) and always die unless stubbed.
    *
    * `refresh` defaults to `Effect.void` honestly: the double holds no memo,
@@ -3009,6 +3146,23 @@ declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot,
    * importer versions; bun and npm yield an empty index.
    */
   readonly importerVersions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>>;
+  /**
+   * Which version each declared config dependency's hook was replayed from at
+   * this moment, keyed by name.
+   *
+   * @remarks
+   * Versions only — WHERE this machine found each pnpmfile (the `source` of a
+   * live `HookReplay`) is machine-local provenance, not part of "what the
+   * workspace looked like then", so it stays on the live `HookInjection`
+   * diagnostic and off this serializable value. Every fresh read sets the
+   * field: `{}` under the no-op layer, which resolves nothing, when the file
+   * declares no config dependencies, or on the bun / `package.json` path,
+   * where config dependencies do not exist. Absent only when decoding a
+   * snapshot serialized before the field existed, so stored values stay
+   * readable. Carried through `withSeededCatalogs` and `crossSeed`
+   * unchanged, like `importerVersions`.
+   */
+  readonly hookReplays: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
   /**
    * Catalogs supplied from OUTSIDE this moment, consulted only when
    * `catalogs` cannot answer.
@@ -3022,11 +3176,14 @@ declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot,
    * always wins and both halves stay readable.
    *
    * The motivating case is a catalog injected by a config-dependency
-   * `pnpmfile` hook. It is recorded in no committed catalog source, so
-   * `WorkspaceSnapshots.at(ref)` — which never replays hooks, by design — cannot
-   * see it, and a `catalog:` specifier against it resolves to nothing on BOTH
-   * sides of a diff. Seeding the live hook-injected set, or the other side's
-   * set, restores a declared RANGE without executing any historical code.
+   * `pnpmfile` hook. It is recorded in no committed catalog source, so under
+   * a non-replaying `ConfigDependencyHooks` layer (`layerNoop`, the default)
+   * `WorkspaceSnapshots.at(ref)` cannot see it, and a `catalog:` specifier
+   * against it resolves to nothing on BOTH sides of a diff. Seeding the live
+   * hook-injected set, or the other side's set, restores a declared RANGE
+   * without executing any historical code. Under a replaying layer `at(ref)`
+   * replays the ref's own pinned hook and the seed answers only what neither
+   * source declared.
    *
    * Defaults to absent, which makes the seed inert — exactly the behavior of
    * every snapshot captured before this field existed.
@@ -3147,8 +3304,8 @@ export declare class WorkspaceStateSnapshot extends WorkspaceStateSnapshot_base
    * value, and an accumulating seed would make precedence depend on call
    * order). {@link WorkspaceStateSnapshot.crossSeed} is the deliberate
    * exception: it composes the two seeds explicitly, precisely because a bare
-   * replace would discard a layer-level seed. `catalogs`, `packages` and `importerVersions` are carried through
-   * unchanged, so what the ref declared is still exactly what it declared.
+   * replace would discard a layer-level seed. `catalogs`, `packages`, `importerVersions` and `hookReplays` are
+   * carried through unchanged, so what the ref declared is still exactly what it declared.
    *
    * The two seeds worth reaching for: the LIVE hook-injected catalog set (from
    * a `WorkspaceCatalogs` built by one of the config-dependency layers), or the
@@ -3186,16 +3343,19 @@ export declare class WorkspaceStateSnapshot extends WorkspaceStateSnapshot_base
    * missing it, at strictly lower precedence than that side's own catalogs, so
    * a genuine change between the refs still reads as a change.
    *
-   * **The limitation is inherent and is not a defect to work around.** A range
-   * change made purely by bumping the config dependency BETWEEN the two refs is
-   * suppressed: neither committed source declares the catalog, so each side
-   * falls back to the other's value and the two agree by construction. Seeding
-   * the live hook-injected set via
-   * {@link WorkspaceStateSnapshot.withSeededCatalogs} has the same blind spot
-   * against history — recovering it would mean replaying each ref's pinned
-   * config-dependency code, which `at(ref)` will not do. If that case must be
-   * detected, diff `configDependencies` in `pnpm-workspace.yaml` directly; it
-   * is the only committed evidence that the injection changed.
+   * **What cross-seeding can and cannot see depends on the hooks layer.** A
+   * range change made purely by bumping the config dependency BETWEEN the two
+   * refs is detected when the snapshots were read under a replaying
+   * `ConfigDependencyHooks` layer: `WorkspaceSnapshots.at(ref)` replays each
+   * ref's hook at the version that ref's `configDependencies` declares, so
+   * each side's OWN catalogs carry that side's injected range and the seed
+   * never gets a say. Under `layerNoop` the case stays suppressed — neither
+   * committed source declares the catalog, so each side falls back to the
+   * other's value and the two agree by construction; there, diff
+   * `configDependencies` in `pnpm-workspace.yaml` directly, the only committed
+   * evidence that the injection changed. Cross-seeding is harmless under a
+   * replaying layer (own catalogs take precedence) and still worthwhile under
+   * the no-op one, which is why it stays.
    *
    * **The seeding relationship is symmetric; the RETURN ORDER is not.** Each
    * snapshot is seeded with the other's catalogs, so neither argument is
@@ -3258,15 +3418,15 @@ export declare class WorkspaceStateSnapshot extends WorkspaceStateSnapshot_base
 //#region src/WorkspaceSnapshots.d.ts
 /**
  * Every failure `WorkspaceSnapshots.at` can surface: git's own typed
- * errors, a catalog-assembly failure from the inline config source at the ref,
- * or an unfindable workspace root.
+ * errors, a catalog-assembly failure from the inline config source or the
+ * config-dependency hook replay at the ref, or an unfindable workspace root.
  *
  * @remarks
  * Narrow by design. `at` reads through git and never enumerates the live
  * filesystem, so no `WorkspaceDiscoveryError` / `WorkspacePatternError` appears —
  * and a malformed *lockfile* at the ref degrades to no catalogs (a lockfile is a
- * record, not a source of truth), so only the inline source raises
- * `CatalogAssemblyError`.
+ * record, not a source of truth), so only the inline source and a
+ * `hooks`-source replay failure raise `CatalogAssemblyError`.
  *
  * @public
  */
@@ -3309,10 +3469,13 @@ interface WorkspaceSnapshotsOptions {
    * remembering to call `withSeededCatalogs` at each site — and a forgotten
    * call is a silently missing diff row, not a type error.
    *
-   * **This executes nothing.** The caller supplies the set; `at(ref)` still
-   * never replays config-dependency hooks and still never fetches. The
-   * deliberate at/worktree asymmetry is unchanged — this only lets a consumer
-   * who has already paid for the live set share it with the ref side.
+   * **This executes nothing by itself.** The caller supplies the set, and
+   * `at(ref)` still never fetches. Whether `at(ref)` replays that ref's
+   * config-dependency hooks is decided by the {@link ConfigDependencyHooks}
+   * layer in scope, not by this option: under a replaying layer the ref's own
+   * replay answers first and the seed fills only what neither source declared;
+   * under `layerNoop` the seed is the only way a hook-injected catalog reaches
+   * the ref side at all.
    *
    * Applied to `worktree()` too, for symmetry. There it is usually inert: a
    * live set assembled under a config-dependency layer already contains the
@@ -3330,7 +3493,18 @@ interface WorkspaceSnapshotsOptions {
  * @public
  */
 interface WorkspaceSnapshotsShape {
-  /** The workspace state at a git ref, read with no checkout. Cached per `(root, ref)`. */
+  /**
+   * The workspace state at a git ref, read with no checkout. Cached per
+   * `(root, ref)`.
+   *
+   * @remarks
+   * The ref's `pnpm-workspace.yaml` `configDependencies` are replayed through
+   * the {@link ConfigDependencyHooks} layer in scope at the versions THAT ref
+   * declares (a replaying layer resolves them via `.pnpm-config` or the pnpm
+   * store and fails closed when a declared version is installed nowhere;
+   * `layerNoop` executes nothing). The injected catalogs merge above the
+   * ref's lockfile and inline sources, exactly as the live assembler does.
+   */
   readonly at: (ref: string) => Effect.Effect<WorkspaceStateSnapshot, WorkspaceSnapshotAtFailure>;
   /** The live workspace state, over discovery and catalog assembly. Uncached. */
   readonly worktree: () => Effect.Effect<WorkspaceStateSnapshot, WorkspaceSnapshotWorktreeFailure>;
@@ -3362,8 +3536,17 @@ declare const WorkspaceSnapshots_base: Context.ServiceClass<WorkspaceSnapshots,
  * @public
  */
 export declare class WorkspaceSnapshots extends WorkspaceSnapshots_base {
-  /** Builds the service over `Git`, {@link WorkspaceRoot}, {@link WorkspaceDiscovery} and {@link WorkspaceCatalogs}. */
-  static readonly make: (options?: WorkspaceSnapshotsOptions) => Effect.Effect<WorkspaceSnapshotsShape, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs>;
+  /**
+   * Builds the service over `Git`, {@link WorkspaceRoot}, {@link WorkspaceDiscovery},
+   * {@link WorkspaceCatalogs} and {@link ConfigDependencyHooks}.
+   *
+   * @remarks
+   * `ConfigDependencyHooks` is what `at(ref)` replays a ref's
+   * `configDependencies` through — at the versions THAT ref declares, which is
+   * why the composites hand the same hooks layer to this service and to
+   * `WorkspaceCatalogs`. Under `layerNoop` the ref read executes nothing.
+   */
+  static readonly make: (options?: WorkspaceSnapshotsOptions) => Effect.Effect<WorkspaceSnapshotsShape, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs | ConfigDependencyHooks>;
   /**
    * The live layer.
    *
@@ -3371,7 +3554,7 @@ export declare class WorkspaceSnapshots extends WorkspaceSnapshots_base {
    * Parameterized, so it mints a fresh reference per call — bind it to a
    * `const` and reuse it, or layer memoization does not apply.
    */
-  static readonly layer: (options?: WorkspaceSnapshotsOptions) => Layer.Layer<WorkspaceSnapshots, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs>;
+  static readonly layer: (options?: WorkspaceSnapshotsOptions) => Layer.Layer<WorkspaceSnapshots, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs | ConfigDependencyHooks>;
   /**
    * A test double satisfying the full {@link WorkspaceSnapshotsShape} with no
    * git, filesystem, discovery, or catalog assembly.
@@ -3630,6 +3813,43 @@ export declare class Workspaces {
    * ```
    */
   static readonly layerWithGitAndConfigDependenciesSubprocess: (options?: WorkspacesGitOptions) => Layer.Layer<WorkspacesServices | ChangeDetector | WorkspaceSnapshots | Git, never, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * The git composite over a **caller-supplied** hooks layer — the same graph
+   * as {@link Workspaces.layerWithGit} and its two config-dependency
+   * variants, with the `ConfigDependencyHooks` policy chosen by the caller.
+   *
+   * @remarks
+   * The three fixed git composites are this function applied to
+   * {@link ConfigDependencyHooks.layerNoop}, {@link ConfigDependencyHooks.layerLive}
+   * and {@link ConfigDependencyHooks.layerSubprocess}. It exists for the fourth
+   * policy: {@link ConfigDependencyHooks.layerFrom}, the hermetic seam, which a
+   * snapshot-backed test otherwise cannot reach without rebuilding the whole
+   * git graph by hand — the copy `layerWithGitAndConfigDependencies` was added
+   * to delete. The ONE hooks reference is handed to both `WorkspaceCatalogs`
+   * and `WorkspaceSnapshots`, so `at(ref)` and `worktree()` cannot drift on
+   * which policy they replay. A hooks layer carrying its own requirement (the
+   * subprocess variant's `ChildProcessSpawner`) threads it through to the
+   * composite's `R` unchanged.
+   *
+   * **Bind the result to a `const`.**
+   *
+   * @param hooks - The `ConfigDependencyHooks` layer to wire on both sides.
+   * @param options - The composite options, as for {@link Workspaces.layerWithGit}.
+   *
+   * @example
+   * ```ts
+   * import { ConfigDependencyHooks, Workspaces } from "@effected/workspaces";
+   *
+   * // A test pinning what at(ref) replays for two declared plugin versions.
+   * const KitLayer = Workspaces.layerWithGitAndHooks(
+   *   ConfigDependencyHooks.layerFrom({
+   *     "@scope/plugin@1.0.0": "/fixtures/plugin-1/pnpmfile.mjs",
+   *     "@scope/plugin@2.0.0": "/fixtures/plugin-2/pnpmfile.mjs",
+   *   }),
+   * );
+   * ```
+   */
+  static readonly layerWithGitAndHooks: <R = never>(hooks: Layer.Layer<ConfigDependencyHooks, never, R>, options?: WorkspacesGitOptions) => Layer.Layer<WorkspacesServices | ChangeDetector | WorkspaceSnapshots | Git, never, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner | R>;
   /**
    * This package's implementation of `@effected/commands`' `LocalExec`
    * contract: how to run a project-local binary here.
@@ -4092,5 +4312,5 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
  */
 export declare const getWorkspacePackagesSync: (root: string, options: GetWorkspacePackagesSyncOptions) => ReadonlyArray<WorkspacePackage>;
 //#endregion
-export type { CatalogAssemblyFailure, ChangeDetectionFailure, ChangeDetectorShape, ClassifyOptions, ConfigDependencyHooksShape, DependencyDiff, DuplicateCheckOptions, FindWorkspaceRootOptions, GetWorkspacePackagesSyncOptions, HookInjection, ImporterVersions, LockfileReadFailure, LockfileReaderOptions, LockfileReaderShape, PackageManagerDetectionFailure, PackageManagerDetectorShape, PackageRelease, PeerCheckOptions, PeerDependencyRules, PublishabilityDetectorShape, SyncDirectoryEntry, SyncFileSystem, SyncPath, TagClassification, TagFormatOptions, TrackingTagOptions, UnverifiedReason, VersioningDetectOptions, WorkspaceCatalogsOptions, WorkspaceCatalogsShape, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceDiscoverySkip, WorkspaceDiscoverySkipKind, WorkspaceLookupFailure, WorkspaceRootShape, WorkspaceSnapshotAtFailure, WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshotsOptions, WorkspaceSnapshotsShape, WorkspacesGitOptions, WorkspacesOptions, WorkspacesServices, WorkspacesSyncOptions };
+export type { CatalogAssemblyFailure, ChangeDetectionFailure, ChangeDetectorShape, ClassifyOptions, ConfigDependencyHooksShape, DependencyDiff, DuplicateCheckOptions, FindWorkspaceRootOptions, GetWorkspacePackagesSyncOptions, HookInjection, HookReplay, HookReplaySource, ImporterVersions, LockfileReadFailure, LockfileReaderOptions, LockfileReaderShape, PackageManagerDetectionFailure, PackageManagerDetectorShape, PackageRelease, PeerCheckOptions, PeerDependencyRules, PublishabilityDetectorShape, SyncDirectoryEntry, SyncFileSystem, SyncPath, TagClassification, TagFormatOptions, TrackingTagOptions, UnverifiedReason, VersioningDetectOptions, WorkspaceCatalogsOptions, WorkspaceCatalogsShape, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceDiscoverySkip, WorkspaceDiscoverySkipKind, WorkspaceLookupFailure, WorkspaceRootShape, WorkspaceSnapshotAtFailure, WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshotsOptions, WorkspaceSnapshotsShape, WorkspacesGitOptions, WorkspacesOptions, WorkspacesServices, WorkspacesSyncOptions };
 //# sourceMappingURL=index.d.ts.map