effect-dynamodb 1.31.0 → 1.33.0

package/dist/EventStore.d.ts

@@ -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`,
@@ -36,13 +44,13 @@
 import type { AttributeDefinition, GlobalSecondaryIndex, LocalSecondaryIndex } from "@aws-sdk/client-dynamodb";
 import { type PackedConfig } from "@effect-dynamodb/schema/DynamoModel.js";
 import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.js";
-import { AdditionalItemConditionFailed, AppendTooLarge, type ConcurrentModification, DuplicateCommand, type OptimisticLockError, TransactionCancelled, type UniqueConstraintViolation, ValidationError, VersionConflict } from "@effect-dynamodb/schema/Errors.js";
+import { AdditionalItemConditionFailed, AppendTooLarge, type ConcurrentModification, DuplicateCommand, type OptimisticLockError, StreamSealed, TransactionCancelled, type UniqueConstraintViolation, ValidationError, VersionConflict } from "@effect-dynamodb/schema/Errors.js";
 import { DateTime, type Duration, Effect, Option, Pipeable, Schedule, Schema } from "effect";
 import { DynamoClient, type DynamoClientError } from "./DynamoClient.js";
 import { type EventProjection } from "./internal/EventProjection.js";
 import { type MultiProjection, type MultiSource } from "./internal/MultiProjection.js";
 import { type StreamImage } from "./internal/Packed.js";
-import { type TransactWriteOp } from "./internal/TransactWriteOps.js";
+import { type AppendWriteOp, type StreamAppendOp } from "./internal/TransactWriteOps.js";
 import * as Query from "./Query.js";
 import { type Table, type TableConfig } from "./Table.js";
 /**
@@ -81,6 +89,18 @@ export interface StreamEvent<A, M = Record<string, unknown> | undefined> {
      * ({@link AppendOptionsBase.eventTimestamps}).
      */
     readonly timestamp: string;
+    /**
+     * Present, and `true`, only on a sealing event: the stream's final event
+     * (see {@link AppendOptionsBase.seal}). Absent on every other event.
+     *
+     * Read from the item's `__edd_sealed__` marker, so it is reported by every
+     * read of the item itself — `read`, `readFrom`, `query.events`,
+     * `readLatest`, `decodeStreamImage`, and a stream index of projection
+     * `"all"` or `"keys"` — but not through a `"withoutMetadata"` index (whose
+     * projection does not include the marker), nor on a raw row whose
+     * `Query.select` projection omits it.
+     */
+    readonly sealed?: true;
 }
 /**
  * A {@link StreamEvent} together with the event's stored `data` in its wire
@@ -219,7 +239,8 @@ export interface AppendMeasurement {
      * What the stream's own actions (the contiguity check, the event puts, the
      * sentinel and the inline snapshot) add to the `TransactWriteItems` request
      * — its 4 MB (4,194,304-byte) limit counts items, keys and expressions.
-     * Caller `additionalItems` are not included: add their size yourself.
+     * Caller `additionalItems` are not included: add their size yourself. With
+     * a `headProof` there is no contiguity check to count.
      */
     readonly transactionBytes: number;
 }
@@ -316,6 +337,20 @@ export type AppendMetadataOptions<TMetadata> = {
      */
     readonly eventMetadata?: ReadonlyArray<TMetadata | undefined>;
 };
+/**
+ * The item of an {@link EventStream.append} that proves the stream head is at
+ * `expectedVersion`, in place of the version-contiguity `ConditionCheck` (see
+ * {@link AppendOptionsBase.headProof}).
+ *
+ * - `{ additionalItem: n }` — `additionalItems[n]`, whose own condition holds
+ *   only when the stream is at `expectedVersion` (the caller's state record,
+ *   conditioned on the version it was loaded at, or on its absence at 0).
+ * - `"snapshot"` — the append's inline snapshot, conditioned on
+ *   `asOfVersion = expectedVersion`.
+ */
+export type HeadProof = {
+    readonly additionalItem: number;
+} | "snapshot";
 /**
  * The options of {@link EventStream.append} other than its metadata (see
  * {@link AppendMetadataOptions}).
@@ -341,8 +376,21 @@ export interface AppendOptionsBase<TState = never> {
      * the entity's put would: `UniqueConstraintViolation`, a history
      * `ValidationError`, or — a race lost on every attempt —
      * `OptimisticLockError` / `ConcurrentModification`.
+     *
+     * **Another stream's append** (#166): `otherStream.appendOp(...)` (see
+     * {@link EventStream.appendOp}) rides here too, so several streams' events
+     * commit together or not at all — and a stream can be sealed in the same
+     * transaction that opens its successor. Its failures name the inner stream
+     * (`StreamSealed`, `VersionConflict`), judged after this stream's own and
+     * ahead of the other items' errors.
+     *
+     * The element type is {@link AppendWriteOp}, wider than the
+     * `TransactWriteOp` that `Transaction.transactWrite` takes. Passing a
+     * `TransactWriteOp[]` here is unaffected; code that reads this property's
+     * type and forwards the value to `transactWrite` must annotate it
+     * `ReadonlyArray<TransactWriteOp>`.
      */
-    readonly additionalItems?: ReadonlyArray<TransactWriteOp>;
+    readonly additionalItems?: ReadonlyArray<AppendWriteOp>;
     /** Opt in to exactly-once command processing — see {@link AppendIdempotency}. */
     readonly idempotency?: AppendIdempotency;
     /**
@@ -380,6 +428,107 @@ export interface AppendOptionsBase<TState = never> {
      *   repeat, run backwards or lie in the future, as imported history can.
      */
     readonly eventTimestamps?: ReadonlyArray<DateTime.DateTime | undefined>;
+    /**
+     * The item that proves the stream head is at `expectedVersion`, in place of
+     * the version-contiguity `ConditionCheck`. Omitted: the check is written.
+     *
+     * The check reads the event at `expectedVersion`, and DynamoDB bills a
+     * `ConditionCheck` inside a transaction at 2 WCU per KB of the checked
+     * item, so with large events it is a sizeable part of every append. The
+     * event puts already reject a stale `expectedVersion`; the check rejects
+     * one that is ahead of the head, which would leave a gap. An item whose own
+     * condition holds only at `expectedVersion` proves that just as well.
+     *
+     * - `{ additionalItem: n }` — `additionalItems[n]` is the proof. It must
+     *   carry a condition of its own (`.condition()`, `create()`,
+     *   `Transaction.check`); one without, or an `n` that is not an index into
+     *   `additionalItems`, fails with `ValidationError` before anything is
+     *   written. When that condition fails, the append fails with
+     *   `VersionConflict` — never `AdditionalItemConditionFailed` — judged
+     *   after `DuplicateCommand` and the event puts, ahead of the other items.
+     *
+     *   **The caller owns the invariant**: every writer of the stream (a
+     *   handler, an import, a migration, a raw `append`) must write the item in
+     *   the same transaction as its events, conditioned the same way. An append
+     *   without it leaves the item behind the head, and every later append
+     *   fails with `VersionConflict` until it is repaired. Writing the item's
+     *   version without the events it counts moves it ahead of the head — the
+     *   one way to open a gap — so write that version only in their append.
+     * - `"snapshot"` — the inline snapshot is the proof: its `Put` is
+     *   conditioned on `asOfVersion = expectedVersion` (`attribute_not_exists`
+     *   at version 0), and a failure is a `VersionConflict`. Requires
+     *   `snapshot` (else `ValidationError`) and a stream whose snapshot config
+     *   is `mode: "inline"` without `every` (else a defect, `[EDD-9085]`). A
+     *   snapshot can lag the head (a raw `append`, data written before inline
+     *   mode), and then fails the condition: use it only when the snapshot is
+     *   known to be at the head, as {@link CommandHandlerOptions.headProof}
+     *   does.
+     *
+     * **On a sealed stream** ({@link AppendOptionsBase.seal}): a head proof
+     * replaces the contiguity check, which is where the seal is enforced.
+     *
+     * - `"snapshot"`: the sealing append's inline snapshot carries the seal
+     *   marker, and the proof's condition also requires the snapshot to be
+     *   unmarked (`StreamSealed` otherwise). A seal written through a
+     *   definition **without** this snapshot config leaves the snapshot
+     *   unmarked below the seal; a later `writeSnapshot` at the seal version
+     *   then writes an unmarked snapshot there, and a snapshot-proof append can
+     *   land past the seal (see {@link EventStream.writeSnapshot}). Seal through
+     *   a definition that shares the writers' snapshot config.
+     * - `{ additionalItem: n }`: the library does not enforce the seal (it
+     *   cannot know the stream is sealed without a read). Seal such a stream
+     *   with **exactly one event**, and keep the record at the seal's
+     *   `expectedVersion` (one below the seal, with a sealed flag and the
+     *   seal's version for {@link LoadedState.sealedVersion}): every
+     *   record-proof writer then appends at that version, and its first event
+     *   put lands on the sealing event and fails with `StreamSealed`.
+     *   Advancing the record to the seal's version lets a record-proof writer
+     *   append past the seal, unless every writer's record condition also tests
+     *   the sealed flag. A seal of several events leaves a record-proof writer
+     *   on `VersionConflict` instead.
+     */
+    readonly headProof?: HeadProof | undefined;
+    /**
+     * Seal the stream with this append (#166): its **last** event becomes the
+     * stream's final event, and no append can land after it — one that tries
+     * fails with `StreamSealed`. `false` and `undefined` do nothing.
+     *
+     * The append writes events `expectedVersion + 1 … expectedVersion + n`, so
+     * the seal version is `expectedVersion + n`. The library writes a marker
+     * attribute (`__edd_sealed__`) on that event's item, and on the inline
+     * snapshot when the append writes one; reads report it
+     * ({@link StreamEvent.sealed}, {@link LatestState.seal}). A seal is
+     * permanent.
+     *
+     * - A value that is not a boolean, or `true` with no events, fails with
+     *   `ValidationError` (`operation: "EventStore.append.seal"`) before
+     *   anything is written.
+     * - On a stream whose snapshot config is `mode: "inline"` without `every`,
+     *   `true` also requires `snapshot`, so the snapshot at the seal version is
+     *   the marked one and an unverified load sees the seal.
+     * - Combines with every other option. Through another stream's
+     *   `additionalItems` use {@link EventStream.appendOp}.
+     *
+     * **Enforcement.** Every append after version 0 already checks the event
+     * at its `expectedVersion`; that check also requires the event to be
+     * unmarked. A writer that loaded after the seal fails it; one that loaded
+     * just before fails on its first event put, which lands on the sealing
+     * event; both get `StreamSealed`. A writer further behind gets
+     * `VersionConflict` and learns of the seal when it reloads.
+     *
+     * **Upgrade every writer first.** A writer on a library version that does
+     * not enforce the seal, a record-proof writer whose record was advanced to
+     * the seal, or a snapshot-proof writer on an unmarked snapshot at the seal
+     * version can land one event past the seal — and that event, unmarked,
+     * reopens the stream for every writer. Reads still report the seal while
+     * the sealing event is among the items they fetch
+     * (`seal.version < version` on {@link LatestState}).
+     *
+     * Zero-event appends (only `additionalItems` and/or `idempotency`) write no
+     * event, and still land on a sealed stream: a seal stops events, not side
+     * writes.
+     */
+    readonly seal?: boolean | undefined;
 }
 /**
  * Options accepted by {@link EventStream.append}: {@link AppendOptionsBase}
@@ -390,8 +539,22 @@ export interface AppendOptionsBase<TState = never> {
  * union: an interface cannot extend it.
  */
 export type AppendOptions<TMetadata, TState = never> = AppendOptionsBase<TState> & AppendMetadataOptions<TMetadata>;
-/** Error channel of {@link EventStream.append}. */
-export type AppendError = VersionConflict | DuplicateCommand | AdditionalItemConditionFailed | AppendTooLarge | DynamoClientError | ValidationError | TransactionCancelled | UniqueConstraintViolation | OptimisticLockError | ConcurrentModification;
+/**
+ * The options of {@link EventStream.appendOp}: those of
+ * {@link EventStream.append} except `additionalItems`, `idempotency` and
+ * `headProof`, which a nested append may not carry (they are refused with
+ * `ValidationError` at runtime too, `operation: "EventStore.appendOp"`).
+ * The appending stream carries them: a record the nested stream's writers
+ * load goes in the OUTER append's `additionalItems`.
+ */
+export type NestedAppendOptions<TMetadata, TState = never> = Omit<AppendOptionsBase<TState>, "additionalItems" | "idempotency" | "headProof"> & AppendMetadataOptions<TMetadata>;
+export type { AppendWriteOp, StreamAppendOp };
+/**
+ * Error channel of {@link EventStream.append}. A nested
+ * {@link EventStream.appendOp}'s failures are reported through it too, naming
+ * the inner stream.
+ */
+export type AppendError = VersionConflict | StreamSealed | DuplicateCommand | AdditionalItemConditionFailed | AppendTooLarge | DynamoClientError | ValidationError | TransactionCancelled | UniqueConstraintViolation | OptimisticLockError | ConcurrentModification;
 /**
  * Options accepted by {@link EventStream.read}, {@link EventStream.readFrom} and
  * {@link EventStream.currentVersion}.
@@ -455,11 +618,30 @@ export interface ReadLatestOptions extends ReadOptions {
  *   present, it is the snapshot's `asOfVersion` and `events` is empty —
  *   **unverified**: events appended without a snapshot (a raw `append`, data
  *   written before `mode: "inline"`) may follow it.
+ * - `seal` — the sealing event, when the read found one (see
+ *   {@link AppendOptionsBase.seal}).
  */
 export interface LatestState<TState, TEvent, M = Record<string, unknown> | undefined> {
     readonly snapshot: Option.Option<Snapshot<TState>>;
     readonly events: ReadonlyArray<StreamEvent<TEvent, M>>;
     readonly version: number;
+    /**
+     * The sealing event when the read found one, absent otherwise. It is
+     * separate from `events` because `events` holds only what follows the
+     * snapshot, and a snapshot written by the sealing append already folds it
+     * in (it is in `events` too when it follows the snapshot).
+     *
+     * Found from **any** sealed event among the items the read fetches, not
+     * only the newest, with no extra request — except with
+     * `verifySnapshot: false`, where a sealed snapshot costs one `GetItem` of
+     * the sealing event. An unverified read of a snapshot left unmarked (a seal
+     * written through a definition without this snapshot config) does not
+     * report it.
+     *
+     * `seal.version < version` means events were written past the seal by a
+     * writer that does not enforce it: they are on a closed stream.
+     */
+    readonly seal?: StreamEvent<TEvent, M>;
 }
 /**
  * The stream id as a stream's index functions receive it: the value of each
@@ -883,6 +1065,23 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
      * infers the `pipe` subject. Method syntax makes the parameter bivariant, so
      * `EventStream<E, F, M, never>` unifies with `EventStream<E, F, M, TState>`
      * again. Callers are unaffected: supplying a `state` still requires `TState`.
+     *
+     * **Sealed streams** ({@link AppendOptionsBase.seal}): `writeSnapshot` is
+     * one plain conditional `PutItem`. It does not know whether the stream is
+     * sealed and never writes the seal marker, so it **must not target a sealed
+     * head with an unmarked snapshot**. Skip sealed streams in a job that
+     * snapshots streams (`readLatest(...).seal` is present), or seal through a
+     * definition that shares the writers' snapshot config: the sealing append
+     * then writes a marked snapshot at the seal version, which this monotonic
+     * write never replaces.
+     *
+     * The residual when it does: a stream sealed at `S` through a definition
+     * without the writers' `mode: "inline"`-without-`every` snapshot config
+     * keeps an unmarked snapshot below `S`; a `writeSnapshot` at `S` then puts
+     * an unmarked snapshot at the seal version, and an append with
+     * `headProof: "snapshot"` at `S` passes its proof and lands event `S + 1`
+     * past the seal — which reopens the stream for every writer. A verified
+     * `readLatest` still reports the seal (`seal.version < version`).
      */
     writeSnapshot(streamId: StreamIdInput<TStreamIdFields>, state: TState, asOfVersion: number): Effect.Effect<void, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
     /**
@@ -900,6 +1099,55 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
      * `options.snapshot` is `never`) stays assignable to other streams.
      */
     append(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: AppendOptions<TMetadata, TState> | undefined): Effect.Effect<AppendResult<TEvent>, AppendError, DynamoClient | TableConfig>;
+    /**
+     * An append of this stream as a transact item of ANOTHER stream's append
+     * (its `additionalItems`, or a `commandHandler`'s): it commits if and only
+     * if that append does (#166). Nothing is built or written until the outer
+     * append runs.
+     *
+     * - **With or without `seal`.** Without it, several streams' events commit
+     *   together or not at all (an atomic multi-stream append). With it, a
+     *   stream is sealed in the same transaction that opens its successor:
+     *
+     *   ```ts
+     *   const latest = yield* Ledgers.readLatest(genA, { consistentRead: true })
+     *   yield* Ledgers.append(genB, [new LedgerOpened({ continuesFrom: latest.version })], 0, {
+     *     additionalItems: [
+     *       Ledgers.appendOp(genA, [new LedgerClosed({ continuedIn: "4" })], latest.version, {
+     *         seal: true,
+     *       }),
+     *     ],
+     *   })
+     *   ```
+     * - **The seal's `expectedVersion` is the version the carried-over state
+     *   was read at** — the same `readLatest` result, or the version carried in
+     *   the decided opening event — never a separate read of the stream's head.
+     *   Re-reading the head between the carry-over read and the commit seals
+     *   over an append the opening event never carried, and that append is
+     *   lost. With the carry-over version, a stale append in between fails the
+     *   seal's check instead (`VersionConflict` naming this stream): re-read and
+     *   build both again.
+     * - It is a full append of this stream — its contiguity check, event puts,
+     *   seal marker and optional inline snapshot (`seal`, `snapshot`,
+     *   `metadata` / `eventMetadata`, `eventTimestamps`) — enforced
+     *   independently of the outer append. It may not carry `additionalItems`,
+     *   `idempotency` or `headProof` (see {@link NestedAppendOptions}); a record
+     *   this stream's writers load (a `loadState` record, a record head proof)
+     *   is written by the outer append's `additionalItems`, beside this op —
+     *   on a sealing op with `sealedVersion` (see {@link LoadedState}). Zero
+     *   events fail with `ValidationError` (`operation: "EventStore.appendOp"`).
+     * - Its failures name this stream: `StreamSealed` (terminal) or
+     *   `VersionConflict`, judged after the outer stream's own and ahead of
+     *   the other additional items. It cannot be a `headProof` target.
+     * - **One client per append.** Its items are sent in the outer append's
+     *   single `TransactWriteItems`, through the outer append's `DynamoClient`.
+     *   This unbound op resolves this stream's `TableConfig` from the outer
+     *   append's context, which must provide it; a bound stream's op resolves
+     *   it from its own captured context — but never uses its captured client.
+     *   Every table must be reachable through the outer client.
+     * - `Transaction.transactWrite` does not accept it.
+     */
+    appendOp(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: NestedAppendOptions<TMetadata, TState> | undefined): StreamAppendOp;
     /**
      * Read every event of the stream, ascending by version. Pass
      * `{ consistentRead: true }` for read-your-writes — see {@link ReadOptions}.
@@ -943,6 +1191,10 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
      * verified read. Accepted only on a `mode: "inline"` stream without `every`
      * (otherwise a defect, `[EDD-9068]`), ignored on a stream without a
      * `snapshot` config — see {@link ReadLatestOptions}.
+     *
+     * On a sealed stream the result carries the sealing event as `seal` when
+     * the read fetches the sealing event, in any mode (see
+     * {@link LatestState.seal} for the cases it does not).
      */
     readLatest(streamId: StreamIdInput<TStreamIdFields>, options?: ReadLatestOptions | undefined): Effect.Effect<LatestState<TState, TEvent, StreamMetadata<TMetadata>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
     /**
@@ -1191,8 +1443,8 @@ export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<strin
  *   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
@@ -1272,6 +1524,15 @@ export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<
     readSnapshot(streamId: StreamIdInput<TStreamIdFields>): Effect.Effect<Option.Option<Snapshot<TState>>, DynamoClientError | ValidationError, never>;
     /** See {@link EventStream.append}. */
     append(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: AppendOptions<TMetadata, TState> | undefined): Effect.Effect<AppendResult<TEvent>, AppendError, never>;
+    /**
+     * See {@link EventStream.appendOp}. The op builds in this bound stream's
+     * captured context, so it resolves this stream's `TableConfig` (and
+     * `Compression` registry) itself: a stream on another table needs no extra
+     * layer in the outer append. Its items are still sent through the OUTER
+     * append's `DynamoClient` — one transaction cannot span clients — so the
+     * table must be reachable through it.
+     */
+    appendOp(streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: NestedAppendOptions<TMetadata, TState> | undefined): StreamAppendOp;
     /** See {@link EventStream.read}. */
     read(streamId: StreamIdInput<TStreamIdFields>, options?: ReadOptions | undefined): Effect.Effect<ReadonlyArray<StreamEvent<TEvent, StreamMetadata<TMetadata>>>, DynamoClientError | ValidationError, never>;
     /** See {@link EventStream.readFrom}. */
@@ -1406,14 +1667,43 @@ export declare const indexDefinitions: (...streams: ReadonlyArray<{
         };
     };
 }>) => StreamIndexDefinitions;
+/**
+ * The state and stream version a {@link CommandHandlerOptions.loadState}
+ * loads from the caller's own record: `version` is the stream version the
+ * state is as of, which the handler appends after.
+ */
+export interface LoadedState<State> {
+    readonly state: State;
+    readonly version: number;
+    /**
+     * The caller's record says the stream is sealed at this version (#166):
+     * the handler then fails with `StreamSealed` before `decide`, without
+     * spending a transaction (after `DuplicateCommand` for a committed
+     * redelivery). It may be `version + 1`: a record-proof stream keeps its
+     * record one below the seal (see {@link AppendOptionsBase.headProof}).
+     *
+     * Must be a non-negative integer, not below `version` — otherwise the call
+     * fails with `ValidationError`
+     * (`operation: "EventStore.commandHandler.loadState"`). The sealing
+     * transaction writes it: in a changeover, the outer append's
+     * `additionalItems` carries the record beside the sealing `appendOp`.
+     * Without it, a record more than one version below the seal leaves the
+     * handler on `VersionConflict` until its retry schedule ends.
+     */
+    readonly sealedVersion?: number | undefined;
+}
 /**
  * Handler-level configuration for {@link commandHandler}.
  *
  * `idempotency` carries the policy that is fixed for the handler; the
  * `commandId` that identifies one delivery can only be per-call and lives in the
  * handler's own options.
+ *
+ * `State` and `TStreamId` type {@link loadState}: the decider's state, and the
+ * stream id the handler is called with (`any` for a data-last handler, whose
+ * stream is not yet known).
  */
-export interface CommandHandlerOptions {
+export interface CommandHandlerOptions<State = any, TStreamId = any> {
     /**
      * Retry policy applied to `VersionConflict` **only**.
      *
@@ -1427,9 +1717,16 @@ export interface CommandHandlerOptions {
      * A number `n` is shorthand for `Schedule.recurs(n)` (n retries *after* the
      * initial attempt). Omit for the default: no retry.
      *
-     * `DuplicateCommand` is deliberately NOT retried — it is terminal. Nor is
-     * any call that supplies {@link CommandOptionsBase.expectedVersion}: the caller asked
-     * for a conditional write, so its `VersionConflict` is always surfaced.
+     * `DuplicateCommand` is deliberately NOT retried — it is terminal, as is
+     * `StreamSealed` (#166). Nor is a `VersionConflict` of this stream on a
+     * call that supplies {@link CommandOptionsBase.expectedVersion}: the caller
+     * asked for a conditional write, so it is always surfaced.
+     *
+     * A `VersionConflict` naming **another** stream — a stream's `appendOp`
+     * carried in `additionalItems` (#166) — is retried, with or without an
+     * `expectedVersion`: this stream's If-Match was not wrong, and the retried
+     * attempt reloads this stream and checks the If-Match again before
+     * `decide`. Without a schedule it is returned as-is, naming that stream.
      */
     readonly retry?: number | Schedule.Schedule<unknown, VersionConflict> | undefined;
     /** Opt in to exactly-once command processing — see {@link AppendIdempotency}. */
@@ -1512,7 +1809,72 @@ export interface CommandHandlerOptions {
      * not extra item reads.
      */
     readonly verifySnapshot?: boolean | undefined;
+    /**
+     * Load the state and head from the caller's own record instead of the
+     * stream (#164). `None` is a new stream: the decider's initial state at
+     * version 0.
+     *
+     * The rest of the cycle is unchanged: the If-Match check against the loaded
+     * `version`, `decide`, `evolve`, the derived items, then the append after
+     * `version` — where the caller writes the record, through `additionalItems`.
+     * A `VersionConflict` re-runs `loadState` under the {@link retry} policy, as
+     * a stream load is re-run. A no-op decision or a `decide` failure is
+     * answered from the record: the stream head is not read.
+     *
+     * - **Read strongly consistent.** An eventually consistent read can return
+     *   a record behind the head; the append then fails with `VersionConflict`
+     *   and burns a retry (nothing is corrupted).
+     * - Without {@link headProof} the append still writes the
+     *   version-contiguity check, so a record that is stale or ahead of the
+     *   head conflicts rather than opening a gap. With
+     *   `headProof: { additionalItem: n }`, the record is the proof, and its
+     *   contract (see {@link AppendOptionsBase.headProof}) covers **every**
+     *   writer of the stream.
+     * - A `version` that is not a non-negative integer, or a result that is not
+     *   an `Option`, fails with `ValidationError`
+     *   (`operation: "EventStore.commandHandler.loadState"`), never retried. A
+     *   failure of the `Effect` surfaces as is. Its error and requirements join
+     *   the handler's (a `BoundEventStream` handler's only requirements).
+     * - On a snapshot-configured stream the snapshot is not read, so its
+     *   version is unknown: a `mode: "inline"` stream without `every` still
+     *   writes it in every append; with `every` (inline or after-append), one
+     *   is written when an append crosses a multiple of `every`.
+     * - Refused with {@link verifySnapshot}`: false` (there is no stream load
+     *   to skip) and with `headProof: "snapshot"` (the handler never sees the
+     *   snapshot, so cannot know it is at the head): `[EDD-9085]` when the
+     *   handler is created.
+     */
+    readonly loadState?: ((streamId: TStreamId) => Effect.Effect<Option.Option<LoadedState<State>>, any, any>) | undefined;
+    /**
+     * The item that proves the stream head, in place of the version-contiguity
+     * `ConditionCheck`, on every append the handler makes (see
+     * {@link AppendOptionsBase.headProof}). Omitted: the check is written.
+     *
+     * - `{ additionalItem: n }` — the caller's record at `additionalItems[n]`,
+     *   conditioned on the loaded version (or its absence at version 0). Every
+     *   call whose decision appends must then return that item, carrying its
+     *   own condition; otherwise the call fails with `ValidationError` and
+     *   nothing is written. A failure of its condition is a `VersionConflict`,
+     *   and follows the {@link retry} policy. Usually paired with
+     *   {@link loadState}.
+     * - `"snapshot"` — the inline snapshot, on a `mode: "inline"` stream
+     *   without `every` (any other throws `[EDD-9085]` when the handler is
+     *   created). Applied on an attempt only when its load found the snapshot
+     *   at the head — a verified load with no event after the snapshot, or an
+     *   unverified one ({@link verifySnapshot}`: false`); otherwise that
+     *   append writes the check. A conflict goes through the same stale-snapshot
+     *   handling and retry policy as without it.
+     */
+    readonly headProof?: HeadProof | undefined;
 }
+/** @internal The error of a handler config's {@link CommandHandlerOptions.loadState}. */
+type LoadStateError<TConfig> = TConfig extends {
+    readonly loadState: (...args: any) => Effect.Effect<any, infer EL, any>;
+} ? EL : never;
+/** @internal The requirements of a handler config's {@link CommandHandlerOptions.loadState}. */
+type LoadStateContext<TConfig> = TConfig extends {
+    readonly loadState: (...args: any) => Effect.Effect<any, any, infer RL>;
+} ? RL : never;
 /**
  * The outcome of one `decide` call, handed to a function-form
  * {@link CommandOptionsBase.additionalItems}, to `eventMetadata`
@@ -1543,8 +1905,23 @@ export interface Decision<State, Event> {
  * directly (pure projection) or as an `Effect` (a projection that needs a read).
  * The effect's `E2` joins the handler's error channel and its `R2` the handler's
  * requirements.
+ *
+ * The ops are {@link AppendWriteOp}s: another stream's `appendOp` (#166) rides
+ * here too, so a handler on stream B can carry stream A's sealing append. Its
+ * `expectedVersion` must come from the **decision** — the version carried in
+ * the decided opening event (`decision.events[0].continuesFrom.version`, say),
+ * from A's state as `decide` read it — never from a separate read of A's head,
+ * which would seal over an append the opening event never carried.
+ *
+ * A `VersionConflict` naming A (not this handler's stream) is never taken
+ * for this stream's lagging snapshot, and is retried by the
+ * {@link CommandHandlerOptions.retry} schedule even under an If-Match. A
+ * `StreamSealed` naming A is terminal: another closer sealed it.
+ *
+ * Code that reads this type and forwards a static array to
+ * `Transaction.transactWrite` must annotate it `ReadonlyArray<TransactWriteOp>`.
  */
-export type AdditionalItemsInput<State, Event, E2 = never, R2 = never> = ReadonlyArray<TransactWriteOp> | ((decision: Decision<State, Event>) => ReadonlyArray<TransactWriteOp> | Effect.Effect<ReadonlyArray<TransactWriteOp>, E2, R2>);
+export type AdditionalItemsInput<State, Event, E2 = never, R2 = never> = ReadonlyArray<AppendWriteOp> | ((decision: Decision<State, Event>) => ReadonlyArray<AppendWriteOp> | Effect.Effect<ReadonlyArray<AppendWriteOp>, E2, R2>);
 /**
  * The form `eventMetadata` ({@link CommandMetadataOptions}) accepts: a
  * function of the {@link Decision} returning one metadata entry per event
@@ -1743,20 +2120,20 @@ export type IdempotentCommandOptions<TMetadata, State = unknown, Event = unknown
 type CommandOptionsArgs<TMetadata, TConfig extends CommandHandlerOptions | undefined, State, TEvent, E2, R2, E3, R3, E4, R4> = TConfig extends {
     readonly idempotency: object;
 } ? [options: IdempotentCommandOptions<TMetadata, State, TEvent, E2, R2, E3, R3, E4, R4>] : [options?: CommandOptions<TMetadata, State, TEvent, E2, R2, E3, R3, E4, R4> | undefined];
-type CommandHandlerErrors<E> = E | VersionConflict | DuplicateCommand | AdditionalItemConditionFailed | AppendTooLarge | DynamoClientError | ValidationError | TransactionCancelled | UniqueConstraintViolation | OptimisticLockError | ConcurrentModification;
+type CommandHandlerErrors<E> = E | VersionConflict | StreamSealed | DuplicateCommand | AdditionalItemConditionFailed | AppendTooLarge | DynamoClientError | ValidationError | TransactionCancelled | UniqueConstraintViolation | OptimisticLockError | ConcurrentModification;
 /**
  * A handler over an {@link EventStream}. Generic per call over the error (`E2`)
  * and requirements (`R2`) of a function-form `additionalItems` that returns an
  * `Effect`, those (`E3` / `R3`) of an `eventMetadata` that does, and those
  * (`E4` / `R4`) of an `eventTimestamps` that does; all are `never` otherwise.
  */
-type CommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = <E2 = never, R2 = never, E3 = never, R3 = never, E4 = never, R4 = never>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2, E3, R3, E4, R4>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2 | E3 | E4, DynamoClient | TableConfig | R2 | R3 | R4>;
+type CommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = <E2 = never, R2 = never, E3 = never, R3 = never, E4 = never, R4 = never>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2, E3, R3, E4, R4>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2 | E3 | E4 | LoadStateError<TConfig>, DynamoClient | TableConfig | R2 | R3 | R4 | LoadStateContext<TConfig>>;
 /**
  * A handler over a {@link BoundEventStream}: the stream's services are already
  * provided, so the `R2` / `R3` / `R4` of a function-form `additionalItems` /
  * `eventMetadata` / `eventTimestamps` are its only requirements.
  */
-type BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = <E2 = never, R2 = never, E3 = never, R3 = never, E4 = never, R4 = never>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2, E3, R3, E4, R4>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2 | E3 | E4, R2 | R3 | R4>;
+type BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TConfig extends CommandHandlerOptions | undefined = undefined> = <E2 = never, R2 = never, E3 = never, R3 = never, E4 = never, R4 = never>(streamId: StreamIdInput<TStreamIdFields>, command: Command, ...options: CommandOptionsArgs<TMetadata, TConfig, State, TEvent, E2, R2, E3, R3, E4, R4>) => Effect.Effect<CommandHandlerResult<State, TEvent>, CommandHandlerErrors<E> | E2 | E3 | E4 | LoadStateError<TConfig>, R2 | R3 | R4 | LoadStateContext<TConfig>>;
 /**
  * The handler the data-last {@link commandHandler} returns for stream `S`: a
  * {@link BoundCommandHandler} for a `BoundEventStream` (checked first — a bound
@@ -1863,13 +2240,13 @@ type CommandHandlerFor<S, State, Command, TEvent, E, TConfig extends CommandHand
  * `EventStreamTypeId` brand of the second argument.
  */
 export declare const commandHandler: {
-    <State, Command, TEvent, E, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, options?: TConfig): <S extends BoundEventStream<TEvent, any, any, State, any, any, any> | EventStream<TEvent, ReadonlyArray<string>, any, State, any, any, any>>(stream: S) => CommandHandlerFor<S, State, Command, TEvent, E, TConfig>;
+    <State, Command, TEvent, E, const TConfig extends CommandHandlerOptions<State> | undefined>(decider: Decider<State, Command, TEvent, E>, options?: TConfig): <S extends BoundEventStream<TEvent, any, any, State, any, any, any> | EventStream<TEvent, ReadonlyArray<string>, any, State, any, any, any>>(stream: S) => CommandHandlerFor<S, State, Command, TEvent, E, TConfig>;
     <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State, TIndexName extends string, TIndexProjections extends {
         readonly [K in TIndexName]: StreamIndexProjection;
-    }, TPartitionedIndexName extends string, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections, TPartitionedIndexName>, options?: TConfig): BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
+    }, TPartitionedIndexName extends string, const TConfig extends CommandHandlerOptions<State, StreamIdInput<TStreamIdFields>> | undefined>(decider: Decider<State, Command, TEvent, E>, stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections, TPartitionedIndexName>, options?: TConfig): BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
     <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata, TState extends State, TIndexName extends string, TIndexProjections extends {
         readonly [K in TIndexName]: StreamIndexProjection;
-    }, TPartitionedIndexName extends string, const TConfig extends CommandHandlerOptions | undefined = undefined>(decider: Decider<State, Command, TEvent, E>, stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections, TPartitionedIndexName>, options?: TConfig): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
+    }, TPartitionedIndexName extends string, const TConfig extends CommandHandlerOptions<State, StreamIdInput<TStreamIdFields>> | undefined>(decider: Decider<State, Command, TEvent, E>, stream: EventStream<TEvent, TStreamIdFields, TMetadata, TState, TIndexName, TIndexProjections, TPartitionedIndexName>, options?: TConfig): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata, TConfig>;
 };
 /**
  * Reconstruct state from events by folding through a decider's `evolve` function.