@ultimat3/entity 30.8.0 → 31.0.0

package/src/search-index-version.ts

@@ -0,0 +1,93 @@
+// A search document's VERSION: the row's `onUpdateNow()` instant, epoch ms — STRICTLY increasing
+// per row. `touch()` stamps it from `entityNow()`, and every driver writes it no earlier than the
+// stored value + 1 ms (`advanceVersion`, `pg-write-sql.ts`'s `greatest`), so two writes inside one
+// millisecond are two versions and an index can keep only newer without losing the second.
+
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+
+/**
+ * The property a searchable entity is versioned by: its first `onUpdateNow()` timestamp. Refused
+ * when there is none — without it no index can tell a `reindex` batch's stale read from a write.
+ */
+export const searchVersionColumn = (entity: EntityCore<unknown>): string => {
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    if (column.$meta.kind === 'timestamptz' && column.$meta.onUpdate !== undefined) return property;
+  }
+  throw new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entity.$name} is searchable but declares no onUpdateNow() column, so a search document has no version and an index cannot refuse a stale one`,
+    fix: `updatedAt: timestamp().defaultNow().onUpdateNow()   # in entity('${entity.$name}'), then: x db gen "version ${entity.$name} for search"`,
+  });
+};
+
+/** How far a write moves a version past the stored one when the clock has not: one millisecond. */
+export const VERSION_STEP_MS = 1;
+
+/**
+ * The property a write of `entity` must ADVANCE, or `undefined`: the version column of a
+ * searchable entity. Every other `onUpdateNow()` column is the clock's reading, unchanged.
+ */
+export const advancingVersionColumn = (entity: EntityCore<unknown>): string | undefined => {
+  if (entity.$search === null) return undefined;
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    if (column.$meta.kind === 'timestamptz' && column.$meta.onUpdate !== undefined) return property;
+  }
+  return undefined;
+};
+
+/**
+ * A soft delete's stamp: `deletedAt`, plus the version column of a searchable entity — a deletion
+ * is a write, so it advances the version too (`advanceVersion`, `greatest(…)` in the statement), and
+ * the tombstone sits past it.
+ */
+export const deletionStamp = (
+  entity: EntityCore<unknown>,
+  softDeleteColumn: string,
+  now: Date,
+): Readonly<Record<string, Date>> => {
+  const version = advancingVersionColumn(entity);
+  return version === undefined
+    ? { [softDeleteColumn]: now }
+    : { [softDeleteColumn]: now, [version]: now };
+};
+
+/**
+ * `merged` with its version no earlier than `stored`'s + `VERSION_STEP_MS`, when the write named
+ * the version column (`named`) — the memory driver's and a custom store's half of the rule; the
+ * Postgres statement says it as `greatest(…)`.
+ */
+export const advanceVersion = <Row>(
+  entity: EntityCore<Row>,
+  stored: Row,
+  merged: Row,
+  named: (property: string) => boolean,
+): Row => {
+  const property = advancingVersionColumn(entity as EntityCore<unknown>);
+  if (property === undefined || !named(property)) return merged;
+  const before = instantMs((stored as Readonly<Record<string, unknown>>)[property]);
+  const after = instantMs((merged as Readonly<Record<string, unknown>>)[property]);
+  if (before === undefined || after === undefined || after > before) return merged;
+  return Object.assign({}, merged, { [property]: new Date(before + VERSION_STEP_MS) }) as Row;
+};
+
+const instantMs = (value: unknown): number | undefined => {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'string') return Date.parse(value);
+  return undefined;
+};
+
+/** The version of one row of `entity`: its version column, epoch ms. */
+export const searchVersionOf = <Row>(entity: EntityCore<Row>, row: Row): number => {
+  const core = entity as EntityCore<unknown>;
+  const property = searchVersionColumn(core);
+  const ms = instantMs((row as Readonly<Record<string, unknown>>)[property]);
+  if (ms === undefined || !Number.isFinite(ms)) {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `a ${entity.$name} row reached the search index without its ${property} instant, so its document has no version`,
+      fix: `searchDocumentOf(${entity.$name}, await db.${entity.$name}.findById(id))   # the whole row: a select() that drops ${property} has no version`,
+    });
+  }
+  return ms;
+};

package/src/search-index.ts

