@photon-grove/evt 0.0.0-stage → 0.1.0

package/src/memory/repository.ts

@@ -0,0 +1,313 @@
+// The in-memory repository. It enforces the storage contract the way the live backends do: a head
+// per stream that every commit raises, optimistic concurrency against it, and the same failure
+// classification and transaction budget. It's for tests and local development.
+
+import {
+  ConflictError,
+  CompactionUncoveredError,
+  EvtError,
+  SequenceGapError,
+  StreamHeadDriftError,
+} from '../errors.js'
+import type {SerializedEvent, SerializedSnapshot} from '../event.js'
+import {int64Argument} from '../fields.js'
+import type {Metadata} from '../metadata.js'
+import {
+  type CallOptions,
+  type Commit,
+  type Repository,
+  checkBudget,
+  checkNotReserved,
+  commitSizes,
+  validateCommit,
+} from '../repository.js'
+
+interface Stream {
+  /** The stream's events by sequence. Compaction deletes from it. */
+  events: Map<bigint, SerializedEvent>
+  snapshot: SerializedSnapshot | null
+  /** The highest event sequence ever committed to the stream, 0 while it has none. */
+  head: bigint
+}
+
+// Reads a repository's streams, for headFixtures. The class's static block sets it.
+let streamsOf: (repo: MemRepository) => Map<string, Stream>
+
+/**
+ * An in-memory {@link Repository}. Every call copies what it stores and what it returns, so a
+ * caller that changes an event after committing it, or one it read, changes nothing stored.
+ *
+ * Each call runs to completion before another starts, so concurrent commits to one stream behave
+ * like racing writers on a live backend: one wins and the rest fail with a conflict.
+ */
+export class MemRepository implements Repository {
+  readonly #streams = new Map<string, Stream>()
+
+  async commit(commit: Commit, options?: CallOptions): Promise<void> {
+    options?.signal?.throwIfAborted()
+    validateCommit(commit)
+    checkNotReserved(commit.entityId)
+    if (commit.events.length === 0) {
+      return
+    }
+
+    // Every backend budgets a commit the same way, so an oversized one fails before any write.
+    checkBudget(commitSizes(commit, () => undefined))
+
+    const held = this.#streams.get(commit.entityId) ?? emptyStream()
+    checkWrite(commit, held)
+
+    // Copy everything before the first write, so a copy that throws leaves the stream as it was.
+    const events = commit.events.map(cloneEvent)
+    const last = events.at(-1)!.sequence
+    const snapshot = commit.snapshot && {
+      entityType: commit.snapshot.entityType,
+      entityId: commit.entityId,
+      sequence: commit.snapshot.sequence,
+      eventSequence: last,
+      payload: copy(commit.snapshot.payload),
+    }
+
+    for (const event of events) {
+      held.events.set(event.sequence, event)
+    }
+    held.head = held.head > last ? held.head : last
+    if (snapshot) {
+      held.snapshot = snapshot
+    }
+
+    this.#streams.set(commit.entityId, held)
+  }
+
+  async events(entityId: string, options?: CallOptions): Promise<SerializedEvent[]> {
+    return this.eventsAfter(entityId, 0n, options)
+  }
+
+  async eventsAfter(
+    entityId: string,
+    after: bigint,
+    options?: CallOptions,
+  ): Promise<SerializedEvent[]> {
+    options?.signal?.throwIfAborted()
+    int64Argument(after, 'after')
+
+    return this.#sorted(entityId)
+      .filter((event) => event.sequence > after)
+      .map(cloneEvent)
+  }
+
+  async latest(entityId: string, n: number, options?: CallOptions): Promise<SerializedEvent[]> {
+    options?.signal?.throwIfAborted()
+    if (!Number.isSafeInteger(n) || n < 1) {
+      throw new EvtError(
+        'invalidArgument',
+        `latest(n) requires a whole number of at least one event: got n = ${n}`,
+      )
+    }
+
+    return this.#sorted(entityId, true).slice(0, n).map(cloneEvent)
+  }
+
+  async snapshot(entityId: string, options?: CallOptions): Promise<SerializedSnapshot | null> {
+    options?.signal?.throwIfAborted()
+    const snapshot = this.#streams.get(entityId)?.snapshot
+
+    return snapshot ? cloneSnapshot(snapshot) : null
+  }
+
+  async putSnapshot(snapshot: SerializedSnapshot, options?: CallOptions): Promise<boolean> {
+    options?.signal?.throwIfAborted()
+    checkNotReserved(snapshot.entityId)
+    int64Argument(snapshot.sequence, 'snapshot.sequence')
+    int64Argument(snapshot.eventSequence, 'snapshot.eventSequence')
+
+    // The stream's head must cover the snapshot. One of an empty stream (event sequence 0) may
+    // have no head at all.
+    const held = this.#streams.get(snapshot.entityId)
+    const head = held?.head ?? 0n
+    if (snapshot.eventSequence > 0n && head < snapshot.eventSequence) {
+      const derived = held ? derivedHead(held) : 0n
+      throw drift(
+        snapshot.entityId,
+        head,
+        derived > snapshot.eventSequence ? derived : snapshot.eventSequence,
+      )
+    }
+
+    const stored = held?.snapshot
+    if (stored && stored.eventSequence > snapshot.eventSequence) {
+      return false
+    }
+
+    const stream = held ?? emptyStream()
+    stream.snapshot = cloneSnapshot(snapshot)
+    this.#streams.set(snapshot.entityId, stream)
+
+    return true
+  }
+
+  async compactBelow(entityId: string, through: bigint, options?: CallOptions): Promise<number> {
+    options?.signal?.throwIfAborted()
+    checkNotReserved(entityId)
+    if (int64Argument(through, 'through') < 1n) {
+      return 0
+    }
+
+    const stream = this.#streams.get(entityId)
+    const covered = stream?.snapshot?.eventSequence ?? null
+    if (stream === undefined || covered === null || covered < through) {
+      throw new CompactionUncoveredError(entityId, through, covered)
+    }
+
+    let deleted = 0
+    for (const sequence of stream.events.keys()) {
+      if (sequence <= through) {
+        stream.events.delete(sequence)
+        deleted++
+      }
+    }
+
+    return deleted
+  }
+
+  static {
+    streamsOf = (repo) => repo.#streams
+  }
+
+  // The stream's events by sequence, ascending or descending. Sequences are unique.
+  #sorted(entityId: string, descending = false): SerializedEvent[] {
+    const events = Array.from(this.#streams.get(entityId)?.events.values() ?? [])
+    const order = descending ? -1 : 1
+    events.sort((a, b) => (a.sequence < b.sequence ? -order : order))
+
+    return events
+  }
+}
+
+// Refuses a commit the stored stream doesn't accept, as the live backends' conditions do. The
+// head update needs no head for a create and the head to be the sequence before the first event
+// for an append. Then no event may exist already, and a snapshot must follow the stored one.
+function checkWrite(commit: Commit, held: Stream): void {
+  const first = commit.events[0]!.sequence
+  const headPasses = first <= 1n ? held.head === 0n : held.head === first - 1n
+  if (!headPasses) {
+    throw probe(commit.entityId, held, first)
+  }
+
+  // The head update passed and an event put would fail: an event sits above the head.
+  if (commit.events.some((event) => held.events.has(event.sequence))) {
+    throw drift(commit.entityId, held.head, derivedHead(held))
+  }
+
+  const snapshot = commit.snapshot
+  const stored = held.snapshot?.sequence ?? 0n
+  if (snapshot && snapshot.sequence !== stored + 1n) {
+    throw new ConflictError(
+      commit.entityId,
+      `snapshot sequence moved: stored ${stored}, commit writes ${snapshot.sequence}`,
+    )
+  }
+}
+
+// Classifies a failed head update the way the live backends' failure-path probe does: a stored
+// head that disagrees with the head derived from the log is drift. Memory has no concurrent
+// writes, so a second derivation would find the same head. A healthy stream fails with a gap when
+// the commit skips past its head, and with a conflict otherwise.
+function probe(entityId: string, held: Stream, first: bigint): EvtError {
+  const derived = derivedHead(held)
+  if (held.head !== derived) {
+    return drift(entityId, held.head, derived)
+  }
+  if (held.head < first - 1n) {
+    return new SequenceGapError(entityId, held.head, first)
+  }
+
+  return new ConflictError(
+    entityId,
+    'conditional check failed: the sequence or snapshot changed since it was read',
+  )
+}
+
+// The head a stream's log implies: the higher of its last event and its snapshot's event sequence.
+function derivedHead(stream: Stream): bigint {
+  let head = stream.snapshot?.eventSequence ?? 0n
+  for (const sequence of stream.events.keys()) {
+    if (sequence > head) {
+      head = sequence
+    }
+  }
+
+  return head
+}
+
+// A stored head of 0 is an absent head.
+function drift(entityId: string, stored: bigint, derived: bigint): StreamHeadDriftError {
+  return new StreamHeadDriftError(entityId, stored > 0n ? stored : null, derived)
+}
+
+/** What a conformance suite needs to make a stream drift, which no repository call can do. */
+export interface HeadFixtures {
+  /** Appends an event without raising its stream's head, as a pre-heads writer would. */
+  appendBypassingHead(event: SerializedEvent): void
+  /** Deletes a stream's head, leaving its events and snapshot. */
+  deleteHead(entityId: string): void
+  /** A stream's stored head, or null when it has none. */
+  storedHead(entityId: string): bigint | null
+}
+
+/**
+ * Hooks that corrupt a repository's heads, for conformance suites only: a stream they touch
+ * drifts, and every later write to it fails.
+ */
+export function headFixtures(repo: MemRepository): HeadFixtures {
+  const streams = streamsOf(repo)
+
+  return {
+    appendBypassingHead(event) {
+      const stream = streams.get(event.entityId) ?? emptyStream()
+      stream.events.set(event.sequence, cloneEvent(event))
+      streams.set(event.entityId, stream)
+    },
+    deleteHead(entityId) {
+      const stream = streams.get(entityId)
+      if (stream) {
+        stream.head = 0n
+      }
+    },
+    storedHead(entityId) {
+      const head = streams.get(entityId)?.head ?? 0n
+
+      return head > 0n ? head : null
+    },
+  }
+}
+
+function emptyStream(): Stream {
+  return {events: new Map(), snapshot: null, head: 0n}
+}
+
+function cloneEvent(event: SerializedEvent): SerializedEvent {
+  return {
+    ...event,
+    payload: event.payload && copy(event.payload),
+    metadata: cloneMetadata(event.metadata),
+  }
+}
+
+function cloneMetadata(metadata: Metadata): Metadata {
+  return {
+    ...metadata,
+    trace: metadata.trace && new Map(metadata.trace),
+    origin: metadata.origin && {...metadata.origin},
+    extensions: new Map(metadata.extensions),
+  }
+}
+
+function cloneSnapshot(snapshot: SerializedSnapshot): SerializedSnapshot {
+  return {...snapshot, payload: snapshot.payload && copy(snapshot.payload)}
+}
+
+// A copy of the bytes. Not slice(): a Node Buffer's slice is a view of the same memory.
+function copy(bytes: Uint8Array): Uint8Array {
+  return new Uint8Array(bytes)
+}

