@ultimat3/cli 1.1.0 → 2.0.0

package/src/sync-authenticator.ts

@@ -0,0 +1,59 @@
+// The app's HTTP authenticator, seen as the `sync` node's. Until this file `sync-node.ts` was
+// handed no `authenticate` by any host, so every socket the framework ever opened carried
+// `actorId: null` — and the channel guard, the live-query gate, the presence entry and the
+// per-tenant subscription cap all decided against an anonymous actor. Realtime was single-tenant
+// by wiring, not by design.
+
+import type { Actor } from '@ultimat3/core';
+import type { HttpConfig } from '@ultimat3/http';
+import {
+  configuredAuthenticator,
+  createRequestContext,
+  defineHttpConfig,
+  UltimateRequest,
+} from '@ultimat3/http';
+import type { SyncAuthenticator, SyncGrant } from '@ultimat3/realtime';
+
+/**
+ * The upgrade request, dressed as the request an `Authenticator` reads.
+ *
+ * A websocket upgrade IS an HTTP request — same cookies, same `Authorization` header — so the
+ * app's one resolver answers it, and an app does not write a second identity for its sockets.
+ * The limiter is off because nothing in this config path serves a request: it exists so
+ * `ctx.config` is a real `HttpConfig`, and a rate limit resolved here would be a second, unread
+ * declaration of the app's own numbers.
+ */
+function upgradeConfig(buildId: string): HttpConfig {
+  return defineHttpConfig({ buildId, rateLimit: { enabled: false, scope: 'process' } });
+}
+
+/**
+ * What the sync node is given when the app configured an authenticator, and `undefined` when it
+ * did not — which keeps `x dev` anonymous and makes the node log that it is, exactly as
+ * `createSyncNode` documents. A stub that answered `{ actor: anonymous }` would look configured.
+ *
+ * The grant carries **no `expiresAt` and no `refresh`**, and that is the honest limit of this
+ * adapter rather than an omission: `configureAuthenticator()` resolves an `Actor` and says nothing
+ * about how long it stays true, so inventing a window here would either close live sockets that
+ * are still authorized or claim a lifetime the app never promised. A deployment whose credential
+ * has a real expiry passes `runtime.syncAuthenticate` and gets re-authorization; the timer for it
+ * already lives in `createSyncNode.start()`.
+ */
+export function syncAuthenticator(buildId: string): SyncAuthenticator | undefined {
+  const authenticate = configuredAuthenticator();
+  if (authenticate === undefined) return undefined;
+  // Once per node, not once per upgrade: resolving a config is pure and a 50k-socket node pays
+  // this per connection otherwise.
+  const config = upgradeConfig(buildId);
+  return async (request: Request): Promise<SyncGrant | null> => {
+    const ctx = createRequestContext({
+      url: new URL(request.url),
+      method: request.method,
+      role: 'sync',
+      config,
+      requestHeaders: request.headers,
+    });
+    const actor: Actor | null = await authenticate(new UltimateRequest(request, ctx), ctx);
+    return actor === null ? null : { actor };
+  };
+}

package/src/templates/action.ts