@@ -0,0 +1,168 @@
+// The `searchIndex` port: where a full-text search over an entity's `.searchable()` columns is
+// answered. Postgres' generated `tsvector` is the built-in one (`search-index-postgres.ts`); an app
+// writes Meilisearch or Typesense against this interface. Tenant-scoped on every call: a document
+// is indexed under its tenant, and a query or a removal names the tenant it may reach.
+
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import { MAX_PAGE_SIZE } from './plan';
+import { rowKey } from './row-key';
+import { searchVersionOf } from './search-index-version';
+
+/** What a search answers: the entity's name and the rows' tenant, never one without the other. */
+export interface SearchScope {
+  /** The entity NAME (`entity('<name>', …)`), not its table. */
+  readonly entity: string;
+  /** The tenant column's value; `null` for an untenanted entity, and only for one. */
+  readonly tenant: string | null;
+}
+
+/** One row as the index sees it: its key and the text of every searchable column it holds. */
+export interface SearchDocument extends SearchScope {
+  /** `rowKey(entity, row)` — the id a hit hands back to `findById`. */
+  readonly id: string;
+  /**
+   * The row's `onUpdateNow()` instant, epoch ms (`search-index-version.ts`). An index keeps the
+   * NEWEST version per id and refuses an older one — a `reindex` batch read before a write.
+   */
+  readonly version: number;
+  /** Searchable property → its text. A NULL column is absent, never `''`. */
+  readonly fields: Readonly<Record<string, string>>;
+}
+
+export interface SearchQuery extends SearchScope {
+  /**
+   * What a search box sent. Every word must match (case-insensitively); punctuation is text and
+   * never an error; a term with no word in it answers no hits.
+   */
+  readonly term: string;
+  /** At most this many hits. Default `DEFAULT_SEARCH_LIMIT`, at most `MAX_PAGE_SIZE`. */
+  readonly limit?: number;
+}
+
+/** How a batch of documents reached `index`. */
+export interface SearchIndexOptions {
+  /**
+   * `true` from the write path: each document is a row a COMMITTED write left, so it replaces a
+   * TOMBSTONE whatever the two versions say — a key deleted and written again is live, even inside
+   * one millisecond. Against a held document it still keeps only newer. Unset (`reindex`'s reads):
+   * a tombstone at the document's version or newer refuses it, so a stale read never brings a
+   * deleted row back.
+   */
+  readonly committed?: boolean;
+}
+
+/**
+ * One page of what an index holds for an entity — what `reindex`'s sweep compares with the table.
+ * `tenant` absent is EVERY tenant's documents: a maintenance read, under the same tenancy rule a
+ * `query` with `tenant: null` follows (the built-in index needs `crossTenant` for it).
+ */
+export interface SearchListQuery {
+  readonly entity: string;
+  readonly tenant?: string | null;
+  /** The previous page's `next`; `null` for the first page. Opaque to the caller. */
+  readonly after: string | null;
+  /** At most this many entries, from 1 to `MAX_PAGE_SIZE`. */
+  readonly limit: number;
+}
+
+/** A document the index holds — never a tombstone. */
+export interface SearchListEntry {
+  readonly tenant: string | null;
+  readonly id: string;
+  /** The version it holds for the id: a sweep's removal is tombstoned just above it. */
+  readonly version: number;
+}
+
+export interface SearchListPage {
+  readonly entries: readonly SearchListEntry[];
+  /** Where the next page starts; `null` once there is none. */
+  readonly next: string | null;
+}
+
+/** A match: the row's id, best first in the index's own relevance order. */
+export interface SearchHit {
+  readonly id: string;
+}
+
+/**
+ * The port. `index` and `remove` take batches because `reindex` (a `backfill()` job) walks a table
+ * page by page. Every method is tenant-scoped: an index that answers tenant A a document indexed
+ * under tenant B is broken, and `searchIndexConformance` says so.
+ *
+ * Keep only newer: a document is applied only when its `version` is newer than what the index
+ * holds for that id — a document, or the TOMBSTONE a `remove` leaves, unless the write path sent it
+ * (`committed`), which replaces a tombstone. A version equal to the one held is a replay.
+ */
+export interface SearchIndex {
+  readonly name: string;
+  /**
+   * Insert or replace each document under its `(entity, tenant, id)`, when it is newer than the
+   * document held — or, `committed`, whatever tombstone is held (`SearchIndexOptions`).
+   */
+  index(documents: readonly SearchDocument[], options?: SearchIndexOptions): Promise<void>;
+  /**
+   * Drop these ids of `scope` and leave a tombstone at `version` (the delete's instant, epoch ms),
+   * so a document no newer than the delete is refused. Another tenant's id is left where it is.
+   */
+  remove(scope: SearchScope, ids: readonly string[], version: number): Promise<void>;
+  query(query: SearchQuery): Promise<readonly SearchHit[]>;
+  /**
+   * Every live document of an entity, paged in an order the index keeps stable across calls: each
+   * id once, none removed. `reindex` sweeps with it, removing what the table no longer holds.
+   */
+  list(query: SearchListQuery): Promise<SearchListPage>;
+}
+
+export const DEFAULT_SEARCH_LIMIT = 20;
+
+/** The limit a query asked for, checked once for every index. */
+export const searchLimitOf = (query: SearchQuery): number => {
+  const limit = query.limit ?? DEFAULT_SEARCH_LIMIT;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_PAGE_SIZE) {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `search of ${query.entity}: limit must be a whole number from 1 to ${MAX_PAGE_SIZE}, got ${String(limit)}`,
+      fix: `searchIndex().query({ entity, tenant, term, limit: ${DEFAULT_SEARCH_LIMIT} })`,
+    });
+  }
+  return limit;
+};
+
+/** A `list` page size, checked once for every index. */
+export const searchListLimitOf = (query: SearchListQuery): number => {
+  const { limit } = query;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_PAGE_SIZE) {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `list of ${query.entity}'s search documents: limit must be a whole number from 1 to ${MAX_PAGE_SIZE}, got ${String(limit)}`,
+      fix: `searchIndex().list({ entity, after: null, limit: ${DEFAULT_SEARCH_LIMIT} })`,
+    });
+  }
+  return limit;
+};
+
+/**
+ * The document a row of `entity` is indexed as — the ONE builder, so a write hook and `reindex`
+ * cannot index the same row two ways. Only `.searchable()` columns travel; nothing else of the row
+ * (a sealed column is never searchable, `sealed-column.ts`) leaves for an external index. Its
+ * version is the row's `onUpdateNow()` instant; an entity declaring none is refused.
+ */
+export const searchDocumentOf = <Row>(entity: EntityCore<Row>, row: Row): SearchDocument => {
+  const record = row as Readonly<Record<string, unknown>>;
+  const fields: Record<string, string> = {};
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    if (column.$meta.searchable === undefined) continue;
+    const value = record[property];
+    if (typeof value === 'string') fields[property] = value;
+  }
+  const tenantColumn = entity.$tenantColumn;
+  const tenant = tenantColumn === null ? null : record[tenantColumn];
+  return {
+    entity: entity.$name,
+    tenant: typeof tenant === 'string' ? tenant : null,
+    id: rowKey(entity, row),
+    version: searchVersionOf(entity, row),
+    fields,
+  };
+};

