@ultimat3/cli 30.4.0 → 30.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "30.4.0",
+  "version": "30.6.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.4.0",
-    "@ultimat3/admin": "30.4.0",
-    "@ultimat3/ai": "30.4.0",
-    "@ultimat3/auth": "30.4.0",
-    "@ultimat3/cache": "30.4.0",
-    "@ultimat3/core": "30.4.0",
-    "@ultimat3/db": "30.4.0",
-    "@ultimat3/entity": "30.4.0",
-    "@ultimat3/flags": "30.4.0",
-    "@ultimat3/http": "30.4.0",
-    "@ultimat3/i18n": "30.4.0",
-    "@ultimat3/jobs": "30.4.0",
-    "@ultimat3/mail": "30.4.0",
-    "@ultimat3/manifest": "30.4.0",
-    "@ultimat3/mcp": "30.4.0",
-    "@ultimat3/money": "30.4.0",
-    "@ultimat3/notify": "30.4.0",
-    "@ultimat3/policy": "30.4.0",
-    "@ultimat3/pwa": "30.4.0",
-    "@ultimat3/query": "30.4.0",
-    "@ultimat3/realtime": "30.4.0",
-    "@ultimat3/render": "30.4.0",
-    "@ultimat3/schema": "30.4.0",
-    "@ultimat3/seo": "30.4.0",
-    "@ultimat3/storage": "30.4.0",
-    "@ultimat3/testing": "30.4.0",
-    "@ultimat3/time": "30.4.0",
+    "@ultimat3/action": "30.6.0",
+    "@ultimat3/admin": "30.6.0",
+    "@ultimat3/ai": "30.6.0",
+    "@ultimat3/auth": "30.6.0",
+    "@ultimat3/cache": "30.6.0",
+    "@ultimat3/core": "30.6.0",
+    "@ultimat3/db": "30.6.0",
+    "@ultimat3/entity": "30.6.0",
+    "@ultimat3/flags": "30.6.0",
+    "@ultimat3/http": "30.6.0",
+    "@ultimat3/i18n": "30.6.0",
+    "@ultimat3/jobs": "30.6.0",
+    "@ultimat3/mail": "30.6.0",
+    "@ultimat3/manifest": "30.6.0",
+    "@ultimat3/mcp": "30.6.0",
+    "@ultimat3/money": "30.6.0",
+    "@ultimat3/notify": "30.6.0",
+    "@ultimat3/policy": "30.6.0",
+    "@ultimat3/pwa": "30.6.0",
+    "@ultimat3/query": "30.6.0",
+    "@ultimat3/realtime": "30.6.0",
+    "@ultimat3/render": "30.6.0",
+    "@ultimat3/schema": "30.6.0",
+    "@ultimat3/seo": "30.6.0",
+    "@ultimat3/storage": "30.6.0",
+    "@ultimat3/testing": "30.6.0",
+    "@ultimat3/time": "30.6.0",
     "babel-preset-solid": "^1.9.16"
   }
 }

package/src/exercise-findings.ts

@@ -12,7 +12,7 @@ import {
   renderFixShellArg,
 } from '@ultimat3/core';
 import type { ExerciseRecord } from '@ultimat3/testing';
-import { planSweepFindings, tenantProofFindings } from '@ultimat3/testing';
+import { crashEffectPlace, planSweepFindings, tenantProofFindings } from '@ultimat3/testing';
 import type { Finding } from './output';
 import { renderTable } from './table';
 
@@ -44,6 +44,20 @@ export const exerciseCounts = (records: readonly ExerciseRecord[]): ExerciseCoun
   };
 };
 
