@ultimat3/cli 30.1.0 → 30.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "30.1.0",
+  "version": "30.3.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "keywords": [
     "ultimate",
@@ -53,33 +53,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.7",
-    "@ultimat3/action": "30.1.0",
-    "@ultimat3/admin": "30.1.0",
-    "@ultimat3/ai": "30.1.0",
-    "@ultimat3/auth": "30.1.0",
-    "@ultimat3/cache": "30.1.0",
-    "@ultimat3/core": "30.1.0",
-    "@ultimat3/db": "30.1.0",
-    "@ultimat3/entity": "30.1.0",
-    "@ultimat3/flags": "30.1.0",
-    "@ultimat3/http": "30.1.0",
-    "@ultimat3/i18n": "30.1.0",
-    "@ultimat3/jobs": "30.1.0",
-    "@ultimat3/mail": "30.1.0",
-    "@ultimat3/manifest": "30.1.0",
-    "@ultimat3/mcp": "30.1.0",
-    "@ultimat3/money": "30.1.0",
-    "@ultimat3/notify": "30.1.0",
-    "@ultimat3/policy": "30.1.0",
-    "@ultimat3/pwa": "30.1.0",
-    "@ultimat3/query": "30.1.0",
-    "@ultimat3/realtime": "30.1.0",
-    "@ultimat3/render": "30.1.0",
-    "@ultimat3/schema": "30.1.0",
-    "@ultimat3/seo": "30.1.0",
-    "@ultimat3/storage": "30.1.0",
-    "@ultimat3/testing": "30.1.0",
-    "@ultimat3/time": "30.1.0",
+    "@ultimat3/action": "30.3.0",
+    "@ultimat3/admin": "30.3.0",
+    "@ultimat3/ai": "30.3.0",
+    "@ultimat3/auth": "30.3.0",
+    "@ultimat3/cache": "30.3.0",
+    "@ultimat3/core": "30.3.0",
+    "@ultimat3/db": "30.3.0",
+    "@ultimat3/entity": "30.3.0",
+    "@ultimat3/flags": "30.3.0",
+    "@ultimat3/http": "30.3.0",
+    "@ultimat3/i18n": "30.3.0",
+    "@ultimat3/jobs": "30.3.0",
+    "@ultimat3/mail": "30.3.0",
+    "@ultimat3/manifest": "30.3.0",
+    "@ultimat3/mcp": "30.3.0",
+    "@ultimat3/money": "30.3.0",
+    "@ultimat3/notify": "30.3.0",
+    "@ultimat3/policy": "30.3.0",
+    "@ultimat3/pwa": "30.3.0",
+    "@ultimat3/query": "30.3.0",
+    "@ultimat3/realtime": "30.3.0",
+    "@ultimat3/render": "30.3.0",
+    "@ultimat3/schema": "30.3.0",
+    "@ultimat3/seo": "30.3.0",
+    "@ultimat3/storage": "30.3.0",
+    "@ultimat3/testing": "30.3.0",
+    "@ultimat3/time": "30.3.0",
     "babel-preset-solid": "^1.9.16"
   }
 }

package/src/cmd-exercise.ts