package/src/search-mirror-batch.ts

@@ -0,0 +1,133 @@
+// One transaction's search-index ops, merged per `(entity, tenant, id)`: a key's last document, and
+// its removal unless a later op wrote it back — sent once the transaction COMMITS, removals first.
+// Every send to one index rides one chain: an index hears this process's writes in commit order.
+
+import { isUltimateError, logger, renderThrowable } from '@ultimat3/core';
+import type { SearchDocument, SearchIndex } from './search-index';
+import type { CommitScope } from './write-commit';
+
+/** The one log event a failed mirror writes — its fields name the entity, the op and the code. */
+export const SEARCH_INDEX_WRITE_FAILED = 'entity.search-index.write-failed';
+
+export const unmirrored = (entity: string, op: string, cause: string, code?: string): void => {
+  logger.warn(SEARCH_INDEX_WRITE_FAILED, {
+    entity,
+    op,
+    ...(code === undefined ? {} : { code }),
+    cause,
+    fix: `reindex({ name: 'reindex-${entity}', entity, source, tenant: 'none' })   # rebuild the index, which missed this ${op}`,
+  });
+};
+
+export const mirrorFailed = (entity: string, op: string, error: unknown): void =>
+  unmirrored(entity, op, renderThrowable(error), isUltimateError(error) ? error.code : undefined);
+
+/** One key's op: its document, or its removal at a tombstone version. */
+export type MirrorOp = { readonly op: string; readonly document: SearchDocument } | Removal;
+
+interface Removal {
+  readonly op: string;
+  readonly entity: string;
+  readonly tenant: string | null;
+  readonly id: string;
+  readonly version: number;
+}
+
+/**
+ * What one key owes at commit. A removal followed by a document keeps BOTH, in that order: the
+ * document (`committed`) replaces the tombstone, and the removal is what retires the document the
+ * index held — of an older incarnation, at a version the new row may not pass. A document followed
+ * by a removal is the removal alone.
+ */
+interface KeyOps {
+  removal?: Removal;
+  document?: SearchDocument;
+}
+
+interface Pending {
+  readonly index: SearchIndex;
+  readonly ops: Map<string, KeyOps>;
+  readonly unnamed: { readonly entity: string; readonly op: string; readonly count: number }[];
+}
+
+/** Each index's tail: the next send waits for the last, whatever it answered. */
+const tails = new WeakMap<SearchIndex, Promise<void>>();
+
+const send = (index: SearchIndex, entity: string, op: string, call: () => Promise<void>) => {
+  const next = (tails.get(index) ?? Promise.resolve()).then(async () => {
+    try {
+      await call();
+    } catch (error) {
+      mirrorFailed(entity, op, error);
+    }
+  });
+  tails.set(index, next);
+};
+
+const flush = ({ index, ops, unnamed }: Pending): void => {
+  const documents: SearchDocument[] = [];
+  const removals = new Map<
+    string,
+    { entity: string; tenant: string | null; version: number; op: string; ids: string[] }
+  >();
+  for (const { removal, document } of ops.values()) {
+    if (document !== undefined) documents.push(document);
+    if (removal === undefined) continue;
+    const at = JSON.stringify([removal.entity, removal.tenant, removal.version]);
+    const group = removals.get(at) ?? { ...removal, ids: [] };
+    group.ids.push(removal.id);
+    removals.set(at, group);
+  }
+  for (const { entity, tenant, version, op, ids } of removals.values()) {
+    send(index, entity, op, () => index.remove({ entity, tenant }, ids, version));
+  }
+  if (documents.length > 0) {
+    const [first] = documents;
+    send(index, first?.entity ?? '', 'index', () => index.index(documents, { committed: true }));
+  }
+  for (const { entity, op, count } of unnamed) {
+    unmirrored(entity, op, `${count} rows changed by a store that did not name them`);
+  }
+};
+
+/** The open batch per transaction: one per scope, flushed by its commit and dropped by rollback. */
+const open = new WeakMap<CommitScope, Pending>();
+
+export interface MirrorBatch {
+  put(key: string, op: MirrorOp): void;
+  unnamed(entity: string, op: string, count: number): void;
+}
+
+/**
+ * The batch `index` takes this write's ops into: the transaction's, registered on its commit the
+ * first time — or, outside one, a batch sent as soon as it is filled (`done`).
+ */
+export const mirrorBatch = (
+  index: SearchIndex,
+  scope: CommitScope | undefined,
+): MirrorBatch & { done(): void } => {
+  const existing = scope === undefined ? undefined : open.get(scope);
+  const pending = existing ?? { index, ops: new Map<string, KeyOps>(), unnamed: [] };
+  if (scope !== undefined && existing === undefined) {
+    open.set(scope, pending);
+    scope.onCommit?.(() => {
+      open.delete(scope);
+      flush(pending);
+    });
+  }
+  return {
+    put: (key, op) => {
+      if (!('document' in op)) {
+        pending.ops.set(key, { removal: op });
+        return;
+      }
+      pending.ops.set(key, { ...pending.ops.get(key), document: op.document });
+    },
+    unnamed: (entity, op, count) => {
+      pending.unnamed.push({ entity, op, count });
+    },
+    done: () => {
+      if (scope === undefined) flush(pending);
+    },
+  };
+};

