effect-dynamodb 1.22.0 → 1.24.0

package/dist/EventStore.js

@@ -4,10 +4,17 @@
  * Provides:
  * - `Decider` type for command-event-state modeling
  * - `makeStream` factory for creating event streams bound to a Table
- * - Core operations: `append`, `read`, `readFrom`, `currentVersion`
- * - Snapshot primitives: `writeSnapshot`, `readSnapshot`
- * - `commandHandler` combinator for read-decide-append cycle (snapshot-aware,
- *   with an optional `VersionConflict` retry policy)
+ * - Core operations: `append` (atomic), `read`, `readFrom`, `currentVersion`,
+ *   `readLatest` (reads optionally strongly consistent)
+ * - Snapshot primitives: `writeSnapshot`, `readSnapshot`, and inline snapshots
+ *   written in the append transaction (`AppendOptions.snapshot`)
+ * - `commandHandler` combinator for the load-decide-fold-append cycle
+ *   (snapshot-aware single-request loads, consistent loads, an optional
+ *   `VersionConflict` retry policy, caller-supplied `expectedVersion`,
+ *   decision-derived `additionalItems`, inline snapshots)
+ * - Stream indexes (`makeStream({ indexes })`): sub-streams ordered by a key
+ *   derived from each event, on an LSI or GSI — `readIndex`, `query.index`,
+ *   and `indexDefinitions` for the `CreateTable` fragments
  * - `fold` / `foldFrom` helpers for state reconstruction
  *
  * Built on the existing library primitives (DynamoSchema, KeyComposer, Query,
@@ -17,12 +24,12 @@ import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.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, Option, Pipeable, Schedule, Schema, } from "effect";
+import { DateTime, Effect, Function, Option, Pipeable, Result, Schedule, Schema, } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
-import { buildTransactWriteItems, } from "./internal/TransactWriteOps.js";
+import { buildTransactWriteItems, GUARDED_TRANSACTION_ATTEMPTS, judgeCancellation, refuseOversizedTransaction, refuseRepeatedItems, transactItemTarget, } from "./internal/TransactWriteOps.js";
 import { fromAttributeMap, toAttributeMap } from "./Marshaller.js";
 import * as Query from "./Query.js";
-import { resolveTtlAttributeName } from "./Table.js";
+import { DEFAULT_TTL_ATTRIBUTE_NAME, resolveTtlAttributeName, } from "./Table.js";
 // ---------------------------------------------------------------------------
 // Envelope schema — validates the persisted event's system fields on read
 // ---------------------------------------------------------------------------
@@ -38,10 +45,209 @@ const EventEnvelope = Schema.Struct({
     eventType: Schema.String,
     timestamp: Schema.String,
 });
+/** @internal DynamoDB's limit on a sort key value, which an index key is. */
+const MAX_INDEX_SORT_KEY_BYTES = 1024;
+/** @internal */
+const utf8 = new TextEncoder();
+/**
+ * @internal Compare two strings by their UTF-8 bytes — the order DynamoDB
+ * sorts (and evaluates `BETWEEN` on) string keys. JavaScript's `<` compares
+ * UTF-16 code units, which disagrees for characters outside the BMP.
+ */
+const compareUtf8 = (a, b) => {
+    const left = utf8.encode(a);
+    const right = utf8.encode(b);
+    const length = Math.min(left.length, right.length);
+    for (let i = 0; i < length; i++) {
+        const diff = left[i] - right[i];
+        if (diff !== 0)
+            return diff;
+    }
+    return left.length - right.length;
+};
+/**
+ * @internal Why a {@link ReadIndexOptions} key condition cannot be sent, or
+ * `undefined` when it can. DynamoDB rejects an empty key value and a
+ * `BETWEEN` whose lower bound sorts after its upper bound.
+ */
+const invalidIndexKeyCondition = (options) => {
+    if (options?.beginsWith !== undefined && options.between !== undefined) {
+        return "Pass at most one of beginsWith and between.";
+    }
+    const beginsWith = options?.beginsWith;
+    if (beginsWith !== undefined) {
+        if (typeof beginsWith !== "string" || beginsWith.length === 0) {
+            return ("beginsWith must be a non-empty string — DynamoDB rejects an empty key value; " +
+                "omit it to read the whole sub-stream.");
+        }
+        return undefined;
+    }
+    const between = options?.between;
+    if (between === undefined)
+        return undefined;
+    if (!Array.isArray(between) ||
+        between.length !== 2 ||
+        !between.every((bound) => typeof bound === "string" && bound.length > 0)) {
+        return "between must be a pair of non-empty strings — DynamoDB rejects an empty key value.";
+    }
+    const [low, high] = between;
+    if (compareUtf8(low, high) > 0) {
+        return `between's lower bound ${JSON.stringify(low)} sorts after its upper bound ${JSON.stringify(high)}.`;
+    }
+    return undefined;
+};
+/**
+ * @internal Attributes a stream writes on its own items — events, snapshot,
+ * idempotency sentinel — plus the default TTL attribute. An index attribute
+ * may not reuse any of them.
+ */
+const STREAM_OWNED_ATTRIBUTES = [
+    "pk",
+    "sk",
+    "__edd_e__",
+    "streamId",
+    "version",
+    "eventType",
+    "data",
+    "metadata",
+    "timestamp",
+    "asOfVersion",
+    "state",
+    "commandId",
+    DEFAULT_TTL_ATTRIBUTE_NAME,
+];
+/**
+ * @internal Validate `makeStream({ indexes })` at definition time.
+ *
+ * @throws `[EDD-9063]` for a malformed entry (unknown `type`, a `gsi` without
+ *   `pk`, an `lsi` with `pk`, an empty name, a `key` that is not a function).
+ * @throws `[EDD-9064]` for an index attribute that collides with a
+ *   stream-owned attribute.
+ * @throws `[EDD-9065]` for two indexes sharing a physical index name or an
+ *   attribute.
+ */
+const resolveStreamIndexes = (streamName, indexes) => {
+    if (indexes === undefined)
+        return [];
+    const fail = (code, message) => {
+        throw new Error(`[${code}] EventStream "${streamName}": ${message}`);
+    };
+    const isName = (value) => typeof value === "string" && value !== "";
+    const resolved = [];
+    for (const [name, raw] of Object.entries(indexes)) {
+        if (typeof raw !== "object" || raw === null) {
+            fail("EDD-9063", `index "${name}" must be an object; received ${String(raw)}.`);
+        }
+        const entry = raw;
+        const type = (entry.type ?? "lsi");
+        if (type !== "lsi" && type !== "gsi") {
+            fail("EDD-9063", `index "${name}": type must be "lsi" or "gsi"; received ${JSON.stringify(entry.type)}.`);
+        }
+        if (!isName(entry.index)) {
+            fail("EDD-9063", `index "${name}": index must name the physical index (a non-empty string).`);
+        }
+        if (!isName(entry.sk)) {
+            fail("EDD-9063", `index "${name}": sk must name the sort key attribute (a non-empty string).`);
+        }
+        if (type === "gsi" && !isName(entry.pk)) {
+            fail("EDD-9063", `index "${name}": a "gsi" index requires pk, the attribute carrying the stream's ` +
+                "partition key (a non-empty string).");
+        }
+        if (type === "lsi" && entry.pk !== undefined) {
+            fail("EDD-9063", `index "${name}": an "lsi" index uses the table partition key "pk"; remove pk, or ` +
+                'declare type: "gsi".');
+        }
+        if (typeof entry.key !== "function") {
+            fail("EDD-9063", `index "${name}": key must be a function (event, version) => string | undefined.`);
+        }
+        const index = entry.index;
+        const sk = entry.sk;
+        const pk = type === "gsi" ? entry.pk : "pk";
+        const attributes = type === "gsi" ? [pk, sk] : [sk];
+        for (const attribute of attributes) {
+            if (STREAM_OWNED_ATTRIBUTES.includes(attribute)) {
+                fail("EDD-9064", `index "${name}": attribute "${attribute}" is written by the stream itself ` +
+                    `(reserved: ${STREAM_OWNED_ATTRIBUTES.join(", ")}). Choose another attribute name.`);
+            }
+        }
+        if (type === "gsi" && pk === sk) {
+            fail("EDD-9065", `index "${name}": pk and sk must be different attributes ("${pk}").`);
+        }
+        for (const other of resolved) {
+            if (other.index === index) {
+                fail("EDD-9065", `indexes "${other.name}" and "${name}" both use the physical index "${index}".`);
+            }
+            const otherAttributes = other.type === "gsi" ? [other.pk, other.sk] : [other.sk];
+            const shared = attributes.find((attribute) => otherAttributes.includes(attribute));
+            if (shared !== undefined) {
+                fail("EDD-9065", `indexes "${other.name}" and "${name}" both use the attribute "${shared}".`);
+            }
+        }
+        resolved.push({
+            name,
+            type,
+            index,
+            pk,
+            sk,
+            key: entry.key,
+        });
+    }
+    return resolved;
+};
 // ---------------------------------------------------------------------------
 // EventStreamTypeId
 // ---------------------------------------------------------------------------
 const EventStreamTypeId = Symbol.for("effect-dynamodb/EventStream");
