@ultimat3/cli 29.4.0 → 30.1.0

package/src/templates/guard-repo-raw-sql.ts

@@ -16,8 +16,10 @@ const source =
 // step — nothing registers this file, so nothing can forget to. Delete it to drop the rule.
 //
 // Only a statement the handle can express is reported: \`select *\`, \`insert\`, \`update\` or \`delete\`
-// on ONE table, with plain comparisons. A join, an aggregate, a CTE, a window, an \`or\`, a function
+// on ONE table, with plain comparisons, and \`select * … where id = ? for update\`. A join, an aggregate, a CTE, a window, an \`or\`, a function
 // call and a statement composed from another fragment are past what the handle says, and silent.
+// One more shape is reported in any statement, join or not: an \`order by date_trunc('milliseconds', …)\`,
+// whose repair is \`keyset()\` from \`@ultimat3/db\`.
 
 import type { Finding, Guard } from '@ultimat3/cli';
 
@@ -142,6 +144,8 @@ const UPDATE = new RegExp(
   \`^update \${TABLE} set \${ASSIGNMENT}(?:, ?\${ASSIGNMENT})* where \${WHERE}(?: returning \\\\*)?$\`,
 );
 const DELETE = new RegExp(\`^delete from \${TABLE} where \${WHERE}(?: returning \\\\*)?$\`);
+/** One row by its id, locked: the read-modify-write \`lock\` exists for. Another lock mode is silent. */
+const LOCKED = new RegExp(\`^select \\\\* from \${TABLE} where \${WHERE}(?: limit 1)? for update$\`);
 
 /** \`short_links\` → \`shortLinks\`: the handle is keyed by the camelCase the entity declares. */
 const camel = (name: string): string =>
@@ -190,6 +194,10 @@ export function handleCallFor(sql: string): string | undefined {
     .trim()
     .replace(/;$/, '')
     .trim();
+  const locked = LOCKED.exec(text);
+  if (locked !== null && /(^| )"?id"? = \\?/.test(locked[2] ?? '')) {
+    return \`db.\${camel(locked[1] ?? '')}.lock(id, fn)\`;
+  }
   const select = SELECT.exec(text);
   if (select !== null) {
     const [, table = '', where, column, direction, limit] = select;
@@ -220,11 +228,38 @@ export function handleCallFor(sql: string): string | undefined {
   return undefined;
 }
 
+/**
+ * \`order by date_trunc('milliseconds', col)\`: the cure for a JS \`Date\` dropping microseconds, and
+ * the plan's loss — an expression the index does not hold sorts every row. A line comment inside
+ * the statement is not code, so it is dropped before the match.
+ */
+export function truncatedOrder(sql: string): boolean {
+  const text = sql
+    .replaceAll(/--[^\\n]*/g, ' ')
+    .toLowerCase()
+    .replaceAll(/\\s+/g, ' ');
+  return /\\border by [^;]*\\bdate_trunc ?\\( ?'milliseconds'/.test(text);
+}
+
+const KEYSET_CALL =
+  "keyset({ scope, keys: [{ column: raw('p.created_at'), kind: 'timestamptz', direction: 'desc' }, { column: raw('p.id'), kind: 'uuid', direction: 'desc' }], after, limit })";
+
+const truncatedFinding = (at: string): Finding => ({
+  code: CODE,
+  cause: \`\${at} orders by date_trunc('milliseconds', …), the workaround for a Date losing microseconds — and the index cannot serve that expression: measured on 300,000 rows, an Index Only Scan (0.2 ms) became a Parallel Seq Scan and a sort (100 ms)\`,
+  fix: \`\${KEYSET_CALL} — from @ultimat3/db, its select, where, orderBy and limit spliced in place of the date_trunc order at \${at}, then: x verify\`,
+  at,
+});
+
 /** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
 export function rawRepoSql(files: readonly RepoFile[]): readonly Finding[] {
   const findings: Finding[] = [];
   for (const file of files) {
     for (const statement of sqlStatements(file.source)) {
+      if (truncatedOrder(statement.text)) {
+        findings.push(truncatedFinding(\`\${file.path}:\${statement.line}\`));
+        continue;
+      }
       const call = handleCallFor(statement.text);
       if (call === undefined) continue;
       const at = \`\${file.path}:\${statement.line}\`;
@@ -254,7 +289,7 @@ const test =
 // a green gate over the convention it was written to enforce.
 
 import { expect, unitTest } from '@ultimat3/testing';
-import { handleCallFor, rawRepoSql, sqlStatements } from './repo-raw-sql';
+import { handleCallFor, rawRepoSql, sqlStatements, truncatedOrder } from './repo-raw-sql';
 
 const REPO = 'apps/web/app/post/repo.ts';
 const repo = (source: string) => [{ path: REPO, source }];
@@ -302,6 +337,18 @@ unitTest('insert, update and delete on one table are the same rule', () => {
   );
 });
 
+unitTest('a row locked by its id is the lock call, with or without its tenant', () => {
+  const locks = [
+    'select * from posts where id = ? for update',
+    'select * from posts where id = ? limit 1 for update',
+    'SELECT * FROM posts WHERE org_id = ? AND id = ? FOR UPDATE;',
+  ];
+  for (const sql of locks) expect(handleCallFor(sql)).toBe('db.posts.lock(id, fn)');
+  const source = \`const row = sql\\\`select * from short_links where id = \${hole('id')} for update\\\`;\`;
+  const findings = rawRepoSql(repo(source));
+  expect(findings[0]?.fix).toStartWith('db.shortLinks.lock(id, fn) — ');
+});
+
 // The legitimate lookalikes — the reason the rule can stay switched on. Each is a statement the
 // handle has no word for, and raw SQL in a repo is the right answer for it.
 unitTest('a statement past what the handle says is silent', () => {
@@ -314,10 +361,32 @@ unitTest('a statement past what the handle says is silent', () => {
     'with recent as (select * from posts) select * from recent',
     'update posts set like_count = like_count + 1 where id = ?',
     'insert into likes (post_id, user_id) values (?, ?) on conflict do nothing',
+    'select * from jobs where state = ? for update skip locked',
+    'select * from posts where id = ? for no key update',
+    'select * from posts where org_id = ? for update',
   ];
   for (const sql of silent) expect(handleCallFor(sql)).toBeUndefined();
 });
 
+unitTest(
+  'an order by a millisecond-truncated column is refused in any statement, naming keyset()',
+  () => {
+    const join =
+      "select p.* from posts p join members m on m.id = p.author_id order by date_trunc('milliseconds', p.created_at) desc, p.id desc";
+    expect(truncatedOrder(join)).toBe(true);
+    expect(
+      truncatedOrder(
+        "select * from posts where date_trunc('day', created_at) = ? order by created_at",
+      ),
+    ).toBe(false);
+    expect(
+      truncatedOrder("select * from posts -- order by date_trunc('milliseconds', created_at)"),
+    ).toBe(false);
+    const findings = rawRepoSql(repo(\`const q = sql\\\`\${join}\\\`;\`));
+    expect(findings[0]?.fix).toStartWith('keyset({ scope, keys: [');
+  },
+);
+
 unitTest('a statement composed from another fragment is silent', () => {
   const inner = \`sql\\\`and a = \${hole('a')}\\\`\`;
   const source = \`const rows = sql\\\`select * from posts where id = \${hole('id')} \${hole(inner)}\\\`;\`;

package/src/templates/job.ts

@@ -34,7 +34,7 @@ export const ${name.camel} = job({
   retry: { attempts: 5, backoff: 'exponential' },
   async run({ input, step }) {
     const row = await step.run('load', () => repo.byId(input.id));
-    if (row === undefined) return { skipped: true };
+    if (row === null) return { skipped: true };
     await step.run('process', async () => {
       await repo.list(1);
     });

package/src/templates/naming.ts

@@ -25,6 +25,11 @@ export interface GeneratedSourceFile {
   readonly path: string;
   readonly contents: string | Uint8Array;
   readonly merge?: undefined;
+  /**
+   * A sibling path this file is a RELATIVE symlink to (`AGENTS.md` → `CLAUDE.md`). `contents` is
+   * then the target's own text: the copy `write-generated.ts` writes where the OS refuses a link.
+   */
+  readonly link?: string;
 }
 
 /**

package/src/templates/pinned/docker-compose.yml

@@ -0,0 +1,6 @@
+# The image pins a scaffolded app's compose files read (pinned-images.ts). YAML because Dependabot
+# rewrites only compose files and Dockerfiles: a pin held in a template string is one it never sees.
+# It is grouped in .github/dependabot.yml with docker/, so one PR moves every copy together.
+services:
+  s3:
+    image: versity/versitygw:v1.9.0@sha256:eb7f786fcd91e72194e48fcf1ac16302d686bf8e3a71434bdbc067a6efd3fdc7

package/src/templates/pinned-images.ts

@@ -0,0 +1,8 @@
+// The one source of a scaffolded app's Dependabot-maintained image pins: ./pinned/docker-compose.yml.
+
+import pinned from './pinned/docker-compose.yml' with { type: 'yaml' };
+
+const { services } = pinned as { services: { s3: { image: string } } };
+
+/** The S3 gateway every scaffolded compose file runs. */
+export const S3_GATEWAY_IMAGE = services.s3.image;

package/src/templates/policy.ts

@@ -80,6 +80,82 @@ export const can${feature.pascal}Create = can(
 );
 `;
 
+/** One grant and no predicate: what decides on an org has nothing to decide on in this slice. */
+const grantRule = (feature: NameSet, rule: string, verb: string): string =>
+  wrapList(
+    '',
+    `export const can${feature.pascal}${rule} = can(`,
+    [`'${feature.kebab}:${verb}'`],
+    ');',
+  );
+
+/**
+ * The slice's entity names no tenant (`sliceHasNoTenant`), so there is no org for a rule to compare
+ * and none an orgless actor lacks: the grant is the whole rule. A row-level one is the author's.
+ */
+const singleTenantPolicySource = (
+  feature: NameSet,
+): string => `// Authz for the ${feature.kebab} feature, whose entity names no tenant: the grant is the rule. Every
+// branch here is reachable from every surface, and predicates are synchronous on purpose.
+
+import { tag } from '@ultimat3/cache';
+import { can, definePermissions } from '@ultimat3/policy';
+
+// The permission set, declared rather than assumed. The augmentation narrows \`can()\` to these
+// strings, so a typo is a build error instead of a rule that silently never matches.
+declare module '@ultimat3/policy' {
+  interface PermissionRegistry {
+    '${feature.kebab}:read': true;
+    '${feature.kebab}:write': true;
+  }
+}
+
+${permissionSet(feature)}
+
+/** What a write invalidates and a read depends on — one tag, both directions. */
+export const ${feature.camel}Tag = tag('${feature.kebab}');
+
+${grantRule(feature, 'Read', 'read')}
+
+${grantRule(feature, 'Write', 'write')}
+
+${grantRule(feature, 'Create', 'write')}
+`;
+
+const singleTenantPolicyTest = (
+  feature: NameSet,
+): string => `// The ${feature.kebab} rules, from the DENIAL side: anonymous, and the actor holding only read.
+import { testActor } from '@ultimat3/policy';
+import { expect, unitTest } from '@ultimat3/testing';
+${wrapImport([`can${feature.pascal}Create`, `can${feature.pascal}Read`, `can${feature.pascal}Write`], './policy')}
+
+// Each grant named once, so every assertion below fits the formatter's width at any feature name.
+const read = '${feature.kebab}:read';
+const write = '${feature.kebab}:write';
+const input = {};
+
+const reader = testActor('reader', { permissions: [read] }).actor;
+const writer = testActor('writer', { permissions: [read, write] }).actor;
+
+unitTest('${feature.camel} read denies anonymous', async () => {
+  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: null, input });
+  await expect(can${feature.pascal}Read).not.toDenyPolicy({ actor: reader, input });
+});
+
+unitTest('${feature.camel} write and create deny the read-only actor', async () => {
+  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: reader, input });
+  await expect(can${feature.pascal}Write).not.toDenyPolicy({ actor: writer, input });
+  await expect(can${feature.pascal}Create).toDenyPolicy({ actor: reader, input });
+  await expect(can${feature.pascal}Create).not.toDenyPolicy({ actor: writer, input });
+});
+
+unitTest('${feature.camel} rules name the permission they require', () => {
+  expect(can${feature.pascal}Read.permissions).toEqual(['${feature.kebab}:read']);
+  expect(can${feature.pascal}Write.permissions).toEqual(['${feature.kebab}:write']);
+  expect(can${feature.pascal}Create.permissions).toEqual(['${feature.kebab}:write']);
+});
+`;
+
 const policyTest = (
   feature: NameSet,
 ): string => `// The ${feature.kebab} rules, from the DENIAL side: anonymous, cross-org, and the actor holding
@@ -142,11 +218,18 @@ unitTest('${feature.camel} rules name the permission they require', () => {
 export function policyFiles(
   rawName: string,
   target: { readonly surfaceDir: string; readonly feature: string },
+  shape: { readonly singleTenant?: boolean } = {},
 ): readonly GeneratedFile[] {
   const feature = names(rawName.length > 0 ? rawName : target.feature);
   const dir = `${target.surfaceDir}/${target.feature}`;
   return [
-    { path: `${dir}/policy.ts`, contents: policySource(feature) },
-    { path: `${dir}/policy.test.ts`, contents: policyTest(feature) },
+    {
+      path: `${dir}/policy.ts`,
+      contents: shape.singleTenant ? singleTenantPolicySource(feature) : policySource(feature),
+    },
+    {
+      path: `${dir}/policy.test.ts`,
+      contents: shape.singleTenant ? singleTenantPolicyTest(feature) : policyTest(feature),
+    },
   ];
 }

package/src/templates/query.ts

@@ -1,13 +1,14 @@
-// `x g query <name> [--live]` — a read. Live queries must be deterministic and bounded, so the
+// `x g query <name> --feature <slice> [--live]` — a read. Live queries must be deterministic and bounded, so the
 // generated declaration always carries `orderBy` + `limit` and the generated test pins them:
 // an unbounded live query is a memory leak that only shows up under load.
 
+import { UltimateError } from '@ultimat3/core';
 import type { FeatureTarget } from './entity';
 import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
 import { PLACEHOLDER_DB_MODULE } from './scaffold-db-client';
-import { sliceFoundation, sliceTakesScaffoldRow } from './slice-foundation';
+import { foreignSliceEntity, sliceFoundation, sliceTakesScaffoldRow } from './slice-foundation';
 import { wrapImport } from './wrap';
 
 /** A live read always fans out fresh, so a TTL on it would only ever be dead configuration. */
@@ -30,27 +31,38 @@ ${wrapImport(
 )}
 import * as repo from '../repo';
 
+/** The columns this read sorts by: \`repo.ListSort\`, and what a page's \`listUrl\` offers. */
+export const ${name.camel}Sorts = ['createdAt', 'title'] as const;
+
 // No \`orgId\` in the input, and none in the policy: \`repo.list\` reads through the typed handle,
 // which scopes every read to the ACTOR's org, and a live window is keyed by the subscriber's
 // tenant. One source of tenancy — a parameter would be a second one a caller could set.
 export const ${name.camel} = query({
-  input: t.object({ limit: t.number.default(50) }),
+  input: t.object({
+    limit: t.number.default(50),
+    // A closed set, so a sort is a column this read has an order for, never a caller's string.
+    sort: t.enum(${name.camel}Sorts).default('createdAt'),
+    dir: t.enum(['asc', 'desc']).default('desc'),
+  }),
   policy: can${feature.pascal}Read,
   live: ${String(live)},${cacheLine(feature, live)}
+  // The refusals a caller may branch on, closed: add each code this read comes to throw.
+  errors: [],
   // Opt-in, unlike an action's tool: a read hands rows to an agent, so silence exposes nothing.
   mcp: { expose: true, description: '${name.raw} — edit this description' },
-  sql: ({ limit }) =>
+  sql: ({ limit, sort, dir }) =>
     // \`feature.table\`, not the kebab plural: \`from()\` quotes the identifier into the SQL text,
     // and the entity created the table as snake_case.
-    from<${feature.pascal}>('${feature.table}', () => repo.list(limit))
-      // Newest first — \`repo.list\`'s own order. These two lines are ONE read spelled twice: the
-      // thunk is what the in-memory driver answers and this chain is the SQL Postgres runs, so a
-      // direction that differs here is a bounded page holding different rows on each.
-      .orderBy('createdAt', 'desc')
-      // The primary key last is what makes the order TOTAL: \`createdAt\` alone ties, and two
-      // rows that tie can swap between evaluations — a bounded read then drops one and repeats
-      // the other, and a live subscription patches a row it never sent.
-      .orderBy('id')
+    from<${feature.pascal}>('${feature.table}', () => repo.list(limit, sort, dir))
+      // \`repo.list\`'s own order. These lines are ONE read spelled twice: the thunk is what the
+      // in-memory driver answers and this chain is the SQL Postgres runs, so a sort or a direction
+      // that differs here is a bounded page holding different rows on each.
+      .orderBy(sort, dir)
+      // The primary key last, in the same direction the handle adds it, is what makes the order
+      // TOTAL: a sort column alone ties, and two rows that tie can swap between evaluations — a
+      // bounded read then drops one and repeats the other, and a live subscription patches a row
+      // it never sent.
+      .orderBy('id', dir)
       .limit(limit),
 });
 `;
@@ -121,6 +133,23 @@ ${wrapper}('${name.camel} is bounded and TOTALLY ordered', async () => {
   expect(text.slice(text.lastIndexOf('order by'))).toContain('id');
 });
 
+${wrapper}('the read sorts by the column it is asked for, either way', async () => {
+  // The same sort the in-memory thunk applies (\`repo.list(limit, sort, dir)\`), spelled as SQL —
+  // and the id tiebreak follows the direction, as the handle's does.
+  const reason = 'a scaffolded test asserts the SQL text; the policy is asserted separately';
+  const sqlFor = async (dir: 'asc' | 'desc') => {
+    const input = { limit: 50, sort: 'title' as const, dir };
+    const source = await sourceFor(target, input, { actor: null, unenforced: reason });
+    return source.toSQL().sql.toLowerCase();
+  };
+  const asc = await sqlFor('asc');
+  expect(asc).toContain('order by "title" asc');
+  expect(asc).toContain('"id" asc');
+  const desc = await sqlFor('desc');
+  expect(desc).toContain('order by "title" desc');
+  expect(desc).toContain('"id" desc');
+});
+
 ${wrapper}('${name.camel} denies an orgless actor before a read', async () => {
   // \`.as()\` is the one read path with the actor swapped: validate, authorize, then read. The
   // denial lands before any SQL executes, which is why this needs no database.
@@ -249,6 +278,15 @@ unitTest('stored rows read back newest first, bounded, and never another org', a
   const theirs = await target.as(outsider, { limit: 50 });
   expect(theirs.map((row) => row.title)).toEqual(['theirs']);
 });
+
+unitTest('the read is one statement, however many rows it answers', async ({ statements }) => {
+  await store(orgId, 'first');
+  await store(orgId, 'second');
+  const before = statements.count();
+  await target.as(member, { limit: 50 });
+  // On this driver as on Postgres: a read added per row in the handler is a third statement here.
+  expect(statements.count() - before).toBe(1);
+});
 `;
 
 /**
@@ -325,11 +363,30 @@ export interface QueryOptions extends FeatureTarget {
   readonly sliceRepo?: string;
 }
 
+/**
+ * Declared beside its one thrower, as `backfill.ts`'s twin is: the read imports the slice's own row
+ * type and repo, and a slice declaring another table under its name has neither.
+ */
+export class QuerySliceEntityError extends UltimateError {
+  constructor(input: { readonly path: string; readonly binding: string; readonly table: string }) {
+    super({
+      code: 'X_QUERY_SLICE_ENTITY',
+      cause: `x g query reads the slice's own scaffolded table, and its entity.ts declares ${input.binding} (${input.table}) instead — the generated read would import a row type and a repo that do not exist`,
+      fix: `x queries list --json   # then declare query({ sql: … from('${input.table}', …) }) by hand in ${input.path}, over ../entity's ${input.binding}`,
+      meta: { binding: input.binding, table: input.table },
+    });
+  }
+}
+
 export function queryFiles(rawName: string, target: QueryOptions): readonly GeneratedFile[] {
   const name = names(rawName);
   const feature = names(target.feature);
   const live = target.live === true;
   const dir = `${target.surfaceDir}/${target.feature}/${live ? 'live' : 'queries'}`;
+  const foreign = foreignSliceEntity(target.feature, target.sliceEntity);
+  if (foreign !== undefined) {
+    throw new QuerySliceEntityError({ path: `${dir}/${name.kebab}.ts`, ...foreign });
+  }
   const shape: ReadShape = {
     live,
     storesRow: sliceTakesScaffoldRow(target, target.sliceEntity, target.sliceRepo),

package/src/templates/resource-create.ts

@@ -137,7 +137,9 @@ const writer = testActor('writer', {
 }).actor;
 
 contractTest('create${feature.pascal} passes the action contract', async () => {
-  for (const contract of target.contract()) await contract.run();
+  // The fourth assertion runs the handler as the writer on 16 generated legal inputs, each
+  // inside a transaction that rolls back, so nothing it creates outlives the test.
+  for (const contract of target.contract({ exercise: { actor: writer } })) await contract.run();
 });
 
 contractTest('create${feature.pascal} needs an actor with an org', async () => {

package/src/templates/resource-form-island.ts

@@ -46,6 +46,7 @@ import {
   createContext,
   createEffect,
   createMemo,
+  createRoot,
   createSignal,
   onCleanup,
   useContext,
@@ -146,17 +147,27 @@ function ${feature.pascal}FormBody(props: ${feature.pascal}FormProps): JSX.Eleme
  * registers. Delete the line and the first \`<UiProvider>\` render throws X_UI_RUNTIME_MISSING —
  * loud on purpose, because a DOM render that lost its runtime is a theme toggle that does nothing.
  *
- * Six NAMED imports, never \`import * as solidRuntime\`: a namespace object handed to a function
+ * Seven NAMED imports, never \`import * as solidRuntime\`: a namespace object handed to a function
  * keeps every export of solid-js alive, and the bundler cannot shake what it cannot see unused —
  * measured at 14.8 kB minified per island chunk (5.6 kB gzipped) for the namespace form.
  *
  * The shell is cleared first: Solid's \`render\` APPENDS when the container already has children,
  * so without it the server's markup stays on screen above a second, live copy of the same thing.
  */
-export function mount(el: HTMLElement, props: ${feature.pascal}FormProps): void {
-  setSolidRuntime({ createContext, useContext, createSignal, createMemo, createEffect, onCleanup });
+export function mount(el: HTMLElement, props: ${feature.pascal}FormProps): () => void {
+  setSolidRuntime({
+    createContext,
+    useContext,
+    createSignal,
+    createMemo,
+    createEffect,
+    onCleanup,
+    createRoot,
+  });
   el.textContent = '';
-  render(
+  // Solid's disposer, returned: the client router calls it when it navigates away, and a mount
+  // that returns nothing is X_ISLAND_DISPOSER_MISSING.
+  return render(
     () => (
       <UiProvider locale={props.locale}>
         <${feature.pascal}FormBody {...props} />

package/src/templates/resource-page-db.ts

@@ -0,0 +1,83 @@
+// `x g resource`'s list page, read by Postgres: the generated test that renders the same sorted,
+// paged list as `page.test.ts` with the app's migrated database installed under the handle.
+
+import { sortedImports } from './imports';
+import type { ResourcePageOptions } from './resource-page';
+
+/** The org the rows belong to — the same one `page.test.ts` writes under. */
+const ORG = '00000000-0000-4000-8000-000000000002';
+
+/**
+ * The same sort and the same pages, read by Postgres: the app's migrated database installed under
+ * the handle, so the query's SQL — `order by`, the keyset seek — answers instead of the memory
+ * thunk. The database is embedded Postgres (PGlite) booted from the migrated template, so the
+ * proof needs no server and runs on the `unit` step.
+ */
+export const pageDbTest = (options: ResourcePageOptions): string => {
+  const { feature } = options;
+  const path = feature.pluralKebab;
+  return `// /${path} against the app's migrated database: the read's SQL path, where page.test.ts is the
+// in-memory one. The same rows, sorted and paged by link, come back in the same order.
+${sortedImports([
+  "import { migratedDatabase } from '@ultimat3/cli';",
+  "import { ctxOf, frozenClock, runWithContext } from '@ultimat3/core';",
+  "import { setDbClient } from '@ultimat3/db';",
+  "import { testActor } from '@ultimat3/policy';",
+  "import {\n  afterAll,\n  beforeAll,\n  expect,\n  renderRoute,\n  reusableDatabase,\n  unitTest,\n} from '@ultimat3/testing';",
+])}
+// The app's API, as boot loads it: \`defineApi\` names the query the page reads.
+import '../../api';
+import * as repo from '../${feature.kebab}/repo';
+import * as page from './page';
+
+// A template restore is ~0.5 s; its first build (initdb plus every migration) is what this bounds.
+const BOOT_MS = 120_000;
+
+const workerDatabase = reusableDatabase(() => migratedDatabase({ root: import.meta.dir }));
+beforeAll(async () => {
+  setDbClient(await workerDatabase());
+}, BOOT_MS);
+// Back to memory, so this file's database never reaches the next file's unit tests.
+afterAll(() => setDbClient(undefined));
+
+const url = 'https://example.test/${path}';
+const orgId = '${ORG}';
+// The read grant, named once so the line below fits the formatter's width at any feature name.
+const read = '${feature.kebab}:read';
+const member = testActor('member', { orgId, permissions: [read] }).actor;
+const clock = frozenClock('2026-01-01T00:00:00.000Z');
+
+const store = (title: string) => {
+  const draft = { orgId, title, price: { minor: 1200, currency: 'USD' } };
+  return runWithContext(ctxOf({ actor: member, clock }), () => repo.insert(draft));
+};
+
+/** The anchor a pager side renders, read off the HTML: \`rel\` names the side. */
+const linkTo = (html: string, rel: string): string | undefined => {
+  const anchor = new RegExp(\`<a\\\\b[^>]*\\\\brel="\${rel}"[^>]*>\`).exec(html)?.[0];
+  return /href="([^"]*)"/.exec(anchor ?? '')?.[1]?.replaceAll('&amp;', '&');
+};
+
+unitTest('Postgres sorts and pages the list as the memory read does', async () => {
+  for (const title of ['beta', 'gamma', 'alpha']) {
+    await store(title);
+    clock.advance(1000);
+  }
+  // Unsorted is the query's own order, newest first.
+  const newest = await renderRoute(page, { url, actor: member });
+  expect(newest.text.indexOf('alpha')).toBeLessThan(newest.text.indexOf('gamma'));
+  expect(newest.text.indexOf('gamma')).toBeLessThan(newest.text.indexOf('beta'));
+
+  // By title, two to a page: the first two titles, then the third through the cursor.
+  const sorted = \`\${url}?sort=title&dir=asc&limit=2\`;
+  const first = await renderRoute(page, { url: sorted, actor: member });
+  expect(first.text.indexOf('alpha')).toBeLessThan(first.text.indexOf('beta'));
+  expect(first.text).not.toContain('gamma');
+  const next = linkTo(first.html, 'next');
+  const second = await renderRoute(page, { url: new URL(next ?? '', url).href, actor: member });
+  expect(second.text).toContain('gamma');
+  expect(second.text).not.toContain('alpha');
+  expect(linkTo(second.html, 'next')).toBeUndefined();
+});
+`;
+};