@ultimat3/entity 30.9.0 → 31.0.0

package/src/memory-repo.ts

@@ -10,10 +10,10 @@ import { pageOf } from '@ultimat3/core';
 import { refuseAbandoned } from '@ultimat3/db';
 import { appendOnlyRepo } from './append-only';
 import { keyOf } from './batch-read';
-import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
 import { entityNow } from './clock';
 import { narrowRow } from './columns';
 import { cursorFor, kindOf, valueAt } from './cursor';
+import { projectRow } from './driver-rows';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { invariantViolated, notFound } from './errors';
 import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
@@ -29,10 +29,14 @@ import { type MemoryTables, sameTenantJudge } from './memory-same-tenant';
 import { afterCursor } from './memory-seek';
 import { StoredRows, uniqueIndex, uniqueViolation } from './memory-unique';
 import { judgeUpdate, mergedRow } from './memory-update';
+import { memoryUpsertAll } from './memory-upsert';
 import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { FindManyArgs, MemoryRepo, RepoOptions } from './repo';
+import { rowKey } from './row-key';
 import { sealedFields } from './sealed';
 import { sealedRepo } from './sealed-repo';
+import { deletionStamp } from './search-index-version';
+import { writtenRowsSink } from './search-written-rows';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
 import type { RowWrite } from './types';
