@photon-grove/evt 0.0.0 → 0.1.1

package/src/dynamodb/requests.ts

@@ -0,0 +1,256 @@
+// The `TransactWriteItems` actions of a commit and of a snapshot write, built from the storage
+// format alone (storage format, "Writes"). Every commit opens with the two control checks, the
+// feature marker's and the rebuild lock's, then writes the stream: its head update, its event
+// puts, and its snapshot put when it has one.
+
+import type {SerializedEvent, SerializedSnapshot} from '../event.js'
+import {int64Argument, safeIntegerArgument} from '../fields.js'
+import type {Commit} from '../repository.js'
+import type {TransactItem} from './client.js'
+import {type HeadAction, headUpdate} from './head.js'
+import {HEAD_SORT_KEY, type Item, SNAPSHOT_SORT_KEY, eventItem, snapshotItem} from './item.js'
+import {FEATURES_PK, REBUILD_LOCK_PK} from './marker.js'
+
+/** The marker check of a writer that validated the manifest at version `:v`. */
+export const MARKER_CHECK_CONDITION = 'attribute_not_exists(pk) OR version = :v'
+
+/** The rebuild-lock check: no lock row, so the rebuild generation is settled. */
+export const REBUILD_LOCK_CONDITION = 'attribute_not_exists(pk)'
+
+/** The condition of an event put: the sequence is new. */
+export const EVENT_PUT_CONDITION = 'attribute_not_exists(sk)'
+
+/** The condition of a commit's first snapshot of a stream. */
+export const FIRST_SNAPSHOT_CONDITION = 'attribute_not_exists(seq)'
+
+/** The condition of a commit's later snapshot: the stored one is the one before it. */
+export const NEXT_SNAPSHOT_CONDITION = 'seq = :seq'
+
+/** A snapshot write's head guard: the head covers the snapshot. */
+export const SNAPSHOT_GUARD_CONDITION = 'head >= :new'
+
+/** The guard of a snapshot of an empty stream (event sequence 0), which needs no head. */
+export const SNAPSHOT_GUARD_EMPTY_CONDITION = 'attribute_not_exists(head) OR head >= :new'
+
+/** The update expression of a retained stream's snapshot guard: it refreshes the head's `ttl`. */
+export const SNAPSHOT_GUARD_RETAINED_UPDATE = 'SET #ttl = :t'
+
+/** {@link SNAPSHOT_GUARD_CONDITION} with retention: the head's `ttl` is raised, never lowered. */
+export const SNAPSHOT_GUARD_RETAINED_CONDITION =
+  'head >= :new AND (attribute_not_exists(#ttl) OR #ttl <= :t)'
+
+/** A snapshot write's put: it never lowers the stored snapshot's event sequence. */
+export const SNAPSHOT_WRITE_CONDITION = 'attribute_not_exists(eventSeq) OR eventSeq <= :new'
+
+/** The key of a control row, or of a stream's snapshot. */
+export function controlKey(pk: string): Item {
+  return {pk: {S: pk}, sk: {N: SNAPSHOT_SORT_KEY.toString()}}
+}
+
+/** The key of a stream's head item. */
+export function headKey(entityId: string): Item {
+  return {pk: {S: entityId}, sk: {N: HEAD_SORT_KEY.toString()}}
+}
+
+/** The marker check of a writer that validated the manifest at `version`. */
+export function markerCheck(table: string, version: bigint): TransactItem {
+  return {
+    ConditionCheck: {
+      TableName: table,
+      Key: controlKey(FEATURES_PK),
+      ConditionExpression: MARKER_CHECK_CONDITION,
+      ExpressionAttributeValues: {':v': number(version)},
+    },
+  }
+}
+
+/** The rebuild-lock check every commit carries second. */
+export function rebuildLockCheck(table: string): TransactItem {
+  return {
+    ConditionCheck: {
+      TableName: table,
+      Key: controlKey(REBUILD_LOCK_PK),
+      ConditionExpression: REBUILD_LOCK_CONDITION,
+    },
+  }
+}
+
+/** The `ttl`s of a commit to a stream with retention, in Unix seconds. */
+export interface CommitTtl {
+  /** The commit's own `ttl`, which its event and snapshot items carry. */
+  items: number
+  /**
+   * The head item's: the commit's own `ttl` on a create, and on an append the larger of it and
+   * the largest `ttl` the writer loaded for the stream, because the head's is never lowered.
+   */
+  head: number
+}
+
+/** The `ttl` of a snapshot written outside a commit, to a stream with retention. */
+export interface SnapshotTtl {
+  /** The snapshot's `ttl`, in Unix seconds, stamped when it's written. */
+  ttl: number
+  /**
+   * Whether the head guard refreshes the head's `ttl` to at least the snapshot's. True unless the
+   * stored head's `ttl` is known to cover it already.
+   */
+  refresh: boolean
+}
+
+/**
+ * The actions of a commit with at least one event, in order, by a writer that validated the
+ * feature manifest at `markerVersion`. `ttl` is given only for a stream with retention. Exported
+ * for the compatibility fixtures: its signature changes when commits span streams.
+ */
+export function commitTransaction(
+  table: string,
+  commit: Commit,
+  markerVersion: bigint,
+  ttl?: CommitTtl,
+): TransactItem[] {
+  const first = commit.events[0]
+  const last = commit.events.at(-1)
+  if (first === undefined || last === undefined) {
+    throw new RangeError('a commit transaction needs at least one event')
+  }
+
+  const items = [markerCheck(table, markerVersion), rebuildLockCheck(table)]
+  const head = headUpdate(commit.entityId, first.sequence, last.sequence, ttl?.head)
+  items.push(headUpdateItem(table, head))
+  for (const event of commit.events) {
+    items.push(eventPut(table, event, ttl?.items))
+  }
+
+  const snapshot = commit.snapshot
+  if (snapshot) {
+    const stored: SerializedSnapshot = {
+      entityType: snapshot.entityType,
+      entityId: commit.entityId,
+      sequence: snapshot.sequence,
+      eventSequence: last.sequence,
+      payload: snapshot.payload,
+    }
+    items.push(commitSnapshotPut(table, stored, ttl?.items))
+  }
+
+  return items
+}
+
+/**
+ * The actions of a snapshot written outside a commit: the marker check, the head guard, and the
+ * put, which never lowers the stored snapshot. It carries no rebuild-lock check. `ttl` is given
+ * only for a stream with retention. Exported for the compatibility fixtures.
+ */
+export function snapshotTransaction(
+  table: string,
+  snapshot: SerializedSnapshot,
+  markerVersion: bigint,
+  ttl?: SnapshotTtl,
+): TransactItem[] {
+  const eventSequence = int64Argument(snapshot.eventSequence, 'snapshot.eventSequence')
+
+  return [
+    markerCheck(table, markerVersion),
+    snapshotGuard(table, snapshot.entityId, eventSequence, ttl),
+    {
+      Put: {
+        TableName: table,
+        Item: snapshotItem(snapshot, ttl?.ttl),
+        ConditionExpression: SNAPSHOT_WRITE_CONDITION,
+        ExpressionAttributeValues: {':new': number(eventSequence)},
+      },
+    },
+  ]
+}
+
+// The head item's action in a snapshot write: a check that the head covers the snapshot, or, for a
+// stream with retention, an update that also keeps the head's `ttl` at least the snapshot's. A
+// snapshot of an empty stream may have no head item, so it's always a check: an update would
+// create a head item without a head.
+function snapshotGuard(
+  table: string,
+  entityId: string,
+  eventSequence: bigint,
+  ttl: SnapshotTtl | undefined,
+): TransactItem {
+  const values: Record<string, {N: string}> = {':new': number(eventSequence)}
+  if (eventSequence === 0n || ttl === undefined || !ttl.refresh) {
+    return {
+      ConditionCheck: {
+        TableName: table,
+        Key: headKey(entityId),
+        ConditionExpression:
+          eventSequence === 0n ? SNAPSHOT_GUARD_EMPTY_CONDITION : SNAPSHOT_GUARD_CONDITION,
+        ExpressionAttributeValues: values,
+      },
+    }
+  }
+
+  values[':t'] = number(BigInt(safeIntegerArgument(ttl.ttl, 'ttl')))
+
+  return {
+    Update: {
+      TableName: table,
+      Key: headKey(entityId),
+      UpdateExpression: SNAPSHOT_GUARD_RETAINED_UPDATE,
+      ConditionExpression: SNAPSHOT_GUARD_RETAINED_CONDITION,
+      ExpressionAttributeNames: {'#ttl': 'ttl'},
+      ExpressionAttributeValues: values,
+    },
+  }
+}
+
+function headUpdateItem(table: string, action: HeadAction): TransactItem {
+  const update: NonNullable<TransactItem['Update']> = {
+    TableName: table,
+    Key: headKey(action.entityId),
+    UpdateExpression: action.updateExpression ?? '',
+    ConditionExpression: action.conditionExpression,
+    ExpressionAttributeValues: Object.fromEntries(
+      action.values.map(([placeholder, value]) => [placeholder, number(value)]),
+    ),
+  }
+  if (action.names.length > 0) {
+    update.ExpressionAttributeNames = Object.fromEntries(action.names)
+  }
+
+  return {Update: update}
+}
+
+function eventPut(table: string, event: SerializedEvent, ttl: number | undefined): TransactItem {
+  return {
+    Put: {TableName: table, Item: eventItem(event, ttl), ConditionExpression: EVENT_PUT_CONDITION},
+  }
+}
+
+// A commit's snapshot follows the stored one: sequence 1 needs none, and a later one needs the
+// one before it.
+function commitSnapshotPut(
+  table: string,
+  snapshot: SerializedSnapshot,
+  ttl: number | undefined,
+): TransactItem {
+  const sequence = int64Argument(snapshot.sequence, 'snapshot.sequence')
+  if (sequence <= 1n) {
+    return {
+      Put: {
+        TableName: table,
+        Item: snapshotItem(snapshot, ttl),
+        ConditionExpression: FIRST_SNAPSHOT_CONDITION,
+      },
+    }
+  }
+
+  return {
+    Put: {
+      TableName: table,
+      Item: snapshotItem(snapshot, ttl),
+      ConditionExpression: NEXT_SNAPSHOT_CONDITION,
+      ExpressionAttributeValues: {':seq': number(sequence - 1n)},
+    },
+  }
+}
+
+function number(value: bigint): {N: string} {
+  return {N: value.toString()}
+}

