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

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,302 @@
+/**
+ * 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. 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>
+  }
+
+const normalize = (paths: Iterable<string>): ReadonlyArray<string> => [...new Set(paths)].sort()
+
+/**
+ * Constructs a deterministic effect declaration: `reads` and `writes` are
+ * collected, deduplicated, and sorted; an absent `tier` is omitted. Paths are
+ * not validated or rewritten.
+ *
+ * @param input - The paths, mode, conflict strategy, and optional tier.
+ * @returns The normalized declaration.
+ * @category constructors
+ * @since 0.0.0
+ */
+export const make = (input: 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.
+ *
+ * @param envelope - One envelope entry.
+ * @param path - One declared path.
+ * @returns `true` when the entry covers the path.
+ * @category predicates
+ * @since 0.0.0
+ */
+export const covers = (envelope: 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.
+ *
+ * @param envelope - The flow's declaration.
+ * @param step - The step's declaration.
+ * @returns `{ ok: true }`, or the first rule the step breaks.
+ * @category validation
+ * @since 0.0.0
+ */
+export const narrow = (envelope: 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.
+ *
+ * @param a - One declaration.
+ * @param b - The other declaration.
+ * @returns The shared write paths; empty when the writes are disjoint.
+ * @category analysis
+ * @since 0.0.0
+ */
+export const overlaps = (a: 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, normalized by
+ * {@link make}. Paths and `onConflict` are kept.
+ *
+ * @param declaration - The declaration to copy.
+ * @returns The copy with `mode: "hermetic"` and `tier: "sealed"`.
+ * @category constructors
+ * @since 0.0.0
+ */
+export const sealed = (declaration: Declaration): Declaration =>
+  make({ ...declaration, mode: "hermetic", tier: "sealed" })