@ultimat3/cli 30.2.0 → 30.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "30.2.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.2.0",
-    "@ultimat3/admin": "30.2.0",
-    "@ultimat3/ai": "30.2.0",
-    "@ultimat3/auth": "30.2.0",
-    "@ultimat3/cache": "30.2.0",
-    "@ultimat3/core": "30.2.0",
-    "@ultimat3/db": "30.2.0",
-    "@ultimat3/entity": "30.2.0",
-    "@ultimat3/flags": "30.2.0",
-    "@ultimat3/http": "30.2.0",
-    "@ultimat3/i18n": "30.2.0",
-    "@ultimat3/jobs": "30.2.0",
-    "@ultimat3/mail": "30.2.0",
-    "@ultimat3/manifest": "30.2.0",
-    "@ultimat3/mcp": "30.2.0",
-    "@ultimat3/money": "30.2.0",
-    "@ultimat3/notify": "30.2.0",
-    "@ultimat3/policy": "30.2.0",
-    "@ultimat3/pwa": "30.2.0",
-    "@ultimat3/query": "30.2.0",
-    "@ultimat3/realtime": "30.2.0",
-    "@ultimat3/render": "30.2.0",
-    "@ultimat3/schema": "30.2.0",
-    "@ultimat3/seo": "30.2.0",
-    "@ultimat3/storage": "30.2.0",
-    "@ultimat3/testing": "30.2.0",
-    "@ultimat3/time": "30.2.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/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/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/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. 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?, tenant?, crash? }`. The fields before `tenant` are A's call. The human table's `tenant` and `crash` columns are the verdicts, `-` where none ran |
+| 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