effect-dynamodb 1.23.0 → 1.25.0

package/dist/EventStore.js

@@ -4,10 +4,18 @@
  * 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, each projecting all of the
+ *   event, all but its metadata, or only its keys — `readIndex`,
+ *   `query.index`, and `indexDefinitions` for the `CreateTable` fragments
  * - `fold` / `foldFrom` helpers for state reconstruction
  *
  * Built on the existing library primitives (DynamoSchema, KeyComposer, Query,
@@ -15,14 +23,15 @@
  */
 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 { AdditionalItemConditionFailed, AppendTooLarge, DuplicateCommand, isAwsConditionalCheckFailed, isAwsTransactionCancelled, 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, GUARDED_TRANSACTION_ATTEMPTS, judgeCancellation, refuseOversizedTransaction, refuseRepeatedItems, transactItemTarget, } from "./internal/TransactWriteOps.js";
+import { buildTransactWriteItems, GUARDED_TRANSACTION_ATTEMPTS, judgeCancellation, transactItemTarget, } from "./internal/TransactWriteOps.js";
+import { diagnosedValidationError, diagnoseFailure, mergeKeyAttributes, withCause, } from "./internal/WriteDiagnosis.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 +47,260 @@ const EventEnvelope = Schema.Struct({
     eventType: Schema.String,
     timestamp: Schema.String,
 });
+/**
+ * @internal Why a {@link ReadIndexOptions} key condition cannot be sent, or
+ * `undefined` when it can: the options' own meaning — at most one of
+ * `beginsWith` and `between`, string bounds (a number would be sent as `N`
+ * against a string key). DynamoDB's rules on the bounds — not empty, a
+ * `between` in order — are DynamoDB's to enforce: its rejection is diagnosed,
+ * naming the index and the bound (#144).
+ */
+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) {
+        return typeof beginsWith === "string"
+            ? undefined
+            : "beginsWith must be a string; omit it to read the whole sub-stream.";
+    }
+    const between = options?.between;
+    if (between === undefined)
+        return undefined;
+    if (!Array.isArray(between) ||
+        between.length !== 2 ||
+        !between.every((bound) => typeof bound === "string")) {
+        return "between must be a pair of strings.";
+    }
+    return undefined;
+};
+/**
+ * @internal The attributes `append` writes on every event item besides the
+ * table key (`pk`, `sk`), the optional `metadata` and the index attributes:
+ * the envelope, `data` and the `__edd_e__` discriminator. Sorted. A
+ * `"withoutMetadata"` stream index projects exactly these.
+ */
+const EVENT_ITEM_ATTRIBUTES = [
+    "__edd_e__",
+    "data",
+    "eventType",
+    "streamId",
+    "timestamp",
+    "version",
+];
+/**
+ * @internal The event attributes an `"all"` or `"withoutMetadata"` stream index
+ * guarantees on its rows and a decode needs: a row lacking one was read
+ * through an index deployed narrower than declared.
+ */
+const PROJECTED_ENVELOPE_ATTRIBUTES = [
+    "data",
+    "eventType",
+    "streamId",
+    "timestamp",
+    "version",
+];
+/**
+ * @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 Every member a stream index entry may declare (`StreamIndexConfigKey`). */
+const STREAM_INDEX_CONFIG_KEYS = [
+    "type",
+    "index",
+    "pk",
+    "sk",
+    "key",
+    "projection",
+];
+/**
+ * @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,
+ *   an unknown `projection`, a member the entry type does not declare — a
+ *   misspelled `projection` would otherwise silently mean `"all"`).
+ * @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 unknownKey = Object.keys(entry).find((key) => !STREAM_INDEX_CONFIG_KEYS.includes(key));
+        if (unknownKey !== undefined) {
+            fail("EDD-9063", `index "${name}": unknown member "${unknownKey}"; an index declares ` +
+                `${STREAM_INDEX_CONFIG_KEYS.join(", ")}.`);
+        }
+        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 projection = (entry.projection ?? "all");
+        if (projection !== "all" && projection !== "withoutMetadata" && projection !== "keys") {
+            fail("EDD-9063", `index "${name}": projection must be "all", "withoutMetadata" or "keys"; received ` +
+                `${JSON.stringify(entry.projection)}.`);
+        }
+        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,
+            projection,
+            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}`}.`;
+/**
+ * @internal Why an `eventTimestamps` value cannot be written for `count`
+ * events — not an array, the wrong length, or an entry that is neither a
+ * valid `DateTime` (finite epoch) nor `undefined` — or `undefined` when it can. `label` opens the
+ * message (`"eventTimestamps has"` / `"eventTimestamps returned"`) and
+ * `events` names the events (`"2 events"` / `"the decision's 2 events"`).
+ */
+const eventTimestampsProblem = (timestamps, count, label, events) => {
+    if (!Array.isArray(timestamps) || timestamps.length !== count) {
+        return (`${label} ${Array.isArray(timestamps) ? timestamps.length : "no"} entries for ${events}: ` +
+            "it needs exactly one entry (a DateTime, or undefined) per event, in order.");
+    }
+    const malformed = timestamps.findIndex((t) => t !== undefined && (!DateTime.isDateTime(t) || !Number.isFinite(DateTime.toEpochMillis(t))));
+    if (malformed === -1)
+        return undefined;
+    const entry = timestamps[malformed];
+    // A DateTime with a NaN epoch (e.g. `setPartsUtc` from a bad parse) passes
+    // `isDateTime` but makes `formatIso` throw, so it is refused here instead.
+    if (DateTime.isDateTime(entry)) {
+        return (`eventTimestamps[${malformed}] is an invalid DateTime (its epoch milliseconds are not a ` +
+            "finite number): each entry must be a valid DateTime, or undefined to keep the append's own time.");
+    }
+    return (`eventTimestamps[${malformed}] is not a DateTime (received ` +
+        `${entry instanceof Date ? "a Date — convert it with DateTime.fromDateUnsafe" : entry === null ? "null" : typeof entry}): ` +
+        "each entry must be a DateTime, or undefined to keep the append's own time.");
+};
 // ---------------------------------------------------------------------------
 // makeStream factory
 // ---------------------------------------------------------------------------
