@photon-grove/evt 0.1.1 → 0.2.0

package/src/postgres/schema.ts

@@ -0,0 +1,302 @@
+// The PostgreSQL layout of an event log, independent of any driver (storage format, "PostgreSQL"):
+// the table names a store is configured with, the engine relations derived from them, and the
+// idempotent DDL that Go's EnsureSchema and Rust's ensure_schema run.
+
+import {EvtError} from '../errors.js'
+
+/** The default events table. */
+export const DEFAULT_EVENTS_TABLE = 'evt_events'
+
+/** The default snapshots table. */
+export const DEFAULT_SNAPSHOTS_TABLE = 'evt_snapshots'
+
+/**
+ * The infix the engine relations derive from the events table name with, such as
+ * `evt_events__evt_features`. A configured table name may not contain it, in any case, so one
+ * log's tables can never equal another log's derived relation.
+ */
+export const RESERVED_INFIX = '__evt_'
+
+/**
+ * The longest events table name, in bytes. Its longest derived relation,
+ * `{events}__evt_rebuild_generation_pkey`, then fills PostgreSQL's 63-byte identifier limit.
+ */
+export const MAX_EVENTS_TABLE_NAME_BYTES = 63 - '__evt_rebuild_generation_pkey'.length
+
+/** The longest snapshots table name, in bytes, which leaves room for its `_pkey` index. */
+export const MAX_SNAPSHOTS_TABLE_NAME_BYTES = 63 - '_pkey'.length
+
+// Only pgTables can make a PgTables, so the names the DDL interpolates are always validated.
+declare const validated: unique symbol
+
+/**
+ * An event log's two configured tables, validated and folded to lower case. Only
+ * {@link pgTables} makes one.
+ */
+export interface PgTables {
+  readonly events: string
+  readonly snapshots: string
+  readonly [validated]: true
+}
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+// PostgreSQL's reserved keywords (pg_get_keywords() categories R and T), which can't be unquoted
+// table names. The same list as Go's and Rust's.
+const RESERVED_KEYWORDS = new Set(
+  `all analyse analyze and any array as asc asymmetric authorization binary both case cast check
+  collate collation column concurrently constraint create cross current_catalog current_date
+  current_role current_schema current_time current_timestamp current_user default deferrable desc
+  distinct do else end except false fetch for foreign freeze from full grant group having ilike in
+  initially inner intersect into is isnull join lateral leading left like limit localtime
+  localtimestamp natural not notnull null offset on only or order outer overlaps placing primary
+  references returning right select session_user similar some symmetric system_user table
+  tablesample then to trailing true union unique user using variadic verbose when where window
+  with`.split(/\s+/),
+)
+
+/**
+ * Validates an event log's table names and folds them to lower case, as PostgreSQL folds unquoted
+ * identifiers. Each must be a plain identifier that isn't a reserved keyword, within its length
+ * limit, without the {@link RESERVED_INFIX}, and no two relations the schema creates may share a
+ * name. A name that breaks a rule fails with `invalidArgument`, as Go and Rust refuse it at
+ * construction.
+ */
+export function pgTables(
+  events: string = DEFAULT_EVENTS_TABLE,
+  snapshots: string = DEFAULT_SNAPSHOTS_TABLE,
+): PgTables {
+  for (const [name, limit] of [
+    [events, MAX_EVENTS_TABLE_NAME_BYTES],
+    [snapshots, MAX_SNAPSHOTS_TABLE_NAME_BYTES],
+  ] as const) {
+    if (!validIdentifier(name, limit)) {
+      throw invalidConfig(`invalid table name ${JSON.stringify(name)}`)
+    }
+    if (name.toLowerCase().includes(RESERVED_INFIX)) {
+      throw invalidConfig(
+        `table name ${JSON.stringify(name)} must not contain the reserved infix ` +
+          JSON.stringify(RESERVED_INFIX),
+      )
+    }
+  }
+
+  const tables = {events: events.toLowerCase(), snapshots: snapshots.toLowerCase()} as PgTables
+  const shared = sharedRelation(tables)
+  if (shared !== null) {
+    throw invalidConfig(
+      `tables ${JSON.stringify(events)} and ${JSON.stringify(snapshots)} would both use the ` +
+        `name ${JSON.stringify(shared)}`,
+    )
+  }
+
+  return tables
+}
+
+/** The command-outcomes table: `evt_events` yields `evt_events__evt_command_outcomes`. */
+export function outcomesTable(tables: PgTables): string {
+  return derived(tables.events, 'command_outcomes')
+}
+
+/** The feature-marker table: `evt_events` yields `evt_events__evt_features`. */
+export function featuresTable(tables: PgTables): string {
+  return derived(tables.events, 'features')
+}
+
+/** The rebuild-lock table: `evt_events` yields `evt_events__evt_rebuild_lock`. */
+export function rebuildLockTable(tables: PgTables): string {
+  return derived(tables.events, 'rebuild_lock')
+}
+
+/** The rebuild-generation table: `evt_events` yields `evt_events__evt_rebuild_generation`. */
+export function rebuildGenerationTable(tables: PgTables): string {
+  return derived(tables.events, 'rebuild_generation')
+}
+
+/** The stream-heads table: `evt_events` yields `evt_events__evt_stream_heads`. */
+export function streamHeadsTable(tables: PgTables): string {
+  return derived(tables.events, 'stream_heads')
+}
+
+/** The entity-type index of the events table: `evt_events__evt_entity_type_idx`. */
+export function entityTypeIndex(tables: PgTables): string {
+  return derived(tables.events, 'entity_type_idx')
+}
+
+/**
+ * The idempotent DDL of an event log, byte for byte the DDL Go's `EnsureSchema` and Rust's
+ * `ensure_schema` run: the events and snapshots tables, the entity-type index (dropping its
+ * pre-v0.9 name), and the command-outcome, feature-marker, rebuild-fence and stream-heads tables.
+ * Run it inside one transaction, after {@link SCHEMA_LOCK} with the events table name, as Go and
+ * Rust do.
+ */
+export function schemaDdl(tables: PgTables): string {
+  const {events, snapshots} = tables
+
+  return `
+CREATE TABLE IF NOT EXISTS ${events} (
+    entity_id   text   NOT NULL,
+    sequence    bigint NOT NULL,
+    event_id    text   NOT NULL,
+    event_type  text   NOT NULL,
+    version     bigint NOT NULL,
+    entity_type text   NOT NULL,
+    payload     bytea  NOT NULL,
+    metadata    jsonb  NOT NULL DEFAULT '{}'::jsonb,
+    created_at  timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (entity_id, sequence)
+);
+CREATE INDEX IF NOT EXISTS ${entityTypeIndex(tables)} ON ${events} (entity_type);
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1 FROM pg_index
+        WHERE indexrelid = to_regclass('${events}_entity_type_idx')
+          AND indrelid = '${events}'::regclass
+    ) THEN
+        DROP INDEX ${events}_entity_type_idx;
+    END IF;
+END $$;
+
+CREATE TABLE IF NOT EXISTS ${snapshots} (
+    entity_id      text   PRIMARY KEY,
+    entity_type    text   NOT NULL,
+    sequence       bigint NOT NULL,
+    event_sequence bigint NOT NULL,
+    payload        bytea  NOT NULL,
+    updated_at     timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS ${outcomesTable(tables)} (
+    command_id text        PRIMARY KEY,
+    status     text        NOT NULL CHECK (status IN ('accepted', 'rejected')),
+    digest     text        NOT NULL,
+    response   bytea,
+    events     jsonb       NOT NULL DEFAULT '[]'::jsonb,
+    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,
+    features          text   NOT NULL,
+    history_dependent text   NOT NULL DEFAULT '[]',
+    retention         text   NOT NULL DEFAULT '[]'
+);
+
+CREATE TABLE IF NOT EXISTS ${rebuildLockTable(tables)} (
+    id               integer PRIMARY KEY,
+    owner            text        NOT NULL,
+    generation       bigint      NOT NULL,
+    lease_expires_at timestamptz NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS ${rebuildGenerationTable(tables)} (
+    id             integer PRIMARY KEY,
+    value          bigint   NOT NULL,
+    force_released boolean  NOT NULL DEFAULT false
+);
+
+CREATE TABLE IF NOT EXISTS ${streamHeadsTable(tables)} (
+    entity_id   text   PRIMARY KEY,
+    entity_type text   NOT NULL,
+    head        bigint NOT NULL CHECK (head >= 1)
+);
+`
+}
+
+/**
+ * Serializes schema changes across processes, in every language: `IF NOT EXISTS` alone can still
+ * race in PostgreSQL's catalogs. `$1` is the events table name.
+ */
+export const SCHEMA_LOCK = 'SELECT pg_advisory_xact_lock(1702261762, hashtext($1))'
+
+/**
+ * The per-entity transaction lock every commit and snapshot write takes, `$1` being the entity
+ * ID. Go and Rust run this exact statement, so writers in every language exclude each other.
+ */
+export const ENTITY_LOCK = 'SELECT pg_advisory_xact_lock(1702261760, hashtext($1))'
+
+/**
+ * The shared engine-row lock a commit takes and holds to `COMMIT`, `$1` being a key from
+ * {@link featuresLockKey} or {@link rebuildLockKey}. Commits don't serialize against each other.
+ */
+export const ENGINE_LOCK_SHARED = 'SELECT pg_advisory_xact_lock_shared(1702261761, hashtext($1))'
+
+/**
+ * The exclusive engine-row lock a declaration or a rebuild lifecycle step takes for its short
+ * transaction, so it never slips between a commit's check and its `COMMIT`.
+ */
+export const ENGINE_LOCK_EXCLUSIVE = 'SELECT pg_advisory_xact_lock(1702261761, hashtext($1))'
+
+/** The feature marker's engine-row lock key: `{events}:features`. */
+export function featuresLockKey(tables: PgTables): string {
+  return `${tables.events}:features`
+}
+
+/** The rebuild fence's engine-row lock key: `{events}:rebuild`. */
+export function rebuildLockKey(tables: PgTables): string {
+  return `${tables.events}:rebuild`
+}
+
+function derived(events: string, suffix: string): string {
+  return `${events}${RESERVED_INFIX}${suffix}`
+}
+
+// A valid identifier is ASCII, so its length is its byte count and folding it changes only A-Z.
+// The type check refuses a non-string passed from JavaScript, which the pattern would coerce.
+function validIdentifier(name: unknown, limit: number): name is string {
+  return (
+    typeof name === 'string' &&
+    name.length <= limit &&
+    IDENTIFIER.test(name) &&
+    !RESERVED_KEYWORDS.has(name.toLowerCase())
+  )
+}
+
+// A name two relations of the schema would share, or null, with the names already folded to lower
+// case. CREATE TABLE IF NOT EXISTS would otherwise skip a table whose name an index already took.
+function sharedRelation(tables: PgTables): string | null {
+  const {events, snapshots} = tables
+  const derivedTables = [
+    outcomesTable(tables),
+    featuresTable(tables),
+    rebuildLockTable(tables),
+    rebuildGenerationTable(tables),
+    streamHeadsTable(tables),
+  ]
+  const relations = [
+    events,
+    `${events}_pkey`,
+    entityTypeIndex(tables),
+    ...derivedTables.flatMap((table) => [table, `${table}_pkey`]),
+    snapshots,
+    `${snapshots}_pkey`,
+  ]
+
+  return relations.find((relation, index) => relations.indexOf(relation) !== index) ?? null
+}
+
+function invalidConfig(message: string): EvtError {
+  return new EvtError('invalidArgument', `postgres: ${message}`)
+}

