@ultimat3/cli 29.3.2 → 30.0.0

package/src/templates/action.ts

@@ -3,16 +3,20 @@
 // job handle, an MCP tool and these tests; the generator writes the declaration and the tests.
 
 import { SlicePolicyIncompleteError } from '../generate-slice-policy';
+import { actionContractTest, actionUnitTest } from './action-tests';
 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 type { DeclaredEntity, SliceModule } from './slice-foundation';
 import {
   exportsUnknown,
+  foreignSliceEntity,
   grantOf,
+  policyReadsOrg,
   sliceExports,
   sliceFoundation,
+  sliceHasNoTenant,
   sliceTakesScaffoldRow,
 } from './slice-foundation';
 import { wrapImport } from './wrap';
@@ -21,22 +25,43 @@ import { wrapImport } from './wrap';
  * The handler's lookup-by-id, or the comment that says what a slice needs before it can have one.
  * `x g resource` writes a slice whose `errors.ts` declares `<Feature>NotFoundError`, and so does
  * the foundation this generator lays under an empty directory; a slice an author wrote by hand
- * (ai-maxxing's `fleet`, with `HostNotFoundError` and `SessionNotFoundError`) declares the errors
+ * (one adopter's `fleet`, with `HostNotFoundError` and `SessionNotFoundError`) declares the errors
  * it has and not this one. Importing it anyway is a file that fails at import.
  */
-const missingLookup = (feature: NameSet, entity: boolean): string =>
-  entity
-    ? `    // No lookup by id: ../errors declares no ${feature.pascal}NotFoundError, and a row that is not
+const missingLookup = (
+  feature: NameSet,
+  entity: boolean,
+  foreign: DeclaredEntity | undefined,
+): string =>
+  foreign !== undefined
+    ? `    // No lookup by id: ../entity declares ${foreign.binding} (${foreign.table}), not the
+    // table this generator scaffolds, so it writes no repo around it. Read the row your own way here.`
+    : entity
+      ? `    // No lookup by id: ../errors declares no ${feature.pascal}NotFoundError, and a row that is not
     // there needs one to be thrown for it. Declare it there — the shape \`x g resource\` writes —
     // then read the row through ../repo and throw it when the read answers nothing.`
-    : `    // No lookup by id: this feature has no entity, and a generator writing into a slice never
+      : `    // No lookup by id: this feature has no entity, and a generator writing into a slice never
     // invents one. \`x g entity ${feature.kebab}\` declares the table; this body is yours until then.`;
 
+/**
+ * The refusals the handler may throw, closed from day one: a 4xx it throws outside the list is
+ * `X_ERROR_UNDECLARED` in every test. The lookup's class answers its own code, so an
+ * `errors.ts` the author wrote keeps whatever code it declares.
+ */
+const errorsLine = (feature: NameSet, lookup: boolean): string =>
+  lookup
+    ? `  // The refusals a caller may branch on: add each code the handler comes to throw.
+  errors: [${feature.pascal}NotFoundError.code],`
+    : `  // The refusals a caller may branch on: add each code the handler comes to throw.
+  errors: [],`;
+
 const actionSource = (
   name: NameSet,
   feature: NameSet,
   lookup: boolean,
   entity: boolean,
+  org: boolean,
+  foreign: DeclaredEntity | undefined,
 ): string => `// ${name.camel}: one mutation, server-authoritative. Input is validated before the handler runs
 // and the policy is the same object the MCP tool and the HTTP route evaluate.
 // \`t\` comes from @ultimat3/action, not @ultimat3/schema: an action file imports one package.
@@ -47,12 +72,17 @@ import { action, t } from '@ultimat3/action';
 ${lookup ? `\nimport { ${feature.pascal}NotFoundError } from '../errors';\n` : ''}${wrapImport([`can${feature.pascal}Write`, `${feature.camel}Tag`], '../policy')}
 ${lookup ? "import * as repo from '../repo';\n" : ''}
 export const ${name.camel} = action({
-  // orgId is part of the input because the policy decides on it — authz reads the declaration,
+${
+  org
+    ? `  // orgId is part of the input because the policy decides on it — authz reads the declaration,
   // never the database.
-  input: t.object({ id: t.uuid, orgId: t.uuid }),
+  input: t.object({ id: t.uuid, orgId: t.uuid }),`
+    : '  input: t.object({ id: t.uuid }),'
+}
   output: t.object({ id: t.uuid${lookup ? ', title: t.string' : ''} }),
   policy: can${feature.pascal}Write,
   cache: { invalidates: [${feature.camel}Tag] },
+${errorsLine(feature, lookup)}
   // No \`mcp\`: a tool's description is what an agent reads to decide to call it, and a placeholder
   // there is worse than no tool. Write one, then \`mcp: { expose: true, description: '…' }\`.
   async handle({ input }) {
@@ -61,7 +91,7 @@ ${
     ? `    const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
     return { id: row.id, title: row.title };`
-    : `${missingLookup(feature, entity)}
+    : `${missingLookup(feature, entity, foreign)}
     return { id: input.id };`
 }
   },