@@ -85,6 +344,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 +358,61 @@ 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}. Each
+ * index's `projection` (default `"all"`) sets what it copies from each event
+ * and how it is read — see {@link StreamIndexProjection}.
+ *
+ * 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`, a `key` that is not a function, a `projection` other than
+ *   `"all"` / `"withoutMetadata"` / `"keys"`, or a member an index entry does
+ *   not declare (such as a misspelled `projection`, also a type error).
+ * @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 +444,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 +453,30 @@ 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,
+            projection: idx.projection,
+        };
+    }
+    /** 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 +491,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 +506,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 +540,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,47 +574,268 @@ export const makeStream = (config) => {
     // ---------------------------------------------------------------------------
     // append
     // ---------------------------------------------------------------------------
+    /**
+     * An event's key in a stream index (#140): a string, or `undefined` to
+     * leave the event out. Another type, or a `key` that throws, is a
+     * `ValidationError`, raised before anything is written. DynamoDB's own
+     * rules on a key — not empty, at most 1024 bytes for a sort key — are not
+     * pre-checked: DynamoDB rejects the append and the rejection is diagnosed,
+     * naming the index and event (see `sendAppendTransaction`).
+     */
+    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.",
+        }));
+        // A string, or the event is not indexed: what the stream's own key
+        // contract means, which DynamoDB cannot see (a number would be sent
+        // as `N`). An empty string is DynamoDB's to reject, and is diagnosed
+        // from its rejection, naming the index and the event (#144).
+        if (typeof derived !== "string") {
+            return refuse(`must be a string or undefined; received ${String(derived)}`);
+        }
+        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) => {
+        const sent = () => ({ _tag: "Transaction", items: tx.items, targets: tx.targets });
+        const diagnosed = (diagnosis, original) => diagnosis._tag === "TooManyItems"
+            ? new AppendTooLarge({
+                streamName: config.streamName,
+                streamId: streamIdStr,
+                count: diagnosis.count,
+                limit: diagnosis.limit,
+                cause: original,
+            })
+            : appendLimitError(diagnosis, original, tx);
+        return client.transactWriteItems({ TransactItems: tx.items }).pipe(Effect.as(undefined), 
+        // One operation per item (#133, #144): diagnosed BEFORE the conditional
+        // mapping below — DynamoDB can report a repeated item as a conditional
+        // failure, which would read as a version conflict or a lost race (and
+        // be retried). Terminal.
+        diagnoseFailure({ sent, only: ["RepeatedItem"], rewrite: diagnosed }), 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,
+            }));
+        }), 
+        // DynamoDB's limits are not pre-checked (#144): a rejection the
+        // conditional mapping above could not explain is diagnosed against the
+        // transaction sent, naming the event, sentinel, snapshot or additional
+        // item at fault. Over 100 items is `AppendTooLarge`, with the EXPANDED
+        // count.
+        diagnoseFailure({
+            sent,
+            keys: () => mergeKeyAttributes({
+                partition: ["pk", ...streamIndexes.map((idx) => idx.pk)],
+                sort: ["sk", ...streamIndexes.map((idx) => idx.sk)],
+            }, tx.additional.keys()),
+            rewrite: diagnosed,
+        }));
+    };
+    /**
+     * A diagnosed rejection of an append (#144) other than its item count. An
+     * over-long (or empty) stream-index sort key OF AN EVENT — the value the
+     * index's `key` function returned — is named by its index and event, as
+     * the `indexes` option reports its other key problems. Only the event puts
+     * carry stream-index keys: an additional item writing the same physical
+     * attribute (single-table designs share `gsi1sk` and the like) is its own
+     * entity's key, and is named as any other item.
+     */
+    const appendLimitError = (diagnosis, original, tx) => {
+        if ((diagnosis._tag === "KeyTooLong" && diagnosis.kind === "sort") ||
+            diagnosis._tag === "EmptyKey") {
+            const position = tx.targets().indexOf(diagnosis.target);
+            const isEvent = position >= tx.guardCount && position < tx.guardCount + tx.eventCount;
+            const idx = isEvent
+                ? streamIndexes.find((candidate) => candidate.sk === diagnosis.attribute)
+                : undefined;
+            if (idx !== undefined) {
+                return new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.indexes",
+                    cause: withCause(`The key of index "${idx.name}" for ${diagnosis.target.source} ` +
+                        (diagnosis._tag === "KeyTooLong"
+                            ? `is ${diagnosis.bytes} bytes, longer than DynamoDB's 1024-byte limit for a ` +
+                                "sort key."
+                            : "is an empty string, which DynamoDB does not accept as a key value; the " +
+                                "key function must return a non-empty string, or undefined to leave the " +
+                                "event out of the index.") +
+                        " DynamoDB rejected the append. Nothing was written.", original),
+                });
+            }
+        }
+        return diagnosedValidationError(diagnosis, original, {
+            operation: "EventStore.append",
+            entityType,
+        });
+    };
     const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
         const additionalOps = options?.additionalItems ?? [];
         const idempotency = options?.idempotency;
