@ultimat3/entity 30.9.0 → 31.0.0

package/src/driver-write-scope.ts

@@ -0,0 +1,107 @@
+// Single responsibility: the two write-side guards a custom store cannot be trusted with. The rows a
+// store hands back from a write are checked against the tenants the write named — a Mongo-style
+// upsert answering the STORED document of a global unique hands over another tenant's row — and a
+// same-tenant reference is judged by memory's own judge, over targets the kit looked up itself.
+
+import { keyOf } from './batch-read';
+import { kindOf, valueAt } from './cursor';
+import { describeReferences } from './describe';
+import { driverRowOutOfScope } from './driver-errors';
+import type { DriverRepo } from './driver-kit-types';
+import type { EntityCore } from './entity';
+import { type MemoryTables, sameTenantJudge } from './memory-same-tenant';
+import { getEntity } from './registry';
+import { assertRowTenant } from './tenancy';
+
+/** How the kit reaches another entity's raw store in the same driver. */
+export type RawFor = <R>(entity: EntityCore<R>) => DriverRepo<R>;
+
+const cell = (entity: EntityCore, property: string, value: unknown): string =>
+  keyOf(kindOf(entity, property) ?? '', value);
+
+/**
+ * Every returned row names a tenant one of the WRITTEN rows named — or, where a written row named
+ * none, passes the actor check `assertRowTenant` applies. Refused whole, never filtered.
+ */
+export const assertWrittenInScope = <Row>(
+  driverName: string,
+  entity: EntityCore<Row>,
+  operation: string,
+  written: readonly Row[],
+  returned: readonly Row[],
+): readonly Row[] => {
+  const column = entity.$tenantColumn;
+  if (column === null) return returned;
+  const own = entity as EntityCore;
+  const named = written.map((row) => valueAt(row, column));
+  const allowed = new Set(
+    named
+      .filter((value) => value !== null && value !== undefined)
+      .map((value) => cell(own, column, value)),
+  );
+  const anyUnnamed = named.some((value) => value === null || value === undefined);
+  for (const row of returned) {
+    const value = valueAt(row, column);
+    if (value !== null && value !== undefined && allowed.has(cell(own, column, value))) continue;
+    if (anyUnnamed) {
+      assertRowTenant(entity.$name, column, operation, row);
+      continue;
+    }
+    throw driverRowOutOfScope(driverName, entity.$name, operation, column);
+  }
+  return returned;
+};
+
+/** The properties holding a same-tenant reference — a patch naming one has to be judged. */
+export const sameTenantProperties = <Row>(entity: EntityCore<Row>): ReadonlySet<string> =>
+  entity.$tenantColumn === null
+    ? new Set()
+    : new Set(
+        describeReferences(entity.$name, Object.entries(entity.$columns))
+          .filter((edge) => edge.sameTenant !== null)
+          .map((edge) => edge.property),
+      );
+
+/**
+ * `sameTenantJudge` over a table of targets fetched first: each referenced value is read from the
+ * target's store UNSCOPED — the judge has to find a target in another tenant to refuse it — and the
+ * judge then answers exactly as it does for the memory driver (`X_DB_FOREIGN_KEY_VIOLATION`).
+ */
+export const sameTenantReferences = <Row>(entity: EntityCore<Row>, rawFor: RawFor) => {
+  const judge = (tables: MemoryTables) => sameTenantJudge(entity, tables);
+  return async (rows: readonly Row[]): Promise<void> => {
+    if (entity.$tenantColumn === null || rows.length === 0) return;
+    const edges = describeReferences(entity.$name, Object.entries(entity.$columns)).filter(
+      (edge) => edge.sameTenant !== null,
+    );
+    if (edges.length === 0) return;
+    const tables: MemoryTables = new Map();
+    for (const edge of edges) {
+      const target = getEntity(edge.targetEntity)?.core;
+      if (target === undefined || target.$tenantColumn === null) continue;
+      const values = [
+        ...new Set(
+          rows
+            .map((row) => valueAt(row, edge.property))
+            .filter((value) => value !== null && value !== undefined),
+        ),
+      ];
+      if (values.length === 0) continue;
+      const where = [{ column: edge.targetProperty, op: 'in' as const, value: values }];
+      const orderBy = target.$primaryKey.map((column) => ({ column, direction: 'asc' as const }));
+      const plan = { entity: target.$name, where, orderBy, limit: values.length };
+      const found = await rawFor(target).select({ plan, after: undefined, limit: values.length });
+      const prior = tables.get(target.$name);
+      tables.set(target.$name, {
+        entity: target,
+        find: (property, value) =>
+          found.find(
+            (row) =>
+              cell(target, property, valueAt(row, property)) === cell(target, property, value),
+          ) ?? prior?.find(property, value),
+      });
+    }
+    const verdict = judge(tables);
+    for (const row of rows) verdict(row, rows);
+  };
+};

