@effected/workspaces 0.30.4 → 0.31.0

package/index.d.ts

@@ -52,7 +52,7 @@ interface DependencyDiff {
   readonly added: Record<string, string>;
   /** Present in the other, absent from the receiver. */
   readonly removed: Record<string, string>;
-  /** Present in both at different specifiers. */
+  /** Present in both at different specifiers: `from` is the other package's, `to` the receiver's. */
   readonly changed: Record<string, {
     readonly from: string;
     readonly to: string;
@@ -112,13 +112,9 @@ declare const WorkspacePackage_base: Schema.Class<WorkspacePackage, Schema.Struc
    * 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 `"."`.
    */
@@ -145,8 +141,7 @@ declare const WorkspacePackage_base: Schema.Class<WorkspacePackage, Schema.Struc
    * 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.
    */
   readonly manifestRecord: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Unknown>, never>>;
 }>, {}>;
@@ -209,8 +204,8 @@ export declare class WorkspacePackage extends WorkspacePackage_base {
   /** The declared specifier for `name`, searched across all four kinds. */
   dependencyVersion(name: string): Option.Option<string>;
   /**
-   * 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
@@ -223,7 +218,12 @@ export declare class WorkspacePackage extends WorkspacePackage_base {
    * @param pattern - A compiled pattern, or a source string to compile.
    */
   matchesDependency(pattern: GlobPattern | string): boolean;
-  /** 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: WorkspacePackage): DependencyDiff;
   /**
    * Project to `@effected/lockfiles`' `WorkspaceManifest` — the input shape of
@@ -234,6 +234,10 @@ export declare class WorkspacePackage extends WorkspacePackage_base {
    * 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 readonly manifest: (self: WorkspacePackage) => Effect.Effect<Package, WorkspaceManifestError, FileSystem.FileSystem>;
   /** Instance form of `WorkspacePackage.manifest`. */
@@ -370,12 +374,10 @@ export declare class WorkspaceRoot extends WorkspaceRoot_base {
    * 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}.
    *
@@ -449,7 +451,7 @@ declare const WorkspaceDiscoveryError_base: Schema.Class<WorkspaceDiscoveryError
  * 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`.
@@ -558,11 +560,10 @@ interface WorkspaceDiscoveryOptions {
    * `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.
+   * sensibly bound, so they ascend unbounded.
    *
    * `LockfileReader`, `WorkspaceCatalogs` and `WorkspaceSnapshots` each
-   * take the same option; give them the same
-   * value when wiring by hand, or let a `Workspaces.*` composite forward one
+   * take the same option; give them the same value when wiring by hand, or let a `Workspaces.*` composite forward one
    * `stopAt` to all of them, so no service adopts a root another refused.
    *
    * @defaultValue no ceiling — the ascent runs to the filesystem root.
@@ -659,11 +660,9 @@ declare const WorkspaceDiscovery_base: Context.ServiceClass<WorkspaceDiscovery,
  * 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
@@ -686,12 +685,14 @@ export declare class WorkspaceDiscovery extends WorkspaceDiscovery_base {
    */
   static readonly make: (options?: WorkspaceDiscoveryOptions) => Effect.Effect<WorkspaceDiscoveryShape, never, WorkspaceRoot | FileSystem.FileSystem | Path.Path>;
   /**
-   * 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 readonly layer: (options?: WorkspaceDiscoveryOptions) => Layer.Layer<WorkspaceDiscovery, never, WorkspaceRoot | FileSystem.FileSystem | Path.Path>;
   /**
@@ -917,21 +918,19 @@ export declare class ChangeDetector extends ChangeDetector_base {
  * **after** computing peer violations, in pnpm's own shape.
  *
  * @remarks
- * The shape is pnpm's rather than ours because that is what comes back off the
- * threaded config: measured against `@savvy-web/pnpm-plugin-silk@0.27.0`, a
- * replayed hook returns `{ allowedVersions, ignoreMissing, allowAny }` intact,
- * needing no reshaping.
- *
- * All three axes are consumed by `PeerCheck`, each established by measurement
- * against `pnpm peers check` with a firing control. `ignoreMissing` and
- * `allowAny` are lists of **peer-name patterns** in pnpm's `@pnpm/matcher`
+ * The shape is pnpm's own, because that is what comes back off the threaded
+ * config: a replayed hook returns `{ allowedVersions, ignoreMissing, allowAny }`
+ * intact, needing no reshaping.
+ *
+ * All three axes are consumed by `PeerCheck`, matching `pnpm peers check`.
+ * `ignoreMissing` and `allowAny` are lists of **peer-name patterns** in pnpm's `@pnpm/matcher`
  * grammar (`*` wildcard, leading `!` negation) — not `parent>peer` keys, which
  * match nothing on those two axes. `ignoreMissing` hides only a required peer
  * that resolved to nothing; `allowAny` hides only a peer that resolved outside
  * its wanted range; the two never cross.
  *
  * `allowedVersions` keys come in two spellings in the wild, and both must be
- * handled: parent-versioned (`"@effect/ai-anthropic@4.0.0-rc.109>effect"`, as
+ * handled: parent-versioned (`"@effect/ai-anthropic@4.0.0>effect"`, as
  * `pnpm:export` materializes them into `pnpm-workspace.yaml`) and unversioned
  * (`"@effect/vitest>vitest"`, as a config-dependency plugin injects them).
  *
@@ -1047,15 +1046,11 @@ interface HookInjection {
    * @remarks
    * Effective rather than hook-only because the rules are **seeded** into the
    * threaded config and the hooks merge onto them, exactly as pnpm seeds its
-   * own config and takes back what the hooks return. That is deliberate: a
-   * kit-owned merge function would be a second implementation of a rule this
-   * seam already enforces, and the two would drift the first time pnpm changed
-   * its threading.
+   * own config and takes back what the hooks return, so there is no second
+   * merge implementation to drift from pnpm's threading.
    *
-   * Measured caveat, and **not a bug to fix**: this repo's plugin *merges*
-   * onto the seeded rules; another plugin could overwrite them. Under seeding
-   * that is pnpm's own behaviour reproduced — a hook that overwrites
-   * overwrites for pnpm too — so do not "repair" it into a merger.
+   * A plugin whose hook *overwrites* the seeded rules rather than merging
+   * onto them replaces them here exactly as it does under pnpm.
    */
   readonly peerDependencyRules: PeerDependencyRules;
   /**
@@ -1489,8 +1484,9 @@ declare const DependencyGraph_base: Schema.Class<DependencyGraph, Schema.Struct<
  * `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
@@ -1525,8 +1521,11 @@ export declare class DependencyGraph extends DependencyGraph_base {
   /** The workspace packages that depend on `name`, sorted. */
   readonly dependentsOf: (name: string) => Effect.Effect<readonly string[], PackageNotFoundError, never>;
   /**
-   * `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.
    */
   readonly affectedBy: (names: readonly string[]) => Effect.Effect<readonly string[], never, never>;
   /**
@@ -1534,9 +1533,8 @@ export declare class DependencyGraph extends DependencyGraph_base {
    * 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.
    */
   readonly levels: () => Effect.Effect<readonly (readonly string[])[], CyclicDependencyError, never>;
   /** The flattened topological order — `levels()` concatenated. */
@@ -1544,6 +1542,13 @@ export declare class DependencyGraph extends DependencyGraph_base {
   /**
    * 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.
    */
   readonly sortSubset: (names: readonly string[]) => Effect.Effect<readonly string[], CyclicDependencyError | PackageNotFoundError, never>;
   /**
@@ -1680,8 +1685,8 @@ declare const DuplicateCheck_base: Schema.Class<DuplicateCheck, Schema.Struct<{
    * 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".
@@ -1702,10 +1707,12 @@ declare const DuplicateCheck_base: Schema.Class<DuplicateCheck, Schema.Struct<{
  *
  * @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 });
@@ -1741,8 +1748,7 @@ export declare class DuplicateCheck extends DuplicateCheck_base {
    * 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
@@ -1946,8 +1952,7 @@ export declare class PackageManagerDetector extends PackageManagerDetector_base
    * `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`
@@ -2017,8 +2022,7 @@ export declare class LockfileReadError extends LockfileReadError_base {
   get message(): string;
 }
 /**
- * Every failure the lockfile methods can surface — the exported init-error
- * union the review named best-in-class DX.
+ * Every failure the lockfile methods can surface.
  *
  * @remarks
  * Layer construction does no IO, so every member surfaces from the *methods*
@@ -2044,9 +2048,7 @@ interface LockfileReaderShape {
    * @remarks
    * A name can resolve at **several versions** in one lockfile (two members
    * depending on different majors of the same package). This returns the
-   * **first** entry in lockfile order and does not attempt to rank them — there
-   * is no single "the" version to return, and picking the highest semver would
-   * imply a resolution decision this reader is not entitled to make. Callers
+   * **first** entry in lockfile order and does not rank them. Callers
    * that must see every resolution should read `lockfile.packagesNamed(name)`
    * off `read()` directly.
    */
@@ -2114,11 +2116,14 @@ export declare class LockfileReader extends LockfileReader_base {
   /** Builds the service. */
   static readonly make: (options?: LockfileReaderOptions) => Effect.Effect<LockfileReaderShape, never, WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
   /**
-   * 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 readonly layer: (options?: LockfileReaderOptions) => Layer.Layer<LockfileReader, never, WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
   /**
@@ -2585,10 +2590,9 @@ export declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
    * `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 readonly catalogResolver: Layer.Layer<CatalogResolver, never, WorkspaceCatalogs>;
 }
@@ -2598,7 +2602,7 @@ export declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
  * Why a report is not a complete answer.
  *
  * @remarks
- * Closed at exactly four, by measurement rather than by guess:
+ * Closed at exactly four:
  *
  * - `"peerRulesNotApplied"` — the effective suppression policy was not applied,
  *   so pnpm's post-hoc suppression could not be replicated and some reported
@@ -2606,7 +2610,7 @@ export declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
  *   because "nobody looked" and "I looked and there are none" are different
  *   facts. Supplied rules never produce it: all three axes —
  *   `allowedVersions`, `ignoreMissing` and `allowAny` — are applied with
- *   pnpm's measured semantics.
+ *   pnpm's semantics.
  * - `"unresolvedEdge"` — some instance records an edge this model could not
  *   name (`ResolvedPackage.unresolvedEdges`), or an importer dependency
  *   resolved through `link:` whose target the caller did not supply, so its
@@ -2663,8 +2667,8 @@ type UnverifiedReason = "peerRulesNotApplied" | "unresolvedEdge" | "peerRangeUnr
  * different results, because a gate must be able to tell "clean" from
  * "unchecked".
  *
- * **All three axes of the supplied rules are applied**, each with the
- * semantics measured against pnpm (see {@link PeerCheck.run}): `allowedVersions`
+ * **All three axes of the supplied rules are applied**, each with pnpm's
+ * semantics (see {@link PeerCheck.run}): `allowedVersions`
  * permits a resolved version by range, `ignoreMissing` hides a required peer
  * nothing resolved for, and `allowAny` hides a peer that resolved outside its
  * range. The two list axes are name patterns, never `parent>peer` keys.
@@ -2833,10 +2837,12 @@ declare const PeerCheck_base: Schema.Class<PeerCheck, Schema.Struct<{
  *
  * @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);
@@ -2895,7 +2901,7 @@ export declare class PeerCheck extends PeerCheck_base {
    * `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,
@@ -2930,6 +2936,8 @@ export declare class PeerCheck extends PeerCheck_base {
    * 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: Lockfile, options?: PeerCheckOptions): PeerCheck;
@@ -3050,16 +3058,13 @@ declare const PublishabilityDetector_base: Context.ServiceClass<PublishabilityDe
 export declare class PublishabilityDetector extends PublishabilityDetector_base {
   /**
    * 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
@@ -3083,13 +3088,12 @@ export declare class PublishabilityDetector extends PublishabilityDetector_base
    *
    * @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`.
@@ -3297,11 +3301,11 @@ declare const ReleaseTag_base: Schema.Class<ReleaseTag, Schema.Struct<{
  * 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
@@ -3321,6 +3325,7 @@ export declare class ReleaseTag extends ReleaseTag_base {
    *
    * @param version - The version being released. Must not be empty.
    * @param options - Formatting overrides.
+   * @returns the single-style {@link ReleaseTag}.
    */
   static single(version: string, options?: TagFormatOptions): ReleaseTag;
   /**
@@ -3419,13 +3424,13 @@ declare const VersioningStrategy_base: Schema.Class<VersioningStrategy, Schema.S
  *
  * @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
@@ -3444,6 +3449,9 @@ export declare class VersioningStrategy extends VersioningStrategy_base {
    * 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: ClassifyOptions): VersioningStrategy;
   /**
@@ -3454,6 +3462,10 @@ export declare class VersioningStrategy extends VersioningStrategy_base {
    * 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 readonly detect: (options?: VersioningDetectOptions | undefined) => Effect.Effect<VersioningStrategy, WorkspaceDiscoveryFailure, PublishabilityDetector | WorkspaceDiscovery>;
   /**
@@ -3469,6 +3481,9 @@ export declare class VersioningStrategy extends VersioningStrategy_base {
    * 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: ReadonlyArray<PackageRelease>, options?: TagFormatOptions): ReadonlyArray<ReleaseTag>;
 }
@@ -3486,8 +3501,7 @@ declare const PackageStateSnapshot_base: Schema.Class<PackageStateSnapshot, Sche
    * 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
@@ -3542,11 +3556,9 @@ declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot,
    * 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.
    */
   readonly importerVersions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>>;
   /**
@@ -3560,9 +3572,8 @@ declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot,
    * 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`.
    */
   readonly hookReplays: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
@@ -3588,8 +3599,7 @@ declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot,
    * 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.
    */
   readonly seededCatalogs: Schema.optionalKey<typeof CatalogSet>;
 }>, {}>;
@@ -3898,8 +3908,7 @@ interface WorkspaceSnapshotsOptions {
    * hook-injected catalogs at full precedence, so the seed answers nothing the
    * snapshot could not answer itself.
    *
-   * @defaultValue absent — no seed, and resolution behaves exactly as before
-   *   this option existed.
+   * @defaultValue absent — no seed.
    */
   readonly seedCatalogs?: CatalogSet;
 }
@@ -3964,11 +3973,14 @@ export declare class WorkspaceSnapshots extends WorkspaceSnapshots_base {
    */
   static readonly make: (options?: WorkspaceSnapshotsOptions) => Effect.Effect<WorkspaceSnapshotsShape, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs | ConfigDependencyHooks>;
   /**
-   * 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 readonly layer: (options?: WorkspaceSnapshotsOptions) => Layer.Layer<WorkspaceSnapshots, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs | ConfigDependencyHooks>;
   /**
@@ -4113,10 +4125,9 @@ export declare class Workspaces {
    * `@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
@@ -4197,10 +4208,9 @@ export declare class Workspaces {
    * `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
@@ -4263,8 +4273,7 @@ export declare class Workspaces {
    * 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
@@ -4294,13 +4303,11 @@ export declare class Workspaces {
    * 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;
@@ -4334,6 +4341,7 @@ export declare class Workspaces {
    *
    * @example
    * ```ts
+   * import { NodeServices } from "@effect/platform-node";
    * import { ToolDiscovery } from "@effected/commands";
    * import { Workspaces } from "@effected/workspaces";
    * import { Layer } from "effect";
@@ -4531,7 +4539,9 @@ interface SyncDirectoryEntry {
  * satisfies it verbatim:
  *
  * ```ts
+ * import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
  * import * as path from "node:path";
+ * import type { WorkspacesSyncOptions } from "@effected/workspaces";
  *
  * const options: WorkspacesSyncOptions = {
  * 	fileSystem: { exists: existsSync, readFile: (p) => readFileSync(p, "utf8"), readDirectory: (p) => readdirSync(p), isDirectory: (p) => statSync(p).isDirectory() },
@@ -4577,8 +4587,8 @@ interface WorkspacesSyncOptions {
  * The same vocabulary the Effect surface fails with, deliberately: a member the
  * async `listPackages()` rejects as `missingName` is the member the sync facade
  * reports as `missingName`. `invalidYaml` is excluded because it describes the
- * `pnpm-workspace.yaml` read, not a manifest. There is no `missingVersion` —
- * a version-less manifest is a member on both surfaces.
+ * `pnpm-workspace.yaml` read, not a manifest. A version-less manifest is a
+ * member on both surfaces.
  *
  * The vocabulary is shared; the CHECKS are shared only as far as this list.
  * Both surfaces perform the same five: the file read (`read`), `JSON.parse`
@@ -4599,10 +4609,10 @@ type WorkspaceDiscoverySkipKind = Exclude<WorkspaceDiscoveryError["kind"], "inva
  *
  * @remarks
  * The sync facade is total, so it cannot fail the way `WorkspaceDiscovery`
- * does — but a skipped member must still be observable. Before this record
- * existed the skip was silent, and a hand-written fixture with one unusable
- * manifest enumerated as a plausible empty array indistinguishable from "no
- * workspaces configured" (issue #605). The fields mirror
+ * does — but a skipped member must still be observable. Without a report, a
+ * hand-written fixture with one unusable manifest would enumerate as a
+ * plausible empty array indistinguishable from "no workspaces configured". The
+ * fields mirror
  * `WorkspaceDiscoveryError`: `root`, `path`, `kind`, and on `cause` either the
  * caught throwable (`read` / `invalidJson`) or an `Error` carrying the same
  * sentence the Effect surface fails with (`invalidShape`). Only `missingName`
@@ -4664,9 +4674,7 @@ interface FindWorkspaceRootSyncOptions extends WorkspacesSyncOptions {
  * 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.
@@ -4723,12 +4731,10 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
    * though this function is total and has no error channel to raise it on.
    *
    * @remarks
-   * Omit it and skips are simply not reported, which is the pre-existing
-   * behaviour; nothing is logged in its place. The callback is invoked
-   * synchronously, before the result is returned, in enumeration order —
-   * members first, then the root, which is read last even though it is
-   * returned first. Its
-   * result is discarded, and a throw from it propagates: the facade is total
+   * Omit it and skips are simply not reported; nothing is logged in its
+   * place. The callback is invoked synchronously, before the result is
+   * returned, in enumeration order — members first, then the root, which is
+   * read last even though it is returned first. Its result is discarded, and a throw from it propagates: the facade is total
    * over *data*, not over caller mistakes, exactly as a bad `maxDepth` is.
    */
   readonly onSkip?: ((skip: WorkspaceDiscoverySkip) => void) | undefined;