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

package/dist/esm/DurableQueue.js

@@ -0,0 +1,303 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * Durable flow queues delegate work to persisted background workers and
+ * resume the waiting flow with the worker result.
+ *
+ * A flow calls `process` to encode a payload, offer it to a named
+ * `PersistedQueue`, attach a `DurableDeferred` token, and suspend. A worker
+ * created with `makeWorker` or `worker` takes the item, runs the handler, and
+ * records the handler's `Exit` through that token so the original flow can
+ * continue with the typed success or error.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from "effect/Array";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Filter from "effect/Filter";
+import * as Layer from "effect/Layer";
+import * as PersistedQueue from "effect/persistence/PersistedQueue";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Tracer from "effect/Tracer";
+import * as Action from "./Action/index.js";
+import * as DurableDeferred from "./DurableDeferred.js";
+import { annotateWaiting } from "./FlowRuntime/index.js";
+/**
+ * Runtime identifier attached to `DurableQueue` values.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export const TypeId = "@smthrs/flow/DurableQueue";
+/**
+ * Creates a `DurableQueue` that waits for persisted items to finish processing
+ * using a `DurableDeferred`.
+ *
+ * **Example** (Defining a durable queue with workers)
+ *
+ * ```ts
+ * import { Action, DurableQueue, Flow, Interpreter } from "@smthrs/flow"
+ * import { Effect, Layer, Schema } from "effect"
+ *
+ * // Define a DurableQueue that can be used to derive workers and offer items for
+ * // processing.
+ * const ApiQueue = DurableQueue.make({
+ *   name: "ApiQueue",
+ *   payload: {
+ *     id: Schema.String
+ *   },
+ *   success: Schema.Void,
+ *   error: Schema.Never,
+ *   idempotencyKey(payload) {
+ *     return payload.id
+ *   }
+ * })
+ *
+ * // Offering an item is work, so it is a declared Action: the declaration is
+ * // pure data, and the implementation attaches separately.
+ * const Offer = Action.make("MyFlow/offer", {
+ *   payload: {
+ *     id: Schema.String
+ *   }
+ * })
+ *
+ * const OfferLive = Offer.toLayer(
+ *   Effect.fnUntraced(function*({ id }) {
+ *     // Add an item to the DurableQueue defined above.
+ *     //
+ *     // When the worker has finished processing the item, the flow will
+ *     // resume.
+ *     //
+ *     yield* DurableQueue.process(ApiQueue, { id })
+ *
+ *     yield* Effect.log("Flow succeeded!")
+ *   })
+ * )
+ *
+ * // The flow is the composite, and its body names the step it is made of.
+ * const MyFlow = Flow.make("MyFlow", {
+ *   payload: {
+ *     id: Schema.String
+ *   },
+ *   idempotencyKey: ({ id }) => id,
+ *   body: (payload) => Offer.call(payload)
+ * })
+ *
+ * const MyFlowLayer = Layer.mergeAll(OfferLive, Interpreter.layer(MyFlow)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ *
+ * // Define a worker layer that can process items from the DurableQueue.
+ * const ApiWorker = DurableQueue.worker(
+ *   ApiQueue,
+ *   Effect.fnUntraced(function*({ id }) {
+ *     yield* Effect.log(`Worker processing API call with id: ${id}`)
+ *   }),
+ *   { concurrency: 5 } // Process up to 5 items concurrently
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options) => ({
+    [TypeId]: TypeId,
+    name: options.name,
+    payloadSchema: Schema.isSchema(options.payload)
+        ? options.payload
+        : Schema.Struct(options.payload),
+    idempotencyKey: options.idempotencyKey,
+    deferred: DurableDeferred.make(`DurableQueue/${options.name}`, {
+        success: options.success,
+        error: options.error
+    })
+});
+const queueSchemas = new WeakMap();
+const getQueueSchema = (payload) => {
+    let schema = queueSchemas.get(payload);
+    if (!schema) {
+        schema = Schema.Struct({
+            token: DurableDeferred.Token,
+            traceId: Schema.String,
+            spanId: Schema.String,
+            sampled: Schema.Boolean,
+            payload
+        });
+        queueSchemas.set(payload, schema);
+    }
+    return schema;
+};
+/**
+ * Adds an item to the queue and waits for a worker to process it.
+ *
+ * `retrySchedule` controls retries when the persisted offer fails. The default
+ * is unbounded, with exponential delays capped at one minute, so a transient
+ * store outage does not lose the item. A caller-supplied schedule may exhaust;
+ * its final offer failure becomes a defect to keep the public error channel
+ * reserved for the worker's declared error.
+ *
+ * Payload construction also becomes a defect when `fields` does not satisfy
+ * the queue's payload schema. The public error channel is the worker result,
+ * not malformed caller input.
+ *
+ * @category processing
+ * @since 0.1.0
+ */
+export const process = 
+// Untraced because queue offer is a worker hot path.
+Effect.fnUntraced(function* (self, fields, options) {
+    const payload = yield* self.payloadSchema.makeEffect(fields).pipe(Effect.mapError((issue) => new Schema.SchemaError(issue)), Effect.orDie);
+    const queueName = `DurableQueue/${self.name}`;
+    const queue = yield* PersistedQueue.make({
+        name: queueName,
+        schema: getQueueSchema(self.payloadSchema)
+    });
+    const key = yield* Action.idempotencyKey(queueName, {
+        parentScope: self.idempotencyKey(payload)
+    });
+    const deferred = DurableDeferred.make(`${self.deferred.name}/${key}`, {
+        success: self.deferred.successSchema,
+        error: self.deferred.errorSchema
+    });
+    const token = yield* DurableDeferred.token(deferred);
+    yield* Effect.useSpan(`DurableQueue/${self.name}/process`, {
+        attributes: { key }
+    }, (span) => queue.offer({
+        token,
+        payload,
+        traceId: span.traceId,
+        spanId: span.spanId,
+        sampled: span.sampled
+    }, { id: key }).pipe(Effect.tapCause(Effect.logWarning), Effect.catchTag("SchemaError", Effect.die), Effect.retry(options?.retrySchedule ?? defaultRetrySchedule), Effect.orDie, Effect.annotateLogs({
+        package: "@smthrs/flow",
+        module: "DurableQueue",
+        fiber: "process",
+        queueName: self.name
+    })));
+    yield* annotateWaiting({ reason: "event", token });
+    return yield* DurableDeferred.await(deferred);
+});
+const maxDeferredNameExcerptChars = 128;
+/** Renders a bounded excerpt of a stored deferred name for a diagnostic. */
+const deferredNameExcerpt = (name) => name.length <= maxDeferredNameExcerptChars
+    ? name
+    : `${name.slice(0, maxDeferredNameExcerptChars)} [${name.length - maxDeferredNameExcerptChars} characters dropped]`;
+const traceIdPattern = /^[0-9a-f]{32}$/;
+const spanIdPattern = /^[0-9a-f]{16}$/;
+/**
+ * The offering span as the worker span's parent, when the stored ids have the
+ * W3C trace-context shape every Effect and OpenTelemetry tracer writes. A
+ * stored item is not trusted to splice arbitrary identifiers into a trace.
+ */
+const externalParent = (item) => traceIdPattern.test(item.traceId) && spanIdPattern.test(item.spanId)
+    ? Tracer.externalSpan({ traceId: item.traceId, spanId: item.spanId, sampled: item.sampled })
+    : undefined;
+const defaultRetrySchedule = Schedule.min([
+    Schedule.exponential(500, 1.5),
+    Schedule.spaced("1 minute")
+]);
+const makeWorkerEffect = Effect.fnUntraced(function* (self, f, concurrency, maxAttempts) {
+    const queue = yield* PersistedQueue.make({
+        name: `DurableQueue/${self.name}`,
+        schema: getQueueSchema(self.payloadSchema),
+        maxAttempts,
+        // The worker owns the 500 ms retry pause below. Keep an upstream queue
+        // default from introducing an additional backoff after an Effect upgrade.
+        retrySchedule: Schedule.spaced(0)
+    });
+    const worker = Effect.suspend(() => {
+        let completion;
+        return queue.take((item_, metadata) => {
+            const item = item_;
+            return Effect.withSpan(Effect.gen(function* () {
+                // Parse before running the handler. A malformed completion address
+                // cannot strand a handler result that was already produced.
+                const parsed = yield* DurableDeferred.TokenParsed.parse(item.token);
+                // `process` offers each item under its key and addresses the
+                // deferred `<queue deferred>/<key>`. Anything else in this queue
+                // names a wait point the queue does not own (another queue's item,
+                // a WaitFor gate, a human task), so completing it here would settle
+                // a foreign wait under this queue's success schema.
+                const expected = `${self.deferred.name}/${metadata.id}`;
+                if (parsed.deferredName !== expected) {
+                    return yield* new DurableDeferred.TokenInvalid({
+                        code: "deferred_mismatch",
+                        message: `The item "${metadata.id}" addresses the deferred "${deferredNameExcerpt(parsed.deferredName)}", not "${deferredNameExcerpt(expected)}".`
+                    });
+                }
+                const deferred = DurableDeferred.make(parsed.deferredName, {
+                    success: self.deferred.successSchema,
+                    error: self.deferred.errorSchema
+                });
+                let exit = yield* Effect.exit(f(item.payload));
+                if (Exit.isFailure(exit)) {
+                    const [interrupts, reasons] = Arr.partition(exit.cause.reasons, Filter.fromPredicate(Cause.isInterruptReason));
+                    // Match DurableDeferred.into: interruption alone is not a durable
+                    // outcome, and must leave the item available without an attempt.
+                    if (interrupts.length === exit.cause.reasons.length) {
+                        return yield* Effect.failCause(Cause.fromReasons(interrupts));
+                    }
+                    else if (interrupts.length > 0) {
+                        exit = Exit.failCause(Cause.fromReasons(reasons));
+                    }
+                }
+                completion = { token: item.token, ...metadata };
+                yield* DurableDeferred.done(deferred, {
+                    token: item.token,
+                    exit
+                });
+            }).pipe(Effect.catchTag("@smthrs/flow/DurableDeferred/TokenInvalid", (error) => Effect.logError(`DurableQueue "${self.name}" could not complete an item because its token was invalid. ${error.message}`))), `DurableQueue/${self.name}/worker`, {
+                captureStackTrace: false,
+                parent: externalParent(item)
+            });
+        }).pipe(Effect.tapCause((cause) => {
+            if (!completion)
+                return Effect.void;
+            return Effect.logError("DurableQueue failed to persist or acknowledge a handler result", cause).pipe(Effect.annotateLogs({
+                token: completion.token,
+                itemId: completion.id,
+                attempt: completion.attempts,
+                maxAttempts,
+                exhausted: !Cause.hasInterrupts(cause) && completion.attempts >= maxAttempts
+            }));
+        }));
+    }).pipe(
+    // A persistently failing take would otherwise consume a core in a tight
+    // loop while the queue store is unavailable.
+    Effect.catchCause((cause) => Effect.logWarning(cause).pipe(Effect.andThen(Effect.sleep(500)))), Effect.forever, Effect.annotateLogs({
+        package: "@smthrs/flow",
+        module: "DurableQueue",
+        fiber: "worker",
+        queueName: self.name
+    }));
+    return yield* Effect.replicateEffect(worker, concurrency, { concurrency, discard: true }).pipe(Effect.andThen(Effect.never));
+});
+/**
+ * Create a worker effect that processes items from the durable queue.
+ *
+ * `concurrency` defaults to one and must be a positive safe integer. It is
+ * checked before the persisted queue is opened. `maxAttempts` defaults to ten
+ * and is passed to the persisted queue. Completion-write failures can rerun the
+ * handler; side effects must be idempotent. Exhaustion leaves the flow waiting.
+ *
+ * @throws A `RangeError` when `concurrency` is not a positive safe integer.
+ * @category worker
+ * @since 0.1.0
+ */
+export const makeWorker = (self, f, options) => {
+    const concurrency = options?.concurrency ?? 1;
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+        throw new RangeError(`DurableQueue.makeWorker: concurrency must be a positive safe integer, and was ${concurrency}.`);
+    }
+    return makeWorkerEffect(self, f, concurrency, options?.maxAttempts ?? 10);
+};
+/**
+ * Create a layer that runs workers for the durable queue.
+ *
+ * @category worker
+ * @since 0.1.0
+ */
+export const worker = (self, f, options) => Layer.effectDiscard(Effect.forkScoped(makeWorker(self, f, options)));
+//# sourceMappingURL=DurableQueue.js.map

