Ultimate

Ultimate

The full-stack framework where the primary developer is an AI agent.

Rails' opinions. Bun's speed. One command that means shippable.

[](https://github.com/developerz-ai/ultimate/actions/workflows/ci.yml) [](LICENSE) [](https://bun.sh) [](CHANGELOG.md)

> Status: 1.2.0, As of 2026-08. 28 @ultimat3/* packages plus the unscoped create-ultimate — 29 in all — versioned in lockstep: one version, one commit, one tag. @ultimat3/flags has never reached npm and the rest sit at 1.2.0, so the registry is not yet in lockstep with the repo (#84); it needs the one-time manual bootstrap every package gets before a trusted publisher can attach. 1.1.0 was the first release published by the workflow, over OIDC trusted publishing with provenance attached; 1.0.0 was the manual bootstrap. Semver applies — a breaking change to a documented API needs a major. That is what the version number means: a stable API under semver, not a promise about your infrastructure.

Built by agents, for agents, maintained by agents

Nobody writes this code by hand anymore, and the framework is designed for that rather than retrofitted to it. A coding agent works 24/7/365, and — the part that actually matters — it writes the tenth feature the way it wrote the first. No Friday-afternoon shortcut, no "I'll clean this up later", no second way of doing a thing because someone new joined. Consistency at volume is the thing humans are worst at and agents are best at.

That only pays off if the framework agrees. One way to do each thing, so there is nothing to choose between. Conventions that are build errors, so the compiler corrects the agent instead of a reviewer. Errors carrying a stable code, a cause and a command that fixes it, so a failure costs one round-trip. Docs local in node_modules, so nothing reaches for a wiki. --json on every command, so output is parsed rather than re-read. Each of those is worth a little on its own; together they are the difference between an agent that ships and one that thrashes.

The Matrix (1999)

Measured, and only this much:

| What was measured | The result | |---|---| | Realtime reachability | 50,000 real WebSocket clients against one sync node, SIGKILLed with no drain — no reconnect frame sent, so every client recovers on its own backoff. All 50,000 reconnected; 49,981 received a channel patch inside the window. Time to first patch on the reconnected socket: p50 54.0s, p90 105.5s, max 145.7s. It times reconnect + resubscribe + one delivery, and nothing after it — it was called "time-to-consistent" until 2026-08, and it could not see a lost patch | | Realtime delivery | 10,000 clients, same forced restart, a probe every 200ms: 1,666,882 channel patches received, 0 observed sequence gaps — every client's sequence dense across its connection, no gap, no duplicate, no rewind. A lower bound, not a proof of zero loss: a hole is only visible between two frames one connection received. As of 2026-08 the only run with delivery accounting; the 50,000-client result predates the counter and has none | | The DB-load half | 156,851 connect attempts shed by the shipped AcceptBudget (500/s, burst 2000) before reaching any query or snapshot path. Recovery is bounded by admission control, not by the matcher | | What it is not | one node, in-process transport — neither run crossed NATS, and neither subscribes to a live query, so no cursor, snapshot or gap-repair path is under test. Per-node recovery, not a multi-node result, and not a throughput or latency-under-load figure |

Reproduce it: bun run scripts/bench/restart-bench.ts --clients 10000 --probe-interval-ms 200 — the committed report and the run's own transcript are in [scripts/bench/results/](scripts/bench/results/).

Not claimed at 1.1.0:

| Open | Where it stands | |---|---| | Two-platform deploy proof | 1.1.0 gave a scaffolded app a real deployable artifact — x new writes apps/web/server.ts, prerender.ts, a Dockerfile and docker-compose.prod.yml, and ROLE=migrate runs release-phase migrations. The proof is still open: the demo app on Compose and K8s from one image, with an invisible rolling restart, is [milestone 11](docs/idea/14-roadmap.md) and has not been demonstrated | | Known gaps shipped in 1.1.0 | all four are fixed on main, unreleased — but a fix and a proof are different things, and one of the four still lacks the proof. x build --target binary no longer crashes at import — the version read is lazy and x build passes --define ULTIMATE_FRAMEWORK_VERSION, and [docker/Dockerfile](docker/Dockerfile) passes it too and ends in /out/app --version, so a binary that cannot answer fails the image build rather than the first command an operator runs. The target is still unproven end to end: booting is not serving, and no scaffolded app has been compiled and served from a bare VM · docker-compose.prod.yml no longer pairs a published host port with replicas above 1: web and sync declare replicas: 1 in all four files and each header names the two ways up, which makes the one-box ceiling declared rather than broken, not lifted · the shared cache tier's Lua invalidation no longer DELs keys it never declares in KEYS · resolveEnvironment exists only in core, and @ultimat3/seo exports neither it nor SeoEnvironment — a breaking change, unreleased. Detail in [CHANGELOG.md](CHANGELOG.md), per-row workarounds for the published packages in Known gaps | | Deferred to v2 | realtime tier 3 local-first (persist: true), the plugin API, multi-region replication, the Redis/NATS job drivers — each behind the interface that ships today. The job drivers throw X_NOT_IMPLEMENTED with a runnable fix: rather than pretending to work |

Never claimed: no adoption numbers, no production deployments, no testimonials. None exist yet, and this file will say so until they do.

---

Why Bun, why SolidJS

Two picks that are load-bearing rather than fashionable, and both for the same reason: they remove a layer an agent would otherwise have to reason about.

Bun is one toolchain where there were six. Runtime, bundler, test runner, package manager, node: compatibility, an HTTP and WebSocket server, hashing and SQLite are the same binary — so there is no tsconfig-versus-bundler-versus-jest disagreement to debug, and no chain of tools each with its own idea of what a module is. It runs TypeScript directly, which is why the tarball published to npm is the source you read: no dist/, no source-map hop when an agent steps into node_modules. And the natives are why the dependency list is two packages long — HTTP, WS, hashing, SQLite, test running and bundling are already there, so most of what a framework would reach for is not a decision at all.

SolidJS compiles away. Fine-grained reactivity means an update touches the one text node that changed rather than re-running a component and diffing a virtual DOM, and there is no re-render model to hold in your head — no dependency arrays, no memo hooks, no rules about where state may be read. That matters twice here: the runtime is small enough that render: 'static' genuinely ships zero JavaScript, and the mental model is small enough that an agent writing its four-hundredth component is not carrying a rulebook about when a closure captures a stale value.

Neither is a bet on popularity. They are the two choices that make the framework's own promises cheap to keep — one command that means shippable, and a static path that never pays for the app path.

---

The thesis

Every framework built in the last fifteen years optimised for a human typing code. Ultimate assumes the code is written by an agent and reviewed by a tired senior engineer working through their own AI agent and AI reviewer.

The goal is the one Rails had: shrink the set of problems the author has to hold in their head, so they spend their attention on the app's features and not on the app's infrastructure. An agent that has to decide on a migration tool, a queue driver, a cache key scheme and an authz model has spent its budget before writing a feature.

That single change of audience rewrites every default:

| Because the author is an agent… | Ultimate does this | |---|---| | ambiguity costs tokens and correctness | one way to do each thing — no second-best path to choose between | | repeated definitions drift | define once, project everywhere — one action becomes six artifacts | | documented conventions get ignored | enforced, not documented — a violated convention is a build error | | errors are the feedback loop | errors are instructions — stable code + cause + the exact fix command | | "is it done?" needs a machine answer | x verify — green means shippable, and it's the whole contract | | output must be machine-readable | --json on everything, end to end |

Wrap, don't reinvent

The framework wraps libraries so you don't have to. Your app wraps the framework so your agent doesn't have to. Two layers, one goal: the least app code that can express the app — more generated code is more bugs, so the unit of progress is lines not written.

| Layer | Wraps | So that | |---|---|---| | Bun natives | Postgres, Redis, S3, WS, the bundler, the test runner | a whole class of dependency never enters the lockfile — see the stack table below | | Ultimate | those natives, behind eight primitives | an agent writes entity / action / job — never a connection pool, a queue, or a cache-key scheme | | Your app | those primitives, behind your own domain vocabulary | a feature is a declaration, not an integration |

The rule that stops this becoming an abstraction tower: a wrapper must delete a decision, not rename one. Reinvention is reserved for the places where wrapping would leak the thing being avoided — which is why there is no ORM, and why the router is ours.

The framework makes the big decisions so the agent spends its budget on your product. Breadth is not the enemy of control; undeclared coupling is. Every capability arrives as an interface with one shipped implementation — assemble like Lego, and drop to the seam when Lego runs out.

→ [The thesis, in full](docs/idea/00-thesis.md)

60 seconds

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

No Docker. No env scavenger hunt. Embedded Postgres, in-process NATS, S3 → a local directory. What you get is a running app with auth, a seeded database, a working example route, and a dev dashboard at /_x.

Every @ultimat3/* dependency it writes is pinned to one exact version. They move together — never mix versions across the scope.

One action, six artifacts

This is the load-bearing idea. You write one declaration:

export const publishPost = action({
  input:  t.object({ postId: t.uuid, orgId: t.uuid, notify: t.boolean.default(true) }),
  output: PostView,
  policy: can('post:publish', ({ input, actor }) => ownsPost(actor, input.postId)),
  cache:  { invalidates: [tag.post, tag.feed] },
  mcp:    { expose: true, description: 'Publish a draft post' },

  async handle({ input }) {
    const post = await publish(input.postId);
    if (input.notify) await notifySubscribers.enqueue({ postId: post.id, orgId: input.orgId });
    return post;
  },
});

> As of 2026-08, the handler's ctx is not the full Ctx. Over HTTP it is a cast of the > request context: it carries actor, locale, tz, requestId and traceId, and it does not > carry logger, now(), clock, signal or services. So ctx.posts and ctx.logger.info(...) > throw on the HTTP path, though both work under a job. Import your service and call the job handle > directly, as above. Tracked, with the fix, in [Known gaps](wiki/Known-Gaps.md).

Ultimate generates all of this from it:

| # | Artifact | Detail | |---|---|---| | 1 | POST /api/posts/publish | the HTTP route, with validation and authz wired | | 2 | OpenAPI entry | deterministic output, diffed by x verify against the committed spec | | 3 | typed RPC client | api.publishPost(...) — a typo is a compile error in the component | | 4 | an MCP tool | identical authz. One policy, two surfaces. | | 5 | a job-callable handle | enqueue the same logic as durable work, no rewrite | | 6 | a contract test + policy test stub | passing, not a TODO |

Authz is defined once and enforced across HTTP, live queries, jobs, and MCP. Two authz systems is how every Meteor-like framework died.

The eight primitives

Everything in the framework is one of these. If a feature doesn't fit, it doesn't ship.

| Primitive | Is | |---|---| | entity | a table + its domain type + invariants | | policy | an authz rule, evaluated in every surface | | action | a mutation or command (server-authoritative) | | mutator | an action with an optimistic local twin (offline/realtime) | | query | a read; optionally live (subscribable) | | job | durable background work, optionally multi-step | | route | a URL + render mode + metadata + offline strategy | | task | a scheduled trigger (cron) that enqueues jobs |

→ [The eight primitives, in full](docs/idea/02-primitives.md)

What you get for free

Not "supported". Not "documented". Enforced, and impossible to get wrong.

| Concern | The default | The enforcement | |---|---|---| | i18n | flat catalogs, Intl for everything numeric | a missing key in a shipped locale fails x verify; misses render loudly as ⟦key⟧ | | Dark theme | semantic tokens, OS-following with an explicit override that wins | a raw hex in a component is a lint failure; one token source of truth | | Timezones | store UTC, format with an explicit IANA zone | no formatter has an ambient default; a cron without a tz won't compile | | Money | integer minor units + currency, always attached | cross-currency arithmetic is refused; the exponent comes from the ISO table, never /100 | | SEO | typed metadata, JSON-LD, sitemap from the route table | a site/ route with no description is a build error | | Offline | sw.js generated from the route table | the offline fallback route is required by the type | | Admin | Django-grade CRUD derived from the entity registry | defineAdmin() — 20 lines to a working dashboard | | MCP | every action is a tool | and your app's dashboards expose their own MCP surface | | Metrics | counters, gauges and histograms on the OpenTelemetry data model; /metrics in Prometheus text | no dependency, and the Helm chart's HPA metrics are the ones the framework already emits | | Secrets | Secret redacts by value — toString, toJSON, the logger, at any depth, under any key | frozen, so a spread cannot unwrap it; .env.example is generated from the typed env declaration |

Rendering — SSR only where it pays

Render mode is a route-level property, not a global one. A landing page is static or ISR at a 0kb JS baseline; a dashboard streams. The site/ surface cannot import from app/ — a build error, not a lint warning — so the marketing path can never grow the app's bundle through a shared component.

| Surface | Default mode | JS baseline | |---|---|---| | site/ | static / isr | 0kb, enforced | | app/ | stream | a per-route budget that fails the build when blown | | api/ | none | n/a |

→ [Surfaces](docs/idea/06-surfaces.md) · [Rendering and SEO](docs/idea/07-rendering-seo.md)

Realtime — a ladder, not a cliff

Three tiers, the same mutator shape at every rung. Tier 2 → tier 3 is a config flag, not a rewrite. Tiers 1–2 ship today; tier 3 lands in v2, behind the interfaces that are already here.

| Tier | What | Covers | |---|---|---| | 1 · Channels | ctx.publish(topic, msg) over B

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: developerz-ai
• Source: developerz-ai/ultimate
• License: MIT
• Homepage: https://github.com/developerz-ai/ultimate/wiki

Install and usage instructions live in the source repository linked above.