effect-dynamodb 1.24.0 → 1.25.0

package/dist/EventStore.js

@@ -13,8 +13,9 @@
  *   `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
  *
  * Built on the existing library primitives (DynamoSchema, KeyComposer, Query,
@@ -22,11 +23,12 @@
  */
 import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.js";
 import { normalizeTtlSeconds } from "@effect-dynamodb/schema/Entity.js";
-import { AdditionalItemConditionFailed, AppendTooLarge, DuplicateCommand, isAwsConditionalCheckFailed, isAwsTransactionCancelled, TRANSACT_WRITE_ITEMS_LIMIT, TransactionCancelled, ValidationError, VersionConflict, } from "@effect-dynamodb/schema/Errors.js";
+import { AdditionalItemConditionFailed, AppendTooLarge, DuplicateCommand, isAwsConditionalCheckFailed, isAwsTransactionCancelled, TransactionCancelled, ValidationError, VersionConflict, } from "@effect-dynamodb/schema/Errors.js";
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
 import { DateTime, Effect, Function, Option, Pipeable, Result, Schedule, Schema, } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
-import { buildTransactWriteItems, GUARDED_TRANSACTION_ATTEMPTS, judgeCancellation, refuseOversizedTransaction, refuseRepeatedItems, transactItemTarget, } from "./internal/TransactWriteOps.js";
+import { buildTransactWriteItems, GUARDED_TRANSACTION_ATTEMPTS, judgeCancellation, transactItemTarget, } from "./internal/TransactWriteOps.js";
+import { diagnosedValidationError, diagnoseFailure, mergeKeyAttributes, withCause, } from "./internal/WriteDiagnosis.js";
 import { fromAttributeMap, toAttributeMap } from "./Marshaller.js";
 import * as Query from "./Query.js";
 import { DEFAULT_TTL_ATTRIBUTE_NAME, resolveTtlAttributeName, } from "./Table.js";
@@ -45,30 +47,13 @@ const EventEnvelope = Schema.Struct({
     eventType: Schema.String,
     timestamp: Schema.String,
 });
-/** @internal DynamoDB's limit on a sort key value, which an index key is. */
-const MAX_INDEX_SORT_KEY_BYTES = 1024;
-/** @internal */
-const utf8 = new TextEncoder();
-/**
- * @internal Compare two strings by their UTF-8 bytes — the order DynamoDB
- * sorts (and evaluates `BETWEEN` on) string keys. JavaScript's `<` compares
- * UTF-16 code units, which disagrees for characters outside the BMP.
- */
-const compareUtf8 = (a, b) => {
-    const left = utf8.encode(a);
-    const right = utf8.encode(b);
-    const length = Math.min(left.length, right.length);
-    for (let i = 0; i < length; i++) {
-        const diff = left[i] - right[i];
-        if (diff !== 0)
-            return diff;
-    }
-    return left.length - right.length;
-};
 /**
  * @internal Why a {@link ReadIndexOptions} key condition cannot be sent, or
- * `undefined` when it can. DynamoDB rejects an empty key value and a
- * `BETWEEN` whose lower bound sorts after its upper bound.
+ * `undefined` when it can: the options' own meaning — at most one of
+ * `beginsWith` and `between`, string bounds (a number would be sent as `N`
+ * against a string key). DynamoDB's rules on the bounds — not empty, a
+ * `between` in order — are DynamoDB's to enforce: its rejection is diagnosed,
+ * naming the index and the bound (#144).
  */
 const invalidIndexKeyCondition = (options) => {
     if (options?.beginsWith !== undefined && options.between !== undefined) {
@@ -76,26 +61,46 @@ const invalidIndexKeyCondition = (options) => {
     }
     const beginsWith = options?.beginsWith;
     if (beginsWith !== undefined) {
-        if (typeof beginsWith !== "string" || beginsWith.length === 0) {
-            return ("beginsWith must be a non-empty string — DynamoDB rejects an empty key value; " +
-                "omit it to read the whole sub-stream.");
-        }
-        return undefined;
+        return typeof beginsWith === "string"
+            ? undefined
+            : "beginsWith must be a string; omit it to read the whole sub-stream.";
     }
     const between = options?.between;
     if (between === undefined)
         return undefined;
     if (!Array.isArray(between) ||
         between.length !== 2 ||
-        !between.every((bound) => typeof bound === "string" && bound.length > 0)) {
-        return "between must be a pair of non-empty strings — DynamoDB rejects an empty key value.";
-    }
-    const [low, high] = between;
-    if (compareUtf8(low, high) > 0) {
-        return `between's lower bound ${JSON.stringify(low)} sorts after its upper bound ${JSON.stringify(high)}.`;
+        !between.every((bound) => typeof bound === "string")) {
+        return "between must be a pair of strings.";
     }
     return undefined;
 };