@@ -51,16 +55,8 @@ export const memoryRepo = <Row>(
   /** The driver's other tables, for a same-tenant reference. Alone, this repository sees itself. */
   tables: MemoryTables = new Map(),
 ): MemoryRepo<Row> => {
-  /**
-   * A stored row's key, spelled the way `batch-read.ts` spells an id — because Postgres compares a
-   * `uuid` as a VALUE and prints it lower-cased, so `findById(UPPER)` reads the row there while
-   * `String(...)` missed it here: `null` from a read and `X_NOT_FOUND` from a write, against a row
-   * that exists, reachable from a path parameter, a client-supplied id or a legacy import.
-   */
-  const storeKey = (row: unknown): string =>
-    entity.$primaryKey
-      .map((property) => keyOf(kindOf(entity, property) ?? '', field(row, property)))
-      .join('
');
+  /** A stored row's key — `row-key.ts`, the one spelling both drivers use. */
+  const storeKey = (row: unknown): string => rowKey(entity, row);
   /** The same key, from the id a caller named rather than from a row it has in hand. */
   const idStoreKey = (id: unknown, operation: string): string =>
     keyOf(kindOf(entity, singleKeyOf(entity, operation)) ?? '', id);
@@ -105,6 +101,9 @@ export const memoryRepo = <Row>(
   const changed = memoryLifecycle(entity as EntityCore, tables);
   const judgeReferences = sameTenantJudge(entity, tables);
   const locks = memoryLocks();
+  /** The stamp a soft delete writes: `deletedAt`, and a searchable entity's version advanced. */
+  const softDeletion = () =>
+    deletionStamp(entity as EntityCore<unknown>, SOFT_DELETE_COLUMN, entityNow());
   /** One guard for every write, as `postgresRepo`'s `writing()`: async, so a refusal rejects. */
   const writing =
     <A extends unknown[], R>(body: (...args: A) => Promise<R>) =>
@@ -113,15 +112,21 @@ export const memoryRepo = <Row>(
       return body(...args);
     };
 
-  const rowsOf = (plan: QueryPlan, args: FindManyArgs): Row[] => {
-    const visible = (row: Row): boolean =>
+  /** Whether a soft-deleted row is in the read: hidden unless the caller asked to include it. */
+  const visibleTo =
+    (args: FindManyArgs) =>
+    (row: Row): boolean =>
       !entity.$softDelete ||
       args.includeDeleted === true ||
       field(row, SOFT_DELETE_COLUMN) === null ||
       field(row, SOFT_DELETE_COLUMN) === undefined;
+  const matchesPlan = (plan: QueryPlan, row: Row): boolean =>
+    plan.where.every((predicate) => matchesPredicate(entity, row, predicate));
+
+  const rowsOf = (plan: QueryPlan, args: FindManyArgs): Row[] => {
     return [...rows.values()]
-      .filter((row) => plan.where.every((predicate) => matchesPredicate(entity, row, predicate)))
-      .filter(visible)
+      .filter((row) => matchesPlan(plan, row))
+      .filter(visibleTo(args))
       .sort((left, right) => {
         for (const entry of plan.orderBy) {
           const order = compareByKind(
@@ -226,12 +231,17 @@ export const memoryRepo = <Row>(
   // synchronously, or half the call sites would need two error paths. Every write asks
   // `refuseAbandoned()` first, as `postgresRepo`'s `writing()` does (`write-abandon.test.ts`).
   const repo: MemoryRepo<Row> = {
+    // Keyed, never a scan: the plan is still built — it is where tenancy is applied and refused —
+    // and the one row under the id must pass every predicate in it and be visible, as `rowsOf`
+    // would judge it. Filtering and sorting the table cost 6.49 ms at 20k rows.
     async findById(id, options) {
-      const { found } = select(
-        { ...options, where: [{ column: singleKeyOf(entity, 'findById'), op: 'eq', value: id }] },
-        'findById',
-      );
-      return found[0] ?? null;
+      const args: FindManyArgs = {
+        ...options,
+        where: [{ column: singleKeyOf(entity, 'findById'), op: 'eq', value: id }],
+      };
+      const plan = readPlan(entity, args, 'findById');
+      const row = rows.get(idStoreKey(id, 'findById'));
+      return row !== undefined && visibleTo(args)(row) && matchesPlan(plan, row) ? row : null;
     },
 
     async findMany(args = {}) {
@@ -240,8 +250,10 @@ export const memoryRepo = <Row>(
       const page = found.slice(start, start + plan.limit);
       const last = page.at(-1);
       const more = start + page.length < found.length;
+      // Projected as `pg-sql.ts` projects (`driver-rows.ts`): the asked columns, the key and the
+      // sort keys — the cursor is minted from the stored row, which holds all of them anyway.
       return pageOf(
-        page,
+        page.map((row) => projectRow(entity, plan, row)),
         more && last !== undefined ? cursorFor(entity, plan, last, storeKey(last)) : null,
       );
     },
@@ -280,69 +292,9 @@ export const memoryRepo = <Row>(
       return batch.map((row) => write(row, options, 'insertAll', undefined, true));
     }),
 
-    upsertAll: writing(async (given, args) => {
-      // The INCOMING rows, judged before any of them is matched: under `onMatch: 'nothing'` a
-      // colliding row is skipped and never reaches `write()`, so checking only what lands would
-      // let a row naming another tenant through whenever it happened to collide. Narrowed first
-      // for the reason `insertAll` above is, and before `conflictKeyOf` reads a target too.
-      const batch = narrowed(given);
-      // Plan first, then rows: the order `postgresRepo` refuses in, so one bad call has one code.
-      const { onConflict, onMatch = 'update', overwrites } = args;
-      const plan = upsertPlan(entity, batch, onConflict, onMatch, overwrites);
-      const keys = conflictKeys(entity, plan, batch);
-      for (const row of batch) {
-        assertRowTenant(entity.$name, entity.$tenantColumn, 'upsertAll', row);
-        entity.$assert(row);
-      }
-      // The stored rows under the same key, so "does this collide" is the question the unique
-      // index answers in Postgres and not a scan per row. A soft-deleted row still occupies its
-      // key here, because the index it would collide with there is not partial either — and a row
-      // whose target holds a null occupies none, because the index is `NULLS DISTINCT`.
-      const stored = new Map<string, Row>();
-      for (const row of rows.values()) {
-        const key = conflictKeyOf(entity, plan.on, row);
-        if (key !== undefined) stored.set(key, row);
-      }
-      // A row that lands is judged before any of them does: the statement refuses as one. One left
-      // alone by `do nothing` wrote nothing, so its reference is checked by nobody on either driver.
-      for (const [position, row] of batch.entries()) {
-        const key = keys[position];
-        const collides = key !== undefined && stored.has(key);
-        if (!collides || plan.set.length > 0) judgeReferences(row, batch);
-      }
-      const written: Row[] = [];
-      // A row colliding on ANOTHER unique takes the rows before it with it, as the statement does.
-      undoingBatch(args.tx, (tx) => {
-        for (const [position, row] of batch.entries()) {
-          const key = keys[position];
-          const existing = key === undefined ? undefined : stored.get(key);
-          // `do nothing` writes no row, and `returning *` therefore names none: a skipped row is
-          // absent from the result rather than present and unchanged.
-          if (existing !== undefined && plan.set.length === 0) continue;
-          const merged =
-            existing === undefined
-              ? row
-              : Object.assign(
-                  {},
-                  existing,
-                  Object.fromEntries(plan.set.map((property) => [property, field(row, property)])),
-                );
-          // `UpsertArgs extends RepoOptions`, so the args ARE the options — one bag, and a `tx`
-          // passed to an upsert registers its undo exactly as it does for every other write here.
-          const result = write(
-            merged,
-            { tx },
-            'upsertAll',
-            existing === undefined ? undefined : storeKey(existing),
-          );
-          // Filed as it lands, so a later row of the same batch collides with an earlier one exactly
-          // as it would with a row the request stored a moment before it.
-          if (key !== undefined) stored.set(key, result);
-          written.push(result);
-        }
-      });
-      return written;
-    }),
+    upsertAll: writing(async (given, args) =>
+      memoryUpsertAll({ entity, rows, write, storeKey, judgeReferences }, narrowed(given), args),
+    ),
 
     update: writing(async (id, given, options) => {
       // Here and in `pg-driver.ts`, the one door: a value `insert` refuses, a fragment included.
@@ -359,13 +311,10 @@ export const memoryRepo = <Row>(
       return locks.turn(`row:${idStoreKey(id, 'delete')}`, options?.tx, () => {
         const current = addressed(id, options, 'delete');
         // Soft delete hides the row without losing it; the column's presence is the switch.
+        // The deleted row, for the search mirror when it asked (`search-written-rows.ts`).
+        writtenRowsSink()?.([current]);
         if (entity.$softDelete) {
-          write(
-            Object.assign({}, current, { [SOFT_DELETE_COLUMN]: entityNow() }),
-            options,
-            'delete',
-            storeKey(current),
-          );
+          write(mergedRow(entity, current, softDeletion()), options, 'delete', storeKey(current));
           return;
         }
         const key = storeKey(current);
@@ -389,12 +338,7 @@ export const memoryRepo = <Row>(
       undoingBatch(options?.tx, (tx) => {
         for (const row of doomed) {
           if (entity.$softDelete) {
-            write(
-              Object.assign({}, row, { [SOFT_DELETE_COLUMN]: entityNow() }),
-              { tx },
-              'deleteWhere',
-              storeKey(row),
-            );
+            write(mergedRow(entity, row, softDeletion()), { tx }, 'deleteWhere', storeKey(row));
             continue;
           }
           const key = storeKey(row);
@@ -403,6 +347,8 @@ export const memoryRepo = <Row>(
           changed(row, undefined, tx);
         }
       });
+      // Past the judged bound the rows are not handed over, as Postgres's `counted` decides.
+      if (doomed.length <= MAX_ASSERTED_ROWS) writtenRowsSink()?.(doomed);
       return doomed.length;
     }),
 
@@ -432,9 +378,10 @@ export const memoryRepo = <Row>(
       // statement back; here nothing was written yet, so nothing has to be undone.
       const merged = judgeUpdate(entity, found, patch, untouched(found), storeKey);
       for (const row of merged) judgeReferences(row);
-      for (const [position, row] of merged.entries()) {
-        write(row, options, 'updateWhere', storeKey(found[position]));
-      }
+      const written = merged.map((row, at) =>
+        write(row, options, 'updateWhere', storeKey(found[at])),
+      );
+      if (written.length <= MAX_ASSERTED_ROWS) writtenRowsSink()?.(written);
       return found.length;
     }),
 

package/src/memory-seek.ts

@@ -1,32 +1,11 @@
 // Single responsibility: where a cursor's next page starts among the memory driver's sorted rows.
 // Split from `memory-repo.ts` for its line ceiling.
 
-import { kindOf, seekFrom, valueAt } from './cursor';
+import { seekFrom } from './cursor';
+import { afterSeek } from './driver-rows';
 import type { EntityCore } from './entity';
-import { compareByKind } from './memory-match';
 import type { QueryPlan } from './tenancy';
 
-/** Lexicographic over the sort keys, direction applied. `> 0` means "after the cursor". */
-const compareToSeek = <Row>(
-  entity: EntityCore<Row>,
-  plan: QueryPlan,
-  row: unknown,
-  seek: readonly unknown[],
-): number => {
-  for (const [index, entry] of plan.orderBy.entries()) {
-    // The COLUMN's kind, not the value's: the seek was revived from the same kind (`cursor.ts`),
-    // so a `bigint` column compares its stored decimal string against a revived `BigInt` as one
-    // number instead of as two pieces of text.
-    const order = compareByKind(
-      kindOf(entity, entry.column),
-      valueAt(row, entry.column),
-      seek[index],
-    );
-    if (order !== 0) return entry.direction === 'desc' ? -order : order;
-  }
-  return 0;
-};
-
 /**
  * Where the next page starts. By sort position, not by the previous row's id: that row may have
  * been deleted between the two requests, and an id that is no longer there would restart
@@ -39,6 +18,14 @@ export const afterCursor = <Row>(
 ): number => {
   const seek = seekFrom(entity, plan);
   if (seek === undefined) return 0;
-  const start = found.findIndex((row) => compareToSeek(entity, plan, row, seek) > 0);
-  return start === -1 ? found.length : start;
+  // Binary search: `found` is sorted by the very keys `afterSeek` reads, so "after the cursor"
+  // is a suffix. A linear `findIndex` made walking a table page by page quadratic.
+  let low = 0;
+  let high = found.length;
+  while (low < high) {
+    const middle = (low + high) >>> 1;
+    if (afterSeek(entity, plan, found[middle], seek)) high = middle;
+    else low = middle + 1;
+  }
+  return low;
 };

package/src/memory-unique.ts

@@ -3,21 +3,21 @@
 // duplicate key and ignored `unique()` entirely, so a signup race that is a 409 in production was
 // a quiet overwrite under `x dev` and in every app test.
 
-import { driverError } from '@ultimat3/db';
 import { keyOf } from './batch-read';
 import { columnName } from './column';
+import { entityUniqueViolation } from './driver-errors';
 import type { EntityCore } from './entity';
 import { bindValues } from './pg-row';
 import type { RowPatch } from './types';
 import { uniqueConstraints } from './unique-constraints';
 
-/** The refusal Postgres answers `23505` with, in the shape `driverError` gives it there. */
+/**
+ * The refusal Postgres answers `23505` with: `X_DB_UNIQUE_VIOLATION`, the same code, through
+ * `driver-errors.ts` — the one builder every non-Postgres store raises it with. No SQLSTATE is
+ * faked: no server said `23505`, so `sqlState()` answers `undefined` here.
+ */
 export const uniqueViolation = (entity: EntityCore, constraint: string): Error =>
-  driverError(`memory write into ${entity.$table}`, {
-    code: '23505',
-    constraint,
-    message: `duplicate key value violates unique constraint "${constraint}"`,
-  });
+  entityUniqueViolation(entity, constraint);
 
 /** A number's kinds: `'2.5'` and `'2.50'` are one key to Postgres, and so are `7` and `'7'`. */
 const BY_VALUE: ReadonlySet<string> = new Set(['integer', 'bigint', 'numeric']);

package/src/memory-update.ts

@@ -10,6 +10,7 @@
 import { narrowRow } from './columns';
 import type { EntityCore } from './entity';
 import { uniqueIndex, uniqueViolation } from './memory-unique';
+import { advanceVersion } from './search-index-version';
 import { assertRowTenant } from './tenancy';
 
 /**
@@ -29,8 +30,12 @@ const defined = (patch: object): object =>
  * same reason (`memory-repo.ts`), and narrowing twice is harmless: the second pass finds nothing
  * left to change.
  */
-export const mergedRow = <Row>(entity: EntityCore<Row>, row: Row, patch: object): Row =>
-  narrowRow<Row>(entity.$columns, Object.assign({}, row, defined(patch)));
+export const mergedRow = <Row>(entity: EntityCore<Row>, row: Row, patch: object): Row => {
+  const given = defined(patch);
+  const merged = narrowRow<Row>(entity.$columns, Object.assign({}, row, given));
+  // A searchable entity's version moves past the stored one even inside one millisecond.
+  return advanceVersion(entity, row, merged, (property) => Object.hasOwn(given, property));
+};
 
 /**
  * The rows a filtered update would write, judged as ONE batch: the patch merged into every

package/src/memory-upsert.ts

@@ -0,0 +1,102 @@
+// Single responsibility: the memory driver's `upsertAll` — which incoming row collides with which
+// stored one, and what a collision overwrites — so a test over memory resolves a conflict exactly
+// as `insert … on conflict` does. Split from `memory-repo.ts` for its line ceiling.
+
+import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
+import type { EntityCore } from './entity';
+import { undoingBatch } from './memory-batch';
+import type { RepoOptions, UpsertArgs } from './repo';
+import { advanceVersion } from './search-index-version';
+import { assertRowTenant } from './tenancy';
+import type { RowWrite } from './types';
+
+const field = (row: unknown, property: string): unknown =>
+  typeof row === 'object' && row !== null ? (row as Record<string, unknown>)[property] : undefined;
+
+/** What the upsert needs of the repository it belongs to: its rows and its one write. */
+export interface MemoryUpsertScope<Row> {
+  readonly entity: EntityCore<Row>;
+  readonly rows: { values(): Iterable<Row> };
+  write(
+    given: RowWrite<Row>,
+    options: RepoOptions | undefined,
+    operation: string,
+    from?: string,
+  ): Row;
+  storeKey(row: unknown): string;
+  judgeReferences(row: Row, batch?: readonly Row[]): void;
+}
+
+/** `batch` is already narrowed: the rows as they would be stored. */
+export const memoryUpsertAll = <Row>(
+  { entity, rows, write, storeKey, judgeReferences }: MemoryUpsertScope<Row>,
+  batch: readonly Row[],
+  args: UpsertArgs<Row>,
+): readonly Row[] => {
+  // The INCOMING rows, judged before any of them is matched: under `onMatch: 'nothing'` a
+  // colliding row is skipped and never reaches `write()`, so checking only what lands would
+  // let a row naming another tenant through whenever it happened to collide. The caller narrowed
+  // them, for the reason its `insertAll` does, and before `conflictKeyOf` reads a target too.
+  // Plan first, then rows: the order `postgresRepo` refuses in, so one bad call has one code.
+  const { onConflict, onMatch = 'update', overwrites } = args;
+  const plan = upsertPlan(entity, batch, onConflict, onMatch, overwrites);
+  const keys = conflictKeys(entity, plan, batch);
+  for (const row of batch) {
+    assertRowTenant(entity.$name, entity.$tenantColumn, 'upsertAll', row);
+    entity.$assert(row);
+  }
+  // The stored rows under the same key, so "does this collide" is the question the unique
+  // index answers in Postgres and not a scan per row. A soft-deleted row still occupies its
+  // key here, because the index it would collide with there is not partial either — and a row
+  // whose target holds a null occupies none, because the index is `NULLS DISTINCT`.
+  const stored = new Map<string, Row>();
+  for (const row of rows.values()) {
+    const key = conflictKeyOf(entity, plan.on, row);
+    if (key !== undefined) stored.set(key, row);
+  }
+  // A row that lands is judged before any of them does: the statement refuses as one. One left
+  // alone by `do nothing` wrote nothing, so its reference is checked by nobody on either driver.
+  for (const [position, row] of batch.entries()) {
+    const key = keys[position];
+    const collides = key !== undefined && stored.has(key);
+    if (!collides || plan.set.length > 0) judgeReferences(row, batch);
+  }
+  const written: Row[] = [];
+  // A row colliding on ANOTHER unique takes the rows before it with it, as the statement does.
+  undoingBatch(args.tx, (tx) => {
+    for (const [position, row] of batch.entries()) {
+      const key = keys[position];
+      const existing = key === undefined ? undefined : stored.get(key);
+      // `do nothing` writes no row, and `returning *` therefore names none: a skipped row is
+      // absent from the result rather than present and unchanged.
+      if (existing !== undefined && plan.set.length === 0) continue;
+      // A collision's version moves past the stored one, as an update's does (`advanceVersion`).
+      const merged =
+        existing === undefined
+          ? row
+          : advanceVersion(
+              entity,
+              existing,
+              Object.assign(
+                {},
+                existing,
+                Object.fromEntries(plan.set.map((property) => [property, field(row, property)])),
+              ),
+              (property) => plan.set.includes(property),
+            );
+      // `UpsertArgs extends RepoOptions`, so the args ARE the options — one bag, and a `tx`
+      // passed to an upsert registers its undo exactly as it does for every other write here.
+      const result = write(
+        merged,
+        { tx },
+        'upsertAll',
+        existing === undefined ? undefined : storeKey(existing),
+      );
+      // Filed as it lands, so a later row of the same batch collides with an earlier one exactly
+      // as it would with a row the request stored a moment before it.
+      if (key !== undefined) stored.set(key, result);
+      written.push(result);
+    }
+  });
+  return written;
+};

package/src/partition.ts

@@ -0,0 +1,140 @@
+// Single responsibility: `entity({ partitionBy })` checked where it is written. Postgres' rules
+// become declaration errors here — the key and every unique index hold the partition column, the
+// column is a timestamp or a date — so `x db gen` never writes a migration the server refuses.
+// The SQL (the `partition by` clause, creating ahead, retention) is `@ultimat3/db`'s.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { PARTITION_INTERVALS, type PartitionInterval } from '@ultimat3/db';
+import { parseDuration } from '@ultimat3/time';
+import { columnName } from './column';
+import { EntityError } from './errors';
+import type { AnyColumn, IndexDef } from './types';
+
+const INTERVALS: readonly string[] = PARTITION_INTERVALS;
+const KINDS: readonly string[] = ['timestamptz', 'date'];
+
+/** Partitions kept ready past the current one, when `ahead` is not said. */
+export const DEFAULT_PARTITIONS_AHEAD = 3;
+/** Postgres' NAMEDATALEN - 1, less the `_pYYYYMMDD` every partition name adds. */
+const MAX_PARENT_BYTES = 63 - 10;
+
+/** What `partitionBy` declares. A range by `column`, one partition per `interval`, UTC bounds. */
+export interface PartitionInit<K extends string = string> {
+  readonly column: K;
+  readonly interval: PartitionInterval;
+  /** Partitions created past the current one, by the migration and by every maintenance run. */
+  readonly ahead?: number;
+  /** Whole partitions whose upper bound is older than `after` are detached, then dropped. */
+  readonly retain?: { readonly after: string };
+}
+
+/** The checked declaration, physical column. Structurally `@ultimat3/db`'s `PartitionDescriptionLike`. */
+export interface PartitionDescription {
+  readonly column: string;
+  readonly interval: PartitionInterval;
+  readonly ahead: number;
+  readonly retain?: { readonly after: string; readonly afterMs: number } | undefined;
+}
+
+/** The rest of the declaration a partitioning has to agree with. */
+export interface PartitionContext {
+  readonly table: string;
+  readonly columns: readonly (readonly [string, AnyColumn])[];
+  /** Properties, as `primaryKey` names them. */
+  readonly primaryKey: readonly string[];
+  readonly indexes: readonly IndexDef[];
+  /** Unique invariants' physical columns. */
+  readonly uniques: readonly (readonly string[])[];
+  readonly retain: boolean;
+  readonly view: boolean;
+}
+
+export const partitionInvalid = (entity: string, reason: string, edit: string): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_PARTITION_INVALID',
+    cause: `entity "${entity}" declares partitionBy, and ${reason}`,
+    fix: `x db gen "partition"   # after ${edit} in entity('${renderFixShellArg(entity, '<entity>')}')`,
+  });
+
+const retainOf = (entity: string, after: unknown): PartitionDescription['retain'] => {
+  let afterMs = Number.NaN;
+  try {
+    afterMs = typeof after === 'string' ? parseDuration(after) : Number.NaN;
+  } catch {
+    // Reported below with the edit, the one place a bad window is described.
+  }
+  if (!(afterMs > 0)) {
+    throw partitionInvalid(
+      entity,
+      'partitionBy.retain.after is no window longer than zero',
+      "partitionBy.retain: { after: '400d' }",
+    );
+  }
+  return { after: String(after), afterMs };
+};
+
+/** `null` when `partitionBy` is absent. Every refusal raised here is at declaration. */
+export function partitionOf(
+  entity: string,
+  init: PartitionInit | undefined,
+  context: PartitionContext,
+): PartitionDescription | null {
+  if (init === undefined) return null;
+  const refuse = (reason: string, edit: string): never => {
+    throw partitionInvalid(entity, reason, edit);
+  };
+  if (context.view) refuse('is a view: a view has no partitions', 'removing partitionBy');
+  if (context.retain) {
+    refuse(
+      'retain sits beside it: a partitioned table drops whole partitions, never rows',
+      'moving the window to partitionBy.retain: { after }',
+    );
+  }
+  if (!INTERVALS.includes(init.interval)) {
+    refuse(
+      `interval "${String(init.interval)}" is none of ${INTERVALS.join(', ')}`,
+      "interval: 'month'",
+    );
+  }
+  const ahead = init.ahead ?? DEFAULT_PARTITIONS_AHEAD;
+  if (!Number.isInteger(ahead) || ahead < 0 || ahead > 1000) {
+    refuse('partitionBy.ahead is no whole number from 0 to 1000', 'ahead: 3');
+  }
+  if (new TextEncoder().encode(context.table).length > MAX_PARENT_BYTES) {
+    refuse(
+      `its table name is over ${MAX_PARENT_BYTES} bytes, and each partition adds 10 (_pYYYYMMDD)`,
+      "table: '<a shorter name>'",
+    );
+  }
+  const column = context.columns.find(([property]) => property === init.column)?.[1];
+  if (column === undefined || !KINDS.includes(column.$meta.kind)) {
+    throw partitionInvalid(
+      entity,
+      `partitionBy.column "${String(init.column)}" is no timestamp() or date() column of it`,
+      "column: 'at'",
+    );
+  }
+  if (!context.primaryKey.includes(init.column)) {
+    refuse(
+      `its primary key (${context.primaryKey.join(', ')}) does not hold "${init.column}": Postgres requires it`,
+      `primaryKey: [${[...context.primaryKey, init.column].map((key) => `'${key}'`).join(', ')}]`,
+    );
+  }
+  const physical = columnName(init.column, column.$meta);
+  const unique = [
+    ...context.indexes.filter((index) => index.unique).map((index) => index.columns),
+    ...context.uniques,
+  ].find((columns) => !columns.includes(physical));
+  if (unique !== undefined) {
+    refuse(
+      `a unique index on (${unique.join(', ')}) does not hold "${physical}": Postgres requires it`,
+      `adding ${init.column} to that unique index or invariant`,
+    );
+  }
+  return {
+    column: physical,
+    interval: init.interval,
+    ahead,
+    ...(init.retain === undefined ? {} : { retain: retainOf(entity, init.retain.after) }),
+  };
+}

package/src/personal-data-kind.ts

@@ -0,0 +1,15 @@
+// The closed set of personal-data kinds `.personalData(kind)` takes, and its membership test.
+// Imports nothing, so `column.ts` (the chain) and `types.ts` (the meta) can both read it without
+// a cycle through the readers in `personal-data.ts` — the shape `search.ts` keeps for `.searchable()`.
+
+/**
+ * What a marked value IS, so an export and an erase can treat each kind by its own rule: an
+ * identifier (a handle, a national id) ties rows to a person; a contact (email, phone, address)
+ * reaches one; free text (a bio, a message) may hold either and is read only by a human.
+ */
+export const PERSONAL_DATA_KINDS = ['identifier', 'contact', 'free-text'] as const;
+
+export type PersonalDataKind = (typeof PERSONAL_DATA_KINDS)[number];
+
+export const isPersonalDataKind = (value: unknown): value is PersonalDataKind =>
+  typeof value === 'string' && (PERSONAL_DATA_KINDS as readonly string[]).includes(value);