Home

Ultimate wiki

A full-stack, Bun-only, opinionated framework: Rails' philosophy applied to Bun + Postgres + SolidJS, where the primary developer is an AI agent and the secondary developer is a tired senior engineer working through their own AI agent and AI reviewer.

As of 2026-08-20. 29 @ultimat3/* packages plus the unscoped create-ultimate — 30 in all — versioned in lockstep, and the current line is a major: 25 changelog entries are marked BREAKING — from a sweep that closed every known gap, and none ships a codemod (Upgrading). 2.0.0 was the first major and carried 33; 3.0.0 carried 10. The footer is the only page here that stamps a version — one release bumps one line, and a stamp on a second page is 46 hand-copies of one fact.

Repository and registry agree, and there are no publication holes As of 2026-08-20. bunx create-ultimate myapp installs whatever latest is; all 30 workspaces resolve at that one version, each published by release.yml over OIDC with a provenance attestation, and registry-audit.yml files an issue on the day that stops being true. Resolve it rather than believing this sentence:

Fact	Read it yourself
what latest is	npm view @ultimat3/core version
that a tarball is attested	npm view @ultimat3/core dist.attestations
who published it	npm view @ultimat3/core _npmUser

Fixed in 2.0.0, in 3.0.0 and in 4.0.0 all mean fixed in a release you can install; the "on 1.2.0, do X" column beside such a row is for readers still pinned to 1.x, not a current workaround. No publication holes — @ultimat3/scraping was the last never-published package, bootstrapped by hand at 2.0.0, so bun add @ultimat3/scraping resolves and browser automation no longer needs a checkout. 3.0.0 and 4.0.0 both went out through the workflow, each tarball attested; 2.0.0 went out by hand and is the one release whose tarballs carry no attestation at all, and 1.0.0 was the manual bootstrap. Milestones 0–10 are ✅; milestone 11 is 🚧, still open on the two-platform deploy proof — 1.1.0 gave a scaffolded app a real deployable artifact, which is progress toward it, not the proof.

The realtime restart numbers are measured and committed, in two halves that answer different questions (scripts/bench/results/). Reachability: 50,000 real WebSocket clients against a single sync node over InProcessTransport, SIGKILLed with no drain — all 50,000 reconnected, 49,981 received a channel patch inside the window, p50 54.0s / p90 105.5s / max 145.7s, and 156,851 connect attempts shed by the AcceptBudget before any query path. That times the first patch on the reconnected socket and nothing after it; it was published as "time-to-consistent" until 2026-08 and could not see a lost patch, so the name changed and the timings did not. Delivery: 10,000 clients, same forced restart, a probe every 200ms — 1,666,882 channel patches received, 0 observed sequence gaps, As of 2026-08 the only run with delivery accounting. That counts holes between frames a connection actually received, so it is a lower bound: no client observed a lost frame, which is not the same claim as none was lost. Both are per-node recovery: neither crossed NATS, so neither is a multi-node result and neither is a throughput figure → Realtime. This wiki is the only public documentation surface; there is no separate site.

Those facts are repeated on several pages because the wiki is plain markdown with no build step. Change them at the source first, then here: docs/idea/14-roadmap.md owns milestone status, CHANGELOG.md owns the version, scripts/bench/results/ owns the benchmark, and VERIFY_STEP_NAMES in packages/cli/src/verify-step.ts owns the x verify step list.

bunx create-ultimate myapp && cd myapp && x dev

If you are	Read, in order
Evaluating it	Getting started → The eight primitives → FAQ
Moving a production app off another stack	Migrating an existing app → Known gaps → Entities and migrations
Building an app	Installation → Project layout → Actions → Testing
An agent driving the framework	CLI reference → Error codes → MCP and AI → Agents
Operating it	Configuration → Deployment → Observability → Troubleshooting
Deciding whether to trust it	Known gaps → FAQ → Upgrading
Contributing	Contributing → Project layout → Testing

Start

Page	What it covers
Getting started	zero to a running app, one action, one green x verify
Installation	prerequisites, x new, typed env, editor and MCP client setup
Project layout	the generated monorepo, the four surfaces, feature slices, the hard boundaries
Migrating an existing app	strangler fig off Rails/Node/Django, adopting a live schema, identity during cutover, and what does not work yet

Tutorials

Follow in order. Each page states what it was executed against in its own first line — tutorial 1 is re-measured on main, the rest against published 1.1.0 packages — and names the gaps it hits with the workaround.

Page	You end with
1 · First app	a scaffolded app running on x dev, green gate, no Docker
2 · First feature	one action projected into five surfaces, with tests
3 · Auth and admin	roles, policies and a real login flow
4 · Jobs and realtime	a durable job, a cron task, a live query
5 · Deploy free	the image running on a free PaaS tier, migrations on release
6 · Growing up	the rung you should be on, and the signal to climb

The primitives

Page	What it covers
The eight primitives	entity, policy, action, mutator, query, job, route, task — the whole vocabulary
Building your own base	wrap a primitive in your own factory: tenantEntity, auditedMutator, the two caveats, and why nothing downstream notices
Actions	every field, the six generated artifacts, the mutator twin, contract tests
Entities and migrations	tables, invariants, tenancy, x db gen, drift, branch databases
Policies and authz	can(), where a policy is evaluated, denials, tenancy scoping
Queries and live queries	reads, live: true, per-row policy, bounded SQL
Jobs and workflows	transactional outbox, durable steps, idempotency, drivers
Scheduled tasks	cron with an explicit tz, leader election, next-run introspection
Routes and render modes	five render modes, hydration timing, budgets, enforced SEO

Capabilities

Page	What it covers
Realtime	channels → live queries → local-first, the pipeline, the reconnect problem
Caching and invalidation	four tiers, one tag graph, one-hop fanout
Batching and preloading	JIT preload, .preload(), insertAll/upsertAll/updateWhere, inBatches, the tenancy guarantee
N+1 detection	the two codes, expectedQueryLoop, four surfaces, why prod pays nothing
PWA and offline	generated sw.js, precache budgets, version skew
MCP and AI	the dev MCP server, every action as a tool, the llm() gateway, evals
Agents	agent() as an action factory, tools as real actions, hive(), agentJob(), and the at-least-once trap
Admin dashboard	the generated admin app and its MCP surface
Scraping	scrape() as a job factory, the driver-blind page vocabulary, robots and host gates, the yield alarm

Cross-cutting

Page	What it covers
I18n	flat catalogs, loud misses, locale routing, hreflang
Theming	24 semantic colour roles as RGB channels, every token scale, defineTheme(), what contrast is gated
UI components	the four page composites, and the generated 52-component catalog
Timezones and dates	store UTC, format with an explicit IANA zone, frozen clocks in tests
Money	Money = { minor, currency }, never a float
Resource management	Disposable db resources, using/await using, idempotent release, compile-time pins
Migrations and backfills	one migration engine and ledger, the destructive-migration rail, backfill() as a job factory
Testing	six test types, cloned databases, sealed network, x verify

Reference

Page	What it covers
CLI reference	every x command and flag, with --json examples
Error codes	every X_* code: meaning, cause, exact fix
Configuration	every app.config.ts field and every env var
Deployment	one image, six roles, ROLE/PORT, drain, compose, Helm, targets, docs/ops/
Observability	counters, gauges, histograms, MetricExporter, the Prometheus body, /metrics on its own port, and what the chart still cannot reach
Known gaps	every defect and unfinished seam in the published release, named
Upgrading	why the next release is a major, breaking-change detection, version skew — and that x upgrade is planned
Troubleshooting	symptom → cause → fix
FAQ	why Bun only, why no GraphQL, is it production ready
Contributing	package layout, import tiers, conventions, PR expectations

The rules everything else follows

Axiom	Consequence
One way to do each thing	no adapter zoo, no mode: escape hatches. Removing an alternative is a feature
Define once, project everywhere	one action → HTTP route + OpenAPI + typed client + job handle + MCP tool + tests
Enforced, not documented	a convention that isn't a build error doesn't exist
Errors are instructions	stable X_* code + cause + exact fix command + --json
One command means shippable	x verify green = deployable
The static path never pays for the app path	site/ cannot import app/; 0kb JS is structural
Deploy anywhere = containers only	zero platform primitives
Ultimate ships mechanism; your app ships convention	mechanisms and structural conventions ship; business conventions never do. Tenancy ships, an org model does not — primitives are functions returning values, so an app wraps one → Building your own base

Source docs in the repo

Where	What it is
docs/idea/	why — the design spec
docs/architecture/	how — the internals
docs/ops/	running an app for real: the PaaS → Compose → Kubernetes ladder, secrets, observability, datastore sizing, disaster recovery, runbooks. Recommendations only — the framework depends on none of it
docs/idea/16-app-targets.md	three targets, one backend, two view layers — design only, not shipped behaviour
docs/idea/17-scale-ladder.md	why the app code is identical at rung 0 and rung 4 — shipped, not design only: 24 of its 26 seam rows are marked shipped, rungs 0–2 are real, and the places the invariant breaks today are named
packages/ui/CATALOG.md	all 52 components with every prop, generated from source and drift-tested
framework.manifest.json	every package, tier, and X_* code with its owner — generated
llms.txt	the machine-readable repo map for agents