@ultimat3/entity 31.6.0 → 31.7.0

package/README.md

@@ -619,7 +619,7 @@ export const find = async (orgId: string, q: string) => {
 
 | Rule | Detail |
 |---|---|
-| `.search(term)` asks the installed index | built-in: the `matches` predicate in the statement (today's SQL). Any other: ids first (at most `MAX_PAGE_SIZE`), then the chain reads those rows with its own tenancy, soft delete, order and cursor |
+| `.search(term)` asks the installed index | built-in: the `matches` predicate in the statement (today's SQL). Any other: ids first — 10,000 (`MAX_PAGE_SIZE`) or more hits are refused with `X_INVARIANT_VIOLATED`, never truncated — then the chain reads those rows with its own tenancy, soft delete, order and cursor |
 | a document has a **version** | the row's `onUpdateNow()` instant, epoch ms. A searchable entity indexed by anything declares one — `updatedAt: timestamp().defaultNow().onUpdateNow()` — or `searchDocumentOf` and `reindex()` refuse (`X_INVARIANT_VIOLATED`) |
 | the version is STRICTLY increasing per row | a write of a searchable entity — a soft delete included — stores its version no earlier than the stored one + 1 ms: Postgres `greatest($now, updated_at + interval '1 millisecond')` in the `update` and the upsert's `on conflict` set; the memory driver in its merge (`advanceVersion`); a `defineDriver` store in ITS write, atomically per row — `DriverRepo.update`'s `advance` argument, and `advanceVersion(entity, stored, merged, (p) => plan.set.includes(p))` in its own `upsert` (`entityDriverConformance` refuses a store that skips either). So two writes inside one millisecond are two versions, and the index keeps the second. The column may run ahead of the clock by a millisecond per same-ms write. Other entities' `onUpdateNow()` columns are the clock's reading, unchanged |
 | keep only newer | an index applies a document only when its version is newer than what it holds for that id: a document, or the tombstone `remove(scope, ids, version)` leaves (a delete's: past the row's last version and no earlier than its instant). Equal = replay. EXCEPT a `committed` document — the write path's, `index(docs, { committed: true })` — which replaces a tombstone whatever its version: a key deleted and written again is live at once, inside one millisecond too. `reindex`'s reads are not `committed`, so a stale read never brings a deleted row back |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "31.6.0",
+  "version": "31.7.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "keywords": [
     "ultimate",
@@ -44,9 +44,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "31.6.0",
-    "@ultimat3/db": "31.6.0",
-    "@ultimat3/schema": "31.6.0",
-    "@ultimat3/time": "31.6.0"
+    "@ultimat3/core": "31.7.0",
+    "@ultimat3/db": "31.7.0",
+    "@ultimat3/schema": "31.7.0",
+    "@ultimat3/time": "31.7.0"
   }
 }

package/src/lifecycle.ts

@@ -13,6 +13,7 @@ import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
 import { type HistoryEntity, type HistoryInit, historyEntity, historyIgnored } from './history';
 import type { Retain } from './retain';
+import { sealedFields } from './sealed';
 import type { ColumnMap } from './types';
 
 /** What `$describe()` gains, each absent unless declared so no other entity's hash moves. */
@@ -68,6 +69,12 @@ function exactColumns(core: EntityCore): Pick<HistoryDescriptionLike, 'text' | '
   };
 }
 
+/** Sealed columns never enter an image (`HistoryDescriptionLike.sealed`). Absent when none. */
+function sealedColumns(core: EntityCore): Pick<HistoryDescriptionLike, 'sealed'> {
+  const sealed = sealedFields(core).map((field) => field.column);
+  return sealed.length === 0 ? {} : { sealed };
+}
+
 const physical = (core: EntityCore, property: string): string => {
   const column = core.$columns[property];
   return column === undefined ? property : columnName(property, column.$meta);
@@ -96,6 +103,7 @@ export function describeLifecycle(
               ]),
             ],
             ...exactColumns(core),
+            ...sealedColumns(core),
           },
         }),
     ...(counters.length === 0 ? {} : { counts: counters.map(describeCounter) }),

package/src/memory-lifecycle.ts

@@ -11,6 +11,7 @@ import { SOFT_DELETE_COLUMN } from './entity';
 import { historyIgnored } from './history';
 import type { MemoryTables } from './memory-same-tenant';
 import type { Tx } from './repo';
+import { sealedFields } from './sealed';
 
 const field = (row: unknown, property: string): unknown =>
   typeof row === 'object' && row !== null ? (row as Record<string, unknown>)[property] : undefined;
@@ -18,10 +19,15 @@ const field = (row: unknown, property: string): unknown =>
 const jsonValue = (value: unknown): unknown =>
   value instanceof Date ? value.toISOString() : value === undefined ? null : value;
 
-/** The stored row as `to_jsonb` spells it: physical names, money as its columns. */
+/**
+ * The stored row as the trigger spells it: physical names, money as its columns, and no sealed
+ * column — its stored string is ciphertext, and a lookup one is deterministic: an equality oracle.
+ */
 export function imageOf(entity: EntityCore, row: unknown): Record<string, unknown> {
   const image = new Map<string, unknown>();
+  const sealed = new Set(sealedFields(entity).map((each) => each.property));
   for (const [property, column] of Object.entries(entity.$columns)) {
+    if (sealed.has(property)) continue;
     const value = field(row, property);
     if (column.$meta.kind !== 'money') {
       image.set(columnName(property, column.$meta), jsonValue(value));

package/src/search-repo.ts

@@ -38,6 +38,21 @@ const keyOf = (entity: EntityCore<unknown>): string => {
   return key;
 };
 
+/**
+ * A full answer is refused, never read: the index stops at `MAX_PAGE_SIZE` hits, so a full list
+ * cannot say whether more matched, and an `in` over it would count, group and page a sample as
+ * if it were every match — where the built-in index counts them all. Not `MAX_PAGE_SIZE + 1`: that
+ * is past the limit every adapter accepts (`searchLimitOf`), so it would break the ones that check
+ * it. The cost is exactly `MAX_PAGE_SIZE` matches being refused too. The index is asked by term and
+ * tenant alone, so the chain's other filters cannot narrow what it answers: the term must.
+ */
+const tooManyHits = (entity: EntityCore<unknown>, indexName: string): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entity.$name}.search(<term>) matched ${MAX_PAGE_SIZE} or more rows in the '${indexName}' search index — it answers at most ${MAX_PAGE_SIZE} ids, so a count, a breakdown or a page over them would be a sample, not every match`,
+    fix: `${entity.$name}.search('<a more specific term>')   # every word must match, so each one added narrows the hits; or installSearchIndex(postgresSearchIndex()) to match inside the statement, unbounded`,
+  });
+
 /** `args` with every `matches` predicate replaced by the ids the installed index answers. */
 const resolved = async (entity: EntityCore<unknown>, args: FindManyArgs): Promise<FindManyArgs> => {
   const where = args.where ?? [];
@@ -56,6 +71,7 @@ const resolved = async (entity: EntityCore<unknown>, args: FindManyArgs): Promis
       term: String(predicate.value ?? ''),
       limit: MAX_PAGE_SIZE,
     });
+    if (hits.length >= MAX_PAGE_SIZE) throw tooManyHits(entity, index.name);
     swapped.push({ column: keyOf(entity), op: 'in', value: hits.map((hit) => hit.id) });
   }
   return { ...args, where: swapped };