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

package/dist/cjs/Flow/Annotations.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Flow/Annotations.ts"],
+  "sourcesContent": ["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Execution policies attached to flow definitions through Effect context.\n *\n * @since 0.1.0\n */\n\nimport * as PlanEffects from \"@smthrs/plan/Effects\"\nimport * as PlanPlacement from \"@smthrs/plan/Placement\"\nimport * as Plan from \"@smthrs/plan/Plan\"\nimport * as Context from \"effect/Context\"\nimport { constFalse, constTrue } from \"effect/Function\"\n\n/**\n * Declared filesystem effects: the plan node effect contract itself.\n *\n * This is `@smthrs/plan`'s `Plan.NodeEffects`, not a copy of it. The two were\n * field-for-field identical structs in two packages, which meant a change to\n * one silently stopped `Plan.compile` decoding what this package wrote.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Effects = Plan.NodeEffects\n\n/**\n * The value form of {@link Effects}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Effects = Plan.NodeEffects\n\n/**\n * A directive naming where a node runs, carried unchanged until planning.\n *\n * This is `@smthrs/plan`'s `Placement.Placement`, the one typed model. It was\n * `Schema.Unknown` here while `@smthrs/core` held a four-variant enum of the\n * same thing, which made every crossing a cast.\n *\n * @category models\n * @since 0.1.0\n */\nexport type PlacementDirective = PlanPlacement.Placement\n\n/**\n * Capability ceiling. An omitted annotation inherits; an explicit empty array denies.\n * The reference default remains an empty metadata projection for catalog readers;\n * execution distinguishes an absent annotation from an explicitly stored one.\n *\n * @category annotations\n * @since 0.1.0\n */\nexport const Capabilities = Context.Reference<ReadonlyArray<string>>(\n  \"@smthrs/flow/Flow/Capabilities\",\n  { defaultValue: () => [] }\n)\n\n/**\n * Required annotation key for a flow's declared filesystem effects.\n *\n * @category annotations\n * @since 0.1.0\n */\nexport const EffectsDeclaration = Context.Service<Effects>(\"@smthrs/flow/Flow/EffectsDeclaration\")\n\n/**\n * The effect AUTHORITY a flow declares: the ceiling every step spliced beneath\n * it must stay inside.\n *\n * This is the one envelope model, `@smthrs/plan/Effects`, which `@smthrs/core`\n * re-exports and `@smthrs/patterns` intersects against. It answers a different\n * question from {@link EffectsDeclaration}: that one says which FILES a node\n * touches, so a plan can order writers and a sandbox can enforce a boundary at\n * run time, while this one says how much a flow is ALLOWED to touch, so\n * {@link module:Graph.build} can refuse a composition that claims more than its\n * caller granted.\n *\n * `Flow.make`'s `effects` option writes it, which is what makes it readable by\n * a catalog that projects a declaration without importing this module.\n *\n * @category annotations\n * @since 0.1.0\n */\nexport const EffectEnvelope = PlanEffects.Envelope\n\n/**\n * Required annotation key for a flow's schema-encodable placement directive.\n *\n * @category annotations\n * @since 0.1.0\n */\nexport const Placement = PlanPlacement.Annotation\n\n/**\n * Captures defects for a flow and includes them in the result of the flow or its actions.\n *\n * **Details**\n *\n * By default, this annotation is set to `true`, meaning defects are captured.\n *\n * @category annotations\n * @since 0.1.0\n */\nexport const CaptureDefects = Context.Reference<boolean>(\n  \"@smthrs/flow/Flow/CaptureDefects\",\n  {\n    defaultValue: constTrue\n  }\n)\n\n/**\n * Whether a catalog may offer this flow to a model, defaulting to yes.\n *\n * It answers a different question from {@link Capabilities}: that one says how\n * much a flow is allowed to touch, this one says whether a model is shown the\n * flow at all. A flow whose actions only one host implements is discoverable\n * everywhere its file is, and teaching it to an agent running somewhere else\n * offers a call that has no implementation to reach.\n *\n * `Flow.make`'s `modelInvocable` option writes it, which is what makes it\n * readable by a catalog that projects a declaration from source text without\n * importing this module, exactly as `capabilities` and `effects` are.\n *\n * @category annotations\n * @since 0.1.0\n */\nexport const ModelInvocable = Context.Reference<boolean>(\n  \"@smthrs/flow/Flow/ModelInvocable\",\n  {\n    defaultValue: constTrue\n  }\n)\n\n/**\n * Marks a flow to suspend when it encounters any error.\n *\n * **Details**\n *\n * The suspended execution can later be resumed with the flow's `resume` method, for example `MyFlow.resume(executionId)`.\n *\n * @category annotations\n * @since 0.1.0\n */\nexport const SuspendOnFailure = Context.Reference<boolean>(\n  \"@smthrs/flow/Flow/SuspendOnFailure\",\n  {\n    defaultValue: constFalse\n  }\n)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,kBAA6B;AAC7B,oBAA+B;AAC/B,WAAsB;AACtB,cAAyB;AACzB,sBAAsC;AAY/B,MAAM,UAAU,KAAK;AA8BrB,MAAM,eAAe,QAAQ;AAAA,EAClC;AAAA,EACA,EAAE,cAAc,MAAM,CAAC,EAAE;AAC3B;AAQO,MAAM,qBAAqB,QAAQ,QAAiB,sCAAsC;AAoB1F,MAAM,iBAAiB,YAAY;AAQnC,MAAM,YAAY,cAAc;AAYhC,MAAM,iBAAiB,QAAQ;AAAA,EACpC;AAAA,EACA;AAAA,IACE,cAAc;AAAA,EAChB;AACF;AAkBO,MAAM,iBAAiB,QAAQ;AAAA,EACpC;AAAA,EACA;AAAA,IACE,cAAc;AAAA,EAChB;AACF;AAYO,MAAM,mBAAmB,QAAQ;AAAA,EACtC;AAAA,EACA;AAAA,IACE,cAAc;AAAA,EAChB;AACF;",
+  "names": []
+}

