bunderstack 0.21.1 → 0.22.0

package/dist/testing.d.ts

@@ -1,27 +1,10 @@
-export type AuthSessionResolverLike = {
-    api: {
-        getSession: (opts: {
-            headers: Headers;
-        }) => Promise<unknown>;
-    };
-};
-export type BunderstackAppLike = {
-    auth: unknown;
-};
-/**
- * Mock the auth session resolver on a Bunderstack app instance for unit testing.
- */
-export declare function mockAuthSession<TUser extends {
-    id: string;
-    email: string;
-    name?: string;
-    role?: string;
-}>(app: BunderstackAppLike, resolver: (opts: {
-    headers: Headers;
-}) => Promise<{
-    user: TUser;
-    session?: {
-        activeOrganizationId?: string | null;
-    } | null;
-} | null>): void;
+export { createTestApp } from './testing/fixture.js';
+export type { TestFixture, TestOptions } from './testing/fixture.js';
+export { mockAuthSession, TestAuthError } from './testing/auth.js';
+export type { SignUpEmailInput, TestAuth, TestIdentity, TestUser, } from './testing/auth.js';
+export type { CapturedEmail, TestEmail } from './testing/email.js';
+export type { TestStorage } from './testing/storage.js';
+export { TestJobsConvergenceError, TestJobsError } from './testing/jobs.js';
+export type { JobRunReport, RunNextOptions, RunUntilIdleOptions, TestJobs, } from './testing/jobs.js';
+export type { TestDatabaseStrategy, TestDatabaseTarget, TestDatabaseTargetOptions, } from './database/adapter.js';
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,uBAAuB,GAAG;IACpC,GAAG,EAAE;QACH,UAAU,EAAE,CAAC,IAAI,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAC7D,CAAA;CACF,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,OAAO,CAAA;CACd,CAAA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,KAAK,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAEzE,GAAG,EAAE,kBAAkB,EACvB,QAAQ,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,KAAK,OAAO,CAAC;IAChD,IAAI,EAAE,KAAK,CAAA;IACX,OAAO,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;CAC1D,GAAG,IAAI,CAAC,GACR,IAAI,CAON"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC/D,YAAY,EACV,gBAAgB,EAChB,QAAQ,EACR,YAAY,EACZ,QAAQ,GACT,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC/D,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACxE,YAAY,EACV,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,QAAQ,GACT,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,oBAAoB,CAAA"}

package/dist/testing.js

@@ -1,11 +1,5 @@
 // src/testing.ts — test utilities for Bunderstack applications.
-/**
- * Mock the auth session resolver on a Bunderstack app instance for unit testing.
- */
-export function mockAuthSession(app, resolver) {
-    const auth = app.auth;
-    if (auth?.api) {
-        auth.api.getSession = resolver;
-    }
-}
+export { createTestApp } from './testing/fixture.js';
+export { mockAuthSession, TestAuthError } from './testing/auth.js';
+export { TestJobsConvergenceError, TestJobsError } from './testing/jobs.js';
 //# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAYhE;;GAEG;AACH,MAAM,UAAU,eAAe,CAG7B,GAAuB,EACvB,QAGS;IAET,MAAM,IAAI,GAAG,GAAG,CAAC,IAA0C,CAAA;IAC3D,IAAI,IAAI,EAAE,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,QAEA,CAAA;IACxB,CAAC;AACH,CAAC","sourcesContent":["// src/testing.ts — test utilities for Bunderstack applications.\n\nexport type AuthSessionResolverLike = {\n  api: {\n    getSession: (opts: { headers: Headers }) => Promise<unknown>\n  }\n}\n\nexport type BunderstackAppLike = {\n  auth: unknown\n}\n\n/**\n * Mock the auth session resolver on a Bunderstack app instance for unit testing.\n */\nexport function mockAuthSession<\n  TUser extends { id: string; email: string; name?: string; role?: string },\n>(\n  app: BunderstackAppLike,\n  resolver: (opts: { headers: Headers }) => Promise<{\n    user: TUser\n    session?: { activeOrganizationId?: string | null } | null\n  } | null>,\n): void {\n  const auth = app.auth as unknown as AuthSessionResolverLike\n  if (auth?.api) {\n    auth.api.getSession = resolver as unknown as (opts: {\n      headers: Headers\n    }) => Promise<unknown>\n  }\n}\n"]}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAS/D,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA","sourcesContent":["// src/testing.ts — test utilities for Bunderstack applications.\n\nexport { createTestApp } from './testing/fixture'\nexport type { TestFixture, TestOptions } from './testing/fixture'\nexport { mockAuthSession, TestAuthError } from './testing/auth'\nexport type {\n  SignUpEmailInput,\n  TestAuth,\n  TestIdentity,\n  TestUser,\n} from './testing/auth'\nexport type { CapturedEmail, TestEmail } from './testing/email'\nexport type { TestStorage } from './testing/storage'\nexport { TestJobsConvergenceError, TestJobsError } from './testing/jobs'\nexport type {\n  JobRunReport,\n  RunNextOptions,\n  RunUntilIdleOptions,\n  TestJobs,\n} from './testing/jobs'\nexport type {\n  TestDatabaseStrategy,\n  TestDatabaseTarget,\n  TestDatabaseTargetOptions,\n} from './database/adapter'\n"]}

