effect-dynamodb 1.23.0 → 1.25.0

package/dist/EventStore.d.ts

@@ -4,18 +4,27 @@
  * 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,
  * DynamoClient, Marshaller).
  */
+import type { AttributeDefinition, GlobalSecondaryIndex, LocalSecondaryIndex } from "@aws-sdk/client-dynamodb";
 import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.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 { DateTime, type Duration, Effect, Option, Pipeable, Schedule, Schema } from "effect";
 import { DynamoClient, type DynamoClientError } from "./DynamoClient.js";
 import { type TransactWriteOp } from "./internal/TransactWriteOps.js";
 import * as Query from "./Query.js";
@@ -24,8 +33,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>;
@@ -45,6 +59,11 @@ export interface StreamEvent<A, M = Record<string, unknown> | undefined> {
     readonly eventType: string;
     readonly data: A;
     readonly metadata: M;
+    /**
+     * ISO 8601 (UTC): when the event was appended, by the append's `Clock` — or
+     * the `eventTimestamps` entry it was appended with
+     * ({@link AppendOptionsBase.eventTimestamps}).
+     */
     readonly timestamp: string;
 }
 /**
@@ -80,16 +99,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 AppendOptionsBase.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 +155,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 CommandOptionsBase.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,10 +183,47 @@ export interface AppendIdempotency {
      */
     readonly ttl?: Duration.Duration | string;
 }