package/src/metadata.ts

@@ -0,0 +1,120 @@
+// Event metadata: the envelope fields stored with every event, mirroring Go's evt.Metadata.
+
+import {DOCUMENT, nullableString, objectOrNull, stringField, stringMap} from './fields.js'
+import {type JsonValue, parseJson, stringifyJson} from './json.js'
+
+/** The system and entry point that initiated a command. */
+export interface Origin {
+  source: string
+  endpoint: string
+}
+
+/**
+ * Metadata stored with each event. Every key is always written, in this order, with absent values
+ * as `null` (or `""` for `region`, `timestamp` and `commitId`, and `{}` for `extensions`).
+ */
+export interface Metadata {
+  /** The command that produced the event. Used to reject duplicate commands. */
+  commandId: string | null
+  /** The W3C trace-context carrier. Its keys are written sorted. */
+  trace: Map<string, string> | null
+  origin: Origin | null
+  /** An optional caller address. Decoding keeps a stored `""`. */
+  address: string | null
+  /** The region the command ran in. */
+  region: string
+  /** RFC 3339 UTC with second precision, such as `2026-01-02T03:04:05Z`. */
+  timestamp: string
+  /** Who issued the command. */
+  principalId: string | null
+  /**
+   * The command that caused this one. The encoder writes the `commandId` when it is null, and
+   * decoding leaves a missing value null.
+   */
+  causationId: string | null
+  /** String-keyed application metadata. Its keys are written sorted. */
+  extensions: Map<string, string>
+  /** The commit that wrote the event, set by the engine. */
+  commitId: string
+}
+
+/** Metadata with every field at its zero value: what `{}` or `null` decodes to. */
+export function emptyMetadata(): Metadata {
+  return {
+    commandId: null,
+    trace: null,
+    origin: null,
+    address: null,
+    region: '',
+    timestamp: '',
+    principalId: null,
+    causationId: null,
+    extensions: new Map(),
+    commitId: '',
+  }
+}
+
+/** The causation ID the encoder writes: the one set, otherwise the command ID. */
+export function effectiveCausationId(metadata: Metadata): string | null {
+  return metadata.causationId ?? metadata.commandId
+}
+
+/** Encodes metadata as Go's canonical JSON. */
+export function encodeMetadata(metadata: Metadata): string {
+  return stringifyJson(metadataJson(metadata))
+}
+
+/** Decodes metadata JSON leniently, as Go does. */
+export function decodeMetadata(json: string): Metadata {
+  return metadataFromJson(parseJson(json, DOCUMENT))
+}
+
+/** The metadata's JSON shape, for documents that embed it. */
+export function metadataJson(metadata: Metadata): object {
+  return {
+    commandId: metadata.commandId,
+    trace: metadata.trace,
+    origin: metadata.origin && {source: metadata.origin.source, endpoint: metadata.origin.endpoint},
+    address: metadata.address,
+    region: metadata.region,
+    timestamp: metadata.timestamp,
+    principalId: metadata.principalId,
+    causationId: effectiveCausationId(metadata),
+    extensions: metadata.extensions,
+    commitId: metadata.commitId,
+  }
+}
+
+/** Decodes metadata from a parsed value. Null is the zero value. */
+export function metadataFromJson(value: JsonValue | undefined): Metadata {
+  const object = objectOrNull(value, 'metadata')
+  const metadata = emptyMetadata()
+  if (object === null) {
+    return metadata
+  }
+
+  metadata.commandId = nullableString(object, 'commandId', 'metadata')
+  metadata.trace = stringMap(object.get('trace'), 'metadata.trace')
+  metadata.origin = origin(object.get('origin'))
+  metadata.address = nullableString(object, 'address', 'metadata')
+  metadata.region = stringField(object, 'region', 'metadata')
+  metadata.timestamp = stringField(object, 'timestamp', 'metadata')
+  metadata.principalId = nullableString(object, 'principalId', 'metadata')
+  metadata.causationId = nullableString(object, 'causationId', 'metadata')
+  metadata.extensions = stringMap(object.get('extensions'), 'metadata.extensions') ?? new Map()
+  metadata.commitId = stringField(object, 'commitId', 'metadata')
+
+  return metadata
+}
+
+function origin(value: JsonValue | undefined): Origin | null {
+  const object = objectOrNull(value, 'metadata.origin')
+  if (object === null) {
+    return null
+  }
+
+  return {
+    source: stringField(object, 'source', 'metadata.origin'),
+    endpoint: stringField(object, 'endpoint', 'metadata.origin'),
+  }
+}

