@ultimat3/entity 29.3.2 → 30.0.0

package/src/entity.ts

@@ -4,32 +4,43 @@
 // this one call.
 
 import type { IndexMethod } from '@ultimat3/db';
-import { describeValue, type Schema } from '@ultimat3/schema';
+import type { Schema } from '@ultimat3/schema';
 import { assertAppendOnlyColumns } from './append-only';
-import { entityNow } from './clock';
 import { assertTableName, bindColumn, columnName, moneyColumns } from './column';
-import { newId } from './columns';
-import { describeEntity, describeReferences } from './describe';
+import {
+  assertNotRetired,
+  assertScan,
+  assertShared,
+  describeEntity,
+  describeReferences,
+} from './describe';
+import { rowParsers } from './entity-parse';
+import { parseEntityPatch } from './entity-patch';
 import { invariantViolated } from './errors';
 import type { InvariantColumns, Resolve } from './expr';
 import { invariantColumns } from './expr';
+import type { HistoryEntity, HistoryInit } from './history';
+import { distinctIndexes } from './index-identity';
 import type { IndexInit } from './index-init';
 import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
+import { describeLifecycle, lifecycleHistory } from './lifecycle';
 import { recordProjection } from './record-projection';
 import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
+import { type Retain, type RetainInit, retainOf } from './retain';
 import { rowSchema } from './row-schema';
 import { sealedFields } from './sealed';
 import { assertSealedDeclaration } from './sealed-declaration';
-import { sealedInView, sealedMissing } from './sealed-errors';
+import { sealedInView } from './sealed-errors';
 import type { SearchInit, SearchSource, SearchVector } from './search';
 import { searchVectorOf } from './search';
 import { resolveTenantColumn } from './tenancy';
-import type { AnyColumn, ColumnMap, ColumnMeta, IndexDef, RowOf, WireRow } from './types';
+import type { AnyColumn, ColumnMap, IndexDef, RowOf, WireRow } from './types';
 import type { EntityView } from './view';
 import { viewFor } from './view';
+import { type ViewInit, type ViewQuery, viewQueryOf } from './view-entity';
 
 /** Presence of this column is what makes an entity soft-deletable — not a flag. */
 export const SOFT_DELETE_COLUMN = 'deletedAt';
@@ -50,6 +61,17 @@ export interface EntityInit<C extends ColumnMap> {
    * `orgId`, so silence never means unscoped.
    */
   readonly tenant?: keyof C & string;
+  /**
+   * Why an entity with no tenant column, referencing a tenant-owned one, belongs to no tenant.
+   * Without it `x verify`'s exercise step reports `X_ENTITY_TENANT_UNDECLARED`; blank is refused.
+   */
+  readonly shared?: string;
+  /**
+   * Why this table may be read by a sequential scan: a closed catalog that stays a handful of rows.
+   * Without it `x verify`'s exercise step reports a statement no index serves (`X_QUERY_UNINDEXED`)
+   * and a reference column no index leads with; blank is refused.
+   */
+  readonly scan?: string;
   /** Composite keys only — a single key is `uuid().primaryKey()` on the column itself. */
   readonly primaryKey?: readonly (keyof C & string)[];
   /**
@@ -79,6 +101,26 @@ export interface EntityInit<C extends ColumnMap> {
    * refuses the same in raw SQL. A soft-delete, `onUpdateNow()` or state-machine column is refused.
    */
   readonly appendOnly?: boolean;
+  /**
+   * Physical columns the previous release still reads and this one does not: a rolling deploy's
+   * first half of a column drop. Delete the column from `columns` and name it here, so it leaves
+   * the row type, the projection and every insert while `x db gen` writes a marker and keeps it.
+   * Remove it from this list in the next release, and `x db gen --allow-destructive` drops it. A
+   * name, not a chain on the column: a column here has no builder left to chain from.
+   */
+  readonly retired?: readonly string[];
+  /**
+   * A relation Postgres derives rather than a table: `x db gen` emits `create [materialized] view`
+   * from `sql`, reads are the chain's (tenancy, codec, `$view`), and every write is
+   * `X_ENTITY_VIEW_READ_ONLY`. `columns` name its output columns; `primaryKey` is the read identity.
+   */
+  readonly view?: ViewInit;
+  /** Rows older than `after` by `on` are swept by `purge({ entities: 'declared' })` (`retain.ts`). */
+  readonly retain?: RetainInit<keyof C & string>;
+  /** Every row change recorded into `<table>_history` by trigger (`history.ts`, `$history`). */
+  readonly history?: HistoryInit;
+  /** Set by `history.ts` on the history entity it declares: the parent's name. Never by hand. */
+  readonly historyOf?: string;
 }
 
 /**
@@ -99,6 +141,14 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   readonly $softDelete: boolean;
   /** `entity({ appendOnly: true })`: update and delete are refused, here and by the table. */
   readonly $appendOnly: boolean;
