effect-dynamodb 1.24.0 → 1.26.0

package/dist/EventStore.d.ts

@@ -13,18 +13,26 @@
  *   `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
+ *   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
+ * - Packed storage (`makeStream({ storedAs: { data } })`, `snapshot.storedAs`):
+ *   event data and snapshot state as one JSON string, optionally compressed —
+ *   read by the stored form, so a stream may mix native, JSON and compressed
+ *   items; `measureAppend` / `measureSnapshot` for caller-side size planning,
+ *   and `decodeStreamImage` for DynamoDB Streams records
  *
  * Built on the existing library primitives (DynamoSchema, KeyComposer, Query,
  * DynamoClient, Marshaller).
  */
 import type { AttributeDefinition, GlobalSecondaryIndex, LocalSecondaryIndex } from "@aws-sdk/client-dynamodb";
+import { type PackedConfig } from "@effect-dynamodb/schema/DynamoModel.js";
 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 StreamImage } from "./internal/Packed.js";
 import { type TransactWriteOp } from "./internal/TransactWriteOps.js";
 import * as Query from "./Query.js";
 import { type Table, type TableConfig } from "./Table.js";
@@ -58,8 +66,35 @@ 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;
 }
+/**
+ * A {@link StreamEvent} together with the event's stored `data` in its wire
+ * form — what `decodeStreamImage(image, { raw: true })` returns.
+ */
+export interface RawStreamEvent<A, M = Record<string, unknown> | undefined> extends StreamEvent<A, M> {
+    /**
+     * The event's `data` as stored, before the event schema decoded it: the
+     * parsed JSON of a packed `data` (`{ _tag, ...fields }`), or the unmarshalled
+     * map of a native one — fields the event schema does not model included. The
+     * same object the decode read, so nothing is parsed twice.
+     */
+    readonly rawData: Readonly<Record<string, unknown>>;
+}
+/** Options of `decodeStreamImage`. */
+export interface DecodeStreamImageOptions {
+    /**
+     * Also return the event's stored `data` in wire form (`rawData`, see
+     * {@link RawStreamEvent}) — for a consumer that needs fields the event
+     * schema does not model, without parsing the image a second time.
+     */
+    readonly raw?: boolean | undefined;
+}
 /**
  * Metadata type carried on {@link StreamEvent} for a stream: the decoded
  * metadata schema type when the stream declares one, an untyped record
@@ -122,7 +157,69 @@ export interface SnapshotConfig<TSchema extends Schema.Top = Schema.Top> {
     readonly schema: TSchema;
     readonly mode?: SnapshotMode | undefined;
     readonly every?: number | undefined;
+    /**
+     * How the snapshot's `state` is stored: a native map (omitted, the default)
+     * or packed — `DynamoModel.Packed({ format: "json", compression? })`, one
+     * JSON string, compressed to binary at or over the threshold when that is
+     * smaller. Packing shrinks a large state the most: an inline snapshot rides
+     * in every append's transaction, and DynamoDB's item and transaction size
+     * limits count its **stored** bytes.
+     *
+     * The state schema's encoded side must be object- or array-shaped
+     * (`[EDD-9073]`). Reads go by the stored form, so changing this setting
+     * needs no rewrite: a snapshot written before still decodes.
+     */
+    readonly storedAs?: PackedConfig | undefined;
 }
+/**
+ * How a stream stores event `data` (`makeStream({ storedAs })`). `data` is a
+ * native map by default; `DynamoModel.Packed({ format: "json", compression? })`
+ * stores it as one JSON string (`S`), compressed to binary (`B`) at or over the
+ * threshold when that is smaller. Metadata always stays a map.
+ *
+ * Reads go by each item's stored form, never by this setting, so a stream may
+ * hold a mix — events appended before packing was turned on still decode, and
+ * so do packed events after it is turned off.
+ */
+export interface StreamStorageConfig {
+    readonly data?: PackedConfig | undefined;
+}
+/** The resolved storage settings exposed on a stream (`stream.storedAs`). */
+export interface StreamStorageSettings {
+    /** Event `data` (`makeStream({ storedAs: { data } })`); `undefined` = native map. */
+    readonly data: PackedConfig | undefined;
+    /** Snapshot `state` (`snapshot.storedAs`); `undefined` = native map. */
+    readonly state: PackedConfig | undefined;
+}
+/**
+ * The bytes an {@link EventStream.append} would write, by DynamoDB's own size
+ * accounting — {@link EventStream.measureAppend}. Every number counts stored
+ * bytes: packed (and compressed) `data` and `state` as they would be sent.
+ */
+export interface AppendMeasurement {
+    /**
+     * The item size of each event `Put`, in order — what DynamoDB's 400 KB
+     * (409,600-byte) item limit measures.
+     */
+    readonly events: ReadonlyArray<number>;
+    /** The item size of the idempotency sentinel `Put`, when `idempotency` is given. */
+    readonly sentinel: number | undefined;
+    /** The item size of the inline snapshot `Put`, when `snapshot` is given. */
+    readonly snapshot: number | undefined;
+    /**
+     * What the stream's own actions (the contiguity check, the event puts, the
+     * sentinel and the inline snapshot) add to the `TransactWriteItems` request
+     * — its 4 MB (4,194,304-byte) limit counts items, keys and expressions.
+     * Caller `additionalItems` are not included: add their size yourself.
+     */
+    readonly transactionBytes: number;
+}
+/**
+ * The options {@link EventStream.measureAppend} accepts: those of
+ * {@link EventStream.append} except `additionalItems`.
+ */
+export type MeasureAppendOptions<TMetadata, TState = never> = Omit<AppendOptionsBase<TState>, "additionalItems"> & AppendMetadataOptions<TMetadata>;
+export type { LambdaAttributeValue, StreamImage } from "./internal/Packed.js";
 /**
  * How {@link commandHandler} writes snapshots.
  *
@@ -130,7 +227,7 @@ export interface SnapshotConfig<TSchema extends Schema.Top = Schema.Top> {
  *   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
+ *   {@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.
@@ -153,7 +250,7 @@ export interface SnapshotSettings {
  * 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}).
+ * 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
@@ -178,14 +275,46 @@ export interface AppendIdempotency {
     readonly ttl?: Duration.Duration | string;
 }
 /**
- * Options accepted by {@link EventStream.append}.
+ * 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 AppendOptions<TMetadata, TState = never> {
-    /** Per-append metadata, validated against the stream's metadata schema when configured. */
-    readonly metadata?: TMetadata;
+export interface AppendOptionsBase<TState = never> {
     /**
      * Caller-owned transact items committed atomically with the events — the same
      * op union `Transaction.transactWrite` accepts (`EntityPut`, `EntityDelete`,
@@ -224,7 +353,34 @@ export interface AppendOptions<TMetadata, TState = never> {
      * 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;
 /**
@@ -298,8 +454,10 @@ export interface LatestState<TState, TEvent, M = Record<string, unknown> | undef
  * - `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.