package/llms.txt

@@ -6,11 +6,13 @@ This file is written for coding agents. It is dense on purpose.
 
 WHAT IT IS
 
-createBunderstack() takes a Drizzle schema and returns an app whose handler is
-a single Web-Standard Request -> Response function. From the schema it
-generates secured CRUD procedures. Your own procedures, file storage, realtime
-subscriptions, and a health check live in the same oRPC graph, reachable both
-as typed RPC and as ordinary HTTP.
+bunderstack() takes a Drizzle schema and returns a synchronous, side-effect-free
+backend declaration. backend.start() materializes the production runtime whose
+handler is a single Web-Standard Request -> Response function. backend.test()
+materializes an isolated, lexically owned test fixture. From the schema the
+runtime generates secured CRUD procedures. Your own procedures, file storage,
+realtime subscriptions, and a health check live in the same oRPC graph,
+reachable both as typed RPC and as ordinary HTTP.
 
 Stack: Bun, Drizzle (+ drizzle-kit), Better Auth, oRPC v2, libSQL or Postgres,
 Bun.Image. Validation accepts any Standard Schema library; generated schemas use
@@ -22,19 +24,22 @@ integration).
 
 MINIMAL APP
 
-  import { createBunderstack } from 'bunderstack'
-  import { libsql } from 'bunderstack/database/libsql'
+  import { bunderstack } from 'bunderstack'
+  import { libsql } from 'bunderstack/libsql'
   import * as schema from './schema'
 