package/dist/esm/DurableQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DurableQueue.js","sourceRoot":"","sources":["../../src/DurableQueue.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,GAAG,MAAM,cAAc,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AACnC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,cAAc,MAAM,mCAAmC,CAAA;AACnE,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAA;AAC3C,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,eAAe,EAAuC,MAAM,wBAAwB,CAAA;AAU7F;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAW,2BAA2B,CAAA;AAqBzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAIlB,OASD,EAIC,EAAE,CAAC,CAAC;IACJ,CAAC,MAAM,CAAC,EAAE,MAAM;IAChB,IAAI,EAAE,OAAO,CAAC,IAAI;IAClB,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC;QAC7C,CAAC,CAAC,OAAO,CAAC,OAAO;QACjB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAc,CAAQ;IAChD,cAAc,EAAE,OAAO,CAAC,cAAqB;IAC7C,QAAQ,EAAE,eAAe,CAAC,IAAI,CAAC,gBAAgB,OAAO,CAAC,IAAI,EAAE,EAAE;QAC7D,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC;CACH,CAAC,CAAA;AAEF,MAAM,YAAY,GAAG,IAAI,OAAO,EAA0B,CAAA;AAE1D,MAAM,cAAc,GAAG,CACrB,OAAgB,EAOf,EAAE;IACH,IAAI,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;YACrB,KAAK,EAAE,eAAe,CAAC,KAAK;YAC5B,OAAO,EAAE,MAAM,CAAC,MAAM;YACtB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO;SACR,CAAC,CAAA;QACF,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACnC,CAAC;IACD,OAAO,MAAa,CAAA;AACtB,CAAC,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,OAAO;AAsBlB,qDAAqD;AACrD,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAIzB,IAA2C,EAAE,MAAgC,EAAE,OAEhF;IACC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAC/D,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EACzD,MAAM,CAAC,KAAK,CACb,CAAA;IACD,MAAM,SAAS,GAAG,gBAAgB,IAAI,CAAC,IAAI,EAAE,CAAA;IAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC;QACvC,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC;KAC3C,CAAC,CAAA;IACF,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE;QAClD,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC;KAC1C,CAAC,CAAA;IAEF,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,GAAG,EAAE,EAAE;QACpE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa;QACpC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW;KACjC,CAAC,CAAA;IACF,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;IAEpD,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,gBAAgB,IAAI,CAAC,IAAI,UAAU,EAAE;QACzD,UAAU,EAAE,EAAE,GAAG,EAAE;KACpB,EAAE,CAAC,IAAI,EAAE,EAAE,CACV,KAAK,CAAC,KAAK,CAAC;QACV,KAAK;QACL,OAAO;QACP,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;KACf,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,CACzB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,EAC1C,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,aAAa,IAAI,oBAAoB,CAAC,EAC5D,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,YAAY,CAAC;QAClB,OAAO,EAAE,cAAc;QACvB,MAAM,EAAE,cAAc;QACtB,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,IAAI,CAAC,IAAI;KACrB,CAAC,CACH,CAAC,CAAA;IAEJ,KAAK,CAAC,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IAClD,OAAO,KAAK,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;AAC/C,CAAC,CAAC,CAAA;AAEJ,MAAM,2BAA2B,GAAG,GAAG,CAAA;AAEvC,4EAA4E;AAC5E,MAAM,mBAAmB,GAAG,CAAC,IAAY,EAAU,EAAE,CACnD,IAAI,CAAC,MAAM,IAAI,2BAA2B;IACxC,CAAC,CAAC,IAAI;IACN,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,2BAA2B,CAAC,KAAK,IAAI,CAAC,MAAM,GAAG,2BAA2B,sBAAsB,CAAA;AAEvH,MAAM,cAAc,GAAG,gBAAgB,CAAA;AACvC,MAAM,aAAa,GAAG,gBAAgB,CAAA;AAEtC;;;;GAIG;AACH,MAAM,cAAc,GAAG,CAAC,IAIvB,EAAmC,EAAE,CACpC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAClE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC5F,CAAC,CAAC,SAAS,CAAA;AAEf,MAAM,oBAAoB,GAAG,QAAQ,CAAC,GAAG,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC;CAC5B,CAAC,CAAA;AAEF,MAAM,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAMlD,IAA2C,EAC3C,CAAiF,EACjF,WAAmB,EACnB,WAAmB;IAEnB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC;QACvC,IAAI,EAAE,gBAAgB,IAAI,CAAC,IAAI,EAAE;QACjC,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC;QAC1C,WAAW;QACX,uEAAuE;QACvE,0EAA0E;QAC1E,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;KAClC,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;QACjC,IAAI,UAES,CAAA;QACb,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;YACpC,MAAM,IAAI,GAAG,KAMZ,CAAA;YACD,OAAO,MAAM,CAAC,QAAQ,CACpB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAClB,mEAAmE;gBACnE,4DAA4D;gBAC5D,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,eAAe,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;gBACnE,6DAA6D;gBAC7D,iEAAiE;gBACjE,mEAAmE;gBACnE,oEAAoE;gBACpE,oDAAoD;gBACpD,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAA;gBACvD,IAAI,MAAM,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;oBACrC,OAAO,KAAK,CAAC,CAAC,IAAI,eAAe,CAAC,YAAY,CAAC;wBAC7C,IAAI,EAAE,mBAAmB;wBACzB,OAAO,EAAE,aAAa,QAAQ,CAAC,EAAE,6BAC/B,mBAAmB,CAAC,MAAM,CAAC,YAAY,CACzC,WAAW,mBAAmB,CAAC,QAAQ,CAAC,IAAI;qBAC7C,CAAC,CAAA;gBACJ,CAAC;gBACD,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE;oBACzD,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa;oBACpC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW;iBACjC,CAAC,CAAA;gBACF,IAAI,IAAI,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAA;gBAC9C,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;oBACzB,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,SAAS,CACzC,IAAI,CAAC,KAAK,CAAC,OAAO,EAClB,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAC9C,CAAA;oBACD,kEAAkE;oBAClE,iEAAiE;oBACjE,IAAI,UAAU,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;wBACpD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,CAAQ,UAAU,CAAC,CAAC,CAAA;oBACtE,CAAC;yBAAM,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACjC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAA;oBACnD,CAAC;gBACH,CAAC;gBACD,UAAU,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,QAAQ,EAAE,CAAA;gBAC/C,KAAK,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,EAAE;oBACpC,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,IAAI;iBACL,CAAC,CAAA;YACJ,CAAC,CAAC,CAAC,IAAI,CACL,MAAM,CAAC,QAAQ,CAAC,2CAA2C,EAAE,CAAC,KAAK,EAAE,EAAE,CACrE,MAAM,CAAC,QAAQ,CACb,iBAAiB,IAAI,CAAC,IAAI,+DAA+D,KAAK,CAAC,OAAO,EAAE,CACzG,CAAC,CACL,EACD,gBAAgB,IAAI,CAAC,IAAI,SAAS,EAClC;gBACE,iBAAiB,EAAE,KAAK;gBACxB,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC;aAC7B,CACF,CAAA;QACH,CAAC,CAAC,CAAC,IAAI,CACL,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE;YACxB,IAAI,CAAC,UAAU;gBAAE,OAAO,MAAM,CAAC,IAAI,CAAA;YACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,gEAAgE,EAAE,KAAK,CAAC,CAAC,IAAI,CAClG,MAAM,CAAC,YAAY,CAAC;gBAClB,KAAK,EAAE,UAAU,CAAC,KAAK;gBACvB,MAAM,EAAE,UAAU,CAAC,EAAE;gBACrB,OAAO,EAAE,UAAU,CAAC,QAAQ;gBAC5B,WAAW;gBACX,SAAS,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,QAAQ,IAAI,WAAW;aAC7E,CAAC,CACH,CAAA;QACH,CAAC,CAAC,CACH,CAAA;IACH,CAAC,CAAC,CAAC,IAAI;IACL,wEAAwE;IACxE,6CAA6C;IAC7C,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,EAAE,CAC1B,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAC3B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAClC,CACF,EACD,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,YAAY,CAAC;QAClB,OAAO,EAAE,cAAc;QACvB,MAAM,EAAE,cAAc;QACtB,KAAK,EAAE,QAAQ;QACf,SAAS,EAAE,IAAI,CAAC,IAAI;KACrB,CAAC,CACH,CAAA;IAED,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAC5F,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAC7B,CAAA;AACH,CAAC,CAAC,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,UAAU,GAsBnB,CAMF,IAA2C,EAC3C,CAAiF,EACjF,OAGC,EACD,EAAE;IACF,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,CAAC,CAAA;IAC7C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,UAAU,CAClB,iFAAiF,WAAW,GAAG,CAChG,CAAA;IACH,CAAC;IACD,OAAO,gBAAgB,CAAC,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,IAAI,EAAE,CAAC,CAAA;AAC3E,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAsBf,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Durable flow queues delegate work to persisted background workers and\n * resume the waiting flow with the worker result.\n *\n * A flow calls `process` to encode a payload, offer it to a named\n * `PersistedQueue`, attach a `DurableDeferred` token, and suspend. A worker\n * created with `makeWorker` or `worker` takes the item, runs the handler, and\n * records the handler's `Exit` through that token so the original flow can\n * continue with the typed success or error.\n *\n * @since 0.1.0\n */\n\nimport * as Arr from \"effect/Array\"\nimport * as Cause from \"effect/Cause\"\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport * as Exit from \"effect/Exit\"\nimport * as Filter from \"effect/Filter\"\nimport * as Layer from \"effect/Layer\"\nimport * as PersistedQueue from \"effect/persistence/PersistedQueue\"\nimport * as Schedule from \"effect/Schedule\"\nimport * as Schema from \"effect/Schema\"\nimport * as Tracer from \"effect/Tracer\"\nimport * as Action from \"./Action/index.ts\"\nimport * as DurableDeferred from \"./DurableDeferred.ts\"\nimport { annotateWaiting, type FlowInstance, type FlowRuntime } from \"./FlowRuntime/index.ts\"\n\n/**\n * Type-level identifier used to recognize `DurableQueue` values.\n *\n * @category type IDs\n * @since 0.1.0\n */\nexport type TypeId = \"@smthrs/flow/DurableQueue\"\n\n/**\n * Runtime identifier attached to `DurableQueue` values.\n *\n * @category type IDs\n * @since 0.1.0\n */\nexport const TypeId: TypeId = \"@smthrs/flow/DurableQueue\"\n\n/**\n * Durable flow queue definition containing a payload schema, idempotency\n * key, and deferred used to await worker results.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface DurableQueue<\n  Payload extends Schema.Top,\n  Success extends Schema.Top = Schema.Void,\n  Error extends Schema.Top = Schema.Never\n> {\n  readonly [TypeId]: TypeId\n  readonly name: string\n  readonly payloadSchema: Payload\n  readonly idempotencyKey: (payload: Payload[\"Type\"]) => string\n  readonly deferred: DurableDeferred.DurableDeferred<Success, Error>\n}\n\n/**\n * Creates a `DurableQueue` that waits for persisted items to finish processing\n * using a `DurableDeferred`.\n *\n * **Example** (Defining a durable queue with workers)\n *\n * ```ts\n * import { Action, DurableQueue, Flow, Interpreter } from \"@smthrs/flow\"\n * import { Effect, Layer, Schema } from \"effect\"\n *\n * // Define a DurableQueue that can be used to derive workers and offer items for\n * // processing.\n * const ApiQueue = DurableQueue.make({\n *   name: \"ApiQueue\",\n *   payload: {\n *     id: Schema.String\n *   },\n *   success: Schema.Void,\n *   error: Schema.Never,\n *   idempotencyKey(payload) {\n *     return payload.id\n *   }\n * })\n *\n * // Offering an item is work, so it is a declared Action: the declaration is\n * // pure data, and the implementation attaches separately.\n * const Offer = Action.make(\"MyFlow/offer\", {\n *   payload: {\n *     id: Schema.String\n *   }\n * })\n *\n * const OfferLive = Offer.toLayer(\n *   Effect.fnUntraced(function*({ id }) {\n *     // Add an item to the DurableQueue defined above.\n *     //\n *     // When the worker has finished processing the item, the flow will\n *     // resume.\n *     //\n *     yield* DurableQueue.process(ApiQueue, { id })\n *\n *     yield* Effect.log(\"Flow succeeded!\")\n *   })\n * )\n *\n * // The flow is the composite, and its body names the step it is made of.\n * const MyFlow = Flow.make(\"MyFlow\", {\n *   payload: {\n *     id: Schema.String\n *   },\n *   idempotencyKey: ({ id }) => id,\n *   body: (payload) => Offer.call(payload)\n * })\n *\n * const MyFlowLayer = Layer.mergeAll(OfferLive, Interpreter.layer(MyFlow)).pipe(\n *   Layer.provideMerge(Action.layerImplementations)\n * )\n *\n * // Define a worker layer that can process items from the DurableQueue.\n * const ApiWorker = DurableQueue.worker(\n *   ApiQueue,\n *   Effect.fnUntraced(function*({ id }) {\n *     yield* Effect.log(`Worker processing API call with id: ${id}`)\n *   }),\n *   { concurrency: 5 } // Process up to 5 items concurrently\n * )\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <\n  Payload extends Schema.Top | Schema.Struct.Fields,\n  Success extends Schema.Top = Schema.Void,\n  Error extends Schema.Top = Schema.Never\n>(options: {\n  readonly name: string\n  readonly payload: Payload\n  readonly idempotencyKey: (\n    payload: Payload extends Schema.Struct.Fields ? Schema.Struct.Type<Payload>\n      : Payload[\"Type\"]\n  ) => string\n  readonly success?: Success | undefined\n  readonly error?: Error | undefined\n}): DurableQueue<\n  Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,\n  Success,\n  Error\n> => ({\n  [TypeId]: TypeId,\n  name: options.name,\n  payloadSchema: Schema.isSchema(options.payload)\n    ? options.payload\n    : Schema.Struct(options.payload as any) as any,\n  idempotencyKey: options.idempotencyKey as any,\n  deferred: DurableDeferred.make(`DurableQueue/${options.name}`, {\n    success: options.success,\n    error: options.error\n  })\n})\n\nconst queueSchemas = new WeakMap<Schema.Top, Schema.Top>()\n\nconst getQueueSchema = <Payload extends Schema.Top>(\n  payload: Payload\n): Schema.Struct<{\n  token: typeof DurableDeferred.Token\n  payload: Payload\n  traceId: typeof Schema.String\n  spanId: typeof Schema.String\n  sampled: typeof Schema.Boolean\n}> => {\n  let schema = queueSchemas.get(payload)\n  if (!schema) {\n    schema = Schema.Struct({\n      token: DurableDeferred.Token,\n      traceId: Schema.String,\n      spanId: Schema.String,\n      sampled: Schema.Boolean,\n      payload\n    })\n    queueSchemas.set(payload, schema)\n  }\n  return schema as any\n}\n\n/**\n * Adds an item to the queue and waits for a worker to process it.\n *\n * `retrySchedule` controls retries when the persisted offer fails. The default\n * is unbounded, with exponential delays capped at one minute, so a transient\n * store outage does not lose the item. A caller-supplied schedule may exhaust;\n * its final offer failure becomes a defect to keep the public error channel\n * reserved for the worker's declared error.\n *\n * Payload construction also becomes a defect when `fields` does not satisfy\n * the queue's payload schema. The public error channel is the worker result,\n * not malformed caller input.\n *\n * @category processing\n * @since 0.1.0\n */\nexport const process: <\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  payload: Payload[\"~type.make.in\"],\n  options?: {\n    readonly retrySchedule?: Schedule.Schedule<any, PersistedQueue.PersistedQueueError> | undefined\n  }\n) => Effect.Effect<\n  Success[\"Type\"],\n  Error[\"Type\"],\n  | FlowRuntime\n  | FlowInstance\n  | Crypto.Crypto\n  | PersistedQueue.PersistedQueueFactory\n  | Payload[\"EncodingServices\"]\n  | Payload[\"DecodingServices\"]\n  | Success[\"DecodingServices\"]\n  | Error[\"DecodingServices\"]\n> =\n  // Untraced because queue offer is a worker hot path.\n  Effect.fnUntraced(function*<\n    Payload extends Schema.Top,\n    Success extends Schema.Top,\n    Error extends Schema.Top\n  >(self: DurableQueue<Payload, Success, Error>, fields: Payload[\"~type.make.in\"], options?: {\n    readonly retrySchedule?: Schedule.Schedule<any, PersistedQueue.PersistedQueueError> | undefined\n  }) {\n    const payload = yield* self.payloadSchema.makeEffect(fields).pipe(\n      Effect.mapError((issue) => new Schema.SchemaError(issue)),\n      Effect.orDie\n    )\n    const queueName = `DurableQueue/${self.name}`\n    const queue = yield* PersistedQueue.make({\n      name: queueName,\n      schema: getQueueSchema(self.payloadSchema)\n    })\n    const key = yield* Action.idempotencyKey(queueName, {\n      parentScope: self.idempotencyKey(payload)\n    })\n\n    const deferred = DurableDeferred.make(`${self.deferred.name}/${key}`, {\n      success: self.deferred.successSchema,\n      error: self.deferred.errorSchema\n    })\n    const token = yield* DurableDeferred.token(deferred)\n\n    yield* Effect.useSpan(`DurableQueue/${self.name}/process`, {\n      attributes: { key }\n    }, (span) =>\n      queue.offer({\n        token,\n        payload,\n        traceId: span.traceId,\n        spanId: span.spanId,\n        sampled: span.sampled\n      } as any, { id: key }).pipe(\n        Effect.tapCause(Effect.logWarning),\n        Effect.catchTag(\"SchemaError\", Effect.die),\n        Effect.retry(options?.retrySchedule ?? defaultRetrySchedule),\n        Effect.orDie,\n        Effect.annotateLogs({\n          package: \"@smthrs/flow\",\n          module: \"DurableQueue\",\n          fiber: \"process\",\n          queueName: self.name\n        })\n      ))\n\n    yield* annotateWaiting({ reason: \"event\", token })\n    return yield* DurableDeferred.await(deferred)\n  })\n\nconst maxDeferredNameExcerptChars = 128\n\n/** Renders a bounded excerpt of a stored deferred name for a diagnostic. */\nconst deferredNameExcerpt = (name: string): string =>\n  name.length <= maxDeferredNameExcerptChars\n    ? name\n    : `${name.slice(0, maxDeferredNameExcerptChars)} [${name.length - maxDeferredNameExcerptChars} characters dropped]`\n\nconst traceIdPattern = /^[0-9a-f]{32}$/\nconst spanIdPattern = /^[0-9a-f]{16}$/\n\n/**\n * The offering span as the worker span's parent, when the stored ids have the\n * W3C trace-context shape every Effect and OpenTelemetry tracer writes. A\n * stored item is not trusted to splice arbitrary identifiers into a trace.\n */\nconst externalParent = (item: {\n  readonly traceId: string\n  readonly spanId: string\n  readonly sampled: boolean\n}): Tracer.ExternalSpan | undefined =>\n  traceIdPattern.test(item.traceId) && spanIdPattern.test(item.spanId)\n    ? Tracer.externalSpan({ traceId: item.traceId, spanId: item.spanId, sampled: item.sampled })\n    : undefined\n\nconst defaultRetrySchedule = Schedule.min([\n  Schedule.exponential(500, 1.5),\n  Schedule.spaced(\"1 minute\")\n])\n\nconst makeWorkerEffect = Effect.fnUntraced(function*<\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top,\n  R\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  f: (payload: Payload[\"Type\"]) => Effect.Effect<Success[\"Type\"], Error[\"Type\"], R>,\n  concurrency: number,\n  maxAttempts: number\n) {\n  const queue = yield* PersistedQueue.make({\n    name: `DurableQueue/${self.name}`,\n    schema: getQueueSchema(self.payloadSchema),\n    maxAttempts,\n    // The worker owns the 500 ms retry pause below. Keep an upstream queue\n    // default from introducing an additional backoff after an Effect upgrade.\n    retrySchedule: Schedule.spaced(0)\n  })\n\n  const worker = Effect.suspend(() => {\n    let completion:\n      | { readonly token: DurableDeferred.Token; readonly id: string; readonly attempts: number }\n      | undefined\n    return queue.take((item_, metadata) => {\n      const item = item_ as {\n        readonly token: DurableDeferred.Token\n        readonly payload: Payload[\"Type\"]\n        readonly traceId: string\n        readonly spanId: string\n        readonly sampled: boolean\n      }\n      return Effect.withSpan(\n        Effect.gen(function*() {\n          // Parse before running the handler. A malformed completion address\n          // cannot strand a handler result that was already produced.\n          const parsed = yield* DurableDeferred.TokenParsed.parse(item.token)\n          // `process` offers each item under its key and addresses the\n          // deferred `<queue deferred>/<key>`. Anything else in this queue\n          // names a wait point the queue does not own (another queue's item,\n          // a WaitFor gate, a human task), so completing it here would settle\n          // a foreign wait under this queue's success schema.\n          const expected = `${self.deferred.name}/${metadata.id}`\n          if (parsed.deferredName !== expected) {\n            return yield* new DurableDeferred.TokenInvalid({\n              code: \"deferred_mismatch\",\n              message: `The item \"${metadata.id}\" addresses the deferred \"${\n                deferredNameExcerpt(parsed.deferredName)\n              }\", not \"${deferredNameExcerpt(expected)}\".`\n            })\n          }\n          const deferred = DurableDeferred.make(parsed.deferredName, {\n            success: self.deferred.successSchema,\n            error: self.deferred.errorSchema\n          })\n          let exit = yield* Effect.exit(f(item.payload))\n          if (Exit.isFailure(exit)) {\n            const [interrupts, reasons] = Arr.partition(\n              exit.cause.reasons,\n              Filter.fromPredicate(Cause.isInterruptReason)\n            )\n            // Match DurableDeferred.into: interruption alone is not a durable\n            // outcome, and must leave the item available without an attempt.\n            if (interrupts.length === exit.cause.reasons.length) {\n              return yield* Effect.failCause(Cause.fromReasons<never>(interrupts))\n            } else if (interrupts.length > 0) {\n              exit = Exit.failCause(Cause.fromReasons(reasons))\n            }\n          }\n          completion = { token: item.token, ...metadata }\n          yield* DurableDeferred.done(deferred, {\n            token: item.token,\n            exit\n          })\n        }).pipe(\n          Effect.catchTag(\"@smthrs/flow/DurableDeferred/TokenInvalid\", (error) =>\n            Effect.logError(\n              `DurableQueue \"${self.name}\" could not complete an item because its token was invalid. ${error.message}`\n            ))\n        ),\n        `DurableQueue/${self.name}/worker`,\n        {\n          captureStackTrace: false,\n          parent: externalParent(item)\n        }\n      )\n    }).pipe(\n      Effect.tapCause((cause) => {\n        if (!completion) return Effect.void\n        return Effect.logError(\"DurableQueue failed to persist or acknowledge a handler result\", cause).pipe(\n          Effect.annotateLogs({\n            token: completion.token,\n            itemId: completion.id,\n            attempt: completion.attempts,\n            maxAttempts,\n            exhausted: !Cause.hasInterrupts(cause) && completion.attempts >= maxAttempts\n          })\n        )\n      })\n    )\n  }).pipe(\n    // A persistently failing take would otherwise consume a core in a tight\n    // loop while the queue store is unavailable.\n    Effect.catchCause((cause) =>\n      Effect.logWarning(cause).pipe(\n        Effect.andThen(Effect.sleep(500))\n      )\n    ),\n    Effect.forever,\n    Effect.annotateLogs({\n      package: \"@smthrs/flow\",\n      module: \"DurableQueue\",\n      fiber: \"worker\",\n      queueName: self.name\n    })\n  )\n\n  return yield* Effect.replicateEffect(worker, concurrency, { concurrency, discard: true }).pipe(\n    Effect.andThen(Effect.never)\n  )\n})\n\n/**\n * Create a worker effect that processes items from the durable queue.\n *\n * `concurrency` defaults to one and must be a positive safe integer. It is\n * checked before the persisted queue is opened. `maxAttempts` defaults to ten\n * and is passed to the persisted queue. Completion-write failures can rerun the\n * handler; side effects must be idempotent. Exhaustion leaves the flow waiting.\n *\n * @throws A `RangeError` when `concurrency` is not a positive safe integer.\n * @category worker\n * @since 0.1.0\n */\nexport const makeWorker: <\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top,\n  R\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  f: (payload: Payload[\"Type\"]) => Effect.Effect<Success[\"Type\"], Error[\"Type\"], R>,\n  options?: {\n    readonly concurrency?: number | undefined\n    readonly maxAttempts?: number | undefined\n  } | undefined\n) => Effect.Effect<\n  never,\n  never,\n  | FlowRuntime\n  | PersistedQueue.PersistedQueueFactory\n  | R\n  | Payload[\"EncodingServices\"]\n  | Payload[\"DecodingServices\"]\n  | Success[\"EncodingServices\"]\n  | Error[\"EncodingServices\"]\n> = <\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top,\n  R\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  f: (payload: Payload[\"Type\"]) => Effect.Effect<Success[\"Type\"], Error[\"Type\"], R>,\n  options?: {\n    readonly concurrency?: number | undefined\n    readonly maxAttempts?: number | undefined\n  }\n) => {\n  const concurrency = options?.concurrency ?? 1\n  if (!Number.isSafeInteger(concurrency) || concurrency < 1) {\n    throw new RangeError(\n      `DurableQueue.makeWorker: concurrency must be a positive safe integer, and was ${concurrency}.`\n    )\n  }\n  return makeWorkerEffect(self, f, concurrency, options?.maxAttempts ?? 10)\n}\n\n/**\n * Create a layer that runs workers for the durable queue.\n *\n * @category worker\n * @since 0.1.0\n */\nexport const worker: <\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top,\n  R\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  f: (payload: Payload[\"Type\"]) => Effect.Effect<Success[\"Type\"], Error[\"Type\"], R>,\n  options?: {\n    readonly concurrency?: number | undefined\n    readonly maxAttempts?: number | undefined\n  } | undefined\n) => Layer.Layer<\n  never,\n  never,\n  | FlowRuntime\n  | PersistedQueue.PersistedQueueFactory\n  | R\n  | Payload[\"EncodingServices\"]\n  | Payload[\"DecodingServices\"]\n  | Success[\"EncodingServices\"]\n  | Error[\"EncodingServices\"]\n> = (self, f, options) => Layer.effectDiscard(Effect.forkScoped(makeWorker(self, f, options)))\n"]}

package/dist/esm/ExternalJob.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Durable external work as ordinary actions, handoffs and parked timers.
+ *
+ * @since 1.0.0
+ */
+import * as Node from "@smthrs/plan/Node";
+import * as Cause from "effect/Cause";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Action from "./Action/index.ts";
+import * as Flow from "./Flow/index.ts";
+import { FlowInstance } from "./FlowRuntime/FlowInstance.ts";
+import * as Sleep from "./Sleep.ts";
+/**
+ * External process observation.
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Status: Schema.Union<readonly [Schema.Struct<{
+    readonly _tag: Schema.Literal<"Running">;
+}>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"Exited">;
+    readonly exitCode: Schema.Int;
+}>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"Lost">;
+}>]>;
+/**
+ * Decoded external process observation.
+ * @category models
+ * @since 1.0.0
+ */
+export type Status = typeof Status.Type;
+/**
+ * Decoded external process observation.
+ * @category models
+ * @since 1.0.0
+ */
+export type Exited = Extract<Status, {
+    readonly _tag: "Exited";
+}>;
+declare const Again_base: Schema.Class<Again, Schema.TaggedStruct<"@smthrs/flow/ExternalJobAgain", {
+    readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * A collected exit that can be replaced.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class Again extends Again_base {
+}
+declare const ExternalJobLost_base: Schema.Class<ExternalJobLost, Schema.TaggedStruct<"@smthrs/flow/ExternalJobLost", {
+    readonly key: Schema.String;
+    readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * No worker or exit receipt remains.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class ExternalJobLost extends ExternalJobLost_base {
+}
+declare const ExternalJobTimedOut_base: Schema.Class<ExternalJobTimedOut, Schema.TaggedStruct<"@smthrs/flow/ExternalJobTimedOut", {
+    readonly key: Schema.String;
+    readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * The deadline anchored before initial start elapsed.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class ExternalJobTimedOut extends ExternalJobTimedOut_base {
+}
+/**
+ * The adapter's full typed failure union belongs in make's error schema.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Operations<P, H, A, E, R> {
+    readonly start: (payload: P, key: string) => Effect.Effect<H, E, R>;
+    readonly status: (handle: H, key: string) => Effect.Effect<Status, E, R>;
+    readonly collect: (handle: H, key: string, exited: Exited) => Effect.Effect<A, E | Again, R>;
+    readonly cancel: (handle: H, key: string) => Effect.Effect<void, never, R>;
+}
+/**
+ * Create-or-get by execution id and generation. Private ordinary flows carry
+ * journaled state; initial callers cannot supply a key or continuation handle.
+ * `restarts` counts replacement generations; zero permits only g1.
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: <const Tag extends string, P extends Schema.Struct.Fields | Flow.AnyStructSchema, H extends Schema.Top, A extends Schema.Top, E extends Schema.Top = typeof Schema.Never>(tag: Tag, options: {
+    readonly payload: P;
+    readonly handle: H;
+    readonly success: A;
+    readonly error?: E;
+    readonly probe: {
+        readonly every: Duration.Input;
+        readonly max: Duration.Input;
+    };
+    readonly timeout: Duration.Input;
+    readonly restarts?: number;
+}) => {
+    readonly call: (payload: Action.PlannedPayload<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["~type.make.in"]>) => Node.Node<A["Type"], Sleep.SleepRequestInvalid | ExternalJobLost | ExternalJobTimedOut | E["Type"], never>;
+    readonly toLayer: <R>(operations: Operations<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Type"], H["Type"], A["Type"], E["Type"], R>) => Layer.Layer<Layer.Success<Layer.Layer<Action.Requirement<`${Tag}/initialize`> | Action.Requirement<`${Tag}/start`> | Action.Requirement<`${Tag}/status`> | Action.Requirement<`${Tag}/collect`> | Action.Requirement<`${Tag}/cancel`> | Action.Requirement<`${Tag}/fail`> | Action.Requirement<`${Tag}/ready`> | Action.Requirement<`${Tag}/launch-timeout`>, never, import("effect/Crypto").Crypto | import("./FlowRuntime/FlowRuntime.ts").FlowRuntime | Action.Implementations | {
+        executionId: string;
+        current: {
+            handle: H["Type"];
+            key: string;
+        } | undefined;
+    } | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], never> | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"], never> | A["DecodingServices"] | Exclude<A["DecodingServices"], never> | A["EncodingServices"] | Exclude<A["EncodingServices"], never> | E["DecodingServices"] | Exclude<E["DecodingServices"], never> | E["EncodingServices"] | Exclude<E["EncodingServices"], never> | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], never> | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"], never> | Schema.Struct.DecodingServices<{
+        readonly handle: Schema.Codec<H["Type"], H["Encoded"], H["DecodingServices"], H["EncodingServices"]>;
+        readonly input: Schema.Codec<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Type"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Encoded"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"]>;
+        readonly origin: Schema.String;
+        readonly startedAt: Schema.Number;
+        readonly generation: Schema.Int;
+        readonly probe: Schema.Int;
+    }> | Schema.Struct.EncodingServices<{
+        readonly handle: Schema.Codec<H["Type"], H["Encoded"], H["DecodingServices"], H["EncodingServices"]>;
+        readonly input: Schema.Codec<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Type"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Encoded"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"]>;
+        readonly origin: Schema.String;
+        readonly startedAt: Schema.Number;
+        readonly generation: Schema.Int;
+        readonly probe: Schema.Int;
+    }> | Exclude<H["DecodingServices"], never> | Exclude<H["EncodingServices"], never> | Exclude<R, FlowInstance | import("effect/Scope").Scope | import("./FlowRuntime/FlowRuntime.ts").FlowRuntime> | Exclude<R, import("effect/Scope").Scope>>>, Layer.Error<Layer.Layer<Action.Requirement<`${Tag}/initialize`> | Action.Requirement<`${Tag}/start`> | Action.Requirement<`${Tag}/status`> | Action.Requirement<`${Tag}/collect`> | Action.Requirement<`${Tag}/cancel`> | Action.Requirement<`${Tag}/fail`> | Action.Requirement<`${Tag}/ready`> | Action.Requirement<`${Tag}/launch-timeout`>, never, import("effect/Crypto").Crypto | import("./FlowRuntime/FlowRuntime.ts").FlowRuntime | Action.Implementations | {
+        executionId: string;
+        current: {
+            handle: H["Type"];
+            key: string;
+        } | undefined;
+    } | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], never> | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"], never> | A["DecodingServices"] | Exclude<A["DecodingServices"], never> | A["EncodingServices"] | Exclude<A["EncodingServices"], never> | E["DecodingServices"] | Exclude<E["DecodingServices"], never> | E["EncodingServices"] | Exclude<E["EncodingServices"], never> | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], never> | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"], never> | Schema.Struct.DecodingServices<{
+        readonly handle: Schema.Codec<H["Type"], H["Encoded"], H["DecodingServices"], H["EncodingServices"]>;
+        readonly input: Schema.Codec<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Type"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Encoded"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"]>;
+        readonly origin: Schema.String;
+        readonly startedAt: Schema.Number;
+        readonly generation: Schema.Int;
+        readonly probe: Schema.Int;
+    }> | Schema.Struct.EncodingServices<{
+        readonly handle: Schema.Codec<H["Type"], H["Encoded"], H["DecodingServices"], H["EncodingServices"]>;
+        readonly input: Schema.Codec<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Type"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Encoded"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"]>;
+        readonly origin: Schema.String;
+        readonly startedAt: Schema.Number;
+        readonly generation: Schema.Int;
+        readonly probe: Schema.Int;
+    }> | Exclude<H["DecodingServices"], never> | Exclude<H["EncodingServices"], never> | Exclude<R, FlowInstance | import("effect/Scope").Scope | import("./FlowRuntime/FlowRuntime.ts").FlowRuntime> | Exclude<R, import("effect/Scope").Scope>>>, Exclude<Layer.Services<Layer.Layer<Action.Requirement<`${Tag}/initialize`> | Action.Requirement<`${Tag}/start`> | Action.Requirement<`${Tag}/status`> | Action.Requirement<`${Tag}/collect`> | Action.Requirement<`${Tag}/cancel`> | Action.Requirement<`${Tag}/fail`> | Action.Requirement<`${Tag}/ready`> | Action.Requirement<`${Tag}/launch-timeout`>, never, import("effect/Crypto").Crypto | import("./FlowRuntime/FlowRuntime.ts").FlowRuntime | Action.Implementations | {
+        executionId: string;
+        current: {
+            handle: H["Type"];
+            key: string;
+        } | undefined;
+    } | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], never> | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"], never> | A["DecodingServices"] | Exclude<A["DecodingServices"], never> | A["EncodingServices"] | Exclude<A["EncodingServices"], never> | E["DecodingServices"] | Exclude<E["DecodingServices"], never> | E["EncodingServices"] | Exclude<E["EncodingServices"], never> | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], never> | Exclude<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"], never> | Schema.Struct.DecodingServices<{
+        readonly handle: Schema.Codec<H["Type"], H["Encoded"], H["DecodingServices"], H["EncodingServices"]>;
+        readonly input: Schema.Codec<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Type"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Encoded"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"]>;
+        readonly origin: Schema.String;
+        readonly startedAt: Schema.Number;
+        readonly generation: Schema.Int;
+        readonly probe: Schema.Int;
+    }> | Schema.Struct.EncodingServices<{
+        readonly handle: Schema.Codec<H["Type"], H["Encoded"], H["DecodingServices"], H["EncodingServices"]>;
+        readonly input: Schema.Codec<(P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Type"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["Encoded"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["DecodingServices"], (P extends Schema.Struct.Fields ? Schema.Struct<P> : P)["EncodingServices"]>;
+        readonly origin: Schema.String;
+        readonly startedAt: Schema.Number;
+        readonly generation: Schema.Int;
+        readonly probe: Schema.Int;
+    }> | Exclude<H["DecodingServices"], never> | Exclude<H["EncodingServices"], never> | Exclude<R, FlowInstance | import("effect/Scope").Scope | import("./FlowRuntime/FlowRuntime.ts").FlowRuntime> | Exclude<R, import("effect/Scope").Scope>>>, {
+        executionId: string;
+        current: {
+            handle: H["Type"];
+            key: string;
+        } | undefined;
+    }>>;
+} & Flow.Flow<Tag, P extends Schema.Struct.Fields ? Schema.Struct<P> : P, A, Schema.Union<readonly [E, typeof ExternalJobLost, typeof ExternalJobTimedOut, typeof Sleep.SleepRequestInvalid]>, Action.Requirement<string>>;
+export {};
+//# sourceMappingURL=ExternalJob.d.ts.map

package/dist/esm/ExternalJob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalJob.d.ts","sourceRoot":"","sources":["../../src/ExternalJob.ts"],"names":[],"mappings":"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"}