@smthrs/flow 0.0.0-stage → 1.0.0-rc.13

package/src/Action/AttemptTimedOut.ts

@@ -0,0 +1,37 @@
+/**
+ * Defines the defect an action attempt settles with when it outlives its
+ * declared `attemptTimeoutMs` or misses its `heartbeatTimeoutMs`.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+/**
+ * One attempt of an action ran past a declared time bound and was
+ * interrupted.
+ *
+ * It is a defect rather than a typed failure because the bound belongs to the
+ * dispatch, not to the action's declared error channel. The engine's retry
+ * decision point still counts it as a retryable attempt failure under the
+ * action's `retryPolicy`, and a policy can refuse it by listing this tag in
+ * `nonRetryable`.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export class AttemptTimedOut extends Schema.TaggedError<AttemptTimedOut>()(
+  "@smthrs/flow/AttemptTimedOut",
+  {
+    code: Schema.Literal("attempt_timed_out").pipe(
+      Schema.withConstructorDefault(Effect.succeed("attempt_timed_out"))
+    ),
+    actionName: Schema.String,
+    attempt: Schema.Number,
+    /** Which bound expired: the whole attempt, or the gap between heartbeats. */
+    bound: Schema.Literals(["attempt", "heartbeat"]),
+    timeoutMs: Schema.Number,
+    message: Schema.String
+  }
+) {}

package/src/Action/BoundaryMode.ts

