effect-dynamodb 1.36.1 → 1.37.0

package/dist/EventStore.js

@@ -49,16 +49,20 @@ 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, isAwsValidationError, StreamSealed, TransactionCancelled, ValidationError, VersionConflict, } from "@effect-dynamodb/schema/Errors.js";
+import * as KeyText136 from "@effect-dynamodb/schema/internal/KeyText136.js";
 import { isDispatchEligible, packedShape, packValue, unpackStoredSync, } from "@effect-dynamodb/schema/internal/PackedCodec.js";
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
 import { Context, DateTime, Effect, Function, Option, Pipeable, Result, Schedule, Schema, } from "effect";
+import { attributeValueEquals } from "./internal/AttributeValueEquals.js";
 import * as Capacity from "./internal/Capacity.js";
 import { ProjectionRoutes } from "./internal/EventProjection.js";
-import { eq } from "./internal/Expr.js";
+import { eq, or } from "./internal/Expr.js";
+import { asReadGuard } from "./internal/ExpressionLimits.js";
 import { itemBytes, transactItemBytes } from "./internal/ItemSize.js";
 import { isMultiProjection, } from "./internal/MultiProjection.js";
 import { codecRequirements, currentRegistry, decodeImage, imageEntityType, runtimeCodecCheck, unregisteredCodecError, withRegistry, } from "./internal/Packed.js";
 import { createPathBuilder } from "./internal/PathBuilder.js";
+import * as Rekey from "./internal/Rekey.js";
 import { buildTransactWriteItems, GUARDED_TRANSACTION_ATTEMPTS, isStreamAppendOp, judgeCancellation, opConditionFailed, StreamAppendTypeId, transactItemTarget, } from "./internal/TransactWriteOps.js";
 import { diagnosedValidationError, diagnoseFailure, mergeKeyAttributes, withCause, } from "./internal/WriteDiagnosis.js";
 import { fromAttributeMap, toAttributeMap } from "./Marshaller.js";
@@ -161,6 +165,15 @@ const SEALED_ATTRIBUTE = "__edd_sealed__";
  * same version (a conflict), however alike their content.
  */
 const WRITE_TOKEN_ATTRIBUTE = "__edd_wt__";
+/**
+ * @internal Set by `rekey` (#171) on the first event of a stream it moved
+ * from its 1.36 partition key, once every row is copied to the current one:
+ * the stream lives there from then on. `locateStream` reads it; an append
+ * located at the 1.36 key checks it is absent (`AppendParts.locationCheck`),
+ * so a writer that located the stream before the move fails with
+ * `VersionConflict` instead of writing where nothing reads.
+ */
+const MOVED_ATTRIBUTE = "__edd_moved__";
 /** @internal The write token's length in hex digits: 128 random bits. */
 const WRITE_TOKEN_LENGTH = 32;
 /** @internal A fresh write token, from the platform's Web Crypto (CSPRNG). */
@@ -243,7 +256,7 @@ const putItemReason = (cause) => {
 };
 /**
  * @internal What a cancelled append means for one stream, from the reasons of
- * its own items: `[0, guardCount)` the contiguity check,
+ * its own items: `[0, guardCount)` the contiguity and location checks,
  * `[guardCount, guardCount + eventCount)` the event puts, and the snapshot at
  * `snapshotIndex` (`-1`: none). `StreamSealed` when the contiguity check, the
  * first event put or the snapshot failed and returned a sealed item (#166);
@@ -301,6 +314,7 @@ const STREAM_OWNED_ATTRIBUTES = [
     "commandId",
     SEALED_ATTRIBUTE,
     WRITE_TOKEN_ATTRIBUTE,
+    MOVED_ATTRIBUTE,
     DEFAULT_TTL_ATTRIBUTE_NAME,
 ];
 /** @internal Every member a stream index entry may declare (`StreamIndexConfigKey`). */
@@ -319,7 +333,12 @@ const STREAM_INDEX_CONFIG_KEYS = [
  * 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);