package/dist/cjs/Flow/CapabilityCeiling.d.ts

@@ -0,0 +1,21 @@
+/** Declared capability ceilings shared by planning and execution.
+ * @since 1.0.0
+ */
+import * as Capability from "@smthrs/capability/Capability";
+import * as Context from "effect/Context";
+/** Returns only explicitly declared ceilings; omission inherits.
+ * @category accessors
+ * @since 1.0.0
+ */
+export declare const capabilityCeilings: (annotations: Context.Context<never>) => ReadonlyArray<ReadonlyArray<string>>;
+/** Parses declaration patterns into ceiling groups. Invalid patterns are dropped, so they deny.
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const parseCapabilityCeilings: (groups: ReadonlyArray<ReadonlyArray<string>>) => ReadonlyArray<ReadonlyArray<Capability.CapabilityPattern>>;
+/** Applies declaration patterns as an exact conjunction. Invalid patterns deny.
+ * @category combinators
+ * @since 1.0.0
+ */
+export declare const attenuateCapabilities: (groups: ReadonlyArray<ReadonlyArray<string>>) => <A, E, R>(effect: import("effect/Effect").Effect<A, E, R>) => import("effect/Effect").Effect<A, E, R>;
+//# sourceMappingURL=CapabilityCeiling.d.ts.map

package/dist/cjs/Flow/CapabilityCeiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityCeiling.d.ts","sourceRoot":"","sources":["../../../src/Flow/CapabilityCeiling.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,UAAU,MAAM,+BAA+B,CAAA;AAE3D,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAIzC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,aAAa,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CACf,CAAA;AAE7F;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,KAC3C,aAAa,CAAC,aAAa,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAMzD,CAAA;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,0GAClB,CAAA"}

package/dist/cjs/Flow/CapabilityCeiling.js