package/src/envelope.ts

@@ -0,0 +1,67 @@
+// The stream envelope: the EventBridge-style message around each committed event, which consumers
+// in every language unwrap. Go decodes it with projectors.StreamRecordFromEnvelope.
+
+import {type SerializedEvent, eventFromJson, encodeEvent} from './event.js'
+import {DOCUMENT, invalid, objectOrNull} from './fields.js'
+import {RawJson, parseJson, stringifyJson} from './json.js'
+
+// Go's zero time.Time, which the publisher left in the time field.
+const ZERO_TIME = '0001-01-01T00:00:00Z'
+
+/** Encodes the envelope for an event, byte for byte as the Go publisher wrote it. */
+export function encodeEnvelope(event: SerializedEvent, source: string): string {
+  return stringifyJson({
+    version: '',
+    id: event.id,
+    'detail-type': event.type,
+    source,
+    account: '',
+    time: ZERO_TIME,
+    region: '',
+    resources: null,
+    detail: new RawJson(encodeEvent(event)),
+  })
+}
+
+/**
+ * Decodes the event from an envelope body: an SNS message, or an SQS body delivered raw. An event
+ * with no entity ID or event ID is refused.
+ */
+export function decodeEnvelope(body: string): SerializedEvent {
+  const envelope = objectOrNull(parseJson(body, DOCUMENT), 'envelope') ?? new Map()
+  const event = eventFromJson(objectOrNull(envelope.get('detail'), 'envelope.detail'))
+  if (event.entityId === '') {
+    throw invalid('event envelope has no entity id')
+  }
+  if (event.id === '') {
+    throw invalid('event envelope has no event id')
+  }
+
+  return event
+}
+
+/**
+ * The message attributes the publisher set, all strings: `entityType` and `eventType`, then
+ * `commandId` and `traceparent` when they aren't empty, and `correlationId`, the command ID or
+ * else the traceparent.
+ */
+export function messageAttributes(event: SerializedEvent): Record<string, string> {
+  const attributes: Record<string, string> = {
+    entityType: event.entityType,
+    eventType: event.type,
+  }
+
+  const commandId = event.metadata.commandId
+  if (commandId !== null && commandId !== '') {
+    attributes['commandId'] = commandId
+    attributes['correlationId'] = commandId
+  }
+
+  const traceparent = event.metadata.trace?.get('traceparent')
+  if (traceparent !== undefined && traceparent !== '') {
+    attributes['traceparent'] = traceparent
+    attributes['correlationId'] ??= traceparent
+  }
+
+  return attributes
+}

