The eight primitives

Everything in the framework is one of these. x g resource <name> scaffolds a whole feature slice — an entity + repo, a policy, an errors module, two actions (create-*, archive-*), a live query, a job, an app route, plus service, UI and i18n files, 25 in all — each with a test that passes on the first run. Not one of each: the slice emits no mutator and no task. Those have their own generators.

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

Every one is a function returning a value, so an app encodes a house rule by wrapping one and exporting its own factory — tenantEntity, auditedMutator — with the registry, the manifest, the projections, admin and MCP treating the result identically. That is how the framework extends itself too (llm() returns an action, backfill() returns a job), and it is why there is no plugin API → Building your own base.

Every primitive projects itself

A primitive's surfaces are methods on the primitive, never free functions taking it. publishPost.openapi(), not toOpenApiOperation(publishPost). (The MCP tool is @ultimat3/mcp's one projection, toolFrom(publishPost): a tier-3 primitive cannot hold a tier-4 projection.) Every declared field is lifted onto it, and the declaration object — the handle, the sql, the server — is not reachable from app code at all.

The declaration lives in a private store inside the package that runs it, and nothing exports a reader for it. So there is one execution path and one authz path structurally, not by convention: a hand-rolled look-alike carrying the right kind is X_ACTION_FOREIGN / X_QUERY_FOREIGN, never a registered primitive. Registration stamps the export name in place, so import { publishPost } is the object that projects once the app has booted — there is no second, differently-named twin to remember.

Each primitive's deep page carries the full member table.

One import per authoring file

t is re-exported from every package that hosts a declaration factory. Import it from the package you declare in; never reach past that package to @ultimat3/schema. It is the same object, not a copy — configureSchemaProvider() still swaps the provider under it — and each package pins that with an identity assertion in its index.test.ts.

policy and route declare no schema, so neither package re-exports t: a policy decides from ({ actor, input, row, ctx }) and a route from its path.

entity

A table + its domain type + invariants. The single source of the DB schema, the TS type, and the parse boundary.

policy

An authz rule, evaluated in every surface.

policy: can('post:publish', ({ input, actor }) => ownsPost(actor, input.postId))

action

A mutation or command, server-authoritative. Declared once, projected six ways.

export const publishPost = action({
  input:  t.object({ postId: 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, ctx }) {
    const post = await ctx.posts.publish(input.postId);
    if (input.notify) await notifySubscribers.enqueue({ postId: post.id, orgId: post.orgId });
    return post;
  },
});

mutator

An action with an optimistic local twin. local runs client-side against the local store; server is authoritative. Same input, same name, both halves in one file.

export const likePost = mutator({
  // REQUIRED (`X_MUTATOR_NOT_IDEMPOTENT`): a replay under the same Idempotency-Key answers the
  // first result instead of running `server` again.
  idempotent: true,
  // Convergent, not incremental: `local` replays on every rebase, so applying it N times has to
  // equal applying it once — `likedByMe` is what makes the second application a no-op.
  local(tx, { postId }) {
    tx.posts.update(postId, (p) =>
      p.likedByMe ? {} : { likedByMe: true, likeCount: p.likeCount + 1 });
  },
  async server(ctx, { postId }) { return ctx.posts.like(postId); },
  conflict: 'server-wins', // | 'last-write-wins' | custom(merge)
});

query

A read; optionally live (subscribable).

export const liveFeed = query({
  input: t.object({ orgId: t.uuid }),
  policy: can('feed:read'),
  live: true,
  sql: ({ orgId }) => db.posts.where({ orgId }).orderBy('createdAt').limit(50),
});

job

Durable background work, optionally multi-step. idempotencyKey is required by the type.

export const onboardOrg = job({
  input: t.object({ orgId: t.uuid }),
  tenant: ({ orgId }) => orgId,               // the org this run acts as
  idempotencyKey: ({ orgId }) => `onboard:${orgId}`,   // REQUIRED by the type
  retry: { attempts: 5, backoff: 'exponential' },
  async run({ input, step, ctx }) {
    const org = await step.run('provision', () => ctx.orgs.provision(input.orgId));
    await step.run('welcome-email', () => ctx.mail.send(welcomeEmail, org));
    await step.sleep('3d');
    await step.run('nudge', () => ctx.mail.send(nudgeEmail, org));
  },
});

route

A URL + render mode + metadata + offline strategy.

export const config = defineRoute({
  render:     'isr',                  // static | isr | ssr | stream
  revalidate: { tags: [tag.post] },
  prerender:  () => db.posts.slugs(),
  offline:    'precache',             // precache | runtime | network-only
  hydrate:    'visible',              // idle | visible | interaction | never
  budget:     { js: '40kb' },
  meta:       ({ post }) => ({ title: post.title, description: post.excerpt,
                               og: { image: post.cover }, ld: ld.Article(post) }),
});

Render modes: static (built once), isr (static + background regen), ssr (per-request), stream (shell flushed instantly, holes streamed — default for app pages). Four, declared once in @ultimat3/core as RENDER_MODES; spa was the fifth until 6.0.0. Table in Routes and render modes.

task

A scheduled trigger. Enqueues jobs; never does work itself.

export const nightlyDigest = task({
  cron: '0 3 * * *',
  tz: 'UTC',
  enqueue: () => [[sendDigest, {}]],
});

Composition

entity ──> policy ──> action ──> job ──> task
   │          │         │
   │          └──> query (live) ──> route
   └──> mutator (action + local twin)

Feature slicing puts a feature's primitives in one folder, not one layer per app:

apps/web/app/<feature>/{entity,repo,service,actions,live,jobs,policy,ui}.ts

Every primitive emits its test beside it, and that test passes on the first run — a generator that emits a TODO has moved the work, not done it. What it pins is the distant invariant the primitive owns: a policy denial, an idempotency key, a budget. Extend it as the feature grows (Testing). Every primitive appears in x.manifest.json, so x manifest --json and the MCP manifest.read tool describe the whole app as data.

The rule

If a feature doesn't fit a primitive, it doesn't ship. No ninth primitive, no escape-hatch mode: option, no plugin API in 1.0. Removing an alternative is a feature — ambiguity is the tax agents pay. Source: docs/idea/02-primitives.md.