# Upgrading **`As of 2026-08`. Semver applies from here.** A breaking change to a documented API needs a major. Every `@ultimat3/*` package moves in lockstep — never mix versions. `x new` declares them at the exact version and `x upgrade` rewrites every pin it moves exact (`20.1.0`, no caret), on purpose — a caret is how `^19.0.0` beside `^19.4.0` came to be mixed, and a range is a silent upgrade that skips the hop's codemods. `x doctor` reports a ranged pin (`X_FRAMEWORK_PIN_RANGE`), naming the exact version to write. > **From v31, one major per 90 days.** The window, what semver covers, the support window and the security exception: [Stability](Stability). A removal now ships its `@deprecated` alias for at least one minor before a major takes it, so `x upgrade` across one major names no edit a minor did not already warn about. The 30 sections below stay as they are. **Thirty majors have shipped since 1.0.0, and this page walks all thirty** — 2.0.0's 33 entries joined it `As of 2026-08`, and `scripts/changelog-check.ts` now refuses a summary row whose section the page does not carry, which is how they were missing for six releases. [`docs/changelog/`](https://github.com/developerz-ai/ultimate/tree/main/docs/changelog) — one file per release, indexed by [`CHANGELOG.md`](https://github.com/developerz-ai/ultimate/blob/main/CHANGELOG.md) — is the source for the majors it still carries, and `git show v:CHANGELOG.md` for the ones it has archived; none ships a codemod, so every entry is a manual edit the entry itself names. **One section per major**, newest first — read the ones between your pin and your target, oldest first. | From → to | Breaking entries | Read | |---|---|---| | 30.x → 31.0.0 | **74** — plan 101 final hardening: an `AuthServerStore` with a required `getCode` and a `pollDevice` that takes the client; a drain that abandoned work exits 70; validation issues capped at 100 and causes at 4 KiB; storage keys, header values and revision-pinned reads; one policy gate for action and query; a paged read capped at 500 rows over the wire; a `PreferenceStore` asked once per 500 recipients; remote MCP tools not re-exposed unless opted in; **a `(tenant, pk)` index on every tenant table that needs one `x db gen`**; an `IsrStore` that may answer with a promise; `localhost` no longer admitted by a wildcard `allowHosts`; span exporters installed by subscribing to `span.end` on the one instrumentation bus; an app's own Sentry transport replacing the `SENTRY_DSN` one, local sinks marked; `jobs.queues` defaulting to `['default']`; OpenTelemetry's stable http, messaging and gen_ai span attributes; a `defineStorage` disk that reports on the bus; OTLP logs and the semconv histograms on every boot; db, entity, policy and cache observer slots replaced by bus events; a database span for every statement in production; a bus installed from `runtime.ts`, never a realtime setter; one `ADAPTER_PORTS` table and core installers on `@ultimat3/core/adapter`; a `SecretSource` port for the master key; `realtime.transport`/`urlEnv` removed from `app.config.ts`; job, event-bus, mail, idempotency, meter and notify installers on each package's `./adapter`, swapped from `runtime.ts`; the rate-limit store, auth limiters, TOTP guard and scrape driver installed the same way, `httpServer` taking no store; one core clock for scraping and flags; admin audit sinks typed by core's `AuditSink`; the AI gateway installed only as `aiGateway`, never through `configureAi`; factories with `belongsTo`/`hasMany`, `buildList`/`createList` and a `create()` that answers the stored row; `runtime.syncAuthenticate` removed, every port a `runtime.ts` field and `/packages/db/factories.ts` linted on `unit`; the audit sink, error reporter and KDF gate installed on `./adapter`, `runtime.storage` a `StorageDriver` and the last four ports `runtime.ts` fields; port suites on `@ultimat3/testing/conformance` only; a malformed uuid refused before the statement; a push subscription that always names its person; no memory delivery ledger outside development; the embedder and semantic cache as `runtime.ts` ports, `configureAi` keeping `redact` only; metric exporters subscribing to `metric.export` on the bus; sign-in routes at `/auth/sso/:provider` for OAuth and SAML alike; the raw-CDP launcher imported from `@ultimat3/scraping/cdp` only; no framework mails — an app declares its own; `noopMetricExporter` deleted; `AuditPrimitive` gaining `'job'` for GDPR erases; the storage quarantine flow replaced by the scanner's `hold` verdict; one retry shape, core's `RetryPolicy`, for the AI gateway, realtime redials and job `jitter`; `setLogSink` replaced by `installLogSink`, which answers its release; realtime's `Row` renamed `LiveRow`; `Surface` and `SURFACES` imported from `@ultimat3/core` only; a `SearchIndex` with a required `list` and a `reindex()` that sweeps what the table lost; `defineApi` the one way to register actions and queries; `x g app`/`package` refusing slice flags; a searchable row's version strictly increasing, advanced by a custom store in its own write; a targeted upload grant refused while a scanner is installed; a write-path search document replacing a tombstone; an instant in a key spelled ISO 8601; every package's `.` barrel cut to the app API, ports on `./adapter` | [the `31.0.0` section](#30x--3100-entry-by-entry), in order | | 29.x → 30.0.0 | **143** — plan 101 (ten waves), issues #990–#999 and two find-and-fix sweeps: a write past its deadline that rolls back, a closed-transaction refusal, a two-release column drop, **same-tenant composite keys that need one `x db gen`**, `upsertAll` overwriting only what it names, every agent and MCP call held by `mcpConfirmations`, `'null'` refused in `cors.origins`, `isr` and `static` that render as nobody, a query-free `isr` key by default, a pool that refuses past `acquireTimeoutMs`, an upload grant bound to its declared size, mail that refuses an unresolved key, a problem document with `retry`, a worker retire on by default, required `StorageDriver`, `JobDriver` and `PoolProfile` members, a `budgets` step that builds before it weighs, no `bin/check` in a new app, `ui`'s Standard Schema copies removed, no vendor link on the default error page, the render brands at `@ultimat3/core/render-node` only, a required `enqueueMany` on every `JobHandle`, `JobsFacade` and `JobDriver`, an outbox relay that claims 500 rows a pass, `'browser'` in `ERROR_SOURCES`, `assets` and `clientErrors` on `AppConfig`, `pwa`'s `retentionPlan` and `retainBuildIds` removed, a `DefineEvalInput` union, `MCP_PROTOCOL_VERSION` deleted, an MCP revision decided per request with `2026-07-28` the newest, a cross-origin `POST /mcp` refused with `'origin-refused'` in `McpAuthRefusal`, `x mcp serve` answering only a loopback Host, a raw `WorkloadToken` payload, a role that refuses a half-loaded app, a query's own MCP tool wording, no `QueryPoll.ms`, an exercise refused outside `bun test`, an accessibility audit on every `e2eTest`, factory values read off each column's declaration, a memory transaction that holds every write inside it, a 21st gate step that runs every primitive with no test written, a finding for an untenanted child of a tenant-owned table, a memory transaction that refuses a write after it ended and runs nested effects at the root's commit, required `failureCapture` and `time` on `AppConfig`, an `x_failures` table in the schema dump, a description on every page `/llms.txt` lists, a required `TimeZoneConfig.detectedCookie`, an MCP resource read handed its caller, a required `DevCapabilities.queryGraph` and `DevSources.mailTemplates`, an exercise step that plans every statement and reds an unindexed read or a loop over rows, an `OpenGraph` that is a hosted `image` or a captured page and never both, a `postgresAuthAdapter()` that reads the ambient client per call, a `refetch()` that returns a promise, 48 more `UI_KEYS` in a module namespace, charts that draw `null` and negative values and refuse a series that does not match its keys, a two-mode `TabsProps`, a command palette that ranks, two more contrast pairs on `bg-soft`, every `mock.module` put back at its file boundary, a static export that writes image variants as files, `/assets` answering only the variants it declares, an island `mount` that must return its disposer, passkey storage on every `AuthAdapter`, a per-call rate limit split from the fixed one, a signed vote in `McpConfirmationStore.decide`, a meter in the manifest and its contract diff, a hand-rolled websocket refused, bad-token counting on every `PushDeviceStore`, exact history images on Postgres, a policy on every multipart part and completion, `LiveHandle.retry`, a Bearer-only CSRF exemption, no `enqueueInTx`, and an event id from `EventLookup.find` | [the `30.0.0` section](#29x--3000-entry-by-entry), in order | | 28.x → 29.0.0 | **2** — **Bun 1.4.4 as the floor**; a `WORKER_QUEUES` entry the app does not know refuses the worker's boot | [the `29.0.0` section](#28x--2900-entry-by-entry), in order | | 27.x → 28.0.0 | **2** — **Bun 1.4.3 as the floor**; `@ultimat3/ui/jsx-probe` and its `probe`/`unprobe` removed | [the `28.0.0` section](#27x--2800-entry-by-entry), in order | | 26.x → 27.0.0 | **2** — `AsyncContext.exit` required; **`/_storage` and `/media` refuse a key outside every `org//` prefix unless `defineStorage({ shared })` lists its prefix**, and `Storage.isShared` required | [the `27.0.0` section](#26x--2700-entry-by-entry), in order | | 25.x → 26.0.0 | **6** — an OAuth login that verifies the id token's signature against the provider's published key set by default; Apple out of the OAuth built-ins; `ServerHandle.describe()` deleted; no `api/**/route.ts` file kind; `recover: 'agent'` deleted and scraping at tier 4; one CLI verb per command (`list`, `show`, `delete`) | [the `26.0.0` section](#25x--2600-entry-by-entry), in order | | 24.x → 25.0.0 | **40** — Bun 1.4.2 as the floor; a closed `app.config.ts` that refuses an undeclared key and every deleted one by name, the locales in `defineCatalogs()`; `assertEnvExample`, `resolveSpeculation` and `normalizeAuditRecord` removed, `AuditRecord.name` / `.primitive` required, every value imported from the package that declares it; one spelling per factory, never `create`; one `Page` (`entity`'s `Page` and `storage`'s `ListPage` removed), `http.drainTimeoutMs` and `http.buildIdHeader` removed, a `bearerMount` catch-all; one MCP projection (`toolFrom`), one page shape (`nextCursor`, `hasMore`), a per-action rate limit that is the action's own, a redaction-keeping `IdempotencyStore`, `SQL_*` statements off the barrels, the NATS job driver stub deleted, required `WebhookLedger.isDisabled` and `ChangeEvent.write`; one MCP block in core with `McpExposure` and its `name` removed, `contentHash` removed, a scopes map that names every tool, a required `DigestAppend.appender`; **no model chosen for an app — it registers its own and names one**; a widened `Menu` `aria-controls`, a private `FakeElement.listeners`, offline scrapes that state their robots reason, `nearest` removed, a `--cdp-url` capture that fails closed, a page that may not import a repo, ai's `contentHash` renamed `promptHash`, one meaning per value name, every job ack counted; a per-queue `jobs.concurrency`, the framework's own secrets in `.env.example`, an e2e app that inherits no `DATABASE_URL`; a two-argument `resolveGrants`, `WORKER_QUEUES` as the exact set, a `jobWorker` default of 8 slots, and `ChangeEvent.table` | [the `25.0.0` section](#24x--2500-entry-by-entry), in order | | 23.x → 24.0.0 | **202** — a calendar check on `t.date`, `t.url` refusing what the parser would cut, plain objects only, a default its own schema must accept, decimal-only coercion, a stricter `defineConfig`, an unknown `LOG_LEVEL` refused, `retry` and `createFlightGate` refusing a bound that is not one, a child context that aborts with its parent, compound credential names redacted, error `meta` under `extra.meta` in the monitor envelope, per-signal OTLP headers, a sampler that ignores a leftover ratio, wildcard host rules that stop at the network edge, an empty cursor secret counted as unset; then tier 1 — `t()` always interpolating, interval crons through both passes of a fall-back hour, exact cron names, `formatRelative` requiring a zone, a transaction that rejects when its body swallowed a failed statement, `X_DB_COMMIT_UNKNOWN`, nested transaction options refused, sibling nested scopes run in turn under a 30 s wait, a `changed-primary-key` drift kind, `introspect()` reporting catalog types, flag expiries that must be ISO; then an `e:` purge key on every tagged response, WebP-only `responsiveImage()` by default, `promoteAttachment` requiring its policy, a required `StorageDriver.stat()`, an optional `lastModified`, a `get()` ceiling, image variant keys that keep the source extension, `v2` signed URLs that name their disk; then a required `Driver.transactor()`, `dbDrift` leaving entity, a preload ceiling, `assertAllowed` throwing the decision's own code, a 401 for a denial with no actor, a malformed policy decision that denies; then `ctx.peer` behind its own switch, anonymous browser writes held to same-origin, failed sign-ins metered to a 429, health bodies trimmed for strangers, a `max-age` treated as a shared-cache offer, a body refused without a `content-type`, an awaited browser `close()`; then auth — **a sealed MFA secret that needs `x auth seal-mfa` run once**, a retired `x_auth_failures` table, a reservation-shaped `AuthLimiter`, API keys bound to their owner and its grants, `X_MFA_REQUIRED` carrying a challenge, eight more required `AuthAdapter` members, `oauthLogin` requiring `APP_URL`, an e2e `offline()` that rejects when a page refuses the switch; then `compareValues` removed from query, a `.limit()` that bounds every page, a `single` read answering one row over MCP, `admin:*` declared by `defineAdmin()` rather than by import; then `mutator()` requiring `idempotent: true`, a regenerated `openapi.json` and schema dump, idempotent actions and cache busts that settle with the commit, a `manifest` step that fails on a stale `openapi.json`; then jobs — a final-attempt lapse buried instead of re-claimed, `cancel` refusing finished jobs, step writes fenced on the claim, a uuid-only `runId`, an awaited `purgeExpired()`, `x_job_events` swept; then realtime — **three operator steps: `APP_URL` on the `sync` role as the whole origin allow-list, `REPLICA IDENTITY FULL` for channels with params, and a replication connection that refuses a weak password without TLS** — rows revived across the bus, five interfaces with new required members, stricter channel re-authorization, and an offline queue abandoned when the principal changes; then a catch-all route that answers its bare prefix, a zero-length ISR `ttl` refused, `NativeReason` gaining `'unparsable'`, CSS-module classes scoped in selectors only with every scoped name changed once, a positional `CompiledPattern.specificity`, and a notification tap that opens this app only; then ui — two required `ThemeEnv` members, a fixed `theme.defaultMode` that a "System" pick and an OS change no longer override, the deprecated theme inline script removed, a `Popover` trigger whose `aria-controls` can be absent, and file controls that post only the files they accepted; then a required `peek` on every rate-limit store and an address refused on required routes once its failed credentials are spent; then mcp — a 5xx cause hidden from a remote caller, `db.query` refusing SQL run as text, a meta tool without `destructive` listed as a query, list calls held to their whitelist, failed tokens metered per address; then a `send()` that waits for its transaction's commit and one recipient rule on every mail driver; then `x_notify_digests` in the schema dump, queries publishing `input`, a non-finite manifest fact refused, and a dropped NOT NULL default classed as breaking; then ai — an atomic `BudgetStore.take`, a required `Gateway.callLedger(keys)`, **gateway `actor` and `org` ceilings that count every model call's caller**, a 5xx tool cause hidden from the model, `fnv1a` removed and `HashEmbedder` vectors changed, an unknown finish reason read as truncated, an unscoped vector read refused inside an org's request, a required `VectorStore.prune`, `chunk()` owning `source`, and `numericTolerance` refusing a bound that is not one; then testing — a coded `app()` before boot, `assertDeterministic` by canonical form, `frozenClock` announcing its moves, one module instance per island mount; then scraping — a proxy switch in launch args refused, a required browser-level `target()`, a jar-less browser refused, `burnSession` comparing `savedAt`, `maxDrop` held to a fraction, credential-shaped URL redaction, a declared header that replaces the session's, wildcard hosts resolved and pinned, robots redirects screened per hop, and an undated recording read as stale; then admin — a nullable keyset bound, **edit forms that post `_version` and a 409 for a stale edit**, a required `AdminFormProps.version`, a `'stale'` `CrudResult`, creates and updates decided on what they write, tenant-scoped audit screens, actions and batches that commit with their audit entry, `?scope=*` for no scope, and stricter list filters; then a split sitemap's parts under `/sitemaps/`, a permission's declaration site restored with it, then cli — an export directory a build must prove is its own, a static build that fails on a module that does not load, unread build flags refused, a `--dry-run` that is the write plan, generator names and API bindings refused before writing, an unowned path read as root-wide, test discovery anchored at the root, guards and app entry files under `filesize` and `errors`, SEO answers kept an hour, a scaffold pinned to the repository's `solid-js` and typechecking the root program, **a permission only `defineAdmin()` declared refused by the `policy` step**, **an unrecorded `REPLICA IDENTITY FULL` refused by the `drift` step**, and a registry snapshot that carries permission sites; then a handler's own CSP kept beside the app's, `x routes --json` in every route fix, **serving roles that leave the framework schema to `ROLE=migrate`**, decimal-only ports and proxy hops, stored files served as sandboxed downloads, no readiness grace off the listening roles, a replicator ready only while its stream runs, and cli commands that exit 1 on an unknown name or any finding, a `/_x` SQL panel that runs only a same-origin POST from this machine, and stricter `x doctor`, `x jobs`, `x shot`, `x dev`, `x verify merge`, `tests.run`, `x mcp serve` and `x routes`; then `checkErrorCodesThrown` waiving only the codes a list names; then **a chart that renders a NetworkPolicy per role, a bounded `/tmp` and a Secret every role must have**, and a sync listener on its own port at port 0 | [the `24.0.0` section](#23x--2400-entry-by-entry), in order | | 22.x → 23.0.0 | **66** — an image line that prebuilds the island store, a worker that imports less of the app, a committed schema dump, a stated coverage floor, step deadlines, raw browser requests refused by the gate, a typed-handle repo with `list(limit)` and a generated query with no `orgId` input, admin label keys the `i18n` step now checks, every hand-written job driver and store fenced on its claim, `runJobs` through a real worker, a framework-served admin that replaces the host's pages and now serves the jobs dashboard, an async `AuditLog`, admin writes held to the row scope, and sealed scraping sessions that discard what was stored before | [the `23.0.0` section](#22x--2300-entry-by-entry), in order | | 21.x → 22.0.0 | **23** — two date readers that refuse a non-ISO string instead of reading it in the host's zone, a `helm` release named after the app, `channel()` requiring a policy, a per-mutation outbox, a `sync` role that refuses to boot with nothing to deliver, boot-owned auth tables, `x shot` on raw CDP with no `puppeteer-core`, `realtime.transport` deciding the bus, and removed exports: `Result`, realtime's `backoffDelay`, the e2e driver's move to `@ultimat3/testing`, `startLiveReplicator` leaving it, unreferenced package internals and 236 of the CLI's, a one-time `x db gen` for a re-stamped schema hash, and a query that filters on a column its loader never selected refusing instead of answering `[]` | [the `22.0.0` section](#21x--2200-entry-by-entry), in order | | 20.x → 21.0.0 | **27** — `AsyncState`'s import path, `custom(merge)` over rows rather than outputs, realtime's second conflict vocabulary removed, `isSuperseded` widened, one error path for every typed client, the record envelope on actions that return entity rows, the service worker's outbox flush replaced by a message to open tabs, a third client-scope answer, `last-write-wins` refused without a clock, the realtime client rebuilt around one page store and one read hook, Compose requiring `SYNC_URL`, `x verify`'s duration as wall time, and channels served by declaration only. The client data layer, one entry per removed surface | [the `21.0.0` section](#20x--2100-entry-by-entry), in order | | 19.x → 20.0.0 | **2**, both `@ultimat3/ui` component behaviour and neither a type change — a `DataTable` that keeps its rows while reloading, and a `Button` whose `loading` no longer sets the native `disabled`. Nothing fails to compile; what changes is what a screen does | [the `20.0.0` section](#19x--2000-entry-by-entry), in order | | 18.x → 19.0.0 | **2**, both from the same hole — the service worker had no build behind it, so the config key that steers it and the route it falls back to both had to move | [the `19.0.0` section](#18x--1900-entry-by-entry), in order | | 17.x → 18.0.0 | **5** — a runtime floor that was a minor behind what the CLI emits, two PWA config surfaces that had to grow before an app could be installable, a `--json` shape, and one scraping interface | [the `18.0.0` section](#17x--1800-entry-by-entry), in order | | 16.x → 17.0.0 | **3**, all one sweep — a numeric option that used to accept `NaN` refuses it, at boot or at the call boundary rather than mid-request | [the `17.0.0` section](#16x--1700-entry-by-entry), in order | | 15.x → 16.0.0 | **1** — `matches(/re/)` refuses a construct the two regex engines read differently, at `entity()` time | [the `16.0.0` section](#15x--1600-entry-by-entry), in order | | 14.x → 15.0.0 | **1** — `DriftKind` gains a member, so an exhaustive `switch` with no `default` stops compiling | [the `15.0.0` section](#14x--1500-entry-by-entry), in order | | 13.x → 14.0.0 | **8** — two are security fixes with a behaviour change (a frame verb, a session key), four are types that refused what the runtime already did, and two remove API nothing called | [the `14.0.0` section](#13x--1400-entry-by-entry), in order | | 12.x → 13.0.0 | **2**, both narrow: a service factory's parameter type, and one deleted `PageLike` member with zero call sites anywhere in the repository | [the `13.0.0` section](#12x--1300-entry-by-entry), in order | | 11.x → 12.0.0 | **16**, from the widest sweep since 4.0.0 — a keyset defect that dropped rows, a name that reached the DDL unchecked, and eight interfaces that gained a member | [the `12.0.0` section](#11x--1200-entry-by-entry), in order | | 10.x → 11.0.0 | **7** | [the `11.0.0` section](#10x--1100-entry-by-entry), in order | | 9.x → 10.0.0 | **19** | [the `10.0.0` section](#9x--1000-entry-by-entry), in order | | 8.x → 9.0.0 | **5** | [the `9.0.0` section](#8x--900-entry-by-entry), in order | | 7.x → 8.0.0 | **6** | [the `8.0.0` section](#7x--800-entry-by-entry), in order | | 6.x → 7.0.0 | **4** | [the `7.0.0` section](#6x--700-entry-by-entry), in order | | 5.x → 6.0.0 | **7** | [the `6.0.0` section](#5x--600-entry-by-entry), in order | | 4.x → 5.0.0 | **2**, over six surfaces, each a declaration that promised what the code did not do | [the `5.0.0` section](#410--500-entry-by-entry), in order | | 3.0.0 → 4.0.0 | **25**, from a sweep that closed every known gap | [the `4.0.0` section](#300--400-entry-by-entry), in order | | 2.0.0 → 3.0.0 | **10**, all from a five-agent bug sweep | [the `3.0.0` section](#200--300-entry-by-entry), in order | | 1.x → 2.0.0 | **33** | [the `2.0.0` section](#1x--200-entry-by-entry), in order | | 11.x → 20.0.0 | **47** | every major section `docs/changelog/` still carries, oldest first | An entry is a line a release file in `docs/changelog/` marks `BREAKING —`. The count is derived, never curated: ```sh cat docs/changelog/*.md | grep -cE '^(- \*\*|### )BREAKING —' # 634 As of 2026-11-10 — every RELEASED section ([Unreleased] stays in CHANGELOG.md), which is the # sum of every row above whose section docs/changelog/ still carries. ``` How that total is counted, and why `[Unreleased]` is cut: the header of [`scripts/changelog-check.ts`](https://github.com/developerz-ai/ultimate/blob/main/scripts/changelog-check.ts). Each entry changes a surface the table below covers. > **Move to whatever `latest` is** — only the [footer](_Footer) stamps the number, because a version written into a page goes stale on the next tag. All 31 workspaces resolve at one version — 29 `@ultimat3/*` plus the unscoped `create-ultimate`, `@ultimat3/scraping` and `@ultimat3/flags` included — and every tarball since 3.0.0 was published by the release workflow with a provenance attestation. Resolve before you pin, never take it from this page: | Check | Command | Answer that means "go" | |---|---|---| | what `latest` is | `npm view @ultimat3/core version` | the version you are pinning | | that a package resolves at it | `npm view @ultimat3/scraping@ version` | that version, not `E404` | | that the tarball is attested | `npm view @ultimat3/core dist.attestations` | a `provenance` object | | every name that must move together | `bun run scripts/release-workflow.ts --json` | the 30 derived names — check each | **A hop's gate, handed to CI in part.** `As of 2026-11-19`. A bare `x upgrade --json` runs the full `x verify` and is the default. On a loaded machine, `x upgrade --only [,…] --json` runs the hop's `x verify` on those steps alone — the list `x verify --only` takes, refused the same way — and every other stage of the hop unchanged. It is **not the full gate**, and the report says so: `proof: "verify-only"`, `verify.only[]` the steps run, `verify.notRun[]` the rest, a summary reading `NOT THE FULL GATE`, and `then` naming `x verify --only --json`. Commit the hop on a branch and let CI run the rest; the hop is proven when that is green. ```sh x upgrade --only typecheck,lint --json # here: two steps, and the hop # then, in CI on the hop's commit: x verify --only --json ``` To leave only `unit`, `live` and `e2e` to CI, name every other step: `x help verify` lists them in the gate's order. ## 30.x → 31.0.0, entry by entry `As of 2026-11-10`, released: the 74 breaking entries of `CHANGELOG.md`'s `## 31.0.0` section, in their order. No legacy path, no codemod, no shim. v31 is the stable line — the next major waits for its window ([Stability](Stability)). **Move TypeScript to `^7.0.2` first** — `bun add -d typescript@^7.0.2` in every workspace that declares it, then `bun install`. `@ultimat3/cli` ships its `.ts` source, and your typecheck reads it: under TypeScript 6 with `exactOptionalPropertyTypes` (on in every `x new` tsconfig), `node_modules/@ultimat3/cli/src/cdp-shot-keys.ts` fails TS2769 at 26:43, so the gate is red before any entry below applies. Since 22.0.0 ([the `22.0.0` section](#21x--2200-entry-by-entry)); `x upgrade` moves the `@ultimat3/*` pins, never `typescript`. From 31.2.0, `x doctor` raises `X_TYPESCRIPT_VERSION` per lagging manifest, its fix the exact `bun add`, and `x upgrade` reports the same lag in `data.typescript` — reported only, never written. `x new` scaffolds `TYPESCRIPT_VERSION` (`packages/cli/src/templates/scaffold-repo.ts`). `As of 2026-11`, measured: TypeScript 6.0.3 reports TS2769 on that file, 7.0.2 nothing. ### The upgrade, top to bottom | # | Do | What you see until you do | Entries | |---|---|---|---| | 1 | commit, then `bunx @ultimat3/cli@latest upgrade --json`: it pins every `@ultimat3/*`, installs and runs the gate | `X_UPGRADE_DIRTY_TREE` on a dirty tree | — | | 2 | `x verify --only typecheck` and close every error: a hand-written `AuthServerStore` or `PreferenceStore`, an import of a removed Redis script or of `MAX_WIRE_ISSUES`, a hand-built `ActionDeniedError`/`QueryDeniedError`, a `set*` job/event-bus/mail/idempotency/meter/notify setter (a `runtime.ts` field), a factory's `associate()` or `buildMany`, a `setAuditSink`/`configureKdfGate`/`configureErrorReporting({ reporter })` call, a `runtime.storage` built with `defineStorage`, a `PushSubscriptionRecord` with `actorId: null`, a `configureAi({ embedder, semanticCache })` or `configureMetrics({ exporter })` call, an import of a framework mail or `noopMetricExporter`, an exhaustive `switch` over `AuditPrimitive` or `ScanVerdict`, `grantUpload({ quarantine })` or `releaseQuarantine`, an import of a name that left a package's `.` (entry 74's list), a gateway `retry` or realtime `backoff` in the old field names, a boolean job `retry.jitter`, a `setLogSink` call, realtime's `Row`, `Surface` from seo or `SURFACES` from render, a hand-written `SearchIndex` without `list`, a `registerActions`/`registerQuery` call | TS2741, TS2554, TS2305, TS2322 | 1, 6, 10, 14, 18, 29, 36, 40, 43–45, 48, 50, 51, 54–65, 67, 71, 72, 74 | | 3 | `x verify --only unit,contract`: shorten a name over 63 bytes, write each `cors.origins` entry as its own `URL.origin`, rename an unsafe storage key or header value, switch a `fromDecimal` branch to `X_MONEY_NOT_DECIMAL`, read a truncated validation through `issuesTruncated`, pass `expose: true` to an `mcpTools()` whose tools your `/mcp` serves, name `localhost` exactly in an `allowHosts` that reaches it through `'*'`, compare a resolved disk by `.name`, advance the version in a custom store's `upsert`, drop `target` from a grant while a scanner is installed | `X_SQL_UNSAFE`, `X_CORS_CONFIG_INVALID` at boot, `X_STORAGE_PATH_UNSAFE`, `X_INVARIANT`, `X_MONEY_NOT_DECIMAL`, a remote tool missing from your `tools/list`, `X_SCRAPE_HOST_BLOCKED` for a `localhost` URL, `X_STORAGE_TARGET_UNSCANNED` | 2, 4, 7, 9, 11, 12, 19, 22, 27, 69, 70 | | 4 | **before the deploy:** list stored objects whose keys the new rule refuses and copy them; cache a projection where a value passes 1 MiB; keep `redisTier`'s default `buildId` or plan the one-time bust; on `docker/helm`, move a pod that reads the metadata endpoint to a workload identity; name a Postgres `notifyStores.ledger` in `runtime.ts` if a notifier runs; add `https:///auth/sso//callback` as a redirect URI at every OAuth IdP **before the new image rolls**, keep `/auth/oauth//callback` registered until the last old pod is gone, and point sign-in links at `/auth/sso/`; with objects still under `org/*/pending/quarantine/`, install an `uploadScanner` answering `hold` for them | a read of an old key refused; a cache miss logged `X_CACHE_TOO_LARGE`; stale tagged keys until their TTL; a metadata-endpoint timeout; `X_NOTIFY_STORE_MISSING` on the first notification | 5, 6, 11, 16, 49, 52, 57 | | 5 | **after the deploy:** declare `maxPage` on a read a client pages past 500 rows (`X_INPUT_INVALID` until you do); treat exit `70` as "drained, work abandoned" in alerts; read rate-limit keys through `addressNetwork`; switch on `denial.surface === 'mcp'` for an MCP read; honour `{ etag }` in a hand-written storage driver; give the collector a logs pipeline or set `OTEL_LOGS_EXPORTER=none`; with an external search index, run each `reindex()` once with `x db backfill --write --force --json` so its sweep drops what the table lost | nothing fails: an alert, a dashboard filter or an ETag answers differently | 3, 8, 13, 14, 17, 28, 30, 66, 73 | | 6 | `x db gen "tenant indexes"`, commit `packages/db/migrations` and `packages/db/schema/`; the new index builds `concurrently`, so a hot table keeps taking writes | `X_DB_DRIFT` from `x verify --only drift` | 20 | ### Entry by entry Tier 0 — `@ultimat3/core` (3), (23), (25), (31), (33–35), (43), (51), (55), (61), `@ultimat3/core` with `@ultimat3/cli` (24), `@ultimat3/core` with `@ultimat3/scraping` (22), `@ultimat3/schema` with `@ultimat3/core` (4), `@ultimat3/core` with `@ultimat3/jobs` (56). Tier 1 — `@ultimat3/db` (2), (30), `@ultimat3/db` with `@ultimat3/entity`, `@ultimat3/policy` and `@ultimat3/cache` (29), `@ultimat3/cache` (5–6), `@ultimat3/money` (7), `@ultimat3/seo` (63), `@ultimat3/storage` (11–13), (27), (57), (70), `@ultimat3/flags` with `@ultimat3/scraping` (38). Tier 2 — `@ultimat3/auth` (1), (44), (52), `@ultimat3/http` (8–9), `@ultimat3/entity` (20), (47), (65), (69), (71–73), `@ultimat3/http` with `@ultimat3/jobs` and `@ultimat3/ai` (26), `@ultimat3/http` with `@ultimat3/auth` and `@ultimat3/scraping` (37). Tier 3 — `@ultimat3/action` (10), `@ultimat3/action` with `@ultimat3/query` (14), (67), `@ultimat3/realtime` (15), (32), (59), (62), `@ultimat3/query` (17), `@ultimat3/jobs` with `@ultimat3/action`, `@ultimat3/mail` and `@ultimat3/notify` (36), `@ultimat3/jobs` (60), (66). Tier 4 — `@ultimat3/notify` (18), `@ultimat3/mcp` (19), `@ultimat3/render` (21), (64), `@ultimat3/ai` (41), (50), (58), `@ultimat3/pwa` (48), `@ultimat3/notify` (49), `@ultimat3/mail` (54). Tier 5 — `@ultimat3/cli` (28), (42), (45), (68), `@ultimat3/admin` (39), `@ultimat3/testing` (40), (46), `@ultimat3/testing` with `@ultimat3/scraping` (53). The framework chart — `docker/helm` (16). Every package's barrel (74). | # | Surface | Costs you an edit if | |---|---|---| | 1 | `AuthServerStore` (`@ultimat3/auth`) | you wrote your own store: TS2741, TS2554. Add `getCode(codeHash)` — the code row, used or not, spending nothing (`select … where code_hash = $1`) — and take `clientId` as `pollDevice`'s second argument, answering `null` and stamping nothing when the row's `clientId` differs. `memoryAuthServerStore()` and `postgresAuthServerStore()` already do | | 2 | `identifier()` (`@ultimat3/db`) | you pass it a name over 63 bytes or holding a NUL: `X_SQL_UNSAFE` now, where Postgres truncated the name without an error (two long names sharing their first 63 bytes were one object). Shorten the name to the one the server already holds — `psql "$DATABASE_URL" -c "select relname from pg_class where relname like '%'"` — and pass that | | 3 | the exit code after a drain (`@ultimat3/core`) | you alert on, or script around, a non-zero exit after SIGTERM: `installSignalHandlers({ exit: true })` now exits `70` (`DRAIN_TIMEOUT_EXIT_CODE`) when a hook or in-flight work was abandoned at the deadline (`X_SHUTDOWN_TIMEOUT`), where it exited `0`. The same 70 when the drain itself threw before its last phase, or a served role's own teardown (`apps//server.ts`, through `runRole`) overran its budget. A clean drain still exits `0`. Raise the budget — `drain: { deadlineMs: 600_000 }` in `app.config.ts` — or treat `70` as "drained, work abandoned"; `drainExitCode()` answers the same number for your own exit | | 4 | validation issues and error causes are bounded (`@ultimat3/schema`, `@ultimat3/core`) | you read more than 100 entries off a failed validation, or a `cause` past 4 KiB: `validate`/`parse`/`safeParse` stop at `MAX_ISSUES` (100) and set `issuesTruncated: true`, and every `UltimateError`/`SchemaError` cause is cut at `MAX_CAUSE_LENGTH` (4096) with `... (N more characters)`. Pass `validate(schema, value, { maxIssues: 1000 })` for a longer list; read the structured `meta`/`issues`, never a parsed `cause` | | 5 | `redisTier()` (`@ultimat3/cache`) | you cache a value whose encoded form is over 1 MiB in the shared tier: its `set` is now `X_CACHE_TOO_LARGE` (recorded by `bestEffort`, read as a miss), where Redis took it. Cache a projection, or raise the cap where the tier is built — `redisTier({ maxValueBytes: 4_194_304 })` | | 6 | `REDIS_INVALIDATE_SCRIPT`, `REDIS_TAG_MEMBER_SCRIPT` (`@ultimat3/cache`) | you imported either: both are gone — tag buckets are sorted sets (`t2:`/`e2:`) read with plain paged commands, and the one script left is internal. Delete the import. With `redisTier({ buildId: null })`, a v30 and a v31 pod mid-deploy do not see each other's buckets, so a bust on one misses keys the other wrote until their TTL: deploy with the default `buildId`, or run `redis-cli -u "$REDIS_URL" --scan --pattern ':c:*' \| xargs -r redis-cli -u "$REDIS_URL" UNLINK` once the rollout completes | | 7 | `fromDecimal()` (`@ultimat3/money`) | you match on the code of a parse failure: a string that is not a plain decimal (`'1,299.00'`, `'1e3'`) — and now a non-string (`12.99`, `null`, `undefined`), which was a bare `TypeError` — is `X_MONEY_NOT_DECIMAL` (HTTP 422), where it was `X_MONEY_NOT_INTEGER`. `grep -rn X_MONEY_NOT_INTEGER src/` and switch the branches that guard a `fromDecimal` parse; excess precision and fractional minors keep `X_MONEY_NOT_INTEGER` | | 8 | anonymous rate-limit keys (`@ultimat3/http`) | you read, seed or alert on an `ip:` key, or count on two IPv6 addresses having two allowances: an anonymous caller's key, and the failed-credential `unauthenticated\|ip:` key, is now its `/64` — `@ultimat3/core`'s `addressNetwork(ip)`: IPv4 whole, an IPv4-mapped IPv6 its IPv4, any other IPv6 `::/64`. A deploy starts every IPv6 bucket full once. Read keys through `addressNetwork`; a dashboard filtering `ip:2001:db8::1` filters `ip:2001:db8:0:0::/64` | | 9 | `cors.origins` (`@ultimat3/http`) | an entry is not its own `URL.origin` — a trailing slash, a capital, the scheme's default port, no scheme: `X_CORS_CONFIG_INVALID` at boot, where it was accepted and matched nothing. Write the form the `fix:` names: `configureHttp({ cors: { origins: ['https://app.com'] } })` | | 10 | `MAX_WIRE_ISSUES` (`@ultimat3/action`) | you import it: TS2305. Import `MAX_ISSUES` from `@ultimat3/schema` — the same 100, now the cap validation itself stops at, so the server and the typed client cannot disagree | | 11 | object keys (`@ultimat3/storage`) | a key has a segment ending in `.` or a Win32 device name (`CON`, `nul.txt`, `com1.log`): `X_STORAGE_PATH_UNSAFE` on every disk, where s3 took it (Windows drops the trailing dot, so `.meta.` IS the reserved `.meta`). A `:` is refused only by a local disk on Windows (an NTFS stream); the fix names the key with `-`. Find them with `aws s3 ls s3:// --recursive \| grep -iE '\.(/\|$)\|(^\|/)(con\|prn\|aux\|nul\|com[0-9]\|lpt[0-9])(\.\|/\|$)'`, copy each to a key without them, and build keys with `scopedKey`/`joinKey` | | 12 | `put()`/`putStream()` `contentType`, `cacheControl` (`@ultimat3/storage`) | either holds a byte outside printable ASCII (a line break, a non-ASCII character): `X_INVARIANT` on every disk, where local stored it and s3 answered `X_STORAGE_WRITE_OUTCOME_UNKNOWN`. Pass a plain header value — `put(key, body, { contentType: 'text/plain' })` | | 13 | `StorageDriver.stream` / `streamRange` (`@ultimat3/storage`) | you implement a driver: both take an optional last argument `{ etag }`, and `/_storage` passes it. Honour it — another revision is `X_STORAGE_OBJECT_CHANGED` (409) — or the route serves an overwrite under the old ETag. A driver that ignores it still compiles | | 14 | an MCP read's denial, and the `ActionDeniedError` / `QueryDeniedError` constructors (`@ultimat3/query`, `@ultimat3/action`) | you read `QueryDeniedError.denial` from an MCP tool call, or filter `PolicyDecisionEvent.surface` for agent reads: an MCP read is judged on policy's `mcp` surface, as an MCP action always was, so `.denial` is `{ surface: 'mcp', isError, content }` and the event says `'mcp'`, where both said `'job'`. Read the code and reason off the error (`error.code`, `error.cause`), or switch on `denial.surface`. If you construct either error yourself: TS2554 — pass `guardPrimitive(kind, policy, subject, surface)`'s answer from `@ultimat3/policy`, the one argument both now take | | 15 | `channel()` with a `catchUp` query (`@ultimat3/realtime`) | the query's `policy` is not the very object the `channel()` call passes: `X_CHANNEL_CATCHUP_POLICY_MISMATCH` at load. The catch-up read is served at `GET /_x/query/` with the channel params as input, so a wider rule (a bare `can(':read')` beside a channel rule comparing a param to the actor) answered any caller what the subscribe refuses. Export the channel's rule from the feature's `policy.ts` and pass it as both `policy:`s. A name-only `catchUp: { name }` (a browser `channelRef`) is not checked | | 16 | `networkPolicy.egress` in the framework chart and the one `x new` writes (`docker/helm`) | a pod dials a link-local address — `169.254.0.0/16`, `fe80::/10`, `fd00:ec2::254`, `64:ff9b::a9fe:a9fe` — or a port-53 resolver outside the cluster: egress is filtered by default, where `egress: []` left it open. The cloud metadata endpoint is the point; a pod reading node credentials from it now times out. Private ranges, every cluster pod and every public address stay reachable. Give the pod a workload identity (IRSA, Workload Identity) instead of the node's, or set `networkPolicy: { egress: [] }` to keep v30's open egress. An existing app's `docker/helm/values.yaml` is its own and keeps what it has until you paste the default in | | 17 | `?_first=` over HTTP (`@ultimat3/query`) | a client pages a read past 500 rows: `_first` above `MAX_WIRE_PAGE_SIZE` (500) is `400 X_INPUT_INVALID`, where the route took up to 10,000. Declare the read's own bound — `query({ maxPage: 2000, ... })`, up to 10,000 (`X_QUERY_MAX_PAGE_INVALID` outside it) — or page with a smaller `first`. A server `read.page()` is unchanged; `openapi.json`'s `maximum` follows `maxPage` | | 18 | `PreferenceStore` (`@ultimat3/notify`) | you wrote your own store: TS2741 / TS2353. `allows(query)` is replaced by `allowsMany(query)`, asked once per chunk of at most `NOTIFY_CHUNK_SIZE` (500) recipients per channel and answering the ids that may be reached (an id it omits is suppressed on that channel only). Turn the per-recipient read into one: `allowsMany: ({ recipients, notifier, channel, ctx }) => prefs.allowed(recipients.map((r) => r.id), notifier, channel, ctx.now())`. `allowAllPreferences()` and `memoryPreferenceStore()` already do. A fan-out's delivery steps are now `deliver::chunk-`; a run mid-flight across the deploy re-runs its chunks and the delivery ledger answers `sent` for whoever it already reached | | 19 | `mcpTools()` (`@ultimat3/mcp`) | you serve a remote server's tools on your own `/mcp` through `include: 'exposed'`: the remote actions are built `expose: false`, so they leave your `tools/list` (an in-app `agent()` is still offered them — they are declared `agents: true`). Opt that server in — `mcpTools({ name, url, allow, policy, lock, expose: true })` — knowing your `/mcp` then answers for the third party's tools. A remote whose tool list moves without a `list_changed` notification is now refused `X_MCP_REMOTE_TOOL_CHANGED` within `reverifyMs` (default 3,600,000) rather than at the next restart: run `x mcp lock ` after reviewing the diff | | 20 | the index a tenant table carries (`@ultimat3/entity`) | an entity has a tenant column — `.tenant()`, `entity(name, { tenant })` or an inferred `orgId`: `$describe().indexes` gains `___idx` on `(tenant, pk)`, built `concurrently`, unless a key or index already starts with `(tenant, pk)`, and `.tenant()`'s own `
__idx` is gone, so `x verify`'s `drift` step is red until `x db gen "tenant indexes"` writes the migration (create the composite concurrently, drop the single-column one). An unindexed tenant page was a sequential scan: 43.7 ms at 500k rows, 1.5 ms on the composite. A table name long enough that the new name passes 63 bytes is `X_INVARIANT_VIOLATED` at `entity()` — rename with `entity(name, { table })` | | 21 | `IsrStore`, `IsrController.revalidateByTags` / `markStale` (`@ultimat3/render`) | you wrote your own store, or call either controller method: a store method may now answer a promise (`IsrAnswer`) and the controller awaits each one; `revalidateByTags` answers `Promise` and `markStale` `Promise` — TS2339 on `.length`/`.includes` of the result, or a test asserting on the promise. `await` both. A synchronous store keeps compiling unchanged. Shared across replicas: `runtime.isrStore = storageIsrStore({ disk: disk('isr') })` | | 22 | a wildcard `allowHosts` rule and `localhost` (`@ultimat3/core`'s `hostDecision`, so `@ultimat3/scraping` and `x shot`) | a scrape or shot under `'*'` or `'*.localhost'` loads `localhost`, `*.localhost` or `localhost.`: refused (`X_SCRAPE_HOST_BLOCKED`, or a `refused: 'host'` ring entry), as `127.0.0.1` already was — the name is loopback by definition, and Chrome sends it around an egress proxy. Name it exactly: `allowHosts: ['*', 'localhost']`. A launched browser with an exit also gets `--proxy-bypass-list=<-loopback>`, so loopback goes through the proxy too; a local target behind a proxy session must be reachable from the proxy | | 23 | `configureTelemetry({ exporter })`, `noopExporter`, `ReadableSpan` (`@ultimat3/core`) | you installed a span exporter: TS2353 on `exporter` and TS2305 on `noopExporter` — spans are the `span.end` event on the instrumentation bus. Write `const off = subscribe('span.end', (event) => exporter.export(event.payload))` and call `off()` where you used to hand back `noopExporter`; a test does the same with `memoryExporter()`. You build a `ReadableSpan` by hand: add `droppedEventsCount: 0` (TS2741). A span now keeps 128 events (`MAX_SPAN_EVENTS`) and counts the rest. A `switch` over `OtlpSignal` gains `'logs'` | | 24 | `SENTRY_DSN` beside reporters an app installed itself (the boot in `@ultimat3/cli`; `sentryTransport`, `localErrorSink` in `@ultimat3/core`) | you set `SENTRY_DSN` AND install an error reporter of your own. Your `sentryErrorReporter` is now the only transport — each error is sent once, through your hooks, where the boot used to send it a second time unscrubbed; a reporter that WRAPS it (`{ report: (r) => inner.report(…) }`) is marked with `sentryTransport(wrapper)`. Local sinks keep the DSN transport beside them: `errorGroupsSink` and `memoryErrorReporter` are marked already, and a sink you wrote that keeps reports on the box is marked with `localErrorSink(sink)`. A reporter marked neither way logs `X_ERROR_REPORTER_DSN_UNCLAIMED` once and the DSN goes unused until you mark it | | 25 | the `jobs.queues` default (`@ultimat3/core`) and `x new`'s `app.config.ts` | `jobs.queues` unset now serves `['default']`, not `['-default']` — the queue a `job()` naming none lands on. Rows still queued on `-default` (`x jobs list --json`), an `enqueue({ queue: '-default' })`, or `WORKER_QUEUES=-default` (`X_WORKER_QUEUE_UNKNOWN` now): list the queue in `jobs.queues`. A config written by `x new` before 31.0.0 says `['-default']`: change it to `['default']` once that queue is empty, or every boot keeps logging the worker's `queue-unregistered` line | | 26 | the span attributes `@ultimat3/http`, `@ultimat3/jobs` and `@ultimat3/ai` write | a dashboard, alert or trace query reading the old names: the request span says `http.request.method`, `http.response.status_code`, `url.scheme`, `server.address` and `ultimate.request_id` (was `http.method`, `http.status_code`, `http.request_id`); a job's run span is kind `consumer` with `messaging.system`, `messaging.operation.type`, `messaging.destination.name` (the queue), `messaging.message.id`, `ultimate.job.name`, `ultimate.job.attempt`, `ultimate.job.enqueued_by` (was `job.name`, `job.id`, `job.attempt`, `job.enqueued_by`), and a CHILD of the new `job..enqueue` producer span, not of the request — the row's `traceparent` names the producer, and an enqueue outside any trace now starts one; `ai.llm` is kind `client` with `gen_ai.request.model`, `gen_ai.provider.name`, `gen_ai.response.model`, `gen_ai.usage.input_tokens` / `output_tokens` (was `llm.model`, `llm.provider`, `llm.tokens`), and every other `llm.*` attribute — on `ai.agent` and its `agent.turn` events too — is `ultimate.llm.*`. Rename the keys in the query | | 27 | `disk()` / `storage().disk()` (`@ultimat3/storage`) | you compare a resolved disk to the driver you declared — `expect(storage.disk('uploads')).toBe(uploads)` fails: `defineStorage` hands out an instrumented view of each driver (every call is a `storage.` event and client span), the same object on every resolution. Compare `.name`, or keep and call the driver you constructed — a driver held directly reports nothing. A driver's own members (`multipart`, a memory disk's `objects()`) still answer through the view | | 28 | the container's telemetry boot (`@ultimat3/cli`) | `OTEL_EXPORTER_OTLP_ENDPOINT` is set and the collector has no logs pipeline: the generic endpoint now names logs too, so every process-logger line is posted to `/v1/logs` and a collector without a logs receiver answers each batch with a 404. Add a logs pipeline, or switch the signal off with `OTEL_LOGS_EXPORTER=none` (also `OTEL_TRACES_EXPORTER` / `OTEL_METRICS_EXPORTER`). Every boot also declares `db_client_operation_duration_seconds`, `job_duration_seconds` and `gen_ai_client_token_usage` on `/metrics`: a scrape with a series allowlist drops them until listed | | 29 | `setStatementObserver`, `statementObserver`, `StatementObserver`, `StatementEvent`, `STATEMENT_ATTRIBUTE` (`@ultimat3/db`); `setRowObserver`, `rowObserver`, `RowObserver`, `RowChange`, `RowBulkChange`, `setCrossTenantObserver` (`@ultimat3/entity`); `setDecisionSink` and its siblings (`@ultimat3/policy`); `recentInvalidations`, `recentTierFailures`, `InvalidationEvent`, `TierFailure` (`@ultimat3/cache`) | you install or read any of them: TS2305. Subscribe on the bus instead — `const off = subscribe('db.statement', (e) => observer.onStatement(e.payload))`, `subscribe('entity.row' \| 'entity.bulk' \| 'entity.cross_tenant', …)`, `subscribe('policy.decision', (e) => sink.record(e.payload))`, `subscribe('cache.invalidate' \| 'cache.tier_failure', …)` from `@ultimat3/core` — and call `off()` where you restored the previous observer; keep your own bounded buffer where you read a `recent*()` list (a cache event carries no `at`: read the clock in the handler). Types: `DbStatementEvent`, `EntityRowEvent`, `EntityBulkEvent`, `PolicyDecisionEvent`, `CacheInvalidateEvent`, `CacheTierFailureEvent`. Every subscriber hears every event — nothing is displaced — and a throwing subscriber is contained by the bus (logged once as `instrument.subscriber_failed`), never the statement's, evaluation's or read's failure; `@ultimat3/testing`'s `statements` fixture now raises its N+1 verdict when it is disposed, not at the looping statement (`statements.verdicts()` reads it earlier) | | 30 | database spans (`@ultimat3/db`) | a trace backend, dashboard or sampling budget: every statement is now a `db.` client span in production, not only under `x dev`, with `db.system.name`, `db.query.text` and `db.operation.name` — the old `db.statement` attribute is gone. Rename the key in a trace query; raise the span budget or lower the sample ratio (`OTEL_TRACES_SAMPLER_ARG`) if a statement-heavy request now exceeds it | | 31 | `addLogSink` (`@ultimat3/core`) | you tee the process logger's lines: TS2305 on `addLogSink` — the tee is the `log.record` event on the instrumentation bus. Write `const off = subscribe('log.record', (event) => store(event.payload))`: the payload is the line's `at`, `level`, `message` and redacted `fields` (not the rendered JSON string — `JSON.stringify` it if you stored lines), and `off()` is the unsubscribe `addLogSink` returned. A throwing subscriber is still swallowed, and is no longer reported as `log.sink_failed`. The test seam that replaces the streams is `installLogSink` (it was `setLogSink`) | | 32 | `setChannelTransport`, `resetChannelTransport`, `selectTransport` (`@ultimat3/realtime`) | you called a setter or the selector yourself: TS2305 on `setChannelTransport`/`resetChannelTransport` — an app's bus is `transport` in `export const runtime = { … }` (`apps//runtime.ts`); a driver or a boot imports `installChannelTransport` from `@ultimat3/realtime/adapter`, whose release is the test reset. TS2559 on `selectTransport(env, config.realtime, opts)`: drop the second argument. `NATS_URL` set now selects NATS with no config key, and any other variable selects nothing — an app that named `urlEnv: 'BUS_URL'` renames its variable to `NATS_URL` or hands a `NatsTransport` to `runtime.ts` | | 33 | `setFailureStore` (`@ultimat3/core`) | you installed a failure store yourself: TS2305 — set `failureStore` in `export const runtime = { … }` (`apps//runtime.ts`); a boot or a test harness imports `installFailureStore` from `@ultimat3/core/adapter`, and calls the function it returns to restore (it no longer returns the previous store) | | 34 | `MasterKeySource`, `MasterKeyRef.source`, `SecretsInstallReport.keySource` (`@ultimat3/core`) | you named the type or switched on `'env' \| 'file'`: TS2305 on `MasterKeySource` — the field is the source's `name`, a `string`; compare it as before or widen your switch. A KMS/Vault key is a `SecretSource` (`{ name, masterKey({ root, env }) }`, from `@ultimat3/core/adapter`) set as `secretSource` in `runtime.ts`, never an exported `ULTIMATE_SECRETS_KEY` written by a wrapper script | | 35 | `realtime.transport`, `realtime.urlEnv`, `REALTIME_TRANSPORTS`, `RealtimeTransport` (`@ultimat3/core`), all removed | your `app.config.ts` writes either key: `X_CONFIG_INVALID` naming its replacement — delete the line; set `NATS_URL` for every realtime role (rename a variable `urlEnv` named), or pass any other `Transport` as `transport` in `runtime.ts`. TS2305 on the two type names | | 36 | `setJobDriver`, `setEventBus` (`@ultimat3/jobs`), `setMailDriver` (`@ultimat3/mail`), `setIdempotencyStore`, `setMeterStore` (`@ultimat3/action`), `setNotifyStores` (`@ultimat3/notify`), and their resets | you installed a backend or reset one yourself: TS2305 — set it in `export const runtime = { … }` (`apps//runtime.ts`): `jobs`, `eventBus`, `mail`, `idempotencyStore`, `meterStore`, `notifyStores`. A driver's author, a boot or a test harness imports `installJobDriver`, `installEventBus`, `installMailDriver`, `installIdempotencyStore`, `installMeterStore`, `installNotifyStores` and `resetJobDriver`, `resetEventBus`, `resetMailDriver`, `resetIdempotency`, `resetMeterStore`, `resetNotifyStores` from `@ultimat3//adapter` — never the `.` barrel. Each `install*` returns a release that removes that install alone, in any order: call it where you called the old setter a second time to put one back | | 37 | `httpServer({ rateLimitStore })`, `installRateLimitStore`, `adoptRateLimitStore` (`@ultimat3/http`), `configureAuthLimiters`, `configureTotpReplay` (`@ultimat3/auth`), `setScrapeDriver` (`@ultimat3/scraping`), and their resets | you passed a store to `httpServer` or called an installer yourself: TS2353/TS2305 — set `rateLimitStore`, `authLimiter`, `totpReplay` or `scrapeDriver` in `export const runtime = { … }` (`apps//runtime.ts`); every server's limiter counts in that one store. A boot or test harness imports `installRateLimitStore` from `@ultimat3/http/adapter`, `installAuthLimiters`/`installTotpReplay` (renamed from `configure*`) from `@ultimat3/auth/adapter`, `installScrapeDriver` from `@ultimat3/scraping/adapter` — each answers its release — and `resetRateLimitStore`, `resetAuthLimiters`, `resetTotpReplay`, `resetScrapeDriver` from the same subpaths, never `.` | | 38 | `ScrapeClock`, `TestScrapeClock`, `systemScrapeClock`, `noWaitClock`, `testScrapeClock`, `scrapeClock`, `setScrapeClock`, `resetScrapeClock` (`@ultimat3/scraping`), `configureFlags({ clock })` (`@ultimat3/flags`) | TS2305 / TS2353 — import `SleepClock`, `FrozenClock`, `systemClock`, `noWaitClock`, `frozenClock`, `ambientClock` from `@ultimat3/core`; replace `setScrapeClock(c)` … `resetScrapeClock()` with `const release = installClock(c)` (`@ultimat3/core/adapter`) … `release()`; drop `clock` from `configureFlags` and set `clock` in `apps//runtime.ts`. A test that asserted a frozen clock advanced on an already-aborted sleep now reads 0 | | 39 | `AuditSink` (`@ultimat3/admin`) | TS2305 on the import — `import type { AuditSink } from '@ultimat3/core/adapter'` and type the sink `AuditSink` | | 40 | `associate`, `associations`, `Association`, `AssociationMap`, `buildMany`, `createMany`, `Persister` (`@ultimat3/testing`) | TS2305/TS2353/TS2339 — `associations: { orgId: associate(orgs, (o) => o.id) }` becomes `belongsTo: { org: belongsTo(orgs, 'orgId') }` (keep `orgId` in `defaults`); rename `buildMany`/`createMany` to `buildList`/`createList`; a hand-written persister is `insert(entity, row)` answering the stored row — or delete it and `usePersister(entityPersister({ driver }))`. A test that asserted `create()` returned the BUILT row now sees the stored one (defaults filled); a test that expected `X_TEST_FACTORY_NOT_PERSISTED` for a real `entity()` now writes to `defaultDriver()`. 31.0.0–31.1.0 widened a string literal in `defaults` to `string` (TS2322 on an `enumerated` column); 31.2.0 keeps it, so an `as const` added for that can go | | 41 | `configureAi({ gateway })` (`@ultimat3/ai`) | TS2353 on `gateway` — set `aiGateway` in `export const runtime = { … }` (`apps//runtime.ts`); keep `configureAi` for `embedder`, `semanticCache`, `redact` only. A test installs one with `const release = installAiGateway(gateway)` from `@ultimat3/ai/adapter` and calls `release()` after | | 42 | `RuntimeOverrides.syncAuthenticate` (`@ultimat3/cli`) | TS2353 on `syncAuthenticate` in `runtime.ts` — delete it; state a token's lifetime as `configureAuthenticator(resolve, { credentialTtlMs })`. A `/packages/db/factories.ts` exporting `factories` is now linted by `unit`: `X_TEST_FACTORY_INVALID` names the factory and trait to fix | | 43 | `setAuditSink`, `resetAuditSink`, `configureErrorReporting({ reporter })` (`@ultimat3/core`) | TS2305 / TS2322 (`reporter` is `never`) — set `auditSink` / `errorReporter` in `export const runtime = { … }` (`apps//runtime.ts`), not at module scope. A test: `const release = installAuditSink(sink)` / `installErrorReporter(reporter)` from `@ultimat3/core/adapter`, `release()` after — or `swapAdapter('auditSink', sink)` from `@ultimat3/testing`. `configureErrorReporting` keeps `clock`, `release`, `environment`, `enabled`. Through 31.1.0, `x exercise` and `x build`'s measurement did not read `runtime.ts`, so the sink declared there was missing in both ("Not breaking, but you will see it", below); 31.2.0 reads it, and a memory sink installed in `apps/web/exercise.ts` or `prerender.ts` as the workaround can be deleted | | 44 | `configureKdfGate`, `resetKdfGate` (`@ultimat3/auth`) | TS2305 — `const release = installKdfGate({ maxConcurrent, maxQueued })` from `@ultimat3/auth/adapter`, `release()` (or `resetKdfGate()`, same subpath) after | | 45 | `RuntimeOverrides.storage` (`@ultimat3/cli`) | TS2322 when `runtime.ts` passes `defineStorage({ … })` — pass the driver (`storage: s3Driver({ … })`): it is the default disk under the driver's `name`. Several disks: `defineStorage()` in `app.config.ts`, which wins | | 46 | `jobDriverConformance`, `budgetStoreConformance`, `BudgetStoreLike` (`@ultimat3/testing`) | TS2305 — import them from `@ultimat3/testing/conformance`, where every port's suite lives; `behavesLike` stays on `@ultimat3/testing` | | 47 | a malformed uuid in a repository write (`@ultimat3/entity`) | a test that expected `X_DB_STATEMENT_FAILED` (Postgres 22P02) for `repo.insert({ id: 'not-a-uuid' })` now sees `X_INVARIANT_VIOLATED`, raised before the statement in both drivers — and memory no longer stores the row: expect the new code | | 48 | `PushSubscriptionRecord.actorId` (`@ultimat3/pwa`) | TS2322 where code builds a record with `actorId: null` — store it for `ctx.actor.id`, as `pushSubscribe()` does; an anonymous visitor has no subscription. At runtime both stores now refuse a missing or empty `actorId` with `X_PWA_PUSH_SUBSCRIPTION_INVALID` before writing (Postgres answered a not-null violation; memory stored it). A custom `PushSubscriptionStore` proves the same with `pushSubscriptionStoreConformance` | | 49 | the default delivery ledger (`@ultimat3/notify`) | you deploy (staging or production) with no `notifyStores.ledger` in `runtime.ts` and a notifier runs: its first claim is `X_NOTIFY_STORE_MISSING`, where a memory ledger answered — one per process, so a replay on another replica or after a restart sent twice. Set `notifyStores: { ledger: postgresDeliveryLedger({ executor: dbExecutor() }) }` in `export const runtime = { … }` (`apps//runtime.ts`); the boot already applies `x_notify_deliveries`. Name every store you keep in that one object — it replaces, never merges. Development and test keep the memory default | | 50 | `configureAi({ embedder, semanticCache })` (`@ultimat3/ai`) | TS2353 on `embedder` / `semanticCache` — set them in `export const runtime = { embedder, semanticCache }` (`apps//runtime.ts`); `semanticCache` is the same `(scope) => SemanticCache` factory. `configureAi` keeps `redact` only. A test: `const release = installAiEmbedder(embedder)` / `installSemanticCache(factory)` from `@ultimat3/ai/adapter`, `release()` after — or `swapAdapter('embedder', …)` from `@ultimat3/testing`. Prove one with `embedderConformance` / `semanticCacheFactoryConformance` from `@ultimat3/testing/conformance` | | 51 | `configureMetrics({ exporter })` (`@ultimat3/core`) | TS2353 on `exporter` — subscribe it: `const release = subscribe('metric.export', (event) => exporter.export(event.payload))`, `release()` to uninstall; `exportMetrics()` / `startMetricExport(ms)` publish the tick as before. `configureMetrics` keeps `clock` and `enabled`. With `OTEL_EXPORTER_OTLP_ENDPOINT` set the boot already subscribes `otlpMetricExporter()` | | 52 | `oauthLogin` (`@ultimat3/auth`) — its paths, cookie and `restartAt` | the routes moved from `/auth/oauth/:provider[/callback]` to `/auth/sso/:provider[/callback]` (`oauthStartPath`/`oauthCallbackPath`/`OAUTH_*_ROUTE_PATH` answer the new values; the call and its options are unchanged). **Before deploying, add `https:///auth/sso//callback` as an allowed redirect URI at each IdP** (GitHub, Google, your OP) — keep the old one until the deploy is out — and point every sign-in link at `/auth/sso/`. A login started before the deploy fails its callback once (`X_OAUTH_STATE_INVALID`: the state cookie is now `__Host-x_sso_`); the user starts again. `restartAt(provider)` and every OAuth `fix:` name `/auth/sso/`. `oauthDenied` and `OAUTH_ROUTE_STATUS` keep their names on `@ultimat3/auth`; a deep import from `./oauth-route` moves to the barrel. The base path is fixed (`OAUTH_BASE_PATH`, `packages/auth/src/oauth-paths.ts`): a mid-roll pod answers on one path only, so both URIs stay registered until the roll completes. **Can't re-register the redirect URI at your IdP?** Keep the old one: `oauthLogin(auth, { callbackPath: '/auth/oauth/:provider/callback' })`, then mount `callback.path` (not `OAUTH_CALLBACK_ROUTE_PATH`); the start link stays `/auth/sso/`. **Hand-built callback?** From 31.2.0, `readHandshakeCookie` opens the cookie `oauthLogin().start` sets, so a `beginOAuth` + `handshakeCookie` start leg written as a workaround can be deleted; its in-flight cookies (`__Host-x_oauth_

