@ultimat3/entity 1.2.0 → 3.0.0

package/src/columns.ts

@@ -3,14 +3,54 @@
 // currency) are the bugs this file exists to make unreachable.
 
 import { uuid as uuidV7 } from '@ultimat3/core';
-import { BARE, column, GENERATED_UUID, makeColumn, makeTimestamp } from './column';
+import {
+  CURRENCY_CODE_PATTERN,
+  describeValue,
+  isCurrencyCode,
+  isMoneyScale,
+  MAX_MONEY_SCALE,
+} from '@ultimat3/schema';
+import {
+  assertColumnName,
+  BARE,
+  column,
+  GENERATED_UUID,
+  makeColumn,
+  makeTimestamp,
+} from './column';
 import { invariantViolated } from './errors';
-import type { Column, MoneyInput, MoneyValue, TimestampColumn, UuidColumn } from './types';
+import type {
+  Column,
+  ColumnMap,
+  ColumnMeta,
+  MoneyColumnNames,
+  MoneyInput,
+  MoneyValue,
+  TimestampColumn,
+  UuidColumn,
+} from './types';
 
 const reject = (rule: string, detail: string): never => {
   throw invariantViolated('column', rule, detail);
 };
 
+/**
+ * The rejected value, rendered as its SHAPE and never its content — `@ultimat3/schema`'s
+ * `describeValue`, the same renderer every builtin validator fails through, so a column and a
+ * schema describe one bad value the same way.
+ *
+ * WHY it is not `String(value)`: a column rejection is not a private diagnostic. It becomes
+ * `X_INVARIANT_VIOLATED`'s `cause` and a `$view` issue, which `@ultimat3/http` returns to the
+ * caller AND writes into the log line — and core's logger redacts by KEY, so a value baked into a
+ * message has no key left to redact. `text()` on a password field wrote the mistyped password to
+ * the central log index in cleartext and into the user's own network tab; a `uuid()` holding an
+ * API key surrogate does the same. A column is the worse half of that pair, because the value can
+ * arrive from the DATABASE — so the leak is not bounded by what someone just typed.
+ *
+ * `got` stays `got` and the "expected …" half is untouched: only what follows it changes.
+ */
+const got = (value: unknown): string => `got ${describeValue(value)}`;
+
 /** uuid v7: time-ordered, so a primary key index stays append-friendly. */
 export const newId = (): string => uuidV7();
 
@@ -19,18 +59,36 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const parseUuid = (value: unknown): string =>
   typeof value === 'string' && UUID.test(value)
     ? value
-    : reject('format', `expected a uuid, got ${String(value)}`);
+    : reject('format', `expected a uuid, ${got(value)}`);
+
+/**
+ * The one place a brand is applied. A brand is a compile-time tag with no runtime witness, so
+ * there is nothing here to check that `parseUuid` has not already checked — same shape as core's
+ * `parseId`, and the reason `uuid<PostId>()` needs no cast at any call site afterwards.
+ */
+const parseBrandedUuid = <T extends string>(value: unknown): T => parseUuid(value) as T;
 