+  /** `entity({ retain })`, checked; `null` when rows are kept. */
+  readonly $retain: Retain | null;
+  /** `entity({ history: true })`: the history entity, registered beside this one; else `null`. */
+  readonly $history: HistoryEntity | null;
+  /** On a history entity, its parent's name; `null` everywhere else. */
+  readonly $historyOf: string | null;
+  /** `entity({ view })`: the query a view is derived by, `null` on a table. Writes are refused. */
+  readonly $viewQuery: ViewQuery | null;
   /** Property key of the tenant column, or `null`. Presence is what turns tenancy on. */
   readonly $tenantColumn: string | null;
   /**
@@ -124,6 +174,8 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   $tagFor(id: string): string;
   /** Fills declared defaults, then validates every column. Throws on a bad value. */
   $parse(value: unknown): Row;
+  /** `$parse` for the columns a patch names: no default fills an absent one. `entity-patch.ts`. */
+  $parsePatch<Patch>(patch: Patch): Patch;
   /**
    * `const PostView = posts.$view(['id', 'title'])` — the projection an action names as its
    * `output`. An unknown key is a compile error, and a declaration error for a JS caller.
@@ -155,28 +207,27 @@ export type Entity<Row, C extends ColumnMap = ColumnMap> = Omit<EntityCore<Row,
 
 const MONEY_PARTS = new Set(['minor', 'currency']);
 
-const defaultValue = (meta: ColumnMeta): unknown => {
-  const declared = meta.default;
-  if (declared === undefined) return undefined;
-  if (declared.kind === 'value') return declared.value;
-  return declared.by === 'uuid-v7' ? newId() : entityNow();
-};
-
 export const entity = <const C extends ColumnMap>(
   name: string,
   init: EntityInit<C>,
 ): Entity<RowOf<C>, C> => {
   type Row = RowOf<C>;
   const entries: readonly (readonly [string, AnyColumn])[] = Object.entries(init.columns);
-  for (const [property, column] of entries) bindColumn(column, name, property);
+  // Resolved before the bindings, because a binding carries the tenant's PHYSICAL column: a
+  // `references()` on another entity reads it through this column's binding at describe time.
+  const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
+  const tenantMeta = tenantColumn === null ? undefined : init.columns[tenantColumn]?.$meta;
+  const tenant = tenantMeta === undefined ? null : columnName(tenantColumn ?? '', tenantMeta);
 
   // Both branches. The declared table was checked and the fallback — which is every entity that
   // does not rename its table — was not, so an entity NAME closed the identifier in the same way a
   // column name could: `entity('t" (x int); drop table u; --')` emitted that `drop table` verbatim.
   const table = assertTableName(name, init.table ?? name);
+  assertShared(name, table, init.shared, tenantColumn);
+  assertScan(name, init.scan);
+  for (const [property, column] of entries) bindColumn(column, name, property, tenant, table);
   const cacheTag = `entity:${name}`;
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
-  const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
   const appendOnly = init.appendOnly === true;
   if (appendOnly) assertAppendOnlyColumns(name, entries, SOFT_DELETE_COLUMN);
 
@@ -303,6 +354,8 @@ export const entity = <const C extends ColumnMap>(
         // 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 } : {}),
       };
     }),
     // The one index nobody declared and every search needs. Through the SAME `IndexInit` path a
@@ -319,29 +372,10 @@ export const entity = <const C extends ColumnMap>(
           },
         ]),
   ];
-  /**
-   * A foreign key already indexes its column; naming it again in `indexes` is not two indexes.
-   *
-   * On the WHOLE definition and not on the name. With the discriminator above the two rules agree
-   * exactly, so this is not a behaviour change on its own — it is which one FAILS LOUDLY if the
-   * naming is ever weakened again. Matching on the name drops the second index in silence, which
-   * is how two different partial indexes became one for three majors; matching on the definition
-   * keeps both, and two `create index` statements sharing a name is `42P07` on the next migration.
-   */
-  const identity = (index: IndexDef): string =>
-    [
-      index.name,
-      index.columns.join(','),
-      index.unique,
-      index.order ?? '',
-      index.where ?? '',
-      index.using ?? '',
-    ].join('|');
-  const indexes: readonly IndexDef[] = declared.filter(
-    (index, position) =>
-      declared.findIndex((other) => identity(other) === identity(index)) === position,
-  );
+  // A foreign key's own index named again in `indexes` is one index, not two (`index-identity.ts`).
+  const indexes = distinctIndexes(declared);
 