+        const snapshotState = options?.snapshot;
+        const eventMetadata = options?.eventMetadata;
+        // Per-event metadata (#144) is checked first — ahead of the no-op fast
+        // path below, which would otherwise accept `append(id, [], v,
+        // { eventMetadata: [m] })` without looking at it.
+        if (eventMetadata !== undefined) {
+            if (options?.metadata !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.eventMetadata",
+                    cause: "metadata and eventMetadata are mutually exclusive: pass one value shared by " +
+                        "every event, or one entry per event. Nothing was written.",
+                });
+            }
+            if (!Array.isArray(eventMetadata) || eventMetadata.length !== events.length) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.eventMetadata",
+                    cause: `eventMetadata has ${Array.isArray(eventMetadata) ? eventMetadata.length : "no"} ` +
+                        `entries for ${events.length} events: it needs exactly one entry (or undefined) ` +
+                        "per event, in order. Nothing was written.",
+                });
+            }
+        }
+        // Per-event timestamps (#144), checked alongside the metadata and for
+        // the same reason: ahead of the no-op fast path.
+        const eventTimestamps = options?.eventTimestamps;
+        if (eventTimestamps !== undefined) {
+            const problem = eventTimestampsProblem(eventTimestamps, events.length, "eventTimestamps has", `${events.length} events`);
+            if (problem !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.eventTimestamps",
+                    cause: `${problem} Nothing was written.`,
+                });
+            }
+        }
+        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);
-        // 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.
-        //
-        // This first check is a LOWER BOUND, counting one item per additional op.
-        // Expansion (uniqueness sentinels, version snapshots — #113) only ever
-        // adds items, so an append that already fails here can never fit, and
-        // 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);
-        if (fixedItems + additionalOps.length > TRANSACT_WRITE_ITEMS_LIMIT) {
-            return yield* new AppendTooLarge({
-                streamName: config.streamName,
-                streamId: streamIdStr,
-                count: fixedItems + additionalOps.length,
-                limit: TRANSACT_WRITE_ITEMS_LIMIT,
+        // 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.`,
             });
         }