-export const uuid = (): UuidColumn => ({
-  ...makeColumn<string, false>({ ...BARE, kind: 'uuid' }, parseUuid, false),
+/**
+ * `uuid()` for a plain id, `uuid<PostId>()` to declare the brand ONCE. The brand then rides the
+ * derivation — row, insert, `findById`, `update`, `delete` — so mixing two entities' ids is a
+ * compile error instead of a query that silently matches nothing.
+ */
+export const uuid = <T extends string = string>(): UuidColumn<T> =>
+  uuidWith({ ...BARE, kind: 'uuid' });
+
+const uuidWith = <T extends string>(meta: ColumnMeta): UuidColumn<T> => ({
+  ...makeColumn<T, false>(meta, parseBrandedUuid, false),
   // Narrower than the generic chain: a uuid key is generated when omitted, so it is the one
   // primary key an insert may leave out.
   primaryKey: () =>
-    makeColumn<string, true>(
-      { ...BARE, kind: 'uuid', primaryKey: true, default: GENERATED_UUID },
-      parseUuid,
+    makeColumn<T, true>(
+      { ...meta, primaryKey: true, default: GENERATED_UUID },
+      parseBrandedUuid,
       true,
     ),
+  // Overridden for the same reason `timestamp()`'s is: `uuid().column('user_id').primaryKey()`
+  // must still be the KEY form, which is optional on insert, rather than the general one.
+  column: (name) => uuidWith<T>({ ...meta, name: assertColumnName(name) }),
 });
 
 export interface TextOptions {
@@ -42,7 +100,7 @@ export const text = (options: TextOptions = {}): Column<string> =>
   column<string>(
     'text',
     (value) =>
-      typeof value === 'string' ? value : reject('type', `expected a string, got ${typeof value}`),
+      typeof value === 'string' ? value : reject('type', `expected a string, ${got(value)}`),
     options.max === undefined
       ? {}
       : { length: options.max, check: (name) => `char_length(${name}) <= ${options.max}` },
@@ -52,12 +110,12 @@ export const integer = (): Column<number> =>
   column<number>('integer', (value) =>
     typeof value === 'number' && Number.isSafeInteger(value)
       ? value
-      : reject('type', `expected a safe integer, got ${String(value)}`),
+      : reject('type', `expected a safe integer, ${got(value)}`),
   );
 
 export const boolean = (): Column<boolean> =>
   column<boolean>('boolean', (value) =>
-    typeof value === 'boolean' ? value : reject('type', `expected a boolean, got ${typeof value}`),
+    typeof value === 'boolean' ? value : reject('type', `expected a boolean, ${got(value)}`),
   );
 
 const parseInstant = (value: unknown): Date => {
@@ -66,7 +124,7 @@ const parseInstant = (value: unknown): Date => {
     const parsed = new Date(value);
     if (!Number.isNaN(parsed.getTime())) return parsed;
   }
-  return reject('format', `expected a UTC instant, got ${String(value)}`);
+  return reject('format', `expected a UTC instant, ${got(value)}`);
 };
 
 /** Always `timestamptz`. UTC storage is not a per-table decision. */
@@ -92,7 +150,7 @@ export const enumerated = <const V extends readonly string[]>(values: V): Column
     (value) =>
       typeof value === 'string' && allowed.has(value)
         ? value
-        : reject('enum', `expected one of ${values.join(' | ')}, got ${String(value)}`),
+        : reject('enum', `expected one of ${values.join(' | ')}, ${got(value)}`),
     { values, check: oneOf(values) },
   );
 };
@@ -113,7 +171,7 @@ export const url = (): Column<string> =>
           // fall through to the shared rejection so the error names the rule
         }
       }
-      return reject('format', `expected an absolute http(s) URL, got ${String(value)}`);
+      return reject('format', `expected an absolute http(s) URL, ${got(value)}`);
     },
     { check: (name) => `${name} ~ '^https?://'` },
   );
@@ -141,7 +199,7 @@ export const tz = <const Z extends readonly string[]>(zones: Z): Column<Z[number
     (value) =>
       typeof value === 'string' && allowed.has(value)
         ? value
-        : reject('iana-tz', `expected one of ${zones.join(' | ')}, got ${String(value)}`),
+        : reject('iana-tz', `expected one of ${zones.join(' | ')}, ${got(value)}`),
     { values: zones, check: oneOf(zones) },
   );
 };
@@ -158,45 +216,177 @@ export const locale = <const L extends readonly string[]>(locales: L): Column<L[
     (value) =>
       typeof value === 'string' && allowed.has(value)
         ? value
-        : reject('bcp-47', `expected one of ${locales.join(' | ')}, got ${String(value)}`),
+        : reject('bcp-47', `expected one of ${locales.join(' | ')}, ${got(value)}`),
     { values: locales, check: oneOf(locales) },
   );
 };
 