package/src/search-mirrored-repo.ts

@@ -0,0 +1,98 @@
+// Every write of a searchable entity, mirrored to an installed external index at COMMIT. A delete
+// and a filtered write run inside `collectWrittenRows`, so the driver answers the rows it touched
+// (`returning *`) — for a composite or non-`id` key too. Not searchable, or the built-in index
+// installed: the repository is handed back, or the write delegates with no extra statement.
+
+import type { EntityCore } from './entity';
+import type { Repo, RepoOptions } from './repo';
+import type { SearchMirror } from './search-index-sync';
+import { mirrorFor, mirrors } from './search-index-sync';
+import { collectWrittenRows } from './search-written-rows';
+
+type Told = (mirror: SearchMirror, rows: readonly unknown[]) => void;
+
+/** A write that answers its rows: each one mirrored as changed. */
+const stored = async <T extends readonly unknown[]>(
+  entity: EntityCore<unknown>,
+  op: string,
+  options: RepoOptions | undefined,
+  write: () => Promise<T>,
+): Promise<T> => {
+  const rows = await write();
+  if (mirrors(entity)) mirrorFor(entity, options)?.changed(op, rows);
+  return rows;
+};
+
+/**
+ * A write that answers a count, run so its driver hands the rows over. `rows` absent is a store
+ * that named none (a custom driver's, or a write past the bound): logged, never silent, never the
+ * write's failure.
+ */
+const collected = async <T>(
+  entity: EntityCore<unknown>,
+  op: string,
+  options: RepoOptions | undefined,
+  write: () => Promise<T>,
+  told: Told,
+  touched: (result: T) => number,
+): Promise<T> => {
+  if (!mirrors(entity)) return await write();
+  const { result, rows } = await collectWrittenRows(write);
+  const mirror = mirrorFor(entity, options);
+  if (mirror === undefined) return result;
+  if (rows !== undefined) told(mirror, rows);
+  else if (touched(result) > 0) mirror.unnamed(op, touched(result));
+  return result;
+};
+
+export function searchMirroredRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Repo<Row> {
+  if (entity.$search === null) return repo;
+  const core = entity as EntityCore<unknown>;
+  const single = async <T>(row: Promise<T>): Promise<readonly [T]> => [await row];
+  const changed =
+    (op: string): Told =>
+    (mirror, rows) =>
+      mirror.changed(op, rows);
+  const deleted =
+    (op: string): Told =>
+    (mirror, rows) =>
+      mirror.deleted(op, rows);
+
+  return {
+    ...repo,
+    insert: async (values, options) =>
+      (await stored(core, 'insert', options, () => single(repo.insert(values, options))))[0],
+    insertAll: (rows, options) =>
+      stored(core, 'insertAll', options, () => repo.insertAll(rows, options)),
+    upsertAll: (rows, args) => stored(core, 'upsertAll', args, () => repo.upsertAll(rows, args)),
+    update: async (id, patch, options) =>
+      (await stored(core, 'update', options, () => single(repo.update(id, patch, options))))[0],
+    delete: (id, options) =>
+      collected(
+        core,
+        'delete',
+        options,
+        () => repo.delete(id, options),
+        deleted('delete'),
+        () => 1,
+      ),
+    deleteWhere: (filter, options) =>
+      collected(
+        core,
+        'deleteWhere',
+        options,
+        () => repo.deleteWhere(filter, options),
+        deleted('deleteWhere'),
+        (count) => count,
+      ),
+    updateWhere: (filter, patch, options) =>
+      collected(
+        core,
+        'updateWhere',
+        options,
+        () => repo.updateWhere(filter, patch, options),
+        changed('updateWhere'),
+        (count) => count,
+      ),
+  };
+}