+const streamPkFilter = (streamPk, streamPk136) => {
+    const pk = createPathBuilder().pk;
+    // A stream still under its 1.36 key (#171) has its items there: either
+    // key, since a stream is never split across the two.
+    return streamPk136 === undefined ? eq(pk, streamPk) : or(eq(pk, streamPk), eq(pk, streamPk136));
+};
 /**
  * @internal Validate `makeStream({ indexes })` at definition time.
  *
@@ -907,6 +926,64 @@ export const makeStream = (config) => {
         const composites = KeyComposer.extractComposites(compositeFields, streamId);
         return DynamoSchema.composeKey(schema, keyLabel, composites, keyOptions);
     };
+    /**
+     * The partition key 1.36 composed for `streamId`, when the 1.36 key
+     * fallback is on and its text differs from {@link composeStreamPk}'s — a
+     * number stream id composite whose text changed (#171). `force` answers
+     * with the fallback off too: `rekey` moves streams whatever it is set to.
+     */
+    const composeStreamPk136 = (streamId, force = false) => {
+        if (!force && !KeyText136.enabled(schema))
+            return undefined;
+        const composites = KeyText136.extractComposites(compositeFields, streamId);
+        const pk136 = DynamoSchema.composeKey(schema, keyLabel, composites, keyOptions);
+        return pk136 === composeStreamPk(streamId) ? undefined : pk136;
+    };
+    /**
+     * The partition key a stream lives under (#171, DESIGN.md §7 "Rows written
+     * by 1.36"): its current key, unless that key's text changed since 1.36 and
+     * the stream's first event is under its 1.36 key. A stream 1.36 started is
+     * read and appended there — its events, snapshot, seal and command
+     * sentinels — until `rekey` moves it whole (and marks its first event
+     * there moved); a stream is never split across the two keys, and a new one
+     * starts under its current key. A stream whose key text did not change
+     * costs no request; one whose did, one consistent `GetItem` of the first
+     * event's key.
+     */
+    const locateStream = (streamId) => composeStreamPk136(streamId) === undefined
+        ? Effect.succeed(composeStreamPk(streamId))
+        : Effect.gen(function* () {
+            const { name: tableName } = yield* config.table.Tag;
+            return yield* locateStreamIn(tableName, streamId);
+        });
+    /** {@link locateStream} in the table named `tableName`. */
+    const locateStreamIn = (tableName, streamId) => {
+        const current = composeStreamPk(streamId);
+        const pk136 = composeStreamPk136(streamId);
+        if (pk136 === undefined)
+            return Effect.succeed(current);
+        return Effect.gen(function* () {
+            const client = yield* Capacity.client;
+            const first = yield* client.getItem({
+                TableName: tableName,
+                Key: toAttributeMap({ pk: pk136, sk: composeEventSk(1) }),
+                ConsistentRead: true,
+                ProjectionExpression: "#pk, #moved",
+                ExpressionAttributeNames: { "#pk": "pk", "#moved": MOVED_ATTRIBUTE },
+            });
+            return first.Item === undefined || first.Item[MOVED_ATTRIBUTE] !== undefined ? current : pk136;
+        });
+    };
+    /**
+     * The `prepare` step of a query of the stream's partition: read it where
+     * the stream lives ({@link locateStream}). Only a stream whose key text
+     * changed has one.
+     */
+    const locatedPrepare = (streamId) => composeStreamPk136(streamId) === undefined
+        ? {}
+        : {
+            prepare: (tableName) => Effect.map(locateStreamIn(tableName, streamId), (pkValue) => ({ pkValue })),
+        };
     const composeEventSk = (version) => DynamoSchema.composeEventVersionKey(schema, eventKeyLabel, version, keyOptions);
     /** Sort key of a command's idempotency sentinel. */
     const composeCommandSk = (commandId) => DynamoSchema.composeKey(schema, commandKeyLabel, [commandId], keyOptions);