package/src/entity-error.ts

@@ -49,6 +49,10 @@ export const ENTITY_ERROR_CODES = [
   'X_ENTITY_RETAIN_UNINDEXED',
   'X_ENTITY_COUNTS_INVALID',
   'X_ENTITY_READ_ONLY',
+  'X_DRIVER_UNSUPPORTED',
+  'X_DRIVER_CAPABILITY_MISSING',
+  'X_DRIVER_ROW_OUT_OF_SCOPE',
+  'X_ENTITY_PARTITION_INVALID',
 ] as const;
 
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
@@ -93,6 +97,12 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   X_ENTITY_COUNTS_INVALID:
     'references(…, { countedIn }) names no integer of its parent, or is no key to its primary key',
   X_ENTITY_READ_ONLY: 'a read-only entity was asked to write a row',
+  X_DRIVER_UNSUPPORTED: 'a custom driver was asked for a capability it does not declare',
+  X_DRIVER_CAPABILITY_MISSING:
+    'a custom driver declares a capability its raw repo does not implement',
+  X_DRIVER_ROW_OUT_OF_SCOPE: 'a custom driver returned a row outside the plan it was given',
+  X_ENTITY_PARTITION_INVALID:
+    'entity({ partitionBy }) declares a partitioning Postgres cannot build',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the

package/src/entity.ts

@@ -7,6 +7,7 @@ import type { IndexMethod } from '@ultimat3/db';
 import type { Schema } from '@ultimat3/schema';
 import { assertAppendOnlyColumns } from './append-only';
 import { assertTableName, bindColumn, columnName, moneyColumns } from './column';
