@effected/workspaces 0.28.0 → 0.29.0

package/index.d.ts

@@ -2182,193 +2182,692 @@ export declare class LockfileReader extends LockfileReader_base {
   static readonly layerTest: (overrides?: Partial<LockfileReaderShape>) => Layer.Layer<LockfileReader>;
 }
 //#endregion
-//#region src/PeerCheck.d.ts
-/**
- * Why a report is not a complete answer.
- *
- * @remarks
- * Closed at exactly two, by measurement rather than by guess:
- *
- * - `"peerRulesNotApplied"` — the effective suppression policy was not applied,
- *   so pnpm's post-hoc suppression could not be replicated and some reported
- *   rows may be ones pnpm hides. **Omitting the option always produces this**,
- *   because "nobody looked" and "I looked and there are none" are different
- *   facts. Supplied rules never produce it: all three axes —
- *   `allowedVersions`, `ignoreMissing` and `allowAny` — are applied with
- *   pnpm's measured semantics.
- * - `"unresolvedEdge"` — some instance records an edge this model could not
- *   name (`ResolvedPackage.unresolvedEdges`), so a peer that edge satisfies
- *   cannot be verified either way.
- *
- * Both mean **fail closed**: a gate should treat an unverified report as "not
- * proven clean" rather than as a pass.
- *
- * @public
- */
-type UnverifiedReason = "peerRulesNotApplied" | "unresolvedEdge";
+//#region src/WorkspaceCatalogs.d.ts
 /**
- * Options for {@link PeerCheck.run}.
+ * Each importer's dependency-name → resolved-version map, keyed by importer path
+ * (`"."` for the root package — the same keys `WorkspaceDiscovery.importerMap()`
+ * uses, and the same value `PackageStateSnapshot.relativePath` carries).
  *
  * @remarks
- * **Presence of `peerDependencyRules` is the assertion; its contents are the
- * value.** Supplying `NoPeerDependencyRules` asserts the workspace has none and
- * yields a verified report; omitting the key entirely says nothing was looked
- * up and always yields `"peerRulesNotApplied"`. The two are deliberately
- * 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`
- * permits a resolved version by range, `ignoreMissing` hides a required peer
- * nothing resolved for, and `allowAny` hides a peer that resolved outside its
- * range. The two list axes are name patterns, never `parent>peer` keys.
- *
- * @public
- */
-interface PeerCheckOptions {
-  /** The workspace's effective rules, from `WorkspaceCatalogs.peerDependencyRules()`. */
-  readonly peerDependencyRules?: PeerDependencyRules;
-}
-declare const PeerParent_base: Schema.Class<PeerParent, Schema.Struct<{
-  /** The package name. */
-  readonly name: Schema.NonEmptyString;
-  /** The resolved version of that package. */
-  readonly version: Schema.String;
-}>, {}>;
-/**
- * One link in the chain from an importer to the package that declared an
- * unsatisfied peer.
+ * What a manager's lockfile records as actually installed, as opposed to what a
+ * manifest declares. It answers a `catalog:` specifier no committed catalog
+ * source declares — the shape a pnpm config-dependency pnpmfile hook produces —
+ * which would otherwise resolve to nothing on both sides of a diff and hide a
+ * real version movement.
  *
- * @remarks
- * Mirrors the shape `pnpm peers check --json` reports, so the two can be
- * compared directly.
+ * Versions are normalized: pnpm's peer-disambiguation suffix
+ * (`1.2.3(effect@4.0.0)`) is stripped, and `link:` / `file:` entries are omitted
+ * because a filesystem edge is not a version. Only pnpm records importer
+ * versions; bun and npm yield an empty index.
  *
  * @public
  */
