effect-dynamodb 1.28.0 → 1.29.0

package/dist/internal/ProjectionEngine.js

@@ -0,0 +1,837 @@
+/**
+ * The row engine behind EventStore projections (#151, #153, #154, #155).
+ *
+ * One engine serves single-source projections (`EventStore.projection`, one
+ * source and a scalar checkpoint) and multi-source projections
+ * (`EventStore.multiProjection`, a checkpoint per source instance): a row is
+ * read strongly consistent, each contributing instance's events are ordered,
+ * deduplicated and gap-filled from the store, folded, and written once —
+ * conditioned on the row's revision (or, without one, its checkpoint) — as
+ * the row, a tombstone (#154), or either together with outbox items in one
+ * transaction (#155).
+ *
+ * Internal: the public shapes live in `EventProjection.ts` / `MultiProjection.ts`.
+ *
+ * @internal
+ */
+import { ConcurrentModification, isAwsConditionalCheckFailed, isAwsTransactionCancelled, ProjectionSourceConflict, ValidationError, } from "@effect-dynamodb/schema/Errors.js";
+import { DateTime, Duration as Dur, Effect, Option, Random, Result, Schema as S, Schedule, } from "effect";
+import { DynamoClient } from "../DynamoClient.js";
+import { decodeMarshalledItem } from "../Entity.js";
+import { fromAttributeMap, toAttributeMap } from "../Marshaller.js";
+import { resolveTtlAttributeName } from "../Table.js";
+import { condition as entityCondition } from "./EntityCombinators.js";
+import { composePrimaryKey, generateTimestampPrimitive, validateAndBuildPutItem, } from "./TransactableOps.js";
+// ---------------------------------------------------------------------------
+// Removal (#154)
+// ---------------------------------------------------------------------------
+const RemoveRowTypeId = Symbol.for("effect-dynamodb/EventStore/RemoveRow");
+/**
+ * Returned from a projection's `evolve`, removes the row: the library writes a
+ * tombstone at the row's key that keeps its checkpoints (and revision), so a
+ * redelivery can't recreate it. A later event starts the row again from
+ * `initial`. Requires `removal` on the projection.
+ */
+export const removeRow = { [RemoveRowTypeId]: RemoveRowTypeId };
+/** @internal */
+export const isRemoveRow = (u) => typeof u === "object" && u !== null && RemoveRowTypeId in u;
+/** The `__edd_e__` of a read model's tombstones. */
+export const tombstoneMarker = (entityType) => `${entityType}#tombstone`;
+/** The `__edd_e__` of a read model's outbox items. */
+export const outboxMarker = (entityType) => `${entityType}#outbox`;
+/** Attribute names the engine owns on tombstones and outbox items. */
+export const REMOVED_AT = "__edd_removed__";
+const CLAIM_TOKEN = "__edd_claim__";
+const CLAIMED_UNTIL = "__edd_claimed_until__";
+const ROW_PK = "__edd_row_pk__";
+const ROW_SK = "__edd_row_sk__";
+/** The engine's own lost-race signal. */
+class LostRace {
+    key;
+    constructor(key) {
+        this.key = key;
+    }
+}
+// ---------------------------------------------------------------------------
+// The engine
+// ---------------------------------------------------------------------------
+/** A key's identity: its fields, sorted, as JSON. */
+export const keyId = (key) => JSON.stringify(Object.entries(key).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+/** `K | Option<K>` → `Option<K>`. */
+export const addressed = (key) => Option.isOption(key) ? key : Option.some(key);
+/** A map checkpoint's key. */
+export const instanceKey = (source, streamId) => `${source}#${streamId}`;
+/** @internal */
+export const modelFields = (model) => {
+    const fields = model.fields;
+    return typeof fields === "object" && fields !== null ? Object.keys(fields) : undefined;
+};
+/** @internal */
+export const makeEngine = (config) => {
+    const { readModel } = config;
+    const entityType = readModel.entityType;
+    const fields = modelFields(readModel.model);
+    const createdAtField = readModel.systemFields.createdAt;
+    /** A domain field's stored attribute name. */
+    const dbName = (field) => {
+        const probe = { [field]: 1 };
+        readModel._renameToDynamo(probe);
+        return Object.keys(probe)[0] ?? field;
+    };
+    const primary = readModel.indexes.primary;
+    const call = (name, f) => Effect.try({
+        try: f,
+        catch: (cause) => new ValidationError({ entityType, operation: `${config.label}.${name}`, cause }),
+    });
+    /** The checkpoint and revision fields a tombstone keeps. */
+    const keptFields = (() => {
+        const kept = new Set();
+        if (config.revision !== undefined)
+            kept.add(config.revision.field);
+        const layout = config.checkpoints;
+        if (layout.kind === "scalar")
+            kept.add(layout.field);
+        else {
+            if (layout.map !== undefined)
+                kept.add(layout.map);
+            for (const f of Object.values(layout.fields)) {
+                kept.add(f.field);
+                kept.add(f.instanceField);
+            }
+        }
+        return [...kept];
+    })();
+    // Resolved when it runs: an entity's table is set when it is registered on
+    // one, which may come after the projection is defined.
+    // Rows may be tombstones (#154): the entity's `create` takes one's place,
+    // keeping these fields — the checkpoints — and the revision one higher.
+    if (config.removal !== undefined) {
+        ;
+        readModel._projectionTombstones = {
+            kept: keptFields.filter((f) => f !== config.revision?.field),
+            revision: config.revision?.field,
+        };
+    }
+    const tableName = Effect.suspend(() => Effect.map(readModel._tableTag, (tc) => tc.name));
+    /** The row, read strongly consistent — raw, so a tombstone reads as one. */
+    const readRow = (key) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        const TableName = yield* tableName;
+        const result = yield* client.getItem({
+            TableName,
+            Key: toAttributeMap(composePrimaryKey(readModel, key)),
+            ConsistentRead: true,
+        });
+        const item = result.Item;
+        if (item === undefined)
+            return Option.none();
+        if (item.__edd_e__?.S === tombstoneMarker(entityType)) {
+            const raw = fromAttributeMap(item);
+            const values = {};
+            for (const f of keptFields) {
+                const v = raw[dbName(f)];
+                if (v !== undefined)
+                    values[f] = v;
+            }
+            return Option.some({ values, tombstone: true, createdAt: undefined });
+        }
+        const decoded = (yield* decodeMarshalledItem(readModel, item));
+        let values = decoded;
+        if (fields !== undefined) {
+            values = {};
+            for (const f of fields)
+                if (decoded[f] !== undefined)
+                    values[f] = decoded[f];
+        }
+        return Option.some({
+            values: readModel._attachPrototype?.(values) ?? values,
+            tombstone: false,
+            createdAt: createdAtField === null ? undefined : decoded[createdAtField],
+        });
+    });
+    /**
+     * `claimed` records, per field-mapped source, the instance that owns its
+     * field in this attempt — so two instances of one source never both take it.
+     */
+    const slotOf = (row, source, streamIdStr, claimed) => {
+        const values = Option.isSome(row) ? row.value.values : undefined;
+        const layout = config.checkpoints;
+        if (layout.kind === "scalar") {
+            const v = values?.[layout.field];
+            return { kind: "scalar", at: v === undefined ? 0 : Number(v) - layout.offset };
+        }
+        const mapped = layout.fields[source];
+        const fromMap = () => {
+            const map = (values?.[layout.map] ?? {});
+            const v = map[instanceKey(source, streamIdStr)];
+            return { kind: "map", at: v === undefined ? 0 : Number(v) };
+        };
+        if (mapped === undefined)
+            return fromMap();
+        const stored = values?.[mapped.instanceField];
+        const owner = claimed.get(source) ?? (stored === null || stored === "" ? undefined : stored);
+        const scalar = values?.[mapped.field];
+        // No owner recorded: a new row, or a legacy one — adopted by this instance.
+        if (owner === undefined || owner === streamIdStr) {
+            claimed.set(source, streamIdStr);
+            return { kind: "field", at: scalar === undefined ? 0 : Number(scalar) - mapped.offset };
+        }
+        if (layout.map !== undefined)
+            return fromMap();
+        return new ProjectionSourceConflict({
+            entityType,
+            source,
+            recorded: String(owner),
+            arriving: streamIdStr,
+        });
+    };
+    /** The row's revision, when the projection keeps one. */
+    const revisionOf = (row) => {
+        if (config.revision === undefined || Option.isNone(row))
+            return undefined;
+        const v = row.value.values[config.revision.field];
+        return v === undefined ? undefined : Number(v);
+    };
+    /** The revision the next write stores: one higher, or `initial` for a row without one. */
+    const nextRevisionOf = (row) => {
+        const current = revisionOf(row);
+        return current === undefined ? config.revision.initial : current + 1;
+    };
+    /** Write the instances' new checkpoints (and the next revision) onto `target`. */
+    const stamp = (target, row, advanced) => {
+        const layout = config.checkpoints;
+        const previous = Option.isSome(row) ? row.value.values : undefined;
+        if (layout.kind === "scalar") {
+            for (const a of advanced)
+                target[layout.field] = a.version + layout.offset;
+        }
+        else {
+            // Carry every field the layout owns over from the row, then advance.
+            for (const f of Object.values(layout.fields)) {
+                if (target[f.field] === undefined && previous?.[f.field] !== undefined)
+                    target[f.field] = previous[f.field];
+                if (target[f.instanceField] === undefined && previous?.[f.instanceField] !== undefined) {
+                    target[f.instanceField] = previous[f.instanceField];
+                }
+            }
+            const map = layout.map === undefined
+                ? {}
+                : { ...(previous?.[layout.map] ?? {}) };
+            for (const a of advanced) {
+                if (a.slot.kind === "field") {
+                    const mapped = layout.fields[a.source];
+                    target[mapped.field] = a.version + mapped.offset;
+                    target[mapped.instanceField] = a.streamIdStr;
+                }
+                else
+                    map[instanceKey(a.source, a.streamIdStr)] = a.version;
+            }
+            if (layout.map !== undefined)
+                target[layout.map] = map;
+        }
+        if (config.revision !== undefined)
+            target[config.revision.field] = nextRevisionOf(row);
+    };
+    /** The write's condition — the revision read, else the scalar checkpoint read. */
+    const guard = (row) => {
+        if (config.revision !== undefined) {
+            const rev = revisionOf(row);
+            const name = dbName(config.revision.field);
+            return rev === undefined
+                ? {
+                    input: Option.isSome(row) ? { attributeNotExists: config.revision.field } : undefined,
+                    raw: { expression: "attribute_not_exists(#g)", names: { "#g": name }, values: {} },
+                }
+                : {
+                    input: { eq: { [config.revision.field]: rev } },
+                    raw: {
+                        expression: "#g = :g",
+                        names: { "#g": name },
+                        values: toAttributeMap({ ":g": rev }),
+                    },
+                };
+        }
+        const layout = config.checkpoints;
+        if (Option.isNone(row)) {
+            return {
+                input: undefined,
+                raw: {
+                    expression: "attribute_not_exists(#g)",
+                    names: { "#g": primary.pk.field },
+                    values: {},
+                },
+            };
+        }
+        const stored = row.value.values[layout.field];
+        return {
+            input: { eq: { [layout.field]: stored } },
+            raw: {
+                expression: "#g = :g",
+                names: { "#g": dbName(layout.field) },
+                values: toAttributeMap({ ":g": stored }),
+            },
+        };
+    };
+    const outboxTable = Effect.gen(function* () {
+        if (config.outbox?.table === undefined)
+            return yield* tableName;
+        const tc = (yield* config.outbox.table.Tag);
+        return tc.name;
+    });
+    /** The outbox items' key attribute names (the row table's, or the outbox table's). */
+    const outboxKeys = () => config.outbox?.table === undefined
+        ? { pk: primary.pk.field, sk: primary.sk.field }
+        : { pk: config.outbox.pk, sk: config.outbox.sk };
+    const pad = (n, width) => String(n).padStart(width, "0");
+    const outboxItems = (rowKey, revision, enqueued) => Effect.forEach(enqueued, (e, i) => Effect.gen(function* () {
+        const outbox = config.outbox;
+        const encoded = yield* S.encodeUnknownEffect(outbox.schema)(e.effect).pipe(Effect.mapError((cause) => new ValidationError({ entityType, operation: `${config.label}.outbox`, cause })));
+        const keys = outboxKeys();
+        const rowPk = String(rowKey[primary.pk.field]);
+        const rowSk = String(rowKey[primary.sk.field]);
+        const sk = `${rowSk}#outbox#${pad(revision, 12)}#${pad(i, 4)}`;
+        const item = {
+            [keys.pk]: rowPk,
+            [keys.sk]: sk,
+            __edd_e__: outboxMarker(entityType),
+            [ROW_PK]: rowPk,
+            [ROW_SK]: rowSk,
+            effect: encoded,
+            source: e.source,
+            streamId: e.event.streamId,
+            version: e.event.version,
+            eventType: e.event.eventType,
+        };
+        if (outbox.index !== undefined) {
+            item[outbox.index.pk] = outboxMarker(entityType);
+            item[outbox.index.sk] = `${rowPk}#${sk}`;
+        }
+        return toAttributeMap(item);
+    }));
+    /** A lost race, from a single write's or a transaction's failure. */
+    const lostRaceOf = (error, transaction) => {
+        const cause = error?.cause;
+        if (!transaction)
+            return isAwsConditionalCheckFailed(cause);
+        return (isAwsTransactionCancelled(cause) &&
+            cause.CancellationReasons?.[0]?.Code === "ConditionalCheckFailed");
+    };
+    /** The row (or tombstone) and any outbox items, written as one conditional unit. */
+    const writeRow = (key, target, kept, row, enqueued, revision) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        const TableName = yield* tableName;
+        const rowKey = composePrimaryKey(readModel, key);
+        const condition = guard(row);
+        const createdAt = Option.isSome(row) ? row.value.createdAt : undefined;
+        // The row's item: the entity's own `put` (no outbox), or built for a transaction.
+        let rowItem;
+        if (Option.isNone(target)) {
+            // A tombstone: the key, the kept checkpoint fields, the revision.
+            const tc = (yield* readModel._tableTag);
+            const now = yield* DateTime.now;
+            const tomb = {
+                ...rowKey,
+                __edd_e__: tombstoneMarker(entityType),
+                [REMOVED_AT]: DateTime.formatIso(now),
+            };
+            for (const [f, v] of Object.entries(kept))
+                tomb[dbName(f)] = v;
+            if (config.removal?.ttl !== undefined) {
+                tomb[resolveTtlAttributeName(tc)] = Math.floor((DateTime.toEpochMillis(now) + Dur.toMillis(config.removal.ttl)) / 1000);
+            }
+            rowItem = toAttributeMap(tomb);
+        }
+        else if (enqueued.length > 0) {
+            const built = yield* validateAndBuildPutItem(readModel, target.value, `${config.label}.write`);
+            const item = { ...built.item };
+            if (createdAtField !== null && DateTime.isDateTime(createdAt)) {
+                item[dbName(createdAtField)] = generateTimestampPrimitive(DateTime.toUtc(createdAt), readModel.systemFields.createdAtEncoding);
+            }
+            rowItem = toAttributeMap(item);
+        }
+        if (rowItem === undefined) {
+            // The row alone, through the entity: `put` conditioned on the guard
+            // (keeping the row's `createdAt`), or `create` for a new row.
+            const value = target.pipe(Option.getOrThrow);
+            const op = condition.input === undefined
+                ? readModel.create(value)
+                : entityCondition(readModel.put(value), condition.input);
+            const run = condition.input === undefined
+                ? op.asEffect()
+                : op._builder("model", {
+                    condition: op._condition,
+                    withVectors: op._withVectors,
+                    putKind: op._putKind,
+                    createdAt: DateTime.isDateTime(createdAt) ? DateTime.toUtc(createdAt) : undefined,
+                });
+            const written = yield* run.pipe(Effect.catchTag("ConditionalCheckFailed", () => Effect.fail(new LostRace(key))));
+            return Option.some(written);
+        }
+        const rowPut = {
+            Put: {
+                TableName,
+                Item: rowItem,
+                ConditionExpression: condition.raw.expression,
+                ExpressionAttributeNames: condition.raw.names,
+                ...(Object.keys(condition.raw.values).length > 0
+                    ? { ExpressionAttributeValues: condition.raw.values }
+                    : {}),
+            },
+        };
+        if (enqueued.length === 0) {
+            yield* client.putItem(rowPut.Put).pipe(Effect.catchIf((error) => lostRaceOf(error, false), () => Effect.fail(new LostRace(key))));
+        }
+        else {
+            const OutboxTable = yield* outboxTable;
+            const items = yield* outboxItems(rowKey, revision ?? 0, enqueued);
+            yield* client
+                .transactWriteItems({
+                TransactItems: [
+                    rowPut,
+                    ...items.map((Item) => ({ Put: { TableName: OutboxTable, Item } })),
+                ],
+            })
+                .pipe(Effect.catchIf((error) => lostRaceOf(error, true), () => Effect.fail(new LostRace(key))));
+        }
+        return target;
+    });
+    // -------------------------------------------------------------------------
+    // Apply
+    // -------------------------------------------------------------------------
+    /** Every version from `from` to the last of `events` was delivered. */
+    const coveredFrom = (events, from, delivered) => {
+        const own = new Set(events.map((e) => e.version));
+        const last = events[events.length - 1].version;
+        for (let v = from; v <= last; v++)
+            if (!own.has(v) && !delivered.has(v))
+                return false;
+        return true;
+    };
+    const gapError = (streamId, from, to) => Effect.fail(new ValidationError({
+        entityType,
+        operation: config.label,
+        cause: `Stream ${JSON.stringify(streamId)} is missing events between versions ${from} and ` +
+            `${to}: a strongly consistent read did not return them. Was the stream written ` +
+            "outside `append`?",
+    }));
+    const withRetry = (attempt) => Effect.retry(attempt, {
+        schedule: config.retry,
+        while: (error) => error instanceof LostRace,
+    }).pipe(Effect.mapError((error) => error instanceof LostRace
+        ? new ConcurrentModification({
+            entityType,
+            key: error.key,
+            attributes: [
+                config.revision?.field ?? config.checkpoints.field,
+            ],
+            current: Option.none(),
+        })
+        : error));
+    /** The row's events of one instance: its checkpoint, what to fold, what was already in. */
+    const runOf = (rowId, slotAt, work) => Effect.gen(function* () {
+        const alreadyApplied = work.events?.filter((e) => e.version <= slotAt) ?? [];
+        const pending = work.events?.filter((e) => e.version > slotAt);
+        if (pending !== undefined ? pending.length === 0 : slotAt >= work.top) {
+            return { run: [], alreadyApplied };
+        }
+        // `latest` reads nothing: its candidates are the batch's events.
+        if (work.source.mode === "latest" && pending !== undefined)
+            return { run: pending, alreadyApplied };
+        if (pending !== undefined && coveredFrom(pending, slotAt + 1, work.delivered)) {
+            return { run: pending, alreadyApplied };
+        }
+        const upTo = pending === undefined ? work.top : pending[pending.length - 1].version;
+        const read = (yield* work.source.stream.readFrom(work.streamId, slotAt, {
+            consistentRead: true,
+            toVersion: upTo,
+        }));
+        let last = slotAt;
+        for (const e of read) {
+            if (e.version !== last + 1)
+                return yield* gapError(work.streamIdStr, last + 1, upTo);
+            last = e.version;
+        }
+        if (last < upTo)
+            return yield* gapError(work.streamIdStr, last + 1, upTo);
+        const mine = [];
+        for (const e of read) {
+            const key = addressed(yield* call("key", () => work.source.key(work.streamId, e)));
+            if (Option.isSome(key) && keyId(key.value) === rowId)
+                mine.push(e);
+        }
+        return { run: mine, alreadyApplied };
+    });
+    /**
+     * Apply a row's work: read, gap-fill per instance, fold in a deterministic
+     * order (sources as declared, then stream id, then version), write once.
+     * `fromScratch` folds from `initial` ignoring the row's state (rebuild).
+     */
+    const applyRow = (key, work, options) => {
+        const rowId = keyId(key);
+        const ordered = [...work].sort((a, b) => {
+            const sa = config.sources.indexOf(a.source);
+            const sb = config.sources.indexOf(b.source);
+            return sa !== sb
+                ? sa - sb
+                : a.streamIdStr < b.streamIdStr
+                    ? -1
+                    : a.streamIdStr > b.streamIdStr
+                        ? 1
+                        : 0;
+        });
+        const attempt = Effect.gen(function* () {
+            const row = yield* readRow(key);
+            /**
+             * Instances that failed (not by `terminal`): left out of this write —
+             * their checkpoints don't move — and reported, so the row's other
+             * sources still apply.
+             */
+            const failed = [];
+            const plans = [];
+            const claimed = new Map();
+            const slotRow = options?.fromScratch === true ? Option.none() : row;
+            for (const w of ordered) {
+                const slot = slotOf(slotRow, w.source.name, w.streamIdStr, claimed);
+                if (slot instanceof ProjectionSourceConflict) {
+                    failed.push({ source: w.source.name, streamId: w.streamIdStr, error: slot });
+                    continue;
+                }
+                const at = options?.fromScratch === true ? 0 : slot.at;
+                const r = yield* Effect.result(runOf(rowId, at, w));
+                if (Result.isFailure(r)) {
+                    failed.push({ source: w.source.name, streamId: w.streamIdStr, error: r.failure });
+                    continue;
+                }
+                plans.push({ work: w, slot, ...r.success });
+            }
+            const initialState = options?.fromScratch === true || Option.isNone(row) || row.value.tombstone
+                ? Option.none()
+                : Option.some(row.value.values);
+            const initiallyRemoved = Option.isSome(row) && row.value.tombstone && options?.fromScratch !== true;
+            /** Fold `active`; the index of the first instance that fails, if one does. */
+            const foldAll = (active) => Effect.gen(function* () {
+                let state = initialState;
+                let removed = initiallyRemoved;
+                const enqueued = [];
+                const results = [];
+                for (const [index, plan] of active.entries()) {
+                    const applied = [];
+                    const rejected = [];
+                    const superseded = [];
+                    const context = {
+                        source: plan.work.source.name,
+                        streamId: plan.work.streamIdStr,
+                    };
+                    /** Evolve one event onto the current state: its next state, or its failure. */
+                    const evolveOne = (event) => Effect.result(Effect.gen(function* () {
+                        const base = Option.isSome(state)
+                            ? state.value
+                            : yield* call("initial", () => config.initial(key, {
+                                source: context.source,
+                                streamId: plan.work.streamId,
+                                event,
+                            }));
+                        const next = yield* plan.work.source.evolve(base, event, context);
+                        if (isRemoveRow(next) && config.removal === undefined) {
+                            return yield* new ValidationError({
+                                entityType,
+                                operation: config.label,
+                                cause: "`evolve` returned `removeRow`, but the projection declares no `removal`.",
+                            });
+                        }
+                        const effects = config.outbox === undefined
+                            ? []
+                            : yield* call("outbox", () => config.outbox.effects(event, isRemoveRow(next) ? undefined : next, context));
+                        return { next, effects };
+                    }));
+                    const accept = (event, outcome) => {
+                        if (isRemoveRow(outcome.next)) {
+                            state = Option.none();
+                            removed = true;
+                        }
+                        else {
+                            state = Option.some(outcome.next);
+                            removed = false;
+                        }
+                        applied.push(event);
+                        for (const effect of outcome.effects)
+                            enqueued.push({ effect, event, source: context.source });
+                    };
+                    if (plan.work.source.mode === "latest") {
+                        // Newest first, until one is accepted: rejections fall back to an
+                        // older event, and only those older than the accepted one are passed over.
+                        for (let i = plan.run.length - 1; i >= 0; i--) {
+                            const event = plan.run[i];
+                            const result = yield* evolveOne(event);
+                            if (Result.isSuccess(result)) {
+                                accept(event, result.success);
+                                superseded.push(...plan.run.slice(0, i));
+                                break;
+                            }
+                            if (plan.work.source.terminal?.(result.failure) === true) {
+                                rejected.unshift({ event, error: result.failure });
+                            }
+                            else
+                                return { failedAt: index, error: result.failure };
+                        }
+                    }
+                    else {
+                        for (const event of plan.run) {
+                            const result = yield* evolveOne(event);
+                            if (Result.isSuccess(result))
+                                accept(event, result.success);
+                            else if (plan.work.source.terminal?.(result.failure) === true) {
+                                rejected.push({ event, error: result.failure });
+                            }
+                            else
+                                return { failedAt: index, error: result.failure };
+                        }
+                    }
+                    results.push({ applied, rejected, superseded });
+                }
+                return { folded: { state, removed, enqueued, results } };
+            });
+            // Fold; an instance that fails is set aside and the rest folded again.
+            let active = plans;
+            let folded;
+            while (true) {
+                const attempt = yield* foldAll(active);
+                if ("folded" in attempt) {
+                    folded = attempt.folded;
+                    break;
+                }
+                const bad = active[attempt.failedAt];
+                failed.push({
+                    source: bad.work.source.name,
+                    streamId: bad.work.streamIdStr,
+                    error: attempt.error,
+                });
+                active = active.filter((p) => p !== bad);
+            }
+            // Every instance failed: the row fails, with the first failure.
+            if (active.length === 0 && failed.length > 0)
+                return yield* Effect.fail(failed[0].error);
+            const { state, removed, enqueued, results } = folded;
+            const instances = (version) => active.map((plan, i) => ({
+                source: plan.work.source.name,
+                streamId: plan.work.streamIdStr,
+                applied: results[i].applied,
+                alreadyApplied: plan.alreadyApplied,
+                rejected: results[i].rejected,
+                superseded: results[i].superseded,
+                version: version(i),
+            }));
+            const unchanged = () => ({
+                key,
+                instances: instances((i) => active[i].slot.at),
+                state: Option.isSome(row) && !row.value.tombstone
+                    ? Option.some(row.value.values)
+                    : Option.none(),
+                removed: Option.isSome(row) && row.value.tombstone,
+                revision: revisionOf(row),
+                enqueued: 0,
+                failed,
+            });
+            const consumed = active.some((p) => p.run.length > 0);
+            if (!consumed && options?.fromScratch !== true)
+                return unchanged();
+            // No row came of it (only rejections, and none existed): write nothing.
+            if (Option.isNone(state) && !removed)
+                return unchanged();
+            // The new checkpoints: every event considered, applied or not.
+            const advanced = active
+                .filter((p) => p.run.length > 0 || options?.fromScratch === true)
+                .map((p) => ({
+                source: p.work.source.name,
+                streamIdStr: p.work.streamIdStr,
+                slot: p.slot,
+                version: p.run.length > 0 ? p.run[p.run.length - 1].version : p.slot.at,
+            }));
+            const target = Option.isSome(state)
+                ? { ...state.value }
+                : {};
+            stamp(target, options?.fromScratch === true ? Option.none() : row, advanced);
+            if (options?.fromScratch === true && config.revision !== undefined) {
+                target[config.revision.field] = nextRevisionOf(row);
+            }
+            const nextRevision = config.revision === undefined ? undefined : target[config.revision.field];
+            let written;
+            if (Option.isNone(state)) {
+                // A tombstone keeps exactly the layout's fields.
+                written = yield* writeRow(key, Option.none(), pick(target), row, enqueued, nextRevision);
+            }
+            else {
+                const mapped = config.toItem === undefined
+                    ? target
+                    : {
+                        ...(yield* call("toItem", () => config.toItem(target, config.toItemContext(key, work)))),
+                        ...pick(target),
+                    };
+                written = yield* writeRow(key, Option.some(mapped), {}, row, enqueued, nextRevision);
+            }
+            const versions = new Map(advanced.map((a) => [`${a.source}\u0000${a.streamIdStr}`, a.version]));
+            return {
+                key,
+                instances: instances((i) => versions.get(`${active[i].work.source.name}\u0000${active[i].work.streamIdStr}`) ??
+                    active[i].slot.at),
+                state: written,
+                removed: Option.isNone(state),
+                revision: nextRevision,
+                enqueued: enqueued.length,
+                failed,
+            };
+        });
+        return withRetry(attempt);
+    };
+    /** The fields the library owns, re-applied after `toItem`. */
+    const pick = (target) => {
+        const out = {};
+        for (const f of keptFields)
+            if (target[f] !== undefined)
+                out[f] = target[f];
+        return out;
+    };
+    // -------------------------------------------------------------------------
+    // Outbox drain (#155)
+    // -------------------------------------------------------------------------
+    /**
+     * Deliver a row's pending effects in order: claim the head item, deliver it,
+     * delete it, repeat. A claim another drainer holds stops the drain; a crash
+     * leaves a claim that expires, so the effect is delivered again.
+     */
+    const drainRaw = (rowPk, rowSk, deliver) => Effect.gen(function* () {
+        const outbox = config.outbox;
+        const client = yield* DynamoClient;
+        const TableName = yield* outboxTable;
+        const keys = outboxKeys();
+        let delivered = 0;
+        while (true) {
+            const page = yield* client.query({
+                TableName,
+                KeyConditionExpression: "#pk = :pk AND begins_with(#sk, :sk)",
+                ExpressionAttributeNames: { "#pk": keys.pk, "#sk": keys.sk },
+                ExpressionAttributeValues: toAttributeMap({ ":pk": rowPk, ":sk": `${rowSk}#outbox#` }),
+                ConsistentRead: true,
+                Limit: 1,
+            });
+            const head = page.Items?.[0];
+            if (head === undefined)
+                return { delivered, undelivered: Option.none() };
+            const raw = fromAttributeMap(head);
+            const now = DateTime.toEpochMillis(yield* DateTime.now);
+            const token = `${now}-${Math.floor((yield* Random.next) * 1e9)}`;
+            const claimed = yield* client
+                .updateItem({
+                TableName,
+                Key: toAttributeMap({ [keys.pk]: raw[keys.pk], [keys.sk]: raw[keys.sk] }),
+                UpdateExpression: "SET #c = :c, #u = :u",
+                ConditionExpression: "attribute_exists(#pk) AND (attribute_not_exists(#u) OR #u < :now)",
+                ExpressionAttributeNames: { "#c": CLAIM_TOKEN, "#u": CLAIMED_UNTIL, "#pk": keys.pk },
+                ExpressionAttributeValues: toAttributeMap({
+                    ":c": token,
+                    ":u": now + Dur.toMillis(outbox.claimFor),
+                    ":now": now,
+                }),
+            })
+                .pipe(Effect.as(true), Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.succeed(false)));
+            // Another drainer holds the head: it delivers in order; stop here.
+            if (!claimed)
+                return { delivered, undelivered: Option.none() };
+            const effect = yield* S.decodeUnknownEffect(outbox.schema)(raw.effect).pipe(Effect.mapError((cause) => new ValidationError({ entityType, operation: `${config.label}.drain`, cause })));
+            const meta = {
+                source: String(raw.source),
+                streamId: String(raw.streamId),
+                version: Number(raw.version),
+                eventType: String(raw.eventType),
+            };
+            const outcome = yield* Effect.result(deliver(effect, meta));
+            if (Result.isFailure(outcome)) {
+                // Release the claim so the next drain retries promptly.
+                yield* client
+                    .updateItem({
+                    TableName,
+                    Key: toAttributeMap({ [keys.pk]: raw[keys.pk], [keys.sk]: raw[keys.sk] }),
+                    UpdateExpression: "REMOVE #c, #u",
+                    ConditionExpression: "#c = :c",
+                    ExpressionAttributeNames: { "#c": CLAIM_TOKEN, "#u": CLAIMED_UNTIL },
+                    ExpressionAttributeValues: toAttributeMap({ ":c": token }),
+                })
+                    .pipe(Effect.ignore);
+                return { delivered, undelivered: Option.some({ meta, error: outcome.failure }) };
+            }
+            // Delivered: remove it, whoever holds the claim now. A drainer whose
+            // claim expired mid-delivery must still retire the effect, or two
+            // slow drainers re-claim it in turn forever.
+            yield* client
+                .deleteItem({
+                TableName,
+                Key: toAttributeMap({ [keys.pk]: raw[keys.pk], [keys.sk]: raw[keys.sk] }),
+                ConditionExpression: "attribute_exists(#pk)",
+                ExpressionAttributeNames: { "#pk": keys.pk },
+            })
+                .pipe(Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.void));
+            delivered++;
+        }
+    });
+    const drain = (key, deliver) => {
+        const rowKey = composePrimaryKey(readModel, key);
+        return drainRaw(String(rowKey[primary.pk.field]), String(rowKey[primary.sk.field]), deliver);
+    };
+    /** Every row with pending effects, through the outbox's sparse index, drained. */
+    const drainPending = (deliver) => Effect.gen(function* () {
+        const outbox = config.outbox;
+        if (outbox.index === undefined) {
+            return yield* new ValidationError({
+                entityType,
+                operation: `${config.label}.drainPending`,
+                cause: "`drainPending` needs `outbox.index` (a sparse index over the outbox items).",
+            });
+        }
+        const client = yield* DynamoClient;
+        const TableName = yield* outboxTable;
+        const rows = new Map();
+        let start;
+        do {
+            const page = yield* client.query({
+                TableName,
+                IndexName: outbox.index.name,
+                KeyConditionExpression: "#p = :p",
+                ExpressionAttributeNames: { "#p": outbox.index.pk },
+                ExpressionAttributeValues: toAttributeMap({ ":p": outboxMarker(entityType) }),
+                ...(start === undefined ? {} : { ExclusiveStartKey: start }),
+            });
+            for (const item of page.Items ?? []) {
+                const raw = fromAttributeMap(item);
+                const pk = String(raw[ROW_PK]);
+                const sk = String(raw[ROW_SK]);
+                rows.set(`${pk}\u0000${sk}`, [pk, sk]);
+            }
+            start = page.LastEvaluatedKey;
+        } while (start !== undefined);
+        let delivered = 0;
+        const undelivered = [];
+        for (const [pk, sk] of rows.values()) {
+            const result = yield* drainRaw(pk, sk, deliver);
+            delivered += result.delivered;
+            if (Option.isSome(result.undelivered))
+                undelivered.push(result.undelivered.value);
+        }
+        return { delivered, undelivered };
+    });
+    return { readRow, applyRow, drain, drainPending, call };
+};
+/**
+ * The default lost-race policy: up to 12 retries after a jittered delay
+ * growing from 5 ms by 1.5× (about 1.3 s in all).
+ */
+export const defaultRetry = Schedule.max([
+    Schedule.jittered(Schedule.exponential("5 millis", 1.5)),
+    Schedule.recurs(12),
+]);
+/** The `retry` option as a schedule. */
+export const retrySchedule = (retry) => (retry === undefined
+    ? defaultRetry
+    : typeof retry === "number"
+        ? Schedule.recurs(retry)
+        : retry);
+//# sourceMappingURL=ProjectionEngine.js.map