effect-dynamodb 1.25.0 → 1.26.0

package/dist/EventStore.js

@@ -17,16 +17,26 @@
  *   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, 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 { 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";
@@ -41,6 +51,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,
@@ -221,6 +238,58 @@ const resolveStreamIndexes = (streamName, indexes) => {
     }
     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
 // ---------------------------------------------------------------------------
@@ -413,6 +482,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,6 +544,39 @@ 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 = {};
@@ -548,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.
@@ -743,7 +887,39 @@ export const makeStream = (config) => {
             entityType,
         });
     };
-    const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
+    /**
+     * 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;
@@ -794,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);
@@ -814,7 +990,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 +1009,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;
@@ -859,6 +1036,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 +1071,7 @@ export const makeStream = (config) => {
                 streamId: streamIdStr,
                 version,
                 eventType: evtType,
-                data: eventData,
+                data: storedData,
                 timestamp: eventTimestamp === undefined ? now : DateTime.formatIso(eventTimestamp),
             };
             const item = { ...envelope };
@@ -931,8 +1118,7 @@ export const makeStream = (config) => {
                         cause,
                     }),
                 });
-                sentinel[resolveTtlAttributeName(tableConfig)] =
-                    DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
+                sentinel[ttlAttribute] = DateTime.toEpochSeconds(nowDateTime) + ttlSeconds;
             }
             sentinelPut = {
                 Put: {
@@ -943,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"),
                 },
             };
         }
@@ -982,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)
@@ -1045,7 +1242,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 +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. */
@@ -1111,19 +1377,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(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",
@@ -1149,7 +1408,12 @@ export const makeStream = (config) => {
      * 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 +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
@@ -1347,6 +1615,10 @@ export const makeStream = (config) => {
             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
@@ -1449,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),
     };
 };
 // ---------------------------------------------------------------------------
@@ -1483,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);
@@ -1495,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)),
@@ -1504,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),