@ultimat3/cli 30.6.0 → 30.7.0

package/src/generate-follow-ups.ts

@@ -1,12 +1,14 @@
 // Everything `x g` edits OUTSIDE the files it creates, in the one order they have to happen: a
 // declared permission granted to a role, a primitive listed in `defineApi`, an entity added to the
-// typed handle, an `--admin` override wired, each new workspace edge declared, and every catalog
-// made selectable. One function over one disk seam, so a real run and a dry run are the same code
+// typed handle, an `--admin` override wired, a contract test's exercise entry declared, each new
+// workspace edge declared, and every catalog made selectable. One function over one disk seam, so a real run and a dry run are the same code
 // — and the dry run's list of touched files is what the run touches, not a second guess at it.
 
 import { registerAdminResources } from './admin-registration';
 import { registerGeneratedPrimitives } from './api-registration';
+import type { ExerciseEntry } from './exercise-entry-edit';
 import type { GenerateDisk } from './generate-disk';
+import { declareGeneratedExercises } from './generate-exercise';
 import { ungrantedByGenerator } from './generate-grant-findings';
 import { grantGeneratedPermissions } from './generate-grants';
 import { declareGeneratedImports } from './generated-imports';
@@ -33,11 +35,15 @@ export async function followUpEdits(
   written: readonly string[],
   dbModule: string | undefined,
   disk: GenerateDisk,
+  /** The written contract tests' entries, declared in `apps/web/exercise.ts` (`generate-exercise.ts`). */
+  exercises: readonly ExerciseEntry[] = [],
 ): Promise<FollowUps> {
   const handle = await registerGeneratedEntities(root, written, dbModule, disk);
   const adminWiring = await registerAdminResources(root, written, disk);
   const granted = await grantGeneratedPermissions(root, written, disk);
   const listed = await registerGeneratedPrimitives(root, written, disk);
+  // Before the manifests: the entry may bring an import (`userActor`) into the exercise file.
+  const exercise = await declareGeneratedExercises(exercises, disk);
   // Last of the manifest writers, because the others add imports too: every sibling workspace a
   // written file imports, declared in the manifest it landed under.
   const imports = await declareGeneratedImports(root, written, disk);
@@ -53,12 +59,19 @@ export async function followUpEdits(
       ...new Set([
         ...granted,
         ...listed,
+        ...exercise.edited,
         ...handle.edited,
         ...adminWiring.edited,
         ...imports,
         ...(indexSync.edited ?? []),
       ]),
     ].filter((path) => !written.includes(path)),
-    findings: [...handle.findings, ...ungranted, ...adminWiring.findings, ...indexSync.findings],
+    findings: [
+      ...handle.findings,
+      ...ungranted,
+      ...adminWiring.findings,
+      ...exercise.findings,
+      ...indexSync.findings,
+    ],
   };
 }

package/src/mcp-errors.ts

@@ -392,6 +392,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --only boundaries --json   # names the file; end its mount() with return render(() => <Island {...props} />, el)',
   X_SOCKET_HAND_ROLLED:
     'x verify --only boundaries --json — names the file and line; delete the upgrade and declare the socket with deviceSocket({ path, resolveToken, onFrame }) from @ultimat3/realtime/server',
+  X_EXERCISE_FILE_UNEDITABLE:
+    'edit apps/web/exercise.ts — paste the entry the finding names into export const exercise = defineExercise({ … })',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/messages.ts

