@ultimat3/cli 1.1.0 → 2.0.0

package/src/templates/entity.ts

@@ -4,6 +4,10 @@
 
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { 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'"];
 
 export interface FeatureTarget {
   /** `apps/web/app` or `apps/web/site` — the surface the feature lives in. */
@@ -28,16 +32,18 @@ export const ${name.camel} = entity('${table}', {
     id: uuid().primaryKey(),
     orgId: uuid(),
     title: text({ max: 200 }),
-    // One property, two physical columns: price_minor bigint + price_currency char(3).
-    // Money is integer minor units plus an ISO code, never a float.
+    // One property, three physical columns: price_minor bigint + price_currency char(3) +
+    // the nullable price_scale integer. Money is integer minor units plus an ISO code, never a
+    // float; the scale is what lets an amount name a sub-cent value, and NULL is not 0.
     price: money(),
     // Always timestamptz. Stored UTC; formatted at the edge with an explicit IANA time zone.
     createdAt: timestamp().defaultNow(),
   },
   // Each rule runs in the app on write AND as a Postgres CHECK — one declaration, both sides.
-  invariants: [
-    invariant('${snake}_title_not_blank', (c) => c.title.trimmed().minLength(1)),
-    invariant('${snake}_price_non_negative', (c) => c.price.minor.atLeast(0)),
+  // \`c\` is typed from the columns above: \`c.titel\` is a compile error that names \`title\`.
+  invariants: (c) => [
+    invariant('${snake}_title_not_blank', c.title.trimmed().minLength(1)),
+    invariant('${snake}_price_non_negative', c.price.minor.atLeast(0)),
   ],
   indexes: [{ on: ['orgId', 'createdAt'] }],
 });
@@ -47,14 +53,31 @@ export type ${name.pascal} = typeof ${name.camel}.$row;
 // What leaves the server: an action writes \`output: ${name.pascal}View\` and the shape is the
 // columns', never a second declaration to keep in sync. The tenant column is not in it — an org
 // id is the caller's context, not the client's data.
-export const ${name.pascal}View = ${name.camel}.$view(['id', 'title', 'price', 'createdAt']);
+${wrapList('', `export const ${name.pascal}View = ${name.camel}.$view([`, VIEW_KEYS, ']);')}
 export type ${name.pascal}View = typeof ${name.pascal}View.$row;
 `;
 
-const repoSource = (
-  name: NameSet,
-  table: string,
-): string => `// The only module allowed to query the ${name.pluralKebab} table. Routes call actions and
+const repoSource = (name: NameSet, table: string): string => {
+  const row = name.pascal;
+  const byIdCall = wrapList(
+    '  ',
+    `const row = await db().one<${row}>(`,
+    [`sql\`select * from ${table} where id = \${id}\``],
+    ');',
+  );
+  const listSignature = wrapList(
+    '',
+    'export async function listByOrg(',
+    ['orgId: string', 'limit = 50'],
+    `): Promise<readonly ${row}[]> {`,
+  );
+  const insertSignature = wrapList(
+    '',
+    'export async function insert(',
+    [`row: Omit<${row}, 'id' | 'createdAt'>`],
+    `): Promise<${row}> {`,
+  );
+  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.
@@ -64,43 +87,53 @@ import { dbDrift, newId } from '@ultimat3/entity';
 import type { ${name.pascal} } from './entity';
 
 export async function byId(id: string): Promise<${name.pascal} | undefined> {
-  const row = await db().one<${name.pascal}>(sql\`select * from ${table} where id = \${id}\`);
+${byIdCall}
   return row ?? undefined;
 }
 
-export async function listByOrg(orgId: string, limit = 50): Promise<readonly ${name.pascal}[]> {
+${listSignature}
   // Ordered and bounded: an unordered page is a different page on every request.
   return db().query<${name.pascal}>(
     sql\`select * from ${table} where org_id = \${orgId} order by created_at desc limit \${limit}\`,
   );
 }
 
-export async function insert(row: Omit<${name.pascal}, 'id' | 'createdAt'>): Promise<${name.pascal}> {
-  // Money is two physical columns — integer minor units plus the ISO code, never a float.
+${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<${name.pascal}>(sql\`
-    insert into ${table} (id, org_id, title, price_minor, price_currency)
-    values (\${newId()}, \${row.orgId}, \${row.title}, \${row.price.minor}, \${row.price.currency})
+    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 created;
 }
 `;
+};
 
 const entityTest = (
   name: NameSet,
   snake: string,
   table: string,
-): string => `import { expect, unitTest } from '@ultimat3/testing';
+): string => `// The ${name.kebab} entity's declaration: the table it maps to and the invariants it names. Both
+// are what the migration generator and every query read, so both are worth pinning.
+import { expect, unitTest } from '@ultimat3/testing';
 import type { ${name.pascal} } from './entity';
-import { ${name.pascal}View, ${name.camel} } from './entity';
+${wrapImport([`${name.pascal}View`, name.camel], './entity')}
+
+type Over = Partial<${name.pascal}>;
 
-const row = (over: Partial<${name.pascal}> = {}): ${name.pascal} => ({
+const row = (over: Over = {}): ${name.pascal} => ({
   id: '00000000-0000-4000-8000-000000000001',
   orgId: '00000000-0000-4000-8000-000000000002',
   title: 'valid title',
-  // \`money()\` puts \`MoneyValue\` on the row, whose minor units are bigint — the column is a
-  // Postgres bigint, and a JS number would silently lose precision above 2^53 minor units.
-  price: { minor: 1000n, currency: 'USD' },
+  // \`money()\` puts \`MoneyValue\` on the row — the same type \`@ultimat3/money\`'s \`Money\` is,
+  // so this value goes straight to \`add()\`, \`formatMoney()\` and \`<Money>\` with no conversion.
+  // Integer minor units, never a float; the column is a Postgres bigint and a stored value past
+  // ±2^53 is refused when it is read rather than rounded into the row.
+  price: { minor: 1000, currency: 'USD' },
   createdAt: new Date(0),
   ...over,
 });
@@ -117,24 +150,32 @@ unitTest('${name.camel} describes itself for the manifest', () => {
   // a column added below reaches every one of them without a second declaration.
   const described = ${name.camel}.$describe();
   expect(described.orgScoped).toBe(true);
-  // One \`price\` property, two physical columns: integer minor units plus the ISO code. The
-  // description is where that shows, and it is what fails here if money ever becomes a float.
+  // One \`price\` property, three physical columns: integer minor units, the ISO code, and the
+  // nullable scale. The description is where that shows, and it is what fails here if money ever
+  // becomes a float — or if a migration forgets the scale column and unscales every sub-cent row.
   expect(described.columns.map((column) => column.column)).toContain('price_minor');
   expect(described.columns.map((column) => column.column)).toContain('price_currency');
-  expect(described.invariants.map((rule) => rule.name)).toContain('${snake}_price_non_negative');
+  expect(described.columns.map((column) => column.column)).toContain('price_scale');
+  // Named first: the assertion line carries the entity's own name and stays under the app's
+  // formatter width whatever that name is.
+  const rules = described.invariants.map((rule) => rule.name);
+  expect(rules).toContain('${snake}_price_non_negative');
 });
 
-unitTest('${name.pascal}View projects the row an action returns, without the tenant', () => {
-  expect(${name.pascal}View.$keys).toEqual(['id', 'title', 'price', 'createdAt']);
+unitTest('${name.pascal}View projects the row an action returns', () => {
+  const keys = ${name.pascal}View.$keys;
+  expect(keys).toEqual([${VIEW_KEYS.join(', ')}]);
   // The org id is the caller's context, never the client's data: a view that leaked it would
   // let a response carry a tenant boundary the policy already decided.
-  expect(${name.pascal}View.$keys).not.toContain('orgId');
+  expect(keys).not.toContain('orgId');
 });
 
-unitTest('${name.camel} invariants reject a blank title and a negative price', () => {
+unitTest('${name.camel} invariants reject blank and negative', () => {
+  const blank = row({ title: '   ' });
+  const negative = row({ price: { minor: -1, currency: 'USD' } });
   expect(() => ${name.camel}.$assert(row())).not.toThrow();
-  expect(() => ${name.camel}.$assert(row({ title: '   ' }))).toThrow();
-  expect(() => ${name.camel}.$assert(row({ price: { minor: -1n, currency: 'USD' } }))).toThrow();
+  expect(() => ${name.camel}.$assert(blank)).toThrow();
+  expect(() => ${name.camel}.$assert(negative)).toThrow();
 });
 
 unitTest('${name.camel} parses a row through its own columns', () => {

package/src/templates/guard.ts

@@ -0,0 +1,143 @@
+// `x g guard <name>` — the app's own convention, scaffolded as a build error. Not a primitive and
+// not a check the framework owns: what the emitted file has to get right is the directory (it is
+// the registration), the exported `guard` the gate looks for, and a rule that fires on something
+// real, so an author replacing the example knows what a working one looks like.
+
+import type { GeneratedFile } from './naming';
+import { kebab } from './naming';
+
+/**
+ * The code the emitted guard raises, derived from its name — the same shape `x g action` derives
+ * `X_<FEATURE>_NOT_FOUND` in. Derived and never written as a literal here for the same reason: an
+ * `X_*` literal in framework source is a framework code, and it would have to be registered and
+ * documented in `wiki/Error-Codes.md`. The app owns the codes its own conventions raise.
+ */
+export const guardCode = (name: string): string =>
+  `X_${kebab(name).toUpperCase().split('-').join('_')}`;
+
+const guardSource = (
+  name: string,
+): string => `// ${name}: one convention this app enforces, as a build error. \`x verify\` discovers every file in
+// \`guards/\` and runs its \`guard\` inside the \`boundaries\` step — nothing registers this file, so
+// nothing can forget to. Replace the rule below with the one this app needs; the shape is the
+// contract, and the findings it returns are what \`--json\` and the exit code are made of.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/**
+ * The example rule, and the class of failure a guard exists for: a migration that adds a NOT NULL
+ * column with no DEFAULT applies cleanly to an empty local database and fails on the first
+ * production table that already holds rows. Nothing else in the gate can see it — \`x verify\`'s
+ * \`drift\` step reads these same files and asks a different question (is every destructive
+ * statement declared?), and a test suite runs against a database this statement has never met.
+ *
+ * The code is this guard's own name: the line an agent reads has to say WHICH convention broke, so
+ * a guard is named after its convention and the two are renamed together.
+ */
+const CODE = '${guardCode(name)}';
+
+/** A column definition begins at \`add column\` and ends at the comma or semicolon after it. */
+const ADD_COLUMN = /add\\s+column\\s+(?:if\\s+not\\s+exists\\s+)?"?([\\w]+)"?([^,;]*)/gi;
+
+export interface MigrationFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly sql: string;
+}
+
+/**
+ * Pure — the caller does the I/O — so the rule is testable without a filesystem, which is the same
+ * split the framework's own checks use. A guard returns findings and nothing else: it never
+ * prints, never throws for a normal result and never decides the exit code.
+ */
+export function unsafeAdditions(files: readonly MigrationFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    // Comments first, block before line: a statement inside \`/* … */\` is a note, and reading one
+    // as real is a finding an author cannot act on — it blocks \`x verify\` over nothing.
+    const sql = file.sql.replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, ' ').replaceAll(/--[^\\n]*/g, ' ');
+    for (const statement of sql.split(';')) {
+      if (!/\\balter\\s+table\\b/i.test(statement)) continue;
+      for (const match of statement.matchAll(ADD_COLUMN)) {
+        const definition = match[2] ?? '';
+        if (!/\\bnot\\s+null\\b/i.test(definition)) continue;
+        // \`DEFAULT NULL\` is a default in syntax and none in effect: every existing row still
+        // takes NULL and still violates NOT NULL, which is this rule's whole subject.
+        const nullDefault = /\\bdefault\\s+\\(?\\s*null\\b/i.test(definition);
+        if (/\\bdefault\\b/i.test(definition) && !nullDefault) continue;
+        const column = match[1] ?? 'the column';
+        findings.push({
+          code: CODE,
+          cause: \`\${file.path} adds \${column} NOT NULL with no usable DEFAULT — every row already in the table takes NULL and violates it the moment this runs against data\`,
+          fix: \`give \${column} a non-null DEFAULT in \${file.path}, then: x db migrate\`,
+          at: file.path,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a migration never adds a NOT NULL column without a DEFAULT',
+  async check(root) {
+    const files: MigrationFile[] = [];
+    for await (const path of new Bun.Glob('packages/db/migrations/*.sql').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      files.push({ path, sql: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return unsafeAdditions(files);
+  },
+};
+`;
+
+const guardTest = (
+  name: string,
+): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { unsafeAdditions } from './${name}';
+
+const migration = (sql: string) => [{ path: 'packages/db/migrations/0002_probe.sql', sql }];
+
+unitTest('a NOT NULL column added with no DEFAULT is refused', () => {
+  const findings = unsafeAdditions(migration('ALTER TABLE posts ADD COLUMN slug text NOT NULL;'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.at).toBe('packages/db/migrations/0002_probe.sql');
+  expect(findings[0]?.cause).toContain('slug');
+});
+
+unitTest('a DEFAULT makes the same addition safe', () => {
+  const sql = "ALTER TABLE posts ADD COLUMN slug text NOT NULL DEFAULT '';";
+  expect(unsafeAdditions(migration(sql))).toHaveLength(0);
+});
+
+unitTest('DEFAULT NULL is a default in syntax and none in effect', () => {
+  const sql = 'ALTER TABLE posts ADD COLUMN slug text NOT NULL DEFAULT NULL;';
+  expect(unsafeAdditions(migration(sql))).toHaveLength(1);
+});
+
+unitTest('a nullable column was always safe, and a new table is not an addition', () => {
+  expect(unsafeAdditions(migration('ALTER TABLE posts ADD COLUMN slug text;'))).toHaveLength(0);
+  expect(unsafeAdditions(migration('CREATE TABLE posts (slug text NOT NULL);'))).toHaveLength(0);
+});
+
+unitTest('a commented-out statement is not a statement', () => {
+  const block = '/* ALTER TABLE posts ADD COLUMN slug text NOT NULL; */';
+  expect(unsafeAdditions(migration(block))).toHaveLength(0);
+  const line = '-- ALTER TABLE posts ADD COLUMN slug text NOT NULL;';
+  expect(unsafeAdditions(migration(line))).toHaveLength(0);
+});
+`;
+
+/** `guards/<name>.ts` and its test. No index, no registry, no manifest row — the directory is it. */
+export function guardFiles(rawName: string): readonly GeneratedFile[] {
+  const name = kebab(rawName);
+  return [
+    { path: `guards/${name}.ts`, contents: guardSource(name) },
+    { path: `guards/${name}.test.ts`, contents: guardTest(name) },
+  ];
+}

package/src/templates/index.ts

@@ -4,11 +4,17 @@
 export type { ActionOptions } from './action';
 export { actionFiles } from './action';
 export { adminFiles } from './admin';
+export type { AdminPageOptions } from './admin-page';
+export { adminPageFiles } from './admin-page';
+export { backfillFiles } from './backfill';
 export type { FeatureTarget } from './entity';
 export { entityFiles } from './entity';
+export { guardCode, guardFiles } from './guard';
+export type { IslandOptions } from './island';
+export { islandFiles } from './island';
 export { jobFiles, taskFiles } from './job';
 export { CATALOG_ROOT, catalogPath, DEFAULT_LOCALES, resolveLocales } from './locales';
-export type { GeneratedFile, NameSet } from './naming';
+export type { GeneratedFile, GeneratedFoundationFile, NameSet } from './naming';
 export { camel, kebab, names, pascal, plural, titleKey } from './naming';
 export { policyFiles } from './policy';
 export type { QueryOptions } from './query';
@@ -18,7 +24,12 @@ export { resourceFiles } from './resource';
 export type { RouteOptions, Surface } from './route';
 export { routeFiles } from './route';
 export { appFiles } from './scaffold-app';
+export { claudeFiles } from './scaffold-claude';
+export { claudeAgentFiles } from './scaffold-claude-agents';
+export { claudeCommandFiles } from './scaffold-claude-commands';
 export { containerFiles } from './scaffold-container';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
 export { i18nIndex } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';
+export type { SliceModule } from './slice-foundation';
+export { sliceFoundation } from './slice-foundation';

package/src/templates/island.ts

@@ -0,0 +1,67 @@
+// `x g island <name>` — the one file on a route that ships JavaScript. Not a ninth primitive and
+// not a component generator: an island is a client ENTRY POINT, so what the scaffold has to get
+// right is the filename (the bundler discovers by it) and the `mount` export (the hydration
+// runtime calls it by name). Both are pinned by the emitted test.
+
+import type { GeneratedFile } from './naming';
+import { kebab, pascal } from './naming';
+
+export interface IslandOptions {
+  /** Directory the entry lands in, app-root-relative and POSIX — normally a route's own folder. */
+  readonly dir: string;
+}
+
+const islandSource = (name: string): string => {
+  const Name = pascal(name);
+  return `// ${Name}: the interactive half of an otherwise static page, and the only module on this
+// route the browser downloads.
+//
+// The page names this file by SPECIFIER, never by import:
+//   const ${Name} = island({ src: './${name}.island.tsx', props: ['label'] });
+// A string has no import edge, so nothing follows one into this file and the page's bundle graph
+// stays the page's (axiom 6). WHEN it wakes is the route's \`hydrate\`, never a declaration here.
+
+/** What the server sends. Declared here AND in the page's \`island({ props })\` — both, or neither. */
+export interface ${Name}Props {
+  /** Already translated: this runs in the browser, where \`t()\`'s catalog is not. */
+  readonly label: string;
+}
+
+/**
+ * The one export the hydration runtime calls — \`import(entry).then((m) => m.mount(el, props))\`.
+ * \`el\` is the wrapper the page rendered, with the server's own markup already inside it, so a
+ * mount that replaces the markup instead of taking it over is a visible flash on every load.
+ */
+export function mount(el: HTMLElement, props: ${Name}Props): void {
+  el.textContent = props.label;
+  el.addEventListener('click', () => {
+    // \`dataset.open\`, not \`dataset['open']\`: the bracket form is lint/complexity/useLiteralKeys,
+    // which the app's own \`biome check\` fails on — twice, in the one file every island copies.
+    el.dataset.open = el.dataset.open === 'true' ? 'false' : 'true';
+  });
+}
+`;
+};
+
+const islandTest = (
+  name: string,
+): string => `// The runtime boots an island by calling \`mount\` on whatever the module exports. A renamed or
+// deleted export is a page that renders, serves, passes every other gate and does nothing when
+// clicked — which is exactly the failure nothing else in the build can see.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import * as entry from './${name}.island';
+
+unitTest('${name}.island exports the mount the hydration runtime calls', () => {
+  expect(typeof entry.mount).toBe('function');
+});
+`;
+
+export function islandFiles(rawName: string, options: IslandOptions): readonly GeneratedFile[] {
+  const name = kebab(rawName);
+  const dir = options.dir.replace(/\/+$/, '');
+  return [
+    { path: `${dir}/${name}.island.tsx`, contents: islandSource(name) },
+    { path: `${dir}/${name}.island.test.ts`, contents: islandTest(name) },
+  ];
+}

package/src/templates/job.ts

@@ -1,10 +1,12 @@
 // `x g job` / `x g task` — durable background work and the cron trigger that enqueues it. The
-// idempotency key is required by the type, so the generator always emits one; the generated test
-// pins it through a real driver, because a key that is not stable is a job that runs twice.
+// idempotency key and the tenant are both required by the type, so the generator always emits
+// both; the generated test pins them through a real driver, because a key that is not stable is a
+// job that runs twice and a tenant that is not declared is a job that reads the wrong org's rows.
 
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { sliceFoundation } from './slice-foundation';
 
 const jobSource = (
   name: NameSet,
@@ -16,7 +18,14 @@ import { job, t } from '@ultimat3/jobs';
 import * as repo from '../repo';
 
 export const ${name.camel} = job({
-  input: t.object({ id: t.uuid }),
+  input: t.object({ id: t.uuid, orgId: t.uuid }),
+  // The org this run's body acts as, derived from the job's OWN input — never from whoever
+  // enqueued it, who may have changed orgs by the time a retried job settles. \`orgId\` is in the
+  // input for this and no other reason: \`x g entity\` scaffolds \`tenant: 'orgId'\`, so every read
+  // below is tenant-scoped. \`tenant: 'none'\` is the other spelling and it STRIPS the org, which
+  // makes a tenant-scoped read fail closed with X_TENANCY_ACTOR_ORG_REQUIRED — use it only for a
+  // job that touches no tenanted table.
+  tenant: (input) => input.orgId,
   idempotencyKey: ({ id }) => \`${name.kebab}:\${id}\`,
   retry: { attempts: 5, backoff: 'exponential' },
   async run({ input, step }) {
@@ -42,17 +51,34 @@ import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
 export const ${name.camel} = task({
   cron: '0 3 * * *',
   tz: 'UTC',
-  enqueue: () => [[${jobName.camel}, { id: '00000000-0000-4000-8000-000000000001' }]],
+  // The org rides in the payload because the job DECLARES its tenant from its own input: a task
+  // has no request behind it, so there is no caller whose org could be read instead.
+  enqueue: () => [
+    [
+      ${jobName.camel},
+      {
+        id: '00000000-0000-4000-8000-000000000001',
+        orgId: '00000000-0000-4000-8000-000000000002',
+      },
+    ],
+  ],
 });
 `;
 
 const jobTest = (
   name: NameSet,
-): string => `import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+): string => `// ${name.camel} against a real driver: enqueue, drain, assert. Retries and the dead-letter path
+// are the framework's, so what this pins is that THIS job's steps run and are idempotent.
+import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
 import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
 import { ${name.camel} } from './${name.kebab}';
 
 const id = '00000000-0000-4000-8000-000000000001';
+const orgId = '00000000-0000-4000-8000-000000000002';
+const input = { id, orgId };
+// The key this job owes, spelled once. Named rather than inlined so the assertion below carries
+// the job's own name and still fits the formatter width the app's \`lint\` step enforces.
+const expectedKey = \`${name.kebab}:\${id}\`;
 
 // 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.
@@ -61,14 +87,22 @@ beforeAll(() => {
 });
 afterAll(resetJobDriver);
 
-jobTest('${name.camel} declares an idempotency key and a retry policy', () => {
+jobTest('${name.camel} declares a key and a retry policy', () => {
   expect(${name.camel}.kind).toBe('job');
-  expect(${name.camel}.idempotencyKeyFor({ id })).toBe(\`${name.kebab}:\${id}\`);
+  expect(${name.camel}.idempotencyKeyFor(input)).toBe(expectedKey);
   expect(${name.camel}.retry.attempts).toBeGreaterThan(1);
 });
 
 jobTest('${name.camel} derives the same key for the same input', () => {
-  expect(${name.camel}.idempotencyKeyFor({ id })).toBe(${name.camel}.idempotencyKeyFor({ id }));
+  const key = ${name.camel}.idempotencyKeyFor(input);
+  expect(${name.camel}.idempotencyKeyFor(input)).toBe(key);
+});
+
+jobTest('${name.camel} runs as the org its own input names', () => {
+  // Not a formality: \`tenant: 'none'\` compiles just as well and strips the org, and every read in
+  // this job is tenant-scoped — so this declaration is the whole of what stands between the body
+  // and X_TENANCY_ACTOR_ORG_REQUIRED, or worse, another org's rows.
+  expect(${name.camel}.tenantFor(input)).toBe(orgId);
 });
 
 jobTest('${name.camel} projects itself into the manifest', () => {
@@ -80,9 +114,9 @@ jobTest('${name.camel} projects itself into the manifest', () => {
 jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
   // The whole point of the key: an at-least-once caller may enqueue twice and the work still
   // happens once. \`.enqueue()\` is the one queue path — a job is never run inline.
-  const first = await ${name.camel}.enqueue({ id });
+  const first = await ${name.camel}.enqueue(input);
   expect(first.deduped).toBe(false);
-  const again = await ${name.camel}.enqueue({ id });
+  const again = await ${name.camel}.enqueue(input);
   expect(again.deduped).toBe(true);
 });
 `;
@@ -90,7 +124,9 @@ jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
 const taskTest = (
   name: NameSet,
   jobName: NameSet,
-): string => `import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+): string => `// ${name.camel}: the schedule it declares, the timezone it declares it in, and the job it
+// enqueues. A cron with no explicit IANA zone fires at a different hour twice a year.
+import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
 import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
 import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
 import { ${name.camel} } from './${name.kebab}';
@@ -106,7 +142,7 @@ jobTest('${name.camel} declares a cron with an explicit time zone', () => {
   expect(${name.camel}.tz).toBe('UTC');
 });
 
-jobTest('${name.camel} enqueues ${jobName.camel} and nothing else', () => {
+jobTest('${name.camel} enqueues exactly one job', () => {
   const pairs = ${name.camel}.entries();
   expect(pairs).toHaveLength(1);
   expect(pairs[0]?.[0]).toBe(${jobName.camel});
@@ -118,7 +154,7 @@ jobTest('${name.camel} describes its schedule and its jobs', () => {
   expect(described.jobs).toHaveLength(1);
 });
 
-jobTest('${name.camel} fires its entries onto the same queue the scheduler would', async () => {
+jobTest('${name.camel} fires its declared entries', async () => {
   // \`.enqueue()\` is the backfill path: the declared entries, through the facade a job handle
   // uses, with no scheduler and no leader involved.
   const results = await ${name.camel}.enqueue();
@@ -131,6 +167,10 @@ export function jobFiles(rawName: string, target: FeatureTarget): readonly Gener
   const name = names(rawName);
   const dir = `${target.surfaceDir}/${target.feature}/jobs`;
   return [
+    // The job's steps read through `../repo`, which carries `../entity` for its row type. No
+    // policy: a job has no request behind it and evaluates none, so a generated one would be a
+    // file nobody asked for. `x g task` inherits this by composing `jobFiles` below.
+    ...sliceFoundation(target, ['entity']),
     { path: `${dir}/${name.kebab}.ts`, contents: jobSource(name) },
     { path: `${dir}/${name.kebab}.test.ts`, contents: jobTest(name) },
   ];

package/src/templates/naming.ts

@@ -27,13 +27,29 @@ export interface GeneratedSourceFile {
   readonly merge?: undefined;
 }
 
+/**
+ * A module the feature slice owns and no single generator does — `entity.ts`, `repo.ts`,
+ * `policy.ts`, `errors.ts`. Several generators import one and none of them wrote it, so `x g job`
+ * into a slice that has no `repo.ts` emitted an import against nothing. Emitting it as an ordinary
+ * file is the opposite failure: the copy on disk is the author's, and rewriting it (or reporting
+ * `X_GENERATE_CONFLICT` and abandoning the whole set) is how `x g action` into an existing slice
+ * stops working. `'if-absent'` is the third answer — written when the slice lacks it, left exactly
+ * as it is when the slice has it, `--force` included, and never a conflict either way.
+ */
+export interface GeneratedFoundationFile {
+  /** POSIX path relative to the app root. */
+  readonly path: string;
+  readonly contents: string;
+  readonly merge: 'if-absent';
+}
+
 /**
  * Split on `merge` rather than widening one shape's `contents` in place, so the split is
  * load-bearing, not cosmetic: a `merge: 'json'` file's `contents` stays a plain `string` at the
  * type level, which is what stops a byte-carrying file from ever reaching
  * `cmd-generate.ts`'s JSON parser — the compiler refuses the call before the code can run.
  */
-export type GeneratedFile = GeneratedJsonFile | GeneratedSourceFile;
+export type GeneratedFile = GeneratedJsonFile | GeneratedSourceFile | GeneratedFoundationFile;
 
 const words = (input: string): readonly string[] =>
   input