effect-dynamodb 1.32.0 → 1.34.0

package/dist/EventStore.js

@@ -16,6 +16,10 @@
  * - Head proofs (`append({ headProof })`, #164): an additional item or the
  *   inline snapshot proves the stream head in place of the version-contiguity
  *   `ConditionCheck`
+ * - Sealing (#166): `append(..., { seal: true })` makes its last event the
+ *   stream's final one (`StreamSealed` for any later append), and
+ *   `stream.appendOp(...)` carries one stream's append — sealing or not — in
+ *   another append's transaction
  * - 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`,
@@ -41,7 +45,7 @@ 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 { AdditionalItemConditionFailed, AppendTooLarge, DuplicateCommand, isAwsConditionalCheckFailed, isAwsTransactionCancelled, StreamSealed, 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 { Context, DateTime, Effect, Function, Option, Pipeable, Result, Schedule, Schema, } from "effect";
@@ -52,7 +56,7 @@ 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 { buildTransactWriteItems, GUARDED_TRANSACTION_ATTEMPTS, judgeCancellation, opConditionFailed, transactItemTarget, } from "./internal/TransactWriteOps.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";
 import * as Query from "./Query.js";
@@ -133,6 +137,71 @@ const PROJECTED_ENVELOPE_ATTRIBUTES = [
     "timestamp",
     "version",
 ];
+/**
+ * @internal The seal marker (#166): a native `BOOL` `true` on the sealing
+ * event's item and on the sealing append's inline snapshot. In the library's
+ * `__edd_*__` namespace, beside `__edd_e__`, so no model field can collide
+ * with it (event `data` is a nested map or a packed value). Not one of
+ * {@link EVENT_ITEM_ATTRIBUTES}: adding it would change the `INCLUDE` list of
+ * every deployed `"withoutMetadata"` index.
+ */
+const SEALED_ATTRIBUTE = "__edd_sealed__";
+/**
+ * @internal The version a sealed item returned by a failed condition
+ * (`ReturnValuesOnConditionCheckFailure: "ALL_OLD"`) seals the stream at: an
+ * event's `version`, a snapshot's `asOfVersion`. `undefined` for a missing or
+ * unmarked item.
+ */
+const sealedVersionOf = (item) => {
+    if (item === undefined)
+        return undefined;
+    const marker = item[SEALED_ATTRIBUTE];
+    if (marker?.BOOL !== true)
+        return undefined;
+    const raw = fromAttributeMap(item);
+    const version = typeof raw.version === "number" ? raw.version : raw.asOfVersion;
+    return typeof version === "number" ? version : undefined;
+};
+/**
+ * @internal What a cancelled append means for one stream, from the reasons of
+ * its own items: `[0, guardCount)` the contiguity check,
+ * `[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);
+ * `VersionConflict` for any other failure of the check or the event puts;
+ * `undefined` otherwise. Shared by an append's own verdict and a nested
+ * {@link StreamAppendOp}'s.
+ */
+const streamAppendVerdict = (reasons, layout) => {
+    const failedAt = (index) => index >= 0 && reasons[index]?.Code === "ConditionalCheckFailed";
+    const checked = [
+        ...(layout.guardCount > 0 ? [0] : []),
+        ...(layout.eventCount > 0 ? [layout.guardCount] : []),
+        layout.snapshotIndex,
+    ];
+    for (const index of checked) {
+        if (!failedAt(index))
+            continue;
+        const sealedVersion = sealedVersionOf(reasons[index]?.Item);
+        if (sealedVersion !== undefined) {
+            return new StreamSealed({
+                streamName: layout.streamName,
+                streamId: layout.streamId,
+                sealedVersion,
+            });
+        }
+    }
+    for (let i = 0; i < layout.guardCount + layout.eventCount; i++) {
+        if (failedAt(i)) {
+            return new VersionConflict({
+                streamName: layout.streamName,
+                streamId: layout.streamId,
+                expectedVersion: layout.expectedVersion,
+            });
+        }
+    }
+    return undefined;
+};
 /**
  * @internal Attributes a stream writes on its own items — events, snapshot,
  * idempotency sentinel — plus the default TTL attribute. An index attribute
@@ -151,6 +220,7 @@ const STREAM_OWNED_ATTRIBUTES = [
     "asOfVersion",
     "state",
     "commandId",
+    SEALED_ATTRIBUTE,
     DEFAULT_TTL_ATTRIBUTE_NAME,
 ];
 /** @internal Every member a stream index entry may declare (`StreamIndexConfigKey`). */
@@ -619,8 +689,8 @@ const eventTimestampsProblem = (timestamps, count, label, events) => {
  *   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
- *   default TTL attribute `_ttl`). A custom `TableConfig.ttlAttributeName`
+ *   `metadata`, `timestamp`, `asOfVersion`, `state`, `commandId`, the seal
+ *   marker `__edd_sealed__`, or the default TTL attribute `_ttl`). A custom `TableConfig.ttlAttributeName`
  *   is only known at runtime: an index attribute equal to it fails each append
  *   with `ValidationError`.
  * @throws `[EDD-9065]` when two indexes share a physical index name or an
@@ -853,14 +923,18 @@ export const makeStream = (config) => {
                 ? yield* Schema.decodeUnknownEffect(metadataSchema)(raw.metadata).pipe(Effect.mapError(toValidationError("EventStore.decode.metadata")))
                 : raw.metadata;
         }
-        return {
+        const event = {
             streamId: envelope.streamId,
             version: envelope.version,
             eventType: envelope.eventType,
             data,
             metadata,
             timestamp: envelope.timestamp,
+            // The seal marker (#166), present only on a sealing event, so an
+            // ordinary event's shape is unchanged.
+            ...(raw[SEALED_ATTRIBUTE] === true ? { sealed: true } : {}),
         };
+        return event;
     });
     // ---------------------------------------------------------------------------
     // append
