@smthrs/plan 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/Effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Effects.js","sourceRoot":"","sources":["../../src/Effects.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure effect declarations used to describe flow read and write envelopes.\n *\n * This is the ONE effect-envelope model. `@smthrs/flow` enforces it while it\n * builds a graph, `@smthrs/core` re-exports it, and `@smthrs/patterns` reads it\n * to intersect a decorator's declaration with the flow it wraps. It lives here\n * because `@smthrs/plan` is the lowest package all three depend on, beside the\n * `tier` and `onConflict` vocabularies a plan already speaks.\n *\n * Two layers: the declaration API, which a flow author and a catalog use, and\n * the prepared matching API below it, which a graph builder uses to check one\n * envelope against many steps without re-reading the envelope each time.\n *\n * Governing contract: `packages/smithers/flows/plan/docs/api.md`, published as\n * https://smithers.sh/docs/reference/api/plan.\n *\n * @since 0.0.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Schema from \"effect/Schema\"\nimport * as Index from \"./internal/effects.ts\"\n\n/**\n * How reversible the work beneath a declaration is.\n *\n * This is the ONE tier vocabulary. `KeyMaterial.kind` is this schema, and so\n * is `@smthrs/flow`'s `Action.Tier`: an action's durability and a declared\n * envelope's ceiling are the same three words, and a fourth spelling of them\n * in one of the three places would fork identity silently.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const Tier = Schema.Literals([\"sealed\", \"compensable\", \"irreversible\"])\n\n/**\n * The value form of {@link Tier}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Tier = typeof Tier.Type\n\n/**\n * How hermetic the work beneath a declaration is.\n *\n * This is the ONE mode vocabulary: the two words were written out in\n * `Declaration`, in `MakeOptions`, and twice more inside the matcher.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const Mode = Schema.Literals([\"hermetic\", \"expected\"])\n\n/**\n * The value form of {@link Mode}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Mode = typeof Mode.Type\n\n/**\n * What a plan does when two nodes write the same path.\n *\n * This is the ONE conflict vocabulary: `Declaration.onConflict` declares it and\n * `Plan.PairStrategy` is this same schema, resolved per pair by\n * `Plan.compile`.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const ConflictStrategy = Schema.Literals([\"serialize\", \"lane\", \"fail\"])\n\n/**\n * The value form of {@link ConflictStrategy}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type ConflictStrategy = typeof ConflictStrategy.Type\n\n/**\n * The annotation key a flow's declared effect ENVELOPE is carried under.\n *\n * One key, here, because two graph builders read it: `@smthrs/flow`'s\n * `Graph.build` enforces the envelope it names, and `@smthrs/core` re-exports\n * this key as `Annotations.Effects`. While they were separate keys a flow\n * annotated for one builder was invisible to the other.\n *\n * It is a `Context` key, not hashed material: annotating a flow with an\n * envelope changes what a build ADMITS, and the declaration reaches identity\n * only through `KeyMaterial.kind`.\n *\n * @category annotations\n * @since 1.0.0-rc.0\n */\nexport const Envelope = Context.Service<Declaration>(\"@smthrs/plan/Effects/Envelope\")\n\n/**\n * The prepared matching API: what a graph builder needs to check one envelope\n * against every step it encloses, and to find the write overlaps between two\n * declarations, at the cost the public functions above pay once rather than\n * once per step.\n *\n * {@link prepareEnvelope} reads an envelope once into the form\n * {@link narrowPrepared} answers from, which is what makes a wide envelope cost\n * its size per build rather than per node. {@link indexPaths},\n * {@link rankPaths} and {@link overlapRanks} are the same decomposition for\n * write overlap, which {@link overlaps} wraps for the pairwise case.\n * {@link boundedEffects} snapshots a declaration into builder-owned data,\n * refusing through the caller's own error before the copy grows past its limit,\n * and {@link maximumPathLength} and {@link maximumGlobs} are the per-path bounds\n * that refusal enforces.\n *\n * @category matching\n * @since 1.0.0-rc.0\n */\nexport type { PathIndex, PreparedEnvelope, Ranked } from \"./internal/effects.ts\"\n\n/**\n * The prepared matching API. See the type re-exports above for what each member\n * is for.\n *\n * @category matching\n * @since 1.0.0-rc.0\n */\nexport {\n  boundedEffects,\n  indexPaths,\n  maximumGlobs,\n  maximumPathLength,\n  narrowPrepared,\n  overlapRanks,\n  prepareEnvelope,\n  rankPaths\n} from \"./internal/effects.ts\"\n\n/**\n * A normalized description of the resources a flow or step may read and\n * write.\n *\n * @category models\n * @since 0.0.0\n * @slop\n */\nexport interface Declaration {\n  readonly reads: ReadonlyArray<string>\n  readonly writes: ReadonlyArray<string>\n  readonly mode: Mode\n  readonly onConflict: ConflictStrategy\n  readonly tier?: Tier | undefined\n}\n\n/**\n * Input accepted by {@link make}. Iterables are normalized into sorted,\n * duplicate-free arrays so declarations are deterministic key material.\n * Envelope entries and declared paths must already be path-normalized: no\n * separator or dot-segment rewriting is performed. A declared path containing\n * a whole `.` or `..` segment is never covered and therefore surfaces from\n * {@link narrow} as an `effect_outside_envelope` diagnostic.\n *\n * @category models\n * @since 0.0.0\n * @slop\n */\nexport interface MakeOptions {\n  readonly reads: Iterable<string>\n  readonly writes: Iterable<string>\n  readonly mode: Mode\n  readonly onConflict: ConflictStrategy\n  readonly tier?: Tier | undefined\n}\n\n/**\n * A result of checking that a step declaration narrows a flow envelope.\n *\n * @category models\n * @since 0.0.0\n * @slop\n */\nexport type NarrowResult =\n  | { readonly ok: true }\n  | {\n    readonly ok: false\n    readonly code: \"effect_outside_envelope\" | \"effect_mode_widening\" | \"effect_tier_widening\"\n    readonly paths: ReadonlyArray<string>\n  }\n\nconst normalize = (paths: Iterable<string>): ReadonlyArray<string> => [...new Set(paths)].sort()\n\n/**\n * Constructs a deterministic effect declaration.\n *\n * @category constructors\n * @since 0.0.0\n * @slop\n */\nexport const make = (input: MakeOptions): Declaration => ({\n  reads: normalize(input.reads),\n  writes: normalize(input.writes),\n  mode: input.mode,\n  onConflict: input.onConflict,\n  ...(input.tier === undefined ? {} : { tier: input.tier })\n})\n\n/**\n * Checks whether `path` is covered by an envelope entry.\n *\n * The grammar is exhaustive: an exact path matches itself; `*` and `**` match\n * everything; `prefix*` matches by string prefix; and `prefix/**` matches\n * `prefix/` and everything below it, but not bare `prefix`. This is\n * intentionally not full minimatch syntax. Envelope entries and declared paths\n * must be normalized. A path containing a whole `.` or `..` segment is never\n * covered, so {@link narrow} reports it as `effect_outside_envelope` rather\n * than silently accepting an escape.\n *\n * @category predicates\n * @since 0.0.0\n * @slop\n */\nexport const covers = (envelope: string, path: string): boolean => {\n  if (Index.hasDotSegment(path)) return false\n  return envelope === path || (Index.isGlob(envelope) && path.startsWith(Index.globPrefix(envelope)))\n}\n\n/**\n * Verifies that a step declaration stays within an enclosing flow envelope.\n *\n * Read and write paths must be covered independently. A step may tighten\n * `expected` to `hermetic`, but cannot widen `hermetic` to `expected`.\n * Effect tiers narrow from irreversible to compensable to sealed.\n *\n * The envelope's lists are prepared once: exact entries go into a set and\n * covering patterns collapse to their outermost prefixes, sorted, so each step\n * path costs one dot-segment scan, one lookup, and one binary search ending in\n * one prefix comparison, whatever the envelope's width or how many of its\n * patterns nest. A graph build prepares each envelope once for every node it\n * encloses.\n *\n * @category validation\n * @since 0.0.0\n * @slop\n */\nexport const narrow = (envelope: Declaration, step: Declaration): NarrowResult =>\n  Index.narrowPrepared(Index.prepareEnvelope(envelope), step)\n\n/**\n * Returns the concrete or narrower write declarations shared by two effect\n * declarations. The result is sorted and duplicate-free.\n *\n * Two declarations of the same literal path always overlap, including a path\n * {@link covers} refuses to match because it carries a `.` or `..` segment.\n * Glob coverage stays strict for those paths, so an unnormalized declaration\n * still escapes no envelope, but two writers naming the same unnormalized path\n * are still detected as writing the same resource.\n *\n * The union of both declarations is indexed once: the distinct paths are\n * sorted, each is scanned once for a dot segment, and each pattern's prefix\n * is located by binary search. Exact paths then match through a merge of two\n * rank lists and each covering pattern enumerates the other declaration's\n * ranks inside its interval, so the cost is linear in the two declarations\n * plus the matches, whatever the paths' lengths or how many patterns nest.\n *\n * @category analysis\n * @since 0.0.0\n * @slop\n */\nexport const overlaps = (a: Declaration, b: Declaration): ReadonlyArray<string> => {\n  const indexed = Index.indexPaths([a.writes, b.writes])\n  return Index.overlapRanks(indexed, Index.rankPaths(indexed, a.writes), Index.rankPaths(indexed, b.writes))\n    .map((rank) => indexed.paths[rank]!)\n}\n\n/**\n * Returns a sealed, hermetic copy of an effect declaration.\n *\n * @category constructors\n * @since 0.0.0\n * @slop\n */\nexport const sealed = (declaration: Declaration): Declaration =>\n  make({ ...declaration, mode: \"hermetic\", tier: \"sealed\" })\n"]}

