@ultimat3/cli 29.3.2 → 30.0.0

package/wiki/Building-Your-Own-Base.md

@@ -0,0 +1,203 @@
+# Building your own base
+
+**Ultimate ships mechanism; your app ships convention.** Ultimate's own conventions are structural —
+file naming, the four surfaces, the tier order — and they ship as build errors. Your *business*
+conventions are yours, and a primitive is a function returning a value, so you encode one by
+wrapping and exporting your own factory. No fork, no monkey-patch, no plugin API, no release to
+wait for.
+
+Everything downstream treats the result identically — registry, manifest, projections, admin,
+MCP, `x verify`.
+
+**Re-run against 4.0.0** `As of 2026-08-20`: every fenced example on this page compiles under the
+repository's own `tsconfig.base.json` (`strict`, `exactOptionalPropertyTypes`,
+`noUncheckedIndexedAccess`, `verbatimModuleSyntax`), and both compile errors quoted under
+[Two caveats](#two-caveats) are `tsc`'s verbatim words at that setting. The `tenantEntity` example
+was executed as well, and again `As of 2026-11-03` — `getEntity('invoices').describe()` answers columns `id, memo, orgId,
+createdAt`, one index `invoices_org_id_idx` on `org_id`, `orgScoped: true`, and
+`invoices.$tenantColumn` is `'orgId'`. The projections are run too, on every gate:
+`packages/cli/src/third-party-wrapper.test.ts` installs a factory-built entity, an MCP-exposed
+action and a job from a package under `node_modules/`, re-exports them from an app, and asserts
+`x entities`, the manifest and `tools/list` hold them, the action's policy refuses a caller without
+the grant, and the job runs. It fails the day any of those learns where a primitive came from.
+
+Put the factory in a surface both `app/` and `api/` may import — `apps/web/shared/base/` in the
+generated layout ([Project layout](Project-Layout)).
+
+## A tenant entity
+
+```ts
+// apps/web/shared/base/tenant-entity.ts
+import { entity, timestamp, uuid, type ColumnMap, type EntityInit } from '@ultimat3/entity';
+
+/** Every table in this app is org-scoped and stamped. Declared once, not at forty call sites. */
+export const tenantEntity = <const C extends ColumnMap>(name: string, init: EntityInit<C>) =>
+  entity(name, {
+    ...init,
+    columns: { ...init.columns, orgId: uuid().tenant(), createdAt: timestamp().defaultNow() },
+    indexes: [...(init.indexes ?? []), { on: ['orgId'] }],
+  });
+```
+
+```ts
+// apps/web/app/invoices/entity.ts
+import { text, uuid } from '@ultimat3/entity';
+import { tenantEntity } from '../../shared/base/tenant-entity';
+
+export const invoices = tenantEntity('invoices', {
+  columns: { id: uuid().primaryKey(), memo: text() },
+});
+
+export type Invoice = typeof invoices.$row;
+```
+
+What it buys:
+
+| Before | After |
+|---|---|
+| every entity file remembers `orgId: uuid().tenant()` | tenancy is a property of the base, unforgettable |
+| a forgotten tenant column is an unscoped read that ships | there is no way to declare an unscoped table through this factory |
+| the `orgId` index is remembered per table, or is not | it arrives with the column |
+| `createdAt` drifts in name and default across features | one spelling, one default |
+
+The row type still derives from the merged column set: `Invoice` carries `orgId` and `createdAt`
+without a second declaration. `invoices.$tenantColumn` is `'orgId'`, and a read built without an org
+predicate throws `X_TENANCY_UNSCOPED` exactly as it would for a hand-written entity.
+
+## A mutator factory
+
+The pattern is not entity-specific. Any primitive is a function returning a value, so any primitive
+wraps:
+
+```ts
+// apps/web/shared/base/audited-mutator.ts
+import { mutator, type ActionPolicy, type LocalTx, type Mutator } from '@ultimat3/action';
+import type { Ctx } from '@ultimat3/core';
+import type { AnySchema, InferOutput } from '@ultimat3/schema';
+
+interface AuditedDef<TIn extends AnySchema, TOut extends AnySchema> {
+  readonly input: TIn;
+  readonly output: TOut;
+  readonly policy: ActionPolicy;
+  readonly event: string;
+  local(tx: LocalTx, input: InferOutput<TIn>): void;
+  server(ctx: Ctx, input: InferOutput<TIn>): Promise<InferOutput<TOut>>;
+}
+
+/** Every write in this app records who did what. `conflict` is a house decision, made once. */
+export const auditedMutator = <TIn extends AnySchema, TOut extends AnySchema>(
+  def: AuditedDef<TIn, TOut>,
+): Mutator<TIn, TOut> =>
+  mutator({
+    input: def.input,
+    output: def.output,
+    policy: def.policy,
+    idempotent: true, // required on every mutator — see Actions
+    conflict: 'server-wins',
+    local: def.local,
+    server: async (ctx, input) => {
+      const row = await def.server(ctx, input);
+      ctx.logger.info('audit', { event: def.event, actor: ctx.actor.id });
+      return row;
+    },
+  });
+```
+
+The result is a `Mutator`, which **is** an `Action` — so it keeps its route, its OpenAPI operation,
+its typed client method, its MCP tool, its job handle and its contract test, and its authz is still
+the one evaluation. The same shape works over `action()`, `job()` and `query()`.
+
+## Why nothing downstream notices
+
+| Machinery | Why the wrapper is invisible |
+|---|---|
+| the entity registry | `entity()` calls `registerEntity` itself, so registration happens whenever your factory calls it |
+| `isAction()` | structural — a function, `kind === 'action'`, a stashed declaration. It asks whether `action()` built the value, never where |
+| `registerActions(module)` | names the export **in place**, so `getAction('issueInvoice') === issueInvoice` by identity, not a copy |
+| `x verify` | no step matches source text for `action(` / `entity(` / `mutator(`. Every primitive fact reaches the gate by importing the module and reading the runtime registries. The only text scanning is for `X_*` codes |
+| manifest · admin CRUD · MCP · the five projections | all read those same registries |
+
+## Two caveats
+
+Both will bite. Both are the app's job, one line each.
+
+| Caveat | Fix |
+|---|---|
+| **A factory must add its own index for a column it injects.** `IndexInit` is keyed on the *caller's* columns — correctly, since a call site cannot name a column it did not declare. `tenantEntity('invoices', { indexes: [{ on: ['orgId'] }] })` is a compile error: `Type '"orgId"' is not assignable to type '"id" \| "memo"'` | put the index inside the factory, next to the column it belongs to — as `tenantEntity` above does |
+| **A factory building a derived schema must be generic over `AnySchema`**, exported from `@ultimat3/schema`. `<TOut extends StandardSchemaV1>` is *not* assignable to `AnySchema`, so `t.object({ data: out })` fails with `Type 'TOut' is not assignable to type 'AnySchema'` | constrain to `AnySchema`. `StandardSchemaV1` is the interop contract; `AnySchema` is the framework's own supertype and the one `t.object` accepts |
+
+## An error code is declared, not wrapped
+
+A primitive is wrapped; an error code is not. Declare each code at its own call site with
+`defineError({ code: 'X_INVOICE_NOT_FOUND', title, status: 404, cause, fix })` from
+`@ultimat3/core` — the title, the HTTP status and the class in one call. The `errors` step and the
+manifest read the `code:` literal where it is written, so a factory that takes the code as a
+parameter hides it (`X_ERROR_CODE_UNRESOLVED`). A family of codes is a prefix (`X_BILLING_*`),
+never a base class: `guards/error-declared.ts` refuses `extends UltimateError`, and
+`InvoiceNotFound.is(error)` matches the code where `instanceof` cannot — a browser's rebuilt
+refusal included.
+
+## Publish it
+
+A base that two of your apps share, or that strangers could use, is an npm package. Nothing
+registers it: the app re-exports what it wants, and the framework sees primitives.
+
+| Rule | Why |
+|---|---|
+| name it `ultimate-<name>`, unscoped, with the keyword `ultimate-package` | `npm search keywords:ultimate-package` is the directory. There is no marketplace, registry or plugin API (axiom 8). `@ultimat3/` is reserved for the framework |
+| `@ultimat3/*` in `peerDependencies` at `^<major>`, for every package it imports — never `dependencies` | the app's own install is the one copy of each registry; a second copy is a second registry the app's gate never reads |
+| ship JavaScript (or `.ts` Bun can run) with `exports` | a consumer's `bun install` is the whole integration |
+| no `tier` | tiers order the framework's own packages (`scripts/lib/tiers.ts`); a third-party package sits beside the app, below nothing |
+| guards are copied, not imported | an app's `guards/*.ts` are its own files and `x verify` runs only those. A package that ships a guard ships it as a file the README tells the author to copy |
+
+```json
+{
+  "name": "ultimate-acme-log",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": { ".": "./index.js" },
+  "keywords": ["ultimate-package"],
+  "peerDependencies": {
+    "@ultimat3/action": "^30.0.0",
+    "@ultimat3/entity": "^30.0.0",
+    "@ultimat3/jobs": "^30.0.0",
+    "@ultimat3/policy": "^30.0.0"
+  }
+}
+```
+
+The app takes what it wants by re-export, in the surface the primitive belongs to: one line,
+`export { acmeLog } from 'ultimate-acme-log';`, in `apps/web/app/acme/entity.ts`.
+
+What a consumer's `x verify` sees: the package's entity in `drift` (its table needs a migration,
+`x db gen`), its actions and jobs in `manifest` and `contract-diff`, its permissions in `policy`
+(the app's roles grant them), its MCP tools in the tool list. It
+does **not** see the package's own tests, lint or guards: those are the package's to run.
+
+A **starter** (a whole app shape, not a factory) is not a package: it is a repository a person
+copies, and its README says so. Once one exists, a community list is a wiki page added by pull
+request.
+
+## The honest limit
+
+**The registry cannot tell that an entity came from your factory, and that erasure is the feature.**
+`getEntity('invoices').describe()` reports columns, indexes and references — never `tenantEntity`.
+A factory-built primitive is indistinguishable from a hand-written one, which is precisely why the
+manifest, admin, MCP and the gate need no knowledge of your base.
+
+The consequence for tooling: a subagent, a reviewer or a doc generator learns your house base **from
+your source**, not from the registry. Name the factory for what it guarantees, keep it in one file
+under `shared/base/`, and say so in your app's `AGENTS.md` — that file exists for conventions an
+agent cannot infer.
+
+This is not a gap awaiting a fix. A registry that recorded the factory would make your convention a
+framework fact, and the next thing that read it would start depending on it.
+
+## Read next
+
+| Page | Why |
+|---|---|
+| [The eight primitives](The-Eight-Primitives) | the vocabulary you are wrapping |
+| [Entities and migrations](Entities-And-Migrations) | tenancy, invariants, what a merged column set migrates to |
+| [Actions](Actions) | the six artifacts a wrapped action still projects |
+| [`docs/idea/19-mechanism-not-convention.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/19-mechanism-not-convention.md) | axiom 8: which decisions are the framework's and which are yours |

package/wiki/CI-Parallel-Gate.md

@@ -0,0 +1,220 @@
+# CI: the gate across parallel jobs
+
+`x verify` is the gate on a laptop (its `budgets` step builds when the stats are stale): one
+process tree, bounded to a memory budget. On CI, where wall time is what a pull request waits on,
+the same gate splits across jobs — each step runnable on its own, the parallel test steps sharded —
+and one aggregate job folds the parts back into the one verdict. Green means exactly what the local
+gate's green means: every step, over the whole tree, passed.
+
+## Every step is its own command
+
+`x verify --only <step>[,<step>…] --json` runs just those steps, in one process, paying nothing
+for the others (no app load for a step that does not need one, no test run for a static step). Its
+JSON is a *part*: `x verify merge` reads it back.
+
+| Step | One job runs | Needs |
+|---|---|---|
+| `typecheck` | `x verify --only typecheck --json` | nothing |
+| `lint` `boundaries` `filesize` `package-shape` `errors` | `x verify --only lint,boundaries,filesize,package-shape,errors --json` | nothing |
+| `unit` | `x verify --only unit --shard i/n --json` | nothing (PGlite in process) |
+| `contract` | `x verify --only contract --shard i/n --json` | nothing |
+| `job` | `x verify --only job --shard i/n --json` | nothing |
+| `live` | `x verify --only live --json` (or `--shard i/n`) | the test services (`docker/test-services.env`): Postgres (`TEST_DATABASE_URL`), the logical + TLS server (`TEST_REPLICATION_URL`, `TEST_TLS_REPLICATION_URL`), pooler, standby, Redis, NATS, S3 — one process per runner |
+| `e2e` | `x verify --only e2e --json` (or `--shard i/n`) | the static build (`x build --target static --no-preflight`), Chrome — one process per runner |
+| `eval` | `x verify --only eval --json` | nothing; baselines committed |
+| `drift` `contract-diff` | `x verify --only drift,contract-diff --json` | nothing |
+| `budgets` `seo` `i18n` `policy` | `x verify --only budgets,seo,i18n,policy --json` | the static build — `budgets` weighs `.x/build-stats.json` |
+| `manifest` `roadmap` | `x verify --only manifest,roadmap --json` | nothing |
+
+The grouping is yours: any split works as long as every step lands in exactly one part (or, for a
+sharded step, in shards `1..n` exactly once). `x verify merge` refuses anything else.
+
+## `--shard i/n` — the parallel test steps
+
+```bash
+x verify --only unit --shard 2/4 --json > part-unit-2.json
+```
+
+- Only with `--only`, and only over the test steps: `unit`, `contract`, `live`, `job`, `e2e`
+  (any other step is `X_VERIFY_SHARD_INVALID`). `live` and `e2e` stay ONE process inside a shard —
+  serial means one replication slot and one browser per machine, and each runner starts its own
+  services — so when sharded, their shards split across runners, never across workers. `As of 2026-11-07` this
+  repository's CI still runs each as one part: its longest job is a `packages` coverage shard, so
+  a second live or e2e runner would cost runner minutes and save no wall clock.
+- The split is a pure function of the step's **sorted** file list: round-robin by default, so job
+  2 of 4 is the same files on every runner and on your laptop. `--timings <file>` (Bun's
+  `--timings` file, e.g. the `.x/test-timings.json` every parallel run refreshes — cache it
+  between CI runs) splits greedy longest-first instead; a file the timings do
+  not know is costed at their median.
+- The part's JSON carries `data.shard` (`index`, `total`, and per step the `corpusHash` of the whole
+  list plus the `files` this shard ran), and each step carries the same facts as `steps[].shard`.
+- A shard whose slice is empty, or ran only skipped tests, is not red: the zero-tests floor
+  (`x.verify.json`) is applied by `merge`, on the counts summed over every shard.
+- An app's coverage floor is not judged by a shard — one slice cannot hold it. The shard is green
+  on coverage and carries what it covered in `data.coverage.unit.facts`; `merge` folds every shard and judges
+  once (`X_COVERAGE_BELOW_FLOOR`). Shards that carry nothing fold to 0%, never to a skip.
+- Under `--json` each finished step is one line on stderr (`{"step":"unit","ok":true,"ms":61250}`),
+  so a cancelled job's log ends on the last step that finished. Redirect stdout only.
+- A red shard reproduces locally with the same flags.
+
+## `x verify merge <part.json…>` — the verdict
+
+```bash
+x verify merge parts/*.json --json
+```
+
+Reads each part (the **last** JSON line of the file, so an older scaffold's `bun run check --json` output works too) and
+answers the gate:
+
+- every step of the gate appears — `X_VERIFY_MERGE_INCOMPLETE` names a step no part ran;
+- a sharded step has shards `1..n` exactly once, all with one `corpusHash` — a missing shard, a
+  duplicate, or two corpora (jobs on different commits) is named;
+- and their `files` partition that corpus: a file in two shards, or in none (the union does not
+  hash to `corpusHash` — shards split by two rules, one with `--timings` and one without), is named;
+- the zero-tests floor is applied to each sharded step's summed counts;
+- an app's coverage floor is applied to the fold of a sharded `unit` step's `data.coverage.unit.facts`;
+- a red step in any part is red here, with its findings and output kept.
+
+The merged document has no `notAGateRun` — it is the gate's answer — and its `durationMs` is the
+slowest part's, which is the wall time CI waited. A part that is not an `x verify --json`
+document is `X_VERIFY_MERGE_INPUT` — and so is a step whose `durationMs` is not a number or whose
+`findings` are not each a `code`, `cause` and `fix`.
+
+## A GitHub Actions workflow
+
+```yaml
+name: ci
+on: [push, pull_request]
+
+jobs:
+  part:
+    name: ${{ matrix.name }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false # every part must upload, red or green: merge decides
+      matrix:
+        include:
+          - { name: typecheck, only: typecheck }
+          - { name: static, only: 'lint,boundaries,filesize,package-shape,errors' }
+          - { name: unit-1, only: unit, shard: 1/4 }
+          - { name: unit-2, only: unit, shard: 2/4 }
+          - { name: unit-3, only: unit, shard: 3/4 }
+          - { name: unit-4, only: unit, shard: 4/4 }
+          - { name: contract-1, only: contract, shard: 1/2 }
+          - { name: contract-2, only: contract, shard: 2/2 }
+          - { name: job, only: job, shard: 1/1 }
+          - { name: tail, only: 'eval,drift,contract-diff,manifest,roadmap' }
+          - { name: built, only: 'e2e,budgets,seo,i18n,policy', build: true }
+          - { name: live, only: live, postgres: true }
+    env:
+      TEST_DATABASE_URL: ${{ matrix.postgres && 'postgres://postgres:postgres@localhost:5432/postgres' || '' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - if: matrix.postgres # live needs logical replication: a service container cannot pass -c
+        run: |
+          docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:17 -c wal_level=logical
+          until docker run --rm --network host postgres:17 pg_isready -h localhost; do sleep 1; done
+      - if: matrix.build
+        run: bunx x build --target static --no-preflight
+      - name: x verify (one part)
+        run: |
+          bunx x verify --only '${{ matrix.only }}' \
+            ${{ matrix.shard && format('--shard {0}', matrix.shard) || '' }} \
+            --json > "$RUNNER_TEMP/part.json" || true
+      # Outside the checkout: the file is open and empty while the part runs, and `lint` walks the tree.
+      - uses: actions/upload-artifact@v4
+        with: { name: 'part-${{ matrix.name }}', path: '${{ runner.temp }}/part.json' }
+
+  check: # the one required status check
+    needs: part
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - uses: actions/download-artifact@v4
+        with: { pattern: 'part-*', path: parts }
+      - run: bunx x verify merge parts/*/part.json
+```
+
+Make `check` the single required status. A job that crashed before uploading its part is not a
+pass: its steps are missing and `merge` names them.
+
+## A push a green PR run already tested
+
+Merging an up-to-date green pull request pushes a tree CI has already tested. `x ci tested` says
+so — `data.tested` — and every job that run answered skips. As of 2026-11, 55 of this repository's
+last 81 pushes to `main` were such a tree.
+
+| `tested: true` needs | Why |
+|---|---|
+| the subject ends `(#N)` | only a merge of PR N is a candidate |
+| PR N merged as **this** commit | a `(#N)` typed by hand proves nothing |
+| its head is in this repository | a fork writes its own workflow; its green is not reused |
+| its head tree is this tree | a base that moved after the run is an untested merge |
+| the newest same-repository run on that head concluded `success`, under `--max-age` (default `24h`) | the runner image and the registry move |
+
+Any doubt — a condition unmet, `gh` absent, an API that did not answer — is `false`: a full run.
+The command exits 0 on every answer.
+
+```yaml
+jobs:
+  tested:
+    runs-on: ubuntu-latest
+    permissions: { contents: read, actions: read, pull-requests: read }
+    outputs:
+      tested: ${{ steps.tested.outputs.tested }}
+    steps:
+      # Only a push asks. Never a release commit: what publishes is a run of everything.
+      - if: github.event_name == 'push' && !startsWith(github.event.head_commit.message, 'release')
+        uses: actions/checkout@v4
+      - if: github.event_name == 'push' && !startsWith(github.event.head_commit.message, 'release')
+        uses: oven-sh/setup-bun@v2
+      - if: github.event_name == 'push' && !startsWith(github.event.head_commit.message, 'release')
+        run: bun install --frozen-lockfile
+      - id: tested
+        if: github.event_name == 'push' && !startsWith(github.event.head_commit.message, 'release')
+        env: { GH_TOKEN: '${{ github.token }}' }
+        run: |
+          bunx x ci tested --repo "$GITHUB_REPOSITORY" --json > tested.json
+          echo "tested=$(jq -r .data.tested tested.json)" >> "$GITHUB_OUTPUT"
+
+  part:
+    needs: tested
+    if: ${{ !cancelled() && needs.tested.outputs.tested != 'true' }}
+    # … the matrix above, unchanged
+
+  check:
+    needs: [tested, part]
+    if: ${{ !cancelled() && needs.tested.outputs.tested != 'true' }}
+    # … unchanged
+```
+
+Each reused job carries that **one** `if` and nothing else, so a skip has exactly one cause:
+`tested` said true. `!cancelled()` is load-bearing: a bare `needs.…` condition implies
+`success()`, and a red or timed-out `tested` would skip every job instead of running them. A
+reader of a skipped check (a deploy, a required status) can then accept the skip only beside a
+green `tested` check. On a
+pull request every step of `tested` is skipped and nothing below it is. The cost: one near-empty
+job's runner acquisition ahead of every other job, a few seconds.
+
+## Width and memory, per job
+
+Each job sizes its own test width the same way the laptop does (`x verify` prints it on the step
+line, e.g. `3 workers (budget 4.0 GB)`): a budget of `max(2.75 GiB, 25% of the runner's RAM)`,
+1.25 GiB planned per worker, never more workers than cores. On a 16 GB `ubuntu-latest` that is 3
+workers; a 62 GB, 16-core workstation plans 12 (`As of 2026-11-07`, when the fixed 4 GiB cap went —
+the machine-wide slot pool is what keeps two runs on one box inside one budget). `ULTIMATE_TEST_MEMORY_BUDGET=6g` or `ULTIMATE_TEST_MAX_WORKERS=4` override it; `--workers`
+wins over both. The machine-wide slot pool (see [Testing](Testing#memory-width-and-isolation))
+has nothing to share on a one-job VM; `ULTIMATE_TEST_SLOTS=0` turns it off.
+
+## Skipping the build's duplicate preflight
+
+`x build` runs the six static steps before it builds (typecheck, lint, boundaries, filesize,
+package-shape, errors) so a bare build never ships an artifact from a tree that does not typecheck.
+In a gate that runs those steps anyway, `--no-preflight` skips them — `x verify`'s `budgets` step does
+when it builds, and so does the `built` job above, whose build first leaves `budgets` fresh stats and
+no second build. The default stays safe.