@photon-grove/evt 0.1.1 → 0.2.0

package/src/errors.ts

@@ -15,6 +15,10 @@
  * - `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.
+ * - `fenceConflict`: another writer moved a stream the transaction read but didn't write. A
+ *   conflict, retryable when the engine observed the fenced head.
+ * - `retentionConflict`: a transaction fenced a stream whose entity type has retention, which a
+ *   fence can't protect. Nothing was written.
  * - `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.
@@ -30,6 +34,8 @@
  * - `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.
+ * - `projectorOnlyCommit`: a commit carries projector operations but no events. Nothing was
+ *   written.
  * - `replay`: a stored event failed to upcast or decode while an aggregate loaded.
  * - `snapshot`: a stored snapshot failed to decode while an aggregate loaded.
  */
@@ -40,6 +46,8 @@ export type EvtErrorCode =
   | 'invalidCommit'
   | 'conflict'
   | 'sequenceGap'
+  | 'fenceConflict'
+  | 'retentionConflict'
   | 'streamHeadDrift'
   | 'commitTooLarge'
   | 'compactionUncovered'
@@ -51,6 +59,7 @@ export type EvtErrorCode =
   | 'transient'
   | 'rebuildInProgress'
   | 'historyDependentProjection'
+  | 'projectorOnlyCommit'
   | 'replay'
   | 'snapshot'
 
@@ -280,6 +289,48 @@ export class RebuildInProgressError extends EvtError {
   }
 }
 
+/** Where a read fence's head came from (ADR 0004): the engine's own read, or the caller. */
+export type FenceProvenance = 'engine' | 'caller'
+
+/**
+ * A read fence failed: another writer moved a stream the transaction read but didn't write past
+ * the head it observed. A fence the engine filled is retryable, since loading again observes the
+ * new head. A caller-stamped one isn't: the caller's input is stale. Nothing was written.
+ */
+export class FenceConflictError extends EvtError {
+  override readonly name = 'FenceConflictError'
+  override readonly code = 'fenceConflict'
+  readonly entityId: string
+  /** The head the transaction fenced the stream at. */
+  readonly head: bigint
+  readonly provenance: FenceProvenance
+
+  constructor(entityId: string, head: bigint, provenance: FenceProvenance) {
+    super('fenceConflict', `read fence failed for ${entityId} at head ${head} (${provenance})`)
+    this.entityId = entityId
+    this.head = head
+    this.provenance = provenance
+  }
+}
+
+/**
+ * A transaction fenced a stream whose entity type has retention: TTL deletes items in no order, so
+ * a fence on a retained stream protects nothing. Nothing was written.
+ */
+export class RetentionConflictError extends EvtError {
+  override readonly name = 'RetentionConflictError'
+  override readonly code = 'retentionConflict'
+  readonly entityType: string
+
+  constructor(entityType: string) {
+    super(
+      'retentionConflict',
+      `read fences refused for retention-enabled entity type ${entityType}`,
+    )
+    this.entityType = entityType
+  }
+}
+
 /**
  * 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.
@@ -301,6 +352,26 @@ export class HistoryDependentProjectionError extends EvtError {
   }
 }
 
+/**
+ * A commit carried projector operations but no events. Views are projections of committed events,
+ * so operations with no event behind them are refused on every backend. Nothing was written.
+ */
+export class ProjectorOnlyCommitError extends EvtError {
+  override readonly name = 'ProjectorOnlyCommitError'
+  override readonly code = 'projectorOnlyCommit'
+  /** How many projector operations the commit carried. */
+  readonly operations: number
+
+  constructor(operations: number) {
+    super(
+      'projectorOnlyCommit',
+      `a commit carries ${operations} projector operations but no events; views need a ` +
+        'backing event in the same commit',
+    )
+    this.operations = operations
+  }
+}
+
 /** 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'
@@ -337,16 +408,27 @@ export class SnapshotError extends EvtError {
   }
 }
 
-/** Whether an error is an optimistic-concurrency conflict: a `conflict` or a `sequenceGap`. */
+/**
+ * Whether an error is an optimistic-concurrency conflict: a `conflict`, a `sequenceGap` or a
+ * `fenceConflict`.
+ */
 export function isConflict(error: unknown): boolean {
-  return error instanceof EvtError && (error.code === 'conflict' || error.code === 'sequenceGap')
+  return (
+    error instanceof EvtError &&
+    (error.code === 'conflict' || error.code === 'sequenceGap' || error.code === 'fenceConflict')
+  )
 }
 
 /**
- * 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.
+ * Whether reloading and running the command again may succeed: after a conflict (a fence the
+ * caller stamped excepted), while a rebuild holds the store, after the feature manifest changed
+ * under the writer, or after throttling.
  */
 export function isRetryable(error: unknown): boolean {
+  // A caller-stamped fence stays stale however often the command runs again.
+  if (error instanceof FenceConflictError) {
+    return error.provenance === 'engine'
+  }
   if (isConflict(error)) {
     return true
   }

package/src/index.ts

@@ -9,6 +9,8 @@ export {
   type EventDefinition,
   type EventDefinitions,
   type EventOf,
+  type Projection,
+  type Projector,
   type Rejection,
   type Upcaster,
   defineAggregate,
@@ -31,10 +33,14 @@ export {
   EvtError,
   type EvtErrorCode,
   FeatureManifestChangedError,
+  FenceConflictError,
+  type FenceProvenance,
   HistoryDependentProjectionError,
+  ProjectorOnlyCommitError,
   RebuildInProgressError,
   ReplayError,
   ReservedEntityIdError,
+  RetentionConflictError,
   SequenceGapError,
   SnapshotError,
   StoreNotInitializedError,
@@ -73,12 +79,18 @@ export {
   emptyMetadata,
   encodeMetadata,
 } from './metadata.js'
-export type {
-  CallOptions,
-  Commit,
-  NewSnapshot,
-  Repository,
-  StoreInitializer,
+export {
+  type CallOptions,
+  type Commit,
+  type NewSnapshot,
+  type NormalizedTransaction,
+  type ProjectorGroup,
+  type ReadFence,
+  type Repository,
+  type StoreInitializer,
+  type TransactionCommit,
+  type TransactionalRepository,
+  normalizeTransaction,
 } from './repository.js'
 export {
   DEFAULT_RETRY_POLICY,
@@ -87,6 +99,7 @@ export {
 } from './retry.js'
 export {MAX_COMMIT_ITEM_BYTES, snapshotCommitSize, snapshotEventsDue} from './snapshots.js'
 export {compareUtf8, utf8Length} from './utf8.js'
+export {type CallerFence, StreamRead, Transaction, type TransactionResult} from './transaction.js'
 export {
   DEFAULT_SNAPSHOT_INTERVAL,
   type ExecuteOptions,

package/src/memory/repository.ts

@@ -7,6 +7,7 @@ import {
   ConflictError,
   CompactionUncoveredError,
   EvtError,
+  FenceConflictError,
   HistoryDependentProjectionError,
   RebuildInProgressError,
   SequenceGapError,
@@ -27,11 +28,17 @@ import type {Metadata} from '../metadata.js'
 import {
   type CallOptions,
   type Commit,
-  type Repository,
+  type NormalizedTransaction,
+  type ReadFence,
   type StoreInitializer,
+  type TransactionCommit,
+  type TransactionalRepository,
   checkBudget,
+  checkFenceRetention,
   checkNotReserved,
-  commitSizes,
+  normalizeTransaction,
+  rankFailures,
+  transactionSizes,
   validateCommit,
 } from '../repository.js'
 
@@ -75,7 +82,7 @@ let controlsOf: (repo: MemRepository) => Controls
  * on its feature manifest, so {@link initialize} is needed only where code treats every backend
  * alike.
  */
-export class MemRepository implements Repository, StoreInitializer {
+export class MemRepository implements TransactionalRepository, StoreInitializer {
   readonly #streams = new Map<string, Stream>()
   readonly #controls: Controls = {manifest: null, rebuild: {generation: 0n, lock: null}}
 
@@ -95,44 +102,80 @@ export class MemRepository implements Repository, StoreInitializer {
     options?.signal?.throwIfAborted()
     validateCommit(commit)
     checkNotReserved(commit.entityId)
-    if (commit.events.length === 0) {
-      return
+    if (commit.events.length > 0) {
+      this.#write(normalizeTransaction({streams: [commit]}))
     }
+  }
+
+  async commitTransaction(transaction: TransactionCommit, options?: CallOptions): Promise<void> {
+    options?.signal?.throwIfAborted()
+    const normalized = normalizeTransaction(transaction)
+    if (normalized.streams.length > 0 || normalized.fences.length > 0) {
+      this.#write(normalized)
+    }
+  }
 
+  // Writes a transaction, or refuses it with nothing written, in the order the live backends
+  // check: the budget, the marker and the fences' retention, the rebuild lock, then every stream
+  // and fence, ranked.
+  #write(transaction: NormalizedTransaction): void {
     // Every backend budgets a commit the same way, so an oversized one fails before any write.
-    checkBudget(commitSizes(commit, () => undefined))
+    checkBudget(transactionSizes(transaction, () => undefined))
 
     // The control rows come first, as the two checks that open every live commit: the marker,
     // then the rebuild lock, which an unsettled generation fails, a force-released one included.
     this.#checkManifest()
+    const retention = this.#controls.manifest?.retention ?? []
+    checkFenceRetention(transaction, (entityType) => retention.includes(entityType))
     const {rebuild} = this.#controls
     if (rebuild.lock !== null || rebuild.generation % 2n !== 0n) {
       throw new RebuildInProgressError()
     }
 
-    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),
+    const failures: EvtError[] = []
+    for (const stream of transaction.streams) {
+      const failure = checkWrite(stream, this.#streams.get(stream.entityId) ?? emptyStream())
+      if (failure !== null) {
+        failures.push(failure)
+      }
     }
-
-    for (const event of events) {
-      held.events.set(event.sequence, event)
+    for (const fence of transaction.fences) {
+      const failure = checkFence(fence, this.#streams.get(fence.entityId) ?? emptyStream())
+      if (failure !== null) {
+        failures.push(failure)
+      }
     }
-    held.head = held.head > last ? held.head : last
-    if (snapshot) {
-      held.snapshot = snapshot
+    const failure = rankFailures(failures)
+    if (failure !== undefined) {
+      throw failure
     }
 
-    this.#streams.set(commit.entityId, held)
+    // Copy everything before the first write, so a copy that throws leaves every stream as it was.
+    const writes = transaction.streams.map((commit) => {
+      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),
+      }
+
+      return {entityId: commit.entityId, events, last, snapshot}
+    })
+
+    for (const {entityId, events, last, snapshot} of writes) {
+      const held = this.#streams.get(entityId) ?? emptyStream()
+      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(entityId, held)
+    }
   }
 
   async events(entityId: string, options?: CallOptions): Promise<SerializedEvent[]> {
@@ -272,29 +315,47 @@ export class MemRepository implements Repository, StoreInitializer {
   }
 }
 
-// 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 {
+// The failure of a commit the stored stream doesn't accept, as the live backends' conditions find
+// it, or null. 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): EvtError | null {
   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)
+    return 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))
+    return 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(
+    return new ConflictError(
       commit.entityId,
       `snapshot sequence moved: stored ${stored}, commit writes ${snapshot.sequence}`,
     )
   }
+
+  return null
+}
+
+// The failure of a fence whose stream's head moved, or null: drift when the head disagrees with
+// the log, and otherwise a fence conflict.
+function checkFence(fence: ReadFence, held: Stream): EvtError | null {
+  if (held.head === fence.head) {
+    return null
+  }
+
+  const derived = derivedHead(held)
+  if (held.head !== derived) {
+    return drift(fence.entityId, held.head, derived)
+  }
+
+  return new FenceConflictError(fence.entityId, fence.head, fence.provenance)
 }
 
 // Classifies a failed head update the way the live backends' failure-path probe does: a stored

package/src/postgres/client.ts

@@ -0,0 +1,37 @@
+// The PostgreSQL client a PgRepository takes: a structural interface that `pg`'s Pool, Neon's
+// serverless Pool and PGlite satisfy without an adapter, so this package imports no driver.
+
+/** The result of one statement: its rows, as the driver returns them. */
+export interface PgResult {
+  readonly rows: readonly unknown[]
+}
+
+/** Something that runs one statement: `$1`, `$2` and so on in `text` take `values` in order. */
+export interface PgQueryable {
+  query(text: string, values?: unknown[]): Promise<PgResult>
+}
+
+/**
+ * A connection held for one transaction, as a pool lends it. `release` returns it to the pool, and
+ * gets the error when the connection may be unusable, so the pool can discard it.
+ */
+export interface PgConnection extends PgQueryable {
+  release(error?: Error): void
+}
+
+/**
+ * The client a {@link PgRepository} runs on.
+ *
+ * - A pool, such as `pg`'s `Pool` or Neon's serverless `Pool`, has `connect`, which lends one
+ *   connection for each transaction. Single statements outside a transaction go to `query`.
+ * - A single connection without `connect`, such as PGlite, runs everything itself, so every
+ *   repository on it runs one operation at a time on it. Nothing else may use the connection
+ *   meanwhile: a statement sent inside a repository's transaction would join it.
+ *
+ * Every value the repository sends is a string or null, with casts in the SQL, and every column it
+ * reads is text, so no driver's type parsing touches a stored value. A `pg` `Client` has a
+ * `connect` that opens the client rather than lending a connection, so pass a `Pool` instead.
+ */
+export interface PgClient extends PgQueryable {
+  connect?(): Promise<PgConnection>
+}

package/src/postgres/index.ts

@@ -0,0 +1,23 @@
+// @photon-grove/evt/postgres: the PostgreSQL backend. It imports no driver: the repository takes
+// `pg`'s Pool, or anything shaped like it, as a PgClient.
+
+export {type PgClient, type PgConnection, type PgQueryable, type PgResult} from './client.js'
+export {POSTGRES_BACKEND, PgRepository, type PgRepositoryOptions} from './repository.js'
+
+export {
+  DEFAULT_EVENTS_TABLE,
+  DEFAULT_SNAPSHOTS_TABLE,
+  MAX_EVENTS_TABLE_NAME_BYTES,
+  MAX_SNAPSHOTS_TABLE_NAME_BYTES,
+  type PgTables,
+  RESERVED_INFIX,
+  SCHEMA_LOCK,
+  entityTypeIndex,
+  featuresTable,
+  outcomesTable,
+  pgTables,
+  rebuildGenerationTable,
+  rebuildLockTable,
+  schemaDdl,
+  streamHeadsTable,
+} from './schema.js'