package/src/errors.ts

@@ -0,0 +1,365 @@
+// Every failure evt throws is an EvtError with a code, as the Rust crate returns its Error enum.
+// Domain outcomes (a rejected command, a duplicate) are values, never errors. A failure with
+// details has its own subclass, so `instanceof` narrows to its fields.
+
+/**
+ * What went wrong:
+ *
+ * - `invalidJson`: text that isn't JSON.
+ * - `invalidRecord`: a stored record (an event, a snapshot, an item) with the wrong shape.
+ * - `invalidArgument`: a value evt can't write, such as a float that isn't finite or an object
+ *   whose key order the engine has already changed, or a read with a bad argument, such as
+ *   `latest(0)`.
+ * - `invalidCommit`: a commit built wrong, such as one with another entity's event. Nothing was
+ *   written.
+ * - `conflict`: optimistic concurrency failed. Another writer committed since the stream was
+ *   read. Reload and run the command again.
+ * - `sequenceGap`: a commit or a load skips a sequence. A conflict.
+ * - `streamHeadDrift`: a stream's head disagrees with its events or snapshot. Never retried.
+ * - `commitTooLarge`: the commit is over the transaction budget. Nothing was written.
+ * - `compactionUncovered`: no snapshot covers the events compaction was asked to delete.
+ * - `reservedEntityId`: a write to an entity ID in a namespace only the engine writes.
+ * - `unsupportedFeature`: the store declares a feature this package doesn't model. Nothing was
+ *   written.
+ * - `streamHeadsNotMigrated`: the store holds data but doesn't declare stream-heads. Nothing was
+ *   written.
+ * - `storeNotInitialized`: the store doesn't declare stream-heads, and the writer doesn't
+ *   initialize a store itself. Nothing was written.
+ * - `featureManifestChanged`: another writer changed the store's feature manifest since this one
+ *   validated it. Retryable: the writer validates it again.
+ * - `transient`: the backend throttled the write. Retryable. Nothing was written.
+ * - `rebuildInProgress`: a projection rebuild holds the store, so commits wait. Retryable.
+ * - `historyDependentProjection`: compaction was refused for a history-dependent entity type.
+ * - `replay`: a stored event failed to upcast or decode while an aggregate loaded.
+ * - `snapshot`: a stored snapshot failed to decode while an aggregate loaded.
+ */
+export type EvtErrorCode =
+  | 'invalidJson'
+  | 'invalidRecord'
+  | 'invalidArgument'
+  | 'invalidCommit'
+  | 'conflict'
+  | 'sequenceGap'
+  | 'streamHeadDrift'
+  | 'commitTooLarge'
+  | 'compactionUncovered'
+  | 'reservedEntityId'
+  | 'unsupportedFeature'
+  | 'streamHeadsNotMigrated'
+  | 'storeNotInitialized'
+  | 'featureManifestChanged'
+  | 'transient'
+  | 'rebuildInProgress'
+  | 'historyDependentProjection'
+  | 'replay'
+  | 'snapshot'
+
+export class EvtError extends Error {
+  override readonly name: string = 'EvtError'
+  readonly code: EvtErrorCode
+
+  constructor(code: EvtErrorCode, message: string, options?: {cause?: unknown}) {
+    super(message, options)
+    this.code = code
+  }
+}
+
+/** Optimistic concurrency failed on a written stream: its sequence or snapshot moved. */
+export class ConflictError extends EvtError {
+  override readonly name = 'ConflictError'
+  override readonly code = 'conflict'
+  readonly entityId: string
+
+  constructor(entityId: string, detail: string) {
+    super('conflict', `conflict on entity ${entityId}: ${detail}`)
+    this.entityId = entityId
+  }
+}
+
+/** A commit's first event skips past the stream's head, or a load found a hole. A conflict. */
+export class SequenceGapError extends EvtError {
+  override readonly name = 'SequenceGapError'
+  override readonly code = 'sequenceGap'
+  readonly entityId: string
+  /** The last sequence before the gap. */
+  readonly after: bigint
+  /** The sequence found next, which isn't `after + 1`. */
+  readonly found: bigint
+
+  constructor(entityId: string, after: bigint, found: bigint) {
+    super(
+      'sequenceGap',
+      `conflict on entity ${entityId}: the stream skips from sequence ${after} to ${found}: it ` +
+        'was compacted during the load, or events expired',
+    )
+    this.entityId = entityId
+    this.after = after
+    this.found = found
+  }
+}
+
+/**
+ * A stream's head disagrees with its events or snapshot (ADR 0007): a writer appended without
+ * raising the head, events were deleted, a snapshot is ahead of the head, or a stream has data and
+ * no head. It isn't retryable: running the command again fails the same way. Repair is offline.
+ */
+export class StreamHeadDriftError extends EvtError {
+  override readonly name = 'StreamHeadDriftError'
+  override readonly code = 'streamHeadDrift'
+  readonly entityId: string
+  /** The stored head, or null when the stream has no head. */
+  readonly stored: bigint | null
+  /** The head its events and snapshot imply: the higher of the two. */
+  readonly derived: bigint
+
+  constructor(entityId: string, stored: bigint | null, derived: bigint) {
+    super(
+      'streamHeadDrift',
+      `stream head drift on entity ${entityId}: stored head ${stored ?? 'absent'}, ` +
+        `derived head ${derived}`,
+    )
+    this.entityId = entityId
+    this.stored = stored
+    this.derived = derived
+  }
+}
+
+/** The commit is over the transaction budget: too many actions, bytes, or bytes in one item. */
+export class CommitTooLargeError extends EvtError {
+  override readonly name = 'CommitTooLargeError'
+  override readonly code = 'commitTooLarge'
+  readonly actions: number
+  readonly bytes: number
+  readonly largestItem: number
+
+  constructor(actions: number, bytes: number, largestItem: number) {
+    super(
+      'commitTooLarge',
+      `commit exceeds transaction budget: ${actions} actions, ${bytes} bytes, ` +
+        `largest item ${largestItem}`,
+    )
+    this.actions = actions
+    this.bytes = bytes
+    this.largestItem = largestItem
+  }
+}
+
+/** Compaction was refused because no snapshot covers the events it would delete. */
+export class CompactionUncoveredError extends EvtError {
+  override readonly name = 'CompactionUncoveredError'
+  override readonly code = 'compactionUncovered'
+  readonly entityId: string
+  readonly through: bigint
+  /** The event sequence the stored snapshot covers, or null with no snapshot. */
+  readonly covered: bigint | null
+
+  constructor(entityId: string, through: bigint, covered: bigint | null) {
+    super(
+      'compactionUncovered',
+      'compaction refused: no durable snapshot covers the requested range ' +
+        `(entity ${entityId}, through ${through}, snapshot covers ${covered ?? 'nothing'})`,
+    )
+    this.entityId = entityId
+    this.through = through
+    this.covered = covered
+  }
+}
+
+/** A write to an entity ID in a reserved namespace (`SYSTEM#`, `command-outcome#`). */
+export class ReservedEntityIdError extends EvtError {
+  override readonly name = 'ReservedEntityIdError'
+  override readonly code = 'reservedEntityId'
+  readonly entityId: string
+
+  constructor(entityId: string) {
+    super(
+      'reservedEntityId',
+      `entity ID ${entityId} is in a reserved namespace (SYSTEM#, command-outcome#)`,
+    )
+    this.entityId = entityId
+  }
+}
+
+/** A feature and one of its stored-format versions. */
+export interface FeaturePair {
+  readonly name: string
+  readonly version: number
+}
+
+/**
+ * The store's feature manifest declares pairs this package doesn't model, so it refuses to write:
+ * a commit, a snapshot write, compaction or initialization. Nothing was written.
+ */
+export class UnsupportedFeatureError extends EvtError {
+  override readonly name = 'UnsupportedFeatureError'
+  override readonly code = 'unsupportedFeature'
+  /** Every unsupported pair, sorted by name. */
+  readonly unsupported: readonly FeaturePair[]
+
+  constructor(unsupported: readonly FeaturePair[]) {
+    const pairs = unsupported.map((pair) => `${pair.name}@${pair.version}`).join(', ')
+    super('unsupportedFeature', `store declares unsupported features (${pairs}); refusing to write`)
+    this.unsupported = unsupported
+  }
+}
+
+/**
+ * The store holds data but its feature manifest doesn't declare stream-heads: its streams may have
+ * no head items, so a head-aware write could fail every stream. Migrate the store with every older
+ * writer stopped. Nothing was written.
+ */
+export class StreamHeadsNotMigratedError extends EvtError {
+  override readonly name = 'StreamHeadsNotMigratedError'
+  override readonly code = 'streamHeadsNotMigrated'
+
+  constructor() {
+    super(
+      'streamHeadsNotMigrated',
+      'store does not declare the stream-heads feature and holds data without per-stream head ' +
+        'items; migrate it before writing',
+    )
+  }
+}
+
+/**
+ * The store's feature manifest doesn't declare stream-heads, and this writer doesn't initialize a
+ * store itself (the DynamoDB default), so it refuses rather than scan the table to learn whether
+ * it's fresh. Initialize a fresh store once, at deploy time, or migrate one written before stream
+ * heads. Nothing was written.
+ */
+export class StoreNotInitializedError extends EvtError {
+  override readonly name = 'StoreNotInitializedError'
+  override readonly code = 'storeNotInitialized'
+
+  constructor() {
+    super(
+      'storeNotInitialized',
+      'store is not initialized: the feature manifest does not declare stream-heads; initialize ' +
+        'a fresh store, or migrate one written before stream heads, before writing',
+    )
+  }
+}
+
+/**
+ * Another writer changed the store's feature manifest after this one validated it, so the commit's
+ * marker check failed. The writer has validated the new manifest, which it supports. Retryable.
+ * Nothing was written.
+ */
+export class FeatureManifestChangedError extends EvtError {
+  override readonly name = 'FeatureManifestChangedError'
+  override readonly code = 'featureManifestChanged'
+
+  constructor(options?: {cause?: unknown}) {
+    super('featureManifestChanged', 'feature manifest changed under this writer', options)
+  }
+}
+
+/**
+ * The backend refused the write for now, such as a DynamoDB transaction cancelled for throttling.
+ * Retryable, after a backoff. Nothing was written. The backend's error is its cause.
+ */
+export class TransientError extends EvtError {
+  override readonly name = 'TransientError'
+  override readonly code = 'transient'
+
+  constructor(detail: string, options?: {cause?: unknown}) {
+    super('transient', `transient failure: ${detail}`, options)
+  }
+}
+
+/**
+ * A projection rebuild holds the store, or one was force-released and no rebuild has finished
+ * since, so every commit is refused. Retryable: the command can run again once the rebuild ends.
+ */
+export class RebuildInProgressError extends EvtError {
+  override readonly name = 'RebuildInProgressError'
+  override readonly code = 'rebuildInProgress'
+
+  constructor() {
+    super('rebuildInProgress', 'a projection rebuild is in progress')
+  }
+}
+
+/**
+ * Compaction was refused because the store declares the entity's type history-dependent: its
+ * projectors' rebuild replays the events compaction would delete. Nothing was deleted.
+ */
+export class HistoryDependentProjectionError extends EvtError {
+  override readonly name = 'HistoryDependentProjectionError'
+  override readonly code = 'historyDependentProjection'
+  readonly entityType: string
+  readonly entityId: string
+
+  constructor(entityType: string, entityId: string) {
+    super(
+      'historyDependentProjection',
+      `entity type ${entityType} is declared history-dependent; compaction would delete the ` +
+        `commits its rebuild replays (entity ${entityId})`,
+    )
+    this.entityType = entityType
+    this.entityId = entityId
+  }
+}
+
+/** A load failed closed on a stored event: an upcaster threw, or the payload didn't decode. */
+export class ReplayError extends EvtError {
+  override readonly name = 'ReplayError'
+  override readonly code = 'replay'
+  readonly eventType: string
+  /** The stored version, or the version an earlier upcaster produced. */
+  readonly version: number
+  readonly phase: 'upcast' | 'decode'
+
+  constructor(
+    eventType: string,
+    version: number,
+    phase: 'upcast' | 'decode',
+    detail: string,
+    cause?: unknown,
+  ) {
+    const doing = phase === 'upcast' ? 'upcasting' : 'decoding'
+    super('replay', `replay failed while ${doing} ${eventType} v${version}: ${detail}`, {cause})
+    this.eventType = eventType
+    this.version = version
+    this.phase = phase
+  }
+}
+
+/** A load found a stored snapshot whose payload the aggregate's state codec doesn't decode. */
+export class SnapshotError extends EvtError {
+  override readonly name = 'SnapshotError'
+  override readonly code = 'snapshot'
+  readonly entityId: string
+
+  constructor(entityId: string, cause: unknown) {
+    super('snapshot', `decoding snapshot for entity ${entityId}: ${messageOf(cause)}`, {cause})
+    this.entityId = entityId
+  }
+}
+
+/** Whether an error is an optimistic-concurrency conflict: a `conflict` or a `sequenceGap`. */
+export function isConflict(error: unknown): boolean {
+  return error instanceof EvtError && (error.code === 'conflict' || error.code === 'sequenceGap')
+}
+
+/**
+ * Whether reloading and running the command again may succeed: after a conflict, while a rebuild
+ * holds the store, after the feature manifest changed under the writer, or after throttling.
+ */
+export function isRetryable(error: unknown): boolean {
+  if (isConflict(error)) {
+    return true
+  }
+
+  return (
+    error instanceof EvtError &&
+    (error.code === 'rebuildInProgress' ||
+      error.code === 'featureManifestChanged' ||
+      error.code === 'transient')
+  )
+}
+
+/** An error's message, or the value itself as text. */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}