@ultimat3/query 12.0.0 → 14.0.0

package/CLAUDE.md

@@ -28,6 +28,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `input-shape.ts` | what a read's `input:` may be, given that its route is a query STRING |
 | `sql.ts` | `explain()` / `describeSql()` |
 | `cache.ts` | the read path: the request memo, and the fill through `@ultimat3/cache`'s registered tiers |
+| `search.ts` | `search()` — the query FACTORY over an entity's `.searchable()` columns |
 | `source.ts` | `SqlSource` contract + `from()` in-memory reference |
 | `shape.ts` | shared read vocabulary (filters, ordering, seek keys) |
 | `policy-gate.ts` | **the only** file that touches `@ultimat3/policy` |
@@ -207,6 +208,20 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   --json` measures, and they must stay that: `errors.ts` runs `registerErrorCodes` at import in both
   packages, and query's `registry.ts` runs `registerPrimitiveRegistrar('query', …)` — drop either
   and a bundled app loses its error titles or throws `X_REGISTRAR_MISSING`. Never `false`.
+- **`search()` is a FACTORY over `query()`, never a ninth primitive.** It owns the input schema
+  (`q` + a `limit` bounded in the schema, beside the read's own keys), trims and refuses a blank
+  term, and calls `.search(term)` on the chain the app hands it — which is what makes the term
+  unable to arrive any other way. The chain crosses **structurally** (`SearchChain`): this package
+  may import `@ultimat3/entity` and nothing here does, so four methods are not worth a new
+  `package.json` edge and a new `bun.lock` block — the trade `@ultimat3/db`'s `entity-shape.ts`
+  makes one tier down. It needs no row in `PRIMITIVE_FACTORIES`: that table is for a factory
+  returning an `action` or a `job` from OUTSIDE the primitive's own package, and this returns a
+  query from the query package. **It serves ONE page and refuses a second**, because a `SqlSource`
+  is handed a `SeekKey` and the entity chain wants its own signed, plan-scoped cursor — there is no
+  minting one from the other here, and falling through to `paginate`'s in-memory slice would cut
+  inside the one page the provider fetched and report `hasNextPage: false` at its edge. Rows served
+  on no page at all is the defect 12.0.0 spent a release removing from the timestamp seek; the
+  `fix:` names the entity chain, which pages this read correctly.
 - Policy runs per subscriber for live queries. Never cache a decision across actors.
 - The matcher patches from `QueryShape`, never from SQL text.
 - `paginate` has no `offset` parameter and must never grow one, and it is reachable **only** as

package/README.md

@@ -172,6 +172,54 @@ server memory bought with an occasional extra page fetch.
 An honest refusal beats a silently wrong result set, so unsupported shapes fail at
 **subscribe** time, not on the first change event.
 
+## `search()` — the query factory over a searchable entity
+
+A model call is an `action` and a sweep is a `job`; a search is a **read**, so `search()` returns a
+`query`. It inherits the policy, the cache tags, the MCP tool, the typed client, the route and its
+manifest row — there is no ninth primitive.
+
+```ts
+import { type QueryPolicy, search, type SearchChain, t } from '@ultimat3/query';
+
+interface PostRow {
+  readonly id: string;
+  readonly title: string;
+  readonly createdAt: Date;
+}
+
+// `@ultimat3/entity`'s chain, crossed STRUCTURALLY: a real `db.posts` satisfies `SearchChain`
+// as written, so this package holds no dependency edge on entity.
+declare const db: {
+  readonly posts: {
+    where(filter: { readonly orgId: string }): {
+      orderBy(column: keyof PostRow & string, direction: 'asc' | 'desc'): SearchChain<PostRow>;
+    };
+  };
+};
+declare const postRead: QueryPolicy;
+declare const orgId: string;
+
+export const searchPosts = search({
+  input: { orgId: t.uuid },              // your own keys — `q` and `limit` are added
+  policy: postRead,
+  page: { max: 50, default: 20 },
+  // The chain WITHOUT the term: tenancy, filters, and the order the page is served in.
+  in: ({ input }) => db.posts.where({ orgId: input.orgId }).orderBy('createdAt', 'desc'),
+});
+
+// A query is CALLABLE — there is no `.run()`; `.as()`, `.page()` and `.client()` are the rest.
+await searchPosts({ orgId, q: 'cats -dogs "exact phrase"' });
+```
+
+`search()` adds `.search(q)` and `.limit(limit)` and nothing else, which is what makes the term
+unable to arrive any other way. A blank term is refused rather than answered with no rows — an
+empty box is not an empty result set.
+
+**It serves one page.** The rows come from the entity chain, which pages by its own signed cursor;
+that cursor cannot cross the `SqlSource` seam, and slicing in memory instead would cut inside the
+page the provider fetched and report `hasNextPage: false` at its edge. So a second page is
+refused, and the `fix:` names the chain — `db.posts.search(term).after(cursor).page()`.
+
 ## Pagination is cursor-only
 
 `offset` does not exist in this package on purpose: it makes the database count rows it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "12.0.0",
+  "version": "14.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -35,10 +35,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "12.0.0",
-    "@ultimat3/core": "12.0.0",
-    "@ultimat3/http": "12.0.0",
-    "@ultimat3/policy": "12.0.0",
-    "@ultimat3/schema": "12.0.0"
+    "@ultimat3/cache": "14.0.0",
+    "@ultimat3/core": "14.0.0",
+    "@ultimat3/http": "14.0.0",
+    "@ultimat3/policy": "14.0.0",
+    "@ultimat3/schema": "14.0.0"
   }
 }

package/src/index.ts

@@ -133,6 +133,9 @@ export {
   registerQuery,
   resetRegistry,
 } from './registry';
+/** The query FACTORY over an entity's searchable columns — a `query`, never a ninth primitive. */
+export type { SearchChain, SearchDef, SearchInput, SearchPage } from './search';
+export { search } from './search';
 export type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
 /**
  * `isNull` is the one definition of SQL NULL a custom `SqlSource` has to agree with, and

package/src/search.ts

@@ -0,0 +1,145 @@
+/**
+ * `search()` — a QUERY FACTORY over an entity's `.searchable()` columns, the shape `llm()` and
+ * `backfill()` already have. It returns a `query`, so a search inherits the policy, the cache tags,
+ * the MCP tool, the typed client, the route and its manifest row rather than becoming a ninth
+ * primitive. What it adds is the one thing a hand-written read gets wrong: the term never becomes
+ * syntax, and the tenant predicate is never optional.
+ */
+
+import { assert, type Ctx } from '@ultimat3/core';
+import type { InferOutput, Shape, Simplify } from '@ultimat3/schema';
+import { t } from '@ultimat3/schema';
+import type { QueryPolicy } from './policy-gate';
+import type { QueryCache, QueryMcp, QueryRateLimit } from './query';
+import { query } from './query';
+import type { SeekKey } from './shape';
+import type { SqlSource, SqlText } from './source';
+import { from } from './source';
+
+/**
+ * What `@ultimat3/entity`'s `ReadBuilder` answers, crossed STRUCTURALLY.
+ *
+ * This package may import `@ultimat3/entity` (tier 2) and deliberately does not: nothing here does
+ * today, so a real dependency would be a new edge in `package.json` and a new block in `bun.lock`
+ * for four methods. Same trade `@ultimat3/db`'s `entity-shape.ts` makes one tier down, and the same
+ * discipline — the shape is the contract, and a chain that does not satisfy it does not compile.
+ */
+export interface SearchChain<Row extends object> {
+  /** Appends the full-text predicate. The TERM, never a tsquery. */
+  search(term: string): SearchChain<Row>;
+  limit(rows: number): SearchChain<Row>;
+  all(): Promise<readonly Row[]>;
+  /** Only `entity` is read — the name the `SqlSource` and every cache tag are keyed by. */
+  plan(): { readonly entity: string };
+}
+
+export interface SearchPage {
+  /** The largest page this read will serve. Bounded in the INPUT SCHEMA, so a client cannot ask past it. */
+  readonly max?: number;
+  readonly default?: number;
+}
+
+const DEFAULT_PAGE_MAX = 100;
+const DEFAULT_PAGE_SIZE = 20;
+/**
+ * The longest term accepted. A `tsquery` past ~1 MB is a server error, and a search box does not
+ * send a novel — the bound belongs in the schema so it is refused before a statement exists.
+ */
+const DEFAULT_TERM_MAX = 200;
+
+export interface SearchDef<S extends Shape, Row extends object> {
+  /** The read's own input keys, beside `q` and `limit` — a tenant id, a status filter, a date. */
+  readonly input?: S;
+  readonly policy: QueryPolicy;
+  /**
+   * The chain this search runs on, WITHOUT the term: the tenancy, the filters and the ordering the
+   * page is served in. `search()` adds `.search(q)` and `.limit(limit)` and nothing else, which is
+   * what makes the term unable to arrive any other way.
+   */
+  in(args: { readonly input: SearchInput<S>; readonly ctx: Ctx }): SearchChain<Row>;
+  readonly termMax?: number;
+  readonly page?: SearchPage;
+  readonly cache?: QueryCache;
+  readonly mcp?: QueryMcp;
+  readonly rateLimit?: QueryRateLimit;
+}
+
+type SearchShape<S extends Shape> = Simplify<
+  S & { q: ReturnType<typeof termSchema>; limit: ReturnType<typeof limitSchema> }
+>;
+
+export type SearchInput<S extends Shape> = InferOutput<ReturnType<typeof t.object<SearchShape<S>>>>;
+
+const termSchema = (max: number) => t.string.min(1).max(max);
+
+const limitSchema = (max: number, fallback: number) =>
+  t.number.int().min(1).max(max).default(fallback);
+
+/**
+ * A search serves ONE page, and asking for a second is refused rather than answered wrongly.
+ *
+ * The rows come from the entity chain, which pages by its own keyset cursor — proven against a real
+ * server in `packages/entity/src/pg-search.live.test.ts`. That cursor cannot cross this seam: a
+ * `SqlSource` is handed a `SeekKey` (the previous page's sort VALUES) and the chain wants its own
+ * signed, plan-scoped string, and there is no way to mint one from the other here. Falling through
+ * to `paginate`'s in-memory slice would cut inside the one page the provider fetched and report
+ * `hasNextPage: false` at its edge — rows served on no page at all, which is the defect 12.0.0 spent
+ * a release removing from the timestamp seek. So it is a refusal with the alternative in the `fix`:
+ * page with the entity chain's own `.search(term).after(cursor)`, or raise this read's `limit`.
+ */
+const onePage = <Row extends object>(base: SqlSource<Row>, entity: string): SqlSource<Row> => ({
+  toSQL: (): SqlText => base.toSQL(),
+  execute: () => base.execute(),
+  shape: () => base.shape(),
+  ...(base.total === undefined ? {} : { total: () => onePage(base.total?.() ?? base, entity) }),
+  seek: (after: SeekKey | null, limit: number): SqlSource<Row> => {
+    assert(
+      after === null,
+      `search of ${entity} serves one page: a relevance-filtered read has no cursor this layer can carry`,
+      `db.${entity}.search(term).orderBy('<key>').after(cursor).page()   # the entity chain pages this read — or raise its limit`,
+    );
+    return onePage(base.seek?.(after, limit) ?? base, entity);
+  },
+});
+
+/**
+ * The factory. `live: false` and the source declares itself unpatchable, because the incremental
+ * matcher decides membership from `QueryShape` filters and a `tsvector` match is not one of them —
+ * a live search would have to re-read on every write to the table.
+ */
+export const search = <Row extends object, S extends Shape = Record<string, never>>(
+  def: SearchDef<S, Row>,
+) => {
+  const page = def.page ?? {};
+  const max = page.max ?? DEFAULT_PAGE_MAX;
+  const shape = {
+    ...((def.input ?? {}) as S),
+    q: termSchema(def.termMax ?? DEFAULT_TERM_MAX),
+    limit: limitSchema(max, Math.min(page.default ?? DEFAULT_PAGE_SIZE, max)),
+  } as SearchShape<S>;
+
+  return query({
+    input: t.object(shape),
+    policy: def.policy,
+    live: false,
+    ...(def.cache === undefined ? {} : { cache: def.cache }),
+    ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
+    ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
+    sql: (input, ctx) => {
+      const parsed = input as SearchInput<S> & { readonly q: string; readonly limit: number };
+      // Trimmed and refused HERE, before the chain exists: `websearch_to_tsquery('english', '  ')`
+      // is a legal empty tsquery matching nothing, so a blank box would answer "no results" as if
+      // it had searched. Saying so is the difference between an empty answer and an empty question.
+      const term = parsed.q.trim();
+      assert(
+        term.length > 0,
+        'a search term of only whitespace is not a search',
+        'guard the input before calling: if (term.trim() === "") return [] — an empty box is not an empty result set',
+      );
+      const chain = def.in({ input: parsed, ctx });
+      const name = chain.plan().entity;
+      const rows = () => chain.search(term).limit(parsed.limit).all();
+      return onePage(from<Row>(name, rows).raw('full-text search'), name);
+    },
+  });
+};