+import { declaredIndexOf } from './declared-index';
 import {
   assertNotRetired,
   assertScan,
@@ -26,6 +27,7 @@ import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
 import { describeLifecycle, lifecycleHistory } from './lifecycle';
+import { type PartitionInit, partitionOf } from './partition';
 import { assertReadOnly } from './read-only';
 import { recordProjection } from './record-projection';
 import type { EntityDescription, ReferenceDescription } from './registry';
@@ -38,6 +40,7 @@ import { sealedInView } from './sealed-errors';
 import type { SearchInit, SearchSource, SearchVector } from './search';
 import { searchVectorOf } from './search';
 import { resolveTenantColumn } from './tenancy';
+import { coveredByTenantIndex, tenantIndexOf, withoutDerivedDuplicate } from './tenant-index';
 import type { AnyColumn, ColumnMap, IndexDef, RowOf, WireRow } from './types';
 import type { EntityView } from './view';
 import { viewFor } from './view';
@@ -125,6 +128,12 @@ export interface EntityInit<C extends ColumnMap> {
   readonly retain?: RetainInit<keyof C & string>;
   /** Every row change recorded into `<table>_history` by trigger (`history.ts`, `$history`). */
   readonly history?: HistoryInit;
+  /**
+   * Range-partitioned by a `timestamp()`/`date()` in the primary key, one partition per `interval`
+   * (`partition.ts`). `x db gen` writes `partition by range` and the first partitions; a scheduled
+   * maintenance run creates `ahead` more and drops what `retain` expired. Never beside `retain`.
+   */
+  readonly partitionBy?: PartitionInit<keyof C & string>;
   /** Set by `history.ts` on the history entity it declares: the parent's name. Never by hand. */
   readonly historyOf?: string;
 }
@@ -307,6 +316,7 @@ export const entity = <const C extends ColumnMap>(
       const physical = [
         meta.kind === 'money' ? moneyColumns(property, meta).minor : columnName(property, meta),
       ];
+      if (coveredByTenantIndex(physical[0] ?? '', tenant, meta.unique)) return [];
       return [
         {
           name: indexName(name, table, physical, meta.unique),
@@ -315,58 +325,9 @@ export const entity = <const C extends ColumnMap>(
         },
       ];
     }),
-    ...(init.indexes ?? []).map((index) => {
-      const columns = index.on.map((property) => resolve([property]));
-      const unique = index.unique === true;
-      // `on: []` is type-legal and names nothing: the generated DDL would be `on "posts" ()`, a
-      // syntax error one migration later. Refused where it was written instead.
-      if (columns.length === 0) {
-        throw invariantViolated(name, 'index', 'an index must name at least one column');
-      }
-      const where = index.where?.(columnsExpr).toSql(resolve) ?? null;
-      if (index.where !== undefined && where === null) {
-        throw invariantViolated(
-          name,
-          'index',
-          'a partial index predicate must be expressible in SQL; a JS predicate cannot be one',
-        );
-      }
-      // Two rules Postgres has that a declaration can break, refused where the author wrote it.
-      // `@ultimat3/db` refuses both again at `createIndex` — that is not a duplicate, it is the
-      // guard for a description nobody built here — but its refusal lands at `x db gen` or, if a
-      // migration was already written, inside `ROLE=migrate` as the server's own syntax error with
-      // none of the entity's words in it.
-      if (index.using !== undefined && index.using !== 'btree') {
-        if (unique) {
-          throw invariantViolated(
-            name,
-            'index',
-            `the index on (${columns.join(', ')}) is unique and ${index.using}; ` +
-              `Postgres has no unique ${index.using} index — drop unique, or drop using`,
-          );
-        }
-        if (index.order !== undefined) {
-          throw invariantViolated(
-            name,
-            'index',
-            `the index on (${columns.join(', ')}) is ${index.using} and ${index.order}; ` +
-              'only a btree orders its keys — drop order, or drop using',
-          );
-        }
-      }
-      return {
-        name: indexName(name, table, columns, unique, index.order, where, index.using),
-        columns,
-        unique,
-        ...(index.order === undefined ? {} : { order: index.order }),
-        ...(where === null ? {} : { where }),
-        // Absent stays absent: `btree` written out would be a field every existing snapshot lacks,
-        // and `indexMethodOf` reads the two the same way precisely so nothing regenerates.
-        ...(index.using === undefined || index.using === 'btree' ? {} : { using: index.using }),
-        // How it is BUILT, so not part of the name: `true` or absent, like `appendOnly`.
-        ...(index.concurrently === true ? { concurrently: true as const } : {}),
-      };
-    }),
+    ...(init.indexes ?? []).map((index) =>
+      declaredIndexOf(index, { name, table, resolve, columns: columnsExpr }),
+    ),
     // The one index nobody declared and every search needs. Through the SAME `IndexInit` path a
     // hand-written `using: 'gin'` takes — `indexName` gives it the method discriminator, so it can
     // never collide with a btree an author declares on the same column.
@@ -381,10 +342,34 @@ export const entity = <const C extends ColumnMap>(
           },
         ]),
   ];
