effect-dynamodb 1.24.0 → 1.26.0

package/dist/EventStore.js

@@ -13,20 +13,32 @@
  *   `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 { Compression } from "@effect-dynamodb/schema/Compression.js";
+import { isPackedConfig } from "@effect-dynamodb/schema/DynamoModel.js";
 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 { isDispatchEligible, packedShape, packValue, unpackStoredSync, } from "@effect-dynamodb/schema/internal/PackedCodec.js";
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
-import { DateTime, Effect, Function, Option, Pipeable, Result, Schedule, Schema, } from "effect";
+import { Context, 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 { itemBytes, transactItemBytes } from "./internal/ItemSize.js";
+import { codecRequirements, currentRegistry, decodeImage, imageEntityType, runtimeCodecCheck, unregisteredCodecError, withRegistry, } from "./internal/Packed.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";
@@ -39,36 +51,26 @@ import { DEFAULT_TTL_ATTRIBUTE_NAME, resolveTtlAttributeName, } from "./Table.js
  *
  * @internal
  */
+/** The codecs a stream's packed `data` / `state` name (`[EDD-9078]` when unregistered). */
+const streamCodecRequirements = (streamName, storedAs) => codecRequirements(`stream "${streamName}"`, [
+    ["data", storedAs.data],
+    ["state", storedAs.state],
+]);
+/** The attributes a stream image reads by stored form: event `data` only. */
+const DATA_ATTRIBUTES = ["data"];
 const EventEnvelope = Schema.Struct({
     streamId: Schema.String,
     version: Schema.Number,
     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 +78,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 +138,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 +172,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 +198,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,11 +232,64 @@ const resolveStreamIndexes = (streamName, indexes) => {
             index,
             pk,
             sk,
+            projection,
             key: entry.key,
         });
     }
     return resolved;
 };
+/**
+ * @internal Validate `makeStream({ storedAs })` and `snapshot.storedAs` at
+ * definition time (#147).
+ *
+ * @throws `[EDD-9079]` for a `storedAs` that is not an object, a key other
+ *   than `data`, or a value that is not a `DynamoModel.Packed(...)` config.
+ * @throws `[EDD-9073]` for a packed snapshot whose state schema's encoded side
+ *   is not object- or array-shaped.
+ */
+const resolveStreamStorage = (streamName, storedAs, snapshot) => {
+    const fail = (code, message) => {
+        throw new Error(`[${code}] EventStream "${streamName}": ${message}`);
+    };
+    const describe = (value) => value === null
+        ? "null"
+        : typeof value === "object"
+            ? "an object that is not a DynamoModel.Packed(...) config"
+            : `${typeof value} ${JSON.stringify(value)}`;
+    let data;
+    if (storedAs !== undefined) {
+        if (typeof storedAs !== "object" || storedAs === null || Array.isArray(storedAs)) {
+            fail("EDD-9079", `storedAs must be an object { data?: DynamoModel.Packed(...) }; received ${describe(storedAs)}.`);
+        }
+        for (const [key, value] of Object.entries(storedAs)) {
+            if (key !== "data") {
+                fail("EDD-9079", `storedAs declares "${key}", but only "data" can be stored packed` +
+                    (key === "metadata" ? " — event metadata always stays a map" : "") +
+                    (key === "state" ? " — pack snapshot state with snapshot.storedAs" : "") +
+                    ".");
+            }
+            if (value !== undefined && !isPackedConfig(value)) {
+                fail("EDD-9079", `storedAs.data must be a DynamoModel.Packed(...) config; received ${describe(value)}.`);
+            }
+            data = value;
+        }
+    }
+    let state;
+    const snapshotStoredAs = snapshot?.storedAs;
+    if (snapshot !== undefined && snapshotStoredAs !== undefined) {
+        if (!isPackedConfig(snapshotStoredAs)) {
+            fail("EDD-9079", `snapshot.storedAs must be a DynamoModel.Packed(...) config; received ` +
+                `${describe(snapshotStoredAs)}.`);
+        }
+        const shape = packedShape(snapshot.schema);
+        if (shape._tag === "Refused") {
+            fail("EDD-9073", `snapshot.storedAs packs the snapshot state, but the state schema cannot be packed: ` +
+                `${shape.reason}. Packed storage holds object- or array-shaped JSON.`);
+        }
+        state = snapshotStoredAs;
+    }
+    return { data, state };
+};
 // ---------------------------------------------------------------------------
 // EventStreamTypeId
 // ---------------------------------------------------------------------------
@@ -248,6 +344,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 +432,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 +471,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
@@ -356,6 +482,18 @@ const unverifiedSnapshotRefusal = (streamName, settings, operation) => settings
  *   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 const makeStream = (config) => {
     const schema = config.table.schema;
@@ -406,11 +544,50 @@ export const makeStream = (config) => {
     const snapshotSettings = snapshot === undefined
         ? undefined
         : { mode: snapshot.mode ?? "after-append", every: snapshot.every };
+    // Packed storage (EDD-9079, EDD-9073) — validated at definition time.
+    const storage = resolveStreamStorage(config.streamName, config.storedAs, snapshot);
+    /** Event `data` packing, or `undefined` for the native map. */
+    const dataStoredAs = storage.data;
+    /** Snapshot `state` packing, or `undefined` for the native map. */
+    const stateStoredAs = storage.state;
+    /**
+     * Whether a snapshot's stored `state` is read by its stored form: when it is
+     * configured packed, or when its schema's encoded side is object- or
+     * array-shaped (a native state is then never `S` / `B`), so a stream that
+     * turned packing off still reads its packed snapshot.
+     */
+    const stateDispatch = snapshot !== undefined && (stateStoredAs !== undefined || isDispatchEligible(snapshot.schema));
+    /**
+     * The first operation run with a given compressor registry checks that it
+     * has every codec `storedAs` names (`[EDD-9078]`, a defect): the stream
+     * meets values compressed with them on every read and write. `bind` checks
+     * the registry it captures up front instead.
+     */
+    const codecCheck = runtimeCodecCheck(`EventStore (first use of stream "${config.streamName}")`, streamCodecRequirements(config.streamName, storage));
+    const checked = (op) => codecCheck === undefined ? op : (...args) => Effect.andThen(codecCheck, op(...args));
+    /** The `[EDD-9076]` guard for queries of a stream whose `data` is packed. */
+    const dataGuards = dataStoredAs === undefined
+        ? []
+        : [
+            {
+                attribute: "data",
+                owner: `EventStream "${config.streamName}"`,
+                storedAs: dataStoredAs,
+                alternative: (path) => `Use Query.filterBy((event) => /* test event.${path} */), which runs on the ` +
+                    "decoded event inside the same paging loop.",
+            },
+        ];
     // Stream indexes (#140) — validated at definition time (EDD-9063..9065).
     const streamIndexes = resolveStreamIndexes(config.streamName, config.indexes);
     const indexSettings = {};
     for (const idx of streamIndexes) {
-        indexSettings[idx.name] = { type: idx.type, index: idx.index, pk: idx.pk, sk: idx.sk };
+        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]);
@@ -485,11 +662,41 @@ export const makeStream = (config) => {
     // Decode a raw DynamoDB item → StreamEvent<TEvent>
     // ---------------------------------------------------------------------------
     const decodeEnvelope = Schema.decodeUnknownEffect(EventEnvelope);
+    /**
+     * An event's stored `data` → its wire form (plain JSON), by the stored
+     * form. A native value costs one `typeof` check.
+     */
+    const unpackData = (stored, operation) => typeof stored === "string" || stored instanceof Uint8Array
+        ? withRegistry((registry) => unpackStoredSync(stored, registry, { entityType, operation }, "data"))
+        : Effect.succeed(stored);
+    /**
+     * A raw event row (`Query.select`) with its `data` — when projected — as
+     * plain parsed JSON, whatever its stored form (R3: a stream that switched
+     * encoding holds a mix). Never schema-decoded. Only this stream's event
+     * rows are read: a row of another type (`Query.ignoreOwnership`) is handed
+     * back untouched, its `__edd_e__` borrowed for the check and stripped again.
+     * In place, so the strip reaches the row returned.
+     */
+    const rawEventRow = Object.assign((raw) => {
+        const stored = raw.data;
+        if (raw.__edd_e__ !== entityType)
+            return Effect.succeed(raw);
+        if (typeof stored !== "string" && !(stored instanceof Uint8Array))
+            return Effect.succeed(raw);
+        return Effect.map(unpackData(stored, "EventStore.select"), (data) => {
+            raw.data = data;
+            return raw;
+        });
+    }, { reads: ["__edd_e__"], attributes: ["data"] });
     const decodeStreamEvent = (raw) => Effect.gen(function* () {
         const toValidationError = (operation) => (cause) => new ValidationError({ entityType, operation, cause });
         const envelope = yield* decodeEnvelope(raw).pipe(Effect.mapError(toValidationError("EventStore.decode")));
+        // `data` is read by its stored form (#147): a native map as it is, a
+        // JSON string (`S`) parsed, compressed binary (`B`) decompressed and
+        // parsed — whatever the stream's current `storedAs` says.
+        const wireData = yield* unpackData(raw.data, "EventStore.decode");
         const decoder = Schema.decodeUnknownEffect(eventUnion);
-        const data = yield* decoder(raw.data).pipe(Effect.mapError(toValidationError("EventStore.decode")));
+        const data = yield* decoder(wireData).pipe(Effect.mapError(toValidationError("EventStore.decode")));
         // Metadata is decoded through its schema when the stream declares one —
         // the mirror of the encode performed by `append`. Streams without a
         // metadata schema surface the stored attribute map untouched.
@@ -512,10 +719,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 +738,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 +761,204 @@ 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,
         }));
-    }));
-    const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
+    };
+    /**
+     * 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,
+        });
+    };
+    /**
+     * The snapshot item for `state` at `asOfVersion`: the state encoded through
+     * the state schema, then packed per `snapshot.storedAs` (#147) — so every
+     * size measured afterwards is the stored size. Shared by `writeSnapshot`,
+     * the inline snapshot of `append`, and `measureSnapshot` / `measureAppend`.
+     */
+    const buildSnapshotItem = (pk, streamIdStr, state, asOfVersion, now, operation) => Effect.gen(function* () {
+        const encoded = yield* encodeSnapshotState(state, operation);
+        const stored = stateStoredAs === undefined
+            ? encoded
+            : yield* packValue(stateStoredAs, encoded, yield* currentRegistry, {
+                entityType: snapshotEntityType,
+                attribute: "state",
+                operation: `${operation}.packed`,
+            });
+        return toAttributeMap({
+            pk,
+            sk: snapshotSk,
+            __edd_e__: snapshotEntityType,
+            streamId: streamIdStr,
+            asOfVersion,
+            state: stored,
+            timestamp: now,
+        });
+    });
+    /**
+     * The stream's own items of an append — everything but the caller's
+     * `additionalItems` — validated and built exactly as `append` sends them.
+     * Shared by `append` and `measureAppend`, so a measurement is the size of
+     * the request `append` would send. `undefined` for an append with nothing
+     * to write (the historical no-op).
+     */
+    const buildAppend = (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 })");
         }
@@ -626,7 +970,7 @@ export const makeStream = (config) => {
             additionalOps.length === 0 &&
             idempotency === undefined &&
             snapshotState === undefined) {
-            return { version: expectedVersion, events: [] };
+            return undefined;
         }
         // Resolve stream ID string for storage (join composites)
         const streamIdStr = composeStreamIdString(streamId);
@@ -641,33 +985,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;
         // A custom TTL attribute is only known at runtime. An index key attribute
@@ -687,7 +1009,10 @@ 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
+        // The compressor registry in scope, for packed `data` / `state` (#147).
+        const registry = yield* currentRegistry;
+        // 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,18 +1036,47 @@ 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 = {
+            // Packed `data` (#147): one JSON string, or compressed binary at
+            // or over the threshold when that is smaller — packed here, before
+            // marshalling, so every size measured afterwards is stored bytes.
+            const storedData = dataStoredAs === undefined
+                ? eventData
+                : yield* packValue(dataStoredAs, eventData, registry, {
+                    entityType,
+                    attribute: "data",
+                    operation: "EventStore.append.packed",
+                });
+            // 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,
                 streamId: streamIdStr,
                 version,
                 eventType: evtType,
-                data: eventData,
-                timestamp: now,
+                data: storedData,
+                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
@@ -764,8 +1118,7 @@ export const makeStream = (config) => {
                         cause,
                     }),
                 });
-                sentinel[resolveTtlAttributeName(tableConfig)] =
-                    DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
+                sentinel[ttlAttribute] = DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
             }
             sentinelPut = {
                 Put: {
@@ -776,21 +1129,14 @@ export const makeStream = (config) => {
             };
         }
         // The inline snapshot (#138): unconditional — see AppendOptions.snapshot.
+        // Packed per `snapshot.storedAs` (#147), so the transaction-size and
+        // item-size diagnosis count its stored bytes.
         let snapshotPut;
         if (snapshotState !== undefined) {
-            const encoded = yield* encodeSnapshotState(snapshotState, "EventStore.append.snapshot");
             snapshotPut = {
                 Put: {
                     TableName: tableName,
-                    Item: toAttributeMap({
-                        pk,
-                        sk: snapshotSk,
-                        __edd_e__: snapshotEntityType,
-                        streamId: streamIdStr,
-                        asOfVersion: expectedVersion + events.length,
-                        state: encoded,
-                        timestamp: now,
-                    }),
+                    Item: yield* buildSnapshotItem(pk, streamIdStr, snapshotState, expectedVersion + events.length, now, "EventStore.append.snapshot"),
                 },
             };
         }
@@ -815,6 +1161,24 @@ export const makeStream = (config) => {
                 },
             }
             : undefined;
+        const parts = {
+            tableName,
+            streamIdStr,
+            contiguityCheck,
+            eventItems,
+            sentinelPut,
+            snapshotPut,
+        };
+        return parts;
+    });
+    const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
+        const additionalOps = options?.additionalItems ?? [];
+        const idempotency = options?.idempotency;
+        const parts = yield* buildAppend(streamId, events, expectedVersion, options);
+        if (parts === undefined)
+            return { version: expectedVersion, events: [] };
+        const { tableName, streamIdStr, contiguityCheck, eventItems, sentinelPut, snapshotPut } = parts;
+        const client = yield* DynamoClient;
         /**
          * Lay out the append's one transaction — see {@link AppendTransaction}:
          *   [0, C)                version-contiguity ConditionCheck (C is 0 or 1)
@@ -832,10 +1196,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 +1210,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 +1218,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 +1238,13 @@ 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). The
+            // items carry packed `data` / `state` as stored (#147), so the
+            // diagnosis attributes stored bytes.
             const outcome = yield* sendAppendTransaction(client, tx, streamIdStr, idempotency?.commandId);
             if (outcome === undefined) {
                 return { version: expectedVersion + events.length, events };
@@ -899,6 +1254,73 @@ export const makeStream = (config) => {
         return yield* Effect.fail(lost);
     });
     // ---------------------------------------------------------------------------
+    // measureAppend / measureSnapshot — caller-side size planning (#147, R1)
+    // ---------------------------------------------------------------------------
+    const measureAppend = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
+        if (options?.additionalItems !== undefined) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "EventStore.measureAppend",
+                cause: "measureAppend does not measure additionalItems (building a guarded put reads the " +
+                    "table): measure the stream's own items without them, and add the size of your " +
+                    "own items.",
+            });
+        }
+        const parts = yield* buildAppend(streamId, events, expectedVersion, options);
+        if (parts === undefined) {
+            return { events: [], sentinel: undefined, snapshot: undefined, transactionBytes: 0 };
+        }
+        const putBytes = (item) => itemBytes(item.Put?.Item ?? {});
+        const owned = [
+            ...(parts.contiguityCheck === undefined ? [] : [parts.contiguityCheck]),
+            ...parts.eventItems,
+            ...(parts.sentinelPut === undefined ? [] : [parts.sentinelPut]),
+            ...(parts.snapshotPut === undefined ? [] : [parts.snapshotPut]),
+        ];
+        const measurement = {
+            events: parts.eventItems.map(putBytes),
+            sentinel: parts.sentinelPut === undefined ? undefined : putBytes(parts.sentinelPut),
+            snapshot: parts.snapshotPut === undefined ? undefined : putBytes(parts.snapshotPut),
+            transactionBytes: owned.reduce((sum, item) => sum + transactItemBytes(item), 0),
+        };
+        return measurement;
+    });
+    const measureSnapshot = (streamId, state, asOfVersion) => Effect.gen(function* () {
+        if (snapshot === undefined)
+            return yield* snapshotUnavailable("measureSnapshot");
+        const now = DateTime.formatIso(yield* DateTime.now);
+        const item = yield* buildSnapshotItem(composeStreamPk(streamId), composeStreamIdString(streamId), state, asOfVersion, now, "EventStore.measureSnapshot");
+        return itemBytes(item);
+    });
+    // ---------------------------------------------------------------------------
+    // decodeStreamImage — DynamoDB Streams records (#147, R2)
+    // ---------------------------------------------------------------------------
+    const decodeStreamImage = (image, options) => Effect.gen(function* () {
+        const ctx = { entityType, operation: "EventStore.decodeStreamImage" };
+        // Not one of this stream's events — its snapshot, a sentinel, another
+        // stream's or an entity's item: none, decided from the raw image before
+        // anything is unmarshalled, so nothing in a foreign image can fail it.
+        if (typeof image === "object" &&
+            image !== null &&
+            !Array.isArray(image) &&
+            imageEntityType(image) !== entityType) {
+            return Option.none();
+        }
+        // In DynamoDB JSON the S / B tag says what `data` is; unmarshalled, a
+        // string that is base64 of a `B` value is told apart from JSON text.
+        const raw = yield* decodeImage(image, DATA_ATTRIBUTES, ctx);
+        const event = yield* decodeStreamEvent(raw);
+        if (options?.raw !== true)
+            return Option.some(event);
+        // `raw.data` is the wire form the decode just read: the parsed JSON of a
+        // packed value, the unmarshalled map of a native one.
+        const withRaw = {
+            ...event,
+            rawData: raw.data,
+        };
+        return Option.some(withRaw);
+    });
+    // ---------------------------------------------------------------------------
     // read
     // ---------------------------------------------------------------------------
     /** Apply {@link ReadOptions} to an event query. */
@@ -955,33 +1377,43 @@ export const makeStream = (config) => {
         const client = yield* DynamoClient;
         const { name: tableName } = yield* config.table.Tag;
         const now = DateTime.formatIso(yield* DateTime.now);
-        const encoded = yield* encodeSnapshotState(state, "EventStore.writeSnapshot");
-        const item = {
-            pk: composeStreamPk(streamId),
-            sk: snapshotSk,
-            __edd_e__: snapshotEntityType,
-            streamId: composeStreamIdString(streamId),
-            asOfVersion,
-            state: encoded,
-            timestamp: now,
-        };
-        yield* client
-            .putItem({
+        // Packed per `snapshot.storedAs` (#147): the diagnosis below measures
+        // the stored bytes.
+        const item = yield* buildSnapshotItem(composeStreamPk(streamId), composeStreamIdString(streamId), state, asOfVersion, now, "EventStore.writeSnapshot");
+        const put = {
             TableName: tableName,
-            Item: toAttributeMap(item),
+            Item: item,
             // Monotonic: never regress the cache. Losing this race is a no-op,
             // not an error — the events it summarises are already durable.
             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
      * state schema is a `ValidationError` — never silently discarded.
      */
-    const decodeSnapshotItem = (raw, operation) => Schema.decodeUnknownEffect(snapshot.schema)(raw.state).pipe(Effect.mapError((cause) => new ValidationError({ entityType: snapshotEntityType, operation, cause })), Effect.map((state) => ({
+    const decodeSnapshotItem = (raw, operation) => 
+    // `state` is read by its stored form (#147) when it may be packed — see
+    // `stateDispatch` — then decoded through the state schema as before.
+    (stateDispatch && (typeof raw.state === "string" || raw.state instanceof Uint8Array)
+        ? withRegistry((registry) => unpackStoredSync(raw.state, registry, { entityType: snapshotEntityType, operation }, "state"))
+        : Effect.succeed(raw.state)).pipe(Effect.flatMap((state) => Schema.decodeUnknownEffect(snapshot.schema)(state).pipe(Effect.mapError((cause) => new ValidationError({ entityType: snapshotEntityType, operation, cause })))), Effect.map((state) => ({
         state,
         asOfVersion: raw.asOfVersion,
         timestamp: raw.timestamp,
@@ -1144,6 +1576,10 @@ export const makeStream = (config) => {
             skField: "sk",
             entityTypes: [entityType],
             decoder: (raw) => decodeStreamEvent(raw),
+            // Raw rows (`Query.select`) carry `data` as parsed JSON, whatever its
+            // stored form, and a filter inside a packed `data` is refused (#147).
+            rawRow: rawEventRow,
+            packed: dataGuards,
             resolveTableName: config.table.Tag.useSync((tc) => tc.name),
             keyFields: ["pk", "sk"],
             // Bound to the event SK range so non-event items in the stream partition
@@ -1178,14 +1614,67 @@ export const makeStream = (config) => {
             pkValue: composeStreamPk(streamId),
             skField: idx.sk,
             entityTypes: [entityType],
-            decoder: (raw) => decodeStreamEvent(raw),
+            decoder: indexDecoder(idx),
+            // As for `query.events` (#147) — the `"keys"` hydration path decodes
+            // its fetched rows through the same hooks.
+            rawRow: rawEventRow,
+            packed: dataGuards,
             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);
@@ -1232,19 +1721,23 @@ export const makeStream = (config) => {
         streamName: config.streamName,
         eventSchema: eventUnion,
         snapshotConfig: snapshotSettings,
+        storedAs: storage,
         indexes: indexSettings,
-        writeSnapshot,
-        readSnapshot,
-        append,
-        read,
-        readFrom,
-        currentVersion,
-        readLatest,
-        readIndex,
+        writeSnapshot: checked(writeSnapshot),
+        readSnapshot: checked(readSnapshot),
+        append: checked(append),
+        read: checked(read),
+        readFrom: checked(readFrom),
+        currentVersion: checked(currentVersion),
+        readLatest: checked(readLatest),
+        readIndex: checked(readIndex),
+        measureAppend: checked(measureAppend),
+        measureSnapshot: checked(measureSnapshot),
+        decodeStreamImage: checked(decodeStreamImage),
         query: queryNamespace,
         [StreamIdFormatter]: composeStreamIdString,
-        [CommandSentinelProbe]: hasCommandSentinel,
-        [HeadAboveProbe]: headAbove,
+        [CommandSentinelProbe]: checked(hasCommandSentinel),
+        [HeadAboveProbe]: checked(headAbove),
     };
 };
 // ---------------------------------------------------------------------------
@@ -1266,6 +1759,11 @@ export const makeStream = (config) => {
  */
 export const bind = (stream) => Effect.gen(function* () {
     const ctx = yield* Effect.context();
+    // The stream meets values compressed with every codec its `storedAs`
+    // names, so the registry captured here must have them (#147).
+    const codecError = unregisteredCodecError("EventStore.bind", streamCodecRequirements(stream.streamName, stream.storedAs), Context.getOrUndefined(ctx, Compression));
+    if (codecError !== undefined)
+        throw codecError;
     const provide = (effect) => Effect.provide(effect, ctx);
     const probe = commandSentinelProbeOf(stream);
     const headProbe = headAboveProbeOf(stream);
@@ -1278,6 +1776,7 @@ export const bind = (stream) => Effect.gen(function* () {
         streamName: stream.streamName,
         eventSchema: stream.eventSchema,
         snapshotConfig: stream.snapshotConfig,
+        storedAs: stream.storedAs,
         indexes: stream.indexes,
         writeSnapshot: (streamId, state, asOfVersion) => provide(stream.writeSnapshot(streamId, state, asOfVersion)),
         readSnapshot: (streamId) => provide(stream.readSnapshot(streamId)),
@@ -1287,6 +1786,11 @@ export const bind = (stream) => Effect.gen(function* () {
         currentVersion: (streamId, options) => provide(stream.currentVersion(streamId, options)),
         readLatest: (streamId, options) => provide(stream.readLatest(streamId, options)),
         readIndex: (name, streamId, options) => provide(stream.readIndex(name, streamId, options)),
+        // The captured context carries a `Compression` registry provided where
+        // the stream was bound (#147).
+        measureAppend: (streamId, events, expectedVersion, options) => provide(stream.measureAppend(streamId, events, expectedVersion, options)),
+        measureSnapshot: (streamId, state, asOfVersion) => provide(stream.measureSnapshot(streamId, state, asOfVersion)),
+        decodeStreamImage: ((image, options) => provide(stream.decodeStreamImage(image, options))),
         query: stream.query,
         provide,
         [StreamIdFormatter]: (id) => formatStreamIdOf(stream, id),
@@ -1298,14 +1802,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 +1846,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 +1868,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 +1883,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 +1910,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 +1931,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 +2042,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 +2087,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 +2180,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 +2354,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 +2387,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 +2397,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.
  *