@effected/workspaces 0.6.2 → 0.8.0

package/LockfileReader.js

@@ -27,6 +27,8 @@ var LockfileReadError = class extends Schema.TaggedErrorClass()("LockfileReadErr
 		return `Cannot read ${this.format} lockfile at ${this.lockfilePath}`;
 	}
 };
+/** A defect naming the unstubbed test-double method — a test-wiring mistake, not a typed failure. */
+const unstubbed = (method) => Effect.die(/* @__PURE__ */ new Error(`LockfileReader.makeTest: ${method}() was called but not stubbed — pass a \`${method}\` override.`));
 /**
 * Reads and parses the workspace's lockfile.
 *
@@ -112,6 +114,74 @@ var LockfileReader = class LockfileReader extends Context.Service()("@effected/w
 	* `const` and reuse it.
 	*/
 	static layer = (options) => Layer.effect(LockfileReader, LockfileReader.make(options));
+	/**
+	* A test double satisfying the full {@link LockfileReaderShape} with no
+	* filesystem, root walk, or package-manager detection.
+	*
+	* @remarks
+	* There is **no honest default lockfile**: an empty one that looks like a
+	* legitimate answer is indistinguishable from "this workspace resolves
+	* nothing" — the silent-empty failure class this package documents on the
+	* live paths — so `read` **dies** with an instructive defect until stubbed.
+	*
+	* The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+	* derived-from-the-primary rule: when a `read` override is supplied,
+	* `resolvedVersion` answers as the live service does — the **first** entry
+	* of `lockfile.packagesNamed(name)` in lockfile order, `Option.none()` on a
+	* miss — so the two stay consistent by construction. `integrity` is **not**
+	* derivable: the live method compares the lockfile against the workspace
+	* manifests discovery enumerates, and the double has no discovery to ask, so
+	* it dies unless stubbed.
+	*
+	* `refresh` defaults to `Effect.void` honestly: the live contract is "drop
+	* the memoized read so the next call re-reads", and this double memoizes
+	* nothing — every `read()` call re-invokes the override — so there is
+	* nothing to drop and the no-op is truthful, the same reasoning as
+	* `WorkspaceDiscovery.makeTest`'s `refresh`.
+	*
+	* @example
+	* ```ts
+	* import { Lockfile } from "@effected/lockfiles";
+	* import { LockfileReader } from "@effected/workspaces";
+	* import { Effect } from "effect";
+	*
+	* const double = LockfileReader.makeTest({
+	*   read: () =>
+	*     Effect.succeed(
+	*       Lockfile.make({ format: "pnpm", lockfileVersion: "9.0", packages: [], workspaceDependencies: [] }),
+	*     ),
+	* });
+	* // `resolvedVersion` now answers consistently from that lockfile.
+	* ```
+	*/
+	static makeTest = (overrides = {}) => {
+		const read = overrides.read;
+		return {
+			read: () => unstubbed("read"),
+			resolvedVersion: read !== void 0 ? (packageName) => Effect.map(read(), (lockfile) => Option.fromUndefinedOr(lockfile.packagesNamed(packageName)[0])) : () => unstubbed("resolvedVersion"),
+			integrity: () => unstubbed("integrity"),
+			refresh: () => Effect.void,
+			...overrides
+		};
+	};
+	/**
+	* The test layer: {@link LockfileReader.makeTest} behind `Layer.succeed`, so
+	* a suite provides only the methods it exercises.
+	*
+	* @remarks
+	* A parameterized layer factory mints a **fresh reference per call**, and
+	* layers memoize by reference — bind the result to a `const` and reuse it
+	* rather than calling `layerTest(...)` at each composition site.
+	*
+	* @example
+	* ```ts
+	* import { LockfileReader } from "@effected/workspaces";
+	*
+	* const TestLockfiles = LockfileReader.layerTest();
+	* // program.pipe(Effect.provide(TestLockfiles)) — dies loudly if touched.
+	* ```
+	*/
+	static layerTest = (overrides = {}) => Layer.succeed(LockfileReader, LockfileReader.makeTest(overrides));
 };
 
 //#endregion

package/README.md

