effect-dynamodb 1.31.0 → 1.33.0

package/dist/EventStore.js

@@ -11,7 +11,15 @@
  * - `commandHandler` combinator for the load-decide-fold-append cycle
  *   (snapshot-aware single-request loads, consistent loads, an optional
  *   `VersionConflict` retry policy, caller-supplied `expectedVersion`,
- *   decision-derived `additionalItems`, inline snapshots)
+ *   decision-derived `additionalItems`, inline snapshots, a caller's own
+ *   state record as the load via `loadState`)
+ * - 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`,
@@ -37,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";
@@ -48,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, 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";
@@ -129,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
@@ -147,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`). */
@@ -410,6 +484,38 @@ const unverifiedSnapshotRefusal = (streamName, settings, operation) => settings
         `snapshot mode "inline" without "every" — the only mode that writes the snapshot in every ` +
         `append, so it is normally at the head. This stream's snapshot is mode "${settings.mode}"` +
         `${settings.every === undefined ? "" : ` with every: ${settings.every}`}.`;
+/**
+ * @internal `[EDD-9085]`: a snapshot head proof (`headProof: "snapshot"`) is
+ * accepted only by a stream whose snapshot is written in every append
+ * (`mode: "inline"` without `every`) — any other snapshot lags the head by
+ * design, and would fail the proof's condition. Returns the refusal message,
+ * or `undefined` when the stream accepts it.
+ */
+const snapshotProofRefusal = (streamName, settings, operation) => settings !== undefined && settings.mode === "inline" && settings.every === undefined
+    ? undefined
+    : `[EDD-9085] EventStream "${streamName}": ${operation} with headProof: "snapshot" requires ` +
+        `snapshot mode "inline" without "every" — the only mode that writes the snapshot in every ` +
+        `append, so it can prove the head. ` +
+        (settings === undefined
+            ? "This stream has no snapshot config."
+            : `This stream's snapshot is mode "${settings.mode}"` +
+                `${settings.every === undefined ? "" : ` with every: ${settings.every}`}.`);
+/**
+ * @internal Why a `headProof` is malformed — not `"snapshot"` nor
+ * `{ additionalItem: n }` with `n` a non-negative integer — or `undefined`
+ * when it is well-formed.
+ */
+const headProofShapeProblem = (headProof) => {
+    if (headProof === "snapshot")
+        return undefined;
+    const n = typeof headProof === "object" && headProof !== null
+        ? headProof.additionalItem
+        : undefined;
+    return typeof n === "number" && Number.isInteger(n) && n >= 0
+        ? undefined
+        : `headProof must be "snapshot" or { additionalItem: n } with n a non-negative integer; ` +
+            `received ${JSON.stringify(headProof) ?? String(headProof)}. Nothing was written.`;
+};
 /**
  * @internal Why an `eventTimestamps` value cannot be written for `count`
  * events — not an array, the wrong length, or an entry that is neither a
@@ -583,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
@@ -817,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
@@ -935,16 +1045,34 @@ 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.
+            const proofFailed = tx.headProof === "snapshot"
+                ? failedAt(tx.snapshotIndex)
+                : tx.headProof !== undefined &&
+                    opConditionFailed(tx.additional, rawReasons, tx.headProof.additionalItem, tx.guardCount + tx.eventCount);
+            if (proofFailed) {
+                return Effect.fail(new VersionConflict({
+                    streamName: config.streamName,
+                    streamId: streamIdStr,
+                    expectedVersion: tx.expectedVersion,
+                }));
             }
             // The additional items, attributed back to the caller OPS that
             // produced them (several items can belong to one op). Only an op's
@@ -952,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") {
@@ -1062,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
@@ -1101,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);
     });
     /**
@@ -1153,6 +1290,69 @@ export const makeStream = (config) => {
         if (snapshotState !== undefined && snapshot === undefined) {
             return yield* snapshotUnavailable("append({ snapshot })");
         }
+        // The head proof (#164), checked ahead of the no-op fast path, as the
+        // per-event options are. An index into `additionalItems` is checked by
+        // `append`, which has them (`measureAppend` does not take them).
+        const headProof = options?.headProof;
+        if (headProof !== undefined) {
+            const problem = headProofShapeProblem(headProof);
+            if (problem !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.headProof",
+                    cause: problem,
+                });
+            }
+            if (headProof === "snapshot") {
+                const refusal = snapshotProofRefusal(config.streamName, snapshotSettings, 'append({ headProof: "snapshot" })');
+                if (refusal !== undefined)
+                    return yield* Effect.die(new Error(refusal));
+                if (snapshotState === undefined) {
+                    return yield* new ValidationError({
+                        entityType: snapshotEntityType,
+                        operation: "EventStore.append.headProof",
+                        cause: 'headProof: "snapshot" requires the inline snapshot it names: pass `snapshot` ' +
+                            "with the state as of this append. Nothing was written.",
+                    });
+                }
+            }
+        }
+        // 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
@@ -1180,7 +1380,8 @@ export const makeStream = (config) => {
         // (#144): an append is never split — splitting would break its
         // atomicity — so one over the limit is rejected whole by DynamoDB and
         // reported as `AppendTooLarge`, with the expanded item count.
-        const needsContiguityCheck = expectedVersion > 0 && events.length > 0;
+        // A head proof (#164) proves the same thing, so it replaces the check.
+        const needsContiguityCheck = expectedVersion > 0 && events.length > 0 && headProof === undefined;
         const tableConfig = yield* config.table.Tag;
         const tableName = tableConfig.name;
         // A custom TTL attribute is only known at runtime. An index key attribute
@@ -1308,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" } : {}),
                 },
             };
         }));
@@ -1347,16 +1557,38 @@ 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.
+        // The inline snapshot (#138): unconditional — see AppendOptions.snapshot
+        // — unless it is the head proof (#164), when it is conditioned on being
+        // at `expectedVersion`. Packed per `snapshot.storedAs` (#147), so the
+        // 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);
+            // As a head proof, a sealed snapshot fails the proof (#166), and
+            // returns its item so the failure is reported as `StreamSealed`.
             snapshotPut = {
-                Put: {
-                    TableName: tableName,
-                    Item: yield* buildSnapshotItem(streamId, snapshotState, expectedVersion + events.length, now, "EventStore.append.snapshot", eventPartitions),
-                },
+                Put: headProof !== "snapshot"
+                    ? { TableName: tableName, Item: item }
+                    : expectedVersion === 0
+                        ? {
+                            TableName: tableName,
+                            Item: item,
+                            ConditionExpression: "attribute_not_exists(pk)",
+                            ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+                        }
+                        : {
+                            TableName: tableName,
+                            Item: item,
+                            ConditionExpression: "#asOfVersion = :expectedVersion AND attribute_not_exists(#sealed)",
+                            ExpressionAttributeNames: {
+                                "#asOfVersion": "asOfVersion",
+                                "#sealed": SEALED_ATTRIBUTE,
+                            },
+                            ExpressionAttributeValues: toAttributeMap({
+                                ":expectedVersion": expectedVersion,
+                            }),
+                            ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+                        },
             };
         }
         /**
@@ -1370,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;
@@ -1393,6 +1632,22 @@ export const makeStream = (config) => {
     const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
         const additionalOps = options?.additionalItems ?? [];
         const idempotency = options?.idempotency;
+        const headProof = options?.headProof;
+        // The additional item a head proof names (#164) must exist — checked
+        // before anything is read, and ahead of the no-op fast path. Its shape
+        // is checked first, by `buildAppend`'s own rule.
+        const proofOp = typeof headProof === "object" && headProofShapeProblem(headProof) === undefined
+            ? headProof.additionalItem
+            : undefined;
+        if (proofOp !== undefined && proofOp >= additionalOps.length) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "EventStore.append.headProof",
+                cause: `headProof names additionalItems[${proofOp}], but the append has ` +
+                    `${additionalOps.length} additional item${additionalOps.length === 1 ? "" : "s"}. ` +
+                    "Nothing was written.",
+            });
+        }
         const parts = yield* buildAppend(streamId, events, expectedVersion, options);
         if (parts === undefined)
             return { version: expectedVersion, events: [] };
@@ -1449,6 +1704,7 @@ export const makeStream = (config) => {
                 sentinelIndex,
                 snapshotIndex,
                 expectedVersion,
+                headProof,
             };
         };
         // A guarded put among the additional items reads its item; a race with
@@ -1457,7 +1713,26 @@ 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. 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: 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);
             // DynamoDB's rules — one operation per item (an additional item
             // repeating an event, the contiguity check, the idempotency sentinel
@@ -1475,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* () {
@@ -1664,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");
@@ -1680,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
@@ -1698,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;
@@ -1774,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)
@@ -2000,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),
@@ -2058,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)),
@@ -2264,6 +2672,34 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
     }
     // Ignored on a stream without a snapshot config: there is no snapshot to trust.
     const unverifiedLoads = options?.verifySnapshot === false && snapshotSettings !== undefined;
+    // The head proof and a caller's load (#164), refused up front (EDD-9085)
+    // when they cannot work together or on this stream.
+    const loadState = options?.loadState;
+    const headProof = options?.headProof;
+    const refuse = (problem) => {
+        throw new Error(`[EDD-9085] EventStream "${stream.streamName}": commandHandler ${problem}`);
+    };
+    if (loadState !== undefined && typeof loadState !== "function") {
+        refuse("loadState must be a function of the stream id.");
+    }
+    if (headProof !== undefined) {
+        const problem = headProofShapeProblem(headProof);
+        if (problem !== undefined)
+            refuse(problem.replace(" Nothing was written.", ""));
+        if (headProof === "snapshot") {
+            const refusal = snapshotProofRefusal(stream.streamName, snapshotSettings, "commandHandler");
+            if (refusal !== undefined)
+                throw new Error(refusal);
+        }
+    }
+    if (loadState !== undefined && options?.verifySnapshot === false) {
+        refuse("with loadState and verifySnapshot: false — loadState replaces the stream load, so " +
+            "there is no snapshot load to leave unverified.");
+    }
+    if (loadState !== undefined && headProof === "snapshot") {
+        refuse('with loadState and headProof: "snapshot" — the handler never reads the snapshot, so ' +
+            "it cannot know the snapshot is at the head.");
+    }
     const retryPolicy = options?.retry;
     const schedule = retryPolicy === undefined
         ? undefined
@@ -2276,12 +2712,105 @@ 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.
+            if (loadState !== undefined) {
+                const result = yield* loadState(streamId);
+                const refused = (cause) => new ValidationError({
+                    entityType: stream.streamName,
+                    operation: "EventStore.commandHandler.loadState",
+                    cause,
+                });
+                if (!Option.isOption(result)) {
+                    return yield* refused("loadState must return an Option of { state, version }: None for a new stream. " +
+                        "Nothing was written.");
+                }
+                if (Option.isNone(result)) {
+                    const fresh = {
+                        state,
+                        version: 0,
+                        snapshotAsOfVersion: undefined,
+                        verified: true,
+                        eventsAfterSnapshot: 0,
+                        sealedVersion: undefined,
+                    };
+                    return fresh;
+                }
+                const record = result.value;
+                if (!Number.isInteger(record.version) || record.version < 0) {
+                    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;
+            }
             if (snapshotSettings !== undefined) {
                 const latest = (yield* stream.readLatest(streamId, verify ? readOptions : unverifiedReadOptions));
                 let snapshotAsOfVersion = 0;
@@ -2300,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;
             }
@@ -2313,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;
         });
@@ -2400,17 +2932,36 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
             }
             // Inline snapshots (#138) ride in the append transaction: on every
             // append, or once `every` events have accumulated since the snapshot.
+            // A `loadState` load never saw the snapshot (#164), so its cadence is
+            // an append that crosses a multiple of `every`.
             const mode = snapshotSettings?.mode ?? "after-append";
             const every = snapshotSettings?.every;
             const newVersion = baseVersion + newEvents.length;
+            const snapshotDue = (version) => every !== undefined &&
+                (loaded.snapshotAsOfVersion === undefined
+                    ? Math.floor(version / every) > Math.floor(baseVersion / every)
+                    : version - loaded.snapshotAsOfVersion >= every);
             if (snapshotSettings !== undefined &&
                 mode === "inline" &&
-                (every === undefined || newVersion - loaded.snapshotAsOfVersion >= every)) {
+                (every === undefined || snapshotDue(newVersion))) {
                 appendOptions.snapshot = next;
             }
+            // The head proof (#164). The caller's record proves it on every
+            // append; the inline snapshot only when this load found it at the
+            // head — a lagging one would fail the condition, so the check stays.
+            if (typeof headProof === "object") {
+                appendOptions.headProof = headProof;
+            }
+            else if (headProof === "snapshot" &&
+                appendOptions.snapshot !== undefined &&
+                loaded.snapshotAsOfVersion === baseVersion) {
+                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;
@@ -2419,9 +2970,7 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
             //    Best-effort: the events are already durable, so a snapshot-write
             //    failure must not report the command as failed. The next threshold
             //    crossing retries it.
-            if (mode === "after-append" &&
-                every !== undefined &&
-                result.version - loaded.snapshotAsOfVersion >= every) {
+            if (mode === "after-append" && snapshotDue(result.version)) {
                 yield* stream
                     .writeSnapshot(streamId, next, result.version)
                     .pipe(Effect.catchCause((cause) => Effect.logWarning(`EventStore: snapshot write failed for stream "${stream.streamName}" at version ${result.version}`, cause)));
@@ -2441,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,
             });
@@ -2600,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
@@ -2610,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)),
             });
     };
 };