effect-dynamodb 1.25.0 → 1.27.0

package/dist/EventStore.js

@@ -15,18 +15,32 @@
  * - Stream indexes (`makeStream({ indexes })`): sub-streams ordered by a key
  *   derived from each event, on an LSI or GSI, each projecting all of the
  *   event, all but its metadata, or only its keys — `readIndex`,
- *   `query.index`, and `indexDefinitions` for the `CreateTable` fragments
+ *   `query.index`, and `indexDefinitions` for the `CreateTable` fragments.
+ *   A GSI may derive its partition too, so several streams share one
+ *   partition of it, snapshots included (#149)
  * - `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, 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 { eq } from "./internal/Expr.js";
+import { itemBytes, transactItemBytes } from "./internal/ItemSize.js";
+import { codecRequirements, currentRegistry, decodeImage, imageEntityType, runtimeCodecCheck, unregisteredCodecError, withRegistry, } from "./internal/Packed.js";
+import { createPathBuilder } from "./internal/PathBuilder.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";
@@ -41,6 +55,13 @@ 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,
@@ -128,21 +149,31 @@ const STREAM_INDEX_CONFIG_KEYS = [
     "pk",
     "sk",
     "key",
+    "partition",
+    "snapshot",
     "projection",
 ];
+/**
+ * @internal `pk = <streamPk>`: keeps one stream id's items in a partition of a
+ * stream index several streams (or stream ids) share (#149). The table's `pk`
+ * is projected into every index, whatever its projection.
+ */
+const streamPkFilter = (streamPk) => eq(createPathBuilder().pk, streamPk);
 /**
  * @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,
- *   an unknown `projection`, a member the entry type does not declare — a
- *   misspelled `projection` would otherwise silently mean `"all"`).
+ *   `pk`, an `lsi` with `pk`, `partition` or `snapshot`, an empty name, a
+ *   `key` / `partition` / `snapshot` that is not a function, a `snapshot`
+ *   without `partition` or on a stream without a snapshot config, 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
  *   attribute.
  */
-const resolveStreamIndexes = (streamName, indexes) => {
+const resolveStreamIndexes = (streamName, indexes, hasSnapshotConfig) => {
     if (indexes === undefined)
         return [];
     const fail = (code, message) => {
@@ -179,7 +210,30 @@ const resolveStreamIndexes = (streamName, indexes) => {
                 'declare type: "gsi".');
         }
         if (typeof entry.key !== "function") {
-            fail("EDD-9063", `index "${name}": key must be a function (event, version) => string | undefined.`);
+            fail("EDD-9063", `index "${name}": key must be a function (event, version, streamId) => string | undefined.`);
+        }
+        if (entry.partition !== undefined) {
+            if (type !== "gsi") {
+                fail("EDD-9063", `index "${name}": an "lsi" index is partitioned by the stream; only a "gsi" index ` +
+                    'derives its partition. Remove partition, or declare type: "gsi".');
+            }
+            if (typeof entry.partition !== "function") {
+                fail("EDD-9063", `index "${name}": partition must be a function (event, version, streamId) => string | undefined.`);
+            }
+        }
+        if (entry.snapshot !== undefined) {
+            if (typeof entry.snapshot !== "function") {
+                fail("EDD-9063", `index "${name}": snapshot must be a function (state, asOfVersion, streamId) => ` +
+                    "{ partition, key } | undefined.");
+            }
+            if (entry.partition === undefined) {
+                fail("EDD-9063", `index "${name}": snapshot requires partition — only a "gsi" index with a derived ` +
+                    "partition indexes the stream's snapshot.");
+            }
+            if (!hasSnapshotConfig) {
+                fail("EDD-9063", `index "${name}": snapshot requires the stream's snapshot config ` +
+                    "(makeStream({ snapshot: { schema } })); the stream writes no snapshot to index.");
+            }
         }
         const projection = (entry.projection ?? "all");
         if (projection !== "all" && projection !== "withoutMetadata" && projection !== "keys") {
@@ -216,11 +270,67 @@ const resolveStreamIndexes = (streamName, indexes) => {
             pk,
             sk,
             projection,
+            partition: entry.partition === undefined ? "stream" : "derived",
+            snapshot: entry.snapshot !== undefined,
             key: entry.key,
+            derivePartition: entry.partition,
+            snapshotEntry: entry.snapshot,
         });
     }
     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
 // ---------------------------------------------------------------------------