-const parseMinor = (value: unknown): bigint => {
-  if (typeof value === 'bigint') return value;
-  if (typeof value === 'number') {
-    if (!Number.isInteger(value)) {
-      return reject(
-        'money-minor-units',
-        `got the float ${value}; money is integer minor units — 12.34 EUR is 1234n, not 12.34`,
-      );
-    }
-    return BigInt(value);
+/**
+ * The column is `bigint` and the value type is a `number`, which is the one narrowing in this
+ * package that can lose information — so it is the one narrowing that refuses rather than rounds.
+ *
+ * `number` is not a compromise here: money is projected onto every wire this framework generates,
+ * and `JSON.stringify` throws on a bigint. What the wide column buys is the ability to *hold* a
+ * value written by something that is not this framework — a psql session, a backfill, another
+ * service — and the honest answer to reading one back is a coded refusal naming the row, not a
+ * `minor` that silently rounds and not a `bigint` that crashes the response three layers later.
+ * `@ultimat3/realtime` refuses the identical value for the identical reason (`pg-entity-row.ts`),
+ * so the two readers of one column agree.
+ */
+const parseMinor = (value: unknown): number => {
+  const minor =
+    typeof value === 'bigint' || (typeof value === 'string' && /^-?\d+$/.test(value))
+      ? Number(value)
+      : value;
+  if (typeof minor !== 'number' || !Number.isFinite(minor)) {
+    return reject('money-minor-units', `expected integer minor units, ${got(value)}`);
+  }
+  if (!Number.isInteger(minor)) {
+    return reject(
+      'money-minor-units',
+      `got the float ${minor}; money is integer minor units — 12.34 EUR is 1234, not 12.34`,
+    );
   }
-  if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
-  return reject('money-minor-units', `expected integer minor units, got ${String(value)}`);
+  if (!Number.isSafeInteger(minor)) {
+    return reject(
+      'money-minor-units',
+      `${String(value)} is past ±2^53 and no JS number holds it exactly — money is minor units ` +
+        'inside that range; store the overflow in its own column or split the amount',
+    );
+  }
+  return minor;
 };
 
+/**
+ * The bound is `@ultimat3/schema`'s, imported rather than restated — the same rule `parseScale`
+ * below follows for `isMoneyScale`. This column, `moneySchema`, the OpenAPI `pattern` and the
+ * CHECK at the bottom of this file are four projections of one declaration; each was individually
+ * correct and would have drifted silently, since only a psql session sees the disagreement.
+ */
 const parseCurrency = (value: unknown): string =>
-  typeof value === 'string' && /^[A-Z]{3}$/.test(value)
+  isCurrencyCode(value)
     ? value
-    : reject('iso-4217', `expected a 3-letter ISO-4217 code, got ${String(value)}`);
+    : reject('iso-4217', `expected a 3-letter ISO-4217 code, ${got(value)}`);
+
+/**
+ * The decimal exponent `minor` counts in, when it is not the currency's own. `undefined` and `0`
+ * are DIFFERENT values — "the currency's natural minor unit" versus "whole units" — so the key is
+ * carried only when it was supplied, exactly as `@ultimat3/schema`'s `moneySchema` carries it.
+ * The legal range is `isMoneyScale`'s, imported rather than restated: one bound, one declaration.
+ */
+const parseScale = (value: unknown): number => {
+  const scale = typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : value;
+  return isMoneyScale(scale)
+    ? scale
+    : reject(
+        'money-scale',
+        `expected a whole number of decimal places between 0 and ${MAX_MONEY_SCALE}, ${got(value)}`,
+      );
+};
 
 const parseMoney = (value: unknown): MoneyValue => {
   if (typeof value !== 'object' || value === null) {
-    return reject('money', `expected { minor, currency }, got ${String(value)}`);
+    return reject('money', `expected { minor, currency }, ${got(value)}`);
   }
   const input: Partial<MoneyInput> = value;
-  return { minor: parseMinor(input.minor), currency: parseCurrency(input.currency) };
+  return {
+    minor: parseMinor(input.minor),
+    currency: parseCurrency(input.currency),
+    ...(input.scale === undefined || input.scale === null
+      ? {}
+      : { scale: parseScale(input.scale) }),
+  };
+};
+
+/**
+ * One property, three physical columns: `<name>_minor bigint`, `<name>_currency char(3)` and
+ * `<name>_scale integer null`. A single implied currency is a migration nobody wants to write
+ * later, and a float is a rounding bug nobody wants to debug.
+ *
+ * The third column is not decoration: `scale` is what lets an amount name a sub-cent value, and
+ * the entity layer used to rebuild the row as `{ minor, currency }` — so
+ * `{ minor: 2, currency: 'USD', scale: 6 }` ($0.000002) was stored and read back as $0.02, a
+ * silent 10,000x reinterpretation of a value the type system, `t.money` and `@ultimat3/money` all
+ * carry. `null` in the column is "no explicit scale" and decodes to an ABSENT key, never to `0`.
+ */
+export interface MoneyOptions {
+  /**
+   * Where the three columns already live, for a table this framework did not create. Named per
+   * part and merged over `<name>_minor` / `<name>_currency` / `<name>_scale`, so a legacy
+   * `amount_cents` beside a `currency` is two words rather than three.
+   *
+   * `scale: null` says the table has no scale column at all. What that costs is stated where the
+   * option is declared (`MoneyColumnNames`): every amount is then at the currency's own minor
+   * unit. What it does NOT cost is correctness — an absent scale already means exactly that.
+   */
+  readonly columns?: MoneyColumnNames;
+}
+
+export const money = (options: MoneyOptions = {}): Column<MoneyValue> =>
+  column<MoneyValue>(
+    'money',
+    parseMoney,
+    options.columns === undefined ? {} : { parts: checkedParts(options.columns) },
+  );
+
+/** Every part named goes through the same identifier rule a `.column()` does. */
+const checkedParts = (columns: MoneyColumnNames): MoneyColumnNames => ({
+  ...(columns.minor === undefined ? {} : { minor: assertColumnName(columns.minor) }),
+  ...(columns.currency === undefined ? {} : { currency: assertColumnName(columns.currency) }),
+  ...(columns.scale === undefined || columns.scale === null
+    ? { ...(columns.scale === null ? { scale: null } : {}) }
+    : { scale: assertColumnName(columns.scale) }),
+});
+
+/**
+ * Money is the one column whose write type is wider than its row type — `MoneyInput` takes a
+ * `bigint` so a minor unit read straight off a `bigint` column needs no conversion at the call
+ * site — so it is the one column where "the caller's value" and "the row's value" can differ.
+ * This is where they stop differing, and BOTH drivers call it: `bindValues` before a statement,
+ * `memoryRepo`'s `write` before it stores. A rule applied to one of them and not the other is
+ * exactly the drift the two-driver split exists to prevent — here it would mean an in-memory row
+ * holding a `bigint` that `JSON.stringify` refuses while the Postgres row holds a `number`.
+ *
+ * Every other kind is returned untouched: writes are asserted, not parsed, and money is the only
+ * kind that widens. A value already holding safe-integer minor units is left alone — that is the
+ * overwhelmingly common case and it costs one `typeof`-grade check and no allocation (axiom 6);
+ * everything else goes through `parseMinor`, so a `bigint` narrows and a float is refused with
+ * the same message it would get coming back from the database.
+ */
+export const narrowMoney = <Row>(columns: ColumnMap, row: Row): Row => {
+  let narrowed: Record<string, unknown> | undefined;
+  const record = row as Readonly<Record<string, unknown>>;
+  for (const [property, column] of Object.entries(columns)) {
+    if (column.$meta.kind !== 'money') continue;
+    const value = record[property] as Partial<MoneyInput> | null | undefined;
+    if (value === null || value === undefined || Number.isSafeInteger(value.minor)) continue;
+    // Spread rather than rebuild: `currency` is the column's to validate on read and Postgres's
+    // to CHECK on write, and narrowing a minor unit is not the place to start refusing one.
+    narrowed ??= { ...record };
+    narrowed[property] = { ...value, minor: parseMinor(value.minor) };
+  }
+  return (narrowed ?? row) as Row;
 };
 
 /**
- * One property, two physical columns: `<name>_minor bigint` and `<name>_currency char(3)`.
- * A single implied currency is a migration nobody wants to write later, and a float is a
- * rounding bug nobody wants to debug.
+ * The CHECK that stops a psql session writing a currency the app would refuse — the app's own
+ * bound, projected into SQL rather than restated in it.
+ *
+ * SQL cannot call `isCurrencyCode`, so what crosses is `CURRENCY_CODE_PATTERN`, the pattern source
+ * that predicate is built from — the same move `scaleCheck` below already makes with
+ * `MAX_MONEY_SCALE`. It holds because the pattern is deliberately kept to the syntax ECMAScript
+ * and POSIX ERE spell identically (see its declaration); the one thing a TypeScript test cannot
+ * prove is that a real server reads it the same way, which is what
+ * `currency-check.live.test.ts` sends to Postgres. Quoting is not a concern and must not become
+ * one: this is a compile-time constant from tier 0, never a value.
  */
-export const money = (): Column<MoneyValue> => column<MoneyValue>('money', parseMoney);
+export const currencyCheck = (currencyColumn: string): string =>
+  `${currencyColumn} ~ '${CURRENCY_CODE_PATTERN}'`;
 
-/** The CHECK that stops a psql session writing a currency the app would refuse. */
-export const currencyCheck = (currencyColumn: string): string => `${currencyColumn} ~ '^[A-Z]{3}$'`;
+/**
+ * The same for the scale column: `parseScale` refuses anything outside `0…MAX_MONEY_SCALE`, and a
+ * row written by a backfill or a psql session must not be able to hold a value the app would
+ * refuse to read back. `is null` is legal and is the ordinary case.
+ */
+export const scaleCheck = (scaleColumn: string): string =>
+  `${scaleColumn} is null or (${scaleColumn} >= 0 and ${scaleColumn} <= ${MAX_MONEY_SCALE})`;

package/src/count-by.ts

@@ -0,0 +1,148 @@
+// Single responsibility: what a grouped count is made of — which columns a count may be keyed by,
+// how many groups one statement is allowed to answer with, and the order the map comes back in.
+// Both drivers read those three rules from here, so a `countBy` against memory means exactly what
+// a `countBy` against Postgres means; a rule added to one driver alone is the drift this file
+// exists to prevent.
+
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import type { AnyColumn, ColumnKind } from './types';
+
+/**
+ * How many groups one call may answer with. A grouped count answers a page's worth of keys, or a
+ * column with a handful of values; past that it is a report, and a report is paged. The statement
+ * therefore asks for one group more than this and the extra one is *refused* rather than dropped —
+ * a map that silently lost its tail reads exactly like a complete one, and a caller recounting
+ * from it would write the wrong number to every row it missed.
+ */
+export const MAX_GROUPS = 1000;
+
+/**
+ * The kinds a group key can be. A `Map` compares keys by identity for anything that is not a
+ * primitive, so a `timestamptz` (a `Date`) or a `jsonb` (an object) would file every row under a
+ * key no caller can look up again — the result would be a map that only ever answers `undefined`.
+ * `money` is two physical columns, which is not one value to group by at all.
+ */
+const GROUPABLE: ReadonlySet<ColumnKind> = new Set<ColumnKind>([
+  'uuid',
+  'text',
+  'char',
+  'boolean',
+  'integer',
+  'bigint',
+]);
+
+const groupableColumns = <Row>(entity: EntityCore<Row>): readonly string[] =>
+  Object.entries(entity.$columns)
+    .filter(([, column]) => GROUPABLE.has(column.$meta.kind))
+    .map(([property]) => property);
+
+/**
+ * Not `invariantViolated`: its fix opens `x entity explain`, which describes invariants nobody
+ * wrote here. What repairs this is one edit to the call — a different column, named in the message
+ * because the entity is the only place the answer lives. Only when this entity offers no such
+ * column does the fix become a command, and then it is `x entities describe`, which prints the
+ * kinds: there is no call to suggest, since every column it declares would be refused the same way.
+ */
+const notGroupable = <Row>(
+  entity: EntityCore<Row>,
+  operation: string,
+  property: string,
+  reason: string,
+): EntityError => {
+  const [first] = groupableColumns(entity);
+  return new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entity.$name}.${operation}('${property}'): ${reason}`,
+    fix:
+      first === undefined
+        ? `x entities describe ${entity.$name} --json   # this entity declares no column a count can be keyed by`
+        : `${entity.$name}.${operation}('${first}')   # group by one of: ${groupableColumns(entity).join(', ')}`,
+  });
+};
+
+/**
+ * The bound, spelled as the call that stays under it. A grouped count of a foreign key is the
+ * point of this method, so the fix leads with the `in` predicate that bounds one — the shape a
+ * page-then-count loop collapses to.
+ */
+const tooManyGroups = <Row>(
+  entity: EntityCore<Row>,
+  operation: string,
+  property: string,
+): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entity.$name}.${operation}('${property}') matched more than ${MAX_GROUPS} distinct values — that column is a key, not a grouping`,
+    fix: `${entity.$name}.andWhere('${property}', 'in', <values>).${operation}('${property}')   # bound the values first; a whole-table breakdown is a report, and a report is paged`,
+  });
+
+/**
+ * The column a count may be keyed by, or the refusal. Called by both drivers before the statement
+ * exists, so an ungroupable column is the same error whichever one is installed.
+ */
+export const groupColumnOf = <Row>(
+  entity: EntityCore<Row>,
+  property: string,
+  operation: string,
+): AnyColumn => {
+  const column = entity.$columns[property];
+  if (column === undefined) {
+    throw notGroupable(
+      entity,
+      operation,
+      property,
+      `no column "${property}" on ${entity.$name} — pick from: ${Object.keys(entity.$columns).join(', ')}`,
+    );
+  }
+  if (!GROUPABLE.has(column.$meta.kind)) {
+    throw notGroupable(
+      entity,
+      operation,
+      property,
+      `a ${column.$meta.kind} column is not a key a map can be looked up by`,
+    );
+  }
+  return column;
+};
+
+/**
+ * The value a group is filed under: re-parsed by the column that declared it, exactly as
+ * `decodeRow` re-parses a row's own value — `int8` arrives as a string and would otherwise key the
+ * map by text where the in-memory driver keys it by a `bigint`. An absent value is `null`, which
+ * is the one group SQL's `group by` puts every NULL row in.
+ */
+export const groupValue = (column: AnyColumn, value: unknown): unknown =>
+  value === null || value === undefined ? null : column.$parse(value);
+
+/** Ties: numbers and bigints numerically, everything else by its text, `null` last. */
+const byValue = (left: unknown, right: unknown): number => {
+  if (left === null) return right === null ? 0 : 1;
+  if (right === null) return -1;
+  if (typeof left === 'number' && typeof right === 'number') return left - right;
+  if (typeof left === 'bigint' && typeof right === 'bigint') {
+    return left < right ? -1 : left > right ? 1 : 0;
+  }
+  const [a, b] = [String(left), String(right)];
+  return a < b ? -1 : a > b ? 1 : 0;
+};
+
+/**
+ * The map both drivers hand back: the biggest group first, ties by the value itself, `null` last.
+ * Ordered here rather than in the statement, because there is no order to inherit — a hash
+ * aggregate returns groups in whatever order it built them and a `Map` filled row by row returns
+ * them in insertion order, so the two drivers would disagree about a result they agree on.
+ * Sorting the groups (never the rows) costs nothing at this size and it is what makes
+ * "the largest bucket" readable off the front.
+ */
+export const countsFrom = <Row>(
+  entity: EntityCore<Row>,
+  property: string,
+  operation: string,
+  groups: readonly (readonly [unknown, number])[],
+): ReadonlyMap<unknown, number> => {
+  if (groups.length > MAX_GROUPS) throw tooManyGroups(entity, operation, property);
+  return new Map(
+    [...groups].sort((left, right) => right[1] - left[1] || byValue(left[0], right[0])),
+  );
+};