+ *   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
@@ -322,9 +480,9 @@ export type StreamIndexKey<TEvent> = (event: TEvent, version: number) => string
  * 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}.
+ * 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;
@@ -333,13 +491,19 @@ export interface LocalStreamIndexConfig<TEvent> {
     /** 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. A strongly consistent
- * read of it is refused with `ValidationError`.
+ * 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
@@ -350,6 +514,7 @@ export interface LocalStreamIndexConfig<TEvent> {
  * - `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";
@@ -357,6 +522,11 @@ export interface GlobalStreamIndexConfig<TEvent> {
     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,
@@ -364,30 +534,95 @@ export interface GlobalStreamIndexConfig<TEvent> {
  * 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). 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.
+ *   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. Refused with
- *   `ValidationError` on a GSI-backed index, which DynamoDB reads only
- *   eventually consistently.
+ * - `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;
@@ -413,9 +648,15 @@ export type EventStreamTypeId = typeof EventStreamTypeId;
  *
  * `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.
+ * `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, TIndexName extends string = 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;
@@ -434,6 +675,11 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
      * snapshots.
      */
     readonly snapshotConfig: SnapshotSettings | undefined;
+    /**
+     * How the stream stores event `data` and snapshot `state` — see
+     * {@link StreamStorageConfig} and {@link SnapshotConfig.storedAs}.
+     */
+    readonly storedAs: StreamStorageSettings;
     /**
      * Write (or overwrite) this stream's snapshot.
      *
@@ -515,22 +761,92 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
      * 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}.
+     * 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>;
+    /**
+     * The bytes {@link EventStream.append} would write for these arguments, by
+     * DynamoDB's own size accounting — for planning chunks against the 400 KB
+     * item and 4 MB transaction limits without re-implementing the stream's
+     * item layout or packing. The items are built by the same code `append`
+     * uses (envelope, keys, packed and compressed `data`, metadata, stream-index
+     * attributes, the sentinel, the inline snapshot), so the numbers are exact
+     * for the request `append` would send now with this runtime's compressors.
+     *
+     * Nothing is read or written, and nothing is refused for its size: this is
+     * caller-side planning, not a pre-check. `additionalItems` are not accepted
+     * — add their size yourself. Fails as `append` would on invalid options
+     * (`ValidationError`), and — with a `CompressorNotRegistered` cause — when a
+     * value crosses its compression threshold without a registered compressor.
+     */
+    measureAppend(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: MeasureAppendOptions<TMetadata, TState> | undefined): Effect.Effect<AppendMeasurement, ValidationError, TableConfig>;
+    /**
+     * The item size, in bytes, of the snapshot {@link EventStream.writeSnapshot}
+     * (or an inline snapshot at `asOfVersion`) would write — packed `state` as
+     * stored. Caller-side planning, like {@link EventStream.measureAppend}. Dies
+     * with `[EDD-9026]` on a stream without a `snapshot` config.
      */
-    readIndex(name: TIndexName, streamId: StreamIdInput<TStreamIdFields>, options?: ReadIndexOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    measureSnapshot(streamId: StreamIdInput<TStreamIdFields>, state: TState, asOfVersion: number): Effect.Effect<number, ValidationError, TableConfig>;
+    /**
+     * Decode a DynamoDB Streams record image (`NewImage` / `OldImage`) of one
+     * of this stream's events into exactly the {@link StreamEvent} the read
+     * paths return — `data` decoded through the event schemas (by its stored
+     * form: native map, JSON string or compressed binary), `metadata` through
+     * the metadata schema when the stream declares one.
+     *
+     * Accepts DynamoDB JSON as Lambda and EventBridge Pipes deliver it (`B` /
+     * `BS` members as base64 text, or as bytes), or an already-unmarshalled
+     * item (a packed `data` as bytes or base64 text). `Option.none()` for an
+     * image that is not one of this stream's events — its snapshot, an
+     * idempotency sentinel, another stream's or an entity's item — so one
+     * handler can fan a table's records across decoders. The type is read off
+     * the raw image before anything is unmarshalled, so nothing in another
+     * item's image (a number the SDK cannot represent, say) fails the decode.
+     * An event image that does not decode fails with `ValidationError`.
+     *
+     * With `{ raw: true }`, each event also carries `rawData`: its `data` as
+     * stored, in wire form, unmodelled fields included (see
+     * {@link RawStreamEvent}).
+     *
+     * The compressor registry is not in the type (`R = never`): this unbound
+     * method reads the `Compression` service from the running fiber. When the
+     * stream's `storedAs.data` or `snapshot.storedAs` names a codec that
+     * registry does not hold — including no `Compression` at all, for example
+     * one lost behind `Layer.provide` — it dies with the `[EDD-9078]`
+     * configuration defect on first use, whatever the image, rather than
+     * failing with a typed error. Provide `Compression` where the handler runs,
+     * or decode through {@link EventStore.bind}, which captures it.
+     */
+    decodeStreamImage(image: StreamImage, options: DecodeStreamImageOptions & {
+        readonly raw: true;
+    }): Effect.Effect<Option.Option<RawStreamEvent<TEvent, StreamMetadata<TMetadata>>>, ValidationError, never>;
+    decodeStreamImage(image: StreamImage, options?: DecodeStreamImageOptions): Effect.Effect<Option.Option<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, ValidationError, never>;
     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.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(name: TIndexName, streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, StreamMetadata<TMetadata>>>;
+        index<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>): Query.Query<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>;
     };
 }
 /**
@@ -592,7 +908,9 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  * 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}.
+ * `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
@@ -629,7 +947,9 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  *   `"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.
+ *   / `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
@@ -638,10 +958,22 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  *   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).
+ * @throws `[EDD-9079]` when `storedAs` declares a key other than `data`
+ *   (metadata always stays a map), or a `storedAs.data` / `snapshot.storedAs`
+ *   value is not a `DynamoModel.Packed(...)` config.
+ * @throws `[EDD-9073]` when `snapshot.storedAs` is set and the state schema's
+ *   encoded side is not object- or array-shaped.
+ *
+ * `storedAs: { data: DynamoModel.Packed(...) }` stores event `data` packed, and
+ * `snapshot.storedAs` the snapshot `state` — see {@link StreamStorageConfig}.
+ * Register the codecs a compressed config names through the `Compression`
+ * service (`Compression.layer([...])` merged into the application layer): a
+ * bound stream refuses to bind without them, and an unbound one to run its
+ * first operation (`[EDD-9078]`).
  */
 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, const TIndexName extends string = never>(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;
@@ -649,8 +981,10 @@ export declare const makeStream: <const TEvents extends ReadonlyArray<Schema.Top
     readonly metadata?: TMetadata;
     readonly snapshot?: TSnapshot;
     readonly casing?: DynamoSchema.Casing | undefined;
-    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>;
+    readonly indexes?: TIndexes & StreamIndexesConfig<TIndexes, Schema.Schema.Type<TEvents[number]>>;
+    /** How event `data` is stored — see {@link StreamStorageConfig}. */
+    readonly storedAs?: StreamStorageConfig | 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, keyof TIndexes & string, IndexProjectionsOf<TIndexes>>;
 /**
  * An EventStream whose operations have `DynamoClient` and `TableConfig` already
  * resolved, so all methods return `Effect<A, E, never>`.
@@ -671,12 +1005,18 @@ export declare const makeStream: <const TEvents extends ReadonlyArray<Schema.Top
  * }) {}
  * ```
  */
-export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState = never, TIndexName extends string = 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.storedAs}. */
+    readonly storedAs: StreamStorageSettings;
     /** See {@link EventStream.indexes}. */
     readonly indexes: {
         readonly [K in TIndexName]: StreamIndexSettings;
@@ -696,15 +1036,27 @@ export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<
     /** 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>;
+    readIndex<N extends TIndexName>(name: N, streamId: StreamIdInput<TStreamIdFields>, options?: ReadIndexOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, IndexEventMetadata<TMetadata, TIndexProjections[N]>>>, DynamoClientError | ValidationError, never>;
+    /** See {@link EventStream.measureAppend}. */
+    measureAppend(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: MeasureAppendOptions<TMetadata, TState> | undefined): Effect.Effect<AppendMeasurement, ValidationError, never>;
+    /** See {@link EventStream.measureSnapshot}. */
+    measureSnapshot(streamId: StreamIdInput<TStreamIdFields>, state: TState, asOfVersion: number): Effect.Effect<number, ValidationError, never>;
+    /** See {@link EventStream.decodeStreamImage}. */
+    decodeStreamImage(image: StreamImage, options: DecodeStreamImageOptions & {
+        readonly raw: true;
+    }): Effect.Effect<Option.Option<RawStreamEvent<TEvent, StreamMetadata<TMetadata>>>, ValidationError, never>;
+    decodeStreamImage(image: StreamImage, options?: DecodeStreamImageOptions): Effect.Effect<Option.Option<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, ValidationError, never>;
     /**
      * The stream's query builders — unbound: run them with {@link provide}, or
-     * where `DynamoClient` and `TableConfig` are provided.
+     * where `DynamoClient` and `TableConfig` are provided. They do not use the
+     * context this bound stream captured unless run through {@link provide}:
+     * run directly, raw-row unpacking (`Query.select`) and decoding read the
+     * `Compression` registry of the caller's context, not the bound one.
      */
     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>>>;
+        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>;
@@ -723,7 +1075,7 @@ 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, TIndexName extends string = never>(stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName>) => Effect.Effect<BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName>, 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
@@ -738,11 +1090,26 @@ export interface StreamIndexDefinitions {
 /**
  * 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.
+ * `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.
@@ -750,7 +1117,6 @@ export interface StreamIndexDefinitions {
  * - 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
@@ -773,12 +1139,15 @@ export interface StreamIndexDefinitions {
  * ```
  *
  * @throws `[EDD-9067]` when two streams define the same physical index
- *   differently (another type, or other key attributes).
+ *   differently (another type, other key attributes, or another projection).
  */
 export declare const indexDefinitions: (...streams: ReadonlyArray<{
     readonly streamName: string;
     readonly indexes: {
-        readonly [name: string]: StreamIndexSettings;
+        readonly [name: string]: Omit<StreamIndexSettings, "projection"> & {
+            /** Read as `"all"` when absent (a hand-built settings object). */
+            readonly projection?: StreamIndexProjection | undefined;
+        };
     };
 }>) => StreamIndexDefinitions;
 /**
@@ -803,7 +1172,7 @@ export interface CommandHandlerOptions {
      * initial attempt). Omit for the default: no retry.
      *
      * `DuplicateCommand` is deliberately NOT retried — it is terminal. Nor is
-     * any call that supplies {@link CommandOptions.expectedVersion}: the caller asked
+     * 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;
@@ -850,7 +1219,7 @@ export interface CommandHandlerOptions {
      *
      * - **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
+     * - **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
@@ -890,7 +1259,9 @@ export interface CommandHandlerOptions {
 }
 /**
  * The outcome of one `decide` call, handed to a function-form
- * {@link CommandOptions.additionalItems}.
+ * {@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).
@@ -911,7 +1282,7 @@ export interface Decision<State, Event> {
     readonly version: number;
 }
 /**
- * The forms {@link CommandOptions.additionalItems} accepts: a static array of
+ * 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
@@ -919,15 +1290,97 @@ export interface Decision<State, Event> {
  */
 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}.
+ * 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.
  *
- * `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.
+ * 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 interface CommandOptions<TMetadata, State = unknown, Event = unknown, E2 = never, R2 = never> {
+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` — also when
@@ -964,7 +1417,7 @@ export interface CommandOptions<TMetadata, State = unknown, Event = unknown, E2
     readonly expectedVersion?: number | undefined;
     /**
      * Caller-owned transact items committed atomically with the produced events
-     * (see {@link AppendOptions.additionalItems}).
+     * (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
@@ -974,31 +1427,80 @@ export interface CommandOptions<TMetadata, State = unknown, Event = unknown, E2
      * `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, State = unknown, Event = unknown, E2 = never, R2 = never> extends CommandOptions<TMetadata, State, Event, E2, R2> {
+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, State, TEvent, E2, R2> = 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, State, TEvent, E2, R2>] : [options?: CommandOptions<TMetadata, State, TEvent, E2, R2> | 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;
 /**
  * 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.
+ * `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>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2, DynamoClient | TableConfig | R2>;
+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 a function-form `additionalItems`' `R2` is its only requirement.
+ * 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>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2, R2>;
+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
@@ -1042,6 +1544,24 @@ type CommandHandlerFor<S, State, Command, TEvent, E, TConfig extends CommandHand
  * 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)),
+ * })
  * ```
  *
  * Each invocation runs
@@ -1057,7 +1577,7 @@ type CommandHandlerFor<S, State, Command, TEvent, E, TConfig extends CommandHand
  *   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}.
+ * - **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.
@@ -1067,8 +1587,8 @@ type CommandHandlerFor<S, State, Command, TEvent, E, TConfig extends CommandHand
  *   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
+ *   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.
  *
@@ -1087,9 +1607,13 @@ type CommandHandlerFor<S, State, Command, TEvent, E, TConfig extends CommandHand
  * `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): <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>;
+    <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.
@@ -1109,5 +1633,4 @@ export declare const foldFrom: {
     <A>(startState: unknown, events: ReadonlyArray<StreamEvent<A>>): <S, C, E>(decider: Decider<S, C, A, E>) => S;
     <S, C, A, E>(decider: Decider<S, C, A, E>, startState: S, events: ReadonlyArray<StreamEvent<A>>): S;
 };
-export {};
 //# sourceMappingURL=EventStore.d.ts.map