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

package/dist/cjs/Action/CacheEnvironment.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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";
+/**
+ * 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 declare const CacheEnvironment: Schema.Struct<{
+    /** Ordered semantic runtime layers, including versions and configuration. */
+    readonly layers: Schema.$Array<Schema.NonEmptyString>;
+    /** Complete effective capability groups. */
+    readonly capabilities: Schema.$Record<Schema.String, Schema.$Array<Schema.NonEmptyString>>;
+}>;
+/**
+ * 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 declare const CacheScope: Schema.Literals<readonly ["run", "flow", "shared"]>;
+/**
+ * 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 declare const CachePolicy: Schema.Struct<{
+    readonly ttlMs: Schema.optionalKey<Schema.Int>;
+    readonly scope: Schema.optionalKey<Schema.Literals<readonly ["run", "flow", "shared"]>>;
+}>;
+/**
+ * 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 declare const CachePolicyAnnotation: import("effect/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 0.1.0
+ */
+export declare const cachePolicyOf: (annotations: import("effect/Context").Context<never>) => PlanCachePolicy.CachePolicy | undefined;
+/**
+ * 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 declare const withCache: <A extends {
+    annotate: (key: typeof PlanCachePolicy.CachePolicyAnnotation, value: PlanCachePolicy.CachePolicy) => A;
+}>(declaration: A, policy: PlanCachePolicy.CachePolicy) => A;
+//# sourceMappingURL=CacheEnvironment.d.ts.map

package/dist/cjs/Action/CacheEnvironment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheEnvironment.d.ts","sourceRoot":"","sources":["../../../src/Action/CacheEnvironment.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,eAAe,MAAM,0BAA0B,CAAA;AAC3D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAcvC;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;IAC3B,6EAA6E;;IAE7E,4CAA4C;;EAE5C,CAAA;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,qDAA6B,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,CAAC,UAAU,CAAA;AAEnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW;;;EAA8B,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC,WAAW,CAAA;AAErD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB;;;;;;EAAwC,CAAA;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,mGAAgC,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,SAAS;;4DAA2B,CAAA"}

package/dist/cjs/Action/CacheEnvironment.js

@@ -0,0 +1,57 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var CacheEnvironment_exports = {};
+__export(CacheEnvironment_exports, {
+  CacheEnvironment: () => CacheEnvironment,
+  CachePolicy: () => CachePolicy,
+  CachePolicyAnnotation: () => CachePolicyAnnotation,
+  CacheScope: () => CacheScope,
+  cachePolicyOf: () => cachePolicyOf,
+  withCache: () => withCache
+});
+module.exports = __toCommonJS(CacheEnvironment_exports);
+var PlanCachePolicy = __toESM(require("@smthrs/plan/CachePolicy"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+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"
+  )
+);
+const CacheEnvironment = Schema.Struct({
+  /** Ordered semantic runtime layers, including versions and configuration. */
+  layers: Schema.Array(Schema.NonEmptyString),
+  /** Complete effective capability groups. */
+  capabilities: Capabilities
+});
+const CacheScope = PlanCachePolicy.CacheScope;
+const CachePolicy = PlanCachePolicy.CachePolicy;
+const CachePolicyAnnotation = PlanCachePolicy.CachePolicyAnnotation;
+const cachePolicyOf = PlanCachePolicy.cachePolicyOf;
+const withCache = PlanCachePolicy.annotate;
+//# sourceMappingURL=CacheEnvironment.js.map