-/** Options accepted by {@link EventStream.append}. */
-export interface AppendOptions<TMetadata> {
-    /** Per-append metadata, validated against the stream's metadata schema when configured. */
+/**
+ * The metadata of an {@link EventStream.append}: one value shared by every
+ * event (`metadata`), or one entry per event (`eventMetadata`) — never both.
+ *
+ * Passing both is a compile error, and a `ValidationError` at runtime for an
+ * untyped caller. `undefined` counts as absent for either, so
+ * `{ metadata: undefined, eventMetadata: [...] }` is not "both".
+ */
+export type AppendMetadataOptions<TMetadata> = {
+    /**
+     * Metadata written onto **every** event of the append — a copy per item,
+     * encoded once through the stream's metadata schema when one is
+     * configured. For metadata that belongs to each event (an event id, the
+     * original occurrence time of an imported event) use `eventMetadata`:
+     * packing a list into `metadata` stores every entry on every item, so
+     * stored metadata grows with the square of the append size.
+     */
     readonly metadata?: TMetadata;
+    readonly eventMetadata?: undefined;
+} | {
+    readonly metadata?: undefined;
+    /**
+     * Per-event metadata: entry `i` is written onto event `i` (and read back
+     * as that event's `StreamEvent.metadata`). Each defined entry is encoded
+     * through the stream's metadata schema, as `metadata` is; an `undefined`
+     * entry writes its event without a `metadata` attribute.
+     *
+     * Must have exactly one entry per event — a length mismatch fails with
+     * `ValidationError` before anything is read or written, also for an
+     * append of no events (where only `[]` is accepted).
+     */
+    readonly eventMetadata?: ReadonlyArray<TMetadata | undefined>;
+};
+/**
+ * The options of {@link EventStream.append} other than its metadata (see
+ * {@link AppendMetadataOptions}).
+ *
+ * `TState` is the stream's snapshot state type (`never` for a stream without a
+ * `snapshot` config, so `snapshot` cannot be supplied there).
+ */
+export interface AppendOptionsBase<TState = never> {
     /**
      * Caller-owned transact items committed atomically with the events — the same
      * op union `Transaction.transactWrite` accepts (`EntityPut`, `EntityDelete`,
@@ -147,9 +245,305 @@ export interface AppendOptions<TMetadata> {
     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;
+    /**
+     * Per-event timestamps: entry `i` is written as event `i`'s `timestamp` (and
+     * read back as that event's `StreamEvent.timestamp`), for history imported
+     * with its original occurrence times. An `undefined` entry keeps the
+     * append's `Clock` time. Independent of `metadata` / `eventMetadata`.
+     *
+     * Written with `DateTime.formatIso` — the format the append's own time is
+     * written in — so a zoned `DateTime` is stored as its UTC instant.
+     *
+     * - Must have exactly one entry per event, each a valid `DateTime` (finite
+     *   epoch) or `undefined` — anything else fails with `ValidationError` before anything is read or
+     *   written, also for an append of no events (where only `[]` is accepted).
+     * - Only the event items change: the idempotency sentinel, its TTL and the
+     *   inline snapshot record when the append was written.
+     * - No ordering is enforced. `version` orders a stream; timestamps may
+     *   repeat, run backwards or lie in the future, as imported history can.
+     */
+    readonly eventTimestamps?: ReadonlyArray<DateTime.DateTime | undefined>;
 }
+/**
+ * Options accepted by {@link EventStream.append}: {@link AppendOptionsBase}
+ * plus the exclusive `metadata` / `eventMetadata` pair
+ * ({@link AppendMetadataOptions}).
+ *
+ * A type alias rather than an interface, since it is an intersection with a
+ * union: an interface cannot extend it.
+ */
+export type AppendOptions<TMetadata, TState = never> = AppendOptionsBase<TState> & AppendMetadataOptions<TMetadata>;
 /** Error channel of {@link EventStream.append}. */
 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 — as does a `key` that throws. A key over DynamoDB's 1024-byte
+ *   sort-key limit is sent and rejected by DynamoDB; the append then fails
+ *   with `ValidationError` naming the index and the event (#144), and nothing
+ *   is written.
+ *
+ * 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. What
+ * the index copies from each event is its `projection` — see
+ * {@link StreamIndexProjection}.
+ */
+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>;
+    /**
+     * What the index copies from each event — see {@link StreamIndexProjection}.
+     * Default `"all"`. Must match the deployed index.
+     */
+    readonly projection?: StreamIndexProjection | undefined;
+}
+/**
+ * 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. DynamoDB rejects a
+ * strongly consistent read of it, diagnosed as a `ValidationError` naming the
+ * index.
+ *
+ * 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}.
+ * - `projection` — see {@link StreamIndexProjection}.
+ */
+export interface GlobalStreamIndexConfig<TEvent> {
+    readonly type: "gsi";
+    readonly index: string;
+    readonly pk: string;
+    readonly sk: string;
+    readonly key: StreamIndexKey<TEvent>;
+    /**
+     * What the index copies from each event — see {@link StreamIndexProjection}.
+     * Default `"all"`. Must match the deployed index.
+     */
+    readonly projection?: StreamIndexProjection | undefined;
+}
+/**
+ * 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>;
+/**
+ * What a stream index copies from each event (`projection` on an entry of
+ * `makeStream({ indexes })`). {@link indexDefinitions} emits the matching
+ * `Projection`, and the reads choose their path from it.
+ *
+ * | Value | Emitted `Projection` | Read |
+ * |---|---|---|
+ * | `"all"` (default) | `ALL` | one query |
+ * | `"withoutMetadata"` | `INCLUDE` of every event attribute except `metadata` | one query; `metadata` is `undefined` (and typed so) |
+ * | `"keys"` | `INCLUDE ["__edd_e__"]` — **not** `KEYS_ONLY` | LSI: one query with `Select: ALL_ATTRIBUTES` (DynamoDB fetches each event from the table). GSI: the query, then `BatchGetItem` for the events of each page, in index order |
+ *
+ * `__edd_e__` is always projected because every read filters on it, and
+ * DynamoDB refuses a filter on an attribute an index does not project.
+ *
+ * `metadata` is often an event's largest attribute; `"withoutMetadata"` keeps
+ * it out of the index, and `"keys"` keeps the index entries minimal at the cost
+ * of a table read per event read (rounded up to 4 KB each).
+ *
+ * **The declared projection must match the deployed index.** The library does
+ * not migrate: an LSI's projection is fixed when the table is created, and a
+ * GSI's cannot be updated (it must be deleted and created again). Tables
+ * deployed with CDK or Terraform copy `Projection` from
+ * {@link indexDefinitions}' output. An index deployed narrower than declared
+ * fails reads: DynamoDB refuses the `__edd_e__` filter ("does not project one
+ * or more filter attributes"), or rows lack event attributes, which the read
+ * reports as a `ValidationError` (`operation: "EventStore.index.decode"`)
+ * naming the index.
+ */
+export type StreamIndexProjection = "all" | "withoutMetadata" | "keys";
+/**
+ * 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.
+ * `projection` is resolved: `"all"` when the index declares none.
+ */
+export interface StreamIndexSettings {
+    readonly type: "lsi" | "gsi";
+    readonly index: string;
+    readonly pk: string;
+    readonly sk: string;
+    readonly projection: StreamIndexProjection;
+}
+/**
+ * The `metadata` type of an event read through a stream index of projection
+ * `P`: `undefined` for a `"withoutMetadata"` index, which does not hold it,
+ * the stream's {@link StreamMetadata} otherwise.
+ */
+export type IndexEventMetadata<TMetadata, P extends StreamIndexProjection> = [P] extends [
+    "withoutMetadata"
+] ? undefined : StreamMetadata<TMetadata>;
+/** @internal The `projection` an index config declares (`"all"` when none). */
+type ProjectionOf<C> = C extends {
+    readonly projection: infer P extends StreamIndexProjection;
+} ? P : "all";
+/**
+ * The projection of each index of a `makeStream({ indexes })` config, by name.
+ * `"all"` for an index that declares none.
+ */
+export type IndexProjectionsOf<TIndexes> = {
+    readonly [K in keyof TIndexes & string]: ProjectionOf<TIndexes[K]>;
+};
+/** @internal The members a stream index entry may declare. */
+type StreamIndexConfigKey = keyof LocalStreamIndexConfig<unknown> | keyof GlobalStreamIndexConfig<unknown>;
+/**
+ * The `indexes` parameter of {@link makeStream}: each entry is a
+ * {@link StreamIndexConfig}, and a member it does not declare (a misspelled
+ * `projection`, say) is typed `never`, so it is a compile error. Inferring
+ * `TIndexes` from the entries turns off TypeScript's own excess-property check,
+ * which would otherwise catch it.
+ */
+export type StreamIndexesConfig<TIndexes, TEvent> = {
+    readonly [K in keyof TIndexes]: StreamIndexConfig<TEvent> & {
+        readonly [P in Exclude<keyof TIndexes[K], StreamIndexConfigKey>]: never;
+    };
+};
+/**
+ * Options accepted by {@link EventStream.readIndex}.
+ *
+ * - `beginsWith` / `between` — a sort-key condition on the derived key (at most
+ *   one of them, string bounds). Omitted, the whole sub-stream is read.
+ *   DynamoDB rejects an empty bound, and a `between` whose lower bound sorts
+ *   (by UTF-8 bytes) after its upper bound; the read then fails with a
+ *   `ValidationError` naming the index and the bound, DynamoDB's error as its
+ *   cause.
+ * - `reverse` — descending key order.
+ * - `limit` — return at most this many events (a positive integer).
+ * - `consistentRead` — strongly consistent read. DynamoDB rejects it on a
+ *   GSI-backed index, which it reads only eventually consistently: the read
+ *   fails with a `ValidationError` naming the index.
+ */
+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;
 };