@@ -134,7 +134,21 @@ A specifier the workspace cannot answer fails typed as `UnresolvedDependencyErro
 
 ## The synchronous escape hatch
 
-Vitest's config-time project discovery cannot await. Two functions exist for exactly that case, and they run synchronously over file and path operations you supply — the module itself imports nothing platform-shaped, and Node's built-ins satisfy the operations one-liner each:
+Vitest's config-time project discovery cannot await. Two functions exist for exactly that case, and they run synchronously over file and path operations you supply. On Node you do not have to write them: the `@effected/workspaces/node-sync` subpath exports `nodeSyncOps`, the ready-made `node:fs` and `node:path` bindings, so adopting the sync path is one extra import.
+
+```ts
+import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/workspaces";
+import { nodeSyncOps } from "@effected/workspaces/node-sync";
+
+const root = findWorkspaceRootSync(process.cwd(), nodeSyncOps);
+const packages = root === null ? [] : getWorkspacePackagesSync(root, nodeSyncOps);
+// root: the workspace root path, or null when none is found above the cwd
+// packages: the discovered workspace packages, empty when there is no root
+```
+
+Both entry points take their path positionally, so the bag usually passes through verbatim; spread it to add `getWorkspacePackagesSync`'s traversal extras — `{ ...nodeSyncOps, maxDepth }`. The bindings are a separate subpath deliberately: the main entry imports nothing platform-shaped, and re-exporting them from it would drag `node:*` into every consumer, including the ones supplying their own operations. `nodePath` is the running platform's `node:path`, so on Windows the paths handed back are win32 paths.
+
+Write the operations yourself when Node's built-ins are not the platform you mean — a Bun or Deno binding, a test fake, or `node:path/win32` to pin a dialect rather than follow the running platform. Each one is a one-liner:
 
 ```ts
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
@@ -157,7 +171,7 @@ const packages = root === null ? [] : getWorkspacePackagesSync(root, options);
 // packages: the discovered workspace packages, empty when there is no root
 ```
 
-Windows correctness is the operations you pass — `node:path` on Windows is already win32-appropriate. Both entry points drive one traversal state machine (the same dequeue order, depth rule, visit budget and `node_modules` prune), so the sync and Effect surfaces can never disagree about what a pattern means. The one deliberate difference is at a bound: the Effect enumerator fails typed, the sync one truncates. Prefer the Effect API everywhere you can run one.
+Windows correctness is therefore the operations you pass, and nothing else. Both entry points drive one traversal state machine (the same dequeue order, depth rule, visit budget and `node_modules` prune), so the sync and Effect surfaces can never disagree about what a pattern means. The one deliberate difference is at a bound: the Effect enumerator fails typed, the sync one truncates. Prefer the Effect API everywhere you can run one.
 
 ## Error handling
 
@@ -220,6 +234,7 @@ A name miss in the derived `getPackage` fails with the service's own typed `Pack
 - `ChangeDetector` — git-range change detection over `@effected/git`'s `Git` service; swap the layer to mock it with no repository.
 - `PublishabilityDetector` — whether a package publishes and to where, as a `PublishTarget` (registry, directory, access, provenance). The default layer implements npm's semantics; swap the layer if yours differ.
 - `findWorkspaceRootSync` / `getWorkspacePackagesSync` — the synchronous escape hatch for config-time callers that cannot await, over file and path operations you supply.
+- `@effected/workspaces/node-sync` — a second entry point holding the Node bindings for those operations (`nodeFileSystem`, `nodePath` and the `nodeSyncOps` bag), kept off the main entry so `node:*` never reaches a consumer that supplies its own.
 
 ## License
 

package/WorkspaceCatalogs.js

@@ -2,6 +2,7 @@ import { WorkspaceRoot } from "./WorkspaceRoot.js";
 import { inlineCatalogs, merge, normalize, rangeOf } from "./internal/catalogs.js";
 import { ConfigDependencyHooks } from "./ConfigDependencyHooks.js";
 import { LockfileReader } from "./LockfileReader.js";
+import { importerVersionsOf } from "./internal/importerVersions.js";
 import { Context, Duration, Effect, Exit, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
 import { CatalogAssemblyError, CatalogResolver, DependencyResolutionError, PartialReleaseAgeGate, ReleaseAgeGate } from "@effected/npm";
 import { Yaml } from "@effected/yaml";
@@ -282,6 +283,8 @@ const validatePnpmWorkspaceCatalogs = (document) => {
 		catalogs: "catalogs"
 	}));
 };