@@ -971,17 +1045,21 @@ export const makeStream = (config) => {
                     commandId,
                 }));
             }
-            // The contiguity ConditionCheck and the event puts both mean "the
-            // stream is not where you said it was", so they share one verdict.
-            for (let i = 0; i < tx.guardCount + tx.eventCount; i++) {
-                if (failedAt(i)) {
-                    return Effect.fail(new VersionConflict({
-                        streamName: config.streamName,
-                        streamId: streamIdStr,
-                        expectedVersion: tx.expectedVersion,
-                    }));
-                }
-            }
+            // A sealed stream (#166): the contiguity check, the first event put
+            // or the snapshot proof returned a sealing item — terminal, so it
+            // ranks above a conflict. Otherwise the contiguity ConditionCheck
+            // and the event puts both mean "the stream is not where you said it
+            // was", so they share one verdict.
+            const own = streamAppendVerdict(rawReasons, {
+                guardCount: tx.guardCount,
+                eventCount: tx.eventCount,
+                snapshotIndex: tx.snapshotIndex,
+                streamName: config.streamName,
+                streamId: streamIdStr,
+                expectedVersion: tx.expectedVersion,
+            });
+            if (own !== undefined)
+                return Effect.fail(own);
             // The head proof (#164) stands in for the contiguity check, so its
             // own condition failing shares their verdict — ahead of the other
             // additional items.