package/dist/esm/FileSet.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Static filesystem declaration vocabulary shared by planning and execution.
+ *
+ * Declared paths use `/` as their canonical separator and normalize Unicode
+ * to NFC. Workspace-relative paths reject C0 controls (U+0000 through U+001F)
+ * and DEL (U+007F), which name nothing a supported filesystem can open. C1
+ * controls (U+0080 through U+009F) remain accepted because those bytes are
+ * legal in a POSIX file name.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * How strictly a declared file set is enforced at the boundary.
+ *
+ * `hard` rejects undeclared access. `expected` records access for validation
+ * after execution without requiring the sandbox to reject it immediately.
+ *
+ * This is the ONE spelling of the pair. `Plan.NodeEffects.boundaryMode` is this
+ * schema and so is `@smthrs/flow`'s `Action.BoundaryMode`; the literal used to
+ * be written out in all three places.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const BoundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
+/**
+ * The value form of {@link BoundaryMode}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type BoundaryMode = typeof BoundaryMode.Type;
+/**
+ * The canonical spelling of a declared path or pattern: every separator is
+ * `/`, and Unicode is normalized to NFC.
+ *
+ * {@link workspaceRelative} accepts a backslash as a separator, so
+ * `dist\same.js` and `dist/same.js` are two spellings of ONE workspace path.
+ * Every exact-path comparison in this module goes through this form, because
+ * comparing the raw spellings would let the separator alias defeat overlap
+ * detection exactly as `.` segments and empty segments would.
+ *
+ * @category accessors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const canonical: (path: string) => string;
+/**
+ * The {@link canonical} spelling with letter case folded away.
+ *
+ * A case-insensitive filesystem (default macOS APFS, Windows NTFS) opens
+ * `src/A.ts` and `src/a.ts` as one file, so static overlap compares this form:
+ * two declarations that differ only in case must serialize. Folding goes
+ * through upper case because that mapping is context-free, so it folds each
+ * character alone and commutes with splitting a path into segments.
+ *
+ * @category accessors
+ * @since 1.0.0-rc.0
+ */
+export declare const folded: (path: string) => string;
+/** Workspace-relative glob pattern.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const Pattern: Schema.NonEmptyString;
+/**
+ * Whether a declared path or pattern stays inside the workspace and names it
+ * one way only. Refuses absolute paths (POSIX and drive-letter), upward
+ * traversal, and the aliasing forms — `.` segments, empty segments — that
+ * would let two spellings of one file defeat exact-string overlap detection.
+ *
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export declare const workspaceRelative: (pattern: string) => boolean;
+/** Bazel-style file glob.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const Glob: Schema.TaggedStruct<"Glob", {
+    readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+    readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>;
+/** Bazel-style file glob.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Glob = typeof Glob.Type;
+/** A directory output captured and replayed as one tree artifact.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const TreeArtifact: Schema.TaggedStruct<"TreeArtifact", {
+    readonly path: Schema.NonEmptyString;
+}>;
+/** A directory output captured and replayed as one tree artifact.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type TreeArtifact = typeof TreeArtifact.Type;
+/** One leaf of a named filegroup.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const Entry: Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+    readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+    readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>, Schema.TaggedStruct<"TreeArtifact", {
+    readonly path: Schema.NonEmptyString;
+}>]>;
+/** One leaf of a named filegroup.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Entry = typeof Entry.Type;
+/** A declaration valid in a read set.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const ReadEntry: Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+    readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+    readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>]>;
+/** A declaration valid in a read set.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type ReadEntry = typeof ReadEntry.Type;
+/** A named reusable collection expanded before measurement.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const Filegroup: Schema.TaggedStruct<"Filegroup", {
+    readonly name: Schema.NonEmptyString;
+    readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+        readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+        readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>, Schema.TaggedStruct<"TreeArtifact", {
+        readonly path: Schema.NonEmptyString;
+    }>]>>;
+}>;
+/** A named reusable collection expanded before measurement.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Filegroup = typeof Filegroup.Type;
+/** A named read-only collection.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const ReadFilegroup: Schema.TaggedStruct<"Filegroup", {
+    readonly name: Schema.NonEmptyString;
+    readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+        readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+        readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>]>>;
+}>;
+/** A named read-only collection.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type ReadFilegroup = typeof ReadFilegroup.Type;
+/** Any declaration accepted by a plan effect set.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const Declaration: Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+    readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+    readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>, Schema.TaggedStruct<"TreeArtifact", {
+    readonly path: Schema.NonEmptyString;
+}>]>, Schema.TaggedStruct<"Filegroup", {
+    readonly name: Schema.NonEmptyString;
+    readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+        readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+        readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>, Schema.TaggedStruct<"TreeArtifact", {
+        readonly path: Schema.NonEmptyString;
+    }>]>>;
+}>]>;
+/** Any declaration accepted by a plan effect set.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Declaration = typeof Declaration.Type;
+/** Any declaration accepted by a plan read set.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const ReadDeclaration: Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+    readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+    readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>]>, Schema.TaggedStruct<"Filegroup", {
+    readonly name: Schema.NonEmptyString;
+    readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+        readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+        readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>]>>;
+}>]>;
+/** Any declaration accepted by a plan read set.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type ReadDeclaration = typeof ReadDeclaration.Type;
+/** Creates a named filegroup.
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const makeFilegroup: (name: string, entries: ReadonlyArray<Entry>) => Filegroup;
+/** Expands filegroups deterministically, preserving declaration order.
+ * @category accessors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const expand: (declarations: ReadonlyArray<Declaration>) => ReadonlyArray<Entry>;
+/** Expands read filegroups deterministically, preserving declaration order.
+ * @category accessors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const expandReads: (declarations: ReadonlyArray<ReadDeclaration>) => ReadonlyArray<ReadEntry>;
+/** Whether a value is a glob declaration.
+ * @category guards
+ * @since 0.1.0
+ * @slop
+ */
+export declare const isGlob: (value: unknown) => value is Glob;
+/** Whether a value is a tree artifact declaration.
+ * @category guards
+ * @since 0.1.0
+ * @slop
+ */
+export declare const isTreeArtifact: (value: unknown) => value is TreeArtifact;
+/** Tests one workspace-relative path against one Bazel-style pattern.
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export declare const matchesPattern: (pattern: string, path: string) => boolean;
+/** Tests one file path against a glob, including exclusions.
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export declare const matchesGlob: (glob: Glob, path: string) => boolean;
+/**
+ * Conservative static overlap. `true` may over-serialize; `false` proves that
+ * no path can belong to both declarations.
+ *
+ * A plain string is a literal path, even when it contains `*` or `**`, as it
+ * is at execution (sandbox admission, capture, removal, and replay); wildcard
+ * matching belongs to a Glob.
+ *
+ * Exact paths and tree roots compare in their
+ * {@link folded} form, so separator aliases, canonically equivalent Unicode
+ * spellings, and spellings that differ only in letter case overlap. A Glob
+ * against an exact path matches both its `include` and `exclude` patterns in
+ * folded form. {@link matchesGlob} itself stays case-sensitive and tests the path bytes it
+ * is handed; its property suite pins a backslash inside a path segment as
+ * literal text, so canonicalizing a measured path before matching is its
+ * caller's decision, not this module's.
+ *
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export declare const overlaps: (left: Entry, right: Entry) => boolean;
+//# sourceMappingURL=FileSet.d.ts.map

package/dist/esm/FileSet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSet.d.ts","sourceRoot":"","sources":["../../src/FileSet.ts"],"names":[],"mappings":"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"}

package/dist/esm/FileSet.js

@@ -0,0 +1,324 @@
+/**
+ * Static filesystem declaration vocabulary shared by planning and execution.
+ *
+ * Declared paths use `/` as their canonical separator and normalize Unicode
+ * to NFC. Workspace-relative paths reject C0 controls (U+0000 through U+001F)
+ * and DEL (U+007F), which name nothing a supported filesystem can open. C1
+ * controls (U+0080 through U+009F) remain accepted because those bytes are
+ * legal in a POSIX file name.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * How strictly a declared file set is enforced at the boundary.
+ *
+ * `hard` rejects undeclared access. `expected` records access for validation
+ * after execution without requiring the sandbox to reject it immediately.
+ *
+ * This is the ONE spelling of the pair. `Plan.NodeEffects.boundaryMode` is this
+ * schema and so is `@smthrs/flow`'s `Action.BoundaryMode`; the literal used to
+ * be written out in all three places.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const BoundaryMode = Schema.Literals(["hard", "expected"]);
+/**
+ * The canonical spelling of a declared path or pattern: every separator is
+ * `/`, and Unicode is normalized to NFC.
+ *
+ * {@link workspaceRelative} accepts a backslash as a separator, so
+ * `dist\same.js` and `dist/same.js` are two spellings of ONE workspace path.
+ * Every exact-path comparison in this module goes through this form, because
+ * comparing the raw spellings would let the separator alias defeat overlap
+ * detection exactly as `.` segments and empty segments would.
+ *
+ * @category accessors
+ * @since 0.1.0
+ * @slop
+ */
+export const canonical = (path) => path.replaceAll("\\", "/").normalize("NFC");
+/**
+ * The {@link canonical} spelling with letter case folded away.
+ *
+ * A case-insensitive filesystem (default macOS APFS, Windows NTFS) opens
+ * `src/A.ts` and `src/a.ts` as one file, so static overlap compares this form:
+ * two declarations that differ only in case must serialize. Folding goes
+ * through upper case because that mapping is context-free, so it folds each
+ * character alone and commutes with splitting a path into segments.
+ *
+ * @category accessors
+ * @since 1.0.0-rc.0
+ */
+export const folded = (path) => canonical(path).toUpperCase().normalize("NFC");
+/** Workspace-relative glob pattern.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Pattern = Schema.NonEmptyString.check(Schema.makeFilter((pattern) => workspaceRelative(pattern) || "file patterns must be workspace-relative and cannot traverse upward", { title: "workspaceRelativePattern" }));
+/**
+ * Whether a declared path or pattern stays inside the workspace and names it
+ * one way only. Refuses absolute paths (POSIX and drive-letter), upward
+ * traversal, and the aliasing forms — `.` segments, empty segments — that
+ * would let two spellings of one file defeat exact-string overlap detection.
+ *
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export const workspaceRelative = (pattern) => {
+    for (let index = 0; index < pattern.length; index++) {
+        const code = pattern.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return false;
+    }
+    if (pattern.startsWith("/"))
+        return false;
+    const segments = canonical(pattern).split("/");
+    // `C:foo` is drive-relative on Windows, so any drive-letter prefix escapes.
+    if (/^[A-Za-z]:/.test(segments[0]) || segments[0].endsWith(":"))
+        return false;
+    return segments.every((segment) => segment !== ".." && segment !== "." && segment !== "");
+};
+/** Bazel-style file glob.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Glob = Schema.TaggedStruct("Glob", {
+    include: Schema.NonEmptyArray(Pattern),
+    exclude: Schema.optional(Schema.Array(Pattern))
+});
+/** A directory output captured and replayed as one tree artifact.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const TreeArtifact = Schema.TaggedStruct("TreeArtifact", {
+    path: Pattern
+});
+/** One leaf of a named filegroup.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Entry = Schema.Union([Pattern, Glob, TreeArtifact]);
+/** A declaration valid in a read set.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const ReadEntry = Schema.Union([Pattern, Glob]);
+/** A named reusable collection expanded before measurement.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Filegroup = Schema.TaggedStruct("Filegroup", {
+    name: Schema.NonEmptyString,
+    entries: Schema.Array(Entry)
+});
+/** A named read-only collection.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const ReadFilegroup = Schema.TaggedStruct("Filegroup", {
+    name: Schema.NonEmptyString,
+    entries: Schema.Array(ReadEntry)
+});
+/** Any declaration accepted by a plan effect set.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Declaration = Schema.Union([Entry, Filegroup]);
+/** Any declaration accepted by a plan read set.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const ReadDeclaration = Schema.Union([ReadEntry, ReadFilegroup]);
+/** Creates a named filegroup.
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export const makeFilegroup = (name, entries) => ({
+    _tag: "Filegroup",
+    name,
+    entries
+});
+/** Expands filegroups deterministically, preserving declaration order.
+ * @category accessors
+ * @since 0.1.0
+ * @slop
+ */
+export const expand = (declarations) => declarations.flatMap((declaration) => typeof declaration !== "string" && declaration._tag === "Filegroup" ? declaration.entries : [declaration]);
+/** Expands read filegroups deterministically, preserving declaration order.
+ * @category accessors
+ * @since 0.1.0
+ * @slop
+ */
+export const expandReads = (declarations) => declarations.flatMap((declaration) => typeof declaration !== "string" && declaration._tag === "Filegroup" ? declaration.entries : [declaration]);
+/** Whether a value is a glob declaration.
+ * @category guards
+ * @since 0.1.0
+ * @slop
+ */
+export const isGlob = (value) => typeof value === "object" && value !== null && "_tag" in value && value._tag === "Glob";
+/** Whether a value is a tree artifact declaration.
+ * @category guards
+ * @since 0.1.0
+ * @slop
+ */
+export const isTreeArtifact = (value) => typeof value === "object" && value !== null && "_tag" in value && value._tag === "TreeArtifact";
+/** KMP searches a literal without rescanning a long near-matching prefix. */
+const literalSearch = (literal) => {
+    const fallback = new Uint32Array(literal.length);
+    let matched = 0;
+    for (let index = 1; index < literal.length; index++) {
+        while (matched > 0 && literal[index] !== literal[matched])
+            matched = fallback[matched - 1];
+        if (literal[index] === literal[matched])
+            matched++;
+        fallback[index] = matched;
+    }
+    return (path, start, end) => {
+        let matched = 0;
+        for (let index = start; index < end; index++) {
+            while (matched > 0 && path[index] !== literal[matched])
+                matched = fallback[matched - 1];
+            if (path[index] === literal[matched])
+                matched++;
+            if (matched === literal.length)
+                return index + 1;
+        }
+        return -1;
+    };
+};
+/** Anchored ends and disjoint literal searches make each segment match linear. */
+const segmentMatcher = (segment) => {
+    const chunks = segment.split(/\*+/);
+    const prefix = chunks.shift();
+    if (chunks.length === 0)
+        return (path) => path === prefix;
+    const suffix = chunks.pop();
+    const searches = chunks.map(literalSearch);
+    return (path) => {
+        const end = path.length - suffix.length;
+        if (prefix.length > end || !path.startsWith(prefix) || !path.endsWith(suffix))
+            return false;
+        let position = prefix.length;
+        for (const search of searches) {
+            position = search(path, position, end);
+            if (position === -1)
+                return false;
+        }
+        return true;
+    };
+};
+const patternMatchers = new Map();
+/** Compile once per canonical spelling; recursive segments use no backtracking. */
+const patternMatcher = (pattern) => {
+    const key = canonical(pattern);
+    const cached = patternMatchers.get(key);
+    if (cached !== undefined)
+        return cached;
+    const segments = key.split("/").map((segment) => segment === "**" ? undefined : segmentMatcher(segment));
+    const matcher = (path) => {
+        const parts = path.split("/");
+        // Suffix membership: next[j] says the remaining pattern matches parts[j..].
+        // Each pattern/path segment pair is visited once, even with repeated **.
+        let next = new Uint8Array(parts.length + 1);
+        next[parts.length] = 1;
+        for (let index = segments.length - 1; index >= 0; index--) {
+            const segment = segments[index];
+            const current = new Uint8Array(parts.length + 1);
+            for (let part = parts.length - 1; part >= 0; part--) {
+                current[part] = segment === undefined
+                    // A trailing ** accepts every remaining code unit. It still needs
+                    // the separator preceding it: src/** does not match bare src.
+                    ? Number(index === segments.length - 1 || next[part] === 1 ||
+                        (parts[part] !== "" && current[part + 1] === 1))
+                    : Number(next[part + 1] === 1 && segment(parts[part]));
+            }
+            next = current;
+        }
+        return next[0] === 1;
+    };
+    patternMatchers.set(key, matcher);
+    return matcher;
+};
+/** Tests one workspace-relative path against one Bazel-style pattern.
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export const matchesPattern = (pattern, path) => patternMatcher(pattern)(path);
+/** Tests one file path against a glob, including exclusions.
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export const matchesGlob = (glob, path) => glob.include.some((pattern) => matchesPattern(pattern, path)) &&
+    !(glob.exclude ?? []).some((pattern) => matchesPattern(pattern, path));
+const beneath = (tree, path) => {
+    const root = folded(tree);
+    const inside = folded(path);
+    return inside === root || inside.startsWith(`${root}/`);
+};
+/** {@link matchesGlob} over {@link folded} spellings of the glob and the path. */
+const matchesGlobFolded = (glob, path) => {
+    const inside = folded(path);
+    return glob.include.some((pattern) => matchesPattern(folded(pattern), inside)) &&
+        !(glob.exclude ?? []).some((pattern) => matchesPattern(folded(pattern), inside));
+};
+/**
+ * Conservative static overlap. `true` may over-serialize; `false` proves that
+ * no path can belong to both declarations.
+ *
+ * A plain string is a literal path, even when it contains `*` or `**`, as it
+ * is at execution (sandbox admission, capture, removal, and replay); wildcard
+ * matching belongs to a Glob.
+ *
+ * Exact paths and tree roots compare in their
+ * {@link folded} form, so separator aliases, canonically equivalent Unicode
+ * spellings, and spellings that differ only in letter case overlap. A Glob
+ * against an exact path matches both its `include` and `exclude` patterns in
+ * folded form. {@link matchesGlob} itself stays case-sensitive and tests the path bytes it
+ * is handed; its property suite pins a backslash inside a path segment as
+ * literal text, so canonicalizing a measured path before matching is its
+ * caller's decision, not this module's.
+ *
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export const overlaps = (left, right) => {
+    if (typeof left === "string" && typeof right === "string")
+        return folded(left) === folded(right);
+    if (typeof left === "string" && isGlob(right))
+        return matchesGlobFolded(right, left);
+    if (isGlob(left) && typeof right === "string")
+        return matchesGlobFolded(left, right);
+    if (isGlob(left) && isGlob(right))
+        return true;
+    if (isTreeArtifact(left) && typeof right === "string")
+        return beneath(left.path, right);
+    if (typeof left === "string" && isTreeArtifact(right))
+        return beneath(right.path, left);
+    if (isTreeArtifact(left) && isTreeArtifact(right)) {
+        return beneath(left.path, right.path) || beneath(right.path, left.path);
+    }
+    if (isTreeArtifact(left) && isGlob(right))
+        return true;
+    /* v8 ignore else -- the closed Entry union leaves only Glob/TreeArtifact here */
+    if (isGlob(left) && isTreeArtifact(right))
+        return overlaps(right, left);
+    /* v8 ignore next -- Entry's closed union makes every pair return above */
+    return true;
+};
+//# sourceMappingURL=FileSet.js.map