package/src/repository.ts

@@ -0,0 +1,247 @@
+// The storage contract every backend implements, and the commit rules every backend applies the
+// same way: validation, the reserved namespaces, and the transaction budget.
+
+import {headActionSize, headUpdate} from './dynamodb/head.js'
+import {eventItem, itemSize, snapshotItem} from './dynamodb/item.js'
+import {CommitTooLargeError, EvtError, ReservedEntityIdError} from './errors.js'
+import {type SerializedEvent, type SerializedSnapshot, eventId} from './event.js'
+import {MAX_COMMIT_ITEM_BYTES} from './snapshots.js'
+
+/** A snapshot to write with a commit. Its event sequence is the commit's last event. */
+export interface NewSnapshot {
+  entityType: string
+  /** The stored snapshot's sequence plus one, or 1 for the stream's first snapshot. */
+  sequence: bigint
+  /** The aggregate state after the commit's events. */
+  payload: Uint8Array
+}
+
+/**
+ * Everything a repository writes atomically for one command. A commit with no events is a no-op,
+ * and its snapshot is ignored.
+ */
+export interface Commit {
+  /** The stream the events are appended to. */
+  entityId: string
+  /** The new events, in ascending sequence order. */
+  events: SerializedEvent[]
+  /** The snapshot to write, when the commit reaches a snapshot boundary. */
+  snapshot?: NewSnapshot | null | undefined
+}
+
+/** Options every repository call takes. */
+export interface CallOptions {
+  /** Aborts the call. An abort before the call starts rejects with the signal's reason. */
+  signal?: AbortSignal | undefined
+}
+
+/**
+ * An append-only event log with one optional snapshot and one head per stream (ADR 0007). Every
+ * backend must:
+ *
+ * - refuse a commit built wrong ({@link validateCommit}) with `invalidCommit`;
+ * - keep a head per stream, the highest event sequence ever committed to it, which a commit
+ *   raises to its last event and compaction never touches;
+ * - refuse a commit whose first event doesn't follow the stored head with a
+ *   {@link ConflictError}, or with a {@link SequenceGapError} when it skips past the head;
+ * - report a stream whose head disagrees with its events or snapshot as a
+ *   {@link StreamHeadDriftError}, ranked above a gap and any other conflict;
+ * - refuse a commit's snapshot whose sequence isn't the stored snapshot's plus one (1 with none
+ *   stored) with a {@link ConflictError};
+ * - write a commit's events, head and snapshot atomically, or nothing;
+ * - refuse an entity ID in a reserved namespace on every write path, before any request;
+ * - return events in ascending sequence order, and `latest` in descending order.
+ */
+export interface Repository {
+  /** Appends a commit's events, and its snapshot if it has one, atomically. */
+  commit(commit: Commit, options?: CallOptions): Promise<void>
+
+  /** Every stored event of the stream, ascending. */
+  events(entityId: string, options?: CallOptions): Promise<SerializedEvent[]>
+
+  /** The stream's events after sequence `after`, ascending. */
+  eventsAfter(entityId: string, after: bigint, options?: CallOptions): Promise<SerializedEvent[]>
+
+  /**
+   * The stream's last `n` events, newest first, never the snapshot. `n` must be a safe integer of
+   * at least 1, or the call fails with `invalidArgument` before any request.
+   */
+  latest(entityId: string, n: number, options?: CallOptions): Promise<SerializedEvent[]>
+
+  /** The stream's snapshot, or null when it has none. */
+  snapshot(entityId: string, options?: CallOptions): Promise<SerializedSnapshot | null>
+
+  /**
+   * Writes a snapshot outside a commit, such as a catch-up snapshot. It never lowers the stored
+   * snapshot's event sequence: it replaces a snapshot at or below it and resolves `true`, or
+   * leaves a newer one in place and resolves `false`. The stream's head must cover the snapshot,
+   * or the write fails with a {@link StreamHeadDriftError}. A snapshot at event sequence 0 needs no
+   * head.
+   */
+  putSnapshot(snapshot: SerializedSnapshot, options?: CallOptions): Promise<boolean>
+
+  /**
+   * Deletes the stream's events with sequences 1 to `through`, but only when the stored snapshot
+   * covers them (its event sequence is at least `through`), and resolves to how many it deleted.
+   * It never deletes the snapshot or touches the head. A `through` below 1 deletes nothing.
+   */
+  compactBelow(entityId: string, through: bigint, options?: CallOptions): Promise<number>
+}
+
+/** The most actions one commit may carry, DynamoDB's transaction limit. */
+export const MAX_COMMIT_ACTIONS = 100
+
+/** The most bytes one commit may carry, summed over its actions: 95% of DynamoDB's 4 MB. */
+export const MAX_COMMIT_BYTES = 3_800_000
+
+/** The prefixes of the entity IDs only the engine writes. */
+export const RESERVED_PREFIXES: readonly string[] = Object.freeze([
+  'SYSTEM#',
+  'command-outcome#',
+])
+
+// The control rows every commit checks: the feature marker and the rebuild lock.
+const FEATURES_ID = 'SYSTEM#FEATURES'
+const REBUILD_LOCK_ID = 'SYSTEM#REBUILD'
+
+/** Whether an entity ID is in a reserved namespace. */
+export function isReserved(entityId: string): boolean {
+  return RESERVED_PREFIXES.some((prefix) => entityId.startsWith(prefix))
+}
+
+/** Refuses an entity ID in a reserved namespace, on a write path, before any request. */
+export function checkNotReserved(entityId: string): void {
+  if (isReserved(entityId)) {
+    throw new ReservedEntityIdError(entityId)
+  }
+}
+
+/**
+ * Checks that a commit's events can be stored as written: each belongs to the commit's entity and
+ * has the ID `{entityId}:{sequence}`, they share one entity type, the first sequence is at least
+ * 1, and the sequences are contiguous. A snapshot must have the events' entity type and a
+ * sequence of at least 1. A commit with no events is valid, and its snapshot isn't checked.
+ */
+export function validateCommit(commit: Commit): void {
+  const [first] = commit.events
+  if (first === undefined) {
+    return
+  }
+
+  for (const event of commit.events) {
+    if (event.entityType !== first.entityType) {
+      throw invalidCommit(
+        `event ${event.id} has entity type ${event.entityType}, but the commit's first event ` +
+          `has ${first.entityType}`,
+      )
+    }
+  }
+
+  const snapshot = commit.snapshot
+  if (snapshot && snapshot.entityType !== first.entityType) {
+    throw invalidCommit(
+      `the snapshot has entity type ${snapshot.entityType}, but the events have ` +
+        first.entityType,
+    )
+  }
+  if (snapshot && snapshot.sequence < 1n) {
+    throw invalidCommit(
+      `snapshot sequence ${snapshot.sequence} is below 1; snapshot sequences start at 1`,
+    )
+  }
+
+  for (const event of commit.events) {
+    if (event.entityId !== commit.entityId) {
+      throw invalidCommit(
+        `event ${event.id} belongs to entity ${event.entityId}, not ${commit.entityId}`,
+      )
+    }
+
+    const id = eventId(event.entityId, event.sequence)
+    if (event.id !== id) {
+      throw invalidCommit(`event ${event.id} should have the ID ${id}`)
+    }
+  }
+
+  if (first.sequence < 1n) {
+    throw invalidCommit(`event sequence ${first.sequence} is below 1; sequences start at 1`)
+  }
+
+  for (let i = 1; i < commit.events.length; i++) {
+    const previous = commit.events[i - 1]!.sequence
+    const next = commit.events[i]!.sequence
+    if (next !== previous + 1n) {
+      throw invalidCommit(
+        `event sequence ${next} follows ${previous}; sequences must be contiguous`,
+      )
+    }
+  }
+}
+
+/**
+ * The size of each action a commit's transaction carries, in order: the feature-marker and
+ * rebuild-lock checks, then the stream's head update, its event puts, and its snapshot put when
+ * it writes one. `ttl` gives the expiry an entity type's items carry, if it's retained. Every
+ * backend budgets a commit by these sizes, so an oversized commit fails the same way on each.
+ */
+export function commitSizes(
+  commit: Commit,
+  ttl: (entityType: string) => number | undefined,
+): number[] {
+  const sizes = [controlCheckSize(FEATURES_ID), controlCheckSize(REBUILD_LOCK_ID)]
+  const first = commit.events[0]
+  const last = commit.events.at(-1)
+  if (first === undefined || last === undefined) {
+    return sizes
+  }
+
+  const head = headUpdate(commit.entityId, first.sequence, last.sequence, ttl(first.entityType))
+  sizes.push(headActionSize(head))
+  for (const event of commit.events) {
+    sizes.push(itemSize(eventItem(event, ttl(event.entityType))))
+  }
+
+  const snapshot = commit.snapshot
+  if (snapshot) {
+    const stored: SerializedSnapshot = {
+      entityType: snapshot.entityType,
+      entityId: commit.entityId,
+      sequence: snapshot.sequence,
+      eventSequence: last.sequence,
+      payload: snapshot.payload,
+    }
+    sizes.push(itemSize(snapshotItem(stored, ttl(snapshot.entityType))))
+  }
+
+  return sizes
+}
+
+/**
+ * Refuses a commit whose actions are over the budget: more than {@link MAX_COMMIT_ACTIONS}, more
+ * than {@link MAX_COMMIT_BYTES} in all, or one over {@link MAX_COMMIT_ITEM_BYTES}.
+ */
+export function checkBudget(sizes: readonly number[]): void {
+  let bytes = 0
+  let largestItem = 0
+  for (const size of sizes) {
+    bytes += size
+    largestItem = Math.max(largestItem, size)
+  }
+
+  const tooLarge =
+    sizes.length > MAX_COMMIT_ACTIONS ||
+    bytes > MAX_COMMIT_BYTES ||
+    largestItem > MAX_COMMIT_ITEM_BYTES
+  if (tooLarge) {
+    throw new CommitTooLargeError(sizes.length, bytes, largestItem)
+  }
+}
+
+// A control check is sized by its key: `pk` and `sk = 0`.
+function controlCheckSize(pk: string): number {
+  return itemSize({pk: {S: pk}, sk: {N: '0'}})
+}
+
+function invalidCommit(message: string): EvtError {
+  return new EvtError('invalidCommit', `invalid commit: ${message}`)
+}