+/** A defect naming the unstubbed test-double method — a test-wiring mistake, not a typed failure. */
+const unstubbed = (method) => Effect.die(/* @__PURE__ */ new Error(`WorkspaceCatalogs.makeTest: ${method}() was called but not stubbed — pass a \`${method}\` override.`));
 /**
 * Assembles a workspace's catalogs, package-manager-aware.
 *
@@ -325,7 +328,15 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 		}));
 		const assemble = Effect.gen(function* () {
 			const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd()));
-			const fromLockfile = yield* lockfiles.read().pipe(Effect.map(CatalogSet.fromLockfile), Effect.catch((_failure) => Effect.succeed(CatalogSet.empty())));
+			const lockfileOutputs = yield* lockfiles.read().pipe(Effect.map((lockfile) => ({
+				catalogs: CatalogSet.fromLockfile(lockfile),
+				importerVersions: importerVersionsOf(lockfile)
+			})), Effect.catch((_failure) => Effect.succeed({
+				catalogs: CatalogSet.empty(),
+				importerVersions: {}
+			})));
+			const fromLockfile = lockfileOutputs.catalogs;
+			const importerVersions = lockfileOutputs.importerVersions;
 			const workspaceYaml = path.join(root, "pnpm-workspace.yaml");
 			const hasPnpmWorkspace = yield* probeExists(workspaceYaml);
 			let inline;
@@ -353,7 +364,8 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 				const manifestPath = path.join(root, "package.json");
 				if (!(yield* probeExists(manifestPath))) return {
 					catalogs: fromLockfile,
-					releaseAgeGate: ReleaseAgeGate.combine()
+					releaseAgeGate: ReleaseAgeGate.combine(),
+					importerVersions
 				};
 				const text = yield* fs.readFileString(manifestPath).pipe(Effect.mapError((cause) => new CatalogAssemblyError({
 					source: "manifest",
@@ -372,7 +384,8 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 			}));
 			return {
 				catalogs: assembled,
-				releaseAgeGate
+				releaseAgeGate,
+				importerVersions
 			};
 		});
 		const [resolveOnce, invalidate] = yield* Effect.cachedInvalidateWithTTL(assemble, Duration.infinity);
@@ -386,6 +399,9 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 			}),
 			releaseAgeGate: Effect.fn("WorkspaceCatalogs.releaseAgeGate")(function* () {
 				return (yield* memo).releaseAgeGate;
+			}),
+			importerVersions: Effect.fn("WorkspaceCatalogs.importerVersions")(function* () {
+				return (yield* memo).importerVersions;
 			})
 		};
 	});
@@ -412,6 +428,70 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 	*/
 	static layerWithConfigDependencies = (options) => Layer.effect(WorkspaceCatalogs, WorkspaceCatalogs.make(options)).pipe(Layer.provide(ConfigDependencyHooks.layerLive));
 	/**
+	* A test double satisfying the full {@link WorkspaceCatalogsShape} with no
+	* filesystem, lockfile read, or hook replay.
+	*
+	* @remarks
+	* There is **no honest default catalog set**: an empty `CatalogSet` that
+	* looks like a legitimate answer is the "every dependency looks newly added"
+	* failure class the live assembler hard-fails to prevent, so every method
+	* **dies** with an instructive defect until stubbed — a test-wiring mistake
+	* fails loudly as a defect rather than succeeding with a lie or failing with
+	* a dishonest typed error.
+	*
+	* The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+	* derived-from-the-primary rule: when a `set` override is supplied,
+	* `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
+	* `CatalogSet`) and always die unless stubbed.
+	*
+	* @example
+	* ```ts
+	* import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+	* import { Effect } from "effect";
+	*
+	* const double = WorkspaceCatalogs.makeTest({
+	*   set: () => Effect.succeed(CatalogSet.fromCatalogs({ default: { effect: "4.0.0" } })),
+	* });
+	* // `resolveSpecifier` now answers consistently from that set.
+	* ```
+	*/
+	static makeTest = (overrides = {}) => {
+		const set = overrides.set;
+		return {
+			set: () => unstubbed("set"),
+			resolveSpecifier: set !== void 0 ? (dependency, specifier) => Effect.map(set(), (catalogs) => catalogs.resolveSpecifier(dependency, specifier)) : () => unstubbed("resolveSpecifier"),
+			releaseAgeGate: () => unstubbed("releaseAgeGate"),
+			importerVersions: () => unstubbed("importerVersions"),
+			...overrides
+		};
+	};
+	/**
+	* The test layer: {@link WorkspaceCatalogs.makeTest} behind `Layer.succeed`,
+	* so a suite provides only the methods it exercises.
+	*
+	* @remarks
+	* A parameterized layer factory mints a **fresh reference per call**, and
+	* layers memoize by reference — bind the result to a `const` and reuse it
+	* rather than calling `layerTest(...)` at each composition site.
+	*
+	* @example
+	* ```ts
+	* import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+	* import { Effect } from "effect";
+	*
+	* const TestCatalogs = WorkspaceCatalogs.layerTest({
+	*   set: () => Effect.succeed(CatalogSet.empty()),
+	* });
+	* // program.pipe(Effect.provide(TestCatalogs))
+	* ```
+	*/
+	static layerTest = (overrides = {}) => Layer.succeed(WorkspaceCatalogs, WorkspaceCatalogs.makeTest(overrides));
+	/**
 	* The real implementation of `@effected/npm`'s `CatalogResolver` contract —
 	* the one `@effected/package-json` declares but cannot fill.
 	*

package/WorkspaceStateSnapshot.js

@@ -1,3 +1,4 @@
+import { unanimousVersionOf } from "./internal/importerVersions.js";
 import { CatalogSet } from "./WorkspaceCatalogs.js";
 import { Effect, Exit, Layer, Option, Schema } from "effect";
 import { CatalogResolver, DependencySpecifier, WorkspaceResolver } from "@effected/npm";
@@ -86,7 +87,19 @@ var WorkspaceStateSnapshot = class extends Schema.Class("WorkspaceStateSnapshot"
 	/** Every workspace package captured at this moment. */
 	packages: Schema.Array(PackageStateSnapshot),
 	/** The catalog set assembled at this moment. */
