29.x → 30.0.0, entry by entry
Released 2026-11-07: CHANGELOG.md's ## 30.0.0 breaking entries in their order, grouped by package, lowest tier first. No legacy path, no codemod, no shim. Rows are never renumbered; each row's CHANGELOG.md line names it as (#N) after the dash.
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/*, raises the Bun floor, installs and runs the gate | X_UPGRADE_DIRTY_TREE on a dirty tree | — |
| 2 | x db gen "same-tenant keys", commit packages/db/migrations and packages/db/schema/. A validate failing X_DB_FOREIGN_KEY_VIOLATION found rows already pointing across tenants: decide those rows, or state crossTenant: '<reason>' on an edge that means it | X_DB_DRIFT from drift, and X_SCHEMA_DUMP_DRIFT for the new framework columns. An entity whose { table } differs from its name moves its keys to the table they always meant in the same migration. X_DB_DRIFT from a dump column no snapshot records is an edited migration: restore it | 8, 25, 46, 53 |
| 3 | x verify --only typecheck and close every error: a Date off a step result, step.waitForEvent with no schema, a hand-written TotpReplayGuard, DeliveryLedger, JobDriver or StorageDriver, a hand-built ReferenceDescription or PoolProfile, a Record<StageName, …>, 'queue-depth', REPLAYED_HEADER from @ultimat3/action, requestedUrls(), suspenseBoundaries, csrfBlocked with two arguments, a read of DownloadFile.body, ERROR_PAGE_LINKS.homepage, FormSchema or its siblings from @ultimat3/ui, JSX_NODE from @ultimat3/render, a hand-written JobHandle or JobsFacade, an exhaustive switch or Record over ErrorSource, a hand-built AppConfig, retentionPlan / RetentionPlan / Deploy from @ultimat3/pwa, retainBuildIds passed to generateServiceWorker, input.prompt off a DefineEvalInput, MCP_PROTOCOL_VERSION, an exhaustive switch over McpAuthRefusal | a compile error at each site | 8, 16, 21, 22, 25, 30, 32, 35, 39, 40, 43, 44, 45, 47, 50, 57, 58, 61, 62, 65, 66, 67, 68, 69, 70, 73 |
| 4 | x verify --only manifest: correct a misspelt name in mcpConfirmations({ tools }), or expose the action, or build a hand-written server at module scope in apps/<app>/mcp.ts. For a role load, add the import its fix names to apps/web/api/index.ts, or move the declaration into a module that imports no .tsx and no stylesheet | X_MCP_CONFIRMATION_TOOL_UNKNOWN, X_ROLE_LOAD_INCOMPLETE | 18, 27 |
| 5 | x verify --only unit,contract,job: move each fixture the new refusals name | X_DB_TRANSACTION_CLOSED, X_INVARIANT_VIOLATED, a memory-driver fixture wiring two tenants refused, X_N_PLUS_ONE_QUERY from a memory-backed loop now counted, X_MAIL_KEY_MISSING from a mail test, an enqueue spy on a spread memoryJobDriver() that enqueueMany or the relay no longer calls | 3, 4, 8–14, 19, 20, 41, 48, 63 |
| 6 | grep -rnE "render: '(isr|static)'" apps/: a page varying per visitor becomes ssr, and every parameter a load or page reads goes in revalidate: { query: ['<name>'] } | nothing fails: a signed-in load sees nobody, and a query the key dropped serves one document for every value | 23, 24 |
| 7 | grep -rnE "upsertAll|seed\.upsert" apps/ packages/: name each column a collision must overwrite. A wide insertAll that relied on partial progress splits its own batch | nothing fails: a timestamp stops moving on re-upsert, or a failed batch leaves no rows | 11, 12, 13 |
| 8 | read mcpConfirmations({ tools }) against every agent({ tools }) and every MCP server: the agent's output reports the pending confirmation id, and a tool that must run unconfirmed leaves tools | the write answers X_MCP_CONFIRMATION_PENDING and writes nothing | 17, 26 |
| 9 | before the next column drop: declare it retired, deploy, then drop | X_MIGRATION_ROLLING_UNSAFE from x db gen | 5 |
| 10 | before the deploy: move a CDN rule keyed on public, immutable for /media; re-upload through the server an XML or +xml object over 64 KiB that awaits promotion | a CDN miss; X_STORAGE_TYPE_REJECTED at promotion | 6, 7, 15 |
| 11 | grep -rnE "onShutdown|retry\(" apps/: reorder a close hook that depends on running first; wrap a retry or a write that must outlive its caller in runToCompletion(fn) | nothing fails: a write or a retry stops with its caller | 1, 2, 3 |
| 12 | grep -rn "'null'" apps/ packages/, and read each list built from URL.parse(…).origin: list real origins with their scheme | X_CORS_CONFIG_INVALID at boot | 28 |
| 13 | read each HeadTag with a non-http(s) href: serve an inline SVG favicon from site.favicon, or a same-origin path under assets/ | nothing fails in production; head.attribute_dropped once in dev | 29 |
| 14 | x manifest, commit openapi*.json and x.manifest.json, once, after every other edit | X_MANIFEST_STALE from manifest | 38, 42, 49 |
| 15 | x verify --only manifest for X_JOB_OUTLASTS_DRAIN: raise drain.workerRetireMs or lower the job's timeout | X_JOB_OUTLASTS_DRAIN naming the job, its limit and the budget | 52 |
| 16 | x verify --only i18n, then x i18n sync <locale> per locale it names, and translate what it seeds. Add the framework's mail.* keys meta.keys lists to packages/i18n/catalogs/<locale>.json by hand. A subject interpolates only the payload's top-level scalars: put each {slot} there | X_CATALOG_MISSING_KEYS; X_MAIL_KEY_MISSING from send() | 33, 34, 48 |
| 17 | x verify --only boundaries: move each packages/* file's runtime import of apps/* down. A scaffold from before 30.0.0 has two: packages/mcp/src/index.ts (export const appMcp = () => defineAppMcp({ name, include: 'exposed' }), no import of apps/web/api/health) and packages/db/src/seed.ts (const DEMO_ORG_LABEL = 'org:demo';) | X_BOUNDARY_PACKAGE_TO_APP | 55 |
| 18 | x g query / x g backfill take --feature <slice>; a new table is x g resource <name> | X_FEATURE_REQUIRED, zero files written | 54 |
| 19 | every upload action's input carries size: file.size; every disk.signedUrl(key, { method: 'PUT', maxBytes }) on s3 adds contentLength: file.size; S3_FORCE_PATH_STYLE is 0, 1 or blank in every environment | X_STORAGE_UPLOAD_SIZE_UNDECLARED; X_CONFIG_INVALID at boot; a 403 SignatureDoesNotMatch for a client PUTting another length | 36, 37, 56 |
| 20 | before the deploy: the autoscaler adapter gains max by (queue) (queue_demand) and an app's own chart its worker HPA metric; set drain.workerRetireMs (or 0 for the old stop) and re-deploy with x deploy --method helm. A scaffolded chart's preStop arrives by editing docker/helm/templates/_helpers.tpl: const end = Date.now() + {{ int $cfg.retireSeconds }} * 1000; for (let n = 1; Date.now() < end; n++) | the HPA reads a metric nothing publishes; an old worker Terminating up to an hour while it holds a job | 30, 51 |
| 21 | before the deploy: a transaction's slow outbound await moves before withTransaction; a pod behind a pooler sets DATABASE_POOLER and both bounds with alter role, as X_DB_POOLER_OPTIONS_REFUSED prints; size DATABASE_POOL_MAX from the pool gauges | X_DB_STATEMENT_FAILED (25P03) on an idle transaction; X_DB_POOL_EXHAUSTED where a statement used to queue | 31, 32 |
| 22 | x verify --only budgets: it now builds when .x/build-stats.json is missing or older than your source. A route it finds over budget: shrink it, or raise the budget by the measured figure with the reason. Raise stepTimeoutMs.budgets in x.verify.json if the build outlasts the 5-minute step deadline | X_BUDGET_EXCEEDED on a route stale stats hid | 59 |
| 23 | optional: delete bin/check.ts and the check script, and run bun run verify (x verify) locally and in CI. A script that killed x dev by pid or pkill calls x stop --json | nothing fails: bun run check still works and does not build twice | 60 |
| 24 | a compose deploy of an app scaffolded before 30.0.0: in docker/docker-compose.prod.yml's x-image block, tmpfs: [/tmp, '/app/.x:uid=1000,gid=1000'] (1000 is the USER of docker/Dockerfile), then x env init --production if the app has no .env.production | X_STORAGE_UNWRITABLE … EACCES at boot on every role; X_DEPLOY_ENV_MISSING before the first step | — |
| 25 | grep -rn "outboxRelay(" apps/ packages/: a relay that runs the row loop (a driver without enqueueMany, such as redisJobDriver) against very slow publishes passes batchSize: 100 | nothing fails: 500 rows must publish inside the 30 s claim lease, or they are claimed again | 64 |
| 26 | optional, a repository that copies ci.yml's tested job (CI-Parallel-Gate): give each reused job, the verdict job included, needs: tested and if: ${{ !cancelled() && needs.tested.outputs.tested != 'true' }} and no other if | without !cancelled(), a red or cancelled tested skips every job instead of running them | — |
| 27 | an MCP client: a browser page on another origin calling POST /mcp lists that origin in http.cors.origins; a script reaching x mcp serve through a LAN name or a tunnel uses localhost; a test pinning initialize's 2025-06-18 answer offers that revision | 403 X_MCP_ORIGIN_REFUSED; 421 X_MCP_HOST_REFUSED; protocolVersion: '2025-11-25' | 71, 72, 74 |
| 28 | x verify --only typecheck: add createRoot to each setSolidRuntime call, ui.first to a Record<UiKey, string>, errors to a hand-built descriptor, raw to a hand-built WorkloadToken; drop each read of QueryPoll.ms. Add failureCapture and time to a hand-built AppConfig, detectedCookie to a full TimeZoneConfig, queryGraph to a DevHost, mailTemplates to a hand-built DevSources, and the caller to each direct read of an MCP resource. Add the 48 keys entry 122 lists to a Record<UiKey, string>, a null check to each read of ChartPoint.value and each barRects() rect, none to a direct chartTable() call, and async to a hand-built refetch; make an interface that extends OpenGraph, BarChartProps or TabsProps a type … = … & { … } | TS2345, TS2741, TS2339, TS2554, TS18047, TS2312, TS2322, TS2375 | 75, 77, 82, 83, 86, 111, 114, 115, 116, 117, 119, 121, 122, 123, 125 |
| 29 | x verify --only contract: give each guarded action and query an exercise, and fix what its generated input finds. A keyset list that drew a disabled Previous takes firstHref | X_CONTRACT_EXERCISE_UNDECLARED, X_CONTRACT_DEFECT, X_CONTRACT_EXERCISE_UNREACHED, X_UI_INVALID_VALUE | 76, 78, 80, 81 |
| 30 | grep -rn "refresh()" apps/: a caller that wanted focus on <main>, the title read out, or a navigation cancelled says so itself | nothing fails: focus stays where it was | 79 |
| 31 | x verify --only e2e: name what the audit lists — visible text, aria-label, <label for>, alt (alt="" for a decorative image), a <title>, <html lang>, nothing focusable under aria-hidden — or give that test { a11y: { allow: [{ role, selector, because }] } }. A raw-tab test (browser.session.newTab()) names what it lists too, or calls allowA11y([{ role, selector, because }]) before the navigation. A hand-written E2eBrowserPage implements or forwards accessibilityTree(request) | X_E2E_A11Y_VIOLATION naming each element; X_TEST_FIXTURE_UNAVAILABLE from every e2eTest on a page without the method | 88 |
| 32 | x verify --only unit,contract: a test that asserted a factoriesFor value by its old name rule asserts the declared one, or builds it with defineFactory; a test that relied on a memory write surviving a failed memoryTransactor().run writes it outside the transaction | an assertion on an old name-derived value (<column>-<index>, new Date(0), 'USD' in a …Currency text column) fails; X_SEED_GRAPH_UNSATISFIED; a row gone after a rolled-back transaction | 89, 90 |
| 33 | x exercise --json: paste each printed fix: entry into apps/web/exercise.ts's defineExercise({ … }) — an actor its policy allows, an input binding a real row — or give the primitive { off: '<why>' }; then x exercise <name> --json for that one. An app with no apps/web/exercise.ts writes import { defineExercise } from '@ultimat3/testing'; export const exercise = defineExercise({}); first | X_CONTRACT_EXERCISE_UNREACHED from the exercise step, one per primitive | 91 |
| 34 | for each entity exercise names: orgId: uuid().tenant() in its columns, x db gen '<table> tenant', and on a table that already holds rows x g backfill <name> --feature <slice> to fill it; or entity('<name>', { shared: '<why it belongs to no tenant>' }) | X_ENTITY_TENANT_UNDECLARED from the exercise step | 92 |
| 35 | x verify --only unit,contract,job: await every write inside a memoryTransactor().run; a test that asserted an onCommit effect right after a nested run asserts it after the root's | X_DB_TRANSACTION_CLOSED; an effect not yet run where the old one had run | 93 |
| 36 | x db gen, commit packages/db/schema/; x verify --only seo and add each description it names (or seo: { llms: false }); then x exercise --json and close each plan finding with the indexes: line and x db gen it prints, or a stated scan, expectedSeqScan or expectedQueryLoop reason | X_SCHEMA_DUMP_DRIFT; X_SEO_LLMS_DESCRIPTION_MISSING; X_QUERY_UNINDEXED, X_QUERY_SORT_UNSERVED, X_QUERY_SCALES_WITH_ROWS | 112, 113, 118 |
| 37 | x verify --only unit,contract,e2e: mock each module in the file that reads it, and move a test pinning a palette order, an empty chart gap cell or deltaOf(x, 0) === undefined to the new answer. Then x build --target static: put each image a finding names under apps/web/site/assets/ and pass asset('assets/<file>'), or drop avif from that route's formats. Read each served responsiveImage() over asset() for its own widths or formats, and each defineTheme() brand for chart-1 and chart-5 against bg-soft. A site route whose prerender() or load reads the app's own query passes entries: report.entries, llmsPages: report.llmsPages to siteSeo({ … }) in apps/web/prerender.ts | X_TEST_MODULE_MOCK_UNRESTORABLE, or a test that reads the real module; X_UI_INVALID_VALUE; X_IMAGE_SOURCE_UNREADABLE, X_IMAGE_UNSUPPORTED; 404 X_ASSET_VARIANT_UNDECLARED; X_UI_CONTRAST_INSUFFICIENT; X_CLIENT_TRANSPORT_FAILED from the export | 120, 124, 126–130 |
| 38 | x verify --only boundaries: end each .island.tsx's mount with return render(() => <Island {...props} />, el) and type it (): () => void; a plain-DOM island returns a function that removes what it added | X_ISLAND_DISPOSER_MISSING | 131 |
| 39 | x verify --only typecheck,boundaries,contract-diff: give an out-of-tree AuthAdapter the nine PasskeyStore methods; read a function limit from descriptor.rateLimitPerCall; pass decide the signature and give a custom McpConfirmation its quorum, approvers, approvals; move a hand-rolled websocket to deviceSocket({ path, resolveToken, onFrame }); then x manifest and commit the new meter field | TS2420, TS2339, TS2554; X_SOCKET_HAND_ROLLED; X_MANIFEST_DRIFT | 132–136 |
| 40 | give a custom PushDeviceStore noteBadToken and clearBadToken and pass TokenCache.invalidate the refused token; with history: true on Postgres, x db gen "history exact images", and parse a history reader's bigint/decimal value as a string | TS2420, TS2554; X_DB_DRIFT until the migration exists | 137, 138 |
| 41 | pass the grant's server-side policy to every signPart and completeUpload; give a hand-written LiveHandle retry() and a custom event bus's find the event id and afterId; replace enqueueInTx with handle.enqueue; a client calling with cached Basic credentials across sites sends a Bearer token or comes from a listed origin | TS2345, TS2741, TS2305; X_INVARIANT; X_CSRF_BLOCKED | 139–143 |
Entry by entry
Tier 0 — @ultimat3/core (1–2). Tier 1 — @ultimat3/db (3–5), @ultimat3/storage (6–7). Tier 2 — @ultimat3/entity (8–14), @ultimat3/http (15), @ultimat3/auth (16). Tier 3 — @ultimat3/action (17–20), @ultimat3/jobs (21–22). Tier 4 — @ultimat3/render (23–24), @ultimat3/notify (25). Appended after the tier order: @ultimat3/mcp (26–27), @ultimat3/http (28), @ultimat3/render (29). Appended by the second wave, by tier: @ultimat3/core (30), @ultimat3/db (31–32), @ultimat3/i18n (33–34), @ultimat3/storage (35–37), @ultimat3/http (38–40), @ultimat3/entity (41), @ultimat3/query (42–43), @ultimat3/action (44), @ultimat3/jobs (45–46), @ultimat3/render (47), @ultimat3/mail (48), @ultimat3/manifest (49), @ultimat3/testing (50), @ultimat3/cli (51–56). Appended by the third wave, by tier: @ultimat3/http (57), @ultimat3/ui (58), @ultimat3/cli (59–60). Appended by the wave 3 gate fix: @ultimat3/render (61). Appended by the fourth wave: @ultimat3/jobs (62–64), @ultimat3/core (65–66), @ultimat3/pwa (67–68), @ultimat3/ai (69), @ultimat3/mcp (70–73), @ultimat3/cli (74). Appended by the fifth wave: @ultimat3/ui (75–78), @ultimat3/render (79), @ultimat3/action (80–82). Appended by wave 5b: @ultimat3/auth (83), @ultimat3/cli (84), @ultimat3/mcp (85), @ultimat3/realtime (86), @ultimat3/core (87). Appended by wave 6a: @ultimat3/testing (88–89), @ultimat3/entity (90). Appended by wave 6b: @ultimat3/cli (91), @ultimat3/entity (92–93). Appended by wave 7: @ultimat3/cli (94), @ultimat3/testing (95), @ultimat3/auth (96–97), @ultimat3/jobs (98–100), @ultimat3/scraping (101), @ultimat3/db (102), @ultimat3/ai (103). Appended by wave 8: @ultimat3/cache (104), @ultimat3/db (105–106), @ultimat3/core (107), @ultimat3/db (108), @ultimat3/cli (109–110). Appended by wave 9: @ultimat3/core (111), @ultimat3/db (112), @ultimat3/seo (113), @ultimat3/http (114), @ultimat3/mcp (115–116), @ultimat3/admin (117), @ultimat3/cli (118). Appended by wave 10: @ultimat3/seo (119), @ultimat3/auth (120), @ultimat3/realtime (121), @ultimat3/ui (122–127), @ultimat3/testing (128), @ultimat3/cli (129–131). Appended by the issues PR (#990–#999): @ultimat3/auth (132), @ultimat3/action (133), @ultimat3/mcp (134), @ultimat3/manifest (135), @ultimat3/cli (136). Appended by sweep 1: @ultimat3/notify (137), @ultimat3/db (138). Appended by sweep 2: @ultimat3/storage (139), @ultimat3/realtime (140), @ultimat3/http (141), @ultimat3/jobs (142–143).
| # | Surface | Costs you an edit if |
|---|---|---|
| 1 | close-phase onShutdown order | a close hook relies on running before one registered after it: hooks now run last-registered first, so register in the order you want released. accept and inflight are unchanged |
| 2 | retry() | a retry must outlive its caller: it now stops when the ambient ctx.signal aborts and never waits past ctx.deadlineAt. Write runToCompletion(() => retry(work, policy)). Outside a request context nothing changes |
| 3 | a write past requestTimeoutMs or a job's cancellation | the work must land anyway: it now rolls back. Wrap the whole of it, runToCompletion(() => withTransaction(fn)): wrapped inside the transaction, the statement lands and the COMMIT is still refused. It drops the deadline for what runs inside it, so give a raw fetch in there its own. A keyed idempotent action already runs in that scope, up to configureIdempotency({ scope, ceilingMs }), twice requestTimeoutMs by default; a handler past it is aborted and its key replays X_IDEMPOTENCY_RUN_CEILING |
| 4 | a statement on a finished DbTx | one outlives its scope: it is X_DB_TRANSACTION_CLOSED, not an autocommit. await it inside withTransaction(fn), or use outsideTransaction(fn) for work that must outlive the scope |
| 5 | dropping a column | you drop in one release: set retired: ['<c>'] and x db gen "retire <c>", deploy, then remove it and x db gen "drop <c>" --allow-destructive. One instance that stops before it starts: --rolling-unsafe |
| 6 | promoteAttachment | a pending object's bytes do not match its type: it reads the first 64 KiB and refuses. An XML or +xml object over 64 KiB refuses too: upload it through the server. An object overwritten during promotion refuses X_STORAGE_OBJECT_CHANGED: promote again once the upload has finished |
| 7 | the content sniff | a file opens with over 4,096 B of whitespace: refused everywhere. Trim it before upload |
| 8 | references() between two tenant-scoped entities | always once: x db gen "same-tenant keys" adds one unique index per referenced table and swaps the key online. A row already crossing tenants fails the validate: decide it, or state crossTenant: '<reason>' on an edge that means it, including two tenant columns meaning different things. A memory test wiring a parent and child across tenants moves its fixture. onDelete: 'set null' needs Postgres 15+. A null tenant column skips the check. A hand-built ReferenceDescription needs sameTenant: null and targetTable. An entity declared with a { table } that differs from its name, as a target: X_DB_DRIFT until x db gen |
| 9 | update, updateWhere, transition | a value insert would refuse reached them: it is refused before the statement, not as X_DB_STATEMENT_FAILED, and a number written to a text column is an error, not a coercion. Pass the column's type |
| 10 | orderBy on a json, bytes or array column | you order by one: refused at plan time (it paged wrongly or threw past page 1). Order by a scalar |
| 11 | db.x.upsertAll, seed.upsert | you relied on a collision resetting unnamed columns: name the column, { ...row, label: 'default', createdAt: now }. A timestamp expected to move on re-upsert (reviewedAt) is named or declared onUpdateNow(). Both X_INVARIANT_VIOLATED: rows naming different columns (give each row the same columns), and rows naming only the conflict target or primary key, which answer would write nothing: db.blocks.upsertAll([{ blockerId, blockedId }], { onConflict: ['blockerId', 'blockedId'] }) takes onMatch: 'nothing' when "already there" is fine, or a named column to overwrite |
| 12 | repo.upsertAll on a hand-held repository | one row holds label: undefined and another a value: X_INVARIANT_VIOLATED. Give every row a value, or none |
| 13 | a wide insertAll / upsertAll | you relied on partial progress when one failed: it now leaves nothing. Split the batch yourself and call once per part |
| 14 | a soft delete under a JS-only invariant | the stamped row breaks the rule: refused on Postgres too, and deleteWhere past MAX_ASSERTED_ROWS matched rows is refused. Relax the invariant for the stamped row, or delete in smaller where sets |
| 15 | /media on a shared key | a CDN rule keys on public, immutable: it misses from now on. Serve a public image from apps/web/site/assets/ via asset(), or from an app route using objectResponse. Existing variants under old keys go unread and are re-minted once |
| 16 | a custom totpReplay | you wrote one: replace isUsed/remember with claim(subject, step, at): Promise<boolean>, answering true the first time, false for a replay, and rejecting when its store is down. A framework-booted app needs no edit: drop the option and the boot installs postgresTotpReplayGuard, whose table x_totp_steps is applied at boot (ROLE=migrate on an external database) |
| 17 | a tool in both mcpConfirmations({ tools }) and agent({ tools }) | an agent calls it: it now waits for a person. Have the agent's output report the pending confirmation id, or remove the tool from tools to let the call run unconfirmed. With two deciders on one tool, the first registered answers in-app |
| 18 | a decision action's module that reaches a document | manifest goes red with X_ROLE_LOAD_INCOMPLETE: add the import its fix names to apps/web/api/index.ts, or move the declaration into a module that imports no .tsx and no stylesheet |
| 19 | asProjectableAction(handBuilt) | you compare by identity: it returns a copy behind the gate, and projecting that copy, or a spread of it, passes the gate once. Compare a hand-built tool by name |
| 20 | a failed agent tool's text | a test pins the rendered (fix: …) of an error that declares callerFix: the model now sees callerFix. Move the assertion with it |
| 21 | step.run's answer | you read a value JSON changes: a Date is a compile error at the read, so write new Date(value); a miss stored from undefined is null, so compare === null; a value JSON cannot hold (a bigint, a cycle, NaN, an infinity, an invalid Date, a NUL, a lone surrogate) is X_STEP_OUTPUT_UNSERIALIZABLE; a keyed action answering such text is X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE. A step's object keys read in jsonb's order on every attempt. Runs in flight across the upgrade replay as they always did |
| 22 | step.waitForEvent | you wait on an event: schema is required and <T> is gone. Pass a schema |
| 23 | isr and static routes | a load reads the actor, a cookie, Authorization or any other inbound header: it now sees none, ctx.ip and ctx.peer are null, ctx.tz is the app's default, and ctx.url is the document's address, with no undeclared query. A page that varies per visitor is render: 'ssr'. With no declared origin, a process stores isr pages for 16 request origins: set APP_URL if you serve more |
| 24 | an isr route with no revalidate.query | its load or page reads a query parameter: the route now serves one document for every value, and nothing can see that from the key alone. List it in revalidate: { query: ['<name>'] } |
| 25 | x_notify_deliveries, DeliveryLedger | always, for the column: x db gen, commit packages/db/schema/. An app with its own ledger also takes the table below. A channel whose send can outlast five minutes sets reclaimAfterMs above its slowest send, or a reclaimer overlaps it |
| 26 | a tool in mcpConfirmations({ tools }) on a server you handed no confirmations | a caller relied on it running at once: it now waits. To let a call run unconfirmed, remove the tool from tools |
| 27 | a name in mcpConfirmations({ tools }) | no exposed action, exposed query, MCP tool or in-process tool answers to it: X_MCP_CONFIRMATION_TOOL_UNKNOWN at manifest. Correct the spelling, or expose the action. A hand-written tool counts once its defineAppMcp has run when the app loads, so build that server at module scope in apps/<app>/mcp.ts |
| 28 | cors.origins containing 'null' | you list it, or build the list from URL.parse('localhost:3000').origin (no scheme): X_CORS_CONFIG_INVALID at boot, with or without credentials. List real origins with their scheme: configureHttp({ cors: { origins: ['http://localhost:3000'] } }). A public, credential-free API uses origins: ['*'], credentials: false |
| 29 | a HeadTag href | a link carries data:image/svg+xml, any other data: type, or a scheme outside http, https, mailto, tel, sms: it prints no href (android-app: and ios-app: stay on rel="alternate"; a raster data:image/ stays). Serve the file: site.favicon for an icon, or a same-origin path under assets/. head.attribute_dropped names the tag and attribute in dev |
| 30 | the ScalingSignal 'queue-depth' | you name it, or an adapter rule reads queue_depth for the worker HPA: it is 'queue-demand', SCALING_METRICS['queue-demand'] is queue_demand. Add the adapter rule max by (queue) (queue_demand). queue_depth stays, the ready-only gauge for a backlog alert |
| 31 | a plain statement behind a full pool | you relied on it queueing past acquireTimeoutMs: it answers X_DB_POOL_EXHAUSTED. Raise DATABASE_POOL_MAX or fix the slow statement. A statement unanswered past the role's bound plus 5 s is X_DB_UNAVAILABLE and the pool is replaced; an autocommit write may have landed, and a job worker re-runs that attempt, so make such a write idempotent |
| 32 | a transaction left idle, PoolProfile | a transaction awaits slow outbound work: past 30 s (web, sync) or 120 s (worker, scheduler) the server closes it, X_DB_STATEMENT_FAILED (25P03). Do that work before opening it. A hand-built PoolProfile adds idleInTransactionMs. Behind a pooler, set DATABASE_POOLER and both bounds with alter role |
| 33 | keys only a mail or a push names | x verify's i18n step reports them: x i18n sync <locale>, then translate |
| 34 | an en key another locale lacks | always, for a key reached only through a template literal: x i18n sync <locale>. A ⟦…⟧ marker over such a key stays missing until replaced |
| 35 | a third-party StorageDriver | you wrote one: implement streamRange(key, [first, last]), reading no byte before first, and putStream(key, stream, { maxBytes, … }), storing nothing past maxBytes |
| 36 | grantUpload | your own action builds the grant: its input carries size: file.size (uploadFile already sends it), or X_STORAGE_UPLOAD_SIZE_UNDECLARED. grant.maxBytes is now that size, not the policy's; an s3 URL accepts exactly that many bytes, so another length is 403 SignatureDoesNotMatch |
| 37 | disk.signedUrl(key, { method: 'PUT', maxBytes }) on s3 | you call it: refused. Add contentLength: file.size, or drop maxBytes for a URL that binds nothing |
| 38 | the problem document's retry | a golden test pins a whole body, or a middleware adds retry: errorRetry(error): the member is on every document, 401 and scope 404 included. Add it to the test; delete the middleware. x manifest regenerates openapi.json's Problem |
| 39 | PIPELINE_STAGES, StageName | a Record<StageName, …>: add compress. A handler whose answer must not be coded sets no-transform |
| 40 | csrfBlocked(pathname, reason, ip, origin) | you call it: pass the request's ip and origin |
| 41 | memoryRepo and the statements fixture | a memory-backed test that uses statements loops: it now fails X_N_PLUS_ONE_QUERY / X_N_PLUS_ONE_WRITE. preload(), or expectedQueryLoop('<why>', …) |
| 42 | a read's published rows: | an app declaring rows: finds openapi*.json stale: x manifest, commit. Later, a member removed, retyped or made optional fails contract-diff with X_MANIFEST_BREAKING until the app's major moves |
| 43 | DownloadFile.body | code reads the field rather than handing it over: narrow the function form, (range?) => BodyInit, whose size is required |
| 44 | REPLAYED_HEADER | import { REPLAYED_HEADER } from '@ultimat3/action': import it from @ultimat3/core |
| 45 | a custom JobDriver | implement demand(): Promise<readonly QueueDemand[]>: per queue, the running rows not held by a worker whose live registry row says it drains, plus the due ready/delayed/suspended rows of an unpaused queue; list only queues above 0, sorted by code unit |
| 46 | x_job_workers.build | always, for the dump: x db gen, commit packages/db/schema/ |
| 47 | suspenseBoundaries, ModeSpec.needsSuspense | you pass or read them (TS2353 / TS2339): delete the key or the read. To stream, wrap the slow read: <Hole fallback={<Skeleton lines={3} />}>{readRows}</Hole> from @ultimat3/render |
| 48 | send() | a mail holds a key the locale lacks, a catalog value still ⟦…⟧, or a {slot} the payload's top-level scalars do not carry: X_MAIL_KEY_MISSING, a framework mail.* mail included. Add the key, translate it, or put the field at the top level |
| 49 | QueryFact.rows, Manifest.mounts | an app declaring rows: or a mount: x manifest, commit. Later, a name dropped from a mount's scopes or a changed prefix fails contract-diff with X_MANIFEST_BREAKING until the app's major moves |
| 50 | requestedUrls() | you call it: requestLog().map((call) => call.url) answers the same list. NetworkSnapshot.seen is NetworkSnapshot.log |
| 51 | the worker retire | always, on a chart: a rollout leaves an old worker Terminating while it holds a job, for up to retireSeconds. drain.workerRetireMs: 0 keeps the old stop. An app's own chart keeps its values until x deploy sets the retire |
| 52 | a job's timeout | it outlasts the worker's budget: X_JOB_OUTLASTS_DRAIN at manifest. Raise drain.workerRetireMs, or lower the timeout |
| 53 | packages/db/schema/04_tables/ against the newest snapshot | a column one holds and the other does not: an edited migration. Restore the file, then x db gen |
| 54 | x g query, x g backfill | you named no slice: pass --feature <slice>, or x g resource <name> for a new table |
| 55 | a packages/* runtime import of apps/* | you have one: move the code down. import type passes, and packages/db/src/ may read an entity module |
| 56 | S3_FORCE_PATH_STYLE | it holds anything but 0, 1 or blank: X_CONFIG_INVALID at boot. Write 1 |
| 57 | ERROR_PAGE_LINKS.homepage | you read it: it is removed, and the default error page links only the repository. ERROR_PAGE_LINKS.repository is unchanged. An app that wants its own links ships apps/web/site/errors/<status>.html, as before |
| 58 | FormSchema, FormValidationResult, FormValidationIssue, formatFieldPath, IssuePathSegment from @ultimat3/ui | you import one: take StandardSchemaV1, StandardResult<unknown>, StandardIssue, formatPath, StandardPathSegment from @ultimat3/schema. A hand-written schema handed to formBinding({ schema }) adds version: 1 and a vendor beside validate. parseFieldPath, fieldSelector and MAX_FIELD_INDEX are unchanged |
| 59 | x verify's budgets step | your stats were stale: it builds first (x build --target static --no-preflight --out .x/verify-static) and weighs fresh bytes, so a route stale stats hid is red. Shrink it or raise its budget by the measured figure; x verify can be one static build slower after an edit (8.2 s on dummy/social-media-clone) |
| 60 | bin/check.ts, bun run check | a script or CI step expects a new scaffold to have them: run bun run verify. An existing app keeps its own; it still works |
| 61 | JSX_NODE from @ultimat3/render | you import it: import { JSX_NODE } from '@ultimat3/core/render-node', the same global symbol. HOLE_NODE and ISLAND_NODE live there too |
| 62 | a hand-written JobHandle, JobsFacade or JobDriver | you wrote one: each gains a required member. JobHandle.enqueueMany(inputs, options?) (a fake built from job() has it already). JobsFacade.enqueueMany(handle, inputs, options?), or build the facade with outboxJobsFacade(). JobDriver.enqueueMany(requests): answer each request as enqueue would, in order, in one round trip, opening with assertEnqueueMany('<driver>', requests); a driver with no batch primitive loops its own enqueue. It refuses a request carrying onConflict: 'error' (X_INVARIANT): send that one alone through driver.enqueue. OutboxStore.stageMany / markPublishedMany stay optional |
| 63 | an enqueue spy on a spread memoryJobDriver() | a test wraps the driver as { ...driver, enqueue: spy } and drives handle.enqueueMany or the outbox relay: both go through driver.enqueueMany, so the spy is never called. Wrap that member too |
| 64 | outboxRelay()'s default batchSize | it claims 500 rows a pass, not 100. Pass batchSize: 100 to keep the old figure; the one reason to is a relay running the row loop (a driver without enqueueMany, such as redisJobDriver) against very slow publishes, where 500 rows must still publish inside the 30 s claim lease |
| 65 | ERROR_SOURCES, ErrorSource | an exhaustive switch on ErrorSource with no default, or a Record<ErrorSource, …>: add a browser arm. It is what /_client-errors reports with, once clientErrors.enabled is set |
| 66 | AppConfig | you build one by hand (a test fake, { … } as AppConfig aside): it gains the required assets and clientErrors (TS2741). Spread defineConfig({ name })'s answer, or add assets: { retain: undefined } and clientErrors: { enabled: false, anonymous: false, perMinute: 30 } |
| 67 | retentionPlan, RetentionPlan, Deploy from @ultimat3/pwa | you import them (TS2305): delete the call, which retained nothing unless your own code acted on its answer. To keep earlier builds' hashed files served across deploys, declare assets: { retain: { disk: '<a disk every web pod shares>', builds: <n> } } in app.config.ts, with that disk in defineStorage({ disks }) |
| 68 | ServiceWorkerConfig.retainBuildIds passed to generateServiceWorker | you pass it (TS2353, excess property): delete the key. An activating worker keeps only its own build's caches; a tab open across a deploy gets earlier builds' chunks from the server, through assets: { retain: { disk, builds } } |
| 69 | DefineEvalInput | you read input.prompt off one (TS2339): it is PromptEvalInput | AgentEvalInput; narrow with 'prompt' in input. A defineEval({ prompt, … }) call is unchanged, and a custom Scorer typed against { output; expected? } still compiles. An eval of a prompt an agent() runs may move to the agent arm, defineEval({ name, agent, cases: [{ name, input }], tools: { <tool>: (input) => <answer> }, scorers, baseline, tolerance }), with its baseline re-recorded by ULTIMATE_EVAL_RECORD=1 x test eval |
| 70 | MCP_PROTOCOL_VERSION from @ultimat3/mcp | you import it (TS2305; it was '2025-06-18'): MCP_MODERN_VERSIONS[0] for the modern revision ('2026-07-28'), MCP_LEGACY_VERSIONS for the handshake ones. grep -rn MCP_PROTOCOL_VERSION apps packages finds every caller |
| 71 | the MCP revision a server answers | a client or test pins initialize's answer: it echoes an offered MCP_LEGACY_VERSIONS revision, else 2025-11-25 (was always 2025-06-18). A request whose _meta names 2026-07-28 is served statelessly, with no initialize or ping; an unserved version in _meta or MCP-Protocol-Version is 400 -32022. Legacy clients (initialize) keep working unchanged |
| 72 | POST /mcp with an Origin | it is not this app and not in http.cors.origins: 403 X_MCP_ORIGIN_REFUSED, before resolveToken. Call from the app's own origin, list a sibling page's origin in http.cors.origins, or call from a client that sends no Origin |
| 73 | McpAuthRefusal | an exhaustive switch over it, or a Record<McpAuthRefusal, …>: add an 'origin-refused' arm (mcp.auth.origin-refused, onAudit's auth-refused with status 403) |
| 74 | x mcp serve --transport http | you reach it through a name that is not localhost, *.localhost or a loopback address: 421 X_MCP_HOST_REFUSED. Use http://localhost:<port>/mcp or http://127.0.0.1:<port>/mcp. GET/DELETE on it answer 405 X_METHOD_NOT_ALLOWED, not 404 |
| 75 | setSolidRuntime | every island that registers the runtime: add createRoot to the solid-js import and to the call, setSolidRuntime({ createContext, useContext, createSignal, createMemo, createEffect, onCleanup, createRoot }). A six-name call no longer compiles (TS2345). A whole solid-js namespace still registers |
| 76 | DataTable's rowKey | two rows answering one key are X_UI_INVALID_VALUE: make the key the row's primary key — unique within rows, stable across updates, never an index — rowKey={(row) => row.id} |
| 77 | UI_KEYS, UiKey | a Record<UiKey, string>: add ui.first |
| 78 | a cursor-mode Pagination with no prevCursor | it no longer draws a disabled Previous. To give a keyset list a way back, pass firstHref (link mode, listUrl().firstHref) or onFirst (callback mode) |
| 79 | refresh() from @ultimat3/render/client | code that relied on the old behaviour, the table below |
| 80 | .contract() on a non-public action or query | it calls your handler 16 times with generated legal input: pass { exercise: { actor } } or { exercise: { off: '<reason>' } }, the rules below |
| 81 | sampleInput | you imported action's sample-input module by path; it is gone: import { sampleInput } from '@ultimat3/schema/sample' |
| 82 | ActionDescriptor, QueryDescriptor, Query | code that assigned .method to a 'POST'-typed variable widens it to ActionHttpMethod. A hand-built descriptor adds errors: null; a hand-built Query adds contract |
| 83 | WorkloadToken (@ultimat3/auth) | you build one by hand, usually a test fake: add raw, the decoded payload (raw: {} where nothing reads it) |
| 84 | a deployed role's app modules | a module throws on import or registration: the role now exits X_APP_MODULE_LOAD_FAILED instead of serving without it. x manifest --json names the module and why |
| 85 | MCP tool descriptions | you snapshot tools/list: an undescribed query reads Read with the "<name>" query., an admin action quotes its name. Set mcp: { description } to keep your own wording. exposedPrimitives() returns opted-in primitives only |
| 86 | QueryPoll | you read .ms: keep the number you passed to pollEvery |
| 87 | .contract() / exerciseAction / exerciseQuery | you ran one with ULTIMATE_ENV or NODE_ENV set to staging or production: run it under bun test |
| 88 | e2eTest, E2eBrowserPage (@ultimat3/testing) | Every e2eTest now audits the browser's accessibility tree. Name what it lists — visible text, aria-label, <label for>, alt (alt="" for a decorative image), a <title>, <html lang>, nothing focusable under aria-hidden — or add { a11y: { allow: [{ role, selector, because }] } } to that test. A tab a suite drives itself (browser.session.newTab()) is audited too: name what it lists, or call allowA11y([{ role, selector, because }]) in that test before the navigation. A hand-written E2eBrowserPage passed to installE2eDriver({ page }) must implement or forward accessibilityTree(request). toAxNode is imported from @ultimat3/testing, not @ultimat3/cli's cdp-shot-a11y.ts |
| 89 | factoriesFor (@ultimat3/testing) | a test reads a value it never set: it is now the column's declared default, an enumerated value or its kind's value, never derived from the name. Set the value in the call (build({ column: … })) or a defineFactory. A registry whose $columns are not entity() columns throws X_SEED_GRAPH_UNSATISFIED: pass real entities |
| 90 | memoryTransactor().run (@ultimat3/entity) | a memory-store write inside it that names no tx must survive the transaction throwing: move it outside run. A write that names no tx now rolls back with the transaction, as on Postgres |
| 91 | x verify (@ultimat3/cli) | a registered action, query or job no generated run reaches as an allowed actor: the new exercise step is red with X_CONTRACT_EXERCISE_UNREACHED. Paste the entry x exercise --json prints into apps/web/exercise.ts, or give { off: '<why>' }. A script that pinned the step count reads one more (VERIFY_STEP_NAMES) |
| 92 | entity() (@ultimat3/entity) | an entity with no tenant column references, directly or through others, one that has one: X_ENTITY_TENANT_UNDECLARED from the exercise step. Add orgId: uuid().tenant() and x db gen '<table> tenant' (with x g backfill on a table holding rows), or declare shared: '<why>' |
| 93 | memoryTransactor().run (@ultimat3/entity) | a test writes after the transaction ended — an unawaited promise — and now gets X_DB_TRANSACTION_CLOSED; or it relied on a nested run's onCommit effect running at that nested commit: it now runs at the root's, and never after the root rolls back |
| 94 | x exercise, the exercise step (@ultimat3/cli) | a primitive hands tenant B a row of tenant A's, or changes one, when B passes A's ids: X_TENANT_LEAK / X_TENANT_WRITE_CROSSED. Read and write by input id through the repository scoped to ctx.actor; x exercise <name> --json reruns it |
| 95 | SeedWriter (@ultimat3/testing) | you wrote one by hand: add snapshot: async (rows) => rows.map(() => null) at least — TS2741 otherwise. A seeded count per tenant moved: an untenanted child of a tenant-owned table now has rows under each tenant |
| 96 | the framework schema (@ultimat3/auth) | you commit a schema dump: five x_oauth_* tables appear. x db gen, then commit packages/db/schema/ |
| 97 | VerificationPurpose (@ultimat3/auth) | you switch over a purpose or type one as the two-value union: it is string. Add a default arm; declare a new purpose with defineVerificationPurpose |
| 98 | publishEvent on the Postgres bus (@ultimat3/jobs) | you commit a schema dump: x_job_steps_waiting_idx appears; x db gen, commit. A wait that relied on the 30 s poll to notice an event published by other means than publishEvent: eventPoll: '30s' |
| 99 | StepStatus, step names (@ultimat3/jobs) | you switch over StepStatus: handle started and cleared. A step named unwinding or compensate:<x>: rename it. A hand-written driver keeps compiling: resolveStep is optional |
| 100 | enqueuing a tenant-declared job (@ultimat3/jobs) | it names another org than its tenantId or the acting user's: X_JOB_TENANT_MISMATCH. Enqueue from the job's own org, or inside crossTenant(reason, fn) by an actor holding tenancy:cross when crossing is meant. A client that read the code as a 500 now gets 403. Rows already queued that way go dead: re-enqueue them, never x jobs retry |
| 101 | ScrapePage, the wedge watchdog (@ultimat3/scraping) | you wrote a ScrapePage fake: add activity(): void (the shipped fakes carry it). An attached browser now closes when the watchdog fires, not when the run unwinds: a run that waits on slow work the page cannot see calls page.activity() |
| 102 | the schema dump (@ultimat3/db) | the database holds a policy, hand-written or from rowSecurity: it is rendered under 10_policies/ and no longer named in unrendered.sql. x db gen, commit packages/db/schema/. A hand-built CatalogDescription adds the two row-security fields |
| 103 | a prompt over the model's window (@ultimat3/ai) | you matched X_AI_PROVIDER_UNAVAILABLE or the provider's text for it: the code is X_AI_CONTEXT_OVERFLOW, terminal, and agent() compacts and retries first, ending X_AGENT_CONTEXT_EXHAUSTED. A run over dense tool results compacts earlier: raise compact: { at } (up to 1) if it summarises too soon |
| 104 | the Redis client (@ultimat3/cache, @ultimat3/jobs) | you relied on Bun.redis queueing commands while Redis was down: a cache read is now a miss at once and enqueue is X_DRIVER_UNAVAILABLE. Catch it where a queued retry was implied. A client you hand in keeps its behaviour and gets the deadline |
| 105 | the framework schema (@ultimat3/db, @ultimat3/admin) | you commit a schema dump: x_migrations.destructive and x_error_groups appear. x db gen, commit packages/db/schema/ |
| 106 | a rollback (@ultimat3/db) | you roll back across a migration a newer build recorded as destructive: X_MIGRATION_ROLLBACK_DESTRUCTIVE. Check the older build on the newer schema, then ROLLBACK_ALLOW_DESTRUCTIVE=<id>[,<id>] on the migrate role |
| 107 | ClientErrorsConfig (@ultimat3/core) | you build one by hand: TS2741 on vitals. { ...CLIENT_ERRORS_DEFAULTS, enabled: true } |
| 108 | a statement inside a transaction (@ultimat3/db) | one runs past the role's statement_timeout + 5 s on purpose: it now fails X_DB_UNAVAILABLE, where it hung. Raise the bound in that transaction: setLocal(tx, { statement_timeout: '<ms>' }) |
| 109 | x exercise, the exercise step (@ultimat3/cli) | a job makes an effect outside step.run that a retry repeats: X_JOB_CRASH_DIVERGED. Wrap the effect the finding names in step.run('<name>', …); there is no pin |
| 110 | the chart (docker/helm) | your cluster serves the Prometheus operator and you did not want the ServiceMonitor or the alert rules: set serviceMonitor.enabled: false and alerts.enabled: false. A dashboard grouping on the scrape's labels sees app_kubernetes_io_instance |
| 111 | AppConfig (@ultimat3/core) | you build one by hand (a test fake, { … } as AppConfig aside): TS2741 on failureCapture and time. Spread defineConfig({ name })'s answer, or add failureCapture: FAILURE_CAPTURE_DEFAULTS and time: TIME_DEFAULTS |
| 112 | the framework schema (@ultimat3/db) | you commit a schema dump: x_failures appears and drift is X_SCHEMA_DUMP_DRIFT. x db gen, commit packages/db/schema/ |
| 113 | /llms.txt, the seo step (@ultimat3/seo) | a public, static site/ page has a title and no description: X_SEO_LLMS_DESCRIPTION_MISSING. Add description to its defineRoute({ meta }), or set seo: { llms: false } in app.config.ts. |
| 114 | TimeZoneConfig (@ultimat3/http) | you build a full TimeZoneConfig or HttpConfig literal: TS2741 on detectedCookie. Spread DEFAULT_TZ_CONFIG; configureHttp({ tz }) is unaffected |
| 115 | McpResource.read, ResourceRegistry.read (@ultimat3/mcp) | you call either yourself: TS2554. Pass the admitted caller: resource.read(caller), registry.read(uri, caller). A resource whose read() takes no argument is unchanged |
| 116 | DevCapabilities (@ultimat3/mcp) | you wrote a DevHost: TS2741 on queryGraph. Implement queryGraph(question) — x impact <node> --json's data for { kind: 'impact' }, x graph --from --to --json's for { kind: 'path' } — or throw for a host with no graph |
| 117 | DevSources (@ultimat3/admin/dev) | you build one by hand: TS2741 on mailTemplates. Add mailTemplates: async () => [], or build it with defaultDevSources() |
| 118 | x exercise, the exercise step (@ultimat3/cli) | a statement no index serves, a limited read that sorts, or a loop over rows: X_QUERY_UNINDEXED, X_QUERY_SORT_UNSERVED, X_QUERY_SCALES_WITH_ROWS. x exercise --json; paste the printed indexes: line into that entity() and run its x db gen, or declare the reason: entity({ scan: '<why>' }), expectedSeqScan('<why>', fn), expectedQueryLoop('<why>', fn); a loop is usually a missing preload() |
| 119 | OpenGraph (@ultimat3/seo) | you extend it, or spread one while setting image: TS2312, TS2375. Write type MyOg = OpenGraph & { … }, and { ...og, image, capture: undefined } |
| 120 | postgresAuthAdapter() (@ultimat3/auth) | you build it with no client and rely on it keeping that client past a later setDbClient, or outside a withTransaction it is now called in: pass the client, postgresAuthAdapter(client) |
| 121 | QueryAccessor.refetch (@ultimat3/realtime) | you hand-build an accessor (a test fake): TS2322 on refetch. Write refetch: async () => {}. Where noFloatingPromises is on, void x.refetch(); or await x.refetch(); |
| 122 | UI_KEYS, UiKey (@ultimat3/ui) | a Record<UiKey, string>: add the 48 keys entry 122 lists, or build it with uiCatalog(t). Code that read Object.keys(UI_KEYS) in declaration order reads it alphabetical |
| 123 | ChartPoint, barRects, BarChartProps, chartTable (@ultimat3/ui) | you read point.value or a barRects() rect as always there, extend BarChartProps, or call chartTable() yourself: TS18047, TS2312, TS2345. Check value === null and skip a null rect; type X = BarChartProps & { … }; pass none: t(UI_KEYS.chartNone) |
| 124 | BarChart, Sparkline, LineChart, AreaChart, deltaOf (@ultimat3/ui) | you pass a negative value you expected drawn at zero, a series whose values do not match keys, or test an empty gap cell or deltaOf(x, 0) === undefined: clamp it yourself (Math.max(0, v)); give each series one value per key, null for a gap (X_UI_INVALID_VALUE); assert ui.chart.none's text and the signed difference |
| 125 | TabsProps (@ultimat3/ui) | you extend it or index TabsProps['onChange']: TS2312, and onChange is | undefined. Name the mode you mean: TabsButtonProps, or TabsLinkProps for link tabs |
| 126 | CommandPalette, filterItems (@ultimat3/ui) | a test pins the filtered order, or that an accented label stays out: assert the ranked order, label prefix first |
| 127 | CONTRAST_PAIRS, defineTheme() (@ultimat3/ui) | your brand sets chart-1 or chart-5 under 4.5:1 against bg-soft, or fg-strong, accent or a status role under 3:1 on a surface: X_UI_CONTRAST_INSUFFICIENT names the pair and its ratio. Move that role until it passes |
| 128 | the test preload (@ultimat3/testing) | a test passed by reading a module another file mocked: mock it in the file that needs it. X_TEST_MODULE_MOCK_UNRESTORABLE on a file's first test: the file before it mocked a module that does not load. Hand that dependency to the code under test as a parameter, or run x test unit --isolate |
| 129 | x build --target static, responsiveImage() (@ultimat3/cli) | a static page names an image the export does not hold, or asks for avif: X_IMAGE_SOURCE_UNREADABLE, X_IMAGE_UNSUPPORTED. Put the file under apps/web/site/assets/ and pass asset('assets/<file>'), or an absolute URL; drop avif from that route's formats. A CDN rule keyed on ?w= now sees /_img/ paths |
| 130 | /assets/* (@ultimat3/cli) | a served responsiveImage() over asset() passes its own widths or formats, or a link adds ?q=: 404 X_ASSET_VARIANT_UNDECLARED. Drop the override, or store the image and serve it from /media, which answers any width |
| 131 | .island.tsx mount (@ultimat3/cli) | x verify --only boundaries is red with X_ISLAND_DISPOSER_MISSING: end mount with return render(() => <Island {...props} />, el) and type it (): () => void; a plain-DOM island returns a function that removes what it added (an AbortController's abort) |
| 132 | AuthAdapter (@ultimat3/auth) | an adapter you wrote is TS2420 until it implements PasskeyStore's nine methods; passkey-postgres.ts is the reference. The built-in adapters need nothing |
| 133 | ActionDescriptor.rateLimit (@ultimat3/action) | a reader that met a function limit there reads rateLimitPerCall; rateLimit is now the fixed limit or null |
| 134 | McpConfirmationStore, McpConfirmation (@ultimat3/mcp) | a custom store's decide takes the signature as its fifth argument and records it; a hand-built confirmation carries quorum, approvers and approvals. The Postgres store's three new columns are added at boot |
| 135 | x.manifest.json, the contract diff (@ultimat3/manifest) | x manifest adds actions[].meter: commit it. Introducing or tightening a meter is now breaking in x verify --only contract-diff |
| 136 | a websocket upgrade (@ultimat3/cli) | x verify --only boundaries is red with X_SOCKET_HAND_ROLLED on server.upgrade or Bun.serve({ websocket }): declare deviceSocket({ path, resolveToken, onFrame }) instead |
| 137 | PushDeviceStore, TokenCache (@ultimat3/notify) | a store you wrote is TS2420 until it implements noteBadToken and clearBadToken; a caller of invalidate() passes the token the provider refused. The built-in stores need nothing; x_push_devices.bad_tokens is added at boot |
| 138 | history: true images (@ultimat3/db) | x db gen "history exact images" reinstalls the trigger; a reader that did arithmetic on a bigint or decimal value in before/after parses the string; timestamps are UTC …Z. Rows already written keep the old spelling |
| 139 | signPart, completeUpload (@ultimat3/storage) | pass the policy the grant was made under — the app's own, never a value from the request; without it both throw X_INVARIANT. The browser's MultipartUploadClient is unchanged |
| 140 | LiveHandle (@ultimat3/realtime) | a handle you wrote is TS2741 until it implements retry(): boolean: re-send the subscribe of a refused registration and answer whether it did |
| 141 | CsrfCheckInput, the csrf stage (@ultimat3/http) | a caller of checkCsrf passes authorization: request.header('authorization'); a write a browser sends with only cached Basic, Digest or Negotiate credentials is now judged like a cookie session — send Authorization: Bearer, or list the origin in cors.origins |
| 142 | enqueueInTx (@ultimat3/jobs) | TS2305 on the import: call handle.enqueue(input) (or jobsFacade().enqueue) inside the transaction — it joins it and runs the refusals enqueueInTx skipped |
| 143 | EventLookup.find (@ultimat3/jobs) | a custom event bus returns each event's id and seeks strictly past (afterMs, afterId) when afterId is given. A job live across the deploy was queued with no tenant, so a plain enqueue of its key afterwards is a new job |
Entry 25: a hand-written DeliveryLedger
A compile error until it does:
| Was | Now |
|---|---|
claim(claim, at): Promise<boolean> | claim(claim, at): Promise<DeliveryClaimAnswer>: { outcome: 'owned', claimId }, { outcome: 'sent' } or { outcome: 'held', retryAfterMs } |
settle(claim, status, at): Promise<void> | settle(claim, status, at, claimId): Promise<boolean>: false when claimId no longer owns a sending row, and nothing changes |
A sending row is no longer re-claimable at once: it is held for reclaimAfterMs, default DEFAULT_DELIVERY_RECLAIM_MS (5 minutes). A retry landing inside it raises X_NOTIFY_DELIVERY_HELD and is rescheduled past the window with the attempt uncounted.
Entry 79: what refresh() no longer does
Only an app that relied on the old behaviour has anything to do:
| Relied on | Now | Do |
|---|---|---|
focus landing on <main> after refresh() | focus stays on the control the visitor was in; <main> only when it is gone | call document.querySelector('main')?.focus() after await refresh() where that is wanted |
the title read out after refresh() | nothing is announced | announce in the app's own live region |
refresh() cancelling a navigation in flight | it resolves and does nothing; that navigation lands | await navigate(location.href, { replace: true }) to replace it |
refresh() re-fetching the page under an open modal | nothing is fetched | closeModal() first, then refresh() |
Entry 80: the exercise assertion
.contract()'s fourth assertion calls the handler 16 times with input input: accepts, inside a rolled-back transaction.
| Case | Answer | Do |
|---|---|---|
no exercise, on a non-public action or query | X_CONTRACT_EXERCISE_UNDECLARED | { exercise: { actor } }, or { exercise: { off: '<reason>' } }. A public one (its policy admits an anonymous caller) runs as the signed-out caller with nothing declared |
| an input a generated uuid cannot satisfy: a row id, an org the policy compares | every run stops before the handler | a binder: { exercise: { actor, input: (drawn) => ({ ...drawn, postId, orgId }) } } |
| the handler throws uncoded, fails its output schema, or answers a coded 5xx on a legal input | X_CONTRACT_DEFECT; an errors:-undeclared code counts as a 5xx | fix the handler. The fix: is the bun test <file> -t '<name>: handler survives generated input' that replays the run |
| no run reaches the handler: every run denied, or a sealed network | X_CONTRACT_EXERCISE_UNREACHED | a grant the actor holds, or a binder |
the memory store (storeMode memory) | each run's writes roll back, as on Postgres (since entry 90; before it, what a run wrote stayed until the next seed()) | nothing |
Not breaking, but you will see it
| What moved | Do |
|---|---|
with DATABASE_REPLICA_URL set, a request that wrote sets __Host-x-pos and x-ultimate-position | nothing. A proxy with a cookie allowlist passes __Host-x-pos; stripped, the next read may land on a standby that has not replayed the write |
a job attempt that completed and was acked leaves ctx.signal un-aborted (As of 2026-11-07); before, its timers' writes and enqueues were refused X_ABORTED, "was cancelled" | nothing. A body that read an aborted signal as "the run ended" reads the settle instead (onSettled); work that must outlive a FAILED attempt too runs in runToCompletion(() => work) from @ultimat3/core |
onSettled's ctx.signal is live | a hook that treated an aborted signal as "the run ended" reads settled.outcome instead. It is aborted at onSettledTimeout, 30 s across every try by default: raise it on a hook that takes longer |
publishEvent inside a transaction commits and rolls back with it | nothing, unless a rolled-back event must still resume a run: publish it in outsideTransaction(fn) |
the drift step's rollingSince rail is off until set | optional: set rollingSince in x.verify.json to your newest applied migration id. x doctor reminds you |
any other HeadTag attribute drops as attributePair does: on*, srcdoc, a non-http(s) href or src on base or script | nothing to migrate: these never belonged in a document |
disk.delete still leaves a variant's bytes, now unreadable once its source is gone | an erasure of one object also calls deleteVariants({ disk, key }) |
a websocket upgrade from an unlisted origin is refused whatever sec-fetch-site it carries | add a sibling host to allowedOrigins |
stored isr entries re-render once, for the new key | nothing |
an isr route's isr.query.undeclared log line is gone | remove an alert keyed on it |
a public text answer of 1 KiB to 256 KiB with a declared length leaves as gzip with a weak etag; a signed-in one only when immutable | a handler that must not be coded sets no-transform |
html, textResponse and jsonResponse set content-length | a handler that rewrites such a body drops the header |
a mount declaring rateLimit lifts the token's per-route cap of 120 a minute, and a mount's 422s and pipeline 403s spend the allowance | check the mount's number is the ceiling you meant |
Link: rel="successor-version" on a mount names the mounted path, or is absent when this token cannot follow it | nothing |
rpc or queryClient pointed at a mount's prefix never reached it | call a mount from its own OpenAPI document |
DEFAULT_CORS allows and exposes more headers | an app with its own allowHeaders or exposeHeaders adds the new names itself |
RemoteActionError.meta and a problemError's meta gain requestId | a toEqual on a whole meta gains the key |
a rendered fix: prints bunx x where the app's own bin exists | an agent parsing the string for x adjusts |
a positional x deploy <word> is refused | x deploy --image <ref>, or x deploy verify |
x deploy verify with no DATABASE_URL passes with graded: false and reads no queue | give the step the database credentials to grade the workers |
x new's docker/Dockerfile.dockerignore drops **/*.test.ts, **/*.test.tsx and docs | optional: append the three lines to your own; !docs/<path> re-includes a served file |
x jobs show / inspectJob(driver, id).input is '[redacted]' for a job name this process has not registered with job() | to read such a payload, register the job again (a stub job({ name, input: t.json(), … })) in the process that inspects it |
a field marked .sensitive() (last in the chain) is masked in the audit record and x jobs show; one reachable from an action output or a query rows fails boot with X_SCHEMA_SENSITIVE_OUTPUT | optional: mark what must never be written down. An app's own logger.info('x', input) is not covered: keep redactKeys or a Secret there |
every builtin schema refusal carries rule (SCHEMA_RULES) and params, on the wire and on FormIssue | key a form's messageFor on issue.rule, not the English issue.message; keep a fallback, since a third-party schema library sends no rule |
app codes declare with defineError({ code, title, status | offSocket, cause, fix }) from @ultimat3/core, which registers the status in the same call | optional: replace class X extends UltimateError with defineError; X.is(error) replaces instanceof, and a base class becomes a code prefix. x g guard error-declared adds the guard that keeps it so; x g guard bare-error --force refreshes the bare-error guard's fix. An app code with no status still answers 500 |
the Sentry envelope carries fingerprint: [errorFingerprint(report)] | nothing: each existing issue reopens once under its new group. A reporter of your own groups the same way with errorFingerprint(report) |
OTLP export retries 429, 502, 503, 504 and a transport failure, inside the exporter's timeoutMs (default 10 s) | lower timeoutMs if a shorter hold on the in-flight batch matters more than delivery. A collector that accepted a batch then answered 503 receives it twice; span ids dedupe it |
X_DEV_ALREADY_RUNNING's fix is x stop --json | a script that killed x dev by pid calls x stop --json, which returns once the next x dev can boot |
| the AI gateway skips a provider for 30 s once it fails five passes in a row | to keep re-spending every attempt on every call: providerGateway({ …, breaker: 'off' }); your own per provider: breaker: (provider) => breaker({ … }) |
| after the replica breaker's cooldown, one read probes the replica and the rest take the primary until it answers | nothing |
x doctor lists raw-fetch as a shipped guard your app lacks | bunx x g guard raw-fetch, then give each server fetch( a signal, or call outbound() from @ultimat3/core/outbound |
DeadlineTimer and platformDeadlineTimer left @ultimat3/scraping's clock.ts (never on its barrel) | import them from @ultimat3/core/outbound |
breaker()'s admit() returns a ticket (or undefined) that succeeded, failed and released take; defaultBreakerClassify is not exported | pass the ticket back; write your own classify |
registerErrorStatus's table is core's: the writers are on the internal subpath @ultimat3/core/internal/error-status, never a barrel | nothing: call registerErrorStatus from @ultimat3/http, or declare an app code with defineError |
x new writes .mcp.json and mounts a refusing POST /mcp | optional: copy .mcp.json ({ "mcpServers": { "<app>": { "command": "bunx", "args": ["@ultimat3/cli", "mcp", "serve", "--transport", "stdio"] } } }) and apps/web/mcp.ts (defineAppMcp({ include: 'exposed', resolveToken: apiKeyResolver(() => appAuth().adapter) })) from a fresh bunx create-ultimate, or set ai: { mcp: { expose: false } } to silence X_MCP_APP_UNMOUNTED. Spell commands bunx x … in AGENTS.md, CLAUDE.md and .claude/ |
x docs reads the wiki and every installed @ultimat3/* package; its hits move | nothing: the --json shape is unchanged |
an app test file through @ultimat3/testing/preload starts on the installed frozen instant: the clock is reset at every file boundary | a file that relied on an EARLIER file's advanceClock calls setFrozenClock() itself |
@ultimat3/core/render-nodes ships the node-tree walker for tests | optional: a test that copied a walker (a Symbol.for('ultimate.render.jsx') check over type/props) imports renderNodes, nodesOf, byTag, byComponent, withAttr, one, attachRef and fire from it; examples/dummy/apps/web/app/settings/page.test.ts is the worked example |
x new writes AGENTS.md as a symlink to CLAUDE.md; x upgrade links an AGENTS.md byte-identical to CLAUDE.md and reports a different one as data.agentsMd: "differs" | optional: merge what only AGENTS.md says into CLAUDE.md, then ln -sf CLAUDE.md AGENTS.md. The manifest step then holds CLAUDE.md to the 12 kB AGENTS.md budget: raise agentsMdMaxBytes in x.verify.json if it needs more. A Windows clone without core.symlinks checks the link out as a file reading CLAUDE.md |
x env init --production writes .env.production; x deploy --method compose refuses without one | add .env.production to .gitignore if yours does not list it (x env init does this itself) |
x dev and the statements fixture report a loop of await job.enqueue(input) as X_N_PLUS_ONE_WRITE, naming handle.enqueueMany | replace the loop with await job.enqueueMany(inputs): one round trip per 1,000 inputs |
a duplicate job enqueue with a different payload, or one still in flight, never threw X_IDEMPOTENCY_CONFLICT, whatever the wiki said: it answers { deduped: true, id } of the live row, and the first payload wins | a catch for X_IDEMPOTENCY_CONFLICT around <job>.enqueue() never runs: read result.deduped. A job re-enqueuing itself from its own body arms nothing, because its own running row holds the key: re-arm from outside the run, for example a task on a cron |
webhookReceiver() from @ultimat3/jobs is the one supported door for an inbound webhook; a pinned action (http: { path }) or a hand-mounted runtime.ts route keeps working | optional: replace it with webhookReceiver({ name, path, tenant, verify, handle }). In verify(inbound) run the signature check (verifyBodyHmac(...), answering { text }, or verifyWebhookSignature(inbound.request(), { secret })) and return { eventId, payload } read from the verified data, never an unsigned header; move the work into handle. List it in defineApi({ jobs }), delete the runtime.ts line, and point the vendor at the new path, which must not sit under /api or /_x (X_WEBHOOK_RECEIVER_INVALID). A verify that parses the body catches the parser's error and throws its own code: Bun's JSON.parse message quotes the token it stopped at. Past the queue's live window handle runs at least once per eventId; the stored payload stays in x_jobs until jobs.doneRetentionMs / jobs.deadRetentionMs |
importRows() from @ultimat3/jobs reads a CSV or ndjson object page by page into the app's handle | optional: replace a hand-rolled import with importRows({ name, input, tenant, source: () => disk('…'), key, format, columns, schema, handle, errors: { sink, prefix } }), writing with upsertAll in handle, since a page can be handled more than once. A cell exportRows() prefixed with ' comes back with the ' |
browser reporting, clientErrors in app.config.ts, is off by default | optional: clientErrors: { enabled: true } mounts /x-client-errors.js and POST /_client-errors and reports each app/ document's uncaught failures as X_CLIENT_ERROR. Signed-in members only, 30 reports a minute each; anonymous: true opens it to visitors with no session, limited per address |
assets: { retain: { disk, builds } } keeps earlier builds' hashed files reachable across a deploy; off unless declared | optional: name a disk every web pod can read (an S3-compatible bucket, or a volume shared on one box) and size the window, assets: { retain: { disk: 'deploys', builds: 3 } }. Each app and environment gets its own prefix (x-build-assets/<config.name>/<environment>/). A disk the app did not declare refuses the web boot with X_CONFIG_INVALID; a file over the disk's maxPutBytes is skipped and named in one assets.retain_skipped line |
/admin/audit refuses a parameter it does not read with a 400 (X_ADMIN_FILTER_INVALID), not the unfiltered trail | drop the parameter. An app that overrode admin.audit.empty for the row's history card moves that text to admin.audit.empty-row; admin.audit.empty is the trail's "nothing matches". An app's own AuditLog honours outcome, since and until in entries() with auditWindow(subject, query) and auditEntryMatches(entry, query), or the screen drops the entries that do not match and pages draw short |
x ci gains tested; --branch, --run, --tail, --full and --event belong to runs | nothing: x ci with no subcommand is x ci runs, as before |
X_DB_LOCK_TIMEOUT's fix: reads x db diagnostics --json | jq '.data.blockers.rows[] | {pid, blockedBy, blockerState}' | a script that matched the old psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity …" text matches on the code instead. --limit on x db is accepted by diagnostics as well as backfill |
x new writes storeMode(env) === 'memory' ? testDriver() : postgresDriver() in packages/db/src/client.ts | optional, one line: import { type Driver, database, postgresDriver, testDriver } from '@ultimat3/entity', then change the memory arm of selectDriver to testDriver(). Without it nothing changes; with it a test file that runs the Testing recipe reads and writes its migrated database through db, and a file that installs no client behaves as before. A web workspace that runs the recipe lists @ultimat3/db (and @ultimat3/cli) among its dependencies |
hand-rolled polling in an island (setInterval(…) beside a visibilitychange listener) | optional: visibleInterval(run, ms) from @ultimat3/core/page, or useQuery(ref, input, { poll: pollEvery(ms) }) for a read; x g guard raw-interval adds the guard that refuses the bare call. A channel event that re-renders the page is scheduleRefresh() from @ultimat3/render/client, not refresh() |
errors: on action(), mutator() and query() is optional | an operation that does not declare it keeps its behaviour and its OpenAPI bytes. To close a contract, list each 4xx code the handler throws, importing the defineError class and listing its .code (the import registers the status before action() checks the list): errors: [PostNotFound.code, 'X_FORBIDDEN']. Then x verify --only contract: a 4xx the list does not name is X_ERROR_UNDECLARED, whose fix: names the code to add |
http.path takes :param templates, and http.method is new | nothing for an app that pins no parameterised path: every static route, its OpenAPI bytes and its manifest fact are unchanged. To serve a resource-shaped URL pin it on the primitive and write no route file: http: { path: '/orders/:id/refund', method: 'POST' }, each :param a required t.string key of input:. Call it with action.client() or read.client(); derivePath('refundOrder') throws, so use actionHttpPath('refundOrder', { id }) |
a body or search string naming a :param's key | it carries the URL's value or leaves the key out; a different value is 400 X_HTTP_PATH_INPUT_CONFLICT |
every action pinned before 30.0.0 gains http: { path, method: 'POST' } in x.manifest.json | additive in contract-diff, not breaking: regenerate with x manifest |
an app with no persist: true entity: a useQuery / useRecord island is no longer held | nothing: it paints earlier |