@@ -0,0 +1,33 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Defines filesystem boundary enforcement modes.
+ *
+ * The schema itself is `@smthrs/plan`'s `FileSet.BoundaryMode`, because the
+ * same two words are what a plan node's `effects.boundaryMode` carries. This
+ * module is the name an action reaches for; there is one declaration behind
+ * both.
+ *
+ * @since 0.1.0
+ */
+
+import * as FileSet from "@smthrs/plan/FileSet"
+
+/**
+ * Schema for how strictly an action's filesystem boundary is enforced.
+ *
+ * `hard` rejects undeclared access. `expected` records access for validation
+ * after execution without requiring the sandbox to reject it immediately.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const BoundaryMode = FileSet.BoundaryMode
+
+/**
+ * How strictly an action's filesystem boundary is enforced.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type BoundaryMode = FileSet.BoundaryMode

package/src/Action/CacheEnvironment.ts

@@ -0,0 +1,170 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * The environment description folded into every cross-run cache key.
+ *
+ * A cached result is only reusable on a host that would have produced the same
+ * bytes, so the key has to name the environment as well as the inputs — the
+ * platform, the toolchain, and the capability groups in force. Bazel's action
+ * key does the same thing for the same reason.
+ *
+ * It is a *complete* value on purpose: an environment a composition cannot
+ * fully describe is one whose cache hits cannot be justified, and the engine
+ * executes rather than guessing at the missing part.
+ *
+ * @since 0.1.0
+ */
+
+import * as PlanCachePolicy from "@smthrs/plan/CachePolicy"
+import * as Schema from "effect/Schema"
+
+/**
+ * Validates named capability groups.
+ *
+ * @private
+ * @since 0.1.0
+ */
+const Capabilities = Schema.Record(Schema.String, Schema.Array(Schema.NonEmptyString)).check(
+  Schema.makeFilter((capabilities) =>
+    Object.keys(capabilities).every((name) => name.length > 0) || "Capability names must not be empty"
+  )
+)
+
+/**
+ * Complete runtime environment included in every cross-run cache key.
+ *
+ * If a composition cannot provide this complete value, the engine executes
+ * normally but does not derive a cross-run cache key.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CacheEnvironment = typeof CacheEnvironment.Type
+
+/**
+ * Schema for the complete runtime environment included in cache keys.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const CacheEnvironment = Schema.Struct({
+  /** Ordered semantic runtime layers, including versions and configuration. */
+  layers: Schema.Array(Schema.NonEmptyString),
+  /** Complete effective capability groups. */
+  capabilities: Capabilities
+})
+
+/**
+ * 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.
+ *
+ * This is `@smthrs/plan`'s `CachePolicy.CacheScope`, the one scope vocabulary
+ * `@smthrs/patterns` also declares its policy with.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const CacheScope = PlanCachePolicy.CacheScope
+
+/**
+ * How far a recorded sealed result may travel.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CacheScope = PlanCachePolicy.CacheScope
+
+/**
+ * The caller's declaration about the decay and the reach of a sealed action's
+ * recorded 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.
+ *
+ * This is `@smthrs/plan`'s `CachePolicy.CachePolicy`, the one policy schema.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const CachePolicy = PlanCachePolicy.CachePolicy
+
+/**
+ * The caller's declaration about the decay and the reach of a sealed action's
+ * recorded result.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CachePolicy = PlanCachePolicy.CachePolicy
+
+/**
+ * Annotation key carrying a declaration's {@link CachePolicy}.
+ *
+ * It is an annotation, not a field on the action, 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.
+ *
+ * It is `@smthrs/plan`'s `CachePolicy.CachePolicyAnnotation` itself, the same
+ * object `@smthrs/patterns` annotates a flow with, identified by
+ * `"@smthrs/flow/Action/CachePolicy"`.
+ *
+ * @category annotations
+ * @since 0.1.0
+ */
+export const CachePolicyAnnotation = PlanCachePolicy.CachePolicyAnnotation
+
+/**
+ * Reads the cache policy an annotation bag carries, or `undefined` when it
+ * carries none.
+ *
+ * @category getters
+ * @since 0.1.0
+ */
+export const cachePolicyOf = PlanCachePolicy.cachePolicyOf
+
+/**
+ * Declares a cache policy on an action.
+ *
+ * This is the form the engine honors today: `@smthrs/engine-store` reads
+ * {@link CachePolicyAnnotation} off the dispatched action, bounds the age of
+ * the row it may serve by `ttlMs`, and narrows the address that row is stored
+ * under from `scope`. `@smthrs/patterns`' `WithCache` declares the same policy
+ * over a `@smthrs/core` flow under the same annotation key, for the
+ * declaration surface, so a policy written by either is read by the engine.
+ *
+ * The action is not mutated. `annotate` returns a new declaration carrying the
+ * policy, which is what a plan captures.
+ *
+ * It is `@smthrs/plan`'s `CachePolicy.annotate` under this package's name for
+ * it.
+ *
+ * @example
+ * ```ts
+ * import { Action } from "@smthrs/flow"
+ * import * as CacheEnvironment from "@smthrs/flow/CacheEnvironment"
+ * import * as Effect from "effect/Effect"
+ * import * as Schema from "effect/Schema"
+ *
+ * const compile = CacheEnvironment.withCache(
+ *   Action.make({
+ *     name: "build/compile",
+ *     success: Schema.String,
+ *     tier: "sealed",
+ *     execute: Effect.succeed("dist/server.js")
+ *   }),
+ *   { ttlMs: 60_000, scope: "shared" }
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const withCache = PlanCachePolicy.annotate

package/src/Action/ConcurrentKeylessDispatch.ts

@@ -0,0 +1,38 @@
+/**
+ * Defines the `ConcurrentKeylessDispatch` action failure.
+ *
+ * The `_tag` string was settled under `@smthrs/flow/` for 1.0.0-rc.0. The RC
+ * makes no compatibility promise to 0.x journals, and the tag freezes when
+ * the RC ships.
+ *
+ * @since 0.1.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+/**
+ * Two ordinal-keyed invocations of one allocation scope were in flight
+ * concurrently, either keyless invocations of one declaration or same-key
+ * invocations at a non-sealed tier (issue #130), so their ordinals, and with
+ * them their step keys, attempt rows, and recorded outcomes, would be
+ * assigned by fiber arrival order. A crash-resume that replays the fibers in
+ * the opposite order would silently hand one invocation the other's recorded
+ * outcome (issue #111); Temporal fails such replays with a nondeterminism
+ * error, and the engine refuses the hazard up front instead of detecting it
+ * after the corruption. Declare an `idempotencyKey` *distinguishing* the
+ * invocations to dispatch them concurrently; a sealed action with a key
+ * takes a pure cache key and is exempt.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class ConcurrentKeylessDispatch extends Schema.TaggedError<ConcurrentKeylessDispatch>()(
+  "@smthrs/flow/ConcurrentKeylessDispatch",
+  {
+    code: Schema.Literal("concurrent_keyless_dispatch").pipe(
+      Schema.withConstructorDefault(Effect.succeed("concurrent_keyless_dispatch"))
+    ),
+    actionName: Schema.String
+  }
+) {}

package/src/Action/Context.ts

@@ -0,0 +1,156 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Defines runtime context carried across action attempts.
+ *
+ * @since 0.1.0
+ */
+
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import type { CacheEnvironment } from "./CacheEnvironment.ts"
+
+/**
+ * Context reference carrying the complete environment folded into reusable
+ * action keys.
+ *
+ * A composition either provides a complete {@link CacheEnvironment} or leaves
+ * it absent. When absent, the engine scopes action keys to the current run
+ * instead of presenting incomplete environment data as reusable identity.
+ *
+ * @category idempotency
+ * @since 0.1.0
+ */
+export const CurrentCacheEnvironment = Context.Reference<CacheEnvironment | undefined>(
+  "@smthrs/flow/Action/CurrentCacheEnvironment",
+  { defaultValue: () => undefined }
+)
+
+/**
+ * Declares the complete cache environment of a composition as a layer.
+ *
+ * **When to use**
+ *
+ * Use this only when the composition can identify every semantic runtime
+ * layer and its complete capability set. Otherwise leave the context absent.
+ *
+ * @category idempotency
+ * @since 0.1.0
+ */
+export const layerCacheEnvironment = (
+  environment: CacheEnvironment
+): Layer.Layer<never> => Layer.succeed(CurrentCacheEnvironment)(environment)
+
+/**
+ * The ordinal slots a retry sequence shares across its attempts, keyed by
+ * allocation scope.
+ *
+ * `Action.retry` cannot allocate ordinals itself — allocation is scoped by
+ * action identity and only the engine knows which action is being
+ * dispatched (issue #73) — so it provides an empty map the engine fills per
+ * scope on the first attempt and reads back on every later one. The map is
+ * scope-keyed rather than a single value because one retry block may
+ * dispatch several distinct actions; a shared unkeyed slot handed the
+ * first action's ordinal to every later one, silently skipping their own
+ * name-scoped counters and aliasing a later independent dispatch onto an
+ * in-block key (issue #84).
+ *
+ * Each scope pins a *sequence* of ordinals rather than a single value
+ * (issue #100): one retry block may dispatch the same declaration several
+ * times, and a single-valued slot handed the first dispatch's ordinal to
+ * every later one, so the second dispatch silently replayed the first's
+ * recorded outcome. `cursors` counts the dispatches of each scope within the
+ * current attempt — `Action.retry` resets it at every attempt boundary —
+ * so the n-th same-scope dispatch of every attempt reuses the n-th pinned
+ * ordinal.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export interface OrdinalSlot {
+  readonly values: Map<string, Array<number>>
+  readonly cursors: Map<string, number>
+}
+
+/**
+ * Context reference carrying the ordinal slot of the enclosing
+ * `Action.retry` sequence, when present.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export const CurrentOrdinal = Context.Reference<OrdinalSlot | undefined>(
+  "@smthrs/flow/Action/CurrentOrdinal",
+  { defaultValue: () => undefined }
+)
+
+/**
+ * Context reference containing the current action retry attempt, defaulting
+ * to `1`.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export const CurrentAttempt = Context.Reference<number>(
+  "@smthrs/flow/Action/CurrentAttempt",
+  { defaultValue: () => 1 }
+)
+
+/**
+ * Context reference carrying the persisted key of the dispatch an
+ * implementation is currently running under, when the runtime supplies one.
+ *
+ * **When to use**
+ *
+ * Use it in an action implementation that has to name durable state of its
+ * own — `Sleep` names a `DurableClock` — so the name it derives belongs to
+ * THIS dispatch. The key is the identity the engine already allocated for the
+ * dispatch: its attempt rows, its recorded outcome, and its cache row are
+ * addressed by it, so it is stable across every replay of one node and
+ * distinct between two identical calls of the same declaration. Deriving from
+ * it is therefore the only way an implementation gets both properties without
+ * allocating a second identity beside the engine's.
+ *
+ * **Gotchas**
+ *
+ * A runtime that has not adopted the seam leaves the reference absent rather
+ * than substituting a placeholder, because a placeholder would silently alias
+ * every dispatch of one declaration onto one name. An implementation that
+ * needs durable identity refuses instead.
+ *
+ * @category idempotency
+ * @since 0.1.0
+ */
+export const CurrentInvocationKey = Context.Reference<string | undefined>(
+  "@smthrs/flow/Action/CurrentInvocationKey",
+  { defaultValue: () => undefined }
+)
+
+/**
+ * Context reference carrying the heartbeat of the attempt currently running,
+ * which the runtime installs for an action declared with
+ * `heartbeatTimeoutMs`. Outside such an attempt it does nothing.
+ *
+ * @category attempts
+ * @since 1.0.0
+ */
+export const CurrentHeartbeat = Context.Reference<Effect.Effect<void>>(
+  "@smthrs/flow/Action/CurrentHeartbeat",
+  { defaultValue: () => Effect.void }
+)
+
+/**
+ * Reports that the running action attempt is still making progress.
+ *
+ * An action declared with `heartbeatTimeoutMs` fails its attempt with
+ * `AttemptTimedOut` when that long passes without a heartbeat; each call
+ * restarts the gap. In any other action it is a no-op.
+ *
+ * @category attempts
+ * @since 1.0.0
+ */
+export const heartbeat: Effect.Effect<void> = Effect.gen(function*() {
+  const beat = yield* CurrentHeartbeat
+  yield* beat
+})

