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

package/dist/esm/CachePolicy.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The caller-declared cache policy: how far a recorded sealed result may
+ * travel, and how long it stays servable.
+ *
+ * This is the ONE cache-policy model. `@smthrs/flow` publishes it as
+ * `CacheEnvironment.CachePolicy` and the engine reads it off a dispatched
+ * action; `@smthrs/patterns` declares it over a flow as `WithCache.Policy`. It
+ * used to be two declarations in those two packages, tied together by nothing
+ * but a re-typed identifier string, so a field added on one side was invisible
+ * to the other. It lives here because `@smthrs/plan` is the package both
+ * already depend on.
+ *
+ * The annotation key still reads `"@smthrs/flow/Action/CachePolicy"`.
+ * `@smthrs/engine-store`'s `ActionPersistence` reads the policy off stored and
+ * dispatched actions by that identifier, so retagging it would make every
+ * policy already written invisible at dispatch. The identifier is a wire
+ * value, not a location.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Context from "effect/Context";
+import * as Schema from "effect/Schema";
+/**
+ * How far a recorded sealed result may travel.
+ *
+ * `shared` is the content-addressed default: the key names the inputs and the
+ * environment, so any run on any host that would have produced the same bytes
+ * may reuse the row. `run` and `flow` narrow that on purpose — a step whose
+ * result is only meaningful inside one execution, or inside one flow, folds
+ * that identity into its key so a sibling never reads it.
+ *
+ * The old scope vocabulary was `run | workflow | global`; `flow` and `shared`
+ * are the same three levels named after the current concepts.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const CacheScope: Schema.Literals<readonly ["run", "flow", "shared"]>;
+/**
+ * The value form of {@link CacheScope}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type CacheScope = typeof CacheScope.Type;
+/**
+ * The caller's declaration about the decay and the reach of a sealed result.
+ *
+ * `ttlMs` bounds the age of a row the engine may serve: past it the dispatch
+ * executes again and journals `cache-expired`, so the refusal is durable
+ * evidence a replay reads rather than a fresh clock reading. `scope` decides
+ * what the key names besides the inputs.
+ *
+ * Both fields are optional and both defaults are the pre-policy behavior: no
+ * age bound, and the reach the composition's cache environment already
+ * granted.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const CachePolicy: Schema.Struct<{
+    readonly ttlMs: Schema.optionalKey<Schema.Int>;
+    readonly scope: Schema.optionalKey<Schema.Literals<readonly ["run", "flow", "shared"]>>;
+}>;
+/**
+ * The value form of {@link CachePolicy}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type CachePolicy = typeof CachePolicy.Type;
+/**
+ * Annotation key carrying a declaration's {@link CachePolicy}.
+ *
+ * It is an annotation, not a field on the declaration, for the same reason
+ * placement and effects are: the policy is data that travels with the
+ * declaration and is read by whoever executes it, and adding it changes no
+ * existing call site.
+ *
+ * @category annotations
+ * @since 1.0.0-rc.0
+ */
+export declare const CachePolicyAnnotation: Context.Service<{
+    readonly ttlMs?: number;
+    readonly scope?: "run" | "flow" | "shared";
+}, {
+    readonly ttlMs?: number;
+    readonly scope?: "run" | "flow" | "shared";
+}>;
+/**
+ * Reads the cache policy an annotation bag carries, or `undefined` when it
+ * carries none.
+ *
+ * @category getters
+ * @since 1.0.0-rc.0
+ */
+export declare const cachePolicyOf: (annotations: Context.Context<never>) => CachePolicy | undefined;
+/**
+ * Attaches a cache policy to a declaration that can carry annotations.
+ *
+ * The declaration is not mutated: `annotate` answers a new one carrying the
+ * policy, which is what a plan captures. It is written against the `annotate`
+ * method rather than against an action or a flow type so the one declaration
+ * serves both, which is what `@smthrs/flow` publishes as
+ * `CacheEnvironment.withCache`.
+ *
+ * @example
+ * ```ts
+ * import { CachePolicy } from "@smthrs/plan"
+ * import { Action } from "@smthrs/flow"
+ * import * as Effect from "effect/Effect"
+ * import * as Schema from "effect/Schema"
+ *
+ * const compile = CachePolicy.annotate(
+ *   Action.make({
+ *     name: "build/compile",
+ *     success: Schema.String,
+ *     tier: "sealed",
+ *     execute: Effect.succeed("dist/server.js")
+ *   }),
+ *   { ttlMs: 60_000, scope: "shared" }
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export declare const annotate: <A extends {
+    annotate: (key: typeof CachePolicyAnnotation, value: CachePolicy) => A;
+}>(declaration: A, policy: CachePolicy) => A;
+//# sourceMappingURL=CachePolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CachePolicy.d.ts","sourceRoot":"","sources":["../../src/CachePolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,qDAA6C,CAAA;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;AAU/C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;EAGtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;;;EAAkE,CAAA;AAEpG;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,aAAa,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,WAAW,GAAG,SACJ,CAAA;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS;IAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,qBAAqB,EAAE,KAAK,EAAE,WAAW,KAAK,CAAC,CAAA;CAAE,EAC3G,aAAa,CAAC,EACd,QAAQ,WAAW,KAClB,CAAwD,CAAA"}

package/dist/esm/CachePolicy.js

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

package/dist/esm/CachePolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CachePolicy.js","sourceRoot":"","sources":["../../src/CachePolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;AAUpE;;;;;GAKG;AACH,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;AAEhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC;IACzC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC;CACtC,CAAC,CAAA;AAUF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAc,iCAAiC,CAAC,CAAA;AAEpG;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,WAAmC,EAA2B,EAAE,CAC5F,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,WAAW,EAAE,qBAAqB,CAAC,CAAC,CAAA;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,WAAc,EACd,MAAmB,EAChB,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAA","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 — 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"]}

package/dist/esm/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/esm/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/esm/Effects.js

@@ -0,0 +1,167 @@
+/**
+ * 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.
+ *
+ * @category constructors
+ * @since 0.0.0
+ * @slop
+ */
+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.
+ *
+ * @category predicates
+ * @since 0.0.0
+ * @slop
+ */
+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.
+ *
+ * @category validation
+ * @since 0.0.0
+ * @slop
+ */
+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.
+ *
+ * @category analysis
+ * @since 0.0.0
+ * @slop
+ */
+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.
+ *
+ * @category constructors
+ * @since 0.0.0
+ * @slop
+ */
+export const sealed = (declaration) => make({ ...declaration, mode: "hermetic", tier: "sealed" });
+//# sourceMappingURL=Effects.js.map