effect-dynamodb 1.11.0 → 1.12.1

package/dist/EventStore.js

@@ -5,19 +5,39 @@
  * - `Decider` type for command-event-state modeling
  * - `makeStream` factory for creating event streams bound to a Table
  * - Core operations: `append`, `read`, `readFrom`, `currentVersion`
- * - `commandHandler` combinator for read-decide-append cycle
+ * - Snapshot primitives: `writeSnapshot`, `readSnapshot`
+ * - `commandHandler` combinator for read-decide-append cycle (snapshot-aware,
+ *   with an optional `VersionConflict` retry policy)
  * - `fold` / `foldFrom` helpers for state reconstruction
  *
  * Built on the existing library primitives (DynamoSchema, KeyComposer, Query,
  * DynamoClient, Marshaller).
  */
 import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.js";
-import { isAwsTransactionCancelled, TransactionCancelled, ValidationError, VersionConflict, } from "@effect-dynamodb/schema/Errors.js";
+import { normalizeTtlSeconds } from "@effect-dynamodb/schema/Entity.js";
+import { AdditionalItemConditionFailed, AppendTooLarge, DuplicateCommand, isAwsConditionalCheckFailed, isAwsTransactionCancelled, TRANSACT_WRITE_ITEMS_LIMIT, TransactionCancelled, ValidationError, VersionConflict, } from "@effect-dynamodb/schema/Errors.js";
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
-import { DateTime, Effect, Function, Schema } from "effect";
+import { DateTime, Effect, Function, Option, Pipeable, Schedule, Schema, } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
-import { toAttributeMap } from "./Marshaller.js";
+import { buildTransactWriteItems, } from "./internal/TransactWriteOps.js";
+import { fromAttributeMap, toAttributeMap } from "./Marshaller.js";
 import * as Query from "./Query.js";
+import { resolveTtlAttributeName } from "./Table.js";
+// ---------------------------------------------------------------------------
+// Envelope schema — validates the persisted event's system fields on read
+// ---------------------------------------------------------------------------
+/**
+ * Schema for the persisted event envelope (system fields written by `append`).
+ * Event `data` and `metadata` are decoded separately through their own schemas.
+ *
+ * @internal
+ */
+const EventEnvelope = Schema.Struct({
+    streamId: Schema.String,
+    version: Schema.Number,
+    eventType: Schema.String,
+    timestamp: Schema.String,
+});
 // ---------------------------------------------------------------------------
 // EventStreamTypeId
 // ---------------------------------------------------------------------------