+        // DynamoDB's 100-item limit on one transaction is not pre-checked
+        // (#144): an append is never split — splitting would break its
+        // atomicity — so one over the limit is rejected whole by DynamoDB and
+        // reported as `AppendTooLarge`, with the expanded item count.
+        const needsContiguityCheck = expectedVersion > 0 && events.length > 0;
         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;
         const now = DateTime.formatIso(nowDateTime);
-        // Validate and encode metadata to wire form if schema provided
+        // Validate and encode metadata to wire form if schema provided. Shared
+        // by every event; per-event `eventMetadata` is encoded in the loop below.
         let encodedMetadata;
         if (options?.metadata !== undefined && metadataSchema) {
             const encoded = yield* encodeToWire(metadataSchema, options.metadata, "EventStore.append.metadata");
@@ -289,7 +859,25 @@ export const makeStream = (config) => {
             // Inject _tag for plain Schema.Class events; Schema.TaggedClass
             // events already carry _tag in their encoded form, which wins.
             const eventData = { _tag: evtType, ...wire };
-            const item = {
+            // This event's own metadata entry (#144), encoded as `metadata`
+            // is; an `undefined` entry writes no metadata attribute.
+            let itemMetadata = encodedMetadata;
+            if (eventMetadata !== undefined) {
+                const entry = eventMetadata[i];
+                itemMetadata =
+                    entry === undefined
+                        ? undefined
+                        : metadataSchema
+                            ? (yield* encodeToWire(metadataSchema, entry, `EventStore.append.eventMetadata[${i}]`))
+                            : entry;
+            }
+            // This event's own timestamp (#144), or the append's `now`.
+            // `formatIso` renders the UTC instant, so a zoned DateTime is
+            // stored in the same format as `now`.
+            const eventTimestamp = eventTimestamps?.[i];
+            // Exactly the table key and EVENT_ITEM_ATTRIBUTES — what a
+            // "withoutMetadata" stream index projects — checked by the type.
+            const envelope = {
                 pk,
                 sk: composeEventSk(version),
                 __edd_e__: entityType,
@@ -297,10 +885,22 @@ export const makeStream = (config) => {
                 version,
                 eventType: evtType,
                 data: eventData,
-                timestamp: now,
+                timestamp: eventTimestamp === undefined ? now : DateTime.formatIso(eventTimestamp),
             };
-            if (encodedMetadata !== undefined) {
-                item.metadata = encodedMetadata;
+            const item = { ...envelope };
+            if (itemMetadata !== undefined) {
+                item.metadata = itemMetadata;
+            }
+            // 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: {
@@ -310,6 +910,129 @@ export const makeStream = (config) => {
                 },
             };
         }));
+        // The idempotency sentinel: a Put guarded by `attribute_not_exists(pk)`.
+        let sentinelPut;
+        if (idempotency !== undefined) {
+            const sentinel = {
+                pk,
+                sk: composeCommandSk(idempotency.commandId),
+                __edd_e__: commandEntityType,
+                streamId: streamIdStr,
+                commandId: idempotency.commandId,
+                version: expectedVersion + events.length,
+                timestamp: now,
+            };
+            if (idempotency.ttl !== undefined) {
+                const ttlSeconds = yield* Effect.try({
+                    try: () => normalizeTtlSeconds(idempotency.ttl),
+                    catch: (cause) => new ValidationError({
+                        entityType: commandEntityType,
+                        operation: "EventStore.append.idempotency.ttl",
+                        cause,
+                    }),
+                });
+                sentinel[resolveTtlAttributeName(tableConfig)] =
+                    DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
+            }
+            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,
+                    }),
+                },
+            };
+        }
+        /**
+         * 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)",
+                },
+            }
+            : 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 = [];
+            // What names each item, so the targets are built only on failure.
+            const naming = [];
+            const pushStreamItem = (item, type, source) => {
+                items.push(item);
+                naming.push(() => [transactItemTarget(item, tableName, ["pk", "sk"], type, source)]);
+            };
+            if (contiguityCheck !== undefined) {
+                pushStreamItem(contiguityCheck, entityType, "the version-contiguity check");
+            }
+            const guardCount = items.length;
+            for (const [i, item] of eventItems.entries()) {
+                pushStreamItem(item, entityType, `the event at version ${expectedVersion + i + 1}`);
+            }
+            items.push(...additional.items);
+            naming.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");
+            }
+            let targets;
+            return {
+                items,
+                // Built once, on failure: a diagnosis's target is found by identity.
+                targets: () => (targets ??= naming.flatMap((name) => name())),
+                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;
@@ -317,174 +1040,15 @@ export const makeStream = (config) => {
             // 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 additionalItems = additional.items;
-            // 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 guarded put (#133) expands into its item plus its sentinel
-            // reservations and releases plus a snapshot. The 1:1 "item index == caller
-            // index" assumption is gone, so the reason mapping below goes through
-            // `judgeCancellation` — 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 sentinelIndex = idempotency !== undefined ? transactItems.length : -1;
-            if (idempotency !== undefined) {
-                const sentinel = {
-                    pk,
-                    sk: DynamoSchema.composeKey(schema, commandKeyLabel, [idempotency.commandId], keyOptions),
-                    __edd_e__: commandEntityType,
-                    streamId: streamIdStr,
-                    commandId: idempotency.commandId,
-                    version: expectedVersion + events.length,
-                    timestamp: now,
-                };
-                if (idempotency.ttl !== undefined) {
-                    const ttlSeconds = yield* Effect.try({
-                        try: () => normalizeTtlSeconds(idempotency.ttl),
-                        catch: (cause) => new ValidationError({
-                            entityType: commandEntityType,
-                            operation: "EventStore.append.idempotency.ttl",
-                            cause,
-                        }),
-                    });
-                    sentinel[resolveTtlAttributeName(tableConfig)] =
-                        DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
-                }
-                transactItems.push({
-                    Put: {
-                        TableName: tableName,
-                        Item: toAttributeMap(sentinel),
-                        ConditionExpression: "attribute_not_exists(pk)",
-                    },
-                });
-            }
-            // Checked before anything is sent: one op per item — an additional item
-            // repeating an event, the contiguity check or the idempotency sentinel
-            // is refused, as additional items repeating each other are — and the
-            // whole transaction within DynamoDB's 4 MB (#133).
-            const additionalStart = checkCount + eventCount;
-            const streamItemSource = (i) => i < checkCount
-                ? "the version-contiguity check"
-                : i < additionalStart
-                    ? `the event at version ${expectedVersion + i - checkCount + 1}`
-                    : "the idempotency sentinel";
-            const targets = transactItems.map((item, i) => i >= additionalStart && i < additionalStart + additionalItems.length
-                ? additional.targets[i - additionalStart]
-                : transactItemTarget(item, tableName, ["pk", "sk"], entityType, streamItemSource(i)));
-            yield* refuseRepeatedItems(targets, "EventStore.append");
-            yield* refuseOversizedTransaction(transactItems, targets, "EventStore.append");
-            const outcome = yield* client.transactWriteItems({ TransactItems: transactItems }).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 (idempotency !== undefined && failedAt(sentinelIndex)) {
-                    return Effect.fail(new DuplicateCommand({
-                        streamName: config.streamName,
-                        streamId: streamIdStr,
-                        commandId: idempotency.commandId,
-                    }));
-                }
-                // The contiguity ConditionCheck and the event puts both mean "the
-                // stream is not where you said it was", so they share one verdict.
-                for (let i = 0; i < checkCount + eventCount; i++) {
-                    if (failedAt(i)) {
-                        return Effect.fail(new VersionConflict({
-                            streamName: config.streamName,
-                            streamId: streamIdStr,
-                            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(additional, rawReasons, checkCount + 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, or a truncated/absent reason list) — never
-                // guess a VersionConflict.
-                return Effect.fail(new TransactionCancelled({
-                    operation: "TransactWriteItems",
-                    reasons,
-                    cause: error.cause,
-                }));
-            }));
+            const tx = layout(additional);
+            // DynamoDB's rules — one operation per item (an additional item
+            // repeating an event, the contiguity check, the idempotency sentinel
+            // or the inline snapshot, or another additional item), 100 items,
+            // 4 MB, 400 KB per item, 1024-byte sort keys — are not pre-checked:
+            // `sendAppendTransaction` diagnoses DynamoDB's rejection (#144).
+            const outcome = yield* sendAppendTransaction(client, tx, streamIdStr, idempotency?.commandId);
             if (outcome === undefined) {
-                return {
-                    version: expectedVersion + events.length,
-                    events,
-                };
+                return { version: expectedVersion + events.length, events };
             }
             lost = outcome;
         }
@@ -493,37 +1057,49 @@ export const makeStream = (config) => {
     // ---------------------------------------------------------------------------
     // 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
     // ---------------------------------------------------------------------------
@@ -535,11 +1111,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,
@@ -549,8 +1121,7 @@ export const makeStream = (config) => {
             state: encoded,
             timestamp: now,
         };
-        yield* client
-            .putItem({
+        const put = {
             TableName: tableName,
             Item: toAttributeMap(item),
             // Monotonic: never regress the cache. Losing this race is a no-op,
@@ -558,12 +1129,33 @@ export const makeStream = (config) => {
             ConditionExpression: "attribute_not_exists(#pk) OR #asOfVersion < :asOfVersion",
             ExpressionAttributeNames: { "#pk": "pk", "#asOfVersion": "asOfVersion" },
             ExpressionAttributeValues: toAttributeMap({ ":asOfVersion": asOfVersion }),
-        })
-            .pipe(Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.void));
+        };
+        yield* client.putItem(put).pipe(Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.void), 
+        // An oversized snapshot is DynamoDB's to reject (#144); named here.
+        diagnoseFailure({
+            sent: () => ({
+                _tag: "Item",
+                item: { Put: put },
+                target: () => transactItemTarget({ Put: put }, tableName, ["pk", "sk"], snapshotEntityType, "the snapshot"),
+            }),
+            keys: () => ({ partition: ["pk"], sort: ["sk"] }),
+            rewrite: (diagnosis, original) => diagnosedValidationError(diagnosis, original, {
+                operation: "EventStore.writeSnapshot",
+                entityType: snapshotEntityType,
+            }),
+        }));
     });
-    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({
@@ -572,21 +1164,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
@@ -608,8 +1319,118 @@ 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: indexDecoder(idx),
+            resolveTableName: config.table.Tag.useSync((tc) => tc.name),
+            // DynamoDB's rejection of the key condition (an empty bound, a reversed
+            // `between`) is named against the stream index; so, as for every
+            // query, is a consistent read of a GSI (#144).
+            keyConditionDiagnosis: {
+                operation: "EventStore.readIndex",
+                label: `EventStream "${config.streamName}" index "${idx.name}"`,
+            },
+            keyFields: [idx.pk, idx.sk, "pk", "sk"],
+            // A "keys" index holds no events: an LSI has DynamoDB fetch them
+            // (`Select: ALL_ATTRIBUTES`), a GSI fetches each page's with
+            // `BatchGetItem` on the table key.
+            ...(idx.projection === "keys"
+                ? {
+                    hydration: idx.type === "lsi"
+                        ? { _tag: "Fetch" }
+                        : { _tag: "BatchGet", tableKey: ["pk", "sk"] },
+                }
+                : {}),
+        });
+    };
+    /**
+     * @internal The decoder of events read through `idx`.
+     *
+     * - `"withoutMetadata"` ignores any `metadata` on the row (an index deployed
+     *   wider than declared still carries it), so the value matches the type.
+     * - `"all"` / `"withoutMetadata"`: a decode failure on a row that lacks an
+     *   attribute the declared projection guarantees is diagnosed as the
+     *   deployed index projecting less than declared — a `ValidationError`
+     *   (`operation: "EventStore.index.decode"`) naming the index, the original
+     *   error kept as its cause. Anything else passes through unchanged.
+     * - `"keys"` decodes items fetched from the table, so a missing attribute
+     *   there is not a projection problem: failures pass through.
+     */
+    const indexDecoder = (idx) => (raw) => {
+        if (idx.projection === "keys")
+            return decodeStreamEvent(raw);
+        let row = raw;
+        if (idx.projection === "withoutMetadata" && raw.metadata !== undefined) {
+            row = { ...raw };
+            delete row.metadata;
+        }
+        return decodeStreamEvent(row).pipe(Effect.mapError((error) => {
+            const missing = PROJECTED_ENVELOPE_ATTRIBUTES.filter((name) => row[name] === undefined);
+            if (missing.length === 0)
+                return error;
+            return new ValidationError({
+                entityType,
+                operation: "EventStore.index.decode",
+                cause: withCause(`Stream index "${idx.name}" (physical "${idx.index}") is declared ` +
+                    `projection: "${idx.projection}", but its rows lack ${missing.join(", ")}: the ` +
+                    "deployed index likely projects less than declared. Deploy the Projection " +
+                    "EventStore.indexDefinitions emits for it.", error),
+            });
+        }));
+    };
+    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
@@ -628,13 +1449,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,
     };
 };
 // ---------------------------------------------------------------------------
