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

package/dist/cjs/CachePolicy.js

@@ -0,0 +1,50 @@
+"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 CachePolicy_exports = {};
+__export(CachePolicy_exports, {
+  CachePolicy: () => CachePolicy,
+  CachePolicyAnnotation: () => CachePolicyAnnotation,
+  CacheScope: () => CacheScope,
+  annotate: () => annotate,
+  cachePolicyOf: () => cachePolicyOf
+});
+module.exports = __toCommonJS(CachePolicy_exports);
+var Context = __toESM(require("effect/Context"), 1);
+var Option = __toESM(require("effect/Option"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+const CacheScope = Schema.Literals(["run", "flow", "shared"]);
+const PositiveMillis = Schema.Int.check(Schema.isGreaterThan(0));
+const CachePolicy = Schema.Struct({
+  ttlMs: Schema.optionalKey(PositiveMillis),
+  scope: Schema.optionalKey(CacheScope)
+});
+const CachePolicyAnnotation = Context.Service("@smthrs/flow/Action/CachePolicy");
+const cachePolicyOf = (annotations) => Option.getOrUndefined(Context.getOption(annotations, CachePolicyAnnotation));
+const annotate = (declaration, policy) => declaration.annotate(CachePolicyAnnotation, policy);
+//# sourceMappingURL=CachePolicy.js.map

package/dist/cjs/CachePolicy.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/CachePolicy.ts"],
+  "sourcesContent": ["/**\n * The caller-declared cache policy: how far a recorded sealed result may\n * travel, and how long it stays servable.\n *\n * This is the ONE cache-policy model. `@smthrs/flow` publishes it as\n * `CacheEnvironment.CachePolicy` and the engine reads it off a dispatched\n * action; `@smthrs/patterns` declares it over a flow as `WithCache.Policy`. It\n * used to be two declarations in those two packages, tied together by nothing\n * but a re-typed identifier string, so a field added on one side was invisible\n * to the other. It lives here because `@smthrs/plan` is the package both\n * already depend on.\n *\n * The annotation key still reads `\"@smthrs/flow/Action/CachePolicy\"`.\n * `@smthrs/engine-store`'s `ActionPersistence` reads the policy off stored and\n * dispatched actions by that identifier, so retagging it would make every\n * policy already written invisible at dispatch. The identifier is a wire\n * value, not a location.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * How far a recorded sealed result may travel.\n *\n * `shared` is the content-addressed default: the key names the inputs and the\n * environment, so any run on any host that would have produced the same bytes\n * may reuse the row. `run` and `flow` narrow that on purpose \u2014 a step whose\n * result is only meaningful inside one execution, or inside one flow, folds\n * that identity into its key so a sibling never reads it.\n *\n * The old scope vocabulary was `run | workflow | global`; `flow` and `shared`\n * are the same three levels named after the current concepts.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const CacheScope = Schema.Literals([\"run\", \"flow\", \"shared\"])\n\n/**\n * The value form of {@link CacheScope}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type CacheScope = typeof CacheScope.Type\n\n/**\n * A positive whole number of milliseconds.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nconst PositiveMillis = Schema.Int.check(Schema.isGreaterThan(0))\n\n/**\n * The caller's declaration about the decay and the reach of a sealed result.\n *\n * `ttlMs` bounds the age of a row the engine may serve: past it the dispatch\n * executes again and journals `cache-expired`, so the refusal is durable\n * evidence a replay reads rather than a fresh clock reading. `scope` decides\n * what the key names besides the inputs.\n *\n * Both fields are optional and both defaults are the pre-policy behavior: no\n * age bound, and the reach the composition's cache environment already\n * granted.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const CachePolicy = Schema.Struct({\n  ttlMs: Schema.optionalKey(PositiveMillis),\n  scope: Schema.optionalKey(CacheScope)\n})\n\n/**\n * The value form of {@link CachePolicy}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type CachePolicy = typeof CachePolicy.Type\n\n/**\n * Annotation key carrying a declaration's {@link CachePolicy}.\n *\n * It is an annotation, not a field on the declaration, for the same reason\n * placement and effects are: the policy is data that travels with the\n * declaration and is read by whoever executes it, and adding it changes no\n * existing call site.\n *\n * @category annotations\n * @since 1.0.0-rc.0\n */\nexport const CachePolicyAnnotation = Context.Service<CachePolicy>(\"@smthrs/flow/Action/CachePolicy\")\n\n/**\n * Reads the cache policy an annotation bag carries, or `undefined` when it\n * carries none.\n *\n * @category getters\n * @since 1.0.0-rc.0\n */\nexport const cachePolicyOf = (annotations: Context.Context<never>): CachePolicy | undefined =>\n  Option.getOrUndefined(Context.getOption(annotations, CachePolicyAnnotation))\n\n/**\n * Attaches a cache policy to a declaration that can carry annotations.\n *\n * The declaration is not mutated: `annotate` answers a new one carrying the\n * policy, which is what a plan captures. It is written against the `annotate`\n * method rather than against an action or a flow type so the one declaration\n * serves both, which is what `@smthrs/flow` publishes as\n * `CacheEnvironment.withCache`.\n *\n * @example\n * ```ts\n * import { CachePolicy } from \"@smthrs/plan\"\n * import { Action } from \"@smthrs/flow\"\n * import * as Effect from \"effect/Effect\"\n * import * as Schema from \"effect/Schema\"\n *\n * const compile = CachePolicy.annotate(\n *   Action.make({\n *     name: \"build/compile\",\n *     success: Schema.String,\n *     tier: \"sealed\",\n *     execute: Effect.succeed(\"dist/server.js\")\n *   }),\n *   { ttlMs: 60_000, scope: \"shared\" }\n * )\n * ```\n *\n * @category combinators\n * @since 1.0.0-rc.0\n */\nexport const annotate = <A extends { annotate: (key: typeof CachePolicyAnnotation, value: CachePolicy) => A }>(\n  declaration: A,\n  policy: CachePolicy\n): A => declaration.annotate(CachePolicyAnnotation, policy)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBA,cAAyB;AACzB,aAAwB;AACxB,aAAwB;AAiBjB,MAAM,aAAa,OAAO,SAAS,CAAC,OAAO,QAAQ,QAAQ,CAAC;AAgBnE,MAAM,iBAAiB,OAAO,IAAI,MAAM,OAAO,cAAc,CAAC,CAAC;AAiBxD,MAAM,cAAc,OAAO,OAAO;AAAA,EACvC,OAAO,OAAO,YAAY,cAAc;AAAA,EACxC,OAAO,OAAO,YAAY,UAAU;AACtC,CAAC;AAqBM,MAAM,wBAAwB,QAAQ,QAAqB,iCAAiC;AAS5F,MAAM,gBAAgB,CAAC,gBAC5B,OAAO,eAAe,QAAQ,UAAU,aAAa,qBAAqB,CAAC;AAgCtE,MAAM,WAAW,CACtB,aACA,WACM,YAAY,SAAS,uBAAuB,MAAM;",
+  "names": []
+}

package/dist/cjs/Effects.d.ts

@@ -0,0 +1,258 @@
+/**
+ * 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. Build one with {@link make}.
+ *
+ * @category models
+ * @since 0.0.0
+ */
+export interface Declaration {
+    /** Readable paths or envelope patterns, sorted and duplicate-free. */
+    readonly reads: ReadonlyArray<string>;
+    /** Writable paths or envelope patterns, sorted and duplicate-free. */
+    readonly writes: ReadonlyArray<string>;
+    /** `hermetic` or `expected` enforcement. */
+    readonly mode: Mode;
+    /** What a plan does when another node writes an overlapping path. */
+    readonly onConflict: ConflictStrategy;
+    /** The effect tier. Absent means `sealed`. */
+    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
+ */
+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.
+ *
+ * On failure, `code` names the first rule broken, checked in this order:
+ * `effect_outside_envelope` (with the uncovered read and write paths, sorted),
+ * `effect_mode_widening`, then `effect_tier_widening` (both with empty
+ * `paths`).
+ *
+ * @category models
+ * @since 0.0.0
+ */
+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: `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 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.
+ *
+ * @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 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.
+ *
+ * @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 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.
+ *
+ * @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 declare const overlaps: (a: Declaration, b: Declaration) => ReadonlyArray<string>;
+/**
+ * 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 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":"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"}

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. 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"],
+  "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;AAmGpF,MAAM,YAAY,CAAC,UAAmD,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,EAAE,KAAK;AAYxF,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;AAmBO,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;AAsBO,MAAM,SAAS,CAAC,UAAuB,SAC5C,MAAM,eAAe,MAAM,gBAAgB,QAAQ,GAAG,IAAI;AAyBrD,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;AAWO,MAAM,SAAS,CAAC,gBACrB,KAAK,EAAE,GAAG,aAAa,MAAM,YAAY,MAAM,SAAS,CAAC;",
+  "names": []
+}