@effected/workspaces 0.27.0 → 0.28.0-next-20260927071821

package/ConfigDependencyHooks.js

@@ -1,4 +1,5 @@
 import { normalize } from "./internal/catalogs.js";
+import { makeFetchConfigDependency } from "./internal/configDependencyFetch.js";
 import { lookupPnpmfiles, resolvePnpmfiles } from "./internal/configDependencyResolution.js";
 import { Context, Duration, Effect, Layer, Predicate, Schema } from "effect";
 import { CatalogAssemblyError } from "@effected/npm";
@@ -381,9 +382,10 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 	* `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
+	* a typed error with `reason: "notInstalled"` naming the package, the
+	* declared version, what is installed, the stores searched, and the
+	* remediation (`pnpm add --config <name>@<version>` in a throwaway
+	* workspace, or the subprocess layer, which fetches). 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".
@@ -396,9 +398,9 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 	* wired by `WorkspaceCatalogs.layerWithConfigDependencies` and the
 	* `Workspaces` composites of the same name.
 	*/
-	static layerLive = Layer.succeed(ConfigDependencyHooks, { inject: (root, configDependencies, seed, rules) => Effect.gen(function* () {
+	static layerLive = Layer.succeed(ConfigDependencyHooks, { inject: (root, configDependencies, seed, rules, context) => Effect.gen(function* () {
 		if (Object.keys(configDependencies).length === 0) return untouched(seed, rules);
-		const pnpmfiles = yield* resolvePnpmfiles(root, configDependencies);
+		const pnpmfiles = yield* resolvePnpmfiles(root, configDependencies, { side: context });
 		return yield* replayInProcess(pnpmfiles, seed, rules);
 	}) });
 	/**
@@ -463,9 +465,24 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 	*
 	* 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
+	* pnpm store) runs here, and the child receives the resolved
+	* `[name, fileUrl]` pairs as one JSON argv argument.
+	*
+	* One rung more than `layerLive`: a version held nowhere is FETCHED into
+	* the store rather than failing, so a diff whose base side declares a
+	* version this checkout never installed still replays that version. pnpm
+	* runs `install --frozen-lockfile` in a scratch workspace (removed
+	* afterwards) whose lockfile pins the integrity the declaring side recorded
+	* — the inline `<version>+<integrity>` spec, else that side's
+	* `pnpm-lock.yaml` env preamble ({@link HookReplayContext.lockfile}) — so
+	* pnpm itself refuses a download that does not match. It writes to the
+	* first store the ladder searched, so the next replay finds the version
+	* there. The replay records `source: "fetched"`. Fail-closed: two recorded
+	* integrities that disagree fail with `reason: "integrityMismatch"`, none
+	* with `reason: "integrityUnavailable"` — nothing is fetched in either case
+	* — and a fetch that fails with `reason: "fetchFailed"`, keeping the
+	* not-installed remediation. The fetch needs `pnpm` 11 or 12 on `PATH` and
+	* registry access, and is bounded at two minutes. 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
@@ -498,9 +515,13 @@ var ConfigDependencyHooks = class ConfigDependencyHooks extends Context.Service(
 	*/
 	static layerSubprocess = Layer.effect(ConfigDependencyHooks, Effect.gen(function* () {
 		const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-		return { inject: (root, configDependencies, seed, rules) => Effect.gen(function* () {
+		const fetch = makeFetchConfigDependency(spawner);
+		return { inject: (root, configDependencies, seed, rules, context) => Effect.gen(function* () {
 			if (Object.keys(configDependencies).length === 0) return untouched(seed, rules);
-			const pnpmfiles = yield* resolvePnpmfiles(root, configDependencies);
+			const pnpmfiles = yield* resolvePnpmfiles(root, configDependencies, {
+				side: context,
+				fetch
+			});
 			const loadable = pnpmfiles.flatMap(({ name, path }) => path === void 0 ? [] : [[name, pathToFileURL(path).href]]);
 			if (loadable.length === 0) return untouched(seed, rules, replaysOf(pnpmfiles));
 			const command = ChildProcess.make("node", [

package/ConfigDependencySpec.js

@@ -0,0 +1,170 @@
+import { splitConfigDependencySpec } from "./internal/configDependencySpecGrammar.js";
+import { Effect, Exit, Option, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
+import { SriIntegrityHash } from "@effected/npm";
+import { SemVer } from "@effected/semver";
+
+//#region src/ConfigDependencySpec.ts
+/**
+* Indicates that a string could not be parsed as a pnpm `configDependencies`
+* spec (`<version>[+<integrity>]`).
+*
+* Raised by {@link ConfigDependencySpec.parse} and
+* {@link ConfigDependencySpec.parseResult}; the decode direction of
+* {@link ConfigDependencySpec.FromString} reports the same failure through a
+* generic `Schema` parse error carrying the same message. The offending string
+* is preserved on `input`; `reason` says which half failed.
+*
+* @public
+*/
+var InvalidConfigDependencySpecError = class extends Schema.TaggedError()("InvalidConfigDependencySpecError", {
+	/** The raw spec string that failed validation. */
+	input: Schema.String,
+	/**
+	* Which half of the spec failed: `version` (the text before the first
+	* `+` is not an exact SemVer version — ranges, partial versions,
+	* dist-tags and padded values all land here) or `integrity` (the text
+	* after the first `+` is not an SRI `<algo>-<base64>` hash).
+	*/
+	reason: Schema.Literals(["version", "integrity"])
+}) {
+	get message() {
+		return this.reason === "version" ? `Invalid config dependency spec "${this.input}": version must be an exact SemVer version (ranges, partial versions and dist-tags are not allowed)` : `Invalid config dependency spec "${this.input}": integrity must be an SRI <algo>-<base64> hash`;
+	}
+};
+const specVersion = SemVer.pipe(Schema.check(Schema.makeFilter((version) => version.build.length === 0 ? void 0 : "Expected a version without build metadata")));
+/**
+* A pnpm `configDependencies` spec from `pnpm-workspace.yaml`: an exact
+* `version` and, on the legacy inline form only, an SRI `integrity`.
+*
+* @remarks
+* pnpm 11 and later write the **bare** form — `pnpm add --config` records
+* `0.11.1`, and the integrity lives in the lockfile. The inline form
+* `0.11.1+sha512-<base64>` is deprecated but still read, and workspaces in the
+* wild still carry it. {@link ConfigDependencySpec.bare} renders the bare form
+* (a tool normalizing the field writes this); `toString()` re-renders the form
+* that was parsed, so a tool that must not rewrite the field round-trips it
+* byte-identically.
+*
+* The first `+` always begins the integrity, never semver build metadata, so
+* `0.11.1+sha512-…` is version `0.11.1` plus integrity `sha512-…`; a tail that
+* is not an SRI hash fails with `reason: "integrity"` rather than falling back
+* to build-metadata parsing.
+*
+* `version` is `@effected/semver`'s `SemVer`: prerelease versions are
+* accepted, ranges (`^0.11.1`), partial versions, dist-tags, a `v` prefix and
+* padded values are not.
+*
+* @example
+* ```ts
+* import { ConfigDependencySpec } from "@effected/workspaces";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const spec = yield* ConfigDependencySpec.parse("0.11.1+sha512-m35m…==");
+*   return [spec.bare, spec.hasIntegrity] as const; // ["0.11.1", true]
+* });
+* ```
+*
+* @public
+*/
+var ConfigDependencySpec = class ConfigDependencySpec extends Schema.Class("ConfigDependencySpec")({
+	/**
+	* The exact declared version. Never carries build metadata — the spec
+	* grammar cannot express it (see the class remarks), and a version
+	* constructed with build identifiers is rejected at construction.
+	*/
+	version: specVersion,
+	/**
+	* The inline integrity (e.g. `sha512-m35m…==`): `@effected/npm`'s
+	* `SriIntegrityHash`, the shared restriction of the `IntegrityHash` brand
+	* to the SRI `<algo>-<base64>` form. `None` on the bare form pnpm 11+
+	* writes.
+	*/
+	integrity: Schema.Option(SriIntegrityHash)
+}) {
+	/**
+	* Schema transformation between the `<version>[+<integrity>]` string and a
+	* {@link ConfigDependencySpec}. Decoding parses via
+	* {@link ConfigDependencySpec.parseResult} (the surfaces share one grammar);
+	* encoding prints `toString()`, the form that was parsed.
+	*/
+	static FromString = Schema.String.pipe(Schema.decodeTo(Schema.instanceOf(ConfigDependencySpec), SchemaTransformation.transformEffect({
+		decode: (input) => {
+			const parsed = ConfigDependencySpec.parseResult(input);
+			return Result.isSuccess(parsed) ? Effect.succeed(parsed.success) : Effect.fail(new SchemaIssue.InvalidValue({ message: parsed.failure.message }, input));
+		},
+		encode: (spec) => Effect.succeed(spec.toString())
+	})));
+	/**
+	* Parse a `configDependencies` spec, synchronously, returning a `Result`
+	* instead of an `Effect`.
+	*
+	* @remarks
+	* The text before the first `+` must be an exact SemVer version that
+	* renders back to itself byte for byte (`SemVer.isPinnable`, plus a
+	* canonical-spelling check so `toString()` round-trips); the text after it,
+	* when present, must be an SRI `<algo>-<base64>` hash. An empty tail
+	* (`0.11.1+`) is an integrity failure, not a bare spec.
+	* {@link ConfigDependencySpec.parse} is defined in terms of this function.
+	*
+	* @param input - the spec string to parse
+	* @returns a `Result` succeeding with the parsed {@link ConfigDependencySpec},
+	* or failing with {@link InvalidConfigDependencySpecError} naming the half
+	* that failed.
+	*/
+	static parseResult(input) {
+		const parts = splitConfigDependencySpec(input);
+		const version = SemVer.parseResult(parts.version);
+		if (Result.isFailure(version) || !SemVer.isPinnable(parts.version) || version.success.toString() !== parts.version) return Result.fail(new InvalidConfigDependencySpecError({
+			input,
+			reason: "version"
+		}));
+		if (parts.integrity === void 0) return Result.succeed(ConfigDependencySpec.make({
+			version: version.success,
+			integrity: Option.none()
+		}));
+		const integrity = Schema.decodeUnknownExit(SriIntegrityHash)(parts.integrity);
+		if (Exit.isFailure(integrity)) return Result.fail(new InvalidConfigDependencySpecError({
+			input,
+			reason: "integrity"
+		}));
+		return Result.succeed(ConfigDependencySpec.make({
+			version: version.success,
+			integrity: Option.some(integrity.value)
+		}));
+	}
+	/**
+	* Parse a `configDependencies` spec. Defined in terms of
+	* {@link ConfigDependencySpec.parseResult} — synchronous callers can use
+	* that variant directly.
+	*
+	* @param input - the spec string to parse
+	* @returns the parsed {@link ConfigDependencySpec}. Fails with
+	* {@link InvalidConfigDependencySpecError} when `input` is not a valid spec.
+	*/
+	static parse = Effect.fn("ConfigDependencySpec.parse")((input) => Effect.fromResult(ConfigDependencySpec.parseResult(input)));
+	/** Whether the spec carries an inline integrity (the legacy form). */
+	get hasIntegrity() {
+		return Option.isSome(this.integrity);
+	}
+	/**
+	* The bare `<version>` form — what pnpm 11+ writes to `configDependencies`
+	* — with any inline integrity dropped.
+	*/
+	get bare() {
+		return this.version.toString();
+	}
+	/**
+	* The spec as parsed: `<version>` or `<version>+<integrity>`. The encode
+	* direction of {@link ConfigDependencySpec.FromString} prints exactly this.
+	*/
+	toString() {
+		return Option.match(this.integrity, {
+			onNone: () => this.bare,
+			onSome: (integrity) => `${this.bare}+${integrity}`
+		});
+	}
+};
+
+//#endregion
+export { ConfigDependencySpec, InvalidConfigDependencySpecError };

package/WorkspaceCatalogs.js

@@ -7,6 +7,7 @@ import { configDependenciesOf, inlinePeerDependencyRules } from "./internal/work
 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";
+import { filenameFor } from "@effected/lockfiles";
 
 //#region src/WorkspaceCatalogs.ts
 /**
@@ -289,10 +290,13 @@ const unstubbed = (method) => Effect.die(/* @__PURE__ */ new Error(`WorkspaceCat
 * @remarks
 * Rules are SEEDED, not merged afterwards: the workspace file's block goes
 * into the threaded config so the hooks merge onto it, exactly as pnpm seeds
