effect-dynamodb 1.22.0 → 1.24.0

package/dist/EventStore.d.ts

@@ -4,17 +4,25 @@
  * Provides:
  * - `Decider` type for command-event-state modeling
  * - `makeStream` factory for creating event streams bound to a Table
- * - Core operations: `append`, `read`, `readFrom`, `currentVersion`
- * - Snapshot primitives: `writeSnapshot`, `readSnapshot`
- * - `commandHandler` combinator for read-decide-append cycle (snapshot-aware,
- *   with an optional `VersionConflict` retry policy)
+ * - Core operations: `append` (atomic), `read`, `readFrom`, `currentVersion`,
+ *   `readLatest` (reads optionally strongly consistent)
+ * - Snapshot primitives: `writeSnapshot`, `readSnapshot`, and inline snapshots
+ *   written in the append transaction (`AppendOptions.snapshot`)
+ * - `commandHandler` combinator for the load-decide-fold-append cycle
+ *   (snapshot-aware single-request loads, consistent loads, an optional
+ *   `VersionConflict` retry policy, caller-supplied `expectedVersion`,
+ *   decision-derived `additionalItems`, inline snapshots)
+ * - Stream indexes (`makeStream({ indexes })`): sub-streams ordered by a key
+ *   derived from each event, on an LSI or GSI — `readIndex`, `query.index`,
+ *   and `indexDefinitions` for the `CreateTable` fragments
  * - `fold` / `foldFrom` helpers for state reconstruction
  *
  * Built on the existing library primitives (DynamoSchema, KeyComposer, Query,
  * DynamoClient, Marshaller).
  */
+import type { AttributeDefinition, GlobalSecondaryIndex, LocalSecondaryIndex } from "@aws-sdk/client-dynamodb";
 import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.js";
-import { AdditionalItemConditionFailed, AppendTooLarge, DuplicateCommand, TransactionCancelled, ValidationError, VersionConflict } from "@effect-dynamodb/schema/Errors.js";
+import { AdditionalItemConditionFailed, AppendTooLarge, type ConcurrentModification, DuplicateCommand, type OptimisticLockError, TransactionCancelled, type UniqueConstraintViolation, ValidationError, VersionConflict } from "@effect-dynamodb/schema/Errors.js";
 import { type Duration, Effect, Option, Pipeable, Schedule, Schema } from "effect";
 import { DynamoClient, type DynamoClientError } from "./DynamoClient.js";
 import { type TransactWriteOp } from "./internal/TransactWriteOps.js";
@@ -24,8 +32,13 @@ import { type Table, type TableConfig } from "./Table.js";
  * A Decider encodes the command-event-state triad for an aggregate.
  *
  * - `decide` — given a command and current state, produce events (or fail with E)
