@ultimat3/cli 22.14.0 → 23.0.0

package/src/templates/backfill.ts

@@ -3,39 +3,13 @@
 // One live run per name: a second enqueue while the pass is going is the same pass.
 
 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 } from './slice-foundation';
 import { wrapImport } from './wrap';
 
-/**
- * What the entity's value export is called inside the generated file. `x g backfill invoice
- * --feature invoice` is a legal invocation and it emitted `import { invoice } from '../entity'`
- * beside `export const invoice = backfill(...)` — one name, two declarations, which is
- * `lint/suspicious/noRedeclare` in the app's own gate and a genuinely ambiguous reference in TS.
- * Aliased only when it would collide, because every other backfill reads better without one.
- */
-const entityRef = (name: NameSet, feature: NameSet): string =>
-  name.camel === feature.camel ? `${feature.camel}Entity` : feature.camel;
-
-const entityImport = (name: NameSet, feature: NameSet): string => {
-  const local = entityRef(name, feature);
-  return local === feature.camel ? feature.camel : `${feature.camel} as ${local}`;
-};
-
-/**
- * The chain accessor, wrapped the way Biome would wrap it. Emitted pre-formatted rather than
- * always-wrapped because the formatter joins an arrow body back onto one line when it fits — so a
- * fixed shape is wrong for one name length or the other. Same reason `policy.ts` measures its
- * `definePermissions` line.
- */
-const tableLine = (name: NameSet, feature: NameSet): string => {
-  const ref = entityRef(name, feature);
-  const head = `const ${feature.camel}Table = () =>`;
-  const body = `tableFor(${ref}, postgresRepo(${ref}));`;
-  return `${head} ${body}`.length <= 100 ? `${head} ${body}` : `${head}\n  ${body}`;
-};
-
 /**
  * Working source, never a stub: a generated `throw new Error(…)` carries no `X_*` code and a
  * generated no-op handler checkpoints a page it never wrote, which reports swept rows nobody
@@ -45,32 +19,29 @@ const tableLine = (name: NameSet, feature: NameSet): string => {
 const backfillSource = (
   name: NameSet,
   feature: NameSet,
+  dbModule: string,
 ): string => `// ${name.camel}: one pass over a chain of rows. The backfill is a job factory, not a ninth
 // primitive, so it inherits .enqueue(), retry, cancellation and the manifest row.
 // \`BackfillBatch\` comes from @ultimat3/jobs, not @ultimat3/schema: a backfill file imports one package.
 
-import type { Ctx } from '@ultimat3/core';
-import { assert, hasScope } from '@ultimat3/core';
-import type { ReadBuilder } from '@ultimat3/entity';
-import { CROSS_TENANT_SCOPE, postgresRepo, tableFor } from '@ultimat3/entity';
-import type { BackfillBatch } from '@ultimat3/jobs';
-import { backfill } from '@ultimat3/jobs';
+${sortedImports([
+  "import { assert, type Ctx, hasScope } from '@ultimat3/core';",
+  "import { CROSS_TENANT_SCOPE, type ReadBuilder } from '@ultimat3/entity';",
+  "import { type BackfillBatch, backfill } from '@ultimat3/jobs';",
+  `import { db } from '${dbModule}';`,
+])}
 import type { ${feature.pascal} } from '../entity';
-import { ${entityImport(name, feature)} } from '../entity';
 
 /** The row this sweep visits, aliased once: every signature below then reads at one width. */
 type Row = ${feature.pascal};
 