@@ -5,6 +5,8 @@
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { sliceFoundation } from './slice-foundation';
+import { wrapImport } from './wrap';
 
 const actionSource = (
   name: NameSet,
@@ -18,7 +20,7 @@ import { action, t } from '@ultimat3/action';
 // slice's own files and are shared by every action in it.
 
 import { ${feature.pascal}NotFoundError } from '../errors';
-import { can${feature.pascal}Write, ${feature.camel}Tag } from '../policy';
+${wrapImport([`can${feature.pascal}Write`, `${feature.camel}Tag`], '../policy')}
 import * as repo from '../repo';
 
 export const ${name.camel} = action({
@@ -28,7 +30,7 @@ export const ${name.camel} = action({
   output: t.object({ id: t.uuid, title: t.string }),
   policy: can${feature.pascal}Write,
   cache: { invalidates: [${feature.camel}Tag] },
-  mcp: { expose: true, description: '${name.raw} — generated, edit the description' },
+  mcp: { expose: true, description: '${name.raw} — edit this description' },
   async handle({ input }) {
     const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
@@ -58,7 +60,7 @@ export const ${name.camel} = mutator({
   input: t.object({ id: t.uuid, orgId: t.uuid, title: t.string }),
   output: t.object({ id: t.uuid, title: t.string }),
   policy: can${feature.pascal}Write,
-  mcp: { expose: true, description: '${name.raw} — generated, edit the description' },
+  mcp: { expose: true, description: '${name.raw} — edit this description' },
   // 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.
@@ -77,25 +79,6 @@ export const ${name.camel} = mutator({
 });
 `;
 
-const errorsSource = (
-  feature: NameSet,
-): string => `// The ${feature.kebab} feature's X_* codes. Never throw a bare Error: an agent reading the failure
-// needs the code, the cause and the exact command that fixes it.
-
-import { UltimateError } from '@ultimat3/core';
-
-export class ${feature.pascal}NotFoundError extends UltimateError {
-  constructor(input: { id: string }) {
-    super({
-      code: 'X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND',
-      cause: \`no ${feature.kebab} with id \${input.id}\`,
-      fix: 'x db studio to confirm the row exists, or pass an id from the list query',
-      docs: 'https://ultimate.dev/errors/X_NOT_FOUND',
-    });
-  }
-}
-`;
-
 const ID = '00000000-0000-4000-8000-000000000001';
 const ORG = '00000000-0000-4000-8000-000000000002';
 const OTHER_ORG = '00000000-0000-4000-8000-000000000009';
@@ -121,7 +104,9 @@ const actionTest = (
   name: NameSet,
   feature: NameSet,
   isMutator: boolean,
-): string => `import { testActor } from '@ultimat3/policy';
+): string => `// ${name.camel}: its declared shape, the input it refuses, the contract every action owes, and the
+// foreign-org actor it denies before the handler runs. One declaration, every surface.
+import { testActor } from '@ultimat3/policy';
 import { contractTest, expect, unitTest } from '@ultimat3/testing';
 import { ${name.camel} } from './${name.kebab}';
 
@@ -148,21 +133,21 @@ unitTest('${name.camel} rejects input that is not a uuid', async () => {
   await expect(target.input).toAcceptInput(input);
 });
 
-contractTest('${name.camel} passes the contract every action owes', async () => {
+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();
 });
 
-contractTest('${name.camel} denies a foreign org before the handler runs', async () => {
+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');
 });
 
-contractTest('${name.camel} projects one MCP tool and one OpenAPI operation', () => {
+contractTest('${name.camel} projects one tool and one operation', () => {
   // Same policy object on both surfaces — an MCP call cannot reach a different authz path.
   expect(target.tool().policy).toBe(target.policy);
   expect(target.tool().description).not.toBe('');
@@ -180,14 +165,14 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
   const dir = `${target.surfaceDir}/${target.feature}/actions`;
   const isMutator = target.mutator === true;
   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`
+    // into a slice no `x g resource` had created emitted all three imports and wrote none of them.
+    ...sliceFoundation(target, ['entity', 'policy', 'errors']),
     {
       path: `${dir}/${name.kebab}.ts`,
       contents: isMutator ? mutatorSource(name, feature) : actionSource(name, feature),
     },
     { path: `${dir}/${name.kebab}.test.ts`, contents: actionTest(name, feature, isMutator) },
-    {
-      path: `${target.surfaceDir}/${target.feature}/errors.ts`,
-      contents: errorsSource(feature),
-    },
   ];
 }

package/src/templates/admin-page.ts

@@ -0,0 +1,103 @@
+// `x g admin:page <name>` — a screen the admin derives from nothing: a reconciliation fixer, a
+// proxy health board, a deploy button. What the template has to get right is what it does NOT
+// emit: no `defineRoute`, because `pages:` is the one thing that puts a page in the admin's route
+// table and `guardedPage()` is the one thing that decides it. A scaffold that wrote a route
+// declaration here would hand back the unguarded second way in that seam exists to close.
+
+import { catalogJson } from './catalog-json';
+import { catalogPath, resolveLocales } from './locales';
+import type { GeneratedFile } from './naming';
+import { camel, kebab, pascal } from './naming';
+
+/** Where an admin lives when the caller does not say. `x new` scaffolds this layout. */
+export const DEFAULT_ADMIN_PAGE_DIR = 'apps/admin/src/pages';
+
+export interface AdminPageOptions {
+  /** The permission the page's own work needs. `admin:read` is composed in front of it. */
+  readonly permission: string;
+  /**
+   * Directory the page lands in, app-root-relative and POSIX — the same `--at` `x g island` takes,
+   * and for the same reason: an app's admin is wherever its `defineAdmin` is, which no generator
+   * can derive. `apps/admin/app/admin/` is as real a layout as the scaffold's, and a hardcoded
+   * destination means every such app moves the two files by hand after every run.
+   */
+  readonly dir?: string;
+  readonly locales?: readonly string[];
+}
+
+const titleKeyFor = (name: string): string => `admin.${name}.title`;
+
+const pageSource = (name: string, permission: string, dir: string): string => {
+  const Name = pascal(name);
+  const declaration = camel(name);
+  return `// Admin page: /${name}. An ORDINARY component — there is no \`defineRoute\` here, deliberately:
+// \`pages:\` is what puts this in the admin's route table and \`guardedPage()\` is what decides it,
+// so a route declaration in this file would be a second, unguarded way in.
+//
+// Wire it in once, and add \`navGroup\` to link it in the sidebar — this file is ${dir}/${name}.tsx,
+// so the specifier is relative to wherever \`defineAdmin\` lives:
+//   import { ${declaration}Page } from './${name}';
+//   defineAdmin({ …, pages: […, ${declaration}Page] })
+
+import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';
+import { t } from '@ultimat3/i18n';
+
+export function ${Name}Page(props: AdminPageProps) {
+  return (
+    <section>
+      <h1>{t('${titleKeyFor(name)}')}</h1>
+      <p>{props.url}</p>
+    </section>
+  );
+}
+
+export const ${declaration}Page: AdminCustomPage = {
+  path: '/${name}',
+  titleKey: '${titleKeyFor(name)}',
+  // At least one, never empty: an empty list is X_ADMIN_PAGE_UNGUARDED at declaration time, which
+  // is the whole reason the permission is a required field and not an optional one.
+  permissions: ['${permission}'],
+  component: ${Name}Page,
+};
+`;
+};
+
+const pageTest = (name: string, permission: string): string => {
+  const declaration = camel(name);
+  return `// The ${name} admin page is guarded and owns no route of its own — the two facts that separate an
+// admin screen from a page, and the two an edit here is most likely to break.
+import { expect, unitTest } from '@ultimat3/testing';
+import { ${declaration}Page } from './${name}';
+
+// Both facts the frame reads off the declaration, so both are decidable without a request: a path
+// that is not rooted is X_ADMIN_PAGE_PATH_INVALID, and no permission at all is
+// X_ADMIN_PAGE_UNGUARDED — a page that would render for anyone who can open the admin.
+unitTest('the ${name} admin page is rooted and guarded', () => {
+  expect(${declaration}Page.path.startsWith('/')).toBe(true);
+  expect(${declaration}Page.permissions).toContain('${permission}');
+});
+
+unitTest('the ${name} admin page declares no route of its own', () => {
+  // \`pages:\` is the only way in. A \`config\` export here would be a route the frame never guards.
+  expect('config' in ${declaration}Page).toBe(false);
+});
+`;
+};
+
+export function adminPageFiles(
+  rawName: string,
+  options: AdminPageOptions,
+): readonly GeneratedFile[] {
+  const name = kebab(rawName);
+  // Trailing slashes trimmed exactly as `islandFiles` does — one `--at`, one normalization.
+  const dir = (options.dir ?? DEFAULT_ADMIN_PAGE_DIR).replace(/\/+$/, '');
+  return [
+    { path: `${dir}/${name}.tsx`, contents: pageSource(name, options.permission, dir) },
+    { path: `${dir}/${name}.test.ts`, contents: pageTest(name, options.permission) },
+    ...resolveLocales(options.locales).map((locale) => ({
+      path: catalogPath(locale),
+      contents: catalogJson({ [titleKeyFor(name)]: pascal(name) }),
+      merge: 'json' as const,
+    })),
+  ];
+}

package/src/templates/admin.ts

@@ -11,8 +11,8 @@ import { names } from './naming';
 const resourceSource = (
   feature: NameSet,
 ): string => `// Admin override for ${feature.pluralKebab}. Everything not set here — fields, operations,
-// detail layout — is derived from the entity. Wire this in once:
-//   import { ${feature.camel}AdminResource } from '${'@'}app/web/app/${feature.kebab}/admin/resource';
+// detail layout — is derived from the entity. Wire it in once, importing ${feature.camel}AdminResource
+// through this app's own tsconfig path alias for apps/web/app/${feature.kebab}/admin/resource:
 //   defineAdmin({ entities: [..., ${feature.camel}], resources: { ${feature.table}: ${feature.camel}AdminResource } })
 
 import type { AdminResourceOptions, AdminRow } from '@ultimat3/admin';
@@ -26,13 +26,17 @@ export const ${feature.camel}AdminResource: AdminResourceOptions<AdminRow> = {
 
 const resourceTest = (
   feature: NameSet,
-): string => `import { expect, unitTest } from '@ultimat3/testing';
+): string => `// The ${feature.kebab} admin override says what the entity cannot derive: a title key, the list
+// columns, a bounded page size. Everything unset here is derived, and needs no test.
+import { expect, unitTest } from '@ultimat3/testing';
 import { ${feature.camel}AdminResource } from './resource';
 
-unitTest('${feature.camel}AdminResource sets a title key and bounded list fields', () => {
-  expect(${feature.camel}AdminResource.titleKey).toBe('admin.${feature.kebab}.title');
-  expect(${feature.camel}AdminResource.listFields?.length).toBeGreaterThan(0);
-  expect(${feature.camel}AdminResource.pageSize).toBeGreaterThan(0);
+const resource = ${feature.camel}AdminResource;
+
+unitTest('${feature.camel}AdminResource sets a title key and list fields', () => {
+  expect(resource.titleKey).toBe('admin.${feature.kebab}.title');
+  expect(resource.listFields?.length).toBeGreaterThan(0);
+  expect(resource.pageSize).toBeGreaterThan(0);
 });
 `;
 

package/src/templates/backfill.ts

@@ -0,0 +1,212 @@
+// `x g backfill` — a one-pass table sweep. The backfill is a factory over job(), not a ninth
+// primitive, so it inherits .enqueue(), the retry policy, the cancellation and the manifest row.
+// One live run per name: a second enqueue while the pass is going is the same pass.
+
+import type { FeatureTarget } from './entity';
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+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
+ * touched. The row projection is the one line an author replaces, and it is exported so the
+ * generated test asserts the WORK rather than only the declaration around it.
+ */
+const backfillSource = (
+  name: NameSet,
+  feature: NameSet,
+): 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';
+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.
+ */
+const ${name.camel}Scope = (ctx: Ctx): ReadBuilder<Row> => {
+  assert(
+    hasScope(ctx.actor, CROSS_TENANT_SCOPE),
+    '${name.kebab}: this pass spans every tenant and its actor holds no tenancy:cross',
+    // 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();
+};
+
+/**
+ * What the sweep writes for one row. Replace the projection with the change this pass exists to
+ * make, and keep it IDEMPOTENT: a page replays whole when an attempt is cancelled between the last
+ * row and its checkpoint, so the second run of this function must produce the first run's row.
+ */
+export const ${name.camel}Row = (row: Row): Row => ({
+  ...row,
+  title: row.title.trim(),
+});
+
+export const ${name.camel} = backfill({
+  name: '${name.kebab}',
+  // A sweep over a table belongs to no one org, so it declares none — and \`'none'\` STRIPS the org
+  // rather than inheriting the worker's, so a tenant-scoped read inside the pass fails closed
+  // (X_TENANCY_ACTOR_ORG_REQUIRED) instead of reading somebody's rows by accident. A sweep that
+  // genuinely spans tenants says so out loud: its work runs inside \`crossTenant(reason, fn)\`, and
+  // the reason IS the mechanism. A per-org sweep declares its org instead: \`tenant: () => orgId\`,
+  // one enqueue per org.
+  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.
+    signal.throwIfAborted();
+    const next = rows.map(${name.camel}Row);
+    await ${feature.camel}Table().upsertAll(next, { onConflict: ['id'] });
+  },
+  // 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)\`
+  // and the like): then a dry run cannot lie, and a pass that exhausts its source while this still
+  // answers above zero fails as X_BACKFILL_STALLED instead of writing a completed row nobody can
+  // trust. Left out here because this scaffold re-normalises every row it visits, so a count of
+  // the same chain would never reach zero.
+  // count: ({ ctx }) => ${name.camel}Scope(ctx).andWhere('publishedAt', 'is', null).count(),
+  // batch: 1_000, // rows per step, default. Adjust to balance statement size and retry scope.
+  // rate: 5, // batches per second, default. Raise to sweep faster; there is no unthrottled mode.
+  // retry: { attempts: 5, backoff: 'exponential' },
+  // requires: '20260814120000_add_publish_at', // the migration x db backfill checks first
+  // environments: ['staging', 'production'], // omit for every environment — never implied
+});
+`;
+
+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.
+
+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}`)}
+
+// 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.
+beforeAll(() => {
+  setJobDriver(createMemoryDriver());
+});
+afterAll(resetJobDriver);
+
+// The durable name this sweep runs under, spelled once — so the assertion below carries the
+// 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);
+  expect(${name.camel}.retry.attempts).toBeGreaterThan(1);
+});
+
+jobTest('${name.camel} uses one key across attempts', () => {
+  const key = ${name.camel}.idempotencyKeyFor({});
+  expect(${name.camel}.idempotencyKeyFor({})).toBe(key);
+});
+
+jobTest('${name.camel} projects itself into the manifest', () => {
+  const described = ${name.camel}.describe();
+  expect(described.queue).toBe('default');
+  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.
+  const first = await ${name.camel}.enqueue({});
+  expect(first.deduped).toBe(false);
+  const again = await ${name.camel}.enqueue({});
+  expect(again.deduped).toBe(true);
+});
+`;
+
+export function backfillFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
+  const name = names(rawName);
+  const feature = names(target.feature);
+  const dir = `${target.surfaceDir}/${target.feature}/backfills`;
+  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) },
+    { path: `${dir}/${name.kebab}.test.ts`, contents: backfillTest(name, feature) },
+  ];
+}