+/**
+ * A 5xx's own words — the cause testing recorded (credential values already masked there) and the
+ * fields a validation failure names. The statement is inside the cause, so it is not said twice.
+ */
+const defectOf = (record: ExerciseRecord): string => {
+  const defect = record.defect;
+  if (defect === undefined) return '';
+  const fields =
+    defect.fields === undefined
+      ? ''
+      : ` at ${defect.fields.map((field) => renderCauseValue(field)).join(', ')}`;
+  return ` — cause: ${renderCauseValue(defect.cause)}${fields}`;
+};
+
 /**
  * `X_CONTRACT_EXERCISE_UNREACHED`, `@ultimat3/action`'s code for the same silence one level up: a
  * primitive no run got to as an allowed actor. The fix is the override the pass printed, or the
@@ -56,7 +70,7 @@ const unreachedFinding = (record: ExerciseRecord): Finding => {
   const why = record.reason === undefined ? '' : ` (${renderCauseValue(record.reason)})`;
   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}`,
+    cause: `${record.kind} ${renderCauseValue(record.name)} never reached its handler as an allowed actor in the exercise pass${stopped}${why}${defectOf(record)}`,
     fix:
       record.fix ??
       `defineExercise({ ${override} })   # paste the entry into ${EXERCISE_FILE}, or { off: '<why>' }; then: x exercise ${name} --json`,
@@ -75,27 +89,29 @@ const crashFindingsOf = (record: ExerciseRecord): readonly CrashFinding[] =>
 
 /**
  * `X_JOB_CRASH_DIVERGED`, testing's code: a reached job, killed at a step boundary, made an effect
- * more often than a clean run — it sits outside every `step.run`, so a retry makes it again. One
- * finding per effect and the step it follows, every boundary that showed it named in the cause.
+ * a different number of times than a clean run. Where it ran — outside every `step.run`, or inside
+ * one whose body re-runs — is testing's `crashEffectPlace`, the phrase its error uses too. One
+ * finding per effect and place, every boundary that showed it named in the cause.
  */
 const crashFindings = (record: ExerciseRecord): readonly Finding[] => {
   const groups = new Map<string, CrashFinding[]>();
   for (const one of crashFindingsOf(record)) {
-    const key = `${one.effect}\u0000${one.after ?? ''}`;
+    const key = `${one.effect}\u0000${one.after ?? ''}\u0000${one.inside ?? ''}`;
     groups.set(key, [...(groups.get(key) ?? []), one]);
   }
   const job = renderFixShellArg(record.name, '<job>');
   return [...groups.values()].map((group): Finding => {
     const [first] = group as [CrashFinding, ...CrashFinding[]];
-    const where =
-      first.after === undefined
-        ? 'before the first step'
-        : `after step ${JSON.stringify(first.after)}`;
+    const { place, remedy } = crashEffectPlace(first);
+    const how =
+      first.killed > first.clean
+        ? 'the retry after a crash makes it again'
+        : 'the crash skipped it';
     const at = group.map((one) => JSON.stringify(one.boundary)).join(', ');
     return {
       code: 'X_JOB_CRASH_DIVERGED',
-      cause: `job ${renderCauseValue(record.name)} killed at ${at} made ${renderCauseValue(first.effect)} ${first.killed}× against ${first.clean}× in a clean run: it runs outside every step, ${where}, so the retry after a crash makes it again`,
-      fix: `x exercise ${job} --json   # in job(${renderFixLiteral(record.name, '<job>')}): wrap the ${renderFixLiteral(first.effect, '<effect>')} made ${where} in step.run('<name>', async () => …)`,
+      cause: `job ${renderCauseValue(record.name)} killed at ${at} made ${renderCauseValue(first.effect)} ${first.killed}× against ${first.clean}× in a clean run: ${place}, so ${how}`,
+      fix: `x exercise ${job} --json   # in job(${renderFixLiteral(record.name, '<job>')}), for ${renderFixLiteral(first.effect, '<effect>')}: ${remedy}`,
       docs: ERROR_DOCS_URL,
       at: `${record.kind} ${record.name}`,
     };

package/wiki/Testing.md

@@ -92,6 +92,7 @@ Any test that can pass twice and fail the third time is worse than no test — i
 | **Frozen clock** | time starts at a fixed instant. `clock.advance('3d')` moves it, and it also drives `step.sleep` and cron in tests |
 | **Seeded RNG** | `Math.random`, `crypto.randomUUID`, and Bun's RNG are seeded per test file from its path — reproducible, distinct across files |
 | **Sealed network** | a `fetch`, a `new WebSocket(…)` or a `Bun.connect(…)` to anywhere not explicitly mocked or allowed **fails the test** with `X_TEST_NETWORK_SEALED`, naming the URL and the fix — the three dials share one gate, so the allow-list and `offline()` apply to all of them — `offline()` refuses a loopback dial too (`X_TEST_NETWORK_OFFLINE`). A dial that goes around those three globals (a `node:net` socket, `Bun.udpSocket`) is not sealed |
+| **Sealed names** | `Bun.dns.lookup`, `dns.lookup` and `dns.promises.lookup` ask the same gate: a host a `mockFetch` route names resolves to `MOCKED_HOST_ADDRESS` (`11.11.11.11`, public, so an SSRF screen such as `screenDial` passes it and the dial it pins still meets the mock by its `Host`); this machine, an address literal and an `allowHost` name resolve for real; offline refuses every name (`X_TEST_NETWORK_OFFLINE`); any other name is `X_TEST_NETWORK_SEALED`. A RegExp route names a host it matches at the origin or spells in its source. Not covered: `lookup` bound by a named ESM import (`import { lookup } from 'node:dns'`) before the seal, and `dns.resolve*` |
 | **Fixed timezone + locale** | `UTC` and `en-US` unless a test declares otherwise; a tz-dependent bug fails deterministically |
 | **Ordered concurrency** | job workers in tests run deterministically; `runJobs()` drains the queue synchronously |
 | **Per-test reset** | before EVERY test, not every file, the preload puts the jobs event bus back (`installPerTestReset()`): an answer one test published never resumes the next test's waiting run, with or without `runJobs`. A test that never loaded `@ultimat3/jobs` pays nothing. `As of 2026-10` |
@@ -558,7 +559,7 @@ What the rendered result is then held to: [Interface rules](Interface-Rules).
 | `mail` | `outbox()` · `lastTo(address)` · `failOnce(mail)` | the preload |
 | `network` | `offline()` · `drop()` · `online()` · `state()` | the preload |
 | `push` | `subscribe(actorId, { locale })` · `sent()` — each delivery decrypted, as the device shows it · `answerOnce(status)` | the preload |
-| `runJobs` | enqueue+drain, then `enqueue()` `drain()` `due()` `inFlight()` `depth()` → [A job under `runJobs`](#a-job-under-runjobs) | the preload |
+| `runJobs` | enqueue+drain, then `enqueue()` `drain()` `tick()` `due()` `inFlight()` `depth()` → [A job under `runJobs`](#a-job-under-runjobs) | the preload |
 | `statements` | `all()` · `count(fingerprint?)` · `shapes()` — and an N+1 fails the test | the preload |
 | `page` | `goto` · `gotoStreamed` · `getByRole` · `evaluate` · `waitForServiceWorker` | a browser driver |
 | `budget` | `jsBytes(route)` off the built output | a browser driver |
@@ -994,6 +995,7 @@ shape, same unreached code. `As of 2026-11`.
 | 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, 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 |
 | A job's failure | judged by the action rule: a coded refusal under 500 (an app's 409) is `unreached` under its own code, never a defect; an uncoded throw or a coded 5xx is `X_CONTRACT_DEFECT` |
 | 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` |
@@ -1001,7 +1003,7 @@ shape, same unreached code. `As of 2026-11`.
 | 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` |
 | 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` |
-| 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 |
+| 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 |
 
 ```bash
@@ -1063,7 +1065,7 @@ actor, after the tenant proof. Source: `packages/testing/src/exercise-crash.ts`,
 
 | `crash.verdict` | When | Red |
 |---|---|---|
-| `diverged` | an effect made more often by a killed run: `findings[]` of `{ boundary, mode, effect, clean, killed, after? }` | yes: `X_JOB_CRASH_DIVERGED`, one per effect and the step it follows, every boundary named |
+| `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 |