@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/history/history-service.ts

@@ -0,0 +1,904 @@
+import { PersistenceCoordinator } from './persistence-coordinator';
+import { ResourceRegistry } from './resource-registry';
+import { SnapshotStore } from './snapshot-store';
+import type {
+  HistoryError,
+  HistoryStatus,
+  HistoryTransaction,
+  ResourceChange,
+  ResourceDriver,
+  ResourceKey,
+  ResourceSnapshot,
+  SnapshotRef,
+} from './types';
+
+const DEFAULT_MAX_TRANSACTIONS = 200;
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+const DEFAULT_MAX_TRANSACTION_BYTES = 16 * 1024 * 1024;
+
+export interface HistoryLimits {
+  readonly maxTransactions: number;
+  readonly maxBytes: number;
+  readonly maxTransactionBytes: number;
+}
+
+export interface TransactionOptions {
+  readonly label: string;
+  readonly detail?: string;
+  readonly resources: readonly ResourceKey[];
+  readonly scope: 'project' | 'session';
+  readonly sessionId?: string;
+  readonly mergeKey?: string;
+}
+
+export interface HistoryTransactionContext {
+  read(resource: ResourceKey): Promise<ResourceSnapshot>;
+  write(resource: ResourceKey, bytes: Uint8Array, contentType?: string): Promise<void>;
+  writeText(resource: ResourceKey, text: string, contentType?: string): Promise<void>;
+  writeJson(resource: ResourceKey, value: unknown): Promise<void>;
+}
+
+export interface AppliedResourceChange {
+  readonly resource: ResourceKey;
+  readonly beforeBytes: Uint8Array;
+  readonly afterBytes: Uint8Array;
+  readonly contentType: string;
+}
+
+export interface HistorySnapshot {
+  readonly version: number;
+  readonly transactions: readonly HistoryTransaction[];
+  readonly cursor: number;
+  readonly busy: boolean;
+  readonly blocked: boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly undoLabel: string | null;
+  readonly redoLabel: string | null;
+  readonly uniqueSnapshotBytes: number;
+  readonly lastError: HistoryError | null;
+}
+
+export interface HistoryServiceOptions {
+  readonly registry?: ResourceRegistry;
+  readonly snapshots?: SnapshotStore;
+  readonly persistence?: PersistenceCoordinator;
+  readonly limits?: Partial<HistoryLimits>;
+  readonly makeId?: () => string;
+  readonly now?: () => number;
+}
+
+interface StagedResource {
+  readonly driver: ResourceDriver;
+  readonly beforeSnapshot: ResourceSnapshot;
+  readonly before: SnapshotRef;
+  afterBytes: Uint8Array;
+  afterContentType: string;
+  beforeOwned: boolean;
+}
+
+interface MutableTransaction extends Omit<HistoryTransaction, 'status' | 'error'> {
+  status: HistoryStatus;
+  error: HistoryError | null;
+}
+
+export class HistoryOperationError extends Error {
+  constructor(readonly historyError: HistoryError) {
+    super(historyError.message);
+    this.name = 'HistoryOperationError';
+  }
+}
+
+function defaultId(): string {
+  return crypto.randomUUID();
+}
+
+function historyError(
+  code: HistoryError['code'],
+  message: string,
+  resources: readonly ResourceKey[],
+  cause?: unknown,
+): HistoryError {
+  const error: HistoryError = { code, message, resources };
+  return cause === undefined ? error : { ...error, cause };
+}
+
+function transactionBytes(changes: readonly ResourceChange[]): number {
+  const blobs = new Map<string, number>();
+  for (const change of changes) {
+    blobs.set(change.before.blobKey, change.before.byteLength);
+    blobs.set(change.after.blobKey, change.after.byteLength);
+  }
+  let total = 0;
+  for (const length of blobs.values()) total += length;
+  return total;
+}
+
+/** One authoritative, async undo/redo timeline for an open project session. */
+export class HistoryService {
+  readonly registry: ResourceRegistry;
+  readonly snapshots: SnapshotStore;
+  readonly persistence: PersistenceCoordinator;
+  readonly limits: HistoryLimits;
+
+  private readonly drivers = new Map<ResourceKey, ResourceDriver>();
+  private readonly listeners = new Set<() => void>();
+  private readonly commitListeners = new Set<(transaction: HistoryTransaction) => void>();
+  private readonly makeId: () => string;
+  private readonly now: () => number;
+  private entries: MutableTransaction[] = [];
+  private cursorValue = 0;
+  private version = 0;
+  private pendingExecutions = 0;
+  private pendingProducers = 0;
+  private activeTransaction = false;
+  private disposeRequested = false;
+  private disposeComplete = false;
+  private blockedValue = false;
+  private lastErrorValue: HistoryError | null = null;
+  private executionTail: Promise<void> = Promise.resolve();
+  private publicSnapshot: HistorySnapshot;
+
+  constructor(options: HistoryServiceOptions = {}) {
+    this.registry = options.registry ?? new ResourceRegistry();
+    this.snapshots = options.snapshots ?? new SnapshotStore();
+    this.persistence = options.persistence ?? new PersistenceCoordinator();
+    this.makeId = options.makeId ?? defaultId;
+    this.now = options.now ?? Date.now;
+    this.limits = {
+      maxTransactions: options.limits?.maxTransactions ?? DEFAULT_MAX_TRANSACTIONS,
+      maxBytes: options.limits?.maxBytes ?? DEFAULT_MAX_BYTES,
+      maxTransactionBytes: options.limits?.maxTransactionBytes ?? DEFAULT_MAX_TRANSACTION_BYTES,
+    };
+    if (
+      this.limits.maxTransactions < 1 ||
+      this.limits.maxBytes < 1 ||
+      this.limits.maxTransactionBytes < 1 ||
+      this.limits.maxTransactionBytes > this.limits.maxBytes
+    ) {
+      throw new Error('History limits must be positive.');
+    }
+    this.publicSnapshot = this.buildSnapshot();
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    if (this.disposeRequested) return () => undefined;
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  getSnapshot = (): HistorySnapshot => this.publicSnapshot;
+
+  subscribeCommits(listener: (transaction: HistoryTransaction) => void): () => void {
+    this.assertNotDisposed();
+    this.commitListeners.add(listener);
+    return () => this.commitListeners.delete(listener);
+  }
+
+  /** Reserves shell ordering while an async producer prepares a transaction. */
+  reserveProducer(): () => void {
+    this.assertNotDisposed();
+    this.pendingProducers++;
+    this.notify();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.pendingProducers--;
+      this.finishDisposeIfIdle();
+      if (!this.disposeComplete) this.notify();
+    };
+  }
+
+  registerDriver(driver: ResourceDriver): () => void {
+    this.assertNotDisposed();
+    const key = driver.descriptor.key;
+    const registered = this.registry.get(key);
+    if (!registered) throw new Error(`Driver resource "${key}" is not registered.`);
+    if (this.drivers.has(key)) throw new Error(`Resource "${key}" already has a driver.`);
+    this.drivers.set(key, driver);
+    return () => {
+      if (this.drivers.get(key) === driver) this.drivers.delete(key);
+    };
+  }
+
+  transaction<T>(
+    options: TransactionOptions,
+    operation: (tx: HistoryTransactionContext) => Promise<T> | T,
+  ): Promise<T> {
+    this.validateOptions(options);
+    if (this.activeTransaction) {
+      return Promise.reject(
+        new HistoryOperationError(
+          historyError('busy', 'A history transaction cannot nest another transaction.', []),
+        ),
+      );
+    }
+    return this.enqueue(() => this.transactionNow(options, operation));
+  }
+
+  private async transactionNow<T>(
+    options: TransactionOptions,
+    operation: (tx: HistoryTransactionContext) => Promise<T> | T,
+  ): Promise<T> {
+    this.assertCanStartTransaction();
+
+    this.activeTransaction = true;
+    this.notify();
+    const allowed = new Set(options.resources);
+    const staged = new Map<ResourceKey, StagedResource>();
+    const ensureStaged = async (resource: ResourceKey): Promise<StagedResource> => {
+      if (!allowed.has(resource)) {
+        throw new Error(`Transaction did not declare resource "${resource}".`);
+      }
+      const existing = staged.get(resource);
+      if (existing) return existing;
+      const driver = this.requireDriver(resource);
+      this.validateResourceScope(driver, options);
+      const beforeSnapshot = await driver.capture();
+      const before = await this.storeCapturedSnapshot(beforeSnapshot);
+      const state: StagedResource = {
+        driver,
+        beforeSnapshot,
+        before,
+        afterBytes: Uint8Array.from(beforeSnapshot.bytes),
+        afterContentType: beforeSnapshot.contentType,
+        beforeOwned: true,
+      };
+      staged.set(resource, state);
+      return state;
+    };
+
+    const context: HistoryTransactionContext = {
+      read: async (resource) => {
+        const state = await ensureStaged(resource);
+        return {
+          revision: state.beforeSnapshot.revision,
+          contentType: state.afterContentType,
+          bytes: Uint8Array.from(state.afterBytes),
+          sha256: state.beforeSnapshot.sha256,
+        };
+      },
+      write: async (resource, bytes, contentType) => {
+        const state = await ensureStaged(resource);
+        state.afterBytes = Uint8Array.from(bytes);
+        state.afterContentType = contentType ?? state.afterContentType;
+      },
+      writeText: async (resource, text, contentType = 'text/plain') => {
+        await context.write(resource, new TextEncoder().encode(text), contentType);
+      },
+      writeJson: async (resource, value) => {
+        await context.writeText(resource, JSON.stringify(value, null, 2), 'application/json');
+      },
+    };
+
+    try {
+      const result = await operation(context);
+      const changes = await this.finishStaging(staged);
+      if (changes.length === 0) return result;
+      await this.commitStagedTransaction(options, changes);
+      return result;
+    } finally {
+      // Any before refs left in a staging map with no matching committed change
+      // are released by finishStaging. If the callback throws before that point,
+      // release them here.
+      for (const state of staged.values()) {
+        if (state.beforeOwned) this.snapshots.release(state.before);
+      }
+      this.activeTransaction = false;
+      this.finishDisposeIfIdle();
+      if (!this.disposeComplete) this.notify();
+    }
+  }
+
+  undo(): Promise<boolean> {
+    return this.enqueue(() => this.undoNow());
+  }
+
+  redo(): Promise<boolean> {
+    return this.enqueue(() => this.redoNow());
+  }
+
+  /**
+   * Journals an editor mutation whose exact before/after bytes were captured in
+   * the same synchronous UI turn. The command queue is shared with undo/redo, so
+   * an immediate shortcut always runs after this entry becomes authoritative.
+   */
+  recordAppliedTransaction(
+    options: TransactionOptions,
+    applied: readonly AppliedResourceChange[],
+  ): Promise<boolean> {
+    this.assertCanRecordAppliedChange();
+    this.validateOptions(options);
+    if (applied.length === 0) return Promise.resolve(false);
+    const declared = new Set(options.resources);
+    if (
+      applied.length !== declared.size ||
+      applied.some((change) => !declared.has(change.resource))
+    ) {
+      return Promise.reject(
+        new Error('Applied history changes must exactly match declared resources.'),
+      );
+    }
+    // Resolve drivers before queueing. A synchronous document switch may retire
+    // the resource before this journal task runs, but the already-applied edit
+    // must still be recorded (as expired), never rejected or retargeted.
+    for (const change of applied) {
+      const driver = this.requireDriver(change.resource);
+      this.validateResourceScope(driver, options);
+    }
+    return this.enqueue(async () => {
+      this.assertCanRecordAppliedChange();
+      const changes: ResourceChange[] = [];
+      try {
+        for (const change of applied) {
+          const before = await this.snapshots.put({
+            revision: 0,
+            contentType: change.contentType,
+            bytes: change.beforeBytes,
+          });
+          const after = await this.snapshots.put({
+            revision: 1,
+            contentType: change.contentType,
+            bytes: change.afterBytes,
+          });
+          if (before.sha256 === after.sha256) {
+            this.snapshots.release(before);
+            this.snapshots.release(after);
+            continue;
+          }
+          changes.push({ resource: change.resource, before, after });
+        }
+        if (changes.length === 0) return false;
+        this.appendAppliedTransaction(options, changes);
+        return true;
+      } catch (error) {
+        this.releaseChanges(changes);
+        this.lastErrorValue =
+          error instanceof HistoryOperationError
+            ? error.historyError
+            : historyError(
+                'apply-failed',
+                `Failed to journal “${options.label.trim()}”.`,
+                applied.map((change) => change.resource),
+                error,
+              );
+        this.notify();
+        throw error;
+      }
+    });
+  }
+
+  /** Preflight for producers that mutate state before journaling it. */
+  assertCanRecordAppliedChange(): void {
+    this.assertNotDisposed();
+    if (this.blockedValue) {
+      if (this.lastErrorValue?.code === 'compensation-failed') {
+        throw new HistoryOperationError(this.lastErrorValue);
+      }
+      throw new HistoryOperationError(
+        historyError('compensation-failed', 'History is blocked pending recovery.', []),
+      );
+    }
+  }
+
+  /** Surface a recovered producer failure without blocking later safe edits. */
+  reportAppliedChangeFailure(
+    label: string,
+    resources: readonly ResourceKey[],
+    cause: unknown,
+  ): void {
+    if (this.blockedValue) return;
+    this.lastErrorValue = historyError(
+      'apply-failed',
+      `Failed to apply “${label.trim()}”; prior state was restored.`,
+      resources,
+      cause,
+    );
+    this.notify();
+  }
+
+  /**
+   * Permanently blocks history after an already-applied producer could not
+   * restore exact prior bytes. Producers outside HistoryService's own apply
+   * loop use this to surface the same loud recovery state as undo/redo.
+   */
+  blockForCompensationFailure(
+    label: string,
+    resources: readonly ResourceKey[],
+    cause: unknown,
+  ): HistoryOperationError {
+    if (this.blockedValue && this.lastErrorValue?.code === 'compensation-failed') {
+      return new HistoryOperationError(this.lastErrorValue);
+    }
+    const problem = historyError(
+      'compensation-failed',
+      `History recovery failed while applying “${label.trim()}”.`,
+      resources,
+      cause,
+    );
+    this.blockedValue = true;
+    this.lastErrorValue = problem;
+    this.notify();
+    return new HistoryOperationError(problem);
+  }
+
+  jumpTo(cursor: number): Promise<boolean> {
+    if (!Number.isInteger(cursor) || cursor < 0 || cursor > this.entries.length) {
+      return Promise.reject(new Error(`History cursor ${cursor} is out of range.`));
+    }
+    return this.enqueue(async () => {
+      while (this.cursorValue > cursor) {
+        if (!(await this.undoNow())) return false;
+      }
+      while (this.cursorValue < cursor) {
+        if (!(await this.redoNow())) return false;
+      }
+      return true;
+    });
+  }
+
+  expireSession(sessionId: string): void {
+    this.assertNotDisposed();
+    const resources = new Set(this.registry.expireSession(sessionId));
+    if (resources.size === 0) return;
+    this.entries = this.entries.map((entry) =>
+      entry.sessionId === sessionId ||
+      entry.changes.some((change) => resources.has(change.resource))
+        ? { ...entry, status: 'expired', error: null }
+        : entry,
+    );
+    this.notify();
+  }
+
+  expireResources(resources: Iterable<ResourceKey>): void {
+    this.assertNotDisposed();
+    const expired = new Set(this.registry.expireResources(resources));
+    if (expired.size === 0) return;
+    this.entries = this.entries.map((entry) =>
+      entry.changes.some((change) => expired.has(change.resource))
+        ? { ...entry, status: 'expired', error: null }
+        : entry,
+    );
+    this.notify();
+  }
+
+  dispose(): void {
+    if (this.disposeRequested) return;
+    this.disposeRequested = true;
+    this.listeners.clear();
+    this.commitListeners.clear();
+    this.finishDisposeIfIdle();
+  }
+
+  private finishDisposeIfIdle(): void {
+    if (
+      !this.disposeRequested ||
+      this.disposeComplete ||
+      this.activeTransaction ||
+      this.pendingExecutions > 0 ||
+      this.pendingProducers > 0
+    ) {
+      return;
+    }
+    for (const entry of this.entries) this.releaseChanges(entry.changes);
+    this.entries = [];
+    this.cursorValue = 0;
+    this.drivers.clear();
+    this.registry.clear();
+    this.snapshots.clear();
+    this.blockedValue = false;
+    this.lastErrorValue = null;
+    this.disposeComplete = true;
+    this.notify();
+  }
+
+  private async finishStaging(staged: Map<ResourceKey, StagedResource>): Promise<ResourceChange[]> {
+    const changes: ResourceChange[] = [];
+    try {
+      for (const [resource, state] of staged) {
+        const after = await this.snapshots.put({
+          revision: state.beforeSnapshot.revision + 1,
+          contentType: state.afterContentType,
+          bytes: state.afterBytes,
+        });
+        if (after.sha256 === state.before.sha256) {
+          this.snapshots.release(after);
+          this.snapshots.release(state.before);
+          state.beforeOwned = false;
+          continue;
+        }
+        changes.push({ resource, before: state.before, after });
+        state.beforeOwned = false;
+      }
+      return changes;
+    } catch (error) {
+      this.releaseChanges(changes);
+      throw error;
+    }
+  }
+
+  private async commitStagedTransaction(
+    options: TransactionOptions,
+    changes: readonly ResourceChange[],
+  ): Promise<void> {
+    const byteSize = transactionBytes(changes);
+    if (byteSize > this.limits.maxTransactionBytes) {
+      this.releaseChanges(changes);
+      throw new HistoryOperationError(
+        historyError(
+          'history-limit',
+          `Transaction requires ${byteSize} bytes; the limit is ${this.limits.maxTransactionBytes}.`,
+          changes.map((change) => change.resource),
+        ),
+      );
+    }
+
+    const transaction: MutableTransaction = {
+      id: this.makeId(),
+      label: options.label.trim(),
+      detail: options.detail?.trim() || null,
+      timestamp: this.now(),
+      scope: options.scope,
+      sessionId: options.scope === 'session' ? options.sessionId! : null,
+      changes,
+      byteSize,
+      mergeKey: options.mergeKey?.trim() || null,
+      status: 'committed',
+      error: null,
+    };
+
+    try {
+      this.assertCanRecordAppliedChange();
+      await this.persistence.runMany(
+        changes.map((change) => change.resource),
+        async () => {
+          this.assertCanRecordAppliedChange();
+          await this.preflight(transaction, 'redo');
+          await this.applyWithCompensation(transaction, 'redo');
+        },
+      );
+    } catch (error) {
+      const problem =
+        error instanceof HistoryOperationError
+          ? error.historyError
+          : historyError(
+              'apply-failed',
+              `Failed to commit “${transaction.label}”.`,
+              changes.map((change) => change.resource),
+              error,
+            );
+      this.lastErrorValue = problem;
+      if (problem.code === 'compensation-failed') this.blockedValue = true;
+      this.releaseChanges(changes);
+      this.notify();
+      throw error;
+    }
+
+    this.truncateRedo();
+    this.entries.push(transaction);
+    this.cursorValue = this.entries.length;
+    if (!this.blockedValue) this.lastErrorValue = null;
+    this.trimToLimits();
+    this.notify();
+    for (const listener of this.commitListeners) listener(transaction);
+  }
+
+  private appendAppliedTransaction(
+    options: TransactionOptions,
+    changes: readonly ResourceChange[],
+  ): void {
+    const byteSize = transactionBytes(changes);
+    if (byteSize > this.limits.maxTransactionBytes) {
+      this.releaseChanges(changes);
+      throw new HistoryOperationError(
+        historyError(
+          'history-limit',
+          `Transaction requires ${byteSize} bytes; the limit is ${this.limits.maxTransactionBytes}.`,
+          changes.map((change) => change.resource),
+        ),
+      );
+    }
+    const transaction: MutableTransaction = {
+      id: this.makeId(),
+      label: options.label.trim(),
+      detail: options.detail?.trim() || null,
+      timestamp: this.now(),
+      scope: options.scope,
+      sessionId: options.scope === 'session' ? options.sessionId! : null,
+      changes,
+      byteSize,
+      mergeKey: options.mergeKey?.trim() || null,
+      status: changes.every((change) => this.registry.isActive(change.resource))
+        ? 'committed'
+        : 'expired',
+      error: null,
+    };
+    this.truncateRedo();
+    this.entries.push(transaction);
+    this.cursorValue = this.entries.length;
+    if (!this.blockedValue) this.lastErrorValue = null;
+    this.trimToLimits();
+    this.notify();
+    for (const listener of this.commitListeners) listener(transaction);
+  }
+
+  private async undoNow(): Promise<boolean> {
+    if (this.cursorValue === 0 || this.blockedValue) return false;
+    const transaction = this.entries[this.cursorValue - 1]!;
+    if (transaction.status === 'expired') {
+      const error = historyError(
+        'expired',
+        `“${transaction.label}” belongs to an expired session.`,
+        [],
+      );
+      transaction.error = error;
+      this.lastErrorValue = error;
+      this.notify();
+      return false;
+    }
+    return this.executeExisting(transaction, 'undo');
+  }
+
+  private async redoNow(): Promise<boolean> {
+    if (this.cursorValue >= this.entries.length || this.blockedValue) return false;
+    const transaction = this.entries[this.cursorValue]!;
+    if (transaction.status === 'expired') {
+      const error = historyError(
+        'expired',
+        `“${transaction.label}” belongs to an expired session.`,
+        [],
+      );
+      transaction.error = error;
+      this.lastErrorValue = error;
+      this.notify();
+      return false;
+    }
+    return this.executeExisting(transaction, 'redo');
+  }
+
+  private async executeExisting(
+    transaction: MutableTransaction,
+    direction: 'undo' | 'redo',
+  ): Promise<boolean> {
+    const resources = transaction.changes.map((change) => change.resource);
+    try {
+      await this.persistence.runMany(resources, async () => {
+        await this.preflight(transaction, direction);
+        transaction.status = direction === 'undo' ? 'undoing' : 'redoing';
+        transaction.error = null;
+        this.notify();
+        await this.applyWithCompensation(transaction, direction);
+      });
+      if (direction === 'undo') {
+        this.cursorValue--;
+        transaction.status = 'undone';
+      } else {
+        this.cursorValue++;
+        transaction.status = 'committed';
+      }
+      transaction.error = null;
+      this.lastErrorValue = null;
+      this.notify();
+      return true;
+    } catch (error) {
+      const problem =
+        error instanceof HistoryOperationError
+          ? error.historyError
+          : historyError(
+              'apply-failed',
+              `Failed to ${direction} “${transaction.label}”.`,
+              resources,
+              error,
+            );
+      transaction.error = problem;
+      transaction.status = problem.code === 'compensation-failed' ? 'failed-partial' : 'failed';
+      this.lastErrorValue = problem;
+      if (problem.code === 'compensation-failed') this.blockedValue = true;
+      this.notify();
+      return false;
+    }
+  }
+
+  private async preflight(
+    transaction: MutableTransaction,
+    direction: 'undo' | 'redo',
+  ): Promise<void> {
+    for (const change of transaction.changes) {
+      if (!this.registry.isActive(change.resource)) {
+        throw new HistoryOperationError(
+          historyError('expired', `Resource "${change.resource}" is unavailable.`, [
+            change.resource,
+          ]),
+        );
+      }
+      const expected = direction === 'undo' ? change.after : change.before;
+      const result = await this.requireDriver(change.resource).preflight(expected);
+      if (!result.ok) {
+        throw new HistoryOperationError(
+          historyError(
+            result.reason === 'expired' ? 'expired' : 'conflict',
+            `Resource "${change.resource}" no longer matches “${transaction.label}”.`,
+            [change.resource],
+          ),
+        );
+      }
+    }
+  }
+
+  private async applyWithCompensation(
+    transaction: MutableTransaction,
+    direction: 'undo' | 'redo',
+  ): Promise<void> {
+    const ordered =
+      direction === 'undo' ? [...transaction.changes].reverse() : [...transaction.changes];
+    const applied: ResourceChange[] = [];
+    try {
+      for (const change of ordered) {
+        const target = direction === 'undo' ? change.before : change.after;
+        await this.requireDriver(change.resource).restore(target);
+        applied.push(change);
+      }
+    } catch (applyError) {
+      try {
+        for (const change of [...applied].reverse()) {
+          const compensation = direction === 'undo' ? change.after : change.before;
+          await this.requireDriver(change.resource).restore(compensation);
+        }
+      } catch (compensationError) {
+        throw new HistoryOperationError(
+          historyError(
+            'compensation-failed',
+            `History recovery failed while applying “${transaction.label}”.`,
+            transaction.changes.map((change) => change.resource),
+            { applyError, compensationError },
+          ),
+        );
+      }
+      throw new HistoryOperationError(
+        historyError(
+          'apply-failed',
+          `Failed to apply “${transaction.label}”; prior state was restored.`,
+          transaction.changes.map((change) => change.resource),
+          applyError,
+        ),
+      );
+    }
+  }
+
+  private enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.disposeRequested) return Promise.reject(new Error('History service is disposed.'));
+    this.pendingExecutions++;
+    this.notify();
+    const run = () => {
+      this.assertNotDisposed();
+      return operation();
+    };
+    const result = this.executionTail.then(run, run);
+    this.executionTail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result.finally(() => {
+      this.pendingExecutions--;
+      this.finishDisposeIfIdle();
+      if (!this.disposeComplete) this.notify();
+    });
+  }
+
+  private async storeCapturedSnapshot(snapshot: ResourceSnapshot): Promise<SnapshotRef> {
+    const ref = await this.snapshots.put({
+      revision: snapshot.revision,
+      contentType: snapshot.contentType,
+      bytes: snapshot.bytes,
+    });
+    if (ref.sha256 !== snapshot.sha256) {
+      this.snapshots.release(ref);
+      throw new Error('Resource driver returned bytes that do not match its SHA-256.');
+    }
+    return ref;
+  }
+
+  private truncateRedo(): void {
+    if (this.cursorValue === this.entries.length) return;
+    for (const entry of this.entries.slice(this.cursorValue)) this.releaseChanges(entry.changes);
+    this.entries = this.entries.slice(0, this.cursorValue);
+  }
+
+  private trimToLimits(): void {
+    while (
+      this.entries.length > 1 &&
+      (this.entries.length > this.limits.maxTransactions ||
+        this.snapshots.uniqueByteLength > this.limits.maxBytes)
+    ) {
+      const [oldest, ...rest] = this.entries;
+      this.entries = rest;
+      this.releaseChanges(oldest!.changes);
+      this.cursorValue = Math.max(0, this.cursorValue - 1);
+    }
+  }
+
+  private releaseChanges(changes: readonly ResourceChange[]): void {
+    for (const change of changes) {
+      if (this.snapshots.has(change.before)) this.snapshots.release(change.before);
+      if (this.snapshots.has(change.after)) this.snapshots.release(change.after);
+    }
+  }
+
+  private requireDriver(resource: ResourceKey): ResourceDriver {
+    const driver = this.drivers.get(resource);
+    if (!driver) throw new Error(`No history resource driver is registered for "${resource}".`);
+    return driver;
+  }
+
+  private validateOptions(options: TransactionOptions): void {
+    if (!options.label.trim()) throw new Error('History transaction label cannot be empty.');
+    if (options.resources.length === 0) throw new Error('History transaction needs a resource.');
+    if (new Set(options.resources).size !== options.resources.length) {
+      throw new Error('History transaction resources must be unique.');
+    }
+    if (options.scope === 'session' && !options.sessionId?.trim()) {
+      throw new Error('A session transaction requires a session id.');
+    }
+    if (options.scope === 'project' && options.sessionId !== undefined) {
+      throw new Error('A project transaction cannot have a session id.');
+    }
+  }
+
+  private assertCanStartTransaction(): void {
+    this.assertNotDisposed();
+    if (this.blockedValue) {
+      throw new HistoryOperationError(
+        historyError('compensation-failed', 'History is blocked pending recovery.', []),
+      );
+    }
+    if (this.activeTransaction) {
+      throw new HistoryOperationError(
+        historyError('busy', 'Another history operation is already in progress.', []),
+      );
+    }
+  }
+
+  private assertNotDisposed(): void {
+    if (this.disposeRequested) throw new Error('History service is disposed.');
+  }
+
+  private validateResourceScope(driver: ResourceDriver, options: TransactionOptions): void {
+    const descriptor = driver.descriptor;
+    if (descriptor.scope !== options.scope) {
+      throw new Error(`Resource "${descriptor.key}" does not match transaction scope.`);
+    }
+    if (options.scope === 'session' && descriptor.sessionId !== options.sessionId) {
+      throw new Error(`Resource "${descriptor.key}" belongs to another session.`);
+    }
+  }
+
+  private notify(): void {
+    this.version++;
+    this.publicSnapshot = this.buildSnapshot();
+    for (const listener of this.listeners) listener();
+  }
+
+  private buildSnapshot(): HistorySnapshot {
+    const undo = this.cursorValue > 0 ? this.entries[this.cursorValue - 1]! : null;
+    const redo = this.cursorValue < this.entries.length ? this.entries[this.cursorValue]! : null;
+    const idle =
+      this.pendingExecutions === 0 && this.pendingProducers === 0 && !this.activeTransaction;
+    return {
+      version: this.version,
+      transactions: this.entries.map((entry) => ({
+        ...entry,
+        changes: entry.changes.map((change) => ({ ...change })),
+      })),
+      cursor: this.cursorValue,
+      busy: !idle,
+      blocked: this.blockedValue,
+      canUndo: idle && !!undo && undo.status !== 'expired' && !this.blockedValue,
+      canRedo: idle && !!redo && redo.status !== 'expired' && !this.blockedValue,
+      undoLabel: undo?.label ?? null,
+      redoLabel: redo?.label ?? null,
+      uniqueSnapshotBytes: this.snapshots.uniqueByteLength,
+      lastError: this.lastErrorValue,
+    };
+  }
+}