-export declare class PeerParent extends PeerParent_base {}
-declare const UnsatisfiedPeer_base: Schema.Class<UnsatisfiedPeer, Schema.Struct<{
-  /** The importer path the problem belongs to (`"."` for the root). */
-  readonly importer: Schema.NonEmptyString;
-  /** The peer dependency's name. */
-  readonly dependency: Schema.NonEmptyString;
-  /** The range the declaring package asked for. */
-  readonly wanted: Schema.String;
-  /** The version that resolved, or `null` when nothing resolved. */
-  readonly found: Schema.NullOr<Schema.String>;
-  /** Whether the declaring package marked the peer optional. */
-  readonly optional: Schema.Boolean;
-  /** The path from the importer to the declaring package. */
-  readonly parents: Schema.$Array<typeof PeerParent>;
+type ImporterVersions = Readonly<Record<string, Readonly<Record<string, string>>>>;
+declare const CatalogSet_base: Schema.Class<CatalogSet, Schema.Struct<{
+  /** Catalog name → dependency name → version range. */
+  readonly entries: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>;
 }>, {}>;
 /**
- * One peer dependency that is declared but not satisfied.
+ * An immutable, fully-normalized catalog collection — the one catalog
+ * resolution semantic in the package.
  *
  * @remarks
- * `found` carries the version that actually resolved, or `null` when nothing
- * resolved at all. There is deliberately **no separate discriminant** between
- * "missing" and "unmet": `found === null` is the whole distinction, and a
- * renderer reads it directly.
- *
- * `optional` must be respected by any gate — an unsatisfied *optional* peer is
- * normal and should not fail a build, which is why the flag travels with the
- * row rather than being filtered out here. {@link PeerCheck.required} is the
- * convenience for the common case.
- *
- * `parents` is the path from the importer down to the package that declared
- * the peer, nearest-to-the-importer first. It is a path rather than a single
- * package because a peer declared by a transitive dependency is still that
- * importer's problem, and the chain is what makes the report actionable.
- *
- * A package an importer reaches by more than one path yields **one** row, not
- * one per path, carrying the path the walk reached first — which is what
- * `pnpm peers check` reports for the same graph. Read `parents` as *a* route to
- * the declaring package, never as the complete set of them.
+ * `entries` is catalog name → dependency → range, with pnpm's unnamed
+ * top-level `catalog:` block normalized under the key `"default"`. Lockfile
+ * catalog entries, which pnpm records as `{ specifier, version }`, are
+ * normalized to their `specifier` — the declared range, which is what a catalog
+ * resolves to.
  *
  * @public
  */
-export declare class UnsatisfiedPeer extends UnsatisfiedPeer_base {}
-declare const PeerCheck_base: Schema.Class<PeerCheck, Schema.Struct<{
+export declare class CatalogSet extends CatalogSet_base {
+  /** The empty set — a workspace with no catalogs. */
+  static empty(): CatalogSet;
+  /** Wrap a pnpm `Catalogs` map, dropping unusable entries. */
+  static fromCatalogs(catalogs: unknown): CatalogSet;
   /**
-   * Whether the lockfile's format records peer resolution at all.
+   * The `catalog:` and `catalogs:` blocks of a `pnpm-workspace.yaml` document.
    *
-   * `false` for yarn: yarn resolves peers **virtually**, giving a
-   * peer-bearing package one `@virtual:` locator per consumer, and the
-   * lockfile does not record which virtual instance satisfied which peer.
-   * The answer is not recoverable, so it is not fabricated — `unsatisfied`
-   * is empty and this flag says why.
+   * @param text - The raw YAML text.
    */
-  readonly supported: Schema.Boolean;
-  /** Every unsatisfied peer found, optional ones included. */
-  readonly unsatisfied: Schema.$Array<typeof UnsatisfiedPeer>;
+  static readonly fromWorkspaceYaml: (text: string) => Effect.Effect<CatalogSet, CatalogAssemblyError, never>;
   /**
-   * Importers whose dependencies could not be resolved to instances, so no
-   * verdict was reached for them.
+   * The `catalogs:` section of a pnpm lockfile, whose entries are either a bare
+   * range or a `{ specifier, version }` pair.
+   */
+  static fromLockfileCatalogs(raw: unknown): CatalogSet;
+  /**
+   * The catalog set a parsed lockfile records, PM-aware.
    *
    * @remarks
-   * 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.
+   * Both pnpm and bun record catalogs in the lockfile, in different shapes:
+   * pnpm under `extension.catalogs`, bun under `extension.catalog` /
+   * `extension.catalogs`. Assembly reads whichever the parsed lockfile carries
+   * rather than assuming the pnpm extension. A lockfile with no extension, or a
+   * pnpm one with no catalogs, yields the empty set.
    *
-   * Reported rather than silently skipped, for the same reason `supported`
-   * exists: a gate that sees no rows is entitled to know whether that means
-   * "clean" or "not looked at".
+   * @param lockfile - A parsed lockfile from `@effected/lockfiles`.
    */
-  readonly unresolvedImporters: Schema.$Array<Schema.String>;
+  static fromLockfile(lockfile: Lockfile): CatalogSet;
   /**
-   * Why this report is not a complete answer, or empty when it is.
+   * A catalog set from bun's `{ catalog, catalogs }` blocks — used for the
+   * `bun.lock` extension and for the root `package.json` `workspaces` block. The
+   * unnamed default catalog normalizes under `"default"`. Tolerant: unusable
+   * values are dropped, never fatal.
+   *
+   * @param blocks - The `catalog` (default) and `catalogs` (named) blocks.
+   */
+  static fromBunBlocks(blocks: {
+    readonly catalog?: unknown;
+    readonly catalogs?: unknown;
+  }): CatalogSet;
+  /**
+   * The `catalog` / `catalogs` blocks of a root `package.json` `workspaces` field
+   * — bun's package.json analogue of pnpm's `pnpm-workspace.yaml` blocks.
    *
    * @remarks
-   * See {@link UnverifiedReason}. A gate must treat a non-empty `unverified`
-   * as **not proven clean** rather than as a pass: both reasons mean some
-   * finding may be missing or spurious, and failing closed is the requirement.
+   * **Hard-fail by design**, preserving the semantics catalog output is
+   * load-bearing for: a present-but-malformed `workspaces` shape (a number, a
+   * string, an object with a malformed `packages` / `catalog` / `catalogs`), or
+   * the default catalog declared twice — once as `workspaces.catalog` and again
+   * as `workspaces.catalogs.default` — fails with `CatalogAssemblyError`
+   * naming what was wrong. An absent `workspaces` field, one explicitly `null`,
+   * or the plain array form (npm/yarn patterns, which carry no catalogs) yields
+   * the empty set. Presence is checked structurally, so an explicitly-declared
+   * empty `catalog: {}` still counts as a declaration.
+   *
+   * @param text - The raw root `package.json` text.
    */
-  readonly unverified: Schema.$Array<Schema.Literals<readonly ["peerRulesNotApplied", "unresolvedEdge"]>>;
-}>, {}>;
+  static readonly fromManifestWorkspaces: (text: string) => Effect.Effect<CatalogSet, CatalogAssemblyError, never>;
+  /** Merge sets. Later sets win per dependency within a catalog. */
+  static merge(...sets: ReadonlyArray<CatalogSet>): CatalogSet;
+  /** Whether any catalog declares anything. */
+  get isEmpty(): boolean;
+  /**
+   * The range a `catalog:` specifier resolves to.
+   *
+   * @remarks
+   * Total: an unmatched dependency, an unknown catalog name, or a non-catalog
+   * specifier all yield `Option.none()`. A *malformed* catalog — one pnpm
+   * itself rejects — also yields `Option.none()` here; the fallible surface is
+   * {@link WorkspaceCatalogs}, which fails typed on assembly instead.
+   *
+   * @param dependency - The package name being resolved.
+   * @param specifier - The declared specifier, e.g. `catalog:` or `catalog:build`.
+   */
+  resolveSpecifier(dependency: string, specifier: string): Option.Option<string>;
+  /**
+   * The range `dependency` carries in a named catalog, or in the default
+   * catalog when `catalog` is `Option.none()`.
+   *
+   * @remarks
+   * The shape `@effected/npm`'s `CatalogResolver` contract asks for.
+   */
+  rangeOf(dependency: string, catalog: Option.Option<string>): Option.Option<string>;
+}
 /**
- * The result of checking a lockfile for unsatisfied peer dependencies.
- *
- * @remarks
- * A report rather than a bare array, because an empty array is the most
- * dangerous success shape this domain has: it is indistinguishable from "this
- * format cannot be checked". `supported` and `unresolvedImporters` make the
- * difference legible, so a consumer cannot read a limitation as a clean bill
- * of health.
- *
- * Pure and total — construct it with {@link PeerCheck.run}, which never fails.
- *
- * @example
- * ```ts
- * import { PeerCheck } from "@effected/workspaces";
- * import { Lockfile } from "@effected/lockfiles";
- * import { Effect } from "effect";
+ * Every failure catalog assembly can surface.
  *
- * const program = Effect.gen(function* () {
- *   const lockfile = yield* Lockfile.parse(text, { format: "pnpm" });
- *   const report = PeerCheck.run(lockfile);
- *   return report.supported ? report.required : [];
- * });
- * ```
+ * @public
+ */
+type CatalogAssemblyFailure = CatalogAssemblyError | WorkspaceRootNotFoundError;
+/**
+ * The {@link WorkspaceCatalogs} service shape.
  *
  * @public
  */
-export declare class PeerCheck extends PeerCheck_base {
-  /** The unsatisfied peers a gate should act on — the non-optional ones. */
-  get required(): ReadonlyArray<UnsatisfiedPeer>;
+interface WorkspaceCatalogsShape {
+  /** The assembled catalog set for the workspace. Memoized after the first call. */
+  readonly set: () => Effect.Effect<CatalogSet, CatalogAssemblyFailure>;
+  /** Resolve one `catalog:` specifier; `Option.none()` when it names nothing. */
+  readonly resolveSpecifier: (dependency: string, specifier: string) => Effect.Effect<Option.Option<string>, CatalogAssemblyFailure>;
   /**
-   * Compute the unsatisfied peer dependencies of a parsed lockfile.
+   * The effective pnpm release-age gate for the workspace, combined
+   * strictest-wins from the inline `pnpm-workspace.yaml` keys
+   * (`minimumReleaseAge` / `minimumReleaseAgeExclude`) and the replayed
+   * config-dependency hooks. Assembled from the same single read and hook
+   * replay as `set`, and memoized with it.
    *
    * @remarks
-   * Pure, total and format-free: no IO, no error channel, and no knowledge of
-   * which package manager wrote the file. Range satisfaction is
-   * `@effected/semver`'s, never hand-rolled.
-   *
-   * The walk starts at each importer's resolved dependencies and follows
-   * `resolved` edges, so a peer declared by a *transitive* dependency is
-   * attributed to the importer that pulls it in, with the chain in
-   * `parents` — matching how `pnpm peers check` attributes them.
+   * Under the default layer (no-op hooks) only inline values contribute; under
+   * {@link WorkspaceCatalogs.layerWithConfigDependencies} the replayed hooks
+   * contribute too. A workspace with no pnpm-workspace.yaml (a bun/npm
+   * workspace) has no release-age keys, so the gate is the inert zero gate.
+   */
+  readonly releaseAgeGate: () => Effect.Effect<ReleaseAgeGate, CatalogAssemblyFailure>;
+  /**
+   * The workspace's **effective** `peerDependencyRules` — pnpm's post-hoc
+   * suppression policy, which the lockfile does not record at all.
+   *
+   * @remarks
+   * Assembled from the same single read and hook replay as `set`, and memoized
+   * with it. The `pnpm-workspace.yaml` block (what `pnpm:export` materializes)
+   * is **seeded** into the replayed config and the config-dependency hooks
+   * merge onto it, so one object carries both sources — the kit never merges
+   * them itself, because that would be a second implementation of a rule the
+   * hook seam already enforces.
+   *
+   * A consumer needs these to avoid **reporting** what pnpm suppresses: pnpm
+   * computes the same peer violations and then hides the ones a rule allows,
+   * so a checker without them reports findings pnpm calls clean. `PeerCheck`
+   * applies all three axes.
+   */
+  readonly peerDependencyRules: () => Effect.Effect<PeerDependencyRules, CatalogAssemblyFailure>;
+  /**
+   * Each importer's dependency-name → resolved-version map, as the manager's
+   * lockfile records it. Read from the same single lockfile read as `set`, and
+   * memoized with it.
+   *
+   * @remarks
+   * Feeds `WorkspaceStateSnapshot`'s fallback for a `catalog:` specifier no
+   * committed catalog source declares — the shape a config-dependency pnpmfile
+   * hook produces. Only pnpm records importer versions; a bun or npm workspace
+   * yields an empty index, and an absent or unreadable lockfile contributes
+   * nothing rather than failing.
+   */
+  readonly importerVersions: () => Effect.Effect<ImporterVersions, CatalogAssemblyFailure>;
+  /**
+   * Which version each declared config dependency was replayed from, keyed
+   * by name — off the same single memoized assemble pass as `set()`.
+   *
+   * @remarks
+   * Every dependency the hooks layer resolved when a `pnpm-workspace.yaml`
+   * was read — `{}` when it declares no config dependencies or under the
+   * no-op layer, which resolves nothing. Config dependencies are a pnpm
+   * feature, so the bun / `package.json` path yields `{}` too, exactly as
+   * `importerVersions` does.
+   */
+  readonly hookReplays: () => Effect.Effect<Readonly<Record<string, HookReplay>>, CatalogAssemblyFailure>;
+  /**
+   * Discard the memoized assembly so the **next** read re-assembles — the same
+   * single read and hook replay as the first, over the workspace as it stands
+   * then.
+   *
+   * @remarks
+   * The explicit memoization boundary for a tool that **mutates the workspace
+   * mid-run** — installs, bumps a config dependency, regenerates the lockfile.
+   * Release-age gating wants the before-state, a post-install peer check the
+   * after-state, and one infinite memo cannot serve both without this call in
+   * between; without it, `peerDependencyRules` keeps answering from the
+   * pre-mutation hook replay and the checker reports findings the new rules
+   * suppress.
+   *
+   * Unconditional and infallible: the memo is already success-only (a failed
+   * or interrupted assembly retries by itself), so `refresh` exists solely to
+   * discard a *successful* assembly that mutation has made stale. Calling it
+   * before any read is harmless.
+   */
+  readonly refresh: () => Effect.Effect<void>;
+}
+/**
+ * Options for the {@link WorkspaceCatalogs} layer.
+ *
+ * @public
+ */
+interface WorkspaceCatalogsOptions {
+  /**
+   * The directory the workspace root is resolved from.
+   *
+   * @defaultValue `process.cwd()`, read lazily on first use.
+   */
+  readonly cwd?: string;
+  /**
+   * A ceiling for the root ascent from `cwd`, passed straight through to the
+   * `stopAt` of {@link WorkspaceRoot}'s `find`.
+   *
+   * @remarks
+   * Inclusive, and resolved to an absolute path exactly as `cwd` is. When no
+   * root is found at or below the ceiling, catalog assembly fails with
+   * {@link WorkspaceRootNotFoundError} carrying the resolved `stopAt` rather
+   * than adopting an enclosing directory's workspace. Pass the same value as
+   * {@link WorkspaceDiscoveryOptions.stopAt} so every service agrees on the
+   * root; the `Workspaces.*` composites forward one `stopAt` to all of them.
+   *
+   * @defaultValue no ceiling — the ascent runs to the filesystem root.
+   */
+  readonly stopAt?: string | undefined;
+}
+declare const WorkspaceCatalogs_base: Context.ServiceClass<WorkspaceCatalogs, "@effected/workspaces/WorkspaceCatalogs", WorkspaceCatalogsShape>;
+/**
+ * Assembles a workspace's catalogs, package-manager-aware.
+ *
+ * @remarks
+ * The inline source is picked by **file presence**, the same rule
+ * `internal/patterns.ts` uses for globs: a `pnpm-workspace.yaml` selects the pnpm
+ * path (its `catalog:` / `catalogs:` blocks); its absence selects the root
+ * `package.json` `workspaces.catalog` / `workspaces.catalogs` (bun's analogue).
+ * The lockfile source is PM-aware too — whichever extension the parsed lockfile
+ * carries (pnpm or bun) contributes its recorded catalogs.
+ *
+ * Precedence, lowest first: catalogs recorded in the lockfile, then the inline
+ * declaration, then — only under {@link WorkspaceCatalogs.layerWithConfigDependencies}
+ * — the config-dependency `pnpmfile.cjs` hooks, each layer winning per dependency
+ * within a catalog. An unreadable or absent lockfile degrades to no lockfile
+ * catalogs rather than failing (the inline declaration is the source of truth, the
+ * lockfile a record of what was installed); a malformed inline source **fails
+ * typed** with `CatalogAssemblyError`, because a silently-empty catalog read
+ * is the "every dependency looks newly added" bug.
+ *
+ * Assembly is deferred to the first call and memoized success-only, matching
+ * {@link WorkspaceDiscovery}.
+ *
+ * @public
+ */
+export declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
+  /** Builds the service. */
+  static readonly make: (options?: WorkspaceCatalogsOptions) => Effect.Effect<WorkspaceCatalogsShape, never, WorkspaceRoot | LockfileReader | ConfigDependencyHooks | FileSystem.FileSystem | Path.Path>;
+  /**
+   * The service over an explicit {@link ConfigDependencyHooks} layer — the
+   * one builder every `layer*` static and the `Workspaces` composites
+   * delegate to, so the hooks layer is provided to {@link WorkspaceCatalogs.make}
+   * in exactly one place.
+   *
+   * @remarks
+   * Reach for it when the hooks layer is chosen elsewhere — a composite that
+   * must hand ONE hooks reference to both this service and
+   * `WorkspaceSnapshots` (layers memoize by reference, so two references
+   * would replay twice and could run two policies), or a test wiring
+   * {@link ConfigDependencyHooks.layerFrom}. The three `layer*` statics are
+   * this with the hooks layer fixed. `R` is the hooks layer's own
+   * requirement (the subprocess variant's `ChildProcessSpawner`), threaded
+   * through. Parameterized, so bind it to a `const` and reuse it.
+   *
+   * @param hooks - The {@link ConfigDependencyHooks} layer to replay through.
+   * @param options - The same options the other layer statics take.
+   */
+  static readonly layerWithHooks: <R = never>(hooks: Layer.Layer<ConfigDependencyHooks, never, R>, options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path | R>;
+  /**
+   * The live layer — the default, which **never executes config-dependency
+   * code**: it wires {@link ConfigDependencyHooks.layerNoop}, whose hooks return
+   * the inline-catalog seed untouched.
+   *
+   * @remarks
+   * Parameterized, so it mints a fresh reference per call — bind it to a
+   * `const` and reuse it, or layer memoization does not apply.
+   */
+  static readonly layer: (options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path>;
+  /**
+   * The opt-in live layer that **does** replay config-dependency `pnpmfile.cjs`
+   * hooks: it wires {@link ConfigDependencyHooks.layerLive}, which dynamically
+   * imports and runs each config dependency's `updateConfig` in process.
+   *
+   * @remarks
+   * Same output and requirement set as {@link WorkspaceCatalogs.layer} — the only
+   * difference is that config-dependency code is executed. Use it deliberately;
+   * the default catalog path stays free of any config-dependency execution.
+   * Parameterized, so bind it to a `const` and reuse it.
+   */
+  static readonly layerWithConfigDependencies: (options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path>;
+  /**
+   * The opt-in layer that replays config-dependency `pnpmfile` hooks in a
+   * `node` **child process**: it wires
+   * {@link ConfigDependencyHooks.layerSubprocess} in place of the in-process
+   * `layerLive`.
+   *
+   * @remarks
+   * Same typed semantics as {@link WorkspaceCatalogs.layerWithConfigDependencies}
+   * — the two hook layers are drop-in interchangeable — but the replay's
+   * computed dynamic `import()` runs in the subprocess, so it survives bundling
+   * (a bundler compiles a computed in-process `import()` into a context module
+   * that cannot resolve at runtime — every bundled GitHub Action hits this).
+   * The cost is one extra requirement: core's `ChildProcessSpawner`, provided
+   * once at the edge (`@effect/platform-node`'s `NodeServices.layer`) — the
+   * same sanctioned R-widening as `Workspaces.layerWithGit`. Parameterized, so
+   * bind it to a `const` and reuse it.
+   */
+  static readonly layerWithConfigDependenciesSubprocess: (options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * A test double satisfying the full {@link WorkspaceCatalogsShape} with no
+   * filesystem, lockfile read, or hook replay.
+   *
+   * @remarks
+   * There is **no honest default catalog set**: an empty `CatalogSet` that
+   * looks like a legitimate answer is the "every dependency looks newly added"
+   * failure class the live assembler hard-fails to prevent, so every method
+   * **dies** with an instructive defect until stubbed — a test-wiring mistake
+   * fails loudly as a defect rather than succeeding with a lie or failing with
+   * a dishonest typed error.
+   *
+   * The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+   * derived-from-the-primary rule: when a `set` override is supplied,
+   * `resolveSpecifier` answers from that `CatalogSet`'s own
+   * {@link CatalogSet.resolveSpecifier} — exactly what the live service runs
+   * over its assembled set — so the two stay consistent by construction.
+   * `releaseAgeGate`, `importerVersions` and `hookReplays` are **not**
+   * derivable from a catalog set (the gate comes from release-age keys and
+   * hook contributions, the importer index from the lockfile's importer
+   * blocks, the replay record from the hooks layer — none is in a
+   * `CatalogSet`) and always die unless stubbed.
+   *
+   * `refresh` defaults to `Effect.void` honestly: the double holds no memo,
+   * so "drop the memoized assembly" is genuinely a no-op — the stubs answer
+   * fresh on every call already. This mirrors `WorkspaceDiscovery.makeTest`'s
+   * `refresh`.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const double = WorkspaceCatalogs.makeTest({
+   *   set: () => Effect.succeed(CatalogSet.fromCatalogs({ default: { effect: "4.0.0" } })),
+   * });
+   * // `resolveSpecifier` now answers consistently from that set.
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<WorkspaceCatalogsShape>) => WorkspaceCatalogsShape;
+  /**
+   * The test layer: {@link WorkspaceCatalogs.makeTest} behind `Layer.succeed`,
+   * so a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestCatalogs = WorkspaceCatalogs.layerTest({
+   *   set: () => Effect.succeed(CatalogSet.empty()),
+   * });
+   * // program.pipe(Effect.provide(TestCatalogs))
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<WorkspaceCatalogsShape>) => Layer.Layer<WorkspaceCatalogs>;
+  /**
+   * The real implementation of `@effected/npm`'s `CatalogResolver` contract —
+   * the one `@effected/package-json` declares but cannot fill.
+   *
+   * @remarks
+   * `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`.
+   */
+  static readonly catalogResolver: Layer.Layer<CatalogResolver, never, WorkspaceCatalogs>;
+}
+//#endregion
+//#region src/PeerCheck.d.ts
+/**
+ * Why a report is not a complete answer.
+ *
+ * @remarks
+ * Closed at exactly four, by measurement rather than by guess:
+ *
+ * - `"peerRulesNotApplied"` — the effective suppression policy was not applied,
+ *   so pnpm's post-hoc suppression could not be replicated and some reported
+ *   rows may be ones pnpm hides. **Omitting the option always produces this**,
+ *   because "nobody looked" and "I looked and there are none" are different
+ *   facts. Supplied rules never produce it: all three axes —
+ *   `allowedVersions`, `ignoreMissing` and `allowAny` — are applied with
+ *   pnpm's measured semantics.
+ * - `"unresolvedEdge"` — some instance records an edge this model could not
+ *   name (`ResolvedPackage.unresolvedEdges`), or an importer dependency
+ *   resolved through `link:` whose target the caller did not supply, so its
+ *   manifest peers are still invisible. Either way the peers that edge
+ *   involves are neither confirmed satisfied nor confirmed unmet.
+ *
+ * Supplying {@link PeerCheckOptions.workspacePackages} clears the second
+ * trigger for every `link:` target the supplied set covers AND the walk
+ * reaches: the linked manifest's peers are joined and judged for real, which
+ * is what makes the report an answer rather than a refusal. Omitting the
+ * option — or omitting a linked target from it — leaves the edge unverified,
+ * because an unjoined parent's peers are recorded nowhere in the lockfile; so
+ * does a covered target the lockfile records no workspace row for, since
+ * there is nothing to walk and its peers were never judged.
+ *
+ * - `"peerRangeUnresolved"` — a peer declared by a joined `link:` manifest has
+ *   a range that is a protocol specifier this check could not turn into a
+ *   range, while something resolved for that peer, so the comparison was
+ *   never performed. The trigger is a `catalog:` specifier with
+ *   {@link PeerCheckOptions.catalogs} omitted, a `catalog:` specifier the
+ *   supplied set names nothing for, or any other protocol (`workspace:*` and
+ *   friends). A peer with NOTHING resolved never produces it: "no provider"
+ *   is reportable without the range, so that row is emitted as usual.
+ * - `"peerVersionUnresolved"` — a peer resolved to a non-workspace provider
+ *   whose version is a protocol specifier rather than a version, so the
+ *   comparison was never performed. That is any `file:` provider — a
+ *   directory, a tarball, or either through a `file:` override
+ *   (`file:../x`) — and equally a git or remote-tarball provider, which
+ *   pnpm keys by its URL (`https://codeload.github.com/…`,
+ *   `git+https://…`), so the URL stands where a version belongs. The
+ *   lockfile records no version for a `file:` directory at all, and
+ *   `pnpm peers check` reports such a peer as a `bad` row carrying the
+ *   specifier as its found version even when the directory's own manifest
+ *   satisfies the range, so calling it satisfied would pass a workspace
+ *   pnpm rejects. Applies to a peer declared by a lockfile row and
+ *   by a joined `link:` manifest alike. A workspace-row provider never
+ *   produces it (it is accepted as always), and neither does a plain
+ *   unparseable version, which is skipped.
+ *
+ * All four mean **fail closed**: a gate should treat an unverified report as
+ * "not proven clean" rather than as a pass.
+ *
+ * @public
+ */
+type UnverifiedReason = "peerRulesNotApplied" | "unresolvedEdge" | "peerRangeUnresolved" | "peerVersionUnresolved";
+/**
+ * Options for {@link PeerCheck.run}.
+ *
+ * @remarks
+ * **Presence of `peerDependencyRules` is the assertion; its contents are the
+ * value.** Supplying `NoPeerDependencyRules` asserts the workspace has none and
+ * yields a verified report; omitting the key entirely says nothing was looked
+ * up and always yields `"peerRulesNotApplied"`. The two are deliberately
+ * 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`
+ * permits a resolved version by range, `ignoreMissing` hides a required peer
+ * nothing resolved for, and `allowAny` hides a peer that resolved outside its
+ * range. The two list axes are name patterns, never `parent>peer` keys.
+ *
+ * @public
+ */
+interface PeerCheckOptions {
+  /** The workspace's effective rules, from `WorkspaceCatalogs.peerDependencyRules()`. */
+  readonly peerDependencyRules?: PeerDependencyRules;
+  /**
+   * The workspace's discovered packages, from `WorkspaceDiscovery` — the
+   * manifests a `link:`-resolved parent's peers have to be read from,
+   * because the lockfile does not record them.
+   *
+   * @remarks
+   * **Supplying this key is what turns a `link:` edge from a refusal into an
+   * answer.** pnpm records no peer declarations for workspace projects, so a
+   * parent reached through `link:` joins at best to a row whose peers are
+   * empty *by design*; with the manifests supplied, that parent's declared
+   * peers are joined and judged instead. A `link:` target absent from the
+   * supplied set — and every target, when the key is omitted — keeps the
+   * report's `"unresolvedEdge"` marker, on the same presence-is-the-
+   * assertion rule as `peerDependencyRules`.
+   *
+   * A `link:` target matches a package when it names the package's
+   * `relativePath` — the POSIX workspace-relative directory the lockfile's
+   * importer paths are spelled in — or its publish directory: pnpm links a
+   * workspace dependency INTO `publishConfig.directory` unless
+   * `publishConfig.linkDirectory` is `false` (it defaults to true), so the
+   * lockfile then records `link:../a/dist`. Both spellings are normalized,
+   * and the caller passes what discovery produced without re-spelling
+   * anything.
+   *
+   * For a publish-directory link, pnpm reads the peers from the manifest AT
+   * the link target — the built one — while this check reads the supplied
+   * source manifest and resolves its `catalog:` ranges through
+   * {@link PeerCheckOptions.catalogs}. The two agree when the build emits the
+   * peer ranges the source's specifiers resolve to, which is the contract a
+   * publish-directory build keeps.
+   */
+  readonly workspacePackages?: ReadonlyArray<WorkspacePackage>;
+  /**
+   * The workspace's catalogs, from `WorkspaceCatalogs.set()` — which already
+   * includes any catalogs a config-dependency hook injects.
+   *
+   * @remarks
+   * A joined manifest may declare a peer as `catalog:` or `catalog:<name>`
+   * rather than as a range. With this key supplied, such a specifier is
+   * resolved through the set and the RESOLVED range is judged and reported
+   * as `wanted`, which is what `pnpm peers check` reports as `wantedRange`.
+   * A specifier the set names nothing for — and every `catalog:` specifier,
+   * when the key is omitted — cannot be judged against a provider, and the
+   * report carries `"peerRangeUnresolved"` rather than calling the peer
+   * satisfied: the same presence-is-the-assertion rule as the other two
+   * keys.
+   */
+  readonly catalogs?: CatalogSet;
+}
+declare const PeerParent_base: Schema.Class<PeerParent, Schema.Struct<{
+  /** The package name. */
+  readonly name: Schema.NonEmptyString;
+  /** The resolved version of that package. */
+  readonly version: Schema.String;
+}>, {}>;
+/**
+ * One link in the chain from an importer to the package that declared an
+ * unsatisfied peer.
+ *
+ * @remarks
+ * Mirrors the shape `pnpm peers check --json` reports, so the two can be
+ * compared directly.
+ *
+ * @public
+ */
+export declare class PeerParent extends PeerParent_base {}
+declare const UnsatisfiedPeer_base: Schema.Class<UnsatisfiedPeer, Schema.Struct<{
+  /** The importer path the problem belongs to (`"."` for the root). */
+  readonly importer: Schema.NonEmptyString;
+  /** The peer dependency's name. */
+  readonly dependency: Schema.NonEmptyString;
+  /** The range the declaring package asked for. */
+  readonly wanted: Schema.String;
+  /** The version that resolved, or `null` when nothing resolved. */
+  readonly found: Schema.NullOr<Schema.String>;
+  /** Whether the declaring package marked the peer optional. */
+  readonly optional: Schema.Boolean;
+  /** The path from the importer to the declaring package. */
+  readonly parents: Schema.$Array<typeof PeerParent>;
+}>, {}>;
+/**
+ * One peer dependency that is declared but not satisfied.
+ *
+ * @remarks
+ * `found` carries the version that actually resolved, or `null` when nothing
+ * resolved at all. There is deliberately **no separate discriminant** between
+ * "missing" and "unmet": `found === null` is the whole distinction, and a
+ * renderer reads it directly.
+ *
+ * `optional` must be respected by any gate — an unsatisfied *optional* peer is
+ * normal and should not fail a build, which is why the flag travels with the
+ * row rather than being filtered out here. {@link PeerCheck.required} is the
+ * convenience for the common case.
+ *
+ * `parents` is the path from the importer down to the package that declared
+ * the peer, nearest-to-the-importer first. It is a path rather than a single
+ * package because a peer declared by a transitive dependency is still that
+ * importer's problem, and the chain is what makes the report actionable.
+ *
+ * A package an importer reaches by more than one path yields **one** row, not
+ * one per path, carrying the path the walk reached first — which is what
+ * `pnpm peers check` reports for the same graph. Read `parents` as *a* route to
+ * the declaring package, never as the complete set of them.
+ *
+ * @public
+ */
+export declare class UnsatisfiedPeer extends UnsatisfiedPeer_base {}
+declare const PeerCheck_base: Schema.Class<PeerCheck, Schema.Struct<{
+  /**
+   * Whether the lockfile's format records peer resolution at all.
+   *
+   * `false` for yarn: yarn resolves peers **virtually**, giving a
+   * peer-bearing package one `@virtual:` locator per consumer, and the
+   * lockfile does not record which virtual instance satisfied which peer.
+   * The answer is not recoverable, so it is not fabricated — `unsatisfied`
+   * is empty and this flag says why.
+   */
+  readonly supported: Schema.Boolean;
+  /** Every unsatisfied peer found, optional ones included. */
+  readonly unsatisfied: Schema.$Array<typeof UnsatisfiedPeer>;
+  /**
+   * Importers whose dependencies could not be resolved to instances, so no
+   * verdict was reached for them.
+   *
+   * @remarks
+   * 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.
+   *
+   * Reported rather than silently skipped, for the same reason `supported`
+   * exists: a gate that sees no rows is entitled to know whether that means
+   * "clean" or "not looked at".
+   */
+  readonly unresolvedImporters: Schema.$Array<Schema.String>;
+  /**
+   * Why this report is not a complete answer, or empty when it is.
+   *
+   * @remarks
+   * See {@link UnverifiedReason}. A gate must treat a non-empty `unverified`
+   * as **not proven clean** rather than as a pass: every reason means some
+   * finding may be missing or spurious, and failing closed is the requirement.
+   */
+  readonly unverified: Schema.$Array<Schema.Literals<readonly ["peerRulesNotApplied", "unresolvedEdge", "peerRangeUnresolved", "peerVersionUnresolved"]>>;
+}>, {}>;
+/**
+ * The result of checking a lockfile for unsatisfied peer dependencies.
+ *
+ * @remarks
+ * A report rather than a bare array, because an empty array is the most
+ * dangerous success shape this domain has: it is indistinguishable from "this
+ * format cannot be checked". `supported` and `unresolvedImporters` make the
+ * difference legible, so a consumer cannot read a limitation as a clean bill
+ * of health.
+ *
+ * Pure and total — construct it with {@link PeerCheck.run}, which never fails.
+ *
+ * @example
+ * ```ts
+ * import { PeerCheck } from "@effected/workspaces";
+ * import { Lockfile } from "@effected/lockfiles";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const lockfile = yield* Lockfile.parse(text, { format: "pnpm" });
+ *   const report = PeerCheck.run(lockfile);
+ *   return report.supported ? report.required : [];
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class PeerCheck extends PeerCheck_base {
+  /** The unsatisfied peers a gate should act on — the non-optional ones. */
+  get required(): ReadonlyArray<UnsatisfiedPeer>;
+  /**
+   * Compute the unsatisfied peer dependencies of a parsed lockfile.
+   *
+   * @remarks
+   * Pure, total and format-free: no IO, no error channel, and no knowledge of
+   * which package manager wrote the file. Range satisfaction is
+   * `@effected/semver`'s, never hand-rolled.
+   *
+   * The walk starts at each importer's resolved dependencies and follows
+   * `resolved` edges, so a peer declared by a *transitive* dependency is
+   * attributed to the importer that pulls it in, with the chain in
+   * `parents` — matching how `pnpm peers check` attributes them.
+   * Attribution stops at a workspace package: a linked package's own
+   * dependencies — registry or linked — are judged by that package's own
+   * importer, and a linked package's manifest peers are judged only for the
+   * importer that links it DIRECTLY, against that importer's dependencies.
+   * pnpm never surfaces them on a consumer one link further out.
    *
-   * Three judgements are deliberate:
+   * Four judgements are deliberate:
    *
    * - **A required peer with nothing resolved is reported** (`found: null`),
    *   whether or not the declared range is parseable — a peer with no
@@ -2381,6 +2880,9 @@ export declare class PeerCheck extends PeerCheck_base {
    * - **An unparseable range or version with something resolved is skipped.**
    *   The check cannot judge it, and asserting "unsatisfied" on a comparison
    *   that was never performed would be a wrong answer rather than a gap.
+   *   Two protocol-specifier cases are the exception and fail the report
+   *   closed instead: a joined manifest's range, and a provider whose version
+   *   is a protocol specifier (both below).
    * - **A workspace-linked provider counts.** Resolution is followed through
    *   whatever the edge names, including a workspace row.
    *
@@ -2388,7 +2890,44 @@ export declare class PeerCheck extends PeerCheck_base {
    * bun root importer (see `unresolvedImporters`), and pnpm recording no peer
    * declarations for workspace projects themselves — under pnpm a workspace
    * package's *own* unsatisfied peers are not in the lockfile at all, and
-   * `pnpm peers check` does not report them either.
+   * `pnpm peers check` does not report them either. A `link:`-resolved
+   * importer dependency is the same blind spot from the other side, and there
+   * `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).
+   *
+   * Supplying {@link PeerCheckOptions.workspacePackages} closes that gap for
+   * every `link:` target the set covers — the root importer's included,
+   * whose linked targets the walk seeds itself because the root has no
+   * workspace row to reach them through: the claimed manifest's declared
+   * peers are walked, judged against the importer's own dependency set
+   * (never a sibling importer's), and reported with the manifest's name and
+   * version in `parents` — the two facts a workspace row cannot carry, since
+   * the lockfile names an importer by directory at the placeholder version
+   * `0.0.0`.
+   *
+   * A joined manifest's peer range may be a protocol specifier rather than a
+   * range. A `catalog:` specifier is resolved through
+   * {@link PeerCheckOptions.catalogs} and judged and reported by its
+   * resolved range, as `pnpm peers check` reports `wantedRange`. One that
+   * stays unresolvable — the catalogs key omitted, a catalog naming nothing
+   * for the peer, or another protocol such as `workspace:*` — is not judged
+   * against a provider that resolved for it, and the report carries
+   * `"peerRangeUnresolved"` rather than passing the peer as satisfied. With
+   * nothing resolved for it, the row is still reported, since "no provider"
+   * needs no range.
+   *
+   * The provider side has the same hole: a peer that resolved to a `file:`
+   * dependency, directly or through a `file:` override, carries the specifier
+   * (`file:vendor/react`) where a version belongs, and for a `file:` directory
+   * the lockfile records no version anywhere. `pnpm peers check` reports such a
+   * peer as a `bad` row with the specifier as its found version, even when the
+   * directory's manifest satisfies the range. Such a peer is neither reported
+   * nor passed: no row is fabricated, and the report carries
+   * `"peerVersionUnresolved"`, for a lockfile row's peer and a joined
+   * manifest's peer alike. A workspace-row provider is still accepted without a
+   * version check, and a plain unparseable version is still skipped.
    *
    * @param lockfile - a lockfile parsed by `@effected/lockfiles`
    * @returns the report; never fails
@@ -2718,631 +3257,220 @@ type TagClassification = {
   readonly kind: "unrecognized";
 };
 /**
- * Decide whether a tag string is a release tag, a tracking alias, or neither.
- *
- * @remarks
- * The two families are told apart by **segment count**, not by the `v` prefix:
- * three numeric segments is a version (so `1.0.0` and `v1.0.0` are both release
- * tags), while one or two segments is a truncated alias. The `v` *is* required
- * on an alias — a bare `1` is neither valid SemVer nor the tracking convention,
- * and accepting it would make this function guess.
- *
- * The package prefix splits at the **last** `@`, so a leading npm scope
- * survives: `@scope/pkg@1.0.0` is package `@scope/pkg` at version `1.0.0`.
- *
- * Round-tripping is a tested property: every tag {@link ReleaseTag} and
- * {@link TrackingTag} format classifies back to the family that produced it,
- * with its fields intact.
- *
- * @param tag - Any tag string.
- * @returns The classification.
- *
- * @public
- */
-export declare const classifyTag: (tag: string) => TagClassification;
-declare const ReleaseTag_base: Schema.Class<ReleaseTag, Schema.Struct<{
-  /** The tag string exactly as it appears in git. */
-  readonly value: Schema.NonEmptyString;
-  /** The package the tag names; absent on a workspace-wide single tag. */
-  readonly packageName: Schema.optionalKey<Schema.NonEmptyString>;
-  /** The version the tag names, without any prefix. */
-  readonly version: Schema.NonEmptyString;
-  /** Which style produced it. */
-  readonly style: Schema.Literals<readonly ["single", "scoped"]>;
-}>, {}>;
-/**
- * A git tag naming a release, and the parts it was built from.
- *
- * @remarks
- * `value` is the tag exactly as it appears in git; `version` stays **bare**
- * 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`.
- *
- * @example
- * ```ts
- * import { ReleaseTag } from "@effected/workspaces";
- *
- * ReleaseTag.single("1.2.3").value;               // "1.2.3"
- * ReleaseTag.scoped("@acme/cli", "1.2.3").value;  // "@acme/cli@1.2.3"
- * ReleaseTag.scoped("cli", "1.2.3").value;        // "cli@1.2.3"
- * ReleaseTag.scoped("cli", "1.2.3", { versionPrefix: "v" }).value; // "cli@v1.2.3"
- * ```
- *
- * @public
- */
-export declare class ReleaseTag extends ReleaseTag_base {
-  /**
-   * One shared tag for a whole release: `1.2.3`.
-   *
-   * @param version - The version being released. Must not be empty.
-   * @param options - Formatting overrides.
-   */
-  static single(version: string, options?: TagFormatOptions): ReleaseTag;
-  /**
-   * A per-package tag: `<packageName>@<version>` — `@scope/pkg@1.2.3` for a
-   * scoped name, `pkg@1.2.3` for an unscoped one, uniformly, unless
-   * `options.versionPrefix` says otherwise.
-   *
-   * @param packageName - The package being released. Must not be empty.
-   * @param version - The version being released. Must not be empty.
-   * @param options - Formatting overrides.
-   */
-  static scoped(packageName: string, version: string, options?: TagFormatOptions): ReleaseTag;
-}
-//#endregion
-//#region src/VersioningStrategy.d.ts
-/**
- * How a workspace assigns versions across its publishable packages.
- *
- * @remarks
- * - `single` — zero or one publishable package, so one tag names the release.
- * - `fixed-group` — every publishable package sits inside one group that
- *   versions in lockstep, so one tag still names the release.
- * - `independent` — publishable packages version separately, so a shared tag
- *   would be ambiguous and each package needs its own.
- *
- * @public
- */
-export declare const VersioningStrategyType: Schema.Literals<readonly ["single", "fixed-group", "independent"]>;
-/**
- * The decoded type of {@link (VersioningStrategyType:variable)}.
- *
- * @public
- */
-export type VersioningStrategyType = typeof VersioningStrategyType.Type;
-/**
- * Arguments to {@link VersioningStrategy.classify}.
- *
- * @public
- */
-interface ClassifyOptions {
-  /** Publishable package names, in any order. Duplicates are collapsed. */
-  readonly packages: ReadonlyArray<string>;
-  /**
-   * Groups of packages that version in lockstep.
-   *
-   * @remarks
-   * A **plain argument, deliberately.** Fixed groups are a release tool's
-   * concept — changesets writes them to `.changeset/config.json` — and a
-   * workspace-model package that read that file would be taking on one tool's
-   * schema and one tool's release policy. The caller reads its own tool's
-   * config and hands the groups in. Groups may name packages that are not
-   * publishable, or do not exist; only whether some single group covers the
-   * whole publishable set matters.
-   */
-  readonly fixedGroups?: ReadonlyArray<ReadonlyArray<string>>;
-}
-/**
- * Arguments to {@link VersioningStrategy.detect}.
- *
- * @public
- */
-interface VersioningDetectOptions {
-  /** See {@link ClassifyOptions.fixedGroups}. Defaults to none. */
-  readonly fixedGroups?: ReadonlyArray<ReadonlyArray<string>>;
-}
-/**
- * One entry in a release batch: which package went out, at which version.
- *
- * @remarks
- * Deliberately structural and minimal — a caller passes whatever it already
- * has (a publish result, a changeset plan row) without projecting it into a
- * package-specific type first.
- *
- * @public
- */
-interface PackageRelease {
-  /** The package that was released. */
-  readonly name: string;
-  /** The version it was released at. */
-  readonly version: string;
-}
-declare const VersioningStrategy_base: Schema.Class<VersioningStrategy, Schema.Struct<{
-  /** The classification. */
-  readonly type: Schema.Literals<readonly ["single", "fixed-group", "independent"]>;
-  /** The groups classification was performed against, as supplied. */
-  readonly fixedGroups: Schema.$Array<Schema.$Array<Schema.String>>;
-  /** The publishable package names, sorted and de-duplicated. */
-  readonly publishablePackages: Schema.$Array<Schema.String>;
-}>, {}>;
-/**
- * How a workspace versions, and the tagging that follows from it.
- *
- * @remarks
- * Built either purely with {@link VersioningStrategy.classify}, or from a live
- * workspace with {@link VersioningStrategy.detect}.
- *
- * @example
- * ```ts
- * import { 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);
- * });
- * ```
- *
- * @public
- */
-export declare class VersioningStrategy extends VersioningStrategy_base {
-  /**
-   * Whether a release needs one tag per package rather than one shared tag.
-   */
-  get perPackageTags(): boolean;
-  /** The tag style this strategy implies. */
-  get tagStyle(): TagStyle;
-  /**
-   * Classify a workspace from its publishable package names and fixed groups.
-   *
-   * @remarks
-   * 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.
-   */
-  static classify(options: ClassifyOptions): VersioningStrategy;
-  /**
-   * Classify the ambient workspace: enumerate its packages, keep the ones the
-   * {@link PublishabilityDetector} says publish somewhere, and classify those.
-   *
-   * @remarks
-   * 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.
-   */
-  static readonly detect: (options?: VersioningDetectOptions | undefined) => Effect.Effect<VersioningStrategy, WorkspaceDiscoveryFailure, PublishabilityDetector | WorkspaceDiscovery>;
-  /**
-   * The tags a release of `releases` produces under this strategy.
-   *
-   * @remarks
-   * Under `independent` this is one {@link ReleaseTag} per release, in the
-   * order given. Under `single` and `fixed-group` it is exactly one shared tag
-   * carrying the **first** release's version — every release in a lockstep
-   * batch shares a version by construction, so the choice is only visible on a
-   * batch that should not exist. Whether a batch actually agreed is a property
-   * of that batch rather than of the workspace, so it stays the caller's
-   * one-line check rather than a field here.
-   *
-   * An empty batch produces no tags under either style.
-   */
-  tagsFor(releases: ReadonlyArray<PackageRelease>, options?: TagFormatOptions): ReadonlyArray<ReleaseTag>;
-}
-//#endregion
-//#region src/WorkspaceCatalogs.d.ts
-/**
- * Each importer's dependency-name → resolved-version map, keyed by importer path
- * (`"."` for the root package — the same keys `WorkspaceDiscovery.importerMap()`
- * uses, and the same value `PackageStateSnapshot.relativePath` carries).
+ * Decide whether a tag string is a release tag, a tracking alias, or neither.
  *
  * @remarks
- * What a manager's lockfile records as actually installed, as opposed to what a
- * manifest declares. It answers a `catalog:` specifier no committed catalog
- * source declares — the shape a pnpm config-dependency pnpmfile hook produces —
- * which would otherwise resolve to nothing on both sides of a diff and hide a
- * real version movement.
+ * The two families are told apart by **segment count**, not by the `v` prefix:
+ * three numeric segments is a version (so `1.0.0` and `v1.0.0` are both release
+ * tags), while one or two segments is a truncated alias. The `v` *is* required
+ * on an alias — a bare `1` is neither valid SemVer nor the tracking convention,
+ * and accepting it would make this function guess.
  *
- * Versions are normalized: pnpm's peer-disambiguation suffix
- * (`1.2.3(effect@4.0.0)`) is stripped, and `link:` / `file:` entries are omitted
- * because a filesystem edge is not a version. Only pnpm records importer
- * versions; bun and npm yield an empty index.
+ * The package prefix splits at the **last** `@`, so a leading npm scope
+ * survives: `@scope/pkg@1.0.0` is package `@scope/pkg` at version `1.0.0`.
+ *
+ * Round-tripping is a tested property: every tag {@link ReleaseTag} and
+ * {@link TrackingTag} format classifies back to the family that produced it,
+ * with its fields intact.
+ *
+ * @param tag - Any tag string.
+ * @returns The classification.
  *
  * @public
  */
-type ImporterVersions = Readonly<Record<string, Readonly<Record<string, string>>>>;
-declare const CatalogSet_base: Schema.Class<CatalogSet, Schema.Struct<{
-  /** Catalog name → dependency name → version range. */
-  readonly entries: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>;
+export declare const classifyTag: (tag: string) => TagClassification;
+declare const ReleaseTag_base: Schema.Class<ReleaseTag, Schema.Struct<{
+  /** The tag string exactly as it appears in git. */
+  readonly value: Schema.NonEmptyString;
+  /** The package the tag names; absent on a workspace-wide single tag. */
+  readonly packageName: Schema.optionalKey<Schema.NonEmptyString>;
+  /** The version the tag names, without any prefix. */
+  readonly version: Schema.NonEmptyString;
+  /** Which style produced it. */
+  readonly style: Schema.Literals<readonly ["single", "scoped"]>;
 }>, {}>;
 /**
- * An immutable, fully-normalized catalog collection — the one catalog
- * resolution semantic in the package.
+ * A git tag naming a release, and the parts it was built from.
  *
  * @remarks
- * `entries` is catalog name → dependency → range, with pnpm's unnamed
- * top-level `catalog:` block normalized under the key `"default"`. Lockfile
- * catalog entries, which pnpm records as `{ specifier, version }`, are
- * normalized to their `specifier` — the declared range, which is what a catalog
- * resolves to.
+ * `value` is the tag exactly as it appears in git; `version` stays **bare**
+ * 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`.
+ *
+ * @example
+ * ```ts
+ * import { ReleaseTag } from "@effected/workspaces";
+ *
+ * ReleaseTag.single("1.2.3").value;               // "1.2.3"
+ * ReleaseTag.scoped("@acme/cli", "1.2.3").value;  // "@acme/cli@1.2.3"
+ * ReleaseTag.scoped("cli", "1.2.3").value;        // "cli@1.2.3"
+ * ReleaseTag.scoped("cli", "1.2.3", { versionPrefix: "v" }).value; // "cli@v1.2.3"
+ * ```
  *
  * @public
  */
-export declare class CatalogSet extends CatalogSet_base {
-  /** The empty set — a workspace with no catalogs. */
-  static empty(): CatalogSet;
-  /** Wrap a pnpm `Catalogs` map, dropping unusable entries. */
-  static fromCatalogs(catalogs: unknown): CatalogSet;
-  /**
-   * The `catalog:` and `catalogs:` blocks of a `pnpm-workspace.yaml` document.
-   *
-   * @param text - The raw YAML text.
-   */
-  static readonly fromWorkspaceYaml: (text: string) => Effect.Effect<CatalogSet, CatalogAssemblyError, never>;
-  /**
-   * The `catalogs:` section of a pnpm lockfile, whose entries are either a bare
-   * range or a `{ specifier, version }` pair.
-   */
-  static fromLockfileCatalogs(raw: unknown): CatalogSet;
-  /**
-   * The catalog set a parsed lockfile records, PM-aware.
-   *
-   * @remarks
-   * Both pnpm and bun record catalogs in the lockfile, in different shapes:
-   * pnpm under `extension.catalogs`, bun under `extension.catalog` /
-   * `extension.catalogs`. Assembly reads whichever the parsed lockfile carries
-   * rather than assuming the pnpm extension. A lockfile with no extension, or a
-   * pnpm one with no catalogs, yields the empty set.
-   *
-   * @param lockfile - A parsed lockfile from `@effected/lockfiles`.
-   */
-  static fromLockfile(lockfile: Lockfile): CatalogSet;
-  /**
-   * A catalog set from bun's `{ catalog, catalogs }` blocks — used for the
-   * `bun.lock` extension and for the root `package.json` `workspaces` block. The
-   * unnamed default catalog normalizes under `"default"`. Tolerant: unusable
-   * values are dropped, never fatal.
-   *
-   * @param blocks - The `catalog` (default) and `catalogs` (named) blocks.
-   */
-  static fromBunBlocks(blocks: {
-    readonly catalog?: unknown;
-    readonly catalogs?: unknown;
-  }): CatalogSet;
-  /**
-   * The `catalog` / `catalogs` blocks of a root `package.json` `workspaces` field
-   * — bun's package.json analogue of pnpm's `pnpm-workspace.yaml` blocks.
-   *
-   * @remarks
-   * **Hard-fail by design**, preserving the semantics catalog output is
-   * load-bearing for: a present-but-malformed `workspaces` shape (a number, a
-   * string, an object with a malformed `packages` / `catalog` / `catalogs`), or
-   * the default catalog declared twice — once as `workspaces.catalog` and again
-   * as `workspaces.catalogs.default` — fails with `CatalogAssemblyError`
-   * naming what was wrong. An absent `workspaces` field, one explicitly `null`,
-   * or the plain array form (npm/yarn patterns, which carry no catalogs) yields
-   * the empty set. Presence is checked structurally, so an explicitly-declared
-   * empty `catalog: {}` still counts as a declaration.
-   *
-   * @param text - The raw root `package.json` text.
-   */
-  static readonly fromManifestWorkspaces: (text: string) => Effect.Effect<CatalogSet, CatalogAssemblyError, never>;
-  /** Merge sets. Later sets win per dependency within a catalog. */
-  static merge(...sets: ReadonlyArray<CatalogSet>): CatalogSet;
-  /** Whether any catalog declares anything. */
-  get isEmpty(): boolean;
+export declare class ReleaseTag extends ReleaseTag_base {
   /**
-   * The range a `catalog:` specifier resolves to.
-   *
-   * @remarks
-   * Total: an unmatched dependency, an unknown catalog name, or a non-catalog
-   * specifier all yield `Option.none()`. A *malformed* catalog — one pnpm
-   * itself rejects — also yields `Option.none()` here; the fallible surface is
-   * {@link WorkspaceCatalogs}, which fails typed on assembly instead.
+   * One shared tag for a whole release: `1.2.3`.
    *
-   * @param dependency - The package name being resolved.
-   * @param specifier - The declared specifier, e.g. `catalog:` or `catalog:build`.
+   * @param version - The version being released. Must not be empty.
+   * @param options - Formatting overrides.
    */
-  resolveSpecifier(dependency: string, specifier: string): Option.Option<string>;
+  static single(version: string, options?: TagFormatOptions): ReleaseTag;
   /**
-   * The range `dependency` carries in a named catalog, or in the default
-   * catalog when `catalog` is `Option.none()`.
+   * A per-package tag: `<packageName>@<version>` — `@scope/pkg@1.2.3` for a
+   * scoped name, `pkg@1.2.3` for an unscoped one, uniformly, unless
+   * `options.versionPrefix` says otherwise.
    *
-   * @remarks
-   * The shape `@effected/npm`'s `CatalogResolver` contract asks for.
+   * @param packageName - The package being released. Must not be empty.
+   * @param version - The version being released. Must not be empty.
+   * @param options - Formatting overrides.
    */
-  rangeOf(dependency: string, catalog: Option.Option<string>): Option.Option<string>;
+  static scoped(packageName: string, version: string, options?: TagFormatOptions): ReleaseTag;
 }
+//#endregion
+//#region src/VersioningStrategy.d.ts
 /**
- * Every failure catalog assembly can surface.
+ * How a workspace assigns versions across its publishable packages.
+ *
+ * @remarks
+ * - `single` — zero or one publishable package, so one tag names the release.
+ * - `fixed-group` — every publishable package sits inside one group that
+ *   versions in lockstep, so one tag still names the release.
+ * - `independent` — publishable packages version separately, so a shared tag
+ *   would be ambiguous and each package needs its own.
  *
  * @public
  */
-type CatalogAssemblyFailure = CatalogAssemblyError | WorkspaceRootNotFoundError;
+export declare const VersioningStrategyType: Schema.Literals<readonly ["single", "fixed-group", "independent"]>;
 /**
- * The {@link WorkspaceCatalogs} service shape.
+ * The decoded type of {@link (VersioningStrategyType:variable)}.
  *
  * @public
  */
-interface WorkspaceCatalogsShape {
-  /** The assembled catalog set for the workspace. Memoized after the first call. */
-  readonly set: () => Effect.Effect<CatalogSet, CatalogAssemblyFailure>;
-  /** Resolve one `catalog:` specifier; `Option.none()` when it names nothing. */
-  readonly resolveSpecifier: (dependency: string, specifier: string) => Effect.Effect<Option.Option<string>, CatalogAssemblyFailure>;
-  /**
-   * The effective pnpm release-age gate for the workspace, combined
-   * strictest-wins from the inline `pnpm-workspace.yaml` keys
-   * (`minimumReleaseAge` / `minimumReleaseAgeExclude`) and the replayed
-   * config-dependency hooks. Assembled from the same single read and hook
-   * replay as `set`, and memoized with it.
-   *
-   * @remarks
-   * Under the default layer (no-op hooks) only inline values contribute; under
-   * {@link WorkspaceCatalogs.layerWithConfigDependencies} the replayed hooks
-   * contribute too. A workspace with no pnpm-workspace.yaml (a bun/npm
-   * workspace) has no release-age keys, so the gate is the inert zero gate.
-   */
-  readonly releaseAgeGate: () => Effect.Effect<ReleaseAgeGate, CatalogAssemblyFailure>;
-  /**
-   * The workspace's **effective** `peerDependencyRules` — pnpm's post-hoc
-   * suppression policy, which the lockfile does not record at all.
-   *
-   * @remarks
-   * Assembled from the same single read and hook replay as `set`, and memoized
-   * with it. The `pnpm-workspace.yaml` block (what `pnpm:export` materializes)
-   * is **seeded** into the replayed config and the config-dependency hooks
-   * merge onto it, so one object carries both sources — the kit never merges
-   * them itself, because that would be a second implementation of a rule the
-   * hook seam already enforces.
-   *
-   * A consumer needs these to avoid **reporting** what pnpm suppresses: pnpm
-   * computes the same peer violations and then hides the ones a rule allows,
-   * so a checker without them reports findings pnpm calls clean. `PeerCheck`
-   * applies all three axes.
-   */
-  readonly peerDependencyRules: () => Effect.Effect<PeerDependencyRules, CatalogAssemblyFailure>;
-  /**
-   * Each importer's dependency-name → resolved-version map, as the manager's
-   * lockfile records it. Read from the same single lockfile read as `set`, and
-   * memoized with it.
-   *
-   * @remarks
-   * Feeds `WorkspaceStateSnapshot`'s fallback for a `catalog:` specifier no
-   * committed catalog source declares — the shape a config-dependency pnpmfile
-   * hook produces. Only pnpm records importer versions; a bun or npm workspace
-   * yields an empty index, and an absent or unreadable lockfile contributes
-   * nothing rather than failing.
-   */
-  readonly importerVersions: () => Effect.Effect<ImporterVersions, CatalogAssemblyFailure>;
-  /**
-   * Which version each declared config dependency was replayed from, keyed
-   * by name — off the same single memoized assemble pass as `set()`.
-   *
-   * @remarks
-   * Every dependency the hooks layer resolved when a `pnpm-workspace.yaml`
-   * was read — `{}` when it declares no config dependencies or under the
-   * no-op layer, which resolves nothing. Config dependencies are a pnpm
-   * feature, so the bun / `package.json` path yields `{}` too, exactly as
-   * `importerVersions` does.
-   */
-  readonly hookReplays: () => Effect.Effect<Readonly<Record<string, HookReplay>>, CatalogAssemblyFailure>;
-  /**
-   * Discard the memoized assembly so the **next** read re-assembles — the same
-   * single read and hook replay as the first, over the workspace as it stands
-   * then.
-   *
-   * @remarks
-   * The explicit memoization boundary for a tool that **mutates the workspace
-   * mid-run** — installs, bumps a config dependency, regenerates the lockfile.
-   * Release-age gating wants the before-state, a post-install peer check the
-   * after-state, and one infinite memo cannot serve both without this call in
-   * between; without it, `peerDependencyRules` keeps answering from the
-   * pre-mutation hook replay and the checker reports findings the new rules
-   * suppress.
-   *
-   * Unconditional and infallible: the memo is already success-only (a failed
-   * or interrupted assembly retries by itself), so `refresh` exists solely to
-   * discard a *successful* assembly that mutation has made stale. Calling it
-   * before any read is harmless.
-   */
-  readonly refresh: () => Effect.Effect<void>;
-}
+export type VersioningStrategyType = typeof VersioningStrategyType.Type;
 /**
- * Options for the {@link WorkspaceCatalogs} layer.
+ * Arguments to {@link VersioningStrategy.classify}.
  *
  * @public
  */
-interface WorkspaceCatalogsOptions {
-  /**
-   * The directory the workspace root is resolved from.
-   *
-   * @defaultValue `process.cwd()`, read lazily on first use.
-   */
-  readonly cwd?: string;
+interface ClassifyOptions {
+  /** Publishable package names, in any order. Duplicates are collapsed. */
+  readonly packages: ReadonlyArray<string>;
   /**
-   * A ceiling for the root ascent from `cwd`, passed straight through to the
-   * `stopAt` of {@link WorkspaceRoot}'s `find`.
+   * Groups of packages that version in lockstep.
    *
    * @remarks
-   * Inclusive, and resolved to an absolute path exactly as `cwd` is. When no
-   * root is found at or below the ceiling, catalog assembly fails with
-   * {@link WorkspaceRootNotFoundError} carrying the resolved `stopAt` rather
-   * than adopting an enclosing directory's workspace. Pass the same value as
-   * {@link WorkspaceDiscoveryOptions.stopAt} so every service agrees on the
-   * root; the `Workspaces.*` composites forward one `stopAt` to all of them.
-   *
-   * @defaultValue no ceiling — the ascent runs to the filesystem root.
+   * A **plain argument, deliberately.** Fixed groups are a release tool's
+   * concept — changesets writes them to `.changeset/config.json` — and a
+   * workspace-model package that read that file would be taking on one tool's
+   * schema and one tool's release policy. The caller reads its own tool's
+   * config and hands the groups in. Groups may name packages that are not
+   * publishable, or do not exist; only whether some single group covers the
+   * whole publishable set matters.
    */
-  readonly stopAt?: string | undefined;
+  readonly fixedGroups?: ReadonlyArray<ReadonlyArray<string>>;
 }
-declare const WorkspaceCatalogs_base: Context.ServiceClass<WorkspaceCatalogs, "@effected/workspaces/WorkspaceCatalogs", WorkspaceCatalogsShape>;
 /**
- * Assembles a workspace's catalogs, package-manager-aware.
+ * Arguments to {@link VersioningStrategy.detect}.
+ *
+ * @public
+ */
+interface VersioningDetectOptions {
+  /** See {@link ClassifyOptions.fixedGroups}. Defaults to none. */
+  readonly fixedGroups?: ReadonlyArray<ReadonlyArray<string>>;
+}
+/**
+ * One entry in a release batch: which package went out, at which version.
  *
  * @remarks
- * The inline source is picked by **file presence**, the same rule
- * `internal/patterns.ts` uses for globs: a `pnpm-workspace.yaml` selects the pnpm
- * path (its `catalog:` / `catalogs:` blocks); its absence selects the root
- * `package.json` `workspaces.catalog` / `workspaces.catalogs` (bun's analogue).
- * The lockfile source is PM-aware too — whichever extension the parsed lockfile
- * carries (pnpm or bun) contributes its recorded catalogs.
+ * Deliberately structural and minimal — a caller passes whatever it already
+ * has (a publish result, a changeset plan row) without projecting it into a
+ * package-specific type first.
  *
- * Precedence, lowest first: catalogs recorded in the lockfile, then the inline
- * declaration, then — only under {@link WorkspaceCatalogs.layerWithConfigDependencies}
- * — the config-dependency `pnpmfile.cjs` hooks, each layer winning per dependency
- * within a catalog. An unreadable or absent lockfile degrades to no lockfile
- * catalogs rather than failing (the inline declaration is the source of truth, the
- * lockfile a record of what was installed); a malformed inline source **fails
- * typed** with `CatalogAssemblyError`, because a silently-empty catalog read
- * is the "every dependency looks newly added" bug.
+ * @public
+ */
+interface PackageRelease {
+  /** The package that was released. */
+  readonly name: string;
+  /** The version it was released at. */
+  readonly version: string;
+}
+declare const VersioningStrategy_base: Schema.Class<VersioningStrategy, Schema.Struct<{
+  /** The classification. */
+  readonly type: Schema.Literals<readonly ["single", "fixed-group", "independent"]>;
+  /** The groups classification was performed against, as supplied. */
+  readonly fixedGroups: Schema.$Array<Schema.$Array<Schema.String>>;
+  /** The publishable package names, sorted and de-duplicated. */
+  readonly publishablePackages: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * How a workspace versions, and the tagging that follows from it.
  *
- * Assembly is deferred to the first call and memoized success-only, matching
- * {@link WorkspaceDiscovery}.
+ * @remarks
+ * Built either purely with {@link VersioningStrategy.classify}, or from a live
+ * workspace with {@link VersioningStrategy.detect}.
+ *
+ * @example
+ * ```ts
+ * import { 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);
+ * });
+ * ```
  *
  * @public
  */
-export declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
-  /** Builds the service. */
-  static readonly make: (options?: WorkspaceCatalogsOptions) => Effect.Effect<WorkspaceCatalogsShape, never, WorkspaceRoot | LockfileReader | ConfigDependencyHooks | FileSystem.FileSystem | Path.Path>;
-  /**
-   * The service over an explicit {@link ConfigDependencyHooks} layer — the
-   * one builder every `layer*` static and the `Workspaces` composites
-   * delegate to, so the hooks layer is provided to {@link WorkspaceCatalogs.make}
-   * in exactly one place.
-   *
-   * @remarks
-   * Reach for it when the hooks layer is chosen elsewhere — a composite that
-   * must hand ONE hooks reference to both this service and
-   * `WorkspaceSnapshots` (layers memoize by reference, so two references
-   * would replay twice and could run two policies), or a test wiring
-   * {@link ConfigDependencyHooks.layerFrom}. The three `layer*` statics are
-   * this with the hooks layer fixed. `R` is the hooks layer's own
-   * requirement (the subprocess variant's `ChildProcessSpawner`), threaded
-   * through. Parameterized, so bind it to a `const` and reuse it.
-   *
-   * @param hooks - The {@link ConfigDependencyHooks} layer to replay through.
-   * @param options - The same options the other layer statics take.
-   */
-  static readonly layerWithHooks: <R = never>(hooks: Layer.Layer<ConfigDependencyHooks, never, R>, options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path | R>;
-  /**
-   * The live layer — the default, which **never executes config-dependency
-   * code**: it wires {@link ConfigDependencyHooks.layerNoop}, whose hooks return
-   * the inline-catalog seed untouched.
-   *
-   * @remarks
-   * Parameterized, so it mints a fresh reference per call — bind it to a
-   * `const` and reuse it, or layer memoization does not apply.
-   */
-  static readonly layer: (options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path>;
+export declare class VersioningStrategy extends VersioningStrategy_base {
   /**
-   * The opt-in live layer that **does** replay config-dependency `pnpmfile.cjs`
-   * hooks: it wires {@link ConfigDependencyHooks.layerLive}, which dynamically
-   * imports and runs each config dependency's `updateConfig` in process.
-   *
-   * @remarks
-   * Same output and requirement set as {@link WorkspaceCatalogs.layer} — the only
-   * difference is that config-dependency code is executed. Use it deliberately;
-   * the default catalog path stays free of any config-dependency execution.
-   * Parameterized, so bind it to a `const` and reuse it.
+   * Whether a release needs one tag per package rather than one shared tag.
    */
-  static readonly layerWithConfigDependencies: (options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path>;
+  get perPackageTags(): boolean;
+  /** The tag style this strategy implies. */
+  get tagStyle(): TagStyle;
   /**
-   * The opt-in layer that replays config-dependency `pnpmfile` hooks in a
-   * `node` **child process**: it wires
-   * {@link ConfigDependencyHooks.layerSubprocess} in place of the in-process
-   * `layerLive`.
+   * Classify a workspace from its publishable package names and fixed groups.
    *
    * @remarks
-   * Same typed semantics as {@link WorkspaceCatalogs.layerWithConfigDependencies}
-   * — the two hook layers are drop-in interchangeable — but the replay's
-   * computed dynamic `import()` runs in the subprocess, so it survives bundling
-   * (a bundler compiles a computed in-process `import()` into a context module
-   * that cannot resolve at runtime — every bundled GitHub Action hits this).
-   * The cost is one extra requirement: core's `ChildProcessSpawner`, provided
-   * once at the edge (`@effect/platform-node`'s `NodeServices.layer`) — the
-   * same sanctioned R-widening as `Workspaces.layerWithGit`. Parameterized, so
-   * bind it to a `const` and reuse it.
+   * 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.
    */
-  static readonly layerWithConfigDependenciesSubprocess: (options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  static classify(options: ClassifyOptions): VersioningStrategy;
   /**
-   * A test double satisfying the full {@link WorkspaceCatalogsShape} with no
-   * filesystem, lockfile read, or hook replay.
+   * Classify the ambient workspace: enumerate its packages, keep the ones the
+   * {@link PublishabilityDetector} says publish somewhere, and classify those.
    *
    * @remarks
-   * There is **no honest default catalog set**: an empty `CatalogSet` that
-   * looks like a legitimate answer is the "every dependency looks newly added"
-   * failure class the live assembler hard-fails to prevent, so every method
-   * **dies** with an instructive defect until stubbed — a test-wiring mistake
-   * fails loudly as a defect rather than succeeding with a lie or failing with
-   * a dishonest typed error.
-   *
-   * The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
-   * derived-from-the-primary rule: when a `set` override is supplied,
-   * `resolveSpecifier` answers from that `CatalogSet`'s own
-   * {@link CatalogSet.resolveSpecifier} — exactly what the live service runs
-   * over its assembled set — so the two stay consistent by construction.
-   * `releaseAgeGate`, `importerVersions` and `hookReplays` are **not**
-   * derivable from a catalog set (the gate comes from release-age keys and
-   * hook contributions, the importer index from the lockfile's importer
-   * blocks, the replay record from the hooks layer — none is in a
-   * `CatalogSet`) and always die unless stubbed.
-   *
-   * `refresh` defaults to `Effect.void` honestly: the double holds no memo,
-   * so "drop the memoized assembly" is genuinely a no-op — the stubs answer
-   * fresh on every call already. This mirrors `WorkspaceDiscovery.makeTest`'s
-   * `refresh`.
-   *
-   * @example
-   * ```ts
-   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
-   * import { Effect } from "effect";
-   *
-   * const double = WorkspaceCatalogs.makeTest({
-   *   set: () => Effect.succeed(CatalogSet.fromCatalogs({ default: { effect: "4.0.0" } })),
-   * });
-   * // `resolveSpecifier` now answers consistently from that set.
-   * ```
+   * 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.
    */
-  static readonly makeTest: (overrides?: Partial<WorkspaceCatalogsShape>) => WorkspaceCatalogsShape;
+  static readonly detect: (options?: VersioningDetectOptions | undefined) => Effect.Effect<VersioningStrategy, WorkspaceDiscoveryFailure, PublishabilityDetector | WorkspaceDiscovery>;
   /**
-   * The test layer: {@link WorkspaceCatalogs.makeTest} behind `Layer.succeed`,
-   * so a suite provides only the methods it exercises.
+   * The tags a release of `releases` produces under this strategy.
    *
    * @remarks
-   * A parameterized layer factory mints a **fresh reference per call**, and
-   * layers memoize by reference — bind the result to a `const` and reuse it
-   * rather than calling `layerTest(...)` at each composition site.
-   *
-   * @example
-   * ```ts
-   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
-   * import { Effect } from "effect";
-   *
-   * const TestCatalogs = WorkspaceCatalogs.layerTest({
-   *   set: () => Effect.succeed(CatalogSet.empty()),
-   * });
-   * // program.pipe(Effect.provide(TestCatalogs))
-   * ```
-   */
-  static readonly layerTest: (overrides?: Partial<WorkspaceCatalogsShape>) => Layer.Layer<WorkspaceCatalogs>;
-  /**
-   * The real implementation of `@effected/npm`'s `CatalogResolver` contract —
-   * the one `@effected/package-json` declares but cannot fill.
+   * Under `independent` this is one {@link ReleaseTag} per release, in the
+   * order given. Under `single` and `fixed-group` it is exactly one shared tag
+   * carrying the **first** release's version — every release in a lockstep
+   * batch shares a version by construction, so the choice is only visible on a
+   * batch that should not exist. Whether a batch actually agreed is a property
+   * of that batch rather than of the workspace, so it stays the caller's
+   * one-line check rather than a field here.
    *
-   * @remarks
-   * `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`.
+   * An empty batch produces no tags under either style.
    */
-  static readonly catalogResolver: Layer.Layer<CatalogResolver, never, WorkspaceCatalogs>;
+  tagsFor(releases: ReadonlyArray<PackageRelease>, options?: TagFormatOptions): ReadonlyArray<ReleaseTag>;
 }
 //#endregion
 //#region src/WorkspaceStateSnapshot.d.ts
@@ -3350,23 +3478,24 @@ declare const PackageStateSnapshot_base: Schema.Class<PackageStateSnapshot, Sche
   /** The package name. */
   readonly name: Schema.NonEmptyString;
   /**
-   * The raw `version` string, as recorded at the captured moment — or `""` for
+   * The raw `version` string, as recorded at the captured moment — absent for
    * a manifest that declared none.
    *
    * @remarks
-   * `WorkspacePackage.version` is optional and a version-less member is an
-   * ordinary pnpm shape, but this field stays a plain required string because a
-   * snapshot is a serialized value someone stores and diffs: an absent key and
-   * a present one would read as a change the moment one side of a diff was
-   * captured by a different code path. **`""` is therefore the sentinel for
-   * "the manifest declared no version", not a version anyone can use** — both
-   * `snapshotOf` at a ref and the worktree snapshot write it, so the two sides
-   * agree. Every resolution surface treats it as absence:
-   * {@link WorkspaceStateSnapshot.resolve} answers `Option.none()` for a
-   * `workspace:` specifier against it, because `some("")` would rewrite
-   * `workspace:^` as a bare `"^"`.
-   */
-  readonly version: Schema.String;
+   * Optional exactly as `WorkspacePackage.version` is: a version-less member is
+   * 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.
+   *
+   * A version-less member is still a member: it appears in `packages` and
+   * answers {@link WorkspaceStateSnapshot.package}, but is absent from
+   * {@link WorkspaceStateSnapshot.versions}, resolves a `workspace:` specifier
+   * to `Option.none()`, and fails its snapshot-bound `WorkspaceResolver`'s
+   * `versionOf` typed.
+   */
+  readonly version: Schema.decodeTo<Schema.optionalKey<Schema.NonEmptyString>, Schema.optionalKey<Schema.String>, never, never>;
   /** POSIX path relative to the workspace root; `"."` for the root package. */
   readonly relativePath: Schema.String;
   /** Production dependencies. */
@@ -3497,15 +3626,13 @@ declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot,
 export declare class WorkspaceStateSnapshot extends WorkspaceStateSnapshot_base {
   #private;
   /**
-   * Every captured package's name → version. Total; O(1) after the first call.
+   * Every captured package's name → version, for the packages that declared
+   * one. Total; O(1) after the first call.
    *
    * @remarks
-   * Values are `PackageStateSnapshot.version` verbatim, so a member whose
-   * manifest declared no version maps to the **`""` sentinel** rather than
-   * being absent from the map — presence here answers membership, not
-   * "has a usable version". A caller reading a version out of this map owes
-   * the `""` check itself; {@link WorkspaceStateSnapshot.resolve} already
-   * makes it.
+   * A member whose manifest declared no version is **absent** from this map,
+   * so every value is a real version and presence answers "has a version",
+   * not membership — ask {@link WorkspaceStateSnapshot.package} for that.
    */
   get versions(): ReadonlyMap<string, string>;
   /** A single captured package by name, or `Option.none()`. Total. */
@@ -4497,6 +4624,33 @@ interface WorkspaceDiscoverySkip {
    */
   readonly cause: unknown;
 }
+/**
+ * Options for {@link findWorkspaceRootSync}: the consumer-supplied operations
+ * plus the ascent's ceiling.
+ *
+ * @public
+ */
+interface FindWorkspaceRootSyncOptions extends WorkspacesSyncOptions {
+  /**
+   * A ceiling directory, with the semantics of `FindWorkspaceRootOptions.stopAt`
+   * on the Effect surface. The ascent stops after probing it, so an unmarked
+   * `stopAt` returns `null` rather than silently adopting an enclosing
+   * repository's workspace.
+   *
+   * @remarks
+   * Inclusive: a ceiling that is itself a workspace root is returned. The
+   * ceiling is resolved through the supplied {@link SyncPath.resolve} at
+   * lookup time, so a relative one is taken against the process working
+   * directory when the call runs (with `node:path`). A ceiling that names no
+   * ancestor of `cwd` never matches, and the ascent runs to the filesystem
+   * root. Omit it for the unbounded ascent.
+   *
+   * Pass `stopAt: cwd` for a checkout nested inside someone else's workspace
+   * (a self-hosted runner, `actions/checkout` with `path:`): a checkout that is
+   * itself a root still resolves, and one that is not returns `null`.
+   */
+  readonly stopAt?: string | undefined;
+}
 /**
  * The nearest workspace root at or above `cwd`, or `null`.
  *
@@ -4517,9 +4671,17 @@ interface WorkspaceDiscoverySkip {
  * Markers match the async service exactly: a `pnpm-workspace.yaml`, or a
  * `package.json` carrying a `workspaces` field.
  *
+ * The ascent is unbounded unless `options.stopAt` names a ceiling
+ * ({@link FindWorkspaceRootSyncOptions.stopAt}), with the Effect surface's
+ * semantics: inclusive, resolved at lookup time. Where `WorkspaceRoot.find`
+ * fails `WorkspaceRootNotFoundError` carrying the resolved ceiling, this
+ * returns `null` — the facade is total and has no error channel, and the
+ * caller already holds the ceiling it passed.
+ *
  * @param cwd - Where to start the ascent (typically `process.cwd()`),
  *   matching the Effect layers' `{ cwd }` option.
- * @param options - The consumer-supplied file and path operations.
+ * @param options - The consumer-supplied file and path operations, plus an
+ *   optional `stopAt` ceiling.
  *
  * @example
  * ```ts
@@ -4540,7 +4702,7 @@ interface WorkspaceDiscoverySkip {
  *
  * @public
  */
-export declare const findWorkspaceRootSync: (cwd: string, options: WorkspacesSyncOptions) => string | null;
+export declare const findWorkspaceRootSync: (cwd: string, options: FindWorkspaceRootSyncOptions) => string | null;
 /**
  * Options for {@link getWorkspacePackagesSync}: the required consumer-supplied
  * operations plus the traversal bound.
@@ -4628,5 +4790,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, 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 };
+export type { CatalogAssemblyFailure, ChangeDetectionFailure, ChangeDetectorShape, ClassifyOptions, ConfigDependencyHooksShape, DependencyDiff, DuplicateCheckOptions, FindWorkspaceRootOptions, FindWorkspaceRootSyncOptions, 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