@ultimat3/entity 23.0.0 → 24.0.0

package/src/entity-error.ts

@@ -1,12 +1,19 @@
 // The entity layer's code registry, its error class, and the two refusals the declaration path
 // raises — split from `errors.ts` so a module the BROWSER loads (the record key, the projection,
-// the registry) can raise one without importing `@ultimat3/db`, which `errors.ts` needs for
-// `dbDrift`'s shell-inert fix line.
+// the registry) can raise one without importing `@ultimat3/db`.
 import type { ErrorRetry } from '@ultimat3/core';
-import { registerErrorCodes, registerErrorRetry, UltimateError } from '@ultimat3/core';
+import {
+  isFixShellSafe,
+  registerErrorCodes,
+  registerErrorRetry,
+  UltimateError,
+} from '@ultimat3/core';
 
-/** Codes this package declares and owns. */
-export const ENTITY_OWNED_ERROR_CODES = [
+/**
+ * Every code this package throws, and it owns each one. `X_DB_DRIFT` is `@ultimat3/db`'s and is
+ * raised there — drift is a fact about migrations.
+ */
+export const ENTITY_ERROR_CODES = [
   'X_ENTITY_DUPLICATE',
   'X_INVARIANT_VIOLATED',
   'X_TENANCY_UNSCOPED',
@@ -33,23 +40,9 @@ export const ENTITY_OWNED_ERROR_CODES = [
   'X_ENTITY_SEALED_IN_VIEW',
 ] as const;
 
-/**
- * `X_DB_DRIFT` is `@ultimat3/db`'s — drift is a fact about migrations, and this package imports db
- * rather than the other way round. `dbDrift()` below throws it; nothing here titles it, because a
- * second copy of the title is what lets the two packages disagree about what the code means.
- */
-export const ENTITY_BORROWED_ERROR_CODES = ['X_DB_DRIFT'] as const;
-
-/** Every code entity can throw: the ones it owns plus the one it borrows. */
-export const ENTITY_ERROR_CODES = [
-  ...ENTITY_OWNED_ERROR_CODES,
-  ...ENTITY_BORROWED_ERROR_CODES,
-] as const;
-
-export type EntityOwnedErrorCode = (typeof ENTITY_OWNED_ERROR_CODES)[number];
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
 
-export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>> = {
+export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   X_ENTITY_DUPLICATE: 'two entities claim the same name',
   X_INVARIANT_VIOLATED: 'a domain invariant rejected this row',
   X_TENANCY_UNSCOPED: 'a tenant-scoped query has no org predicate',
@@ -96,7 +89,7 @@ registerErrorCodes(
 export const ENTITY_ERROR_RETRY = {
   X_ENTITY_SEALED_PREDICATE: 'terminal',
   X_ENTITY_SEALED_IN_VIEW: 'terminal',
-} as const satisfies Readonly<Partial<Record<EntityOwnedErrorCode, ErrorRetry>>>;
+} as const satisfies Readonly<Partial<Record<EntityErrorCode, ErrorRetry>>>;
 
 registerErrorRetry(ENTITY_ERROR_RETRY);
 
@@ -120,6 +113,18 @@ export class EntityError extends UltimateError {
   }
 }
 
+/**
+ * The one command a BOUND refusal hands back — a page size, a preload ceiling, a judged write: it
+ * runs, and it names the real entity. The edit itself is code on a chain whose variable no error
+ * can know (`db.members`, not `preload_test_members`), so it is spelled in the `cause` as the call
+ * to write, never in the `fix` as though the entity name were that variable. A name a shell would
+ * read is not spliced.
+ */
+export const describeCommand = (entityName: string): string =>
+  isFixShellSafe(entityName)
+    ? `x entities describe ${entityName} --json`
+    : 'x entities list --json';
+
 /**
  * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
  * given. A literal is an entity that does not exist, and this fix then hands the reader

package/src/entity.ts

@@ -6,7 +6,7 @@
 import type { IndexMethod } from '@ultimat3/db';
 import { describeValue, type Schema } from '@ultimat3/schema';
 import { entityNow } from './clock';
-import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
+import { assertTableName, bindColumn, columnName, moneyColumns } from './column';
 import { newId } from './columns';
 import { describeEntity, describeReferences } from './describe';
 import { invariantViolated } from './errors';
@@ -186,7 +186,7 @@ export const entity = <const C extends ColumnMap>(
   // 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 = assertColumnName(init.table ?? name);
+  const table = assertTableName(name, init.table ?? name);
   const cacheTag = `entity:${name}`;
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
@@ -242,10 +242,7 @@ export const entity = <const C extends ColumnMap>(
     return part === 'minor' ? parts.minor : parts.currency;
   };
 
-  const columnsExpr = invariantColumns<C>(
-    name,
-    entries.map(([property]) => property),
-  );
+  const columnsExpr = invariantColumns<C>(name, init.columns);
   // Through the one resolver, so a soft-delete column the table spells differently is still the
   // column every partial index excludes rows by.
   const partialWhere = softDelete ? `${resolve([SOFT_DELETE_COLUMN])} is null` : undefined;

package/src/errors.ts

@@ -1,16 +1,14 @@
-// The entity layer's stable error codes. Each factory produces the exact command
-// that fixes the situation — `X_DB_DRIFT` is the flagship: it names the table, the
-// column and the generator invocation. The code registry, the class, `invariantViolated` and
-// `entityDuplicate` live in `entity-error.ts`, which imports no `@ultimat3/db`; re-exported here.
-import { shellInertIdentifier } from '@ultimat3/db';
+// The entity layer's stable error codes. Each factory produces the exact command that fixes the
+// situation. The code registry, the class, `invariantViolated` and `entityDuplicate` live in
+// `entity-error.ts`, which imports no `@ultimat3/db`; re-exported here. `X_DB_DRIFT` is not
+// raised here at all: drift is `@ultimat3/db`'s, factory included.
 import { EntityError } from './entity-error';
 
-export type { EntityErrorCode, EntityOwnedErrorCode } from './entity-error';
+export type { EntityErrorCode } from './entity-error';
 export {
-  ENTITY_BORROWED_ERROR_CODES,
+  describeCommand,
   ENTITY_ERROR_CODES,
   ENTITY_ERROR_TITLES,
-  ENTITY_OWNED_ERROR_CODES,
   EntityError,
   entityDuplicate,
   invariantViolated,
@@ -165,20 +163,18 @@ export const crossTenantDenied = (init: {
   });
 
 /**
- * A repository built with an explicit `client`, used while a transaction is open.
+ * A repository built with an explicit `client`, used inside a transaction that was opened on some
+ * OTHER client.
  *
- * Refused rather than resolved, because neither answer is available. `withTransaction` reserves
- * ONE connection and runs `BEGIN` on it — the ambient pool's, or a reservation of its own
- * `client:` option — while a repository pinned through `postgresDriver({ client })` sends every
- * statement straight to that client, which takes a different connection out of the pool. So the
- * write commits immediately and survives the rollback, and the read cannot see the rows the
- * transaction has already written; both are silent. Joining the transaction instead would be the
- * worse half of the same guess: a `DbTx` does not name the client it was opened on, so "is this
- * even the same database" is not a question this layer can ask, and on a sharded app the answer
- * is no.
+ * Refused rather than resolved. `withTransaction` reserves one connection and runs `BEGIN` on it,
+ * while a pinned repository sends to its own client — another connection, and on a sharded app
+ * another database — so the write would commit immediately and survive the rollback, and the read
+ * would miss rows the transaction has written; both silent. A transaction opened ON the pinned
+ * client (`tx.origin`) is the same database and the same reservation, and the repository joins it:
+ * that case never reaches here.
  *
- * The fix names the ambient seam because that is the one path a repository joins a transaction
- * through: `db()` resolves `currentTx()` first, which is exactly what a pinned client skips.
+ * The fix names the ambient seam because that is the path a repository joins the AMBIENT
+ * transaction through: `db()` resolves `currentTx()` first, which is what a pinned client skips.
  */
 export const repoClientPinned = (entityName: string): EntityError =>
   new EntityError({
@@ -187,28 +183,6 @@ 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()`,
   });
 
-/**
- * The contract's pinned wording. Mirror of `@ultimat3/db`'s `dbDrift()` (`drift-errors.ts`) —
- * keep in sync; both screen through the same `shellInertIdentifier`, so the two lines are one
- * text on both sides of the tier seam, and `errors.test.ts` asserts it rather than asking.
- *
- * The column is the CATALOG's, so it is data, and `x db gen "add C"` puts it inside SHELL DOUBLE
- * QUOTES where `$(…)` and a backtick substitute before `x` is reached at all. The argument is a
- * migration DESCRIPTION, not an identifier, so no quoted form makes a hostile name safe to pass —
- * a refused one is left OUT of the command rather than escaped into it, and read off `cause`.
- */
-export const dbDrift = (tableName: string, columnName: string): EntityError =>
-  new EntityError({
-    code: 'X_DB_DRIFT',
-    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
-    fix:
-      shellInertIdentifier(columnName) === null
-        ? 'x db gen "add the column named in this error"   # its name carries a backtick, a ' +
-          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
-          'this command'
-        : `x db gen "add ${columnName}"`,
-  });
-
 export const notFound = (entityName: string, id: string): EntityError =>
   new EntityError({
     code: 'X_NOT_FOUND',

package/src/expr.ts

@@ -15,6 +15,7 @@
 import { literal as sqlLiteral } from '@ultimat3/db';
 import { invariantViolated } from './errors';
 import { isNullish } from './is-null';
+import { DECIMAL_TEXT, numericOrder } from './numeric-compare';
 import { unportableConstruct } from './pattern-portability';
 import { refuseInvariant } from './refuse';
 import type { ColumnMap } from './types';
@@ -49,12 +50,14 @@ export interface Expr {
 interface Term {
   readonly path: readonly string[];
   readonly label: string;
+  /** The column's row value is decimal TEXT (`bigint()`, `decimal()`), by its declared kind. */
+  readonly decimal: boolean;
   sql(resolve: Resolve): string;
   read(row: Row): unknown;
 }
 
 export interface ColumnExpr {
-  /** `btrim(...)` in SQL, `.trim()` in the app — the same rule, both sides. */
+  /** `btrim(col)` in SQL and its rule in the app: leading and trailing SPACES (U+0020) only. */
   trimmed(): ColumnExpr;
   minLength(length: number): Expr;
   contains(value: string): Expr;
@@ -178,6 +181,21 @@ const check = (
   holds: (row: Row) => boolean,
 ): Expr => ({ kind: 'check', paths, message, toSql: sql, holds });
 
+/**
+ * A numeric operand a CHECK can spell. `NaN` and the infinities render as `col >= NaN` — a column
+ * reference Postgres does not have — so they are refused on the line that wrote them.
+ */
+const finite = <T>(rule: 'atLeast' | 'eq', operand: T): T => {
+  if (typeof operand === 'number' && !Number.isFinite(operand)) {
+    refuseInvariant(
+      rule,
+      `${String(operand)} is not a number a CHECK can compare a column against`,
+      `pass a finite number — c.total.${rule}(0) — or a bigint for a bound past 2^53: c.total.${rule}(9007199254740993n)`,
+    );
+  }
+  return operand;
+};
+
 const isColumnExpr = (value: unknown): value is ColumnExpr =>
   typeof value === 'object' && value !== null && terms.has(value as ColumnExpr);
 
@@ -192,11 +210,14 @@ const expr = (term: Term): ColumnExpr => {
     trimmed: () =>
       expr({
         path: term.path,
+        decimal: term.decimal,
         label: `trimmed ${term.label}`,
         sql: (resolve) => `btrim(${term.sql(resolve)})`,
         read: (row) => {
           const value = term.read(row);
-          return typeof value === 'string' ? value.trim() : value;
+          // U+0020 only — what one-argument `btrim` strips. `.trim()` also removed tabs, newlines
+          // and NBSP, so the app approved a row the CHECK then refused as a raw 23514.
+          return typeof value === 'string' ? value.replace(/^ +| +$/g, '') : value;
         },
       }),
 
@@ -233,21 +254,32 @@ const expr = (term: Term): ColumnExpr => {
       );
     },
 
-    atLeast: (bound) =>
-      one(
+    atLeast: (bound) => {
+      finite('atLeast', bound);
+      return one(
         `${term.label} must be at least ${bound}`,
         (resolve) => `${term.sql(resolve)} >= ${bound}`,
-        (value) => (typeof value === 'number' || typeof value === 'bigint') && value >= bound,
-      ),
+        // By the column's KIND, never `typeof value`: a `bigint()`/`decimal()` row is decimal text,
+        // so a number test failed every row the CHECK beside it accepts.
+        (value) => (numericOrder(term.decimal, value, bound) ?? -1) >= 0,
+      );
+    },
 
-    eq: (other) =>
-      isColumnExpr(other)
-        ? sameAs(term, other)
-        : one(
-            `${term.label} must equal ${literal(other)}`,
-            (resolve) => `${term.sql(resolve)} = ${literal(other)}`,
-            (value) => value === other,
-          ),
+    eq: (other) => {
+      if (isColumnExpr(other)) return sameAs(term, other);
+      finite('eq', other);
+      // `col = 1.5` is numeric equality whatever spelled the operand, and on a decimal column so is
+      // `col = '1.5'` — Postgres coerces the literal. Everything else is the value itself.
+      const numeric = term.decimal || typeof other === 'number' || typeof other === 'bigint';
+      return one(
+        `${term.label} must equal ${literal(other)}`,
+        (resolve) => `${term.sql(resolve)} = ${literal(other)}`,
+        (value) =>
+          numeric && typeof other !== 'boolean'
+            ? numericOrder(term.decimal, value, other) === 0
+            : value === other,
+      );
+    },
 
     isTrue: () =>
       one(
@@ -281,6 +313,8 @@ const expr = (term: Term): ColumnExpr => {
 const part = (term: Term, key: string): ColumnExpr =>
   expr({
     path: [...term.path, key],
+    // A money part is a `number` (minor) or text (currency) — never decimal text.
+    decimal: false,
     label: `${term.label}.${key}`,
     sql: (resolve) => resolve([...term.path, key]),
     read: (row) => walk(row, [...term.path, key]),
@@ -300,12 +334,18 @@ const sameAs = (left: Term, other: ColumnExpr): Expr => {
     [left.path, right.path],
     `${left.label} must equal ${right.label}`,
     (resolve) => `${left.sql(resolve)} = ${right.sql(resolve)}`,
-    (row) => left.read(row) === right.read(row),
+    // Two numeric columns are equal when their NUMBERS are: `'2' = '2.00'` across a `bigint()` and
+    // a `decimal()`, which `===` over the two row strings denied.
+    (row) =>
+      left.decimal || right.decimal
+        ? numericOrder(true, left.read(row), right.read(row)) === 0
+        : left.read(row) === right.read(row),
   );
 };
 
-const columnTerm = (property: string): Term => ({
+const columnTerm = (property: string, decimal: boolean): Term => ({
   path: [property],
+  decimal,
   label: property,
   sql: (resolve) => resolve([property]),
   read: (row) => row[property],
@@ -403,25 +443,31 @@ export const iff = (left: Expr, right: Expr): Expr => {
  * catches a typo at compile time: a JS caller, a dynamically built rule and a `satisfies()` column
  * list all reach it untyped, and the thrown message names the columns that do exist rather than
  * failing later as `undefined is not a function`.
+ *
+ * It takes the column MAP, not a name list: a numeric rule is judged by the column's declared kind
+ * (`numeric-compare.ts`), and the map is the only place that kind is written.
  */
 export const invariantColumns = <C extends ColumnMap>(
   entity: string,
-  properties: readonly string[],
+  columns: C,
 ): InvariantColumns<C> => {
-  const known = new Set(properties);
+  const properties = Object.keys(columns);
   const helpers = { unique, satisfies };
   return new Proxy(helpers, {
     get(target, property) {
       if (property === 'unique' || property === 'satisfies') return target[property];
       if (typeof property !== 'string') return undefined;
-      if (!known.has(property)) {
+      // `Object.hasOwn`, never `columns[property]`: the name is caller data on the JS path, and a
+      // plain read answers an `Object.prototype` member for `constructor`.
+      const column = Object.hasOwn(columns, property) ? columns[property] : undefined;
+      if (column === undefined) {
         throw invariantViolated(
           entity,
           'invariant',
           `no column "${property}"; declared columns are ${properties.join(', ')}`,
         );
       }
-      return expr(columnTerm(property));
+      return expr(columnTerm(property, DECIMAL_TEXT.has(column.$meta.kind)));
     },
   }) as unknown as InvariantColumns<C>;
 };

package/src/index.ts

@@ -45,7 +45,6 @@ export type {
 // so a third-party driver has to be able to raise the same refusals the two shipped ones do.
 export {
   crossTenantDenied,
-  dbDrift,
   ENTITY_ERROR_CODES,
   ENTITY_ERROR_TITLES,
   EntityError,
@@ -76,6 +75,10 @@ export {
 } from './feature-errors';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
 export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';
+// 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.
+export { compareByKind, sameValueOfKind } from './memory-match';
 export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
@@ -90,6 +93,8 @@ export { postgresTransactor } from './pg-transactor';
 // its own `pageSize` input against a hardcoded 10_000 is a second declaration of one number.
 export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from './plan';
 export type { RelatedTable, RelatedTables } from './preload';
+export type { PreloadOptions } from './preload-ceiling';
+export { MAX_PRELOADED_ROWS } from './preload-ceiling';
 export type { Preloaded, ReadBuilder, Table } from './query';
 export { tableFor } from './query';
 // The client projection of an entity (plan 101): record type, record key, and the brand on

package/src/invariants.ts

@@ -7,7 +7,7 @@
 // callback the typed column proxy once, so a rule is written against property keys (`c.likeCount`)
 // and `entity()` alone resolves them to physical names. A physical name is never typed twice.
 
-import { EntityError, invariantViolated } from './errors';
+import { describeCommand, EntityError, invariantViolated } from './errors';
 import type { Expr, Resolve, Row } from './expr';
 
 /** `assert` is a rule only the app can run — a JS predicate with no SQL translation. */
@@ -110,8 +110,8 @@ export const assertedRowsTooMany = (
 ): EntityError =>
   new EntityError({
     code: 'X_INVARIANT_VIOLATED',
-    cause: `${entityName}.${operation}() matches ${matched} rows and ${entityName} declares an invariant only the app can judge, so every one of them would be read back — past ${MAX_ASSERTED_ROWS} that is the whole table in memory`,
-    fix: `for await (const rows of ${entityName}.where(filter).inBatches(1000)) { … }   # one page per statement, judged one page at a time`,
+    cause: `${entityName}.${operation}() matches ${matched} rows and ${entityName} declares an invariant only the app can judge, so every one of them would be read back — past ${MAX_ASSERTED_ROWS} that is the whole table in memory. Read the same filter with .where(filter).inBatches(1000) and write each page: one page per statement, judged one page at a time`,
+    fix: `${describeCommand(entityName)}   # shows the invariant with sql: null that forces the read-back; then sweep the filter with inBatches()`,
   });
 
 /** Runs on every write. Reports every violation at once so one round trip fixes all. */

package/src/judged-write.ts

@@ -0,0 +1,28 @@
+// Single responsibility: a write whose RESULT the app still has to judge. A rule with no CHECK
+// (`kind: 'assert'`) is asserted on the rows a statement returned — after it was sent — so outside
+// a transaction the violating row was committed and the refusal arrived too late to matter.
+
+import { type DbClient, withTransaction } from '@ultimat3/db';
+import type { EntityCore } from './entity';
+import { hasJsOnlyInvariant } from './invariants';
+
+/**
+ * Runs `work` on the connection its statement and its judgement share. With an app-only rule
+ * declared that is one transaction — a SAVEPOINT inside an open one — so the throw takes the write
+ * with it. With none, a CHECK already refused the statement and this is `direct` and nothing else:
+ * no `BEGIN`, no extra round trip.
+ *
+ * `direct` is resolved by the CALLER first, so a pinned repository inside a transaction opened on
+ * some other client is still refused (`X_REPO_CLIENT_PINNED`) before anything opens. `pinned` is
+ * that same client when the repository has one: the transaction is opened on it — a SAVEPOINT when
+ * one is already open there — never on the ambient pool.
+ */
+export const judgedWrite = <Row, T>(
+  entity: EntityCore<Row>,
+  direct: DbClient,
+  pinned: DbClient | undefined,
+  work: (send: DbClient) => Promise<T>,
+): Promise<T> => {
+  if (!hasJsOnlyInvariant(entity.$invariants)) return work(direct);
+  return withTransaction((tx) => work(tx), pinned === undefined ? {} : { client: pinned });
+};

package/src/like.ts

@@ -0,0 +1,85 @@
+// Single responsibility: what a SQL `LIKE` pattern matches in the in-memory driver — Postgres'
+// default escape handling, counted in CHARACTERS, in time bounded by pattern × value.
+
+import { EntityError } from './errors';
+
+/**
+ * Postgres answers a `LIKE` pattern ending in the escape character with `22025 — LIKE pattern must
+ * not end with escape character`, so a pattern that means nothing there means nothing here either.
+ * The pattern itself is never echoed: a filter value is app data, and this cause is rendered into
+ * a log line.
+ */
+const danglingEscape = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}: a like pattern ends with a backslash, which is the escape character — Postgres answers that pattern with 22025 (LIKE pattern must not end with escape character)`,
+    fix: "double it — 'a\\\\' is the pattern that matches one literal backslash, and 'a\\%b' matches a literal %",
+  });
+
+const ONE = Symbol('_');
+const MANY = Symbol('%');
+
+/** One literal character, `_` (exactly one character) or `%` (any run, the empty one included). */
+type Part = string | typeof ONE | typeof MANY;
+
+/**
+ * The pattern as its parts: `%` and `_` are the wildcards, a backslash escapes either (or itself),
+ * everything else is literal. Read by CODE POINT, which is what Postgres counts — `_` over `😀` is
+ * one character there and was two UTF-16 units to a regex `.` without the `u` flag.
+ *
+ * A run of `%` is one `%`, as Postgres reads it.
+ */
+const partsOf = (entityName: string, pattern: string): readonly Part[] => {
+  const chars = [...pattern];
+  const parts: Part[] = [];
+  for (let at = 0; at < chars.length; at += 1) {
+    const char = chars[at] ?? '';
+    if (char === '\\') {
+      const escaped = chars[at + 1];
+      if (escaped === undefined) throw danglingEscape(entityName);
+      parts.push(escaped);
+      at += 1;
+    } else if (char === '%') {
+      if (parts.at(-1) !== MANY) parts.push(MANY);
+    } else {
+      parts.push(char === '_' ? ONE : char);
+    }
+  }
+  return parts;
+};
+
+/**
+ * `text like pattern`. NOT a compiled regex: an anchored regex with one `.*` per `%` backtracks
+ * combinatorially the moment the wildcards are separated (`%a%a%a%…b`, `%_%_%_…b`) — seconds at
+ * seven of them over a 70-character value, and a filter value arrives from a search box. This is
+ * the two-pointer walk with ONE backtrack point (the last `%`), so the worst case is pattern
+ * length × value length whatever the pattern holds.
+ */
+export const likeMatches = (entityName: string, pattern: string, text: string): boolean => {
+  const parts = partsOf(entityName, pattern);
+  const chars = [...text];
+  let part = 0;
+  let char = 0;
+  let star = -1;
+  let resume = 0;
+  while (char < chars.length) {
+    const current = parts[part];
+    if (current === MANY) {
+      star = part;
+      resume = char;
+      part += 1;
+    } else if (current !== undefined && (current === ONE || current === chars[char])) {
+      part += 1;
+      char += 1;
+    } else if (star !== -1) {
+      // The last `%` takes one more character and the walk resumes after it.
+      part = star + 1;
+      resume += 1;
+      char = resume;
+    } else {
+      return false;
+    }
+  }
+  while (parts[part] === MANY) part += 1;
+  return part === parts.length;
+};