@effected/workspaces 0.1.0

package/index.d.ts

@@ -0,0 +1,1559 @@
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
+import { CatalogResolver, WorkspaceResolver } from "@effected/npm";
+import { GlobPattern } from "@effected/glob";
+import { Lockfile, LockfileFramingError, LockfileIntegrity, LockfileParseError, ResolvedPackage, WorkspaceManifest } from "@effected/lockfiles";
+import { Package } from "@effected/package-json";
+import { ChildProcessSpawner } from "effect/unstable/process";
+//#region src/CatalogAssemblyError.d.ts
+declare const CatalogAssemblyError_base: Schema.Class<CatalogAssemblyError, Schema.TaggedStruct<"CatalogAssemblyError", {
+  /**
+   * Which input failed: `manifest` for a file-level or top-level shape problem,
+   * `catalog` for a malformed catalog block or the double-default duplication,
+   * `hooks` for a config-dependency `pnpmfile.cjs` load or replay failure.
+   */
+  readonly source: Schema.Literals<readonly ["manifest", "catalog", "hooks"]>;
+  /** The file, the catalog name, or the config dependency name. */
+  readonly path: Schema.String;
+  /** The originating failure. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a workspace's catalogs cannot be assembled — a `pnpm-workspace.yaml`
+ * that is unreadable or not valid YAML, a root `package.json` `workspaces` field
+ * whose shape or catalog blocks are malformed in a way pnpm itself rejects
+ * (including the default catalog declared twice), or a config dependency whose
+ * `pnpmfile.cjs` cannot be loaded or replayed.
+ *
+ * @remarks
+ * A *missing* `pnpm-workspace.yaml`, an *absent* `workspaces` field, or one
+ * explicitly `null` is not an error: there is simply nothing to misread, so
+ * assembly yields the empty set. The reader is otherwise **hard-fail by design** —
+ * a silently-empty catalog read is the "every dependency looks newly added" bug,
+ * because catalog output is load-bearing for snapshot diffing.
+ *
+ * @public
+ */
+declare class CatalogAssemblyError extends CatalogAssemblyError_base {
+  /** Renders the failing source into a one-line message. */
+  get message(): string;
+}
+//#endregion
+//#region src/WorkspacePackage.d.ts
+declare const PublishConfig_base: Schema.Class<PublishConfig, Schema.Struct<{
+  /** Scoped-package visibility. Its presence overrides `private`. */
+  readonly access: Schema.optionalKey<Schema.Literals<readonly ["public", "restricted"]>>;
+  /** The registry to publish to. */
+  readonly registry: Schema.optionalKey<Schema.String>;
+  /** A subdirectory to publish instead of the package root. */
+  readonly directory: Schema.optionalKey<Schema.String>;
+  /** The dist-tag to publish under. */
+  readonly tag: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * The `publishConfig` fields workspace tooling reads.
+ *
+ * @remarks
+ * Deliberately narrow. `@effected/package-json` models `publishConfig` as an
+ * open `Record<string, unknown>` for round-trip fidelity, which preserves every
+ * key but types none of them; this is the typed projection of the four that
+ * decide *where and whether* a package publishes. Unknown keys are ignored, not
+ * rejected.
+ *
+ * @public
+ */
+declare class PublishConfig extends PublishConfig_base {}
+/**
+ * The result of comparing two {@link WorkspacePackage} dependency snapshots.
+ *
+ * @remarks
+ * Comparison runs across all four dependency kinds combined, so a dependency
+ * that moves between kinds at the same version does not appear in the diff.
+ *
+ * @public
+ */
+interface DependencyDiff {
+  /** Present in the receiver, absent from the other. */
+  readonly added: Record<string, string>;
+  /** Present in the other, absent from the receiver. */
+  readonly removed: Record<string, string>;
+  /** Present in both at different specifiers. */
+  readonly changed: Record<string, {
+    readonly from: string;
+    readonly to: string;
+  }>;
+}
+declare const WorkspaceManifestError_base: Schema.Class<WorkspaceManifestError, Schema.TaggedStruct<"WorkspaceManifestError", {
+  /** Absolute path to the `package.json` that failed. */
+  readonly packageJsonPath: Schema.String;
+  /** Whether the file could not be read, or read but not decoded. */
+  readonly kind: Schema.Literals<readonly ["read", "decode"]>;
+  /** The originating failure, preserved rather than flattened to a string. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a workspace member's `package.json` cannot be read or decoded
+ * into the strict `@effected/package-json` `Package` model.
+ *
+ * @remarks
+ * Discovery itself never raises this — it uses the tolerant projection. Only
+ * `WorkspacePackage.manifest` does, so opting into the strict model is an
+ * explicit, individually recoverable step.
+ *
+ * @public
+ */
+declare class WorkspaceManifestError extends WorkspaceManifestError_base {
+  /** Renders the path and failure kind into a one-line message. */
+  get message(): string;
+}
+declare const WorkspacePackage_base: Schema.Class<WorkspacePackage, Schema.Struct<{
+  /** The package name. */
+  readonly name: Schema.NonEmptyString;
+  /** The raw `version` string — deliberately not semver-validated. */
+  readonly version: Schema.String;
+  /** Absolute path to the package directory. */
+  readonly path: Schema.NonEmptyString;
+  /** Absolute path to the package's `package.json`. */
+  readonly packageJsonPath: Schema.NonEmptyString;
+  /** POSIX path relative to the workspace root; `"."` for the root package. */
+  readonly relativePath: Schema.String;
+  /** Whether the package is marked private. */
+  readonly private: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.Boolean, never>>;
+  /** Production dependencies. */
+  readonly dependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** Development dependencies. */
+  readonly devDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** Peer dependencies. */
+  readonly peerDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** Optional dependencies. */
+  readonly optionalDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** The `publishConfig` block, when present. */
+  readonly publishConfig: Schema.optionalKey<typeof PublishConfig>;
+}>, {}>;
+/**
+ * A single package inside a workspace: the discovery-relevant slice of its
+ * `package.json` plus its filesystem location.
+ *
+ * @remarks
+ * Produced by `WorkspaceDiscovery` for every directory the `packages:` patterns
+ * enumerate. The root package is always present with `relativePath` `"."`.
+ *
+ * @example
+ * ```ts
+ * import { WorkspacePackage } from "@effected/workspaces";
+ *
+ * const pkg = WorkspacePackage.make({
+ *   name: "@my-org/utils",
+ *   version: "1.0.0",
+ *   path: "/repo/packages/utils",
+ *   packageJsonPath: "/repo/packages/utils/package.json",
+ *   relativePath: "packages/utils",
+ * });
+ *
+ * pkg.isRootWorkspace; // false
+ * pkg.unscopedName;    // "utils"
+ * ```
+ *
+ * @public
+ */
+declare class WorkspacePackage extends WorkspacePackage_base {
+  /** Whether this is the workspace root package. */
+  get isRootWorkspace(): boolean;
+  /** Whether the package is publishable in principle (not marked private). */
+  get isPublic(): boolean;
+  /** The npm scope (`@org`), or `Option.none()` for an unscoped name. */
+  get scope(): Option.Option<string>;
+  /** The name with any scope stripped. */
+  get unscopedName(): string;
+  /**
+   * Every dependency, merged across the four kinds.
+   *
+   * @remarks
+   * Precedence on a name declared in several kinds runs
+   * `dependencies` \> `devDependencies` \> `peerDependencies` \>
+   * `optionalDependencies`.
+   */
+  get allDependencies(): Record<string, string>;
+  /** Whether `name` is a production dependency. */
+  hasDependency(name: string): boolean;
+  /** Whether `name` is a development dependency. */
+  hasDevDependency(name: string): boolean;
+  /** Whether `name` is a peer dependency. */
+  hasPeerDependency(name: string): boolean;
+  /** Whether `name` is an optional dependency. */
+  hasOptionalDependency(name: string): boolean;
+  /** Whether `name` appears in any of the four dependency kinds. */
+  hasAnyDependencyOn(name: string): boolean;
+  /** The declared specifier for `name`, searched across all four kinds. */
+  dependencyVersion(name: string): Option.Option<string>;
+  /**
+   * Whether any dependency name matches `pattern` — the `minimatch` runtime
+   * dependency's one call site, now over `@effected/glob`'s vendored engine.
+   *
+   * @remarks
+   * A `GlobPattern` is total and free to test. A `string` is compiled on every
+   * call and an **uncompilable** literal throws: a glob written into a call
+   * site is developer wiring, not untrusted input, so it belongs in the defect
+   * channel rather than widening the typed channel every caller must branch
+   * on. Compile once with `GlobPattern.compile` and pass the result when
+   * testing many packages.
+   *
+   * @param pattern - A compiled pattern, or a source string to compile.
+   */
+  matchesDependency(pattern: GlobPattern | string): boolean;
+  /** Compare this package's dependencies against `other`'s. */
+  dependencyDiff(other: WorkspacePackage): DependencyDiff;
+  /**
+   * Project to `@effected/lockfiles`' `WorkspaceManifest` — the input shape of
+   * `LockfileIntegrity.compare`. Total.
+   */
+  toWorkspaceManifest(): WorkspaceManifest;
+  /**
+   * Read and decode this package's `package.json` into the strict
+   * `@effected/package-json` `Package` model — the bridge from the
+   * tolerant discovery projection to the fully typed manifest.
+   */
+  static readonly manifest: (self: WorkspacePackage) => Effect.Effect<Package, WorkspaceManifestError, FileSystem.FileSystem>;
+  /** Instance form of `WorkspacePackage.manifest`. */
+  manifest(): Effect.Effect<Package, WorkspaceManifestError, FileSystem.FileSystem>;
+}
+//#endregion
+//#region src/WorkspaceRoot.d.ts
+/**
+ * The marker filenames {@link WorkspaceRoot} probes for, in priority order.
+ *
+ * @public
+ */
+declare const WORKSPACE_MARKERS: ReadonlyArray<string>;
+declare const WorkspaceRootNotFoundError_base: Schema.Class<WorkspaceRootNotFoundError, Schema.TaggedStruct<"WorkspaceRootNotFoundError", {
+  /** The directory the ascent started from. */
+  readonly searchPath: Schema.String;
+  /** The marker filenames probed at each ancestor. */
+  readonly markers: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when no workspace root can be found by ascending from a directory.
+ *
+ * @remarks
+ * `markers` records what was probed, so the failure names the contract rather
+ * than paraphrasing it in prose.
+ *
+ * @public
+ */
+declare class WorkspaceRootNotFoundError extends WorkspaceRootNotFoundError_base {
+  /** Renders the search path and probed markers into a one-line message. */
+  get message(): string;
+}
+declare const WorkspaceRoot_base: Context.ServiceClass<WorkspaceRoot, "@effected/workspaces/WorkspaceRoot", {
+  /**
+   * The nearest workspace root at or above `cwd`.
+   *
+   * @param cwd - The directory to start the ascent from; resolved to an
+   *   absolute path first.
+   */
+  readonly find: (cwd: string) => Effect.Effect<string, WorkspaceRootNotFoundError>;
+}>;
+/**
+ * Locates the workspace root by ascending from a starting directory.
+ *
+ * @example
+ * ```ts
+ * import { WorkspaceRoot } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root = yield* WorkspaceRoot;
+ *   return yield* root.find("/repo/packages/utils/src");
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class WorkspaceRoot extends WorkspaceRoot_base {
+  /** Builds the service over core `FileSystem` and `Path`. */
+  static readonly make: Effect.Effect<{
+    readonly find: (cwd: string) => Effect.Effect<string, WorkspaceRootNotFoundError>;
+  }, never, FileSystem.FileSystem | Path.Path>;
+  /** The live layer. */
+  static readonly layer: Layer.Layer<WorkspaceRoot, never, FileSystem.FileSystem | Path.Path>;
+}
+//#endregion
+//#region src/WorkspaceDiscovery.d.ts
+declare const WorkspaceDiscoveryError_base: Schema.Class<WorkspaceDiscoveryError, Schema.TaggedStruct<"WorkspaceDiscoveryError", {
+  /** The workspace root discovery was running against. */
+  readonly root: Schema.String;
+  /** The file that failed. */
+  readonly path: Schema.String;
+  /** What went wrong with it. */
+  readonly kind: Schema.Literals<readonly ["read", "invalidJson", "invalidShape", "invalidYaml", "missingName", "missingVersion"]>;
+  /** The originating failure, if there was one. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a workspace member's `package.json` cannot be read, parsed, or
+ * used — it is missing, malformed, or lacks a `name` or `version`.
+ *
+ * @remarks
+ * `kind` is the discriminant a caller branches on; `cause` preserves the
+ * originating failure rather than flattening it into a sentence.
+ *
+ * @public
+ */
+declare class WorkspaceDiscoveryError extends WorkspaceDiscoveryError_base {
+  /** Renders the failing file and kind into a one-line message. */
+  get message(): string;
+}
+declare const WorkspacePatternError_base: Schema.Class<WorkspacePatternError, Schema.TaggedStruct<"WorkspacePatternError", {
+  /** The workspace root the patterns were expanded against. */
+  readonly root: Schema.String;
+  /** The offending pattern, verbatim. */
+  readonly pattern: Schema.String;
+  /** Why it could not be enumerated. */
+  readonly kind: Schema.Literals<readonly ["missingBaseDir", "uncompilable", "depthExceeded", "budgetExceeded", "unreadableDirectory"]>;
+  /** A short, structured detail — the missing directory, or the bound exceeded. */
+  readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a `packages:` pattern cannot be enumerated: its base directory is
+ * absent (usually a typo), the descent exceeded its depth cap, or the visit
+ * budget was exhausted.
+ *
+ * @public
+ */
+declare class WorkspacePatternError extends WorkspacePatternError_base {
+  /** Renders the pattern and failure kind into a one-line message. */
+  get message(): string;
+}
+declare const PackageNotFoundError_base: Schema.Class<PackageNotFoundError, Schema.TaggedStruct<"PackageNotFoundError", {
+  /** The name that was requested. */
+  readonly name: Schema.String;
+  /** Every workspace package name that does exist. */
+  readonly available: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a workspace package is requested by a name no member carries.
+ *
+ * @remarks
+ * `available` lists every known member, which is what makes the error
+ * actionable — a typo is obvious next to the list it missed.
+ *
+ * @public
+ */
+declare class PackageNotFoundError extends PackageNotFoundError_base {
+  /** Renders the requested name into a one-line message. */
+  get message(): string;
+}
+declare const WorkspaceInfo_base: Schema.Class<WorkspaceInfo, Schema.Struct<{
+  /** Absolute path to the workspace root. */
+  readonly root: Schema.String;
+  /** The `packages:` patterns, verbatim. */
+  readonly patterns: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * Top-level facts about a workspace: where it is, what manages it, and the
+ * patterns that define its membership.
+ *
+ * @public
+ */
+declare class WorkspaceInfo extends WorkspaceInfo_base {}
+/**
+ * Every failure `WorkspaceDiscovery.getPackage` can surface: the discovery
+ * failures plus a name that matches no member.
+ *
+ * @public
+ */
+type WorkspaceLookupFailure = WorkspaceRootNotFoundError | WorkspaceDiscoveryError | WorkspacePatternError | PackageNotFoundError;
+/**
+ * The error channel of the discovery methods that do not look a package up by
+ * name — everything except `getPackage`.
+ *
+ * @public
+ */
+type WorkspaceDiscoveryFailure = Exclude<WorkspaceLookupFailure, PackageNotFoundError>;
+/**
+ * Options for the {@link WorkspaceDiscovery} layer.
+ *
+ * @public
+ */
+interface WorkspaceDiscoveryOptions {
+  /**
+   * The directory the workspace root is resolved from.
+   *
+   * @defaultValue `process.cwd()`, read lazily on first use — so a
+   *   `process.chdir` between providing the layer and the first call is
+   *   honoured.
+   */
+  readonly cwd?: string;
+  /** Descent cap for segment-crossing patterns. Defaults to 32. */
+  readonly maxDepth?: number;
+}
+/**
+ * The {@link WorkspaceDiscovery} service shape.
+ *
+ * @public
+ */
+interface WorkspaceDiscoveryShape {
+  /** Facts about the resolved workspace. */
+  readonly info: () => Effect.Effect<WorkspaceInfo, WorkspaceDiscoveryFailure>;
+  /** Every workspace package, root first, then the rest sorted by relative path. */
+  readonly listPackages: () => Effect.Effect<ReadonlyArray<WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /** The discovered packages keyed by their root-relative importer path. */
+  readonly importerMap: () => Effect.Effect<ReadonlyMap<string, WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /** A single package by name. */
+  readonly getPackage: (name: string) => Effect.Effect<WorkspacePackage, WorkspaceLookupFailure>;
+  /** The package owning an absolute file path, by longest-prefix match. */
+  readonly resolveFile: (filePath: string) => Effect.Effect<Option.Option<WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /** The distinct packages owning any of `filePaths`. */
+  readonly resolveFiles: (filePaths: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /** Drop the memoized discovery so the next call re-reads the filesystem. */
+  readonly refresh: () => Effect.Effect<void>;
+}
+declare const WorkspaceDiscovery_base: Context.ServiceClass<WorkspaceDiscovery, "@effected/workspaces/WorkspaceDiscovery", WorkspaceDiscoveryShape>;
+/**
+ * Discovers the packages of a workspace.
+ *
+ * @remarks
+ * Layer construction is O(1): the root walk, pattern read, enumeration and
+ * per-package decode all happen on the first method call and are memoized for
+ * the lifetime of the layer. A Vitest reporter that builds the layer per call
+ * site and never queries it pays nothing.
+ *
+ * The memo is **success-only**. `Effect.cached` memoizes the first `Exit`,
+ * *including an interrupt* — an init interrupted by an unrelated timeout would
+ * otherwise brick the layer permanently with a cause outside its declared error
+ * channel. A failure or interrupt is therefore retried on the next call, which
+ * is a deliberate behaviour change from the v3 library.
+ *
+ * @example
+ * ```ts
+ * import { WorkspaceDiscovery } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const discovery = yield* WorkspaceDiscovery;
+ *   const packages = yield* discovery.listPackages();
+ *   return packages.map((p) => p.name);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class WorkspaceDiscovery extends WorkspaceDiscovery_base {
+  /**
+   * Builds the service. Root resolution is one explicit concern: `cwd` is an
+   * option here, never an ambient `process.cwd()` read inside a method.
+   */
+  static readonly make: (options?: WorkspaceDiscoveryOptions) => Effect.Effect<WorkspaceDiscoveryShape, never, WorkspaceRoot | FileSystem.FileSystem | Path.Path>;
+  /**
+   * The live layer.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layer(...)` at each composition site.
+   */
+  static readonly layer: (options?: WorkspaceDiscoveryOptions) => Layer.Layer<WorkspaceDiscovery, never, WorkspaceRoot | FileSystem.FileSystem | Path.Path>;
+  /**
+   * The real implementation of `@effected/npm`'s `WorkspaceResolver` contract
+   * — the one `@effected/package-json` declares but cannot fill.
+   *
+   * @remarks
+   * `versionOf` returns `Option.none()` for a name that is not a workspace
+   * member, per the contract's convention; the `DependencyResolutionError`
+   * channel is reserved for a failure of the resolution *mechanism* (an
+   * unfindable root, an unreadable manifest), never an ordinary miss.
+   *
+   * @example
+   * ```ts
+   * import { Package } from "@effected/package-json";
+   * import { WorkspaceDiscovery } from "@effected/workspaces";
+   * import { Layer } from "effect";
+   *
+   * const resolvers = WorkspaceDiscovery.workspaceResolver.pipe(
+   *   Layer.provide(WorkspaceDiscovery.layer()),
+   * );
+   * // `Package.resolve` now resolves `workspace:*` for real.
+   * ```
+   */
+  static readonly workspaceResolver: Layer.Layer<WorkspaceResolver, never, WorkspaceDiscovery>;
+}
+//#endregion
+//#region src/ChangeDetector.d.ts
+declare const ChangeDetectionOptions_base: Schema.Class<ChangeDetectionOptions, Schema.Struct<{
+  /**
+   * The ref to compare against.
+   *
+   * @defaultValue `"HEAD~1"`
+   */
+  readonly base: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.String, never>>;
+  /**
+   * The ref to compare to.
+   *
+   * @defaultValue `"HEAD"`
+   */
+  readonly head: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.String, never>>;
+  /**
+   * Whether to include staged, unstaged and untracked working-tree changes on
+   * top of the committed range.
+   *
+   * @defaultValue `false`
+   */
+  readonly includeUncommitted: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.Boolean, never>>;
+}>, {}>;
+/**
+ * Which git refs to compare, and whether to fold in the working tree.
+ *
+ * @example
+ * ```ts
+ * import { ChangeDetectionOptions } from "@effected/workspaces";
+ *
+ * ChangeDetectionOptions.make({});                       // HEAD~1...HEAD
+ * ChangeDetectionOptions.make({ base: "origin/main" });  // against a branch
+ * ```
+ *
+ * @public
+ */
+declare class ChangeDetectionOptions extends ChangeDetectionOptions_base {}
+declare const ChangeDetectionError_base: Schema.Class<ChangeDetectionError, Schema.TaggedStruct<"ChangeDetectionError", {
+  /** The operation that could not run. */
+  readonly operation: Schema.String;
+  /** The originating failure. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when change detection cannot proceed for a reason that is not one of
+ * git's own typed failures — the wrapper for "detection has no ground to stand
+ * on".
+ *
+ * @remarks
+ * A git command that merely *fails* surfaces as one of `@effected/git`'s typed
+ * errors ({@link ChangeDetectionFailure} carries `GitCommandError`,
+ * `NotARepositoryError` and `UnknownRefError`) rather than being flattened into
+ * this wrapper — a caller branches on git's taxonomy directly.
+ *
+ * @public
+ */
+declare class ChangeDetectionError extends ChangeDetectionError_base {
+  /** Renders the failed operation into a one-line message. */
+  get message(): string;
+}
+/**
+ * Every failure the change-detection methods can surface.
+ *
+ * @remarks
+ * `@effected/git`'s typed errors surface directly alongside
+ * {@link ChangeDetectionError} and the discovery failures — a git command that
+ * fails is reported as git classified it (`NotARepositoryError` for a
+ * non-repository, `UnknownRefError` for a bad ref, `GitCommandError`
+ * otherwise), not re-wrapped.
+ *
+ * @public
+ */
+type ChangeDetectionFailure = ChangeDetectionError | GitCommandError | NotARepositoryError | UnknownRefError | WorkspaceDiscoveryFailure;
+/**
+ * The {@link ChangeDetector} service shape.
+ *
+ * @public
+ */
+interface ChangeDetectorShape {
+  /** The file paths (workspace-root-relative, as git reports them) changed in the range. */
+  readonly changedFiles: (options?: ChangeDetectionOptions) => Effect.Effect<ReadonlyArray<string>, ChangeDetectionFailure>;
+  /** The workspace packages owning those files. */
+  readonly changedPackages: (options?: ChangeDetectionOptions) => Effect.Effect<ReadonlyArray<WorkspacePackage>, ChangeDetectionFailure>;
+  /** Those packages plus every workspace package that transitively depends on one. */
+  readonly affectedPackages: (options?: ChangeDetectionOptions) => Effect.Effect<ReadonlyArray<WorkspacePackage>, ChangeDetectionFailure>;
+}
+declare const ChangeDetector_base: Context.ServiceClass<ChangeDetector, "@effected/workspaces/ChangeDetector", ChangeDetectorShape>;
+/**
+ * Detects which workspace packages a git range touches.
+ *
+ * @remarks
+ * Three depths on one service, cheapest first — raw file paths, the packages
+ * owning them, and the transitive blast radius through the dependency graph.
+ *
+ * @example
+ * ```ts
+ * import { ChangeDetectionOptions, ChangeDetector } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const detector = yield* ChangeDetector;
+ *   const affected = yield* detector.affectedPackages(
+ *     ChangeDetectionOptions.make({ base: "origin/main" }),
+ *   );
+ *   return affected.map((pkg) => pkg.name);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class ChangeDetector extends ChangeDetector_base {
+  /** Builds the service over `Git` and {@link WorkspaceDiscovery}. */
+  static readonly make: Effect.Effect<ChangeDetectorShape, never, Git | WorkspaceDiscovery>;
+  /** The live layer. */
+  static readonly layer: Layer.Layer<ChangeDetector, never, Git | WorkspaceDiscovery>;
+}
+//#endregion
+//#region src/ConfigDependencyHooks.d.ts
+/**
+ * The {@link ConfigDependencyHooks} service shape.
+ *
+ * @remarks
+ * `inject` is given the workspace root, the manifest's `configDependencies`
+ * (name → version+integrity), and the inline-catalog seed as a plain
+ * `catalog name → dependency name → range` record, and produces the catalogs the
+ * replayed hooks yield. The default (no-op) implementation returns the seed
+ * unchanged and loads nothing.
+ *
+ * @public
+ */
+interface ConfigDependencyHooksShape {
+  /**
+   * Replay each config dependency's `updateConfig` hook over `seed`, in
+   * declaration order, and return the resulting catalogs.
+   *
+   * @param root - The workspace root; config dependencies resolve under
+   *   `<root>/node_modules/.pnpm-config/<name>`.
+   * @param configDependencies - The `configDependencies` map (name →
+   *   version+integrity) declared in `pnpm-workspace.yaml`.
+   * @param seed - The inline catalogs, as `catalog name → dependency → range`.
+   */
+  readonly inject: (root: string, configDependencies: Readonly<Record<string, string>>, seed: Readonly<Record<string, Readonly<Record<string, string>>>>) => Effect.Effect<Readonly<Record<string, Readonly<Record<string, string>>>>, CatalogAssemblyError>;
+}
+declare const ConfigDependencyHooks_base: Context.ServiceClass<ConfigDependencyHooks, "@effected/workspaces/ConfigDependencyHooks", ConfigDependencyHooksShape>;
+/**
+ * Replays a workspace's `configDependencies` `updateConfig` hooks over the inline
+ * catalogs — the opt-in seam that lets hook-injected catalogs participate in
+ * assembly.
+ *
+ * @remarks
+ * A contract-only service: it declares the shape and ships two layers, never a
+ * baked-in default. {@link ConfigDependencyHooks.layerNoop} executes no
+ * config-dependency code (it returns the seed untouched) and is what the default
+ * {@link WorkspaceCatalogs} layer wires; {@link ConfigDependencyHooks.layerLive}
+ * dynamically imports each `pnpmfile.cjs` and replays it, and is wired only by the
+ * explicit `WorkspaceCatalogs.layerWithConfigDependencies` opt-in.
+ *
+ * @public
+ */
+declare class ConfigDependencyHooks extends ConfigDependencyHooks_base {
+  /**
+   * The no-op layer: `inject` returns the seed unchanged and never touches a
+   * config dependency. The default {@link WorkspaceCatalogs} layer wires this, so
+   * the default catalog path provably executes no config-dependency code.
+   */
+  static readonly layerNoop: Layer.Layer<ConfigDependencyHooks>;
+  /**
+   * The live layer: dynamically imports each config dependency's `pnpmfile.cjs`
+   * (in process, no subprocess) and replays its `updateConfig` hook over the
+   * seed, in declaration order. A dependency without a `pnpmfile.cjs` contributes
+   * nothing; a dependency whose file fails to load or replay fails typed with a
+   * `hooks`-source {@link CatalogAssemblyError}, never a silent skip.
+   *
+   * @remarks
+   * Node-coupled by design — the `node:fs` / `node:path` / `node:url` imports are
+   * the sanctioned Node-only overlay, matching the other seams here. Only ever
+   * wired by `WorkspaceCatalogs.layerWithConfigDependencies`.
+   */
+  static readonly layerLive: Layer.Layer<ConfigDependencyHooks>;
+}
+//#endregion
+//#region src/DependencyGraph.d.ts
+declare const CyclicDependencyError_base: Schema.Class<CyclicDependencyError, Schema.TaggedStruct<"CyclicDependencyError", {
+  /** The packages participating in the cycle. */
+  readonly cycle: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the workspace dependency graph cannot be topologically ordered
+ * because it contains a cycle.
+ *
+ * @remarks
+ * `cycle` lists every package still carrying unsatisfied dependencies when
+ * Kahn's algorithm stalls — the strongly-connected residue, sorted. It is the
+ * set to break, not necessarily a single ordered loop.
+ *
+ * @public
+ */
+declare class CyclicDependencyError extends CyclicDependencyError_base {
+  /** Renders the cycle members into a one-line message. */
+  get message(): string;
+}
+declare const DependencyGraph_base: Schema.Class<DependencyGraph, Schema.Struct<{
+  /** The workspace packages the graph is drawn over. */
+  readonly packages: Schema.$Array<typeof WorkspacePackage>;
+}>, {}>;
+/**
+ * The directed graph of dependencies **between workspace packages**. External
+ * npm dependencies are not nodes.
+ *
+ * @remarks
+ * A pure value over the discovered package list, with the edge indexes built
+ * lazily into `#private` fields the schema never encodes. Edges are drawn from
+ * `dependencies`, `devDependencies`, `peerDependencies` and
+ * `optionalDependencies`; a self-edge is dropped.
+ *
+ * Total accessors never fail; the four fallible operations are `Effect.fn`
+ * boundaries.
+ *
+ * @example
+ * ```ts
+ * import { DependencyGraph, WorkspaceDiscovery } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const discovery = yield* WorkspaceDiscovery;
+ *   const graph = DependencyGraph.make({ packages: yield* discovery.listPackages() });
+ *   return yield* graph.levels();
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class DependencyGraph extends DependencyGraph_base {
+  #private;
+  /** Every workspace package name, sorted. Total. */
+  get names(): ReadonlyArray<string>;
+  /** The adjacency map: name → the names it depends on. Total. */
+  get adjacency(): ReadonlyMap<string, ReadonlySet<string>>;
+  /**
+   * Whether the graph contains a cycle. Total.
+   *
+   * @remarks
+   * An explicit-stack DFS with an on-stack set — never recursive, so a long
+   * dependency chain cannot overflow.
+   */
+  get hasCycle(): boolean;
+  /** The workspace packages `name` depends on, sorted. */
+  readonly dependenciesOf: (name: string) => Effect.Effect<readonly string[], PackageNotFoundError, never>;
+  /** The workspace packages that depend on `name`, sorted. */
+  readonly dependentsOf: (name: string) => Effect.Effect<readonly string[], PackageNotFoundError, never>;
+  /**
+   * `name` plus every package that transitively depends on it — the blast
+   * radius of a change. Sorted; includes `name` itself.
+   */
+  readonly affectedBy: (names: readonly string[]) => Effect.Effect<readonly string[], never, never>;
+  /**
+   * Packages grouped into parallel build levels: level 0 depends on nothing in
+   * the workspace, level *n* depends only on levels below it.
+   *
+   * @remarks
+   * Kahn's algorithm over the reverse-edge index — linear, where v3's rescanned
+   * the whole adjacency map per processed node. Each level is sorted
+   * lexicographically, so the output is deterministic.
+   */
+  readonly levels: () => Effect.Effect<readonly (readonly string[])[], CyclicDependencyError, never>;
+  /** The flattened topological order — `levels()` concatenated. */
+  readonly sort: () => Effect.Effect<readonly string[], CyclicDependencyError, never>;
+  /**
+   * A topological order over `names` plus their transitive workspace
+   * dependencies — the build order for a subset.
+   */
+  readonly sortSubset: (names: readonly string[]) => Effect.Effect<readonly string[], CyclicDependencyError | PackageNotFoundError, never>;
+}
+//#endregion
+//#region src/PackageManagerName.d.ts
+/**
+ * The four package managers this package understands.
+ *
+ * @public
+ */
+declare const PackageManagerName: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+/**
+ * The decoded type of {@link (PackageManagerName:variable)}: `"npm" | "pnpm" | "yarn" | "bun"`.
+ *
+ * @public
+ */
+type PackageManagerName = typeof PackageManagerName.Type;
+declare const DetectedPackageManager_base: Schema.Class<DetectedPackageManager, Schema.Struct<{
+  /** The detected manager. */
+  readonly name: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+  /** Its version, when a manifest field agrees on the manager and carries one. */
+  readonly version: Schema.Option<Schema.String>;
+  /** The JavaScript runtime the manager implies. */
+  readonly runtime: Schema.Literals<readonly ["node", "bun"]>;
+}>, {}>;
+/**
+ * The outcome of package-manager detection at a workspace root.
+ *
+ * @remarks
+ * `version` is `Option.none()` unless a manifest field naming the *same* manager
+ * that was detected also carries a version — a `packageManager: "yarn@4"` in a
+ * pnpm workspace tells us nothing about pnpm's version, so it is not reported as
+ * one. The two fields consulted are the corepack top-level `packageManager` and
+ * `devEngines.packageManager`; see {@link PackageManagerDetector} for the
+ * precedence between them.
+ *
+ * @public
+ */
+declare class DetectedPackageManager extends DetectedPackageManager_base {}
+declare const PackageManagerDetectionError_base: Schema.Class<PackageManagerDetectionError, Schema.TaggedStruct<"PackageManagerDetectionError", {
+  /** The workspace root that was probed. */
+  readonly root: Schema.String;
+  /** The marker files probed, in the order they were probed. */
+  readonly checked: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a directory carries no lockfile and no workspace configuration,
+ * so no package manager can be attributed to it.
+ *
+ * @public
+ */
+declare class PackageManagerDetectionError extends PackageManagerDetectionError_base {
+  /** Renders the root and probed markers into a one-line message. */
+  get message(): string;
+}
+/**
+ * Every failure {@link PackageManagerDetector} can surface: no manager could be
+ * attributed to the root, or the root's `package.json` exists but cannot be read
+ * or parsed.
+ *
+ * @public
+ */
+type PackageManagerDetectionFailure = PackageManagerDetectionError | WorkspaceManifestError;
+declare const PackageManagerDetector_base: Context.ServiceClass<PackageManagerDetector, "@effected/workspaces/PackageManagerDetector", {
+  /** Detect the package manager at a workspace root. */
+  readonly detect: (root: string) => Effect.Effect<DetectedPackageManager, PackageManagerDetectionFailure>;
+}>;
+/**
+ * Detects which package manager owns a workspace root.
+ *
+ * @remarks
+ * **Lockfile evidence is the primary signal** — it is what says which manager
+ * actually ran. Priority, first match wins: a `pnpm-workspace.yaml` means pnpm;
+ * a bun lockfile *plus* a manifest field naming bun means bun; a `yarn.lock`
+ * *plus* a manifest field naming yarn means yarn; a root `package.json` with a
+ * `workspaces` field falls back to npm.
+ *
+ * The manifest conjunction is deliberate: a stray `yarn.lock` in an npm repo is
+ * common, and only a declared manager name disambiguates it.
+ *
+ * **Two manifest fields declare a manager, and they are not interchangeable.**
+ * Corepack reads both, and this is the rule that falls out of how it treats
+ * them:
+ *
+ * - `devEngines.packageManager.name` is authoritative for the **name**.
+ *   Corepack *errors* when a top-level `packageManager` disagrees with it (per
+ *   `devEngines.packageManager.onFail`), so where both are present and disagree,
+ *   `devEngines` is the one to believe. When `devEngines` names a manager, the
+ *   top-level field's name is not consulted as a disambiguator at all.
+ * - The top-level `packageManager` is authoritative for the exact **version**:
+ *   it is the field that carries the integrity hash. Where both name the same
+ *   manager, its version wins; where it is absent, `devEngines.packageManager.version`
+ *   supplies the version instead.
+ *
+ * A version is reported **only when the field it came from names the manager
+ * that was actually detected**. A `packageManager: "yarn@4"` in a pnpm workspace
+ * says nothing about pnpm's version, so no version is reported — and the same
+ * discipline applies to `devEngines`.
+ *
+ * Malformed manifest *hints* are ignored rather than fatal, matching corepack: a
+ * non-object or array `devEngines.packageManager`, a `name` containing `@`, or a
+ * version that is not an exact version cannot turn a detectable workspace into a
+ * detection failure. A manifest that exists but cannot be **read or parsed** is a
+ * different thing entirely and fails with a `WorkspaceManifestError` — a corrupt
+ * root manifest is a real problem, not a missing hint.
+ *
+ * @public
+ */
+declare class PackageManagerDetector extends PackageManagerDetector_base {
+  /** Builds the service over core `FileSystem` and `Path`. */
+  static readonly make: Effect.Effect<{
+    readonly detect: (root: string) => Effect.Effect<DetectedPackageManager, PackageManagerDetectionFailure>;
+  }, never, FileSystem.FileSystem | Path.Path>;
+  /** The live layer. */
+  static readonly layer: Layer.Layer<PackageManagerDetector, never, FileSystem.FileSystem | Path.Path>;
+}
+//#endregion
+//#region src/LockfileReader.d.ts
+declare const LockfileReadError_base: Schema.Class<LockfileReadError, Schema.TaggedStruct<"LockfileReadError", {
+  /** Absolute path to the lockfile that could not be read. */
+  readonly lockfilePath: Schema.String;
+  /** The format the detected package manager implies. */
+  readonly format: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
+  /** The originating failure. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when the workspace's lockfile cannot be read off disk.
+ *
+ * @remarks
+ * Parse failures are `@effected/lockfiles`' `LockfileParseError`, not this —
+ * this is strictly the IO half.
+ *
+ * @public
+ */
+declare class LockfileReadError extends LockfileReadError_base {
+  /** Renders the unreadable path into a one-line message. */
+  get message(): string;
+}
+/**
+ * Every failure the lockfile methods can surface — the exported init-error
+ * union the review named best-in-class DX.
+ *
+ * @remarks
+ * Layer construction does no IO, so every member surfaces from the *methods*
+ * rather than from `Layer.build`: the root cannot be found, no package manager
+ * can be attributed to it (or its manifest is corrupt), its lockfile cannot be
+ * read, the lockfile is malformed, or the lockfile's YAML stream carries no
+ * lockfile document.
+ *
+ * @public
+ */
+type LockfileReadFailure = WorkspaceRootNotFoundError | PackageManagerDetectionFailure | LockfileReadError | LockfileParseError | LockfileFramingError;
+/**
+ * The {@link LockfileReader} service shape.
+ *
+ * @public
+ */
+interface LockfileReaderShape {
+  /** The parsed lockfile, with pnpm importer paths already resolved to real names. */
+  readonly read: () => Effect.Effect<Lockfile, LockfileReadFailure>;
+  /**
+   * The lockfile's record of a package, when it records one.
+   *
+   * @remarks
+   * A name can resolve at **several versions** in one lockfile (two members
+   * depending on different majors of the same package). This returns the
+   * **first** entry in lockfile order and does not attempt to rank them — there
+   * is no single "the" version to return, and picking the highest semver would
+   * imply a resolution decision this reader is not entitled to make. Callers
+   * that must see every resolution should read `lockfile.packagesNamed(name)`
+   * off `read()` directly.
+   */
+  readonly resolvedVersion: (packageName: string) => Effect.Effect<Option.Option<ResolvedPackage>, LockfileReadFailure>;
+  /**
+   * Whether the lockfile agrees with the workspace manifests on disk — the
+   * pure `LockfileIntegrity.compare`, fed the manifests this package reads.
+   */
+  readonly integrity: () => Effect.Effect<LockfileIntegrity, LockfileReadFailure | WorkspaceDiscoveryFailure>;
+  /** Drop the memoized read so the next call re-reads the lockfile. */
+  readonly refresh: () => Effect.Effect<void>;
+}
+/**
+ * Options for the {@link LockfileReader} layer.
+ *
+ * @public
+ */
+interface LockfileReaderOptions {
+  /**
+   * The directory the workspace root is resolved from.
+   *
+   * @defaultValue `process.cwd()`, read lazily on first use.
+   */
+  readonly cwd?: string;
+}
+declare const LockfileReader_base: Context.ServiceClass<LockfileReader, "@effected/workspaces/LockfileReader", LockfileReaderShape>;
+/**
+ * Reads and parses the workspace's lockfile.
+ *
+ * @remarks
+ * Layer construction is O(1). The root walk, package-manager detection, file
+ * read, parse and pnpm name resolution all happen on the first method call and
+ * are memoized success-only for the lifetime of the layer.
+ *
+ * @example
+ * ```ts
+ * import { LockfileReader } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const reader = yield* LockfileReader;
+ *   const lockfile = yield* reader.read();
+ *   return lockfile.packages.length;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class LockfileReader extends LockfileReader_base {
+  /** Builds the service. */
+  static readonly make: (options?: LockfileReaderOptions) => Effect.Effect<LockfileReaderShape, never, WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
+  /**
+   * The live layer.
+   *
+   * @remarks
+   * Parameterized, so it mints a fresh reference per call — bind it to a
+   * `const` and reuse it.
+   */
+  static readonly layer: (options?: LockfileReaderOptions) => Layer.Layer<LockfileReader, never, WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
+}
+//#endregion
+//#region src/Publishability.d.ts
+declare const PublishTarget_base: Schema.Class<PublishTarget, Schema.Struct<{
+  /** The package name being published. */
+  readonly name: Schema.NonEmptyString;
+  /** The registry URL. */
+  readonly registry: Schema.NonEmptyString;
+  /** The directory to publish, relative to the package root; `"."` for the root itself. */
+  readonly directory: Schema.String;
+  /** Scoped-package visibility. */
+  readonly access: Schema.Literals<readonly ["public", "restricted"]>;
+  /** Whether to publish with a provenance attestation. */
+  readonly provenance: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.Boolean, never>>;
+}>, {}>;
+/**
+ * A resolved publish destination for a workspace package.
+ *
+ * @public
+ */
+declare class PublishTarget extends PublishTarget_base {}
+declare const PublishabilityDetector_base: Context.ServiceClass<PublishabilityDetector, "@effected/workspaces/PublishabilityDetector", {
+  /** The publish targets for a package; empty means it does not publish. */
+  readonly detect: (pkg: WorkspacePackage) => Effect.Effect<ReadonlyArray<PublishTarget>>;
+}>;
+/**
+ * Decides whether a workspace package publishes, and to where.
+ *
+ * @remarks
+ * The default layer implements standard npm semantics: a `private` package with
+ * no `publishConfig.access` publishes nowhere; an explicit
+ * `publishConfig.access` overrides `private`; anything else publishes to the
+ * public registry with defaults.
+ *
+ * Those are *npm's* semantics, not necessarily yours. Swap the layer:
+ *
+ * @example
+ * ```ts
+ * import { PublishabilityDetector, PublishTarget } from "@effected/workspaces";
+ * import { Effect, Layer } from "effect";
+ *
+ * const internalOnly = Layer.succeed(PublishabilityDetector, {
+ *   detect: (pkg) =>
+ *     Effect.succeed(
+ *       pkg.name.startsWith("@acme/")
+ *         ? [PublishTarget.make({
+ *             name: pkg.name,
+ *             registry: "https://npm.acme.internal/",
+ *             directory: ".",
+ *             access: "restricted",
+ *           })]
+ *         : [],
+ *     ),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class PublishabilityDetector extends PublishabilityDetector_base {
+  /** Standard npm publishing semantics. Pure — no filesystem, no platform services. */
+  static readonly layer: Layer.Layer<PublishabilityDetector>;
+}
+//#endregion
+//#region src/WorkspaceCatalogs.d.ts
+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>>;
+}>, {}>;
+/**
+ * An immutable, fully-normalized catalog collection — the one catalog
+ * resolution semantic in the package.
+ *
+ * @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.
+ *
+ * @public
+ */
+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 {@link 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;
+  /**
+   * 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>;
+}
+/**
+ * Every failure catalog assembly can surface.
+ *
+ * @public
+ */
+type CatalogAssemblyFailure = CatalogAssemblyError | WorkspaceRootNotFoundError;
+/**
+ * The {@link WorkspaceCatalogs} service shape.
+ *
+ * @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>;
+}
+/**
+ * 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;
+}
+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 {@link 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
+ */
+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 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 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; `DependencyResolutionError` is reserved for a
+   * failure of the resolution *mechanism* — an unfindable workspace root, an
+   * unreadable or malformed `pnpm-workspace.yaml`.
+   */
+  static readonly catalogResolver: Layer.Layer<CatalogResolver, never, WorkspaceCatalogs>;
+}
+//#endregion
+//#region src/WorkspaceStateSnapshot.d.ts
+declare const PackageStateSnapshot_base: Schema.Class<PackageStateSnapshot, Schema.Struct<{
+  /** The package name. */
+  readonly name: Schema.NonEmptyString;
+  /** The raw `version` string, as recorded at the captured moment. */
+  readonly version: Schema.String;
+  /** POSIX path relative to the workspace root; `"."` for the root package. */
+  readonly relativePath: Schema.String;
+  /** Production dependencies. */
+  readonly dependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** Development dependencies. */
+  readonly devDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** Peer dependencies. */
+  readonly peerDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  /** Optional dependencies. */
+  readonly optionalDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+}>, {}>;
+/**
+ * One workspace member as captured in a {@link WorkspaceStateSnapshot} — the
+ * serializable slice a snapshot diff reads: identity, version, location, and the
+ * four dependency records.
+ *
+ * @remarks
+ * Deliberately narrower than {@link WorkspacePackage}: a snapshot is a value to
+ * store and diff, not a located member to act on, so it carries no absolute
+ * paths, `publishConfig`, or `private` flag. The four records are keyed by the
+ * standard manifest field names, which are exactly `@effected/npm`'s
+ * `DependencyField` values.
+ *
+ * @public
+ */
+declare class PackageStateSnapshot extends PackageStateSnapshot_base {
+  /**
+   * Every dependency, merged across the four kinds.
+   *
+   * @remarks
+   * Precedence on a name declared in several kinds runs
+   * `dependencies` \> `devDependencies` \> `peerDependencies` \>
+   * `optionalDependencies`.
+   */
+  get allDependencies(): Record<string, string>;
+}
+declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot, Schema.Struct<{
+  /** Every workspace package captured at this moment. */
+  readonly packages: Schema.$Array<typeof PackageStateSnapshot>;
+  /** The catalog set assembled at this moment. */
+  readonly catalogs: typeof CatalogSet;
+}>, {}>;
+/**
+ * The state of a whole workspace at one moment — its packages and its assembled
+ * catalog set — as a serializable value.
+ *
+ * @remarks
+ * Produced by `WorkspaceSnapshots.at` (a git ref, read with no checkout)
+ * or `WorkspaceSnapshots.worktree` (the live tree). The lookup and
+ * resolution surfaces (`versions`, `package`, `resolve`, the resolver layers)
+ * are backed by `#private` indexes built lazily on first use and never encoded —
+ * the `DependencyGraph` edge-index precedent.
+ *
+ * `resolve` and the resolver layers answer specifiers against THIS snapshot's
+ * own captured state, so a consumer can ask "what did `catalog:` /
+ * `workspace:*` mean as of that ref". An unmatched specifier is always
+ * `Option.none()`, never an error.
+ *
+ * @example
+ * ```ts
+ * import { WorkspaceSnapshots } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const snapshots = yield* WorkspaceSnapshots;
+ *   const before = yield* snapshots.at("origin/main");
+ *   return before.resolve("effect", "catalog:");
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class WorkspaceStateSnapshot extends WorkspaceStateSnapshot_base {
+  #private;
+  /** Every captured package's name → version. Total; O(1) after the first call. */
+  get versions(): ReadonlyMap<string, string>;
+  /** A single captured package by name, or `Option.none()`. Total. */
+  package(name: string): Option.Option<PackageStateSnapshot>;
+  /**
+   * The concrete range or version a specifier resolved to AS OF this snapshot.
+   *
+   * @remarks
+   * The specifier is classified through `@effected/npm`'s
+   * `DependencySpecifier.FromString` — never by prefix-sniffing.
+   * A `workspace:` specifier resolves to the captured version of `dependency`; a
+   * `catalog:` specifier resolves against the captured catalog set. Every other
+   * form — a plain range, a dist-tag, a `file:`/git/url specifier, or an
+   * unparseable string — is `Option.none()`, because there is no indirection to
+   * resolve. Total.
+   *
+   * @param dependency - The dependency's package name (what `workspace:` /
+   *   `catalog:` resolve for).
+   * @param specifier - The raw specifier string.
+   */
+  resolve(dependency: string, specifier: string): Option.Option<string>;
+  /**
+   * A `CatalogResolver` layer implementing `@effected/npm`'s contract against
+   * THIS snapshot's catalog set — so code written to the contract resolves
+   * `catalog:` specifiers as of this ref. Built once per instance and cached, so
+   * it memoizes by reference.
+   */
+  get catalogResolver(): Layer.Layer<CatalogResolver>;
+  /**
+   * A `WorkspaceResolver` layer implementing `@effected/npm`'s contract against
+   * THIS snapshot's captured versions — so code written to the contract resolves
+   * `workspace:` specifiers as of this ref. Built once per instance and cached.
+   */
+  get workspaceResolver(): Layer.Layer<WorkspaceResolver>;
+  /** Both snapshot-scoped resolver layers merged. Built once per instance and cached. */
+  get resolvers(): Layer.Layer<CatalogResolver | WorkspaceResolver>;
+}
+//#endregion
+//#region src/WorkspaceSnapshots.d.ts
+/**
+ * Every failure `WorkspaceSnapshots.at` can surface: git's own typed
+ * errors, a catalog-assembly failure from the inline config source at the ref,
+ * or an unfindable workspace root.
+ *
+ * @remarks
+ * Narrow by design. `at` reads through git and never enumerates the live
+ * filesystem, so no `WorkspaceDiscoveryError` / `WorkspacePatternError` appears —
+ * and a malformed *lockfile* at the ref degrades to no catalogs (a lockfile is a
+ * record, not a source of truth), so only the inline source raises
+ * {@link CatalogAssemblyError}.
+ *
+ * @public
+ */
+type WorkspaceSnapshotAtFailure = GitCommandError | NotARepositoryError | UnknownRefError | CatalogAssemblyError | WorkspaceRootNotFoundError;
+/**
+ * Every failure `WorkspaceSnapshots.worktree` can surface: the discovery
+ * failures plus a catalog-assembly failure.
+ *
+ * @remarks
+ * `worktree` never invokes git — it reads the live tree over
+ * {@link WorkspaceDiscovery} and {@link WorkspaceCatalogs} — so no git error is
+ * reachable.
+ *
+ * @public
+ */
+type WorkspaceSnapshotWorktreeFailure = WorkspaceDiscoveryFailure | CatalogAssemblyError;
+/**
+ * Options for the {@link WorkspaceSnapshots} layer.
+ *
+ * @public
+ */
+interface WorkspaceSnapshotsOptions {
+  /**
+   * The directory `at(ref)` resolves the workspace root from.
+   *
+   * @defaultValue `process.cwd()`, read lazily on first use inside
+   *   `Effect.suspend`, so a `process.chdir` between providing the layer and the
+   *   first call is honoured.
+   */
+  readonly cwd?: string;
+}
+/**
+ * The {@link WorkspaceSnapshots} service shape.
+ *
+ * @public
+ */
+interface WorkspaceSnapshotsShape {
+  /** The workspace state at a git ref, read with no checkout. Cached per `(root, ref)`. */
+  readonly at: (ref: string) => Effect.Effect<WorkspaceStateSnapshot, WorkspaceSnapshotAtFailure>;
+  /** The live workspace state, over discovery and catalog assembly. Uncached. */
+  readonly worktree: () => Effect.Effect<WorkspaceStateSnapshot, WorkspaceSnapshotWorktreeFailure>;
+}
+declare const WorkspaceSnapshots_base: Context.ServiceClass<WorkspaceSnapshots, "@effected/workspaces/WorkspaceSnapshots", WorkspaceSnapshotsShape>;
+/**
+ * Reads workspace state at a git ref with no checkout, and the live worktree.
+ *
+ * @remarks
+ * `at(ref)` is cached per `(resolved root, ref)` via
+ * `Effect.cachedInvalidateWithTTL` at `Duration.infinity`, invalidated on any
+ * non-success exit — never bare `Effect.cached`, which would memoize an
+ * interrupt. A failed `at(ref)` init is therefore retried on the next call, not
+ * memoized.
+ *
+ * @example
+ * ```ts
+ * import { WorkspaceSnapshots } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const snapshots = yield* WorkspaceSnapshots;
+ *   const before = yield* snapshots.at("origin/main");
+ *   const after = yield* snapshots.worktree();
+ *   return { before: before.versions, after: after.versions };
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class WorkspaceSnapshots extends WorkspaceSnapshots_base {
+  /** Builds the service over `Git`, {@link WorkspaceRoot}, {@link WorkspaceDiscovery} and {@link WorkspaceCatalogs}. */
+  static readonly make: (options?: WorkspaceSnapshotsOptions) => Effect.Effect<WorkspaceSnapshotsShape, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs>;
+  /**
+   * The live layer.
+   *
+   * @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?: WorkspaceSnapshotsOptions) => Layer.Layer<WorkspaceSnapshots, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs>;
+}
+//#endregion
+//#region src/Workspaces.d.ts
+/**
+ * Options shared by the composite layers.
+ *
+ * @public
+ */
+interface WorkspacesOptions {
+  /**
+   * The directory every root-consuming service resolves the workspace root
+   * from — one explicit concern, applied uniformly.
+   *
+   * @defaultValue `process.cwd()`, read lazily on first use.
+   */
+  readonly cwd?: string;
+  /** Descent cap for segment-crossing `packages:` patterns. Defaults to 32. */
+  readonly maxDepth?: number;
+}
+/**
+ * Every service the git-free composite layer provides.
+ *
+ * @public
+ */
+type WorkspacesServices = WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | LockfileReader | WorkspaceCatalogs | PublishabilityDetector;
+/**
+ * The composite layers.
+ *
+ * @public
+ */
+declare const Workspaces: {
+  readonly layer: (options?: WorkspacesOptions) => Layer.Layer<WorkspacesServices, never, FileSystem.FileSystem | Path.Path>;
+  readonly layerWithConfigDependencies: (options?: WorkspacesOptions) => Layer.Layer<WorkspacesServices, never, FileSystem.FileSystem | Path.Path>;
+  readonly layerWithGit: (options?: WorkspacesOptions) => Layer.Layer<WorkspacesServices | ChangeDetector | WorkspaceSnapshots | Git, never, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  readonly resolvers: Layer.Layer<CatalogResolver | WorkspaceResolver, never, WorkspaceCatalogs | WorkspaceDiscovery>;
+};
+//#endregion
+//#region src/WorkspacesSync.d.ts
+/**
+ * The nearest workspace root at or above `cwd`, or `null`.
+ *
+ * @remarks
+ * **Synchronous and Node-only.** The Effect surface is `WorkspaceRoot`; reach
+ * for this one only where you genuinely cannot run an Effect — a Vitest config
+ * being the motivating case.
+ *
+ * Markers match the async service exactly: a `pnpm-workspace.yaml`, or a
+ * `package.json` carrying a `workspaces` field.
+ *
+ * @param cwd - Where to start the ascent. Defaults to `process.cwd()`.
+ *
+ * @example
+ * ```ts
+ * import { findWorkspaceRootSync } from "@effected/workspaces";
+ *
+ * const root = findWorkspaceRootSync();
+ * ```
+ *
+ * @public
+ */
+declare const findWorkspaceRootSync: (cwd?: string) => string | null;
+/**
+ * Options for {@link getWorkspacePackagesSync}.
+ *
+ * @public
+ */
+interface GetWorkspacePackagesSyncOptions {
+  /**
+   * Descent cap below a wildcard's enumeration prefix, mirroring
+   * `WorkspaceDiscovery.layer({ maxDepth })`.
+   *
+   * @defaultValue 32
+   */
+  readonly maxDepth?: number;
+}
+/**
+ * Every workspace package under `root`, root package first.
+ *
+ * @remarks
+ * **Synchronous and Node-only.** The Effect surface is `WorkspaceDiscovery`.
+ *
+ * Pattern semantics are not merely "shared" with the Effect enumerator — both
+ * drive the **same traversal state machine** (`internal/traverse.ts`), so the
+ * dequeue order, the depth rule, the visit budget and the prune list cannot
+ * drift apart. A `packages/**` finds exactly the same packages here as there,
+ * including at the depth boundary.
+ *
+ * The one deliberate difference is what happens at a bound: the Effect surface
+ * fails typed (`depthExceeded` / `budgetExceeded`), while this one is **total**
+ * and truncates. An unenumerable pattern or an unreadable manifest is skipped,
+ * not raised — a function with no error channel should not pretend to have one,
+ * and a Vitest config has nowhere to put a failure. Totality covers *data*, not
+ * caller mistakes: a `maxDepth` that is not a positive integer throws, matching
+ * the enumerator's defect.
+ *
+ * @param root - The workspace root, from {@link findWorkspaceRootSync}.
+ * @param options - Traversal bounds; see {@link GetWorkspacePackagesSyncOptions}.
+ *
+ * @example
+ * ```ts
+ * import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/workspaces";
+ *
+ * const root = findWorkspaceRootSync();
+ * const packages = root === null ? [] : getWorkspacePackagesSync(root);
+ * ```
+ *
+ * @public
+ */
+declare const getWorkspacePackagesSync: (root: string, options?: GetWorkspacePackagesSyncOptions) => ReadonlyArray<WorkspacePackage>;
+//#endregion
+export { CatalogAssemblyError, type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type GetWorkspacePackagesSyncOptions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PublishConfig, PublishTarget, PublishabilityDetector, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesOptions, type WorkspacesServices, findWorkspaceRootSync, getWorkspacePackagesSync };
+//# sourceMappingURL=index.d.ts.map