package/src/cross-tenant.ts

@@ -0,0 +1,76 @@
+// Single responsibility: the one explicit way to read across tenants, and the capability that
+// opens it. A scope with a written reason — never a boolean argument on a repository call, which
+// reads exactly like forgetting the tenant, and never a config list of exempt entities (axiom 1):
+// both put the argument somewhere other than the read it defends.
+
+// `node:` because Bun exposes no native async-context primitive: the scope has to outlive every
+// `await` inside it, and `AsyncLocalStorage` is the only thing that carries a value across them.
+// A module-scope flag would be shared by two concurrent requests — one of them ordinary.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { actorLabel, assert, hasScope, tryUseContext } from '@ultimat3/core';
+import { crossTenantDenied } from './errors';
+
+/**
+ * The capability an actor must carry to read across tenants. A scope, not a role: roles are the
+ * app's vocabulary and every app spells its administrator differently, while `scopes` is the
+ * closed list a policy already requires against — so an operator grants this the same way they
+ * grant `post:publish`, and `grep -r 'tenancy:cross'` finds every actor that holds it.
+ */
+export const CROSS_TENANT_SCOPE = 'tenancy:cross';
+
+const storage = new AsyncLocalStorage<string>();
+
+/**
+ * Run `fn` with the tenant guard lifted — every read and write it issues, at any depth and across
+ * every `await`, may span tenants. For the three cases that genuinely have no single tenant: an
+ * admin surface listing every org, background reconciliation, and support tooling.
+ *
+ * ```ts
+ * // one sweep over every tenant's stale invites, nightly
+ * await crossTenant('nightly invite expiry runs for every org', async () => {
+ *   for await (const batch of db.invites.where({ status: 'pending' }).inBatches(500)) …
+ * });
+ * ```
+ *
+ * Three properties, none optional. **The capability is proven, always** — the actor in scope must
+ * carry `tenancy:cross`, here and again at every plan built inside, so an impersonated child
+ * context cannot inherit a permission its own actor never had. **Outside a request context there
+ * is no actor to prove it**, so a script asking for this mints one and says who it is, which is
+ * what makes a cross-tenant sweep auditable rather than ambient. **The reason is required and
+ * non-blank** because it *is* the mechanism: an escape with no argument is a pragma, and the next
+ * reader cannot tell a considered sweep from a forgotten tenant.
+ */
+export function crossTenant<T>(reason: string, fn: () => T): T {
+  assert(
+    reason.trim() !== '',
+    'crossTenant() was given a blank reason, so the tenant guard it lifts carries no argument',
+    "pass why the read spans tenants: crossTenant('nightly expiry sweeps every org', fn)",
+  );
+  assertCrossTenant(reason);
+  return storage.run(reason, fn);
+}
+
+/**
+ * The innermost enclosing reason, or `undefined` outside every scope — which is every query in an
+ * app that never calls `crossTenant`. Read by the tenant guard, and by nothing else.
+ */
+export const crossTenantReason = (): string | undefined => storage.getStore();
+
+/**
+ * The capability check itself, run at `crossTenant()` and again for every plan built inside it.
+ * Twice on purpose: `withChildContext({ actor })` swaps the actor without closing this scope, so a
+ * handler that impersonates a caller inside a sweep would otherwise keep reading across tenants on
+ * a permission that caller does not hold.
+ */
+export const assertCrossTenant = (reason: string): void => {
+  const actor = tryUseContext()?.actor;
+  if (actor !== undefined && hasScope(actor, CROSS_TENANT_SCOPE)) return;
+  throw crossTenantDenied({
+    reason,
+    actor:
+      actor === undefined
+        ? 'no actor — the call is outside every request context'
+        : actorLabel(actor),
+    scope: CROSS_TENANT_SCOPE,
+  });
+};

