@ultimat3/entity 0.0.1 → 1.1.0

package/src/columns.ts

@@ -1,255 +1,202 @@
-// The blessed column helpers. There is exactly one way to store an id, a timestamp,
-// money, a locale and a time zone — the alternatives (float money, naive timestamps,
-// a single implied currency) are the bugs this file exists to make unreachable.
-import { uuid } from '@ultimat3/core';
-import { invariantViolated } from './errors';
-import type { ColumnDef, ColumnMap, IndexDef, TableDef } from './types';
+// The blessed column builders. There is exactly one way to store an id, an instant, money, a
+// locale and a time zone — the alternatives (float money, naive timestamps, a single implied
+// currency) are the bugs this file exists to make unreachable.
 
-const snake = (value: string): string => value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+import { uuid as uuidV7 } from '@ultimat3/core';
+import { BARE, column, GENERATED_UUID, makeColumn, makeTimestamp } from './column';
+import { invariantViolated } from './errors';
+import type { Column, MoneyInput, MoneyValue, TimestampColumn, UuidColumn } from './types';
 
-const reject = (column: string, rule: string, detail: string): never => {
-  throw invariantViolated(column, rule, detail);
+const reject = (rule: string, detail: string): never => {
+  throw invariantViolated('column', rule, detail);
 };
 
-interface ColumnOptions {
-  readonly name?: string;
-  readonly comment?: string;
-}
-
-const base = <T>(
-  kind: ColumnDef<T>['kind'],
-  parse: (value: unknown) => T,
-  overrides: Partial<ColumnDef<T>> = {},
-): ColumnDef<T> => ({
-  // '' means "derive from the property key in table()", so a column is declared once.
-  name: '',
-  kind,
-  notNull: true,
-  primaryKey: false,
-  unique: false,
-  index: false,
-  parse,
-  ...overrides,
-});
-
-const asString =
-  (label: string) =>
-  (value: unknown): string => {
-    if (typeof value === 'string') return value;
-    return reject(label, 'type', `expected a string, got ${typeof value}`);
-  };
-
-const asDate =
-  (label: string) =>
-  (value: unknown): Date => {
-    if (value instanceof Date) return value;
-    if (typeof value === 'string' || typeof value === 'number') {
-      const parsed = new Date(value);
-      if (!Number.isNaN(parsed.getTime())) return parsed;
-    }
-    return reject(label, 'type', `expected a Date or ISO-8601 string, got ${String(value)}`);
-  };
+/** uuid v7: time-ordered, so a primary key index stays append-friendly. */
+export const newId = (): string => uuidV7();
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-const asUuid =
-  (label: string) =>
-  (value: unknown): string => {
-    if (typeof value === 'string' && UUID.test(value)) return value;
-    return reject(label, 'format', `expected a uuid, got ${String(value)}`);
-  };
+const parseUuid = (value: unknown): string =>
+  typeof value === 'string' && UUID.test(value)
+    ? value
+    : reject('format', `expected a uuid, got ${String(value)}`);
+
+export const uuid = (): UuidColumn => ({
+  ...makeColumn<string, false>({ ...BARE, kind: 'uuid' }, parseUuid, 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,
+      true,
+    ),
+});
 
-/** uuid v7: time-ordered, so a primary key index stays append-friendly. */
-export const newId = (): string => uuid();
-
-export const id = (options: ColumnOptions = {}): ColumnDef<string> =>
-  base<string>('uuid', asUuid('id'), {
-    ...options,
-    name: options.name ?? 'id',
-    primaryKey: true,
-    default: { kind: 'generated', by: 'uuid-v7' },
-  });
-
-export const text = (options: ColumnOptions & { readonly check?: string } = {}) =>
-  base<string>('text', asString(options.name ?? 'text'), options);
-
-const asBoolean =
-  (label: string) =>
-  (value: unknown): boolean =>
-    typeof value === 'boolean'
-      ? value
-      : reject(label, 'type', `expected a boolean, got ${typeof value}`);
+export interface TextOptions {
+  /** Emits `char_length(<column>) <= max`, so Postgres refuses an over-long string too. */
+  readonly max?: number;
+}
 
-const asInteger =
-  (label: string) =>
-  (value: unknown): number =>
+export const text = (options: TextOptions = {}): Column<string> =>
+  column<string>(
+    'text',
+    (value) =>
+      typeof value === 'string' ? value : reject('type', `expected a string, got ${typeof value}`),
+    options.max === undefined
+      ? {}
+      : { length: options.max, check: (name) => `char_length(${name}) <= ${options.max}` },
+  );
+
+export const integer = (): Column<number> =>
+  column<number>('integer', (value) =>
     typeof value === 'number' && Number.isSafeInteger(value)
       ? value
-      : reject(label, 'type', `expected a safe integer, got ${String(value)}`);
+      : reject('type', `expected a safe integer, got ${String(value)}`),
+  );
 
-const asCurrency =
-  (label: string) =>
-  (value: unknown): string =>
-    typeof value === 'string' && /^[A-Z]{3}$/.test(value)
-      ? value
-      : reject(label, 'iso-4217', `expected a 3-letter ISO-4217 code, got ${String(value)}`);
-
-export const boolean = (options: ColumnOptions = {}): ColumnDef<boolean> =>
-  base<boolean>('boolean', asBoolean(options.name ?? 'boolean'), options);
-
-export const integer = (
-  options: ColumnOptions & { readonly check?: string } = {},
-): ColumnDef<number> => base<number>('integer', asInteger(options.name ?? 'integer'), options);
-
-/** UTC always. A `timestamp without time zone` column is not expressible here. */
-export const timestamps = (): {
-  readonly createdAt: ColumnDef<Date>;
-  readonly updatedAt: ColumnDef<Date>;
-} => ({
-  createdAt: base<Date>('timestamptz', asDate('createdAt'), {
-    name: 'created_at',
-    default: { kind: 'generated', by: 'now' },
-    index: true,
-  }),
-  updatedAt: base<Date>('timestamptz', asDate('updatedAt'), {
-    name: 'updated_at',
-    default: { kind: 'generated', by: 'now' },
-  }),
-});
+export const boolean = (): Column<boolean> =>
+  column<boolean>('boolean', (value) =>
+    typeof value === 'boolean' ? value : reject('type', `expected a boolean, got ${typeof value}`),
+  );
 
-export type MoneyColumns<N extends string> = {
-  readonly [K in `${N}Minor`]: ColumnDef<bigint>;
-} & {
-  readonly [K in `${N}Currency`]: ColumnDef<string>;
+const parseInstant = (value: unknown): Date => {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
+  if (typeof value === 'string' || typeof value === 'number') {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) return parsed;
+  }
+  return reject('format', `expected a UTC instant, got ${String(value)}`);
 };
 
-const asMinorUnits =
-  (label: string) =>
-  (value: unknown): bigint => {
-    if (typeof value === 'bigint') return value;
-    if (typeof value === 'number') {
-      if (!Number.isInteger(value)) {
-        return reject(
-          label,
-          'money-minor-units',
-          `got the float ${value}; money is integer minor units — 12.34 EUR is 1234n, not 12.34`,
-        );
-      }
-      return BigInt(value);
-    }
-    if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
-    return reject(label, 'money-minor-units', `expected integer minor units, got ${String(value)}`);
-  };
+/** Always `timestamptz`. UTC storage is not a per-table decision. */
+export const timestamp = (): TimestampColumn =>
+  makeTimestamp<false>({ ...BARE, kind: 'timestamptz' }, parseInstant, false);
+
+const quote = (value: string): string => `'${value.replaceAll("'", "''")}'`;
+
+const oneOf =
+  (values: readonly string[]) =>
+  (name: string): string =>
+    `${name} in (${values.map(quote).join(', ')})`;
 
 /**
- * Two columns, always: minor units as bigint and an ISO-4217 code. A single-currency
- * assumption is a migration nobody wants to write later, and a float is a rounding
- * bug nobody wants to debug.
+ * A closed set of strings, emitted as a CHECK rather than a Postgres `ENUM` type: adding a
+ * variant is then a one-line migration instead of `ALTER TYPE`, which cannot run inside a
+ * transaction on older servers.
  */
-export const money = <N extends string>(name: N): MoneyColumns<N> =>
-  ({
-    [`${name}Minor`]: base<bigint>('bigint', asMinorUnits(`${name}Minor`), {
-      name: `${snake(name)}_minor`,
-    }),
-    [`${name}Currency`]: base<string>('char', asCurrency(`${name}Currency`), {
-      name: `${snake(name)}_currency`,
-      length: 3,
-      check: `${snake(name)}_currency ~ '^[A-Z]{3}$'`,
-    }),
-  }) as unknown as MoneyColumns<N>;
-
-/** IANA identifier, validated by `Intl` at write time and by a CHECK in the database. */
-export const tz = (options: ColumnOptions = {}): ColumnDef<string> => {
-  const label = options.name ?? 'tz';
-  return base<string>(
+export const enumerated = <const V extends readonly string[]>(values: V): Column<V[number]> => {
+  const allowed = new Set<string>(values);
+  return column<V[number]>(
+    'text',
+    (value) =>
+      typeof value === 'string' && allowed.has(value)
+        ? value
+        : reject('enum', `expected one of ${values.join(' | ')}, got ${String(value)}`),
+    { values, check: oneOf(values) },
+  );
+};
+
+/**
+ * An absolute http(s) URL, validated on write rather than on render: a bad URL stored once is
+ * served to every reader, and `<img src>` fails silently in the browser.
+ */
+export const url = (): Column<string> =>
+  column<string>(
     'text',
     (value) => {
       if (typeof value === 'string') {
         try {
-          new Intl.DateTimeFormat('en', { timeZone: value }).format(0);
-          return value;
+          const parsed = new URL(value);
+          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') return value;
         } catch {
-          return reject(label, 'iana-tz', `${value} is not an IANA time zone`);
+          // fall through to the shared rejection so the error names the rule
         }
       }
-      return reject(label, 'iana-tz', `expected an IANA time zone, got ${typeof value}`);
+      return reject('format', `expected an absolute http(s) URL, got ${String(value)}`);
     },
-    { ...options, check: `${snake(label)} ~ '^[A-Za-z0-9_+/-]{3,64}$'` },
+    { check: (name) => `${name} ~ '^https?://'` },
   );
+
+const isIanaZone = (value: string): boolean => {
+  try {
+    new Intl.DateTimeFormat('en', { timeZone: value }).format(0);
+    return true;
+  } catch {
+    return false;
+  }
 };
 
-export const locale = (options: ColumnOptions = {}): ColumnDef<string> => {
-  const label = options.name ?? 'locale';
-  return base<string>('text', asString(label), {
-    ...options,
-    check: `${snake(label)} ~ '^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$'`,
-  });
+/**
+ * IANA identifiers, checked against `Intl` when the column is declared — a typo or a UTC offset
+ * is a startup error rather than a row nobody can format. An offset is wrong twice a year.
+ */
+export const tz = <const Z extends readonly string[]>(zones: Z): Column<Z[number]> => {
+  for (const zone of zones) {
+    if (!isIanaZone(zone)) reject('iana-tz', `${zone} is not an IANA time zone`);
+  }
+  const allowed = new Set<string>(zones);
+  return column<Z[number]>(
+    'text',
+    (value) =>
+      typeof value === 'string' && allowed.has(value)
+        ? value
+        : reject('iana-tz', `expected one of ${zones.join(' | ')}, got ${String(value)}`),
+    { values: zones, check: oneOf(zones) },
+  );
 };
 
-export const slug = (options: ColumnOptions = {}): ColumnDef<string> => {
-  const label = options.name ?? 'slug';
-  return base<string>('text', asString(label), {
-    ...options,
-    unique: true,
-    check: `${snake(label)} ~ '^[a-z0-9]+(-[a-z0-9]+)*$'`,
-  });
+const BCP47 = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+
+export const locale = <const L extends readonly string[]>(locales: L): Column<L[number]> => {
+  for (const tag of locales) {
+    if (!BCP47.test(tag)) reject('bcp-47', `${tag} is not a BCP-47 language tag`);
+  }
+  const allowed = new Set<string>(locales);
+  return column<L[number]>(
+    'text',
+    (value) =>
+      typeof value === 'string' && allowed.has(value)
+        ? value
+        : reject('bcp-47', `expected one of ${locales.join(' | ')}, got ${String(value)}`),
+    { values: locales, check: oneOf(locales) },
+  );
 };
 
-/** Takes its own parser: a jsonb column without a schema is an untyped hole. */
-export const jsonb = <T>(parse: (value: unknown) => T, options: ColumnOptions = {}): ColumnDef<T> =>
-  base<T>('jsonb', parse, options);
-
-/** Presence of this column is what makes an entity soft-deletable — not a flag. */
-export const softDelete = (): { readonly deletedAt: ColumnDef<Date | null> } => ({
-  deletedAt: base<Date | null>(
-    'timestamptz',
-    (value) => (value === null || value === undefined ? null : asDate('deletedAt')(value)),
-    { name: 'deleted_at', notNull: false, index: true },
-  ),
-});
+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);
+  }
+  if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
+  return reject('money-minor-units', `expected integer minor units, got ${String(value)}`);
+};
 
-/** Presence of this column is what makes an entity tenant-scoped. See tenancy.ts. */
-export const orgId = (options: ColumnOptions & { readonly table?: string } = {}) =>
-  base<string>('uuid', asUuid('orgId'), {
-    name: options.name ?? 'org_id',
-    index: true,
-    references: { table: options.table ?? 'orgs', column: 'id', onDelete: 'cascade' },
-  });
-
-export const nullable = <T>(column: ColumnDef<T>): ColumnDef<T | null> => ({
-  ...column,
-  notNull: false,
-  parse: (value) => (value === null || value === undefined ? null : column.parse(value)),
-});
+const parseCurrency = (value: unknown): string =>
+  typeof value === 'string' && /^[A-Z]{3}$/.test(value)
+    ? value
+    : reject('iso-4217', `expected a 3-letter ISO-4217 code, got ${String(value)}`);
 
-export const references = <T>(column: ColumnDef<T>, target: string, targetColumn = 'id') => ({
-  ...column,
-  index: true,
-  references: { table: target, column: targetColumn },
-});
+const parseMoney = (value: unknown): MoneyValue => {
+  if (typeof value !== 'object' || value === null) {
+    return reject('money', `expected { minor, currency }, got ${String(value)}`);
+  }
+  const input: Partial<MoneyInput> = value;
+  return { minor: parseMinor(input.minor), currency: parseCurrency(input.currency) };
+};
 
 /**
- * Composes columns into a table, filling every column name that was left to the
- * property key (`orgId` -> `org_id`) so a physical name is written at most once.
+ * 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.
  */
-export const table = <C extends ColumnMap>(name: string, columns: C): TableDef<C> => {
-  const resolved: Record<string, ColumnDef<unknown>> = {};
-  const primaryKey: string[] = [];
-  const indexes: IndexDef[] = [];
-  for (const [property, column] of Object.entries(columns)) {
-    const physical = column.name === '' ? snake(property) : column.name;
-    resolved[property] = { ...column, name: physical };
-    if (column.primaryKey) primaryKey.push(physical);
-    if (column.unique) {
-      indexes.push({ name: `${name}_${physical}_key`, columns: [physical], unique: true });
-    } else if (column.index) {
-      indexes.push({ name: `${name}_${physical}_idx`, columns: [physical], unique: false });
-    }
-  }
-  return {
-    name,
-    columns: resolved as unknown as C,
-    primaryKey: primaryKey.length > 0 ? primaryKey : ['id'],
-    indexes,
-  };
-};
+export const money = (): Column<MoneyValue> => column<MoneyValue>('money', parseMoney);
+
+/** The CHECK that stops a psql session writing a currency the app would refuse. */
+export const currencyCheck = (currencyColumn: string): string => `${currencyColumn} ~ '^[A-Z]{3}$'`;

package/src/cursor.ts

@@ -0,0 +1,187 @@
+// Single responsibility: what an entity cursor *means*. The codec is `@ultimat3/core`'s — this
+// file decides what a page position is bound to (the plan that produced it) and how a sort value
+// survives the round trip (the column's kind).
+//
+// Both drivers call `cursorFor` and `seekFrom` and nothing else, so a rule added to one is added
+// to both. The cursor carries the sort VALUES, not just an id: seeking by id alone needs the row
+// to still exist, and a row deleted between two pages would silently restart pagination.
+
+import { CursorInvalidError, decodeCursor, encodeCursor } from '@ultimat3/core';
+import type { EntityCore } from './entity';
+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' };
+
+/** 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 } => {
+  const [property = path, part] = path.split('.');
+  return part === undefined ? { property } : { property, part };
+};
+
+const columnAt = <Row>(entity: EntityCore<Row>, path: string): AnyColumn => {
+  const column = entity.$columns[partsOf(path).property];
+  if (column === undefined) {
+    throw invariantViolated(entity.$name, 'orderBy', `no column "${path}"`);
+  }
+  return column;
+};
+
+/** The physical type a sort key holds — what tells `revive` how to read its string back. */
+const kindAt = <Row>(entity: EntityCore<Row>, path: string): ColumnKind => {
+  const { part } = partsOf(path);
+  const kind = columnAt(entity, path).$meta.kind;
+  if (part === undefined) {
+    // Money is two physical columns, so the property alone names no single sort value: the
+    // cursor would carry `String({ minor, currency })` and the next page would fail parsing it
+    // as a bare `SyntaxError` from `BigInt`, with no code and no fix. `entity()` refuses the
+    // same path in `resolve()`; refusing it here keeps one answer for one mistake.
+    if (kind !== 'money') return kind;
+    throw invariantViolated(
+      entity.$name,
+      'orderBy',
+      `${path} is money: order by ${path}.minor or ${path}.currency`,
+    );
+  }
+  const money = kind === 'money' ? MONEY_PARTS[part] : undefined;
+  if (money === undefined) {
+    throw invariantViolated(entity.$name, 'orderBy', `${path} names no column part`);
+  }
+  return money;
+};
+
+export const valueAt = (row: unknown, path: string): unknown => {
+  const { property, part } = partsOf(path);
+  const record = typeof row === 'object' && row !== null ? (row as Record<string, unknown>) : {};
+  const base = record[property];
+  if (part === undefined) return base;
+  return typeof base === 'object' && base !== null
+    ? (base as Record<string, unknown>)[part]
+    : undefined;
+};
+
+/** Stringified so the cursor is JSON; `revive` restores the type from the column's kind. */
+const serializeSortValue = (value: unknown): string => {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'bigint') return value.toString();
+  return String(value);
+};
+
+// 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]".
+const reviveSortValue = (kind: ColumnKind, text: string): unknown => {
+  switch (kind) {
+    case 'timestamptz':
+      return new Date(text);
+    case 'bigint':
+      return BigInt(text);
+    case 'integer':
+      return Number(text);
+    case 'boolean':
+      return text === 'true';
+    default:
+      return text;
+  }
+};
+
+/**
+ * A keyset seek only has a total order when every sort column is present on every row —
+ * `null > 'x'` is unknown in SQL and would drop rows from the middle of a listing.
+ *
+ * Checked when a cursor is minted as well as when one is decoded: an ordering that cannot carry
+ * a position is the author's mistake, and reporting it on the *second* page hides it behind
+ * whatever page size the caller happened to use.
+ */
+export const assertSeekable = <Row>(
+  entity: EntityCore<Row>,
+  orderBy: readonly { readonly column: string }[],
+): void => {
+  for (const key of orderBy) {
+    // Resolving the kind is the other half: it refuses a column the entity never declared and a
+    // money property named without its part — both mint a cursor nothing can decode.
+    kindAt(entity, key.column);
+    if (columnAt(entity, key.column).$meta.notNull) continue;
+    throw invariantViolated(
+      entity.$name,
+      'cursor',
+      `${key.column} is nullable and cannot carry a cursor — order by a not-null column ` +
+        `(add .orderBy('${entity.$primaryKey[0] ?? 'id'}') or make ${key.column} not null)`,
+    );
+  }
+};
+
+/** Deterministic, and total over the value shapes a predicate can hold. */
+const renderValue = (value: unknown): string => {
+  if (value === null || value === undefined) return 'null';
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'bigint') return `${value}n`;
+  if (Array.isArray(value)) return `[${value.map(renderValue).join(',')}]`;
+  if (typeof value === 'object') {
+    const record = value as Readonly<Record<string, unknown>>;
+    const keys = Object.keys(record).sort();
+    return `{${keys.map((key) => `${key}:${renderValue(record[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(String(value));
+};
+
+/**
+ * What a cursor is bound to: this entity, these filters, this sort order. Not the page size — a
+ * client may legitimately ask for a bigger next page — and not the projection, which cannot move
+ * a row's position. Filters are sorted because `and` is commutative, so two chains that build the
+ * same predicate set page each other's cursors.
+ *
+ * Hashed rather than spelled out: a cursor is base64, not encrypted, and the caller's filter
+ * values are not the client's to read.
+ */
+export const planScope = (plan: QueryPlan): string => {
+  const where = plan.where
+    .map((predicate) => `${predicate.column} ${predicate.op} ${renderValue(predicate.value)}`)
+    .sort()
+    .join('&');
+  const order = plan.orderBy.map((key) => `${key.column} ${key.direction}`).join(',');
+  return new Bun.CryptoHasher('sha256')
+    .update(`${plan.entity}|${where}|${order}`)
+    .digest('hex')
+    .slice(0, 16);
+};
+
+/** The cursor that continues this plan after `row`. Signed by core, scoped by the plan. */
+export const cursorFor = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  row: unknown,
+  id: string,
+): string => {
+  assertSeekable(entity, plan.orderBy);
+  return encodeCursor({
+    scope: planScope(plan),
+    key: plan.orderBy.map((entry) => serializeSortValue(valueAt(row, entry.column))),
+    id,
+  });
+};
+
+/**
+ * The keyset position a plan resumes from, revived to the types its columns hold — `undefined`
+ * when the plan has no cursor. A cursor that was tampered with, or taken from another entity,
+ * another filter or another sort order, is `X_CURSOR_INVALID` here rather than a silent page one.
+ */
+export const seekFrom = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+): readonly unknown[] | undefined => {
+  if (plan.cursor === undefined) return undefined;
+  const { key } = decodeCursor(plan.cursor, planScope(plan));
+  assertSeekable(entity, plan.orderBy);
+  // Unreachable through the scope check, which already pins the sort order — kept because the
+  // alternative to a bad arity is `?? ''`, and that seeks from an empty string.
+  if (key.length !== plan.orderBy.length) {
+    throw new CursorInvalidError(
+      `it carries ${key.length} sort values, this order needs ${plan.orderBy.length}`,
+    );
+  }
+  return plan.orderBy.map((entry, index) =>
+    reviveSortValue(kindAt(entity, entry.column), String(key[index])),
+  );
+};