-	catalogs: CatalogSet
+	catalogs: CatalogSet,
+	/**
+	* Each importer's dependency-name → resolved-version map, as the manager's
+	* lockfile recorded it at this moment.
+	*
+	* @remarks
+	* Defaults to `{}`, so a `WorkspaceStateSnapshot` serialized before this field
+	* existed still decodes — and an empty index simply makes the `catalog:`
+	* fallback in {@link WorkspaceStateSnapshot.resolve} inert, which is exactly
+	* the behavior those older values were captured under. Only pnpm records
+	* importer versions; bun and npm yield an empty index.
+	*/
+	importerVersions: Schema.optionalKey(Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.String)))
 }) {
 	#versionIndex;
 	#packageIndex;
@@ -121,16 +134,62 @@ var WorkspaceStateSnapshot = class extends Schema.Class("WorkspaceStateSnapshot"
 	* unparseable string — is `Option.none()`, because there is no indirection to
 	* resolve. Total.
 	*
+	* A `catalog:` specifier the catalog set cannot resolve falls back to this
+	* snapshot's `importerVersions` — but only to a version
+	* **every** importer recording that dependency agrees on. A catalog injected
+	* by a config-dependency pnpmfile hook appears in no committed catalog source,
+	* so without this fallback both sides of a before/after diff resolve it to the
+	* same raw string and a real version movement produces no row. When importers
+	* disagree there is no single correct answer, so this stays `Option.none()`
+	* rather than inventing one; {@link WorkspaceStateSnapshot.resolveIn} answers
+	* precisely for callers that know which importer is asking.
+	*
 	* @param dependency - The dependency's package name (what `workspace:` /
 	*   `catalog:` resolve for).
 	* @param specifier - The raw specifier string.
 	*/
 	resolve(dependency, specifier) {
+		return this.#resolveWith(dependency, specifier, () => Option.fromUndefinedOr(unanimousVersionOf(this.importerVersions ?? {}, dependency)));
+	}
+	/**
+	* The concrete range or version a specifier resolved to AS OF this snapshot,
+	* scoped to the importer that declared it.
+	*
+	* @remarks
+	* Identical to {@link WorkspaceStateSnapshot.resolve} except in how an
+	* unresolvable `catalog:` specifier falls back: this consults **only**
+	* `importerPath`'s own recorded versions, so a monorepo whose packages hold
+	* different versions of one dependency still gets an exact answer where
+	* `resolve` must abstain. Prefer this whenever the caller knows the importer —
+	* a consumer iterating `packages` has `relativePath` in hand, which is the
+	* importer key (`"."` for the root package).
+	*
+	* An unknown `importerPath`, or one recording nothing for `dependency`, is
+	* `Option.none()`. Total.
+	*
+	* @param importerPath - The importer's path relative to the workspace root,
+	*   `"."` for the root package — `PackageStateSnapshot.relativePath`.
+	* @param dependency - The dependency's package name.
+	* @param specifier - The raw specifier string.
+	*/
+	resolveIn(importerPath, dependency, specifier) {
+		return this.#resolveWith(dependency, specifier, () => Option.fromUndefinedOr(this.importerVersions?.[importerPath]?.[dependency]));
+	}
+	/**
+	* The shared resolution path: classify, answer from the captured state, and
+	* consult `onUnresolvedCatalog` only for a `catalog:` specifier the catalog set
+	* could not answer. A plain range is already its own answer and must keep
+	* resolving to `Option.none()` so the caller falls back to the raw string.
+	*/
+	#resolveWith(dependency, specifier, onUnresolvedCatalog) {
 		const exit = Schema.decodeUnknownExit(DependencySpecifier.FromString)(specifier);
 		if (!Exit.isSuccess(exit)) return Option.none();
 		const classified = exit.value;
 		switch (classified._tag) {
-			case "catalog": return this.catalogs.rangeOf(dependency, classified.name);
+			case "catalog": {
+				const fromCatalogs = this.catalogs.rangeOf(dependency, classified.name);
+				return Option.isSome(fromCatalogs) ? fromCatalogs : onUnresolvedCatalog();
+			}
 			case "workspace": return Option.fromUndefinedOr(this.#versions().get(dependency));
 			default: return Option.none();
 		}

package/index.d.ts

@@ -1212,6 +1212,65 @@ declare class LockfileReader extends LockfileReader_base {
    * `const` and reuse it.
    */
   static readonly layer: (options?: LockfileReaderOptions) => Layer.Layer<LockfileReader, never, WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
+  /**
+   * A test double satisfying the full {@link LockfileReaderShape} with no
+   * filesystem, root walk, or package-manager detection.
+   *
+   * @remarks
+   * There is **no honest default lockfile**: an empty one that looks like a
+   * legitimate answer is indistinguishable from "this workspace resolves
+   * nothing" — the silent-empty failure class this package documents on the
+   * live paths — so `read` **dies** with an instructive defect until stubbed.
+   *
+   * The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+   * derived-from-the-primary rule: when a `read` override is supplied,
+   * `resolvedVersion` answers as the live service does — the **first** entry
+   * of `lockfile.packagesNamed(name)` in lockfile order, `Option.none()` on a
+   * miss — so the two stay consistent by construction. `integrity` is **not**
+   * derivable: the live method compares the lockfile against the workspace
+   * manifests discovery enumerates, and the double has no discovery to ask, so
+   * it dies unless stubbed.
+   *
+   * `refresh` defaults to `Effect.void` honestly: the live contract is "drop
+   * the memoized read so the next call re-reads", and this double memoizes
+   * nothing — every `read()` call re-invokes the override — so there is
+   * nothing to drop and the no-op is truthful, the same reasoning as
+   * `WorkspaceDiscovery.makeTest`'s `refresh`.
+   *
+   * @example
+   * ```ts
+   * import { Lockfile } from "@effected/lockfiles";
+   * import { LockfileReader } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const double = LockfileReader.makeTest({
+   *   read: () =>
+   *     Effect.succeed(
+   *       Lockfile.make({ format: "pnpm", lockfileVersion: "9.0", packages: [], workspaceDependencies: [] }),
+   *     ),
+   * });
+   * // `resolvedVersion` now answers consistently from that lockfile.
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<LockfileReaderShape>) => LockfileReaderShape;
+  /**
+   * The test layer: {@link LockfileReader.makeTest} behind `Layer.succeed`, so
+   * a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { LockfileReader } from "@effected/workspaces";
+   *
+   * const TestLockfiles = LockfileReader.layerTest();
+   * // program.pipe(Effect.provide(TestLockfiles)) — dies loudly if touched.
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<LockfileReaderShape>) => Layer.Layer<LockfileReader>;
 }
 //#endregion
 //#region src/Publishability.d.ts
@@ -1323,6 +1382,26 @@ declare class PublishabilityDetector extends PublishabilityDetector_base {
 }
 //#endregion
 //#region src/WorkspaceCatalogs.d.ts
+/**
+ * Each importer's dependency-name → resolved-version map, keyed by importer path
+ * (`"."` for the root package — the same keys `WorkspaceDiscovery.importerMap()`
+ * uses, and the same value `PackageStateSnapshot.relativePath` carries).
+ *
+ * @remarks
+ * What a manager's lockfile records as actually installed, as opposed to what a
+ * manifest declares. It answers a `catalog:` specifier no committed catalog
+ * source declares — the shape a pnpm config-dependency pnpmfile hook produces —
+ * which would otherwise resolve to nothing on both sides of a diff and hide a
+ * real version movement.
+ *
+ * Versions are normalized: pnpm's peer-disambiguation suffix
+ * (`1.2.3(effect@4.0.0)`) is stripped, and `link:` / `file:` entries are omitted
+ * because a filesystem edge is not a version. Only pnpm records importer
+ * versions; bun and npm yield an empty index.
+ *
+ * @public
+ */
+type ImporterVersions = Readonly<Record<string, Readonly<Record<string, string>>>>;
 declare const CatalogSet_base: Schema.Class<CatalogSet, Schema.Struct<{
   /** Catalog name → dependency name → version range. */
   readonly entries: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>;
@@ -1455,6 +1534,19 @@ interface WorkspaceCatalogsShape {
    * workspace) has no release-age keys, so the gate is the inert zero gate.
    */
   readonly releaseAgeGate: () => Effect.Effect<ReleaseAgeGate, CatalogAssemblyFailure>;
+  /**
+   * Each importer's dependency-name → resolved-version map, as the manager's
+   * lockfile records it. Read from the same single lockfile read as `set`, and
+   * memoized with it.
+   *
+   * @remarks
+   * Feeds `WorkspaceStateSnapshot`'s fallback for a `catalog:` specifier no
+   * committed catalog source declares — the shape a config-dependency pnpmfile
+   * hook produces. Only pnpm records importer versions; a bun or npm workspace
+   * yields an empty index, and an absent or unreadable lockfile contributes
+   * nothing rather than failing.
+   */
+  readonly importerVersions: () => Effect.Effect<ImporterVersions, CatalogAssemblyFailure>;
 }
 /**
  * Options for the {@link WorkspaceCatalogs} layer.
@@ -1520,6 +1612,61 @@ declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
    * Parameterized, so bind it to a `const` and reuse it.
    */
   static readonly layerWithConfigDependencies: (options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path>;
+  /**
+   * A test double satisfying the full {@link WorkspaceCatalogsShape} with no
+   * filesystem, lockfile read, or hook replay.
+   *
+   * @remarks
+   * There is **no honest default catalog set**: an empty `CatalogSet` that
+   * looks like a legitimate answer is the "every dependency looks newly added"
+   * failure class the live assembler hard-fails to prevent, so every method
+   * **dies** with an instructive defect until stubbed — a test-wiring mistake
+   * fails loudly as a defect rather than succeeding with a lie or failing with
+   * a dishonest typed error.
+   *
+   * The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+   * derived-from-the-primary rule: when a `set` override is supplied,
+   * `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
+   * `CatalogSet`) and always die unless stubbed.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const double = WorkspaceCatalogs.makeTest({
+   *   set: () => Effect.succeed(CatalogSet.fromCatalogs({ default: { effect: "4.0.0" } })),
+   * });
+   * // `resolveSpecifier` now answers consistently from that set.
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<WorkspaceCatalogsShape>) => WorkspaceCatalogsShape;
+  /**
+   * The test layer: {@link WorkspaceCatalogs.makeTest} behind `Layer.succeed`,
+   * so a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestCatalogs = WorkspaceCatalogs.layerTest({
+   *   set: () => Effect.succeed(CatalogSet.empty()),
+   * });
+   * // program.pipe(Effect.provide(TestCatalogs))
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<WorkspaceCatalogsShape>) => Layer.Layer<WorkspaceCatalogs>;
   /**
    * The real implementation of `@effected/npm`'s `CatalogResolver` contract —
    * the one `@effected/package-json` declares but cannot fill.
@@ -1583,6 +1730,18 @@ declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot,
   readonly packages: Schema.$Array<typeof PackageStateSnapshot>;
   /** The catalog set assembled at this moment. */
   readonly catalogs: typeof CatalogSet;
+  /**
+   * Each importer's dependency-name → resolved-version map, as the manager's
+   * lockfile recorded it at this moment.
+   *
+   * @remarks
+   * Defaults to `{}`, so a `WorkspaceStateSnapshot` serialized before this field
+   * existed still decodes — and an empty index simply makes the `catalog:`
+   * fallback in {@link WorkspaceStateSnapshot.resolve} inert, which is exactly
+   * the behavior those older values were captured under. Only pnpm records
+   * importer versions; bun and npm yield an empty index.
+   */
+  readonly importerVersions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>>;
 }>, {}>;
 /**
  * The state of a whole workspace at one moment — its packages and its assembled
@@ -1632,11 +1791,43 @@ declare class WorkspaceStateSnapshot extends WorkspaceStateSnapshot_base {
    * unparseable string — is `Option.none()`, because there is no indirection to
    * resolve. Total.
    *
+   * A `catalog:` specifier the catalog set cannot resolve falls back to this
+   * snapshot's `importerVersions` — but only to a version
+   * **every** importer recording that dependency agrees on. A catalog injected
+   * by a config-dependency pnpmfile hook appears in no committed catalog source,
+   * so without this fallback both sides of a before/after diff resolve it to the
+   * same raw string and a real version movement produces no row. When importers
+   * disagree there is no single correct answer, so this stays `Option.none()`
+   * rather than inventing one; {@link WorkspaceStateSnapshot.resolveIn} answers
+   * precisely for callers that know which importer is asking.
+   *
    * @param dependency - The dependency's package name (what `workspace:` /
    *   `catalog:` resolve for).
    * @param specifier - The raw specifier string.
    */
   resolve(dependency: string, specifier: string): Option.Option<string>;
+  /**
+   * The concrete range or version a specifier resolved to AS OF this snapshot,
+   * scoped to the importer that declared it.
+   *
+   * @remarks
+   * Identical to {@link WorkspaceStateSnapshot.resolve} except in how an
+   * unresolvable `catalog:` specifier falls back: this consults **only**
+   * `importerPath`'s own recorded versions, so a monorepo whose packages hold
+   * different versions of one dependency still gets an exact answer where
+   * `resolve` must abstain. Prefer this whenever the caller knows the importer —
+   * a consumer iterating `packages` has `relativePath` in hand, which is the
+   * importer key (`"."` for the root package).
+   *
+   * An unknown `importerPath`, or one recording nothing for `dependency`, is
+   * `Option.none()`. Total.
+   *
+   * @param importerPath - The importer's path relative to the workspace root,
+   *   `"."` for the root package — `PackageStateSnapshot.relativePath`.
+   * @param dependency - The dependency's package name.
+   * @param specifier - The raw specifier string.
+   */
+  resolveIn(importerPath: string, dependency: string, specifier: string): Option.Option<string>;
   /**
    * A `CatalogResolver` layer implementing `@effected/npm`'s contract against
    * THIS snapshot's catalog set — so code written to the contract resolves
@@ -1751,6 +1942,62 @@ declare class WorkspaceSnapshots extends WorkspaceSnapshots_base {
    * `const` and reuse it, or layer memoization does not apply.
    */
   static readonly layer: (options?: WorkspaceSnapshotsOptions) => Layer.Layer<WorkspaceSnapshots, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs>;
+  /**
+   * A test double satisfying the full {@link WorkspaceSnapshotsShape} with no
+   * git, filesystem, discovery, or catalog assembly.
+   *
+   * @remarks
+   * There are **no honest defaults and no derivations** here: `at(ref)` and
+   * `worktree()` are two independent reads of two different sources (a git ref
+   * vs. the live tree), so neither can be honestly derived from the other, and
+   * a fabricated empty {@link WorkspaceStateSnapshot} on either side of a
+   * before/after diff reads as every dependency newly added or removed — the
+   * exact silent-empty failure class this package documents on the live paths.
+   * Both methods therefore **die** with an instructive defect until stubbed; a
+   * test-wiring mistake fails loudly as a defect rather than succeeding with a
+   * lie.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceSnapshots, WorkspaceStateSnapshot } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const empty = WorkspaceStateSnapshot.make({
+   *   packages: [],
+   *   catalogs: CatalogSet.empty(),
+   *   importerVersions: {},
+   * });
+   * const double = WorkspaceSnapshots.makeTest({
+   *   at: () => Effect.succeed(empty),
+   *   worktree: () => Effect.succeed(empty),
+   * });
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<WorkspaceSnapshotsShape>) => WorkspaceSnapshotsShape;
+  /**
+   * The test layer: {@link WorkspaceSnapshots.makeTest} behind `Layer.succeed`,
+   * so a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceSnapshots, WorkspaceStateSnapshot } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestSnapshots = WorkspaceSnapshots.layerTest({
+   *   worktree: () =>
+   *     Effect.succeed(
+   *       WorkspaceStateSnapshot.make({ packages: [], catalogs: CatalogSet.empty(), importerVersions: {} }),
+   *     ),
+   * });
+   * // program.pipe(Effect.provide(TestSnapshots))
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<WorkspaceSnapshotsShape>) => Layer.Layer<WorkspaceSnapshots>;
 }
 //#endregion
 //#region src/Workspaces.d.ts
@@ -1979,5 +2226,5 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
  */
 declare const getWorkspacePackagesSync: (root: string, options: GetWorkspacePackagesSyncOptions) => ReadonlyArray<WorkspacePackage>;
 //#endregion
-export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, type SyncFileSystem, type SyncPath, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, findWorkspaceRootSync, getWorkspacePackagesSync };
+export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, type SyncFileSystem, type SyncPath, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, findWorkspaceRootSync, getWorkspacePackagesSync };
 //# sourceMappingURL=index.d.ts.map

package/internal/importerVersions.js

@@ -0,0 +1,88 @@
+//#region src/internal/importerVersions.ts
+/**
+* Strip pnpm's peer-disambiguation suffix from a recorded importer version.
+*
+* pnpm records an importer version as the resolved version followed by the peer
+* context it was resolved under — `4.0.0-beta.101(effect@4.0.0-beta.101)(ioredis@5.11.1(supports-color@8.1.1))`.
+* `@effected/lockfiles` stores that string verbatim (its `packages:` key parser
+* strips the suffix; the importer entries deliberately keep it), so the raw
+* value must never reach a consumer's dependency table — it would render the
+* whole parenthesized chain as the "version" a dependency moved to.
+*
+* Everything from the first `(` is dropped; a version with no suffix passes
+* through untouched.
+*/
+const stripPeerSuffix = (version) => {
+	const paren = version.indexOf("(");
+	return paren === -1 ? version : version.slice(0, paren);
+};
+/**
+* Whether a recorded importer version is a concrete version usable as a
+* resolution answer.
+*
+* A `link:` / `file:` entry records a filesystem edge rather than a version, and
+* an empty string is pnpm's "specifier only, nothing installed" marker. Both
+* would be worse than no answer at all: the fallback exists to report a concrete
+* version movement, and reporting `link:../foo` as a version is noise a
+* changeset would carry into release notes.
+*/
+const isConcreteVersion = (version) => version.length > 0 && !version.startsWith("link:") && !version.startsWith("file:");
+/**
+* Build the importer-path → dependency-name → version index a snapshot uses to
+* answer `catalog:` specifiers its catalog set cannot resolve.
+*
+* @remarks
+* Keyed by **name only** within each importer, deliberately across every
+* dependency field. The bug this fixes is a peer declared `catalog:effect:peers`
+* whose importer records no `peerDependencies` entry at all — pnpm writes peer
+* declarations into the importer block only when they are also installed, so the
+* concrete version lives on the package's `devDependencies` row for the same
+* name. Joining by name across fields is what finds it; joining by field, or by
+* matching the recorded specifier, would not.
+*
+* Only pnpm populates importer versions; bun and npm record resolved versions on
+* their package entries instead, so those formats yield an empty index and the
+* fallback is inert for them.
+*/
+const importerVersionsOf = (lockfile) => {
+	const index = Object.create(null);
+	for (const importer of lockfile.importers) {
+		const versions = Object.create(null);
+		for (const dependency of importer.dependencies) {
+			const recorded = dependency.version;
+			if (recorded === void 0) continue;
+			const version = stripPeerSuffix(recorded);
+			if (!isConcreteVersion(version)) continue;
+			versions[dependency.name] ??= version;
+		}
+		index[importer.path] = versions;
+	}
+	return index;
+};
+/**
+* The version every importer agrees `dependency` resolved to, or `undefined`
+* when they disagree or none record it.
+*
+* @remarks
+* The unambiguity rule is what makes a workspace-wide answer safe from a
+* snapshot method that receives no importer context. Two packages in one
+* monorepo may legitimately hold different versions of the same dependency; in
+* that case there is no single correct answer, so this yields nothing and the
+* caller keeps today's behavior (no row) rather than inventing a wrong one.
+*/
+const unanimousVersionOf = (index, dependency) => {
+	let agreed;
+	for (const versions of Object.values(index)) {
+		const version = versions[dependency];
+		if (version === void 0) continue;
+		if (agreed === void 0) {
+			agreed = version;
+			continue;
+		}
+		if (agreed !== version) return void 0;
+	}
+	return agreed;
+};
+
+//#endregion
+export { importerVersionsOf, unanimousVersionOf };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.6.2",
+	"version": "0.8.0",
 	"private": false,
 	"description": "Monorepo workspace tooling as Effect services — root discovery, package enumeration, the dependency graph, package-manager detection, pnpm catalog resolution, lockfile IO and git-based change detection.",
 	"keywords": [
@@ -46,14 +46,14 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/git": "~0.4.2",
+		"@effected/git": "~0.5.0",
 		"@effected/glob": "~0.2.1",
-		"@effected/lockfiles": "~0.1.10",
-		"@effected/npm": "~0.3.1",
-		"@effected/package-json": "~0.5.1",
+		"@effected/lockfiles": "~0.2.0",
+		"@effected/npm": "~0.4.0",
+		"@effected/package-json": "~0.5.2",
 		"@effected/semver": "~0.2.1",
 		"@effected/walker": "~0.3.2",
-		"@effected/yaml": "~0.5.1",
+		"@effected/yaml": "~0.6.0",
 		"@pnpm/catalogs.config": "^1100.0.0",
 		"@pnpm/catalogs.protocol-parser": "^1100.0.0",
 		"@pnpm/catalogs.resolver": "^1100.0.0",