feat: brain.onChange — the in-process change feed for every committed mutation

Subscribe once and receive one post-commit event per affected record for
EVERY canonical write, regardless of origin: direct calls, batch methods,
transact(), imports, and Virtual Filesystem writes all funnel through the
same commit points the feed is emitted from. This is the authoritative
in-process signal for live UIs, cache invalidation, and realtime sync layers
that forward it over their own transports.

Architecture — the post-commit dual of the ifRev precommit hook: mutation
methods hand lightweight event descriptors to the commit seam
(persistSingleOp / transact's plan), which stamps the committed
{generation, timestamp}, enriches entity deletes with the record's LAST
committed state from the commit's own before-images (free — Model B reads
them anyway; removeMany's id-only deletes gain full payloads this way), and
emits only after the commit succeeds — a losing CAS or rejected batch never
announces anything. Dispatch is a microtask FIFO after the mutex releases:
commit-ordered, a slow listener never delays a write, a throwing listener is
logged and isolated, and with no subscribers the write path constructs no
events at all. Single-point emission was chosen over per-method hooks
because the aggregation-hook pattern demonstrably drifted (relation ops and
removeMany were silently missing from it).

Coverage: add/update/remove (+ cascade unrelate per deleted relationship),
relate (both edges when bidirectional)/unrelate/updateRelation, per-item
events for addMany/updateMany/relateMany/removeMany, per-item events sharing
one generation for transact(), and transitively imports + VFS. clear() and
restore() — wholesale raw-state operations outside the per-record commit
path — emit a single store-level event meaning "refetch everything".
brain.close() drops all listeners.

New module src/events/changeFeed.ts (BrainyChangeEvent + ChangeFeed,
exported from the package root); guide docs/guides/reacting-to-changes.md.
Integration suite pins the contract: per-op payload fidelity, delete
last-state payloads, batch per-item emission, one-generation transact
batches, VFS-origin events, CAS-loser silence, ordering, listener isolation,
unsubscribe, and store-level events.

src/events/changeFeed.ts

@@ -0,0 +1,171 @@
+/**
+ * @module events/changeFeed
+ * @description The in-process change feed behind {@link Brainy.onChange} — the
+ * authoritative "something committed" signal for every canonical mutation,
+ * regardless of origin (direct API calls, batches, transactions, imports, the
+ * VFS, or an accelerated native deployment: all of them funnel through the
+ * same generation-store commit points this feed is emitted from).
+ *
+ * Design properties:
+ * - **Post-commit only.** Events are enqueued after the commit succeeds, so an
+ *   aborted commit (a losing `ifRev` CAS, a failed transaction) never emits.
+ * - **Commit-ordered.** Events are enqueued in commit order and dispatched
+ *   FIFO, so a subscriber observes mutations in the order they became durable.
+ * - **Never blocks the write path.** Dispatch happens in a microtask after the
+ *   committing call returns; a slow or throwing listener cannot delay or fail
+ *   a write. Listener errors are isolated per listener and per event.
+ * - **Zero cost when unused.** Callers consult {@link ChangeFeed.hasListeners}
+ *   before constructing event payloads; with no subscribers the write path
+ *   does no event work at all.
+ * - **Fire-and-forget.** No acknowledgement, backpressure, or replay. Events
+ *   carry the committed `generation`, so a consumer that needs catch-up
+ *   semantics can pair the live feed with `transactionLog()` / `asOf()`.
+ */
+
+/** The post-commit view of an entity carried by entity change events. */
+export interface ChangeEventEntity {
+  /** The entity's canonical UUID. */
+  id: string
+  /** The entity's NounType string (e.g. `'person'`, `'document'`). */
+  type: string
+  /** The entity's subtype, when set. */
+  subtype?: string
+  /** The entity's custom (indexed) metadata fields. */
+  metadata: Record<string, unknown>
+  /** The writing service, when set. */
+  service?: string
+}
+
+/** The post-commit view of a relationship carried by relation change events. */
+export interface ChangeEventRelation {
+  /** The relationship's canonical UUID. */
+  id: string
+  /** Source entity UUID. */
+  from: string
+  /** Target entity UUID. */
+  to: string
+  /** The relationship's VerbType string (e.g. `'contains'`). */
+  type: string
+  /** The relationship's custom metadata fields, when present. */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * One committed mutation, as delivered to {@link Brainy.onChange} listeners.
+ *
+ * Exactly one of `entity` / `relation` is populated for `kind: 'entity'` /
+ * `kind: 'relation'` events. `kind: 'store'` events (`clear` / `restore`)
+ * carry neither — they mean "the whole store changed; refetch what you care
+ * about".
+ *
+ * For `op: 'remove'` / `op: 'unrelate'` the payload is the record's LAST
+ * committed state (sourced from the commit's own before-image), so deletes are
+ * fully described rather than id-only.
+ */
+export interface BrainyChangeEvent {
+  /** What changed: one record, one relationship, or the whole store. */
+  kind: 'entity' | 'relation' | 'store'
+  /** The mutation, in Brainy's own API vocabulary. */
+  op:
+    | 'add'
+    | 'update'
+    | 'remove'
+    | 'relate'
+    | 'unrelate'
+    | 'updateRelation'
+    | 'clear'
+    | 'restore'
+  /** The mutated record's id (absent for store-level events). */
+  id?: string
+  /** Post-commit entity view (entity events only). */
+  entity?: ChangeEventEntity
+  /** Post-commit relation view (relation events only). */
+  relation?: ChangeEventRelation
+  /**
+   * The committed generation this mutation belongs to (Model B: every write
+   * is a generation; a transaction's items share one). Absent for store-level
+   * events and init-time bootstrap writes, which are not generation-stamped.
+   */
+  generation?: number
+  /** Commit timestamp (ms since epoch). */
+  timestamp: number
+}
+
+/** Listener signature for {@link Brainy.onChange}. */
+export type ChangeListener = (event: BrainyChangeEvent) => void
+
+/**
+ * A change event as constructed by a mutation method BEFORE its commit: the
+ * commit seam stamps `generation`/`timestamp` after the write becomes
+ * durable. An entity `remove` descriptor may omit `entity` — the seam fills
+ * it from the commit's own before-image (the record's last committed state).
+ */
+export type PendingChangeEvent = Omit<BrainyChangeEvent, 'generation' | 'timestamp'>
+
+/**
+ * @description Listener registry + commit-ordered async dispatcher for
+ * {@link BrainyChangeEvent}s. One instance per {@link Brainy}.
+ */
+export class ChangeFeed {
+  private listeners = new Set<ChangeListener>()
+  private queue: BrainyChangeEvent[] = []
+  private draining = false
+
+  /** Whether any listener is subscribed — the write path's zero-cost gate. */
+  get hasListeners(): boolean {
+    return this.listeners.size > 0
+  }
+
+  /**
+   * @description Subscribe to committed mutations.
+   * @param listener - Called once per committed mutation, in commit order.
+   * @returns An unsubscribe function.
+   */
+  subscribe(listener: ChangeListener): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  /**
+   * @description Enqueue committed events and schedule dispatch. Call ONLY
+   * after the commit has succeeded — this feed must never announce a write
+   * that did not become durable. Safe to call with an empty array.
+   * @param events - The committed mutations, in commit order.
+   */
+  emit(events: BrainyChangeEvent[]): void {
+    if (events.length === 0 || this.listeners.size === 0) return
+    this.queue.push(...events)
+    if (!this.draining) {
+      this.draining = true
+      queueMicrotask(() => this.drain())
+    }
+  }
+
+  /** Deliver everything queued, FIFO, isolating listener errors. */
+  private drain(): void {
+    try {
+      while (this.queue.length > 0) {
+        const event = this.queue.shift()!
+        for (const listener of this.listeners) {
+          try {
+            listener(event)
+          } catch (err) {
+            // A subscriber's bug must never affect the write path or its
+            // sibling subscribers.
+            console.error('[Brainy] onChange listener threw:', err)
+          }
+        }
+      }
+    } finally {
+      this.draining = false
+    }
+  }
+
+  /** Drop all listeners (brain close/teardown). Queued events are discarded. */
+  close(): void {
+    this.listeners.clear()
+    this.queue.length = 0
+  }
+}