@@ -1352,7 +1429,9 @@ export const makeStream = (config) => {
      * `sealed` writes the seal marker (#166): only a sealing append's inline
      * snapshot carries it.
      */
-    const buildSnapshotItem = (streamId, state, asOfVersion, now, operation, eventPartitions, sealed = false) => Effect.gen(function* () {
+    const buildSnapshotItem = (streamId, 
+    /** The partition the stream lives under ({@link locateStream}). */
+    pk, state, asOfVersion, now, operation, eventPartitions, sealed = false) => Effect.gen(function* () {
         const encoded = yield* encodeSnapshotState(state, operation);
         const stored = stateStoredAs === undefined
             ? encoded
@@ -1362,7 +1441,7 @@ export const makeStream = (config) => {
                 operation: `${operation}.packed`,
             });
         const item = {
-            pk: composeStreamPk(streamId),
+            pk,
             sk: snapshotSk,
             __edd_e__: snapshotEntityType,
             streamId: composeStreamIdString(streamId),
@@ -1402,7 +1481,9 @@ export const makeStream = (config) => {
      * 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 buildAppend = (streamId, events, expectedVersion, options, 
+    /** Where the stream lives ({@link locateStream}); its current key when not given. */
+    streamPk) => Effect.gen(function* () {
         const additionalOps = options?.additionalItems ?? [];
         const idempotency = options?.idempotency;
         const snapshotState = options?.snapshot;
@@ -1552,7 +1633,7 @@ export const makeStream = (config) => {
                     "Nothing was written.",
             });
         }
-        const pk = composeStreamPk(streamId);
+        const pk = streamPk ?? composeStreamPk(streamId);
         // Clock-backed timestamp (deterministic under TestClock; wall-clock in prod).
         const nowDateTime = yield* DateTime.now;
         const now = DateTime.formatIso(nowDateTime);
@@ -1718,7 +1799,7 @@ export const makeStream = (config) => {
         // transaction-size and item-size diagnosis count its stored bytes.
         let snapshotPut;
         if (snapshotState !== undefined) {
-            const item = yield* buildSnapshotItem(streamId, snapshotState, expectedVersion + events.length, now, "EventStore.append.snapshot", eventPartitions, sealing);
+            const item = yield* buildSnapshotItem(streamId, pk, snapshotState, expectedVersion + events.length, now, "EventStore.append.snapshot", eventPartitions, sealing);
             // As a head proof, a sealed snapshot fails the proof (#166), and
             // returns its item so the failure is reported as `StreamSealed`.
             snapshotPut = {
@@ -1763,21 +1844,51 @@ export const makeStream = (config) => {
          * costs nothing; `ALL_OLD` returns the item on failure (response bytes
          * only), so a sealed one is reported as `StreamSealed`.
          */
+        // A stream still under its 1.36 key (#171) must not have been moved
+        // since it was located: `rekey` marks its first event once the stream
+        // is copied (`MOVED_ATTRIBUTE`). Checked on the first event — by the
+        // contiguity check when it reads that event — for an append that
+        // writes anything into the stream's partition: events onto the
+        // stream, or a command sentinel alone (a command that decided no
+        // events, recorded for exactly-once), which would otherwise land where
+        // nothing reads it. An append writing events from version 0 needs no
+        // check: its first Put fails on its own, the first event being there.
+        const located136 = streamPk !== undefined &&
+            streamPk !== composeStreamPk(streamId) &&
+            (events.length > 0 ? expectedVersion > 0 : sentinelPut !== undefined);
+        const foldLocation = located136 && needsContiguityCheck && expectedVersion === 1;
         const contiguityCheck = needsContiguityCheck
             ? {
                 ConditionCheck: {
                     TableName: tableName,
                     Key: toAttributeMap({ pk, sk: composeEventSk(expectedVersion) }),
-                    ConditionExpression: "attribute_exists(#pk) AND attribute_not_exists(#sealed)",
-                    ExpressionAttributeNames: { "#pk": "pk", "#sealed": SEALED_ATTRIBUTE },
+                    ConditionExpression: foldLocation
+                        ? "attribute_exists(#pk) AND attribute_not_exists(#sealed) AND attribute_not_exists(#moved)"
+                        : "attribute_exists(#pk) AND attribute_not_exists(#sealed)",
+                    ExpressionAttributeNames: {
+                        "#pk": "pk",
+                        "#sealed": SEALED_ATTRIBUTE,
+                        ...(foldLocation && { "#moved": MOVED_ATTRIBUTE }),
+                    },
                     ReturnValuesOnConditionCheckFailure: "ALL_OLD",
                 },
             }
             : undefined;
+        const locationCheck = located136 && !foldLocation
+            ? {
+                ConditionCheck: {
+                    TableName: tableName,
+                    Key: toAttributeMap({ pk, sk: composeEventSk(1) }),
+                    ConditionExpression: "attribute_exists(#pk) AND attribute_not_exists(#moved)",
+                    ExpressionAttributeNames: { "#pk": "pk", "#moved": MOVED_ATTRIBUTE },
+                },
+            }
+            : undefined;
         const parts = {
             tableName,
             streamIdStr,
             contiguityCheck,
+            locationCheck,
             eventItems,
             sentinelPut,
             snapshotPut,
@@ -1803,14 +1914,17 @@ export const makeStream = (config) => {
                     "Nothing was written.",
             });
         }
-        const parts = yield* buildAppend(streamId, events, expectedVersion, options);
+        // A stream 1.36 started is appended where it lives (#171).
+        const pk = yield* locateStream(streamId);
+        const parts = yield* buildAppend(streamId, events, expectedVersion, options, pk);
         if (parts === undefined)
             return { version: expectedVersion, events: [] };
-        const { tableName, streamIdStr, contiguityCheck, eventItems, sentinelPut, snapshotPut } = parts;
+        const { tableName, streamIdStr, contiguityCheck, locationCheck, eventItems, sentinelPut, snapshotPut, } = parts;
         const client = yield* Capacity.client;
         /**
          * Lay out the append's one transaction — see {@link AppendTransaction}:
-         *   [0, C)                version-contiguity ConditionCheck (C is 0 or 1)
+         *   [0, C)                version-contiguity ConditionCheck, then the
+         *                         1.36 location check (#171) — C is 0 to 2
          *   [C, C + E)            event puts
          *   [C + E, C + E + A)    additional ITEMS (caller op order preserved)
          *   then                  idempotency sentinel, then inline snapshot
@@ -1834,6 +1948,9 @@ export const makeStream = (config) => {
             if (contiguityCheck !== undefined) {
                 pushStreamItem(contiguityCheck, entityType, "the version-contiguity check");
             }
+            if (locationCheck !== undefined) {
+                pushStreamItem(locationCheck, entityType, "the check that rekey has not moved the stream");
+            }
             const guardCount = items.length;
             for (const [i, item] of eventItems.entries()) {
                 pushStreamItem(item, entityType, `the event at version ${expectedVersion + i + 1}`);
@@ -1927,7 +2044,7 @@ export const makeStream = (config) => {
             return yield* refuse(`An append op of stream "${config.streamName}" needs at least one event: with none ` +
                 "it writes nothing. Nothing was written.");
         }
-        const parts = (yield* buildAppend(streamId, events, expectedVersion, options));
+        const parts = (yield* buildAppend(streamId, events, expectedVersion, options, yield* locateStream(streamId)));
         const items = [];
         const sources = [];
         const label = `${source} (stream "${config.streamName}", ${parts.streamIdStr})`;
@@ -1935,6 +2052,10 @@ export const makeStream = (config) => {
             items.push(parts.contiguityCheck);
             sources.push([entityType, `${label}: the version-contiguity check`]);
         }
+        if (parts.locationCheck !== undefined) {
+            items.push(parts.locationCheck);
+            sources.push([entityType, `${label}: the check that rekey has not moved the stream`]);
+        }
         const guardCount = items.length;
         for (const [i, item] of parts.eventItems.entries()) {
             items.push(item);
@@ -2014,7 +2135,7 @@ export const makeStream = (config) => {
         if (snapshot === undefined)
             return yield* snapshotUnavailable("measureSnapshot");
         const now = DateTime.formatIso(yield* DateTime.now);
-        const item = yield* buildSnapshotItem(streamId, state, asOfVersion, now, "EventStore.measureSnapshot");
+        const item = yield* buildSnapshotItem(streamId, composeStreamPk(streamId), state, asOfVersion, now, "EventStore.measureSnapshot");
         return itemBytes(item);
     });
     // ---------------------------------------------------------------------------
@@ -2105,40 +2226,82 @@ export const makeStream = (config) => {
         const client = yield* Capacity.client;
         const { name: tableName } = yield* config.table.Tag;
         const now = DateTime.formatIso(yield* DateTime.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: item,
-            // Monotonic: never regress the cache. Losing this race is a no-op,
-            // not an error — the events it summarises are already durable.
-            ConditionExpression: "attribute_not_exists(#pk) OR #asOfVersion < :asOfVersion",
-            ExpressionAttributeNames: { "#pk": "pk", "#asOfVersion": "asOfVersion" },
-            ExpressionAttributeValues: toAttributeMap({ ":asOfVersion": asOfVersion }),
-        };
-        yield* client.putItem(put).pipe(Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.void), 
-        // An oversized snapshot is DynamoDB's to reject (#144); named here.
-        diagnoseFailure({
-            sent: () => ({
-                _tag: "Item",
-                item: { Put: put },
-                target: () => transactItemTarget({ Put: put }, tableName, ["pk", "sk"], snapshotEntityType, "the snapshot"),
-            }),
-            keys: () => ({
-                partition: ["pk", ...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,
+        const 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.
+        const 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,
+            });
+        // A stream located under its 1.36 key (#171) that `rekey` moves after
+        // the locate is written at its current key on a second pass.
+        for (let pass = 0; pass < 2; pass++) {
+            const pk = yield* locateStream(streamId);
+            // Packed per `snapshot.storedAs` (#147): the diagnosis below measures
+            // the stored bytes.
+            const item = yield* buildSnapshotItem(streamId, pk, state, asOfVersion, now, "EventStore.writeSnapshot");
+            const put = {
+                TableName: tableName,
+                Item: item,
+                // Monotonic: never regress the cache. Losing this race is a no-op,
+                // not an error — the events it summarises are already durable.
+                ConditionExpression: "attribute_not_exists(#pk) OR #asOfVersion < :asOfVersion",
+                ExpressionAttributeNames: { "#pk": "pk", "#asOfVersion": "asOfVersion" },
+                ExpressionAttributeValues: toAttributeMap({ ":asOfVersion": asOfVersion }),
+            };
+            const target = (written) => () => transactItemTarget(written, tableName, ["pk", "sk"], snapshotEntityType, "the snapshot");
+            if (pk === composeStreamPk(streamId)) {
+                return yield* client.putItem(put).pipe(Effect.catchIf((error) => isAwsConditionalCheckFailed(error.cause), () => Effect.void), 
+                // An oversized snapshot is DynamoDB's to reject (#144); named here.
+                diagnoseFailure({
+                    sent: () => ({ _tag: "Item", item: { Put: put }, target: target({ Put: put }) }),
+                    keys,
+                    rewrite,
+                }));
+            }
+            // Under its 1.36 key, the snapshot is written there only while the
+            // stream is — checked on its first event, as an append checks it.
+            const items = [
+                { Put: put },
+                {
+                    ConditionCheck: {
+                        TableName: tableName,
+                        Key: toAttributeMap({ pk, sk: composeEventSk(1) }),
+                        ConditionExpression: "attribute_exists(#pk) AND attribute_not_exists(#moved)",
+                        ExpressionAttributeNames: { "#pk": "pk", "#moved": MOVED_ATTRIBUTE },
+                    },
+                },
+            ];
+            const moved = yield* client.transactWriteItems({ TransactItems: [...items] }).pipe(Effect.as(false), Effect.catch((error) => {
+                if (!isAwsTransactionCancelled(error.cause))
+                    return Effect.fail(error);
+                const reasons = error.cause.CancellationReasons ?? [];
+                if (reasons[1]?.Code === "ConditionalCheckFailed")
+                    return Effect.succeed(true);
+                return reasons[0]?.Code === "ConditionalCheckFailed"
+                    ? Effect.succeed(false)
+                    : Effect.fail(error);
+            }), diagnoseFailure({
+                sent: () => ({
+                    _tag: "Transaction",
+                    items,
+                    targets: () => [
+                        target(items[0])(),
+                        transactItemTarget(items[1], tableName, ["pk", "sk"], entityType, "the check that rekey has not moved the stream"),
+                    ],
                 }),
-        }));
+                keys,
+                rewrite,
+            }));
+            if (!moved)
+                return;
+        }
     });
     /**
      * Decode a stored snapshot item. A snapshot that fails to decode through the
@@ -2161,7 +2324,7 @@ export const makeStream = (config) => {
         const result = yield* client.getItem({
             TableName: tableName,
             Key: toAttributeMap({
-                pk: composeStreamPk(streamId),
+                pk: yield* locateStream(streamId),
                 sk: snapshotSk,
             }),
             ...(consistentRead ? { ConsistentRead: true } : {}),
@@ -2175,7 +2338,7 @@ export const makeStream = (config) => {
         const result = yield* client.getItem({
             TableName: tableName,
             Key: toAttributeMap({
-                pk: composeStreamPk(streamId),
+                pk: yield* locateStream(streamId),
                 sk: composeEventSk(version),
             }),
             ...(consistentRead ? { ConsistentRead: true } : {}),
@@ -2259,7 +2422,7 @@ export const makeStream = (config) => {
             FilterExpression: "#e IN (:eventType, :snapshotType)",
             ExpressionAttributeNames: { "#pk": "pk", "#sk": "sk", "#e": "__edd_e__" },
             ExpressionAttributeValues: toAttributeMap({
-                ":pk": composeStreamPk(streamId),
+                ":pk": yield* locateStream(streamId),
                 ":first": eventSkPrefix,
                 ":snapshot": snapshotSk,
                 ":eventType": entityType,
@@ -2346,7 +2509,7 @@ export const makeStream = (config) => {
         const { name: tableName } = yield* config.table.Tag;
         const result = yield* client.getItem({
             TableName: tableName,
-            Key: toAttributeMap({ pk: composeStreamPk(streamId), sk: composeCommandSk(commandId) }),
+            Key: toAttributeMap({ pk: yield* locateStream(streamId), sk: composeCommandSk(commandId) }),
             ConsistentRead: true,
             ProjectionExpression: "#pk",
             ExpressionAttributeNames: { "#pk": "pk" },
@@ -2375,6 +2538,8 @@ export const makeStream = (config) => {
             // Consumed capacity reports these queries under the stream name, as
             // every `EventStream.*` operation does (#174).
             operationTarget: config.streamName,
+            // A stream 1.36 started is read where it lives (#171).
+            ...locatedPrepare(streamId),
             // Bound to the event SK range so non-event items in the stream partition
             // (the snapshot) are excluded at the key-condition level. A caller-supplied
             // `Query.where` replaces this — the `__edd_e__` filter still applies.
@@ -2434,6 +2599,7 @@ export const makeStream = (config) => {
             throw new Error(`[EDD-9080] EventStream "${config.streamName}": ${partitionProblem}`);
         }
         const streamPk = composeStreamPk(streamId);
+        const derived = idx.partition === "derived";
         const query = Query.make({
             tableName: "",
             indexName: idx.index,
@@ -2456,6 +2622,9 @@ export const makeStream = (config) => {
             },
             keyFields: [idx.pk, idx.sk, "pk", "sk"],
             operationTarget: config.streamName,
+            // A stream-scoped index of a stream 1.36 started is read in the 1.36
+            // partition, as its events are (#171).
+            ...(derived ? {} : locatedPrepare(streamId)),
             // A "keys" index holds no events: an LSI has DynamoDB fetch them
             // (`Select: ALL_ATTRIBUTES`), a GSI fetches each page's with
             // `BatchGetItem` on the table key.
@@ -2467,7 +2636,9 @@ export const makeStream = (config) => {
                 }
                 : {}),
         });
-        return idx.partition === "derived" ? Query.filterExpr(query, streamPkFilter(streamPk)) : query;
+        return derived
+            ? Query.filterExpr(query, streamPkFilter(streamPk, composeStreamPk136(streamId)))
+            : query;
     };
     /**
      * @internal The decoder of events read through `idx`.
@@ -2545,6 +2716,395 @@ export const makeStream = (config) => {
     // type parameter is opaque, causing Effect.gen to infer `unknown` for R. The cast
     // is safe because all operations correctly require DynamoClient | TableConfig at
     // runtime — the user must provide these layers.
+    // ---------------------------------------------------------------------------
+    // rekey (#171): the stream's part in `db.tables.<Table>.rekey()`
+    //
+    // A stream 1.36 started under a partition key whose text changed (a number
+    // stream id composite) moves whole, while writers keep appending: every row
+    // is COPIED to the current key — where nothing is, or a snapshot over an
+    // older one; one transaction then FLIPS it — marks its first event moved,
+    // conditioned on the head and the snapshot being as copied — so
+    // `locateStream` reads the current key from then on, and an append or
+    // snapshot write that located the 1.36 key before fails its location
+    // check; the 1.36 rows are DELETED last, each while it is as read, the
+    // events from the head down and the first event last. A flip or delete
+    // that loses to a write reads again.
+    // ---------------------------------------------------------------------------
+    /** Attributes holding the stream's partition key: a GSI index's partition. */
+    const partitionAttributes = streamIndexes.flatMap((idx) => (idx.type === "gsi" ? [idx.pk] : []));
+    /** At most this many ways to split a stored stream id into its composites are tried. */
+    const STREAM_ID_SPLITS = 256;
+    /**
+     * The stream ids a stored `streamId` can be. A multi-composite id is its
+     * parts joined by `#`, and a string part may hold `#` itself, so every way
+     * to split the text into as many parts is tried; each part is its text, or
+     * the number (or bigint) it spells — the text alone does not say which.
+     */
+    const streamIdCandidates = (text) => {
+        const count = compositeFields.length;
+        const pieces = text.split("#");
+        if (pieces.length < count)
+            return [];
+        const splits = [];
+        const split = (start, parts) => {
+            if (splits.length >= STREAM_ID_SPLITS)
+                return;
+            if (parts.length === count - 1) {
+                splits.push([...parts, pieces.slice(start).join("#")]);
+                return;
+            }
+            for (let end = start + 1; end <= pieces.length - (count - 1 - parts.length); end++) {
+                split(end, [...parts, pieces.slice(start, end).join("#")]);
+            }
+        };
+        split(0, []);
+        return splits.flatMap((parts) => {
+            let candidates = [{}];
+            compositeFields.forEach((field, i) => {
+                const part = parts[i];
+                const values = [part];
+                const n = Number(part);
+                if (part.trim() !== "" && Number.isFinite(n) && String(n) === part)
+                    values.push(n);
+                if (/^-?\d+$/.test(part) && String(BigInt(part)) === part)
+                    values.push(BigInt(part));
+                candidates = candidates.flatMap((candidate) => values.map((value) => ({ ...candidate, [field]: value })));
+            });
+            return candidates;
+        });
+    };
+    /**
+     * Where a stream row belongs now and where 1.36 put it, from its
+     * `streamId`: the readings of the id whose keys hold the row's partition
+     * key. `"ambiguous"` when readings disagree on where it belongs.
+     */
+    const streamKeys = (row) => {
+        const pk = row.pk?.S;
+        const text = row.streamId?.S;
+        if (pk === undefined || text === undefined)
+            return undefined;
+        let found;
+        for (const candidate of streamIdCandidates(text)) {
+            try {
+                const current = composeStreamPk(candidate);
+                const old = composeStreamPk136(candidate, true) ?? current;
+                if (pk !== current && pk !== old)
+                    continue;
+                if (found === undefined)
+                    found = { current, old };
+                else if (found.current !== current || found.old !== old)
+                    return "ambiguous";
+            }
+            catch {
+                // Not this reading of the id.
+            }
+        }
+        return found;
+    };
+    const sameRow = (a, b) => {
+        if (a === undefined || b === undefined)
+            return a === b;
+        const names = new Set([...Object.keys(a), ...Object.keys(b)]);
+        for (const name of names)
+            if (!attributeValueEquals(a[name], b[name]))
+                return false;
+        return true;
+    };
+    /** How many attempts a stream move makes in all: a flip that loses to a write copies again. */
+    const STREAM_MOVE_ATTEMPTS = 8;
+    /**
+     * Move the stream under `from` to `to` — or, when its first event is no
+     * longer under `from` (moved by an earlier run), the rows left there.
+     * Command sentinels whose TTL has passed are gone, whether or not DynamoDB
+     * has deleted them yet.
+     */
+    const moveStream = (ctx, from, to, streamIdText, ttlAttribute) => Effect.gen(function* () {
+        const client = yield* Capacity.client;
+        const firstSk = composeEventSk(1);
+        const nowSeconds = DateTime.toEpochSeconds(yield* DateTime.now);
+        const live = (row) => {
+            const ttl = row[ttlAttribute]?.N;
+            return ttl === undefined || Number(ttl) > nowSeconds;
+        };
+        const readAll = (pkValue) => Effect.gen(function* () {
+            const rows = [];
+            let start;
+            do {
+                const page = yield* client.query({
+                    TableName: ctx.tableName,
+                    KeyConditionExpression: "#pk = :pk",
+                    ExpressionAttributeNames: { "#pk": "pk" },
+                    ExpressionAttributeValues: toAttributeMap({ ":pk": pkValue }),
+                    ConsistentRead: true,
+                    ...(start !== undefined && { ExclusiveStartKey: start }),
+                });
+                rows.push(...(page.Items ?? []).filter(live));
+                start = page.LastEvaluatedKey;
+            } while (start !== undefined);
+            return rows;
+        });
+        const copyOf = (row) => {
+            const copy = { ...row, pk: { S: to } };
+            delete copy[MOVED_ATTRIBUTE];
+            for (const attr of partitionAttributes) {
+                if (copy[attr]?.S === from)
+                    copy[attr] = { S: to };
+            }
+            return copy;
+        };
+        const skOf = (row) => row.sk?.S ?? "";
+        const versionOf = (row) => row.__edd_e__?.S === entityType ? Number(row.version?.N ?? 0) : 0;
+        const asOfOf = (row) => Number(row.asOfVersion?.N ?? 0);
+        const conflict = (reason, message, sk = firstSk) => ({
+            conflicts: [
+                {
+                    member: config.streamName,
+                    kind: "stream",
+                    reason,
+                    key: { pk: from, sk },
+                    target: { pk: to, sk },
+                    message: `Stream ${JSON.stringify(streamIdText)}: ${message}`,
+                },
+            ],
+        });
+        const cancelled = (error) => isAwsConditionalCheckFailed(error.cause) ? Effect.succeed(false) : Effect.fail(error);
+        /**
+         * Copy `row` to `to`: where nothing is (or only a row whose TTL has
+         * passed) — or, a snapshot, over an older one (`older`), so a copy never
+         * regresses it. `false` when a write got there first.
+         */
+        const copy = (row, older) => client
+            .putItem({
+            TableName: ctx.tableName,
+            Item: copyOf(row),
+            ...(older === undefined
+                ? {
+                    ConditionExpression: "attribute_not_exists(#pk) OR #ttl <= :now",
+                    ExpressionAttributeNames: { "#pk": "pk", "#ttl": ttlAttribute },
+                    ExpressionAttributeValues: { ":now": { N: String(nowSeconds) } },
+                }
+                : {
+                    ConditionExpression: "#asOf < :asOf",
+                    ExpressionAttributeNames: { "#asOf": "asOfVersion" },
+                    ExpressionAttributeValues: { ":asOf": row.asOfVersion ?? { N: "0" } },
+                }),
+        })
+            .pipe(Effect.as(true), Effect.catch(cancelled));
+        /** Delete `row` at `from` while it is as read. `false` when a write changed it. */
+        const remove = (row) => client
+            .deleteItem({
+            TableName: ctx.tableName,
+            Key: toAttributeMap({ pk: from, sk: skOf(row) }),
+            ...asReadGuard(row, "pk", []),
+        })
+            .pipe(Effect.as(true), Effect.catch(cancelled));
+        /**
+         * Bring every row still under `from` over, once the stream lives at
+         * `to`: a row `to` lacks is copied (a command sentinel written beside
+         * the flip, a row an append that located the stream before the flip
+         * wrote), a snapshot newer than `to`'s copied over it, and then each is
+         * deleted while it is as read — the events from the head down, the
+         * other rows, and the first event last: until it goes, the stream is
+         * located here, and an append that located it here fails its check. A
+         * row `to` holds differently (an event or sentinel written under both
+         * keys) is a conflict, and the rows are left as they are. `undefined`
+         * when a write landed in between: read again.
+         */
+        const drain = Effect.gen(function* () {
+            const left = yield* readAll(from);
+            const there = new Map((yield* readAll(to)).map((row) => [skOf(row), row]));
+            const differing = [];
+            for (const row of left) {
+                const held = there.get(skOf(row));
+                if (held === undefined || sameRow(copyOf(row), held))
+                    continue;
+                if (skOf(row) === snapshotSk)
+                    continue;
+                differing.push(row);
+            }
+            if (differing.length > 0) {
+                return Rekey.mergeTallies(...differing.map((row) => conflict("bothKeys", "a row of it is under both partition keys, and the two differ; the rows " +
+                    "under its 1.36 key are left as they are.", skOf(row))));
+            }
+            for (const row of left) {
+                const held = there.get(skOf(row));
+                const copied = held === undefined
+                    ? yield* copy(row)
+                    : skOf(row) === snapshotSk && asOfOf(row) > asOfOf(held)
+                        ? yield* copy(row, held)
+                        : true;
+                if (!copied)
+                    return undefined;
+            }
+            const ordered = [
+                ...left.filter((row) => versionOf(row) > 1).sort((a, b) => versionOf(b) - versionOf(a)),
+                ...left.filter((row) => versionOf(row) === 0),
+                ...left.filter((row) => versionOf(row) === 1),
+            ];
+            for (const row of ordered) {
+                if (!(yield* remove(row)))
+                    return undefined;
+            }
+            return { moved: { stream: left.length } };
+        });
+        for (let attempt = 0; attempt < STREAM_MOVE_ATTEMPTS; attempt++) {
+            const rows = yield* readAll(from);
+            // Moved since the scan read it.
+            if (rows.length === 0)
+                return {};
+            const first = rows.find((row) => skOf(row) === firstSk);
+            // Flipped by an earlier attempt or run — or never started here: the
+            // stream lives at `to`, and the rows left move to it.
+            const flipped = first === undefined || first[MOVED_ATTRIBUTE] !== undefined;
+            if (!flipped) {
+                const there = new Map((yield* readAll(to)).map((row) => [skOf(row), row]));
+                const here = new Map(rows.map((row) => [skOf(row), row]));
+                // Rows under the current key are copies of an earlier attempt —
+                // anything else is another stream's: a row this one does not have,
+                // or one it has differently (a snapshot only grows newer).
+                for (const [sk, row] of there) {
+                    const own = here.get(sk);
+                    if (own === undefined) {
+                        return conflict("taken", "rows of another stream are under its current partition key.");
+                    }
+                    if (sk !== snapshotSk && !sameRow(copyOf(own), row)) {
+                        return conflict("bothKeys", "rows of another stream are under its current partition key.", sk);
+                    }
+                }
+                if (ctx.dryRun)
+                    return { moved: { stream: rows.length } };
+                // COPY
+                let copiedAll = true;
+                for (const row of rows) {
+                    const held = there.get(skOf(row));
+                    const copied = held === undefined
+                        ? yield* copy(row)
+                        : skOf(row) === snapshotSk && asOfOf(row) > asOfOf(held)
+                            ? yield* copy(row, held)
+                            : true;
+                    if (!copied) {
+                        copiedAll = false;
+                        break;
+                    }
+                }
+                if (!copiedAll)
+                    continue;
+                // FLIP — conditioned on the stream being as copied: no event past
+                // the head, the head (and its seal) and the snapshot unchanged.
+                const head = rows.reduce((top, row) => Math.max(top, versionOf(row)), 1);
+                const headRow = rows.find((row) => versionOf(row) === head);
+                const snapshot = rows.find((row) => skOf(row) === snapshotSk);
+                const sealClause = headRow?.[SEALED_ATTRIBUTE] === undefined
+                    ? "attribute_not_exists(#sealed)"
+                    : "attribute_exists(#sealed)";
+                const items = [
+                    {
+                        Update: {
+                            TableName: ctx.tableName,
+                            Key: toAttributeMap({ pk: from, sk: firstSk }),
+                            UpdateExpression: "SET #moved = :to",
+                            ConditionExpression: head === 1
+                                ? `attribute_exists(#pk) AND attribute_not_exists(#moved) AND ${sealClause}`
+                                : "attribute_exists(#pk) AND attribute_not_exists(#moved)",
+                            ExpressionAttributeNames: {
+                                "#pk": "pk",
+                                "#moved": MOVED_ATTRIBUTE,
+                                ...(head === 1 && { "#sealed": SEALED_ATTRIBUTE }),
+                            },
+                            ExpressionAttributeValues: toAttributeMap({ ":to": to }),
+                        },
+                    },
+                    {
+                        ConditionCheck: {
+                            TableName: ctx.tableName,
+                            Key: toAttributeMap({ pk: from, sk: composeEventSk(head + 1) }),
+                            ConditionExpression: "attribute_not_exists(#pk)",
+                            ExpressionAttributeNames: { "#pk": "pk" },
+                        },
+                    },
+                    ...(head > 1
+                        ? [
+                            {
+                                ConditionCheck: {
+                                    TableName: ctx.tableName,
+                                    Key: toAttributeMap({ pk: from, sk: composeEventSk(head) }),
+                                    ConditionExpression: `attribute_exists(#pk) AND ${sealClause}`,
+                                    ExpressionAttributeNames: { "#pk": "pk", "#sealed": SEALED_ATTRIBUTE },
+                                },
+                            },
+                        ]
+                        : []),
+                    {
+                        ConditionCheck: {
+                            TableName: ctx.tableName,
+                            Key: toAttributeMap({ pk: from, sk: snapshotSk }),
+                            ...(snapshot === undefined
+                                ? {
+                                    ConditionExpression: "attribute_not_exists(#pk)",
+                                    ExpressionAttributeNames: { "#pk": "pk" },
+                                }
+                                : {
+                                    ConditionExpression: "#asOf = :asOf AND #ts = :ts",
+                                    ExpressionAttributeNames: { "#asOf": "asOfVersion", "#ts": "timestamp" },
+                                    ExpressionAttributeValues: {
+                                        ":asOf": snapshot.asOfVersion ?? { NULL: true },
+                                        ":ts": snapshot.timestamp ?? { NULL: true },
+                                    },
+                                }),
+                        },
+                    },
+                ];
+                const won = yield* client.transactWriteItems({ TransactItems: items }).pipe(Effect.as(true), Effect.catch((err) => isAwsTransactionCancelled(err.cause) ? Effect.succeed(false) : Effect.fail(err)));
+                // A write landed in between: copy again.
+                if (!won)
+                    continue;
+            }
+            else if (ctx.dryRun) {
+                return { moved: { stream: rows.length } };
+            }
+            // DELETE
+            const drained = yield* drain;
+            if (drained !== undefined)
+                return drained;
+        }
+        return conflict("contended", "writes changed it on every attempt to move it.");
+    });
+    const rekeyHandler = {
+        name: config.streamName,
+        types: [entityType, snapshotEntityType, commandEntityType],
+        row: (row, ctx) => Effect.gen(function* () {
+            const tableConfig = yield* config.table.Tag;
+            if (tableConfig.name !== ctx.tableName)
+                return undefined;
+            const keys = streamKeys(row);
+            if (keys === undefined)
+                return { skipped: { unrecognizedKey: 1 } };
+            if (keys === "ambiguous") {
+                return {
+                    conflicts: [
+                        {
+                            member: config.streamName,
+                            kind: "stream",
+                            reason: "failed",
+                            key: { pk: row.pk?.S, sk: row.sk?.S },
+                            target: undefined,
+                            message: `Stream ${JSON.stringify(row.streamId?.S ?? "")}: its stored stream id reads ` +
+                                "as more than one id of the stream's composites, and they disagree on where " +
+                                "it belongs.",
+                        },
+                    ],
+                };
+            }
+            if (row.pk?.S === keys.current)
+                return { unchanged: 1 };
+            // A stream under its 1.36 key moves whole, once per run, from
+            // whichever of its rows the scan reaches first — and rows left there
+            // after it moved move after it.
+            if (!ctx.claim(`${config.streamName}\u0000${keys.old}`))
+                return {};
+            return yield* moveStream(ctx, keys.old, keys.current, row.streamId?.S ?? "", resolveTtlAttributeName(tableConfig));
+        }),
+    };
     return {
         [EventStreamTypeId]: EventStreamTypeId,
         pipe() {
@@ -2575,6 +3135,7 @@ export const makeStream = (config) => {
         [StreamIdFormatter]: composeStreamIdString,
         [CommandSentinelProbe]: checked(hasCommandSentinel),
         [HeadAboveProbe]: checked(headAbove),
+        [Rekey.RekeyHandler]: rekeyHandler,
     };
 };
 // ---------------------------------------------------------------------------
@@ -2653,6 +3214,8 @@ export const bind = (stream) => Effect.gen(function* () {
         [HeadAboveProbe]: headProbe === undefined
             ? undefined
             : (id, floorVersion, options) => provide(headProbe(id, floorVersion, options)),
+        // `rekey` runs it with the table's services, as it runs every member's.
+        [Rekey.RekeyHandler]: Rekey.handlerOf(stream),
     };
 });
 // ---------------------------------------------------------------------------