`) are still read until 32.0.0 | | 53 | the raw-CDP launcher (`@ultimat3/testing` → `@ultimat3/scraping/cdp`) | an e2e suite imports `findChrome`, `launchChrome`, `CHROME_PATH_ENV`, a `Cdp*Error` or `E2E_BROWSER_CLOSE_MS` from `@ultimat3/testing` (TS2305, no exported member): `bun add -d @ultimat3/scraping`, then `import { findChrome, LAUNCHED_CLOSE_MS } from '@ultimat3/scraping/cdp';` — `E2E_BROWSER_CLOSE_MS` is `LAUNCHED_CLOSE_MS`, the same value. Everything e2e-shaped (`openE2eBrowser`, `E2E_BROWSER_OPEN_MS`, `installE2eDriver`, …) stays on `@ultimat3/testing` | | 54 | `welcomeMail`, `verifyEmailMail`, `resetPasswordMail`, `inviteMail`, `mfaEnrolledMail`, `securityAlertMail`, their `*Input` schemas and types, `MFA_METHODS`, `FRAMEWORK_MAILS` (`@ultimat3/mail`) | you import one (TS2305), or send a mail by one of the ids `welcome`, `verify-email`, `reset-password`, `invite`, `mfa-enrolled`, `security-alert` without declaring it — importing the package no longer registers them. Declare your own: `export const welcomeMail = defineMail<{ name: string }>({ id: 'welcome', subject: 'mail.welcome.subject', input: t.object({ name: t.string }), template: ({ data }) => [blocks.heading('mail.welcome.heading', { name: data.name })] })`, and carry every `mail..*` key it renders in `packages/i18n/catalogs/.json` — the base catalog keeps `mail.footer.*` only. Email verification and password reset are untouched: `@ultimat3/auth` sends `auth.email-verify` / `auth.password-reset` from your catalog, as before | | 55 | `noopMetricExporter` (`@ultimat3/core`) | you import it (TS2305): delete the import and what it was handed to — exporting nothing is subscribing nothing to `metric.export` (entry 51). A test that needs an exporter value uses `memoryMetricExporter()` | | 56 | `AuditPrimitive`, `AuditRecord.primitive` (`@ultimat3/core`); `subjectErase()`'s audit record (`@ultimat3/jobs`) | an exhaustive `switch (record.primitive)` in your audit sink: add `case 'job':`. A report over `x_audit.primitive = 'action'` that meant to include GDPR erases adds `'job'` — an erase now records `{ primitive: 'job', surface: 'job' }`. An action a job enqueued still records `primitive: 'action'` on surface `'job'` | | 57 | `grantUpload({ quarantine })`, `releaseQuarantine`, `ReleaseQuarantineInput`, `quarantineKey`, `quarantinePrefix`, `isQuarantinedKey`, `QUARANTINE_SEGMENT` (`@ultimat3/storage`) | you use the quarantine flow: TS2353 on `quarantine`, TS2305 on the rest. Delete the option; a review queue or async vendor scan becomes an `uploadScanner` in `apps//runtime.ts` that answers `{ verdict: 'hold', reason }` for an upload — keyed by the new `ScanInput.pendingKey` — until your own store says cleared, then `{ verdict: 'clean' }`. A hold is `X_STORAGE_QUARANTINED` (409; `meta` is now `{ key, scanner, reason }`), the upload kept pending. That scanner declares `holds: true` — `{ name, holds: true, scan }` — or its `hold` is `X_INVARIANT` and nothing is attached; with it, a scanner that cannot answer is always `X_STORAGE_SCAN_UNAVAILABLE`, even under `onScanUnavailable: 'accept'`. An exhaustive `switch` over `ScanVerdict` gains `'hold'`. **Before deploying, with objects still under `org/*/pending/quarantine/`:** install the holding scanner first, or those keys promote like any pending key — unscanned if no scanner is installed | | 58 | `RetryPolicy`, `providerGateway({ retry })`, `DEFAULT_GATEWAY_RETRY`, `backoffMs` (`@ultimat3/ai`) | you import the type (TS2305) or pass a gateway `retry` (TS2353 on `baseDelayMs`): `import type { RetryPolicy } from '@ultimat3/core'`, and `retry: { attempts: 3, baseDelayMs: 500, maxDelayMs: 8_000 }` becomes `retry: { attempts: 3, base: 500, max: 8_000, jitter: 'full' }` — `jitter` is required. `curve`, `factor` and `timeBudgetMs` (the whole call, across every provider) are now honoured | | 59 | `BackoffPolicy` and every `backoff:` option (`@ultimat3/realtime`: `clientTransport`, `socketEngine`, `natsTransport`, the replicator, `deviceAgent`) | you import `BackoffPolicy` (TS2305) or pass a `backoff` (TS2353 on `baseMs`): `backoff: { baseMs: 500, maxMs: 30_000, factor: 2, jitter: 'full' }` becomes `backoff: { base: 500, max: 30_000, factor: 2, jitter: 'full' }`; type it `Pick` with `RetryPolicy` from `@ultimat3/core`. Reading `defaultBackoff.baseMs` / `.maxMs`: `.base` / `.max`. `curve` is now honoured | | 60 | `retry.jitter` on a `job()` (`@ultimat3/jobs`) | you set it (TS2322 on a boolean): `jitter: false` → `jitter: 'none'`, `jitter: true` → `jitter: 'equal'` — the same delays; `'full'` is new. Omitted is unchanged (`'equal'`). A boolean that reaches `job()` from JS or JSON config is refused at declaration: `X_JOB_DECLARATION_INVALID` | | 61 | `setLogSink` (`@ultimat3/core`) | you install a log sink in a test or preload (TS2305): `const previous = setLogSink(sink); … setLogSink(previous)` becomes `const release = installLogSink(sink); … release()` — the release removes only this install, in any order. `installLogSink(undefined)` routes lines back to the real streams until released. An app scaffolded by `x new` (or given `x g sign-in`) before 31.0.0 has `apps/web/app/auth/dev-actor.test.ts` calling `setLogSink`: the same edit | | 62 | `Row` (`@ultimat3/realtime`) | you import realtime's `Row` (TS2305): `import type { LiveRow } from '@ultimat3/realtime'` — same shape, new name. A `Row` imported from `@ultimat3/core` is a different type and unchanged | | 63 | `Surface` (`@ultimat3/seo`) | you import it from seo (TS2305): `import type { Surface } from '@ultimat3/core'`. `RouteRecord.surface` is `Exclude` — still `'site' \| 'app' \| 'api'` | | 64 | `SURFACES` (`@ultimat3/render`) | you import the value from render (TS2305): `import { SURFACES } from '@ultimat3/core'`. The `Surface` type still comes from either | | 65 | `SearchIndex` (`@ultimat3/entity`) | you wrote your own adapter (Meilisearch, Typesense) — TS2741: add `list({ entity, tenant?, after, limit }) → { entries: { tenant, id, version }[], next: string \| null }`, every live (non-removed) document of the entity, paged in a stable order, `tenant` omitted = every tenant. Prove it with `behavesLike(searchIndexConformance, () => yours)` from `@ultimat3/testing/conformance`; a Postgres-backed subject may pass `everyTenant: (read) => crossTenant(reason, read)` | | 66 | `reindex({ source })` (`@ultimat3/jobs`) | your `source` is narrowed by a filter (`db.posts.where({ published: true })`): the new sweep removes every indexed document that `source` does not read, so it now EMPTIES the index of the other rows — pass the whole table (`source: () => db.posts`). The backfill's checksum changed: a pass already recorded completed re-runs only with `{ force: true }` (`x db backfill --write --force --json`) | | 67 | `registerAction`, `registerActions` (`@ultimat3/action`), `registerQuery`, `registerQueries` (`@ultimat3/query`) | you call one (TS2305): hand the module to `defineApi({ actions, queries })` — the one path — or, if you are writing a loader, import it from `@ultimat3/action/loader` / `@ultimat3/query/loader`. A `/live/.live.test.ts` that `x g query --live` wrote before 31.0.0 says `const live = registerQuery('feed', feed);`: write `const live = defineApi({ queries: { feed } }).queries.feed;` with `import { defineApi } from '@ultimat3/action';`. An app module or test importing a `./loader` is `X_BOUNDARY_LOADER_IMPORT` on `x verify --only boundaries` | | 68 | `x g app` / `x g package` (`@ultimat3/cli`) | a script passes a slice flag (`--feature`, `--surface`, `--live`, `--admin`, `--locales`, `--at`, `--app`, `--permission`): `X_CLI_BAD_FLAG` where the flag was ignored. Drop it — a workspace generator reads `--force` and `--dry-run` only | | 69 | a `defineDriver` store declaring `'upsert'` (`@ultimat3/entity`) | your store merges an upsert collision itself: pass the merged row through `advanceVersion(entity, stored, merged, (p) => plan.set.includes(p))` from `@ultimat3/entity/adapter`, or `entityDriverConformance` fails "a searchable entity's upsert collision in the same ms is a newer version" Every searchable entity's version is now strictly increasing per row: a test asserting `updatedAt` equals a frozen clock after a second write in the same ms expects `+1 ms`, and a `defineDriver` store's `updateWhere` on a searchable entity past `MAX_ASSERTED_ROWS` rows is `X_INVARIANT_VIOLATED` | | 70 | `grantUpload({ target })`, `grantMultipart({ target })` with an `uploadScanner` installed (`@ultimat3/storage`) | a targeted grant: `X_STORAGE_TARGET_UNSCANNED` (500). Drop `target` and call `promoteAttachment({ disk, key, orgId, target, policy })` once the upload lands, so the scanner sees it. Without a scanner nothing changes | | 71 | `SearchIndex.index` (`@ultimat3/entity`) | you wrote your own adapter: `index(documents, options?)` takes `{ committed?: boolean }`. `committed: true` (the write path) replaces a TOMBSTONE whatever the versions say — a key deleted and written again is live — and against a held document still keeps only newer; unset (`reindex()`) keeps the tombstone's stale guard. `searchIndexConformance` checks it | | 72 | `DriverRepo.update` in a `defineDriver` store (`@ultimat3/entity`) | your store's `update` takes a third argument `advance?: { property, stepMs }` (`DriverAdvance`, `@ultimat3/entity/adapter`): write `advance.property` per matched row as the later of the patch's instant and that row's stored one + `stepMs`, atomically with the write — in code, `advanceVersion(entity, row, { ...row, ...patch }, (p) => p === advance.property)`. A store that ignores it fails `entityDriverConformance` | | 73 | `rowKey` of a key holding a `timestamp()` (`@ultimat3/entity`) | a searchable entity has an instant in its primary key (every partitioned table): its search-index ids are now spelled ISO 8601 UTC, where they were `String(date)` in the process zone. Run its `reindex()` once — `x db backfill --write --force --json` if a pass completed: the sweep removes the old spellings, the rows phase writes the new. Cursors are unaffected | | 74 | every package's `.` barrel (all `@ultimat3/*` but `create-ultimate`) | you import one of the 1,409 names that left `.` — TS2305, no exported member. Look it up in [`v31-barrel-removals.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/history/v31-barrel-removals.md): listed under "now on `./adapter`" (46 names), import it from `@ultimat3//adapter`; listed under "no longer exported" (1,363), it was internal — an error factory or class is matched by code instead (`import { isUltimateError } from '@ultimat3/core'`, then `isUltimateError(e) && e.code === 'X_…'`), a `*_ERROR_CODES` table by the package's `ErrorCode` type where it has one; otherwise compare `e.code` to the code string — and anything else through the kept factory and its option and result types, which stay on `.` | ### Every removed setter, and the `runtime.ts` field that replaced it One lookup for entries 32–38, 41, 43 and 50. A backend is swapped in ONE place, `export const runtime = { … }` in `apps//runtime.ts`; the installer beside each field is what the boot calls, and what a harness of your own imports — a test uses `await swapAdapter(port, impl)` from `@ultimat3/testing`. Each port's interface, reference implementation and conformance suite: [Adapters](Adapters). | Removed in 31.0.0 | `runtime.ts` field | The installer, on the package's `./adapter` | Entry | |---|---|---|---| | `setJobDriver` (`@ultimat3/jobs`) | `jobs` | `installJobDriver` (`@ultimat3/jobs/adapter`) | 36 | | `setEventBus` (`@ultimat3/jobs`) | `eventBus` | `installEventBus` (`@ultimat3/jobs/adapter`) | 36 | | `setMailDriver` (`@ultimat3/mail`) | `mail` | `installMailDriver` (`@ultimat3/mail/adapter`) | 36 | | `setIdempotencyStore` (`@ultimat3/action`) | `idempotencyStore` | `installIdempotencyStore` (`@ultimat3/action/adapter`) | 36 | | `setMeterStore` (`@ultimat3/action`) | `meterStore` | `installMeterStore` (`@ultimat3/action/adapter`) | 36 | | `setNotifyStores` (`@ultimat3/notify`) | `notifyStores` | `installNotifyStores` (`@ultimat3/notify/adapter`) | 36 | | `setFailureStore` (`@ultimat3/core`) | `failureStore` | `installFailureStore` (`@ultimat3/core/adapter`) | 33 | | `setChannelTransport`, `selectTransport` (`@ultimat3/realtime`); the two deleted realtime transport config keys (entry 35) | `transport` | `installChannelTransport` (`@ultimat3/realtime/adapter`) | 32, 35 | | `MasterKeySource` (`'env' \| 'file'`, `@ultimat3/core`) | `secretSource` | `installSecretSource` (`@ultimat3/core/adapter`) | 34 | | `setScrapeDriver` (`@ultimat3/scraping`) | `scrapeDriver` | `installScrapeDriver` (`@ultimat3/scraping/adapter`) | 37 | | `httpServer({ rateLimitStore })`, `installRateLimitStore` on the barrel (`@ultimat3/http`) | `rateLimitStore` | `installRateLimitStore` (`@ultimat3/http/adapter`) | 37 | | `configureAuthLimiters` (`@ultimat3/auth`) | `authLimiter` | `installAuthLimiters` (`@ultimat3/auth/adapter`) | 37 | | `configureTotpReplay` (`@ultimat3/auth`) | `totpReplay` | `installTotpReplay` (`@ultimat3/auth/adapter`) | 37 | | `setScrapeClock` (`@ultimat3/scraping`), `configureFlags({ clock })` (`@ultimat3/flags`) | `clock` | `installClock` (`@ultimat3/core/adapter`) | 38 | | `configureAi({ gateway })` (`@ultimat3/ai`) | `aiGateway` | `installAiGateway` (`@ultimat3/ai/adapter`) | 41 | | `setAuditSink` (`@ultimat3/core`) | `auditSink` | `installAuditSink` (`@ultimat3/core/adapter`) | 43 | | `configureErrorReporting({ reporter })` (`@ultimat3/core`) | `errorReporter` | `installErrorReporter` (`@ultimat3/core/adapter`) | 43 | | `configureAi({ embedder })` (`@ultimat3/ai`) | `embedder` | `installAiEmbedder` (`@ultimat3/ai/adapter`) | 50 | | `configureAi({ semanticCache })` (`@ultimat3/ai`) | `semanticCache` | `installSemanticCache` (`@ultimat3/ai/adapter`) | 50 | A setter still on a package's `.` barrel is `X_ADAPTER_PORT_INCOMPLETE` on the `boundaries` step unless `scripts/lib/adapter-port-pins.ts` names why it selects no backend. ### Not breaking, but you will see it | What moved | Do | |---|---| | `x verify`'s `manifest` step is red, `X_MCP_APP_UNMOUNTED`, when `ai.mcp.expose` is `true` — **the default**, so an `app.config.ts` that never names it counts — and no `apps/web/mcp.ts` exports `mcp` (`As of 30.4.0`; before, the boot only logged it while `POST /mcp` answered 404). An app scaffolded before `x new` wrote that file hits it on its first 31.0.0 gate | mount it as `x new` does: `apps/web/mcp.ts` exporting `export const mcp = appMcp({ resolveToken: resolveAgentToken })`, `appMcp` from your `@/mcp` package and `resolveAgentToken` from `./app/auth/agent-token` — copy those files (and `packages/mcp/src/index.ts`, if you have no `@/mcp`) from a fresh `bunx create-ultimate`. With no catalog package, the error's own fix is the whole file: `export const mcp = defineAppMcp({ include: 'exposed', resolveToken })` (`@ultimat3/mcp`), `resolveToken` answering an agent or `null`. No agent surface wanted: `ai: { mcp: { expose: false } }` in `app.config.ts` | | `verifyApiKey` (`@ultimat3/auth`) refuses every key with `X_API_KEY_INVALID` when the stored `prefix` is not the one the bearer parses to: since 31.0.0 it compares `parseApiKey(bearer).prefix` — always `ult__` — to `record.prefix` (`packages/auth/src/api-keys.ts`, `verifyApiKey`). An app that minted keys itself, or stores a display prefix of its own (`acme__`, a truncated `ult_prod`), passed on 30.x and fails every key now. A bearer not shaped `ult___` was already refused by `parseApiKey` before 31 | list the rows that cannot match: `psql "$DATABASE_URL" -c "select id, prefix from x_api_keys where prefix !~ ('^ult_[a-z0-9-]+_' \|\| id \|\| '$')"`; for each, `update x_api_keys set prefix = 'ult__' \|\| id where id = ''`, `` the second segment of the bearer that key's holder sends. A custom `ApiKeyStore` answers `prefix` exactly as `issueApiKey` wrote it | | a unique collision under the memory driver — what a factory's `create()` writes to in a test since entry 40 — is `X_DB_UNIQUE_VIOLATION` with no SQLSTATE: `sqlState(e)` (`@ultimat3/db`) answers `undefined`, where Postgres answers `23505`, so a race handler matching `sqlState(e) === '23505'` passes in production and fails its test (`packages/entity/src/driver-errors.ts`, `entityUniqueViolation`) | match the code, which both drivers raise: `isUltimateError(e) && e.code === 'X_DB_UNIQUE_VIOLATION'` (`isUltimateError` from `@ultimat3/core`); `meta.constraint` names the constraint on both. Through 31.1.0 only the code matches under memory; fixed in **31.2.0**, from which the memory driver and every `defineDriver` store carry `23505` too and `sqlState(e) === SQLSTATE.uniqueViolation` (`@ultimat3/db`) also matches | | `x exercise` reports `X_AUDIT_SINK_MISSING` (`X_QUERY_AUDIT_SINK_MISSING` for a query) on every `audit: true` primitive, and `x build` lists each page whose render runs one under `unmeasured`: entry 43 moved `auditSink` into `runtime.ts`, and neither pass installs `runtime.ts` | fixed in **31.2.0**: both read `apps//runtime.ts` through the boot's own loader, a memory sink standing in for the declared one so neither writes to it. On 31.0.0–31.1.0, install a memory sink at the top of `apps/web/exercise.ts` and `apps/web/prerender.ts` — `installAuditSink(memoryAuditSink())`, `installAuditSink` from `@ultimat3/core/adapter`, `memoryAuditSink` from `@ultimat3/action`; on 31.2.0, delete it | | `defineFactory` (`@ultimat3/testing`, entry 40) widens a string literal in `defaults` or a trait to `string`, so an `enumerated([…])` column is TS2322 — `Type 'string' is not assignable to type '"closed" \| "open"'` | `'open' as const` on the literal. Fixed in **31.2.0**: from it, an `as const` or per-literal annotation added for this TS2322 can be deleted — kept, it is harmless | | `disk('')` is `X_STORAGE_DISK_UNKNOWN` for a disk your own `defineStorage({ disks: { … } })` declares, when an app module reached from `runtime.ts` makes that call: the boot installed its one-disk registry over it | fixed in **31.2.0**: the boot keeps a registry the app declared, and the app's `defineStorage()` wins over `runtime.storage`. Upgrade to it; no workaround is verified for 31.0.0–31.1.0 | | `@ultimat3/auth/schema` (**31.4.0**) exports `AUTH_TABLES`, `AUTH_TABLE_NAMES`, `AUTH_SERVER_TABLES`, `SQL_AUTH_SERVER_TABLES`, `SQL_AUTH_LIMIT_TABLES` and `SQL_TOTP_REPLAY_TABLE` and imports no auth runtime; `@ultimat3/auth` still exports all six | nothing. Optional: a module that reads only those names (a schema reader, a migrate-only script) imports them from `@ultimat3/auth/schema` and stops loading the auth barrel | | `defineError` is exported from `@ultimat3/core/page` (**31.4.1**), and the refreshed `error-declared` guard refuses it imported from `@ultimat3/core`: `X_ERROR_DECLARED` at the import line. Through the barrel, every island that throws an app code carried both framework titles tables: 12,019 B against 6,507 B for one declaration thrown (`As of 2026-11`: Bun 1.4.4, minified) | `import { defineError } from '@ultimat3/core/page'` — the same function, so the swap is the import line only. A `/* @__PURE__ */` or `"sideEffects": false` added to keep the table out is no longer needed for that. `x new` and `x g` write the `./page` import from 31.4.1 | | `x doctor` and `x upgrade` list up to twelve guards as differing from the shipped template after the **31.4.1** hop (`x doctor --json`: `.data.guards.differs[].refresh`). 31.4.1 changed `native-confirm`, `raw-fetch`, `raw-interval`, `unzoned-date`, `semantic-interactive`, `image-dimensions`, `untranslated-string`, `raw-motion`, `undeclared-custom-property`, `undefined-style-class`, `error-declared` and `bare-error` (its `fix:` now names `@ultimat3/core/page`). Your `guards/` copy is the app's own: `x upgrade` never rewrites it | `x g guard --force` per name — it rewrites `guards/.ts` **and** `guards/.test.ts`, so review the diff and keep any rule you edited on purpose. Then `x verify` | | after that refresh, `x verify`'s `boundaries` step reports findings the old guards never saw — all of them already in your code: `X_IMAGE_DIMENSIONS`, `X_SEMANTIC_INTERACTIVE` or `X_UNTRANSLATED_STRING` in `apps/*/shared/**/*.tsx` (the three scanned only `site/` and `app/`); `X_RAW_MOTION` on a raw duration or `cubic-bezier()` assigned to a custom property (`--my-ease: cubic-bezier(0, 0, 1, 1)`); `X_UNDECLARED_CUSTOM_PROPERTY` at a stylesheet that does not compile, `X_UNDEFINED_STYLE_CLASS` at the `.tsx` line importing one — while any sheet fails, `undeclared-custom-property` reports only the broken sheets and checks no `var()` read | fix each where its `fix:` points: the `shared/` component as you would in `app/`; `--my-ease: #{tokens.easing(out)}` for a motion value; the Sass at the compiler error the cause quotes. Then re-run `x verify` — a repaired sheet can surface the `var()` reads it was hiding | | the same refresh drops findings that were false: a file's own function named `confirm`, `fetch` or `setInterval` (a declaration, import, parameter or destructured name), `Intl.DateTimeFormat().resolvedOptions().timeZone`, and a `role="option"` with `tabIndex={-1}` | nothing — a rename made only to quiet one of them can be reverted | | `x doctor` lists `native-confirm`, `raw-fetch` and `raw-interval` as differing from the shipped template after the **31.4.2** hop: their copy from 31.4.1 shows `\u2014` where two comments meant a dash. Comments only; the rule is the same | optional: `x g guard native-confirm --force`, `x g guard raw-fetch --force`, `x g guard raw-interval --force` | | `x doctor` lists `repo-raw-sql` as differing from the shipped template after the **31.5.0** hop: the guard now also reads a `repo-.ts` (a `repo.ts` split at the file ceiling, e.g. `repo-window.ts`) and skips `*.test.ts`; `x verify`'s `boundaries` step may report `X_REPO_RAW_SQL` in a split repo it never read before, and a route importing `repo-` is now `X_BOUNDARY_ROUTE_TO_DB` like one importing `repo` | `x g guard repo-raw-sql --force` — it rewrites `guards/repo-raw-sql.ts` **and** its `.test.ts`, so review the diff and keep any rule you edited on purpose. Then `x verify` | | `undeclared-custom-property` and `undefined-style-class` report ` does not compile: asset("assets/…") ran with no site asset table installed` on 31.4.1 for a sheet that calls Sass `asset()` and builds fine (on 31.4.0, `undeclared-custom-property` passed the whole app on nothing instead). From **31.4.2** a guard's compile resolves `asset()` through the site asset table the build uses, so the sheet compiles and an `asset()` naming a file missing from `apps/web/site/assets/` is still the finding. The fix is in `@ultimat3/cli`'s `GuardSources`, not in a template | nothing to refresh. Delete any placeholder asset table you installed around a guard to work around it, then `x verify` | | built, content-hashed asset routes spend the new `assets` rate-limit bucket (**31.5.0**: 2,000 burst, 200/s), not `default`. An app that lowered `rateLimit.buckets.default` to throttle its static files no longer throttles them that way | to tighten static routes, set `rateLimit: { buckets: { assets: { capacity, refillPerSecond } } }` in `app.config.ts`. Nothing to do otherwise | | `rateLimit.buckets` in `app.config.ts` merges over the shipped buckets key by key (**31.5.0**). Before, any `buckets` you declared replaced the whole table, so `auth`, `mutation` and `assets` were gone and routes naming them used `default` | nothing. A bucket you declared still wins under its own name; delete any copy of a shipped bucket you kept only so it would not disappear | | a `from(entity, fn)` provider's function receives a `RowWindow` (**31.5.0**), `{ after, limit, order, filters }`, the page the read is after | nothing: a function that ignores the argument behaves as before. Optional: a repository that reads its own top N reads `after` and `limit` instead, so later pages are not empty or short | | `x verify`'s `contract-diff` step is red, `X_MANIFEST_BREAKING`, on a breaking change that `x manifest` or `x g` had already written into `x.manifest.json`: from **31.6.0** the baseline is the manifest as committed (at `HEAD`, or at the merge base with `origin/$GITHUB_BASE_REF` in a GitHub pull request), never the working-tree file | bump the major version, or restore the removed surface. Regenerating the manifest no longer clears it | | `x verify`'s `unit` step runs the app's seeds (**31.6.0**; on a migrated scratch database from **31.8.0**): a seed row the entity refuses — float money, a value its schema rejects — turns `unit` red under the entity's own code, and a seed that throws with no code is `X_SEED_FAILED` | fix the seed row the finding names, as its `fix:` says. Then `x verify --only unit` | | `x verify`'s `errors` step reports `X_ERROR_FIX_INVALID` on an app's own error whose `fix:` defers the edit (a whitespace-delimited `# after ing …` or `# once <…>ed`), only says re-run, or runs `x g … --force` (**31.6.0**) | rewrite that `fix:` as the edit itself (`edit .: — `) or a command that works on its own, with no `--force` | | every island and `/_x/assets` URL changes once (**31.6.1**): each is now named by a hash of its final bytes, never its sources (#1075) | nothing to do; a CDN in front needs no purge, since new names never collide with old ones | | Sentry grouping (**31.7.0**): the default fingerprint is `[code]` (`X_INTERNAL`: `[code, ' ']`; `X_CLIENT_ERROR`: `[code, '#']`), and `exception.values[0].stacktrace.frames` carries the stack | nothing: each existing issue reopens once under its code's group, and issues split by operation merge. An alert rule keyed on the old hash moves to the `code` tag (source is a tag, operation is the transaction). `extra.stack` stays through 31.x. Custom grouping: `sentryErrorReporter({ fingerprint })` | | `x verify`'s `unit` step runs the app's seeds on a migrated scratch database (**31.8.0**): `x exercise`'s embedded PGlite with the framework schema and the app's migrations (a server from `TEST_DATABASE_URL` when a migration needs an extension PGlite cannot link), so a seed that calls `register()` or `db()` passes. A seed that writes an entity with no migration behind it is now `X_DB_SCHEMA_STALE`, as `x db seed` already said | nothing for an app with migrations. Otherwise `x db gen initial`, then `x verify --only unit` | | `pollEvery` / `visibleInterval` back off on failure by default (**31.7.0**): `maxMs` is 8 × `ms` | nothing, unless a poll must keep hitting a failing endpoint at full rate: pass `{ maxMs: }` equal to `ms` | | `requestMemo(ctx)` from `@ultimat3/query` returns `MemoFlights`, not a `Map` (**31.7.0**) | a caller that wrote into it: use `memoFlights(ctx, name)` from `@ultimat3/cache`, or `memoPerRequest(fn, key)` for a plain function | | `buildSitemap` / `sitemapUrls` option `now: Date` is deprecated (**31.7.0**) | pass `clock: frozenClock(now)` instead | | a compiled web role cropping or compositing a raster above `RASTER_SYNC_PIXELS` where no Worker can start answers `X_IMAGE_RASTER_BUDGET` (503) (**31.7.0**) | move the transform into a `warmVariants` job | | the authorization server stops issuing and honouring refresh tokens for a client registered with explicit `grantTypes` that leave out `refresh_token`, e.g. `['authorization_code']` (**31.7.0**): its existing refresh tokens answer `unauthorized_client` | add `'refresh_token'` to that client's `grantTypes` if it should keep them | | a confidential client sending its secret by the method it did not register answers `invalid_client` (**31.7.0**) | switch the client to its registered method, or `update x_oauth_clients set auth_method = '' where client_id = ''` | | a sealed column no longer enters a history image (**31.7.0**, security): `x verify` reports `X_DB_DRIFT` in every app with `history: true` until it migrates, since the shared `ultimate_record_history` body changed. Rows already written still hold sealed ciphertext | `x db gen "history leaves sealed columns out"`, then `x db migrate`. Then, per history table whose parent has sealed columns: `begin; alter table "_history" disable trigger "ultimate_history_guard"; update "_history" set "before" = "before" - array['