@@ -0,0 +1,49 @@
+"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 CapabilityCeiling_exports = {};
+__export(CapabilityCeiling_exports, {
+  attenuateCapabilities: () => attenuateCapabilities,
+  capabilityCeilings: () => capabilityCeilings,
+  parseCapabilityCeilings: () => parseCapabilityCeilings
+});
+module.exports = __toCommonJS(CapabilityCeiling_exports);
+var Capability = __toESM(require("@smthrs/capability/Capability"), 1);
+var CapabilitySet = __toESM(require("@smthrs/capability/CapabilitySet"), 1);
+var Context = __toESM(require("effect/Context"), 1);
+var Option = __toESM(require("effect/Option"), 1);
+var import_Annotations = require("./Annotations.js");
+const capabilityCeilings = (annotations) => annotations.mapUnsafe.has(import_Annotations.Capabilities.key) ? [Context.get(annotations, import_Annotations.Capabilities)] : [];
+const parseCapabilityCeilings = (groups) => groups.map(
+  (group) => group.flatMap((text) => {
+    const parsed = Capability.parsePattern(text);
+    return Option.isSome(parsed) ? [parsed.value] : [];
+  })
+);
+const attenuateCapabilities = (groups) => CapabilitySet.attenuateGroups(parseCapabilityCeilings(groups));
+//# sourceMappingURL=CapabilityCeiling.js.map

package/dist/cjs/Flow/CapabilityCeiling.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Flow/CapabilityCeiling.ts"],
+  "sourcesContent": ["/** Declared capability ceilings shared by planning and execution.\n * @since 1.0.0\n */\n\nimport * as Capability from \"@smthrs/capability/Capability\"\nimport * as CapabilitySet from \"@smthrs/capability/CapabilitySet\"\nimport * as Context from \"effect/Context\"\nimport * as Option from \"effect/Option\"\nimport { Capabilities } from \"./Annotations.ts\"\n\n/** Returns only explicitly declared ceilings; omission inherits.\n * @category accessors\n * @since 1.0.0\n */\nexport const capabilityCeilings = (annotations: Context.Context<never>): ReadonlyArray<ReadonlyArray<string>> =>\n  annotations.mapUnsafe.has(Capabilities.key) ? [Context.get(annotations, Capabilities)] : []\n\n/** Parses declaration patterns into ceiling groups. Invalid patterns are dropped, so they deny.\n * @category constructors\n * @since 1.0.0\n */\nexport const parseCapabilityCeilings = (\n  groups: ReadonlyArray<ReadonlyArray<string>>\n): ReadonlyArray<ReadonlyArray<Capability.CapabilityPattern>> =>\n  groups.map((group) =>\n    group.flatMap((text) => {\n      const parsed = Capability.parsePattern(text)\n      return Option.isSome(parsed) ? [parsed.value] : []\n    })\n  )\n\n/** Applies declaration patterns as an exact conjunction. Invalid patterns deny.\n * @category combinators\n * @since 1.0.0\n */\nexport const attenuateCapabilities = (groups: ReadonlyArray<ReadonlyArray<string>>) =>\n  CapabilitySet.attenuateGroups(parseCapabilityCeilings(groups))\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,iBAA4B;AAC5B,oBAA+B;AAC/B,cAAyB;AACzB,aAAwB;AACxB,yBAA6B;AAMtB,MAAM,qBAAqB,CAAC,gBACjC,YAAY,UAAU,IAAI,gCAAa,GAAG,IAAI,CAAC,QAAQ,IAAI,aAAa,+BAAY,CAAC,IAAI,CAAC;AAMrF,MAAM,0BAA0B,CACrC,WAEA,OAAO;AAAA,EAAI,CAAC,UACV,MAAM,QAAQ,CAAC,SAAS;AACtB,UAAM,SAAS,WAAW,aAAa,IAAI;AAC3C,WAAO,OAAO,OAAO,MAAM,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC;AAAA,EACnD,CAAC;AACH;AAMK,MAAM,wBAAwB,CAAC,WACpC,cAAc,gBAAgB,wBAAwB,MAAM,CAAC;",
+  "names": []
+}

