@ultimat3/entity 16.0.0 → 17.0.0

package/CLAUDE.md

@@ -245,10 +245,12 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   number, answers the read they did. `limit(rows)` was `next({ limit: rows })` and nothing else —
   no integer check, no positivity check, no ceiling — so an action taking `pageSize` as input and
   passing it through bound whatever a client sent, and one request could ask for five million rows.
-  `assertPageSize` is `assertBatchable`'s three refusals in the other call, deliberately under the
+  `assertFinitePageSize` is `assertBatchable`'s three refusals in the other call, deliberately under the
   same code (`X_INVARIANT_VIOLATED`) because `limit(0)` and `inBatches(0)` are one mistake in two
   places. Called from **both** `limit()` on the chain (so the refusal lands on the line the author
-  wrote) and `planFor` (so `findMany({ limit })` straight at the repository cannot route around it),
+  wrote) and both `plan()` builders, on the RESOLVED page — so `findMany({ limit })` straight at the
+  repository cannot route around it, and `bun run finite-bounds` can see the repair, which it could
+  not while the screen was spelled `assertPageSize` and took a parameter called `rows` —
   and `MAX_PAGE_SIZE` bounds `inBatches(size)` too — a batch IS a page, so the ceiling belongs to
   the range and not to one of the two calls.
 - **A repository pinned to its own client refuses to run inside a transaction**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "16.0.0",
+  "version": "17.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "16.0.0",
-    "@ultimat3/db": "16.0.0",
-    "@ultimat3/schema": "16.0.0",
-    "@ultimat3/time": "16.0.0"
+    "@ultimat3/core": "17.0.0",
+    "@ultimat3/db": "17.0.0",
+    "@ultimat3/schema": "17.0.0",
+    "@ultimat3/time": "17.0.0"
   }
 }

package/src/errors.ts

@@ -2,6 +2,7 @@
 // that fixes the situation — `X_DB_DRIFT` is the flagship: it names the table, the
 // column and the generator invocation.
 import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { shellInertIdentifier } from '@ultimat3/db';
 
 /** Codes this package declares and owns. */
 export const ENTITY_OWNED_ERROR_CODES = [
@@ -293,11 +294,26 @@ 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: `x db gen "add ${columnName}"`,
+    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 =>

package/src/plan.ts

@@ -88,8 +88,8 @@ export const totalOrder = <Row>(
  * query, a third-party driver's caller — cannot route around it. One function, so the two can
  * never disagree about what a page may be.
  */
-export const assertPageSize = (entityName: string, rows: number): void => {
-  if (Number.isSafeInteger(rows) && rows >= 1 && rows <= MAX_PAGE_SIZE) return;
+export const assertFinitePageSize = (entityName: string, rows: number): number => {
+  if (Number.isSafeInteger(rows) && rows >= 1 && rows <= MAX_PAGE_SIZE) return rows;
   throw new EntityError({
     code: 'X_INVARIANT_VIOLATED',
     cause: `${entityName}.limit(${String(rows)}) — a page is a whole number of rows, at least one and at most ${MAX_PAGE_SIZE}`,
@@ -108,7 +108,6 @@ export const assertPageSize = (entityName: string, rows: number): void => {
  * `cursorFor` and `seekFrom` still call it: they are reached from a driver directly.
  */
 export const planFor = <Row>(entity: EntityCore<Row>, args: FindManyArgs): QueryPlan => {
-  if (args.limit !== undefined) assertPageSize(entity.$name, args.limit);
   const orderBy = totalOrder(entity, args.orderBy ?? []);
   assertSeekable(entity, orderBy);
   const scoped =
@@ -119,7 +118,10 @@ export const planFor = <Row>(entity: EntityCore<Row>, args: FindManyArgs): Query
     entity: entity.$name,
     where: [...(args.where ?? []), ...scoped],
     orderBy,
-    limit: args.limit ?? DEFAULT_PAGE_SIZE,
+    // Screened on the RESOLVED page, so `findMany({ limit })` straight at the repository — a
+    // generated client, a query, a third-party driver's caller — cannot route around the rule the
+    // chain's own `limit()` applies.
+    limit: assertFinitePageSize(entity.$name, args.limit ?? DEFAULT_PAGE_SIZE),
     ...(args.cursor === undefined || args.cursor === null ? {} : { cursor: args.cursor }),
     ...(args.select === undefined ? {} : { select: args.select }),
   };

package/src/query.ts

@@ -9,7 +9,7 @@ import { assertBatchable, batchIterator } from './batch';
 import { entityNow } from './clock';
 import type { EntityCore } from './entity';
 import { searchUndeclared } from './feature-errors';
-import { assertPageSize, DEFAULT_PAGE_SIZE, namedColumns } from './plan';
+import { assertFinitePageSize, DEFAULT_PAGE_SIZE, namedColumns } from './plan';
 import type { RelatedTables } from './preload';
 import { preloaded } from './preload';
 import type { Relation } from './relations';
@@ -305,7 +305,7 @@ const builder = <Source, Row>(
     // sized. `planFor` applies the identical guard, so a caller reaching the repository directly
     // cannot go round it.
     limit: (rows) => {
-      assertPageSize(entity.$name, rows);
+      assertFinitePageSize(entity.$name, rows);
       return next({ limit: rows });
     },
 
@@ -400,7 +400,7 @@ const builder = <Source, Row>(
       where: state.where,
       orderBy: state.orderBy,
       // The page that will actually run, so an unnamed one still reads as the bound it has.
-      limit: state.limit ?? DEFAULT_PAGE_SIZE,
+      limit: assertFinitePageSize(entity.$name, state.limit ?? DEFAULT_PAGE_SIZE),
       ...(state.cursor === null ? {} : { cursor: state.cursor }),
       // The projection actually sent, preload keys included: a plan that is safe to log is only
       // useful if it is the plan that ran.