package/dist/cjs/Action/CacheEnvironment.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Action/CacheEnvironment.ts"],
+  "sourcesContent": ["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * The environment description folded into every cross-run cache key.\n *\n * A cached result is only reusable on a host that would have produced the same\n * bytes, so the key has to name the environment as well as the inputs \u2014 the\n * platform, the toolchain, and the capability groups in force. Bazel's action\n * key does the same thing for the same reason.\n *\n * It is a *complete* value on purpose: an environment a composition cannot\n * fully describe is one whose cache hits cannot be justified, and the engine\n * executes rather than guessing at the missing part.\n *\n * @since 0.1.0\n */\n\nimport * as PlanCachePolicy from \"@smthrs/plan/CachePolicy\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Validates named capability groups.\n *\n * @private\n * @since 0.1.0\n */\nconst Capabilities = Schema.Record(Schema.String, Schema.Array(Schema.NonEmptyString)).check(\n  Schema.makeFilter((capabilities) =>\n    Object.keys(capabilities).every((name) => name.length > 0) || \"Capability names must not be empty\"\n  )\n)\n\n/**\n * Complete runtime environment included in every cross-run cache key.\n *\n * If a composition cannot provide this complete value, the engine executes\n * normally but does not derive a cross-run cache key.\n *\n * @category models\n * @since 0.1.0\n */\nexport type CacheEnvironment = typeof CacheEnvironment.Type\n\n/**\n * Schema for the complete runtime environment included in cache keys.\n *\n * @category models\n * @since 0.1.0\n */\nexport const CacheEnvironment = Schema.Struct({\n  /** Ordered semantic runtime layers, including versions and configuration. */\n  layers: Schema.Array(Schema.NonEmptyString),\n  /** Complete effective capability groups. */\n  capabilities: Capabilities\n})\n\n/**\n * How far a recorded sealed result may travel.\n *\n * `shared` is the content-addressed default: the key names the inputs and the\n * environment, so any run on any host that would have produced the same bytes\n * may reuse the row. `run` and `flow` narrow that on purpose \u2014 a step whose\n * result is only meaningful inside one execution, or inside one flow, folds\n * that identity into its key so a sibling never reads it.\n *\n * This is `@smthrs/plan`'s `CachePolicy.CacheScope`, the one scope vocabulary\n * `@smthrs/patterns` also declares its policy with.\n *\n * @category models\n * @since 0.1.0\n */\nexport const CacheScope = PlanCachePolicy.CacheScope\n\n/**\n * How far a recorded sealed result may travel.\n *\n * @category models\n * @since 0.1.0\n */\nexport type CacheScope = PlanCachePolicy.CacheScope\n\n/**\n * The caller's declaration about the decay and the reach of a sealed action's\n * recorded 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 * This is `@smthrs/plan`'s `CachePolicy.CachePolicy`, the one policy schema.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const CachePolicy = PlanCachePolicy.CachePolicy\n\n/**\n * The caller's declaration about the decay and the reach of a sealed action's\n * recorded result.\n *\n * @category models\n * @since 0.1.0\n */\nexport type CachePolicy = PlanCachePolicy.CachePolicy\n\n/**\n * Annotation key carrying a declaration's {@link CachePolicy}.\n *\n * It is an annotation, not a field on the action, 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 * It is `@smthrs/plan`'s `CachePolicy.CachePolicyAnnotation` itself, the same\n * object `@smthrs/patterns` annotates a flow with, identified by\n * `\"@smthrs/flow/Action/CachePolicy\"`.\n *\n * @category annotations\n * @since 0.1.0\n */\nexport const CachePolicyAnnotation = PlanCachePolicy.CachePolicyAnnotation\n\n/**\n * Reads the cache policy an annotation bag carries, or `undefined` when it\n * carries none.\n *\n * @category getters\n * @since 0.1.0\n */\nexport const cachePolicyOf = PlanCachePolicy.cachePolicyOf\n\n/**\n * Declares a cache policy on an action.\n *\n * This is the form the engine honors today: `@smthrs/engine-store` reads\n * {@link CachePolicyAnnotation} off the dispatched action, bounds the age of\n * the row it may serve by `ttlMs`, and narrows the address that row is stored\n * under from `scope`. `@smthrs/patterns`' `WithCache` declares the same policy\n * over a `@smthrs/core` flow under the same annotation key, for the\n * declaration surface, so a policy written by either is read by the engine.\n *\n * The action is not mutated. `annotate` returns a new declaration carrying the\n * policy, which is what a plan captures.\n *\n * It is `@smthrs/plan`'s `CachePolicy.annotate` under this package's name for\n * it.\n *\n * @example\n * ```ts\n * import { Action } from \"@smthrs/flow\"\n * import * as CacheEnvironment from \"@smthrs/flow/CacheEnvironment\"\n * import * as Effect from \"effect/Effect\"\n * import * as Schema from \"effect/Schema\"\n *\n * const compile = CacheEnvironment.withCache(\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 0.1.0\n */\nexport const withCache = PlanCachePolicy.annotate\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBA,sBAAiC;AACjC,aAAwB;AAQxB,MAAM,eAAe,OAAO,OAAO,OAAO,QAAQ,OAAO,MAAM,OAAO,cAAc,CAAC,EAAE;AAAA,EACrF,OAAO;AAAA,IAAW,CAAC,iBACjB,OAAO,KAAK,YAAY,EAAE,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,KAAK;AAAA,EAChE;AACF;AAmBO,MAAM,mBAAmB,OAAO,OAAO;AAAA;AAAA,EAE5C,QAAQ,OAAO,MAAM,OAAO,cAAc;AAAA;AAAA,EAE1C,cAAc;AAChB,CAAC;AAiBM,MAAM,aAAa,gBAAgB;AAwBnC,MAAM,cAAc,gBAAgB;AA0BpC,MAAM,wBAAwB,gBAAgB;AAS9C,MAAM,gBAAgB,gBAAgB;AAuCtC,MAAM,YAAY,gBAAgB;",
+  "names": []
+}