-  export const app = await createBunderstack({
+  export const backend = bunderstack({
     schema,
     database: { adapter: libsql(), url: 'file:./data.db' },
     access: { posts: { list: 'public', get: 'public' } },
   })
 
-  export type App = typeof app
+  export type App = Awaited<ReturnType<typeof backend.start>>
+  export const app = await backend.start()
+
   Bun.serve({ fetch: app.handler })
 
+The blueprint imports the backend declaration and never starts the runtime.
 Database adapters are imported from their own entry points: libsql(),
 pglite(), bunSql(), postgresJs(). Provisioning: `await provision(app)` pushes
 the schema in development and applies committed migrations once a migrations/
@@ -71,13 +76,38 @@ Router modules are plain objects that import the base they need:
   export const api = { boards: boardsRouter }
 
   // config
-  createBunderstack({ schema, database, api })
+  bunderstack({ schema, database, api })
 
 Do NOT write a factory that receives a bag of procedures. That pattern exists
 only because the api option used to be a callback. The callback form still
 works — api: (o) => ({ ... }) — for a router that must be built from the
 framework builder at configuration time, but the object form is the default.
 
+TESTING
+
+Use lexical fixture ownership; do not use a process-wide app registry or a
+global afterEach hook:
+
+  import { backend } from './backend'
+
+  test('creates a post', async () => {
+    await using t = await backend.test({ database: { schema: 'push' } })
+    const identity = t.auth.mockSession({
+      id: 'user-1',
+      email: 'dev@example.com',
+      name: 'Developer',
+    })
+    const client = t.client(identity)
+    await client.posts.create({ title: 'Hello', userId: identity.user.id })
+  })
+
+The fixture owns isolated database, email, storage, realtime, and job state.
+Its auth helper creates user/session identities only; application-specific
+organization setup belongs in a typed application helper. t.jobs.tick() claims
+one snapshot of runnable jobs. t.jobs.settle() repeats snapshots until the
+queue converges, a terminal job fails, or its limits are reached; it does not
+advance the clock to delayed jobs automatically.
+
 BASES
 
   o.public     session resolved only if the handler calls context.getSession()
@@ -118,7 +148,7 @@ Two placements, and the difference is the thing people get wrong.
 .use() on a base reaches only procedures built from that base. Use it for
 rules about a group of procedures: role checks, organization scope, quotas.
 
-middleware: [...] in createBunderstack reaches EVERY procedure, including the
+middleware: [...] in bunderstack reaches EVERY procedure, including the
 generated CRUD, storage, realtime, and health. Use it for observability. A
 tracing middleware attached to a base leaves generated CRUD unmeasured,
 because the framework builds those procedures itself and they never pass
@@ -137,7 +167,7 @@ through an application base.
     }
   })
 
-  createBunderstack({ schema, database, middleware: [instrumentation], api })
+  bunderstack({ schema, database, middleware: [instrumentation], api })
 
 Rules for graph-wide middleware:
 - It runs before authentication. context.user does not exist there.
@@ -262,7 +292,7 @@ ENV
 
 Server variables must not start with PUBLIC_; client variables must. Validated
 at boot; app.env and context.env are typed from the schema. Declare the schema
-in its own module so both createBunderstack and defineApi can use it.
+in its own module so both bunderstack and defineApi can use it.
 
 AUTH
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Batteries-included backend framework for Bun: type-safe oRPC APIs, auth, storage, realtime, jobs, email, and validated env from one config.",
   "keywords": [
     "backend",
@@ -48,19 +48,23 @@
       "types": "./dist/codegen.d.ts",
       "default": "./dist/codegen.js"
     },
