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

package/package.json

@@ -1,6 +1,257 @@
 {
   "name": "@smthrs/plan",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.4",
+  "license": "MIT",
+  "smthrs": {
+    "group": "engine"
+  },
+  "description": "The persisted flows plan: a keyed action graph, its append-only store, and its diff",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/flows/plan"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "plan",
+    "graph"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "plan",
+    "graph"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./GraphBuildError": {
+      "import": {
+        "types": "./dist/esm/GraphBuildError.d.ts",
+        "default": "./dist/esm/GraphBuildError.js"
+      },
+      "require": {
+        "types": "./dist/cjs/GraphBuildError.d.ts",
+        "default": "./dist/cjs/GraphBuildError.js"
+      }
+    },
+    "./Node": {
+      "import": {
+        "types": "./dist/esm/Node.d.ts",
+        "default": "./dist/esm/Node.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Node.d.ts",
+        "default": "./dist/cjs/Node.js"
+      }
+    },
+    "./Planned": {
+      "import": {
+        "types": "./dist/esm/Planned.d.ts",
+        "default": "./dist/esm/Planned.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Planned.d.ts",
+        "default": "./dist/cjs/Planned.js"
+      }
+    },
+    "./internal/*": null,
+    "./*/index": null,
+    "./Effects": {
+      "import": {
+        "types": "./dist/esm/Effects.d.ts",
+        "default": "./dist/esm/Effects.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Effects.d.ts",
+        "default": "./dist/cjs/Effects.js"
+      }
+    },
+    "./CachePolicy": {
+      "import": {
+        "types": "./dist/esm/CachePolicy.d.ts",
+        "default": "./dist/esm/CachePolicy.js"
+      },
+      "require": {
+        "types": "./dist/cjs/CachePolicy.d.ts",
+        "default": "./dist/cjs/CachePolicy.js"
+      }
+    },
+    "./Repetition": {
+      "import": {
+        "types": "./dist/esm/Repetition.d.ts",
+        "default": "./dist/esm/Repetition.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Repetition.d.ts",
+        "default": "./dist/cjs/Repetition.js"
+      }
+    },
+    "./FileSet": {
+      "import": {
+        "types": "./dist/esm/FileSet.d.ts",
+        "default": "./dist/esm/FileSet.js"
+      },
+      "require": {
+        "types": "./dist/cjs/FileSet.d.ts",
+        "default": "./dist/cjs/FileSet.js"
+      }
+    },
+    "./KeyMaterial": {
+      "import": {
+        "types": "./dist/esm/KeyMaterial.d.ts",
+        "default": "./dist/esm/KeyMaterial.js"
+      },
+      "require": {
+        "types": "./dist/cjs/KeyMaterial.d.ts",
+        "default": "./dist/cjs/KeyMaterial.js"
+      }
+    },
+    "./Migrations": null,
+    "./Plan": {
+      "import": {
+        "types": "./dist/esm/Plan.d.ts",
+        "default": "./dist/esm/Plan.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Plan.d.ts",
+        "default": "./dist/cjs/Plan.js"
+      }
+    },
+    "./Placement": {
+      "import": {
+        "types": "./dist/esm/Placement.d.ts",
+        "default": "./dist/esm/Placement.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Placement.d.ts",
+        "default": "./dist/cjs/Placement.js"
+      }
+    },
+    "./PlanDiff": {
+      "import": {
+        "types": "./dist/esm/PlanDiff.d.ts",
+        "default": "./dist/esm/PlanDiff.js"
+      },
+      "require": {
+        "types": "./dist/cjs/PlanDiff.d.ts",
+        "default": "./dist/cjs/PlanDiff.js"
+      }
+    },
+    "./PlanStore": null,
+    "./StepKey": {
+      "import": {
+        "types": "./dist/esm/StepKey.d.ts",
+        "default": "./dist/esm/StepKey.js"
+      },
+      "require": {
+        "types": "./dist/cjs/StepKey.d.ts",
+        "default": "./dist/cjs/StepKey.js"
+      }
+    },
+    "./Scheduling": {
+      "import": {
+        "types": "./dist/esm/Scheduling.d.ts",
+        "default": "./dist/esm/Scheduling.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Scheduling.d.ts",
+        "default": "./dist/cjs/Scheduling.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./test/PlanFixtures": {
+      "import": {
+        "types": "./dist/esm/test/PlanFixtures.d.ts",
+        "default": "./dist/esm/test/PlanFixtures.js"
+      },
+      "require": {
+        "types": "./dist/cjs/test/PlanFixtures.d.ts",
+        "default": "./dist/cjs/test/PlanFixtures.js"
+      }
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/crypto": "1.0.0-rc.4",
+    "@smthrs/keys": "1.0.0-rc.4",
+    "@smthrs/canonical": "1.0.0-rc.4"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/platform-node": "4.0.0-rc.115",
+    "@effect/vitest": "4.0.0-rc.115",
+    "@eslint/js": "9.39.5",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.0-rc.115",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0",
+    "fast-check": "4.9.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.115"
+  },
+  "scripts": {
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  }
 }

package/src/CachePolicy.ts

@@ -0,0 +1,143 @@
+/**
+ * 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"])
+
+/**
+ * The value form of {@link CacheScope}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type CacheScope = typeof CacheScope.Type
+
+/**
+ * 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)
+})
+
+/**
+ * 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 const CachePolicyAnnotation = Context.Service<CachePolicy>("@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: Context.Context<never>): CachePolicy | undefined =>
+  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 = <A extends { annotate: (key: typeof CachePolicyAnnotation, value: CachePolicy) => A }>(
+  declaration: A,
+  policy: CachePolicy
+): A => declaration.annotate(CachePolicyAnnotation, policy)

package/src/Effects.ts

@@ -0,0 +1,284 @@
+/**
+ * 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.ts"
+
+/**
+ * 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"])
+
+/**
+ * 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 const Mode = Schema.Literals(["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 const ConflictStrategy = Schema.Literals(["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 const Envelope = Context.Service<Declaration>("@smthrs/plan/Effects/Envelope")
+
+/**
+ * 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>
+  }
+
+const normalize = (paths: Iterable<string>): ReadonlyArray<string> => [...new Set(paths)].sort()
+
+/**
+ * Constructs a deterministic effect declaration.
+ *
+ * @category constructors
+ * @since 0.0.0
+ * @slop
+ */
+export const make = (input: MakeOptions): Declaration => ({
+  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: string, path: string): boolean => {
+  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: Declaration, step: Declaration): NarrowResult =>
+  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: Declaration, b: Declaration): ReadonlyArray<string> => {
+  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: Declaration): Declaration =>
+  make({ ...declaration, mode: "hermetic", tier: "sealed" })