-* its own config and takes back what the hooks return. Not part of the public
-* surface; `WorkspaceSnapshots` imports it directly.
+* its own config and takes back what the hooks return. `context` is the
+* document's own side — its lockfile and, at a ref, the ref — so a fetched
+* config dependency is verified against the record of the side that declared
+* it. Not part of the public surface; `WorkspaceSnapshots` imports it
+* directly.
 */
-const injectFromDocument = (hooks, root, document, inline) => Effect.map(hooks.inject(root, configDependenciesOf(document), inline.entries, inlinePeerDependencyRules(document)), (injection) => ({
+const injectFromDocument = (hooks, root, document, inline, context) => Effect.map(hooks.inject(root, configDependenciesOf(document), inline.entries, inlinePeerDependencyRules(document), context), (injection) => ({
 	injected: CatalogSet.fromCatalogs(injection.catalogs),
 	injection
 }));
@@ -370,7 +374,8 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 				yield* validatePnpmWorkspaceCatalogs(document);
 				inline = CatalogSet.fromCatalogs(inlineCatalogs(catalogBlocksOf(document)));
 				inlineGate = yield* inlineReleaseAge(document);
-				const replayed = yield* injectFromDocument(hooks, root, document, inline);
+				const lockfileText = Object.keys(configDependenciesOf(document)).length === 0 ? void 0 : yield* fs.readFileString(path.join(root, filenameFor("pnpm"))).pipe(Effect.orElseSucceed(() => void 0));
+				const replayed = yield* injectFromDocument(hooks, root, document, inline, { lockfile: lockfileText });
 				injected = replayed.injected;
 				hookGate = replayed.injection.releaseAge;
 				peerDependencyRules = replayed.injection.peerDependencyRules;

package/WorkspaceDiscovery.js

@@ -256,7 +256,8 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 			};
 		}).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
 		const discover = Effect.gen(function* () {
-			const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd()));
+			const stopAt = options?.stopAt;
+			const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd(), stopAt === void 0 ? void 0 : { stopAt }));
 			return yield* discoverAt(root);
 		});
 		const [resolveOnce, invalidate] = yield* Effect.cachedInvalidateWithTTL(discover, Duration.infinity);

package/WorkspaceRoot.js

@@ -8,6 +8,8 @@ import { Walker } from "@effected/walker";
 * @public
 */
 const WORKSPACE_MARKERS = ["pnpm-workspace.yaml", "package.json"];
+/** How the not-found message names the `package.json` marker: only one with a `workspaces` field counts. */
+const PACKAGE_JSON_MARKER_PROSE = "package.json with a \"workspaces\" field";
 /**
 * Raised when no workspace root can be found by ascending from a directory.
 *
@@ -36,7 +38,8 @@ var WorkspaceRootNotFoundError = class extends Schema.TaggedError()("WorkspaceRo
 	/** Renders the search path, probed markers and any ceiling into a one-line message. */
 	get message() {
 		const bound = this.stopAt === void 0 ? "" : ` up to ${this.stopAt}`;
-		return `No workspace root above ${this.searchPath}${bound} (looked for ${this.markers.join(", ")})`;
+		const looked = this.markers.map((marker) => marker === "package.json" ? PACKAGE_JSON_MARKER_PROSE : marker);
+		return `No workspace root above ${this.searchPath}${bound} (looked for ${looked.join(", ")})`;
 	}
 };
 /**

package/WorkspaceSnapshots.js

@@ -127,18 +127,20 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 		const catalogsService = yield* WorkspaceCatalogs;
 		const hooks = yield* ConfigDependencyHooks;
 		const seeded = (snapshot) => options?.seedCatalogs === void 0 ? snapshot : snapshot.withSeededCatalogs(options.seedCatalogs);
+		/** A manager's lockfile text at the ref, `none` when the ref has none. */
+		const lockfileText = (root, ref, format) => git.show(root, ref, `./${filenameFor(format)}`);
 		/**
 		* What a manager's lockfile records at the ref: its catalog set and its
 		* importer versions, from ONE parse. Empty on both counts when the
 		* lockfile is absent or malformed.
 		*/