package/src/cursor.ts

@@ -12,7 +12,14 @@ import { invariantViolated } from './errors';
 import type { QueryPlan } from './tenancy';
 import type { AnyColumn, ColumnKind } from './types';
 
-const MONEY_PARTS: Readonly<Record<string, ColumnKind>> = { minor: 'bigint', currency: 'char' };
+/**
+ * The kind a money part is *revived* as, which is the kind the row property holds — not the
+ * physical column's. `<p>_minor` is a `bigint` column, but `MoneyValue.minor` is a `number`
+ * (`@ultimat3/schema` owns that declaration), and a cursor whose value came back a `bigint`
+ * would compare against a `number` property in the memory driver and mint a seek bind of the
+ * wrong type in the other. The narrowing itself is guarded once, where the row is decoded.
+ */
+const MONEY_PARTS: Readonly<Record<string, ColumnKind>> = { minor: 'integer', currency: 'char' };
 
 /** Resolves `price.minor` as well as `title`; money is the one property with two parts. */
 const partsOf = (path: string): { readonly property: string; readonly part?: string } => {
@@ -69,8 +76,15 @@ const serializeSortValue = (value: unknown): string => {
 };
 
 // No `money` case: `kindAt` resolves a money sort key to the kind of the part being ordered by
-// (`minor` is bigint, `currency` is char) and refuses the bare property, so the composite kind
-// never reaches here. A case for it could only ever revive "[object Object]".
+// and refuses the bare property, so the composite kind never reaches here. A case for it could
+// only ever revive "[object Object]".
+//
+// The parts revive as `MONEY_PARTS` declares them — `minor` as an `integer` and `currency` as a
+// `char` — and `minor` is deliberately NOT `bigint` even though the physical column is: the row
+// property is a `number` (`@ultimat3/schema` owns that declaration), and a cursor reviving a
+// `bigint` there would compare against a `number` property in the memory driver and mint a seek
+// bind of the wrong type in the other. The comment here used to claim the opposite of the
+// constant three lines above it.
 const reviveSortValue = (kind: ColumnKind, text: string): unknown => {
   switch (kind) {
     case 'timestamptz':