package/dist/cjs/Flow/DeadlineExceeded.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Defect recorded when an execution runs past its flow's declared deadline.
+ *
+ * @since 1.0.0
+ */
+import * as Schema from "effect/Schema";
+declare const DeadlineExceeded_base: Schema.Class<DeadlineExceeded, Schema.TaggedStruct<"@smthrs/flow/DeadlineExceeded", {
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"deadline_exceeded">>;
+    readonly flowName: Schema.String;
+    readonly executionId: Schema.String;
+    readonly deadlineMs: Schema.Number;
+    readonly startedAtMs: Schema.Number;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An execution was still unsettled when its flow's `deadline` elapsed.
+ *
+ * The deadline counts from the execution's first start, which the engine
+ * journals, so a resume after a restart honors the original deadline rather
+ * than starting a new one. Expiry is terminal: the execution settles with this
+ * defect whether it was running or parked, and its attached children are
+ * cancelled with it. It is not a typed `execute` failure.
+ *
+ * `startedAtMs` is the journaled start and `deadlineMs` the declared bound, so
+ * `startedAtMs + deadlineMs` is when the execution expired.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class DeadlineExceeded extends DeadlineExceeded_base {
+}
+export {};
+//# sourceMappingURL=DeadlineExceeded.d.ts.map

package/dist/cjs/Flow/DeadlineExceeded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeadlineExceeded.d.ts","sourceRoot":"","sources":["../../../src/Flow/DeadlineExceeded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;;;;;;AAGvC;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,SAAQ,qBAYrC;CAAG"}

package/dist/cjs/Flow/DeadlineExceeded.js

@@ -0,0 +1,52 @@
+"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 DeadlineExceeded_exports = {};
+__export(DeadlineExceeded_exports, {
+  DeadlineExceeded: () => DeadlineExceeded
+});
+module.exports = __toCommonJS(DeadlineExceeded_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var Fault = __toESM(require("../Fault.js"), 1);
+class DeadlineExceeded extends Schema.TaggedError()(
+  "@smthrs/flow/DeadlineExceeded",
+  {
+    code: Schema.Literal("deadline_exceeded").pipe(
+      Schema.withConstructorDefault(Effect.succeed("deadline_exceeded"))
+    ),
+    flowName: Schema.String,
+    executionId: Schema.String,
+    deadlineMs: Schema.Number,
+    startedAtMs: Schema.Number,
+    message: Schema.String
+  }
+) {
+}
+Fault.register("@smthrs/flow/DeadlineExceeded", "policy");
+//# sourceMappingURL=DeadlineExceeded.js.map

package/dist/cjs/Flow/DeadlineExceeded.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Flow/DeadlineExceeded.ts"],
+  "sourcesContent": ["/**\n * Defect recorded when an execution runs past its flow's declared deadline.\n *\n * @since 1.0.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport * as Fault from \"../Fault.ts\"\n\n/**\n * An execution was still unsettled when its flow's `deadline` elapsed.\n *\n * The deadline counts from the execution's first start, which the engine\n * journals, so a resume after a restart honors the original deadline rather\n * than starting a new one. Expiry is terminal: the execution settles with this\n * defect whether it was running or parked, and its attached children are\n * cancelled with it. It is not a typed `execute` failure.\n *\n * `startedAtMs` is the journaled start and `deadlineMs` the declared bound, so\n * `startedAtMs + deadlineMs` is when the execution expired.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class DeadlineExceeded extends Schema.TaggedError<DeadlineExceeded>()(\n  \"@smthrs/flow/DeadlineExceeded\",\n  {\n    code: Schema.Literal(\"deadline_exceeded\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"deadline_exceeded\"))\n    ),\n    flowName: Schema.String,\n    executionId: Schema.String,\n    deadlineMs: Schema.Number,\n    startedAtMs: Schema.Number,\n    message: Schema.String\n  }\n) {}\n\nFault.register(\"@smthrs/flow/DeadlineExceeded\", \"policy\")\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,aAAwB;AACxB,aAAwB;AACxB,YAAuB;AAiBhB,MAAM,yBAAyB,OAAO,YAA8B;AAAA,EACzE;AAAA,EACA;AAAA,IACE,MAAM,OAAO,QAAQ,mBAAmB,EAAE;AAAA,MACxC,OAAO,uBAAuB,OAAO,QAAQ,mBAAmB,CAAC;AAAA,IACnE;AAAA,IACA,UAAU,OAAO;AAAA,IACjB,aAAa,OAAO;AAAA,IACpB,YAAY,OAAO;AAAA,IACnB,aAAa,OAAO;AAAA,IACpB,SAAS,OAAO;AAAA,EAClB;AACF,EAAE;AAAC;AAEH,MAAM,SAAS,iCAAiC,QAAQ;",
+  "names": []
+}

package/dist/cjs/Flow/ExecutionIdRequired.d.ts

@@ -0,0 +1,25 @@
+import * as Schema from "effect/Schema";
+declare const ExecutionIdRequired_base: Schema.Class<ExecutionIdRequired, Schema.TaggedStruct<"@smthrs/flow/ExecutionIdRequired", {
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"execution_id_required">>;
+    readonly flowName: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A flow execution has no selected identity.
+ *
+ * The opt-in `derived` execution-id source raises this when the payload
+ * cannot be canonicalized, for example a non-finite number, a lone surrogate,
+ * or a cycle. It dies with it before starting a run, so this is a defect and
+ * not a typed failure a body catches. The default `fresh` source instead
+ * mints a cryptographic UUID for every unkeyed invocation.
+ *
+ * A served resume raises it too: `FlowProxyServer` dies with it when the
+ * `ExecutionIdScope` configured on a layer returns `undefined` for a resume
+ * request, because the client value is not a fallback there.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class ExecutionIdRequired extends ExecutionIdRequired_base {
+}
+export {};
+//# sourceMappingURL=ExecutionIdRequired.d.ts.map

package/dist/cjs/Flow/ExecutionIdRequired.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionIdRequired.d.ts","sourceRoot":"","sources":["../../../src/Flow/ExecutionIdRequired.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,SAAQ,wBAQxC;CAAG"}

package/dist/cjs/Flow/ExecutionIdRequired.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 ExecutionIdRequired_exports = {};
+__export(ExecutionIdRequired_exports, {
+  ExecutionIdRequired: () => ExecutionIdRequired
+});
+module.exports = __toCommonJS(ExecutionIdRequired_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+class ExecutionIdRequired extends Schema.TaggedError()(
+  "@smthrs/flow/ExecutionIdRequired",
+  {
+    code: Schema.Literal("execution_id_required").pipe(
+      Schema.withConstructorDefault(Effect.succeed("execution_id_required"))
+    ),
+    flowName: Schema.String
+  }
+) {
+}
+//# sourceMappingURL=ExecutionIdRequired.js.map

package/dist/cjs/Flow/ExecutionIdRequired.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Flow/ExecutionIdRequired.ts"],
+  "sourcesContent": ["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Failure raised when a flow execution has no explicit or derived identity.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * A flow execution has no selected identity.\n *\n * The opt-in `derived` execution-id source raises this when the payload\n * cannot be canonicalized, for example a non-finite number, a lone surrogate,\n * or a cycle. It dies with it before starting a run, so this is a defect and\n * not a typed failure a body catches. The default `fresh` source instead\n * mints a cryptographic UUID for every unkeyed invocation.\n *\n * A served resume raises it too: `FlowProxyServer` dies with it when the\n * `ExecutionIdScope` configured on a layer returns `undefined` for a resume\n * request, because the client value is not a fallback there.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class ExecutionIdRequired extends Schema.TaggedError<ExecutionIdRequired>()(\n  \"@smthrs/flow/ExecutionIdRequired\",\n  {\n    code: Schema.Literal(\"execution_id_required\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"execution_id_required\"))\n    ),\n    flowName: Schema.String\n  }\n) {}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,aAAwB;AACxB,aAAwB;AAkBjB,MAAM,4BAA4B,OAAO,YAAiC;AAAA,EAC/E;AAAA,EACA;AAAA,IACE,MAAM,OAAO,QAAQ,uBAAuB,EAAE;AAAA,MAC5C,OAAO,uBAAuB,OAAO,QAAQ,uBAAuB,CAAC;AAAA,IACvE;AAAA,IACA,UAAU,OAAO;AAAA,EACnB;AACF,EAAE;AAAC;",
+  "names": []
+}

package/dist/cjs/Flow/ExecutionIds.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The ambient source of execution identity, for a flow executed without one.
+ *
+ * Identity has three sources, in this order: the `executionId` the caller
+ * named, the `idempotencyKey` the flow declared, and — when neither exists —
+ * the source in this module. The first two are decisions an author made at the
+ * call site or the declaration site; the third is a decision the *host* makes
+ * once, for every flow it drives, which is why it is a context reference and
+ * not another option on `execute`.
+ *
+ * The default mints a fresh cryptographic UUID for every unkeyed invocation.
+ * Equal payloads are independent requests. To reattach after a crash, retain
+ * the returned execution id, declare an idempotency key, or explicitly install
+ * the `derived` source. Changing this default does not rewrite stored ids.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { Any } from "./Flow.ts";
+/**
+ * Mints the execution id of an invocation that named none.
+ *
+ * It is consulted only after the two explicit sources are absent, and it runs
+ * before the runtime is read, so a source that cannot name the invocation
+ * fails the execution rather than starting one under a guessed identity.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ExecutionIdSource {
+    readonly mint: <W extends Any>(flow: W, payload: unknown) => Effect.Effect<string, never, Crypto.Crypto | W["payloadSchema"]["EncodingServices"]>;
+}
+/**
+ * An opt-in deterministic source over the flow tag and the payload's
+ * canonical form.
+ *
+ * Same tag and same encoded payload derive the same id, which is exactly the
+ * pair the durable driver already treats as one invocation, so a re-drive of a
+ * crashed program re-attaches to the run it left behind instead of opening a
+ * second one.
+ *
+ * The tag and canonical payload key are JSON-tuple framed before hashing.
+ * Their strings are used exactly as given and encoded as UTF-8, with no Unicode
+ * normalization. This preimage encoding freezes at rc.0.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const derived: ExecutionIdSource;
+/**
+ * Mints independent execution ids for unkeyed requests using host cryptography.
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const fresh: ExecutionIdSource;
+/**
+ * Context reference carrying the host's execution-id source, defaulting to
+ * {@link fresh}.
+ *
+ * @category idempotency
+ * @since 0.1.0
+ */
+export declare const CurrentExecutionIds: Context.Reference<ExecutionIdSource>;
+/**
+ * Declares the host's execution-id source as a layer.
+ *
+ * **When to use**
+ *
+ * Install `derived` when equal payloads deliberately identify the same work,
+ * or provide a host-specific identity source. Explicit caller execution ids
+ * and declared idempotency keys take precedence over this source.
+ *
+ * @category idempotency
+ * @since 0.1.0
+ */
+export declare const layerExecutionIds: (source: ExecutionIdSource) => Layer.Layer<never>;
+//# sourceMappingURL=ExecutionIds.d.ts.map

package/dist/cjs/Flow/ExecutionIds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionIds.d.ts","sourceRoot":"","sources":["../../../src/Flow/ExecutionIds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAGrC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAEpC;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,GAAG,EAC3B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,OAAO,KACb,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAA;CAC1F;AA2BD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,EAAE,iBAOrB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,iBAEnB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,sCAK/B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,iBAAiB,KACxB,KAAK,CAAC,KAAK,CAAC,KAAK,CAA+C,CAAA"}

package/dist/cjs/Flow/ExecutionIds.js

@@ -0,0 +1,66 @@
+"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 ExecutionIds_exports = {};
+__export(ExecutionIds_exports, {
+  CurrentExecutionIds: () => CurrentExecutionIds,
+  derived: () => derived,
+  fresh: () => fresh,
+  layerExecutionIds: () => layerExecutionIds
+});
+module.exports = __toCommonJS(ExecutionIds_exports);
+var import_crypto = require("@smthrs/crypto");
+var import_keys = require("@smthrs/keys");
+var Context = __toESM(require("effect/Context"), 1);
+var Crypto = __toESM(require("effect/Crypto"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var import_ExecutionIdRequired = require("./ExecutionIdRequired.js");
+const canonicalKey = (flow, payload) => Schema.encodeEffect(Schema.toCodecJson(flow.payloadSchema))(payload).pipe(
+  Effect.flatMap((encoded) => Schema.decodeUnknownEffect(import_keys.DerivedKey)(encoded)),
+  Effect.mapError(() => new import_ExecutionIdRequired.ExecutionIdRequired({ flowName: flow._tag }))
+);
+const derived = {
+  mint: (flow, payload) => canonicalKey(flow, payload).pipe(
+    // The JSON tuple prevents delimiter splicing. This exact framing freezes at rc.0.
+    Effect.flatMap((key) => Effect.orDie(Schema.decodeUnknownEffect(import_crypto.Sha256)(JSON.stringify([flow._tag, key])))),
+    Effect.orDie
+  )
+};
+const fresh = {
+  mint: () => Effect.flatMap(Crypto.Crypto, (crypto) => Effect.orDie(crypto.randomUUIDv4))
+};
+const CurrentExecutionIds = Context.Reference(
+  "@smthrs/flow/Flow/CurrentExecutionIds",
+  {
+    defaultValue: () => fresh
+  }
+);
+const layerExecutionIds = (source) => Layer.succeed(CurrentExecutionIds)(source);
+//# sourceMappingURL=ExecutionIds.js.map

package/dist/cjs/Flow/ExecutionIds.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Flow/ExecutionIds.ts"],
+  "sourcesContent": ["/**\n * The ambient source of execution identity, for a flow executed without one.\n *\n * Identity has three sources, in this order: the `executionId` the caller\n * named, the `idempotencyKey` the flow declared, and \u2014 when neither exists \u2014\n * the source in this module. The first two are decisions an author made at the\n * call site or the declaration site; the third is a decision the *host* makes\n * once, for every flow it drives, which is why it is a context reference and\n * not another option on `execute`.\n *\n * The default mints a fresh cryptographic UUID for every unkeyed invocation.\n * Equal payloads are independent requests. To reattach after a crash, retain\n * the returned execution id, declare an idempotency key, or explicitly install\n * the `derived` source. Changing this default does not rewrite stored ids.\n *\n * @since 0.1.0\n */\n\nimport { Sha256 } from \"@smthrs/crypto\"\nimport { DerivedKey } from \"@smthrs/keys\"\nimport * as Context from \"effect/Context\"\nimport * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\nimport { ExecutionIdRequired } from \"./ExecutionIdRequired.ts\"\nimport type { Any } from \"./Flow.ts\"\n\n/**\n * Mints the execution id of an invocation that named none.\n *\n * It is consulted only after the two explicit sources are absent, and it runs\n * before the runtime is read, so a source that cannot name the invocation\n * fails the execution rather than starting one under a guessed identity.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface ExecutionIdSource {\n  readonly mint: <W extends Any>(\n    flow: W,\n    payload: unknown\n  ) => Effect.Effect<string, never, Crypto.Crypto | W[\"payloadSchema\"][\"EncodingServices\"]>\n}\n\n/**\n * The canonical key of an invocation: the flow's own payload codec, then RFC\n * 8785, then SHA-256.\n *\n * Encoding first is what makes the key agree with the durable driver, which\n * compares the ENCODED payload when it decides whether an existing run row is\n * the same invocation. A payload with no canonical form \u2014 a non-finite number,\n * a lone surrogate, a cycle \u2014 has no derivable identity at all, so it fails\n * here instead of hashing something approximate.\n *\n * @private\n */\nconst canonicalKey = <W extends Any>(\n  flow: W,\n  payload: unknown\n): Effect.Effect<string, ExecutionIdRequired, Crypto.Crypto | W[\"payloadSchema\"][\"EncodingServices\"]> =>\n  (Schema.encodeEffect(Schema.toCodecJson(flow.payloadSchema))(payload) as Effect.Effect<\n    unknown,\n    unknown,\n    W[\"payloadSchema\"][\"EncodingServices\"]\n  >).pipe(\n    Effect.flatMap((encoded) => Schema.decodeUnknownEffect(DerivedKey)(encoded)),\n    Effect.mapError(() => new ExecutionIdRequired({ flowName: flow._tag }))\n  )\n\n/**\n * An opt-in deterministic source over the flow tag and the payload's\n * canonical form.\n *\n * Same tag and same encoded payload derive the same id, which is exactly the\n * pair the durable driver already treats as one invocation, so a re-drive of a\n * crashed program re-attaches to the run it left behind instead of opening a\n * second one.\n *\n * The tag and canonical payload key are JSON-tuple framed before hashing.\n * Their strings are used exactly as given and encoded as UTF-8, with no Unicode\n * normalization. This preimage encoding freezes at rc.0.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const derived: ExecutionIdSource = {\n  mint: (flow, payload) =>\n    canonicalKey(flow, payload).pipe(\n      // The JSON tuple prevents delimiter splicing. This exact framing freezes at rc.0.\n      Effect.flatMap((key) => Effect.orDie(Schema.decodeUnknownEffect(Sha256)(JSON.stringify([flow._tag, key])))),\n      Effect.orDie\n    )\n}\n\n/**\n * Mints independent execution ids for unkeyed requests using host cryptography.\n * @category constructors\n * @since 0.1.0\n */\nexport const fresh: ExecutionIdSource = {\n  mint: () => Effect.flatMap(Crypto.Crypto, (crypto) => Effect.orDie(crypto.randomUUIDv4))\n}\n\n/**\n * Context reference carrying the host's execution-id source, defaulting to\n * {@link fresh}.\n *\n * @category idempotency\n * @since 0.1.0\n */\nexport const CurrentExecutionIds = Context.Reference<ExecutionIdSource>(\n  \"@smthrs/flow/Flow/CurrentExecutionIds\",\n  {\n    defaultValue: () => fresh\n  }\n)\n\n/**\n * Declares the host's execution-id source as a layer.\n *\n * **When to use**\n *\n * Install `derived` when equal payloads deliberately identify the same work,\n * or provide a host-specific identity source. Explicit caller execution ids\n * and declared idempotency keys take precedence over this source.\n *\n * @category idempotency\n * @since 0.1.0\n */\nexport const layerExecutionIds = (\n  source: ExecutionIdSource\n): Layer.Layer<never> => Layer.succeed(CurrentExecutionIds)(source)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBA,oBAAuB;AACvB,kBAA2B;AAC3B,cAAyB;AACzB,aAAwB;AACxB,aAAwB;AACxB,YAAuB;AACvB,aAAwB;AACxB,iCAAoC;AAgCpC,MAAM,eAAe,CACnB,MACA,YAEC,OAAO,aAAa,OAAO,YAAY,KAAK,aAAa,CAAC,EAAE,OAAO,EAIjE;AAAA,EACD,OAAO,QAAQ,CAAC,YAAY,OAAO,oBAAoB,sBAAU,EAAE,OAAO,CAAC;AAAA,EAC3E,OAAO,SAAS,MAAM,IAAI,+CAAoB,EAAE,UAAU,KAAK,KAAK,CAAC,CAAC;AACxE;AAkBK,MAAM,UAA6B;AAAA,EACxC,MAAM,CAAC,MAAM,YACX,aAAa,MAAM,OAAO,EAAE;AAAA;AAAA,IAE1B,OAAO,QAAQ,CAAC,QAAQ,OAAO,MAAM,OAAO,oBAAoB,oBAAM,EAAE,KAAK,UAAU,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;AAAA,IAC1G,OAAO;AAAA,EACT;AACJ;AAOO,MAAM,QAA2B;AAAA,EACtC,MAAM,MAAM,OAAO,QAAQ,OAAO,QAAQ,CAAC,WAAW,OAAO,MAAM,OAAO,YAAY,CAAC;AACzF;AASO,MAAM,sBAAsB,QAAQ;AAAA,EACzC;AAAA,EACA;AAAA,IACE,cAAc,MAAM;AAAA,EACtB;AACF;AAcO,MAAM,oBAAoB,CAC/B,WACuB,MAAM,QAAQ,mBAAmB,EAAE,MAAM;",
+  "names": []
+}