@@ -1002,7 +1080,11 @@ export const makeStream = (config) => {
             // the caller set no condition on reports what the entity's own put
             // would — a taken unique value, a history conflict — or, having
             // lost a race to a concurrent write, is written again (#133).
+            // A nested stream append's verdict (#166) comes first, naming its
+            // own stream.
             const judged = judgeCancellation(tx.additional, rawReasons, tx.guardCount + tx.eventCount);
+            if (judged?._tag === "stream")
+                return Effect.fail(judged.error);
             if (judged?._tag === "fail")
                 return Effect.fail(judged.error);
             if (judged?._tag === "conditions") {
@@ -1112,8 +1194,10 @@ export const makeStream = (config) => {
      *
      * `eventPartitions` — the partition the append's events have in each
      * index, by index name — is what the inline snapshot's entry must match.
+     * `sealed` writes the seal marker (#166): only a sealing append's inline
+     * snapshot carries it.
      */
-    const buildSnapshotItem = (streamId, state, asOfVersion, now, operation, eventPartitions) => Effect.gen(function* () {
+    const buildSnapshotItem = (streamId, state, asOfVersion, now, operation, eventPartitions, sealed = false) => Effect.gen(function* () {
         const encoded = yield* encodeSnapshotState(state, operation);
         const stored = stateStoredAs === undefined
             ? encoded
@@ -1151,6 +1235,9 @@ export const makeStream = (config) => {
             item[idx.pk] = entry.partition;
             item[idx.sk] = entry.key;
         }
+        // Top-level and native, beside `state`, so packing never touches it.
+        if (sealed)
+            item[SEALED_ATTRIBUTE] = true;
         return toAttributeMap(item);
     });
     /**
@@ -1230,6 +1317,42 @@ export const makeStream = (config) => {
                 }
             }
         }
+        // The seal (#166), checked ahead of the no-op fast path: a seal with
+        // nothing to mark must not pass as a no-op.
+        const seal = options?.seal;
+        if (seal !== undefined && typeof seal !== "boolean") {
+            return yield* new ValidationError({
+                entityType,
+                operation: "EventStore.append.seal",
+                cause: `seal must be a boolean; received ${JSON.stringify(seal) ?? String(seal)}. ` +
+                    "Nothing was written.",
+            });
+        }
+        const sealing = seal === true;
+        if (sealing && events.length === 0) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "EventStore.append.seal",
+                cause: "A seal needs at least one event to mark. Nothing was written.",
+            });
+        }
+        // On the only snapshot config that accepts the snapshot head proof, the
+        // snapshot at the seal version must be the marked one: a seal without
+        // it leaves the snapshot below the seal, and a later `writeSnapshot` at
+        // the seal version would put an unmarked one a snapshot-proof writer
+        // could append past.
+        if (sealing &&
+            snapshotState === undefined &&
+            snapshotSettings?.mode === "inline" &&
+            snapshotSettings.every === undefined) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "EventStore.append.seal",
+                cause: `Stream "${config.streamName}" writes its snapshot in every append (mode "inline" ` +
+                    "without every), so a seal must carry the inline snapshot: pass `snapshot` with the " +
+                    "state as of the sealing event, which is then marked sealed too. Nothing was written.",
+            });
+        }
         // Nothing at all to write — preserve the historical no-op fast path.
         // With additional items or a dedup sentinel the transaction still runs:
         // a caller who asked for a side write means it, and silently dropping it
@@ -1386,11 +1509,20 @@ export const makeStream = (config) => {
                 if (idx.type === "gsi")
                     item[idx.pk] = partition;
             }
+            // The seal marker (#166) on the sealing append's last event, after
+            // the typed envelope, as `metadata` is.
+            if (sealing && i === events.length - 1)
+                item[SEALED_ATTRIBUTE] = true;
             return {
                 Put: {
                     TableName: tableName,
                     Item: toAttributeMap(item),
                     ConditionExpression: "attribute_not_exists(pk)",
+                    // The first put of a writer one version behind a seal lands on
+                    // the sealing event: its item tells `StreamSealed` from a
+                    // conflict (#166). Only the first: every put's item would
+                    // bloat a failure response for writers already far behind.
+                    ...(i === 0 ? { ReturnValuesOnConditionCheckFailure: "ALL_OLD" } : {}),
                 },
             };
         }));
@@ -1431,7 +1563,9 @@ 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);
+            const item = yield* buildSnapshotItem(streamId, 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 = {
                 Put: headProof !== "snapshot"
                     ? { TableName: tableName, Item: item }
@@ -1440,15 +1574,20 @@ export const makeStream = (config) => {
                             TableName: tableName,
                             Item: item,
                             ConditionExpression: "attribute_not_exists(pk)",
+                            ReturnValuesOnConditionCheckFailure: "ALL_OLD",
                         }
                         : {
                             TableName: tableName,
                             Item: item,
-                            ConditionExpression: "#asOfVersion = :expectedVersion",
-                            ExpressionAttributeNames: { "#asOfVersion": "asOfVersion" },
+                            ConditionExpression: "#asOfVersion = :expectedVersion AND attribute_not_exists(#sealed)",
+                            ExpressionAttributeNames: {
+                                "#asOfVersion": "asOfVersion",
+                                "#sealed": SEALED_ATTRIBUTE,
+                            },
                             ExpressionAttributeValues: toAttributeMap({
                                 ":expectedVersion": expectedVersion,
                             }),
+                            ReturnValuesOnConditionCheckFailure: "ALL_OLD",
                         },
             };
         }
@@ -1463,13 +1602,20 @@ export const makeStream = (config) => {
          * cancellation reason, mapping to VersionConflict just like a
          * stale-version Put failure. A zero-event append (a pure side write)
          * writes no version and so can open no gap.
+         *
+         * It also enforces the seal (#166): the event at `expectedVersion` must
+         * not be a sealing event. It already reads that item, so the clause
+         * costs nothing; `ALL_OLD` returns the item on failure (response bytes
+         * only), so a sealed one is reported as `StreamSealed`.
          */
         const contiguityCheck = needsContiguityCheck
             ? {
                 ConditionCheck: {
                     TableName: tableName,
                     Key: toAttributeMap({ pk, sk: composeEventSk(expectedVersion) }),
-                    ConditionExpression: "attribute_exists(pk)",
+                    ConditionExpression: "attribute_exists(#pk) AND attribute_not_exists(#sealed)",
+                    ExpressionAttributeNames: { "#pk": "pk", "#sealed": SEALED_ATTRIBUTE },
+                    ReturnValuesOnConditionCheckFailure: "ALL_OLD",
                 },
             }
             : undefined;
@@ -1567,16 +1713,24 @@ export const makeStream = (config) => {
         for (let attempt = 0; attempt < GUARDED_TRANSACTION_ATTEMPTS; attempt++) {
             // Caller-owned items, compiled through the same builder
             // `Transaction.transactWrite` uses, so the two APIs cannot drift.
-            const additional = yield* buildTransactWriteItems(additionalOps, "EventStore.append.additionalItems");
+            // Another stream's append (#166) is accepted here, and only here.
+            const additional = yield* buildTransactWriteItems(additionalOps, "EventStore.append.additionalItems", { streams: true });
             // An item without a condition of its own proves nothing about the
-            // head: accepting it would drop the gap protection silently.
+            // head: accepting it would drop the gap protection silently. Nor
+            // does another stream's append: its conditions are its stream's.
             if (proofOp !== undefined && !additional.conditioned.has(proofOp)) {
+                const named = additionalOps[proofOp];
                 return yield* new ValidationError({
                     entityType,
                     operation: "EventStore.append.headProof",
-                    cause: `headProof names additionalItems[${proofOp}], which carries no condition of its ` +
-                        "own: the proof must be conditioned on the stream being at expectedVersion " +
-                        "(`.condition()`, `create()` or `Transaction.check`). Nothing was written.",
+                    cause: isStreamAppendOp(named)
+                        ? `headProof names additionalItems[${proofOp}], which is an append of stream ` +
+                            `"${named.streamName}" (appendOp): its conditions prove that stream's head, ` +
+                            "not this one's. Name an item conditioned on this stream being at " +
+                            "expectedVersion. Nothing was written."
+                        : `headProof names additionalItems[${proofOp}], which carries no condition of its ` +
+                            "own: the proof must be conditioned on the stream being at expectedVersion " +
+                            "(`.condition()`, `create()` or `Transaction.check`). Nothing was written.",
                 });
             }
             const tx = layout(additional);
@@ -1596,6 +1750,73 @@ export const makeStream = (config) => {
         return yield* Effect.fail(lost);
     });
     // ---------------------------------------------------------------------------
+    // appendOp — this stream's append inside another append (#166)
+    // ---------------------------------------------------------------------------
+    /**
+     * The nested append's items, built by `buildAppend` exactly as `append`
+     * builds them — contiguity check, event puts, seal marker, inline snapshot
+     * — with the verdict `append` itself applies to them. The options a nested
+     * append may not carry are refused here, for untyped callers.
+     */
+    const buildNestedAppend = (streamId, events, expectedVersion, options, source) => Effect.gen(function* () {
+        const refuse = (cause) => new ValidationError({ entityType, operation: "EventStore.appendOp", cause });
+        const untyped = options;
+        for (const key of ["additionalItems", "idempotency", "headProof"]) {
+            if (untyped?.[key] !== undefined) {
+                return yield* refuse(`A stream append op may not carry ${key}: one sentinel and one head proof per ` +
+                    "transaction, carried by the appending stream. Put them on the outer append. " +
+                    "Nothing was written.");
+            }
+        }
+        if (events.length === 0) {
+            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 items = [];
+        const sources = [];
+        const label = `${source} (stream "${config.streamName}", ${parts.streamIdStr})`;
+        if (parts.contiguityCheck !== undefined) {
+            items.push(parts.contiguityCheck);
+            sources.push([entityType, `${label}: the version-contiguity check`]);
+        }
+        const guardCount = items.length;
+        for (const [i, item] of parts.eventItems.entries()) {
+            items.push(item);
+            sources.push([entityType, `${label}: the event at version ${expectedVersion + i + 1}`]);
+        }
+        const snapshotIndex = parts.snapshotPut === undefined ? -1 : items.length;
+        if (parts.snapshotPut !== undefined) {
+            items.push(parts.snapshotPut);
+            sources.push([snapshotEntityType, `${label}: the inline snapshot`]);
+        }
+        const layout = {
+            guardCount,
+            eventCount: parts.eventItems.length,
+            snapshotIndex,
+            streamName: config.streamName,
+            streamId: parts.streamIdStr,
+            expectedVersion,
+        };
+        const built = {
+            items,
+            entityType,
+            targets: () => items.map((item, i) => transactItemTarget(item, parts.tableName, ["pk", "sk"], sources[i][0], sources[i][1])),
+            keys: () => ({
+                partition: ["pk", ...streamIndexes.map((idx) => idx.pk)],
+                sort: ["sk", ...streamIndexes.map((idx) => idx.sk)],
+            }),
+            verdict: (reasons) => streamAppendVerdict(reasons, layout),
+        };
+        return built;
+    });
+    const appendOp = (streamId, events, expectedVersion, options) => ({
+        [StreamAppendTypeId]: StreamAppendTypeId,
+        streamName: config.streamName,
+        // The codec check runs as for every other operation of the stream.
+        _build: checked((source) => buildNestedAppend(streamId, events, expectedVersion, options, source)),
+    });
+    // ---------------------------------------------------------------------------
     // measureAppend / measureSnapshot — caller-side size planning (#147, R1)
     // ---------------------------------------------------------------------------
     const measureAppend = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
@@ -1785,6 +2006,20 @@ export const makeStream = (config) => {
         });
         return result.Item === undefined ? undefined : fromAttributeMap(result.Item);
     });
+    /** The raw event item at `version`, by its exact key, in one `GetItem` (#166). */
+    const getEventItem = (streamId, version, consistentRead) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        const { name: tableName } = yield* config.table.Tag;
+        const result = yield* client.getItem({
+            TableName: tableName,
+            Key: toAttributeMap({
+                pk: composeStreamPk(streamId),
+                sk: composeEventSk(version),
+            }),
+            ...(consistentRead ? { ConsistentRead: true } : {}),
+        });
+        return result.Item === undefined ? undefined : fromAttributeMap(result.Item);
+    });
     const readSnapshot = (streamId) => Effect.gen(function* () {
         if (snapshot === undefined)
             return yield* snapshotUnavailable("readSnapshot");
@@ -1801,11 +2036,16 @@ export const makeStream = (config) => {
         // (`verifySnapshot` is ignored).
         if (snapshot === undefined) {
             const events = yield* read(streamId, options);
-            return {
+            // Any sealing event read (#166), not only the newest: a write past
+            // the seal leaves it behind the head (`seal.version < version`).
+            const seal = events.find((event) => event.sealed === true);
+            const state = {
                 snapshot: Option.none(),
                 events,
                 version: events[events.length - 1]?.version ?? 0,
+                ...(seal !== undefined ? { seal } : {}),
             };
+            return state;
         }
         // `verifySnapshot: false` — the snapshot item alone, by its exact key:
         // a `GetItem` reads one item where the verified `Query` reads the
@@ -1819,11 +2059,29 @@ export const makeStream = (config) => {
             const raw = yield* getSnapshotItem(streamId, options.consistentRead === true);
             if (raw !== undefined) {
                 const current = yield* decodeSnapshotItem(raw, "EventStore.readLatest");
-                return {
-                    snapshot: Option.some(current),
-                    events: [],
-                    version: current.asOfVersion,
-                };
+                // A snapshot written by a sealing append carries the marker (#166):
+                // its version is the seal's, so one `GetItem` of that event returns
+                // the sealing event — paid only on a sealed stream.
+                if (raw[SEALED_ATTRIBUTE] !== true) {
+                    const state = {
+                        snapshot: Option.some(current),
+                        events: [],
+                        version: current.asOfVersion,
+                    };
+                    return state;
+                }
+                const sealRaw = yield* getEventItem(streamId, current.asOfVersion, options.consistentRead === true);
+                // Missing only if the data was corrupted: fall through to the
+                // verified read, which reports what the stream holds.
+                if (sealRaw !== undefined) {
+                    const state = {
+                        snapshot: Option.some(current),
+                        events: [],
+                        version: current.asOfVersion,
+                        seal: yield* decodeStreamEvent(sealRaw),
+                    };
+                    return state;
+                }
             }
         }
         const client = yield* DynamoClient;
@@ -1895,11 +2153,28 @@ export const makeStream = (config) => {
         const asOfVersion = Option.isSome(latest) ? latest.value.asOfVersion : 0;
         const delta = eventRaws.filter((raw) => raw.version > asOfVersion).reverse();
         const events = yield* Effect.forEach(delta, (raw) => decodeStreamEvent(raw));
-        return {
+        // The sealing event (#166), from ANY event item the query fetched —
+        // including those at or below the snapshot, which `events` leaves out
+        // (a snapshot at the seal already folds it in) — with no extra request.
+        // The oldest marked item is the seal; anything after it was written
+        // past it.
+        let sealRaw;
+        for (const raw of eventRaws) {
+            if (raw[SEALED_ATTRIBUTE] === true)
+                sealRaw = raw;
+        }
+        const seal = sealRaw === undefined
+            ? undefined
+            : sealRaw.version > asOfVersion
+                ? events.find((event) => event.version === sealRaw.version)
+                : yield* decodeStreamEvent(sealRaw);
+        const state = {
             snapshot: latest,
             events,
             version: events[events.length - 1]?.version ?? asOfVersion,
+            ...(seal !== undefined ? { seal } : {}),
         };
+        return state;
     });
     // ---------------------------------------------------------------------------
     // hasCommandSentinel (internal — see CommandSentinelProbe)
@@ -2121,6 +2396,7 @@ export const makeStream = (config) => {
         writeSnapshot: checked(writeSnapshot),
         readSnapshot: checked(readSnapshot),
         append: checked(append),
+        appendOp,
         read: checked(read),
         readFrom: checked(readFrom),
         currentVersion: checked(currentVersion),
@@ -2179,6 +2455,17 @@ export const bind = (stream) => Effect.gen(function* () {
         writeSnapshot: (streamId, state, asOfVersion) => provide(stream.writeSnapshot(streamId, state, asOfVersion)),
         readSnapshot: (streamId) => provide(stream.readSnapshot(streamId)),
         append: (streamId, events, expectedVersion, options) => provide(stream.append(streamId, events, expectedVersion, options)),
+        // Built in the captured context (#166): only its TableConfig and
+        // Compression are used — the outer append sends the items.
+        appendOp: (streamId, events, expectedVersion, options) => {
+            const op = stream.appendOp(streamId, events, expectedVersion, options);
+            const bound = {
+                [StreamAppendTypeId]: StreamAppendTypeId,
+                streamName: op.streamName,
+                _build: (source) => provide(op._build(source)),
+            };
+            return bound;
+        },
         read: (streamId, options) => provide(stream.read(streamId, options)),
         readFrom: (streamId, afterVersion, options) => provide(stream.readFrom(streamId, afterVersion, options)),
         currentVersion: (streamId, options) => provide(stream.currentVersion(streamId, options)),
@@ -2425,11 +2712,58 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
     const unverifiedReadOptions = { ...readOptions, verifySnapshot: false };
     return (streamId, command, callOptions) => {
         const expectedVersion = callOptions?.expectedVersion;
+        /** This handler's stream id, as `append` reports it on errors. */
+        const ownStreamId = formatStreamIdOf(stream, streamId);
+        /**
+         * Whether a `VersionConflict` names this handler's stream — not another
+         * stream whose `appendOp` rode in `additionalItems` (#166).
+         */
+        const isOwnConflict = (error) => error.streamName === stream.streamName && error.streamId === ownStreamId;
+        // A redelivery of a command that already committed: `append` ranks
+        // `DuplicateCommand` above `VersionConflict` and `StreamSealed`, so the
+        // pre-decide answers consult the command's sentinel first (one strongly
+        // consistent `GetItem`, on those paths only).
+        const failIfCommitted = Effect.gen(function* () {
+            const probe = commandSentinelProbeOf(stream);
+            const commandId = callOptions?.commandId;
+            if (options?.idempotency !== undefined && commandId !== undefined && probe !== undefined) {
+                if (yield* probe(streamId, commandId)) {
+                    return yield* new DuplicateCommand({
+                        streamName: stream.streamName,
+                        streamId: ownStreamId,
+                        commandId,
+                    });
+                }
+            }
+        });
+        // A sealed stream accepts no command (#166) — not even a no-op decision —
+        // so a load that shows the seal fails before `decide`, ahead of the
+        // If-Match check: no retry can succeed, and the caller's move is to the
+        // successor stream.
+        const refuseSealed = (loaded) => Effect.gen(function* () {
+            const sealedVersion = loaded.sealedVersion;
+            if (sealedVersion === undefined)
+                return loaded;
+            yield* failIfCommitted;
+            if (sealedVersion < loaded.version) {
+                // Written past the seal by a writer that does not enforce it: on a
+                // closed stream nobody reads, so the application must recover them.
+                yield* Effect.logWarning(`EventStore: stream "${stream.streamName}" (${ownStreamId}) is sealed at version ` +
+                    `${sealedVersion}, but has events past the seal: versions ${sealedVersion + 1}` +
+                    `${loaded.version > sealedVersion + 1 ? `…${loaded.version}` : ""}.`);
+            }
+            return yield* new StreamSealed({
+                streamName: stream.streamName,
+                streamId: ownStreamId,
+                sealedVersion,
+            });
+        });
         // 1. Establish the base state + version. A snapshot-configured stream
         //    loads its snapshot, the events after it and its head in one request
         //    (#138) — or, unverified, the snapshot item alone; any other stream
         //    replays from the beginning.
-        const load = (verify) => Effect.gen(function* () {
+        const load = (verify) => Effect.flatMap(loadUnchecked(verify), (loaded) => refuseSealed(loaded));
+        const loadUnchecked = (verify) => Effect.gen(function* () {
             let state = decider.initialState;
             // The caller's own record (#164), trusted as the head: the append's
             // check (or the head proof) catches one that is not.
@@ -2451,6 +2785,7 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
                         snapshotAsOfVersion: undefined,
                         verified: true,
                         eventsAfterSnapshot: 0,
+                        sealedVersion: undefined,
                     };
                     return fresh;
                 }
@@ -2459,12 +2794,20 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
                     return yield* refused(`loadState returned version ${String(record.version)}: it must be a non-negative ` +
                         "integer, the stream version the state is as of. Nothing was written.");
                 }
+                const sealedVersion = record.sealedVersion;
+                if (sealedVersion !== undefined &&
+                    (!Number.isInteger(sealedVersion) || sealedVersion < record.version)) {
+                    return yield* refused(`loadState returned sealedVersion ${String(sealedVersion)}: it must be a ` +
+                        `non-negative integer, not below the record's version ${record.version} — the ` +
+                        "version of the stream's sealing event. Nothing was written.");
+                }
                 const loaded = {
                     state: record.state,
                     version: record.version,
                     snapshotAsOfVersion: undefined,
                     verified: true,
                     eventsAfterSnapshot: 0,
+                    sealedVersion,
                 };
                 return loaded;
             }
@@ -2486,6 +2829,7 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
                     // already fallen back to the verified read.
                     verified: verify || Option.isNone(latest.snapshot),
                     eventsAfterSnapshot: latest.events.length,
+                    sealedVersion: latest.seal?.version,
                 };
                 return loaded;
             }
@@ -2499,6 +2843,8 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
                 snapshotAsOfVersion: 0,
                 verified: true,
                 eventsAfterSnapshot: events.length,
+                // Any sealing event (#166), not only the newest.
+                sealedVersion: events.find((event) => event.sealed === true)?.version,
             };
             return loaded;
         });
@@ -2612,8 +2958,10 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
                 appendOptions.headProof = "snapshot";
             }
             const appended = stream.append(streamId, newEvents, baseVersion, appendOptions);
+            // Only this stream's conflict can mean a lagging snapshot: one naming
+            // another stream (a nested `appendOp`, #166) propagates.
             const outcome = yield* returnAppendConflict
-                ? appended.pipe(Effect.catchIf((error) => error instanceof VersionConflict, (conflict) => Effect.succeed(conflict)))
+                ? appended.pipe(Effect.catchIf((error) => error instanceof VersionConflict && isOwnConflict(error), (conflict) => Effect.succeed(conflict)))
                 : appended;
             if (outcome instanceof VersionConflict)
                 return outcome;
@@ -2642,20 +2990,10 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
         // consult the sentinel before reporting the conflict. The extra read is
         // paid on this conflict path only.
         const ifMatchMismatch = (expected, actualVersion) => Effect.gen(function* () {
-            const probe = commandSentinelProbeOf(stream);
-            const commandId = callOptions?.commandId;
-            if (options?.idempotency !== undefined && commandId !== undefined && probe !== undefined) {
-                if (yield* probe(streamId, commandId)) {
-                    return yield* new DuplicateCommand({
-                        streamName: stream.streamName,
-                        streamId: formatStreamIdOf(stream, streamId),
-                        commandId,
-                    });
-                }
-            }
+            yield* failIfCommitted;
             return yield* new VersionConflict({
                 streamName: stream.streamName,
-                streamId: formatStreamIdOf(stream, streamId),
+                streamId: ownStreamId,
                 expectedVersion: expected,
                 actualVersion,
             });
@@ -2801,9 +3139,11 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
             return (yield* commit(verified, newEvents, false));
         });
         // A caller-supplied `expectedVersion` is a conditional write: its
-        // `VersionConflict` (pre-decide or from the append) is the answer, never a
-        // cue to re-read and re-decide.
-        return schedule === undefined || expectedVersion !== undefined
+        // `VersionConflict` of this stream (pre-decide or from the append) is the
+        // answer, never a cue to re-read and re-decide. A conflict naming another
+        // stream (a nested `appendOp`, #166) is retried either way: the If-Match
+        // was not wrong, and the retried attempt checks it again on its reload.
+        return schedule === undefined
             ? attempt
             : Effect.retry(attempt, {
                 // `while` runs before the schedule, so the schedule only ever sees a
@@ -2811,10 +3151,12 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
                 // because `Retry.Options` demands a schedule whose input accepts the
                 // effect's *full* error union, and `Schedule` is contravariant on input.
                 schedule: schedule,
-                // `VersionConflict` only. `DuplicateCommand` is terminal — the same
-                // commandId can never succeed — and `AdditionalItemConditionFailed`
-                // will not resolve itself by re-deciding either.
-                while: (error) => error instanceof VersionConflict,
+                // `VersionConflict` only. `DuplicateCommand` and `StreamSealed` are
+                // terminal — the same commandId, or a sealed stream, can never
+                // succeed — and `AdditionalItemConditionFailed` will not resolve
+                // itself by re-deciding either.
+                while: (error) => error instanceof VersionConflict &&
+                    (expectedVersion === undefined || !isOwnConflict(error)),
             });
     };
 };