@@ -361,11 +471,20 @@ const eventTimestampsProblem = (timestamps, count, label, events) => {
  * `indexes` declares sub-streams ordered by a key derived from each event
  * (#140), on a local (default) or global secondary index. `append` writes each
  * event's derived key (and, for a GSI, the stream's partition key) on the
- * event item; snapshots and idempotency sentinels never carry them, so they
- * are never in an index. Read with {@link EventStream.readIndex} or
- * `query.index`, and create the indexes with {@link indexDefinitions}. Each
- * index's `projection` (default `"all"`) sets what it copies from each event
- * and how it is read — see {@link StreamIndexProjection}.
+ * event item. Idempotency sentinels never carry them; snapshots carry an
+ * entry only in a GSI that derives its partition and declares `snapshot`.
+ * Read with {@link EventStream.readIndex} or `query.index`, and create the
+ * indexes with {@link indexDefinitions}. Each index's `projection` (default
+ * `"all"`) sets what it copies from each event and how it is read — see
+ * {@link StreamIndexProjection}.
+ *
+ * A GSI's `partition` (#149) derives the partition from the stream id and the
+ * event instead, stored raw, so several streams declaring the same GSI write
+ * one partition of it — an order's line, payment and shipment streams under
+ * `ORDER#<orderId>`, read by one query — and its `snapshot` puts each stream's
+ * snapshot item in that partition too, in the same `Put` (so an inline
+ * snapshot enters the index in the append's own transaction). See
+ * {@link GlobalStreamIndexConfig}.
  *
  * Index attributes are written only at append time and events are never
  * rewritten. Declaring an index on a stream that already holds events, or
@@ -377,6 +496,36 @@ const eventTimestampsProblem = (timestamps, count, label, events) => {
  *
  * @example
  * ```typescript
+ * // Lines and payments of an order share `gsi1` under `ORDER#<orderId>`.
+ * const OrderLines = EventStore.makeStream({
+ *   table: EventsTable,
+ *   streamName: "OrderLine",
+ *   events: [LineAdded, LineRemoved],
+ *   streamId: { composite: ["orderId", "lineId"] },
+ *   snapshot: { schema: LineState, mode: "inline" },
+ *   indexes: {
+ *     byOrder: {
+ *       type: "gsi",
+ *       index: "gsi1",
+ *       pk: "gsi1pk",
+ *       sk: "gsi1sk",
+ *       partition: (_event, _version, streamId) => `ORDER#${streamId.orderId}`,
+ *       key: (_event, version, streamId) => `LINE#${streamId.lineId}#EVT#${pad(version)}`,
+ *       snapshot: (_state, _asOfVersion, streamId) => ({
+ *         partition: `ORDER#${streamId.orderId}`,
+ *         key: `LINE#${streamId.lineId}#STATE`,
+ *       }),
+ *     },
+ *   },
+ * })
+ *
+ * const lineEvents = yield* OrderLines.readIndex("byOrder", { orderId, lineId }, {
+ *   partition: `ORDER#${orderId}`,
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
  * const Entries = EventStore.makeStream({
  *   table: EventsTable,
  *   streamName: "Ledger",
@@ -401,10 +550,12 @@ const eventTimestampsProblem = (timestamps, count, label, events) => {
  * @throws `[EDD-9062]` when `snapshot.mode` is neither `"after-append"` nor
  *   `"inline"`.
  * @throws `[EDD-9063]` for a malformed index: a `type` other than `"lsi"` /
- *   `"gsi"`, a `gsi` without `pk`, an `lsi` with `pk`, an empty `index` / `sk`
- *   / `pk`, a `key` that is not a function, a `projection` other than
- *   `"all"` / `"withoutMetadata"` / `"keys"`, or a member an index entry does
- *   not declare (such as a misspelled `projection`, also a type error).
+ *   `"gsi"`, a `gsi` without `pk`, an `lsi` with `pk`, `partition` or
+ *   `snapshot`, an empty `index` / `sk` / `pk`, a `key` / `partition` /
+ *   `snapshot` that is not a function, a `snapshot` without `partition` or on
+ *   a stream without a `snapshot` config, 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
@@ -413,6 +564,18 @@ const eventTimestampsProblem = (timestamps, count, label, events) => {
  *   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;
@@ -463,8 +626,41 @@ 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 streamIndexes = resolveStreamIndexes(config.streamName, config.indexes, snapshot !== undefined);
     const indexSettings = {};
     for (const idx of streamIndexes) {
         indexSettings[idx.name] = {
@@ -473,8 +669,12 @@ export const makeStream = (config) => {
             pk: idx.pk,
             sk: idx.sk,
             projection: idx.projection,
+            partition: idx.partition,
+            snapshot: idx.snapshot,
         };
     }
+    /** The indexes that hold the stream's snapshot (#149). */
+    const snapshotIndexes = streamIndexes.filter((idx) => idx.snapshotEntry !== undefined);
     /** Every attribute the indexes write on an event item. */
     const indexAttributes = streamIndexes.flatMap((idx) => idx.type === "gsi" ? [idx.pk, idx.sk] : [idx.sk]);
     // Build union schema from event schemas for decoding
@@ -548,11 +748,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.
@@ -575,34 +805,61 @@ export const makeStream = (config) => {
     // append
     // ---------------------------------------------------------------------------
     /**
-     * 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`).
+     * One value an index function derives for an item (#140, #149): an event's
+     * `key` or `partition`, a string or `undefined` to leave the item out.
+     * Another type, or a function 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 and 2048 for a partition key — are not
+     * pre-checked: DynamoDB rejects the write and the rejection is diagnosed,
+     * naming the index and the item (see `sendAppendTransaction`).
      */
-    const deriveIndexKey = (idx, event, version) => Effect.try({
-        try: () => idx.key(event, version),
+    const deriveIndexValue = (idx, what, subject, derive) => Effect.try({
+        try: derive,
         catch: (cause) => new ValidationError({ entityType, operation: "EventStore.append.indexes", cause }),
     }).pipe(Effect.flatMap((derived) => {
         if (derived === undefined)
             return Effect.succeed(undefined);
-        const refuse = (problem) => Effect.fail(new ValidationError({
-            entityType,
-            operation: "EventStore.append.indexes",
-            cause: `The key of index "${idx.name}" for the event at version ${version} ${problem}. ` +
-                "Nothing was written.",
-        }));
         // 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.fail(new ValidationError({
+                entityType,
+                operation: "EventStore.append.indexes",
+                cause: `The ${what} of index "${idx.name}" for ${subject} must be a string or ` +
+                    `undefined; received ${String(derived)}. Nothing was written.`,
+            }));
         }
         return Effect.succeed(derived);
     }));
+    /**
+     * The snapshot's entry in a stream index (#149): its partition and key, or
+     * `undefined` to leave it out. Anything but an object of two strings, or an
+     * entry function that throws, is a `ValidationError` before anything is
+     * written; DynamoDB's rules on the values are its own, as for events.
+     */
+    const deriveSnapshotEntry = (idx, entry, state, streamId, asOfVersion, operation) => Effect.try({
+        try: () => entry(state, asOfVersion, streamId),
+        catch: (cause) => new ValidationError({ entityType: snapshotEntityType, operation, cause }),
+    }).pipe(Effect.flatMap((derived) => {
+        if (derived === undefined)
+            return Effect.succeed(undefined);
+        const { partition, key } = typeof derived === "object" && derived !== null
+            ? derived
+            : { partition: undefined, key: undefined };
+        if (typeof partition !== "string" || typeof key !== "string") {
+            return Effect.fail(new ValidationError({
+                entityType: snapshotEntityType,
+                operation,
+                cause: `The snapshot entry of index "${idx.name}" at version ${asOfVersion} must be ` +
+                    "{ partition: string, key: string } or undefined; received " +
+                    `${derived !== null && typeof derived === "object" ? JSON.stringify(derived) : String(derived)}. ` +
+                    "Nothing was written.",
+            }));
+        }
+        return Effect.succeed({ partition, key });
+    }));
     /**
      * Encode snapshot state to wire form through the state schema, with the
      * same `decode → encode` fallback as events and metadata. A structurally
@@ -708,42 +965,127 @@ export const makeStream = (config) => {
     };
     /**
      * 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.
+     * over-long (or empty) stream-index key OF AN EVENT OR THE INLINE SNAPSHOT
+     * — a value an index function returned — is named by its index and item,
+     * as the `indexes` option reports its other key problems (see
+     * {@link indexKeyError}). Only the stream's own items 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") {
+        if (diagnosis._tag === "KeyTooLong" || 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)
+            const isSnapshot = position >= 0 && position === tx.snapshotIndex;
+            const named = isEvent || isSnapshot
+                ? indexKeyError(diagnosis, original, isSnapshot, "the append", "EventStore.append.indexes")
                 : 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),
-                });
-            }
+            if (named !== undefined)
+                return named;
         }
         return diagnosedValidationError(diagnosis, original, {
             operation: "EventStore.append",
             entityType,
         });
     };
-    const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
+    /**
+     * An over-long or empty key value in a stream-index attribute of an event
+     * or snapshot item, named by its index and item, or `undefined` when the
+     * attribute is not one the item's indexes derive. An event carries each
+     * index's `key` (and a derived `partition`); a snapshot, each snapshot
+     * index's entry. A stream-scoped GSI's partition is the stream's own key,
+     * which no function returned: it is named as any key.
+     */
+    const indexKeyError = (diagnosis, original, isSnapshot, request, operation) => {
+        const candidates = isSnapshot ? snapshotIndexes : streamIndexes;
+        const kind = diagnosis._tag === "KeyTooLong"
+            ? diagnosis.kind
+            : candidates.some((idx) => idx.sk === diagnosis.attribute)
+                ? "sort"
+                : "partition";
+        const idx = candidates.find((candidate) => kind === "sort"
+            ? candidate.sk === diagnosis.attribute
+            : candidate.partition === "derived" && candidate.pk === diagnosis.attribute);
+        if (idx === undefined)
+            return undefined;
+        const value = isSnapshot
+            ? `The snapshot entry's ${kind === "sort" ? "key" : "partition"}`
+            : `The ${kind === "sort" ? "key" : "partition"}`;
+        const leaveOut = isSnapshot
+            ? "the snapshot function must return non-empty strings, or undefined to leave the " +
+                "snapshot out of the index."
+            : `the ${kind === "sort" ? "key" : "partition"} function must return a non-empty ` +
+                "string, or undefined to leave the event out of the index.";
+        return new ValidationError({
+            entityType: isSnapshot ? snapshotEntityType : entityType,
+            operation,
+            cause: withCause(`${value} of index "${idx.name}" for ${diagnosis.target.source} ` +
+                (diagnosis._tag === "KeyTooLong"
+                    ? `is ${diagnosis.bytes} bytes, longer than DynamoDB's ` +
+                        `${kind === "sort" ? "1024-byte limit for a sort" : "2048-byte limit for a partition"} key.`
+                    : `is an empty string, which DynamoDB does not accept as a key value; ${leaveOut}`) +
+                ` DynamoDB rejected ${request}. Nothing was written.`, original),
+        });
+    };
+    /**
+     * 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 stored bytes — with its entry in each index
+     * that holds snapshots (#149). Shared by `writeSnapshot`, the inline
+     * snapshot of `append`, and `measureSnapshot` / `measureAppend`.
+     *
+     * `eventPartitions` — the partition the append's events have in each
+     * index, by index name — is what the inline snapshot's entry must match.
+     */
+    const buildSnapshotItem = (streamId, state, asOfVersion, now, operation, eventPartitions) => 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`,
+            });
+        const item = {
+            pk: composeStreamPk(streamId),
+            sk: snapshotSk,
+            __edd_e__: snapshotEntityType,
+            streamId: composeStreamIdString(streamId),
+            asOfVersion,
+            state: stored,
+            timestamp: now,
+        };
+        // The snapshot's index entries (#149), stored raw on the item itself,
+        // so they are written by the same `Put` and count towards its size.
+        for (const idx of snapshotIndexes) {
+            const entry = yield* deriveSnapshotEntry(idx, idx.snapshotEntry, state, streamId, asOfVersion, operation);
+            if (entry === undefined)
+                continue;
+            const events = eventPartitions?.get(idx.name);
+            if (events !== undefined && events.partition !== entry.partition) {
+                return yield* new ValidationError({
+                    entityType: snapshotEntityType,
+                    operation,
+                    cause: `The inline snapshot's partition in index "${idx.name}" is ` +
+                        `${JSON.stringify(entry.partition)}, but ${events.subject} has ` +
+                        `${JSON.stringify(events.partition)}: an append's events and its inline snapshot ` +
+                        "must be in the same partition of an index. Nothing was written.",
+                });
+            }
+            item[idx.pk] = entry.partition;
+            item[idx.sk] = entry.key;
+        }
+        return toAttributeMap(item);
+    });
+    /**
+     * 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;
@@ -794,7 +1136,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);
@@ -814,7 +1156,6 @@ export const makeStream = (config) => {
         // 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 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
@@ -834,6 +1175,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);
+        // 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;
@@ -844,6 +1187,10 @@ export const makeStream = (config) => {
         else if (options?.metadata !== undefined) {
             encodedMetadata = options.metadata;
         }
+        // The partition the events have in each index that derives one (#149),
+        // by index name, with the first event that has it: the events and the
+        // inline snapshot of one append must agree.
+        const eventPartitions = new Map();
         // Build the event puts — one Put per event, each with attribute_not_exists(pk).
         // Events are encoded to wire form through their schema (codec symmetry
         // with the read path, which decodes through the same schema), so this is
@@ -859,6 +1206,16 @@ 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 };
+            // 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;
@@ -884,7 +1241,7 @@ export const makeStream = (config) => {
                 streamId: streamIdStr,
                 version,
                 eventType: evtType,
-                data: eventData,
+                data: storedData,
                 timestamp: eventTimestamp === undefined ? now : DateTime.formatIso(eventTimestamp),
             };
             const item = { ...envelope };
@@ -892,15 +1249,39 @@ export const makeStream = (config) => {
                 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
-            // event item itself, so they count towards the size checks.
+            // GSI the stream's partition key — or the derived partition, raw
+            // too (#149). The attributes are part of the event item itself,
+            // so they count towards the size checks. Both functions run for
+            // every event, so each one's contract is checked on every event.
+            const subject = `the event at version ${version}`;
             for (const idx of streamIndexes) {
-                const derived = yield* deriveIndexKey(idx, event, version);
-                if (derived === undefined)
+                const derived = yield* deriveIndexValue(idx, "key", subject, () => idx.key(event, version, streamId));
+                let partition = pk;
+                if (idx.derivePartition !== undefined) {
+                    const derivePartition = idx.derivePartition;
+                    partition = yield* deriveIndexValue(idx, "partition", subject, () => derivePartition(event, version, streamId));
+                    if (partition !== undefined) {
+                        const first = eventPartitions.get(idx.name);
+                        if (first === undefined) {
+                            eventPartitions.set(idx.name, { partition, subject });
+                        }
+                        else if (first.partition !== partition) {
+                            return yield* new ValidationError({
+                                entityType,
+                                operation: "EventStore.append.indexes",
+                                cause: `The partition of index "${idx.name}" for ${subject} is ` +
+                                    `${JSON.stringify(partition)}, but ${first.subject} has ` +
+                                    `${JSON.stringify(first.partition)}: every event of one append must be ` +
+                                    "in the same partition of an index. Nothing was written.",
+                            });
+                        }
+                    }
+                }
+                if (derived === undefined || partition === undefined)
                     continue;
                 item[idx.sk] = derived;
                 if (idx.type === "gsi")
-                    item[idx.pk] = pk;
+                    item[idx.pk] = partition;
             }
             return {
                 Put: {
@@ -931,8 +1312,7 @@ export const makeStream = (config) => {
                         cause,
                     }),
                 });
-                sentinel[resolveTtlAttributeName(tableConfig)] =
-                    DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
+                sentinel[ttlAttribute] = DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
             }
             sentinelPut = {
                 Put: {
@@ -943,21 +1323,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(streamId, snapshotState, expectedVersion + events.length, now, "EventStore.append.snapshot", eventPartitions),
                 },
             };
         }
@@ -982,6 +1355,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)
@@ -1018,6 +1409,7 @@ export const makeStream = (config) => {
             if (sentinelPut !== undefined) {
                 pushStreamItem(sentinelPut, entityType, "the idempotency sentinel");
             }
+            const snapshotIndex = snapshotPut === undefined ? -1 : items.length;
             if (snapshotPut !== undefined) {
                 pushStreamItem(snapshotPut, snapshotEntityType, "the inline snapshot");
             }
@@ -1030,6 +1422,7 @@ export const makeStream = (config) => {
                 eventCount: eventItems.length,
                 additional,
                 sentinelIndex,
+                snapshotIndex,
                 expectedVersion,
             };
         };
@@ -1045,7 +1438,9 @@ export const makeStream = (config) => {
             // 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).
+            // `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 };
@@ -1055,6 +1450,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(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. */
@@ -1111,19 +1573,12 @@ 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,
-        };
+        // Packed per `snapshot.storedAs` (#147): the diagnosis below measures
+        // the stored bytes.
+        const item = yield* buildSnapshotItem(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",
@@ -1138,18 +1593,31 @@ export const makeStream = (config) => {
                 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,
+            keys: () => ({
+                partition: ["pk", ...snapshotIndexes.map((idx) => idx.pk)],
+                sort: ["sk", ...snapshotIndexes.map((idx) => idx.sk)],
             }),
+            // A snapshot index entry's empty or over-long value (#149) is named
+            // by its index, as an inline snapshot's is.
+            rewrite: (diagnosis, original) => (diagnosis._tag === "KeyTooLong" || diagnosis._tag === "EmptyKey"
+                ? indexKeyError(diagnosis, original, true, "the snapshot", "EventStore.writeSnapshot")
+                : undefined) ??
+                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,
@@ -1312,6 +1780,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
@@ -1323,15 +1795,44 @@ export const makeStream = (config) => {
     // Stream indexes — query.index / readIndex (#140)
     // ---------------------------------------------------------------------------
     /**
-     * A query of one stream index, scoped to the stream's partition: the LSI
-     * shares the table's `pk`; a GSI's `pk` attribute carries the same value.
-     * No sort-key condition — the index holds only this stream's indexed events
-     * under that key; `Query.where` narrows the derived-key range.
+     * @internal Why `partition` cannot be passed for index `name`, or
+     * `undefined` when it can: required (a string) for an index that derives
+     * its partition (#149), refused for any other. Unreachable through the
+     * types. An unknown name is left to {@link buildIndexQuery}.
+     */
+    const invalidIndexPartition = (name, partition) => {
+        const idx = streamIndexes.find((candidate) => candidate.name === name);
+        if (idx === undefined)
+            return undefined;
+        if (idx.partition === "derived") {
+            return typeof partition === "string"
+                ? undefined
+                : `Index "${name}" derives its partition: pass the partition to read as ` +
+                    `options.partition (a string); received ${String(partition)}.`;
+        }
+        return partition === undefined
+            ? undefined
+            : `Index "${name}" is scoped to the stream; it takes no partition.`;
+    };
+    /**
+     * A query of one stream index. A stream-scoped index is queried in the
+     * stream's partition: the LSI shares the table's `pk`; a GSI's `pk`
+     * attribute carries the same value. No sort-key condition — the index holds
+     * only this stream's indexed events under that key; `Query.where` narrows
+     * the derived-key range.
+     *
+     * An index that derives its partition (#149) is queried in `partition`,
+     * which other streams (and this one's other stream ids, and snapshots) may
+     * share: the `__edd_e__` filter keeps this stream's events, and a filter on
+     * the table's `pk` — projected by every index — keeps `streamId`'s.
      *
      * @throws `[EDD-9066]` for a name the stream does not declare (unreachable
      *   through the types).
+     * @throws `[EDD-9080]` for a missing `partition` on an index that derives
+     *   it, or one passed to an index that does not (unreachable through the
+     *   types).
      */
-    const buildIndexQuery = (name, streamId) => {
+    const buildIndexQuery = (name, streamId, partition) => {
         const idx = streamIndexes.find((candidate) => candidate.name === name);
         if (idx === undefined) {
             throw new Error(`[EDD-9066] EventStream "${config.streamName}": unknown index "${String(name)}". ` +
@@ -1339,14 +1840,23 @@ export const makeStream = (config) => {
                     ? "The stream declares no indexes."
                     : `Declared: ${streamIndexes.map((candidate) => `"${candidate.name}"`).join(", ")}.`));
         }
-        return Query.make({
+        const partitionProblem = invalidIndexPartition(name, partition);
+        if (partitionProblem !== undefined) {
+            throw new Error(`[EDD-9080] EventStream "${config.streamName}": ${partitionProblem}`);
+        }
+        const streamPk = composeStreamPk(streamId);
+        const query = Query.make({
             tableName: "",
             indexName: idx.index,
             pkField: idx.pk,
-            pkValue: composeStreamPk(streamId),
+            pkValue: idx.partition === "derived" ? partition : streamPk,
             skField: idx.sk,
             entityTypes: [entityType],
             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),
             // DynamoDB's rejection of the key condition (an empty bound, a reversed
             // `between`) is named against the stream index; so, as for every
@@ -1367,6 +1877,7 @@ export const makeStream = (config) => {
                 }
                 : {}),
         });
+        return idx.partition === "derived" ? Query.filterExpr(query, streamPkFilter(streamPk)) : query;
     };
     /**
      * @internal The decoder of events read through `idx`.
@@ -1413,7 +1924,11 @@ export const makeStream = (config) => {
         if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
             return yield* refuse(`limit must be a positive integer; received ${String(limit)}. Nothing was sent.`);
         }
-        let query = buildIndexQuery(name, streamId);
+        const partitionProblem = invalidIndexPartition(name, options?.partition);
+        if (partitionProblem !== undefined) {
+            return yield* refuse(`${partitionProblem} Nothing was sent.`);
+        }
+        let query = buildIndexQuery(name, streamId, options?.partition);
         if (options?.beginsWith !== undefined) {
             query = Query.where(query, { beginsWith: options.beginsWith });
         }
@@ -1430,7 +1945,7 @@ export const makeStream = (config) => {
     });
     const queryNamespace = {
         events: (streamId) => buildEventsQuery(streamId),
-        index: (name, streamId) => buildIndexQuery(name, streamId),
+        index: (name, streamId, options) => buildIndexQuery(name, streamId, options?.partition),
     };
     // ---------------------------------------------------------------------------
     // Return EventStream
@@ -1449,19 +1964,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),
     };
 };
 // ---------------------------------------------------------------------------
@@ -1483,6 +2002,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);
@@ -1495,6 +2019,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)),
@@ -1503,7 +2028,12 @@ export const bind = (stream) => Effect.gen(function* () {
         readFrom: (streamId, afterVersion, options) => provide(stream.readFrom(streamId, afterVersion, options)),
         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)),
+        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),
@@ -1523,12 +2053,22 @@ export const bind = (stream) => Effect.gen(function* () {
  * Neither list names a key attribute: table and index keys are always
  * projected.
  */
-const projectionDefinition = (projection) => projection === "all"
+const projectionDefinition = (projection, snapshot) => projection === "all"
     ? { ProjectionType: "ALL" }
     : {
         ProjectionType: "INCLUDE",
-        NonKeyAttributes: projection === "keys" ? ["__edd_e__"] : [...EVENT_ITEM_ATTRIBUTES],
+        NonKeyAttributes: projection === "keys"
+            ? ["__edd_e__"]
+            : snapshot
+                ? [...EVENT_ITEM_ATTRIBUTES, ...SNAPSHOT_ONLY_ATTRIBUTES].sort()
+                : [...EVENT_ITEM_ATTRIBUTES],
     };
+/**
+ * @internal The snapshot item's attributes an event item does not carry: what
+ * a `"withoutMetadata"` index that holds snapshots (#149) projects besides
+ * {@link EVENT_ITEM_ATTRIBUTES}.
+ */
+const SNAPSHOT_ONLY_ATTRIBUTES = ["asOfVersion", "state"];
 /**
  * Derive the `CreateTable` fragments for the stream indexes (#140) of the given
  * streams (`EventStream` or `BoundEventStream`) — `AttributeDefinitions`,
@@ -1543,7 +2083,7 @@ const projectionDefinition = (projection) => projection === "all"
  * | `projection` | `Projection` |
  * |---|---|
  * | `"all"` (default) | `{ ProjectionType: "ALL" }` |
- * | `"withoutMetadata"` | `{ ProjectionType: "INCLUDE", NonKeyAttributes: ["__edd_e__", "data", "eventType", "streamId", "timestamp", "version"] }` |
+ * | `"withoutMetadata"` | `{ ProjectionType: "INCLUDE", NonKeyAttributes: ["__edd_e__", "data", "eventType", "streamId", "timestamp", "version"] }` — plus `"asOfVersion"` and `"state"` when a stream declaring the index puts its snapshot in it (#149) |
  * | `"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
@@ -1554,7 +2094,12 @@ const projectionDefinition = (projection) => projection === "all"
  * 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.
+ * once — the way several streams write one GSI whose partition they derive
+ * (`partition`, #149): an order's line, payment and shipment streams under
+ * `ORDER#<orderId>`, say. Whether each declaration derives its partition or
+ * indexes its snapshot is not part of the definition: the index's key schema
+ * and projection kind are. Lists are sorted by index name, attributes by
+ * attribute name.
  *
  * - An LSI can only be created with the table, and caps the item collection
  *   of every partition key value in the table at 10 GB — entity partitions
@@ -1582,25 +2127,32 @@ const projectionDefinition = (projection) => projection === "all"
  *
  * @throws `[EDD-9067]` when two streams define the same physical index
  *   differently (another type, other key attributes, or another projection).
+ *   Whether a declaration derives its partition or indexes its snapshot is not
+ *   part of the index's definition: streams that differ only there share it.
  */
 export const indexDefinitions = (...streams) => {
+    /** Per physical index: its definition, its first declarer, and whether any declarer indexes snapshots. */
     const byIndex = new Map();
     for (const stream of streams) {
         for (const [name, raw] of Object.entries(stream.indexes)) {
-            const settings = { ...raw, projection: raw.projection ?? "all" };
+            const settings = {
+                type: raw.type,
+                index: raw.index,
+                pk: raw.pk,
+                sk: raw.sk,
+                projection: raw.projection ?? "all",
+            };
+            const snapshot = raw.snapshot === true;
             const owner = `index "${name}" of stream "${stream.streamName}"`;
             const existing = byIndex.get(settings.index);
             if (existing === undefined) {
-                byIndex.set(settings.index, {
-                    type: settings.type,
-                    index: settings.index,
-                    pk: settings.pk,
-                    sk: settings.sk,
-                    projection: settings.projection,
-                    owner,
-                });
+                byIndex.set(settings.index, { ...settings, owner, snapshot });
                 continue;
             }
+            // Several streams writing one GSI they derive the partition of (#149)
+            // is the point: one declaration indexing snapshots and another not
+            // still share it, and the projection covers the snapshots.
+            existing.snapshot ||= snapshot;
             if (existing.type !== settings.type ||
                 existing.pk !== settings.pk ||
                 existing.sk !== settings.sk ||
@@ -1623,7 +2175,7 @@ export const indexDefinitions = (...streams) => {
                 { AttributeName: settings.pk, KeyType: "HASH" },
                 { AttributeName: settings.sk, KeyType: "RANGE" },
             ],
-            Projection: projectionDefinition(settings.projection),
+            Projection: projectionDefinition(settings.projection, settings.snapshot),
         };
         attributes.add(settings.sk);
         if (settings.type === "gsi") {