+/**
+ * @internal The attributes `append` writes on every event item besides the
+ * table key (`pk`, `sk`), the optional `metadata` and the index attributes:
+ * the envelope, `data` and the `__edd_e__` discriminator. Sorted. A
+ * `"withoutMetadata"` stream index projects exactly these.
+ */
+const EVENT_ITEM_ATTRIBUTES = [
+    "__edd_e__",
+    "data",
+    "eventType",
+    "streamId",
+    "timestamp",
+    "version",
+];
+/**
+ * @internal The event attributes an `"all"` or `"withoutMetadata"` stream index
+ * guarantees on its rows and a decode needs: a row lacking one was read
+ * through an index deployed narrower than declared.
+ */
+const PROJECTED_ENVELOPE_ATTRIBUTES = [
+    "data",
+    "eventType",
+    "streamId",
+    "timestamp",
+    "version",
+];
 /**
  * @internal Attributes a stream writes on its own items — events, snapshot,
  * idempotency sentinel — plus the default TTL attribute. An index attribute
@@ -116,11 +121,22 @@ const STREAM_OWNED_ATTRIBUTES = [
     "commandId",
     DEFAULT_TTL_ATTRIBUTE_NAME,
 ];
+/** @internal Every member a stream index entry may declare (`StreamIndexConfigKey`). */
+const STREAM_INDEX_CONFIG_KEYS = [
+    "type",
+    "index",
+    "pk",
+    "sk",
+    "key",
+    "projection",
+];
 /**
  * @internal Validate `makeStream({ indexes })` at definition time.
  *
  * @throws `[EDD-9063]` for a malformed entry (unknown `type`, a `gsi` without
- *   `pk`, an `lsi` with `pk`, an empty name, a `key` that is not a function).
+ *   `pk`, an `lsi` with `pk`, an empty name, a `key` that is not a function,
+ *   an unknown `projection`, a member the entry type does not declare — a
+ *   misspelled `projection` would otherwise silently mean `"all"`).
  * @throws `[EDD-9064]` for an index attribute that collides with a
  *   stream-owned attribute.
  * @throws `[EDD-9065]` for two indexes sharing a physical index name or an
@@ -139,6 +155,11 @@ const resolveStreamIndexes = (streamName, indexes) => {
             fail("EDD-9063", `index "${name}" must be an object; received ${String(raw)}.`);
         }
         const entry = raw;
+        const unknownKey = Object.keys(entry).find((key) => !STREAM_INDEX_CONFIG_KEYS.includes(key));
+        if (unknownKey !== undefined) {
+            fail("EDD-9063", `index "${name}": unknown member "${unknownKey}"; an index declares ` +
+                `${STREAM_INDEX_CONFIG_KEYS.join(", ")}.`);
+        }
         const type = (entry.type ?? "lsi");
         if (type !== "lsi" && type !== "gsi") {
             fail("EDD-9063", `index "${name}": type must be "lsi" or "gsi"; received ${JSON.stringify(entry.type)}.`);
@@ -160,6 +181,11 @@ const resolveStreamIndexes = (streamName, indexes) => {
         if (typeof entry.key !== "function") {
             fail("EDD-9063", `index "${name}": key must be a function (event, version) => string | undefined.`);
         }
+        const projection = (entry.projection ?? "all");
+        if (projection !== "all" && projection !== "withoutMetadata" && projection !== "keys") {
+            fail("EDD-9063", `index "${name}": projection must be "all", "withoutMetadata" or "keys"; received ` +
+                `${JSON.stringify(entry.projection)}.`);
+        }
         const index = entry.index;
         const sk = entry.sk;
         const pk = type === "gsi" ? entry.pk : "pk";
@@ -189,6 +215,7 @@ const resolveStreamIndexes = (streamName, indexes) => {
             index,
             pk,
             sk,
+            projection,
             key: entry.key,
         });
     }
@@ -248,6 +275,32 @@ const unverifiedSnapshotRefusal = (streamName, settings, operation) => settings
         `snapshot mode "inline" without "every" — the only mode that writes the snapshot in every ` +
         `append, so it is normally at the head. This stream's snapshot is mode "${settings.mode}"` +
         `${settings.every === undefined ? "" : ` with every: ${settings.every}`}.`;
+/**
+ * @internal Why an `eventTimestamps` value cannot be written for `count`
+ * events — not an array, the wrong length, or an entry that is neither a
+ * valid `DateTime` (finite epoch) nor `undefined` — or `undefined` when it can. `label` opens the
+ * message (`"eventTimestamps has"` / `"eventTimestamps returned"`) and
+ * `events` names the events (`"2 events"` / `"the decision's 2 events"`).
+ */
+const eventTimestampsProblem = (timestamps, count, label, events) => {
+    if (!Array.isArray(timestamps) || timestamps.length !== count) {
+        return (`${label} ${Array.isArray(timestamps) ? timestamps.length : "no"} entries for ${events}: ` +
+            "it needs exactly one entry (a DateTime, or undefined) per event, in order.");
+    }
+    const malformed = timestamps.findIndex((t) => t !== undefined && (!DateTime.isDateTime(t) || !Number.isFinite(DateTime.toEpochMillis(t))));
+    if (malformed === -1)
+        return undefined;
+    const entry = timestamps[malformed];
+    // A DateTime with a NaN epoch (e.g. `setPartsUtc` from a bad parse) passes
+    // `isDateTime` but makes `formatIso` throw, so it is refused here instead.
+    if (DateTime.isDateTime(entry)) {
+        return (`eventTimestamps[${malformed}] is an invalid DateTime (its epoch milliseconds are not a ` +
+            "finite number): each entry must be a valid DateTime, or undefined to keep the append's own time.");
+    }
+    return (`eventTimestamps[${malformed}] is not a DateTime (received ` +
+        `${entry instanceof Date ? "a Date — convert it with DateTime.fromDateUnsafe" : entry === null ? "null" : typeof entry}): ` +
+        "each entry must be a DateTime, or undefined to keep the append's own time.");
+};
 // ---------------------------------------------------------------------------
 // makeStream factory
 // ---------------------------------------------------------------------------
@@ -310,7 +363,9 @@ const unverifiedSnapshotRefusal = (streamName, settings, operation) => settings
  * 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