- * - `evolve` — pure left fold: apply one event to a state
- * - `initialState` — starting state for a new aggregate
+ * - `evolve` — left fold: apply one event to a state. It may return new state or
+ *   mutate the given state in place and return it; the library requires
+ *   neither. State the library persists, returns or projects is always this
+ *   fold, never anything produced inside `decide`.
+ * - `initialState` — starting state for a new aggregate. An `evolve` that
+ *   mutates in place must not mutate a shared `initialState` object (declare it
+ *   as a getter that returns a fresh value).
  */
 export interface Decider<State, Command, Event, E = never> {
     readonly decide: (command: Command, state: State) => Effect.Effect<ReadonlyArray<Event>, E>;
@@ -80,16 +93,52 @@ export interface Snapshot<State> {
  * - `schema` — the state codec. Snapshot state round-trips through it
  *   (`Schema.encodeUnknownEffect` on write, `Schema.decodeUnknownEffect` on
  *   read), so transforming schemas work.
- * - `every` — optional auto-snapshot cadence for {@link commandHandler}: after a
- *   successful append, write a fresh snapshot once at least this many events
- *   have accumulated since the last one. Must be a positive integer.
+ * - `mode` — how {@link commandHandler} writes snapshots (see
+ *   {@link SnapshotMode}). Default `"after-append"`.
+ * - `every` — optional snapshot cadence for {@link commandHandler}: write a
+ *   fresh snapshot once at least this many events have accumulated since the
+ *   last one. Must be a positive integer. With `mode: "after-append"` and no
+ *   `every`, the handler never snapshots; with `mode: "inline"` and no `every`,
+ *   it snapshots on every append.
+ *
+ * `every` also sizes the first page of {@link EventStream.readLatest}, which
+ * {@link commandHandler} loads state with: a snapshot that lags the head by up
+ * to `every` events still loads in one request. The first page is read whatever
+ * the actual lag, so every load reads up to `every + 1` items (`2` without
+ * `every`), including events the snapshot already covers, which are discarded.
+ * For an `"after-append"` stream that trades read capacity for requests: with
+ * `every: 100` and a snapshot one event behind, a load reads the snapshot and
+ * 100 events in one request, where a `GetItem` plus `readFrom` would read the
+ * snapshot and one event in two. Size `every` with that in mind, or use
+ * `mode: "inline"`, which keeps the snapshot current so the page stays small.
  */
 export interface SnapshotConfig<TSchema extends Schema.Top = Schema.Top> {
+    /**
+     * The state schema. Snapshot state is encoded through it, falling back to
+     * `decode → encode` (as events are) for a value not already in its type
+     * shape — so a `Schema.Class` state folded by an immutable `evolve` that
+     * spreads (`({ ...s, balance })`, a plain object) still encodes.
+     */
     readonly schema: TSchema;
+    readonly mode?: SnapshotMode | undefined;
     readonly every?: number | undefined;
 }
+/**
+ * How {@link commandHandler} writes snapshots.
+ *
+ * - `"after-append"` (default) — a best-effort `writeSnapshot` after the append
+ *   succeeds, at the `every` cadence. A failed snapshot write never fails the
+ *   command; the snapshot simply lags until the next threshold crossing.
+ * - `"inline"` — the snapshot `Put` rides in the append's own transaction (see
+ *   {@link AppendOptions.snapshot}), on every append, or at the `every` cadence
+ *   when one is set. The snapshot is then current after every command that
+ *   writes one, so {@link EventStream.readLatest} loads state in one request.
+ *   The snapshot counts towards the transaction's item and size limits.
+ */
+export type SnapshotMode = "after-append" | "inline";
 /** The runtime snapshot settings exposed on a stream. */
 export interface SnapshotSettings {
+    readonly mode: SnapshotMode;
     readonly every: number | undefined;
 }
 /**
@@ -100,6 +149,12 @@ export interface SnapshotSettings {
  * `commandId` therefore cancels the whole transaction and surfaces as
  * `DuplicateCommand` — the events are never written twice.
  *
+ * The sentinel is consulted only by an append. Through `commandHandler`, a
+ * redelivery whose `decide` returns no events against the loaded state never
+ * appends, so it succeeds as a no-op instead of failing with
+ * `DuplicateCommand`. Whether a no-op redelivery needs to be told apart is the
+ * application's call (see {@link CommandOptions.commandId}).
+ *
  * The sentinel is co-located in the stream's own partition, so `commandId`
  * uniqueness is scoped to the stream (which is what "have I already applied this
  * command to this aggregate?" asks). It is invisible to `read` / `readFrom` /
@@ -122,8 +177,13 @@ export interface AppendIdempotency {
      */
     readonly ttl?: Duration.Duration | string;
 }
-/** Options accepted by {@link EventStream.append}. */
-export interface AppendOptions<TMetadata> {
+/**
+ * Options accepted by {@link EventStream.append}.
+ *
+ * `TState` is the stream's snapshot state type (`never` for a stream without a
+ * `snapshot` config, so `snapshot` cannot be supplied there).
+ */
+export interface AppendOptions<TMetadata, TState = never> {
     /** Per-append metadata, validated against the stream's metadata schema when configured. */
     readonly metadata?: TMetadata;
     /**
@@ -131,16 +191,215 @@ export interface AppendOptions<TMetadata> {
      * op union `Transaction.transactWrite` accepts (`EntityPut`, `EntityDelete`,
      * `Transaction.check(...)`).
      *
-     * Conditional failures on these items are reported as
-     * `AdditionalItemConditionFailed` (carrying the 0-based indices into this
-     * array), never as `VersionConflict`.
+     * A put of a versioned or unique-constrained entity is written exactly as
+     * the entity's own `put` writes it (#133) — reading the item, continuing a
+     * replaced item's version and history, rotating its sentinels — and an
+     * append whose read raced a concurrent write is written again.
+     *
+     * A failure of an item's OWN condition (`.condition()`, `create()`,
+     * `Transaction.check`) is reported as `AdditionalItemConditionFailed`
+     * (carrying the 0-based indices into this array), never as
+     * `VersionConflict`. A guarded put the caller set no condition on fails as
+     * the entity's put would: `UniqueConstraintViolation`, a history
+     * `ValidationError`, or — a race lost on every attempt —
+     * `OptimisticLockError` / `ConcurrentModification`.
      */
     readonly additionalItems?: ReadonlyArray<TransactWriteOp>;
     /** Opt in to exactly-once command processing — see {@link AppendIdempotency}. */
     readonly idempotency?: AppendIdempotency;
+    /**
+     * An inline snapshot: the stream's state as of this append's last event.
+     *
+     * The snapshot `Put` (`asOfVersion` = `expectedVersion + events.length`,
+     * encoded through the state schema) joins the **same transaction** as the
+     * events, after the idempotency sentinel, so it commits if and only if the
+     * events do. The `Put` is unconditional: the event puts already prove this
+     * writer owns `asOfVersion`, so it cannot regress the snapshot. It counts
+     * towards the item and size limits, and a cancellation reason at its
+     * position (throttling, for example) reports `TransactionCancelled`.
+     *
+     * `undefined` means no snapshot. Requires at least one event — with none,
+     * nothing proves the writer owns the version, and the append fails with
+     * `ValidationError`. On a stream without a `snapshot` config (where the type
+     * is `never`) it dies with `[EDD-9026]`, as `writeSnapshot` does.
+     */
+    readonly snapshot?: TState;
 }
 /** Error channel of {@link EventStream.append}. */
-export type AppendError = VersionConflict | DuplicateCommand | AdditionalItemConditionFailed | AppendTooLarge | DynamoClientError | ValidationError | TransactionCancelled;
+export type AppendError = VersionConflict | DuplicateCommand | AdditionalItemConditionFailed | AppendTooLarge | DynamoClientError | ValidationError | TransactionCancelled | UniqueConstraintViolation | OptimisticLockError | ConcurrentModification;
+/**
+ * Options accepted by {@link EventStream.read}, {@link EventStream.readFrom} and
+ * {@link EventStream.currentVersion}.
+ *
+ * `consistentRead: true` sets `ConsistentRead` on every `Query` page, so the
+ * read observes every append acknowledged before it started (read-your-writes).
+ * Default `false`: eventually consistent, at half the read cost.
+ *
+ * {@link commandHandler} loads state with strongly consistent reads by default —
+ * see {@link CommandHandlerOptions.consistentRead}.
+ */
+export interface ReadOptions {
+    readonly consistentRead?: boolean | undefined;
+}
+/**
+ * Options accepted by {@link EventStream.readLatest}: {@link ReadOptions} plus
+ * `verifySnapshot`.
+ *
+ * - `verifySnapshot` — default `true`: one `Query` reads the snapshot and the
+ *   events after it, so the result is verified against the stream head.
+ *   `false` reads **only the snapshot item**, with one `GetItem` (consistent
+ *   per `consistentRead`), and returns
+ *   `{ snapshot, events: [], version: snapshot.asOfVersion }` **without
+ *   checking that no event follows it** — `version` is then the snapshot's
+ *   version, not a verified head. When there is no snapshot item, it falls
+ *   back to the verified read and returns that result.
+ *
+ *   Why: a `Query`'s read capacity counts every item it reads, and the
+ *   verified read's first page is the snapshot **plus** the newest event,
+ *   even when the snapshot is current; a `GetItem` reads the snapshot alone.
+ *   With large events that roughly halves the read capacity of a load.
+ *
+ *   Only a stream whose snapshot config is `mode: "inline"` **without**
+ *   `every` (the only mode that writes the snapshot in every append, so it is
+ *   normally at the head) accepts `false`; any other snapshot config dies with
+ *   `[EDD-9068]`. On a stream without a `snapshot` config the option is
+ *   ignored. {@link commandHandler} exposes the same trade-off, with
+ *   automatic fallbacks, as {@link CommandHandlerOptions.verifySnapshot}.
+ */
+export interface ReadLatestOptions extends ReadOptions {
+    readonly verifySnapshot?: boolean | undefined;
+}
+/**
+ * A stream's latest state as {@link EventStream.readLatest} loads it.
+ *
+ * - `snapshot` — the stream's snapshot, if one exists (always `None` on a
+ *   stream without a `snapshot` config).
+ * - `events` — the events after the snapshot (every event when there is
+ *   none), ascending by version. Fold them onto the snapshot's state.
+ * - `version` — the stream head: the newest event's version, the snapshot's
+ *   `asOfVersion` when no event follows it, `0` for an empty stream. With
+ *   `verifySnapshot: false` (see {@link ReadLatestOptions}) and a snapshot
+ *   present, it is the snapshot's `asOfVersion` and `events` is empty —
+ *   **unverified**: events appended without a snapshot (a raw `append`, data
+ *   written before `mode: "inline"`) may follow it.
+ */
+export interface LatestState<TState, TEvent, M = Record<string, unknown> | undefined> {
+    readonly snapshot: Option.Option<Snapshot<TState>>;
+    readonly events: ReadonlyArray<StreamEvent<TEvent, M>>;
+    readonly version: number;
+}
+/**
+ * Derives an event's key in a stream index from the domain event (before it is
+ * encoded) and the version it is appended at.
+ *
+ * - A string is the event's sort key in the index. It is stored **raw**: no
+ *   casing and no prefixing is applied, so compose it to sort the way you
+ *   query (zero-pad numbers, for example).
+ * - `undefined` leaves the event out of the index (a sparse index).
+ * - An empty string (or any other value) fails the append with
+ *   `ValidationError` before anything is written — DynamoDB rejects empty key
+ *   values. So do a key over DynamoDB's 1024-byte sort-key limit and a `key`
+ *   that throws.
+ *
+ * The key is derived only when an event is appended. Events are never
+ * rewritten, so changing `key` later leaves events already stored under their
+ * old keys (or out of the index), and declaring an index on a stream that
+ * already holds events indexes only the events appended from then on. The
+ * library does not backfill: re-deriving and writing the index attributes on
+ * existing events is the application's decision (see `indexes` on
+ * {@link makeStream}).
+ */
+export type StreamIndexKey<TEvent> = (event: TEvent, version: number) => string | undefined;
+/**
+ * A stream index on a **local** secondary index (the default `type`). An LSI
+ * shares the table's partition key (`pk`), so its items are exactly the
+ * stream's indexed events, readable with strongly consistent reads.
+ *
+ * - `index` — the physical LSI name.
+ * - `sk` — the attribute carrying the derived key (the LSI's sort key).
+ * - `key` — see {@link StreamIndexKey}.
+ *
+ * An LSI must be created with the table. A table with any LSI caps the item
+ * collection of **every** partition key value in it at 10 GB — not only the
+ * indexed stream's partitions, but every stream's (indexed or not) and every
+ * entity partition sharing the table; a write that would exceed it fails. Its
+ * projection must be `ALL`, because events are decoded from the index item —
+ * see {@link indexDefinitions}.
+ */
+export interface LocalStreamIndexConfig<TEvent> {
+    readonly type?: "lsi" | undefined;
+    readonly index: string;
+    readonly sk: string;
+    /** An LSI uses the table partition key; supplying `pk` is refused (`[EDD-9063]`). */
+    readonly pk?: undefined;
+    readonly key: StreamIndexKey<TEvent>;
+}
+/**
+ * A stream index on a **global** secondary index. `append` writes the stream's
+ * partition key value into the `pk` attribute of each indexed event, so the
+ * index is scoped to the same stream: the eventually consistent equivalent of
+ * an LSI, without the LSI's 10 GB item-collection cap. A strongly consistent
+ * read of it is refused with `ValidationError`.
+ *
+ * Unlike an LSI, the GSI itself can be added to an existing table
+ * (`UpdateTable`), but that does not index the stream's existing events: the
+ * index attributes are written only by `append`, so only events appended after
+ * the index is declared are in it — see {@link StreamIndexKey}.
+ *
+ * - `index` — the physical GSI name.
+ * - `pk` — the attribute carrying the stream's partition key (the GSI's HASH key).
+ * - `sk` — the attribute carrying the derived key (the GSI's RANGE key).
+ * - `key` — see {@link StreamIndexKey}.
+ */
+export interface GlobalStreamIndexConfig<TEvent> {
+    readonly type: "gsi";
+    readonly index: string;
+    readonly pk: string;
+    readonly sk: string;
+    readonly key: StreamIndexKey<TEvent>;
+}
+/**
+ * One entry of `makeStream({ indexes })`: a sub-stream of the stream's events,
+ * ordered by a key derived from each event. See {@link LocalStreamIndexConfig}
+ * and {@link GlobalStreamIndexConfig}.
+ */
+export type StreamIndexConfig<TEvent> = LocalStreamIndexConfig<TEvent> | GlobalStreamIndexConfig<TEvent>;
+/**
+ * The runtime settings of one stream index, as exposed on
+ * {@link EventStream.indexes}. `pk` is the index's partition key attribute:
+ * the table's `pk` for an LSI, the configured attribute for a GSI.
+ */
+export interface StreamIndexSettings {
+    readonly type: "lsi" | "gsi";
+    readonly index: string;
+    readonly pk: string;
+    readonly sk: string;
+}
+/**
+ * Options accepted by {@link EventStream.readIndex}.
+ *
+ * - `beginsWith` / `between` — a sort-key condition on the derived key (at most
+ *   one of them). Omitted, the whole sub-stream is read. Each bound must be a
+ *   non-empty string, and `between`'s lower bound must not sort (by UTF-8
+ *   bytes, as DynamoDB sorts) after its upper bound; otherwise the read fails
+ *   with `ValidationError` before anything is sent.
+ * - `reverse` — descending key order.
+ * - `limit` — return at most this many events (a positive integer).
+ * - `consistentRead` — strongly consistent read. Refused with
+ *   `ValidationError` on a GSI-backed index, which DynamoDB reads only
+ *   eventually consistently.
+ */
+export type ReadIndexOptions = {
+    readonly reverse?: boolean | undefined;
+    readonly limit?: number | undefined;
+    readonly consistentRead?: boolean | undefined;
+} & ({
+    readonly beginsWith?: string | undefined;
+    readonly between?: undefined;
+} | {
+    readonly between?: readonly [string, string] | undefined;
+    readonly beginsWith?: undefined;
+});
 type StreamIdInput<T extends ReadonlyArray<string>> = {
     readonly [K in T[number]]: string;
 };
@@ -151,14 +410,28 @@ export type EventStreamTypeId = typeof EventStreamTypeId;
  *
  * Created via {@link makeStream}. Operations are called directly on the stream:
  * `MatchEvents.append(...)`, `MatchEvents.read(...)`, `MatchEvents.query.events(...)`.
+ *
+ * `TIndexName` is the union of the stream's index names (`makeStream({ indexes })`),
+ * `never` for a stream without indexes, so {@link EventStream.readIndex} and
+ * `query.index` only accept a declared name.
  */
-export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState = never> extends Pipeable.Pipeable {
+export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState = never, TIndexName extends string = never> extends Pipeable.Pipeable {
     readonly [EventStreamTypeId]: EventStreamTypeId;
     readonly streamName: string;
     readonly eventSchema: Schema.Top;
+    /**
+     * The stream's indexes (`makeStream({ indexes })`) by name — their physical
+     * index and key attributes. Empty for a stream without indexes.
+     * {@link indexDefinitions} derives `CreateTable` fragments from it.
+     */
+    readonly indexes: {
+        readonly [K in TIndexName]: StreamIndexSettings;
+    };
     /**
      * Present iff the stream was created with a `snapshot` config. Its presence
-     * is what switches {@link commandHandler} onto the snapshot-aware read path.
+     * is what switches {@link commandHandler} onto the snapshot-aware read path
+     * ({@link EventStream.readLatest}); its `mode` decides how the handler writes
+     * snapshots.
      */
     readonly snapshotConfig: SnapshotSettings | undefined;
     /**
@@ -187,12 +460,77 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
      * hide state-schema evolution bugs.
      */
     readSnapshot(streamId: StreamIdInput<TStreamIdFields>): Effect.Effect<Option.Option<Snapshot<TState>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
-    append(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: AppendOptions<TMetadata> | undefined): Effect.Effect<AppendResult<TEvent>, AppendError, DynamoClient | TableConfig>;
-    read(streamId: StreamIdInput<TStreamIdFields>): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
-    readFrom(streamId: StreamIdInput<TStreamIdFields>, afterVersion: number): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
-    currentVersion(streamId: StreamIdInput<TStreamIdFields>): Effect.Effect<number, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    /**
+     * Append `events` after `expectedVersion`, atomically, in one transaction —
+     * see {@link AppendOptions}.
+     * A method, like `writeSnapshot`, so a snapshot-less stream (whose
+     * `options.snapshot` is `never`) stays assignable to other streams.
+     */
+    append(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: AppendOptions<TMetadata, TState> | undefined): Effect.Effect<AppendResult<TEvent>, AppendError, DynamoClient | TableConfig>;
+    /**
+     * Read every event of the stream, ascending by version. Pass
+     * `{ consistentRead: true }` for read-your-writes — see {@link ReadOptions}.
+     */
+    read(streamId: StreamIdInput<TStreamIdFields>, options?: ReadOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    /**
+     * Read the events after `afterVersion` (exclusive), ascending. Pass
+     * `{ consistentRead: true }` for read-your-writes — see {@link ReadOptions}.
+     */
+    readFrom(streamId: StreamIdInput<TStreamIdFields>, afterVersion: number, options?: ReadOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    /**
+     * The version of the stream's newest event (`0` for an empty stream), in one
+     * request. Pass `{ consistentRead: true }` for read-your-writes — see
+     * {@link ReadOptions}.
+     */
+    currentVersion(streamId: StreamIdInput<TStreamIdFields>, options?: ReadOptions | undefined): Effect.Effect<number, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    /**
+     * The stream's snapshot (if any), the events after it, and its head — in
+     * **one request** in steady state. This is how {@link commandHandler} loads
+     * state on a snapshot-configured stream.
+     *
+     * Issues a single reverse `Query` over the sort-key range from the first
+     * event to the snapshot (the snapshot sorts after every event, and the
+     * idempotency sentinels before them, so the range holds exactly the events
+     * and the snapshot), with a first page of `(every ?? 1) + 1` items. Further
+     * pages are read only while the snapshot's `asOfVersion` has not been reached
+     * (a snapshot lagging by more than `every` events) — each sized to the events
+     * still missing, so a lagging snapshot costs one more request — or to the
+     * start of the stream when there is no snapshot. Pass
+     * `{ consistentRead: true }` for read-your-writes; it applies to the snapshot
+     * and the events alike.
+     *
+     * A snapshot that fails to decode through the state schema fails with
+     * `ValidationError`, as {@link EventStream.readSnapshot} does. On a stream
+     * without a `snapshot` config it is {@link EventStream.read} plus the head.
+     *
+     * `{ verifySnapshot: false }` reads only the snapshot item, with one
+     * `GetItem`, and returns it with no events and its `asOfVersion` as an
+     * **unverified** `version`; with no snapshot item it falls back to the
+     * verified read. Accepted only on a `mode: "inline"` stream without `every`
+     * (otherwise a defect, `[EDD-9068]`), ignored on a stream without a
+     * `snapshot` config — see {@link ReadLatestOptions}.
+     */
+    readLatest(streamId: StreamIdInput<TStreamIdFields>, options?: ReadLatestOptions | undefined): Effect.Effect<LatestState<TState, TEvent, StreamMetadata<TMetadata>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    /**
+     * Read the stream's events in the order of one of its indexes (#140) — the
+     * events whose index `key` returned a string, ordered by that key. A
+     * convenience over `query.index`; pass `beginsWith` or `between` to narrow
+     * the key range, `reverse`, `limit` and `consistentRead` (refused on a GSI)
+     * — see {@link ReadIndexOptions}.
+     */
+    readIndex(name: TIndexName, streamId: StreamIdInput<TStreamIdFields>, options?: ReadIndexOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
     readonly query: {
         events(streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, StreamMetadata<TMetadata>>>;
+        /**
+         * A query of one of the stream's indexes (#140), scoped to `streamId`:
+         * decoded events in index-key order. It composes with the `Query`
+         * combinators — `Query.where` (a condition on the derived key),
+         * `Query.reverse`, `Query.limit`, `Query.consistentRead` (refused with
+         * `ValidationError` on a GSI-backed index) — and terminals
+         * (`Query.collect`, `Query.execute`, `Query.paginate`). The
+         * `__edd_e__ = <stream>.event` filter still applies.
+         */
+        index(name: TIndexName, streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, StreamMetadata<TMetadata>>>;
     };
 }
 /**
@@ -235,6 +573,10 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  * })
  * ```
  *
+ * `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
@@ -245,11 +587,61 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  * (`<stream>.event` etc.) are always lower-cased. In the next major, omitting
  * `casing` will mean the schema's casing, as it does for indexes.
  *
+ * `indexes` declares sub-streams ordered by a key derived from each event
+ * (#140), on a local (default) or global secondary index. `append` writes each
+ * event's derived key (and, for a GSI, the stream's partition key) on the
+ * event item; snapshots and idempotency sentinels never carry them, so they
+ * are never in an index. Read with {@link EventStream.readIndex} or
+ * `query.index`, and create the indexes with {@link indexDefinitions}.
+ *
+ * Index attributes are written only at append time and events are never
+ * rewritten. Declaring an index on a stream that already holds events, or
+ * changing an index's `key`, therefore leaves the earlier events out of the
+ * index (or under their old keys), and `readIndex` returns only what was
+ * indexed — without an error. The library does not backfill; whether and how
+ * to re-index existing events (for example, an `UpdateItem` per event setting
+ * the derived attributes) is the application's decision.
+ *
+ * @example
+ * ```typescript
+ * const Entries = EventStore.makeStream({
+ *   table: EventsTable,
+ *   streamName: "Ledger",
+ *   events: [EntryRecorded, EntryVoided],
+ *   streamId: { composite: ["ledgerId"] },
+ *   indexes: {
+ *     byEntry: {
+ *       index: "lsi1",
+ *       sk: "lsi1sk",
+ *       key: (event, version) =>
+ *         event._tag === "EntryRecorded" ? `ENTRY#${event.section}#${pad(version)}` : undefined,
+ *     },
+ *     // Every event, by the day it was recorded (both event types carry `day`).
+ *     byDay: { type: "gsi", index: "gsi1", pk: "gsi1pk", sk: "gsi1sk", key: (e) => e.day },
+ *   },
+ * })
+ *
+ * const sectionThree = yield* Entries.readIndex("byEntry", { ledgerId }, { beginsWith: "ENTRY#3#" })
+ * ```
+ *
  * @throws `[EDD-9027]` when `snapshot.every` is not a positive integer.
+ * @throws `[EDD-9062]` when `snapshot.mode` is neither `"after-append"` nor
+ *   `"inline"`.
+ * @throws `[EDD-9063]` for a malformed index: a `type` other than `"lsi"` /
+ *   `"gsi"`, a `gsi` without `pk`, an `lsi` with `pk`, an empty `index` / `sk`
+ *   / `pk`, or a `key` that is not a function.
+ * @throws `[EDD-9064]` when an index attribute is one the stream writes itself
+ *   (`pk`, `sk`, `__edd_e__`, `streamId`, `version`, `eventType`, `data`,
+ *   `metadata`, `timestamp`, `asOfVersion`, `state`, `commandId`, or the
+ *   default TTL attribute `_ttl`). A custom `TableConfig.ttlAttributeName`
+ *   is only known at runtime: an index attribute equal to it fails each append
+ *   with `ValidationError`.
+ * @throws `[EDD-9065]` when two indexes share a physical index name or an
+ *   attribute (or a GSI's `pk` and `sk` are the same attribute).
  */
 export declare const makeStream: <const TEvents extends ReadonlyArray<Schema.Top>, TTable extends Table, const TStreamName extends string, const TStreamId extends {
     readonly composite: ReadonlyArray<string>;
-}, TMetadata extends Schema.Top | undefined = undefined, TSnapshot extends SnapshotConfig | undefined = undefined>(config: {
+}, TMetadata extends Schema.Top | undefined = undefined, TSnapshot extends SnapshotConfig | undefined = undefined, const TIndexName extends string = never>(config: {
     readonly table: TTable;
     readonly streamName: TStreamName;
     readonly events: TEvents;
@@ -257,7 +649,8 @@ export declare const makeStream: <const TEvents extends ReadonlyArray<Schema.Top
     readonly metadata?: TMetadata;
     readonly snapshot?: TSnapshot;
     readonly casing?: DynamoSchema.Casing | undefined;
-}) => EventStream<Schema.Schema.Type<TEvents[number]>, TStreamId["composite"], TMetadata extends Schema.Top ? Schema.Schema.Type<TMetadata> : undefined, TSnapshot extends SnapshotConfig<infer TStateSchema> ? Schema.Schema.Type<TStateSchema> : never>;
+    readonly indexes?: { readonly [K in TIndexName]: StreamIndexConfig<Schema.Schema.Type<TEvents[number]>>; };
+}) => EventStream<Schema.Schema.Type<TEvents[number]>, TStreamId["composite"], TMetadata extends Schema.Top ? Schema.Schema.Type<TMetadata> : undefined, TSnapshot extends SnapshotConfig<infer TStateSchema> ? Schema.Schema.Type<TStateSchema> : never, TIndexName>;
 /**
  * An EventStream whose operations have `DynamoClient` and `TableConfig` already
  * resolved, so all methods return `Effect<A, E, never>`.
@@ -278,22 +671,40 @@ export declare const makeStream: <const TEvents extends ReadonlyArray<Schema.Top
  * }) {}
  * ```
  */
-export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState = never> extends Pipeable.Pipeable {
+export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState = never, TIndexName extends string = never> extends Pipeable.Pipeable {
     readonly [EventStreamTypeId]: EventStreamTypeId;
     readonly streamName: string;
     readonly eventSchema: Schema.Top;
     /** See {@link EventStream.snapshotConfig}. */
     readonly snapshotConfig: SnapshotSettings | undefined;
+    /** See {@link EventStream.indexes}. */
+    readonly indexes: {
+        readonly [K in TIndexName]: StreamIndexSettings;
+    };
     /** See {@link EventStream.writeSnapshot} — a method for the same variance reason. */
     writeSnapshot(streamId: StreamIdInput<TStreamIdFields>, state: TState, asOfVersion: number): Effect.Effect<void, DynamoClientError | ValidationError, never>;
     /** See {@link EventStream.readSnapshot}. */
     readSnapshot(streamId: StreamIdInput<TStreamIdFields>): Effect.Effect<Option.Option<Snapshot<TState>>, DynamoClientError | ValidationError, never>;
-    append(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: AppendOptions<TMetadata> | undefined): Effect.Effect<AppendResult<TEvent>, AppendError, never>;
-    read(streamId: StreamIdInput<TStreamIdFields>): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, never>;
-    readFrom(streamId: StreamIdInput<TStreamIdFields>, afterVersion: number): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, never>;
-    currentVersion(streamId: StreamIdInput<TStreamIdFields>): Effect.Effect<number, DynamoClientError | ValidationError, never>;
+    /** See {@link EventStream.append}. */
+    append(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: AppendOptions<TMetadata, TState> | undefined): Effect.Effect<AppendResult<TEvent>, AppendError, never>;
+    /** See {@link EventStream.read}. */
+    read(streamId: StreamIdInput<TStreamIdFields>, options?: ReadOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, never>;
+    /** See {@link EventStream.readFrom}. */
+    readFrom(streamId: StreamIdInput<TStreamIdFields>, afterVersion: number, options?: ReadOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, never>;
+    /** See {@link EventStream.currentVersion}. */
+    currentVersion(streamId: StreamIdInput<TStreamIdFields>, options?: ReadOptions | undefined): Effect.Effect<number, DynamoClientError | ValidationError, never>;
+    /** See {@link EventStream.readLatest}. */
+    readLatest(streamId: StreamIdInput<TStreamIdFields>, options?: ReadLatestOptions | undefined): Effect.Effect<LatestState<TState, TEvent, StreamMetadata<TMetadata>>, DynamoClientError | ValidationError, never>;
+    /** See {@link EventStream.readIndex}. */
+    readIndex(name: TIndexName, streamId: StreamIdInput<TStreamIdFields>, options?: ReadIndexOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, never>;
+    /**
+     * The stream's query builders — unbound: run them with {@link provide}, or
+     * where `DynamoClient` and `TableConfig` are provided.
+     */
     readonly query: {
         events(streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, StreamMetadata<TMetadata>>>;
+        /** See `EventStream.query.index`. */
+        index(name: TIndexName, streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, StreamMetadata<TMetadata>>>;
     };
     /** Escape hatch: provide DynamoClient | TableConfig to an arbitrary effect. */
     readonly provide: <A, E>(effect: Effect.Effect<A, E, DynamoClient | TableConfig>) => Effect.Effect<A, E, never>;
@@ -312,7 +723,64 @@ export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<
  * yield* stream.append({ matchId: "m-1" }, [event], 0)     // R = never
  * ```
  */
-export declare const bind: <TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState>(stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState>) => Effect.Effect<BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState>, never, DynamoClient | TableConfig>;
+export declare const bind: <TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState, TIndexName extends string = never>(stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName>) => Effect.Effect<BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName>, never, DynamoClient | TableConfig>;
+/**
+ * `CreateTable` fragments for the stream indexes of one or more streams — see
+ * {@link indexDefinitions}. The lists are absent when empty, because
+ * DynamoDB rejects an empty index list.
+ */
+export interface StreamIndexDefinitions {
+    /** The index key attributes (all strings), excluding the table's `pk` / `sk`. */
+    readonly AttributeDefinitions: Array<AttributeDefinition>;
+    readonly LocalSecondaryIndexes?: Array<LocalSecondaryIndex> | undefined;
+    readonly GlobalSecondaryIndexes?: Array<GlobalSecondaryIndex> | undefined;
+}
+/**
+ * Derive the `CreateTable` fragments for the stream indexes (#140) of the given
+ * streams (`EventStream` or `BoundEventStream`) — `AttributeDefinitions`,
+ * `LocalSecondaryIndexes` and `GlobalSecondaryIndexes`, each index projecting
+ * `ALL` — to merge into the caller's `CreateTable` input. Event tables are not
+ * derived by `Table.definition`, and the table's own `pk` / `sk` are not
+ * included: add them (and, on a provisioned table, each GSI's
+ * `ProvisionedThroughput`) yourself.
+ *
+ * An index shared by several streams with the same definition is emitted
+ * once. Lists are sorted by index name, attributes by attribute name.
+ *
+ * - An LSI can only be created with the table, and caps the item collection
+ *   of every partition key value in the table at 10 GB — entity partitions
+ *   and streams without indexes included.
+ * - The projection must stay `ALL`: events are decoded from the index item.
+ *
+ * @example
+ * ```typescript
+ * const fragments = EventStore.indexDefinitions(Entries, Orders)
+ * yield* client.createTable({
+ *   TableName: "events",
+ *   BillingMode: "PAY_PER_REQUEST",
+ *   KeySchema: [
+ *     { AttributeName: "pk", KeyType: "HASH" },
+ *     { AttributeName: "sk", KeyType: "RANGE" },
+ *   ],
+ *   AttributeDefinitions: [
+ *     { AttributeName: "pk", AttributeType: "S" },
+ *     { AttributeName: "sk", AttributeType: "S" },
+ *     ...fragments.AttributeDefinitions,
+ *   ],
+ *   LocalSecondaryIndexes: fragments.LocalSecondaryIndexes,
+ *   GlobalSecondaryIndexes: fragments.GlobalSecondaryIndexes,
+ * })
+ * ```
+ *
+ * @throws `[EDD-9067]` when two streams define the same physical index
+ *   differently (another type, or other key attributes).
+ */
+export declare const indexDefinitions: (...streams: ReadonlyArray<{
+    readonly streamName: string;
+    readonly indexes: {
+        readonly [name: string]: StreamIndexSettings;
+    };
+}>) => StreamIndexDefinitions;
 /**
  * Handler-level configuration for {@link commandHandler}.
  *
@@ -327,32 +795,188 @@ export interface CommandHandlerOptions {
      * The retried unit is the entire read–decide–append cycle, so every attempt
      * decides against freshly read state — a blind re-append of stale events is
      * impossible by construction. Snapshot reads participate: a retried attempt
-     * re-reads the snapshot and its delta.
+     * re-reads the snapshot and its delta (the snapshot alone with
+     * {@link verifySnapshot}`: false`), and a function-form `additionalItems` is
+     * re-evaluated against the new decision.
      *
      * A number `n` is shorthand for `Schedule.recurs(n)` (n retries *after* the
      * initial attempt). Omit for the default: no retry.
      *
-     * `DuplicateCommand` is deliberately NOT retried — it is terminal.
+     * `DuplicateCommand` is deliberately NOT retried — it is terminal. Nor is
+     * any call that supplies {@link CommandOptions.expectedVersion}: the caller asked
+     * for a conditional write, so its `VersionConflict` is always surfaced.
      */
     readonly retry?: number | Schedule.Schedule<unknown, VersionConflict> | undefined;
     /** Opt in to exactly-once command processing — see {@link AppendIdempotency}. */
     readonly idempotency?: {
         readonly ttl?: Duration.Duration | string;
     };
+    /**
+     * Load state with strongly consistent reads. Default `true`.
+     *
+     * An eventually consistent load can miss the newest events, so `decide` runs
+     * against stale state and the append then fails with `VersionConflict` (or
+     * burns a retry). A consistent load costs twice the read capacity of an
+     * eventually consistent one. Set `false` to trade that for the occasional
+     * conflict. On a snapshot-configured stream the snapshot and its delta are
+     * one query ({@link EventStream.readLatest}), so the setting covers both.
+     */
+    readonly consistentRead?: boolean | undefined;
+    /**
+     * Verify the snapshot against the stream head when loading state. Default
+     * `true`.
+     *
+     * With `true`, a snapshot-configured stream loads with one `Query` that
+     * reads the snapshot **and** the newest event (more on a lagging snapshot),
+     * so the state `decide` sees is verified current. `false` loads with one
+     * `GetItem` of the snapshot item only ({@link EventStream.readLatest} with
+     * `verifySnapshot: false`). A `Query`'s read capacity counts every item it
+     * reads, a `GetItem` only the snapshot, so with large events `false`
+     * roughly halves the read capacity per command.
+     *
+     * Accepted only when the stream's snapshot config is `mode: "inline"`
+     * **without** `every` — the only mode that writes the snapshot in every
+     * append's transaction, so it is normally at the head. Any other snapshot
+     * config throws `[EDD-9068]` when the handler is created (data-first or
+     * data-last). On a stream without a `snapshot` config the option is
+     * ignored: state is replayed and verified as always.
+     *
+     * The snapshot can still lag the head — events appended without one (a raw
+     * `append`, data written before `mode: "inline"`). So no answer made on an
+     * unverified snapshot is returned until the head confirms it: a successful
+     * append confirms it by itself; anything else — a `decide` failure, a no-op
+     * decision, an append `VersionConflict` — is checked with one more read,
+     * and a stale load falls back to a verified one:
+     *
+     * - **No snapshot item** (a stream not yet snapshotted): the verified load
+     *   runs at once, and `decide` runs once.
+     * - **With {@link CommandOptions.expectedVersion}**: a snapshot whose
+     *   `asOfVersion` differs from it is re-read verified before the If-Match
+     *   check, so only a genuine mismatch is reported (its `actualVersion` is
+     *   the verified head). A snapshot at the expected version holds exactly the
+     *   state the caller saw, so `decide` runs on it; if that decision does not
+     *   append, one head `Query` above the If-Match checks the head (see
+     *   below). A head past the
+     *   If-Match discards the decision and answers as a verified load would:
+     *   `DuplicateCommand` for a committed redelivery, else `VersionConflict`
+     *   with the head as `actualVersion` — never re-decided or retried.
+     * - **Without it**, a `decide` failure or a no-op is checked against the
+     *   head the same way and returned when the head is at the snapshot. An
+     *   append that fails with `VersionConflict` triggers one verified load:
+     *   a snapshot at the head means another writer won a genuine race, and
+     *   the `VersionConflict` goes to the {@link retry} policy as it always
+     *   does. Otherwise — the head past the snapshot, or past the version
+     *   decided on — the first decision was made on stale state and is
+     *   discarded: the handler loads verified (if it has not) and decides again
+     *   on that state, then appends — **`decide` (and a function-form
+     *   `additionalItems`, for a decision that appends) runs twice for that
+     *   call**. That is the optimistic-concurrency price of skipping the
+     *   verification read, the same one a `VersionConflict` retry pays: a
+     *   decision is only as current as the state it was made on, and a stale
+     *   one cannot be patched, only made again. Without the re-decision, a
+     *   lagging snapshot would fail or mis-answer every command on the stream,
+     *   since only a successful inline append rewrites it. It happens at most
+     *   once per attempt, and the second decision's outcome is final for the
+     *   attempt (its conflict follows the policy).
+     *
+     * The head check is a reverse `Limit: 1` `Query` bounded below by the
+     * snapshot's version (or the If-Match), never a read of the newest event:
+     * while the snapshot is current the range is empty, so it reads no items
+     * and costs only DynamoDB's per-request minimum, however large the events
+     * are. A decision that appends nothing therefore costs one extra round trip,
+     * not extra item reads.
+     */
+    readonly verifySnapshot?: boolean | undefined;
 }
-/** Per-call options accepted by a handler produced by {@link commandHandler}. */
-export interface CommandOptions<TMetadata> {
+/**
+ * The outcome of one `decide` call, handed to a function-form
+ * {@link CommandOptions.additionalItems}.
+ *
+ * - `events` — what `decide` returned (never empty: the function is not called
+ *   for a no-op decision).
+ * - `state` — the `evolve` fold of `previous` with `events`: the state the
+ *   handler returns and snapshots.
+ * - `previous` — the state `decide` was given.
+ * - `version` — the stream version the events are appended after; the new
+ *   events take `version + 1 … version + events.length`.
+ *
+ * `evolve` may mutate state in place. When it does, `previous` and `state` are
+ * the same reference and `previous` already reflects `events`; a projection
+ * that needs a pristine `previous` requires an `evolve` that returns new state.
+ */
+export interface Decision<State, Event> {
+    readonly events: ReadonlyArray<Event>;
+    readonly state: State;
+    readonly previous: State;
+    readonly version: number;
+}
+/**
+ * The forms {@link CommandOptions.additionalItems} accepts: a static array of
+ * transact ops, or a function of the {@link Decision} returning the array
+ * directly (pure projection) or as an `Effect` (a projection that needs a read).
+ * The effect's `E2` joins the handler's error channel and its `R2` the handler's
+ * requirements.
+ */
+export type AdditionalItemsInput<State, Event, E2 = never, R2 = never> = ReadonlyArray<TransactWriteOp> | ((decision: Decision<State, Event>) => ReadonlyArray<TransactWriteOp> | Effect.Effect<ReadonlyArray<TransactWriteOp>, E2, R2>);
+/**
+ * Per-call options accepted by a handler produced by {@link commandHandler}.
+ *
+ * `State` / `Event` type the {@link Decision} a function-form `additionalItems`
+ * receives; `E2` / `R2` are the error and requirements of the `Effect` it may
+ * return. The handler infers all four, so they only need naming when this type
+ * is written out by hand.
+ */
+export interface CommandOptions<TMetadata, State = unknown, Event = unknown, E2 = never, R2 = never> {
     readonly metadata?: TMetadata;
     /**
      * Identifier for this command delivery. Required when the handler was created
-     * with `idempotency`; a replayed id fails with `DuplicateCommand`.
+     * with `idempotency`; a replayed id fails with `DuplicateCommand` — also when
+     * the replay carries an {@link expectedVersion} the stream has since moved
+     * past (see there).
+     *
+     * Otherwise the sentinel is consulted when the events are appended, after
+     * `decide`, so a replay whose `decide` fails against the advanced state
+     * reports that failure, and one whose `decide` returns no events succeeds as
+     * a no-op. Only a redelivery that appends fails with `DuplicateCommand`.
      */
     readonly commandId?: string;
-    /** Caller-owned transact items committed atomically with the produced events. */
-    readonly additionalItems?: ReadonlyArray<TransactWriteOp>;
+    /**
+     * The stream version the caller last saw — an HTTP `If-Match`.
+     *
+     * After state is loaded and **before `decide` runs**, a stream at any other
+     * version fails the call with `VersionConflict`, carrying the loaded version
+     * as `actualVersion`; `decide` never sees state the caller did not. Otherwise
+     * the append is conditioned on this version, so a writer that slips in
+     * between the load and the append also fails it with `VersionConflict`
+     * (without `actualVersion`). Neither is retried, whatever the handler's
+     * `retry` policy says.
+     *
+     * With `idempotency`, a mismatch is first checked against the command's
+     * sentinel (one strongly consistent `GetItem`, on the mismatch path only): a
+     * redelivery of a command that already committed — its response lost, the
+     * same `commandId` and If-Match sent again — fails with `DuplicateCommand`,
+     * not `VersionConflict`, matching the precedence `append` applies.
+     *
+     * A no-op decision (`decide` returns `[]`) at the matching version succeeds
+     * with the current state and version. Must be a non-negative integer — any
+     * other value fails with `ValidationError` before anything is read.
+     */
+    readonly expectedVersion?: number | undefined;
+    /**
+     * Caller-owned transact items committed atomically with the produced events
+     * (see {@link AppendOptions.additionalItems}).
+     *
+     * Either a static array, or a function of the {@link Decision} — an inline
+     * projection — returning the array or an `Effect` of it. The function runs
+     * after `decide` and after the new events are folded, is not called when
+     * `decide` returns no events, and is re-run on every retry attempt. The items
+     * it returns count towards `AppendTooLarge`, and the `indices` of an
+     * `AdditionalItemConditionFailed` refer to the array it returned.
+     */
+    readonly additionalItems?: AdditionalItemsInput<State, Event, E2, R2>;
 }
 /** Per-call options when the handler was created with `idempotency` — `commandId` is required. */
-export interface IdempotentCommandOptions<TMetadata> extends CommandOptions<TMetadata> {
+export interface IdempotentCommandOptions<TMetadata, State = unknown, Event = unknown, E2 = never, R2 = never> extends CommandOptions<TMetadata, State, Event, E2, R2> {
     readonly commandId: string;
 }
 /**
@@ -360,12 +984,28 @@ export interface IdempotentCommandOptions<TMetadata> extends CommandOptions<TMet
  * required (and `commandId` within it non-optional), so a missing `commandId`
  * is a compile error rather than a silent downgrade to at-least-once.
  */
-type CommandOptionsArgs<TMetadata, TConfig extends CommandHandlerOptions | undefined> = TConfig extends {
+type CommandOptionsArgs<TMetadata, TConfig extends CommandHandlerOptions | undefined, State, TEvent, E2, R2> = TConfig extends {
     readonly idempotency: object;
-} ? [options: IdempotentCommandOptions<TMetadata>] : [options?: CommandOptions<TMetadata> | undefined];
-type CommandHandlerErrors<E> = E | VersionConflict | DuplicateCommand | AdditionalItemConditionFailed | AppendTooLarge | DynamoClientError | ValidationError | TransactionCancelled;
-type CommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = (streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E>, DynamoClient | TableConfig>;
-type BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = (streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E>, never>;
+} ? [options: IdempotentCommandOptions<TMetadata, State, TEvent, E2, R2>] : [options?: CommandOptions<TMetadata, State, TEvent, E2, R2> | undefined];
+type CommandHandlerErrors<E> = E | VersionConflict | DuplicateCommand | AdditionalItemConditionFailed | AppendTooLarge | DynamoClientError | ValidationError | TransactionCancelled | UniqueConstraintViolation | OptimisticLockError | ConcurrentModification;
+/**
+ * A handler over an {@link EventStream}. Generic per call over the error (`E2`)
+ * and requirements (`R2`) of a function-form `additionalItems` that returns an
+ * `Effect`; both are `never` otherwise.
+ */
+type CommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = <E2 = never, R2 = never>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2, DynamoClient | TableConfig | R2>;
+/**
+ * A handler over a {@link BoundEventStream}: the stream's services are already
+ * provided, so a function-form `additionalItems`' `R2` is its only requirement.
+ */
+type BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = <E2 = never, R2 = never>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2, R2>;
+/**
+ * The handler the data-last {@link commandHandler} returns for stream `S`: a
+ * {@link BoundCommandHandler} for a `BoundEventStream` (checked first — a bound
+ * stream is also structurally an `EventStream`), a {@link CommandHandler}
+ * otherwise.
+ */
+type CommandHandlerFor<S, State, Command, TEvent, E, TConfig extends CommandHandlerOptions | undefined> = S extends BoundEventStream<any, infer TStreamIdFields, infer TMetadata, any, any> ? BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig> : S extends EventStream<any, infer TStreamIdFields, infer TMetadata, any, any> ? CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig> : never;
 /**
  * Create a command handler that reads, decides, and appends atomically.
  *
@@ -391,12 +1031,51 @@ type BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields extends Read
  *   idempotency: { ttl: Duration.days(1) },
  * })
  * yield* handle({ matchId: "m-1" }, command, { commandId: "cmd-7f3a" })
+ *
+ * // Load state from the inline snapshot alone (mode "inline" without `every`)
+ * const handle = EventStore.commandHandler(decider, stream, { verifySnapshot: false })
+ *
+ * // If-Match: fail with VersionConflict (never retried) unless the stream is at v7
+ * yield* handle({ matchId: "m-1" }, command, { expectedVersion: 7 })
+ *
+ * // Inline projection, committed in the same transaction as the events
+ * yield* handle({ matchId: "m-1" }, command, {
+ *   additionalItems: ({ state }) => [Scoreboard.put({ matchId: "m-1", runs: state.runs })],
+ * })
  * ```
  *
- * When the stream declares a `snapshot` config, each invocation reads the
- * snapshot and folds only the events after it, instead of replaying the stream
- * from the beginning. With `snapshot.every` set, a fresh snapshot is written
- * (best-effort) after a successful append once the cadence threshold is crossed.
+ * Each invocation runs
+ * `load → [expectedVersion check] → decide → fold new events → derive items → append → [snapshot]`.
+ *
+ * - **Load.** Strongly consistent by default — see
+ *   {@link CommandHandlerOptions.consistentRead}. When the stream declares a
+ *   `snapshot` config, state is loaded with {@link EventStream.readLatest} —
+ *   the snapshot, the events after it and the head in one request in steady
+ *   state — and only those events are folded, instead of replaying the stream
+ *   from the beginning. On a `mode: "inline"` stream without `every`,
+ *   {@link CommandHandlerOptions.verifySnapshot}`: false` loads the snapshot
+ *   item alone (one `GetItem`); an answer that is not a successful append is
+ *   confirmed against the head first, and a snapshot that proves stale falls
+ *   back to the verified load — in which case `decide` may run twice.
+ * - **expectedVersion.** See {@link CommandOptions.expectedVersion}.
+ * - **Fold before append.** The new events are folded into state before the
+ *   append, so the state returned, snapshotted and handed to a function-form
+ *   `additionalItems` (see {@link Decision}) is always the `evolve` fold.
+ * - **Snapshot.** With `snapshot.mode: "inline"`, the snapshot is written in
+ *   the append transaction itself — on every append, or at the `every`
+ *   cadence. With the default `"after-append"` and `snapshot.every` set, a
+ *   fresh snapshot is written (best-effort) after a successful append once the
+ *   cadence threshold is crossed. See {@link SnapshotMode}.
+ * - **One atomic append.** One command, one decision, one append: a decision
+ *   too large for one transaction fails with `AppendTooLarge` before anything
+ *   is written. A large command is split by the application into stepped
+ *   commands — each an ordinary call, chained by `expectedVersion` — so a
+ *   failure partway leaves the stream at a real intermediate state.
+ *
+ * The handler is generic per call over the error and requirements of a
+ * function-form `additionalItems` that returns an `Effect`: they join the
+ * handler's error channel and requirements (on a `BoundEventStream` handler
+ * they are its only requirements).
  *
  * Without `idempotency`, command processing is **at-least-once**: a retry after
  * an acked-but-lost response re-runs `decide` and appends again.
@@ -408,12 +1087,9 @@ type BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields extends Read
  * `EventStreamTypeId` brand of the second argument.
  */
 export declare const commandHandler: {
-    <State, Command, TEvent, E, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, options?: TConfig): {
-        <TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State>(stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState>): BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
-        <TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State>(stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState>): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
-    };
-    <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState>, options?: TConfig): BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
-    <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState>, options?: TConfig): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
+    <State, Command, TEvent, E, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, options?: TConfig): <S extends BoundEventStream<TEvent, any, any, State, any> | EventStream<TEvent, ReadonlyArray<string>, any, State, any>>(stream: S) => CommandHandlerFor<S, State, Command, TEvent, E, TConfig>;
+    <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State, TIndexName extends string, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName>, options?: TConfig): BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
+    <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State, TIndexName extends string, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName>, options?: TConfig): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
 };
 /**
  * Reconstruct state from events by folding through a decider's `evolve` function.