@@ -95,7 +95,7 @@ async function exercise(
     proved.length === 0
       ? []
       : await withExerciseDatabase(root, ctx.env, (client) =>
-          subjectProofFindings(proved, cores, client),
+          subjectProofFindings(proved, cores, client, overrides?.factories),
         );
   const report = exerciseReport(records, seed);
   // The whole pass, not a one-primitive run's slice of it, is what the file is for — but a

package/src/exercise-database.ts

@@ -7,7 +7,12 @@ import type { Environment } from '@ultimat3/core';
 import { ENVIRONMENT_KEY, resolveEnvironment, UltimateError } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
 import { migrate, raw, setDbClient } from '@ultimat3/db';
-import { testSealKeyEnv } from '@ultimat3/testing';
+import {
+  captureDeterminism,
+  installDeterminism,
+  restoreCapturedDeterminism,
+  testSealKeyEnv,
+} from '@ultimat3/testing';
 import { chooseReplayEngine, withScratchDatabase } from './db-replay-engine';
 import { applyFrameworkSchema } from './framework-schema';
 import { readMigrations } from './migrations';
@@ -50,6 +55,12 @@ const PINNED = [ENVIRONMENT_KEY, 'NODE_ENV'] as const;
  * module reads it, and the throwaway seal key `bun test` gets when the app supplied none (CI names
  * no `ULTIMATE_SECRETS_KEY`, and every row sealed here dies with the scratch database). Every
  * variable is put back as found: a command that exits must not leave the next one a test process.
+ *
+ * The frozen clock too, and FIRST — as `bun test`'s preload freezes it before any module loads. The
+ * scratch database is PGlite, whose Postgres arms its timers off `Date.now()`: booted on the real
+ * clock and frozen under later (the pass's room), its 10 s idle-stats timer was re-armed at
+ * real-now minus frozen-now, ~2^34 ms, clamped to 1 ms — a `TimeoutOverflowWarning` busy loop for
+ * the whole pass. One clock for the engine's whole life: the deadline and the delay agree.
  */
 export async function withExerciseProcess<T>(
   root: string,
@@ -62,10 +73,13 @@ export async function withExerciseProcess<T>(
   );
   const added = { ...pinned, ...testSealKeyEnv({ root, env: { ...env, ...pinned } }) };
   const previous = Object.keys(added).map((key) => [key, process.env[key]] as const);
+  const clock = captureDeterminism();
+  if (!clock.installed) installDeterminism();
   Object.assign(process.env, added);
   try {
     return await work();
   } finally {
+    restoreCapturedDeterminism(clock);
     for (const [key, value] of previous) {
       if (value === undefined) delete process.env[key];
       else process.env[key] = value;

package/src/exercise-findings.ts

@@ -57,7 +57,9 @@ const unreachedFinding = (record: ExerciseRecord): Finding => {
   return {
     code: 'X_CONTRACT_EXERCISE_UNREACHED',
     cause: `${record.kind} ${renderCauseValue(record.name)} never reached its handler as an allowed actor in the exercise pass${stopped}${why}`,
-    fix: `defineExercise({ ${override} })   # paste the entry into ${EXERCISE_FILE}, or { off: '<why>' }; then: x exercise ${name} --json`,
+    fix:
+      record.fix ??
+      `defineExercise({ ${override} })   # paste the entry into ${EXERCISE_FILE}, or { off: '<why>' }; then: x exercise ${name} --json`,
     docs: ERROR_DOCS_URL,
     at: EXERCISE_FILE,
   };

package/src/exercise-subject.ts

@@ -9,6 +9,7 @@ import { identifier, sql } from '@ultimat3/db';
 import type { EntityCore, RegistryEntry } from '@ultimat3/entity';
 import type { Subject } from '@ultimat3/jobs';
 import { planSubject } from '@ultimat3/jobs';
+import type { SeedFactory } from '@ultimat3/testing';
 import { entitySeedWriter, subjectProof } from '@ultimat3/testing';
 import type { Finding } from './output';
 
@@ -39,6 +40,7 @@ export async function subjectProofFindings(
   subjects: readonly Subject<never>[],
   cores: Readonly<Record<string, EntityCore>>,
   client: DbClient,
+  factories?: Readonly<Record<string, SeedFactory>>,
 ): Promise<readonly Finding[]> {
   const findings: Finding[] = [];
   for (const [index, subject] of subjects.entries()) {
@@ -49,6 +51,7 @@ export async function subjectProofFindings(
       read: (entity) =>
         client.query<Record<string, unknown>>(sql`select * from ${identifier(entity.$table)}`),
       seed: SUBJECT_PROOF_SEED + index,
+      factories,
     }).then(
       (result) => result.problems.filter((p) => p.code === 'X_SUBJECT_ERASE_INCOMPLETE'),
       (error: unknown) => (isUltimateError(error) ? [error] : Promise.reject(error)),

package/src/seo-routes.ts

@@ -183,7 +183,7 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
     return first.answer;
   };
 
-  return [
+  const routes: Route[] = [
     {
       method: 'GET',
       path: ROBOTS_PATH,
@@ -256,4 +256,7 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
       },
     },
   ];
+  // `seo.llms: false` hands the path to the app: an app that writes its own `/llms.txt` (plans,
+  // prices) mounted it beside this one and every boot refused with X_ROUTE_CONFLICT.
+  return options.site?.llms === false ? routes.filter((route) => route.path !== LLMS_PATH) : routes;
 }

package/src/site-config.ts

@@ -26,7 +26,7 @@ export interface SiteSettings {
    * `SiteSettings` literal written before it existed still compiles.
    */
   readonly favicon?: SiteFavicon | undefined;
-  /** `seo.llms` — `/llms.txt` on (the default) or off. Optional for `robotsGroups`' reason. */
+  /** `seo.llms` — `/llms.txt` on (the default) or off: off, the path is the app's to mount. Optional for `robotsGroups`' reason. */
   readonly llms?: boolean | undefined;
 }
 

package/src/site-seo-write.ts

@@ -9,10 +9,17 @@ import { ROBOTS_PATH, type SiteSeo } from './site-seo';
 /**
  * Writes every file of `seo` under `out` and answers their site-relative paths, the sitemap files
  * first. `Bun.write` creates `sitemaps/` on the way, so an index and its parts land together.
+ * `llms: false` (`seo.llms`) writes no `llms.txt`: the path is the app's, as on a running web role.
  */
-export async function writeSiteSeo(out: string, seo: SiteSeo): Promise<readonly string[]> {
+export async function writeSiteSeo(
+  out: string,
+  seo: SiteSeo,
+  options: { readonly llms?: boolean | undefined } = {},
+): Promise<readonly string[]> {
   for (const file of seo.sitemaps) await Bun.write(join(out, file.path), file.xml);
   await Bun.write(join(out, ROBOTS_PATH), seo.robots);
+  const sitemaps = seo.sitemaps.map((file) => file.path);
+  if (options.llms === false) return [...sitemaps, ROBOTS_PATH];
   await Bun.write(join(out, LLMS_PATH), seo.llms);
-  return [...seo.sitemaps.map((file) => file.path), ROBOTS_PATH, LLMS_PATH];
+  return [...sitemaps, ROBOTS_PATH, LLMS_PATH];
 }

package/src/templates/scaffold-entries.ts

@@ -119,7 +119,7 @@ async function writeSeoFiles(report: PrerenderReport): Promise<readonly string[]
     entries: report.entries,
     llmsPages: report.llmsPages,
   });
-  return await writeSiteSeo(out, seo);
+  return await writeSiteSeo(out, seo, { llms: settings.llms });
 }
 
 if (import.meta.main) {

package/wiki/Entities-And-Migrations.md

@@ -968,6 +968,22 @@ export const postTotals = entity('post_totals', {
 | Admin, MCP | listed read-only: `list`, `detail`, `search`, and no create/edit/delete route, button or admin MCP tool. An `operations` override naming a write is `X_ADMIN_VIEW_WRITE` ([Admin dashboard](Admin-Dashboard)) |
 | Manifest | the entity's fact carries `view: { materialized }`; a table becoming a view is a **breaking** change, a view becoming a table additive |
 
+## Read-only tables
+
+`entity(name, { readOnly: '<why>', columns })` declares a table the app reads and never writes —
+legacy history a trigger closed to INSERTs, a table another system owns. The reason is required. As
+of 2026-11:
+
+| Rule | |
+|---|---|
+| Writes | `insert`, `insertAll`, `upsertAll`, `update`, `delete`, `updateWhere`, `deleteWhere`, `lock`: `X_ENTITY_READ_ONLY`, in both drivers, before a statement exists, the reason in the cause |
+| Refused at declaration | a blank reason, `view` (already read-only), `appendOnly` (it admits the inserts this refuses): `X_INVARIANT_VIOLATED` |
+| Seeds | `x db seed --generate` and `x exercise` seed no row of it. A nullable reference into it is seeded null; a NOT NULL one is `X_SEED_GRAPH_UNSATISFIED` naming the table, its reason, and the fix: `readOnly` on the referencing table too, or `.nullable()` then `x db gen` |
+| Subjects | `defineSubject`'s `'delete'` or `anonymize` on it is `X_SUBJECT_TREATMENT_INVALID`; `retain` is the one treatment that holds |
+| Admin, MCP | listed read-only, as a view; an `operations` override naming a write is `X_ADMIN_READ_ONLY_WRITE` |
+| Projection, manifest | `$describe().readOnly` and the manifest's entity fact carry the reason, absent when undeclared; becoming readOnly is **breaking**, ceasing to be additive |
+| DDL | none: `x db gen` emits nothing for it. The trigger, grant or ownership that closes the table is yours |
+
 ## Migration workflow
 
 | Step | Command | Behavior |

package/wiki/SEO.md

@@ -265,7 +265,7 @@ description, in path order, under the home page's title and description:
 | served | `GET /llms.txt` from the web role (`text/markdown`, the sitemap's hour of cache); the static export writes the same bytes (`writeSiteSeo`) |
 | listed | public, indexable `site/` pages, in the default locale, less `seo.robots.disallow`. A dynamic route (or one with a `load`) is expanded through `prerender()` page by page, each line the title and description that page's own `meta` gives it through its `load` — the export lists only the pages it emitted, as the sitemap does; a page whose `meta` says `robots: { index: false }` is left out. `prerender()` runs once per answer for the sitemap and this file together |
 | outside production | an empty document, for `robots.txt`'s reason |
-| opt out | `seo: { llms: false }` in `app.config.ts`: an empty document everywhere |
+| opt out | `seo: { llms: false }` in `app.config.ts`: the framework mounts no `GET /llms.txt` and the static export writes none — the path is the app's own route to serve, or a 404 |
 | build error | while on, a listed page with no `meta.description` is `X_SEO_LLMS_DESCRIPTION_MISSING` in the `seo` step. The step reads `meta` without a database, so it checks the pages whose `meta` needs no `load`; an expanded page with no description is listed by its title alone |
 
 The repository's own `llms.txt` is a separate, hand-kept file and is not this.

package/wiki/Testing.md

@@ -981,14 +981,16 @@ shape, same unreached code. `As of 2026-11`.
 | Rule | |
 |---|---|
 | 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) |
+| 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 |
 | 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, or left out of the draw — 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` |
 | 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. A call out is refused and counted, so the primitive is `unreached` |
+| 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` |
-| 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. An unknown name is `X_DECLARATION_UNKNOWN` |
-| Report | `.x/exercise.json` and `--json`: `{ seed, counts, records[] }`, each record `{ kind, name, outcome, code?, reason?, statements, effects, ms, override?, tenant?, crash? }`. The fields before `tenant` are A's call. The human table's `tenant` and `crash` columns are the verdicts, `-` where none ran |
+| 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` |
+| Report | `.x/exercise.json` and `--json`: `{ seed, counts, records[] }`, each record `{ kind, name, outcome, code?, reason?, statements, effects, ms, override?, fix?, tenant?, crash? }` — `fix` where no override reaches it. 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 |
 
 ```bash