@@ -103,6 +103,8 @@ const CATALOG = {
   'cli.exercise.none': 'this app registers no action, query or job: nothing to exercise',
   'cli.exercise.summary':
     '{total} primitive(s): {reached} reached, {refused} refused, {off} off, {unreached} unreached — {file}',
+  'cli.exercise.phases': 'took {total} ms — {phases} — slowest: {slowest}',
+  'cli.exercise.slowest': 'slowest: {primitive} · {proof} {ms} ms',
   // One rendering of "this file was written", for every command that writes files — `x g`, its
   // own `--dry-run`, and `x new`. Three copies of the same two characters is how a fourth writer
   // arrives with a fifth marker; `--json` carries the paths themselves in `data.files`.

package/src/templates/action-exercise.ts

@@ -0,0 +1,71 @@
+// A generated action's ONE exercise declaration: its entry in `apps/web/exercise.ts`, which `x g`
+// inserts (`exercise-entry-edit.ts`) and both runners read — the contract test hands that file's
+// export to `.contract({ exercise })`, and `x exercise` re-homes the actor into each tenant it seeds.
+
+import type { ExerciseEntry } from '../exercise-entry-edit';
+
+const ORG = '00000000-0000-4000-8000-000000000002';
+
+/**
+ * `../../../exercise` from a directory under the app root (`apps/web/app/post/actions`). Counted
+ * off the shared `apps/web/` prefix, which every generated surface sits under.
+ */
+export function exerciseImportFrom(dir: string): string {
+  const prefix = 'apps/web/';
+  const depth = dir.startsWith(prefix) ? dir.slice(prefix.length).split('/').length : 0;
+  return depth === 0 ? './exercise' : `${'../'.repeat(depth)}exercise`;
+}
+
+/** The import line a contract test reads the declarations with. */
+export const exerciseImportLine = (dir: string): string =>
+  `import { exercise } from '${exerciseImportFrom(dir)}';`;
+
+/**
+ * Who the generated-input runs act as: a member holding the slice's grant, in the org every draw
+ * is bound to when the policy compares orgs. A grant that cannot be read is the author's to name,
+ * so the entry turns the exercise off and says what to write instead. Printed expanded at every
+ * level, the shape Biome keeps for an object written over several lines.
+ */
+export function actionExerciseEntry(
+  name: string,
+  grant: string | undefined,
+  orgRule: boolean,
+  feature: string,
+): ExerciseEntry {
+  if (grant === undefined) {
+    return {
+      name,
+      value: `{\n  off: '${feature}/policy.ts names no one grant: give { actor } holding what it checks',\n}`,
+    };
+  }
+  return memberEntry(name, grant, orgRule ? { org: ORG, bindsInput: true } : {});
+}
+
+/**
+ * A member holding `grant`; in `org` when given, and with every draw's `orgId` bound to it when
+ * `bindsInput` — an action whose input names no org (a create that writes under the actor's) gets
+ * the actor's org alone.
+ */
+export function memberEntry(
+  name: string,
+  grant: string,
+  where: { readonly org?: string; readonly bindsInput?: boolean },
+): ExerciseEntry {
+  const { org } = where;
+  const actor = [
+    'actor: userActor({',
+    "  id: 'member',",
+    ...(org === undefined ? [] : [`  orgId: '${org}',`]),
+    `  permissions: ['${grant}'],`,
+    '}),',
+  ];
+  const input =
+    org === undefined || where.bindsInput !== true
+      ? []
+      : [`input: (drawn) => ({ ...drawn, orgId: '${org}' }),`];
+  return {
+    name,
+    value: `{\n${[...actor, ...input].map((line) => `  ${line}`).join('\n')}\n}`,
+    imports: [{ name: 'userActor', from: '@ultimat3/core' }],
+  };
+}

package/src/templates/action-tests.ts

@@ -44,10 +44,12 @@ const preamble = (
   isMutator: boolean,
   wrappers: string,
   outsider: boolean,
-  /** `testActor` is imported for the outsider, or for a contract suite's exercise actor. */
+  /** `testActor` is imported for the outsider. */
   importsActor = outsider,
+  /** A contract suite's import of `apps/web/exercise.ts`, the one home of its exercise. */
+  exerciseImport?: string,
 ): string => `${importsActor ? "import { testActor } from '@ultimat3/policy';\n" : ''}import { ${wrappers} } from '@ultimat3/testing';
-import { ${name.camel} } from './${name.kebab}';
+${exerciseImport === undefined ? '' : `${exerciseImport}\n`}import { ${name.camel} } from './${name.kebab}';
 ${
   outsider
     ? `
@@ -233,33 +235,6 @@ unitTest('${name.camel} rejects input that is not a uuid', async () => {
 ${shape.isMutator ? localTwinTests() : ''}${handlerTests(feature, shape)}`;
 };
 
-/**
- * Who the generated-input runs act as: an actor holding the slice's grant — `<feature>:write` for
- * the policy this generator wrote, the one literal `can('<perm>')` of a handwritten one — in the
- * input's org when the rule compares orgs. A grant that cannot be read is the author's to name,
- * so those runs are skipped out loud instead.
- */
-const exerciseActor = (grant: string | undefined, orgRule: boolean): string =>
-  grant === undefined
-    ? ''
-    : `
-// Holds the grant${orgRule ? ', in the org every generated input is bound to' : ''}: the actor the handler runs as when \`.contract()\`
-// calls it with generated legal input.
-const member = testActor('member', {${orgRule ? '\n  orgId,' : ''}
-  permissions: ['${grant}'],
-}).actor;
-`;
-
-/** The `.contract()` argument: the actor and, under an org rule, the org every draw is bound to. */
-const exerciseOption = (grant: string | undefined, orgRule: boolean): string => {
-  if (grant === undefined) {
-    return "{\n    exercise: { off: '../policy.ts names no one grant: pass { actor } holding what it checks' },\n  }";
-  }
-  return orgRule
-    ? '{\n    exercise: { actor: member, input: (drawn) => ({ ...(drawn as object), orgId }) },\n  }'
-    : '{ exercise: { actor: member } }';
-};
-
 export const actionContractTest = (
   name: NameSet,
   feature: NameSet,
@@ -268,16 +243,17 @@ export const actionContractTest = (
   scaffoldPolicy = true,
   /** That policy holds an org rule: false for a slice whose entity names no tenant. */
   orgRule = scaffoldPolicy,
-  /** The permission the exercise actor holds; `undefined` when the policy's grant cannot be read. */
-  grant: string | undefined = scaffoldPolicy ? `${feature.kebab}:write` : undefined,
+  /** The line importing `apps/web/exercise.ts`'s export, relative to this test (`action-exercise.ts`). */
+  exerciseImport = "import { exercise } from '../../../exercise';",
 ): 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', orgRule, orgRule || grant !== undefined)}${exerciseActor(grant, orgRule)}
+${preamble(name, feature, isMutator, 'contractTest, expect', orgRule, orgRule, exerciseImport)}
 contractTest('${name.camel} passes the action contract', async () => {
   // Four assertions the framework makes for any action, without knowing what this one does:
   // garbage input is rejected, an anonymous actor is denied, the operation reaches the OpenAPI
-  // document, and the handler survives 16 generated legal inputs, each rolled back.
-  for (const contract of target.contract(${exerciseOption(grant, orgRule)})) {
+  // document, and the handler survives 16 generated legal inputs, each rolled back — run as its
+  // entry in apps/web/exercise.ts declares, the same entry \`x exercise\` runs.
+  for (const contract of target.contract({ exercise })) {
     await contract.run();
   }
 });

package/src/templates/action.ts

@@ -3,6 +3,7 @@
 // job handle, an MCP tool and these tests; the generator writes the declaration and the tests.
 
 import { SlicePolicyIncompleteError } from '../generate-slice-policy';
+import { actionExerciseEntry, exerciseImportLine } from './action-exercise';
 import { actionContractTest, actionUnitTest } from './action-tests';
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
@@ -194,6 +195,8 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
       : grantOf(target.slicePolicy, `can${feature.pascal}Write`);
   const org =
     !singleTenant || (target.slicePolicy !== undefined && policyReadsOrg(target.slicePolicy));
+  // The org rule the contract can rely on: the one this generator's own policy writes.
+  const orgRule = target.slicePolicy === undefined && !singleTenant;
   // Before a file is planned: a generated action that does not compile is refused, never written.
   assertPolicyExports(target, feature, isMutator);
   const lookup =
@@ -247,10 +250,12 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
         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,
+        orgRule,
+        exerciseImportLine(dir),
       ),
+      // Who its handler runs as, declared once in apps/web/exercise.ts — the file this test reads
+      // and `x exercise` reads. A hand-written policy's one literal grant: an actor holding it.
+      exercise: actionExerciseEntry(name.camel, grant, orgRule, target.feature),
     },
   ];
 }

package/src/templates/naming.ts

@@ -1,6 +1,8 @@
 // Name derivation for generators. One place, because `x g resource post` has to agree with itself
 // across eight emitted files — a second casing helper is how `Post`/`post`/`posts` drift apart.
 
+import type { ExerciseEntry } from '../exercise-entry-edit';
+
 /**
  * A catalog is one file per locale that many generators contribute keys to; a whole-file write
  * would delete every key already in it, so a `'json'` file merges instead of overwriting. Always
@@ -30,6 +32,11 @@ export interface GeneratedSourceFile {
    * then the target's own text: the copy `write-generated.ts` writes where the OS refuses a link.
    */
   readonly link?: string;
+  /**
+   * The primitive's entry in `apps/web/exercise.ts`, for the contract test that reads it: the run
+   * that writes this file inserts it there (`generate-exercise.ts`), never the file itself.
+   */
+  readonly exercise?: ExerciseEntry;
 }
 
 /**

package/src/templates/resource-create.ts

@@ -3,6 +3,7 @@
 // input was `{ id, orgId }` while the form posted `{ title }`. The input is the entity's own view of
 // the columns a caller supplies; the org comes from the actor, never from the body.
 
+import { exerciseImportLine, memberEntry } from './action-exercise';
 import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
@@ -119,10 +120,13 @@ unitTest('orgOf answers the org of the actor, and refuses an actor with none', (
 
 const createContractTest = (
   feature: NameSet,
+  /** The line importing `apps/web/exercise.ts`'s export, relative to this test. */
+  exerciseImport: string,
 ): string => `// create${feature.pascal}: the contract every action owes, and the orgless actor it denies before
 // the handler runs — the org a row is written under is the actor's, so an actor with none is refused.
 import { testActor } from '@ultimat3/policy';
 import { contractTest, expect } from '@ultimat3/testing';
+${exerciseImport}
 import { create${feature.pascal} } from './create-${feature.kebab}';
 
 const target = create${feature.pascal}.named('create${feature.pascal}');
@@ -137,9 +141,9 @@ const writer = testActor('writer', {
 }).actor;
 
 contractTest('create${feature.pascal} passes the action contract', async () => {
-  // The fourth assertion runs the handler as the writer on 16 generated legal inputs, each
-  // inside a transaction that rolls back, so nothing it creates outlives the test.
-  for (const contract of target.contract({ exercise: { actor: writer } })) await contract.run();
+  // The fourth assertion runs the handler on 16 generated legal inputs, each inside a transaction
+  // that rolls back, as its entry in apps/web/exercise.ts declares — the one \`x exercise\` runs.
+  for (const contract of target.contract({ exercise })) await contract.run();
 });
 
 contractTest('create${feature.pascal} needs an actor with an org', async () => {
@@ -167,7 +171,9 @@ export function resourceCreateFiles(
     { path: `${dir}/create-${feature.kebab}.test.ts`, contents: createUnitTest(feature, dbModule) },
     {
       path: `${dir}/create-${feature.kebab}.contract.test.ts`,
-      contents: createContractTest(feature),
+      contents: createContractTest(feature, exerciseImportLine(dir)),
+      // A writer in one org: the create writes under the actor's org, so no input names one.
+      exercise: memberEntry(`create${feature.pascal}`, `${feature.kebab}:write`, { org: ORG }),
     },
   ];
 }

package/src/templates/scaffold-auth.ts

@@ -27,6 +27,7 @@ const devActor = (
 //
 // Delete it the day sign-in exists, and the fallback line in \`authenticator.ts\` with it.
 import { type Actor, logger, readCookie } from '@ultimat3/core';
+import { seedId } from '@ultimat3/entity';
 import { DEMO_ORG_ID } from '../../shared/demo-org';
 import { roles } from '../../shared/roles';
 
@@ -56,13 +57,20 @@ export const devRoleFrom = (cookieHeader: string | null): string | undefined =>
   return Object.hasOwn(roles, named) ? named : undefined;
 };
 
+/**
+ * The viewer's user id for \`role\`: a uuid, as \`ctx.actor.id\` is on every real request (an
+ * \`x_users\` key) — a name here was \`22P02 invalid input syntax for type uuid\` the first time a
+ * handler looked its caller up. \`seedId\`, so a seed's id('user:dev:<role>') is this very user.
+ */
+export const devActorId = (role: string): string => seedId(\`user:dev:\${role}\`);
+
 /**
  * \`roles\`, never a permission list: \`can()\` expands the role map at decision time, so a grant
  * moved between roles reaches this actor without an edit here.
  */
 export const devActorFor = (role: string): Actor => ({
   kind: 'user',
-  id: 'dev-actor',
+  id: devActorId(role),
   // The seed's org, never an invented string: a generated tenant policy compares it with a uuid.
   orgId: DEMO_ORG_ID,
   roles: [role],
@@ -230,6 +238,14 @@ unitTest('a cookie naming an undeclared role is never the default viewer', () =>
   }
 });
 
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+unitTest('the viewer is a user: a uuid id, one per role', () => {
+  // An app reads \`ctx.actor.id\` as an \`x_users\` key; a name in it fails the uuid cast.
+  for (const role of declaredDevRoles()) expect(devActorFor(role).id).toMatch(UUID);
+  expect(devActorFor('admin').id).not.toBe(devActorFor('member').id);
+});
+
 unitTest('the actor it mints holds what the role map grants it, and nothing else', () => {
   // \`actorHas\` and not \`holds\`: this is the function \`can()\` itself calls, so the assertion is
   // the pipeline's own decision rather than a second implementation of it. The map is passed

package/src/templates/scaffold-exercise.ts

@@ -7,7 +7,8 @@ const exercise =
   (): string => `// What \`x exercise\` cannot guess about this app: an input a primitive needs bound to a real
 // row, an actor its policy permits, or a primitive that must not run in the pass and why. Empty
 // runs every action, query and job as generated. \`x exercise --json\` prints the entry to paste
-// for each one it could not reach; each value is the \`exercise\` option \`.contract()\` takes.
+// for each one it could not reach. A contract test reads the same entry:
+// \`target.contract({ exercise })\`, handed this file's export.
 import { defineExercise } from '@ultimat3/testing';
 
 export const exercise = defineExercise({});

package/wiki/Actions.md

@@ -144,7 +144,7 @@ Every projection needs the name `registerActions()` stamps on. It names the expo
 | 3 | **Typed client function** | `input` + `output` | one map-wide client, `export const client = rpc<Api['actions']>({ baseUrl })`, then `await client.publishPost({ postId })` in `app/`; or `publishPost.client({ baseUrl })` for a single method. `rpc` is the only name for the map-wide client — no `createClient` alias, no fetch, no codegen step to remember. `x new` writes it as `apps/web/shared/browser-client.ts` (`browserClient`, beside `browserQueries`); it typechecks at any app size (pinned at 300 actions in 100 modules). **`rpc` and `queryClient` do not reach a mount**: under `baseUrl: '…/v1'` they derive `/v1/api/…` and a valid token answers 404. A machine caller uses the mount's OpenAPI document |
 | 4 | **Job handle** | the whole declaration | `publishPost.job()` — a namespaced name, an `idempotencyKey` from the payload, and an `invoke` that runs the same handler durably. Register it with the queue; `.enqueue()` belongs to a declared `job` |
 | 5 | **MCP tool** | `mcp` + `input` + `policy` | `toolFrom(publishPost)` from `@ultimat3/mcp` — one tool named `publishPost` per exposed action, exactly the `tools/list` entry, JSON Schema from `input`, every call through this action's `invoke` (authz unchanged) |
-| 6 | **Test** | `input` + `policy` + `handle` | `publishPost.contract({ exercise: { actor } })` — schema round-trip, a denial test per policy branch, and the handler on generated legal input, generated green, not as a `TODO` |
+| 6 | **Test** | `input` + `policy` + `handle` | `publishPost.contract({ exercise })`, handed `apps/web/exercise.ts`'s export, where `x g` declares its entry — schema round-trip, a denial test per policy branch, and the handler on generated legal input, generated green, not as a `TODO` |
 
 **A client for code that cannot import the app.** `rpc` needs the app's action types, so a customer's TypeScript never had one. `x client customer --out <dir>` compiles the committed `openapi.json` (or a bearer mount's own document, `--mount /v1`) into `index.ts` + `types.ts` with no import beyond the platform: `createClient({ baseUrl, headers })`, one method per `operationId`, a non-2xx as `ProblemError`, and `refusalOf(error, 'publishPost')` narrowing to the codes that operation declares under `errors:`. The calling direction is `x client vendor <name>` — `outbound()` and `t` schemas from a third party's document. One compiler for both, never a second way: [CLI reference](CLI-Reference#x-client). `As of 2026-11`.
 

package/wiki/CLI-Reference.md

@@ -356,7 +356,7 @@ is a word (`a-z`, `0-9`, `-`, `_`) or `[param]` / `[...rest]`; `..`, `.` and emp
 | `--force` | boolean | `false` | overwrite existing files |
 | `--dry-run` | boolean | `false` | the write plan, nothing written: **every file the run would touch** — the ones it creates (a slice module already on disk is skipped, not listed) and, `As of 27.6.2`, the ones it EDITS outside the slice (role map, typed handle, API index, manifests, catalogs, the i18n index), in the order the run lists them. `--json`: `data.files` is that list, `data.edits` the subset that already exists, `data.refreshes` the committed contracts (`x.manifest.json`, `openapi.json`) a real run re-projects. `ok: false` with every finding the real run would report — an existing file, an API-index binding already held, a grant or a handle entry it cannot place |
 
-`resource` emits the whole slice — `entity`, `repo`, `policy`, `errors`, `service`, `actions`, `live`, `jobs`, `ui`, the form island, the plural route and a test beside each declaration — **37 files** on a dry run in an app scaffolded with its example slice, 39 on the real run after `bun run setup` (`x.manifest.json` and `openapi.json` re-projected; 40 dry with `--admin`) — and `x g resource` in a `--no-example` app, which also gains two `package.json` edits, writes 39 and 41 files (42 and 44 with `--admin`; `--live` is refused — a resource already ships a live query, and the flag belongs to `x g query`: `X_CLI_BAD_FLAG`, fix `x g query <name>-feed --feature <name> --live`), and **no migration**: `x db gen` is the only writer of `packages/db/migrations`, so a new slice is `x g resource <name>`, then `x db gen "create <table>"`, then `x db migrate`, then `x build --target static && x verify --only budgets` — the four commands the run prints, in that order (`data.next` under `--json`). **The plural route is reachable as written**, `As of 2026-10-01`: its `load` reads the list through the slice's query as the request's actor (no org in the URL), `AsyncRegion` renders ready, empty and refused, the form island is mounted, and the route declares `policy: { permission: '<name>:read' }`. Its `budget.js` is MEASURED on `x new`'s app (58,522 B, Bun 1.4.0) and carries the `measured:` / `why:` comment `bun run budget-raises` reads; an app that charges more to every document — `navigation: { client: [...] }` adds its router — is over it on the printed build, and the raise is that edit. The page sits in `apps/web/shared/shell.tsx` when the app has one. `backfill` emits a `backfill()` declaration with its `source()` and `handle()` to fill in — see [Migrations and backfills](Migrations-And-Backfills). **`x g query` and `x g backfill` read a table and never create one**, `As of 2026-11-02`: both name a slice holding an `entity.ts`, by `--feature <slice>` or by a name that is one, and neither finding it is `X_FEATURE_REQUIRED`, zero files written, its fix the closest slice's `--feature` line or `x g resource <name>`. `x g resource` and `x g entity` are what create a table. Every generator produces code that passes `x verify` unmodified, and writes it through the app's own Biome when the app has one: `node_modules/.bin/biome` over the TypeScript files that run created, best effort, never a failed `x g`. A slice whose `entity.ts` declares another table under its name gets no foundation from `x g action`/`x g mutator`, and `x g query` there is `X_QUERY_SLICE_ENTITY`. Errors: `X_GENERATE_CONFLICT`, `X_DB_HANDLE_UNREGISTERED`, `X_FEATURE_UNKNOWN`, `X_FEATURE_REQUIRED`, `X_QUERY_SLICE_ENTITY`.
+`resource` emits the whole slice — `entity`, `repo`, `policy`, `errors`, `service`, `actions`, `live`, `jobs`, `ui`, the form island, the plural route and a test beside each declaration — **38 files** on a dry run in an app scaffolded with its example slice, 40 on the real run after `bun run setup` (`x.manifest.json` and `openapi.json` re-projected; 41 dry with `--admin`) — and `x g resource` in a `--no-example` app, which also gains two `package.json` edits, writes 40 and 42 files (43 and 45 with `--admin`; `--live` is refused — a resource already ships a live query, and the flag belongs to `x g query`: `X_CLI_BAD_FLAG`, fix `x g query <name>-feed --feature <name> --live`), and **no migration**: `x db gen` is the only writer of `packages/db/migrations`, so a new slice is `x g resource <name>`, then `x db gen "create <table>"`, then `x db migrate`, then `x build --target static && x verify --only budgets` — the four commands the run prints, in that order (`data.next` under `--json`). **The plural route is reachable as written**, `As of 2026-10-01`: its `load` reads the list through the slice's query as the request's actor (no org in the URL), `AsyncRegion` renders ready, empty and refused, the form island is mounted, and the route declares `policy: { permission: '<name>:read' }`. Its `budget.js` is MEASURED on `x new`'s app (58,522 B, Bun 1.4.0) and carries the `measured:` / `why:` comment `bun run budget-raises` reads; an app that charges more to every document — `navigation: { client: [...] }` adds its router — is over it on the printed build, and the raise is that edit. The page sits in `apps/web/shared/shell.tsx` when the app has one. `backfill` emits a `backfill()` declaration with its `source()` and `handle()` to fill in — see [Migrations and backfills](Migrations-And-Backfills). **`x g query` and `x g backfill` read a table and never create one**, `As of 2026-11-02`: both name a slice holding an `entity.ts`, by `--feature <slice>` or by a name that is one, and neither finding it is `X_FEATURE_REQUIRED`, zero files written, its fix the closest slice's `--feature` line or `x g resource <name>`. `x g resource` and `x g entity` are what create a table. Every generator produces code that passes `x verify` unmodified, and writes it through the app's own Biome when the app has one: `node_modules/.bin/biome` over the TypeScript files that run created, best effort, never a failed `x g`. A slice whose `entity.ts` declares another table under its name gets no foundation from `x g action`/`x g mutator`, and `x g query` there is `X_QUERY_SLICE_ENTITY`. A written contract test reads its exercise from `apps/web/exercise.ts` (`target.contract({ exercise })`), and the same run inserts its entry there — once, the file created from `x new`'s when absent, `As of 2026-11-08`; a file that is not one `export const exercise = defineExercise({ … })` is `X_EXERCISE_FILE_UNEDITABLE`, the entry to paste in its `fix:`. Errors: `X_GENERATE_CONFLICT`, `X_DB_HANDLE_UNREGISTERED`, `X_FEATURE_UNKNOWN`, `X_FEATURE_REQUIRED`, `X_QUERY_SLICE_ENTITY`, `X_EXERCISE_FILE_UNEDITABLE`.
 
 **A name the templates would mangle is `X_CLI_BAD_FLAG` before anything is planned**, each with a `fix:` that runs: a reserved word or a leading digit; a letter outside ASCII (`Über` → `x g entity uber` — it was dropped to `ber`); an already-plural `resource`/`entity` name (`posts` → `x g resource post` — it became `entity('postses')`); and a name whose type spelling an emitted file also uses as a global or local type (`promise`, `omit`, `partial`, `row` → `x g resource promise-resource`).
 

package/wiki/Policies-And-Authz.md

@@ -168,14 +168,15 @@ gate's `exercise` step, around each primitive's own call: B, then A, then B agai
 
 ```
 X_TENANT_LEAK: another tenant's row reached a call's output or effect
-  cause: action readAttachment, called by tenant B with tenant A's ids before A ran, handed back A's seeded data at output.url: …
-  fix:   x exercise readAttachment --json — then read the row behind output.url through the repository scoped to ctx.actor, never by the input id alone
+  cause: action readAttachment, called by tenant B with A's own input before A ran, handed back A's seeded data at output.url: …
+  fix:   x exercise readAttachment --json — then read the row behind output.url through the repository scoped to ctx.actor, never by the input id alone, nor by an unscoped statement
 ```
 
 | Not a failure | Why |
 |---|---|
 | `public` | the policy admits an anonymous caller: what it returns, anyone may read. The read half is skipped; a crossed **write** is still red |
 | `public`, as a declared sweep | a job that reads every org on purpose says so with `crossTenant(reason, fn)`, and its input names no org's rows. The proof sees the scope and quotes the reason; the read half is skipped, a crossed **write** is still red. The same scope in an action or a query, or in a job handed A's id, is still `X_TENANT_LEAK` |
+| `public`, as a tenantless job | a job declaring `tenant: 'none'` whose input names none of A's rows — a nightly cleanup across every org, input `{ occurrenceMs }`. No org and no id of B's choosing reaches its run, so B's run is A's run: what it writes it writes for every enqueuer. The **write** half is skipped, the read half kept. Handed one of A's ids it is crossed as ever; an action or a query handed no id still crosses, since B's org runs it |
 | `unproven` | A's own call was not reached (that record is already red as `X_CONTRACT_EXERCISE_UNREACHED`), or a query answered A none of A's rows — B's empty answer then proves nothing |
 
 B holds the role A held, minus `tenancy:cross`. **Not checked**: a `route` `load` and a `task`

package/wiki/Testing.md

@@ -609,7 +609,7 @@ Enforced through it, keyed or not: `concurrency` and `whenBusy` — each pass is
 
 | Call | Runs | Answers |
 |---|---|---|
-| `crashProof(job, input)` | one clean run, then one per boundary it crossed (each step write landing, each settle), the worker killed there and the next one reclaiming; then each boundary again with the write's answer lost | `{ boundaries, divergences, reruns }`. A divergence carries `error`, an `X_JOB_CRASH_DIVERGED` naming the effect and the step it follows — `throw report.divergences[0].error`. A rerun is at-least-once, reported, never red |
+| `crashProof(job, input)` | one clean run, then one per distinct boundary it crossed (each step write landing, each settle), the worker killed there and the next one reclaiming; then each again with the write's answer lost. A loop's steps named by row id (`fanout:${row.id}`, `page-3` — a uuid, a digit run, an 8+ character token with a digit) are one point, killed at its first and last row: the cost is the job's steps, never the rows seeded. Over `CRASH_POINT_BOUND` (32) points per mode it throws `X_JOB_CRASH_UNBOUNDED` after the clean run, never a pass | `{ boundaries, crossed, divergences, reruns }` — `boundaries` the kills, `crossed` every boundary they stand for. A divergence carries `error`, an `X_JOB_CRASH_DIVERGED` naming the effect and the step it follows — `throw report.divergences[0].error`. A rerun is at-least-once, reported, never red |
 | `simulateJobs({ jobs: [{ handle, input }], workers, faults, invariant })` | `seeds` (20) seeds from `seed` (1), N workers, every driver call interleaved and faulted by a seeded picker: `kill`, `answer-lost`, `lease-lapse`, `duplicate-claim`, `clock-jump` (`ALL_FAULTS`) | throws `X_JOB_SIM_INVARIANT` with the seed and its faults when `invariant(state)` throws or answers `false`; `X_JOB_SIM_NONDETERMINISTIC` when one seed traces two ways. `x test job --seed <n>` replays one |
 
 A `compensates: true` job is also forced to fail for good and killed while it unwinds: each `compensate:*` once, last in first out. A kill inside `step.run(…, { once: true })` ends `X_STEP_OUTCOME_UNKNOWN` and is green. Postgres is not simulated. The reference: `examples/dummy/apps/web/app/posts/jobs.job.test.ts`.
@@ -896,10 +896,10 @@ await insertSeedGraph(graph, writer);
 | Rule | What it does |
 |---|---|
 | order | parents before children, over the entities' own `$references()` |
-| tenancy | each child points at a parent of its **own** tenant; the entity a tenant column references holds one row per tenant, keyed by the tenant. A table with no tenant column whose references reach a tenant-owned one, and no `shared` reason, is seeded per tenant too, under its own tenant's parent — `row.tenant` is that parent's tenant |
+| tenancy | each child points at a parent of its **own** tenant; the entity a tenant column references holds one row per tenant, keyed by the tenant. A table with no tenant column whose references reach a tenant-owned one, and no `shared` reason, is seeded per tenant too, under its own tenant's parent — `row.tenant` is that parent's tenant. A `shared` (or tenantless) table a tenant-owned one references through a key unique across the table — the unique holds the reference and not the tenant column — seeds `perTable` rows **per tenant**, still `tenant: null`, so every tenant's unique children find a parent row no other tenant took (`As of 2026-11-08`) |
 | a cycle | broken at a nullable key: inserted `null`, set by an entry of `graph.updates` once its target exists. The break prefers a table that takes updates — never an `appendOnly` one, whose key stays `null` when it is the only break. In `x exercise`, a deferred update the database refuses (a trigger no declaration carries) leaves the key `null`; an environment failure still fails. A cycle with no nullable key is `X_SEED_GRAPH_UNSATISFIED` |
 | values | read off the declaration, as `factoriesFor` reads them, and kept only if `$parse` accepts them |
-| patterns and schemas | a `matches(/…/)` pattern adds strings drawn from the pattern itself: literals, classes, `.`, groups, `\|`, quantifiers, anchors. Lookaround, backreferences, `\b` and `\p{…}` add nothing, so the column's other candidates stand. A `json(schema)` column draws from its schema, as the contract step's `arbitrary` does. Both are seeded by the row, so the same seed gives the same bytes |
+| patterns and schemas | a `matches(/…/)` pattern adds strings drawn from the pattern itself — `patternSamples` (`@ultimat3/schema/sample`), the one generator the input sampler uses too: literals, classes, `.`, groups, `\|`, quantifiers, anchors. Lookaround, backreferences, `\b` and `\p{…}` add nothing, so the column's other candidates stand. A `json(schema)` column draws from its schema, as the contract step's `arbitrary` does. Both are seeded by the row, so the same seed gives the same bytes |
 | rules | every invariant, the primary key, unique columns and unique indexes are kept; a partial unique is treated as total. A unique column that runs out of values ends its table early — but a table-wide unique that runs out before every tenant holds a row is `X_SEED_GRAPH_UNSATISFIED` (`… runs out of values before tenant 2 of 2 holds a row`): that tenant's children would have no parent |
 | an unseeded target | a key — the tenant column included — whose target entity is not in the set is `X_SEED_GRAPH_UNSATISFIED` (`… which is not in the set seeded — pass it too`) |
 | soft delete | a soft-deleting table's `deletedAt` is `null` unless a factory builds it: seeded rows are live |
@@ -960,10 +960,12 @@ A legal input that crashes the handler is red in `contract`, the day the action
 
 | Rule | |
 |---|---|
-| Who acts | `action.contract({ exercise: { actor } })`. Required unless the policy admits an anonymous caller. There is no bypass: a policy that denies `actor` makes an unreached run |
-| A row | `{ exercise: { actor, input: (drawn) => ({ ...drawn, postId }) } }` binds what a generated uuid cannot resolve |
-| Opting out | `{ exercise: { off: '<reason>' } }`. The reason is in the test's name. A blank one is `X_CONTRACT_EXERCISE_UNDECLARED` |
-| Runs | 16 (`EXERCISE_RUNS` from `@ultimat3/core`), `runs` from 1 to 64. Runs 0-3 sit on the IR's bounds (`minLength`, `maxLength`, `minimum`, `maximum`, `minItems`). The rest draw multibyte text, every enum and union member, optional keys on and off, `null` where nullable. A format value (`t.uuid`, `t.email`, …) is never varied |
+| **One declaration** | in an app, an action's exercise lives in `apps/web/exercise.ts` and nowhere else: `import { exercise } from '<…>/exercise'` then `action.contract({ exercise })` — the whole `defineExercise()` value, of which the contract reads the entry named for the action. `x exercise` reads the same entry, so a test and the pass cannot disagree on who acts. An entry declared only inline in a test is one `x exercise` cannot see (it reports the primitive `unreached`). `As of 2026-11-08` |
+| Who acts | the entry's `actor`. Required unless the policy admits an anonymous caller: no entry is `X_CONTRACT_EXERCISE_UNDECLARED`, its `fix:` the `defineExercise({ <name>: { actor } })` line to paste. An entry with no `actor` (`{ input }` alone, which typechecks) runs signed out where the policy admits it, else is `X_CONTRACT_EXERCISE_UNDECLARED` too: `x exercise` picks a role, a contract test has none to pick from (`As of 2026-11-08`). There is no bypass: a policy that denies `actor` makes an unreached run |
+| Inline, for a test's own world | `action.contract({ exercise: { actor, input } })` — one entry, not the app's — only when the test binds rows it seeded itself (`seed('dev').pick(…)`, an `actorFor`): those ids exist in that test alone. Kept and not deprecated; the who-acts of the primitive still belongs in `apps/web/exercise.ts` |
+| A row | `{ actor, input: (drawn) => ({ ...drawn, postId }) }` binds what a generated uuid cannot resolve |
+| Opting out | `{ off: '<reason>' }` as the entry. The reason is in the test's name. A blank one is `X_CONTRACT_EXERCISE_UNDECLARED` (`defineExercise` refuses it as the file loads) |
+| Runs | 16 (`EXERCISE_RUNS` from `@ultimat3/core`), `runs` from 1 to 64. Runs 0-3 sit on the IR's bounds (`minLength`, `maxLength`, `minimum`, `maximum`, `minItems`). The rest draw multibyte text, every enum and union member, optional keys on and off, `null` where nullable. A format value (`t.uuid`, `t.email`, …) is never varied. A `t.string.pattern(/…/)` no drawn text meets is walked from the pattern itself (days, months, hex digests, digit ids, base64url tokens), inside its length bounds; the minimal draw keeps `'sample'` when the pattern accepts it (`As of 2026-11-08`) |
 | Seed | `fnv1a(<action name>)`, never time, so a red run replays: `bun test <file> -t '<name>: handler survives generated input'` |
 | Rolled back | each run inside a memory transaction, always, and in it `withTransaction` when SQL can hold the writes: a SAVEPOINT in a test's open transaction, a root transaction once `setDbClient` installed a client. Both always roll back. The handler's SQL writes, its memory-store writes (`storeMode` `memory`, `tx` passed or not, since `memoryTransactor().run` is ambient), the outbox stage and the post-commit bust drop with it (`packages/action/src/tx-scope.ts` `inRolledBackScope`) |
 | **Not rolled back** | a write on a second client or `outsideTransaction`. A job enqueued with `outbox: false`. Storage puts. Mail and outbound fetch: the test preload seals both, so a real one is only sent where a test opted out. An audit record a non-database sink accepted |
@@ -972,14 +974,14 @@ A legal input that crashes the handler is red in `contract`, the day the action
 | Pass | the output parsed, or a coded refusal under 500 |
 | Defect, `X_CONTRACT_DEFECT` | an uncoded throw, `X_OUTPUT_INVALID`, or a coded 5xx (an undeclared `errors:` code is one). `meta.run`, `meta.input`, `meta.failure` |
 | Red, `X_CONTRACT_EXERCISE_UNREACHED` | no run reached the handler. `X_TEST_NETWORK_SEALED` counts as unreached, its host in `meta.outcomes` |
-| Red, `X_CONTRACT_DRIFT` | the schema refused every draw: a provider refinement the IR does not carry. Bind it with `exercise.input` |
+| Red, `X_CONTRACT_DRIFT` | the schema refused every draw: a provider refinement the IR does not carry, or a `pattern` past the generator's subset (lookaround, backreferences, `\b`, `\p{…}`), named in the cause as `field (must match …)`. Bind it with `exercise.input` |
 
-A query has the same assertion: `orgFeed.contract({ exercise: { actor } })`, named
+A query has the same assertion, read off the same file: `orgFeed.contract({ exercise })`, named
 `<name>: read survives generated input`. "Reached" is `sql()` building a source, and a read
 writes nothing, so no transaction wraps it; it refuses a deploy the same way. Both are one loop,
 `@ultimat3/core`'s `runExercise`: the verdicts above are the same words for a read and a write.
-The generators emit the call with an actor (`x g action`, `x g resource`), holding the slice's grant: a hand-written `policy.ts`'s one literal
-`can('<perm>')`, or `{ off }` when its grant cannot be read.
+The generators declare an actor (`x g action`, `x g resource`), holding the slice's grant: a hand-written `policy.ts`'s one literal
+`can('<perm>')`, or `{ off }` when its grant cannot be read. As of 2026-11-08 the call is `target.contract({ exercise })` and the actor is the ENTRY the generator inserts into `apps/web/exercise.ts` (`userActor({ id: 'member', orgId, permissions: [grant] })`, its draw's `orgId` bound under a tenancy rule; `x new` writes its example slice's the same way). The file is created from `x new`'s when absent; a file the generator cannot edit — no single `export const exercise = defineExercise({ … })` — is `X_EXERCISE_FILE_UNEDITABLE`, the entry to paste in its `fix:`. `x g query` emits no `.contract()` call: `x exercise` picks a reader by role.
 `@ultimat3/schema/sample`'s `arbitrary(schema, { seed, run })` is the draw, off the barrel.
 
 ## The exercise pass
@@ -992,7 +994,7 @@ shape, same unreached code. `As of 2026-11`.
 |---|---|
 | Database | a scratch one with the framework tables and every migration applied; never the developer's. The pass commits, so the tenant proof can read rows after the call |
 | Rows | one seed graph for the pass, a fresh pair of tenants per primitive in it — the first the actor's (A), the second the tenant proof's intruder (B); every table seeded off its declaration, parents first, same-tenant keys (`x db seed --generate`'s graph). A view and a `readOnly: '<why>'` table get no row; a NOT NULL key into a `readOnly` one is `X_SEED_GRAPH_UNSATISFIED` naming it ([Read-only tables](Entities-And-Migrations#read-only-tables)) |
-| Actor | the first of `x policy explain`'s actors the policy allows, in the primitive's tenant. None allowed is `refused`, by design |
+| Actor | the entry's `actor` when it declares one, seated in the primitive's tenant — and a top-level value of its bound input equal to the org the entry declared becomes that tenant too, so `input: (drawn) => ({ ...drawn, orgId: '<the actor's org>' })` holds in every tenant the pass seeds; otherwise the first of `x policy explain`'s actors the policy allows, in the primitive's tenant (an `{ input }`-only entry keeps this pick and still binds its input). None allowed is `refused`, by design. Its id has a user's shape: a uuid per role × tenant, the same on every run (`exerciseActorId`), never the role's name. Where the database has `x_users` (the framework schema every pass database is built with) each actor the pass acts as gets its row first — `<id>@exercise.invalid`, its tenant, roles, permissions, scopes — so `findUserById(ctx.actor.id)` finds it; a refused insert is `X_EXERCISE_ACTOR_USER_UNSEATED`. `defineExercise(…, { actor: members })` makes the id a seeded row's key instead (`As of 2026-11-08`) |
 | Input | the override, then an id field whose stem names a seeded entity (`postId` → `posts`), then the schema's minimal draw. A wrong guess shows as `unreached` |
 | A job's org | the field(s) its `tenant(input)` reads — any name, nested, left out of the draw, or under a parent the draw left out (a scoped backfill's `payload.input.orgId`) — are set to the tenant it is enqueued in, found by reading them: A's for the control, B's for the tenant proof (B's own job, carrying A's ids). A `tenant` no input field moves (one fixed org) is `unreached`, `X_JOB_TENANT_MISMATCH`, its `fix:` the declaration: `tenant: (input) => input.orgId` |
 | A job's run | its own execution alone: enqueued on a queue holding nothing else, run by one worker pass. What it enqueues is left queued, as an action's is — an `enqueue` effect on its record, searched by the tenant proof, never run in its room. Its `statements`, effects, verdict and scale and plan sweeps are its own body's: a job that queues one child per row is flat, a body that reads each row is still `X_QUERY_SCALES_WITH_ROWS`. A child is judged as its own primitive. The crash proof too: its clean and killed runs claim only the job's own row, a child compared as its `enqueue:` effect |
@@ -1000,9 +1002,10 @@ shape, same unreached code. `As of 2026-11`.
 | Async input | an override's `input` may be `async`: it is awaited inside the call's request, as the call's actor, so it can mint what the action checks (a one-time token, a passkey assertion). `x drill`'s load skips an `async` input and says why |
 | Room | network sealed, mail captured, jobs in memory, clock frozen — from before the app loads and the scratch database boots, as `bun test`'s preload does, so the embedded Postgres never sees its clock jump. A call out is refused and counted, so the primitive is `unreached` |
 | Cost | rows are primitives × tables; statements are not: the graph is written one `insertAll` per table, each tenant-proof snapshot is one statement, and a primitive reads only its own pair's rows of the graph |
-| Overrides | `apps/web/exercise.ts`: `export const exercise = defineExercise({ publishPost: { actor, input }, sendInvoice: { off: '<why>' } })`. Each value is `.contract({ exercise })`'s option. An unknown name is `X_DECLARATION_UNKNOWN`; a blank `off` is `X_CONTRACT_EXERCISE_UNDECLARED` |
+| Overrides | `apps/web/exercise.ts`: `export const exercise = defineExercise({ publishPost: { actor, input }, sendInvoice: { off: '<why>' } })`. The same value is what every contract test hands `.contract({ exercise })` ([one declaration](#the-exercise-assertion)). An unknown name is `X_DECLARATION_UNKNOWN`; a blank `off` is `X_CONTRACT_EXERCISE_UNDECLARED` |
 | A handler that calls a vendor | `defineExercise({ … }, { setup: () => { mockFetch('https://api.vendor.test/*', handler); } })` — or `setup: () => cassette(import.meta.dir, 'exercise')`. Runs once in the exercise process, after the seal and before the first row; what it returns is disposed after the pass. A call a setup route answers is reached, not refused. `allowHost` in it is `X_EXERCISE_SETUP_UNSEALED` |
 | Rows a generated value cannot satisfy | a cross-column `c.satisfies(…)` reads `X_SEED_GRAPH_UNSATISFIED`: `defineExercise({ … }, { factories: { bosses: defineFactory(bosses, { defaults: (i) => ({ … }) }) } })`, keyed by entity name, the graph's keys kept. A column that follows from a key or reference the graph picked: `derive: (row) => ({ scopeKey: … })` beside `build`/`reset`, reading `row.ownerOrgId`. A partial unique whose columns the factory builds is the database's to judge. An unknown name is `X_DECLARATION_UNKNOWN` |
+| Drift | a schema no draw satisfies is `unreached`, `X_CONTRACT_DRIFT`; its `override` binds each field the sampler names as a gap with what it needs (`digest: "<must match ^[0-9a-f]{64}$>"`), the contract step's `fix:` the same `input:` (`As of 2026-11-08`) |
 | Report | `.x/exercise.json` and `--json`: `{ seed, counts, records[] }`, each record `{ kind, name, outcome, code?, reason?, defect?, statements, effects, ms, override?, fix?, tenant?, crash? }` — `fix` where no override reaches it; `defect` on a 5xx: `{ cause, statement?, fields? }`, the error's own cause (a value the input held under a credential key or a `.sensitive()` field masked `[redacted]`), the SQL a database refusal names and the paths a validation failure names, all carried into the `X_CONTRACT_EXERCISE_UNREACHED` finding. The fields before `tenant` are A's call. The human table's `tenant` and `crash` columns are the verdicts, `-` where none ran |
 | Gate | the `exercise` step, after `job`, runs `x exercise --json` as a child and is red on its findings: `X_CONTRACT_EXERCISE_UNREACHED`, `X_TENANT_LEAK`, `X_TENANT_WRITE_CROSSED`, `X_JOB_CRASH_DIVERGED`, and — on a whole pass, not `x exercise <name>` — `X_ENTITY_TENANT_UNDECLARED`. `unreached` is never sampled or skipped: it is a finding whose `fix:` is the entry to paste |
 
@@ -1038,16 +1041,20 @@ only what came back and what changed.
 | `unproven` | A's own call was not `reached` | no — the record is already `unreached`, which is |
 | `public` | the policy admits an anonymous caller with an empty input: read half skipped, write half kept | no |
 | `public` | a **job** whose B leg opened `crossTenant(reason, fn)` and whose input carried none of A's marks — a declared sweep, `sendDigest` fanning out one delivery per org. The reason is quoted in the verdict; read half skipped, write half kept | no |
+| `public` | a **job** declaring `tenant: 'none'` whose input carried none of A's marks — a nightly cleanup across every org, input `{ occurrenceMs }`. No org and no id B chose reaches its run, so B's run is A's run: write half skipped (no snapshots taken), read half kept. Handed one of A's ids, crossed as ever. Both this and a declared sweep: both reasons, `; `-joined | no |
 | `unproven` | a query whose A answer held none of A's marks: B's empty answer proves nothing | no |
 | `proven` | otherwise | no |
 
 `off` and `refused` records carry no `tenant`. A job has no policy, so it is `public` only as a
-declared sweep. `crossTenant()` is the one declaration the proof reads (`@ultimat3/entity` tells a
-witness each scope opened, after its capability is proven); it excuses nothing on an action or a
-query, which answer B directly, nor on a job B handed one of A's ids — that is B choosing A's row,
-crossed as ever. A finding prints paths, tables and seeded ids, never a bound value. The fix on each:
-`x exercise <name> --json`, then read or write the row through the repository scoped to
-`ctx.actor`. What this does not walk — a `route` `load`, a `task` — is
+declared sweep or a `tenant: 'none'` job handed nothing of A's. `crossTenant()` is the one
+declaration the proof reads (`@ultimat3/entity` tells a witness each scope opened, after its
+capability is proven); it excuses nothing on an action or a query, which answer B directly, nor on a
+job B handed one of A's ids — that is B choosing A's row, crossed as ever. `tenant: 'none'` excuses
+only the write half, and only with no id of A's handed: an action or a query runs as B's actor, so a
+write to A's row with no id in the input is a statement no tenant predicate scopes, crossed. A
+finding prints paths, tables and seeded ids, never a bound value. The fix on each: `x exercise
+<name> --json`, then read or write the row through the repository scoped to `ctx.actor`. What this
+does not walk — a `route` `load`, a `task` — is
 [Policies and authz](Policies-And-Authz#the-dynamic-tenant-proof).
 
 ### The crash proof
@@ -1062,12 +1069,20 @@ actor, after the tenant proof. Source: `packages/testing/src/exercise-crash.ts`,
 | Runs | committed on the pass's scratch database, after the control. A job body runs outside every transaction, so no rollback scope can hold its writes, and an effect is counted when it commits |
 | Oracle | the effect multiset — row writes through a repository, mail, calls out, enqueues — of each killed run against the clean one. Raw SQL is no effect, and reads are none |
 | A job with no step | one boundary, before the ack: an effect in its body runs again on the retry |
+| A sweep | one step per row is one kill point when the step is named by the row's id: a job over 1,500 seeded rows costs the runs one over 3 does. Steps named otherwise (a slug, an email) past 32 points are `unproven`, `X_JOB_CRASH_UNBOUNDED` |
 
 | `crash.verdict` | When | Red |
 |---|---|---|
 | `diverged` | an effect made more often by a killed run: `findings[]` of `{ boundary, mode, effect, clean, killed, after?, inside? }` — `inside` the step whose body made it (`@ultimat3/jobs`' `currentStep()`), `after` the last step completed before it. An effect inside a step that did not complete, made FEWER times by a kill that spent one of its attempts, is not a divergence | yes: `X_JOB_CRASH_DIVERGED`, one per effect and place, every boundary named. Inside a step the fix keys its call on `${jobId}:<step>`; outside every step it wraps it in `step.run` |
-| `held` | otherwise; `boundaries` and `reruns` (lost answers — at-least-once, never red) counted | no |
-| `unproven` | the proof itself threw: `reason` | no |
+| `held` | otherwise; `boundaries` (kills), `crossed` (boundaries they stand for) and `reruns` (lost answers — at-least-once, never red) counted | no |
+| `unproven` | the proof itself threw, or could not finish in its bound: `reason`, `X_JOB_CRASH_UNBOUNDED: …` for the second | no |
+
+**Where the time went.** Every record carries `proofMs: { tenant, crash, scale }` beside `ms` (the
+control's own call); the report carries `phases: { seed, primitives, scale, plans, subject }`, in
+milliseconds. No per-record plan time: one statement is planned once for every primitive that sent
+it. The table's `tenant ms` / `crash ms` / `scale ms` columns, then
+`took 44704 ms — seed 818 · primitives 41099 · … — slowest: primitives` and the five slowest
+proofs by record, `slowest: job billing.plan-catalog · crash 35692 ms`. `As of 2026-11`.
 
 The human output prints one line per killed boundary,
 `job chargeOrder · killed at mail · X_JOB_CRASH_DIVERGED row:payments:insert 2× (clean 1×)`. The fix
@@ -1085,7 +1100,7 @@ Source: `packages/testing/src/scale-sweep*.ts`, `plan-oracle.ts`, `plan-sweep*.t
 | Sweep | What | Red |
 |---|---|---|
 | scale | every reached primitive once more in a tenant at 2 rows a table, once in one at 8; per statement shape, the counts compared | a shape sent more often at 8: `X_QUERY_SCALES_WITH_ROWS`, fix `preload()` or `expectedQueryLoop('<why>', fn)` |
-| plans | every distinct statement whose first relation is an app table, `PREPARE`d and explained as a generic plan with `enable_seqscan`, `enable_bitmapscan`, `enable_sort` off, in a read-only transaction | `Seq Scan`, or an index scan with no `Index Cond` no `Limit` stops: `X_QUERY_UNINDEXED`. `Sort` under `Limit`: `X_QUERY_SORT_UNSERVED`. Each prints `indexes: [{ on: [...] }]` |
+| plans | every distinct statement whose first relation is an app table, `PREPARE`d and explained as a generic plan with `enable_seqscan`, `enable_bitmapscan`, `enable_sort` off, in a read-only transaction | `Seq Scan`, or an index scan with no `Index Cond` no `Limit` stops: `X_QUERY_UNINDEXED`. `Sort` under `Limit`: `X_QUERY_SORT_UNSERVED`, on the table its key names. Each prints an `indexes:` entry, one per arm for an `or`; a sort no declarable index serves (an expression, an aggregate, a derived column, keys across tables, mixed directions) or an index the entity already declares prints a rewrite or `expectedSeqScan` instead |
 
 With the planner's scans and sorts disabled it picks one only when no index can answer, so the
 verdict reads the schema on empty tables — no volume, no statistics. Never red: `scale.verdict`