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

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

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityCeiling.js","sourceRoot":"","sources":["../../../src/Flow/CapabilityCeiling.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,UAAU,MAAM,+BAA+B,CAAA;AAC3D,OAAO,KAAK,aAAa,MAAM,kCAAkC,CAAA;AACjE,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,WAAmC,EAAwC,EAAE,CAC9G,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AAE7F;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,MAA4C,EACgB,EAAE,CAC9D,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACnB,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;IACrB,MAAM,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AACpD,CAAC,CAAC,CACH,CAAA;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAA4C,EAAE,EAAE,CACpF,aAAa,CAAC,eAAe,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAA","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"]}

package/dist/esm/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/esm/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/esm/Flow/DeadlineExceeded.js

@@ -0,0 +1,34 @@
+/**
+ * Defect recorded when an execution runs past its flow's declared deadline.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Fault from "../Fault.js";
+/**
+ * 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 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/esm/Flow/DeadlineExceeded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeadlineExceeded.js","sourceRoot":"","sources":["../../../src/Flow/DeadlineExceeded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AAEpC;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,gBAAiB,SAAQ,MAAM,CAAC,WAAW,EAAoB,CAC1E,+BAA+B,EAC/B;IACE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAC5C,MAAM,CAAC,sBAAsB,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,CACnE;IACD,QAAQ,EAAE,MAAM,CAAC,MAAM;IACvB,WAAW,EAAE,MAAM,CAAC,MAAM;IAC1B,UAAU,EAAE,MAAM,CAAC,MAAM;IACzB,WAAW,EAAE,MAAM,CAAC,MAAM;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM;CACvB,CACF;CAAG;AAEJ,KAAK,CAAC,QAAQ,CAAC,+BAA+B,EAAE,QAAQ,CAAC,CAAA","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"]}

package/dist/esm/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/esm/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/esm/Flow/ExecutionIdRequired.js

@@ -0,0 +1,30 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * Failure raised when a flow execution has no explicit or derived identity.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/**
+ * 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 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/esm/Flow/ExecutionIdRequired.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionIdRequired.js","sourceRoot":"","sources":["../../../src/Flow/ExecutionIdRequired.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,mBAAoB,SAAQ,MAAM,CAAC,WAAW,EAAuB,CAChF,kCAAkC,EAClC;IACE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC,IAAI,CAChD,MAAM,CAAC,sBAAsB,CAAC,MAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CACvE;IACD,QAAQ,EAAE,MAAM,CAAC,MAAM;CACxB,CACF;CAAG","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"]}

package/dist/esm/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/esm/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/esm/Flow/ExecutionIds.js

@@ -0,0 +1,91 @@
+/**
+ * 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 { Sha256 } from "@smthrs/crypto";
+import { DerivedKey } from "@smthrs/keys";
+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 * as Schema from "effect/Schema";
+import { ExecutionIdRequired } from "./ExecutionIdRequired.js";
+/**
+ * The canonical key of an invocation: the flow's own payload codec, then RFC
+ * 8785, then SHA-256.
+ *
+ * Encoding first is what makes the key agree with the durable driver, which
+ * compares the ENCODED payload when it decides whether an existing run row is
+ * the same invocation. A payload with no canonical form — a non-finite number,
+ * a lone surrogate, a cycle — has no derivable identity at all, so it fails
+ * here instead of hashing something approximate.
+ *
+ * @private
+ */
+const canonicalKey = (flow, payload) => Schema.encodeEffect(Schema.toCodecJson(flow.payloadSchema))(payload).pipe(Effect.flatMap((encoded) => Schema.decodeUnknownEffect(DerivedKey)(encoded)), Effect.mapError(() => new ExecutionIdRequired({ flowName: flow._tag })));
+/**
+ * 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 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(Sha256)(JSON.stringify([flow._tag, key])))), Effect.orDie)
+};
+/**
+ * Mints independent execution ids for unkeyed requests using host cryptography.
+ * @category constructors
+ * @since 0.1.0
+ */
+export const fresh = {
+    mint: () => Effect.flatMap(Crypto.Crypto, (crypto) => Effect.orDie(crypto.randomUUIDv4()))
+};
+/**
+ * Context reference carrying the host's execution-id source, defaulting to
+ * {@link fresh}.
+ *
+ * @category idempotency
+ * @since 0.1.0
+ */
+export const CurrentExecutionIds = Context.Reference("@smthrs/flow/Flow/CurrentExecutionIds", {
+    defaultValue: () => fresh
+});
+/**
+ * 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 const layerExecutionIds = (source) => Layer.succeed(CurrentExecutionIds)(source);
+//# sourceMappingURL=ExecutionIds.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionIds.js","sourceRoot":"","sources":["../../../src/Flow/ExecutionIds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,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;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAoB9D;;;;;;;;;;;GAWG;AACH,MAAM,YAAY,GAAG,CACnB,IAAO,EACP,OAAgB,EACoF,EAAE,CACrG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAIlE,CAAC,IAAI,CACL,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,CAAC,EAC5E,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CACxE,CAAA;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,OAAO,GAAsB;IACxC,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CACtB,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI;IAC9B,kFAAkF;IAClF,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAC3G,MAAM,CAAC,KAAK,CACb;CACJ,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAsB;IACtC,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;CAC3F,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAClD,uCAAuC,EACvC;IACE,YAAY,EAAE,GAAG,EAAE,CAAC,KAAK;CAC1B,CACF,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,MAAyB,EACL,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA","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 — when neither exists —\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 — a non-finite number,\n * a lone surrogate, a cycle — 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"]}