', ...], "after" = "after" - array['', ...]; alter table "_history" enable trigger "ultimate_history_guard"; commit;`. If history left the database (exports, admin), treat lookup ciphertext as leaked and rotate the seal key | | `.search()` through a non-Postgres search index answers `X_INVARIANT_VIOLATED` when a term matches 10,000 or more rows (**31.7.0**); before, it silently counted and paged only the first 10,000 | narrow the term, or `installSearchIndex(postgresSearchIndex())` | | a multipart part URL on a local or memory disk signs its exact length (**31.8.0**: `x-len`, `v3-part`): one minted before the upgrade is refused, and a part shorter than signed is `X_STORAGE_URL_INVALID`, as on s3 | nothing: `uploadFile` re-requests the part URL (each expires in 15 min anyway). A client of its own calls `signPart` again with the part's exact `size` | | `x db gen` builds an index on an existing table `concurrently` by default (**31.8.0**), in a `-- transaction: false` follow-up file; `x verify` refuses an unmarked lock-heavy migration newer than `20261113000000` (`X_MIGRATION_LOCK_HEAVY`) | generated migrations: nothing. A hand-written `create index` on an existing table: `create index concurrently` in a file whose first line is `-- transaction: false`, or `-- lock-heavy: true` for a deliberate plain build. A hand-written `set not null`: a `check (… is not null) not valid` constraint, validated in the next migration, first | | drift can newly report `changed-index` (**31.8.0**) for a live index of a declared name that a hand edit gave `INCLUDE` columns or a non-default operator class: drift now compares both | rebuild it as declared — `drop index concurrently` then `create index concurrently` in a `-- transaction: false` migration — or give the hand-built index a name of its own: a live index no snapshot names is never drift. Through 31.9.x an entity's `indexes:` cannot declare `include` or an operator class; from **31.10.0** it can (`include`, `operatorClass`, [Index key parts](Entities-And-Migrations#index-key-parts)) | | an anonymous, compressible, public answer carries `W/"…"` whenever the request offers a coding (**31.8.0**), even when too small to be coded; the 304 carries the same form | nothing. A client comparing that ETag strongly switches to weak comparison | | the boot runs `alter table x_rate_limit set unlogged` (**31.8.0**): a rewrite under ACCESS EXCLUSIVE of a tiny table, bounded by the migrate `lock_timeout`. After a Postgres crash, or on a promoted standby, every bucket comes back full — one free burst per key, never a lockout; a clean restart keeps the buckets. `x_auth_lockouts` stays logged. An app that commits the framework schema dump (`packages/db/schema/framework/`) sees `X_SCHEMA_DUMP_DRIFT` on `x_rate_limit` until it regenerates it | `x db gen` once, commit the regenerated `04_tables/x_rate_limit.sql` (now `create unlogged table … with (fillfactor=70)`); no migration | | a routine 401/403/429 refusal logs `debug` after the first `info` line per route per minute (**31.8.0**) | an alert keyed on those `info` lines moves to the `http_refusals_total{code}` counter | | a read whose page weighs more than `MAX_PAGE_BYTES` (64 MiB) before decoding is `X_ENTITY_PAGE_TOO_LARGE`, a 500 (**31.9.0**), on Postgres, memory and `defineDriver` alike — a test storing big rows in memory meets it too. Before, the page was decoded whole. `inBatches()` halves its batch instead of refusing, down to one row | paste the `fix:` onto that read: `.select({ … })` without the heaviest column it names, and the `.limit(n)` that fits — or `.inBatches(n)` to visit every row. A single row over 64 MiB on its own stays refused: move that value to storage | | `updateMany`, `copyAll` and the `{ returning: false }` forms (**31.9.0**) reach a hand-written `Repo` — a `Driver.repo()` not built with `defineDriver` — through fallbacks, as optional members: `updateMany` is one `updateWhere` per row (n statements, no duplicate-id or same-columns refusal, atomic only inside `withTransaction`), `copyAll` and a count form are `insertAll(…)` / `upsertAll(…)` counted. A `defineDriver` store needs nothing | nothing. For one statement, implement `updateMany`, `insertAllCount`, `upsertAllCount` and `copyAll` on the repository (`Repo` in `@ultimat3/entity`) | | `deletePlan` / `updatePlan` from `@ultimat3/entity/adapter` are the shipped names of `writeWherePlan` / `updateWherePlan` (**31.9.0**): the same arguments and refusals, plus an optional `options.where` for a chain's predicates | nothing | | `X_SUBJECT_TABLE_UNDECLARED` for `
_history` (**31.10.0**, security): a `defineSubject()` that deletes or anonymizes an entity declared with `history: true` now reaches its history table, because that write records the person in one more before image. The run refuses before touching a row, and `x verify`'s `exercise` step reports it. Before, an erased person's data survived in `before`/`after` images | add the history table to `tables`: `posts_history: 'delete'` (every row whose `before` or `after` image names the subject, a row deleted before the erase included, removed in the parent's own transaction) or `posts_history: { retain: '' }`. Images of people erased before the upgrade stay until removed by hand, per table: `begin; select set_config('x.purge', '_history', true); delete from "_history" where row_id = any(array['', …]); commit;` — the ids from the images themselves, e.g. `select distinct row_id from "_history" where before->>'' = ''` | | `andWhere(col, 'contains', term)` on a `text()`/`char()` column is a case-insensitive substring match (**31.10.0**). Before, Postgres refused the statement (`text @> text[]`) and the memory driver compared for equality, so a test passed that production failed | where equality was meant, `andWhere(col, 'eq', term)`. Where search was meant, keep it and declare `indexes: [{ on: [''], using: 'gin', operatorClass: 'gin_trgm_ops' }]`, then `x db gen "trigram "` — without it the plan sweep reports `X_QUERY_UNINDEXED` | | `database()` over a `defineDriver` store throws `X_DRIVER_UNSUPPORTED` (`meta.capability: 'countedIn'`) for an entity whose column declares `countedIn` (**31.10.0**). Before, the parent's count silently never moved | serve that entity with `postgresDriver()` or `memoryDriver()`, or drop `countedIn` from the column and read `db..countBy('')` instead | | `registerClient()` throws `X_AUTH_CLIENT_INVALID` (422, `meta.field`) for a redirect URI, grant type, scope or resource that is empty or contains whitespace (**31.10.0**). Before, it was stored and read back as a different list | split the value into one element per item: `registerClient({ name, scopes: ['read', 'write'] })`, never `['read write']`. Rows already stored: `select client_id, redirect_uris, scopes from x_oauth_clients` and re-register any whose list is wrong | | a `development` or `test` process logs `entity.all.truncated` (`ALL_TRUNCATED`) when `.all()` dropped a next page and its chain named no `.limit(n)` (**31.10.0**). The rows answered are unchanged: one page | `.inBatches(n)` where every row was meant; `.limit(n)` where one page was | | a `countedIn` child write publishes an `entity.row` `update` for the parent row on memory and Postgres, PGlite in `x dev` included (**31.10.0**), so a live view of the count moves by itself | nothing. A mutator that recounted only to move a live view (`countBy` then `update`) can drop the recount | | `AuthAdapter` gains the optional `getSessionWithUser(id)` (**31.10.0**); `postgresAuthAdapter` and `memoryAuthAdapter` implement it, taking `authenticate` from two statements to one | nothing. A hand-written adapter may add it — `{ session, user \| null }` or `null`, what `getSession` then `findUserById` answer — and run `authAdapterConformance` on it | | an entity that adds `version: ''` (**31.10.0**, opt-in) refuses `update(id)` without the version, setting it in `updateWhere`, and `upsertAll` with the default `onMatch: 'update'` — a seed's `upsertAll` included (`X_ENTITY_VERSION_INVALID`) | carry the version read: `update(id, { …patch, lockVersion: row.lockVersion })`; a seed uses `upsertAll(rows, { onConflict, onMatch: 'nothing' })` | | a read whose policy is `scoped()` (`@ultimat3/policy`, **31.10.0**) has the scope composed into its `from()` source before the page is cut (**31.11.0**): a page that came back short because the rule dropped rows after the cut now comes back full, so a page's rows and its `nextCursor` can differ from 31.10.x. The rule still runs on every row. Such a read is cached per actor, whatever its `cache.scope`. A scoped policy on a read whose `sql` returns a hand-written `SqlSource` is `X_QUERY_SCOPE_UNCOMPOSABLE` (500) on every call | nothing for a `from()` read. Under `X_QUERY_SCOPE_UNCOMPOSABLE`: return `from(entity, (window) => repo.window(window))` from `sql`, or keep the hand-written source and declare the policy without `scoped()` | | a `development` or `test` process logs `query.live.order_collation` (`X_LIVE_ORDER_COLLATION`) once per live query ordered by a declared text column (`text()`, `enumerated()`, `url()`, `tz()`, `locale()`) not `.collate('C')` (**31.11.0**). Nothing is refused and nothing else changes; staging and production stay silent. A refusal at subscribe is planned for `next` | for a `text()` column, declare it `text().collate('C')` and run `x db gen "
collate C"` (an in-place `alter column … collate "C"`; the column's visible order becomes code-point order everywhere it is read), or order the live read by a non-text key: `.orderBy('createdAt', 'desc').orderBy('id')` — the only fix for `enumerated()`/`url()`/`tz()`/`locale()`, which have no `.collate()` | | `x verify`'s `manifest` step lists `X_NATIVE_FORM_UNANSWERED` under `warnings` for each `page.tsx` `
` posting to an action with no `native` (**31.11.0**). The step stays green; a refusal is planned for `next` | add `native: { success: (output) => '/where-it-lands' }` to that action's declaration, then `x verify --only manifest` | | an action that declares `native` answers a refusal with a 4xx other than `X_UNAUTHENTICATED` to a browser form POST as a `303` (**31.11.0**). `X_UNAUTHENTICATED` keeps the sign-in redirect, so a protected form posted signed-out lands on sign-in as before; a sign-in action's own 401 (a wrong password) is a refusal and lands back on its form with its code. Without `native` nothing changes | nothing. A sign-in page that showed its failure some other way reads `useActionAnswer('')` in its route's `load`: `outcome: 'refusal'` and the `code` the sign-in threw. Any 401 a sign-in throws must use its own code, never `X_UNAUTHENTICATED`, or it takes the sign-in redirect | | an action that answers a browser form by sniffing `accept` itself (**31.11.0**, optional) | delete the hand-written `if (accept includes 'text/html') setRedirect(next)` from `handle` and declare `native: { success: (output) => output.next }` on the action. A `setRedirect()` still in `handle` keeps winning on success, so a sign-in's per-request `next` can stay where it is | | the first boot on **31.13.0** drops `x_jobs_finished_idx`, builds `x_jobs_ended_idx` and sets `x_jobs` to `fillfactor = 80`, inside the locked framework-schema apply. The index build is not `concurrently` (the apply is one transaction): enqueues, claims and settles wait for one build over `x_jobs`, bounded by the migrate `lock_timeout`. Existing pages reach the fillfactor as rows churn; nothing is rewritten. An app that commits the framework schema dump (`packages/db/schema/framework/`) sees `X_SCHEMA_DUMP_DRIFT` on `x_jobs` until it regenerates it | on a large `x_jobs`, roll the `migrate` job at a quiet hour. Then `x db gen` once and commit the regenerated `04_tables/x_jobs.sql` (`with (fillfactor=80)`) and `05_indexes/x_jobs.sql` (`x_jobs_ended_idx`); no migration | | a killed scheduler leader's standby takes over up to ~80 s later (**31.13.0**: the 60 s lease, then its next ask, every 20 s; was ~40 s), and a drained leader's within 20 s (was 10 s) | nothing: the boot's leader takes no TTL from `app.config.ts` (`postgresLeaseLeader({ executor })`, `packages/cli/src/role-start.ts`). A scheduler you start yourself can pass `postgresLeaseLeader({ executor, ttlMs })` | | a killed worker stays in `workers()`, `x jobs`, `/admin/jobs/workers` and `x deploy verify`'s queue grade for up to 60 s (**31.13.0**: the registry row lives `max(60 s, visibility timeout)`, renewed every 20 s; was one visibility timeout, 30 s by default) | nothing. A deploy check that counts live workers right after killing one waits 60 s | | `counters()` / `counterTotals()` read from another process than the one that settled can lag up to 10 s (**31.13.0**: the Postgres driver writes settle counts in a per-process batch every 10 s and on `close()`); a crashed process loses at most its last 10 s of counts. A read in the settling process flushes first. Job rows and `stats()` are exact as before | nothing. A test that settles in one process and reads counters in another calls `close()` on the settling driver first | | an on-time `jobs.scheduler.dispatched` logs at `debug` (**31.13.0**); a catch-up fire and `jobs.scheduler.already-fired` stay `info` | an alert or dashboard keyed on `jobs.scheduler.dispatched` at `info` keys on `catchUp: true` for missed fires, or sets `LOG_LEVEL=debug` on the `scheduler` role to keep every line | | with a proven wake, an idle worker rests up to 60 s between claims (**31.13.0**; was ≤ 5 s). An enqueue due within 60 s now notifies (was within 1 s), so a delayed job another process queues still starts at its `runAt`; a worker that stops holding a retry or `step.sleep` due soon announces it (`JobDriver.wake`). Only a driver with `wake` rests — Redis keeps the 5 s poll | nothing for the shipped drivers. A custom `JobDriver` whose enqueues reach every worker adds `wake(queue?)` to let its workers rest; without it they keep the 2–5 s poll | | a custom `JobDriver` or `OutboxStore` proved with `behavesLike(jobDriverConformance, …)` / `behavesLike(outboxStoreConformance, …)` (`@ultimat3/testing/conformance`) meets new checks (**31.13.0**): an empty claim calls `ClaimOptions.onEmpty(dueInMs)` (`null`, a delayed row, a held lease), a claimed row carries `steps`, and an empty outbox `claim(limit, { onEmpty })` reports a held row's lease | implement them — `memoryJobDriver` and `memoryOutboxStore` are the shapes to copy — or keep the driver unproved: each is optional on the interface, and a driver without them keeps the 2–5 s poll and the per-attempt step list | | the first boot on **31.14.0** adds `x_jobs.expires_at`, `x_jobs.settle_owed` (`boolean not null default false`) with the partial index `x_jobs_settle_owed_idx`, `x_jobs.debounced_id` (`uuid`) with the partial index `x_jobs_debounced_idx`, and `x_outbox.on_conflict` / `x_outbox.expires_at`, inside the locked framework-schema apply — additive, no row rewritten. An app that commits the framework schema dump (`packages/db/schema/framework/`) sees `X_SCHEMA_DUMP_DRIFT` on `x_jobs` and `x_outbox` until it regenerates it | `x db gen` once and commit the regenerated `04_tables/x_jobs.sql`, `04_tables/x_outbox.sql` and `05_indexes/x_jobs.sql`; no migration | | `onSettled` can now run more than once for one ending (**31.14.0**): a failure, a dead letter, a `whenBusy: 'fail'` refusal or a completion whose body returned `undefined`, when the worker died between the settle and the hook's return — re-driven by the scheduler leader with `settled.redriven === true`, `reason: 'lost'`. A completion that returned a value, a final-attempt lease lapse the claim buried and an expired row are still told at most once | write the hook to be repeated: an upsert or a guarded update, a notification keyed by `settled.input` and the outcome. Branch on `settled.redriven` where a repeat must be told apart | | `jobs.step.output-too-large` (`X_STEP_OUTPUT_TOO_LARGE`) at `warn`, once per job and step, for a `step.run` output past 256 KiB of JSON (**31.14.0**). Stored as before; refused by default from the next major | `step.run(name, async () => { await storage.put(key, bytes); return key; })` — persist the payload and return its key; or declare `job({ stepOutputMax: })`, which refuses past it now (terminal) | | `x verify` reports `X_PARTITIONS_UNMAINTAINED` in an app with an entity declaring `partitionBy` and no `partitions()` job, where a job carrying a `.schedule` task — a `cronJob()`, or one built by hand that way — used to satisfy it (**31.14.0**: a maintainer is recognised by identity, `isPartitionsJob`) | export `partitions()` (`@ultimat3/jobs`) from a module listed under `jobs` in `apps/web/api/index.ts` and its `.schedule` under `tasks`, then `x verify --only manifest --json` — the error's own `fix:` | | a custom `JobDriver` or `OutboxStore` proved with `behavesLike(jobDriverConformance, …)` / `behavesLike(outboxStoreConformance, …)` meets new checks (**31.14.0**): `onConflict: 'replace'` (fenced by request order, a repeat after the holder ran included) and `expiresAt` on `enqueue`, `backlog(queue, cap)`, `holds(name, key, tenantId?)`, the `settleDebt` debt, a requeue that clears expiry and debt, and a staged row keeping `onConflict` / `expiresAt` | implement them — `memoryJobDriver` (`driver-memory-enqueue.ts`, `driver-memory-settle.ts`) and `memoryOutboxStore` are the shapes to copy — or keep the driver unproved: `backlog` and `settleDebt` are optional, and without them a job declaring `maxPending` is `X_INVARIANT` at enqueue and `onSettled` stays at most once | | a realtime hook created inside a component is released when that component is disposed (**31.14.0**): `x build`'s island bootstrap calls `installRealtime({ signal: createSignal, cleanup: onCleanup })`, and every `use*` hook registers its own `release()` through it. Before, it lived until the island called `release()` — or, forgotten, until the page unloaded, holding a socket subscription and a cap slot. A handle the island kept using after its component went (stored in a module variable or a parent's state) now reads nothing new | create a long-lived handle outside any component — at module scope or in `mount`, before `render()`: no owner, nothing registered, its `release()` is yours. A hand-built island (one that calls `installRealtime` itself) adds `cleanup: onCleanup` from its own `solid-js`; without it every `release()` stays the island's. An `onCleanup(() => h.release())` already written is harmless: a release runs once. Optional: delete it | | `x doctor` lists `raw-interval` as differing from the shipped template after the **31.14.0** hop: its `fix:` now names `useQuery(ref, input, { poll: pollEvery(ms) })` for a query's timed re-read, before `visibleInterval(run, ms)`. The rule is the same; nothing new is reported | `x g guard raw-interval --force` — it rewrites `guards/raw-interval.ts` **and** its `.test.ts`, so review the diff and keep any rule you edited on purpose. Then `x verify` | | a replicator restart chains (**31.14.0**): the change envelope is version 2 — a run's first envelope carries `from`, and a clean stop publishes a handover on `x.change.-handover` — so a deploy of the `replicator` role after a clean stop re-snapshots no live window. A crash still costs one re-read per window. During a roll, an old node reading a new replicator, or a new node reading an old one, reads the restart as a gap, exactly as before | roll the `sync` role before the `replicator` role. Either order is safe; only nodes already on 31.14.0 chain the replicator's own restart. A custom `ChangeFeed` (`@ultimat3/realtime/server`) chains only once it implements the optional `position()` and `onResume` | | an island whose render throws can show its server HTML instead of a blank box (**31.15.0**): `mountOver(el, draw)` from `@ultimat3/render/client` clears the wrapper, draws, and puts the server markup back on a throw (then rethrows, so `data-x-failed` and `clientErrors` still fire). `x g island`, `x new` and the resource form island write it; an older island keeps working as it was | `x g guard island-mount-clears`, then `x verify --only boundaries`: for each finding delete `el.textContent = ''` and end `mount` with `return mountOver(el, (root) => render(() => , root))`, adding `import { mountOver } from '@ultimat3/render/client'` | | every `/_img/` URL a static export writes changes once (**31.15.0**): a variant is named by the hash of its source bytes, width, format and encoder (framework + Bun version), no longer the source hash alone, so an upgrade that may re-encode an image never serves other bytes under an `immutable` name | nothing. A CDN fetches each image once again | | an exposed LIST query's MCP tool answers at most 500 rows and 256 KiB of JSON per call (**31.15.0**), with `truncated` and a `nextCursor` when cut short; an agent or test that read every row from one call now gets the first page | follow `nextCursor`: call the tool again with `_after: ` until it is `null`. An answer that fits is the bare rows, as before | | unauthenticated MCP failures are counted per IPv6 /64, not per address (**31.15.0**) — the key `@ultimat3/http`'s limiter uses — and `mcp.auth.*` lines log that network, never the full address; `mcp.auth.missing-token` logs at `info` | IPv6 clients sharing a /64 now share one allowance of 20 a minute: where that is legitimate traffic, raise `defineAppMcp({ rateLimits: { unauthenticated } })` (or `mcpHttpRoute`'s). An alert keyed on `mcp.auth.missing-token` at `warn` keys on `info` | | an `llm()` / `generate` / `stream` call that stops early now spends budget (**31.15.0**): a stream abandoned, cut or aborted after its first provider byte records the running usage; any call aborted after its request was sent records the prompt's estimate. Before, all of these released the whole reservation. Only a call never sent, or refused by the provider, is free | raise `tokensPerRun`, `costPerRun` or an actor/org ceiling that was tuned against the old under-count. A custom `Provider` reports nothing and keeps the old release | | a `postgresVectorStore` search runs in a read-only transaction that widens the HNSW scan (**31.15.0**: `hnsw.iterative_scan = relaxed_order` on pgvector ≥ 0.8, else `hnsw.ef_search = max(40, k × 10)`), 2–3 round trips where it was 1, so a small tenant gets `k` hits | nothing. On pgvector < 0.8, upgrade the extension for the cheaper iterative scan | | `x build --target static` writes `.br` (brotli 11) and `.gz` (gzip 9) siblings beside each island chunk and stylesheet (**31.15.0**), and the app brand ships at the end of each surface stylesheet instead of an inline `