-		const lockfileRecord = (root, ref, format) => git.show(root, ref, `./${filenameFor(format)}`).pipe(Effect.flatMap((content) => Option.match(content, {
+		const lockfileRecord = (content, format) => Option.match(content, {
 			onNone: () => Effect.succeed(EMPTY_LOCKFILE_RECORD),
 			onSome: (text) => Lockfile.parse(text, { format }).pipe(Effect.map((lockfile) => ({
 				catalogs: CatalogSet.fromLockfile(lockfile),
 				importerVersions: importerVersionsOf(lockfile)
 			})), Effect.catch(() => Effect.succeed(EMPTY_LOCKFILE_RECORD)))
-		})));
+		});
 		const computeAt = (root, ref) => Effect.gen(function* () {
 			const [pnpmWorkspaceText, rootManifestText] = yield* Effect.all([git.show(root, ref, "./pnpm-workspace.yaml"), git.show(root, ref, "./package.json")], { concurrency: 2 });
 			const rootManifest = Option.match(rootManifestText, {
@@ -159,15 +161,19 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 				const pnpmPatterns = pnpmPatternsOf(document);
 				patterns = pnpmPatterns.length > 0 ? pnpmPatterns : manifestPatternsOf(rootManifest);
 				inline = yield* CatalogSet.fromWorkspaceYaml(pnpmWorkspaceText.value);
-				const replayed = yield* injectFromDocument(hooks, root, document, inline);
+				const lockfile = yield* lockfileText(root, ref, "pnpm");
+				const replayed = yield* injectFromDocument(hooks, root, document, inline, {
+					lockfile: Option.getOrUndefined(lockfile),
+					ref
+				});
 				injected = replayed.injected;
 				hookReplays = replayed.injection.replays;
-				recorded = yield* lockfileRecord(root, ref, "pnpm");
+				recorded = yield* lockfileRecord(lockfile, "pnpm");
 			} else {
 				patterns = manifestPatternsOf(rootManifest);
 				inline = bunInlineCatalogs(rootManifest);
 				injected = CatalogSet.empty();
-				recorded = yield* lockfileRecord(root, ref, "bun");
+				recorded = yield* lockfileRecord(yield* lockfileText(root, ref, "bun"), "bun");
 			}
 			const catalogs = CatalogSet.merge(recorded.catalogs, inline, injected);
 			const globs = yield* GlobSet.compile(patterns).pipe(Effect.mapError((error) => new CatalogAssemblyError({

package/index.d.ts

@@ -1,10 +1,11 @@
 import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
-import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { Context, Effect, FileSystem, Layer, Option, Path, Result, Schema } from "effect";
 import { CatalogAssemblyError, CatalogResolver, DependencyResolutionError, Manifest, PartialReleaseAgeGate, ReleaseAgeGate, UnresolvedDependencyError, WorkspaceResolver } from "@effected/npm";
 import { GlobPattern } from "@effected/glob";
 import { Lockfile, LockfileFramingError, LockfileIntegrity, LockfileParseError, ResolvedPackage, WorkspaceManifest } from "@effected/lockfiles";
 import { Package } from "@effected/package-json";
 import { ChildProcessSpawner } from "effect/unstable/process";
+import { SemVer } from "@effected/semver";
 import { LocalExec } from "@effected/commands";
 //#region src/WorkspacePackage.d.ts
 declare const PublishConfig_base: Schema.Class<PublishConfig, Schema.Struct<{
@@ -540,6 +541,28 @@ interface WorkspaceDiscoveryOptions {
    *   honoured.
    */
   readonly cwd?: string;
+  /**
+   * A ceiling for the layer-bound root ascent from `cwd`, passed straight
+   * through to the `stopAt` of {@link WorkspaceRoot}'s `find`.
+   *
+   * @remarks
+   * Inclusive: the ceiling itself is probed, so a `cwd` that is its own
+   * workspace root still resolves with `stopAt: cwd`. A relative ceiling is
+   * resolved against the process working directory, exactly as `cwd` is. When
+   * no root is found at or below the ceiling, the methods fail with
+   * {@link WorkspaceRootNotFoundError} carrying the resolved `stopAt`, rather
+   * than adopting an enclosing directory's workspace — pass `stopAt: cwd` for
+   * a checkout nested inside someone else's monorepo.
+   *
+   * Applies ONLY to the layer-bound methods (`info`, `listPackages`,
+   * `importerMap`, `getPackage`, `resolveFile`, `resolveFiles`). The per-call
+   * `infoIn`, `listPackagesIn` and `refreshIn` resolve from an arbitrary
+   * directory the caller names, which a single layer-level ceiling cannot
+   * sensibly bound, so they ascend unbounded as before.
+   *
+   * @defaultValue no ceiling — the ascent runs to the filesystem root.
+   */
+  readonly stopAt?: string | undefined;
   /** Descent cap for segment-crossing patterns. Defaults to 32. */
   readonly maxDepth?: number;
 }
@@ -934,12 +957,43 @@ interface PeerDependencyRules {
 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
+ * `node_modules/.pnpm-config` copy, the pnpm store's `links/` tree, the store
+ * after {@link ConfigDependencyHooks.layerSubprocess} fetched it, or a
  * {@link ConfigDependencyHooks.layerFrom} entry.
  *
  * @public
  */
-type HookReplaySource = "installed" | "store" | "supplied";
+type HookReplaySource = "installed" | "store" | "fetched" | "supplied";
+/**
+ * What the side whose `configDependencies` are being replayed recorded beyond
+ * that map — the input the fetch rung needs to verify what it fetches.
+ *
+ * @remarks
+ * Both fields are optional, and omitting the whole context is always valid:
+ * nothing here changes which version is replayed. `lockfile` matters only when
+ * a replaying layer must fetch a version installed nowhere, and only
+ * {@link ConfigDependencyHooks.layerSubprocess} fetches. Without it, a bare
+ * `configDependencies` spec has no integrity to verify a fetch against, so the
+ * fetch fails closed with `reason: "integrityUnavailable"`.
+ *
+ * `WorkspaceCatalogs` passes the working tree's lockfile, and
+ * `WorkspaceSnapshots.at(ref)` passes the lockfile and the ref it read at, so
+ * each side of a diff is verified against its own record.
+ *
+ * @public
+ */
+interface HookReplayContext {
+  /**
+   * The declaring side's `pnpm-lock.yaml` text, whose env preamble records each
+   * config dependency's integrity. `undefined` when that side has no lockfile.
+   */
+  readonly lockfile?: string | undefined;
+  /**
+   * The git ref whose `pnpm-workspace.yaml` declared the `configDependencies`,
+   * used to name the side in error messages. `undefined` for the working tree.
+   */
+  readonly ref?: string | undefined;
+}
 /**
  * Which version of a config dependency a replay actually loaded, and where
  * that version came from.
@@ -949,7 +1003,9 @@ type HookReplaySource = "installed" | "store" | "supplied";
  * 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
+ * `store` the pnpm store's `links/` tree, `fetched` the store copy
+ * {@link ConfigDependencyHooks.layerSubprocess} fetched, verified, because
+ * neither held the declared version, and `supplied` a
  * {@link ConfigDependencyHooks.layerFrom} entry.
  *
  * @public
@@ -1048,8 +1104,12 @@ interface ConfigDependencyHooksShape {
    *   threaded config so hooks merge onto them rather than replacing them.
    *   Omitted means "the workspace file declares none", which is different
    *   from "nobody looked" — the caller owns that distinction.
+   * @param context - What the declaring side recorded beyond the map: its
+   *   lockfile, which verifies a fetched version, and its ref, which names it
+   *   in errors. Only {@link ConfigDependencyHooks.layerSubprocess} reads the
+   *   lockfile; omitting the context never changes which version is replayed.
    */
-  readonly inject: (root: string, configDependencies: Readonly<Record<string, string>>, seed: Readonly<Record<string, Readonly<Record<string, string>>>>, rules?: PeerDependencyRules) => Effect.Effect<HookInjection, CatalogAssemblyError>;
+  readonly inject: (root: string, configDependencies: Readonly<Record<string, string>>, seed: Readonly<Record<string, Readonly<Record<string, string>>>>, rules?: PeerDependencyRules, context?: HookReplayContext) => Effect.Effect<HookInjection, CatalogAssemblyError>;
 }
 declare const ConfigDependencyHooks_base: Context.ServiceClass<ConfigDependencyHooks, "@effected/workspaces/ConfigDependencyHooks", ConfigDependencyHooksShape>;
 /**
@@ -1100,9 +1160,10 @@ export declare class ConfigDependencyHooks extends ConfigDependencyHooks_base {
    * `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
+   * a typed error with `reason: "notInstalled"` naming the package, the
+   * declared version, what is installed, the stores searched, and the
+   * remediation (`pnpm add --config <name>@<version>` in a throwaway
+   * workspace, or the subprocess layer, which fetches). 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".
@@ -1174,9 +1235,24 @@ export declare class ConfigDependencyHooks extends ConfigDependencyHooks_base {
    *
    * 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
+   * pnpm store) runs here, and the child receives the resolved
+   * `[name, fileUrl]` pairs as one JSON argv argument.
+   *
+   * One rung more than `layerLive`: a version held nowhere is FETCHED into
+   * the store rather than failing, so a diff whose base side declares a
+   * version this checkout never installed still replays that version. pnpm
+   * runs `install --frozen-lockfile` in a scratch workspace (removed
+   * afterwards) whose lockfile pins the integrity the declaring side recorded
+   * — the inline `<version>+<integrity>` spec, else that side's
+   * `pnpm-lock.yaml` env preamble ({@link HookReplayContext.lockfile}) — so
+   * pnpm itself refuses a download that does not match. It writes to the
+   * first store the ladder searched, so the next replay finds the version
+   * there. The replay records `source: "fetched"`. Fail-closed: two recorded
+   * integrities that disagree fail with `reason: "integrityMismatch"`, none
+   * with `reason: "integrityUnavailable"` — nothing is fetched in either case
+   * — and a fetch that fails with `reason: "fetchFailed"`, keeping the
+   * not-installed remediation. The fetch needs `pnpm` 11 or 12 on `PATH` and
+   * registry access, and is bounded at two minutes. 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
@@ -1210,6 +1286,157 @@ export declare class ConfigDependencyHooks extends ConfigDependencyHooks_base {
   static readonly layerSubprocess: Layer.Layer<ConfigDependencyHooks, never, ChildProcessSpawner.ChildProcessSpawner>;
 }
 //#endregion
+//#region src/ConfigDependencySpec.d.ts
+declare const InvalidConfigDependencySpecError_base: Schema.Class<InvalidConfigDependencySpecError, Schema.TaggedStruct<"InvalidConfigDependencySpecError", {
+  /** The raw spec string that failed validation. */
+  readonly input: Schema.String;
+  /**
+   * Which half of the spec failed: `version` (the text before the first
+   * `+` is not an exact SemVer version — ranges, partial versions,
+   * dist-tags and padded values all land here) or `integrity` (the text
+   * after the first `+` is not an SRI `<algo>-<base64>` hash).
+   */
+  readonly reason: Schema.Literals<readonly ["version", "integrity"]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a string could not be parsed as a pnpm `configDependencies`
+ * spec (`<version>[+<integrity>]`).
+ *
+ * Raised by {@link ConfigDependencySpec.parse} and
+ * {@link ConfigDependencySpec.parseResult}; the decode direction of
+ * {@link ConfigDependencySpec.FromString} reports the same failure through a
+ * generic `Schema` parse error carrying the same message. The offending string
+ * is preserved on `input`; `reason` says which half failed.
+ *
+ * @public
+ */
+export declare class InvalidConfigDependencySpecError extends InvalidConfigDependencySpecError_base {
+  get message(): string;
+}
+declare const ConfigDependencySpec_base: Schema.Class<ConfigDependencySpec, Schema.Struct<{
+  /**
+   * The exact declared version. Never carries build metadata — the spec
+   * grammar cannot express it (see the class remarks), and a version
+   * constructed with build identifiers is rejected at construction.
+   */
+  readonly version: Schema.decodeTo<Schema.declareConstructor<SemVer, {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly prerelease: readonly (string | number)[];
+    readonly build: readonly string[];
+  }, readonly [Schema.Struct<{
+    readonly major: Schema.Number;
+    readonly minor: Schema.Number;
+    readonly patch: Schema.Number;
+    readonly prerelease: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+    readonly build: Schema.$Array<Schema.String>;
+  }>], {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly prerelease: readonly (string | number)[];
+    readonly build: readonly string[];
+  }>, Schema.Struct<{
+    readonly major: Schema.Number;
+    readonly minor: Schema.Number;
+    readonly patch: Schema.Number;
+    readonly prerelease: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+    readonly build: Schema.$Array<Schema.String>;
+  }>, never, never>;
+  /**
+   * The inline integrity (e.g. `sha512-m35m…==`): `@effected/npm`'s
+   * `SriIntegrityHash`, the shared restriction of the `IntegrityHash` brand
+   * to the SRI `<algo>-<base64>` form. `None` on the bare form pnpm 11+
+   * writes.
+   */
+  readonly integrity: Schema.Option<Schema.brand<Schema.String, "IntegrityHash">>;
+}>, {}>;
+/**
+ * A pnpm `configDependencies` spec from `pnpm-workspace.yaml`: an exact
+ * `version` and, on the legacy inline form only, an SRI `integrity`.
+ *
+ * @remarks
+ * pnpm 11 and later write the **bare** form — `pnpm add --config` records
+ * `0.11.1`, and the integrity lives in the lockfile. The inline form
+ * `0.11.1+sha512-<base64>` is deprecated but still read, and workspaces in the
+ * wild still carry it. {@link ConfigDependencySpec.bare} renders the bare form
+ * (a tool normalizing the field writes this); `toString()` re-renders the form
+ * that was parsed, so a tool that must not rewrite the field round-trips it
+ * byte-identically.
+ *
+ * The first `+` always begins the integrity, never semver build metadata, so
+ * `0.11.1+sha512-…` is version `0.11.1` plus integrity `sha512-…`; a tail that
+ * is not an SRI hash fails with `reason: "integrity"` rather than falling back
+ * to build-metadata parsing.
+ *
+ * `version` is `@effected/semver`'s `SemVer`: prerelease versions are
+ * accepted, ranges (`^0.11.1`), partial versions, dist-tags, a `v` prefix and
+ * padded values are not.
+ *
+ * @example
+ * ```ts
+ * import { ConfigDependencySpec } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const spec = yield* ConfigDependencySpec.parse("0.11.1+sha512-m35m…==");
+ *   return [spec.bare, spec.hasIntegrity] as const; // ["0.11.1", true]
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class ConfigDependencySpec extends ConfigDependencySpec_base {
+  /**
+   * Schema transformation between the `<version>[+<integrity>]` string and a
+   * {@link ConfigDependencySpec}. Decoding parses via
+   * {@link ConfigDependencySpec.parseResult} (the surfaces share one grammar);
+   * encoding prints `toString()`, the form that was parsed.
+   */
+  static readonly FromString: Schema.Codec<ConfigDependencySpec, string>;
+  /**
+   * Parse a `configDependencies` spec, synchronously, returning a `Result`
+   * instead of an `Effect`.
+   *
+   * @remarks
+   * The text before the first `+` must be an exact SemVer version that
+   * renders back to itself byte for byte (`SemVer.isPinnable`, plus a
+   * canonical-spelling check so `toString()` round-trips); the text after it,
+   * when present, must be an SRI `<algo>-<base64>` hash. An empty tail
+   * (`0.11.1+`) is an integrity failure, not a bare spec.
+   * {@link ConfigDependencySpec.parse} is defined in terms of this function.
+   *
+   * @param input - the spec string to parse
+   * @returns a `Result` succeeding with the parsed {@link ConfigDependencySpec},
+   * or failing with {@link InvalidConfigDependencySpecError} naming the half
+   * that failed.
+   */
+  static parseResult(input: string): Result.Result<ConfigDependencySpec, InvalidConfigDependencySpecError>;
+  /**
+   * Parse a `configDependencies` spec. Defined in terms of
+   * {@link ConfigDependencySpec.parseResult} — synchronous callers can use
+   * that variant directly.
+   *
+   * @param input - the spec string to parse
+   * @returns the parsed {@link ConfigDependencySpec}. Fails with
+   * {@link InvalidConfigDependencySpecError} when `input` is not a valid spec.
+   */
+  static readonly parse: (input: string) => Effect.Effect<ConfigDependencySpec, InvalidConfigDependencySpecError, never>;
+  /** Whether the spec carries an inline integrity (the legacy form). */
+  get hasIntegrity(): boolean;
+  /**
+   * The bare `<version>` form — what pnpm 11+ writes to `configDependencies`
+   * — with any inline integrity dropped.
+   */
+  get bare(): string;
+  /**
+   * The spec as parsed: `<version>` or `<version>+<integrity>`. The encode
+   * direction of {@link ConfigDependencySpec.FromString} prints exactly this.
+   */
+  toString(): string;
+}
+//#endregion
 //#region src/DependencyGraph.d.ts
 declare const CyclicDependencyError_base: Schema.Class<CyclicDependencyError, Schema.TaggedStruct<"CyclicDependencyError", {
   /** The packages participating in the cycle. */
@@ -4312,5 +4539,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, 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 };
+export type { CatalogAssemblyFailure, ChangeDetectionFailure, ChangeDetectorShape, ClassifyOptions, ConfigDependencyHooksShape, DependencyDiff, DuplicateCheckOptions, FindWorkspaceRootOptions, GetWorkspacePackagesSyncOptions, HookInjection, HookReplay, HookReplayContext, 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

package/index.js

@@ -4,6 +4,7 @@ import { PackageNotFoundError, WorkspaceDiscovery, WorkspaceDiscoveryError, Work
 import { CyclicDependencyError, DependencyGraph } from "./DependencyGraph.js";
 import { ChangeDetectionError, ChangeDetectionOptions, ChangeDetector } from "./ChangeDetector.js";
 import { ConfigDependencyHooks, NoPeerDependencyRules } from "./ConfigDependencyHooks.js";
+import { ConfigDependencySpec, InvalidConfigDependencySpecError } from "./ConfigDependencySpec.js";
 import { Dependent, DuplicateCheck, DuplicateInstance, DuplicatedPackage, DuplicatedVersion } from "./DuplicateCheck.js";
 import { DetectedPackageManager, PackageManagerDetectionError, PackageManagerDetector, PackageManagerEvidence, PackageManagerName } from "./PackageManagerName.js";
 import { LockfileReadError, LockfileReader } from "./LockfileReader.js";
@@ -17,4 +18,4 @@ import { WorkspaceSnapshots } from "./WorkspaceSnapshots.js";
 import { Workspaces } from "./Workspaces.js";
 import { findWorkspaceRootSync, getWorkspacePackagesSync } from "./WorkspacesSync.js";
 
-export { CatalogSet, ChangeDetectionError, ChangeDetectionOptions, ChangeDetector, ConfigDependencyHooks, CyclicDependencyError, DependencyGraph, Dependent, DetectedPackageManager, DuplicateCheck, DuplicateInstance, DuplicatedPackage, DuplicatedVersion, LockfileReadError, LockfileReader, NoPeerDependencyRules, PackageManagerDetectionError, PackageManagerDetector, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PeerCheck, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, ReleaseTag, TagStyle, TrackingTag, UnsatisfiedPeer, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, WorkspaceSnapshots, WorkspaceStateSnapshot, Workspaces, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
+export { CatalogSet, ChangeDetectionError, ChangeDetectionOptions, ChangeDetector, ConfigDependencyHooks, ConfigDependencySpec, CyclicDependencyError, DependencyGraph, Dependent, DetectedPackageManager, DuplicateCheck, DuplicateInstance, DuplicatedPackage, DuplicatedVersion, InvalidConfigDependencySpecError, LockfileReadError, LockfileReader, NoPeerDependencyRules, PackageManagerDetectionError, PackageManagerDetector, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PeerCheck, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, ReleaseTag, TagStyle, TrackingTag, UnsatisfiedPeer, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, WorkspaceDiscovery, WorkspaceDiscoveryError, WorkspaceInfo, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, WorkspaceSnapshots, WorkspaceStateSnapshot, Workspaces, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };

package/internal/configDependencyFetch.js

@@ -0,0 +1,146 @@
+import { carries, manifestVersion, messageOf, sideLabel } from "./configDependencyShared.js";
+import { splitConfigDependencySpec } from "./configDependencySpecGrammar.js";
+import { Duration, Effect } from "effect";
+import { IntegrityHash } from "@effected/npm";
+import { Run } from "@effected/commands";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+//#region src/internal/configDependencyFetch.ts
+const fetchFailure = (reason, message, cause) => cause === void 0 ? {
+	reason,
+	message
+} : {
+	reason,
+	message,
+	cause
+};
+/**
+* The ceiling on one fetch. It downloads one small tarball; two minutes covers
+* a slow registry without letting a hung pnpm stall catalog assembly forever.
+*/
+const FETCH_TIMEOUT = Duration.minutes(2);
+/**
+* The integrity the fetched copy must match, decided before anything is
+* spawned: the inline spec integrity (legacy) and the declaring side's
+* lockfile preamble entry for exactly `<name>@<version>`. Both present and
+* different, neither present, an inline integrity that is not SRI, or a
+* lockfile that cannot be read all fail typed. A lockfile that records the
+* name at a different version is not a source for this version.
+*
+* @remarks
+* An unreadable lockfile fails closed even when the spec carries an inline
+* integrity: the lockfile is the declaring side's own checksum store, and a
+* store that cannot be read cannot be confirmed to agree with the inline pin.
+*/
+const expectedIntegrity = (request) => Effect.gen(function* () {
+	const { name, version, side } = request;
+	const key = `${name}@${version}`;
+	const inline = splitConfigDependencySpec(request.spec).integrity;
+	if (inline !== void 0 && !IntegrityHash.isSri(inline)) return yield* Effect.fail(fetchFailure("integrityUnavailable", `config dependency ${key} declared by ${sideLabel(side)} carries an inline integrity that is not an SRI hash, so a fetched copy cannot be verified and nothing was fetched.`));
+	const lock = (yield* request.locks.pipe(Effect.mapError((cause) => fetchFailure("integrityUnavailable", `config dependency ${key} must be fetched, but the pnpm-lock.yaml of ${sideLabel(side)} cannot be read (${messageOf(cause)}), so its recorded integrity cannot be checked and nothing was fetched.`, cause))))?.get(name);
+	const locked = lock !== void 0 && lock.version === version ? lock.integrity : void 0;
+	if (inline !== void 0 && locked !== void 0 && inline !== locked) return yield* Effect.fail(fetchFailure("integrityMismatch", `config dependency ${key} declared by ${sideLabel(side)} has two different recorded integrities: pnpm-workspace.yaml pins ${inline} and pnpm-lock.yaml records ${locked}. Nothing was fetched; reconcile the two (a fresh \`pnpm install\` rewrites the lockfile) before retrying.`));
+	const integrity = inline ?? locked;
+	if (integrity === void 0) return yield* Effect.fail(fetchFailure("integrityUnavailable", `config dependency ${key} must be fetched, but ${sideLabel(side)} records no integrity for it (no inline integrity in pnpm-workspace.yaml and no pnpm-lock.yaml entry for that version), so a fetched copy could not be verified and nothing was fetched.`));
+	return integrity;
+});
+/**
+* The scratch workspace's `pnpm-workspace.yaml`. Every scalar is a
+* JSON-quoted string, which YAML reads verbatim, so no declared text can
+* change the document's structure.
+*/
+const scratchWorkspaceYaml = (name, version) => `configDependencies:\n  ${JSON.stringify(name)}: ${JSON.stringify(version)}\n`;
+/**
+* The scratch workspace's `pnpm-lock.yaml`: the env preamble pnpm 11 and 12
+* write for a lone config dependency, pinned to `integrity`, followed by the
+* empty lockfile document they write when there are no projects.
+*/
+const scratchLockfile = (name, version, integrity) => {
+	const key = JSON.stringify(`${name}@${version}`);
+	return [
+		"---",
+		"lockfileVersion: '9.0'",
+		"",
+		"importers:",
+		"",
+		"  .:",
+		"    configDependencies:",
+		`      ${JSON.stringify(name)}:`,
+		`        specifier: ${JSON.stringify(version)}`,
+		`        version: ${JSON.stringify(version)}`,
+		"",
+		"packages:",
+		"",
+		`  ${key}:`,
+		`    resolution: {integrity: ${JSON.stringify(integrity)}}`,
+		"",
+		"snapshots:",
+		"",
+		`  ${key}: {}`,
+		"",
+		"---",
+		""
+	].join("\n");
+};
+/**
+* The `--store-dir` to hand pnpm so it writes into the store the ladder
+* searched first. Discovered stores are the versioned directories
+* (`<root>/v11`), and pnpm appends that segment itself, so a versioned
+* directory is passed as its parent. `undefined` (pnpm's own default) when no
+* store was discovered.
+*/
+const storeDirArgument = (stores) => {
+	const first = stores[0];
+	if (first === void 0) return void 0;
+	return /^v\d+$/.test(basename(first)) ? dirname(first) : first;
+};
+/** The pnpm argv for the verified fetch. */
+const fetchArgs = (scratch, stores) => {
+	const storeDir = storeDirArgument(stores);
+	return [
+		"install",
+		"--frozen-lockfile",
+		"--dir",
+		scratch,
+		...storeDir === void 0 ? [] : ["--store-dir", storeDir]
+	];
+};
+/** Whether `resolved` sits under a store's `links/<name>/<version>/` tree. */
+const isStoreEntry = (resolved, name, version) => resolved.split(/[/\\]/).join("/").includes(`/links/${name}/${version}/`);
+/**
+* Build the fetch rung over a spawner. Wired only by
+* `ConfigDependencyHooks.layerSubprocess`.
+*/
+const makeFetchConfigDependency = (spawner) => (request) => Effect.scoped(Effect.gen(function* () {
+	const { name, version } = request;
+	const key = `${name}@${version}`;
+	const failed = (message, cause) => fetchFailure("fetchFailed", message, cause);
+	const io = (what, run) => Effect.tryPromise({
+		try: run,
+		catch: (cause) => failed(`${what} failed: ${messageOf(cause)}`, cause)
+	});
+	const integrity = yield* expectedIntegrity(request);
+	const scratch = yield* Effect.acquireRelease(io("creating a scratch workspace", () => mkdtemp(join(tmpdir(), "effected-config-dependency-"))), (dir) => Effect.promise(() => rm(dir, {
+		recursive: true,
+		force: true
+	}).catch(() => void 0)));
+	const lockfile = scratchLockfile(name, version, integrity);
+	yield* io("writing the scratch workspace", async () => {
+		await writeFile(join(scratch, "pnpm-workspace.yaml"), scratchWorkspaceYaml(name, version));
+		await writeFile(join(scratch, "pnpm-lock.yaml"), lockfile);
+	});
+	const command = ChildProcess.make("pnpm", fetchArgs(scratch, request.stores), { cwd: scratch });
+	yield* Run.text(command, { timeout: FETCH_TIMEOUT }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner), Effect.mapError((cause) => failed(`fetching ${key} with \`pnpm ${fetchArgs("<scratch>", request.stores).join(" ")}\` failed: ${messageOf(cause)}`, cause)));
+	if ((yield* io("reading back the scratch lockfile", () => readFile(join(scratch, "pnpm-lock.yaml"), "utf8"))) !== lockfile) return yield* Effect.fail(failed(`fetching ${key}: pnpm rewrote the integrity-pinned scratch lockfile instead of installing from it, so the installed copy was not verified against the recorded integrity and is not used.`));
+	const linked = join(scratch, "node_modules", ".pnpm-config", name);
+	const resolved = yield* io(`resolving ${linked}`, () => realpath(linked));
+	const manifest = yield* manifestVersion(name, resolved).pipe(Effect.mapError((error) => failed(`the fetched ${key} has an unreadable package.json: ${messageOf(error.cause)}`, error.cause)));
+	if (!carries(manifest, version) || !isStoreEntry(resolved, name, version)) return yield* Effect.fail(failed(`fetching ${key}: pnpm linked ${resolved}, which is not a store copy of that version (its manifest reads ${manifest._tag === "version" ? manifest.version : "no version"}).`));
+	return resolved;
+}));
+
+//#endregion
+export { expectedIntegrity, fetchArgs, makeFetchConfigDependency, storeDirArgument };

package/internal/configDependencyResolution.js

@@ -1,6 +1,9 @@
+import { carries, hooksError, ioOrNone, manifestVersion, sideLabel } from "./configDependencyShared.js";
+import { splitConfigDependencySpec } from "./configDependencySpecGrammar.js";
 import { Array, Duration, Effect, Exit, Option, Predicate, Result } from "effect";
-import { CatalogAssemblyError, PackageManagerCache } from "@effected/npm";
+import { PackageManagerCache } from "@effected/npm";
 import { Yaml } from "@effected/yaml";
+import { PnpmEnvLockfile } from "@effected/lockfiles";
 import { readFile, readdir, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
@@ -15,11 +18,13 @@ const PNPMFILE_CANDIDATES = [
 /**
 * The version part of a `configDependencies` spec: the text before the first
 * `+` (`0.9.0+sha512-…` → `0.9.0`); a bare `0.9.0` is returned whole.
+*
+* Deliberately lenient — it goes through the same split as the public
+* `ConfigDependencySpec` but validates neither half. See
+* `configDependencySpecGrammar.ts` for why replay must not adopt the strict
+* model's rejections.
 */
-const declaredVersionOf = (spec) => {
-	const plus = spec.indexOf("+");
-	return plus === -1 ? spec : spec.slice(0, plus);
-};
+const declaredVersionOf = (spec) => splitConfigDependencySpec(spec).version;
 /**
 * Whether a config-dependency `name` carries a `..` path segment. A scoped name
 * legitimately contains `/` (`@scope/pkg`), so only a `..` *segment* is rejected —
@@ -27,12 +32,6 @@ const declaredVersionOf = (spec) => {
 * dynamic `import()`.
 */
 const hasTraversalSegment = (name) => name.split(/[/\\]/).includes("..");
-/** The typed `hooks`-source failure every rung of the ladder reports through. */
-const hooksError = (path, cause) => new CatalogAssemblyError({
-	source: "hooks",
-	path,
-	cause
-});
 /**
 * The declared `(name, version)` pairs of a `configDependencies` map, in
 * declaration order, with EVERY name validated before any path is built from
@@ -42,36 +41,12 @@ const hooksError = (path, cause) => new CatalogAssemblyError({
 const declaredEntries = (configDependencies) => {
 	const entries = Object.entries(configDependencies).map(([name, spec]) => ({
 		name,
-		version: declaredVersionOf(spec)
+		version: declaredVersionOf(spec),
+		spec
 	}));
 	const traversal = entries.find((entry) => hasTraversalSegment(entry.name));
 	return traversal === void 0 ? Effect.succeed(entries) : Effect.fail(hooksError(traversal.name, /* @__PURE__ */ new Error(`config dependency name has a '..' path segment: ${traversal.name}`)));
 };
-/** Whether a `node:fs` rejection means "nothing there" (as opposed to a real IO failure). */
-const isAbsent = (cause) => Predicate.isObject(cause) && (cause.code === "ENOENT" || cause.code === "ENOTDIR");
-/**
-* Run a `node:fs/promises` call, mapping an absent target to `Option.none()`
-* and ANY other rejection (`EACCES`, `EIO`, …) to a typed `hooks` error
-* attributed to `path` — never a silent skip.
-*/
-const ioOrNone = (path, run) => Effect.tryPromise({
-	try: run,
-	catch: (cause) => cause
-}).pipe(Effect.map(Option.some), Effect.catch((cause) => isAbsent(cause) ? Effect.succeed(Option.none()) : Effect.fail(hooksError(path, cause))));
-/**
-* The `version` of the `package.json` in `dir`: `None` when the manifest is
-* absent, `Some("")` when present but carrying no string version (so it can
-* never match a declared version), typed on any other IO failure or on
-* unparseable JSON — a manifest that exists but cannot be read is not
-* evidence of absence.
-*/
-const manifestVersion = (name, dir) => ioOrNone(name, () => readFile(join(dir, "package.json"), "utf8")).pipe(Effect.flatMap((text) => {
-	if (Option.isNone(text)) return Effect.succeed(Option.none());
-	return Effect.try({
-		try: () => JSON.parse(text.value),
-		catch: (cause) => hooksError(name, cause)
-	}).pipe(Effect.map((parsed) => Option.some(Predicate.isObject(parsed) && typeof parsed.version === "string" ? parsed.version : "")));
-}));
 /** Directory entries of `dir`, or `[]` when it is absent; typed on any other failure. */
 const entriesOf = (path, dir) => ioOrNone(path, () => readdir(dir)).pipe(Effect.map(Option.getOrElse(() => [])));
 /** The `<root>/node_modules/.pnpm-config` directory. */
@@ -206,7 +181,7 @@ const findInStores = (name, declared, stores) => Effect.gen(function* () {
 		for (const hash of yield* entriesOf(name, versionDir)) {
 			const dir = join(versionDir, hash, "node_modules", name);
 			const version = yield* manifestVersion(name, dir);
-			if (Option.isSome(version) && version.value === declared) matches.push(dir);
+			if (carries(version, declared)) matches.push(dir);
 		}
 		if (matches.length > 0) return {
 			store,
@@ -220,12 +195,23 @@ const findInStores = (name, declared, stores) => Effect.gen(function* () {
 });
 /** The fail-closed message for a version ONE store holds more than once: which store, which copies, how to disambiguate. */
 const ambiguousMessage = (name, declared, store, matches) => `config dependency ${name}@${declared} is ambiguous: the pnpm store at ${store} holds ${matches.length} copies of that version (${matches.join(", ")}) and the store records no integrity to tell them apart, so none is replayed. Remove the stale copies, or install ${name}@${declared} in this workspace so node_modules/.pnpm-config answers instead.`;
-/** The fail-closed message: what was declared, what is installed, where we looked, and how to fix it. */
-const notInstalledMessage = (name, declared, installed, stores) => {
-	return `config dependency ${name}@${declared} is not installed: node_modules/.pnpm-config/${name} holds ${Option.match(installed, {
-		onNone: () => "nothing",
-		onSome: (version) => version === "" ? "a package with no version" : `version ${version}`
-	})}, and no store copy of ${name}@${declared} was found (${stores.length === 0 ? "no pnpm store directory could be located" : `searched ${stores.join(", ")}`}). Run \`pnpm add --config ${name}@${declared}\` in a throwaway workspace to populate the store, then retry.`;
+/**
+* The fail-closed message: what was declared, by which side, what is
+* installed, where we looked, why that happens, and how to fix it. `fetch`
+* is the fetch rung's failure when one ran.
+*/
+const notInstalledMessage = (name, declared, installed, stores, side, fetch) => {
+	const holds = installed._tag === "absent" ? "nothing" : installed._tag === "unversioned" ? "a package with no version" : `version ${installed.version}`;
+	const searched = stores.length === 0 ? "no pnpm store directory could be located" : `searched ${stores.join(", ")}`;
+	return [
+		`config dependency ${name}@${declared}${side.ref === void 0 ? "" : ` (declared at ${sideLabel(side)})`} is not installed: node_modules/.pnpm-config/${name} holds ${holds}, and no store copy of ${name}@${declared} was found (${searched}).`,
+		installed._tag === "version" && installed.version !== declared ? "This side declares a different version from the installed one, as the base side of a diff across a config-dependency bump does: that version was never installed in this checkout." : "",
+		Option.match(fetch, {
+			onNone: () => "This replay layer does not fetch; ConfigDependencyHooks.layerSubprocess, which the *Subprocess Workspaces composites use, fetches the declared version, verified, into the store.",
+			onSome: (failure) => failure.reason === "fetchFailed" ? `Fetching it into the store failed: ${failure.message}` : failure.message
+		}),
+		Option.exists(fetch, (failure) => failure.reason === "integrityMismatch") ? "" : `Run \`pnpm add --config ${name}@${declared}\` in a throwaway workspace to populate the store, then retry.`
+	].filter((sentence) => sentence !== "").join(" ");
 };
 /**
 * The first pnpmfile candidate present in `dir`, from ONE directory listing.
@@ -238,14 +224,26 @@ const pnpmfileIn = (name, dir) => entriesOf(name, dir).pipe(Effect.map((entries)
 /**
 * Resolve one declared config dependency to the directory holding its
 * declared version: `.pnpm-config` when it holds exactly that version, else
-* the store, else a typed fail-closed error. `stores` is the memoized
-* discovery, run at most once per {@link resolvePnpmfiles} call and only on
-* the first `.pnpm-config` miss.
+* the store, else the fetch rung when one is wired, else a typed fail-closed
+* error. `stores` is the memoized discovery, run at most once per
+* {@link resolvePnpmfiles} call and only on the first `.pnpm-config` miss;
+* `locks` is the declaring side's memoized lockfile decode, run at most once
+* per call and only by the fetch rung.
+*
+* @remarks
+* A fetch failure is folded into the not-installed message, so the error
+* still says what was declared, what is installed and where the ladder
+* looked, and it keeps the fetch rung's own `reason` (`integrityMismatch`,
+* `integrityUnavailable`, `fetchFailed`). The `pnpm add --config`
+* remediation is kept except for `integrityMismatch`, where the pins must be
+* reconciled first.
 */
-const resolveDirectory = (root, name, declared, stores) => Effect.gen(function* () {
+const resolveDirectory = (root, entry, stores, locks, options) => Effect.gen(function* () {
+	const { name, version: declared } = entry;
+	const side = options.side ?? {};
 	const installedDir = join(pnpmConfigDir(root), name);
 	const installed = yield* manifestVersion(name, installedDir);
-	if (Option.isSome(installed) && installed.value === declared) return {
+	if (carries(installed, declared)) return {
 		dir: installedDir,
 		source: "installed"
 	};
@@ -256,23 +254,51 @@ const resolveDirectory = (root, name, declared, stores) => Effect.gen(function*
 		dir: only,
 		source: "store"
 	};
-	if (only !== void 0) return yield* Effect.fail(hooksError(name, new Error(ambiguousMessage(name, declared, store, matches))));
-	return yield* Effect.fail(hooksError(name, new Error(notInstalledMessage(name, declared, installed, searched))));
+	if (only !== void 0) return yield* Effect.fail(hooksError(name, new Error(ambiguousMessage(name, declared, store, matches)), "ambiguous"));
+	const notInstalled = (fetch) => {
+		const message = notInstalledMessage(name, declared, installed, searched, side, fetch);
+		const cause = Option.getOrUndefined(fetch)?.cause;
+		return hooksError(name, cause === void 0 ? new Error(message) : new Error(message, { cause }), Option.match(fetch, {
+			onNone: () => "notInstalled",
+			onSome: (failure) => failure.reason
+		}));
+	};
+	if (options.fetch === void 0) return yield* Effect.fail(notInstalled(Option.none()));
+	return {
+		dir: yield* options.fetch({
+			name,
+			version: declared,
+			spec: entry.spec,
+			stores: searched,
+			side,
+			locks
+		}).pipe(Effect.mapError((failure) => notInstalled(Option.some(failure)))),
+		source: "fetched"
+	};
 });
 /**
+* A lazy memo of `effect`, scoped to one {@link resolvePnpmfiles} call: the
+* house success-only memo (never `Effect.cached`, which would pin an
+* interrupt), so a failed or interrupted run is retried by the next user.
+*/
+const memoizeSuccess = (effect) => Effect.map(Effect.cachedInvalidateWithTTL(effect, Duration.infinity), ([once, invalidate]) => Effect.onExit(once, (exit) => Exit.isSuccess(exit) ? Effect.void : invalidate));
+/**
 * Resolve every declared config dependency at its declared version, in
 * declaration order. A dependency that ships no pnpmfile is still returned
 * (resolved, `path` undefined — the one legitimate skip at replay time); a
 * `..` segment in a name, an unresolvable declared version, or any
 * non-absent IO failure fails typed as a `hooks`-source
-* `CatalogAssemblyError`.
+* `CatalogAssemblyError`. `options.fetch`, when wired, is tried for a version
+* found nowhere before that fails.
 */
-const resolvePnpmfiles = (root, configDependencies) => Effect.gen(function* () {
+const resolvePnpmfiles = (root, configDependencies, options = {}) => Effect.gen(function* () {
 	const entries = yield* declaredEntries(configDependencies);
-	const [discoverOnce, invalidate] = yield* Effect.cachedInvalidateWithTTL(discoverStores(root), Duration.infinity);
-	const stores = Effect.onExit(discoverOnce, (exit) => Exit.isSuccess(exit) ? Effect.void : invalidate);
-	return yield* Effect.forEach(entries, ({ name, version }) => Effect.gen(function* () {
-		const { dir, source } = yield* resolveDirectory(root, name, version, stores);
+	const stores = yield* memoizeSuccess(discoverStores(root));
+	const lockfile = options.side?.lockfile;
+	const locks = lockfile === void 0 ? Effect.succeed(void 0) : yield* memoizeSuccess(PnpmEnvLockfile.configDependencies(lockfile));
+	return yield* Effect.forEach(entries, (entry) => Effect.gen(function* () {
+		const { name, version } = entry;
+		const { dir, source } = yield* resolveDirectory(root, entry, stores, locks, options);
 		const pnpmfile = yield* pnpmfileIn(name, dir);
 		return {
 			name,

package/internal/configDependencyShared.js

@@ -0,0 +1,51 @@
+import { Effect, Option, Predicate } from "effect";
+import { CatalogAssemblyError } from "@effected/npm";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+//#region src/internal/configDependencyShared.ts
+/** The typed `hooks`-source failure every rung of the ladder reports through. */
+const hooksError = (path, cause, reason) => new CatalogAssemblyError({
+	source: "hooks",
+	path,
+	cause,
+	...reason === void 0 ? {} : { reason }
+});
+/** The message of a cause, for splicing into ours. */
+const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Where the declared spec came from, for messages: `the working tree` or `ref <ref>`. */
+const sideLabel = (side) => side.ref === void 0 ? "the working tree" : `ref ${side.ref}`;
+/** Whether a `node:fs` rejection means "nothing there" (as opposed to a real IO failure). */
+const isAbsent = (cause) => Predicate.isObject(cause) && (cause.code === "ENOENT" || cause.code === "ENOTDIR");
+/**
+* Run a `node:fs/promises` call, mapping an absent target to `Option.none()`
+* and ANY other rejection (`EACCES`, `EIO`, …) to a typed `hooks` error
+* attributed to `path` — never a silent skip.
+*/
+const ioOrNone = (path, run) => Effect.tryPromise({
+	try: run,
+	catch: (cause) => cause
+}).pipe(Effect.map(Option.some), Effect.catch((cause) => isAbsent(cause) ? Effect.succeed(Option.none()) : Effect.fail(hooksError(path, cause))));
+const ABSENT = { _tag: "absent" };
+const UNVERSIONED = { _tag: "unversioned" };
+/** Whether a manifest carries exactly `declared`. Only a `version` state can. */
+const carries = (manifest, declared) => manifest._tag === "version" && manifest.version === declared;
+/**
+* The version state of the `package.json` in `dir`: `absent` when there is
+* no manifest, `unversioned` when it carries no non-empty string `version`,
+* typed on any other IO failure or on unparseable JSON — a manifest that
+* exists but cannot be read is not evidence of absence.
+*/
+const manifestVersion = (name, dir) => ioOrNone(name, () => readFile(join(dir, "package.json"), "utf8")).pipe(Effect.flatMap((text) => {
+	if (Option.isNone(text)) return Effect.succeed(ABSENT);
+	return Effect.try({
+		try: () => JSON.parse(text.value),
+		catch: (cause) => hooksError(name, cause)
+	}).pipe(Effect.map((parsed) => Predicate.isObject(parsed) && typeof parsed.version === "string" && parsed.version !== "" ? {
+		_tag: "version",
+		version: parsed.version
+	} : UNVERSIONED));
+}));
+
+//#endregion
+export { carries, hooksError, ioOrNone, manifestVersion, messageOf, sideLabel };

package/internal/configDependencySpecGrammar.js

@@ -0,0 +1,15 @@
+//#region src/internal/configDependencySpecGrammar.ts
+/** Split a spec on its first `+`: `0.9.0+sha512-…` → `{ version: "0.9.0", integrity: "sha512-…" }`. */
+const splitConfigDependencySpec = (spec) => {
+	const plus = spec.indexOf("+");
+	return plus === -1 ? {
+		version: spec,
+		integrity: void 0
+	} : {
+		version: spec.slice(0, plus),
+		integrity: spec.slice(plus + 1)
+	};
+};
+
+//#endregion
+export { splitConfigDependencySpec };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.27.0",
+	"version": "0.28.0-next-20260927071821",
 	"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": [
@@ -55,9 +55,9 @@
 		"@effected/git": "^0.17.0",
 		"@effected/glob": "^0.8.0",
 		"@effected/jsonc": "^0.13.0",
-		"@effected/lockfiles": "^0.11.0",
-		"@effected/npm": "^0.16.0",
-		"@effected/package-json": "^0.17.0",
+		"@effected/lockfiles": "^0.12.0-next-20260927071821",
+		"@effected/npm": "^0.17.0-next-20260927071821",
+		"@effected/package-json": "^0.18.0-next-20260927071821",
 		"@effected/semver": "^0.9.0",
 		"@effected/walker": "^0.12.0",
 		"@effected/yaml": "^0.17.0",

package/testing.d.ts

@@ -633,6 +633,28 @@ interface WorkspaceDiscoveryOptions {
    *   honoured.
    */
   readonly cwd?: string;
+  /**
+   * A ceiling for the layer-bound root ascent from `cwd`, passed straight
+   * through to the `stopAt` of {@link WorkspaceRoot}'s `find`.
+   *
+   * @remarks
+   * Inclusive: the ceiling itself is probed, so a `cwd` that is its own
+   * workspace root still resolves with `stopAt: cwd`. A relative ceiling is
+   * resolved against the process working directory, exactly as `cwd` is. When
+   * no root is found at or below the ceiling, the methods fail with
+   * {@link WorkspaceRootNotFoundError} carrying the resolved `stopAt`, rather
+   * than adopting an enclosing directory's workspace — pass `stopAt: cwd` for
+   * a checkout nested inside someone else's monorepo.
+   *
+   * Applies ONLY to the layer-bound methods (`info`, `listPackages`,
+   * `importerMap`, `getPackage`, `resolveFile`, `resolveFiles`). The per-call
+   * `infoIn`, `listPackagesIn` and `refreshIn` resolve from an arbitrary
+   * directory the caller names, which a single layer-level ceiling cannot
+   * sensibly bound, so they ascend unbounded as before.
+   *
+   * @defaultValue no ceiling — the ascent runs to the filesystem root.
+   */
+  readonly stopAt?: string | undefined;
   /** Descent cap for segment-crossing patterns. Defaults to 32. */
   readonly maxDepth?: number;
 }