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

package/dist/cjs/Effects.d.ts

@@ -0,0 +1,240 @@
+/**
+ * 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";
+/**
+ * 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 declare const Tier: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+/**
+ * The value form of {@link Tier}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Tier = typeof Tier.Type;
+/**
+ * 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 declare const Mode: Schema.Literals<readonly ["hermetic", "expected"]>;
+/**
+ * The value form of {@link Mode}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Mode = typeof Mode.Type;
+/**
+ * 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 declare const ConflictStrategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
+/**
+ * The value form of {@link ConflictStrategy}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ConflictStrategy = typeof ConflictStrategy.Type;
+/**
+ * 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 declare const Envelope: Context.Service<Declaration, Declaration>;
+/**
+ * The prepared matching API: what a graph builder needs to check one envelope
+ * against every step it encloses, and to find the write overlaps between two
+ * declarations, at the cost the public functions above pay once rather than
+ * once per step.
+ *
+ * {@link prepareEnvelope} reads an envelope once into the form
+ * {@link narrowPrepared} answers from, which is what makes a wide envelope cost
+ * its size per build rather than per node. {@link indexPaths},
+ * {@link rankPaths} and {@link overlapRanks} are the same decomposition for
+ * write overlap, which {@link overlaps} wraps for the pairwise case.
+ * {@link boundedEffects} snapshots a declaration into builder-owned data,
+ * refusing through the caller's own error before the copy grows past its limit,
+ * and {@link maximumPathLength} and {@link maximumGlobs} are the per-path bounds
+ * that refusal enforces.
+ *
+ * @category matching
+ * @since 1.0.0-rc.0
+ */
+export type { PathIndex, PreparedEnvelope, Ranked } from "./internal/effects.ts";
+/**
+ * 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.ts";
+/**
+ * A normalized description of the resources a flow or step may read and
+ * write.
+ *
+ * @category models
+ * @since 0.0.0
+ * @slop
+ */
+export interface Declaration {
+    readonly reads: ReadonlyArray<string>;
+    readonly writes: ReadonlyArray<string>;
+    readonly mode: Mode;
+    readonly onConflict: ConflictStrategy;
+    readonly tier?: Tier | undefined;
+}
+/**
+ * Input accepted by {@link make}. Iterables are normalized into sorted,
+ * duplicate-free arrays so declarations are deterministic key material.
+ * Envelope entries and declared paths must already be path-normalized: no
+ * separator or dot-segment rewriting is performed. A declared path containing
+ * a whole `.` or `..` segment is never covered and therefore surfaces from
+ * {@link narrow} as an `effect_outside_envelope` diagnostic.
+ *
+ * @category models
+ * @since 0.0.0
+ * @slop
+ */
+export interface MakeOptions {
+    readonly reads: Iterable<string>;
+    readonly writes: Iterable<string>;
+    readonly mode: Mode;
+    readonly onConflict: ConflictStrategy;
+    readonly tier?: Tier | undefined;
+}
+/**
+ * A result of checking that a step declaration narrows a flow envelope.
+ *
+ * @category models
+ * @since 0.0.0
+ * @slop
+ */
+export type NarrowResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: "effect_outside_envelope" | "effect_mode_widening" | "effect_tier_widening";
+    readonly paths: ReadonlyArray<string>;
+};
+/**
+ * Constructs a deterministic effect declaration.
+ *
+ * @category constructors
+ * @since 0.0.0
+ * @slop
+ */
+export declare const make: (input: MakeOptions) => Declaration;
+/**
+ * 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.
+ *
+ * @category predicates
+ * @since 0.0.0
+ * @slop
+ */
+export declare const covers: (envelope: string, path: string) => boolean;
+/**
+ * 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.
+ *
+ * @category validation
+ * @since 0.0.0
+ * @slop
+ */
+export declare const narrow: (envelope: Declaration, step: Declaration) => NarrowResult;
+/**
+ * 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.
+ *
+ * @category analysis
+ * @since 0.0.0
+ * @slop
+ */
+export declare const overlaps: (a: Declaration, b: Declaration) => ReadonlyArray<string>;
+/**
+ * Returns a sealed, hermetic copy of an effect declaration.
+ *
+ * @category constructors
+ * @since 0.0.0
+ * @slop
+ */
+export declare const sealed: (declaration: Declaration) => Declaration;
+//# sourceMappingURL=Effects.d.ts.map

package/dist/cjs/Effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Effects.d.ts","sourceRoot":"","sources":["../../src/Effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,qEAA6D,CAAA;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAA;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,oDAA4C,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAA;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,yDAAiD,CAAA;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,2CAAgE,CAAA;AAErF;;;;;;;;;;;;;;;;;;GAkBG;AACH,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAEhF;;;;;;GAMG;AACH,OAAO,EACL,cAAc,EACd,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,SAAS,EACV,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAA;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAA;CACjC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAA;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAA;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IACA,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,IAAI,EAAE,yBAAyB,GAAG,sBAAsB,GAAG,sBAAsB,CAAA;IAC1F,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACtC,CAAA;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,WAAW,KAAG,WAMxC,CAAA;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,KAAG,OAGvD,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,GAAI,UAAU,WAAW,EAAE,MAAM,WAAW,KAAG,YACL,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,QAAQ,GAAI,GAAG,WAAW,EAAE,GAAG,WAAW,KAAG,aAAa,CAAC,MAAM,CAI7E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,aAAa,WAAW,KAAG,WACU,CAAA"}