-    "./database/bun-sql": {
+    "./bun-sql": {
       "types": "./dist/database/bun-sql.d.ts",
       "default": "./dist/database/bun-sql.js"
     },
-    "./database/libsql": {
+    "./bun-sqlite": {
+      "types": "./dist/database/bun-sqlite.d.ts",
+      "default": "./dist/database/bun-sqlite.js"
+    },
+    "./libsql": {
       "types": "./dist/database/libsql.d.ts",
       "default": "./dist/database/libsql.js"
     },
-    "./database/pglite": {
+    "./pglite": {
       "types": "./dist/database/pglite.d.ts",
       "default": "./dist/database/pglite.js"
     },
-    "./database/postgres-js": {
+    "./postgres-js": {
       "types": "./dist/database/postgres-js.d.ts",
       "default": "./dist/database/postgres-js.js"
     },
@@ -72,11 +76,15 @@
       "types": "./dist/provision.d.ts",
       "default": "./dist/provision.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
     "./schema": {
       "types": "./dist/schema-export.d.ts",
       "default": "./dist/schema-export.js"
     },
-    "./schema/pg": {
+    "./schema-pg": {
       "types": "./dist/schema-export-pg.d.ts",
       "default": "./dist/schema-export-pg.js"
     },
@@ -84,7 +92,7 @@
       "types": "./dist/typeid.d.ts",
       "default": "./dist/typeid.js"
     },
-    "./typeid/pg": {
+    "./typeid-pg": {
       "types": "./dist/typeid-pg.d.ts",
       "default": "./dist/typeid-pg.js"
     },
@@ -100,7 +108,7 @@
       "types": "./dist/cron.d.ts",
       "default": "./dist/cron.js"
     },
-    "./email/smtp": {
+    "./email-smtp": {
       "types": "./dist/email/smtp.d.ts",
       "default": "./dist/email/smtp.js"
     },
@@ -112,23 +120,23 @@
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
     },
-    "./client/rest": {
+    "./client-rest": {
       "types": "./dist/client/rest.d.ts",
       "default": "./dist/client/rest.js"
     },
-    "./client/react": {
+    "./client-react": {
       "types": "./dist/client/react.d.ts",
       "default": "./dist/client/react.js"
     },
-    "./client/solid": {
+    "./client-solid": {
       "types": "./dist/client/solid.d.ts",
       "default": "./dist/client/solid.js"
     },
-    "./client/svelte": {
+    "./client-svelte": {
       "types": "./dist/client/svelte.d.ts",
       "default": "./dist/client/svelte.js"
     },
-    "./client/vue": {
+    "./client-vue": {
       "types": "./dist/client/vue.d.ts",
       "default": "./dist/client/vue.js"
     },
@@ -136,7 +144,7 @@
       "types": "./dist/query/index.d.ts",
       "default": "./dist/query/index.js"
     },
-    "./query/react": {
+    "./query-react": {
       "types": "./dist/query/react.d.ts",
       "default": "./dist/query/react.js"
     },
@@ -148,7 +156,7 @@
       "types": "./dist/start/index.d.ts",
       "default": "./dist/start/index.js"
     },
-    "./start/auth": {
+    "./start-auth": {
       "types": "./dist/start/auth-client.d.ts",
       "default": "./dist/start/auth-client.js"
     }

package/skills/creating-bunderstack-apps/references/application-structure.md

@@ -1,23 +1,27 @@
 # Application structure
 
-## Keep the entry declarative
+## Separate declaration from runtime
 
-The Bunderstack entry constructs and exports `app` (and usually `type App =
-typeof app`), configures the declared capabilities, and calls `provision(app)`
-when the application owns provisioning. Keep unrelated external side effects
-out of its import graph: the blueprint command imports this entry with
-`BUNDERSTACK_INTROSPECT=1`.
+`src/bunderstack/backend.ts` synchronously constructs and exports `backend =
+bunderstack({...})`. It is pure: it validates the declaration and exposes
+`backend.manifest`, but it does not connect to infrastructure. The blueprint
+imports this declaration without starting the application.
+
+`src/bunderstack/index.ts` owns the production runtime: it imports `backend`,
+calls `await backend.start()`, exports `app`, and calls `provision(app)` when the
+application owns provisioning. Keep unrelated external side effects out of the
+backend import graph.
 
 Start a small API in `src/bunderstack.ts`. Split a meaningful configuration
-into `src/bunderstack/` with `index.ts`, `schema/`, `access.ts`, `auth.ts`,
+into `src/bunderstack/` with `backend.ts`, `index.ts`, `schema/`, `access.ts`, `auth.ts`,
 `env.ts`, `jobs/`, and `api/` as needed. The entry remains the one place that
-assembles those modules into `createBunderstack()`; do not create parallel app,
+starts the declared backend; do not create parallel app,
 database, or auth instances.
 
 ## Aggregate the schema
 
 Export every domain, Better Auth, plugin, and Bunderstack internal table from
-the schema object passed to `createBunderstack()`. Include
+the schema object passed to `bunderstack()`. Include
 `export * from 'bunderstack/schema'` so migrations include the internal tables.
 Define Better Auth tables required by the selected auth flows and plugins; do
 not assume a minimal auth configuration needs every optional provider table.
@@ -61,8 +65,8 @@ export const projectsRouter = {
 // src/bunderstack/api/index.ts
 export const api = { projects: projectsRouter }
 
-// entry
-createBunderstack({ schema, database, api })
+// backend.ts
+bunderstack({ schema, database, api })
 ```
 
 Do not write a router factory that receives a bag of procedures. That shape
@@ -118,7 +122,7 @@ const instrumentation = o.middleware(async ({ context, next, path }) => {
   }
 })
 
-createBunderstack({ schema, database, middleware: [instrumentation], api })
+bunderstack({ schema, database, middleware: [instrumentation], api })
 ```
 
 Three rules apply to a graph-wide middleware. It runs before authentication, so

package/skills/creating-bunderstack-apps/references/runtime-integrations.md

@@ -39,8 +39,11 @@ Declare queue jobs with `jobs: (j) => j.define(...)`, then run them in a
 separate production process:
 
 ```ts
-import { app } from './bunderstack'
+import { backend } from './bunderstack/backend'
 
+const app = await backend.start({
+  env: { ...process.env, BUNDERSTACK_ROLE: 'web' },
+})
 await app.runWorker()
 ```
 

package/skills/migrating-to-bunderstack/SKILL.md

@@ -16,7 +16,7 @@ infrastructure, use `creating-bunderstack-apps` instead.
    capability today and which call sites depend on it.
 2. Add a migration contract test before removing legacy paths, so every
    deletion has a gate that fails when behaviour is lost.
-3. Establish one Bunderstack app and one schema aggregate.
+3. Establish one Bunderstack backend declaration, one runtime, and one schema aggregate.
 4. Move auth and access without creating duplicate instances.
 5. Replace infrastructure capability by capability.
 6. Mount one handler and separate the production worker.
@@ -31,8 +31,9 @@ database client sits outside provisioning, migration state, and request
 transactions. A second env schema drifts from the validated one and passes
 locally while failing at boot.
 
-Pass `authConfig` into `createBunderstack()`, re-export `app.auth` and `app.db`
-from the entry, and let the `env` passed to `createBunderstack()` be the only
+Pass `authConfig` into `bunderstack()`, start that declaration once in the web
+entry, and re-export `app.auth` and `app.db` from the runtime entry. Let the
+declared `env` schema plus the source passed to `backend.start()` be the only
 validated source. A more specific file route also shadows the catch-all, so a
 surviving `/api/auth/$` silently keeps serving the instance you meant to delete.
 
@@ -53,7 +54,7 @@ surviving `/api/auth/$` silently keeps serving the instance you meant to delete.
 | Channel-and-payload realtime publishing                       | `ctx.realtime.publish(schema.tasks, 'update', row)` after the write commits       |
 | AWS or Tigris SDK wrapper                                     | `app.storage` buckets                                                             |
 | Resend SDK wrapper                                            | `app.email.send(...)`                                                             |
-| `createEnv()` beside the app                                  | `env` passed to `createBunderstack()`                                             |
+| `createEnv()` beside the app                                  | `env` schema in `bunderstack()` and source in `backend.start()`                   |
 | Implicit database driver                                      | Explicit adapter, `database: { adapter: libsql(), url }`                          |
 | Schema push in production                                     | Committed Drizzle `migrations/`, applied by `provision(app)`                      |
 | Undeclared deployment                                         | `package.json#bunderstack.entry` and a checked blueprint                          |
@@ -73,8 +74,8 @@ shim is acceptable when call sites are numerous; the shim is deleted under this
 same gate. Uninstall the replaced SDK package in the commit that removes its
 last importer, so a stale wrapper cannot be reintroduced silently.
 
-Tests and scripts that construct their own app instance must call
-`app.close()`.
+Tests should use lexically scoped `await using` fixtures from `backend.test()`;
+scripts that explicitly start a runtime must close the runtime they own.
 
 ## Production gate
 

package/skills/migrating-to-bunderstack/references/audit-checklist.md

@@ -6,26 +6,26 @@ output or a file reference, not an assertion.
 
 | Capability             | Legacy shape to find                                                                 | Authoritative replacement                                                            | Evidence that the move is done                                                                        | Deletion gate                                                       |
 | ---------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| Auth instance          | A second `betterAuth({...})` call, a custom session resolver, a patched `getSession` | `authConfig` passed to `createBunderstack()`; consumers import `app.auth`            | One `betterAuth` construction in the repository; a protected route rejects an unauthenticated request | No importer of the legacy auth module remains                       |
+| Auth instance          | A second `betterAuth({...})` call, a custom session resolver, a patched `getSession` | `authConfig` passed to `bunderstack()`; consumers import `app.auth`                  | One `betterAuth` construction in the repository; a protected route rejects an unauthenticated request | No importer of the legacy auth module remains                       |
 | Auth schema            | Auth tables generated into a legacy schema directory                                 | Auth tables in the one schema aggregate                                              | Generated migration includes `user`, `session`, `account`, `verification`                             | Legacy schema directory has no importers                            |
 | Database client        | A module constructing its own libSQL/Postgres client                                 | `app.db`, re-exported from the entry                                                 | The entry is the only place calling the adapter factory                                               | Legacy `db` module deleted or reduced to a re-export, then deleted  |
 | API mounting           | Hand-written handler maps; separate `/api/auth/$`, `/api/trpc/$`                     | `createApiHandlers(app)` on one `/api/$`                                             | Auth and oRPC requests succeed with only the catch-all present                                        | Shadowing route files deleted                                       |
 | Custom API routes      | Route files doing CRUD the framework can generate                                    | Generated CRUD plus `defineAccess`, or an `o.protected` procedure                    | Access rules cover each exposed table; a cross-owner request is denied                                | Route file has no client callers                                    |
 | Access control         | Per-endpoint session checks and hand-written SQL filters                             | `defineAccess(schema, rules)` with `scope.read` / `scope.write`                      | A test asserts a second user cannot read or write the first user's rows                               | Manual filter helpers unused                                        |
-| Jobs                   | BullMQ or a bespoke queue module                                                     | `jobs.define({ ... })` and `app.jobs.enqueue(...)`                                   | Job appears in `app.manifest.background.jobs`                                                         | No queue library importer; package uninstalled                      |
+| Jobs                   | BullMQ or a bespoke queue module                                                     | `jobs.define({ ... })` and `app.jobs.enqueue(...)`                                   | Job appears in `backend.manifest.background.jobs`                                                     | No queue library importer; package uninstalled                      |
 | Cron                   | `/api/cron/*` guarded by a shared secret                                             | `jobs.cron({ schedule, handler })`                                                   | Cron task appears in the blueprint                                                                    | Cron route file and its secret removed from env                     |
 | Worker topology        | `startWorker()` or a queue bootstrap in the web entry                                | `src/worker.ts` calling `app.runWorker()`, run as its own process                    | Web entry starts no worker; the worker command exists in deployment config                            | Worker process is deployed before the embedded call is removed      |
 | Realtime               | Custom WebSocket server, manual pub/sub, channel-and-payload publishing              | `realtime` config plus `ctx.realtime.publish(table, event, row)` after commit        | A direct write reaches a subscriber with the complete row                                             | Custom transport deleted; shared Redis configured for multi-process |
 | Storage                | AWS or Tigris SDK wrapper, custom multipart upload route                             | Declared buckets and `app.storage`                                                   | Upload, signed URL, and delete work through the facade                                                | Wrapper deleted and SDK uninstalled                                 |
 | Email                  | Resend or SMTP SDK wrapper                                                           | `email` config and `app.email.send(...)`                                             | A send succeeds through the configured provider                                                       | Wrapper deleted and SDK uninstalled                                 |
-| Env                    | `createEnv()` beside the app, `dotenv`, unchecked `process.env` reads                | `env` passed to `createBunderstack()`; `app.env` / `ctx.env`                         | Boot fails with a clear message when a required variable is missing                                   | Legacy env module unused; `.env.example` lists names only           |
+| Env                    | `createEnv()` beside the app, `dotenv`, unchecked `process.env` reads                | `env` schema in `bunderstack()`; source in `backend.start()`; `app.env` / `ctx.env`  | Boot fails with a clear message when a required variable is missing                                   | Legacy env module unused; `.env.example` lists names only           |
 | API declaration        | Router factories taking a bag of procedures; hand-written builder generics           | `defineApi({ schema, env })` bases in one module, plain router objects, `api` object | A router module imports its base and exports an object; no factory remains                            | `BunderstackApiBuilder<...>` and `os.$context<...>()` deleted       |
 | Observability          | Tracing or logging attached to an application procedure base                         | `middleware: [...]` in the config, which also reaches the generated CRUD             | A generated CRUD request produces a span or log line                                                  | Per-base instrumentation removed                                    |
 | Errors                 | `new ORPCError(...)` at call sites, or a second error model                          | `errors.CODE({ message })`; `BunderstackError` outside a handler                     | A failing request answers the declared status, not 500                                                | `ORPCError` import gone from the api layer                          |
 | List endpoints         | Hand-rolled limit/offset/filter/count blocks repeated per table                      | `listSpec(table, options)` applied to your own base                                  | The endpoint accepts cursor and `count: true` and answers `ListResult`                                | Duplicated paging helpers deleted                                   |
 | Migrations             | Schema push against production                                                       | Committed Drizzle `migrations/`, applied by `provision(app)`                         | `migrations/` is under version control and applies cleanly to an empty database                       | Push command removed from deployment                                |
 | Deployment declaration | No `bunderstack.entry`, no blueprint                                                 | `package.json#bunderstack.entry` and a committed blueprint                           | `bun run blueprint:check` passes in CI                                                                | Deployment reads the blueprint rather than ad-hoc process config    |
-| App lifetime           | Tests and scripts leaking app instances                                              | `app.close()` in a `finally` or `afterEach`                                          | The test run exits without hanging                                                                    | —                                                                   |
+| App lifetime           | Tests and scripts leaking app instances                                              | Lexical `await using` fixture from `backend.test()`                                  | Concurrent tests own independent fixtures and the run exits without hanging                           | —                                                                   |
 
 ## Reading a partially migrated application
 

package/skills/migrating-to-bunderstack/references/runtime-replacements.md

@@ -6,13 +6,12 @@ names; do not change the contracts.
 ## Modular entry
 
 A migrated application has enough configuration to justify `src/bunderstack/`
-with `index.ts`, `schema/`, `access.ts`, `auth.ts`, `env.ts`, `jobs/`, and
-`api/`. The entry is the only place that assembles them:
+with `backend.ts`, `index.ts`, `schema/`, `access.ts`, `auth.ts`, `env.ts`,
+`jobs/`, and `api/`. The declaration is the only place that assembles them:
 
 ```ts
-import { createBunderstack } from 'bunderstack'
-import { libsql } from 'bunderstack/database/libsql'
-import { provision } from 'bunderstack/provision'
+import { bunderstack } from 'bunderstack'
+import { libsql } from 'bunderstack/libsql'
 import { access } from './access'
 import { authConfig } from './auth'
 import { envSchema } from './env'
@@ -20,33 +19,31 @@ import { defineJobs } from './jobs'
 import { schema } from './schema'
 import * as v from 'valibot'
 
-export async function createApp(options: { databaseUrl?: string } = {}) {
-  return createBunderstack({
-    schema,
-    access,
-    env: envSchema,
-    database: {
-      adapter: libsql(),
-      url: options.databaseUrl ?? process.env.DATABASE_URL ?? 'file:./data.db',
-    },
-    auth: authConfig,
-    email: { from: process.env.EMAIL_FROM ?? 'App <no-reply@example.com>' },
-    storage: {
-      local: './uploads',
-      defaultBucket: 'files',
-      buckets: {
-        files: {
-          visibility: 'private',
-          access: { create: 'authenticated', get: 'owner', delete: 'owner' },
-        },
+export const backend = bunderstack({
+  schema,
+  access,
+  env: envSchema,
+  database: {
+    adapter: libsql(),
+    url: 'file:./data.db',
+  },
+  auth: authConfig,
+  email: { from: 'App <no-reply@example.com>' },
+  storage: {
+    local: './uploads',
+    defaultBucket: 'files',
+    buckets: {
+      files: {
+        visibility: 'private',
+        access: { create: 'authenticated', get: 'owner', delete: 'owner' },
       },
     },
-    realtime: process.env.REDIS_URL ? { redis: process.env.REDIS_URL } : true,
-    jobs: defineJobs,
-    middleware: [instrumentation],
-    api,
-  })
-}
+  },
+  realtime: true,
+  jobs: defineJobs,
+  middleware: [instrumentation],
+  api,
+})
 
 // api/base.ts — the builder is a module value, so router modules import the
 // bases they need instead of receiving them through the config callback.
@@ -59,7 +56,11 @@ export async function createApp(options: { databaseUrl?: string } = {}) {
 //
 //   export const api = { projects: projectsRouter }
 
-export const app = await createApp()
+// index.ts
+import { provision } from 'bunderstack/provision'
+import { backend } from './backend'
+
+export const app = await backend.start()
 export const { db, auth, env } = app
 export type App = typeof app
 
@@ -67,12 +68,9 @@ await provision(app)
 ```
 
 The database adapter is imported explicitly; there is no implicit driver. Keep
-the factory for tests that need an isolated `file::memory:` database.
-
-Keep unrelated external side effects out of this import graph. The blueprint
-command imports the entry with `BUNDERSTACK_INTROSPECT=1`, so a module that
-connects to a queue or calls a third-party API at import time breaks
-introspection.
+unrelated external side effects out of the backend import graph. The blueprint
+imports the declaration and reads `backend.manifest`; it never starts the app,
+connects to a queue, or needs a special environment flag.
 
 Aggregate every domain, Better Auth, plugin, and internal table in the schema
 object, including `export * from 'bunderstack/schema'`, so migrations cover the
@@ -116,8 +114,11 @@ Production queue work is its own process:
 
 ```ts
 // src/worker.ts
-import { app } from './bunderstack'
+import { backend } from './bunderstack/backend'
 
+const app = await backend.start({
+  env: { ...process.env, BUNDERSTACK_ROLE: 'web' },
+})
 await app.runWorker()
 ```
 
@@ -224,7 +225,7 @@ const url = await app.storage.getUrl(key, { expiresIn: 3600 })
 await app.storage.delete(fileId)
 ```
 
-Buckets are declared in `createBunderstack()` with their own visibility and
+Buckets are declared in `bunderstack()` with their own visibility and
 access rules. Delete the AWS or Tigris wrapper and uninstall the SDK. A custom
 multipart upload route is replaced by the bucket's own upload route unless it
 performs domain work that cannot move into a job.
@@ -241,7 +242,7 @@ Standard `fetch`, so the `resend` package is uninstalled.
 
 ## Env
 
-Pass `envSchema` to `createBunderstack({ env: envSchema })` and read `app.env`
+Pass `envSchema` to `bunderstack({ env: envSchema })` and read `app.env`
 or `ctx.env`. Remove `@t3-oss/env-core` `createEnv()` calls and `dotenv`; Bun
 loads `.env` itself. Server variables must not use the `PUBLIC_` prefix, and
 browser-safe variables must. Declared env appears in the deployment blueprint,
@@ -256,7 +257,7 @@ commit migrations before production:
 
 ```json
 {
-  "bunderstack": { "entry": "src/bunderstack/index.ts" },
+  "bunderstack": { "entry": "src/bunderstack/backend.ts" },
   "scripts": {
     "worker": "bun src/worker.ts",
     "db:generate": "drizzle-kit generate",
@@ -273,14 +274,19 @@ or build output.
 
 ## Test and script ownership
 
-A test or script that constructs its own app owns its lifetime:
+A test or script owns its fixture lexically:
 
 ```ts
-const app = await createApp({ databaseUrl: 'file::memory:' })
-try {
-  await provision(app, { force: true })
-  // ...
-} finally {
-  await app.close()
-}
+await using t = await backend.test({ database: { schema: 'push' } })
+const identity = t.auth.mockSession({
+  id: 'user-1',
+  email: 'dev@example.com',
+  name: 'Developer',
+})
+const client = t.client(identity)
+// ...
 ```
+
+The fixture isolates database, email, storage, realtime, and queue state and is
+disposed at the end of the block. Keep application-specific organization setup
+in a typed helper layered on top of the base user/session auth helper.