-/** The table as a chain — the seam \`database()\` hands an app, so this sweep reads what a query reads. */
-${tableLine(name, feature)}
-
 /**
- * The rows this pass visits. A one-pass sweep has no single org, so it declares \`tenant: 'none'\`
- * below — which STRIPS the org from the run rather than inheriting the worker's. That makes
- * spanning tenants a capability instead of an accident: the actor this worker runs as has to carry
- * \`tenancy:cross\`, and this is where that is said, before a page is read rather than inside the
- * plan builder. A single-org sweep is the other shape — declare \`tenant: () => '<org id>'\` and put
- * \`.where({ orgId: ctx.actor.orgId })\` back.
+ * The rows this pass visits, read through the app's typed handle — the table a query reads. A
+ * one-pass sweep has no single org, so it declares \`tenant: 'none'\` below — which STRIPS the org
+ * from the run rather than inheriting the worker's. That makes spanning tenants a capability
+ * instead of an accident: the actor this worker runs as has to carry \`tenancy:cross\`, and this is
+ * where that is said, before a page is read rather than inside the plan builder. A single-org
+ * sweep is the other shape — declare \`tenant: () => '<org id>'\`, and the handle scopes the read.
  */
 const ${name.camel}Scope = (ctx: Ctx): ReadBuilder<Row> => {
   assert(
@@ -79,7 +50,7 @@ const ${name.camel}Scope = (ctx: Ctx): ReadBuilder<Row> => {
     // A generated \`fix:\` is copied and run verbatim, so it names a command this build SHIPS.
     'x db backfill ${name.kebab} --write --json',
   );
-  return ${feature.camel}Table();
+  return db.${feature.plural};
 };
 
 /**
@@ -103,12 +74,18 @@ export const ${name.camel} = backfill({
   tenant: 'none',
   source: ({ ctx }): ReadBuilder<Row> => ${name.camel}Scope(ctx),
   handle: async ({ rows, signal }: BackfillBatch<Row>) => {
-    // One page, in its own durable step, at least once. Write through upsertAll, updateWhere or an
-    // idempotent statement; never count + 1. The signal is the run cancellation composed with this
-    // batch's ceiling, so a cancelled pass stops here instead of writing past its lease.
+    // One page, in its own durable step, at least once. The signal is the run cancellation
+    // composed with this batch's ceiling, so a cancelled pass stops here instead of writing past
+    // its lease.
     signal.throwIfAborted();
-    const next = rows.map(${name.camel}Row);
-    await ${feature.camel}Table().upsertAll(next, { onConflict: ['id'] });
+    // One \`update\` per row, by primary key, and only the column this pass owns — never count + 1.
+    // Not \`upsertAll(rows, { onConflict: ['id'] })\`: on a tenant-scoped table a collision judged
+    // on \`id\` alone could land on another tenant's row, so the handle refuses it
+    // (X_TENANCY_UNSCOPED) and the pass would retry its first page for ever.
+    for (const row of rows) {
+      const next = ${name.camel}Row(row);
+      await db.${feature.plural}.update(row.id, { title: next.title });
+    }
   },
   // How many rows still NEED the change — never how many the sweep visits. Declare it once
   // \`source\` narrows to the rows that are actually behind (\`.andWhere('publishedAt', 'is', null)\`
@@ -127,15 +104,12 @@ export const ${name.camel} = backfill({
 
 const backfillTest = (
   name: NameSet,
-  feature: NameSet,
-): string => `// ${name.camel} sweeps rows a user never asked for, so the two facts worth failing on are its
-// durable identity — one live run per name, retried under the same key — and that the row
-// projection it applies is idempotent, because a cancelled attempt replays its page whole.
+): string => `// ${name.camel}'s durable identity: one live run per name, retried under the same key. The work
+// itself — the pass over real rows and the projection it applies — is the unit suite's, next door.
 
 import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
 import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
-import type { ${feature.pascal} } from '../entity';
-${wrapImport([name.camel, `${name.camel}Row`], `./${name.kebab}`)}
+import { ${name.camel} } from './${name.kebab}';
 
 // The driver is process-global, so it is installed and released around this file rather than
 // left behind for whichever test happens to run next.
@@ -148,15 +122,6 @@ afterAll(resetJobDriver);
 // backfill's own name and still fits the formatter width the app's \`lint\` step enforces.
 const expectedKey = '${name.kebab}';
 
-const row = (over: Partial<${feature.pascal}> = {}): ${feature.pascal} => ({
-  id: '00000000-0000-4000-8000-000000000001',
-  orgId: '00000000-0000-4000-8000-000000000002',
-  title: '  needs normalising  ',
-  price: { minor: 1000, currency: 'USD' },
-  createdAt: new Date(0),
-  ...over,
-});
-
 jobTest('${name.camel} declares a durable name and retry policy', () => {
   expect(${name.camel}.kind).toBe('job');
   expect(${name.camel}.idempotencyKeyFor({})).toBe(expectedKey);
@@ -174,19 +139,6 @@ jobTest('${name.camel} projects itself into the manifest', () => {
   expect(described.retry.attempts).toBeGreaterThan(0);
 });
 
-jobTest('${name.camel} actually rewrites the row it is handed', () => {
-  // The declaration alone cannot fail this: a handler that returned without writing would still
-  // enqueue, still checkpoint and still report the page as swept.
-  expect(${name.camel}Row(row()).title).toBe('needs normalising');
-});
-
-jobTest('${name.camel} replays a page idempotently', () => {
-  // At least once is the contract: an attempt cancelled between the last row and its checkpoint
-  // hands this page to the next attempt. Twice through must equal once through.
-  const once = ${name.camel}Row(row());
-  expect(${name.camel}Row(once)).toEqual(once);
-});
-
 jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
   // One live run per name, forced or not: a second enqueue while the pass is going is the same pass.
   // \`.enqueue()\` is the backfill path — the declared job, queued with no scheduler involved.
@@ -197,18 +149,100 @@ jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
 });
 `;
 
-export function backfillFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
+/**
+ * The WORK, on the `unit` step: one whole pass, run by an in-process worker over rows in the
+ * in-memory driver, and the projection it applies. An app's coverage floor counts the unit suite
+ * alone — and a sweep whose handler nothing ever ran is how a body that could not complete shipped.
+ */
+const backfillUnitTest = (
+  name: NameSet,
+  feature: NameSet,
+  dbModule: string,
+): string => `// ${name.camel}, SWEPT: one whole pass run by a worker in this process, over rows in the in-memory
+// driver. A sweep rewrites rows no user asked it to, so what is worth failing on is that it reaches
+// every tenant's rows, writes the projection and nothing else, and that a replay changes nothing.
+${sortedImports([
+  "import { createContext, runWithContext } from '@ultimat3/core';",
+  "import { testActor } from '@ultimat3/policy';",
+  "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
+  `import { db, driver } from '${dbModule}';`,
+])}
+import type { ${feature.pascal} } from '../entity';
+${wrapImport([name.camel, `${name.camel}Row`], `./${name.kebab}`)}
+
+const orgA = '00000000-0000-4000-8000-000000000002';
+const orgB = '00000000-0000-4000-8000-000000000009';
+
+/** What a request is to the handle: an actor, whose org every read and write runs under. */
+const inOrg = <T>(orgId: string, run: () => Promise<T>): Promise<T> =>
+  runWithContext(createContext({ actor: testActor('member', { orgId }).actor }), run);
+
+const store = (orgId: string, title: string): Promise<${feature.pascal}> => {
+  const draft = { orgId, title, price: { minor: 1000, currency: 'USD' } };
+  return inOrg(orgId, () => db.${feature.plural}.insert(draft));
+};
+
+const titlesOf = (orgId: string): Promise<readonly string[]> =>
+  inOrg(orgId, async () => (await db.${feature.plural}.all()).map((row) => row.title));
+
+// One store per process: without this, one test's rows are the next test's fixtures.
+afterEach(() => {
+  driver.reset?.();
+});
+
+unitTest('one pass rewrites the rows of every tenant, and completes', async ({ runJobs }) => {
+  await store(orgA, '  needs normalising  ');
+  await store(orgB, ' so does this ');
+  const trace = await runJobs(${name.camel}, {});
+  // \`completed\`, not retried: a handler the table refuses retries its first page for ever.
+  expect(trace.executions.map((run) => run.outcome)).toEqual(['completed']);
+  expect(await titlesOf(orgA)).toEqual(['needs normalising']);
+  expect(await titlesOf(orgB)).toEqual(['so does this']);
+});
+
+unitTest('the pass writes the projection and nothing else', async ({ runJobs }) => {
+  const stored = await store(orgA, ' padded ');
+  await runJobs(${name.camel}, {});
+  const [swept] = await inOrg(orgA, () => db.${feature.plural}.all());
+  expect(swept).toEqualRow({ ...stored, title: 'padded' });
+});
+
+unitTest('the projection is idempotent: a replayed page changes nothing', () => {
+  // At least once is the contract: an attempt cancelled between the last row and its checkpoint
+  // hands this page to the next attempt. Twice through must equal once through.
+  const row: ${feature.pascal} = {
+    id: '00000000-0000-4000-8000-000000000001',
+    orgId: orgA,
+    title: '  needs normalising  ',
+    price: { minor: 1000, currency: 'USD' },
+    createdAt: new Date(0),
+  };
+  const once = ${name.camel}Row(row);
+  expect(once.title).toBe('needs normalising');
+  expect(${name.camel}Row(once)).toEqual(once);
+});
+`;
+
+export interface BackfillOptions extends FeatureTarget {
+  /** Every locale the planted entity's admin labels ship for. Defaults to `['en']`. */
+  readonly locales?: readonly string[];
+}
+
+export function backfillFiles(rawName: string, target: BackfillOptions): readonly GeneratedFile[] {
   const name = names(rawName);
   const feature = names(target.feature);
   const dir = `${target.surfaceDir}/${target.feature}/backfills`;
+  const dbModule = target.dbModule ?? PLACEHOLDER_DB_MODULE;
   return [
-    // A sweep is a chain over the entity's own table (`tableFor(entity, postgresRepo(entity))`), so
-    // the entity is what it reads and what its generated test builds rows of. No repo call, but
-    // `repo.ts` rides along with `entity.ts`: it is that file's only reader.
-    ...sliceFoundation(target, ['entity']),
-    { path: `${dir}/${name.kebab}.ts`, contents: backfillSource(name, feature) },
-    // A sweep IS a job (`backfill()` is a job factory), its test is a `jobTest`, and the gate
-    // types a test by its filename — so `<name>.test.ts` put it in the `unit` step forever.
-    { path: `${dir}/${name.kebab}.job.test.ts`, contents: backfillTest(name, feature) },
+    // A sweep is a chain over the entity's own table, reached through the app's typed handle
+    // (`db.<table>`), so the entity is what it reads and what its generated test stores rows of.
+    // No repo call, but `repo.ts` rides along with `entity.ts`: it is that file's only reader.
+    ...sliceFoundation(target, ['entity'], target.locales),
+    { path: `${dir}/${name.kebab}.ts`, contents: backfillSource(name, feature, dbModule) },
+    // A sweep IS a job (`backfill()` is a job factory): its durable identity is a `jobTest`, and
+    // the gate types a test by its filename.
+    { path: `${dir}/${name.kebab}.job.test.ts`, contents: backfillTest(name) },
+    // And the pass itself on the `unit` step, against the in-memory driver.
+    { path: `${dir}/${name.kebab}.test.ts`, contents: backfillUnitTest(name, feature, dbModule) },
   ];
 }

package/src/templates/entity.ts

@@ -1,10 +1,13 @@
 // `x g entity <name>` — a table, its domain type and its invariants, plus the repo that owns the
-// only DB access for the feature. Emitted as strings rather than copied fixture files so the
-// generator output is typed, diffable and testable from a unit test.
+// only DB access for the feature and reads through the app's typed handle. Emitted as strings
+// rather than copied fixture files so the generator output is typed, diffable and testable from a
+// unit test.
 
+import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
-import { wrapImport, wrapList } from './wrap';
+import { PLACEHOLDER_DB_MODULE } from './scaffold-db-client';
+import { LINE_WIDTH, wrapImport, wrapList } from './wrap';
 
 /** The columns that leave the server. One list, read by the declaration and by its test. */
 const VIEW_KEYS: readonly string[] = ["'id'", "'title'", "'price'", "'createdAt'"];
@@ -13,6 +16,12 @@ export interface FeatureTarget {
   /** `apps/web/app` or `apps/web/site` — the surface the feature lives in. */
   readonly surfaceDir: string;
   readonly feature: string;
+  /**
+   * The app's own db package, `@<app>/db` — where the generated `repo.ts` imports the typed handle
+   * from. Supplied by `x g` (read off `packages/db/package.json`) and by `x new`; absent only in a
+   * pure call that names no app, which gets `PLACEHOLDER_DB_MODULE`.
+   */
+  readonly dbModule?: string;
 }
 
 const entitySource = (
@@ -30,10 +39,10 @@ export const ${name.camel} = entity('${table}', {
   //
   // SINGLE-TENANT APP? There is no flag: \`x g action\`, \`x g query\` and \`x g policy\` decide on
   // \`orgId\` too, so the edit is per slice and it is this: delete \`tenant: 'orgId'\` and the
-  // \`orgId: uuid()\` column below, drop \`'orgId'\` from \`indexes\`, and in repo.ts turn
-  // \`listByOrg(orgId, limit)\` into \`list(limit)\` with no \`org_id\` predicate and no \`org_id\` in
-  // the insert. entity.test.ts then expects \`$tenantColumn\` null and \`orgScoped\` false, and its
-  // \`row()\` fixture loses \`orgId\`. Nothing else reads the column.
+  // \`orgId: uuid()\` column below and drop \`'orgId'\` from \`indexes\`. repo.ts needs no edit —
+  // it names no org. entity.test.ts then expects \`$tenantColumn\` null and \`orgScoped\` false,
+  // its \`row()\` fixture and repo.test.ts's \`draft()\` lose \`orgId\`, and repo.test.ts loses its
+  // last test. Nothing else reads the column.
   tenant: 'orgId',
   columns: {
     id: uuid().primaryKey(),
@@ -64,67 +73,152 @@ ${wrapList('', `export const ${name.pascal}View = ${name.camel}.$view([`, VIEW_K
 export type ${name.pascal}View = typeof ${name.pascal}View.$row;
 `;
 
-const repoSource = (name: NameSet, table: string): string => {
+/**
+ * A fluent read the way Biome prints it: on one line while it fits, one call per line when it does
+ * not. The name decides which — `db.creditNoteAttachments` breaks a chain `db.posts` does not — so
+ * a fixed shape is a red `lint` over code nobody typed.
+ */
+const chain = (indent: string, head: string, calls: readonly string[]): string => {
+  const joined = `${indent}${head}${calls.join('')};`;
+  if (joined.length <= LINE_WIDTH) return joined;
+  return `${indent}${head}\n${calls.map((call) => `${indent}  ${call}`).join('\n')};`;
+};
+
+const repoSource = (name: NameSet, dbModule: string): string => {
   const row = name.pascal;
-  const byIdCall = wrapList(
-    '  ',
-    'const row = await db().one<Physical>(',
-    [`sql\`select * from ${table} where id = \${id}\``],
-    ');',
-  );
+  const table = `db.${name.plural}`;
   const listSignature = wrapList(
     '',
-    'export async function listByOrg(',
-    ['orgId: string', 'limit = 50'],
+    'export async function list(',
+    ['limit = 50'],
     `): Promise<readonly ${row}[]> {`,
   );
+  const byIdSignature = wrapList(
+    '',
+    'export async function byId(',
+    ['id: string'],
+    `): Promise<${row} | undefined> {`,
+  );
+  const byIdBody = `  return (await ${table}.where({ id }).one()) ?? undefined;`;
   const insertSignature = wrapList(
     '',
     'export async function insert(',
     [`row: Omit<${row}, 'id' | 'createdAt'>`],
     `): Promise<${row}> {`,
   );
+  const listChain = chain('  ', `return ${table}`, [
+    ".orderBy('createdAt', 'desc')",
+    '.limit(limit)',
+    '.all()',
+  ]);
   return `// The only module allowed to query the ${name.pluralKebab} table. Routes call actions and
 // queries; actions call services; services call this.
-// \`db()\` is the ambient handle: inside a transaction it IS the transaction, so these functions
-// join the caller's transaction without knowing one is open.
-
-import { db, sql } from '@ultimat3/db';
-import { dbDrift, decodeRow, newId } from '@ultimat3/entity';
-${wrapImport([`type ${name.pascal}`, name.camel], './entity')}
+//
+// Every statement goes through the typed handle (\`db.<table>\`), so a renamed column is a compile
+// error here and there is no SQL text to keep in step with the entity. The handle owns the rest:
+// tenancy (every read runs under the ACTOR's org, so no function here takes or names one), the
+// codecs (money is one property; a sealed column is opened on read), keyset paging (\`.limit()\`,
+// \`.after(cursor)\`) and the ambient transaction.
+//
+// Raw SQL has two homes and neither is this file: a \`query\`'s source and a migration. Reach for
+// it here only for a statement the handle cannot express — a join, a window, a CTE.
 
-// What \`select *\` answers: snake_case columns, and money as three of them. Never cast to the row
-// type — \`decodeRow\` is the entity's own reading of it, so \`price\` is a Money again.
-type Physical = Readonly<Record<string, unknown>>;
+import { db } from '${dbModule}';
+import type { ${row} } from './entity';
 
-export async function byId(id: string): Promise<${name.pascal} | undefined> {
-${byIdCall}
-  return row === null ? undefined : decodeRow(${name.camel}, row);
+${byIdSignature}
+${byIdBody}
 }
 
 ${listSignature}
-  // Ordered and bounded: an unordered page is a different page on every request.
-  const rows = await db().query<Physical>(
-    sql\`select * from ${table} where org_id = \${orgId} order by created_at desc limit \${limit}\`,
-  );
-  return rows.map((row) => decodeRow(${name.camel}, row));
+  // 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.
+${listChain}
 }
 
 ${insertSignature}
-  // Money is three physical columns — integer minor units, the ISO code, and the scale, never a
-  // float. \`scale ?? null\`: an amount at the currency's own minor unit carries no scale at all,
-  // and writing \`0\` for it would claim whole units — a 100x reinterpretation of the price.
-  const created = await db().one<Physical>(sql\`
-    insert into ${table} (id, org_id, title, price_minor, price_currency, price_scale)
-    values (\${newId()}, \${row.orgId}, \${row.title}, \${row.price.minor}, \${row.price.currency},
-            \${row.price.scale ?? null})
-    returning *\`);
-  if (created === null) throw dbDrift('${table}', 'id');
-  return decodeRow(${name.camel}, created);
+  // \`id\` and \`createdAt\` are the declaration's defaults, filled by the handle. The row names its
+  // org, and one that is not the actor's is refused (X_TENANCY_ACTOR_MISMATCH).
+  return ${table}.insert(row);
 }
 `;
 };
 
+/**
+ * The repo's own test, emitted beside it: a generated file with no test is uncovered source in an
+ * app whose gate holds a coverage floor. Runs against the in-memory driver — the same contract
+ * Postgres serves — so it needs no database.
+ */
+const repoTest = (
+  name: NameSet,
+  dbModule: string,
+): string => `// The ${name.kebab} repo against the in-memory driver: the contract Postgres serves, with no
+// database. What it pins is what the repo cannot show by being read — whose rows a call reaches.
+${sortedImports([
+  "import { createContext, frozenClock, runWithContext } from '@ultimat3/core';",
+  "import { testActor } from '@ultimat3/policy';",
+  "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
+  `import { driver } from '${dbModule}';`,
+])}
+import * as repo from './repo';
+
+const orgId = '00000000-0000-4000-8000-000000000002';
+const otherOrg = '00000000-0000-4000-8000-000000000009';
+
+// The request clock, so \`createdAt\` is an instant this file chose and "newest" is decidable.
+const clock = frozenClock('2026-01-01T00:00:00.000Z');
+
+/** What a request is to the handle: an actor, whose org every read and write runs under. */
+const inOrg = <T>(org: string, run: () => Promise<T>): Promise<T> =>
+  runWithContext(createContext({ actor: testActor('member', { orgId: org }).actor, clock }), run);
+
+const draft = (title: string) => ({ orgId, title, price: { minor: 1200, currency: 'USD' } });
+
+// One store per process: without this, one test's rows are the next test's fixtures.
+afterEach(() => {
+  driver.reset?.();
+});
+
+unitTest('insert stores the row and byId reads it back', async () => {
+  const stored = await inOrg(orgId, () => repo.insert(draft('first')));
+  // Neither was supplied: the entity's own defaults filled both.
+  expect(stored.id).toHaveLength(36);
+  expect(stored.createdAt).toEqual(clock.now());
+  expect(stored.price).toEqual({ minor: 1200, currency: 'USD' });
+  // \`toEqualRow\`, never \`toEqual\`: a \`.sealed()\` column is a non-enumerable property of a row,
+  // so \`toEqual\` would call two rows equal that hold different secrets.
+  expect(await inOrg(orgId, () => repo.byId(stored.id))).toEqualRow(stored);
+});
+
+unitTest('byId answers undefined for an id nothing holds', async () => {
+  const absent = '00000000-0000-4000-8000-0000000000ff';
+  expect(await inOrg(orgId, () => repo.byId(absent))).toBeUndefined();
+});
+
+unitTest('list is newest first and bounded', async () => {
+  for (const title of ['first', 'second', 'third']) {
+    await inOrg(orgId, () => repo.insert(draft(title)));
+    clock.advance(1000);
+  }
+  const page = await inOrg(orgId, () => repo.list(2));
+  expect(page.map((row) => row.title)).toEqual(['third', 'second']);
+});
+
+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.
+  expect(await inOrg(otherOrg, () => repo.byId(stored.id))).toBeUndefined();
+  expect(await inOrg(otherOrg, () => repo.list())).toEqual([]);
+  expect(await inOrg(orgId, () => repo.list())).toHaveLength(1);
+});
+
+unitTest('a read with no actor is refused rather than answered for every org', async () => {
+  const refused = await repo.list().catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('X_TENANCY_UNSCOPED');
+});
+`;
+
 const entityTest = (
   name: NameSet,
   snake: string,
@@ -202,9 +296,11 @@ unitTest('${name.camel} parses a row through its own columns', () => {
 export function entityFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
   const name = names(rawName);
   const dir = `${target.surfaceDir}/${target.feature}`;
+  const dbModule = target.dbModule ?? PLACEHOLDER_DB_MODULE;
   return [
     { path: `${dir}/entity.ts`, contents: entitySource(name, name.snake, name.table) },
     { path: `${dir}/entity.test.ts`, contents: entityTest(name, name.snake, name.table) },
-    { path: `${dir}/repo.ts`, contents: repoSource(name, name.table) },
+    { path: `${dir}/repo.ts`, contents: repoSource(name, dbModule) },
+    { path: `${dir}/repo.test.ts`, contents: repoTest(name, dbModule) },
   ];
 }

package/src/templates/guard-animated-layout-property.ts

@@ -185,17 +185,10 @@ function layoutFinding(path: string, at: string, property: string, where: string
 
 export const guard: Guard = {
   summary: 'an animation moves transform and opacity, never the layout',
-  async check(root) {
-    const files: StyleFile[] = [];
-    for await (const entry of new Bun.Glob('{apps,packages}/**/*.scss').scan({
-      cwd: root,
-      absolute: false,
-    })) {
-      const path = entry.split('\\\\').join('/');
-      if (path.includes('node_modules/')) continue;
-      files.push({ path, scss: await Bun.file(\`\${root}/\${path}\`).text() });
-    }
-    return animatedLayoutProperties(files);
+  async check(_root, sources) {
+    // The run's ONE read of the stylesheets: every guard asking for this glob shares the walk.
+    const sheets = await sources.files('{apps,packages}/**/*.scss');
+    return animatedLayoutProperties(sheets.map((file) => ({ path: file.path, scss: file.text })));
   },
 };
 `;

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

@@ -67,19 +67,15 @@ export function bareThrows(files: readonly SourceFile[]): readonly Finding[] {
 
 export const guard: Guard = {
   summary: 'a failure carries a code, a cause and an executable fix — never a bare Error',
-  async check(root) {
-    const files: SourceFile[] = [];
-    for await (const entry of new Bun.Glob('{apps,packages}/**/*.{ts,tsx}').scan({
-      cwd: root,
-      absolute: false,
-    })) {
-      const path = entry.split('\\\\').join('/');
-      // A test states its verdict with \`expect.unreachable()\`, which the suite reports on its own
-      // terms; \`node_modules\` is not this app's source.
-      if (path.includes('node_modules/') || /\\.(?:test|d)\\.tsx?$/.test(path)) continue;
-      files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
-    }
-    return bareThrows(files);
+  async check(_root, sources) {
+    // A test states its verdict with \`expect.unreachable()\`, which the suite reports on its own
+    // terms. The run's ONE read of the source: every guard asking for this glob shares the walk.
+    const code = await sources.files('{apps,packages}/**/*.{ts,tsx}');
+    return bareThrows(
+      code
+        .filter((file) => !/\\.(?:test|d)\\.tsx?$/.test(file.path))
+        .map((file) => ({ path: file.path, source: file.text })),
+    );
   },
 };
 `;

package/src/templates/guard-focus-visible.ts

@@ -161,17 +161,10 @@ export function unreplacedFocusRings(files: readonly StyleFile[]): readonly Find
 
 export const guard: Guard = {
   summary: 'a stylesheet replaces the focus ring, never only removes it',
-  async check(root) {
-    const files: StyleFile[] = [];
-    for await (const entry of new Bun.Glob('{apps,packages}/**/*.scss').scan({
-      cwd: root,
-      absolute: false,
-    })) {
-      const path = entry.split('\\\\').join('/');
-      if (path.includes('node_modules/')) continue;
-      files.push({ path, scss: await Bun.file(\`\${root}/\${path}\`).text() });
-    }
-    return unreplacedFocusRings(files);
+  async check(_root, sources) {
+    // The run's ONE read of the stylesheets: every guard asking for this glob shares the walk.
+    const sheets = await sources.files('{apps,packages}/**/*.scss');
+    return unreplacedFocusRings(sheets.map((file) => ({ path: file.path, scss: file.text })));
   },
 };
 `;

package/src/templates/guard-image-dimensions.ts

@@ -141,19 +141,19 @@ export function unsizedImages(files: readonly SourceFile[]): readonly Finding[]
 
 export const guard: Guard = {
   summary: 'an image declares its box, and the priority one is never lazy',
-  async check(root) {
+  async check(_root, sources) {
     const files: SourceFile[] = [];
     // TWO globs, and the rule is that a brace ALTERNATIVE may not contain a \`/\`. Measured on Bun
     // 1.4.0 against \`examples/dummy\`: \`{apps/*/{site,app},packages/*/src}/**/*.tsx\` and
     // \`{apps/web,packages/ui}/**/*.tsx\` each match ZERO files, where \`apps/*/{site,app}/**/*.tsx\`
     // matches 17 — so folding these into one line silently turns the guard off, which is worse than
-    // the hole it closes. A LEADING group is fine and four guards here rely on it:
+    // the hole it closes. A LEADING group is fine and the stylesheet guards here rely on it:
     // \`{apps,packages}/**/*.scss\` matches all 15.
     for (const pattern of ['apps/*/{site,app}/**/*.tsx', 'packages/*/src/**/*.tsx']) {
-      for await (const entry of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
-        const path = entry.split('\\\\').join('/');
-        if (path.includes('node_modules/') || /\\.test\\.tsx?$/.test(path)) continue;
-        files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+      // The run's ONE read: every guard asking for these two globs shares the walk.
+      for (const file of await sources.files(pattern)) {
+        if (/\\.test\\.tsx?$/.test(file.path)) continue;
+        files.push({ path: file.path, source: file.text });
       }
     }
     return unsizedImages(files);