@@ -657,6 +1484,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() {
@@ -666,106 +1495,528 @@ 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)),
     };
 });
+// ---------------------------------------------------------------------------
+// EventStore.indexDefinitions — CreateTable fragments for stream indexes (#140)
+// ---------------------------------------------------------------------------
+/**
+ * @internal The `Projection` a stream index of `projection` is created with.
+ * Neither list names a key attribute: table and index keys are always
+ * projected.
+ */
+const projectionDefinition = (projection) => projection === "all"
+    ? { ProjectionType: "ALL" }
+    : {
+        ProjectionType: "INCLUDE",
+        NonKeyAttributes: projection === "keys" ? ["__edd_e__"] : [...EVENT_ITEM_ATTRIBUTES],
+    };
+/**
+ * Derive the `CreateTable` fragments for the stream indexes (#140) of the given
+ * streams (`EventStream` or `BoundEventStream`) — `AttributeDefinitions`,
+ * `LocalSecondaryIndexes` and `GlobalSecondaryIndexes` — 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.
+ *
+ * Each index's `Projection` follows its {@link StreamIndexProjection}:
+ *
+ * | `projection` | `Projection` |
+ * |---|---|
+ * | `"all"` (default) | `{ ProjectionType: "ALL" }` |
+ * | `"withoutMetadata"` | `{ ProjectionType: "INCLUDE", NonKeyAttributes: ["__edd_e__", "data", "eventType", "streamId", "timestamp", "version"] }` |
+ * | `"keys"` | `{ ProjectionType: "INCLUDE", NonKeyAttributes: ["__edd_e__"] }` — not `KEYS_ONLY`: every read filters on `__edd_e__` |
+ *
+ * The deployed index must project what is declared — copy `Projection` from
+ * this output into CDK or Terraform definitions. Neither an LSI's nor a GSI's
+ * projection can be changed in place, and the library migrates nothing. A
+ * table projects at most 100 `NonKeyAttributes` across all its indexes;
+ * `"withoutMetadata"` spends 6 of them and `"keys"` 1 (DynamoDB refuses a
+ * table over the limit).
+ *
+ * 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.
+ *
+ * @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, other key attributes, or another projection).
+ */
+export const indexDefinitions = (...streams) => {
+    const byIndex = new Map();
+    for (const stream of streams) {
+        for (const [name, raw] of Object.entries(stream.indexes)) {
+            const settings = { ...raw, projection: raw.projection ?? "all" };
+            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,
+                    projection: settings.projection,
+                    owner,
+                });
+                continue;
+            }
+            if (existing.type !== settings.type ||
+                existing.pk !== settings.pk ||
+                existing.sk !== settings.sk ||
+                existing.projection !== settings.projection) {
+                const describe = (s) => `${s.type} (pk "${s.pk}", sk "${s.sk}", projection "${s.projection}")`;
+                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: projectionDefinition(settings.projection),
+        };
+        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 CommandOptionsBase.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 Resolve an `eventMetadata` ({@link CommandMetadataOptions}) against a decision. */
+const deriveEventMetadata = (input, decision) => {
+    if (input === undefined)
+        return Effect.succeed(undefined);
+    const derived = input(decision);
+    return Effect.isEffect(derived) ? derived : Effect.succeed(derived);
+};
+/** @internal Resolve a {@link CommandOptionsBase.eventTimestamps} against a decision. */
+const deriveEventTimestamps = (input, decision) => {
+    if (input === undefined)
+        return Effect.succeed(undefined);
+    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;
+            }
+            const events = yield* stream.read(streamId, readOptions);
+            for (const event of events) {
+                state = decider.evolve(state, event.data);
             }