+/**
+ * @internal Carries the stream's stream-id formatter (composites joined in
+ * declaration order — the `streamId` reported on errors and stored on items),
+ * so {@link commandHandler} can report a pre-decide `VersionConflict` exactly
+ * as `append` would. Not part of the public interface: `makeStream` and `bind`
+ * attach it; a hand-built stream object falls back to joining the id's values.
+ */
+const StreamIdFormatter = Symbol.for("effect-dynamodb/EventStream/StreamIdFormatter");
+/** @internal */
+const formatStreamIdOf = (stream, streamId) => {
+    const formatter = stream[StreamIdFormatter];
+    return formatter !== undefined ? formatter(streamId) : Object.values(streamId).join("#");
+};
+/**
+ * @internal Carries a probe for a command's idempotency sentinel (one strongly
+ * consistent `GetItem`), so {@link commandHandler} can tell a redelivered
+ * command from a lost race when its pre-decide If-Match check fails. Not part
+ * of the public interface: `makeStream` and `bind` attach it (a bound stream's
+ * probe has its services provided); a hand-built stream object has none.
+ */
+const CommandSentinelProbe = Symbol.for("effect-dynamodb/EventStream/CommandSentinelProbe");
+/** @internal */
+const commandSentinelProbeOf = (stream) => stream[CommandSentinelProbe];
+/**
+ * @internal Carries a head probe bounded below by a known version: the newest
+ * event version above `floorVersion`, or `floorVersion` itself when there is
+ * none. {@link commandHandler} uses it to confirm an unverified snapshot is
+ * still the head. Unlike `currentVersion`, it never reads the newest event when
+ * the snapshot is current — the key range above `floorVersion` is empty, so the
+ * `Query` reads no items and costs only DynamoDB's per-request minimum, however
+ * large the events are. Attached by `makeStream` and `bind` like
+ * {@link CommandSentinelProbe}; a hand-built stream falls back to
+ * `currentVersion`.
+ */
+const HeadAboveProbe = Symbol.for("effect-dynamodb/EventStream/HeadAboveProbe");
+/** @internal */
+const headAboveProbeOf = (stream) => stream[HeadAboveProbe];
+/**
+ * @internal `[EDD-9068]`: `verifySnapshot: false` is accepted only by a stream
+ * whose snapshot is written in every append (`mode: "inline"` without `every`),
+ * the only mode in which the snapshot is normally at the head. Returns the
+ * refusal message, or `undefined` when the option is acceptable — including on
+ * a stream without a snapshot config, where it is ignored.
+ */
+const unverifiedSnapshotRefusal = (streamName, settings, operation) => settings === undefined || (settings.mode === "inline" && settings.every === undefined)
+    ? undefined
+    : `[EDD-9068] EventStream "${streamName}": ${operation} with verifySnapshot: false requires ` +
+        `snapshot mode "inline" without "every" — the only mode that writes the snapshot in every ` +
+        `append, so it is normally at the head. This stream's snapshot is mode "${settings.mode}"` +
+        `${settings.every === undefined ? "" : ` with every: ${settings.every}`}.`;
 // ---------------------------------------------------------------------------
 // makeStream factory
 // ---------------------------------------------------------------------------
@@ -85,6 +291,10 @@ const EventStreamTypeId = Symbol.for("effect-dynamodb/EventStream");
  * })
  * ```
  *
+ * `snapshot.mode: "inline"` writes the snapshot in the append transaction
+ * itself, so it is current after every command and state loads in one
+ * request — see {@link SnapshotMode}.
+ *
  * `casing` overrides the key casing for this stream, as an index's or a vector
  * index's `casing` does: the stream name, stream-id values and command ids in
  * its keys all take it. When omitted, the stream name is lower-cased and the
@@ -95,7 +305,57 @@ const EventStreamTypeId = Symbol.for("effect-dynamodb/EventStream");
  * (`<stream>.event` etc.) are always lower-cased. In the next major, omitting
  * `casing` will mean the schema's casing, as it does for indexes.
  *
+ * `indexes` declares sub-streams ordered by a key derived from each event
+ * (#140), on a local (default) or global secondary index. `append` writes each
+ * event's derived key (and, for a GSI, the stream's partition key) on the
+ * event item; snapshots and idempotency sentinels never carry them, so they
+ * are never in an index. Read with {@link EventStream.readIndex} or
+ * `query.index`, and create the indexes with {@link indexDefinitions}.
+ *
+ * Index attributes are written only at append time and events are never
+ * rewritten. Declaring an index on a stream that already holds events, or
+ * changing an index's `key`, therefore leaves the earlier events out of the
+ * index (or under their old keys), and `readIndex` returns only what was
+ * indexed — without an error. The library does not backfill; whether and how
+ * to re-index existing events (for example, an `UpdateItem` per event setting
+ * the derived attributes) is the application's decision.
+ *
+ * @example
+ * ```typescript
+ * const Entries = EventStore.makeStream({
+ *   table: EventsTable,
+ *   streamName: "Ledger",
+ *   events: [EntryRecorded, EntryVoided],
+ *   streamId: { composite: ["ledgerId"] },
+ *   indexes: {
+ *     byEntry: {
+ *       index: "lsi1",
+ *       sk: "lsi1sk",
+ *       key: (event, version) =>
+ *         event._tag === "EntryRecorded" ? `ENTRY#${event.section}#${pad(version)}` : undefined,
+ *     },
+ *     // Every event, by the day it was recorded (both event types carry `day`).
+ *     byDay: { type: "gsi", index: "gsi1", pk: "gsi1pk", sk: "gsi1sk", key: (e) => e.day },
+ *   },
+ * })
+ *
+ * const sectionThree = yield* Entries.readIndex("byEntry", { ledgerId }, { beginsWith: "ENTRY#3#" })
+ * ```
+ *
  * @throws `[EDD-9027]` when `snapshot.every` is not a positive integer.
+ * @throws `[EDD-9062]` when `snapshot.mode` is neither `"after-append"` nor
+ *   `"inline"`.
+ * @throws `[EDD-9063]` for a malformed index: a `type` other than `"lsi"` /
+ *   `"gsi"`, a `gsi` without `pk`, an `lsi` with `pk`, an empty `index` / `sk`
+ *   / `pk`, or a `key` that is not a function.
+ * @throws `[EDD-9064]` when an index attribute is one the stream writes itself
+ *   (`pk`, `sk`, `__edd_e__`, `streamId`, `version`, `eventType`, `data`,
+ *   `metadata`, `timestamp`, `asOfVersion`, `state`, `commandId`, or the
+ *   default TTL attribute `_ttl`). A custom `TableConfig.ttlAttributeName`
+ *   is only known at runtime: an index attribute equal to it fails each append
+ *   with `ValidationError`.
+ * @throws `[EDD-9065]` when two indexes share a physical index name or an
+ *   attribute (or a GSI's `pk` and `sk` are the same attribute).
  */
 export const makeStream = (config) => {
     const schema = config.table.schema;
@@ -127,7 +387,7 @@ export const makeStream = (config) => {
     const commandKeyLabel = `${keyLabel}.command`;
     const compositeFields = config.streamId.composite;
     // -------------------------------------------------------------------------
-    // Snapshot config validation (EDD-9027) — fail fast at definition time.
+    // Snapshot config validation (EDD-9027, EDD-9062) — fail fast at definition time.
     // -------------------------------------------------------------------------
     const snapshot = config.snapshot;
     if (snapshot !== undefined && snapshot.every !== undefined) {
@@ -136,7 +396,24 @@ export const makeStream = (config) => {
                 `received ${String(snapshot.every)}.`);
         }
     }
-    const snapshotSettings = snapshot === undefined ? undefined : { every: snapshot.every };
+    if (snapshot !== undefined &&
+        snapshot.mode !== undefined &&
+        snapshot.mode !== "after-append" &&
+        snapshot.mode !== "inline") {
+        throw new Error(`[EDD-9062] EventStream "${config.streamName}": snapshot.mode must be "after-append" or ` +
+            `"inline"; received ${JSON.stringify(snapshot.mode)}.`);
+    }
+    const snapshotSettings = snapshot === undefined
+        ? undefined
+        : { mode: snapshot.mode ?? "after-append", every: snapshot.every };
+    // Stream indexes (#140) — validated at definition time (EDD-9063..9065).
+    const streamIndexes = resolveStreamIndexes(config.streamName, config.indexes);
+    const indexSettings = {};
+    for (const idx of streamIndexes) {
+        indexSettings[idx.name] = { type: idx.type, index: idx.index, pk: idx.pk, sk: idx.sk };
+    }
+    /** Every attribute the indexes write on an event item. */
+    const indexAttributes = streamIndexes.flatMap((idx) => idx.type === "gsi" ? [idx.pk, idx.sk] : [idx.sk]);
     // Build union schema from event schemas for decoding
     const eventUnion = config.events.length === 1
         ? config.events[0]
@@ -151,6 +428,8 @@ export const makeStream = (config) => {
         return DynamoSchema.composeKey(schema, keyLabel, composites, keyOptions);
     };
     const composeEventSk = (version) => DynamoSchema.composeEventVersionKey(schema, eventKeyLabel, version, keyOptions);
+    /** Sort key of a command's idempotency sentinel. */
+    const composeCommandSk = (commandId) => DynamoSchema.composeKey(schema, commandKeyLabel, [commandId], keyOptions);
     /**
      * 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
@@ -164,6 +443,13 @@ export const makeStream = (config) => {
      * 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.
+     *
+     * The three stream-owned SKs share `<prefix>#<label>.` and differ first at
+     * the literal suffix: `.command#<id>` < `.event_1#<version>` < `.snapshot`.
+     * The suffixes are lower-case, and a stream `casing` applies to all three
+     * alike (`"uppercase"` gives `.COMMAND` < `.EVENT_1` < `.SNAPSHOT`), so the
+     * order holds under every casing. `readLatest` relies on it: the range
+     * `[eventSkPrefix, snapshotSk]` holds exactly the events and the snapshot.
      */
     const snapshotSk = DynamoSchema.composeKey(schema, snapshotKeyLabel, [], keyOptions);
     const composeStreamIdString = (streamId) => compositeFields.map((f) => streamId[f]).join("#");
