@ultimat3/entity 30.9.0 → 31.0.0

package/src/row-observer.ts

@@ -1,5 +1,6 @@
-// Committed row changes, as the framework's own repositories saw them. One seam, above the driver,
-// so it reports the same changes whether rows live in memory or in Postgres.
+// Committed row changes, as the framework's own repositories saw them, emitted on the bus as
+// `entity.row` / `entity.bulk`. One emitter, above the driver, so it reports the same changes
+// whether rows live in memory or in Postgres.
 //
 // It exists because a change feed needs a source and only one of the two has one. Production
 // decodes the write-ahead log (`@ultimat3/realtime`'s `postgresChangeFeed()`); PGlite has no
@@ -13,80 +14,35 @@
 // the replicator — `@ultimat3/realtime`'s `selectChangeFeed` still decides, and this is never in
 // that decision.
 
-import { currentWriteOrigin } from '@ultimat3/core';
-import { currentTx, expectedQueryLoop } from '@ultimat3/db';
+import { currentWriteOrigin, type EntityRowOp, instrument, subscribed } from '@ultimat3/core';
+import { expectedQueryLoop } from '@ultimat3/db';
 import type { EntityCore } from './entity';
-import { memoryJournal } from './memory-journal';
 import { MAX_PAGE_SIZE } from './plan';
 import { readRecorder } from './read-capture';
 import type { Repo, RepoOptions, UpsertArgs } from './repo';
 import { sealedFields } from './sealed';
+import { searchMirroredRepo } from './search-mirrored-repo';
 import type { IdOf, RowPatch } from './types';
-
-export type RowChangeOp = 'insert' | 'update' | 'delete';
-
-/**
- * One committed row change. `before`/`after` are whole rows, exactly as logical replication reports
- * them with `REPLICA IDENTITY FULL` — a consumer diffs them itself rather than trusting a patch it
- * did not compile.
- */
-export interface RowChange {
-  /** Entity name as declared, never a table name — the vocabulary a matcher's dependency set uses. */
-  readonly entity: string;
-  readonly op: RowChangeOp;
-  readonly before: Readonly<Record<string, unknown>> | null;
-  readonly after: Readonly<Record<string, unknown>> | null;
-  /**
-   * The keyed write this change belongs to — `@ultimat3/core`'s `currentWriteOrigin()` at the
-   * moment the repository wrote, i.e. the digest of the idempotency key the request arrived with.
-   * The WAL decoder reads the same fact off the transaction's opening message; absent both ways
-   * for a write no keyed request made.
-   */
-  readonly write?: string;
-}
-
-/**
- * A write this seam cannot itemise: `deleteWhere` and `updateWhere` name a filter, not a row, and
- * reading the matching rows first would turn one statement into two and change what the code under
- * test issues. Reported as a bulk fact so a consumer can re-read rather than be told nothing —
- * silence is the one answer that diverges silently, which is the failure `invalidate()` exists for.
- */
-export interface RowBulkChange {
-  readonly entity: string;
-  readonly op: 'delete' | 'update';
-  readonly rows: number;
-}
-
-export interface RowObserver {
-  onChange(change: RowChange): void;
-  /** Optional: an observer that re-reads everything on any change has nothing to do here. */
-  onBulk?(change: RowBulkChange): void;
-}
-
-let installed: RowObserver | null = null;
+import { afterCommit } from './write-commit';
 
 /**
- * Install the process's row observer, or clear it with `null`. One per process, exactly like
- * `@ultimat3/db`'s `setStatementObserver` — a second observer would be a second consumer disagreeing
- * about what a write is, and the caller that wants two composes them itself.
+ * A committed row change is `entity.row` on the bus (`EntityRowEvent`, core's shape): `before` and
+ * `after` are whole rows, exactly as logical replication reports them with `REPLICA IDENTITY FULL`
+ * — a subscriber diffs them itself rather than trusting a patch it did not compile. `write` is
+ * `currentWriteOrigin()` at the moment the repository wrote; the WAL decoder reads the same fact.
  *
- * Returns the observer that was installed, so a harness restores rather than clears: `bun test`
- * shares one process across files, and a fixture that cleared unconditionally would take an outer
- * harness's observer with it.
+ * `deleteWhere` and `updateWhere` name a filter, not a row, and reading the matching rows first
+ * would turn one statement into two — so they are `entity.bulk` (`EntityBulkEvent`), a count a
+ * subscriber re-reads on rather than silence, which is the one answer that diverges silently.
  */