+  // After every other index, so one that already starts with `(tenant, pk)` is seen (`tenant-index.ts`).
+  const physicalKey = primaryKey.map((property) => resolve([property]));
+  const [tenantIndex] = tenantIndexOf({
+    entityName: name,
+    table,
+    tenant,
+    primaryKey: physicalKey,
+    plainView: init.view != null && init.view.materialized !== true,
+    covering: [
+      ...declared.filter((index) => index.where == null && index.using === undefined),
+      ...invariants.filter((inv) => inv.kind === 'unique' && inv.where == null),
+    ].map((each) => each.columns),
+  });
   // A foreign key's own index named again in `indexes` is one index, not two (`index-identity.ts`).
-  const indexes = distinctIndexes(declared);
+  const indexes = distinctIndexes(
+    tenantIndex === undefined ? declared : [...declared, tenantIndex],
+  );
 
   const retain = retainOf(name, init.retain, entries, indexes, appendOnly);
+  const partition = partitionOf(name, init.partitionBy, {
+    table,
+    columns: entries,
+    primaryKey,
+    indexes,
+    uniques: invariants.filter((inv) => inv.kind === 'unique').map((inv) => inv.columns),
+    retain: init.retain !== undefined,
+    view: init.view != null,
+  });
   const sealed = sealedFields({ $name: name, $table: table, $columns: init.columns });
   assertSealedDeclaration({
     name,
@@ -411,7 +396,7 @@ export const entity = <const C extends ColumnMap>(
       columns: entries,
       primaryKey,
       invariants,
-      indexes,
+      indexes: withoutDerivedDuplicate(table, physicalKey, tenantIndex, indexes),
       tags,
       cacheTag,
       softDelete,
@@ -424,6 +409,7 @@ export const entity = <const C extends ColumnMap>(
       readOnly: init.readOnly,
       view: viewQuery,
       lifecycle: describeLifecycle(core as EntityCore, retain, init.historyOf),
+      partition,
     });
   assertNotRetired(name, entries, init.retired);
   const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);

package/src/enum-column.ts

@@ -14,6 +14,14 @@ import type { ColumnMeta, EnumeratedColumn } from './types';
  * transaction on older servers.
  */
 export const enumerated = <const V extends readonly string[]>(values: V): EnumeratedColumn<V> => {
+  // An empty set renders `x in ()`, which `x db migrate` dies on with 42601 — refused here instead.
+  if (values.length === 0) {
+    refuseColumn(
+      'enum',
+      'the set of allowed values is empty — no row could ever hold this column',
+      "enumerated(['draft', 'published']) — declare at least one value; a column with no legal value is a column to delete",
+    );
+  }
   const allowed = new Set<string>(values);
   const parse = (value: unknown): V[number] =>
     typeof value === 'string' && allowed.has(value)

package/src/index.ts

@@ -1,5 +1,12 @@
 // The public surface of @ultimat3/entity. Explicit, never `export *`.
 
+// The `entity.*` payloads are core's (the bus is tier 0); re-exported, never a second shape.
+export type {
+  EntityBulkEvent,
+  EntityCrossTenantEvent,
+  EntityRowEvent,
+  EntityRowOp,
+} from '@ultimat3/core';
 /** Re-exported so an `entity` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
@@ -32,10 +39,11 @@ export type { Counter } from './counter';
 export { countersOf, describeCounter } from './counter';
 // `crossTenantReason` stays internal: an app that could read the flag would have a second way to
 // reason about tenant scope — branch on it — next to the one way, which is entering the scope.
-export { CROSS_TENANT_SCOPE, crossTenant, setCrossTenantObserver } from './cross-tenant';
+export { CROSS_TENANT_SCOPE, crossTenant } from './cross-tenant';
+// Leaves, so a reader of a row's key (`@ultimat3/jobs`' reindex sweep) skips `./adapter`'s driver kit.
+export { kindOf } from './cursor';
 export type { Database, DatabaseOptions, Driver, EntitySet } from './database';
 export { database, defaultDriver, memoryDriver } from './database';
-export type { DescribeInput } from './describe';
 export type { TenantColumnDescription } from './describe-tenancy';
 export { describeTenancy } from './describe-tenancy';
 export type { Entity, EntityCore, EntityInit } from './entity';
@@ -46,41 +54,24 @@ export { entity, SOFT_DELETE_COLUMN } from './entity';
 export type {
   EntityErrorCode,
   PreloadCandidate,
-  QueryLoopBatch,
-  WriteLoopBatch,
 } from './errors';
 // Every error factory this package owns, its three tenancy siblings included: `Driver` is public,
 // so a third-party driver has to be able to raise the same refusals the two shipped ones do.
 export {
-  crossTenantDenied,
   ENTITY_ERROR_CODES,
   ENTITY_ERROR_TITLES,
   EntityError,
   entityDuplicate,
   invariantViolated,
   notFound,
-  nPlusOneQuery,
-  nPlusOneWrite,
   patchEmpty,
   preloadUnknownRelation,
-  repoClientPinned,
-  tenancyActorMismatch,
   tenancyActorOrgRequired,
   tenancyRowMismatch,
-  tenancyUnscoped,
-  writeUnfiltered,
 } from './errors';
 export type { ColumnExpr, Expr, InvariantColumns, Resolve } from './expr';
 export { iff } from './expr';
 /** The two DECLARED capabilities' refusals — a third-party driver raises the same ones. */
-export type { IllegalTransition } from './feature-errors';
-export {
-  searchInMemory,
-  searchUndeclared,
-  stateConflict,
-  stateTransitionIllegal,
-  stateUndeclared,
-} from './feature-errors';
 export type { HistoryColumns, HistoryEntity, HistoryInit } from './history';
 export type { IndexInit } from './index-init';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
@@ -94,7 +85,20 @@ export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
 export { isOperator, OPERATORS } from './operator';
+// `entity({ partitionBy })`, checked at declaration (`partition.ts`); the SQL is `@ultimat3/db`'s.
+export type {
+  PartitionContext,
+  PartitionDescription,
+  PartitionInit,
+} from './partition';
+export { partitionOf } from './partition';
 export { persistedRecordTypes } from './persisted-types';
+// GDPR: the personal-data column marker and its readers (`personal-data.ts`).
+export type { PersonalDataColumn, PersonalDataEntity, PersonalDataKind } from './personal-data';
+export {
+  personalDataEntities,
+  personalDataOf,
+} from './personal-data';
 // For a change feed holding a table name and raw columns: `entityForTable` + `decodeRow` is the row
 // the app declared, money and all. Exported for `@ultimat3/realtime` (plan 101, 06 i).
 export type { PgArray } from './pg-array-literal';
@@ -154,8 +158,8 @@ export type {
   UpsertArgs,
 } from './repo';
 export type { Retain, RetainInit } from './retain';
-export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-observer';
-export { observedRepo, rowObserver, setRowObserver } from './row-observer';
+export { rowKey } from './row-key';
+export { observedRepo } from './row-observer';
 export { rowSecuritySettings } from './row-security-settings';
 export type { RecordsByKey, RecordsByType } from './rows-of';
 export { hasEntityRows, projectionsIn, rowsOf } from './rows-of';
@@ -168,14 +172,27 @@ export { sealedRepo } from './sealed-repo';
 // `SEARCH_PROPERTY` is what a `matches` predicate names, which a hand-built `QueryPlan` needs.
 export type { SearchInit, SearchLanguage, SearchSource, SearchVector } from './search';
 export {
-  DEFAULT_SEARCH_COLUMN,
-  DEFAULT_SEARCH_LANGUAGE,
-  DEFAULT_SEARCH_WEIGHT,
-  isSearchLanguage,
-  isSearchWeight,
   SEARCH_LANGUAGES,
   SEARCH_WEIGHTS,
 } from './search';
+// The searchIndex port: types, the document builder, the installed index, the two shipped ones.
+export type {
+  SearchDocument,
+  SearchHit,
+  SearchIndex,
+  SearchIndexOptions,
+  SearchListEntry,
+  SearchListPage,
+  SearchListQuery,
+  SearchQuery,
+  SearchScope,
+} from './search-index';
+export { searchDocumentOf } from './search-index';
+export { searchIndex } from './search-index-installed';
+export { memorySearchIndex } from './search-index-memory';
+export type { PostgresSearchIndexOptions } from './search-index-postgres';
+export { postgresSearchIndex } from './search-index-postgres';
+export { searchVersionColumn, searchVersionOf } from './search-index-version';
 export type {
   Seed,
   SeedContext,
@@ -195,7 +212,6 @@ export {
   canMove,
   isState,
   isTerminal,
-  movesFrom,
   stateMachineOf,
 } from './state-machine';
 export type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';

package/src/memory-match.ts

@@ -23,15 +23,44 @@ import type { ColumnKind } from './types';
 const sign = <T extends number | bigint | string>(left: T, right: T): number =>
   left < right ? -1 : left > right ? 1 : 0;
 
+/**
+ * Text in CODE-POINT order, which is byte order over UTF-8 and so Postgres' `C` collation — the
+ * order `auth`'s memory adapter already keeps. JS `<` compares UTF-16 code units, which puts an
+ * astral character (lead surrogate 0xD800–0xDBFF) ahead of U+E000–U+FFFF: `'😀' < '！'` is true
+ * here and false there, so a page cut on a text key differed between dev and prod. The first
+ * differing unit decides; `codePointAt` there reads the whole character when it is a lead surrogate.
+ */
+export const byCodePoint = (left: string, right: string): number => {
+  const shorter = Math.min(left.length, right.length);
+  for (let at = 0; at < shorter; at += 1) {
+    if (left.charCodeAt(at) !== right.charCodeAt(at)) {
+      return sign(left.codePointAt(at) ?? 0, right.codePointAt(at) ?? 0);
+    }
+  }
+  return sign(left.length, right.length);
+};
+
+/**
+ * An `integer()` operand written as TEXT is the number Postgres parses it as: the parameter takes
+ * the column's type, so `id = '007'` finds row 7 there, and `===` against `7` found nothing here.
+ * Only an integer literal is read; anything else stays as written and compares as text.
+ */
+const INTEGER_TEXT = /^\s*[+-]?\d+\s*$/;
+const asInteger = (kind: ColumnKind | undefined, value: unknown): unknown =>
+  kind === 'integer' && typeof value === 'string' && INTEGER_TEXT.test(value)
+    ? Number(value)
+    : value;
+
 /**
  * Two values of one column, ordered as Postgres orders that column. `-1`, `0` or `1` — never a
  * difference, so a `bigint` pair needs no subtraction it cannot express in a `number`.
  */
 export const compareByKind = (
   kind: ColumnKind | undefined,
-  left: unknown,
-  right: unknown,
+  given: unknown,
+  operand: unknown,
 ): number => {
+  const [left, right] = [asInteger(kind, given), asInteger(kind, operand)];
   // NULL is the LARGEST value, which is what `order by` means in Postgres and what `nulls last`
   // ascending / `nulls first` descending spell out (`pg-sql.ts`'s `orderSql`, `@ultimat3/query`'s
   // `compareValues`). Two absences are equal, so the next sort key decides — without this rule a
@@ -64,7 +93,7 @@ export const compareByKind = (
   // `undefined` means the pair is not a numeric comparison, and it falls through as text.
   const numeric = numericOrder(kind !== undefined && DECIMAL_TEXT.has(kind), left, right);
   if (numeric !== undefined) return numeric;
-  return sign(String(left), String(right));
+  return byCodePoint(String(left), String(right));
 };
 
 /**
@@ -76,9 +105,10 @@ export const compareByKind = (
  */
 export const sameValueOfKind = (
   kind: ColumnKind | undefined,
-  left: unknown,
-  right: unknown,
+  given: unknown,
+  operand: unknown,
 ): boolean => {
+  const [left, right] = [asInteger(kind, given), asInteger(kind, operand)];
   if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
   // An instant handed over as ISO text is the instant it names, as Postgres parses the bound
   // parameter: `eq` against a stored `Date` compared an object to a string and matched no row.

package/src/memory-observed.ts

@@ -1,10 +1,10 @@
-// Single responsibility: the memory driver's half of `@ultimat3/db`'s statement seam. Generated
+// Single responsibility: the memory driver's half of the `db.statement` event. Generated
 // tests run on this driver, so a loop it never reported was a `statements` assertion that could not
 // fail. One event per repository operation, attributed exactly as `postgresRepo` attributes its
 // statement; nothing is sent, so `text` names the operation and holds no SQL.
 
-import { tryUseContext } from '@ultimat3/core';
-import { expectedQueryLoopReason, statementObserver } from '@ultimat3/db';
+import { callerStack, instrument, subscribed, tryUseContext } from '@ultimat3/core';
+import { expectedQueryLoopReason } from '@ultimat3/db';
 import type { MemoryRepo } from './repo';
 
 /** What one operation reports: the verb `statementKind` reads, and its row count. */
@@ -48,11 +48,13 @@ const report = (
   op: string,
   verb: Reported['verb'],
   rows: number,
+  callerStack: string | undefined,
   error?: unknown,
 ): void => {
-  const observer = statementObserver();
-  if (observer === undefined) return;
-  observer.onStatement({
+  if (!subscribed('db.statement')) return;
+  // Emitted here, not through `@ultimat3/db`: nothing is sent, so no funnel sees it — this IS the
+  // memory driver's funnel, and a subscriber must not be able to tell the two drivers apart.
+  instrument('db.statement', {
     text: `${verb} ${entity}.${op} (memory driver, no SQL sent)`,
     values: [],
     // Nothing crossed a wire, and a duration made up of `Map` reads would only rank as noise.
@@ -61,6 +63,7 @@ const report = (
     ...(error === undefined ? {} : { error }),
     attribution: { entity, op },
     expected: expectedQueryLoopReason(),
+    callerStack,
   });
 };
 
@@ -86,7 +89,7 @@ const pointLookups = (): (() => boolean) => {
 
 type AnyMethod = (...args: readonly unknown[]) => Promise<unknown>;
 
-/** `repo`, each statement-shaped method reporting once it settles, as the funnels report. */
+/** `repo`, each statement-shaped method emitting once it settles, as the funnels emit. */
 export function observedMemoryRepo<Row>(entity: string, repo: MemoryRepo<Row>): MemoryRepo<Row> {
   const wrapped: Record<string, AnyMethod> = {};
   const firstInMicrotask = pointLookups();
@@ -94,26 +97,28 @@ export function observedMemoryRepo<Row>(entity: string, repo: MemoryRepo<Row>):
     const method = repo[op] as AnyMethod;
     const { verb, rows } = OPERATIONS[op];
     wrapped[op] = async (...args) => {
-      if (statementObserver() === undefined) return method(...args);
+      if (!subscribed('db.statement')) return method(...args);
       // Decided as the call is made: by the time the row is back the microtask has moved on.
       const reports = op !== 'findById' || firstInMicrotask();
       // `postgresRepo` attributes an aggregate to its function, never to `aggregate`.
       const name = op === 'aggregate' ? String(args[0]) : op;
+      // Before the `await`, as the Postgres funnel reads it: nothing unless capture is on.
+      const stack = callerStack();
       let answer: unknown;
       try {
         answer = await method(...args);
       } catch (error) {
-        if (reports) report(entity, name, verb, 0, error);
+        if (reports) report(entity, name, verb, 0, stack, error);
         throw error;
       }
-      if (reports) report(entity, name, verb, rows(answer));
+      if (reports) report(entity, name, verb, rows(answer), stack);
       return answer;
     };
   }
   for (const op of LOCKS) {
     const method = repo[op] as AnyMethod;
     wrapped[op] = async (...args) => {
-      report(entity, op, 'select', 1);
+      report(entity, op, 'select', 1, callerStack());
       return method(...args);
     };
   }