package/dist/cjs/Effects.js

@@ -0,0 +1,76 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Effects_exports = {};
+__export(Effects_exports, {
+  ConflictStrategy: () => ConflictStrategy,
+  Envelope: () => Envelope,
+  Mode: () => Mode,
+  Tier: () => Tier,
+  boundedEffects: () => import_effects.boundedEffects,
+  covers: () => covers,
+  indexPaths: () => import_effects.indexPaths,
+  make: () => make,
+  maximumGlobs: () => import_effects.maximumGlobs,
+  maximumPathLength: () => import_effects.maximumPathLength,
+  narrow: () => narrow,
+  narrowPrepared: () => import_effects.narrowPrepared,
+  overlapRanks: () => import_effects.overlapRanks,
+  overlaps: () => overlaps,
+  prepareEnvelope: () => import_effects.prepareEnvelope,
+  rankPaths: () => import_effects.rankPaths,
+  sealed: () => sealed
+});
+module.exports = __toCommonJS(Effects_exports);
+var Context = __toESM(require("effect/Context"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var Index = __toESM(require("./internal/effects.js"), 1);
+var import_effects = require("./internal/effects.js");
+const Tier = Schema.Literals(["sealed", "compensable", "irreversible"]);
+const Mode = Schema.Literals(["hermetic", "expected"]);
+const ConflictStrategy = Schema.Literals(["serialize", "lane", "fail"]);
+const Envelope = Context.Service("@smthrs/plan/Effects/Envelope");
+const normalize = (paths) => [...new Set(paths)].sort();
+const make = (input) => ({
+  reads: normalize(input.reads),
+  writes: normalize(input.writes),
+  mode: input.mode,
+  onConflict: input.onConflict,
+  ...input.tier === void 0 ? {} : { tier: input.tier }
+});
+const covers = (envelope, path) => {
+  if (Index.hasDotSegment(path)) return false;
+  return envelope === path || Index.isGlob(envelope) && path.startsWith(Index.globPrefix(envelope));
+};
+const narrow = (envelope, step) => Index.narrowPrepared(Index.prepareEnvelope(envelope), step);
+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]);
+};
+const sealed = (declaration) => make({ ...declaration, mode: "hermetic", tier: "sealed" });
+//# sourceMappingURL=Effects.js.map

package/dist/cjs/Effects.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Effects.ts"],
+  "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"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmBA,cAAyB;AACzB,aAAwB;AACxB,YAAuB;AA2GvB,qBASO;AAvGA,MAAM,OAAO,OAAO,SAAS,CAAC,UAAU,eAAe,cAAc,CAAC;AAmBtE,MAAM,OAAO,OAAO,SAAS,CAAC,YAAY,UAAU,CAAC;AAoBrD,MAAM,mBAAmB,OAAO,SAAS,CAAC,aAAa,QAAQ,MAAM,CAAC;AAyBtE,MAAM,WAAW,QAAQ,QAAqB,+BAA+B;AA4FpF,MAAM,YAAY,CAAC,UAAmD,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,EAAE,KAAK;AASxF,MAAM,OAAO,CAAC,WAAqC;AAAA,EACxD,OAAO,UAAU,MAAM,KAAK;AAAA,EAC5B,QAAQ,UAAU,MAAM,MAAM;AAAA,EAC9B,MAAM,MAAM;AAAA,EACZ,YAAY,MAAM;AAAA,EAClB,GAAI,MAAM,SAAS,SAAY,CAAC,IAAI,EAAE,MAAM,MAAM,KAAK;AACzD;AAiBO,MAAM,SAAS,CAAC,UAAkB,SAA0B;AACjE,MAAI,MAAM,cAAc,IAAI,EAAG,QAAO;AACtC,SAAO,aAAa,QAAS,MAAM,OAAO,QAAQ,KAAK,KAAK,WAAW,MAAM,WAAW,QAAQ,CAAC;AACnG;AAoBO,MAAM,SAAS,CAAC,UAAuB,SAC5C,MAAM,eAAe,MAAM,gBAAgB,QAAQ,GAAG,IAAI;AAuBrD,MAAM,WAAW,CAAC,GAAgB,MAA0C;AACjF,QAAM,UAAU,MAAM,WAAW,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC;AACrD,SAAO,MAAM,aAAa,SAAS,MAAM,UAAU,SAAS,EAAE,MAAM,GAAG,MAAM,UAAU,SAAS,EAAE,MAAM,CAAC,EACtG,IAAI,CAAC,SAAS,QAAQ,MAAM,IAAI,CAAE;AACvC;AASO,MAAM,SAAS,CAAC,gBACrB,KAAK,EAAE,GAAG,aAAa,MAAM,YAAY,MAAM,SAAS,CAAC;",
+  "names": []
+}

package/dist/cjs/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/cjs/FileSet.d.ts.map

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