@@ -73,6 +103,8 @@ const mutatorSource = (
   feature: NameSet,
   lookup: boolean,
   entity: boolean,
+  org: boolean,
+  foreign: DeclaredEntity | undefined,
 ): string => `// ${name.camel}: an action with an optimistic local twin. The local half runs against the client
 // store immediately; the server half is authoritative and reconciles on conflict.
 
@@ -86,18 +118,19 @@ interface Local${feature.pascal} {
 }
 
 export const ${name.camel} = mutator({
-  input: t.object({ id: t.uuid, orgId: t.uuid, title: t.string }),
+  input: t.object({ id: t.uuid,${org ? ' orgId: t.uuid,' : ''} title: t.string }),
   output: t.object({ id: t.uuid, title: t.string }),
   policy: can${feature.pascal}Write,
   // Required on a mutator (X_MUTATOR_NOT_IDEMPOTENT): the client replays this write under one
   // Idempotency-Key after a dropped response, and the replay answers the first result.
   idempotent: true,
+${errorsLine(feature, lookup)}
   // No \`mcp\` until a real description is written: see \`x g action\`.
   // tx.table(name) rather than tx.${feature.plural}: the typed accessor exists only once the app
   // augments LocalTables, and generated code cannot assume that has happened yet. The name is the
   // entity's snake_case table, so the local twin and the server row live under one key.
   local(tx, input) {
-    tx.table<Local${feature.pascal}>('${feature.table}').update(input.id, {
+    tx.table<Local${feature.pascal}>('${foreign?.table ?? feature.table}').update(input.id, {
       title: input.title,
       pending: true,
     });
@@ -108,7 +141,7 @@ ${
     ? `    const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
     return { id: row.id, title: input.title };`
-    : `${missingLookup(feature, entity)}
+    : `${missingLookup(feature, entity, foreign)}
     return { id: input.id, title: input.title };`
 }
   },
