@savvy-web/silk 3.0.4 → 3.0.5

package/changesets-changelog.d.cts

@@ -1,4 +1,4 @@
-import { Brand, Context, Effect, Equal, FileSystem, Hash, HashMap, Layer, Option, Order, Path, Schema } from "effect";
+import { Brand, Context, Effect, Equal, FileSystem, Hash, HashMap, Layer, Option, Order, Path, Result, Schema } from "effect";
 import { ChildProcessSpawner } from "effect/unstable/process";
 //#region ../../node_modules/.pnpm/@types+unist@3.0.3/node_modules/@types/unist/index.d.ts
 // ## Interfaces
@@ -3650,7 +3650,7 @@ declare class Git extends Git_base {
   static readonly layer: Layer.Layer<Git, never, ChildProcessSpawner.ChildProcessSpawner>;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@effected+semver@0.1.1_effect@4.0.0-beta.99/node_modules/@effected/semver/index.d.ts
+//#region ../../node_modules/.pnpm/@effected+semver@0.2.0_effect@4.0.0-beta.99/node_modules/@effected/semver/index.d.ts
 //#region src/SemVer.d.ts
 declare const InvalidVersionError_base: Schema.Class<InvalidVersionError, Schema.TaggedStruct<"InvalidVersionError", {
   /** The raw input string that failed to parse. */
@@ -3719,11 +3719,45 @@ declare class SemVer extends SemVer_base {
    */
   static readonly FromString: Schema.Codec<SemVer, string>;
   /**
-   * Parse a strict SemVer 2.0.0 version string.
+   * Parse a strict SemVer 2.0.0 version string, synchronously, returning a
+   * `Result` instead of an `Effect`.
    *
    * Rejects `v`/`V` prefixes, `=` prefixes, leading zeros on numeric
    * identifiers and partially consumed input.
    *
+   * @remarks
+   * {@link SemVer.parse} is defined in terms of this function; the two never
+   * diverge. Reach for the `Effect` variant inside Effect code — it carries
+   * the `SemVer.parse` tracing span — and for this one at synchronous
+   * boundaries.
+   *
+   * @example
+   * ```ts
+   * import { SemVer } from "@effected/semver";
+   * import { Result } from "effect";
+   *
+   * const ok = SemVer.parseResult("1.2.3");
+   * if (Result.isSuccess(ok)) {
+   *   console.log(ok.success.major); // => 1
+   * }
+   *
+   * const bad = SemVer.parseResult("v1.2.3");
+   * if (Result.isFailure(bad)) {
+   *   console.log(bad.failure._tag); // => "InvalidVersionError"
+   * }
+   * ```
+   *
+   * @param input - the version string to parse
+   * @returns a `Result` succeeding with the parsed {@link SemVer}, or failing
+   * with {@link InvalidVersionError} when `input` is not a valid version
+   * string.
+   */
+  static parseResult(input: string): Result.Result<SemVer, InvalidVersionError>;
+  /**
+   * Parse a strict SemVer 2.0.0 version string. Defined in terms of
+   * {@link SemVer.parseResult} — synchronous callers can use that variant
+   * directly.
+   *
    * @param input - the version string to parse
    * @returns the parsed {@link SemVer}. Fails with {@link InvalidVersionError}
    * when `input` is not a valid version string.
@@ -3924,7 +3958,41 @@ declare class Comparator extends Comparator_base {
    * and {@link Comparator}.
    */
   static readonly FromString: Schema.Codec<Comparator, string>;
-  /** Parse a comparator string (e.g. `">=1.2.3"`). */
+  /**
+   * Parse a comparator string (e.g. `">=1.2.3"`), synchronously, returning a
+   * `Result` instead of an `Effect`.
+   *
+   * @remarks
+   * {@link Comparator.parse} is defined in terms of this function; the two
+   * never diverge. Reach for the `Effect` variant inside Effect code — it
+   * carries the `Comparator.parse` tracing span — and for this one at
+   * synchronous boundaries.
+   *
+   * @example
+   * ```ts
+   * import { Comparator } from "@effected/semver";
+   * import { Result } from "effect";
+   *
+   * const ok = Comparator.parseResult(">=1.2.3");
+   * if (Result.isSuccess(ok)) {
+   *   console.log(ok.success.operator); // => ">="
+   * }
+   * ```
+   *
+   * @param input - the comparator string to parse
+   * @returns a `Result` succeeding with the parsed {@link Comparator}, or
+   * failing with {@link InvalidComparatorError}.
+   */
+  static parseResult(input: string): Result.Result<Comparator, InvalidComparatorError>;
+  /**
+   * Parse a comparator string (e.g. `">=1.2.3"`). Defined in terms of
+   * {@link Comparator.parseResult} — synchronous callers can use that variant
+   * directly.
+   *
+   * @param input - the comparator string to parse
+   * @returns the parsed {@link Comparator}. Fails with
+   * {@link InvalidComparatorError}.
+   */
   static readonly parse: (input: string) => Effect.Effect<Comparator, InvalidComparatorError, never>;
   /** Test whether a version satisfies this comparator. */
   test(version: SemVer): boolean;
@@ -3986,7 +4054,40 @@ declare class Range extends Range_base {
    * prints `a b || c d`.
    */
   static readonly FromString: Schema.Codec<Range, string>;
-  /** Parse a range expression and normalize its comparator sets. */
+  /**
+   * Parse a range expression and normalize its comparator sets,
+   * synchronously, returning a `Result` instead of an `Effect`.
+   *
+   * @remarks
+   * {@link Range.parse} is defined in terms of this function; the two never
+   * diverge. Reach for the `Effect` variant inside Effect code — it carries
+   * the `Range.parse` tracing span — and for this one at synchronous
+   * boundaries.
+   *
+   * @example
+   * ```ts
+   * import { Range } from "@effected/semver";
+   * import { Result } from "effect";
+   *
+   * const ok = Range.parseResult("^1.0.0");
+   * if (Result.isSuccess(ok)) {
+   *   console.log(ok.success.toString()); // => ">=1.0.0 <2.0.0-0"
+   * }
+   * ```
+   *
+   * @param input - the range expression to parse
+   * @returns a `Result` succeeding with the parsed {@link Range}, or failing
+   * with {@link InvalidRangeError}.
+   */
+  static parseResult(input: string): Result.Result<Range, InvalidRangeError>;
+  /**
+   * Parse a range expression and normalize its comparator sets. Defined in
+   * terms of {@link Range.parseResult} — synchronous callers can use that
+   * variant directly.
+   *
+   * @param input - the range expression to parse
+   * @returns the parsed {@link Range}. Fails with {@link InvalidRangeError}.
+   */
   static readonly parse: (input: string) => Effect.Effect<Range, InvalidRangeError, never>;
   /**
    * Test whether a version satisfies a range; see {@link Range.test} for the
@@ -4019,11 +4120,44 @@ declare class Range extends Range_base {
     (that: Range): (self: Range) => Range;
     (self: Range, that: Range): Range;
   };
+  /**
+   * Intersect two ranges via a cross-product of their comparator sets,
+   * keeping only satisfiable combinations, synchronously, returning a
+   * `Result` instead of an `Effect`. Fails with
+   * {@link UnsatisfiableConstraintError} when no satisfiable set remains —
+   * an honest typed failure instead of an unsatisfiable range. Dual API.
+   *
+   * @remarks
+   * {@link Range.intersect} is defined in terms of this function; the two
+   * never diverge. Reach for the `Effect` variant inside Effect code — it
+   * carries the `Range.intersect` tracing span — and for this one at
+   * synchronous boundaries.
+   *
+   * @example
+   * ```ts
+   * import { Range } from "@effected/semver";
+   * import { Result } from "effect";
+   *
+   * const a = Result.getOrThrow(Range.parseResult("^1.0.0"));
+   * const b = Result.getOrThrow(Range.parseResult(">=1.5.0"));
+   * const merged = Range.intersectResult(a, b);
+   * if (Result.isSuccess(merged)) {
+   *   console.log(merged.success.toString()); // => ">=1.0.0 <2.0.0-0 >=1.5.0"
+   * }
+   * ```
+   */
+  static readonly intersectResult: {
+    (that: Range): (self: Range) => Result.Result<Range, UnsatisfiableConstraintError>;
+    (self: Range, that: Range): Result.Result<Range, UnsatisfiableConstraintError>;
+  };
   /**
    * Intersect two ranges via a cross-product of their comparator sets,
    * keeping only satisfiable combinations. Fails with
    * {@link UnsatisfiableConstraintError} when no satisfiable set remains —
    * an honest typed failure instead of an unsatisfiable range. Dual API.
+   *
+   * Defined in terms of {@link Range.intersectResult} — synchronous callers
+   * can use that variant directly.
    */
   static readonly intersect: {
     (that: Range): (self: Range) => Effect.Effect<Range, UnsatisfiableConstraintError>;
@@ -4091,7 +4225,7 @@ declare class UnsatisfiableConstraintError extends UnsatisfiableConstraintError_
   get message(): string;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@effected+npm@0.2.1_@effected+semver@0.1.1_effect@4.0.0-beta.99__effect@4.0.0-beta.99/node_modules/@effected/npm/index.d.ts
+//#region ../../node_modules/.pnpm/@effected+npm@0.2.3_@effected+semver@0.2.0_effect@4.0.0-beta.99__effect@4.0.0-beta.99/node_modules/@effected/npm/index.d.ts
 //#region src/CatalogAssemblyError.d.ts
 declare const CatalogAssemblyError_base: Schema.Class<CatalogAssemblyError, Schema.TaggedStruct<"CatalogAssemblyError", {
   /**
@@ -4363,7 +4497,7 @@ declare class InvalidIntegrityHashError extends InvalidIntegrityHashError_base {
  */
 type IntegrityHashBrand = string & Brand.Brand<"IntegrityHash">;
 //#endregion
-//#region ../../node_modules/.pnpm/@effected+glob@0.1.2_effect@4.0.0-beta.99/node_modules/@effected/glob/index.d.ts
+//#region ../../node_modules/.pnpm/@effected+glob@0.2.0_effect@4.0.0-beta.99/node_modules/@effected/glob/index.d.ts
 //#region src/GlobPattern.d.ts
 declare const GlobPatternError_base: Schema.Class<GlobPatternError, Schema.TaggedStruct<"GlobPatternError", {
   readonly pattern: Schema.String;
@@ -4436,15 +4570,40 @@ declare const GlobPattern_base: Schema.Class<GlobPattern, Schema.Struct<{
 declare class GlobPattern extends GlobPattern_base {
   #private;
   /**
-   * Compile a pattern under the given options — the package's fallible
-   * boundary. Guard trips (over-length, expansion budget, nesting depth)
-   * fail typed with {@link GlobPatternError}; invalid options never reach
-   * here (they throw at `GlobPatternOptions.make`, a wiring defect).
+   * Compile a pattern under the given options, synchronously — the package's
+   * fallible boundary in its primitive form. Compilation is pure
+   * string→predicate work with no IO, no services and no async step, so the
+   * sync form is the real primitive and {@link GlobPattern.compile} is
+   * derived from it.
+   *
+   * Total: never throws for pattern input. Guard trips (over-length,
+   * expansion budget, nesting depth) come back as a `Result` failure holding
+   * {@link GlobPatternError}; invalid *options* never reach here (they throw
+   * at `GlobPatternOptions.make`, a wiring defect).
    *
    * The pattern must also compile under DEFAULT options, whatever the
    * effective options are — permissive options (say `nobrace` over a brace
    * bomb) do not admit a defaults-rejected pattern; the same typed error
    * surfaces instead.
+   *
+   * @remarks
+   * For synchronous call sites that cannot host an Effect — a lint-staged
+   * handler, a config predicate — this removes the
+   * `Effect.runSync(Effect.result(...))` escape hatch: pair it with
+   * `Result.isSuccess` and read `.success` directly. Effect call sites should
+   * prefer {@link GlobPattern.compile}, which carries the tracing span.
+   */
+  static compileResult(source: string, options?: GlobPatternOptions): Result.Result<GlobPattern, GlobPatternError>;
+  /**
+   * Compile a pattern under the given options — the package's fallible
+   * boundary, and the form Effect call sites should reach for. Guard trips
+   * (over-length, expansion budget, nesting depth) fail typed with
+   * {@link GlobPatternError}; invalid options never reach here (they throw at
+   * `GlobPatternOptions.make`, a wiring defect).
+   *
+   * Defined in terms of {@link GlobPattern.compileResult} — synchronous
+   * callers can use that variant directly. Same semantics, same errors; this
+   * form adds only the `GlobPattern.compile` tracing span.
    */
   static readonly compile: (source: string, options?: GlobPatternOptions | undefined) => Effect.Effect<GlobPattern, GlobPatternError, never>;
   /**
@@ -4503,7 +4662,7 @@ declare class GlobPattern extends GlobPattern_base {
   static readonly FromString: Schema.Codec<GlobPattern, string>;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@effected+lockfiles@0.1.5_@effected+jsonc@0.4.0_effect@4.0.0-beta.99__@effected+npm@0.2_b1d671782d9bef489a2d22b7bd2ef126/node_modules/@effected/lockfiles/index.d.ts
+//#region ../../node_modules/.pnpm/@effected+lockfiles@0.1.8_@effected+jsonc@0.5.0_effect@4.0.0-beta.99__@effected+npm@0.2_d9e647ebf030778b1166690cbf4c6aa9/node_modules/@effected/lockfiles/index.d.ts
 //#region src/BunExtension.d.ts
 declare const BunExtension_base: Schema.Class<BunExtension, Schema.Struct<{
   readonly _tag: Schema.tag<"bun">;
@@ -4923,7 +5082,7 @@ declare class LockfileIntegrity extends LockfileIntegrity_base {
   static compare(lockfile: Lockfile, manifests: ReadonlyArray<WorkspaceManifest>): LockfileIntegrity;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@effected+package-json@0.3.1_effect@4.0.0-beta.99/node_modules/@effected/package-json/index.d.ts
+//#region ../../node_modules/.pnpm/@effected+package-json@0.4.1_effect@4.0.0-beta.99/node_modules/@effected/package-json/index.d.ts
 //#region src/Dependency.d.ts
 declare const Dependency_base: Schema.Class<Dependency, Schema.Struct<{
   /** The package name. */
@@ -5056,23 +5215,60 @@ declare const Person_base: Schema.Class<Person, Schema.Struct<{
   readonly email: Schema.optionalKey<Schema.String>;
   /** The optional homepage URL. */
   readonly url: Schema.optionalKey<Schema.String>;
+  /** Any additional keys, preserved verbatim and flattened back on encode. */
+  readonly rest: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
 }>, {}>;
 /**
- * A structured person object with `name` and optional `email` / `url`.
+ * A structured person object with `name`, optional `email` / `url`, and a
+ * `rest` catch-all preserving any additional keys across a read/write cycle.
  *
  * @public
  */
 declare class Person extends Person_base {
+  /**
+   * The object wire codec: an open JSON object ↔ a {@link Person}, partitioning
+   * unknown keys into `rest` and flattening them back on encode so the on-disk
+   * shape never carries a literal `rest` key.
+   */
+  static readonly schema: Schema.Codec<Person, {
+    readonly [k: string]: unknown;
+  }>;
   /**
    * Schema transformation between the `"Name <email> (url)"` shorthand string
-   * and a {@link Person}.
+   * and a {@link Person}. Decoding remembers the input text so that encoding
+   * reproduces it verbatim; see {@link Person.wireStringOf}.
    */
   static readonly FromString: Schema.Codec<Person, string>;
   /**
    * The `author` / `contributors` value: either the shorthand string or the
    * structured object, always decoded to a {@link Person}.
+   *
+   * The wire form is preserved across a round trip — a person read from the
+   * shorthand string encodes back to that string, byte for byte, and one read
+   * from an object encodes back to an object with its unknown keys intact.
+   * Formatting a manifest therefore never rewrites one legal encoding into the
+   * other.
+   *
+   * Provenance belongs to the instance, so a person that is *rebuilt* (rather
+   * than carried through unchanged) has none and encodes in the canonical
+   * object form. Editing an unrelated field of the surrounding `Package`
+   * carries the same person instance through and preserves its encoding.
    */
-  static readonly FromValue: Schema.Union<[typeof Person, Schema.Codec<Person, string>]>;
+  static readonly FromValue: Schema.Codec<Person, string | {
+    readonly [k: string]: unknown;
+  }>;
+  /**
+   * The shorthand text this person was decoded from, when it was decoded from
+   * the string form and still matches its fields; `None` for a person built
+   * from an object or by hand.
+   *
+   * Exposed so callers can tell which encoding a manifest used without
+   * re-reading the file.
+   *
+   * @param person - the person to inspect
+   * @returns the original shorthand text, or `None`
+   */
+  static wireStringOf(person: Person): Option.Option<string>;
 }
 declare const PackageDecodeError_base: Schema.Class<PackageDecodeError, Schema.TaggedStruct<"PackageDecodeError", {
   /** The underlying `SchemaError`, preserved structurally rather than stringified. */
@@ -5142,8 +5338,12 @@ declare const Package_base: Schema.Class<Package, Schema.Struct<{
   readonly type: Schema.optionalKey<Schema.Literals<readonly ["module", "commonjs"]>>;
   readonly main: Schema.optionalKey<Schema.String>;
   readonly license: Schema.optionalKey<Schema.brand<Schema.String, "SpdxLicense">>;
-  readonly author: Schema.optionalKey<Schema.Union<[typeof Person, Schema.Codec<Person, string, never, never>]>>;
-  readonly contributors: Schema.optionalKey<Schema.$Array<Schema.Union<[typeof Person, Schema.Codec<Person, string, never, never>]>>>;
+  readonly author: Schema.optionalKey<Schema.Codec<Person, string | {
+    readonly [k: string]: unknown;
+  }, never, never>>;
+  readonly contributors: Schema.optionalKey<Schema.$Array<Schema.Codec<Person, string | {
+    readonly [k: string]: unknown;
+  }, never, never>>>;
   readonly repository: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.$Record<Schema.String, Schema.Unknown>]>>;
   readonly dependencies: Schema.decodeTo<Schema.HashMap<Schema.String, Schema.String>, Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>, never, never>;
   readonly devDependencies: Schema.decodeTo<Schema.HashMap<Schema.String, Schema.String>, Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>, never, never>;
@@ -5330,7 +5530,7 @@ declare class Package extends Package_base {
   toJsonString(options?: PackageFormatOptions): string;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@effected+workspaces@0.4.1_@effected+jsonc@0.4.0_effect@4.0.0-beta.99__effect@4.0.0-beta.99/node_modules/@effected/workspaces/index.d.ts
+//#region ../../node_modules/.pnpm/@effected+workspaces@0.5.2_@effected+jsonc@0.5.0_effect@4.0.0-beta.99__effect@4.0.0-beta.99/node_modules/@effected/workspaces/index.d.ts
 //#region src/WorkspacePackage.d.ts
 declare const PublishConfig_base: Schema.Class<PublishConfig, Schema.Struct<{
   /** Scoped-package visibility. Its presence overrides `private`. */
@@ -5416,6 +5616,21 @@ declare const WorkspacePackage_base: Schema.Class<WorkspacePackage, Schema.Struc
   readonly packageJsonPath: Schema.NonEmptyString;
   /** POSIX path relative to the workspace root; `"."` for the root package. */
   readonly relativePath: Schema.String;
+  /**
+   * Absolute path to the workspace root this package was discovered under.
+   *
+   * @remarks
+   * Carried, not derived. Whoever built this value already knew the root —
+   * `WorkspaceDiscovery` resolved it before enumerating, and the sync entry
+   * point is handed it — so dropping it forced every consumer into per-package
+   * root arithmetic (counting `relativePath` segments and re-ascending that
+   * many `..`). That reconstruction is exact only while `path` and
+   * `relativePath` agree, and it re-derives something the kit never had to
+   * lose.
+   *
+   * For the root package this equals `path`, and `relativePath` is `"."`.
+   */
+  readonly workspaceRoot: Schema.NonEmptyString;
   /** Whether the package is marked private. */
   readonly private: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.Boolean, never>>;
   /** Production dependencies. */
@@ -5461,10 +5676,12 @@ declare const WorkspacePackage_base: Schema.Class<WorkspacePackage, Schema.Struc
  *   path: "/repo/packages/utils",
  *   packageJsonPath: "/repo/packages/utils/package.json",
  *   relativePath: "packages/utils",
+ *   workspaceRoot: "/repo",
  * });
  *
  * pkg.isRootWorkspace; // false
  * pkg.unscopedName;    // "utils"
+ * pkg.workspaceRoot;   // "/repo"
  * ```
  *
  * @public
@@ -5530,11 +5747,53 @@ declare class WorkspacePackage extends WorkspacePackage_base {
   /** Instance form of `WorkspacePackage.manifest`. */
   manifest(): Effect.Effect<Package, WorkspaceManifestError, FileSystem.FileSystem>;
 }
+/**
+ * Options for {@link WorkspaceRoot}'s `find`.
+ *
+ * @remarks
+ * Both bounds are passed straight through to `@effected/walker`'s
+ * `Walker.ascend`; this package does not re-decide either.
+ *
+ * @public
+ */
+interface FindWorkspaceRootOptions {
+  /**
+   * A ceiling directory. The ascent stops after probing it, so an unmarked
+   * `stopAt` fails typed as {@link WorkspaceRootNotFoundError} rather than
+   * silently escaping into an enclosing repository.
+   *
+   * @remarks
+   * Resolved to an absolute path before comparison, exactly as `cwd` is — a
+   * relative or non-normalized ceiling that never string-matched an ancestor
+   * would reintroduce the unbounded ascent it was passed to prevent.
+   */
+  readonly stopAt?: string;
+  /**
+   * Hard cap on the number of directories probed.
+   *
+   * @remarks
+   * A non-integer or non-positive value is a **defect**, not a typed failure —
+   * it is developer wiring, and walker's guard raises it.
+   *
+   * @defaultValue 256
+   */
+  readonly maxDepth?: number;
+}
 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>;
+  /**
+   * The resolved ceiling the ascent was bounded by, when one was supplied.
+   *
+   * @remarks
+   * Absent means the ascent ran to the filesystem root. Its presence is what
+   * lets a caller tell "there is no workspace root anywhere above me" from
+   * "there is none below the ceiling I set" — two failures that otherwise
+   * render identically.
+   */
+  readonly stopAt: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Raised when no workspace root can be found by ascending from a directory.
@@ -5546,18 +5805,32 @@ declare const WorkspaceRootNotFoundError_base: Schema.Class<WorkspaceRootNotFoun
  * @public
  */
 declare class WorkspaceRootNotFoundError extends WorkspaceRootNotFoundError_base {
-  /** Renders the search path and probed markers into a one-line message. */
+  /** Renders the search path, probed markers and any ceiling into a one-line message. */
   get message(): string;
 }
-declare const WorkspaceRoot_base: Context.ServiceClass<WorkspaceRoot, "@effected/workspaces/WorkspaceRoot", {
+/**
+ * The {@link WorkspaceRoot} service contract.
+ *
+ * @remarks
+ * Named so a consumer can type its own double — or a `Layer.succeed` — against
+ * the contract rather than re-deriving it, exactly as `WorkspaceDiscoveryShape`
+ * does. Prefer {@link WorkspaceRoot.layerTest} to hand-rolling one.
+ *
+ * @public
+ */
+interface WorkspaceRootShape {
   /**
    * The nearest workspace root at or above `cwd`.
    *
    * @param cwd - The directory to start the ascent from; resolved to an
    *   absolute path first.
+   * @param options - Optional ascent bounds. Unbounded by default, which
+   *   walks to the filesystem root and can therefore resolve to an enclosing
+   *   repository's root; pass `stopAt` when the caller knows the ceiling.
    */
-  readonly find: (cwd: string) => Effect.Effect<string, WorkspaceRootNotFoundError>;
-}>;
+  readonly find: (cwd: string, options?: FindWorkspaceRootOptions) => Effect.Effect<string, WorkspaceRootNotFoundError>;
+}
+declare const WorkspaceRoot_base: Context.ServiceClass<WorkspaceRoot, "@effected/workspaces/WorkspaceRoot", WorkspaceRootShape>;
 /**
  * Locates the workspace root by ascending from a starting directory.
  *
@@ -5572,15 +5845,86 @@ declare const WorkspaceRoot_base: Context.ServiceClass<WorkspaceRoot, "@effected
  * });
  * ```
  *
+ * @example
+ * Bounded: an unmarked fixture directory fails typed instead of escaping into
+ * the enclosing repository.
+ *
+ * ```ts
+ * import { WorkspaceRoot } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const roots = yield* WorkspaceRoot;
+ *   return yield* roots.find("/tmp/fixture/packages/a", { stopAt: "/tmp/fixture" });
+ * });
+ * ```
+ *
  * @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>;
+  static readonly make: Effect.Effect<WorkspaceRootShape, never, FileSystem.FileSystem | Path.Path>;
   /** The live layer. */
   static readonly layer: Layer.Layer<WorkspaceRoot, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * A test double resolving every `find` to `root`, with no filesystem.
+   *
+   * @remarks
+   * The nine-copies-of-a-four-line-mock case — a `Layer.succeed` over a `find`
+   * that ignores its arguments and succeeds with a fixed root is what consumers
+   * were writing by hand. The difference is that this double **honours
+   * `stopAt`**: a hand-rolled `find` that ignores the ceiling makes a bounded
+   * call pass under test and fail against the live service, which is the
+   * failure mode the option exists to catch. A `root` above the ceiling fails
+   * here exactly as it would live, with the same
+   * {@link WorkspaceRootNotFoundError}.
+   *
+   * The ceiling is `path.resolve`d through the injected `Path` service before
+   * the comparison, exactly as the live `make` path does — so a `stopAt`
+   * carrying `..` segments bounds the double identically to the live service,
+   * not by raw string. This is why `makeTest` yields an `Effect` requiring
+   * `Path`: it captures the service once at construction, the same shape as
+   * `make`. Consumers reach for {@link WorkspaceRoot.layerTest}, which provides
+   * `Path.layer` internally, so the requirement never surfaces at their call
+   * site.
+   *
+   * `maxDepth` is deliberately NOT modelled: the double does not walk, so it has
+   * no depth to cap, and pretending otherwise would encode a fiction. A suite
+   * exercising the depth guard wants the live service over a fixture tree.
+   *
+   * @param root - The root every unbounded `find` resolves to.
+   */
+  static readonly makeTest: (root: string) => Effect.Effect<WorkspaceRootShape, never, Path.Path>;
+  /**
+   * The test layer: {@link WorkspaceRoot.makeTest} with `Path.layer` provided.
+   *
+   * @remarks
+   * `makeTest` requires `Path` to normalize the `stopAt` ceiling; this layer
+   * supplies core's `Path.layer` internally, so the requirement never reaches a
+   * consumer — the published type stays `Layer.Layer<WorkspaceRoot>`.
+   *
+   * 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.
+   *
+   * Pair it with `WorkspaceDiscovery.layerTest` to stand up the whole discovery
+   * path without a filesystem; between them there is nothing left for a
+   * module-level mock of `@effected/workspaces` to do, and a provided layer
+   * keeps the service graph — and its typed errors — intact.
+   *
+   * @example
+   * ```ts
+   * import { WorkspaceDiscovery, WorkspaceRoot } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestRoot = WorkspaceRoot.layerTest("/repo");
+   * const TestDiscovery = WorkspaceDiscovery.layerTest({
+   *   listPackages: () => Effect.succeed([]),
+   * });
+   * // program.pipe(Effect.provide(TestRoot), Effect.provide(TestDiscovery))
+   * ```
+   */
+  static readonly layerTest: (root: string) => Layer.Layer<WorkspaceRoot>;
 }
 //#endregion
 //#region src/WorkspaceDiscovery.d.ts
@@ -5796,6 +6140,7 @@ declare class WorkspaceDiscovery extends WorkspaceDiscovery_base {
    *         path: "/repo/packages/utils",
    *         packageJsonPath: "/repo/packages/utils/package.json",
    *         relativePath: "packages/utils",
+   *         workspaceRoot: "/repo",
    *       }),
    *     ]),
    * });
@@ -5906,9 +6251,13 @@ declare class ConfigDependencyHooks extends ConfigDependencyHooks_base {
    * `hooks`-source `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`.
+   * Runtime-coupled by design, not node-exclusive. The `import()` below loads
+   * **and executes** a config dependency's pnpmfile in-process — code execution,
+   * not IO, so no `FileSystem` / `Path` service abstracts it. The `node:path` and
+   * `node:url` imports (`join`, `pathToFileURL`) exist only to build the URL that
+   * `import()` consumes; node and bun both implement those builtins and dynamic
+   * import, so this layer runs on either runtime. Only ever wired by
+   * `WorkspaceCatalogs.layerWithConfigDependencies`.
    */
   static readonly layerLive: Layer.Layer<ConfigDependencyHooks>;
 }
@@ -6669,7 +7018,7 @@ interface WorkspacesOptions {
   readonly maxDepth?: number;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@effected+walker@0.2.2_@effected+glob@0.1.2_effect@4.0.0-beta.99__effect@4.0.0-beta.99/node_modules/@effected/walker/index.d.ts
+//#region ../../node_modules/.pnpm/@effected+walker@0.3.1_@effected+glob@0.2.0_effect@4.0.0-beta.99__effect@4.0.0-beta.99/node_modules/@effected/walker/index.d.ts
 declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<"DescendError", {
   /** The glob pattern's source text. */
   readonly pattern: Schema.String;
@@ -6690,6 +7039,39 @@ declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<
 declare class DescendError extends DescendError_base {
   get message(): string;
 }
+declare const GlobExpansionError_base: Schema.Class<GlobExpansionError, Schema.TaggedStruct<"GlobExpansionError", {
+  /** The glob pattern's source text, as handed to {@link compileAndExpand}. */
+  readonly pattern: Schema.String;
+  /** The underlying typed failure, intact: a compile guard trip or a descent failure. */
+  readonly cause: Schema.Union<readonly [typeof GlobPatternError, typeof DescendError]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Typed failure raised by {@link compileAndExpand}: the single error the
+ * compile+expand recipe fails with, so a caller catches one tag rather than
+ * folding two error channels by hand.
+ *
+ * @remarks
+ * One tag, two genuinely different causes — "your pattern is malformed" and
+ * "that directory is unreadable" are different problems with different fixes,
+ * so `cause` keeps the underlying typed error intact
+ * rather than flattening it into a string. Discriminate on `cause._tag`
+ * (`"GlobPatternError"` vs `"DescendError"`), or read
+ * {@link GlobExpansionError.stage} when only the phase matters; either way the
+ * original payload — a guard's `limit`/`actual`, a descent's `path` — is still
+ * there. `cause` is also the native `Error` cause, so error chaining and
+ * stack-printing work without extra wiring.
+ *
+ * @public
+ */
+declare class GlobExpansionError extends GlobExpansionError_base {
+  /**
+   * Which phase failed — `"compile"` when the pattern itself was rejected,
+   * `"descend"` when the filesystem walk failed. A convenience over
+   * `cause._tag` for callers that only need the phase.
+   */
+  get stage(): "compile" | "descend";
+  get message(): string;
+}
 //#endregion
 //#region ../silk-effects/dist/dev/pkg/index.d.ts
 //#endregion
@@ -11560,7 +11942,7 @@ declare class VersionFiles {
    * @param cwd - Project root directory
    * @returns Effect of `[filePath, config]` tuples
    */
-  static resolveGlobs(configs: readonly LegacyVersionFileConfig[], cwd: string): Effect.Effect<Array<[string, LegacyVersionFileConfig]>, DescendError, FileSystem.FileSystem>;
+  static resolveGlobs(configs: readonly LegacyVersionFileConfig[], cwd: string): Effect.Effect<Array<[string, LegacyVersionFileConfig]>, GlobExpansionError, FileSystem.FileSystem>;
   /**
    * Detect indentation from file content.
    *
@@ -11662,7 +12044,7 @@ declare class VersionFiles {
     name: string;
     version: string;
     path: string;
-  }>): Effect.Effect<VersionFileUpdate[], DescendError, FileSystem.FileSystem>;
+  }>): Effect.Effect<VersionFileUpdate[], GlobExpansionError, FileSystem.FileSystem>;
   /**
    * Apply version-file updates from the resolved (post-`ConfigInspector`)
    * representation. Each {@link ResolvedPackageScope} already names the