package/src/repository.ts

@@ -1,12 +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, ReservedEntityIdError} from './errors.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 {
@@ -17,9 +27,24 @@ export interface NewSnapshot {
   payload: Uint8Array
 }
 
+/**
+ * Operations a projector adds to a commit, for the backend it names to write in the commit's own
+ * transaction (Go's transaction groups). The DynamoDB repository writes `dynamodb` groups, whose
+ * operations are `TransactWriteItems` actions. The in-memory repository budgets every group and
+ * writes none, as Go's does, so code with projectors runs on it unchanged.
+ */
+export interface ProjectorGroup {
+  /** The backend whose transaction carries the operations, such as `dynamodb`. */
+  readonly backend: string
+  /** The operations, in the order they're written. */
+  readonly operations: readonly unknown[]
+  /** Each operation's size in the commit budget, as DynamoDB counts it. */
+  readonly sizes: readonly number[]
+}
+
 /**
  * Everything a repository writes atomically for one command. A commit with no events is a no-op,
- * and its snapshot is ignored.
+ * and its snapshot is ignored, unless it carries projector operations: then it's refused.
  */
 export interface Commit {
   /** The stream the events are appended to. */
@@ -28,6 +53,8 @@ export interface Commit {
   events: SerializedEvent[]
   /** The snapshot to write, when the commit reaches a snapshot boundary. */
   snapshot?: NewSnapshot | null | undefined
+  /** The operations the aggregate's projectors add, written first, in order. */
+  projections?: readonly ProjectorGroup[] | null | undefined
 }
 
 /** Options every repository call takes. */
@@ -53,7 +80,9 @@ export interface CallOptions {
  *   {@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;
+ * - write a commit's events, head and snapshot atomically, or nothing, with the projector
+ *   operations it writes (a backend writes only its own groups), and refuse projector operations
+ *   without events with a {@link ProjectorOnlyCommitError};
  * - refuse an entity ID in a reserved namespace on every write path, before any request;
  * - refuse every write (a commit, a snapshot write, compaction) to a store whose feature manifest
  *   declares a pair this package doesn't model, with an {@link UnsupportedFeatureError}, and to
@@ -119,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
 
@@ -147,11 +301,27 @@ export function checkNotReserved(entityId: string): void {
  * 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.
+ * sequence of at least 1, and each projector group a size per operation. A commit with no events
+ * is valid, and its snapshot isn't checked, but its projector operations are refused.
  */
 export function validateCommit(commit: Commit): void {
+  let operations = 0
+  for (const group of commit.projections ?? []) {
+    if (group.sizes.length !== group.operations.length) {
+      throw invalidCommit(
+        `a ${group.backend} projector group has ${group.operations.length} operations but ` +
+          `${group.sizes.length} sizes`,
+      )
+    }
+    operations += group.operations.length
+  }
+
   const [first] = commit.events
   if (first === undefined) {
+    if (operations > 0) {
+      throw new ProjectorOnlyCommitError(operations)
+    }
+
     return
   }
 
@@ -207,16 +377,50 @@ export function validateCommit(commit: Commit): void {
 
 /**
  * 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.
+ * rebuild-lock checks, the projector operations, 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 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 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) {
@@ -265,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'}})