-            // 2. Decide
-            const newEvents = yield* decider.decide(command, state);
-            // 3. No-op command — return current state
+            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;
+            }
+            // 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 per-event metadata, then per-event
+            //    timestamps, then items, from the decision — in that order
+            //    (#144). Re-run on every attempt (and on a re-decision), because
+            //    the whole cycle is the retried unit.
+            const decision = {
+                events: newEvents,
+                state: next,
+                previous,
+                version: baseVersion,
+            };
+            const eventMetadata = yield* deriveEventMetadata(callOptions?.eventMetadata, decision);
+            // A supplied function must return the array — `undefined` (e.g. a
+            // block body with no `return`) is refused, not silently dropped.
+            if (callOptions?.eventMetadata !== undefined &&
+                (!Array.isArray(eventMetadata) || eventMetadata.length !== newEvents.length)) {
+                return yield* new ValidationError({
+                    entityType: stream.streamName,
+                    operation: "EventStore.commandHandler.eventMetadata",
+                    cause: `eventMetadata returned ${Array.isArray(eventMetadata) ? eventMetadata.length : "no"} ` +
+                        `entries for the decision's ${newEvents.length} events: it must return exactly ` +
+                        "one entry (or undefined) per event, in order. Nothing was written.",
+                });
             }
-            // 4. Append with optimistic concurrency, plus any caller-owned items and
-            //    the dedup sentinel, all in one transaction.
+            // A function (checked before the load), returning the array or an
+            // `Effect` of it; the result of either form is checked here, so the
+            // error names the handler's option rather than `append`'s.
+            const eventTimestamps = yield* deriveEventTimestamps(callOptions?.eventTimestamps, decision);
+            if (callOptions?.eventTimestamps !== undefined) {
+                const problem = eventTimestampsProblem(eventTimestamps, newEvents.length, "eventTimestamps returned", `the decision's ${newEvents.length} events`);
+                if (problem !== undefined) {
+                    return yield* new ValidationError({
+                        entityType: stream.streamName,
+                        operation: "EventStore.commandHandler.eventTimestamps",
+                        cause: `${problem} Nothing was written.`,
+                    });
+                }
+            }
+            const additionalItems = yield* deriveAdditionalItems(callOptions?.additionalItems, decision);
+            // 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 (eventMetadata !== undefined)
+                appendOptions.eventMetadata = eventMetadata;
+            if (eventTimestamps !== undefined)
+                appendOptions.eventTimestamps = eventTimestamps;
+            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;
+        });
+        // 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,
+            });
         });