@@ -28,13 +48,18 @@ const EventStreamTypeId = Symbol.for("effect-dynamodb/EventStream");
 /**
  * Create an EventStream bound to a Table.
  *
+ * Define event schemas with `Schema.TaggedClass` (not plain `Schema.Class`):
+ * stored events are decoded through a `Schema.Union` of the event schemas, and
+ * without a declared `_tag` field the union discriminates structurally — two
+ * event types with identical fields would mis-decode as each other.
+ *
  * @example
  * ```typescript
- * class MatchStarted extends Schema.Class<MatchStarted>("MatchStarted")({
+ * class MatchStarted extends Schema.TaggedClass<MatchStarted>()("MatchStarted", {
  *   venue: Schema.String,
  * }) {}
  *
- * class InningsCompleted extends Schema.Class<InningsCompleted>("InningsCompleted")({
+ * class InningsCompleted extends Schema.TaggedClass<InningsCompleted>()("InningsCompleted", {
  *   innings: Schema.Number,
  *   runs: Schema.Number,
  * }) {}
@@ -46,11 +71,45 @@ const EventStreamTypeId = Symbol.for("effect-dynamodb/EventStream");
  *   streamId: { composite: ["matchId"] },
  * })
  * ```
+ *
+ * Opt into snapshots by declaring a state schema:
+ *
+ * @example
+ * ```typescript
+ * const MatchEvents = EventStore.makeStream({
+ *   table: EventsTable,
+ *   streamName: "Match",
+ *   events: [MatchStarted, InningsCompleted],
+ *   streamId: { composite: ["matchId"] },
+ *   snapshot: { schema: MatchStateSchema, every: 100 },
+ * })
+ * ```
+ *
+ * @throws `[EDD-9027]` when `snapshot.every` is not a positive integer.
  */
 export const makeStream = (config) => {
     const schema = config.table.schema;
     const entityType = `${config.streamName.toLowerCase()}.event`;
+    const snapshotEntityType = `${config.streamName.toLowerCase()}.snapshot`;
+    /**
+     * Entity type of the command-dedup sentinel. Distinct from `entityType` so the
+     * sentinel is filtered out of every event query (`read`, `readFrom`,
+     * `currentVersion` all constrain `__edd_e__`), and it sorts before the event
+     * keys (`.command` < `.event`) so it also falls outside `readFrom` ranges.
+     */
+    const commandEntityType = `${config.streamName.toLowerCase()}.command`;
     const compositeFields = config.streamId.composite;
+    // -------------------------------------------------------------------------
+    // Snapshot config validation (EDD-9027) — fail fast at definition time.
+    // -------------------------------------------------------------------------
+    const snapshot = config.snapshot;
+    if (snapshot !== undefined && snapshot.every !== undefined) {
+        if (!Number.isInteger(snapshot.every) || snapshot.every <= 0) {
+            throw new Error(`[EDD-9027] EventStream "${config.streamName}": snapshot.every must be a positive integer; ` +
+                `received ${String(snapshot.every)}.`);
+        }
+    }
+    const snapshotSettings = snapshot === undefined ? undefined : { every: snapshot.every };
     // Build union schema from event schemas for decoding
     const eventUnion = config.events.length === 1
         ? config.events[0]
@@ -65,63 +124,142 @@ export const makeStream = (config) => {
         return DynamoSchema.composeKey(schema, config.streamName.toLowerCase(), composites);
     };
     const composeEventSk = (version) => DynamoSchema.composeEventVersionKey(schema, entityType, version);
+    /**
+     * Every event SK begins with this; nothing else in the stream partition does.
+     * Bounding event reads to it excludes the snapshot item at the key-condition
+     * level, which matters because DynamoDB applies `Limit` *before*
+     * `FilterExpression` — a filtered-out snapshot would still burn a `Limit` slot.
+     */
+    const eventSkPrefix = DynamoSchema.composeEventVersionKeyPrefix(schema, entityType);
+    /** Inclusive upper bound of the event SK range (10-digit padding maximum). */
+    const maxEventSk = composeEventSk(DynamoSchema.MAX_EVENT_VERSION);
+    /**
+     * The snapshot SK. Distinct entity-type label (`<stream>.snapshot` vs
+     * `<stream>.event_1#…`), so it can never collide with an event SK, and it
+     * sorts after every event in the partition.
+     */
+    const snapshotSk = DynamoSchema.composeKey(schema, snapshotEntityType, []);
+    const composeStreamIdString = (streamId) => compositeFields.map((f) => streamId[f]).join("#");
+    // ---------------------------------------------------------------------------
+    // Codec helpers — write encodes, read decodes (symmetry with Entity/Aggregate)
+    // ---------------------------------------------------------------------------
+    /**
+     * Resolve the schema to encode an event with. Prefers the exact member
+     * schema (via `instanceof` for `Schema.Class`/`Schema.TaggedClass` events)
+     * over the union so structurally-overlapping members can't shadow each
+     * other; falls back to the union for non-class event schemas.
+     */
+    const memberSchemaFor = (event) => {
+        if (config.events.length === 1)
+            return config.events[0];
+        for (const member of config.events) {
+            const ctor = member;
+            if (typeof ctor === "function" && event instanceof ctor)
+                return member;
+        }
+        return eventUnion;
+    };
+    /**
+     * Validate input and produce wire-form output: `Schema.encode` first, with a
+     * `decode → encode` fallback for inputs already in encoded shape. Mirrors
+     * the Entity write path (`encodeOrDecodeEncode` in `Entity.ts`).
+     */
+    const encodeToWire = (codec, input, operation) => Schema.encodeUnknownEffect(codec)(input).pipe(Effect.catch((primaryCause) => Schema.decodeUnknownEffect(codec)(input).pipe(Effect.flatMap((decoded) => Schema.encodeUnknownEffect(codec)(decoded)), 
+    // Surface the original encode error — its message is keyed on the
+    // caller's input shape, which is what the user expects to see.
+    Effect.catch(() => Effect.fail(new ValidationError({ entityType, operation, cause: primaryCause }))))));
     // ---------------------------------------------------------------------------
     // Decode a raw DynamoDB item → StreamEvent<TEvent>
     // ---------------------------------------------------------------------------
+    const decodeEnvelope = Schema.decodeUnknownEffect(EventEnvelope);
     const decodeStreamEvent = (raw) => Effect.gen(function* () {
+        const toValidationError = (operation) => (cause) => new ValidationError({ entityType, operation, cause });
+        const envelope = yield* decodeEnvelope(raw).pipe(Effect.mapError(toValidationError("EventStore.decode")));
         const decoder = Schema.decodeUnknownEffect(eventUnion);
-        const data = yield* decoder(raw.data).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "EventStore.decode",
-            cause,
-        })));
+        const data = yield* decoder(raw.data).pipe(Effect.mapError(toValidationError("EventStore.decode")));
+        // Metadata is decoded through its schema when the stream declares one —
+        // the mirror of the encode performed by `append`. Streams without a
+        // metadata schema surface the stored attribute map untouched.
+        let metadata;
+        if (raw.metadata !== undefined) {
+            metadata = metadataSchema
+                ? yield* Schema.decodeUnknownEffect(metadataSchema)(raw.metadata).pipe(Effect.mapError(toValidationError("EventStore.decode.metadata")))
+                : raw.metadata;
+        }
         return {
-            streamId: raw.streamId,
-            version: raw.version,
-            eventType: raw.eventType,
+            streamId: envelope.streamId,
+            version: envelope.version,
+            eventType: envelope.eventType,
             data,
-            metadata: raw.metadata,
-            timestamp: raw.timestamp,
+            metadata,
+            timestamp: envelope.timestamp,
         };
     });
     // ---------------------------------------------------------------------------
     // append
     // ---------------------------------------------------------------------------
     const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
