@effected/workspaces 0.30.3 → 0.31.0

package/DependencyGraph.js

@@ -33,8 +33,9 @@ cycle: Schema.Array(Schema.String) }) {
 * `dependencies`, `devDependencies`, `peerDependencies` and
 * `optionalDependencies`; a self-edge is dropped.
 *
-* Total accessors never fail; the four fallible operations are `Effect.fn`
-* boundaries.
+* Total accessors never fail. The lookups fail with `PackageNotFoundError` for
+* an unknown name, and the ordering operations (`levels`, `sort`, `sortSubset`)
+* fail with {@link CyclicDependencyError} when the graph has a cycle.
 *
 * @example
 * ```ts
@@ -141,8 +142,11 @@ packages: Schema.Array(WorkspacePackage) }) {
 		})) : Effect.succeed([...dependents].sort());
 	});
 	/**
-	* `name` plus every package that transitively depends on it — the blast
-	* radius of a change. Sorted; includes `name` itself.
+	* Each of `names` plus every package that transitively depends on any of
+	* them — the blast radius of a change. Sorted and de-duplicated; the given
+	* names are included, whether or not the graph knows them.
+	*
+	* @param names - The changed package names.
 	*/
 	affectedBy = Effect.fn("DependencyGraph.affectedBy")((names) => {
 		const { reverse } = this.#index();
@@ -162,9 +166,8 @@ packages: Schema.Array(WorkspacePackage) }) {
 	* the workspace, level *n* depends only on levels below it.
 	*
 	* @remarks
-	* Kahn's algorithm over the reverse-edge index — linear, where v3's rescanned
-	* the whole adjacency map per processed node. Each level is sorted
-	* lexicographically, so the output is deterministic.
+	* Kahn's algorithm over the reverse-edge index, linear in the edge count.
+	* Each level is sorted lexicographically, so the output is deterministic.
 	*/
 	levels = Effect.fn("DependencyGraph.levels")(() => Effect.suspend(() => {
 		const edges = this.#index();
@@ -176,6 +179,13 @@ packages: Schema.Array(WorkspacePackage) }) {
 	/**
 	* A topological order over `names` plus their transitive workspace
 	* dependencies — the build order for a subset.
+	*
+	* @remarks
+	* Fails with `PackageNotFoundError` for a name the graph does not contain,
+	* and with {@link CyclicDependencyError} when the subset's closure has a
+	* cycle.
+	*
+	* @param names - The packages to build; each must be a workspace package.
 	*/
 	sortSubset = Effect.fn("DependencyGraph.sortSubset")((names) => Effect.suspend(() => {
 		const { forward } = this.#index();

package/DuplicateCheck.js

@@ -85,10 +85,12 @@ var DuplicatedPackage = class extends Schema.Class("DuplicatedPackage")({
 *
 * @example
 * ```ts
-* import { DuplicateCheck } from "@effected/workspaces";
 * import { Lockfile } from "@effected/lockfiles";
+* import { DuplicateCheck } from "@effected/workspaces";
 * import { Effect } from "effect";
 *
+* declare const text: string; // the text of a pnpm-lock.yaml
+*
 * const program = Effect.gen(function* () {
 *   const lockfile = yield* Lockfile.parse(text, { format: "pnpm" });
 *   const report = DuplicateCheck.run(lockfile, { names: DuplicateCheck.kit });
@@ -119,8 +121,8 @@ var DuplicateCheck = class DuplicateCheck extends Schema.Class("DuplicateCheck")
 	* In practice this is the **root importer under npm and bun**: neither
 	* records a resolved version per importer dependency, and neither emits a
 	* package row for the root, so there is nothing to join on. pnpm records a
-	* version per importer dependency and is unaffected. The same limitation
-	* `PeerCheck` reports, measured by the same code.
+	* version per importer dependency and is unaffected. `PeerCheck` reports the
+	* same limitation.
 	*
 	* Reported rather than silently skipped: a gate that sees no duplicates is
 	* entitled to know whether that means "clean" or "not looked at".
@@ -147,8 +149,7 @@ var DuplicateCheck = class DuplicateCheck extends Schema.Class("DuplicateCheck")
 	* Exactly those — not `@effect/*`, and not names merely starting with
 	* `effect`. A duplicated kit package presents as a `Layer` requirement that
 	* looks provided yet cannot be satisfied, at the entry point, naming neither
-	* the package nor the skew (issue #298); this predicate is the check that
-	* names both.
+	* the package nor the skew; this predicate is the check that names both.
 	*
 	* @param name - a package name
 	* @returns whether the name belongs to the kit
@@ -222,7 +223,7 @@ var DuplicateCheck = class DuplicateCheck extends Schema.Class("DuplicateCheck")
 		const dependents = /* @__PURE__ */ new Map();
 		const seen = /* @__PURE__ */ new Set();
 		const record = (targetId, dependent) => {
-			const key = `${targetId}${renderKey(dependent)}`;
+			const key = `${targetId}\0${renderKey(dependent)}`;
 			if (seen.has(key)) return;
 			seen.add(key);
 			const list = dependents.get(targetId) ?? [];
@@ -287,7 +288,7 @@ const dependentOf = (from) => from.isWorkspace && from.relativePath !== void 0 ?
 	version: from.version
 };
 /** @internal */
-const renderKey = (dependent) => dependent._tag === "importer" ? `importer${dependent.path}` : `package${dependent.name}${dependent.version}`;
+const renderKey = (dependent) => dependent._tag === "importer" ? `importer\0${dependent.path}` : `package\0${dependent.name}\0${dependent.version}`;
 
 //#endregion
 export { Dependent, DuplicateCheck, DuplicateInstance, DuplicatedPackage, DuplicatedVersion };

package/LayerPolicy.js

@@ -59,7 +59,7 @@ var LayerPolicyError = class extends Schema.TaggedError()("LayerPolicyError", {
 * message names every such key. A typo on an optional key would otherwise be
 * silently dropped: `requiredEdge` would remove the non-vacuity guard and
 * leave the report green. `$schema` is always accepted. A file that carries
-* keys of its own, such as systems' `harness`, passes them in `allowKeys`.
+* keys of its own, such as a `harness` block, passes them in `allowKeys`.
 *
 * @example
 * ```ts

package/LockfileReader.js

@@ -112,11 +112,14 @@ var LockfileReader = class LockfileReader extends Context.Service()("@effected/w
 		};
 	});
 	/**
-	* The live layer.
+	* The live layer: reads the lockfile of the detected package manager at the
+	* workspace root.
 	*
 	* @remarks
 	* Parameterized, so it mints a fresh reference per call — bind it to a
 	* `const` and reuse it.
+	*
+	* @param options - Root resolution (`cwd`, `stopAt`).
 	*/
 	static layer = (options) => Layer.effect(LockfileReader, LockfileReader.make(options));
 	/**

package/PackageManagerName.js

@@ -82,8 +82,8 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 * is not an exact version.
 *
 * Reuses the corepack `name@version+integrity` grammar rather than a second
-* parser, so a `devEngines` version carrying a hash (`11.11.0+sha512.…`, which
-* this repo's own root manifest does) normalizes to the same `11.11.0` the
+* parser, so a `devEngines` version carrying a hash (`11.11.0+sha512.…`)
+* normalizes to the same `11.11.0` the
 * top-level field reports — and a *range* (`^11`, `11.x`) yields none, because a
 * range is not a version and corepack will not run one either.
 */
@@ -326,8 +326,7 @@ var PackageManagerDetector = class PackageManagerDetector extends Context.Servic
 	* `WorkspaceDiscovery.info` posture, for the same reason. A stand-in that
 	* answered `"pnpm"` would hand a consumer a fact nothing established, and it
 	* would contradict the very service it stands in for: the live detector's
-	* defining property is that it [refuses to
-	* guess](https://github.com/spencerbeggs/effected) when no evidence matches.
+	* defining property is that it refuses to guess when no evidence matches.
 	* A double that guesses is worse than no double.
 	*
 	* Failing typed would be the subtler mistake: `PackageManagerDetectionError`

package/PeerCheck.js

@@ -402,10 +402,12 @@ const judgeJoined = (context, catalogs, peer, declared, optional) => {
 *
 * @example
 * ```ts
-* import { PeerCheck } from "@effected/workspaces";
 * import { Lockfile } from "@effected/lockfiles";
+* import { PeerCheck } from "@effected/workspaces";
 * import { Effect } from "effect";
 *
+* declare const text: string; // the text of a pnpm-lock.yaml
+*
 * const program = Effect.gen(function* () {
 *   const lockfile = yield* Lockfile.parse(text, { format: "pnpm" });
 *   const report = PeerCheck.run(lockfile);
@@ -508,7 +510,7 @@ var PeerCheck = class PeerCheck extends Schema.Class("PeerCheck")({
 	* `pnpm peers check` DOES report the linked parent's peers (it reads the
 	* manifest on disk): every `link:` edge whose target the caller did not
 	* supply therefore fails the report closed rather than letting the
-	* invisible parent pass as checked (effected#800).
+	* invisible parent pass as checked.
 	*
 	* Supplying {@link PeerCheckOptions.workspacePackages} closes that gap for
 	* every `link:` target the set covers — the root importer's included,
@@ -543,6 +545,8 @@ var PeerCheck = class PeerCheck extends Schema.Class("PeerCheck")({
 	* version check, and a plain unparseable version is still skipped.
 	*
 	* @param lockfile - a lockfile parsed by `@effected/lockfiles`
+	* @param options - the workspace's effective rules, manifests and catalogs; see
+	*   {@link PeerCheckOptions}
 	* @returns the report; never fails
 	*/
 	static run(lockfile, options) {

package/Publishability.js

@@ -87,16 +87,13 @@ var PublishTarget = class extends Schema.Class("PublishTarget")({
 var PublishabilityDetector = class extends Context.Service()("@effected/workspaces/PublishabilityDetector") {
 	/**
 	* Standard npm publishing semantics, **as a value**. Pure — no filesystem,
-	* no platform services.
+	* no platform services. Never publishes with provenance (`provenance: false`).
 	*
 	* @remarks
 	* Exposed as a shape and not only as a layer, because a consumer composing
-	* *around* these rules cannot reach them through a layer without re-entering
-	* the very tag it is replacing. `@savvy-web/silk-effects` had to write
-	* `Effect.provide(PublishabilityDetector, PublishabilityDetector.layer)`
-	* **inside its own implementation of that tag** to get at this function for
-	* its pass-through branch; with the value exposed that becomes
-	* `PublishabilityDetector.npm.detect(pkg)`.
+	* *around* these rules cannot reach them through a layer without
+	* re-entering the very tag it is replacing. A custom detector's pass-through
+	* branch calls `PublishabilityDetector.npm.detect(pkg)` directly.
 	*
 	* @example
 	* ```ts
@@ -131,13 +128,12 @@ var PublishabilityDetector = class extends Context.Service()("@effected/workspac
 	*
 	* @remarks
 	* Named for its policy rather than called `layer`, deliberately. **No
-	* composite in this package provides a publishability detector**: a
-	* `Workspaces.layer()` that quietly supplied npm semantics made the choice
-	* invisible, and worse, made a naively-ordered override lose to it in
-	* silence — `Layer.mergeAll(myDetector, Workspaces.layer())` resolved to the
-	* default, because `mergeAll` is last-wins. For a service that decides
-	* whether a package publishes and to which registry, that silent revert was
-	* the worst available failure.
+	* composite in this package provides a publishability detector**: one that
+	* quietly supplied npm semantics would hide the choice and, because
+	* `Layer.mergeAll` is last-wins, would let a naively-ordered override such
+	* as `Layer.mergeAll(myDetector, Workspaces.layer())` lose to the default in
+	* silence. For a service that decides whether a package publishes and to
+	* which registry, that silent revert is the worst available failure.
 	*
 	* The composites do not *require* a detector either — nothing inside them
 	* asks a publishability question, so their `R` stays `FileSystem | Path`.

package/README.md

@@ -7,10 +7,10 @@
 
 Monorepo workspace tooling for [Effect](https://effect.website) v4: find the workspace root, enumerate its packages, walk the dependency graph, detect the package manager, resolve pnpm catalogs, read the lockfile, check it for unsatisfied peer dependencies and work out which packages a git range touches. Every capability is a service you provide at the edge and swap in tests. Works with npm, pnpm, yarn Berry and bun.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/ReleaseTag.js

@@ -194,11 +194,11 @@ const classifyTag = (tag) => {
 * even when `value` carries a prefix, so a consumer comparing versions never
 * has to strip one back off.
 *
-* Formatting is **total**: there is no error channel, because the only failure
-* v3 modelled — an empty version — is caught by `Schema.NonEmptyString` when
-* the value is constructed. A bad version reaching these statics is developer
-* wiring rather than untrusted input, so it dies as a defect, the same posture
-* as an uncompilable glob literal in `WorkspacePackage.matchesDependency`.
+* Formatting has **no error channel**: an empty version is rejected by
+* `Schema.NonEmptyString` when the value is constructed. A bad version
+* reaching these statics is developer wiring rather than untrusted input, so it
+* dies as a defect, the same posture as an uncompilable glob literal in
+* `WorkspacePackage.matchesDependency`.
 *
 * @example
 * ```ts
@@ -227,6 +227,7 @@ var ReleaseTag = class ReleaseTag extends Schema.Class("ReleaseTag")({
 	*
 	* @param version - The version being released. Must not be empty.
 	* @param options - Formatting overrides.
+	* @returns the single-style {@link ReleaseTag}.
 	*/
 	static single(version, options) {
 		const prefix = options?.versionPrefix ?? "";

package/SourceBoundary.js

@@ -616,7 +616,7 @@ var SourceBoundary = class SourceBoundary {
 	});
 	/** The shipped positive- and negative-control snippets, at least one of each per rule kind. */
 	static fixtures = FIXTURES;
-	/** The names of shipped fixtures the scanner now gets wrong; `[]` means it still flags and spares what it must. */
+	/** The names of shipped fixtures the scanner gets wrong; `[]` means it still flags and spares what it must. */
 	static verifyFixtures = () => FIXTURES.filter((fixture) => SourceBoundary.check("fixture.ts", fixture.source, [fixture.rule]).length > 0 !== fixture.flagged).map((fixture) => `${fixture.flagged ? "missed" : "false positive"}: ${fixture.name}`);
 };
 

package/VersioningStrategy.js

@@ -30,13 +30,13 @@ const VersioningStrategyType = Schema.Literals([
 *
 * @example
 * ```ts
-* import { VersioningStrategy } from "@effected/workspaces";
+* import { PublishabilityDetector, VersioningStrategy } from "@effected/workspaces";
 * import { Effect } from "effect";
 *
 * const program = Effect.gen(function* () {
-*   const strategy = yield* VersioningStrategy.detect({ fixedGroups });
-*   return strategy.tagsFor(released).map((tag) => tag.value);
-* });
+*   const strategy = yield* VersioningStrategy.detect({ fixedGroups: [["@acme/a", "@acme/b"]] });
+*   return strategy.tagsFor([{ name: "@acme/a", version: "1.2.3" }]).map((tag) => tag.value);
+* }).pipe(Effect.provide(PublishabilityDetector.layerNpm));
 * ```
 *
 * @public
@@ -66,6 +66,9 @@ var VersioningStrategy = class VersioningStrategy extends Schema.Class("Versioni
 	* Pure and total — no IO, no error channel. `packages` is sorted and
 	* de-duplicated first, so a name listed twice cannot inflate a one-package
 	* repo into an independent one.
+	*
+	* @param options - The publishable package names and any fixed groups.
+	* @returns the classified {@link VersioningStrategy}.
 	*/
 	static classify(options) {
 		const fixedGroups = options.fixedGroups ?? [];
@@ -85,6 +88,10 @@ var VersioningStrategy = class VersioningStrategy extends Schema.Class("Versioni
 	* The publishability question is asked through the service precisely so a
 	* consumer with its own rules — honouring a release tool's ignore list, say —
 	* swaps the layer instead of filtering afterwards.
+	*
+	* Requires `WorkspaceDiscovery` and `PublishabilityDetector` (for example
+	* `PublishabilityDetector.layerNpm`) in `R`, and fails with
+	* `WorkspaceDiscoveryFailure` when discovery does.
 	*/
 	static detect = Effect.fn("VersioningStrategy.detect")(function* (options) {
 		const discovery = yield* WorkspaceDiscovery;
@@ -114,6 +121,9 @@ var VersioningStrategy = class VersioningStrategy extends Schema.Class("Versioni
 	* one-line check rather than a field here.
 	*
 	* An empty batch produces no tags under either style.
+	*
+	* @param releases - The packages released and their versions.
+	* @param options - Tag formatting overrides, such as `versionPrefix`.
 	*/
 	tagsFor(releases, options) {
 		if (releases.length === 0) return [];

package/WorkspaceCatalogs.js

@@ -578,10 +578,9 @@ var WorkspaceCatalogs = class WorkspaceCatalogs extends Context.Service()("@effe
 	* `rangeOf` returns `Option.none()` for a dependency no catalog declares, per
 	* the contract's convention. A failed catalog *assembly* — an unreadable or
 	* malformed `pnpm-workspace.yaml`, a broken config-dependency hook — passes
-	* through **typed** as the contract's `CatalogAssemblyError` (it used to be
-	* folded into `DependencyResolutionError`'s defect `cause`, which forced
-	* consumers to `_tag`-sniff `unknown`); only the remaining mechanism failure,
-	* an unfindable workspace root, is wrapped as `DependencyResolutionError`.
+	* through **typed** as the contract's `CatalogAssemblyError`; only the
+	* remaining mechanism failure, an unfindable workspace root, is wrapped as
+	* `DependencyResolutionError`.
 	*/
 	static catalogResolver = Layer.effect(CatalogResolver, Effect.gen(function* () {
 		const catalogs = yield* WorkspaceCatalogs;

package/WorkspaceDiscovery.js

@@ -19,7 +19,7 @@ import { DependencyResolutionError, WorkspaceResolver } from "@effected/npm";
 * A manifest with no `version` is NOT a failure: pnpm accepts a version-less
 * private package and a private monorepo root without one is the ordinary
 * shape, so the member is discovered with `WorkspacePackage.version` absent.
-* The former `missingVersion` kind is retired. Only ABSENCE is tolerated: a
+* Only ABSENCE is tolerated: a
 * `version` that is present but not a string — or present and `""`, which pnpm
 * never wrote and which would resolve `workspace:^` to a bare `"^"` — is the
 * manifest's shape being wrong and reports `invalidShape`.
@@ -118,11 +118,9 @@ const patternKindOf = (kind) => kind;
 * the lifetime of the layer. A Vitest reporter that builds the layer per call
 * site and never queries it pays nothing.
 *
-* The memo is **success-only**. `Effect.cached` memoizes the first `Exit`,
-* *including an interrupt* — an init interrupted by an unrelated timeout would
-* otherwise brick the layer permanently with a cause outside its declared error
-* channel. A failure or interrupt is therefore retried on the next call, which
-* is a deliberate behaviour change from the v3 library.
+* The memo is **success-only**: a failure or interrupt is not cached, so an
+* init interrupted by an unrelated timeout cannot brick the layer, and the next
+* call retries.
 *
 * @example
 * ```ts
@@ -380,12 +378,14 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 		};
 	});
 	/**
-	* The live layer.
+	* The live layer, discovering the workspace from `options.cwd`.
 	*
 	* @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 `layer(...)` at each composition site.
+	*
+	* @param options - Root resolution and enumeration bounds.
 	*/
 	static layer = (options) => Layer.effect(WorkspaceDiscovery, WorkspaceDiscovery.make(options));
 	/**

package/WorkspacePackage.js

@@ -119,13 +119,9 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 	* Absolute path to the workspace root this package was discovered under.
 	*
 	* @remarks
-	* Carried, not derived. Whoever built this value already knew the root —
-	* `WorkspaceDiscovery` resolved it before enumerating, and the sync entry
-	* point is handed it — so dropping it forced every consumer into per-package
-	* root arithmetic (counting `relativePath` segments and re-ascending that
-	* many `..`). That reconstruction is exact only while `path` and
-	* `relativePath` agree, and it re-derives something the kit never had to
-	* lose.
+	* Carried, not derived: `WorkspaceDiscovery` resolves the root before
+	* enumerating, so every package arrives with it and consumers need no
+	* per-package root arithmetic over `relativePath`.
 	*
 	* For the root package this equals `path`, and `relativePath` is `"."`.
 	*/
@@ -152,8 +148,7 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 	* validated beyond being a record. For the strict typed model use
 	* `manifest()`, which deliberately **re-reads** the file — a point-in-time
 	* refresh this captured record cannot provide. Defaults to `{}` for
-	* construction sites and previously-serialized values that predate the
-	* field.
+	* values constructed or decoded without the field.
 	*/
 	manifestRecord: Schema.Record(Schema.String, Schema.Unknown).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY_MANIFEST)), Schema.withConstructorDefault(Effect.succeed(EMPTY_MANIFEST)))
 }) {
@@ -218,8 +213,8 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 		return version === void 0 ? Option.none() : Option.some(version);
 	}
 	/**
-	* Whether any dependency name matches `pattern` — the `minimatch` runtime
-	* dependency's one call site, now over `@effected/glob`'s vendored engine.
+	* Whether any dependency name (across all four kinds) matches the glob
+	* `pattern`, using `@effected/glob`.
 	*
 	* @remarks
 	* A `GlobPattern` is total and free to test. A `string` is compiled on every
@@ -235,7 +230,12 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 		const compiled = typeof pattern === "string" ? GlobPattern.make({ source: pattern }) : pattern;
 		return Object.keys(this.allDependencies).some((dependency) => compiled.matches(dependency));
 	}
-	/** Compare this package's dependencies against `other`'s. */
+	/**
+	* Compare this package's dependencies against `other`'s, treating `other` as
+	* the baseline: what this package added, removed or re-specified.
+	*
+	* @param other - The package to compare against.
+	*/
 	dependencyDiff(other) {
 		const mine = this.allDependencies;
 		const theirs = other.allDependencies;
@@ -271,6 +271,10 @@ var WorkspacePackage = class WorkspacePackage extends Schema.Class("WorkspacePac
 	* Read and decode this package's `package.json` into the strict
 	* `@effected/package-json` `Package` model — the bridge from the
 	* tolerant discovery projection to the fully typed manifest.
+	*
+	* @remarks
+	* Fails with {@link WorkspaceManifestError} (`kind: "read"` or `"decode"`) and
+	* requires core `FileSystem`.
 	*/
 	static manifest = Effect.fn("WorkspacePackage.manifest")(function* (self) {
 		const content = yield* (yield* FileSystem.FileSystem).readFileString(self.packageJsonPath).pipe(Effect.mapError((cause) => new WorkspaceManifestError({

package/WorkspaceRoot.js

@@ -127,12 +127,10 @@ var WorkspaceRoot = class WorkspaceRoot extends Context.Service()("@effected/wor
 	* A test double resolving every `find` to `root`, with no filesystem.
 	*
 	* @remarks
-	* The nine-copies-of-a-four-line-mock case — a `Layer.succeed` over a `find`
-	* that ignores its arguments and succeeds with a fixed root is what consumers
-	* were writing by hand. The difference is that this double **honours
-	* `stopAt`**: a hand-rolled `find` that ignores the ceiling makes a bounded
-	* call pass under test and fail against the live service, which is the
-	* failure mode the option exists to catch. A `root` above the ceiling fails
+	* Stands in for a hand-written `Layer.succeed` over a `find` that ignores its
+	* arguments. Unlike that, this double **honours `stopAt`**: a `find` that
+	* ignores the ceiling makes a bounded call pass under test and fail against
+	* the live service, which is the failure mode the option exists to catch. A `root` above the ceiling fails
 	* here exactly as it would live, with the same
 	* {@link WorkspaceRootNotFoundError}.
 	*

package/WorkspaceSnapshots.js

@@ -250,11 +250,14 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 		};
 	});
 	/**
-	* The live layer.
+	* The live layer, reading workspace state at a git ref or from the live
+	* worktree.
 	*
 	* @remarks
 	* Parameterized, so it mints a fresh reference per call — bind it to a
 	* `const` and reuse it, or layer memoization does not apply.
+	*
+	* @param options - Root resolution and the optional `seedCatalogs`.
 	*/
 	static layer = (options) => Layer.effect(WorkspaceSnapshots, WorkspaceSnapshots.make(options));
 	/**

package/WorkspaceStateSnapshot.js

@@ -12,10 +12,9 @@ const DependencyMap = Schema.Record(Schema.String, Schema.String).pipe(Schema.wi
 *
 * @remarks
 * The Type side is a `NonEmptyString`, so `make` rejects `""` outright. The
-* encoded side stays a plain optional string for one reason only: snapshots
-* serialized while `""` was the "declared no version" sentinel must still
-* decode, and they decode to the absent key they always meant — so an old
-* stored value and a fresh capture of the same manifest compare equal.
+* encoded side stays a plain optional string so that a stored value carrying
+* `""` still decodes, to the absent key it meant — a stored value and a fresh
+* capture of the same manifest compare equal.
 */
 const SnapshotVersion = Schema.optionalKey(Schema.String).pipe(Schema.decodeTo(Schema.optionalKey(Schema.NonEmptyString), SchemaTransformation.transformOptional({
 	decode: (encoded) => Option.filter(encoded, (version) => version !== ""),
@@ -47,8 +46,7 @@ var PackageStateSnapshot = class extends Schema.Class("PackageStateSnapshot")({
 	* an ordinary pnpm shape. Both capture paths — `WorkspaceSnapshots.at(ref)`
 	* and `WorkspaceSnapshots.worktree()` — omit the key for such a member, so
 	* the two sides of a diff agree without a placeholder. Never `""`: `make`
-	* rejects it, and a snapshot serialized when `""` was the "no version"
-	* sentinel decodes to the absent key.
+	* rejects it, and a stored `""` decodes to the absent key.
 	*
 	* A version-less member is still a member: it appears in `packages` and
 	* answers {@link WorkspaceStateSnapshot.package}, but is absent from
@@ -125,11 +123,9 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 	* 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.
+	* Defaults to `{}` when absent from a stored value; an empty index makes the
+	* `catalog:` fallback in {@link WorkspaceStateSnapshot.resolve} inert. 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))),
 	/**
@@ -143,9 +139,8 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 	* diagnostic and off this serializable value. Every fresh read sets the
 	* field: `{}` under the no-op layer, which resolves nothing, when the file
 	* declares no config dependencies, or on the bun / `package.json` path,
-	* where config dependencies do not exist. Absent only when decoding a
-	* snapshot serialized before the field existed, so stored values stay
-	* readable. Carried through `withSeededCatalogs` and `crossSeed`
+	* where config dependencies do not exist. Absent only when decoding a stored
+	* value that omits it. Carried through `withSeededCatalogs` and `crossSeed`
 	* unchanged, like `importerVersions`.
 	*/
 	hookReplays: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
@@ -171,8 +166,7 @@ var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("
 	* replays the ref's own pinned hook and the seed answers only what neither
 	* source declared.
 	*
-	* Defaults to absent, which makes the seed inert — exactly the behavior of
-	* every snapshot captured before this field existed.
+	* Defaults to absent, which makes the seed inert.
 	*/
 	seededCatalogs: Schema.optionalKey(CatalogSet)
 }) {

package/Workspaces.js

@@ -80,13 +80,12 @@ var Workspaces = class {
 	* @remarks
 	* Requires core `FileSystem` and `Path`, which the consumer provides at the
 	* edge (`@effect/platform-node`, `@effect/platform-bun`, or a test's
-	* `FileSystem.layerNoop`).
+	* `@effected/memfs` volume).
 	*
 	* **`PublishabilityDetector` is neither provided nor required here.** The
-	* composite used to bake in npm semantics, which a naively-ordered override
-	* silently lost to; now it supplies no default, and — because nothing inside
-	* the composite asks a publishability question — it does not require one in
-	* `R` either. The requirement surfaces in the `R` of each operation that
+	* composite supplies no default policy, and — because nothing inside it asks
+	* a publishability question — it does not require one in `R` either. The
+	* requirement surfaces in the `R` of each operation that
 	* asks (`VersioningStrategy.detect`, e.g.), so a program that asks and never
 	* wires a detector fails to compile at that operation, and a program that
 	* never asks never supplies a publish policy. Wire one explicitly where
@@ -167,10 +166,9 @@ var Workspaces = class {
 	* `pnpmfile.cjs` hooks**.
 	*
 	* @remarks
-	* The composite that did not exist. `layerWithGit` hard-wires the no-op
-	* catalogs layer, so a consumer wanting snapshots + git + hook replay had to
-	* rebuild the entire service graph by hand — which is exactly what
-	* `@savvy-web/silk-effects` did, and the copy this static deletes.
+	* `layerWithGit` wires the no-op catalogs layer, so this is the composite to
+	* reach for when you want snapshots, git and hook replay together without
+	* assembling the service graph by hand.
 	*
 	* Requirements are unchanged from {@link Workspaces.layerWithGit}: a
 	* filesystem, a path service, and core's `ChildProcessSpawner` (behind
@@ -233,8 +231,7 @@ var Workspaces = class {
 	* and {@link ConfigDependencyHooks.layerSubprocess}. It exists for the fourth
 	* policy: {@link ConfigDependencyHooks.layerFrom}, the hermetic seam, which a
 	* snapshot-backed test otherwise cannot reach without rebuilding the whole
-	* git graph by hand — the copy `layerWithGitAndConfigDependencies` was added
-	* to delete. The ONE hooks reference is handed to both `WorkspaceCatalogs`
+	* git graph by hand. The ONE hooks reference is handed to both `WorkspaceCatalogs`
 	* and `WorkspaceSnapshots`, so `at(ref)` and `worktree()` cannot drift on
 	* which policy they replay. A hooks layer carrying its own requirement (the
 	* subprocess variant's `ChildProcessSpawner`) threads it through to the
@@ -264,13 +261,11 @@ var Workspaces = class {
 	* contract: how to run a project-local binary here.
 	*
 	* @remarks
-	* **An inverted contract, the `@effected/npm` `CatalogResolver`
-	* precedent.** Tool discovery needs package-manager detection and
-	* workspace-root resolution, both of which live here — but a direct edge
-	* from `@effected/commands` to this package would make that boundary-tier
-	* package integrated, and through the planned `npm` → `commands` edge
-	* would drag `npm`, `lockfiles` (pure!) and `package-json` up a tier with
-	* it. So `commands` declares the narrow contract and we ship the layer.
+	* **An inverted contract, like `@effected/npm`'s `CatalogResolver`.** Tool
+	* discovery needs package-manager detection and workspace-root resolution,
+	* both of which live here, but `@effected/commands` must not depend on this
+	* package. So `commands` declares the narrow `LocalExec` contract and this
+	* package ships the layer.
 	*
 	* **The argv knowledge is not duplicated.** `LocalExec.prefixes(name)` is
 	* the one home of the four managers' `exec`/`dlx`/script-runner prefixes;
@@ -304,6 +299,7 @@ var Workspaces = class {
 	*
 	* @example
 	* ```ts
+	* import { NodeServices } from "@effect/platform-node";
 	* import { ToolDiscovery } from "@effected/commands";
 	* import { Workspaces } from "@effected/workspaces";
 	* import { Layer } from "effect";

package/WorkspacesSync.js

@@ -113,9 +113,7 @@ const isPackage = (options, dir) => options.fileSystem.exists(options.path.join(
 * The signature is path-first, options second — the same shape as
 * {@link getWorkspacePackagesSync} and the rest of the kit's sync facades
 * (`TsconfigLoaderSync.load(configPath, options)`). `cwd` is required and
-* positional: the earlier options-bag form defaulted it to an ambient
-* `process.cwd()` read, which both broke the symmetry with its sibling and
-* was the module's one platform assumption.
+* positional, so the function reads no ambient `process.cwd()`.
 *
 * Markers match the async service exactly: a `pnpm-workspace.yaml`, or a
 * `package.json` carrying a `workspaces` field.