-        return schedule === undefined
+        // 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`.",
+                });
+            }
+            // The same backstop for the exclusive metadata pair (#144), and for an
+            // `eventMetadata` or `eventTimestamps` that is not the function it must
+            // be — refused before anything is read, rather than by `append` after
+            // `decide`.
+            if (callOptions?.eventMetadata !== undefined) {
+                if (callOptions.metadata !== undefined) {
+                    return yield* new ValidationError({
+                        entityType: stream.streamName,
+                        operation: "EventStore.commandHandler.eventMetadata",
+                        cause: "metadata and eventMetadata are mutually exclusive: pass one value shared by " +
+                            "every event, or a function deriving one entry per event. Nothing was written.",
+                    });
+                }
+                if (typeof callOptions.eventMetadata !== "function") {
+                    return yield* new ValidationError({
+                        entityType: stream.streamName,
+                        operation: "EventStore.commandHandler.eventMetadata",
+                        cause: "eventMetadata must be a function of the decision: the number of events is " +
+                            "known only once `decide` has run. Nothing was written.",
+                    });
+                }
+            }
+            if (callOptions?.eventTimestamps !== undefined &&
+                typeof callOptions.eventTimestamps !== "function") {
+                return yield* new ValidationError({
+                    entityType: stream.streamName,
+                    operation: "EventStore.commandHandler.eventTimestamps",
+                    cause: "eventTimestamps must be a function of the decision: the number of events is " +
+                        "known only once `decide` has run. Nothing was written.",
+                });
+            }
+            // 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
@@ -805,12 +2056,69 @@ 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 })],
+ * })
+ *
+ * // Per-event metadata derived from the decision: entry i is written onto event i
+ * // (`crypto` is the `Crypto.Crypto` service; `randomUUIDv7` works the same way)
+ * yield* handle({ matchId: "m-1" }, command, {
+ *   eventMetadata: ({ events }) =>
+ *     Effect.forEach(events, () => Effect.map(crypto.randomULID, (eventId) => ({ eventId }))),
+ * })
+ *
+ * // Per-event timestamps derived from the decision (undefined → the Clock time)
+ * yield* handle({ matchId: "m-1" }, command, {
+ *   eventTimestamps: ({ events }) => events.map((event) => event.occurredAt),
+ * })
+ *
+ * // ...or from a service, as an Effect (its errors / requirements join the handler's)
+ * yield* handle({ matchId: "m-1" }, command, {
+ *   eventTimestamps: ({ events }) =>
+ *     Effect.forEach(events, (event) => SourceLog.originalTime(event.sourceId)),
+ * })
  * ```
  *
- * 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 CommandOptionsBase.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 is rejected whole by DynamoDB and fails with
+ *   `AppendTooLarge` — nothing 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.