package/src/search-repo.ts

@@ -0,0 +1,91 @@
+// The ONE search path: a chain's `.search(term)` asks the INSTALLED `SearchIndex`. The built-in
+// Postgres index answers inside the statement (its `matches` predicate, today's SQL, untouched);
+// any other index is asked for ids first, and the chain then reads those rows with its own
+// tenancy, soft delete, order and cursor — so a Meilisearch hit can never widen what the chain sees.
+
+import { tryUseContext } from '@ultimat3/core';
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import { MAX_PAGE_SIZE } from './plan';
+import type { FindManyArgs, Repo } from './repo';
+import { SEARCH_PROPERTY } from './search';
+import { searchIndex } from './search-index-installed';
+import { answersInStatement } from './search-index-postgres';
+import type { Predicate } from './tenancy';
+
+const isMatch = (predicate: Predicate): boolean =>
+  predicate.column === SEARCH_PROPERTY && predicate.op === 'matches';
+
+/** The tenant the chain is scoped to: its own `eq` on the tenant column, else the actor's. */
+const tenantOf = (entity: EntityCore<unknown>, where: readonly Predicate[]): string | null => {
+  const column = entity.$tenantColumn;
+  if (column === null) return null;
+  const named = where.find((each) => each.column === column && each.op === 'eq');
+  if (typeof named?.value === 'string') return named.value;
+  return tryUseContext()?.actor.orgId ?? null;
+};
+
+/** The single key a hit's id is read back by; a composite key has no `in` an index id can name. */
+const keyOf = (entity: EntityCore<unknown>): string => {
+  const [key, ...rest] = entity.$primaryKey;
+  if (key === undefined || rest.length > 0) {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `search of ${entity.$name} through an external index needs a single-column primary key; it has ${entity.$primaryKey.length}`,
+      fix: 'installSearchIndex(postgresSearchIndex()) — the built-in index matches inside the statement, whatever the key',
+    });
+  }
+  return key;
+};
+
+/** `args` with every `matches` predicate replaced by the ids the installed index answers. */
+const resolved = async (entity: EntityCore<unknown>, args: FindManyArgs): Promise<FindManyArgs> => {
+  const where = args.where ?? [];
+  const index = searchIndex();
+  if (answersInStatement(index)) return args;
+  const tenant = tenantOf(entity, where);
+  const swapped: Predicate[] = [];
+  for (const predicate of where) {
+    if (!isMatch(predicate)) {
+      swapped.push(predicate);
+      continue;
+    }
+    const hits = await index.query({
+      entity: entity.$name,
+      tenant,
+      term: String(predicate.value ?? ''),
+      limit: MAX_PAGE_SIZE,
+    });
+    swapped.push({ column: keyOf(entity), op: 'in', value: hits.map((hit) => hit.id) });
+  }
+  return { ...args, where: swapped };
+};
+
+const searching = (args: FindManyArgs | undefined): boolean => args?.where?.some(isMatch) === true;
+
+/**
+ * `repo` with every read that takes a chain's arguments routed through `resolved` — only when the
+ * chain searched, so a read with no `.search()` reaches the repository exactly as before.
+ */
+export const searchedRepo = <Row>(entity: EntityCore<Row>, repo: Repo<Row>): Repo<Row> => {
+  const core = entity as EntityCore<unknown>;
+  const series = repo.series;
+  return {
+    ...repo,
+    findMany: async (args) =>
+      repo.findMany(searching(args) ? await resolved(core, args ?? {}) : args),
+    count: async (args) => repo.count(searching(args) ? await resolved(core, args ?? {}) : args),
+    countBy: async (column, args) =>
+      repo.countBy(column, searching(args) ? await resolved(core, args ?? {}) : args),
+    aggregate: async (fn, column, args) =>
+      repo.aggregate(fn, column, searching(args) ? await resolved(core, args ?? {}) : args),
+    approximateCount: async (args) =>
+      repo.approximateCount(searching(args) ? await resolved(core, args ?? {}) : args),
+    ...(series === undefined
+      ? {}
+      : {
+          series: async (spec, args) =>
+            series.call(repo, spec, searching(args) ? await resolved(core, args ?? {}) : args),
+        }),
+  };
+};