-        if (events.length === 0) {
+        const additionalOps = options?.additionalItems ?? [];
+        const idempotency = options?.idempotency;
+        // Nothing at all to write — preserve the historical no-op fast path.
+        // With additional items or a dedup sentinel the transaction still runs:
+        // a caller who asked for a side write means it, and silently dropping it
+        // would lose data.
+        if (events.length === 0 && additionalOps.length === 0 && idempotency === undefined) {
             return { version: expectedVersion, events: [] };
         }
+        // Resolve stream ID string for storage (join composites)
+        const streamIdStr = composeStreamIdString(streamId);
+        // Guard: every item the transaction will carry — one Put per event, one
+        // per caller-supplied additional item, the idempotency sentinel, and the
+        // version-contiguity ConditionCheck when expectedVersion > 0 — must fit
+        // DynamoDB's TransactWriteItems limit. Counted before any work is done so
+        // an oversized append costs nothing. Never chunk: chunking would break
+        // append atomicity.
+        const needsContiguityCheck = expectedVersion > 0 && events.length > 0;
+        const requiredItems = events.length +
+            additionalOps.length +
+            (idempotency !== undefined ? 1 : 0) +
+            (needsContiguityCheck ? 1 : 0);
+        if (requiredItems > TRANSACT_WRITE_ITEMS_LIMIT) {
+            return yield* new AppendTooLarge({
+                streamName: config.streamName,
+                streamId: streamIdStr,
+                count: requiredItems,
+                limit: TRANSACT_WRITE_ITEMS_LIMIT,
+            });
+        }
         const client = yield* DynamoClient;
-        const { name: tableName } = yield* config.table.Tag;
+        const tableConfig = yield* config.table.Tag;
+        const tableName = tableConfig.name;
         const pk = composeStreamPk(streamId);
         // Clock-backed timestamp (deterministic under TestClock; wall-clock in prod).
-        const now = DateTime.formatIso(yield* DateTime.now);
-        // Resolve stream ID string for storage (join composites)
-        const streamIdStr = compositeFields
-            .map((f) => streamId[f])
-            .join("#");
-        // Validate and encode metadata if schema provided
+        const nowDateTime = yield* DateTime.now;
+        const now = DateTime.formatIso(nowDateTime);
+        // Validate and encode metadata to wire form if schema provided
         let encodedMetadata;
         if (options?.metadata !== undefined && metadataSchema) {
-            const validated = yield* Schema.decodeUnknownEffect(metadataSchema)(options.metadata).pipe(Effect.mapError((cause) => new ValidationError({
-                entityType,
-                operation: "EventStore.append.metadata",
-                cause,
-            })));
-            encodedMetadata = validated;
+            const encoded = yield* encodeToWire(metadataSchema, options.metadata, "EventStore.append.metadata");
+            encodedMetadata = encoded;
         }
         else if (options?.metadata !== undefined) {
             encodedMetadata = options.metadata;
         }
-        // Build transact items — one Put per event, each with attribute_not_exists(pk)
-        const transactItems = events.map((event, i) => {
+        // Build the event puts — one Put per event, each with attribute_not_exists(pk).
+        // Events are encoded to wire form through their schema (codec symmetry
+        // with the read path, which decodes through the same schema), so this is
+        // an effectful build rather than a plain `map`.
+        const eventItems = yield* Effect.forEach(events, (event, i) => Effect.gen(function* () {
             const version = expectedVersion + i + 1;
             // In Effect v4, Schema.Class instances don't have _tag as an own property.
             // The identifier is on the constructor (class) itself.
             const evtType = event._tag ??
                 event.constructor.identifier ??
                 event.constructor.name;
-            const eventData = { _tag: evtType, ...event };
+            const wire = yield* encodeToWire(memberSchemaFor(event), event, "EventStore.append");
+            // Inject _tag for plain Schema.Class events; Schema.TaggedClass
+            // events already carry _tag in their encoded form, which wins.
+            const eventData = { _tag: evtType, ...wire };
             const item = {
                 pk,
                 sk: composeEventSk(version),
@@ -142,28 +280,131 @@ export const makeStream = (config) => {
                     ConditionExpression: "attribute_not_exists(pk)",
                 },
             };
-        });
+        }));
+        // Caller-owned items, compiled through the same builder
+        // `Transaction.transactWrite` uses, so the two APIs cannot drift.
+        const additionalItems = yield* buildTransactWriteItems(additionalOps, "EventStore.append.additionalItems");
+        // Version-contiguity guard: `attribute_not_exists(pk)` on the event puts
+        // only rejects STALE expected versions (the target slot already exists).
+        // An AHEAD expectedVersion (e.g. 10 when the stream is at 3) would
+        // silently write from version 11, leaving a permanent gap. When
+        // expectedVersion > 0, require the event at exactly `expectedVersion` to
+        // exist so the appended range is contiguous with the stream head. Its
+        // failure surfaces as a ConditionalCheckFailed cancellation reason,
+        // mapping to VersionConflict below just like a stale-version Put failure.
+        //
+        // Only when events are actually being written: the guard exists to stop an
+        // AHEAD expectedVersion opening a permanent gap, and a zero-event append
+        // (pure `additionalItems` / sentinel side-write) writes no version and so
+        // can open no gap.
+        const contiguityCheck = needsContiguityCheck
+            ? [
+                {
+                    ConditionCheck: {
+                        TableName: tableName,
+                        Key: toAttributeMap({ pk, sk: composeEventSk(expectedVersion) }),
+                        ConditionExpression: "attribute_exists(pk)",
+                    },
+                },
+            ]
+            : [];
+        // Item layout is load-bearing — cancellation reasons are positional:
+        //   [0, C)                version-contiguity ConditionCheck (C is 0 or 1)
+        //   [C, C + E)            event puts
+        //   [C + E, C + E + A)    additional items (caller order preserved)
+        //   C + E + A             idempotency sentinel (last, so adding it never
+        //                         shifts the additional-item indices the caller sees)
+        const transactItems = [
+            ...contiguityCheck,
+            ...eventItems,
+            ...additionalItems,
+        ];
+        const checkCount = contiguityCheck.length;
+        const eventCount = eventItems.length;
+        const additionalCount = additionalItems.length;
+        const sentinelIndex = idempotency !== undefined ? transactItems.length : -1;
+        if (idempotency !== undefined) {
+            const sentinel = {
+                pk,
+                sk: DynamoSchema.composeKey(schema, commandEntityType, [idempotency.commandId]),
+                __edd_e__: commandEntityType,
+                streamId: streamIdStr,
+                commandId: idempotency.commandId,
+                version: expectedVersion + events.length,
+                timestamp: now,
+            };
+            if (idempotency.ttl !== undefined) {
+                const ttlSeconds = yield* Effect.try({
+                    try: () => normalizeTtlSeconds(idempotency.ttl),
+                    catch: (cause) => new ValidationError({
+                        entityType: commandEntityType,
+                        operation: "EventStore.append.idempotency.ttl",
+                        cause,
+                    }),
+                });
+                sentinel[resolveTtlAttributeName(tableConfig)] =
+                    DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
+            }
+            transactItems.push({
+                Put: {
+                    TableName: tableName,
+                    Item: toAttributeMap(sentinel),
+                    ConditionExpression: "attribute_not_exists(pk)",
+                },
+            });
+        }
         yield* client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((error) => {
-            if (isAwsTransactionCancelled(error.cause)) {
-                const reasons = (error.cause.CancellationReasons ?? []).map((r) => ({
-                    code: r?.Code,
-                    message: r?.Message,
-                }));
-                const hasConflict = reasons.some((r) => r.code === "ConditionalCheckFailed");
-                if (hasConflict) {
+            if (!isAwsTransactionCancelled(error.cause)) {
+                return error;
+            }
+            const reasons = (error.cause.CancellationReasons ?? []).map((r) => ({
+                code: r?.Code,
+                message: r?.Message,
+            }));
+            const failedAt = (index) => index >= 0 && reasons[index]?.code === "ConditionalCheckFailed";
+            // Precedence is ordered by how terminal the caller's response should
+            // be: a duplicate can never succeed on retry, a version conflict
+            // invites a re-read, and only then is the caller's own condition the
+            // most specific explanation left.
+            if (idempotency !== undefined && failedAt(sentinelIndex)) {
+                return new DuplicateCommand({
+                    streamName: config.streamName,
+                    streamId: streamIdStr,
+                    commandId: idempotency.commandId,
+                });
+            }
+            // The contiguity ConditionCheck and the event puts both mean "the
+            // stream is not where you said it was", so they share one verdict.
+            for (let i = 0; i < checkCount + eventCount; i++) {
+                if (failedAt(i)) {
                     return new VersionConflict({
                         streamName: config.streamName,
                         streamId: streamIdStr,
                         expectedVersion,
                     });
                 }
-                return new TransactionCancelled({
-                    operation: "TransactWriteItems",
+            }
+            const failedAdditional = [];
+            for (let i = 0; i < additionalCount; i++) {
+                if (failedAt(checkCount + eventCount + i))
+                    failedAdditional.push(i);
+            }
+            if (failedAdditional.length > 0) {
+                return new AdditionalItemConditionFailed({
+                    streamName: config.streamName,
+                    streamId: streamIdStr,
+                    indices: failedAdditional,
                     reasons,
-                    cause: error.cause,
                 });
             }
-            return error;
+            // No conditional failure we can positionally justify (throttling,
+            // TransactionConflict, or a truncated/absent reason list) — never
+            // guess a VersionConflict.
+            return new TransactionCancelled({
+                operation: "TransactWriteItems",
+                reasons,
+                cause: error.cause,
+            });
         }));
         return {
             version: expectedVersion + events.length,
@@ -181,18 +422,92 @@ export const makeStream = (config) => {
     // readFrom
     // ---------------------------------------------------------------------------
     const readFrom = (streamId, afterVersion) => Effect.gen(function* () {
-        const query = buildEventsQuery(streamId).pipe(Query.where({ gt: composeEventSk(afterVersion) }));
+        // Versions are integers, so the inclusive lower bound `afterVersion + 1`
+        // is exactly the old exclusive `#sk > eventSk(afterVersion)`. The upper
+        // bound keeps the snapshot item (which sorts after every event) out of the
+        // scanned range.
+        const query = buildEventsQuery(streamId).pipe(Query.where({ between: [composeEventSk(afterVersion + 1), maxEventSk] }));
         return yield* Query.collect(query);
     });
     // ---------------------------------------------------------------------------
     // currentVersion
     // ---------------------------------------------------------------------------
     const currentVersion = (streamId) => Effect.gen(function* () {
+        // Single page, not `collect`: with `Limit: 1` DynamoDB returns a
+        // `LastEvaluatedKey` on every truncated page, so `collect` would walk the
+        // whole partition one request per item. The `begins_with` bound on
+        // `buildEventsQuery` guarantees the single evaluated item is the newest
+        // *event* (never the snapshot, which sorts last).
         const query = buildEventsQuery(streamId).pipe(Query.reverse, Query.limit(1));
-        const results = yield* Query.collect(query);
-        if (results.length === 0)
+        const page = yield* Query.execute(query);
+        const newest = page.items[0];
+        if (newest === undefined)
             return 0;
-        return results[0].version;
+        return newest.version;
+    });
+    // ---------------------------------------------------------------------------
+    // Snapshot primitives
+    // ---------------------------------------------------------------------------
+    const snapshotUnavailable = (operation) => Effect.die(new Error(`[EDD-9026] EventStream "${config.streamName}": ${operation} requires a snapshot config. ` +
+        `Declare one with makeStream({ ..., snapshot: { schema } }).`));
+    const writeSnapshot = (streamId, state, asOfVersion) => Effect.gen(function* () {
+        if (snapshot === undefined)
+            return yield* snapshotUnavailable("writeSnapshot");
+        const client = yield* DynamoClient;
+        const { name: tableName } = yield* config.table.Tag;
+        const now = DateTime.formatIso(yield* DateTime.now);
+        const encoded = yield* Schema.encodeUnknownEffect(snapshot.schema)(state).pipe(Effect.mapError((cause) => new ValidationError({
+            entityType: snapshotEntityType,
+            operation: "EventStore.writeSnapshot",
+            cause,
+        })));
+        const item = {
+            pk: composeStreamPk(streamId),
+            sk: snapshotSk,
+            __edd_e__: snapshotEntityType,
+            streamId: composeStreamIdString(streamId),
+            asOfVersion,
+            state: encoded,
+            timestamp: now,
+        };
+        yield* client
+            .putItem({
+            TableName: tableName,
+            Item: toAttributeMap(item),
+            // Monotonic: never regress the cache. Losing this race is a no-op,
+            // not an error — the events it summarises are already durable.
+            ConditionExpression: "attribute_not_exists(#pk) OR #asOfVersion < :asOfVersion",
+            ExpressionAttributeNames: { "#pk": "pk", "#asOfVersion": "asOfVersion" },
+            ExpressionAttributeValues: toAttributeMap({ ":asOfVersion": asOfVersion }),
+        })
+            .pipe(Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.void));
+    });
+    const readSnapshot = (streamId) => Effect.gen(function* () {
+        if (snapshot === undefined)
+            return yield* snapshotUnavailable("readSnapshot");
+        const client = yield* DynamoClient;
+        const { name: tableName } = yield* config.table.Tag;
+        const result = yield* client.getItem({
+            TableName: tableName,
+            Key: toAttributeMap({
+                pk: composeStreamPk(streamId),
+                sk: snapshotSk,
+            }),
+            ConsistentRead: true,
+        });
+        if (result.Item === undefined)
+            return Option.none();
+        const raw = fromAttributeMap(result.Item);
+        const state = yield* Schema.decodeUnknownEffect(snapshot.schema)(raw.state).pipe(Effect.mapError((cause) => new ValidationError({
+            entityType: snapshotEntityType,
+            operation: "EventStore.readSnapshot",
+            cause,
+        })));
+        return Option.some({
+            state,
+            asOfVersion: raw.asOfVersion,
+            timestamp: raw.timestamp,
+        });
     });
     // ---------------------------------------------------------------------------
     // query.events helper
@@ -208,7 +523,10 @@ export const makeStream = (config) => {
             entityTypes: [entityType],
             decoder: (raw) => decodeStreamEvent(raw),
             resolveTableName: config.table.Tag.useSync((tc) => tc.name),
-        });
+            // Bound to the event SK range so non-event items in the stream partition
+            // (the snapshot) are excluded at the key-condition level. A caller-supplied
+            // `Query.where` replaces this — the `__edd_e__` filter still applies.
+        }).pipe(Query.where({ beginsWith: eventSkPrefix }));
     };
     const queryNamespace = {
         events: (streamId) => buildEventsQuery(streamId),
@@ -223,8 +541,15 @@ export const makeStream = (config) => {
     // runtime — the user must provide these layers.
     return {
         [EventStreamTypeId]: EventStreamTypeId,
+        pipe() {
+            // eslint-disable-next-line prefer-rest-params
+            return Pipeable.pipeArguments(this, arguments);
+        },
         streamName: config.streamName,
         eventSchema: eventUnion,
+        snapshotConfig: snapshotSettings,
+        writeSnapshot,
+        readSnapshot,
         append,
         read,
         readFrom,
@@ -254,8 +579,15 @@ export const bind = (stream) => Effect.gen(function* () {
     const provide = (effect) => Effect.provide(effect, ctx);
     return {
         [EventStreamTypeId]: EventStreamTypeId,
+        pipe() {
+            // eslint-disable-next-line prefer-rest-params
+            return Pipeable.pipeArguments(this, arguments);
+        },
         streamName: stream.streamName,
         eventSchema: stream.eventSchema,
+        snapshotConfig: stream.snapshotConfig,
+        writeSnapshot: (streamId, state, asOfVersion) => provide(stream.writeSnapshot(streamId, state, asOfVersion)),
+        readSnapshot: (streamId) => provide(stream.readSnapshot(streamId)),
         append: (streamId, events, expectedVersion, options) => provide(stream.append(streamId, events, expectedVersion, options)),
         read: (streamId) => provide(stream.read(streamId)),
         readFrom: (streamId, afterVersion) => provide(stream.readFrom(streamId, afterVersion)),
@@ -264,6 +596,110 @@ export const bind = (stream) => Effect.gen(function* () {
         provide,
     };
 });
+/** @internal Both `EventStream` and `BoundEventStream` carry this brand. */
+const hasEventStreamBrand = (u) => typeof u === "object" && u !== null && EventStreamTypeId in u;
+/** @internal */
+const makeCommandHandlerImpl = (decider, stream, options) => {
+    const retryPolicy = options?.retry;
+    const schedule = retryPolicy === undefined
+        ? undefined
+        : typeof retryPolicy === "number"
+            ? Schedule.recurs(retryPolicy)
+            : retryPolicy;
+    return (streamId, command, callOptions) => {
+        const attempt = Effect.gen(function* () {
+            // Backstop for JS callers and `any`-shaped call sites: silently degrading
+            // to at-least-once would look like success right up until the day a
+            // duplicate mattered. Not retryable — `while` below only retries
+            // `VersionConflict`, so this surfaces on the first attempt.
+            if (options?.idempotency !== undefined && callOptions?.commandId === undefined) {
+                return yield* new ValidationError({
+                    entityType: stream.streamName,
+                    operation: "EventStore.commandHandler",
+                    cause: "commandId is required when commandHandler is configured with `idempotency`.",
+                });
+            }
+            const snapshotSettings = stream.snapshotConfig;
+            // 1. Establish the base state + version — from a snapshot plus its delta
+            //    when the stream has snapshots enabled and one exists, otherwise from
+            //    a full replay.
+            let state = decider.initialState;
+            let baseVersion = 0;
+            let snapshotAsOfVersion = 0;
+            const snapshot = snapshotSettings === undefined
+                ? Option.none()
+                : (yield* stream.readSnapshot(streamId));
+            if (Option.isSome(snapshot)) {
+                snapshotAsOfVersion = snapshot.value.asOfVersion;
+                baseVersion = snapshot.value.asOfVersion;
+                state = snapshot.value.state;
+                const delta = yield* stream.readFrom(streamId, snapshot.value.asOfVersion);
+                for (const event of delta) {
+                    state = decider.evolve(state, event.data);
+                }
+                const newest = delta[delta.length - 1];
+                if (newest !== undefined)
+                    baseVersion = newest.version;
+            }
+            else {
+                const events = yield* stream.read(streamId);
+                for (const event of events) {
+                    state = decider.evolve(state, event.data);
+                }
+                const newest = events[events.length - 1];
+                baseVersion = newest === undefined ? 0 : newest.version;
+            }
+            // 2. Decide
+            const newEvents = yield* decider.decide(command, state);
+            // 3. No-op command — return current state
+            if (newEvents.length === 0) {
+                return { state, version: baseVersion, events: [] };
+            }
+            // 4. Append with optimistic concurrency, plus any caller-owned items and
+            //    the dedup sentinel, all in one transaction.
+            const appendOptions = {};
+            if (callOptions?.metadata !== undefined)
+                appendOptions.metadata = callOptions.metadata;
+            if (callOptions?.additionalItems !== undefined) {
+                appendOptions.additionalItems = callOptions.additionalItems;
+            }
+            if (options?.idempotency !== undefined && callOptions?.commandId !== undefined) {
+                appendOptions.idempotency =
+                    options.idempotency.ttl !== undefined
+                        ? { commandId: callOptions.commandId, ttl: options.idempotency.ttl }
+                        : { commandId: callOptions.commandId };
+            }
+            const result = yield* stream.append(streamId, newEvents, baseVersion, appendOptions);
+            // 5. Evolve state through the new events
+            for (const event of newEvents) {
+                state = decider.evolve(state, event);
+            }
+            // 6. Auto-snapshot once the cadence threshold is crossed. Best-effort:
+            //    the events are already durable, so a snapshot-write failure must not
+            //    report the command as failed. The next threshold crossing retries it.
+            const every = snapshotSettings?.every;
+            if (every !== undefined && result.version - snapshotAsOfVersion >= every) {
+                yield* stream
+                    .writeSnapshot(streamId, state, result.version)
+                    .pipe(Effect.catchCause((cause) => Effect.logWarning(`EventStore: snapshot write failed for stream "${stream.streamName}" at version ${result.version}`, cause)));
+            }
+            return { state, version: result.version, events: newEvents };
+        });
+        return schedule === undefined
+            ? attempt
+            : Effect.retry(attempt, {
+                // `while` runs before the schedule, so the schedule only ever sees a
+                // `VersionConflict` input — the widening cast is sound. It is needed
+                // because `Retry.Options` demands a schedule whose input accepts the
+                // effect's *full* error union, and `Schedule` is contravariant on input.
+                schedule: schedule,
+                // `VersionConflict` only. `DuplicateCommand` is terminal — the same
+                // commandId can never succeed — and `AdditionalItemConditionFailed`
+                // will not resolve itself by re-deciding either.
+                while: (error) => error instanceof VersionConflict,
+            });
+    };
+};
 /**
  * Create a command handler that reads, decides, and appends atomically.
  *
@@ -279,31 +715,39 @@ export const bind = (stream) => Effect.gen(function* () {
  *
  * // Data-last (pipe)
  * const handle = stream.pipe(EventStore.commandHandler(decider))
+ *
+ * // Retry the full read-decide-append cycle on VersionConflict
+ * const handle = EventStore.commandHandler(decider, stream, { retry: 3 })
+ * const handle2 = stream.pipe(EventStore.commandHandler(decider, { retry: 3 }))
+ *
+ * // Exactly-once command processing — `commandId` becomes required per call
+ * const handle = EventStore.commandHandler(decider, stream, {
+ *   idempotency: { ttl: Duration.days(1) },
+ * })
+ * yield* handle({ matchId: "m-1" }, command, { commandId: "cmd-7f3a" })
  * ```
+ *
+ * When the stream declares a `snapshot` config, each invocation reads the
+ * snapshot and folds only the events after it, instead of replaying the stream
+ * from the beginning. With `snapshot.every` set, a fresh snapshot is written
+ * (best-effort) after a successful append once the cadence threshold is crossed.
+ *
+ * Without `idempotency`, command processing is **at-least-once**: a retry after
+ * an acked-but-lost response re-runs `decide` and appends again.
+ *
+ * Note: this is a hand-rolled dual rather than `Function.dual` — the data
+ * argument (`stream`) is the *second* parameter, which `Function.dual` cannot
+ * express, and its numeric-arity form would silently drop the trailing options
+ * (`retry`, `idempotency`) that both forms depend on. Dispatch is on the
+ * `EventStreamTypeId` brand of the second argument.
  */
-export const commandHandler = Function.dual(2, (decider, stream) => (streamId, command, options) => Effect.gen(function* () {
-    // 1. Read all events
-    const events = yield* stream.read(streamId);
-    // 2. Fold to current state
-    const curVersion = events.length > 0 ? events[events.length - 1].version : 0;
-    let state = decider.initialState;
-    for (const event of events) {
-        state = decider.evolve(state, event.data);
+export const commandHandler = ((decider, streamOrOptions, maybeOptions) => {
+    if (hasEventStreamBrand(streamOrOptions)) {
+        return makeCommandHandlerImpl(decider, streamOrOptions, maybeOptions);
     }
-    // 3. Decide
-    const newEvents = yield* decider.decide(command, state);
-    // 4. No-op command — return current state
-    if (newEvents.length === 0) {
-        return { state, version: curVersion, events: [] };
-    }
-    // 5. Append with optimistic concurrency
-    const result = yield* stream.append(streamId, newEvents, curVersion, options);
-    // 6. Evolve state through new events
-    for (const event of newEvents) {
-        state = decider.evolve(state, event);
-    }
-    return { state, version: result.version, events: newEvents };
-}));
+    const options = streamOrOptions;
+    return (stream) => makeCommandHandlerImpl(decider, stream, options);
+});
 // ---------------------------------------------------------------------------
 // fold helpers
 // ---------------------------------------------------------------------------