@ultimat3/admin 31.25.0 → 31.26.0

package/CLAUDE.md

@@ -28,12 +28,13 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **A `/_x` source reads a registry through its DESCRIPTOR TYPE, never as an untyped bag** — `import type { RouteDescriptor }` beside the dynamic `import()`; `dev/published-keys.test.ts` walks what the registries EMIT. A route fact carries `mount` (`{ by, permissions }` or `null`).
 - **A fact `/_x` cannot know is absent or `null` — never a value that happens to be constant.** `JobDescriptor.idempotent` is published *because* `job()` refuses a definition without a key. `DbPanelData.drift` is `null` when nothing wired the check, because drift is the entities against the DATABASE and `[]` claims a match nobody verified.
 - **The routes are in the framework's ONE route list, as mounted routes** — `route-config.ts` calls `registerMountedRoutes` at `defineAdmin`, so `describePages()` (`x routes`, `/_x`, `sw.js`, the manifest) lists each with `mount: { by: 'defineAdmin', permissions }` and `routeEntries()` holds none. `AdminApp.describe()` (`describe.ts`) is what the manifest's `admin` section records: filters, sorts, scopes, `rowScoped`, routes.
-- **The admin's stylesheets are claimed for `app/`** (`stylesheet-scope.ts`, `claimStylesheets`). `stylesheet-scope.test.ts`.
+- **The admin's stylesheets are claimed for `app/`** (`claimStylesheets` in `stylesheet-scope(.test).ts`).
 - **Importing this package declares NO permission.** `defineAdmin()` calls `declareAdminPermissions`, which registers `ADMIN_PERMISSIONS` plus what the mount derives (`policy-bridge.test.ts`).
 - **One bridge per foreign package.** `policy-bridge.ts` → `evaluate`/`definePermissions`; `route-config.ts` → `defineRoute`/`registerMountedRoutes` (+ `claim-route.ts`, the `@ultimat3/http` bridge); `mcp.ts` → `defineAppMcp`; `dev/data.ts` → introspection, dynamically. A test declares its own fixtures' permissions and calls `defineAdmin()` in `beforeAll`, never at module scope.
 - **One entity surface** (`registry.ts`) — the admin reads what `entity()` actually exposes: `$name`, `$primaryKey`, `$columns[c].$meta`, `$schema`, `$describe()`. It is a structural subset so a new column kind still derives, and `RegisteredEntity` is the `tsc`-checked proof that a real `entity()` result satisfies it — never a comment claiming it does.
 - **One flattener.** `entity-columns.ts` is the only file that reads `$meta` or calls `$describe()`; everything downstream takes `AdminColumnFacts`. Money stays one property (the admin renders rows, not tables), a FK target comes back resolved from `$describe()`, and only a **generated** default (`uuid`, `now`) is read-only — `.default('free')` is a starting value.
-- **A deliberate query loop declares itself** — `expectedQueryLoop()` from `@ultimat3/db`, with a `reason` (`search.ts`, `batch.ts`, `relations.ts`). Never a comment pragma, never an exempt list; an undeclared loop is an N+1.
+- **A deliberate query loop declares itself** — `expectedQueryLoop()` from `@ultimat3/db`, with a `reason` (`search-resource.ts`, `batch.ts`, `relations.ts`), never a pragma or exempt list.
+- **Search: vector, then `contains`** (`search-resource.ts`): `AdminRepo.search` iff `$search`; only `X_SEARCH_IN_MEMORY` falls back.
 - **The timeline panel renders the detector's verdicts** (`DevSources.statementLoops()`), never a second count; none wired is `null`, never `[]`.
 - **This catalog is the framework's one opt-OUT MCP surface, deliberately**: `mcp-tools.ts` does not call `isMcpExposed` — every tool is already gated on an admin permission. `mcp: { expose: false }` withdraws one. A *second* exception anywhere is the bug.
 - **A dev panel catches only the error that means "not wired".** `DevSourceUnavailableError` and nothing wider — in `panel-live`, `panel-db`, `panel-timeline` and `panel-cache` alike (`dev/panel-degrade.test.ts`). Everything else reaches `panelPayload`, which renders its code and its fix.