package/src/search-written-rows.ts

@@ -0,0 +1,36 @@
+// The rows a delete or a filtered write touched, handed up to the search mirror. A driver hands
+// them over only while `collectWrittenRows` runs — the mirror opens it for a searchable entity
+// under an external index, and nowhere else — so every other write sends no `returning *`.
+
+import { asyncContext } from '@ultimat3/core';
+
+/** What one write answered: its rows, or nothing — a store that cannot say which rows it touched. */
+interface WrittenRows {
+  rows: unknown[] | undefined;
+}
+
+const collecting = asyncContext<WrittenRows>('the search index write path');
+
+/**
+ * The sink a driver hands a write's rows to, or `undefined` when nobody asked — the one check a
+ * driver pays per delete and filtered write. A driver that holds the rows anyway calls it too.
+ */
+export const writtenRowsSink = (): ((rows: readonly unknown[]) => void) | undefined => {
+  const open = collecting.get();
+  if (open === undefined) return undefined;
+  return (rows) => {
+    open.rows = [...(open.rows ?? []), ...rows];
+  };
+};
+
+/**
+ * Run one write and answer what it returned plus the rows its driver handed over. `rows` is
+ * `undefined` when the driver handed none — a custom store's raw update, which reports a count.
+ */
+export const collectWrittenRows = async <T>(
+  write: () => Promise<T>,
+): Promise<{ readonly result: T; readonly rows: readonly unknown[] | undefined }> => {
+  const open: WrittenRows = { rows: undefined };
+  const result = await collecting.run(open, write);
+  return { result, rows: open.rows };
+};