@@ -347,7 +402,9 @@ const unverifiedSnapshotRefusal = (streamName, settings, operation) => settings
  *   `"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
@@ -410,7 +467,13 @@ export const makeStream = (config) => {
     const streamIndexes = resolveStreamIndexes(config.streamName, config.indexes);
     const indexSettings = {};
     for (const idx of streamIndexes) {
-        indexSettings[idx.name] = { type: idx.type, index: idx.index, pk: idx.pk, sk: idx.sk };
+        indexSettings[idx.name] = {
+            type: idx.type,
+            index: idx.index,
+            pk: idx.pk,
+            sk: idx.sk,
+            projection: idx.projection,
+        };
     }
     /** Every attribute the indexes write on an event item. */
     const indexAttributes = streamIndexes.flatMap((idx) => idx.type === "gsi" ? [idx.pk, idx.sk] : [idx.sk]);
@@ -512,10 +575,12 @@ export const makeStream = (config) => {
     // append
     // ---------------------------------------------------------------------------
     /**
-     * An event's key in a stream index (#140): a non-empty string, or
-     * `undefined` to leave the event out. Anything else — an empty string
-     * (DynamoDB rejects empty key values), another type, a `key` that throws —
-     * is a `ValidationError`, raised before anything is written.
+     * An event's key in a stream index (#140): a string, or `undefined` to
+     * leave the event out. Another type, or a `key` that throws, is a
+     * `ValidationError`, raised before anything is written. DynamoDB's own
+     * rules on a key — not empty, at most 1024 bytes for a sort key — are not
+     * pre-checked: DynamoDB rejects the append and the rejection is diagnosed,
+     * naming the index and event (see `sendAppendTransaction`).
      */
     const deriveIndexKey = (idx, event, version) => Effect.try({
         try: () => idx.key(event, version),
@@ -529,12 +594,12 @@ export const makeStream = (config) => {
             cause: `The key of index "${idx.name}" for the event at version ${version} ${problem}. ` +
                 "Nothing was written.",
         }));
-        if (typeof derived !== "string" || derived === "") {
-            return refuse("must be a non-empty string or undefined; received " +
-                (typeof derived === "string" ? "an empty string" : String(derived)));
-        }
-        if (utf8.encode(derived).length > MAX_INDEX_SORT_KEY_BYTES) {
-            return refuse(`is longer than DynamoDB's ${MAX_INDEX_SORT_KEY_BYTES}-byte limit for a sort key`);
+        // A string, or the event is not indexed: what the stream's own key
+        // contract means, which DynamoDB cannot see (a number would be sent
+        // as `N`). An empty string is DynamoDB's to reject, and is diagnosed
+        // from its rejection, naming the index and the event (#144).
+        if (typeof derived !== "string") {
+            return refuse(`must be a string or undefined; received ${String(derived)}`);
         }
         return Effect.succeed(derived);
     }));