-export function setRowObserver(next: RowObserver | null): RowObserver | null {
-  const previous = installed;
-  installed = next;
-  return previous;
-}
-
-export const rowObserver = (): RowObserver | null => installed;
+const ROW = 'entity.row';
+const BULK = 'entity.bulk';
 
 /**
  * The reads a change needs and a plain write does not. `before` costs one `findById` per update and
- * per delete — paid ONLY while an observer is installed, which is why the guard is the first line of
- * every method below rather than a flag read once at wrap time. With no observer this wrapper is one
- * comparison and a delegation, on a path that already awaits a database.
+ * per delete — paid ONLY while `entity.row` has a subscriber, which is why the guard is the first line
+ * of every method below rather than a flag read once at wrap time. With none this wrapper is one map
+ * read and a delegation, on a path that already awaits a database.
  */
 const idOf = (value: unknown): string | undefined => {
   const id = (value as { readonly id?: unknown } | null)?.id;
@@ -114,7 +70,7 @@ const readsById = (entity: EntityCore<unknown>): boolean =>
  *
  * The `catch` is a FLOOR, not a case: no write in this repo is known to succeed while its own
  * `findById` refuses, because every guard a read applies — tenancy, soft delete — the write applies
- * too. It stays because the cost of being wrong is asymmetric: an observer is a diagnostic, and a
+ * too. It stays because the cost of being wrong is asymmetric: a subscriber is a diagnostic, and a
  * diagnostic that turns a working write into a failing one is worse than the gap it was closing.
  */
 const beforeOf = async <Row>(
@@ -129,7 +85,7 @@ const beforeOf = async <Row>(
     // caller's loop, reported on the caller's writes. Without the scope the same loop was reported
     // twice, the second verdict naming a `findById` no app code issued.
     return await expectedQueryLoop(
-      'the row observer reads the row a point write is about to change — one read per write',
+      'the entity.row event reads the row a point write is about to change — one read per write',
       () => repo.findById(id),
     );
   } catch {
@@ -180,12 +136,15 @@ const beforeAllOf = async <Row>(
 
 /**
  * Wrap one repository so its writes are reported. Applied by `database()` to every table it builds,
- * so an app opts in by installing an observer and never by choosing a different repository — the
+ * so an app opts in by subscribing to `entity.row` and never by choosing a different repository — the
  * rows under test are the rows the app reads, which is the whole reason `defaultDriver()` is
  * exported at all.
  */
-export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Repo<Row> {
+export function observedRepo<Row>(entity: EntityCore<Row>, driven: Repo<Row>): Repo<Row> {
   const name = entity.$name;
+  // Beneath the observer, so a searchable entity's writes reach an external index whether or not
+  // anything hears `entity.row` (`search-mirrored-repo.ts`).
+  const repo = searchMirroredRepo(entity, driven);
   const sealed = sealedFields(entity).map((field) => field.property);
 
   /**
@@ -202,42 +161,31 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
   };
 
   /**
-   * Reported at COMMIT. The write may sit in a transaction — the caller's `options.tx`, the
-   * ambient `withTransaction` a Postgres repository joins, or the ambient memory one — and a change reported before COMMIT
-   * put a row in a live query that a rollback then erased (plan 101, 06 m). Outside a transaction
-   * the write is already durable, so it is reported at once. The write origin is read NOW: it is
-   * the request's, and the commit callback may run outside that request's scope.
+   * Reported at COMMIT (`write-commit.ts`): a change reported before COMMIT put a row in a live
+   * query that a rollback then erased (plan 101, 06 m). The write origin is read NOW: it is the
+   * request's, and the commit callback may run outside that request's scope.
    */
-  const afterCommit = (options: RepoOptions | undefined, report: () => void): void => {
-    const tx: { onCommit?(effect: () => void): void } | undefined =
-      options?.tx ?? currentTx() ?? memoryJournal();
-    if (tx?.onCommit === undefined) report();
-    else tx.onCommit(report);
-  };
-
   const emit = (
-    op: RowChangeOp,
+    op: EntityRowOp,
     before: unknown,
     after: unknown,
     options: RepoOptions | undefined,
   ): void => {
-    const observer = installed;
-    if (observer === null) return;
+    if (!subscribed(ROW)) return;
     const write = currentWriteOrigin();
-    const change: RowChange = {
+    const change = {
       entity: name,
       op,
       before: reported(before),
       after: reported(after),
       ...(write === undefined ? {} : { write }),
     };
-    afterCommit(options, () => observer.onChange(change));
+    afterCommit(options, () => instrument(ROW, change));
   };
 
   const bulk = (op: 'delete' | 'update', rows: number, options: RepoOptions | undefined): void => {
-    const observer = installed;
-    if (rows > 0 && observer?.onBulk !== undefined) {
-      afterCommit(options, () => observer.onBulk?.({ entity: name, op, rows }));
+    if (rows > 0 && subscribed(BULK)) {
+      afterCommit(options, () => instrument(BULK, { entity: name, op, rows }));
     }
   };
 
@@ -282,7 +230,7 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
      * did not occur.
      */
     upsertAll: async (rows: readonly Row[], args: UpsertArgs<Row>): Promise<readonly Row[]> => {
-      if (installed === null) return await repo.upsertAll(rows, args);
+      if (!subscribed(ROW)) return await repo.upsertAll(rows, args);
       const ids = [...new Set(rows.flatMap((row) => idOf(row) ?? []))];
       const before = await beforeAllOf(entity, repo, ids);
       const stored = await repo.upsertAll(rows, args);
@@ -295,7 +243,7 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
     },
 
     update: async (id, patch: RowPatch<Row>, options?: RepoOptions): Promise<Row> => {
-      if (installed === null) return await repo.update(id, patch, options);
+      if (!subscribed(ROW)) return await repo.update(id, patch, options);
       const before = await beforeOf(entity, repo, id);
       const after = await repo.update(id, patch, options);
       emit('update', before, after, options);
@@ -303,7 +251,7 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
     },
 
     delete: async (id, options?: RepoOptions): Promise<void> => {
-      if (installed === null) return await repo.delete(id, options);
+      if (!subscribed(ROW)) return await repo.delete(id, options);
       const before = await beforeOf(entity, repo, id);
       await repo.delete(id, options);
       emit('delete', before, null, options);

package/src/search-index-installed.ts

@@ -0,0 +1,24 @@
+// The installed `SearchIndex`: `runtime.ts`'s `searchIndex`, else `postgresSearchIndex()` over the
+// ambient pool. One slot (`adapterSlot`), read per call, so a test's `installSearchIndex(memory)`
+// and the boot's install both release only their own frame.
+
+import { adapterSlot } from '@ultimat3/core/adapter';
+import type { SearchIndex } from './search-index';
+import { postgresSearchIndex } from './search-index-postgres';
+
+let builtIn: SearchIndex | undefined;
+
+const slot = /* @__PURE__ */ adapterSlot<SearchIndex>(() => {
+  builtIn ??= postgresSearchIndex();
+  return builtIn;
+});
+
+/**
+ * On `./adapter` only. Answers the release: it drops this install and no other. While an external
+ * index is the current one, every committed write of a searchable entity is mirrored to it
+ * (`search-index-sync.ts`, asked per write by `row-observer.ts`) — no subscription to hold.
+ */
+export const installSearchIndex = (index: SearchIndex): (() => void) => slot.install(index);
+
+/** The index every search through the port asks — what `reindex` writes and a read queries. */
+export const searchIndex = (): SearchIndex => slot.current();

package/src/search-index-memory.ts

@@ -0,0 +1,132 @@
+// `memorySearchIndex()`: the reference `SearchIndex` an adapter author copies, and the one a unit
+// test installs. Words, case-folded, every query word required — NOT Postgres: no stemming, no
+// stop words, no `websearch` operators — why `memoryDriver()` still refuses `.search()`. Newest
+// version per id wins; tombstones live as long as the index (a reference and a test index only).
+
+import type {
+  SearchDocument,
+  SearchHit,
+  SearchIndex,
+  SearchListEntry,
+  SearchQuery,
+  SearchScope,
+} from './search-index';
+import { searchLimitOf, searchListLimitOf } from './search-index';
+
+/** Letters and digits in any script; everything else separates words. */
+const WORD = /[\p{L}\p{N}]+/gu;
+
+/** The distinct lower-cased words of `text`. */
+export const searchWords = (text: string): readonly string[] => [
+  ...new Set(text.toLocaleLowerCase('und').match(WORD) ?? []),
+];
+
+/** One id's newest state: its words, or `null` — the tombstone a `remove` leaves. */
+interface Held {
+  readonly id: string;
+  readonly version: number;
+  readonly words: ReadonlyMap<string, number> | null;
+}
+
+const countWords = (document: SearchDocument): ReadonlyMap<string, number> => {
+  const counts = new Map<string, number>();
+  for (const text of Object.values(document.fields)) {
+    for (const word of text.toLocaleLowerCase('und').match(WORD) ?? []) {
+      counts.set(word, (counts.get(word) ?? 0) + 1);
+    }
+  }
+  return counts;
+};
+
+/** One key per `(entity, tenant)`: JSON, so no entity name can be spelled into another scope. */
+const scopeKey = (scope: SearchScope): string => JSON.stringify([scope.entity, scope.tenant]);
+
+export const memorySearchIndex = (): SearchIndex => {
+  const scopes = new Map<string, Map<string, Held>>();
+  /** Which tenant each scope key is, so `list` can walk one entity's scopes. */
+  const scopeOwners = new Map<string, SearchScope>();
+  const scopeOf = (scope: SearchScope): Map<string, Held> => {
+    const key = scopeKey(scope);
+    const found = scopes.get(key);
+    if (found !== undefined) return found;
+    const created = new Map<string, Held>();
+    scopes.set(key, created);
+    scopeOwners.set(key, { entity: scope.entity, tenant: scope.tenant });
+    return created;
+  };
+
+  return {
+    name: 'memory',
+    index: async (documents, options) => {
+      for (const document of documents) {
+        const scope = scopeOf(document);
+        const held = scope.get(document.id);
+        // A committed write's row exists: it replaces the tombstone of an earlier delete.
+        const replaces = options?.committed === true && held?.words === null;
+        // Keep only newer: a reindex batch that read the row before a write — or before its
+        // delete — arrives here after it, and must not put the old text back.
+        if (!replaces && (held?.version ?? Number.NEGATIVE_INFINITY) >= document.version) {
+          continue;
+        }
+        scope.set(document.id, {
+          id: document.id,
+          version: document.version,
+          words: countWords(document),
+        });
+      }
+    },
+    remove: async (scope, ids, version) => {
+      const held = scopeOf(scope);
+      for (const id of ids) {
+        // A remove older than what is held (a re-create after it) changes nothing.
+        if ((held.get(id)?.version ?? Number.NEGATIVE_INFINITY) > version) continue;
+        held.set(id, { id, version, words: null });
+      }
+    },
+    // Ordered by `[tenant, id]` as JSON, which is also the cursor: a total order, stable across calls.
+    list: async (query) => {
+      const limit = searchListLimitOf(query);
+      const entries: (SearchListEntry & { readonly at: string })[] = [];
+      for (const [key, owner] of scopeOwners) {
+        if (owner.entity !== query.entity) continue;
+        if (query.tenant !== undefined && owner.tenant !== query.tenant) continue;
+        for (const each of scopes.get(key)?.values() ?? []) {
+          if (each.words === null) continue;
+          const at = JSON.stringify([owner.tenant, each.id]);
+          if (query.after !== null && at <= query.after) continue;
+          entries.push({ tenant: owner.tenant, id: each.id, version: each.version, at });
+        }
+      }
+      entries.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
+      const page = entries.slice(0, limit);
+      const last = page.at(-1);
+      return {
+        entries: page.map(({ tenant, id, version }) => ({ tenant, id, version })),
+        next: entries.length > limit && last !== undefined ? last.at : null,
+      };
+    },
+    query: async (query: SearchQuery): Promise<readonly SearchHit[]> => {
+      const limit = searchLimitOf(query);
+      const words = searchWords(query.term);
+      if (words.length === 0) return [];
+      const held = scopes.get(scopeKey(query)) ?? new Map<string, Held>();
+      const scored: { readonly id: string; readonly score: number }[] = [];
+      for (const each of held.values()) {
+        if (each.words === null) continue;
+        let score = 0;
+        for (const word of words) {
+          const count = each.words.get(word) ?? 0;
+          if (count === 0) {
+            score = -1;
+            break;
+          }
+          score += count;
+        }
+        if (score > 0) scored.push({ id: each.id, score });
+      }
+      // Best first; the id breaks a tie so the same index answers the same order every time.
+      scored.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      return scored.slice(0, limit).map(({ id }) => ({ id }));
+    },
+  };
+};

package/src/search-index-postgres.ts

@@ -0,0 +1,107 @@
+// `postgresSearchIndex()`: the built-in `SearchIndex` — `.searchable()`'s generated `tsvector`,
+// behind the port. Postgres keeps the vector itself on every write (`generated always as … stored`),
+// so `index`/`remove` only check the entity and send nothing; `query` is the repository's own
+// `matches` read, so tenancy, the actor check and soft delete are the ones `.search()` already has.
+
+import type { DbClient } from '@ultimat3/db';
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import { searchUndeclared } from './feature-errors';
+import { postgresRepo } from './pg-driver';
+import { getEntity } from './registry';
+import { rowKey } from './row-key';
+import { SEARCH_PROPERTY } from './search';
+import type { SearchHit, SearchIndex, SearchListPage, SearchScope } from './search-index';
+import { searchLimitOf, searchListLimitOf } from './search-index';
+import { searchVersionOf } from './search-index-version';
+import type { Predicate } from './tenancy';
+
+export interface PostgresSearchIndexOptions {
+  /** Pin a client; left out, the ambient pool (or the open transaction) per statement. */
+  readonly client?: DbClient;
+}
+
+/** The registered entity a scope names, with a search vector — refused otherwise. */
+const searchableEntity = (name: string): EntityCore<unknown> => {
+  const core = getEntity(name)?.core;
+  if (core === undefined || core.$search === null) throw searchUndeclared(name);
+  return core;
+};
+
+/** The tenant predicate a scope adds; a tenant named on an untenanted entity is refused. */
+const tenantPredicate = (core: EntityCore<unknown>, scope: SearchScope): readonly Predicate[] => {
+  const column = core.$tenantColumn;
+  if (column === null) {
+    if (scope.tenant === null) return [];
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `search of ${core.$name} named a tenant, but ${core.$name} has no tenant column — the tenant would scope nothing`,
+      fix: 'searchIndex().query({ entity, tenant: null, term }) — an untenanted entity is searched whole',
+    });
+  }
+  // `null` on a tenanted entity adds no predicate: the repository then takes the acting actor's
+  // tenant, or refuses `X_TENANCY_UNSCOPED` — the rule every other read of it already follows.
+  return scope.tenant === null ? [] : [{ column, op: 'eq', value: scope.tenant }];
+};
+
+/**
+ * `index` and `remove` send nothing, so the version contract holds by construction: the table IS
+ * the newest state, and a stale document never reaches it.
+ *
+ * The indexes whose match is the statement's own `matches` predicate — a chain's `.search()` then
+ * sends today's single statement (`pg-sql.ts`'s `searchSql`), never a round trip for ids. Only
+ * this file adds to it: an app's index is always asked through the port.
+ */
+const inStatement = new WeakSet<SearchIndex>();
+
+export const answersInStatement = (index: SearchIndex): boolean => inStatement.has(index);
+
+export const postgresSearchIndex = (options: PostgresSearchIndexOptions = {}): SearchIndex => {
+  const repoOf = (core: EntityCore<unknown>) =>
+    postgresRepo(core, options.client === undefined ? {} : { client: options.client });
+  const index: SearchIndex = {
+    name: 'postgres',
+    index: async (documents) => {
+      for (const document of documents)
+        tenantPredicate(searchableEntity(document.entity), document);
+    },
+    remove: async (scope) => {
+      tenantPredicate(searchableEntity(scope.entity), scope);
+    },
+    // What it holds IS the table: the rows a `reindex` source reads, so its sweep removes nothing.
+    // Primary-key order, the repository's own cursor; a tenant left out is the ambient rule.
+    list: async (query): Promise<SearchListPage> => {
+      const limit = searchListLimitOf(query);
+      const core = searchableEntity(query.entity);
+      const where = tenantPredicate(core, { entity: query.entity, tenant: query.tenant ?? null });
+      const page = await repoOf(core).findMany({ where, limit, cursor: query.after });
+      const tenantColumn = core.$tenantColumn;
+      return {
+        entries: page.rows.map((row) => {
+          const tenant =
+            tenantColumn === null ? null : (row as Record<string, unknown>)[tenantColumn];
+          return {
+            tenant: typeof tenant === 'string' ? tenant : null,
+            id: rowKey(core, row),
+            version: searchVersionOf(core, row),
+          };
+        }),
+        next: page.nextCursor,
+      };
+    },
+    query: async (query): Promise<readonly SearchHit[]> => {
+      const limit = searchLimitOf(query);
+      const core = searchableEntity(query.entity);
+      const where: readonly Predicate[] = [
+        ...tenantPredicate(core, query),
+        { column: SEARCH_PROPERTY, op: 'matches', value: query.term },
+      ];
+      // Primary-key order, as `.search()` with no `orderBy` answers: a rank is not a sort key the
+      // plan can seek on, so the built-in index returns matches, not a relevance order.
+      const page = await repoOf(core).findMany({ where, limit });
+      return page.rows.map((row) => ({ id: rowKey(core, row) }));
+    },
+  };
+  inStatement.add(index);
+  return index;
+};

package/src/search-index-sync.ts

@@ -0,0 +1,96 @@
+// The search index WRITE path: what a committed write of a searchable entity sends to an installed
+// external index. A live row is indexed (`committed`: it replaces a tombstone); a deleted one — hard,
+// or soft-stamped — removed at a tombstone no older than its last version. Ops are taken when the
+// write runs and sent at COMMIT (`search-mirror-batch.ts`), so a rollback indexes nothing.
+
+import { entityNow } from './clock';
+import type { EntityCore } from './entity';
+import { SOFT_DELETE_COLUMN } from './entity';
+import type { RepoOptions } from './repo';
+import { rowKey } from './row-key';
+import { searchDocumentOf } from './search-index';
+import { searchIndex } from './search-index-installed';
+import { answersInStatement } from './search-index-postgres';
+import { searchVersionOf, VERSION_STEP_MS } from './search-index-version';
+import { mirrorBatch, mirrorFailed } from './search-mirror-batch';
+import { commitScope } from './write-commit';
+
+export { SEARCH_INDEX_WRITE_FAILED } from './search-mirror-batch';
+
+type Record_ = Readonly<Record<string, unknown>>;
+
+/** One write's mirror: bound to the index installed and the transaction open when the write ran. */
+export interface SearchMirror {
+  /** Rows the write left in place: indexed, or removed when a soft-delete stamp is on them. */
+  changed(op: string, rows: readonly unknown[]): void;
+  /** Rows the write deleted. */
+  deleted(op: string, rows: readonly unknown[]): void;
+  /** The write touched `count` rows its driver did not name: said out loud, never silent. */
+  unnamed(op: string, count: number): void;
+}
+
+const isRecord = (row: unknown): row is Record_ => typeof row === 'object' && row !== null;
+
+const tenantOf = (core: EntityCore<unknown>, row: Record_): string | null => {
+  const column = core.$tenantColumn;
+  const tenant = column === null ? null : row[column];
+  return typeof tenant === 'string' ? tenant : null;
+};
+
+const keyOf = (entity: string, tenant: string | null, id: string): string =>
+  JSON.stringify([entity, tenant, id]);
+
+export const mirrorFor = (
+  core: EntityCore<unknown>,
+  options: RepoOptions | undefined,
+): SearchMirror | undefined => {
+  if (core.$search === null) return undefined;
+  const index = searchIndex();
+  if (answersInStatement(index)) return undefined;
+  const entity = core.$name;
+  const batch = mirrorBatch(index, commitScope(options));
+  // Read when the write runs, not at commit: a hard delete's tombstone is no older than its instant.
+  const deletedAt = entityNow().getTime();
+  /** The tombstone a row's removal leaves: past every version the row was indexed at. */
+  const removal = (op: string, row: Record_, at: number) => {
+    const tenant = tenantOf(core, row);
+    const id = rowKey(core, row);
+    const version = Math.max(at, searchVersionOf(core, row) + VERSION_STEP_MS);
+    batch.put(keyOf(entity, tenant, id), { op, entity, tenant, id, version });
+  };
+  const guarded = (op: string, work: () => void) => {
+    try {
+      work();
+    } catch (error) {
+      mirrorFailed(entity, op, error);
+    }
+    batch.done();
+  };
+  return {
+    changed: (op, rows) =>
+      guarded(op, () => {
+        for (const row of rows.filter(isRecord)) {
+          const stamp = core.$softDelete ? row[SOFT_DELETE_COLUMN] : null;
+          if (stamp instanceof Date) {
+            removal(op, row, stamp.getTime());
+            continue;
+          }
+          const document = searchDocumentOf(core, row);
+          batch.put(keyOf(entity, document.tenant, document.id), { op, document });
+        }
+      }),
+    deleted: (op, rows) =>
+      guarded(op, () => {
+        for (const row of rows.filter(isRecord)) removal(op, row, deletedAt);
+      }),
+    unnamed: (op, count) => guarded(op, () => batch.unnamed(entity, op, count)),
+  };
+};
+
+/**
+ * Whether a write of `entity` owes the index anything: nothing for an entity with nothing
+ * searchable (one property read), nor under the built-in Postgres index, whose vector is the row.
+ * Asked per write, so a test's install over the boot's mirrors to the newest one only.
+ */
+export const mirrors = (entity: EntityCore<unknown>): boolean =>
+  entity.$search !== null && !answersInStatement(searchIndex());