@@ -105,8 +106,7 @@ Why each rule is shaped the way it is: [`docs/history/admin.md`](../../docs/hist
 
 ## Commands
 
-From the repo root — the seal-key preload is the root's, so `bun test --filter` from this
-directory fails on the first sealed column:
+From the repo root (the seal-key preload is the root's):
 
 ```bash
 bun test ./packages/admin/

package/README.md

@@ -481,8 +481,18 @@ Reads are audited too, and on both branches: `adminDetail` keys its entry on the
 `adminList` and `adminSearch` key theirs on the table (`entityId: null`), and a refusal is an
 entry of its own. `AdminSearchResult.audit` carries one entry per resource the call decided
 about — searched or refused — so a jump box that walked every readable entity leaves a trace.
-Search is the entity's `contains` per text field — case-insensitive, the `ilike` a `gin_trgm_ops`
-index serves — at most three statements per resource, resources read four at a time.
+Search asks an entity that declares `.searchable()` columns through its vector first —
+`search_tsv`, the GIN index, one statement, `matchedField: 'search_tsv'` — then fills a short page
+with the entity's `contains` per text field — case-insensitive, the `ilike` a `gin_trgm_ops` index
+serves — so a whole word and a prefix ("ali" → "Alice") both find the row. At most 1 + 3
+statements per resource, resources read four at a time, the row scope on every one. Hits are in
+the resource's `defaultSort`, not ranked. A custom `repo:` opts in with `search(query)`
+(`AdminRepo.search`, optional); the memory driver refuses a vector match (`X_SEARCH_IN_MEMORY`),
+so there `contains` alone answers. As of 2026-11 the GIN index serves the vector read only when the
+`defaultSort` is a column no btree covers: every handle read ends in the primary key, so a sort by
+`id` (or an indexed column) with a limit walks that btree and filters `@@` row by row — 139 ms
+tenanted, 283 ms untenanted, against the GIN's 11 ms, on 200,000 rows. The fix is a relevance
+order (`ts_rank`), which no btree serves: deferred with ranking (plan 101-finished slice 06 U2).
 
 ## AI-first
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "31.25.0",
+  "version": "31.26.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "keywords": [
     "ultimate",
@@ -46,21 +46,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "31.25.0",
-    "@ultimat3/ai": "31.25.0",
-    "@ultimat3/cache": "31.25.0",
-    "@ultimat3/core": "31.25.0",
-    "@ultimat3/db": "31.25.0",
-    "@ultimat3/entity": "31.25.0",
-    "@ultimat3/http": "31.25.0",
-    "@ultimat3/i18n": "31.25.0",
-    "@ultimat3/jobs": "31.25.0",
-    "@ultimat3/mcp": "31.25.0",
-    "@ultimat3/money": "31.25.0",
-    "@ultimat3/policy": "31.25.0",
-    "@ultimat3/query": "31.25.0",
-    "@ultimat3/render": "31.25.0",
-    "@ultimat3/schema": "31.25.0",
-    "@ultimat3/ui": "31.25.0"
+    "@ultimat3/action": "31.26.0",
+    "@ultimat3/ai": "31.26.0",
+    "@ultimat3/cache": "31.26.0",
+    "@ultimat3/core": "31.26.0",
+    "@ultimat3/db": "31.26.0",
+    "@ultimat3/entity": "31.26.0",
+    "@ultimat3/http": "31.26.0",
+    "@ultimat3/i18n": "31.26.0",
+    "@ultimat3/jobs": "31.26.0",
+    "@ultimat3/mcp": "31.26.0",
+    "@ultimat3/money": "31.26.0",
+    "@ultimat3/policy": "31.26.0",
+    "@ultimat3/query": "31.26.0",
+    "@ultimat3/render": "31.26.0",
+    "@ultimat3/schema": "31.26.0",
+    "@ultimat3/ui": "31.26.0"
   }
 }

package/src/index.ts

@@ -209,6 +209,7 @@ export {
   type AdminMatchingResult,
   type AdminRepo,
   type AdminRow,
+  type AdminSearchQuery,
   type AdminSort,
   type AdminTable,
   type AdminTableRead,

package/src/registry.ts

@@ -95,6 +95,12 @@ export interface AdminEntity {
    * fixture has none: never a form input, and every update carries the version the admin read.
    */
   readonly $version?: string | null;
+  /**
+   * The generated `tsvector` its `.searchable()` columns derive, `null` with none. Optional only
+   * because a hand-built fixture has none. The admin reads the COLUMN alone: it names a full-text
+   * hit's `matchedField`, and its presence is what makes `adminRepoFor` offer `search`.
+   */
+  readonly $search?: { readonly column: string } | null;
   /** Resolves foreign-key targets. See `entity-columns.ts` for what the admin takes from it. */
   $describe(): AdminEntityDescription;
 }
@@ -119,6 +125,11 @@ export interface AdminTableRead {
   andWhere(column: string, op: Operator, value?: unknown): AdminTableRead;
   orderBy(column: string, direction?: 'asc' | 'desc'): AdminTableRead;
   limit(rows: number): AdminTableRead;
+  /**
+   * The entity's full-text match — legal only on an entity whose `$search` is not `null`.
+   * Optional so a hand-built table still satisfies this surface; `database()`'s always has it.
+   */
+  search?(term: string): AdminTableRead;
   all(): Promise<readonly AdminRow[]>;
   one(): Promise<AdminRow | null>;
   count(): Promise<number>;
@@ -218,8 +229,23 @@ export interface AdminListQuery {
   readonly before?: KeysetBound;
 }
 
+/** One full-text read: the search box's term over the resource's row scope, first page only. */
+export interface AdminSearchQuery {
+  /** User text. Bound as a parameter and parsed by `websearch_to_tsquery`, never a tsquery. */
+  readonly term: string;
+  readonly where: readonly AdminFilter[];
+  readonly sort: AdminSort;
+  readonly limit: number;
+}
+
 export interface AdminRepo<Row> {
   list(query: AdminListQuery): Promise<readonly Row[]>;
+  /**
+   * The entity's declared full-text index (`search_tsv`, GIN), when it has one. Optional: a custom
+   * `repo:` without it is searched by `contains` alone. The memory driver rejects it
+   * `X_SEARCH_IN_MEMORY`, which `adminSearch` answers with the `contains` loop.
+   */
+  search?(query: AdminSearchQuery): Promise<readonly Row[]>;
   find(id: string): Promise<Row | null>;
   create(input: Readonly<Record<string, unknown>>): Promise<Row>;
   update(id: string, patch: Readonly<Record<string, unknown>>): Promise<Row>;

package/src/repo-entity.ts

@@ -13,6 +13,7 @@ import type {
   AdminListQuery,
   AdminRepo,
   AdminRow,
+  AdminSearchQuery,
   AdminTable,
   AdminTableRead,
 } from './registry';
@@ -105,6 +106,7 @@ export function adminRepoFor(entity: AdminEntity, table: AdminTable): AdminRepo<
   const idColumn = Object.hasOwn(entity.$columns, idField) ? entity.$columns[idField] : undefined;
   const typed = typedBy(entity);
   const columns = adminColumnsOf(entity);
+  const searchOf = table.search;
   /**
    * `AdminRepo` carries `id: string` — a URL param, untyped by nature. The primary key column's
    * OWN `$parse` is what earns the crossing: `/posts/nope` is judged here, at the door, instead
@@ -159,6 +161,19 @@ export function adminRepoFor(entity: AdminEntity, table: AdminTable): AdminRepo<
         },
       );
     },
+    // Offered only when the entity declares a vector: the handle refuses `.search()` on one that
+    // does not (`X_SEARCH_UNDECLARED`), and an absent verb is how `adminSearch` knows to skip it.
+    ...(entity.$search === undefined || entity.$search === null || searchOf === undefined
+      ? {}
+      : {
+          search: async (query: AdminSearchQuery): Promise<readonly AdminRow[]> => {
+            const { field, direction } = query.sort;
+            const read = filtered(searchOf.call(table, query.term), query.where, typed);
+            // The id breaks ties, as on a list page; named once when it IS the sort.
+            const sorted = field === idField ? read : read.orderBy(field, direction);
+            return [...(await sorted.orderBy(idField, direction).limit(query.limit).all())];
+          },
+        }),
     // `async`, so a refused id arrives as a rejection: these return promises, and a caller that
     // chains `.catch()` instead of `await`ing would never see a synchronous throw.
     find: async (id) => {

package/src/search-resource.ts

@@ -0,0 +1,108 @@
+// One resource's answer to the search box: its declared full-text index first (`search_tsv`, GIN,
+// one statement), then one `contains` per text field to fill a short page — so a whole word and a
+// substring ("ali" → "Alice") both find the row. At most 1 + `MAX_FIELDS_PER_RESOURCE` statements.
+
+import { isUltimateError } from '@ultimat3/core';
+import { expectedQueryLoop } from '@ultimat3/db';
+import type { AdminActor } from './authz';
+import { rowWhere } from './list-scope';
+import type { AdminFilter, AdminRepo, AdminRow } from './registry';
+import { rowId } from './registry';
+import { labelOf } from './relations';
+import { type AdminResource, repoOf } from './resource';
+
+/** Per resource, and per field within it. Search is a jump box, not a report. */
+const MAX_FIELDS_PER_RESOURCE = 3;
+
+export interface AdminSearchHit {
+  readonly entity: string;
+  readonly id: string;
+  /** The row's label-field value. Already a string; the view does not format it. */
+  readonly label: string;
+  /** The text field a `contains` matched, or the vector column for a full-text hit. */
+  readonly matchedField: string;
+  /** Mount-relative link to the detail page. */
+  readonly href: string;
+}
+
+/**
+ * The full-text read, or `[]` where it cannot run: no vector, a repo with no `search`, or the
+ * memory driver — which refuses a vector match (`X_SEARCH_IN_MEMORY`) rather than answer one
+ * Postgres would not, so there the `contains` loop is the whole answer. Any other failure is
+ * the resource's failure, as a `contains` read's is.
+ */
+async function vectorRows(
+  resource: AdminResource,
+  repo: AdminRepo<AdminRow>,
+  where: readonly AdminFilter[],
+  term: string,
+  limit: number,
+): Promise<readonly AdminRow[]> {
+  if (repo.search === undefined || (resource.entity.$search ?? null) === null) return [];
+  try {
+    return await repo.search({ term, where, sort: resource.defaultSort, limit });
+  } catch (error) {
+    if (isUltimateError(error) && error.code === 'X_SEARCH_IN_MEMORY') return [];
+    throw error;
+  }
+}
+
+/**
+ * One `contains` per searchable field rather than one query with an OR: the admin's query IR is a
+ * conjunction by design, and each field's `contains` is the entity's case-insensitive `ilike` —
+ * served by that column's `gin_trgm_ops` index where the app declared one (`X_QUERY_UNINDEXED`
+ * names the declaration where it did not), which one OR across columns could not use.
+ *
+ * That argument is declared to the runtime and not only to the reader — `expectedQueryLoop`
+ * carries it onto every statement the loop issues, so a statement diagnostic reports the loops
+ * nobody argued for and never this one. The scope ends with the loop: anything the repo does
+ * afterwards is judged normally.
+ */
+export async function searchResource(
+  resource: AdminResource,
+  actor: AdminActor,
+  term: string,
+  limit: number,
+): Promise<readonly AdminSearchHit[]> {
+  const repo = repoOf(resource);
+  // The resource's row scope rides every lookup, the vector's included: a hit is a row, and a row
+  // this actor's `rows` leaves out is not one they may be told exists.
+  const visible = rowWhere(resource, actor);
+  const seen = new Set<string>();
+  const hits: AdminSearchHit[] = [];
+  const take = (rows: readonly AdminRow[], matchedField: string): boolean => {
+    for (const row of rows) {
+      const id = rowId(row, resource.idField);
+      if (id === '' || seen.has(id)) continue;
+      seen.add(id);
+      hits.push({
+        entity: resource.name,
+        id,
+        label: labelOf(row, resource),
+        matchedField,
+        href: `${resource.path}/${id}`,
+      });
+      if (hits.length >= limit) return true;
+    }
+    return false;
+  };
+
+  return expectedQueryLoop(
+    'admin search runs one indexed lookup per text field, which beats one unindexed OR',
+    async () => {
+      const vector = resource.entity.$search?.column;
+      if (vector !== undefined) {
+        if (take(await vectorRows(resource, repo, visible, term, limit), vector)) return hits;
+      }
+      for (const field of resource.searchFields.slice(0, MAX_FIELDS_PER_RESOURCE)) {
+        const where: readonly AdminFilter[] = [
+          ...visible,
+          { field: field.name, op: 'contains', value: term },
+        ];
+        const rows = await repo.list({ where, sort: resource.defaultSort, limit });
+        if (take(rows, field.name)) return hits;
+      }
+      return hits;
+    },
+  );
+}

package/src/search.ts

@@ -1,22 +1,17 @@
-// Cross-entity search, derived: every resource's text fields are the index. No separate
-// search config to drift from the entities, and no result an actor could not have opened —
-// the same `admin:read` + `<entity>:read` pair gates the hit and the detail page it links to.
+// Cross-entity search, derived: an entity's declared full-text index, then its text fields, are
+// the index (`search-resource.ts`). No separate search config to drift from the entities, and no
+// result an actor could not have opened — `admin:read` + `<entity>:read` gate hit and detail alike.
 
 import { finiteCount, mapBounded } from '@ultimat3/core';
-import { expectedQueryLoop } from '@ultimat3/db';
 import { type AuditEntry, deniedDraft } from './audit';
-import type { AdminActor } from './authz';
 import { adminDenied } from './authz';
 import type { CrudCtx } from './crud';
 import { decideOperation } from './crud';
-import { rowWhere } from './list-scope';
-import type { AdminFilter } from './registry';
-import { rowId } from './registry';
-import { labelOf } from './relations';
-import { type AdminResource, repoOf } from './resource';
+import type { AdminResource } from './resource';
+import { type AdminSearchHit, searchResource } from './search-resource';
+
+export type { AdminSearchHit } from './search-resource';
 
-/** Per resource, and per field within it. Search is a jump box, not a report. */
-const MAX_FIELDS_PER_RESOURCE = 3;
 const DEFAULT_LIMIT_PER_RESOURCE = 5;
 /**
  * Resources read at once. Independent reads, so their latencies overlap rather than add — and a
@@ -24,16 +19,6 @@ const DEFAULT_LIMIT_PER_RESOURCE = 5;
  */
 const SEARCH_WIDTH = 4;
 
-export interface AdminSearchHit {
-  readonly entity: string;
-  readonly id: string;
-  /** The row's label-field value. Already a string; the view does not format it. */
-  readonly label: string;
-  readonly matchedField: string;
-  /** Mount-relative link to the detail page. */
-  readonly href: string;
-}
-
 export interface AdminSearchResult {
   readonly term: string;
   readonly hits: readonly AdminSearchHit[];
@@ -57,59 +42,6 @@ export interface AdminSearchInput {
   readonly limitPerResource?: number;
 }
 
-/**
- * One `contains` per searchable field rather than one query with an OR: the admin's query IR is a
- * conjunction by design, and each field's `contains` is the entity's case-insensitive `ilike` —
- * served by that column's `gin_trgm_ops` index where the app declared one (`X_QUERY_UNINDEXED`
- * names the declaration where it did not), which one OR across columns could not use.
- *
- * That argument is declared to the runtime and not only to the reader — `expectedQueryLoop`
- * carries it onto every statement the loop issues, so a statement diagnostic reports the loops
- * nobody argued for and never this one. At most `MAX_FIELDS_PER_RESOURCE` queries, and the scope
- * ends with the loop: anything the repo does afterwards is judged normally.
- */
-async function searchResource(
-  resource: AdminResource,
-  actor: AdminActor,
-  term: string,
-  limit: number,
-): Promise<readonly AdminSearchHit[]> {
-  const repo = repoOf(resource);
-  // The resource's row scope rides every lookup: a hit is a row, and a row this actor's `rows`
-  // leaves out is not one they may be told exists.
-  const visible = rowWhere(resource, actor);
-  const fields = resource.searchFields.slice(0, MAX_FIELDS_PER_RESOURCE);
-  const seen = new Set<string>();
-  const hits: AdminSearchHit[] = [];
-
-  return expectedQueryLoop(
-    'admin search runs one indexed lookup per text field, which beats one unindexed OR',
-    async () => {
-      for (const field of fields) {
-        const where: readonly AdminFilter[] = [
-          ...visible,
-          { field: field.name, op: 'contains', value: term },
-        ];
-        const rows = await repo.list({ where, sort: resource.defaultSort, limit });
-        for (const row of rows) {
-          const id = rowId(row, resource.idField);
-          if (id === '' || seen.has(id)) continue;
-          seen.add(id);
-          hits.push({
-            entity: resource.name,
-            id,
-            label: labelOf(row, resource),
-            matchedField: field.name,
-            href: `${resource.path}/${id}`,
-          });
-          if (hits.length >= limit) return hits;
-        }
-      }
-      return hits;
-    },
-  );
-}
-
 const SKIPPED_FORBIDDEN = 'admin.search.skipped.forbidden';
 const SKIPPED_FAILED = 'admin.search.skipped.failed';