package/dist/cjs/Action/ConcurrentKeylessDispatch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 Schema from "effect/Schema";
+declare const ConcurrentKeylessDispatch_base: Schema.Class<ConcurrentKeylessDispatch, Schema.TaggedStruct<"@smthrs/flow/ConcurrentKeylessDispatch", {
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"concurrent_keyless_dispatch">>;
+    readonly actionName: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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 declare class ConcurrentKeylessDispatch extends ConcurrentKeylessDispatch_base {
+}
+export {};
+//# sourceMappingURL=ConcurrentKeylessDispatch.d.ts.map

package/dist/cjs/Action/ConcurrentKeylessDispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConcurrentKeylessDispatch.d.ts","sourceRoot":"","sources":["../../../src/Action/ConcurrentKeylessDispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,yBAA0B,SAAQ,8BAQ9C;CAAG"}

package/dist/cjs/Action/ConcurrentKeylessDispatch.js

@@ -0,0 +1,46 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ConcurrentKeylessDispatch_exports = {};
+__export(ConcurrentKeylessDispatch_exports, {
+  ConcurrentKeylessDispatch: () => ConcurrentKeylessDispatch
+});
+module.exports = __toCommonJS(ConcurrentKeylessDispatch_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+class ConcurrentKeylessDispatch extends Schema.TaggedError()(
+  "@smthrs/flow/ConcurrentKeylessDispatch",
+  {
+    code: Schema.Literal("concurrent_keyless_dispatch").pipe(
+      Schema.withConstructorDefault(Effect.succeed("concurrent_keyless_dispatch"))
+    ),
+    actionName: Schema.String
+  }
+) {
+}
+//# sourceMappingURL=ConcurrentKeylessDispatch.js.map

package/dist/cjs/Action/ConcurrentKeylessDispatch.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Action/ConcurrentKeylessDispatch.ts"],
+  "sourcesContent": ["/**\n * Defines the `ConcurrentKeylessDispatch` action failure.\n *\n * The `_tag` string was settled under `@smthrs/flow/` for 1.0.0-rc.0. The RC\n * makes no compatibility promise to 0.x journals, and the tag freezes when\n * the RC ships.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Two ordinal-keyed invocations of one allocation scope were in flight\n * concurrently, either keyless invocations of one declaration or same-key\n * invocations at a non-sealed tier (issue #130), so their ordinals, and with\n * them their step keys, attempt rows, and recorded outcomes, would be\n * assigned by fiber arrival order. A crash-resume that replays the fibers in\n * the opposite order would silently hand one invocation the other's recorded\n * outcome (issue #111); Temporal fails such replays with a nondeterminism\n * error, and the engine refuses the hazard up front instead of detecting it\n * after the corruption. Declare an `idempotencyKey` *distinguishing* the\n * invocations to dispatch them concurrently; a sealed action with a key\n * takes a pure cache key and is exempt.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class ConcurrentKeylessDispatch extends Schema.TaggedError<ConcurrentKeylessDispatch>()(\n  \"@smthrs/flow/ConcurrentKeylessDispatch\",\n  {\n    code: Schema.Literal(\"concurrent_keyless_dispatch\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"concurrent_keyless_dispatch\"))\n    ),\n    actionName: Schema.String\n  }\n) {}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,aAAwB;AACxB,aAAwB;AAkBjB,MAAM,kCAAkC,OAAO,YAAuC;AAAA,EAC3F;AAAA,EACA;AAAA,IACE,MAAM,OAAO,QAAQ,6BAA6B,EAAE;AAAA,MAClD,OAAO,uBAAuB,OAAO,QAAQ,6BAA6B,CAAC;AAAA,IAC7E;AAAA,IACA,YAAY,OAAO;AAAA,EACrB;AACF,EAAE;AAAC;",
+  "names": []
+}

package/dist/cjs/Action/Context.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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 declare const CurrentCacheEnvironment: Context.Reference<{
+    readonly layers: readonly string[];
+    readonly capabilities: {
+        readonly [x: string]: readonly string[];
+    };
+} | 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 declare const layerCacheEnvironment: (environment: CacheEnvironment) => Layer.Layer<never>;
+/**
+ * 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 declare const CurrentOrdinal: Context.Reference<OrdinalSlot | undefined>;
+/**
+ * Context reference containing the current action retry attempt, defaulting
+ * to `1`.
+ *
+ * @category attempts
+ * @since 0.1.0
+ */
+export declare const CurrentAttempt: Context.Reference<number>;
+/**
+ * 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 declare const CurrentInvocationKey: Context.Reference<string | 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 declare const CurrentHeartbeat: Context.Reference<Effect.Effect<void, never, never>>;
+/**
+ * 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 declare const heartbeat: Effect.Effect<void>;
+//# sourceMappingURL=Context.d.ts.map

package/dist/cjs/Action/Context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Context.d.ts","sourceRoot":"","sources":["../../../src/Action/Context.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE7D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB;;;;;cAGnC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,aAAa,gBAAgB,KAC5B,KAAK,CAAC,KAAK,CAAC,KAAK,CAAwD,CAAA;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;IAC3C,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACtC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4CAG1B,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,2BAG1B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,uCAGhC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,sDAG5B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAGxC,CAAA"}

package/dist/cjs/Action/Context.js

@@ -0,0 +1,68 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Context_exports = {};
+__export(Context_exports, {
+  CurrentAttempt: () => CurrentAttempt,
+  CurrentCacheEnvironment: () => CurrentCacheEnvironment,
+  CurrentHeartbeat: () => CurrentHeartbeat,
+  CurrentInvocationKey: () => CurrentInvocationKey,
+  CurrentOrdinal: () => CurrentOrdinal,
+  heartbeat: () => heartbeat,
+  layerCacheEnvironment: () => layerCacheEnvironment
+});
+module.exports = __toCommonJS(Context_exports);
+var Context = __toESM(require("effect/Context"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+const CurrentCacheEnvironment = Context.Reference(
+  "@smthrs/flow/Action/CurrentCacheEnvironment",
+  { defaultValue: () => void 0 }
+);
+const layerCacheEnvironment = (environment) => Layer.succeed(CurrentCacheEnvironment)(environment);
+const CurrentOrdinal = Context.Reference(
+  "@smthrs/flow/Action/CurrentOrdinal",
+  { defaultValue: () => void 0 }
+);
+const CurrentAttempt = Context.Reference(
+  "@smthrs/flow/Action/CurrentAttempt",
+  { defaultValue: () => 1 }
+);
+const CurrentInvocationKey = Context.Reference(
+  "@smthrs/flow/Action/CurrentInvocationKey",
+  { defaultValue: () => void 0 }
+);
+const CurrentHeartbeat = Context.Reference(
+  "@smthrs/flow/Action/CurrentHeartbeat",
+  { defaultValue: () => Effect.void }
+);
+const heartbeat = Effect.gen(function* () {
+  const beat = yield* CurrentHeartbeat;
+  yield* beat;
+});
+//# sourceMappingURL=Context.js.map

package/dist/cjs/Action/Context.js.map

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

package/dist/cjs/Action/DuplicateImplementation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Defines the `DuplicateImplementation` action failure.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+declare const DuplicateImplementation_base: Schema.Class<DuplicateImplementation, Schema.TaggedStruct<"@smthrs/flow/Action/DuplicateImplementation", {
+    readonly name: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Two implementations competed for one action tag without an explicit override.
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class DuplicateImplementation extends DuplicateImplementation_base {
+    /** @since 1.0.0 */
+    get message(): string;
+}
+export {};
+//# sourceMappingURL=DuplicateImplementation.d.ts.map

package/dist/cjs/Action/DuplicateImplementation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DuplicateImplementation.d.ts","sourceRoot":"","sources":["../../../src/Action/DuplicateImplementation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;AAEvC;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,4BAG5C;IAGC,mBAAmB;IACnB,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF"}

package/dist/cjs/Action/DuplicateImplementation.js

@@ -0,0 +1,46 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var DuplicateImplementation_exports = {};
+__export(DuplicateImplementation_exports, {
+  DuplicateImplementation: () => DuplicateImplementation
+});
+module.exports = __toCommonJS(DuplicateImplementation_exports);
+var Schema = __toESM(require("effect/Schema"), 1);
+class DuplicateImplementation extends Schema.TaggedError()(
+  "@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 */
+  get message() {
+    return `Action "${this.name}" already has an implementation in this registry; provide its layer once, or pass override: true to replace it`;
+  }
+}
+//# sourceMappingURL=DuplicateImplementation.js.map

package/dist/cjs/Action/DuplicateImplementation.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Action/DuplicateImplementation.ts"],
+  "sourcesContent": ["/**\n * Defines the `DuplicateImplementation` action failure.\n *\n * @since 0.1.0\n */\n\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Two implementations competed for one action tag without an explicit override.\n * @category errors\n * @since 0.1.0\n */\nexport class DuplicateImplementation extends Schema.TaggedError<DuplicateImplementation>()(\n  \"@smthrs/flow/Action/DuplicateImplementation\",\n  { name: Schema.String }\n) {\n  // The `name` field shadows `Error.name`, so without a message a recorded\n  // defect reads only as the bare action tag.\n  /** @since 1.0.0 */\n  override get message(): string {\n    return `Action \"${this.name}\" already has an implementation in this registry; provide its layer once, or pass override: true to replace it`\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,aAAwB;AAOjB,MAAM,gCAAgC,OAAO,YAAqC;AAAA,EACvF;AAAA,EACA,EAAE,MAAM,OAAO,OAAO;AACxB,EAAE;AAAA;AAAA;AAAA;AAAA,EAIA,IAAa,UAAkB;AAC7B,WAAO,WAAW,KAAK,IAAI;AAAA,EAC7B;AACF;",
+  "names": []
+}