@@ -160,14 +554,34 @@ 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. `TIndexProjections` is each
+ * index's {@link StreamIndexProjection} by name, so an event read through a
+ * `"withoutMetadata"` index has `metadata: undefined`.
  */
-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, TIndexProjections extends {
+    readonly [K in TIndexName]: StreamIndexProjection;
+} = {
+    readonly [K in TIndexName]: "all";
+}> 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;
     /**
@@ -196,12 +610,90 @@ 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` (which DynamoDB
+     * rejects on a GSI; the error names the index) — see {@link ReadIndexOptions}.
+     *
+     * How the events are read follows the index's {@link StreamIndexProjection}:
+     * one query for `"all"` and `"withoutMetadata"` (whose events have
+     * `metadata: undefined`, as the type says); for `"keys"`, one query with
+     * `Select: ALL_ATTRIBUTES` on an LSI, or the query followed by `BatchGetItem`
+     * (unprocessed keys retried, index order kept) on a GSI.
+     */
+    readIndex<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>, options?: ReadIndexOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>, 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` (DynamoDB rejects
+         * it on a GSI-backed index: a `ValidationError` naming the index) — and terminals
+         * (`Query.collect`, `Query.execute`, `Query.paginate`). The
+         * `__edd_e__ = <stream>.event` filter still applies.
+         *
+         * It reads as {@link EventStream.readIndex} does for the index's
+         * projection: a `"keys"` GSI fetches each page's events with
+         * `BatchGetItem` (`Query.select` moves onto that fetch); `Query.count`
+         * counts index entries and fetches nothing. On a `"keys"` or
+         * `"withoutMetadata"` index, a `Query.filter` on an attribute the index
+         * does not project is refused by DynamoDB — use `Query.filterBy`.
+         */
+        index<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>;
     };
 }
 /**
@@ -244,6 +736,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
@@ -254,11 +750,65 @@ 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}. 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 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 TIndexes extends { readonly [K in keyof TIndexes]: StreamIndexConfig<Schema.Schema.Type<TEvents[number]>>; } = {}>(config: {
     readonly table: TTable;
     readonly streamName: TStreamName;
     readonly events: TEvents;
@@ -266,7 +816,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?: TIndexes & StreamIndexesConfig<TIndexes, 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, keyof TIndexes & string, IndexProjectionsOf<TIndexes>>;
 /**
  * An EventStream whose operations have `DynamoClient` and `TableConfig` already
  * resolved, so all methods return `Effect<A, E, never>`.
@@ -287,22 +838,44 @@ 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, TIndexProjections extends {
+    readonly [K in TIndexName]: StreamIndexProjection;
+} = {
+    readonly [K in TIndexName]: "all";
+}> 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<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>, options?: ReadIndexOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>, 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<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>;
     };
     /** 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>;
@@ -321,7 +894,81 @@ 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, TIndexProjections extends { readonly [K in TIndexName]: StreamIndexProjection; } = { readonly [K in TIndexName]: "all"; }>(stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections>) => Effect.Effect<BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections>, 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` — 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 declare const indexDefinitions: (...streams: ReadonlyArray<{
+    readonly streamName: string;
+    readonly indexes: {
+        readonly [name: string]: Omit<StreamIndexSettings, "projection"> & {
+            /** Read as `"all"` when absent (a hand-built settings object). */
+            readonly projection?: StreamIndexProjection | undefined;
+        };
+    };
+}>) => StreamIndexDefinitions;
 /**
  * Handler-level configuration for {@link commandHandler}.
  *
@@ -336,45 +983,350 @@ 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 CommandOptionsBase.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 CommandOptionsBase.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 CommandOptionsBase.additionalItems}, to `eventMetadata`
+ * ({@link CommandMetadataOptions}) and to
+ * {@link CommandOptionsBase.eventTimestamps}.
+ *
+ * - `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 CommandOptionsBase.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>);
+/**
+ * The form `eventMetadata` ({@link CommandMetadataOptions}) accepts: a
+ * function of the {@link Decision} returning one metadata entry per event
+ * (`undefined` for an event without metadata), directly or as an `Effect`. The
+ * effect's `E3` joins the handler's error channel and its `R3` the handler's
+ * requirements.
+ *
+ * Function-only: the number of events is known only once `decide` has run.
+ * The `Effect` form lets ids be minted through the `Crypto` service
+ * (`crypto.randomULID`, or `randomUUIDv7`), which keeps them deterministic
+ * under `TestClock` and a test `Crypto` layer with fixed bytes.
+ */
+export type EventMetadataInput<State, Event, TMetadata, E3 = never, R3 = never> = (decision: Decision<State, Event>) => ReadonlyArray<TMetadata | undefined> | Effect.Effect<ReadonlyArray<TMetadata | undefined>, E3, R3>;
+/**
+ * The form {@link CommandOptionsBase.eventTimestamps} accepts: a function of
+ * the {@link Decision} returning one timestamp per event (`undefined` keeps
+ * the append's `Clock` time), directly or as an `Effect` — exactly as
+ * {@link EventMetadataInput}. The effect's `E4` joins the handler's error
+ * channel and its `R4` the handler's requirements.
+ *
+ * Function-only: the number of events is known only once `decide` has run.
+ * The `Effect` form lets times come from a service (a source log, a
+ * per-tenant clock) or from `Clock`, which keeps them deterministic under
+ * `TestClock`.
+ *
+ * `E4` / `R4` are separate from `eventMetadata`'s `E3` / `R3`: with one shared
+ * pair, an `eventMetadata` effect and an `eventTimestamps` effect with
+ * different error types would not compile — TypeScript fixes the parameter
+ * from one candidate and rejects the other instead of inferring a union.
+ */
+export type EventTimestampsInput<State, Event, E4 = never, R4 = never> = (decision: Decision<State, Event>) => ReadonlyArray<DateTime.DateTime | undefined> | Effect.Effect<ReadonlyArray<DateTime.DateTime | undefined>, E4, R4>;
+/**
+ * The per-call metadata of a {@link commandHandler} handler: one value shared
+ * by every event (`metadata`), or a function deriving one entry per event from
+ * the decision (`eventMetadata`) — never both (see
+ * {@link AppendMetadataOptions}).
+ */
+export type CommandMetadataOptions<TMetadata, State, Event, E3 = never, R3 = never> = {
+    /**
+     * Metadata written onto every event the decision appends (see
+     * {@link AppendMetadataOptions}). Fixed before `decide` runs; to give
+     * each event its own entry, use `eventMetadata`.
+     */
     readonly metadata?: TMetadata;
+    readonly eventMetadata?: undefined;
+} | {
+    readonly metadata?: undefined;
+    /**
+     * Per-event metadata derived from the {@link Decision}: the function
+     * returns one entry per event, in order, and entry `i` is written onto
+     * event `i` (see {@link AppendMetadataOptions}).
+     *
+     * - Runs after `decide` and after the new events are folded, receiving
+     *   the same `Decision` a function-form `additionalItems` does — and
+     *   **before** `additionalItems`, so an effectful pair runs in a
+     *   predictable order.
+     * - Not called when `decide` returns no events.
+     * - Re-run on every attempt: each `VersionConflict` retry, and the
+     *   re-decision a stale unverified snapshot triggers
+     *   ({@link CommandHandlerOptions.verifySnapshot}`: false`). Ids minted
+     *   per attempt are safe — a failed attempt writes nothing.
+     * - A result whose length differs from the decision's events fails with
+     *   `ValidationError` (`operation: "EventStore.commandHandler.eventMetadata"`),
+     *   never retried. A failure of the returned `Effect` surfaces as is,
+     *   and is not retried either.
+     *
+     * Without `idempotency`, a redelivery after a lost response decides and
+     * appends again, minting new ids. With it, the redelivery fails with
+     * `DuplicateCommand`, so the first commit's ids are the only ones written:
+     *
+     * ```ts
+     * // `crypto` is the `Crypto.Crypto` service; a ULID takes its time from the
+     * // `Clock`, so `TestClock` plus a fixed-bytes `Crypto` make it deterministic
+     * const handle = EventStore.commandHandler(decider, stream, {
+     *   idempotency: { ttl: Duration.days(1) },
+     * })
+     * yield* handle(streamId, command, {
+     *   commandId: deliveryId,
+     *   eventMetadata: ({ events }) =>
+     *     Effect.forEach(events, () =>
+     *       Effect.map(crypto.randomULID, (eventId) => ({ eventId })),
+     *     ),
+     * })
+     * ```
+     */
+    readonly eventMetadata?: EventMetadataInput<State, Event, TMetadata, E3, R3>;
+};
+/**
+ * The options of a {@link commandHandler} handler other than its metadata
+ * (see {@link CommandMetadataOptions}).
+ */
+export interface CommandOptionsBase<State = unknown, Event = unknown, E2 = never, R2 = never, E4 = never, R4 = never> {
     /**
      * 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 AppendOptionsBase.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-event timestamps derived from the {@link Decision}: the function
+     * returns one entry per event, in order, directly or as an `Effect` (see
+     * {@link EventTimestampsInput}), and entry `i` is written as event `i`'s
+     * `timestamp` — `undefined` keeps the append's `Clock` time (see
+     * {@link AppendOptionsBase.eventTimestamps}). Independent of `metadata` /
+     * `eventMetadata`. The idempotency sentinel, its TTL and an inline snapshot
+     * keep the append's `Clock` time; timestamps carry no ordering check.
+     *
+     * - Runs after `eventMetadata` and before `additionalItems`, each to
+     *   completion before the next, all receiving the same `Decision`; not
+     *   called when `decide` returns no events; re-run on every attempt — each
+     *   `VersionConflict` retry and the re-decision a stale unverified snapshot
+     *   triggers — as `eventMetadata` is.
+     * - A failure of the returned `Effect` surfaces as is, is not retried, and
+     *   `additionalItems` is not run.
+     * - A result — plain or produced by the `Effect` — of the wrong length, or
+     *   with an entry that is neither a valid `DateTime` (finite epoch) nor
+     *   `undefined`, fails with `ValidationError`
+     *   (`operation: "EventStore.commandHandler.eventTimestamps"`), never
+     *   retried. A value that is not a function is refused before anything is
+     *   read.
+     *
+     * ```ts
+     * // plain: the times are in the events
+     * eventTimestamps: ({ events }) => events.map((event) => event.occurredAt)
+     *
+     * // Effect: the times come from a service
+     * eventTimestamps: ({ events }) =>
+     *   Effect.forEach(events, (event) => SourceLog.originalTime(event.sourceId))
+     * ```
+     */
+    readonly eventTimestamps?: EventTimestampsInput<State, Event, E4, R4>;
 }