@@ -191,10 +477,10 @@ export const makeStream = (config) => {
      * `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)), 
+    const encodeToWire = (codec, input, operation, errorEntityType = entityType) => 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 }))))));
+    Effect.catch(() => Effect.fail(new ValidationError({ entityType: errorEntityType, operation, cause: primaryCause }))))));
     // ---------------------------------------------------------------------------
     // Decode a raw DynamoDB item → StreamEvent<TEvent>
     // ---------------------------------------------------------------------------
@@ -225,23 +511,143 @@ export const makeStream = (config) => {
     // ---------------------------------------------------------------------------
     // append
     // ---------------------------------------------------------------------------
+    /**
+     * An event's key in a stream index (#140): a non-empty string, or
+     * `undefined` to leave the event out. Anything else — an empty string
+     * (DynamoDB rejects empty key values), another type, a `key` that throws —
+     * is a `ValidationError`, raised before anything is written.
+     */
+    const deriveIndexKey = (idx, event, version) => Effect.try({
+        try: () => idx.key(event, version),
+        catch: (cause) => new ValidationError({ entityType, operation: "EventStore.append.indexes", cause }),
+    }).pipe(Effect.flatMap((derived) => {
+        if (derived === undefined)
+            return Effect.succeed(undefined);
+        const refuse = (problem) => Effect.fail(new ValidationError({
+            entityType,
+            operation: "EventStore.append.indexes",
+            cause: `The key of index "${idx.name}" for the event at version ${version} ${problem}. ` +
+                "Nothing was written.",
+        }));
+        if (typeof derived !== "string" || derived === "") {
+            return refuse("must be a non-empty string or undefined; received " +
+                (typeof derived === "string" ? "an empty string" : String(derived)));
+        }
+        if (utf8.encode(derived).length > MAX_INDEX_SORT_KEY_BYTES) {
+            return refuse(`is longer than DynamoDB's ${MAX_INDEX_SORT_KEY_BYTES}-byte limit for a sort key`);
+        }
+        return Effect.succeed(derived);
+    }));
+    /**
+     * Encode snapshot state to wire form through the state schema, with the
+     * same `decode → encode` fallback as events and metadata. A structurally
+     * matching plain object — what an immutable `evolve` that spreads a
+     * `Schema.Class` state returns (`({ ...s, balance })`), which TypeScript
+     * accepts as the class type — is decoded into the schema's type first
+     * rather than refused with `Expected <Class>`.
+     */
+    const encodeSnapshotState = (state, operation) => encodeToWire(snapshot.schema, state, operation, snapshotEntityType);
+    /**
+     * Map a failed `TransactWriteItems` of an append to its verdict. Resolves to
+     * the race a guarded additional put lost (so the transaction is built and
+     * written again), and fails with every other verdict.
+     */
+    const sendAppendTransaction = (client, tx, streamIdStr, commandId) => client.transactWriteItems({ TransactItems: tx.items }).pipe(Effect.as(undefined), Effect.catch((error) => {
+        if (!isAwsTransactionCancelled(error.cause)) {
+            return Effect.fail(error);
+        }
+        const rawReasons = error.cause.CancellationReasons ?? [];
+        const reasons = rawReasons.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 are the additional items judged.
+        if (commandId !== undefined && failedAt(tx.sentinelIndex)) {
+            return Effect.fail(new DuplicateCommand({
+                streamName: config.streamName,
+                streamId: streamIdStr,
+                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 < tx.guardCount + tx.eventCount; i++) {
+            if (failedAt(i)) {
+                return Effect.fail(new VersionConflict({
+                    streamName: config.streamName,
+                    streamId: streamIdStr,
+                    expectedVersion: tx.expectedVersion,
+                }));
+            }
+        }
+        // The additional items, attributed back to the caller OPS that
+        // produced them (several items can belong to one op). Only an op's
+        // own condition is `AdditionalItemConditionFailed`: a guarded put
+        // the caller set no condition on reports what the entity's own put
+        // would — a taken unique value, a history conflict — or, having
+        // lost a race to a concurrent write, is written again (#133).
+        const judged = judgeCancellation(tx.additional, rawReasons, tx.guardCount + tx.eventCount);
+        if (judged?._tag === "fail")
+            return Effect.fail(judged.error);
+        if (judged?._tag === "conditions") {
+            return Effect.fail(new AdditionalItemConditionFailed({
+                streamName: config.streamName,
+                streamId: streamIdStr,
+                indices: judged.opIndices,
+                reasons,
+            }));
+        }
+        if (judged?._tag === "retry")
+            return Effect.succeed(judged.error);
+        // No conditional failure we can positionally justify (throttling,
+        // TransactionConflict, a reason at the inline snapshot's position, or
+        // a truncated/absent reason list) — never guess a VersionConflict.
+        return Effect.fail(new TransactionCancelled({
+            operation: "TransactWriteItems",
+            reasons,
+            cause: error.cause,
+        }));
+    }));
     const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
         const additionalOps = options?.additionalItems ?? [];
         const idempotency = options?.idempotency;
+        const snapshotState = options?.snapshot;
+        if (snapshotState !== undefined && snapshot === undefined) {
+            return yield* snapshotUnavailable("append({ snapshot })");
+        }
         // 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) {
+        if (events.length === 0 &&
+            additionalOps.length === 0 &&
+            idempotency === undefined &&
+            snapshotState === undefined) {
             return { version: expectedVersion, events: [] };
         }
         // Resolve stream ID string for storage (join composites)
         const streamIdStr = composeStreamIdString(streamId);
+        // An inline snapshot is unconditional because the event puts prove this
+        // writer owns its version. Without events nothing proves it, and an
+        // unconditional put could regress the snapshot.
+        if (snapshotState !== undefined && events.length === 0) {
+            return yield* new ValidationError({
+                entityType: snapshotEntityType,
+                operation: "EventStore.append.snapshot",
+                cause: "An inline snapshot requires at least one event: nothing else proves the writer " +
+                    `owns version ${expectedVersion}. Nothing was written.`,
+            });
+        }
         // Guard: every item the transaction will carry — one Put per event, the
         // items each caller-supplied additional op compiles to, the idempotency
-        // sentinel, and the version-contiguity ConditionCheck when
-        // expectedVersion > 0 — must fit DynamoDB's TransactWriteItems limit.
-        // Never chunk: chunking would break append atomicity.
+        // sentinel, the inline snapshot, and the version-contiguity
+        // ConditionCheck when expectedVersion > 0 — must fit DynamoDB's
+        // TransactWriteItems limit. Never split: splitting would break append
+        // atomicity (a large command is stepped by the application instead — one
+        // command, one decision, one atomic append).
         //
         // This first check is a LOWER BOUND, counting one item per additional op.
         // Expansion (uniqueness sentinels, version snapshots — #113) only ever
@@ -249,7 +655,10 @@ export const makeStream = (config) => {
         // failing now keeps an oversized append free. The authoritative check runs
         // once the ops are compiled, below.
         const needsContiguityCheck = expectedVersion > 0 && events.length > 0;
-        const fixedItems = events.length + (idempotency !== undefined ? 1 : 0) + (needsContiguityCheck ? 1 : 0);
+        const fixedItems = events.length +
+            (idempotency !== undefined ? 1 : 0) +
+            (snapshotState !== undefined ? 1 : 0) +
+            (needsContiguityCheck ? 1 : 0);
         if (fixedItems + additionalOps.length > TRANSACT_WRITE_ITEMS_LIMIT) {
             return yield* new AppendTooLarge({
                 streamName: config.streamName,
@@ -261,6 +670,19 @@ export const makeStream = (config) => {
         const client = yield* DynamoClient;
         const tableConfig = yield* config.table.Tag;
         const tableName = tableConfig.name;
+        // A custom TTL attribute is only known at runtime. An index key attribute
+        // sharing its name would receive the sentinel's numeric TTL, which a
+        // string-typed index key rejects — refuse it before anything is written.
+        const ttlAttribute = resolveTtlAttributeName(tableConfig);
+        if (indexAttributes.includes(ttlAttribute)) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "EventStore.append.indexes",
+                cause: `An index of stream "${config.streamName}" uses the attribute "${ttlAttribute}", ` +
+                    "which is the table's TTL attribute. Choose another index attribute name. " +
+                    "Nothing was written.",
+            });
+        }
         const pk = composeStreamPk(streamId);
         // Clock-backed timestamp (deterministic under TestClock; wall-clock in prod).
         const nowDateTime = yield* DateTime.now;
@@ -302,6 +724,17 @@ export const makeStream = (config) => {
             if (encodedMetadata !== undefined) {
                 item.metadata = encodedMetadata;
             }
+            // Stream indexes (#140): the derived key, stored raw, and for a
+            // GSI the stream's partition key. The attributes are part of the
+            // event item itself, so they count towards the size checks.
+            for (const idx of streamIndexes) {
+                const derived = yield* deriveIndexKey(idx, event, version);
+                if (derived === undefined)
+                    continue;
+                item[idx.sk] = derived;
+                if (idx.type === "gsi")
+                    item[idx.pk] = pk;
+            }
             return {
                 Put: {
                     TableName: tableName,
@@ -310,71 +743,12 @@ export const makeStream = (config) => {
                 },
             };
         }));
-        // Caller-owned items, compiled through the same builder
-        // `Transaction.transactWrite` uses, so the two APIs cannot drift.
-        const { items: additionalItems, provenance: additionalProvenance } = yield* buildTransactWriteItems(additionalOps, "EventStore.append.additionalItems");
-        // Authoritative cap check: one additional op can compile to several items
-        // (#113), so the pre-flight lower bound above is not sufficient. Reporting
-        // the EXPANDED count is the point — "you passed 40 items" when the caller
-        // passed 30 ops is baffling without it.
-        if (fixedItems + additionalItems.length > TRANSACT_WRITE_ITEMS_LIMIT) {
-            return yield* new AppendTooLarge({
-                streamName: config.streamName,
-                streamId: streamIdStr,
-                count: fixedItems + additionalItems.length,
-                limit: TRANSACT_WRITE_ITEMS_LIMIT,
-            });
-        }
-        // 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 op order preserved)
-        //   C + E + A             idempotency sentinel (last, so adding it never
-        //                         shifts the additional-item indices the caller sees)
-        //
-        // `A` is the count of EMITTED items, which is >= the number of caller ops:
-        // a `unique` / `retain` put expands into its item plus sentinels plus a
-        // snapshot (#113). The 1:1 "item index == caller index" assumption is gone,
-        // so the reason mapping below goes through `additionalProvenance` — the
-        // caller-facing `indices` on `AdditionalItemConditionFailed` are still
-        // indices into the caller's `additionalItems` array, unchanged.
-        const transactItems = [
-            ...contiguityCheck,
-            ...eventItems,
-            ...additionalItems,
-        ];
-        const checkCount = contiguityCheck.length;
-        const eventCount = eventItems.length;
-        const additionalCount = additionalItems.length;
-        const sentinelIndex = idempotency !== undefined ? transactItems.length : -1;
+        // The idempotency sentinel: a Put guarded by `attribute_not_exists(pk)`.
+        let sentinelPut;
         if (idempotency !== undefined) {
             const sentinel = {
                 pk,
-                sk: DynamoSchema.composeKey(schema, commandKeyLabel, [idempotency.commandId], keyOptions),
+                sk: composeCommandSk(idempotency.commandId),
                 __edd_e__: commandEntityType,
                 streamId: streamIdStr,
                 commandId: idempotency.commandId,
@@ -393,116 +767,183 @@ export const makeStream = (config) => {
                 sentinel[resolveTtlAttributeName(tableConfig)] =
                     DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
             }
-            transactItems.push({
+            sentinelPut = {
                 Put: {
                     TableName: tableName,
                     Item: toAttributeMap(sentinel),
                     ConditionExpression: "attribute_not_exists(pk)",
                 },
-            });
+            };
+        }
+        // The inline snapshot (#138): unconditional — see AppendOptions.snapshot.
+        let snapshotPut;
+        if (snapshotState !== undefined) {
+            const encoded = yield* encodeSnapshotState(snapshotState, "EventStore.append.snapshot");
+            snapshotPut = {
+                Put: {
+                    TableName: tableName,
+                    Item: toAttributeMap({
+                        pk,
+                        sk: snapshotSk,
+                        __edd_e__: snapshotEntityType,
+                        streamId: streamIdStr,
+                        asOfVersion: expectedVersion + events.length,
+                        state: encoded,
+                        timestamp: now,
+                    }),
+                },
+            };
         }
-        yield* client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((error) => {
-            if (!isAwsTransactionCancelled(error.cause)) {
-                return error;
+        /**
+         * 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 events
+         * are written after version > 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 just like a
+         * stale-version Put failure. A zero-event append (a pure 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)",
+                },
             }
-            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,
-                });
+            : undefined;
+        /**
+         * Lay out the append's one transaction — see {@link AppendTransaction}:
+         *   [0, C)                version-contiguity ConditionCheck (C is 0 or 1)
+         *   [C, C + E)            event puts
+         *   [C + E, C + E + A)    additional ITEMS (caller op order preserved)
+         *   then                  idempotency sentinel, then inline snapshot
+         *                         (last, so adding them never shifts the
+         *                         additional-item indices the caller sees)
+         *
+         * `A` is the count of EMITTED items, which is >= the number of caller
+         * ops: a guarded put (#133) expands into its item plus its sentinel
+         * reservations and releases plus a snapshot. The caller-facing `indices`
+         * on `AdditionalItemConditionFailed` are still indices into the caller's
+         * `additionalItems` array — `judgeCancellation` maps them.
+         */
+        const layout = (additional) => {
+            const items = [];
+            const targets = [];
+            const pushStreamItem = (item, type, source) => {
+                items.push(item);
+                targets.push(transactItemTarget(item, tableName, ["pk", "sk"], type, source));
+            };
+            if (contiguityCheck !== undefined) {
+                pushStreamItem(contiguityCheck, entityType, "the version-contiguity check");
             }
-            // 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,
-                    });
-                }
+            const guardCount = items.length;
+            for (const [i, item] of eventItems.entries()) {
+                pushStreamItem(item, entityType, `the event at version ${expectedVersion + i + 1}`);
             }
-            // Attribute each failed additional ITEM back to the caller OP that
-            // produced it. Several items can belong to one op (its main item, its
-            // sentinels, its snapshot), so indices are deduped — a caller who
-            // passed one op must never see it reported twice.
-            const failedOps = new Set();
-            for (let i = 0; i < additionalCount; i++) {
-                if (!failedAt(checkCount + eventCount + i))
-                    continue;
-                const from = additionalProvenance[i];
-                // A reason with no provenance entry cannot be justified positionally;
-                // fall through to TransactionCancelled rather than guess.
-                if (from !== undefined)
-                    failedOps.add(from.opIndex);
-            }
-            const failedAdditional = Array.from(failedOps).sort((a, b) => a - b);
-            if (failedAdditional.length > 0) {
-                return new AdditionalItemConditionFailed({
+            items.push(...additional.items);
+            targets.push(...additional.targets);
+            const sentinelIndex = sentinelPut === undefined ? -1 : items.length;
+            if (sentinelPut !== undefined) {
+                pushStreamItem(sentinelPut, entityType, "the idempotency sentinel");
+            }
+            if (snapshotPut !== undefined) {
+                pushStreamItem(snapshotPut, snapshotEntityType, "the inline snapshot");
+            }
+            return {
+                items,
+                targets,
+                guardCount,
+                eventCount: eventItems.length,
+                additional,
+                sentinelIndex,
+                expectedVersion,
+            };
+        };
+        // A guarded put among the additional items reads its item; a race with
+        // that read cancels the append, which is then built and written again.
+        let lost;
+        for (let attempt = 0; attempt < GUARDED_TRANSACTION_ATTEMPTS; attempt++) {
+            // Caller-owned items, compiled through the same builder
+            // `Transaction.transactWrite` uses, so the two APIs cannot drift.
+            const additional = yield* buildTransactWriteItems(additionalOps, "EventStore.append.additionalItems");
+            const tx = layout(additional);
+            // Authoritative cap check: one additional op can compile to several
+            // items (#113), so the pre-flight lower bound above is not sufficient.
+            // Reporting the EXPANDED count is the point — "you passed 40 items"
+            // when the caller passed 30 ops is baffling without it.
+            if (tx.items.length > TRANSACT_WRITE_ITEMS_LIMIT) {
+                return yield* new AppendTooLarge({
                     streamName: config.streamName,
                     streamId: streamIdStr,
-                    indices: failedAdditional,
-                    reasons,
+                    count: tx.items.length,
+                    limit: TRANSACT_WRITE_ITEMS_LIMIT,
                 });
             }
-            // 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,
-            events,
-        };
+            // Checked before anything is sent: one op per item — an additional
+            // item repeating an event, the contiguity check, the idempotency
+            // sentinel or the inline snapshot is refused, as additional items
+            // repeating each other are — and the transaction within DynamoDB's
+            // 4 MB (#133).
+            yield* refuseRepeatedItems(tx.targets, "EventStore.append");
+            yield* refuseOversizedTransaction(tx.items, tx.targets, "EventStore.append");
+            const outcome = yield* sendAppendTransaction(client, tx, streamIdStr, idempotency?.commandId);
+            if (outcome === undefined) {
+                return { version: expectedVersion + events.length, events };
+            }
+            lost = outcome;
+        }
+        return yield* Effect.fail(lost);
     });
     // ---------------------------------------------------------------------------
     // read
     // ---------------------------------------------------------------------------
-    const read = (streamId) => Effect.gen(function* () {
-        const query = buildEventsQuery(streamId);
+    /** Apply {@link ReadOptions} to an event query. */
+    const withReadOptions = (query, options) => options?.consistentRead === true ? Query.consistentRead(query) : query;
+    const read = (streamId, options) => Effect.gen(function* () {
+        const query = withReadOptions(buildEventsQuery(streamId), options);
         return yield* Query.collect(query);
     });
     // ---------------------------------------------------------------------------
     // readFrom
     // ---------------------------------------------------------------------------
-    const readFrom = (streamId, afterVersion) => Effect.gen(function* () {
+    const readFrom = (streamId, afterVersion, options) => Effect.gen(function* () {
         // 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] }));
+        const query = withReadOptions(buildEventsQuery(streamId).pipe(Query.where({ between: [composeEventSk(afterVersion + 1), maxEventSk] })), options);
         return yield* Query.collect(query);
     });
     // ---------------------------------------------------------------------------
     // currentVersion
     // ---------------------------------------------------------------------------
-    const currentVersion = (streamId) => Effect.gen(function* () {
+    const currentVersion = (streamId, options) => 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 query = withReadOptions(buildEventsQuery(streamId).pipe(Query.reverse, Query.limit(1)), options);
         const page = yield* Query.execute(query);
         const newest = page.items[0];
         if (newest === undefined)
             return 0;
         return newest.version;
     });
+    // headAbove (internal — see HeadAboveProbe)
+    const headAbove = (streamId, floorVersion, options) => Effect.gen(function* () {
+        // Reverse, `Limit: 1`, bounded below by `floorVersion + 1`: an empty range
+        // (the common case — nothing appended past the snapshot) reads no items;
+        // otherwise the single evaluated item is the head.
+        const query = withReadOptions(buildEventsQuery(streamId).pipe(Query.where({ between: [composeEventSk(floorVersion + 1), maxEventSk] }), Query.reverse, Query.limit(1)), options);
+        const page = yield* Query.execute(query);
+        const newest = page.items[0];
+        return newest === undefined ? floorVersion : newest.version;
+    });
     // ---------------------------------------------------------------------------
     // Snapshot primitives
     // ---------------------------------------------------------------------------
@@ -514,11 +955,7 @@ export const makeStream = (config) => {
         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 encoded = yield* encodeSnapshotState(state, "EventStore.writeSnapshot");
         const item = {
             pk: composeStreamPk(streamId),
             sk: snapshotSk,
@@ -540,9 +977,17 @@ export const makeStream = (config) => {
         })
             .pipe(Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.void));
     });
-    const readSnapshot = (streamId) => Effect.gen(function* () {
-        if (snapshot === undefined)
-            return yield* snapshotUnavailable("readSnapshot");
+    /**
+     * Decode a stored snapshot item. A snapshot that fails to decode through the
+     * state schema is a `ValidationError` — never silently discarded.
+     */
+    const decodeSnapshotItem = (raw, operation) => Schema.decodeUnknownEffect(snapshot.schema)(raw.state).pipe(Effect.mapError((cause) => new ValidationError({ entityType: snapshotEntityType, operation, cause })), Effect.map((state) => ({
+        state,
+        asOfVersion: raw.asOfVersion,
+        timestamp: raw.timestamp,
+    })));
+    /** The raw snapshot item, by its exact key, in one `GetItem`. */
+    const getSnapshotItem = (streamId, consistentRead) => Effect.gen(function* () {
         const client = yield* DynamoClient;
         const { name: tableName } = yield* config.table.Tag;
         const result = yield* client.getItem({
@@ -551,21 +996,140 @@ export const makeStream = (config) => {
                 pk: composeStreamPk(streamId),
                 sk: snapshotSk,
             }),
-            ConsistentRead: true,
+            ...(consistentRead ? { ConsistentRead: true } : {}),
         });
-        if (result.Item === undefined)
+        return result.Item === undefined ? undefined : fromAttributeMap(result.Item);
+    });
+    const readSnapshot = (streamId) => Effect.gen(function* () {
+        if (snapshot === undefined)
+            return yield* snapshotUnavailable("readSnapshot");
+        const raw = yield* getSnapshotItem(streamId, true);
+        if (raw === 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,
+        return Option.some(yield* decodeSnapshotItem(raw, "EventStore.readSnapshot"));
+    });
+    // ---------------------------------------------------------------------------
+    // readLatest — snapshot + delta + head in one request (#138)
+    // ---------------------------------------------------------------------------
+    const readLatest = (streamId, options) => Effect.gen(function* () {
+        // Without a snapshot config there is nothing to read but the events
+        // (`verifySnapshot` is ignored).
+        if (snapshot === undefined) {
+            const events = yield* read(streamId, options);
+            return {
+                snapshot: Option.none(),
+                events,
+                version: events[events.length - 1]?.version ?? 0,
+            };
+        }
+        // `verifySnapshot: false` — the snapshot item alone, by its exact key:
+        // a `GetItem` reads one item where the verified `Query` reads the
+        // snapshot and at least the newest event. Its version is unverified
+        // (see `ReadLatestOptions`). Without a snapshot item there is nothing to
+        // trust, so fall through to the verified read.
+        if (options?.verifySnapshot === false) {
+            const refusal = unverifiedSnapshotRefusal(config.streamName, snapshotSettings, "readLatest");
+            if (refusal !== undefined)
+                return yield* Effect.die(new Error(refusal));
+            const raw = yield* getSnapshotItem(streamId, options.consistentRead === true);
+            if (raw !== undefined) {
+                const current = yield* decodeSnapshotItem(raw, "EventStore.readLatest");
+                return {
+                    snapshot: Option.some(current),
+                    events: [],
+                    version: current.asOfVersion,
+                };
+            }
+        }
+        const client = yield* DynamoClient;
+        const { name: tableName } = yield* config.table.Tag;
+        // One reverse Query over `[first event SK, snapshot SK]`: the snapshot
+        // sorts after every event and the command sentinels before them (see
+        // `snapshotSk`), so the range holds exactly the events and the snapshot,
+        // and the snapshot is the first item evaluated. The `__edd_e__` filter is
+        // belt and braces — `Limit` counts items before it applies.
+        const base = {
+            TableName: tableName,
+            KeyConditionExpression: "#pk = :pk AND #sk BETWEEN :first AND :snapshot",
+            FilterExpression: "#e IN (:eventType, :snapshotType)",
+            ExpressionAttributeNames: { "#pk": "pk", "#sk": "sk", "#e": "__edd_e__" },
+            ExpressionAttributeValues: toAttributeMap({
+                ":pk": composeStreamPk(streamId),
+                ":first": eventSkPrefix,
+                ":snapshot": snapshotSk,
+                ":eventType": entityType,
+                ":snapshotType": snapshotEntityType,
+            }),
+            ScanIndexForward: false,
+            ...(options?.consistentRead === true ? { ConsistentRead: true } : {}),
+        };
+        let snapshotRaw;
+        /** Event items, newest first. */
+        const eventRaws = [];
+        // The first page is sized for the snapshot plus a lag of up to `every`
+        // events, so a current (or modestly lagging) snapshot loads in one
+        // request.
+        let limit = (snapshot.every ?? 1) + 1;
+        let startKey;
+        for (;;) {
+            const page = yield* client.query({
+                ...base,
+                ...(limit !== undefined ? { Limit: limit } : {}),
+                ...(startKey !== undefined ? { ExclusiveStartKey: startKey } : {}),
+            });
+            for (const item of page.Items ?? []) {
+                const raw = fromAttributeMap(item);
+                if (raw.__edd_e__ === snapshotEntityType)
+                    snapshotRaw = raw;
+                else
+                    eventRaws.push(raw);
+            }
+            startKey = page.LastEvaluatedKey;
+            if (startKey === undefined)
+                break;
+            // Without a snapshot (it would have been the first item evaluated),
+            // read on, unlimited, to the start of the stream.
+            if (snapshotRaw === undefined) {
+                limit = undefined;
+                continue;
+            }
+            // Done once the event right after the snapshot has been seen: versions
+            // are contiguous, so every event the snapshot does not cover is then in
+            // hand, and everything older is already folded into it. Otherwise read
+            // exactly the events still missing, `asOfVersion + 1 … oldest - 1`
+            // (DynamoDB's 1 MB page cap aside).
+            const asOfVersion = snapshotRaw.asOfVersion;
+            const oldest = eventRaws[eventRaws.length - 1]?.version;
+            if (oldest !== undefined && oldest <= asOfVersion + 1)
+                break;
+            limit = oldest === undefined ? undefined : oldest - asOfVersion - 1;
+        }
+        const latest = snapshotRaw === undefined
+            ? Option.none()
+            : Option.some(yield* decodeSnapshotItem(snapshotRaw, "EventStore.readLatest"));
+        const asOfVersion = Option.isSome(latest) ? latest.value.asOfVersion : 0;
+        const delta = eventRaws.filter((raw) => raw.version > asOfVersion).reverse();
+        const events = yield* Effect.forEach(delta, (raw) => decodeStreamEvent(raw));
+        return {
+            snapshot: latest,
+            events,
+            version: events[events.length - 1]?.version ?? asOfVersion,
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // hasCommandSentinel (internal — see CommandSentinelProbe)
+    // ---------------------------------------------------------------------------
+    const hasCommandSentinel = (streamId, commandId) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        const { name: tableName } = yield* config.table.Tag;
+        const result = yield* client.getItem({
+            TableName: tableName,
+            Key: toAttributeMap({ pk: composeStreamPk(streamId), sk: composeCommandSk(commandId) }),
+            ConsistentRead: true,
+            ProjectionExpression: "#pk",
+            ExpressionAttributeNames: { "#pk": "pk" },
         });
+        return result.Item !== undefined;
     });
     // ---------------------------------------------------------------------------
     // query.events helper
@@ -587,8 +1151,69 @@ export const makeStream = (config) => {
             // `Query.where` replaces this — the `__edd_e__` filter still applies.
         }).pipe(Query.where({ beginsWith: eventSkPrefix }));
     };
+    // ---------------------------------------------------------------------------
+    // Stream indexes — query.index / readIndex (#140)
+    // ---------------------------------------------------------------------------
+    /**
+     * A query of one stream index, scoped to the stream's partition: the LSI
+     * shares the table's `pk`; a GSI's `pk` attribute carries the same value.
+     * No sort-key condition — the index holds only this stream's indexed events
+     * under that key; `Query.where` narrows the derived-key range.
+     *
+     * @throws `[EDD-9066]` for a name the stream does not declare (unreachable
+     *   through the types).
+     */
+    const buildIndexQuery = (name, streamId) => {
+        const idx = streamIndexes.find((candidate) => candidate.name === name);
+        if (idx === undefined) {
+            throw new Error(`[EDD-9066] EventStream "${config.streamName}": unknown index "${String(name)}". ` +
+                (streamIndexes.length === 0
+                    ? "The stream declares no indexes."
+                    : `Declared: ${streamIndexes.map((candidate) => `"${candidate.name}"`).join(", ")}.`));
+        }
+        return Query.make({
+            tableName: "",
+            indexName: idx.index,
+            pkField: idx.pk,
+            pkValue: composeStreamPk(streamId),
+            skField: idx.sk,
+            entityTypes: [entityType],
+            decoder: (raw) => decodeStreamEvent(raw),
+            resolveTableName: config.table.Tag.useSync((tc) => tc.name),
+            // A GSI is read only eventually consistently: `Query.consistentRead`
+            // on it is refused before anything is sent.
+            globalIndex: idx.type === "gsi",
+            keyFields: [idx.pk, idx.sk, "pk", "sk"],
+        });
+    };
+    const readIndex = (name, streamId, options) => Effect.gen(function* () {
+        const refuse = (cause) => new ValidationError({ entityType, operation: "EventStore.readIndex", cause });
+        const invalidCondition = invalidIndexKeyCondition(options);
+        if (invalidCondition !== undefined) {
+            return yield* refuse(`${invalidCondition} Nothing was sent.`);
+        }
+        const limit = options?.limit;
+        if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
+            return yield* refuse(`limit must be a positive integer; received ${String(limit)}. Nothing was sent.`);
+        }
+        let query = buildIndexQuery(name, streamId);
+        if (options?.beginsWith !== undefined) {
+            query = Query.where(query, { beginsWith: options.beginsWith });
+        }
+        else if (options?.between !== undefined) {
+            query = Query.where(query, { between: options.between });
+        }
+        if (options?.reverse === true)
+            query = Query.reverse(query);
+        if (limit !== undefined)
+            query = Query.limit(query, limit);
+        if (options?.consistentRead === true)
+            query = Query.consistentRead(query);
+        return yield* Query.collect(query);
+    });
     const queryNamespace = {
         events: (streamId) => buildEventsQuery(streamId),
+        index: (name, streamId) => buildIndexQuery(name, streamId),
     };
     // ---------------------------------------------------------------------------
     // Return EventStream
@@ -607,13 +1232,19 @@ export const makeStream = (config) => {
         streamName: config.streamName,
         eventSchema: eventUnion,
         snapshotConfig: snapshotSettings,
+        indexes: indexSettings,
         writeSnapshot,
         readSnapshot,
         append,
         read,
         readFrom,
         currentVersion,
+        readLatest,
+        readIndex,
         query: queryNamespace,
+        [StreamIdFormatter]: composeStreamIdString,
+        [CommandSentinelProbe]: hasCommandSentinel,
+        [HeadAboveProbe]: headAbove,
     };
 };
 // ---------------------------------------------------------------------------
@@ -636,6 +1267,8 @@ export const makeStream = (config) => {
 export const bind = (stream) => Effect.gen(function* () {
     const ctx = yield* Effect.context();
     const provide = (effect) => Effect.provide(effect, ctx);
+    const probe = commandSentinelProbeOf(stream);
+    const headProbe = headAboveProbeOf(stream);
     return {
         [EventStreamTypeId]: EventStreamTypeId,
         pipe() {
@@ -645,106 +1278,419 @@ export const bind = (stream) => Effect.gen(function* () {
         streamName: stream.streamName,
         eventSchema: stream.eventSchema,
         snapshotConfig: stream.snapshotConfig,
+        indexes: stream.indexes,
         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)),
-        currentVersion: (streamId) => provide(stream.currentVersion(streamId)),
+        read: (streamId, options) => provide(stream.read(streamId, options)),
+        readFrom: (streamId, afterVersion, options) => provide(stream.readFrom(streamId, afterVersion, options)),
+        currentVersion: (streamId, options) => provide(stream.currentVersion(streamId, options)),
+        readLatest: (streamId, options) => provide(stream.readLatest(streamId, options)),
+        readIndex: (name, streamId, options) => provide(stream.readIndex(name, streamId, options)),
         query: stream.query,
         provide,
+        [StreamIdFormatter]: (id) => formatStreamIdOf(stream, id),
+        [CommandSentinelProbe]: probe === undefined
+            ? undefined
+            : (id, commandId) => provide(probe(id, commandId)),
+        [HeadAboveProbe]: headProbe === undefined
+            ? undefined
+            : (id, floorVersion, options) => provide(headProbe(id, floorVersion, options)),
     };
 });
+/**
+ * Derive the `CreateTable` fragments for the stream indexes (#140) of the given
+ * streams (`EventStream` or `BoundEventStream`) — `AttributeDefinitions`,
+ * `LocalSecondaryIndexes` and `GlobalSecondaryIndexes`, each index projecting
+ * `ALL` — to merge into the caller's `CreateTable` input. Event tables are not
+ * derived by `Table.definition`, and the table's own `pk` / `sk` are not
+ * included: add them (and, on a provisioned table, each GSI's
+ * `ProvisionedThroughput`) yourself.
+ *
+ * An index shared by several streams with the same definition is emitted
+ * once. Lists are sorted by index name, attributes by attribute name.
+ *
+ * - An LSI can only be created with the table, and caps the item collection
+ *   of every partition key value in the table at 10 GB — entity partitions
+ *   and streams without indexes included.
+ * - The projection must stay `ALL`: events are decoded from the index item.
+ *
+ * @example
+ * ```typescript
+ * const fragments = EventStore.indexDefinitions(Entries, Orders)
+ * yield* client.createTable({
+ *   TableName: "events",
+ *   BillingMode: "PAY_PER_REQUEST",
+ *   KeySchema: [
+ *     { AttributeName: "pk", KeyType: "HASH" },
+ *     { AttributeName: "sk", KeyType: "RANGE" },
+ *   ],
+ *   AttributeDefinitions: [
+ *     { AttributeName: "pk", AttributeType: "S" },
+ *     { AttributeName: "sk", AttributeType: "S" },
+ *     ...fragments.AttributeDefinitions,
+ *   ],
+ *   LocalSecondaryIndexes: fragments.LocalSecondaryIndexes,
+ *   GlobalSecondaryIndexes: fragments.GlobalSecondaryIndexes,
+ * })
+ * ```
+ *
+ * @throws `[EDD-9067]` when two streams define the same physical index
+ *   differently (another type, or other key attributes).
+ */
+export const indexDefinitions = (...streams) => {
+    const byIndex = new Map();
+    for (const stream of streams) {
+        for (const [name, settings] of Object.entries(stream.indexes)) {
+            const owner = `index "${name}" of stream "${stream.streamName}"`;
+            const existing = byIndex.get(settings.index);
+            if (existing === undefined) {
+                byIndex.set(settings.index, {
+                    type: settings.type,
+                    index: settings.index,
+                    pk: settings.pk,
+                    sk: settings.sk,
+                    owner,
+                });
+                continue;
+            }
+            if (existing.type !== settings.type ||
+                existing.pk !== settings.pk ||
+                existing.sk !== settings.sk) {
+                const describe = (s) => `${s.type} (pk "${s.pk}", sk "${s.sk}")`;
+                throw new Error(`[EDD-9067] EventStore.indexDefinitions: the physical index "${settings.index}" is ` +
+                    `defined as ${describe(existing)} by ${existing.owner} and as ${describe(settings)} ` +
+                    `by ${owner}.`);
+            }
+        }
+    }
+    const attributes = new Set();
+    const lsis = [];
+    const gsis = [];
+    const sorted = [...byIndex.values()].sort((a, b) => a.index.localeCompare(b.index));
+    for (const settings of sorted) {
+        const definition = {
+            IndexName: settings.index,
+            KeySchema: [
+                { AttributeName: settings.pk, KeyType: "HASH" },
+                { AttributeName: settings.sk, KeyType: "RANGE" },
+            ],
+            Projection: { ProjectionType: "ALL" },
+        };
+        attributes.add(settings.sk);
+        if (settings.type === "gsi") {
+            attributes.add(settings.pk);
+            gsis.push(definition);
+        }
+        else {
+            lsis.push(definition);
+        }
+    }
+    return {
+        AttributeDefinitions: [...attributes]
+            .sort()
+            .map((name) => ({ AttributeName: name, AttributeType: "S" })),
+        ...(lsis.length > 0 ? { LocalSecondaryIndexes: lsis } : {}),
+        ...(gsis.length > 0 ? { GlobalSecondaryIndexes: gsis } : {}),
+    };
+};
 /** @internal Both `EventStream` and `BoundEventStream` carry this brand. */
 const hasEventStreamBrand = (u) => typeof u === "object" && u !== null && EventStreamTypeId in u;
+/** @internal Resolve a {@link CommandOptions.additionalItems} against a decision. */
+const deriveAdditionalItems = (input, decision) => {
+    if (typeof input !== "function")
+        return Effect.succeed(input);
+    const derived = input(decision);
+    return Effect.isEffect(derived) ? derived : Effect.succeed(derived);
+};
 /** @internal */
 const makeCommandHandlerImpl = (decider, stream, options) => {
+    // `verifySnapshot: false` is refused up front unless the stream writes its
+    // snapshot in every append (EDD-9068) — at handler construction, so a
+    // misconfiguration fails at startup rather than on the first command.
+    const snapshotSettings = stream.snapshotConfig;
+    if (options?.verifySnapshot === false) {
+        const refusal = unverifiedSnapshotRefusal(stream.streamName, snapshotSettings, "commandHandler");
+        if (refusal !== undefined)
+            throw new Error(refusal);
+    }
+    // Ignored on a stream without a snapshot config: there is no snapshot to trust.
+    const unverifiedLoads = options?.verifySnapshot === false && snapshotSettings !== undefined;
     const retryPolicy = options?.retry;
     const schedule = retryPolicy === undefined
         ? undefined
         : typeof retryPolicy === "number"
             ? Schedule.recurs(retryPolicy)
             : retryPolicy;
+    // Consistent by default: an eventually consistent load can hand `decide`
+    // state that misses acknowledged events (#139).
+    const readOptions = { consistentRead: options?.consistentRead ?? true };
+    const unverifiedReadOptions = { ...readOptions, verifySnapshot: false };
     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.
+        const expectedVersion = callOptions?.expectedVersion;
+        // 1. Establish the base state + version. A snapshot-configured stream
+        //    loads its snapshot, the events after it and its head in one request
+        //    (#138) — or, unverified, the snapshot item alone; any other stream
+        //    replays from the beginning.
+        const load = (verify) => Effect.gen(function* () {
             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);
+            if (snapshotSettings !== undefined) {
+                const latest = (yield* stream.readLatest(streamId, verify ? readOptions : unverifiedReadOptions));
+                let snapshotAsOfVersion = 0;
+                if (Option.isSome(latest.snapshot)) {
+                    snapshotAsOfVersion = latest.snapshot.value.asOfVersion;
+                    state = latest.snapshot.value.state;
                 }
-                const newest = delta[delta.length - 1];
-                if (newest !== undefined)
-                    baseVersion = newest.version;
-            }
-            else {
-                const events = yield* stream.read(streamId);
-                for (const event of events) {
+                for (const event of latest.events) {
                     state = decider.evolve(state, event.data);
                 }
-                const newest = events[events.length - 1];
-                baseVersion = newest === undefined ? 0 : newest.version;
+                const loaded = {
+                    state,
+                    version: latest.version,
+                    snapshotAsOfVersion,
+                    // An unverified read returns a snapshot alone; without one it has
+                    // already fallen back to the verified read.
+                    verified: verify || Option.isNone(latest.snapshot),
+                    eventsAfterSnapshot: latest.events.length,
+                };
+                return loaded;
             }
-            // 2. Decide
-            const newEvents = yield* decider.decide(command, state);
-            // 3. No-op command — return current state
+            const events = yield* stream.read(streamId, readOptions);
+            for (const event of events) {
+                state = decider.evolve(state, event.data);
+            }
+            const loaded = {
+                state,
+                version: events[events.length - 1]?.version ?? 0,
+                snapshotAsOfVersion: 0,
+                verified: true,
+                eventsAfterSnapshot: events.length,
+            };
+            return loaded;
+        });
+        // 4–8. Commit one decision: fold, derive items, append, snapshot. With
+        //    `returnAppendConflict`, an append that fails with `VersionConflict`
+        //    returns the conflict instead of failing, so the caller can tell a
+        //    stale unverified load from a lost race.
+        const commit = (loaded, newEvents, returnAppendConflict) => Effect.gen(function* () {
+            const baseVersion = loaded.version;
+            const state = loaded.state;
+            // 4. No-op command — return current state
             if (newEvents.length === 0) {
-                return { state, version: baseVersion, events: [] };
+                const noop = {
+                    state,
+                    version: baseVersion,
+                    events: [],
+                };
+                return noop;
             }
-            // 4. Append with optimistic concurrency, plus any caller-owned items and
-            //    the dedup sentinel, all in one transaction.
+            // 5. Fold the new events BEFORE appending (#137): the post-decision
+            //    state is what a function-form `additionalItems` projects, what a
+            //    snapshot records, and what the handler returns — always the
+            //    `evolve` fold, never anything produced inside `decide`.
+            const previous = state;
+            let next = state;
+            for (const event of newEvents) {
+                next = decider.evolve(next, event);
+            }
+            // 6. Derive the caller's items from the decision. Re-run on every
+            //    attempt (and on a re-decision), because the whole cycle is the
+            //    retried unit.
+            const additionalItems = yield* deriveAdditionalItems(callOptions?.additionalItems, {
+                events: newEvents,
+                state: next,
+                previous,
+                version: baseVersion,
+            });
+            // 7. Append with optimistic concurrency, plus the caller's items, the
+            //    dedup sentinel and an inline snapshot, all in one transaction.
+            //    `baseVersion` equals any caller-supplied `expectedVersion` here
+            //    (checked in step 2).
             const appendOptions = {};
             if (callOptions?.metadata !== undefined)
                 appendOptions.metadata = callOptions.metadata;
-            if (callOptions?.additionalItems !== undefined) {
-                appendOptions.additionalItems = callOptions.additionalItems;
-            }
+            if (additionalItems !== undefined)
+                appendOptions.additionalItems = 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.
+            // Inline snapshots (#138) ride in the append transaction: on every
+            // append, or once `every` events have accumulated since the snapshot.
+            const mode = snapshotSettings?.mode ?? "after-append";
             const every = snapshotSettings?.every;
-            if (every !== undefined && result.version - snapshotAsOfVersion >= every) {
+            const newVersion = baseVersion + newEvents.length;
+            if (snapshotSettings !== undefined &&
+                mode === "inline" &&
+                (every === undefined || newVersion - loaded.snapshotAsOfVersion >= every)) {
+                appendOptions.snapshot = next;
+            }
+            const appended = stream.append(streamId, newEvents, baseVersion, appendOptions);
+            const outcome = yield* returnAppendConflict
+                ? appended.pipe(Effect.catchIf((error) => error instanceof VersionConflict, (conflict) => Effect.succeed(conflict)))
+                : appended;
+            if (outcome instanceof VersionConflict)
+                return outcome;
+            const result = outcome;
+            // 8. After-append snapshots, 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.
+            if (mode === "after-append" &&
+                every !== undefined &&
+                result.version - loaded.snapshotAsOfVersion >= every) {
                 yield* stream
-                    .writeSnapshot(streamId, state, result.version)
+                    .writeSnapshot(streamId, next, 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 };
+            const done = {
+                state: next,
+                version: result.version,
+                events: newEvents,
+            };
+            return done;
         });
-        return schedule === undefined
+        // The If-Match answer for a stream at `actualVersion` (#136). A
+        // redelivery of a command that already committed (its response was lost)
+        // arrives with its original If-Match, which the stream has since moved
+        // past. It is a duplicate, not a lost race — `append` ranks
+        // `DuplicateCommand` above `VersionConflict` for the same reason — so
+        // consult the sentinel before reporting the conflict. The extra read is
+        // paid on this conflict path only.
+        const ifMatchMismatch = (expected, actualVersion) => Effect.gen(function* () {
+            const probe = commandSentinelProbeOf(stream);
+            const commandId = callOptions?.commandId;
+            if (options?.idempotency !== undefined && commandId !== undefined && probe !== undefined) {
+                if (yield* probe(streamId, commandId)) {
+                    return yield* new DuplicateCommand({
+                        streamName: stream.streamName,
+                        streamId: formatStreamIdOf(stream, streamId),
+                        commandId,
+                    });
+                }
+            }
+            return yield* new VersionConflict({
+                streamName: stream.streamName,
+                streamId: formatStreamIdOf(stream, streamId),
+                expectedVersion: expected,
+                actualVersion,
+            });
+        });
+        // The head, known to be at least `floorVersion` (see HeadAboveProbe): one
+        // `Query` that reads no items while the snapshot is current.
+        const headAbove = (floorVersion) => {
+            const probe = headAboveProbeOf(stream);
+            return probe !== undefined
+                ? probe(streamId, floorVersion, readOptions)
+                : stream.currentVersion(streamId, readOptions);
+        };
+        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`.",
+                });
+            }
+            // A malformed If-Match (`NaN` from a failed parse, a negative or
+            // fractional number) is a caller bug, not a conflict — refuse it before
+            // reading anything.
+            if (expectedVersion !== undefined &&
+                (!Number.isInteger(expectedVersion) || expectedVersion < 0)) {
+                return yield* new ValidationError({
+                    entityType: stream.streamName,
+                    operation: "EventStore.commandHandler",
+                    cause: `expectedVersion must be a non-negative integer; received ${String(expectedVersion)}.`,
+                });
+            }
+            // 1. Load (see `load`).
+            let loaded = yield* load(!unverifiedLoads);
+            // An unverified snapshot at another version than the caller's If-Match
+            // may merely lag the head: re-read verified, so only a genuine mismatch
+            // is reported, with the verified head as its `actualVersion`.
+            if (expectedVersion !== undefined && !loaded.verified && loaded.version !== expectedVersion) {
+                loaded = yield* load(true);
+            }
+            // 2. If-Match (#136): the caller saw a different version, so `decide`
+            //    must not run against state the caller never saw.
+            if (expectedVersion !== undefined && expectedVersion !== loaded.version) {
+                return yield* ifMatchMismatch(expectedVersion, loaded.version);
+            }
+            // 3. Decide on a verified load, and commit. An If-Match call's
+            //    append-time conflict is its answer (never re-read or retried), and
+            //    a verified load's conflict is a lost race.
+            if (loaded.verified) {
+                const newEvents = yield* decider.decide(command, loaded.state);
+                return (yield* commit(loaded, newEvents, false));
+            }
+            // 3'. Decide on an unverified snapshot. It is normally at the head, but
+            //    events appended without one (a raw `append`, data written before
+            //    inline mode) make it lag — and then every answer made on it is
+            //    stale, not only one that appends. So no answer is returned until
+            //    the head is confirmed: an append confirms it by succeeding; a
+            //    decision that appends nothing (a `decide` failure or a no-op) and
+            //    an append conflict are confirmed with one more read.
+            const decided = yield* Effect.result(decider.decide(command, loaded.state));
+            const first = Result.isSuccess(decided) && decided.success.length > 0
+                ? yield* commit(loaded, decided.success, true)
+                : undefined;
+            if (first !== undefined && !(first instanceof VersionConflict))
+                return first;
+            // The answer the first decision gives when the snapshot proves current.
+            const firstAnswer = first !== undefined
+                ? Effect.fail(first)
+                : Result.isFailure(decided)
+                    ? Effect.fail(decided.failure)
+                    : Effect.succeed({ state: loaded.state, version: loaded.version, events: [] });
+            // With an If-Match equal to the snapshot's `asOfVersion`, the snapshot
+            // state is exactly the state the caller saw, so `decide` ran on the
+            // right state — the only question is whether the stream is still at
+            // that version. A newer head answers exactly as a verified load would
+            // have (the pre-decide check above): `DuplicateCommand` for a committed
+            // redelivery, else `VersionConflict` with the head as `actualVersion`.
+            // The first decision is discarded. Never re-decided: an If-Match call's
+            // conflict is its answer.
+            if (expectedVersion !== undefined) {
+                const head = yield* headAbove(expectedVersion);
+                if (head !== expectedVersion)
+                    return yield* ifMatchMismatch(expectedVersion, head);
+                return yield* firstAnswer;
+            }
+            // No If-Match, nothing appended: a head at the snapshot's version
+            // confirms the answer (one `Query` above the snapshot's version, which
+            // reads no items while the snapshot is current).
+            if (first === undefined) {
+                const head = yield* headAbove(loaded.version);
+                if (head === loaded.version)
+                    return yield* firstAnswer;
+            }
+            // No If-Match, the append conflicted — the snapshot lagged the head, or
+            // another writer won the race; one verified load tells them apart. A
+            // snapshot at the head is a genuine race, which the retry policy
+            // handles as it always has (a retried attempt loads unverified again).
+            // A lagging snapshot is decided on again, once: only a successful inline
+            // append rewrites the snapshot, so surfacing the conflict would fail
+            // every command on the stream until something else repaired it.
+            const verified = yield* load(true);
+            if (first !== undefined && verified.eventsAfterSnapshot === 0)
+                return yield* first;
+            // The first decision was made on stale state: decide again on the
+            // verified state — `decide` (and a function-form `additionalItems`)
+            // runs a second time in this attempt. Its own conflict follows the
+            // retry policy.
+            const newEvents = yield* decider.decide(command, verified.state);
+            return (yield* commit(verified, newEvents, false));
+        });
+        // A caller-supplied `expectedVersion` is a conditional write: its
+        // `VersionConflict` (pre-decide or from the append) is the answer, never a
+        // cue to re-read and re-decide.
+        return schedule === undefined || expectedVersion !== undefined
             ? attempt
             : Effect.retry(attempt, {
                 // `while` runs before the schedule, so the schedule only ever sees a
@@ -784,12 +1730,51 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
  *   idempotency: { ttl: Duration.days(1) },
  * })
  * yield* handle({ matchId: "m-1" }, command, { commandId: "cmd-7f3a" })
+ *
+ * // Load state from the inline snapshot alone (mode "inline" without `every`)
+ * const handle = EventStore.commandHandler(decider, stream, { verifySnapshot: false })
+ *
+ * // If-Match: fail with VersionConflict (never retried) unless the stream is at v7
+ * yield* handle({ matchId: "m-1" }, command, { expectedVersion: 7 })
+ *
+ * // Inline projection, committed in the same transaction as the events
+ * yield* handle({ matchId: "m-1" }, command, {
+ *   additionalItems: ({ state }) => [Scoreboard.put({ matchId: "m-1", runs: state.runs })],
+ * })
  * ```
  *
- * 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.
+ * Each invocation runs
+ * `load → [expectedVersion check] → decide → fold new events → derive items → append → [snapshot]`.
+ *
+ * - **Load.** Strongly consistent by default — see
+ *   {@link CommandHandlerOptions.consistentRead}. When the stream declares a
+ *   `snapshot` config, state is loaded with {@link EventStream.readLatest} —
+ *   the snapshot, the events after it and the head in one request in steady
+ *   state — and only those events are folded, instead of replaying the stream
+ *   from the beginning. On a `mode: "inline"` stream without `every`,
+ *   {@link CommandHandlerOptions.verifySnapshot}`: false` loads the snapshot
+ *   item alone (one `GetItem`); an answer that is not a successful append is
+ *   confirmed against the head first, and a snapshot that proves stale falls
+ *   back to the verified load — in which case `decide` may run twice.
+ * - **expectedVersion.** See {@link CommandOptions.expectedVersion}.
+ * - **Fold before append.** The new events are folded into state before the
+ *   append, so the state returned, snapshotted and handed to a function-form
+ *   `additionalItems` (see {@link Decision}) is always the `evolve` fold.
+ * - **Snapshot.** With `snapshot.mode: "inline"`, the snapshot is written in
+ *   the append transaction itself — on every append, or at the `every`
+ *   cadence. With the default `"after-append"` and `snapshot.every` set, a
+ *   fresh snapshot is written (best-effort) after a successful append once the
+ *   cadence threshold is crossed. See {@link SnapshotMode}.
+ * - **One atomic append.** One command, one decision, one append: a decision
+ *   too large for one transaction fails with `AppendTooLarge` before anything
+ *   is written. A large command is split by the application into stepped
+ *   commands — each an ordinary call, chained by `expectedVersion` — so a
+ *   failure partway leaves the stream at a real intermediate state.
+ *
+ * The handler is generic per call over the error and requirements of a
+ * function-form `additionalItems` that returns an `Effect`: they join the
+ * handler's error channel and requirements (on a `BoundEventStream` handler
+ * they are its only requirements).
  *
  * Without `idempotency`, command processing is **at-least-once**: a retry after
  * an acked-but-lost response re-runs `decide` and appends again.