+  const retain = retainOf(name, init.retain, entries, indexes, appendOnly);
   const sealed = sealedFields({ $name: name, $table: table, $columns: init.columns });
   assertSealedDeclaration({
     name,
@@ -352,6 +386,11 @@ export const entity = <const C extends ColumnMap>(
     invariants,
   });
   const sealedKeys = new Set(sealed.map((field) => field.property));
+  const viewQuery = viewQueryOf(name, init.view, {
+    appendOnly,
+    indexes,
+    sealed: [...sealedKeys],
+  });
   /** The columns that leave the server: every one that is not sealed. */
   const wireEntries = entries.filter(([property]) => !sealedKeys.has(property));
 
@@ -370,69 +409,16 @@ export const entity = <const C extends ColumnMap>(
       tenantColumn,
       search,
       appendOnly,
+      retired: init.retired,
+      shared: init.shared,
+      scan: init.scan,
+      view: viewQuery,
+      lifecycle: describeLifecycle(core as EntityCore, retain, init.historyOf),
     });
+  assertNotRetired(name, entries, init.retired);
   const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);
 
-  const parse = (value: unknown): Row => {
-    if (typeof value !== 'object' || value === null) {
-      // `describeValue`, never `String(value)`: this message is a `$parse` failure, which reaches
-      // the caller and the log line — and the whole row is the last value in the framework that
-      // may be echoed there. Same renderer as the column builders (`columns.ts`) use.
-      throw invariantViolated(name, 'row', `expected an object, got ${describeValue(value)}`);
-    }
-    const input = value as Readonly<Record<string, unknown>>;
-    const row: Record<string, unknown> = {};
-    for (const [property, column] of entries) {
-      // `=== undefined`, never `??`: an explicit `null` is the caller CLEARING a nullable column,
-      // and `??` read it as absence and wrote the column's declared default straight back — so
-      // `update(id, { status: null })` reported success and stored `'draft'`, with nothing on any
-      // surface to say otherwise. A present `undefined` still means absence, which is what a
-      // spread of an omitted optional key produces and is the shape every existing caller has.
-      const raw = input[property];
-      const given = raw === undefined ? defaultValue(column.$meta) : raw;
-      if (given === undefined || given === null) {
-        if (column.$meta.notNull) {
-          // A required sealed column ABSENT from a row is nearly always a spread of a repository
-          // row, which does not enumerate it — so the refusal names that, and the rewrite.
-          throw given === undefined && sealedKeys.has(property)
-            ? sealedMissing(name, property)
-            : invariantViolated(name, property, 'is required and has no default');
-        }
-        row[property] = null;
-        continue;
-      }
-      row[property] = column.$parse(given);
-    }
-    // Every property was validated by its own column above, so the shape is the derived row.
-    return row as Row;
-  };
-
-  /**
-   * The row as `$schema` validates it: the sealed columns are neither required nor returned, so a
-   * handler's row — which holds their plaintext — parses to a value that does not.
-   */
-  const parseWire = (value: unknown): WireRow<Row, C> => {
-    if (sealedKeys.size === 0) return parse(value) as WireRow<Row, C>;
-    if (typeof value !== 'object' || value === null) {
-      throw invariantViolated(name, 'row', `expected an object, got ${describeValue(value)}`);
-    }
-    const input = value as Readonly<Record<string, unknown>>;
-    const row: Record<string, unknown> = {};
-    for (const [property, column] of wireEntries) {
-      const raw = input[property];
-      const given = raw === undefined ? defaultValue(column.$meta) : raw;
-      if (given === undefined || given === null) {
-        if (column.$meta.notNull) {
-          throw invariantViolated(name, property, 'is required and has no default');
-        }
-        row[property] = null;
-        continue;
-      }
-      row[property] = column.$parse(given);
-    }
-    // Every wire property was validated by its own column, and no sealed one was copied.
-    return row as WireRow<Row, C>;
-  };
+  const { parse, parseWire } = rowParsers<Row, WireRow<Row, C>>(name, entries, sealedKeys);
 
   const schema = rowSchema<WireRow<Row, C>>(
     { name, table, primaryKey, persist: init.persist === true, sealed: [...sealedKeys] },
@@ -450,7 +436,8 @@ export const entity = <const C extends ColumnMap>(
     $tags: tags,
     $cacheTag: cacheTag,
     $softDelete: softDelete,
-    $appendOnly: appendOnly,
+    $appendOnly: appendOnly || init.historyOf !== undefined,
+    $viewQuery: viewQuery,
     $tenantColumn: tenantColumn,
     $search: search,
     $schema: schema,
@@ -460,6 +447,7 @@ export const entity = <const C extends ColumnMap>(
     },
     $tagFor: (id) => `${cacheTag}:${id}`,
     $parse: parse,
+    $parsePatch: (patch) => parseEntityPatch(name, init.columns, patch),
     $view: <K extends keyof Row & string>(keys: readonly K[]) => {
       // Before the view exists: a view is an `output`, and a sealed column is in none.
       const named = keys.find((key) => sealedKeys.has(key));
@@ -469,6 +457,11 @@ export const entity = <const C extends ColumnMap>(
     $assert: (row) => assertInvariants(name, invariants, row),
     $describe: describe,
     $references: references,
+    $retain: retain,
+    // Assigned below, once this entity is registered: the history entity is declared after it.
+    $history: null,
+    // A history table is append-only to every repository: its rows are its trigger's to write.
+    $historyOf: init.historyOf ?? null,
   };
 
   registerEntity({
@@ -480,6 +473,10 @@ export const entity = <const C extends ColumnMap>(
     describe,
     references,
   });
+  const { history, historyOf } = init;
+  const lifecycle = { name, table, columns: init.columns, primaryKey, tenantColumn, appendOnly };
+  const historyEntity = lifecycleHistory({ ...lifecycle, history, historyOf });
+  if (historyEntity !== null) Object.assign(core, { $history: historyEntity });
   // The columns land on the entity itself so `orgs.id` is a column reference; every framework
   // member is `$`-prefixed, which is why a column may be called `name`.
   // `$schema` is restated so the result carries its real output type; it is the same object.

package/src/errors.ts

@@ -183,6 +183,14 @@ export const repoClientPinned = (entityName: string): EntityError =>
     fix: `setDbClient(client) at boot and build the repository with no client: — postgresDriver() then resolves the open transaction through db() — or run this call outside withTransaction()`,
   });
 
+/** `testDriver()`: the transaction began on one store and `setDbClient` now names the other. */
+export const testDriverClientChanged = (entityName: string, began: string): EntityError =>
+  new EntityError({
+    code: 'X_TEST_DRIVER_CLIENT_CHANGED',
+    cause: `${entityName} was called inside a transaction that began on ${began}, and setDbClient has since ${began === 'memory' ? 'installed a client' : 'cleared the client'} — following it would split one transaction's writes across two stores`,
+    fix: 'beforeAll(() => setDbClient(client)); afterAll(() => setDbClient(undefined));   # outside every transactor().run / withTransaction scope',
+  });
+
 export const notFound = (entityName: string, id: string): EntityError =>
   new EntityError({
     code: 'X_NOT_FOUND',

package/src/history-actor.ts

@@ -0,0 +1,22 @@
+// Single responsibility: who a history row names. The history trigger reads `x.actor` and
+// `x.request` from the WRITE'S transaction; this sets them, once per transaction, before the first
+// repository write to an entity that keeps history. No transaction, nothing set: the trigger then
+// records `null`, never a guess.
+
+import { tryUseContext } from '@ultimat3/core';
+import { ACTOR_SETTING, currentTx, type DbTx, REQUEST_SETTING, setLocal } from '@ultimat3/db';
+
+const stamped = new WeakSet<DbTx>();
+
+/** Before a write to `entity` on the ambient connection. A pinned repository is never stamped. */
+export async function stampHistoryActor(
+  entity: { readonly $history: unknown },
+  pinned: boolean,
+): Promise<void> {
+  if (entity.$history === null || pinned) return;
+  const tx = currentTx();
+  const ctx = tryUseContext();
+  if (tx === undefined || ctx === undefined || stamped.has(tx)) return;
+  await setLocal(tx, { [ACTOR_SETTING]: ctx.actor.id, [REQUEST_SETTING]: ctx.requestId });
+  stamped.add(tx);
+}

package/src/history.ts

@@ -0,0 +1,86 @@
+// Single responsibility: `entity({ history: true })`'s history table as a REAL entity, registered
+// beside its parent — so `$tenantColumn` holds, row security emits its policy, the tenant proof and
+// subject data walk it, and a read of it is an ordinary tenant-scoped, cursor-paged read.
+
+import { t } from '@ultimat3/schema';
+import { columnName, makeColumn } from './column';
+import { text, timestamp, uuid } from './columns';
+import { json } from './columns-data';
+import type { Entity } from './entity';
+import { entity } from './entity';
+import { invariantViolated } from './errors';
+import type { AnyColumn, ColumnMap, RowOf } from './types';
+
+/** `history: true`, or with a retention window of its own. No default window, here or anywhere. */
+export type HistoryInit = true | { readonly retain?: { readonly after: string } };
+
+/** The parent facts the history table is built from. */
+export interface HistoryParent {
+  readonly name: string;
+  readonly table: string;
+  readonly columns: ColumnMap;
+  readonly primaryKey: readonly string[];
+  readonly tenantColumn: string | null;
+}
+
+/** A row image: the stored row as `to_jsonb` spells it, physical names. Any JSON object. */
+const image = () => json(t.record(t.json())).nullable();
+
+/** Every history table's own columns; the parent's tenant column joins them at runtime. */
+const historyColumns = () => ({
+  id: uuid().primaryKey(),
+  rowId: text(),
+  op: text(),
+  at: timestamp().defaultNow(),
+  actorId: text().nullable(),
+  requestId: text().nullable(),
+  before: image(),
+  after: image(),
+});
+
+export type HistoryColumns = ReturnType<typeof historyColumns>;
+/**
+ * A history entity as a read types it. The tenant column is on the row at runtime and absent from
+ * the type: every read of it is scoped by the repository, never filtered by hand.
+ */
+export type HistoryEntity = Entity<RowOf<HistoryColumns>, HistoryColumns>;
+
+/**
+ * The tenant column, copied without its foreign key: a history row outlives an org's cascade only
+ * until its purge, and a key would cascade a delete the guard refuses.
+ */
+const tenantCopy = (column: AnyColumn): AnyColumn => {
+  const { references: _r, onDelete: _o, crossTenant: _c, countedIn: _n, ...meta } = column.$meta;
+  return makeColumn({ ...meta, tenant: true, index: true }, column.$parse, false);
+};
+
+/** The history entity of `parent`, declared now. Its name and table are the parent's `_history`. */
+export function historyEntity(parent: HistoryParent, init: HistoryInit): HistoryEntity {
+  if (parent.primaryKey.length !== 1) {
+    throw invariantViolated(
+      parent.name,
+      'history',
+      'history records a row by its single primary key, and this entity declares a composite one',
+    );
+  }
+  const tenant = parent.tenantColumn;
+  const tenantColumn = tenant === null ? undefined : parent.columns[tenant];
+  const columns = {
+    ...historyColumns(),
+    ...(tenant === null || tenantColumn === undefined
+      ? {}
+      : { [tenant]: tenantCopy(tenantColumn).column(columnName(tenant, tenantColumn.$meta)) }),
+  };
+  const after = init === true ? undefined : init.retain?.after;
+  // Typed as its fixed columns: the tenant key is a runtime name, so it cannot be in the type.
+  return entity<ColumnMap>(`${parent.name}_history`, {
+    table: `${parent.table}_history`,
+    columns,
+    historyOf: parent.name,
+    indexes: [
+      { on: [...(tenant === null ? [] : [tenant]), 'rowId', 'at'] },
+      ...(after === undefined ? [] : [{ on: ['at'] }]),
+    ],
+    ...(after === undefined ? {} : { retain: { after, on: 'at' } }),
+  }) as unknown as HistoryEntity;
+}

package/src/index-identity.ts

@@ -0,0 +1,46 @@
+// When two index declarations are ONE index. Split out of `entity.ts` at the 500-line ceiling: a
+// foreign key already indexes its column, and naming it again in `indexes` is not two indexes.
+
+import type { IndexDef } from './types';
+
+/**
+ * WHAT the index is — never how it is built. `concurrently` is left out on purpose: it changes the
+ * migration that builds an index, not the index, so a foreign key's own index and an `indexes:`
+ * entry asking for the same one concurrently are still one index (`distinctIndexes` keeps the ask).
+ */
+const identity = (index: IndexDef): string =>
+  [
+    index.name,
+    index.columns.join(','),
+    index.unique,
+    index.order ?? '',
+    index.where ?? '',
+    index.using ?? '',
+  ].join('|');
+
+/**
+ * Every declared index once, in first-declared order.
+ *
+ * On the WHOLE definition and not on the name. With the name discriminator (`index-name.ts`) the
+ * two rules agree exactly, so this is not a behaviour change on its own — it is which one FAILS
+ * LOUDLY if the naming is ever weakened again. Matching on the name drops the second index in
+ * silence, which is how two different partial indexes became one for three majors; matching on the
+ * definition keeps both, and two `create index` statements sharing a name is `42P07` on the next
+ * migration.
+ *
+ * A duplicate that asks for `concurrently: true` hands that ask to the one kept: dropping it would
+ * silently build a hot table's index inside the migration's transaction after all.
+ */
+export function distinctIndexes(declared: readonly IndexDef[]): readonly IndexDef[] {
+  return declared
+    .filter(
+      (index, position) =>
+        declared.findIndex((other) => identity(other) === identity(index)) === position,
+    )
+    .map((index) =>
+      index.concurrently !== true &&
+      declared.some((other) => other.concurrently === true && identity(other) === identity(index))
+        ? { ...index, concurrently: true as const }
+        : index,
+    );
+}

package/src/index-init.ts

@@ -26,4 +26,16 @@ export interface IndexInit<C extends ColumnMap> {
    * unique and cannot order its keys.
    */
   readonly using?: IndexMethod;
+  /**
+   * Build it with `create index concurrently`, in a migration step of its own that runs OUTSIDE a
+   * transaction — so a big, hot table keeps taking writes while the index builds. A plain `create
+   * index` holds SHARE on the table for the whole build: every insert, update and delete waits.
+   *
+   * How the index is BUILT, never what it is: not part of its name, not recorded in a snapshot,
+   * and switching it on for an existing index generates nothing. `x db gen` writes the step as
+   * `<id>_concurrently.sql` beside the migration (or as the migration, when it is the only change),
+   * marked `-- transaction: false`; an index on a table the same migration creates is still built
+   * inside that migration's transaction — the table is empty and nobody else can see it.
+   */
+  readonly concurrently?: boolean;
 }

package/src/index.ts

@@ -28,12 +28,16 @@ export {
 } from './columns';
 export type { DecimalOptions } from './columns-data';
 export { arrayOf, bigint, bytes, date, decimal, json } from './columns-data';
+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 } from './cross-tenant';
+export { CROSS_TENANT_SCOPE, crossTenant, setCrossTenantObserver } from './cross-tenant';
 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';
 export { entity, SOFT_DELETE_COLUMN } from './entity';
 // The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
@@ -77,9 +81,11 @@ export {
   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';
 export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';
+export { memoryJournal } from './memory-journal';
 // How Postgres compares two values of one column, decided by the column's declared KIND. Exported
 // because `@ultimat3/query`'s matcher and in-memory source ask the same question — and a second
 // answer there is how a live window and the database returned one read in two orders.
@@ -105,6 +111,12 @@ export type { PreloadOptions } from './preload-ceiling';
 export { MAX_PRELOADED_ROWS } from './preload-ceiling';
 export type { Preloaded, ReadBuilder, Table } from './query';
 export { tableFor } from './query';
+export type {
+  ReadAggregates,
+  SeriesOptions,
+  SeriesValueOf,
+  TimestampKeys,
+} from './read-aggregates';
 // The client projection of an entity (plan 101): record type, record key, and the brand on
 // `$schema` that lets an action or query derive its record envelope from its output schema.
 // Value-light — no Postgres driver behind any of them — so a browser store may import them here.
@@ -118,6 +130,7 @@ export type {
   InvariantDescription,
   ReferenceDescription,
   RegistryEntry,
+  SameTenantKey,
 } from './registry';
 export {
   clearRegistry,
@@ -140,8 +153,10 @@ export type {
   Tx,
   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 { rowSecuritySettings } from './row-security-settings';
 export type { RecordsByKey, RecordsByType } from './rows-of';
 export { hasEntityRows, projectionsIn, rowsOf } from './rows-of';
 // Sealed columns. `sealedFields` is what a manifest or `x doctor` reads to say which columns are
@@ -191,6 +206,10 @@ export {
   orgScoped,
   scopedPlan,
 } from './tenancy';
+// The scaffolded handle's driver under test: memory until `setDbClient` installs a client.
+export { testDriver } from './test-driver';
+export type { SeriesPoint, SeriesSpec, SeriesUnit, SeriesValue } from './time-bucket';
+export { bucketStart, SERIES_UNITS } from './time-bucket';
 export type { Move } from './transition';
 export type { TransitionObservation } from './transition-pins';
 export type {