+/**
+ * Per-call options accepted by a handler produced by {@link commandHandler}:
+ * {@link CommandOptionsBase} plus the exclusive `metadata` / `eventMetadata`
+ * pair ({@link CommandMetadataOptions}).
+ *
+ * `State` / `Event` type the {@link Decision} a function-form `additionalItems`,
+ * `eventMetadata` or `eventTimestamps` receives; `E2` / `R2` are the error and
+ * requirements of the `Effect` `additionalItems` may return, `E3` / `R3` those
+ * of the `Effect` `eventMetadata` may return, `E4` / `R4` those of the
+ * `Effect` `eventTimestamps` may return — separate, so effects with different
+ * error types all join the handler's error channel. The handler infers all of
+ * them, so they only need naming when this type is written out by hand.
+ */
+export type CommandOptions<TMetadata, State = unknown, Event = unknown, E2 = never, R2 = never, E3 = never, R3 = never, E4 = never, R4 = never> = CommandOptionsBase<State, Event, E2, R2, E4, R4> & CommandMetadataOptions<TMetadata, State, Event, E3, R3>;
 /** Per-call options when the handler was created with `idempotency` — `commandId` is required. */
-export interface IdempotentCommandOptions<TMetadata> extends CommandOptions<TMetadata> {
+export type IdempotentCommandOptions<TMetadata, State = unknown, Event = unknown, E2 = never, R2 = never, E3 = never, R3 = never, E4 = never, R4 = never> = CommandOptions<TMetadata, State, Event, E2, R2, E3, R3, E4, R4> & {
     readonly commandId: string;
-}
+};
 /**
  * Options arity: configuring `idempotency` makes the handler's options parameter
  * 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, E3, R3, E4, R4> = TConfig extends {
     readonly idempotency: object;
-} ? [options: IdempotentCommandOptions<TMetadata>] : [options?: CommandOptions<TMetadata> | undefined];
+} ? [options: IdempotentCommandOptions<TMetadata, State, TEvent, E2, R2, E3, R3, E4, R4>] : [options?: CommandOptions<TMetadata, State, TEvent, E2, R2, E3, R3, E4, R4> | undefined];
 type CommandHandlerErrors<E> = E | VersionConflict | DuplicateCommand | AdditionalItemConditionFailed | AppendTooLarge | DynamoClientError | ValidationError | TransactionCancelled | UniqueConstraintViolation | OptimisticLockError | ConcurrentModification;
-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>;
+/**
+ * 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`, those (`E3` / `R3`) of an `eventMetadata` that does, and those
+ * (`E4` / `R4`) of an `eventTimestamps` that does; all are `never` otherwise.
+ */
+type CommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = <E2 = never, R2 = never, E3 = never, R3 = never, E4 = never, R4 = never>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2, E3, R3, E4, R4>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2 | E3 | E4, DynamoClient | TableConfig | R2 | R3 | R4>;
+/**
+ * A handler over a {@link BoundEventStream}: the stream's services are already
+ * provided, so the `R2` / `R3` / `R4` of a function-form `additionalItems` /
+ * `eventMetadata` / `eventTimestamps` are its only requirements.
+ */
+type BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = <E2 = never, R2 = never, E3 = never, R3 = never, E4 = never, R4 = never>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2, E3, R3, E4, R4>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2 | E3 | E4, R2 | R3 | R4>;
+/**
+ * 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.
  *
@@ -400,12 +1352,69 @@ 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 })],
+ * })
+ *
+ * // 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.
@@ -417,12 +1426,13 @@ 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, any> | EventStream<TEvent, ReadonlyArray<string>, any, State, any, 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, TIndexProjections extends {
+        readonly [K in TIndexName]: StreamIndexProjection;
+    }, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections>, 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, TIndexProjections extends {
+        readonly [K in TIndexName]: StreamIndexProjection;
+    }, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections>, options?: TConfig): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
 };
 /**
  * Reconstruct state from events by folding through a decider's `evolve` function.