@@ -116,251 +149,6 @@ ${
 });
 `;
 
-/** The code the slice's `errors.ts` declares for a missing row. */
-const notFoundCode = (feature: NameSet): string =>
-  `X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND`;
-
-const ID = '00000000-0000-4000-8000-000000000001';
-const ORG = '00000000-0000-4000-8000-000000000002';
-const OTHER_ORG = '00000000-0000-4000-8000-000000000009';
-
-/** The declaration-shape assertions that differ between the two primitives. */
-const shapeTest = (name: NameSet, isMutator: boolean): string =>
-  isMutator
-    ? `unitTest('${name.camel} projects both halves and a conflict strategy', () => {
-  // The projected names mirror the declaration: local() optimistic, server() authoritative.
-  // server() routes through the same invoke() core as every other surface, so it cannot skip
-  // the input parse, the policy or the output parse.
-  expect(target.describeMutator().kind).toBe('mutator');
-  expect(target.conflict).toBe('server-wins');
-  expect(typeof target.local).toBe('function');
-  expect(typeof target.server).toBe('function');
-});`
-    : `unitTest('${name.camel} is a declared action', () => {
-  expect(target.kind).toBe('action');
-  expect(target.describe().name).toBe('${name.camel}');
-});`;
-
-/**
- * The preamble both generated tests share. `outsider` rides along only where it is USED: the
- * scaffolded app lints with `noUnusedVariables: error`, so an actor declared in the unit half
- * would be a lint failure in code nobody typed.
- */
-const preamble = (
-  name: NameSet,
-  feature: NameSet,
-  isMutator: boolean,
-  wrappers: string,
-  outsider: boolean,
-): string => `${outsider ? "import { testActor } from '@ultimat3/policy';\n" : ''}import { ${wrappers} } from '@ultimat3/testing';
-import { ${name.camel} } from './${name.kebab}';
-
-const id = '${ID}';
-const orgId = '${ORG}';
-const input = { id, orgId${isMutator ? ", title: 'a title'" : ''} };
-
-// Named here because every projection needs a stable name and this file does not boot the app.
-// At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
-// object, so each projection of it works there with nothing to remember.
-const target = ${name.camel}.named('${name.camel}');
-${
-  outsider
-    ? `
-// Holds the grant, wrong org. That is the interesting actor: a denial here is the predicate
-// deciding, not the permission check, so this test fails if the tenancy rule is ever dropped.
-const outsider = testActor('outsider', {
-  orgId: '${OTHER_ORG}',
-  permissions: ['${feature.kebab}:write'],
-}).actor;
-`
-    : ''
-}`;
-
-/** What the unit test may do with the slice the declaration lives in. */
-interface HandlerShape {
-  readonly isMutator: boolean;
-  /** The handler reads a row by id and throws `<Feature>NotFoundError` when there is none. */
-  readonly lookup: boolean;
-  /** The slice still takes the row `x g entity` scaffolds, so the test may store one. */
-  readonly storesRow: boolean;
-  readonly dbModule: string;
-  /**
-   * The permission the writer is granted — `<feature>:write` for the policy this generator wrote,
-   * the one literal `can('<perm>')` of a handwritten one, or `undefined` when that policy's grant
-   * cannot be read, and then no assertion depends on it.
-   */
-  readonly grant: string | undefined;
-}
-
-/**
- * The optimistic half, run against the client store `@ultimat3/testing` ships. A twin is replayed
- * on every rebase, so the two facts worth failing on are the row one application leaves and that a
- * second leaves the same one — and that a row the store never held is not invented.
- */
-const localTwinTests = (): string => `
-unitTest('the local twin marks the row pending, and a replay lands in the same place', () => {
-  const store = memoryLocalTx({ [TABLE]: { [id]: { id, title: 'before', pending: false } } });
-  target.local(store.tx, input);
-  const once = store.rows(TABLE);
-  expect(once).toEqual({ [id]: { id, title: 'a title', pending: true } });
-  // A rebase replays the queued write: twice through must equal once through.
-  target.local(store.tx, input);
-  expect(store.rows(TABLE)).toEqual(once);
-});
-
-unitTest('the local twin invents no row the store never held', () => {
-  const store = memoryLocalTx();
-  target.local(store.tx, input);
-  expect(store.rows(TABLE)).toEqual({});
-});
-`;
-
-/** The authoritative half's cases, refusal first, in the shape the slice earns. */
-const handlerTests = (feature: NameSet, shape: HandlerShape): string => {
-  if (shape.grant === undefined) {
-    return `
-// No handler assertion: ../policy.ts is hand-written and its grant is not one literal can('…'),
-// so which actor reaches the handler is the author's to state — add that test here.
-`;
-  }
-  const answer = shape.isMutator ? "{ id, title: 'a title' }" : '{ id }';
-  if (!shape.lookup) {
-    return `
-unitTest('an actor without the grant is refused before the handler runs', async () => {
-  const stranger = testActor('stranger', { orgId }).actor;
-  const refused = await target.as(stranger, input).catch((error: unknown) => error);
-  expect(refused).toBeUltimateError('X_FORBIDDEN');
-});
-
-unitTest('the handler answers a writer in the org', async () => {
-  expect(await target.as(writer, input)).toEqual(${answer});
-});
-`;
-  }
-  const found = shape.isMutator
-    ? "{ id: row.id, title: 'a title' }"
-    : "{ id: row.id, title: 'kept' }";
-  const call = shape.isMutator
-    ? "{ id: row.id, orgId, title: 'a title' }"
-    : '{ id: row.id, orgId }';
-  return `
-unitTest('the handler refuses an id nothing holds', async () => {
-  const refused = await target.as(writer, input).catch((error: unknown) => error);
-  expect(refused).toBeUltimateError('${notFoundCode(feature)}');
-});
-${
-  shape.storesRow
-    ? `
-unitTest('the handler answers the row it found', async () => {
-  const draft = { orgId, title: 'kept', price: { minor: 0, currency: 'USD' } };
-  const row = await runWithContext(ctxOf({ actor: writer }), () => repo.insert(draft));
-  const answer = await target.as(writer, ${call});
-  expect(answer).toEqual(${found});
-});
-`
-    : ''
-}`;
-};
-
-/**
- * The unit test: the declaration's shape, the input it refuses, and the HANDLER — run through
- * `.as()`, the one execution path, against the in-memory driver. A mutator's local twin runs
- * against `memoryLocalTx`. The contract projections are next door, in their own suite.
- *
- * A row is stored only in a slice whose row this generator can spell (`sliceTakesScaffoldRow`): a
- * slice an author reshaped has its own columns, and a test that inserted `{ title, price }` into
- * it would be a guess about someone else's table.
- */
-const actionUnitTest = (name: NameSet, feature: NameSet, shape: HandlerShape): string => {
-  const known = shape.grant !== undefined;
-  const stores = known && shape.lookup && shape.storesRow;
-  const testing = [
-    ...(stores ? ['afterEach'] : []),
-    'expect',
-    ...(shape.isMutator ? ['memoryLocalTx'] : []),
-    'unitTest',
-  ].join(', ');
-  return `// ${name.camel}: its declared shape, the input it refuses, and what its handler answers — in
-// process, so all three belong to the \`unit\` step. The contract projections are next door.
-${sortedImports([
-  ...(stores ? ["import { ctxOf, runWithContext } from '@ultimat3/core';"] : []),
-  ...(known ? ["import { testActor } from '@ultimat3/policy';"] : []),
-  `import { ${testing} } from '@ultimat3/testing';`,
-  ...(stores ? [`import { driver } from '${shape.dbModule}';`] : []),
-])}${stores ? "\nimport * as repo from '../repo';" : ''}
-import { ${name.camel} } from './${name.kebab}';
-
-const id = '${ID}';
-const orgId = '${ORG}';
-const input = { id, orgId${shape.isMutator ? ", title: 'a title'" : ''} };
-${shape.isMutator ? `\n// The client store's table: the entity's own, so the twin and the server row share one key.\nconst TABLE = '${feature.table}';\n` : ''}
-// Named here because every projection needs a stable name and this file does not boot the app.
-// At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
-// object, so each projection of it works there with nothing to remember.
-const target = ${name.camel}.named('${name.camel}');
-${
-  known
-    ? `
-// Holds the grant in the org the input names: past the policy, so what answers is the handler.
-const grant = ['${shape.grant}'];
-const writer = testActor('writer', { orgId, permissions: grant }).actor;
-`
-    : ''
-}${
-  stores
-    ? `
-// One store per process: without this, one test's rows are the next test's fixtures.
-afterEach(() => {
-  driver.reset?.();
-});
-`
-    : ''
-}
-${shapeTest(name, shape.isMutator)}
-
-unitTest('${name.camel} rejects input that is not a uuid', async () => {
-  await expect(target.input).toRejectInput({ ...input, id: 'not-a-uuid' });
-  await expect(target.input).toAcceptInput(input);
-});
-${shape.isMutator ? localTwinTests() : ''}${handlerTests(feature, shape)}`;
-};
-
-const actionContractTest = (
-  name: NameSet,
-  feature: NameSet,
-  isMutator: boolean,
-  /** The slice's policy is the one this generator wrote, so its tenancy rule is known. */
-  scaffoldPolicy = true,
-): string => `// ${name.camel}: the contract every action owes, and the foreign-org actor it denies before the
-// handler runs. One declaration, every surface.
-${preamble(name, feature, isMutator, 'contractTest, expect', scaffoldPolicy)}
-contractTest('${name.camel} passes the action contract', async () => {
-  // Three assertions the framework makes for any action, without knowing what this one does:
-  // garbage input is rejected, an anonymous actor is denied, and the operation reaches the
-  // OpenAPI document. \`.contract()\` is the projection; this loop just runs it.
-  for (const contract of target.contract()) await contract.run();
-});
-
-${
-  scaffoldPolicy
-    ? `contractTest('${name.camel} denies a foreign org', async () => {
-  // \`.as()\` is the one execution path with the actor swapped, so this denial is the same one
-  // HTTP, MCP and the job surface would produce — and no repo call happened to produce it.
-  const denied = await target.as(outsider, input).catch((error: unknown) => error);
-  expect(denied).toBeUltimateError('X_FORBIDDEN');
-});
-`
-    : `// No foreign-org assertion: ../policy.ts is hand-written, and whether it checks the org is the
-// author's rule to state — add that test here.
-`
-}
-// No MCP tool until it is described: a placeholder description misleads the agent reading it.
-contractTest('${name.camel} projects one operation and no tool', () => {
-  expect(target.openapi().operationId).toBe('${name.camel}');
-  expect(target.mcp?.expose ?? false).toBe(false);
-});
-`;
-
 export interface ActionOptions extends FeatureTarget {
   readonly mutator?: boolean;
   /**
@@ -392,14 +180,36 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
   const dir = `${target.surfaceDir}/${target.feature}/actions`;
   const isMutator = target.mutator === true;
   const entity = target.sliceEntity !== undefined;
+  // Another table under this slice's name: nothing is planted around it, and no row is read.
+  const foreign = foreignSliceEntity(target.feature, target.sliceEntity);
+  // `job`'s reason: which shape fits is a fact about THIS slice's `entity.ts`, and the comment in
+  // the one `x g entity` writes says deleting its tenant is a per-slice edit the generators read.
+  // A policy still deciding on `input.orgId` keeps it in the input, because the action compiles
+  // against the policy it imports and that file is its author's to change, never this generator's.
+  const singleTenant = sliceHasNoTenant(target.sliceEntity);
+  // The policy this run writes grants `<feature>:write`; a handwritten one, what it says.
+  const grant =
+    target.slicePolicy === undefined
+      ? `${feature.kebab}:write`
+      : grantOf(target.slicePolicy, `can${feature.pascal}Write`);
+  const org =
+    !singleTenant || (target.slicePolicy !== undefined && policyReadsOrg(target.slicePolicy));
   // Before a file is planned: a generated action that does not compile is refused, never written.
   assertPolicyExports(target, feature, isMutator);
   const lookup =
     entity &&
+    foreign === undefined &&
     (target.sliceErrors === undefined ||
       sliceExports(target.sliceErrors, `${feature.pascal}NotFoundError`)) &&
     // The lookup calls `repo.byId`: a `repo.ts` an author wrote without one gets the neutral body.
     (target.sliceRepo === undefined || sliceExports(target.sliceRepo, 'byId'));
+  // `../errors` only when the body throws from it: with no lookup it is a module nothing imports,
+  // and an app's coverage floor counts it (`no unit test loads it`, a red first gate after this).
+  const foundation: readonly SliceModule[] = [
+    ...(entity && foreign === undefined ? (['entity'] as const) : []),
+    'policy',
+    ...(lookup ? (['errors'] as const) : []),
+  ];
   return [
     // The three slice modules this action's source imports — `../errors`, `../policy`, `../repo`
     // (which comes with `../entity`, its row type). Composed rather than assumed: `x g action`
@@ -408,15 +218,12 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
     // And ONLY those: an action is not a resource scaffold. A module already on disk is its
     // author's — it gets no test from here and no admin labels, both of which assert the shape
     // `x g resource` writes, not the one that is there (`withoutOwned`).
-    ...withoutOwned(
-      sliceFoundation(target, entity ? ['entity', 'policy', 'errors'] : ['policy']),
-      target,
-    ),
+    ...withoutOwned(sliceFoundation(target, foundation, undefined, { singleTenant }), target),
     {
       path: `${dir}/${name.kebab}.ts`,
       contents: isMutator
-        ? mutatorSource(name, feature, lookup, entity)
-        : actionSource(name, feature, lookup, entity),
+        ? mutatorSource(name, feature, lookup, entity, org, foreign)
+        : actionSource(name, feature, lookup, entity, org, foreign),
     },
     // TWO test files, because the gate types a test by its FILENAME and this declaration owes two
     // suites: the input parse is a `unit` assertion and the three projections are `contract` ones.
@@ -429,16 +236,21 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
         lookup,
         storesRow: sliceTakesScaffoldRow(target, target.sliceEntity, target.sliceRepo),
         dbModule: target.dbModule ?? PLACEHOLDER_DB_MODULE,
-        // The policy this run writes grants `<feature>:write`; a handwritten one, what it says.
-        grant:
-          target.slicePolicy === undefined
-            ? `${feature.kebab}:write`
-            : grantOf(target.slicePolicy, `can${feature.pascal}Write`),
+        org,
+        grant,
       }),
     },
     {
       path: `${dir}/${name.kebab}.contract.test.ts`,
-      contents: actionContractTest(name, feature, isMutator, target.slicePolicy === undefined),
+      contents: actionContractTest(
+        name,
+        feature,
+        isMutator,
+        target.slicePolicy === undefined,
+        target.slicePolicy === undefined && !singleTenant,
+        // A hand-written policy's one literal grant: its exercise runs as an actor holding it.
+        grant,
+      ),
     },
   ];
 }

package/src/templates/backfill.ts

@@ -242,7 +242,7 @@ const declaredTables = (source: string): readonly string[] =>
 /**
  * Declared beside its one thrower: `errors.ts` sits at its ceiling. The sweep this generator writes
  * reads the slice's OWN scaffolded table (`db.<plural>`, its `title` and `price`), so a slice whose
- * entities are named otherwise — notificado.co's `deadline`, holding `holidays` and
+ * entities are named otherwise — one adopter's `deadline`, holding `holidays` and
  * `court_closures` — got `import type { Deadline }`, `db.deadlines` and admin labels for a table
  * that does not exist. Refused before a file is planned; a hand sweep starts from a job.
  */

package/src/templates/entity.ts

@@ -45,7 +45,8 @@ export const ${name.camel} = entity('${table}', {
   // \`orgId: uuid()\` column below and drop \`'orgId'\` from \`indexes\`. ${stems.repo}.ts needs no edit —
   // it names no org. ${stems.entity}.test.ts then expects \`$tenantColumn\` null and \`orgScoped\` false,
   // its \`row()\` fixture and ${stems.repo}.test.ts's \`draft()\` lose \`orgId\`, and ${stems.repo}.test.ts loses its
-  // last test. Nothing else reads the column.
+  // last test. policy.ts's \`can${name.pascal}Write\` stops reading \`input.orgId\` (\`can('…:write')\`
+  // alone is the rule), and from then on \`x g action\` and \`x g mutator\` input no \`orgId\`.
   tenant: 'orgId',
   columns: {
     id: uuid().primaryKey(),
@@ -93,7 +94,7 @@ const repoSource = (name: NameSet, dbModule: string, stems: EntityStems): string
   const listSignature = wrapList(
     '',
     'export async function list(',
-    ['limit = 50'],
+    ['limit = 50', "sort: ListSort = 'createdAt'", "dir: 'asc' | 'desc' = 'desc'"],
     `): Promise<readonly ${row}[]> {`,
   );
   const byIdSignature = wrapList(
@@ -110,7 +111,7 @@ const repoSource = (name: NameSet, dbModule: string, stems: EntityStems): string
     `): Promise<${row}> {`,
   );
   const listChain = chain('  ', `return ${table}`, [
-    ".orderBy('createdAt', 'desc')",
+    '.orderBy(sort, dir)',
     '.limit(limit)',
     '.all()',
   ]);
@@ -133,10 +134,13 @@ ${byIdSignature}
 ${byIdBody}
 }
 
+/** The columns a list sorts by. Newest first (\`createdAt\`, \`desc\`) when nobody asks. */
+export type ListSort = 'createdAt' | 'title';
+
 ${listSignature}
   // The actor's org and nobody else's: the handle scopes the read, so there is no org to pass.
-  // Ordered and bounded — an unordered page is a different page on every request — and the handle
-  // adds the primary key as the last sort key, so the order is total without \`id\` spelled here.
+  // Ordered BEFORE it is bounded, so a sort by title is the first titles and never the newest rows
+  // re-sorted; the handle adds the primary key last, in this direction, so the order is total.
 ${listChain}
 }
 
@@ -209,6 +213,18 @@ unitTest('list is newest first and bounded', async () => {
   expect(page.map((row) => row.title)).toEqual(['third', 'second']);
 });
 
+unitTest('list sorts before it bounds, either way', async () => {
+  // Written newest-last, so a bound taken before the sort would hold the wrong two.
+  for (const title of ['b', 'c', 'a']) {
+    await inOrg(orgId, () => repo.insert(draft(title)));
+    clock.advance(1000);
+  }
+  const first = await inOrg(orgId, () => repo.list(2, 'title', 'asc'));
+  expect(first.map((row) => row.title)).toEqual(['a', 'b']);
+  const last = await inOrg(orgId, () => repo.list(2, 'title', 'desc'));
+  expect(last.map((row) => row.title)).toEqual(['c', 'b']);
+});
+
 unitTest('an actor in another org never reads the row, and no call names an org', async () => {
   const stored = await inOrg(orgId, () => repo.insert(draft('private')));
   // Neither read takes an org: the handle scopes both to the actor it runs under.

package/src/templates/github/ci.yml.ts

@@ -3,11 +3,11 @@
 //
 // Nothing under `templates/` emitted `.github` until this file, so every scaffolded app started
 // life with a gate that ran on exactly one machine — the author's. The two commands are
-// `bun run setup` and `bun run check` and NOT a restatement of their steps: a workflow that spelled
-// out `bun install`, `x db migrate`, `x build` and `x verify` is a second definition of the gate,
+// `bun run setup` and `bun run verify` and NOT a restatement of their steps: a workflow that spelled
+// out `bun install`, `x db migrate` and `x verify`'s steps is a second definition of the gate,
 // free to drift from the scripts a human runs, and axiom 1 has one way to do each thing.
-// `bun run check` is also not a synonym for `x verify` — it BUILDS first, and the build is what makes the gate's `budgets` step
-// measurable rather than X_BUDGET_UNMEASURED.
+// `bun run verify` is `x verify` alone: its `budgets` step builds when the stats are missing or
+// older than the source (plan 101, 21), so no build step runs before it.
 
 import { REQUIRED_BUN } from '../../app-root';
 import type { GeneratedFile, NameSet } from '../naming';
@@ -35,10 +35,9 @@ const ci = (app: NameSet): string => `name: ${CI_WORKFLOW_NAME}
 # order, on a machine that has never seen this repository. A check that exists only in CI is one
 # nobody can reproduce locally, and a CI file that restates the gate's steps is a second gate.
 #
-# \`bun run check\` is \`x build --target static\` and THEN \`x verify\`. The build is not a
-# convenience: the gate's \`budgets\` step compares declared limits against measured bytes in
-# \`.x/build-stats.json\`, so a run with no build reports X_BUDGET_UNMEASURED. Run \`x verify\` here
-# instead and this workflow is red for a reason that has nothing to do with the commit.
+# \`bun run verify\` is \`x verify\`, the whole gate. Its \`budgets\` step runs
+# \`x build --target static\` itself when \`.x/build-stats.json\` is missing or older than the source,
+# which on a fresh runner it always is, so no build step comes first.
 #
 # \`bun run setup\` brings up embedded Postgres in-process; the TEST services come from
 # \`docker/docker-compose.test.yml\` — Postgres 18, Redis, NATS and S3 in RAM, durability and logs
@@ -94,7 +93,7 @@ jobs:
       # \`--wait\` returns once every healthcheck passes; the env file points the suites at them.
       - run: docker compose -f ${TEST_COMPOSE_PATH} up -d --wait
       - run: cat ${TEST_ENV_PATH} >> "$GITHUB_ENV"
-      - run: bun run check
+      - run: bun run verify
 `;
 
 /** The CI a new app is born with, in the order a reader meets it: the gate, then the image. */

package/src/templates/guard-bare-error.ts

@@ -59,7 +59,7 @@ export function bareThrows(files: readonly SourceFile[]): readonly Finding[] {
       findings.push({
         code: CODE,
         cause: \`\${file.path}:\${line} throws a bare \${thrown} — it reaches its reader as a stack trace with no code, no cause and nothing to run\`,
-        fix: \`subclass UltimateError in \${file.path} with an X_SCREAMING_SNAKE code, a cause and a fix naming a command, then: x verify\`,
+        fix: \`declare the failure in \${file.path} with defineError({ code, title, status, cause, fix }) from @ultimat3/core — an X_SCREAMING_SNAKE code and a fix naming a command — and throw its class, then: x verify\`,
         at: file.path,
       });
     }
@@ -115,7 +115,7 @@ unitTest('every builtin Error class is the same rule', () => {
   expect(bareThrows(file("throw new MyTypeError('x');"))).toEqual([]);
 });
 
-unitTest('an UltimateError subclass is what the rule asks for', () => {
+unitTest('a declared error is what the rule asks for', () => {
   expect(bareThrows(file('throw new PostError(missingPost(id));'))).toEqual([]);
 });