package/src/Action/DuplicateImplementation.ts

@@ -0,0 +1,24 @@
+/**
+ * Defines the `DuplicateImplementation` action failure.
+ *
+ * @since 0.1.0
+ */
+
+import * as Schema from "effect/Schema"
+
+/**
+ * Two implementations competed for one action tag without an explicit override.
+ * @category errors
+ * @since 0.1.0
+ */
+export class DuplicateImplementation extends Schema.TaggedError<DuplicateImplementation>()(
+  "@smthrs/flow/Action/DuplicateImplementation",
+  { name: Schema.String }
+) {
+  // The `name` field shadows `Error.name`, so without a message a recorded
+  // defect reads only as the bare action tag.
+  /** @since 1.0.0 */
+  override get message(): string {
+    return `Action "${this.name}" already has an implementation in this registry; provide its layer once, or pass override: true to replace it`
+  }
+}

package/src/Action/FileBoundary.ts

@@ -0,0 +1,77 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * An action's declaration of which files it reads and which it may write.
+ *
+ * The declaration is what makes a step hermetic enough to cache: the read set
+ * is the dependency edge set folded into the step key, and the write set is
+ * what the host measures the execution against afterwards. `boundaryMode`
+ * decides what happens when the two disagree — a hard boundary refuses the
+ * result, an expected one records the deviation and carries on.
+ *
+ * @since 0.1.0
+ */
+
+import * as FileSet from "@smthrs/plan/FileSet"
+import * as Schema from "effect/Schema"
+import { BoundaryMode } from "./BoundaryMode.ts"
+import { FileInput } from "./FileInput.ts"
+
+/**
+ * Schema for the filesystem boundary of an action.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const FileBoundary = Schema.Struct({
+  /**
+   * Exact files already measured, or globs to expand while preparing.
+   *
+   * Workspace-relative in both forms: a measured {@link FileInput} path is
+   * checked like every pattern, because the engine measures reads inside the
+   * workspace sandbox and would refuse an absolute or upward path only at
+   * prepare time.
+   */
+  readSet: Schema.Array(Schema.Union([FileInput, FileSet.Glob])),
+  /** Files or patterns the action is allowed to write. */
+  writeSet: Schema.Array(FileSet.Entry),
+  /**
+   * Files the action is allowed to DELETE.
+   *
+   * A declared write that is absent when the action finishes is a defect —
+   * Bazel's `SkyframeActionExecutor.checkOutputs` reports "output was not
+   * created" and fails the action — because recording the absence as valid
+   * evidence caches the claim "this file should not exist", which a later
+   * replay then acts on by deleting the path. Deletion stays a feature here,
+   * but only when it was declared, and a declared removal is what makes an
+   * absent path legitimate rather than a crash mid-execution.
+   *
+   * Optional with an empty default, so boundaries persisted before it keep
+   * decoding. Disjoint from {@link writeSet}: a path cannot be both promised
+   * and disclaimed. Workspace-relative like every other declared path —
+   * replay acts on a removal by deleting it, so an absolute or upward
+   * spelling would hand evidence an eraser aimed outside the workspace.
+   */
+  removes: Schema.optional(Schema.Array(FileSet.Pattern)),
+  /** Whether undeclared access is rejected immediately or validated later. */
+  boundaryMode: BoundaryMode
+}).check(
+  Schema.makeFilter(
+    (boundary) => {
+      const both = (boundary.removes ?? []).filter((path) =>
+        boundary.writeSet.some((entry) => FileSet.overlaps(entry, path))
+      )
+      return both.length === 0 ||
+        `a path cannot be both written and removed: ${both.join(", ")}`
+    },
+    { title: "disjointWritesAndRemoves" }
+  )
+)
+
+/**
+ * The filesystem boundary of an action.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type FileBoundary = typeof FileBoundary.Type

package/src/Action/FileInput.ts

@@ -0,0 +1,42 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * A file path paired with the digest measured for its contents.
+ *
+ * Paths alone cannot key a step — the same path holds different bytes on
+ * different days — so every declared read carries the digest observed for it,
+ * and a later run compares digests rather than mtimes.
+ *
+ * @since 0.1.0
+ */
+
+import * as FileSet from "@smthrs/plan/FileSet"
+import * as Schema from "effect/Schema"
+
+/**
+ * Schema for an input file path paired with its measured content digest.
+ *
+ * The path is workspace-relative like every other declared path in a
+ * {@link FileBoundary}: the engine measures reads through the workspace
+ * sandbox, which refuses absolute and upward spellings, so a boundary that
+ * admitted them here would only be refused later, at prepare or replay.
+ * Checking here keeps the boundary this package admits the boundary the
+ * engine accepts.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const FileInput = Schema.Struct({
+  /** Workspace-relative path of the input file. */
+  path: FileSet.Pattern,
+  /** Non-empty digest observed for the file contents. */
+  digest: Schema.NonEmptyString
+})
+
+/**
+ * An input file path paired with its measured content digest.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type FileInput = typeof FileInput.Type

package/src/Action/Filegroup.ts

@@ -0,0 +1,16 @@
+/**
+ * Named reusable filesystem declaration groups.
+ *
+ * @since 0.1.0
+ */
+
+import { Filegroup, makeFilegroup } from "@smthrs/plan/FileSet"
+export { Filegroup }
+export type { Filegroup as Type } from "@smthrs/plan/FileSet"
+/**
+ * Creates a named filegroup.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = makeFilegroup

package/src/Action/Glob.ts

@@ -0,0 +1,8 @@
+/**
+ * Bazel-style workspace-relative file glob declarations.
+ *
+ * @since 0.1.0
+ */
+
+export { Glob, matchesGlob, matchesPattern, Pattern } from "@smthrs/plan/FileSet"
+export type { Glob as Type } from "@smthrs/plan/FileSet"

package/src/Action/ImplementationVersionMismatch.ts

@@ -0,0 +1,27 @@
+/**
+ * Defines the `ImplementationVersionMismatch` action failure.
+ *
+ * The `_tag` string was settled under `@smthrs/flow/` for 1.0.0-rc.0. The RC
+ * makes no compatibility promise to 0.x journals, and the tag freezes when
+ * the RC ships.
+ *
+ * @since 0.1.0
+ */
+
+import * as Schema from "effect/Schema"
+
+/**
+ * A handler registration does not attest the declaration's implementation version.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class ImplementationVersionMismatch extends Schema.TaggedError<ImplementationVersionMismatch>()(
+  "@smthrs/flow/ImplementationVersionMismatch",
+  {
+    actionName: Schema.String,
+    declaredVersion: Schema.NullOr(Schema.String),
+    registeredVersion: Schema.NullOr(Schema.String),
+    message: Schema.String
+  }
+) {}