@photon-grove/evt 0.1.2 → 0.2.0

package/src/postgres/repository.ts

@@ -12,6 +12,7 @@ import {
   CompactionUncoveredError,
   ConflictError,
   EvtError,
+  FenceConflictError,
   HistoryDependentProjectionError,
   RebuildInProgressError,
   SequenceGapError,
@@ -34,13 +35,19 @@ import {decodeMetadata, emptyMetadata, encodeMetadata} from '../metadata.js'
 import {
   type CallOptions,
   type Commit,
-  type Repository,
+  type NormalizedTransaction,
   type StoreInitializer,
+  type TransactionCommit,
+  type TransactionalRepository,
   checkBudget,
+  checkFenceRetention,
   checkNotReserved,
-  commitSizes,
+  normalizeTransaction,
+  rankFailures,
+  transactionSizes,
   validateCommit,
 } from '../repository.js'
+import {compareUtf8} from '../utf8.js'
 import type {PgClient, PgConnection, PgQueryable} from './client.js'
 import {
   ENGINE_LOCK_EXCLUSIVE,
@@ -69,7 +76,9 @@ export interface PgRepositoryOptions {
 /** The backend name a projector group for the PostgreSQL repository would carry. */
 export const POSTGRES_BACKEND = 'postgres'
 
-// The event columns every read selects, each as text, so no driver parses a stored value.
+// The event columns every read selects, each as text, so no driver parses a stored value. An
+// ORDER BY names the table's column, since a bare `sequence` would sort the text alias: 10
+// before 9.
 const EVENT_COLUMNS =
   'event_id, sequence::text AS sequence, event_type, version::text AS version, entity_id, ' +
   "entity_type, encode(payload, 'hex') AS payload, metadata::text AS metadata"
@@ -96,7 +105,7 @@ type Row = Record<string, unknown>
  * it validated. Every commit and snapshot write reads the manifest again under a shared lock that
  * no declaration can take while the write is open, and validates it again when it changed.
  */
-export class PgRepository implements Repository, StoreInitializer {
+export class PgRepository implements TransactionalRepository, StoreInitializer {
   readonly #client: PgClient
   readonly #tables: PgTables
 
@@ -169,11 +178,27 @@ export class PgRepository implements Repository, StoreInitializer {
     options?.signal?.throwIfAborted()
     validateCommit(commit)
     checkNotReserved(commit.entityId)
-    if (commit.events.length === 0) {
-      return
+    if (commit.events.length > 0) {
+      await this.#write(normalizeTransaction({streams: [commit]}), options)
     }
+  }
 
-    for (const group of commit.projections ?? []) {
+  /**
+   * Commits every stream and checks every fence in one transaction, in the order Go and Rust run
+   * it: every stream's entity lock, written and fenced, in ascending entity-ID byte order; the
+   * marker check, the fences' retention and the rebuild-lock assertion; every head statement and
+   * fence read, ranked; the event inserts; then the snapshot upserts.
+   */
+  async commitTransaction(transaction: TransactionCommit, options?: CallOptions): Promise<void> {
+    options?.signal?.throwIfAborted()
+    const normalized = normalizeTransaction(transaction)
+    if (normalized.streams.length > 0 || normalized.fences.length > 0) {
+      await this.#write(normalized, options)
+    }
+  }
+
+  async #write(transaction: NormalizedTransaction, options?: CallOptions): Promise<void> {
+    for (const group of transaction.projections) {
       if (group.backend !== POSTGRES_BACKEND || group.operations.length > 0) {
         throw new EvtError(
           'invalidCommit',
@@ -183,59 +208,116 @@ export class PgRepository implements Repository, StoreInitializer {
     }
 
     // Every backend budgets a commit the same way, so an oversized one fails before any request.
-    checkBudget(commitSizes(commit, () => undefined))
+    checkBudget(transactionSizes(transaction, () => undefined))
     await this.#ensureStreamHeads(options)
 
-    const {entityId, events} = commit
-    const first = events[0]!.sequence
-    const last = events.at(-1)!.sequence
     await this.#transaction(options, async (run) => {
-      await run(ENTITY_LOCK, [entityId])
-      await this.#checkManifest(run)
+      // Each stream once, in the bytewise order that also pins the transaction, so two
+      // transactions that share streams lock them in the same sequence and can't deadlock.
+      const ids = [...transaction.streams, ...transaction.fences].map(({entityId}) => entityId)
+      ids.sort(compareUtf8)
+      for (const [index, entityId] of ids.entries()) {
+        if (ids[index - 1] !== entityId) {
+          await run(ENTITY_LOCK, [entityId])
+        }
+      }
+
+      const manifest = await this.#checkManifest(run)
+      const retention = manifest.retention
+      checkFenceRetention(transaction, (entityType) => retention.includes(entityType))
       await this.#assertNoRebuildLock(run)
 
-      if (!(await this.#moveHead(run, entityId, events[0]!.entityType, first, last))) {
-        throw await this.#probe(run, entityId, first)
+      // Every head statement and fence read runs before any failure is reported, so the ranking
+      // sees them all.
+      const moved: boolean[] = []
+      for (const stream of transaction.streams) {
+        const {entityId, events} = stream
+        const first = events[0]!.sequence
+        const last = events.at(-1)!.sequence
+        moved.push(await this.#moveHead(run, entityId, events[0]!.entityType, first, last))
       }
-
-      for (const event of events) {
-        if (!(await this.#insertEvent(run, event))) {
-          // The head statement passed and the row exists: an event sits above the head. The
-          // entity lock rules out a racing writer.
-          throw drift(entityId, first - 1n, await this.#derivedHead(run, entityId))
+      const stale = []
+      for (const fence of transaction.fences) {
+        if ((await this.#storedHead(run, fence.entityId)) !== fence.head) {
+          stale.push(fence)
         }
       }
 
-      const snapshot = commit.snapshot
-      if (snapshot) {
-        const rows = await run(
-          `SELECT sequence::text AS sequence FROM ${this.#tables.snapshots} WHERE entity_id = $1`,
-          [entityId],
-        )
-        const stored = rows[0] === undefined ? null : BigInt(text(rows[0], 'sequence'))
-        if (stored === null && snapshot.sequence !== 1n) {
-          throw new ConflictError(
-            entityId,
-            `snapshot sequence ${snapshot.sequence} has no stored predecessor`,
-          )
-        }
-        if (stored !== null && snapshot.sequence !== stored + 1n) {
-          throw new ConflictError(
-            entityId,
-            `snapshot sequence moved: stored ${stored}, commit writes ${snapshot.sequence}`,
-          )
+      const failures: EvtError[] = []
+      for (const [index, stream] of transaction.streams.entries()) {
+        if (!moved[index]) {
+          failures.push(await this.#probe(run, stream.entityId, stream.events[0]!.sequence))
         }
+      }
+      for (const fence of stale) {
+        // No first sequence: a fence that didn't drift is a fence conflict.
+        const verdict = await this.#probe(run, fence.entityId, 0n)
+        failures.push(
+          verdict instanceof StreamHeadDriftError
+            ? verdict
+            : new FenceConflictError(fence.entityId, fence.head, fence.provenance),
+        )
+      }
+      const failure = rankFailures(failures)
+      if (failure !== undefined) {
+        throw failure
+      }
 
-        await this.#upsertSnapshot(run, {...snapshot, entityId, eventSequence: last})
+      for (const stream of transaction.streams) {
+        await this.#insertEvents(run, stream)
+      }
+      for (const stream of transaction.streams) {
+        await this.#writeCommitSnapshot(run, stream)
       }
     })
   }
 
+  // A stream's event inserts, after its head statement passed. A row that already exists is an
+  // event above the head: the entity lock rules out a racing writer.
+  async #insertEvents(run: Statement, stream: Commit): Promise<void> {
+    const first = stream.events[0]!.sequence
+    for (const event of stream.events) {
+      if (!(await this.#insertEvent(run, event))) {
+        throw drift(stream.entityId, first - 1n, await this.#derivedHead(run, stream.entityId))
+      }
+    }
+  }
+
+  // A stream's commit snapshot, which must follow the stored one, as the DynamoDB put's condition
+  // requires.
+  async #writeCommitSnapshot(run: Statement, stream: Commit): Promise<void> {
+    const {entityId, snapshot} = stream
+    if (!snapshot) {
+      return
+    }
+
+    const rows = await run(
+      `SELECT sequence::text AS sequence FROM ${this.#tables.snapshots} WHERE entity_id = $1`,
+      [entityId],
+    )
+    const stored = rows[0] === undefined ? null : BigInt(text(rows[0], 'sequence'))
+    if (stored === null && snapshot.sequence !== 1n) {
+      throw new ConflictError(
+        entityId,
+        `snapshot sequence ${snapshot.sequence} has no stored predecessor`,
+      )
+    }
+    if (stored !== null && snapshot.sequence !== stored + 1n) {
+      throw new ConflictError(
+        entityId,
+        `snapshot sequence moved: stored ${stored}, commit writes ${snapshot.sequence}`,
+      )
+    }
+
+    const eventSequence = stream.events.at(-1)!.sequence
+    await this.#upsertSnapshot(run, {...snapshot, entityId, eventSequence})
+  }
+
   async events(entityId: string, options?: CallOptions): Promise<SerializedEvent[]> {
     options?.signal?.throwIfAborted()
     const rows = await this.#read(
       `SELECT ${EVENT_COLUMNS} FROM ${this.#tables.events} WHERE entity_id = $1 ` +
-        'ORDER BY sequence ASC',
+        `ORDER BY ${this.#tables.events}.sequence ASC`,
       [entityId],
     )
 
@@ -251,7 +333,8 @@ export class PgRepository implements Repository, StoreInitializer {
     int64Argument(after, 'after')
     const rows = await this.#read(
       `SELECT ${EVENT_COLUMNS} FROM ${this.#tables.events} ` +
-        'WHERE entity_id = $1 AND sequence > $2::bigint ORDER BY sequence ASC',
+        'WHERE entity_id = $1 AND sequence > $2::bigint ' +
+        `ORDER BY ${this.#tables.events}.sequence ASC`,
       [entityId, after.toString()],
     )
 
@@ -269,7 +352,7 @@ export class PgRepository implements Repository, StoreInitializer {
 
     const rows = await this.#read(
       `SELECT ${EVENT_COLUMNS} FROM ${this.#tables.events} WHERE entity_id = $1 ` +
-        'ORDER BY sequence DESC LIMIT $2::bigint',
+        `ORDER BY ${this.#tables.events}.sequence DESC LIMIT $2::bigint`,
       [entityId, n.toString()],
     )
 
@@ -373,16 +456,18 @@ export class PgRepository implements Repository, StoreInitializer {
   // The commit-time marker check, under the manifest's shared lock held to COMMIT, so a
   // declaration can't slip between the check and the write. A manifest that changed since this
   // writer validated it is validated again.
-  async #checkManifest(run: Statement): Promise<void> {
+  async #checkManifest(run: Statement): Promise<FeatureManifest> {
     await run(ENGINE_LOCK_SHARED, [featuresLockKey(this.#tables)])
     const manifest = await this.#readManifest(run)
     if (manifest !== null && manifest.version === this.#validated) {
-      return
+      return manifest
     }
 
     this.#validated = null
     checkWritable(manifest)
     this.#validated = manifest!.version
+
+    return manifest!
   }
 
   // The commit-time rebuild-lock assertion, under the rebuild fence's shared lock held to COMMIT:
@@ -686,11 +771,11 @@ function transient(error: unknown): unknown {
 }
 
 // The statements of a DDL script, one at a time, since a driver's extended protocol runs one per
-// call. Each ends at a semicolon that ends its line and comes before a blank line, a CREATE, a DO
-// or the end, which no statement inside the DO block's body is followed by.
+// call. Each ends at a semicolon that ends its line and comes before a blank line, a CREATE, an
+// ALTER, a DO or the end, which no statement inside the DO block's body is followed by.
 function statements(ddl: string): string[] {
   return ddl
-    .split(/;\n(?=\n|CREATE |DO |$)/)
+    .split(/;\n(?=\n|CREATE |ALTER |DO |$)/)
     .map((statement) => statement.trim())
     .filter((statement) => statement !== '')
 }

package/src/postgres/schema.ts

@@ -176,10 +176,26 @@ CREATE TABLE IF NOT EXISTS ${outcomesTable(tables)} (
     rejection  jsonb,
     code       text,
     created_at timestamptz NOT NULL DEFAULT now(),
+    command_type text,
+    targets      jsonb,
+    principal    text,
     CHECK ((status = 'rejected' AND rejection IS NOT NULL AND code IS NOT NULL)
            OR (status = 'accepted' AND rejection IS NULL AND code IS NULL))
 );
 
+DO $$
+BEGIN
+    IF (SELECT count(*) FROM pg_attribute
+        WHERE attrelid = '${outcomesTable(tables)}'::regclass
+          AND attname IN ('command_type', 'targets', 'principal')
+          AND NOT attisdropped) < 3 THEN
+        ALTER TABLE ${outcomesTable(tables)}
+            ADD COLUMN IF NOT EXISTS command_type text,
+            ADD COLUMN IF NOT EXISTS targets      jsonb,
+            ADD COLUMN IF NOT EXISTS principal    text;
+    END IF;
+END $$;
+
 CREATE TABLE IF NOT EXISTS ${featuresTable(tables)} (
     id                integer PRIMARY KEY,
     version           bigint NOT NULL,

package/src/repository.ts

@@ -1,17 +1,22 @@
 // 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 {headActionSize, headFence, headUpdate} from './dynamodb/head.js'
 import {eventItem, itemSize, snapshotItem} from './dynamodb/item.js'
 import {FEATURES_PK, REBUILD_LOCK_PK} from './dynamodb/marker.js'
 import {
   CommitTooLargeError,
   EvtError,
+  type FenceProvenance,
   ProjectorOnlyCommitError,
   ReservedEntityIdError,
+  RetentionConflictError,
+  SequenceGapError,
+  StreamHeadDriftError,
 } from './errors.js'
 import {type SerializedEvent, type SerializedSnapshot, eventId} from './event.js'
 import {MAX_COMMIT_ITEM_BYTES} from './snapshots.js'
+import {compareUtf8} from './utf8.js'
 
 /** A snapshot to write with a commit. Its event sequence is the commit's last event. */
 export interface NewSnapshot {
@@ -143,6 +148,131 @@ export interface StoreInitializer {
   initialize(options?: CallOptions): Promise<boolean>
 }
 
+/**
+ * A stream a transaction read but doesn't write, whose head must not move before it commits (ADR
+ * 0007): the fence passes while the stream's stored head still equals `head`.
+ */
+export interface ReadFence {
+  entityId: string
+  /** The stream's entity type, which a fence on a retained type is refused for. */
+  entityType: string
+  /** The head the transaction observed: 0 for a stream with no events. */
+  head: bigint
+  /** Whether the engine read the head itself, or the caller stamped it. */
+  provenance: FenceProvenance
+}
+
+/**
+ * Everything one transaction writes atomically: the streams it appends to, and fences on the
+ * streams it read. A fence on a stream the transaction also writes is dropped, since that stream's
+ * head update already conditions on the head it read. A transaction that writes nothing and fences
+ * nothing is a no-op.
+ */
+export interface TransactionCommit {
+  /** The streams written, each a {@link Commit}, at most one per stream. */
+  streams: readonly Commit[]
+  /** The streams read but not written, at most one fence per stream. */
+  fences?: readonly ReadFence[] | null | undefined
+}
+
+/**
+ * A repository that commits several streams atomically, with read fences (ADR 0004). A
+ * transaction is refused as a commit is, and also:
+ *
+ * - with `invalidCommit` when it writes a stream twice, fences a stream twice, fences at a head
+ *   below 0 or at the largest int64, or carries a snapshot for a stream it writes no events to;
+ * - with a {@link RetentionConflictError} when it fences an entity type with retention: by the
+ *   repository's own configuration before any request, and by the store's manifest after the
+ *   manifest's other refusals, but always before the rebuild lock's;
+ * - with a {@link FenceConflictError} when a fenced stream's head moved, unless the stream
+ *   drifted, ranked after every drift and gap of the transaction, in transaction order.
+ */
+export interface TransactionalRepository extends Repository {
+  /** Appends to every stream and checks every fence atomically. */
+  commitTransaction(transaction: TransactionCommit, options?: CallOptions): Promise<void>
+}
+
+/** A transaction as the backends write it. */
+export interface NormalizedTransaction {
+  /** The streams it writes events to, sorted by entity ID bytes, without their projections. */
+  readonly streams: readonly Commit[]
+  /** Its fences on the streams it doesn't write, sorted the same way. */
+  readonly fences: readonly ReadFence[]
+  /** The written streams' projector groups, in the order the streams were declared. */
+  readonly projections: readonly ProjectorGroup[]
+}
+
+/**
+ * Validates a transaction and puts it in the order every backend writes it: the written streams,
+ * then the fences, each sorted by entity ID bytes, the order that pins a DynamoDB transaction and
+ * PostgreSQL's locks. The projector groups keep the order the streams were declared in. Streams
+ * without events are dropped, and so are the fences on streams that write events, whose head
+ * updates condition on the head they read. A fence on a stream listed without events stays.
+ */
+export function normalizeTransaction(transaction: TransactionCommit): NormalizedTransaction {
+  const listed = new Set<string>()
+  for (const stream of transaction.streams) {
+    validateCommit(stream)
+    checkNotReserved(stream.entityId)
+    if (listed.has(stream.entityId)) {
+      throw invalidCommit(`duplicate stream ${stream.entityId}`)
+    }
+    listed.add(stream.entityId)
+  }
+
+  const fenced = new Set<string>()
+  for (const fence of transaction.fences ?? []) {
+    checkNotReserved(fence.entityId)
+    if (fence.head < 0n || fence.head >= MAX_INT64 || fenced.has(fence.entityId)) {
+      throw invalidCommit(`invalid or duplicate fence ${fence.entityId}`)
+    }
+    fenced.add(fence.entityId)
+  }
+
+  for (const stream of transaction.streams) {
+    if (stream.snapshot && stream.events.length === 0) {
+      throw invalidCommit(`the snapshot of ${stream.entityId} must cover this commit's last event`)
+    }
+  }
+
+  const written = transaction.streams.filter((stream) => stream.events.length > 0)
+  const projections = written.flatMap((stream) => stream.projections ?? [])
+  const streams = written.map((stream) => Object.assign({}, stream, {projections: undefined}))
+  streams.sort(byId)
+  const writes = new Set(streams.map((stream) => stream.entityId))
+  const fences = (transaction.fences ?? []).filter((fence) => !writes.has(fence.entityId))
+  fences.sort(byId)
+
+  return {streams, fences, projections}
+}
+
+/**
+ * Refuses a transaction that fences a retained entity type, by the store's manifest or the
+ * repository's own configuration.
+ */
+export function checkFenceRetention(
+  transaction: NormalizedTransaction,
+  retained: (entityType: string) => boolean,
+): void {
+  for (const fence of transaction.fences) {
+    if (retained(fence.entityType)) {
+      throw new RetentionConflictError(fence.entityType)
+    }
+  }
+}
+
+/**
+ * The error a failed transaction reports from the failures of its streams and fences, given in
+ * transaction order: the first drift, else the first gap, else the first of the rest.
+ */
+export function rankFailures(failures: readonly EvtError[]): EvtError | undefined {
+  return (
+    failures.find((failure) => failure instanceof StreamHeadDriftError) ??
+    failures.find((failure) => failure instanceof SequenceGapError) ??
+    failures[0]
+  )
+}
+
 /** The most actions one commit may carry, DynamoDB's transaction limit. */
 export const MAX_COMMIT_ACTIONS = 100
 
@@ -255,13 +385,42 @@ export function validateCommit(commit: Commit): void {
 export function commitSizes(
   commit: Commit,
   ttl: (entityType: string) => number | undefined,
+): number[] {
+  const transaction = {streams: [commit], fences: [], projections: commit.projections ?? []}
+
+  return transactionSizes(transaction, ttl)
+}
+
+/**
+ * The size of each action a transaction carries: the two control checks, every stream's projector
+ * operations, every written stream's head update, event puts and snapshot put, then a check on
+ * every fenced stream's head. Every backend budgets a transaction by these sizes.
+ */
+export function transactionSizes(
+  transaction: NormalizedTransaction,
+  ttl: (entityType: string) => number | undefined,
 ): number[] {
   // The control rows every commit checks: the feature marker and the rebuild lock.
   const sizes = [controlCheckSize(FEATURES_PK), controlCheckSize(REBUILD_LOCK_PK)]
-  for (const group of commit.projections ?? []) {
+  for (const group of transaction.projections) {
     sizes.push(...group.sizes)
   }
+  for (const stream of transaction.streams) {
+    sizes.push(...streamSizes(stream, ttl))
+  }
+  for (const fence of transaction.fences) {
+    sizes.push(headActionSize(headFence(fence.entityId, fence.head)))
+  }
 
+  return sizes
+}
+
+// A written stream's actions: its head update, its event puts and its snapshot put.
+function streamSizes(
+  commit: Commit,
+  ttl: (entityType: string) => number | undefined,
+): number[] {
+  const sizes: number[] = []
   const first = commit.events[0]
   const last = commit.events.at(-1)
   if (first === undefined || last === undefined) {
@@ -310,6 +469,14 @@ export function checkBudget(sizes: readonly number[]): void {
   }
 }
 
+// Orders streams and fences by their entity IDs' UTF-8 bytes.
+function byId(a: {entityId: string}, b: {entityId: string}): number {
+  return compareUtf8(a.entityId, b.entityId)
+}
+
+// The largest int64, whose successor no head can reach.
+const MAX_INT64 = 2n ** 63n - 1n
+
 // 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'}})

package/src/staging.ts

@@ -0,0 +1,138 @@
+// What a commit of one stream carries beyond its decided events, the same for a single command
+// and for a transaction: the stored events, the snapshot the policy calls for, and the projectors'
+// operations.
+
+import {
+  type Aggregate,
+  type EventDefinitions,
+  type EventOf,
+  type Projection,
+  encodeEventData,
+} from './aggregate.js'
+import {EvtError} from './errors.js'
+import {type SerializedEvent, eventId} from './event.js'
+import type {Metadata} from './metadata.js'
+import type {NewSnapshot, ProjectorGroup} from './repository.js'
+import {MAX_COMMIT_ITEM_BYTES, snapshotCommitSize, snapshotEventsDue} from './snapshots.js'
+
+const INT64_MAX = 2n ** 63n - 1n
+
+/**
+ * Serializes decided events continuing the stream after `after`, each with its own copy of
+ * `metadata`, and then folds them into `state`. Every event is encoded before any is applied, so
+ * when one fails to encode, `state` is untouched, even for an aggregate whose `apply` changes the
+ * state it's given.
+ */
+export function serializeEvents<S, C, D extends EventDefinitions>(
+  aggregate: Aggregate<S, C, D>,
+  entityId: string,
+  after: bigint,
+  state: S,
+  decided: readonly EventOf<D>[],
+  metadata: Metadata,
+): {events: SerializedEvent[]; state: S} {
+  let sequence = after
+  const events: SerializedEvent[] = []
+
+  for (const event of decided) {
+    if (sequence >= INT64_MAX) {
+      throw new EvtError(
+        'invalidCommit',
+        `invalid commit: entity ${entityId} is at the maximum event sequence`,
+      )
+    }
+    sequence++
+
+    const {version, payload} = encodeEventData(aggregate.events, event)
+    events.push({
+      id: eventId(entityId, sequence),
+      sequence,
+      type: event.type,
+      version,
+      entityId,
+      entityType: aggregate.type,
+      payload,
+      metadata: copyMetadata(metadata),
+    })
+  }
+
+  for (const event of decided) {
+    state = aggregate.apply(state, event)
+  }
+
+  return {events, state}
+}
+
+/**
+ * The snapshot a commit of `appended` events after `loadedSequence` carries, or null when the
+ * interval calls for none. A snapshot whose item is over the per-item commit budget is left out
+ * too, since it would fail every commit that carries it.
+ */
+export function commitSnapshot<S, C, D extends EventDefinitions>(
+  aggregate: Aggregate<S, C, D>,
+  entityId: string,
+  interval: number,
+  loaded: {readonly sequence: bigint; readonly snapshotSequence: bigint},
+  appended: number,
+  state: S,
+): NewSnapshot | null {
+  if (snapshotEventsDue(loaded.sequence, appended, interval) === 0) {
+    return null
+  }
+
+  const snapshot: NewSnapshot = {
+    entityType: aggregate.type,
+    sequence: loaded.snapshotSequence + 1n,
+    payload: aggregate.state.encode(state),
+  }
+  const eventSequence = loaded.sequence + BigInt(appended)
+  const size = snapshotCommitSize({...snapshot, entityId, eventSequence})
+
+  return size > MAX_COMMIT_ITEM_BYTES ? null : snapshot
+}
+
+/** The operations the aggregate's projectors add to a commit, in declaration order. */
+export function projectCommit<S, C, D extends EventDefinitions>(
+  aggregate: Aggregate<S, C, D>,
+  entityId: string,
+  state: S,
+  events: readonly SerializedEvent[],
+  snapshot: NewSnapshot | null,
+): ProjectorGroup[] {
+  const projectors = aggregate.projectors ?? []
+  if (projectors.length === 0) {
+    return []
+  }
+
+  // Each projector gets its own frozen copy of the events, their metadata and every byte array,
+  // so none can change what another one sees, or what the commit writes.
+  const encodedState = snapshot?.payload ?? aggregate.state.encode(state)
+  const detached = (): Projection<S> =>
+    Object.freeze({
+      entityType: aggregate.type,
+      entityId,
+      state,
+      encodedState: encodedState.slice(),
+      events: Object.freeze(
+        events.map((event) =>
+          Object.freeze({
+            ...event,
+            payload: event.payload && event.payload.slice(),
+            metadata: Object.freeze(copyMetadata(event.metadata)),
+          }),
+        ),
+      ),
+    })
+
+  return projectors.flatMap((projector) => projector.project(detached()) ?? [])
+}
+
+/** A copy of the metadata, so changing one event's changes no other. */
+export function copyMetadata(metadata: Metadata): Metadata {
+  return {
+    ...metadata,
+    trace: metadata.trace && new Map(metadata.trace),
+    origin: metadata.origin && {...metadata.origin},
+    extensions: new Map(metadata.extensions),
+  }
+}