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

package/dist/esm/Effects.js

@@ -0,0 +1,178 @@
+/**
+ * Pure effect declarations used to describe flow read and write envelopes.
+ *
+ * This is the ONE effect-envelope model. `@smthrs/flow` enforces it while it
+ * builds a graph, `@smthrs/core` re-exports it, and `@smthrs/patterns` reads it
+ * to intersect a decorator's declaration with the flow it wraps. It lives here
+ * because `@smthrs/plan` is the lowest package all three depend on, beside the
+ * `tier` and `onConflict` vocabularies a plan already speaks.
+ *
+ * Two layers: the declaration API, which a flow author and a catalog use, and
+ * the prepared matching API below it, which a graph builder uses to check one
+ * envelope against many steps without re-reading the envelope each time.
+ *
+ * Governing contract: `packages/smithers/flows/plan/docs/api.md`, published as
+ * https://smithers.sh/docs/reference/api/plan.
+ *
+ * @since 0.0.0
+ */
+import * as Context from "effect/Context";
+import * as Schema from "effect/Schema";
+import * as Index from "./internal/effects.js";
+/**
+ * How reversible the work beneath a declaration is.
+ *
+ * This is the ONE tier vocabulary. `KeyMaterial.kind` is this schema, and so
+ * is `@smthrs/flow`'s `Action.Tier`: an action's durability and a declared
+ * envelope's ceiling are the same three words, and a fourth spelling of them
+ * in one of the three places would fork identity silently.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Tier = Schema.Literals(["sealed", "compensable", "irreversible"]);
+/**
+ * How hermetic the work beneath a declaration is.
+ *
+ * This is the ONE mode vocabulary: the two words were written out in
+ * `Declaration`, in `MakeOptions`, and twice more inside the matcher.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Mode = Schema.Literals(["hermetic", "expected"]);
+/**
+ * What a plan does when two nodes write the same path.
+ *
+ * This is the ONE conflict vocabulary: `Declaration.onConflict` declares it and
+ * `Plan.PairStrategy` is this same schema, resolved per pair by
+ * `Plan.compile`.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const ConflictStrategy = Schema.Literals(["serialize", "lane", "fail"]);
+/**
+ * The annotation key a flow's declared effect ENVELOPE is carried under.
+ *
+ * One key, here, because two graph builders read it: `@smthrs/flow`'s
+ * `Graph.build` enforces the envelope it names, and `@smthrs/core` re-exports
+ * this key as `Annotations.Effects`. While they were separate keys a flow
+ * annotated for one builder was invisible to the other.
+ *
+ * It is a `Context` key, not hashed material: annotating a flow with an
+ * envelope changes what a build ADMITS, and the declaration reaches identity
+ * only through `KeyMaterial.kind`.
+ *
+ * @category annotations
+ * @since 1.0.0-rc.0
+ */
+export const Envelope = Context.Service("@smthrs/plan/Effects/Envelope");
+/**
+ * The prepared matching API. See the type re-exports above for what each member
+ * is for.
+ *
+ * @category matching
+ * @since 1.0.0-rc.0
+ */
+export { boundedEffects, indexPaths, maximumGlobs, maximumPathLength, narrowPrepared, overlapRanks, prepareEnvelope, rankPaths } from "./internal/effects.js";
+const normalize = (paths) => [...new Set(paths)].sort();
+/**
+ * Constructs a deterministic effect declaration: `reads` and `writes` are
+ * collected, deduplicated, and sorted; an absent `tier` is omitted. Paths are
+ * not validated or rewritten.
+ *
+ * @param input - The paths, mode, conflict strategy, and optional tier.
+ * @returns The normalized declaration.
+ * @category constructors
+ * @since 0.0.0
+ */
+export const make = (input) => ({
+    reads: normalize(input.reads),
+    writes: normalize(input.writes),
+    mode: input.mode,
+    onConflict: input.onConflict,
+    ...(input.tier === undefined ? {} : { tier: input.tier })
+});
+/**
+ * Checks whether `path` is covered by an envelope entry.
+ *
+ * The grammar is exhaustive: an exact path matches itself; `*` and `**` match
+ * everything; `prefix*` matches by string prefix; and `prefix/**` matches
+ * `prefix/` and everything below it, but not bare `prefix`. This is
+ * intentionally not full minimatch syntax. Envelope entries and declared paths
+ * must be normalized. A path containing a whole `.` or `..` segment is never
+ * covered, so {@link narrow} reports it as `effect_outside_envelope` rather
+ * than silently accepting an escape.
+ *
+ * @param envelope - One envelope entry.
+ * @param path - One declared path.
+ * @returns `true` when the entry covers the path.
+ * @category predicates
+ * @since 0.0.0
+ */
+export const covers = (envelope, path) => {
+    if (Index.hasDotSegment(path))
+        return false;
+    return envelope === path || (Index.isGlob(envelope) && path.startsWith(Index.globPrefix(envelope)));
+};
+/**
+ * Verifies that a step declaration stays within an enclosing flow envelope.
+ *
+ * Read and write paths must be covered independently. A step may tighten
+ * `expected` to `hermetic`, but cannot widen `hermetic` to `expected`.
+ * Effect tiers narrow from irreversible to compensable to sealed.
+ *
+ * The envelope's lists are prepared once: exact entries go into a set and
+ * covering patterns collapse to their outermost prefixes, sorted, so each step
+ * path costs one dot-segment scan, one lookup, and one binary search ending in
+ * one prefix comparison, whatever the envelope's width or how many of its
+ * patterns nest. A graph build prepares each envelope once for every node it
+ * encloses.
+ *
+ * @param envelope - The flow's declaration.
+ * @param step - The step's declaration.
+ * @returns `{ ok: true }`, or the first rule the step breaks.
+ * @category validation
+ * @since 0.0.0
+ */
+export const narrow = (envelope, step) => Index.narrowPrepared(Index.prepareEnvelope(envelope), step);
+/**
+ * Returns the concrete or narrower write declarations shared by two effect
+ * declarations. The result is sorted and duplicate-free.
+ *
+ * Two declarations of the same literal path always overlap, including a path
+ * {@link covers} refuses to match because it carries a `.` or `..` segment.
+ * Glob coverage stays strict for those paths, so an unnormalized declaration
+ * still escapes no envelope, but two writers naming the same unnormalized path
+ * are still detected as writing the same resource.
+ *
+ * The union of both declarations is indexed once: the distinct paths are
+ * sorted, each is scanned once for a dot segment, and each pattern's prefix
+ * is located by binary search. Exact paths then match through a merge of two
+ * rank lists and each covering pattern enumerates the other declaration's
+ * ranks inside its interval, so the cost is linear in the two declarations
+ * plus the matches, whatever the paths' lengths or how many patterns nest.
+ *
+ * @param a - One declaration.
+ * @param b - The other declaration.
+ * @returns The shared write paths; empty when the writes are disjoint.
+ * @category analysis
+ * @since 0.0.0
+ */
+export const overlaps = (a, b) => {
+    const indexed = Index.indexPaths([a.writes, b.writes]);
+    return Index.overlapRanks(indexed, Index.rankPaths(indexed, a.writes), Index.rankPaths(indexed, b.writes))
+        .map((rank) => indexed.paths[rank]);
+};
+/**
+ * Returns a sealed, hermetic copy of an effect declaration, normalized by
+ * {@link make}. Paths and `onConflict` are kept.
+ *
+ * @param declaration - The declaration to copy.
+ * @returns The copy with `mode: "hermetic"` and `tier: "sealed"`.
+ * @category constructors
+ * @since 0.0.0
+ */
+export const sealed = (declaration) => make({ ...declaration, mode: "hermetic", tier: "sealed" });
+//# sourceMappingURL=Effects.js.map

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. Build one with {@link make}.\n *\n * @category models\n * @since 0.0.0\n */\nexport interface Declaration {\n  /** Readable paths or envelope patterns, sorted and duplicate-free. */\n  readonly reads: ReadonlyArray<string>\n  /** Writable paths or envelope patterns, sorted and duplicate-free. */\n  readonly writes: ReadonlyArray<string>\n  /** `hermetic` or `expected` enforcement. */\n  readonly mode: Mode\n  /** What a plan does when another node writes an overlapping path. */\n  readonly onConflict: ConflictStrategy\n  /** The effect tier. Absent means `sealed`. */\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 */\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 * On failure, `code` names the first rule broken, checked in this order:\n * `effect_outside_envelope` (with the uncovered read and write paths, sorted),\n * `effect_mode_widening`, then `effect_tier_widening` (both with empty\n * `paths`).\n *\n * @category models\n * @since 0.0.0\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: `reads` and `writes` are\n * collected, deduplicated, and sorted; an absent `tier` is omitted. Paths are\n * not validated or rewritten.\n *\n * @param input - The paths, mode, conflict strategy, and optional tier.\n * @returns The normalized declaration.\n * @category constructors\n * @since 0.0.0\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 * @param envelope - One envelope entry.\n * @param path - One declared path.\n * @returns `true` when the entry covers the path.\n * @category predicates\n * @since 0.0.0\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 * @param envelope - The flow's declaration.\n * @param step - The step's declaration.\n * @returns `{ ok: true }`, or the first rule the step breaks.\n * @category validation\n * @since 0.0.0\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 * @param a - One declaration.\n * @param b - The other declaration.\n * @returns The shared write paths; empty when the writes are disjoint.\n * @category analysis\n * @since 0.0.0\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, normalized by\n * {@link make}. Paths and `onConflict` are kept.\n *\n * @param declaration - The declaration to copy.\n * @returns The copy with `mode: \"hermetic\"` and `tier: \"sealed\"`.\n * @category constructors\n * @since 0.0.0\n */\nexport const sealed = (declaration: Declaration): Declaration =>\n  make({ ...declaration, mode: \"hermetic\", tier: \"sealed\" })\n"]}

package/dist/esm/FileSet.d.ts

@@ -0,0 +1,366 @@
+/**
+ * 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
+ */
+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;
+/**
+ * A non-empty workspace-relative path or pattern.
+ *
+ * Decoding fails with a `SchemaError` when {@link workspaceRelative} refuses
+ * the string. A bare `Pattern` in a declaration names one literal path; only a
+ * {@link Glob} gives `*` and `**` wildcard meaning.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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.
+ *
+ * C0 controls and DEL are refused as well.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export declare const workspaceRelative: (pattern: string) => boolean;
+/**
+ * A Bazel-style file glob: the paths matching any `include` pattern and no
+ * `exclude` pattern.
+ *
+ * In a pattern, `*` matches within one path segment and a `**` segment
+ * matches zero or more whole segments. A trailing `**` needs its separator,
+ * so `src/**` does not match `src` itself.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Glob: Schema.TaggedStruct<"Glob", {
+    readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+    readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>;
+/**
+ * The value form of {@link Glob}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Glob = typeof Glob.Type;
+/**
+ * A directory output captured and replayed as one tree artifact.
+ *
+ * It covers `path` and every path beneath it, compared in {@link folded}
+ * form.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const TreeArtifact: Schema.TaggedStruct<"TreeArtifact", {
+    readonly path: Schema.NonEmptyString;
+}>;
+/**
+ * The value form of {@link TreeArtifact}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type TreeArtifact = typeof TreeArtifact.Type;
+/**
+ * One leaf declaration: a literal path, a {@link Glob}, or a
+ * {@link TreeArtifact}. Write sets and filegroups hold entries.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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;
+}>]>;
+/**
+ * The value form of {@link Entry}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Entry = typeof Entry.Type;
+/**
+ * One leaf declaration valid in a read set: a literal path or a {@link Glob}.
+ * A read set cannot name a {@link TreeArtifact}, which is an output form.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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>>;
+}>]>;
+/**
+ * The value form of {@link ReadEntry}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ReadEntry = typeof ReadEntry.Type;
+/**
+ * A named, reusable list of {@link Entry} declarations.
+ *
+ * {@link expand} replaces a filegroup with its entries in place before any
+ * overlap check or measurement, so the name never reaches the boundary.
+ * Filegroups do not nest.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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;
+    }>]>>;
+}>;
+/**
+ * The value form of {@link Filegroup}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Filegroup = typeof Filegroup.Type;
+/**
+ * A {@link Filegroup} restricted to {@link ReadEntry} declarations, for use
+ * in a read set. It shares the `"Filegroup"` tag.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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>>;
+    }>]>>;
+}>;
+/**
+ * The value form of {@link ReadFilegroup}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ReadFilegroup = typeof ReadFilegroup.Type;
+/**
+ * Any declaration accepted in a write set: an {@link Entry} or a
+ * {@link Filegroup}.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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;
+    }>]>>;
+}>]>;
+/**
+ * The value form of {@link Declaration}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Declaration = typeof Declaration.Type;
+/**
+ * Any declaration accepted in a read set: a {@link ReadEntry} or a
+ * {@link ReadFilegroup}.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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>>;
+    }>]>>;
+}>]>;
+/**
+ * The value form of {@link ReadDeclaration}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ReadDeclaration = typeof ReadDeclaration.Type;
+/**
+ * Creates a {@link Filegroup}. It does not validate `name` or `entries`;
+ * decode through {@link Filegroup} when the input is untrusted.
+ *
+ * @param name - The filegroup name.
+ * @param entries - The entries the filegroup expands to, in order.
+ * @returns The filegroup value.
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeFilegroup: (name: string, entries: ReadonlyArray<Entry>) => Filegroup;
+/**
+ * Replaces each {@link Filegroup} with its entries, in place, and keeps every
+ * other declaration as it is. Order is preserved and duplicates are kept.
+ *
+ * @param declarations - Write-set declarations, possibly holding filegroups.
+ * @returns The flat list of entries.
+ * @category accessors
+ * @since 0.1.0
+ */
+export declare const expand: (declarations: ReadonlyArray<Declaration>) => ReadonlyArray<Entry>;
+/**
+ * {@link expand} for read sets: replaces each {@link ReadFilegroup} with its
+ * entries, in place, preserving order and duplicates.
+ *
+ * @param declarations - Read-set declarations, possibly holding filegroups.
+ * @returns The flat list of read entries.
+ * @category accessors
+ * @since 0.1.0
+ */
+export declare const expandReads: (declarations: ReadonlyArray<ReadDeclaration>) => ReadonlyArray<ReadEntry>;
+/**
+ * Whether a value carries the `"Glob"` tag. It checks only the tag, not the
+ * patterns.
+ *
+ * @param value - Any value.
+ * @returns `true` for an object whose `_tag` is `"Glob"`.
+ * @category guards
+ * @since 0.1.0
+ */
+export declare const isGlob: (value: unknown) => value is Glob;
+/**
+ * Whether a value carries the `"TreeArtifact"` tag. It checks only the tag,
+ * not the path.
+ *
+ * @param value - Any value.
+ * @returns `true` for an object whose `_tag` is `"TreeArtifact"`.
+ * @category guards
+ * @since 0.1.0
+ */
+export declare const isTreeArtifact: (value: unknown) => value is TreeArtifact;
+/**
+ * Whether `path` matches `pattern` under {@link Glob} wildcard rules.
+ *
+ * The pattern is read in its {@link canonical} spelling; the path is matched
+ * as given, case-sensitively, with `/` as its only separator.
+ *
+ * @param pattern - A Bazel-style pattern such as `src/*.ts` or `docs/**`.
+ * @param path - A workspace-relative path.
+ * @returns `true` when the path matches.
+ * @category predicates
+ * @since 0.1.0
+ */
+export declare const matchesPattern: (pattern: string, path: string) => boolean;
+/**
+ * Whether `path` matches some `include` pattern of `glob` and no `exclude`
+ * pattern, each tested with {@link matchesPattern}. Case-sensitive.
+ *
+ * @param glob - The glob to test.
+ * @param path - A workspace-relative path.
+ * @returns `true` when the glob selects the path.
+ * @category predicates
+ * @since 0.1.0
+ */
+export declare const matchesGlob: (glob: Glob, path: string) => boolean;
+/**
+ * Whether a canonical path is inside a declaration, case-sensitively.
+ * Unlike {@link overlaps}, this predicate establishes replay authority.
+ *
+ * @category predicates
+ * @since 1.0.0-rc.0
+ */
+export declare const contains: (entry: Entry, 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 folds its includes and ignores exclusions: an excluded
+ * spelling may alias an included spelling on another filesystem. {@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
+ */
+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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"}