@@ -552,69 +617,172 @@ export const makeStream = (config) => {
      * the race a guarded additional put lost (so the transaction is built and
      * written again), and fails with every other verdict.
      */
-    const sendAppendTransaction = (client, tx, streamIdStr, commandId) => client.transactWriteItems({ TransactItems: tx.items }).pipe(Effect.as(undefined), Effect.catch((error) => {
-        if (!isAwsTransactionCancelled(error.cause)) {
-            return Effect.fail(error);
-        }
-        const rawReasons = error.cause.CancellationReasons ?? [];
-        const reasons = rawReasons.map((r) => ({
-            code: r?.Code,
-            message: r?.Message,
-        }));
-        const failedAt = (index) => index >= 0 && reasons[index]?.code === "ConditionalCheckFailed";
-        // Precedence is ordered by how terminal the caller's response should
-        // be: a duplicate can never succeed on retry, a version conflict
-        // invites a re-read, and only then are the additional items judged.
-        if (commandId !== undefined && failedAt(tx.sentinelIndex)) {
-            return Effect.fail(new DuplicateCommand({
+    const sendAppendTransaction = (client, tx, streamIdStr, commandId) => {
+        const sent = () => ({ _tag: "Transaction", items: tx.items, targets: tx.targets });
+        const diagnosed = (diagnosis, original) => diagnosis._tag === "TooManyItems"
+            ? new AppendTooLarge({
                 streamName: config.streamName,
                 streamId: streamIdStr,
-                commandId,
+                count: diagnosis.count,
+                limit: diagnosis.limit,
+                cause: original,
+            })
+            : appendLimitError(diagnosis, original, tx);
+        return client.transactWriteItems({ TransactItems: tx.items }).pipe(Effect.as(undefined), 
+        // One operation per item (#133, #144): diagnosed BEFORE the conditional
+        // mapping below — DynamoDB can report a repeated item as a conditional
+        // failure, which would read as a version conflict or a lost race (and
+        // be retried). Terminal.
+        diagnoseFailure({ sent, only: ["RepeatedItem"], rewrite: diagnosed }), Effect.catch((error) => {
+            if (!isAwsTransactionCancelled(error.cause)) {
+                return Effect.fail(error);
+            }
+            const rawReasons = error.cause.CancellationReasons ?? [];
+            const reasons = rawReasons.map((r) => ({
+                code: r?.Code,
+                message: r?.Message,
             }));
-        }
-        // The contiguity ConditionCheck and the event puts both mean "the
-        // stream is not where you said it was", so they share one verdict.
-        for (let i = 0; i < tx.guardCount + tx.eventCount; i++) {
-            if (failedAt(i)) {
-                return Effect.fail(new VersionConflict({
+            const failedAt = (index) => index >= 0 && reasons[index]?.code === "ConditionalCheckFailed";
+            // Precedence is ordered by how terminal the caller's response should
+            // be: a duplicate can never succeed on retry, a version conflict
+            // invites a re-read, and only then are the additional items judged.
+            if (commandId !== undefined && failedAt(tx.sentinelIndex)) {
+                return Effect.fail(new DuplicateCommand({
                     streamName: config.streamName,
                     streamId: streamIdStr,
-                    expectedVersion: tx.expectedVersion,
+                    commandId,
                 }));
             }
-        }
-        // The additional items, attributed back to the caller OPS that
-        // produced them (several items can belong to one op). Only an op's
-        // own condition is `AdditionalItemConditionFailed`: a guarded put
-        // the caller set no condition on reports what the entity's own put
-        // would — a taken unique value, a history conflict — or, having
-        // lost a race to a concurrent write, is written again (#133).
-        const judged = judgeCancellation(tx.additional, rawReasons, tx.guardCount + tx.eventCount);
-        if (judged?._tag === "fail")
-            return Effect.fail(judged.error);
-        if (judged?._tag === "conditions") {
-            return Effect.fail(new AdditionalItemConditionFailed({
-                streamName: config.streamName,
-                streamId: streamIdStr,
-                indices: judged.opIndices,
+            // The contiguity ConditionCheck and the event puts both mean "the
+            // stream is not where you said it was", so they share one verdict.
+            for (let i = 0; i < tx.guardCount + tx.eventCount; i++) {
+                if (failedAt(i)) {
+                    return Effect.fail(new VersionConflict({
+                        streamName: config.streamName,
+                        streamId: streamIdStr,
+                        expectedVersion: tx.expectedVersion,
+                    }));
+                }
+            }
+            // The additional items, attributed back to the caller OPS that
+            // produced them (several items can belong to one op). Only an op's
+            // own condition is `AdditionalItemConditionFailed`: a guarded put
+            // the caller set no condition on reports what the entity's own put
+            // would — a taken unique value, a history conflict — or, having
+            // lost a race to a concurrent write, is written again (#133).
+            const judged = judgeCancellation(tx.additional, rawReasons, tx.guardCount + tx.eventCount);
+            if (judged?._tag === "fail")
+                return Effect.fail(judged.error);
+            if (judged?._tag === "conditions") {
+                return Effect.fail(new AdditionalItemConditionFailed({
+                    streamName: config.streamName,
+                    streamId: streamIdStr,
+                    indices: judged.opIndices,
+                    reasons,
+                }));
+            }
+            if (judged?._tag === "retry")
+                return Effect.succeed(judged.error);
+            // No conditional failure we can positionally justify (throttling,
+            // TransactionConflict, a reason at the inline snapshot's position, or
+            // a truncated/absent reason list) — never guess a VersionConflict.
+            return Effect.fail(new TransactionCancelled({
+                operation: "TransactWriteItems",
                 reasons,
+                cause: error.cause,
             }));
-        }
-        if (judged?._tag === "retry")
-            return Effect.succeed(judged.error);
-        // No conditional failure we can positionally justify (throttling,
-        // TransactionConflict, a reason at the inline snapshot's position, or
-        // a truncated/absent reason list) — never guess a VersionConflict.
-        return Effect.fail(new TransactionCancelled({
-            operation: "TransactWriteItems",
-            reasons,
-            cause: error.cause,
+        }), 
+        // DynamoDB's limits are not pre-checked (#144): a rejection the
+        // conditional mapping above could not explain is diagnosed against the
+        // transaction sent, naming the event, sentinel, snapshot or additional
+        // item at fault. Over 100 items is `AppendTooLarge`, with the EXPANDED
+        // count.
+        diagnoseFailure({
+            sent,
+            keys: () => mergeKeyAttributes({
+                partition: ["pk", ...streamIndexes.map((idx) => idx.pk)],
+                sort: ["sk", ...streamIndexes.map((idx) => idx.sk)],
+            }, tx.additional.keys()),
+            rewrite: diagnosed,
         }));
-    }));
+    };
+    /**
+     * A diagnosed rejection of an append (#144) other than its item count. An
+     * over-long (or empty) stream-index sort key OF AN EVENT — the value the
+     * index's `key` function returned — is named by its index and event, as
+     * the `indexes` option reports its other key problems. Only the event puts
+     * carry stream-index keys: an additional item writing the same physical
+     * attribute (single-table designs share `gsi1sk` and the like) is its own
+     * entity's key, and is named as any other item.
+     */
+    const appendLimitError = (diagnosis, original, tx) => {
+        if ((diagnosis._tag === "KeyTooLong" && diagnosis.kind === "sort") ||
+            diagnosis._tag === "EmptyKey") {
+            const position = tx.targets().indexOf(diagnosis.target);
+            const isEvent = position >= tx.guardCount && position < tx.guardCount + tx.eventCount;
+            const idx = isEvent
+                ? streamIndexes.find((candidate) => candidate.sk === diagnosis.attribute)
+                : undefined;
+            if (idx !== undefined) {
+                return new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.indexes",
+                    cause: withCause(`The key of index "${idx.name}" for ${diagnosis.target.source} ` +
+                        (diagnosis._tag === "KeyTooLong"
+                            ? `is ${diagnosis.bytes} bytes, longer than DynamoDB's 1024-byte limit for a ` +
+                                "sort key."
+                            : "is an empty string, which DynamoDB does not accept as a key value; the " +
+                                "key function must return a non-empty string, or undefined to leave the " +
+                                "event out of the index.") +
+                        " DynamoDB rejected the append. Nothing was written.", original),
+                });
+            }
+        }
+        return diagnosedValidationError(diagnosis, original, {
+            operation: "EventStore.append",
+            entityType,
+        });
+    };
     const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
         const additionalOps = options?.additionalItems ?? [];
         const idempotency = options?.idempotency;
         const snapshotState = options?.snapshot;
+        const eventMetadata = options?.eventMetadata;
+        // Per-event metadata (#144) is checked first — ahead of the no-op fast
+        // path below, which would otherwise accept `append(id, [], v,
+        // { eventMetadata: [m] })` without looking at it.
+        if (eventMetadata !== undefined) {
+            if (options?.metadata !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.eventMetadata",
+                    cause: "metadata and eventMetadata are mutually exclusive: pass one value shared by " +
+                        "every event, or one entry per event. Nothing was written.",
+                });
+            }
+            if (!Array.isArray(eventMetadata) || eventMetadata.length !== events.length) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.eventMetadata",
+                    cause: `eventMetadata has ${Array.isArray(eventMetadata) ? eventMetadata.length : "no"} ` +
+                        `entries for ${events.length} events: it needs exactly one entry (or undefined) ` +
+                        "per event, in order. Nothing was written.",
+                });
+            }
+        }
+        // Per-event timestamps (#144), checked alongside the metadata and for
+        // the same reason: ahead of the no-op fast path.
+        const eventTimestamps = options?.eventTimestamps;
+        if (eventTimestamps !== undefined) {
+            const problem = eventTimestampsProblem(eventTimestamps, events.length, "eventTimestamps has", `${events.length} events`);
+            if (problem !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.eventTimestamps",
+                    cause: `${problem} Nothing was written.`,
+                });
+            }
+        }
         if (snapshotState !== undefined && snapshot === undefined) {
             return yield* snapshotUnavailable("append({ snapshot })");
         }
@@ -641,32 +809,11 @@ export const makeStream = (config) => {
                     `owns version ${expectedVersion}. Nothing was written.`,
             });
         }
-        // Guard: every item the transaction will carry — one Put per event, the
-        // items each caller-supplied additional op compiles to, the idempotency
-        // sentinel, the inline snapshot, and the version-contiguity
-        // ConditionCheck when expectedVersion > 0 — must fit DynamoDB's
-        // TransactWriteItems limit. Never split: splitting would break append
-        // atomicity (a large command is stepped by the application instead — one
-        // command, one decision, one atomic append).
-        //
-        // This first check is a LOWER BOUND, counting one item per additional op.
-        // Expansion (uniqueness sentinels, version snapshots — #113) only ever
-        // adds items, so an append that already fails here can never fit, and
-        // failing now keeps an oversized append free. The authoritative check runs
-        // once the ops are compiled, below.
+        // DynamoDB's 100-item limit on one transaction is not pre-checked
+        // (#144): an append is never split — splitting would break its
+        // atomicity — so one over the limit is rejected whole by DynamoDB and
+        // reported as `AppendTooLarge`, with the expanded item count.
         const needsContiguityCheck = expectedVersion > 0 && events.length > 0;
-        const fixedItems = events.length +
-            (idempotency !== undefined ? 1 : 0) +
-            (snapshotState !== undefined ? 1 : 0) +
-            (needsContiguityCheck ? 1 : 0);
-        if (fixedItems + additionalOps.length > TRANSACT_WRITE_ITEMS_LIMIT) {
-            return yield* new AppendTooLarge({
-                streamName: config.streamName,
-                streamId: streamIdStr,
-                count: fixedItems + additionalOps.length,
-                limit: TRANSACT_WRITE_ITEMS_LIMIT,
-            });
-        }
         const client = yield* DynamoClient;
         const tableConfig = yield* config.table.Tag;
         const tableName = tableConfig.name;
@@ -687,7 +834,8 @@ export const makeStream = (config) => {
         // Clock-backed timestamp (deterministic under TestClock; wall-clock in prod).
         const nowDateTime = yield* DateTime.now;
         const now = DateTime.formatIso(nowDateTime);
-        // Validate and encode metadata to wire form if schema provided
+        // Validate and encode metadata to wire form if schema provided. Shared
+        // by every event; per-event `eventMetadata` is encoded in the loop below.
         let encodedMetadata;
         if (options?.metadata !== undefined && metadataSchema) {
             const encoded = yield* encodeToWire(metadataSchema, options.metadata, "EventStore.append.metadata");
@@ -711,7 +859,25 @@ export const makeStream = (config) => {
             // Inject _tag for plain Schema.Class events; Schema.TaggedClass
             // events already carry _tag in their encoded form, which wins.
             const eventData = { _tag: evtType, ...wire };
-            const item = {
+            // This event's own metadata entry (#144), encoded as `metadata`
+            // is; an `undefined` entry writes no metadata attribute.
+            let itemMetadata = encodedMetadata;
+            if (eventMetadata !== undefined) {
+                const entry = eventMetadata[i];
+                itemMetadata =
+                    entry === undefined
+                        ? undefined
+                        : metadataSchema
+                            ? (yield* encodeToWire(metadataSchema, entry, `EventStore.append.eventMetadata[${i}]`))
+                            : entry;
+            }
+            // This event's own timestamp (#144), or the append's `now`.
+            // `formatIso` renders the UTC instant, so a zoned DateTime is
+            // stored in the same format as `now`.
+            const eventTimestamp = eventTimestamps?.[i];
+            // Exactly the table key and EVENT_ITEM_ATTRIBUTES — what a
+            // "withoutMetadata" stream index projects — checked by the type.
+            const envelope = {
                 pk,
                 sk: composeEventSk(version),
                 __edd_e__: entityType,
@@ -719,10 +885,11 @@ export const makeStream = (config) => {
                 version,
                 eventType: evtType,
                 data: eventData,
-                timestamp: now,
+                timestamp: eventTimestamp === undefined ? now : DateTime.formatIso(eventTimestamp),
             };
-            if (encodedMetadata !== undefined) {
-                item.metadata = encodedMetadata;
+            const item = { ...envelope };
+            if (itemMetadata !== undefined) {
+                item.metadata = itemMetadata;
             }
             // Stream indexes (#140): the derived key, stored raw, and for a
             // GSI the stream's partition key. The attributes are part of the
@@ -832,10 +999,11 @@ export const makeStream = (config) => {
          */
         const layout = (additional) => {
             const items = [];
-            const targets = [];
+            // What names each item, so the targets are built only on failure.
+            const naming = [];
             const pushStreamItem = (item, type, source) => {
                 items.push(item);
-                targets.push(transactItemTarget(item, tableName, ["pk", "sk"], type, source));
+                naming.push(() => [transactItemTarget(item, tableName, ["pk", "sk"], type, source)]);
             };
             if (contiguityCheck !== undefined) {
                 pushStreamItem(contiguityCheck, entityType, "the version-contiguity check");
@@ -845,7 +1013,7 @@ export const makeStream = (config) => {
                 pushStreamItem(item, entityType, `the event at version ${expectedVersion + i + 1}`);
             }
             items.push(...additional.items);
-            targets.push(...additional.targets);
+            naming.push(additional.targets);
             const sentinelIndex = sentinelPut === undefined ? -1 : items.length;
             if (sentinelPut !== undefined) {
                 pushStreamItem(sentinelPut, entityType, "the idempotency sentinel");
@@ -853,9 +1021,11 @@ export const makeStream = (config) => {
             if (snapshotPut !== undefined) {
                 pushStreamItem(snapshotPut, snapshotEntityType, "the inline snapshot");
             }
+            let targets;
             return {
                 items,
-                targets,
+                // Built once, on failure: a diagnosis's target is found by identity.
+                targets: () => (targets ??= naming.flatMap((name) => name())),
                 guardCount,
                 eventCount: eventItems.length,
                 additional,
@@ -871,25 +1041,11 @@ export const makeStream = (config) => {
             // `Transaction.transactWrite` uses, so the two APIs cannot drift.
             const additional = yield* buildTransactWriteItems(additionalOps, "EventStore.append.additionalItems");
             const tx = layout(additional);
-            // Authoritative cap check: one additional op can compile to several
-            // items (#113), so the pre-flight lower bound above is not sufficient.
-            // Reporting the EXPANDED count is the point — "you passed 40 items"
-            // when the caller passed 30 ops is baffling without it.
-            if (tx.items.length > TRANSACT_WRITE_ITEMS_LIMIT) {
-                return yield* new AppendTooLarge({
-                    streamName: config.streamName,
-                    streamId: streamIdStr,
-                    count: tx.items.length,
-                    limit: TRANSACT_WRITE_ITEMS_LIMIT,
-                });
-            }
-            // Checked before anything is sent: one op per item — an additional
-            // item repeating an event, the contiguity check, the idempotency
-            // sentinel or the inline snapshot is refused, as additional items
-            // repeating each other are — and the transaction within DynamoDB's
-            // 4 MB (#133).
-            yield* refuseRepeatedItems(tx.targets, "EventStore.append");
-            yield* refuseOversizedTransaction(tx.items, tx.targets, "EventStore.append");
+            // DynamoDB's rules — one operation per item (an additional item
+            // repeating an event, the contiguity check, the idempotency sentinel
+            // or the inline snapshot, or another additional item), 100 items,
+            // 4 MB, 400 KB per item, 1024-byte sort keys — are not pre-checked:
+            // `sendAppendTransaction` diagnoses DynamoDB's rejection (#144).
             const outcome = yield* sendAppendTransaction(client, tx, streamIdStr, idempotency?.commandId);
             if (outcome === undefined) {
                 return { version: expectedVersion + events.length, events };
@@ -965,8 +1121,7 @@ export const makeStream = (config) => {
             state: encoded,
             timestamp: now,
         };
-        yield* client
-            .putItem({
+        const put = {
             TableName: tableName,
             Item: toAttributeMap(item),
             // Monotonic: never regress the cache. Losing this race is a no-op,
@@ -974,8 +1129,21 @@ export const makeStream = (config) => {
             ConditionExpression: "attribute_not_exists(#pk) OR #asOfVersion < :asOfVersion",
             ExpressionAttributeNames: { "#pk": "pk", "#asOfVersion": "asOfVersion" },
             ExpressionAttributeValues: toAttributeMap({ ":asOfVersion": asOfVersion }),
-        })
-            .pipe(Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.void));
+        };
+        yield* client.putItem(put).pipe(Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.void), 
+        // An oversized snapshot is DynamoDB's to reject (#144); named here.
+        diagnoseFailure({
+            sent: () => ({
+                _tag: "Item",
+                item: { Put: put },
+                target: () => transactItemTarget({ Put: put }, tableName, ["pk", "sk"], snapshotEntityType, "the snapshot"),
+            }),
+            keys: () => ({ partition: ["pk"], sort: ["sk"] }),
+            rewrite: (diagnosis, original) => diagnosedValidationError(diagnosis, original, {
+                operation: "EventStore.writeSnapshot",
+                entityType: snapshotEntityType,
+            }),
+        }));
     });
     /**
      * Decode a stored snapshot item. A snapshot that fails to decode through the
@@ -1178,14 +1346,63 @@ export const makeStream = (config) => {
             pkValue: composeStreamPk(streamId),
             skField: idx.sk,
             entityTypes: [entityType],
-            decoder: (raw) => decodeStreamEvent(raw),
+            decoder: indexDecoder(idx),
             resolveTableName: config.table.Tag.useSync((tc) => tc.name),
-            // A GSI is read only eventually consistently: `Query.consistentRead`
-            // on it is refused before anything is sent.
-            globalIndex: idx.type === "gsi",
+            // DynamoDB's rejection of the key condition (an empty bound, a reversed
+            // `between`) is named against the stream index; so, as for every
+            // query, is a consistent read of a GSI (#144).
+            keyConditionDiagnosis: {
+                operation: "EventStore.readIndex",
+                label: `EventStream "${config.streamName}" index "${idx.name}"`,
+            },
             keyFields: [idx.pk, idx.sk, "pk", "sk"],
+            // A "keys" index holds no events: an LSI has DynamoDB fetch them
+            // (`Select: ALL_ATTRIBUTES`), a GSI fetches each page's with
+            // `BatchGetItem` on the table key.
+            ...(idx.projection === "keys"
+                ? {
+                    hydration: idx.type === "lsi"
+                        ? { _tag: "Fetch" }
+                        : { _tag: "BatchGet", tableKey: ["pk", "sk"] },
+                }
+                : {}),
         });
     };
+    /**
+     * @internal The decoder of events read through `idx`.
+     *
+     * - `"withoutMetadata"` ignores any `metadata` on the row (an index deployed
+     *   wider than declared still carries it), so the value matches the type.
+     * - `"all"` / `"withoutMetadata"`: a decode failure on a row that lacks an
+     *   attribute the declared projection guarantees is diagnosed as the
+     *   deployed index projecting less than declared — a `ValidationError`
+     *   (`operation: "EventStore.index.decode"`) naming the index, the original
+     *   error kept as its cause. Anything else passes through unchanged.
+     * - `"keys"` decodes items fetched from the table, so a missing attribute
+     *   there is not a projection problem: failures pass through.
+     */
+    const indexDecoder = (idx) => (raw) => {
+        if (idx.projection === "keys")
+            return decodeStreamEvent(raw);
+        let row = raw;
+        if (idx.projection === "withoutMetadata" && raw.metadata !== undefined) {
+            row = { ...raw };
+            delete row.metadata;
+        }
+        return decodeStreamEvent(row).pipe(Effect.mapError((error) => {
+            const missing = PROJECTED_ENVELOPE_ATTRIBUTES.filter((name) => row[name] === undefined);
+            if (missing.length === 0)
+                return error;
+            return new ValidationError({
+                entityType,
+                operation: "EventStore.index.decode",
+                cause: withCause(`Stream index "${idx.name}" (physical "${idx.index}") is declared ` +
+                    `projection: "${idx.projection}", but its rows lack ${missing.join(", ")}: the ` +
+                    "deployed index likely projects less than declared. Deploy the Projection " +
+                    "EventStore.indexDefinitions emits for it.", error),
+            });
+        }));
+    };
     const readIndex = (name, streamId, options) => Effect.gen(function* () {
         const refuse = (cause) => new ValidationError({ entityType, operation: "EventStore.readIndex", cause });
         const invalidCondition = invalidIndexKeyCondition(options);
@@ -1298,14 +1515,43 @@ export const bind = (stream) => Effect.gen(function* () {
             : (id, floorVersion, options) => provide(headProbe(id, floorVersion, options)),
     };
 });
+// ---------------------------------------------------------------------------
+// EventStore.indexDefinitions — CreateTable fragments for stream indexes (#140)
+// ---------------------------------------------------------------------------
+/**
+ * @internal The `Projection` a stream index of `projection` is created with.
+ * Neither list names a key attribute: table and index keys are always
+ * projected.
+ */
+const projectionDefinition = (projection) => projection === "all"
+    ? { ProjectionType: "ALL" }
+    : {
+        ProjectionType: "INCLUDE",
+        NonKeyAttributes: projection === "keys" ? ["__edd_e__"] : [...EVENT_ITEM_ATTRIBUTES],
+    };
 /**
  * Derive the `CreateTable` fragments for the stream indexes (#140) of the given
  * streams (`EventStream` or `BoundEventStream`) — `AttributeDefinitions`,
- * `LocalSecondaryIndexes` and `GlobalSecondaryIndexes`, 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.
@@ -1313,7 +1559,6 @@ export const bind = (stream) => Effect.gen(function* () {
  * - 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
@@ -1336,12 +1581,13 @@ export const bind = (stream) => Effect.gen(function* () {
  * ```
  *
  * @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 const indexDefinitions = (...streams) => {
     const byIndex = new Map();
     for (const stream of streams) {
-        for (const [name, settings] of Object.entries(stream.indexes)) {
+        for (const [name, raw] of Object.entries(stream.indexes)) {
+            const settings = { ...raw, projection: raw.projection ?? "all" };
             const owner = `index "${name}" of stream "${stream.streamName}"`;
             const existing = byIndex.get(settings.index);
             if (existing === undefined) {
@@ -1350,14 +1596,16 @@ export const indexDefinitions = (...streams) => {
                     index: settings.index,
                     pk: settings.pk,
                     sk: settings.sk,
+                    projection: settings.projection,
                     owner,
                 });
                 continue;
             }
             if (existing.type !== settings.type ||
                 existing.pk !== settings.pk ||
-                existing.sk !== settings.sk) {
-                const describe = (s) => `${s.type} (pk "${s.pk}", sk "${s.sk}")`;
+                existing.sk !== settings.sk ||
+                existing.projection !== settings.projection) {
+                const describe = (s) => `${s.type} (pk "${s.pk}", sk "${s.sk}", projection "${s.projection}")`;
                 throw new Error(`[EDD-9067] EventStore.indexDefinitions: the physical index "${settings.index}" is ` +
                     `defined as ${describe(existing)} by ${existing.owner} and as ${describe(settings)} ` +
                     `by ${owner}.`);
@@ -1375,7 +1623,7 @@ export const indexDefinitions = (...streams) => {
                 { AttributeName: settings.pk, KeyType: "HASH" },
                 { AttributeName: settings.sk, KeyType: "RANGE" },
             ],
-            Projection: { ProjectionType: "ALL" },
+            Projection: projectionDefinition(settings.projection),
         };
         attributes.add(settings.sk);
         if (settings.type === "gsi") {
@@ -1396,13 +1644,27 @@ export const indexDefinitions = (...streams) => {
 };
 /** @internal Both `EventStream` and `BoundEventStream` carry this brand. */
 const hasEventStreamBrand = (u) => typeof u === "object" && u !== null && EventStreamTypeId in u;
-/** @internal Resolve a {@link CommandOptions.additionalItems} against a decision. */
+/** @internal Resolve a {@link CommandOptionsBase.additionalItems} against a decision. */
 const deriveAdditionalItems = (input, decision) => {
     if (typeof input !== "function")
         return Effect.succeed(input);
     const derived = input(decision);
     return Effect.isEffect(derived) ? derived : Effect.succeed(derived);
 };
+/** @internal Resolve an `eventMetadata` ({@link CommandMetadataOptions}) against a decision. */
+const deriveEventMetadata = (input, decision) => {
+    if (input === undefined)
+        return Effect.succeed(undefined);
+    const derived = input(decision);
+    return Effect.isEffect(derived) ? derived : Effect.succeed(derived);
+};
+/** @internal Resolve a {@link CommandOptionsBase.eventTimestamps} against a decision. */
+const deriveEventTimestamps = (input, decision) => {
+    if (input === undefined)
+        return Effect.succeed(undefined);
+    const derived = input(decision);
+    return Effect.isEffect(derived) ? derived : Effect.succeed(derived);
+};
 /** @internal */
 const makeCommandHandlerImpl = (decider, stream, options) => {
     // `verifySnapshot: false` is refused up front unless the stream writes its
@@ -1493,15 +1755,44 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
             for (const event of newEvents) {
                 next = decider.evolve(next, event);
             }
-            // 6. Derive the caller's items from the decision. Re-run on every
-            //    attempt (and on a re-decision), because the whole cycle is the
-            //    retried unit.
-            const additionalItems = yield* deriveAdditionalItems(callOptions?.additionalItems, {
+            // 6. Derive the caller's per-event metadata, then per-event
+            //    timestamps, then items, from the decision — in that order
+            //    (#144). Re-run on every attempt (and on a re-decision), because
+            //    the whole cycle is the retried unit.
+            const decision = {
                 events: newEvents,
                 state: next,
                 previous,
                 version: baseVersion,
-            });
+            };
+            const eventMetadata = yield* deriveEventMetadata(callOptions?.eventMetadata, decision);
+            // A supplied function must return the array — `undefined` (e.g. a
+            // block body with no `return`) is refused, not silently dropped.
+            if (callOptions?.eventMetadata !== undefined &&
+                (!Array.isArray(eventMetadata) || eventMetadata.length !== newEvents.length)) {
+                return yield* new ValidationError({
+                    entityType: stream.streamName,
+                    operation: "EventStore.commandHandler.eventMetadata",
+                    cause: `eventMetadata returned ${Array.isArray(eventMetadata) ? eventMetadata.length : "no"} ` +
+                        `entries for the decision's ${newEvents.length} events: it must return exactly ` +
+                        "one entry (or undefined) per event, in order. Nothing was written.",
+                });
+            }
+            // A function (checked before the load), returning the array or an
+            // `Effect` of it; the result of either form is checked here, so the
+            // error names the handler's option rather than `append`'s.
+            const eventTimestamps = yield* deriveEventTimestamps(callOptions?.eventTimestamps, decision);
+            if (callOptions?.eventTimestamps !== undefined) {
+                const problem = eventTimestampsProblem(eventTimestamps, newEvents.length, "eventTimestamps returned", `the decision's ${newEvents.length} events`);
+                if (problem !== undefined) {
+                    return yield* new ValidationError({
+                        entityType: stream.streamName,
+                        operation: "EventStore.commandHandler.eventTimestamps",
+                        cause: `${problem} Nothing was written.`,
+                    });
+                }
+            }
+            const additionalItems = yield* deriveAdditionalItems(callOptions?.additionalItems, decision);
             // 7. Append with optimistic concurrency, plus the caller's items, the
             //    dedup sentinel and an inline snapshot, all in one transaction.
             //    `baseVersion` equals any caller-supplied `expectedVersion` here
@@ -1509,6 +1800,10 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
             const appendOptions = {};
             if (callOptions?.metadata !== undefined)
                 appendOptions.metadata = callOptions.metadata;
+            if (eventMetadata !== undefined)
+                appendOptions.eventMetadata = eventMetadata;
+            if (eventTimestamps !== undefined)
+                appendOptions.eventTimestamps = eventTimestamps;
             if (additionalItems !== undefined)
                 appendOptions.additionalItems = additionalItems;
             if (options?.idempotency !== undefined && callOptions?.commandId !== undefined) {
@@ -1598,6 +1893,37 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
                     cause: "commandId is required when commandHandler is configured with `idempotency`.",
                 });
             }
+            // The same backstop for the exclusive metadata pair (#144), and for an
+            // `eventMetadata` or `eventTimestamps` that is not the function it must
+            // be — refused before anything is read, rather than by `append` after
+            // `decide`.
+            if (callOptions?.eventMetadata !== undefined) {
+                if (callOptions.metadata !== undefined) {
+                    return yield* new ValidationError({
+                        entityType: stream.streamName,
+                        operation: "EventStore.commandHandler.eventMetadata",
+                        cause: "metadata and eventMetadata are mutually exclusive: pass one value shared by " +
+                            "every event, or a function deriving one entry per event. Nothing was written.",
+                    });
+                }
+                if (typeof callOptions.eventMetadata !== "function") {
+                    return yield* new ValidationError({
+                        entityType: stream.streamName,
+                        operation: "EventStore.commandHandler.eventMetadata",
+                        cause: "eventMetadata must be a function of the decision: the number of events is " +
+                            "known only once `decide` has run. Nothing was written.",
+                    });
+                }
+            }
+            if (callOptions?.eventTimestamps !== undefined &&
+                typeof callOptions.eventTimestamps !== "function") {
+                return yield* new ValidationError({
+                    entityType: stream.streamName,
+                    operation: "EventStore.commandHandler.eventTimestamps",
+                    cause: "eventTimestamps must be a function of the decision: the number of events is " +
+                        "known only once `decide` has run. Nothing was written.",
+                });
+            }
             // A malformed If-Match (`NaN` from a failed parse, a negative or
             // fractional number) is a caller bug, not a conflict — refuse it before
             // reading anything.
@@ -1741,6 +2067,24 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
  * 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
@@ -1756,7 +2100,7 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
  *   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.
@@ -1766,8 +2110,8 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
  *   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.
  *