@voltro/cli 0.1.0

package/templates/apps/api-data-advanced/database/tenants.entity.ts

@@ -0,0 +1,11 @@
+// Core table — the multi-tenancy boundary. Every row in a `tenant()`-marked
+// table carries `tenantId` pointing here. Unlike `actors`, you DECLARE this
+// one (it's app-shaped — add the fields your org/tenant needs).
+
+import { id, table, text, timestamp } from '@voltro/database'
+
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})

package/templates/apps/api-data-advanced/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/plugin-governance": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/api-data-advanced/queries/authors.withBooks.query.server.ts

@@ -0,0 +1,18 @@
+// EXECUTOR (server-only): returns a query builder with an eager `.with(...)`
+// spec. `.with({ books: true })` attaches each author's books as an array on
+// the row — compiled into ONE SQL roundtrip via the dialect's JSON-aggregation
+// idiom (postgres jsonb_agg, sqlite json_group_array, mysql JSON_ARRAYAGG,
+// mssql FOR JSON PATH). The per-branch `limit`/`orderBy` apply PER author.
+//
+// `authors` carries `tenant()`, so the runtime scopes the root read to the
+// caller's tenant automatically.
+
+import type { AppContext } from '@voltro/runtime'
+import { database } from '../database/index'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) =>
+  database.authors.with({
+    books: { orderBy: [{ column: 'title', direction: 'asc' }], limit: 50 },
+  })
+
+export default execute

package/templates/apps/api-data-advanced/queries/authors.withBooks.query.ts

@@ -0,0 +1,40 @@
+// Authors with their books eager-loaded — demonstrates `.with({ books: true })`.
+//
+// DESCRIPTOR (browser-safe). The `output` shape includes the nested `books`
+// array the eager spec attaches to each author row (the relation registered
+// in authors.relations.ts).
+//
+// `source: ['authors', 'books']` makes the reactive subscription re-run when
+// EITHER table changes — a new book under an author pushes a fresh snapshot.
+// No `cache` here: this is a join-shaped result; we let the live dispatcher
+// keep it fresh rather than cache a snapshot.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+const Book = Schema.Struct({
+  id:       Schema.String,
+  authorId: Schema.String,
+  title:    Schema.String,
+  summary:  Schema.String,
+  genre:    Schema.String,
+  tags:     Schema.Array(Schema.String),
+  slug:     Schema.String,
+  tenantId: Schema.String,
+})
+
+export const authorsWithBooks = defineQuery({
+  name:   'authors.withBooks',
+  source: ['authors', 'books'],
+  input:  Schema.Struct({}),
+  output: Schema.Struct({
+    id:       Schema.String,
+    name:     Schema.String,
+    // `bio` is the `.encrypted()` column — handlers (and the wire) see
+    // plaintext; it's ciphertext only on disk. Nullable in the seed/data.
+    bio:      Schema.NullOr(Schema.String),
+    tenantId: Schema.String,
+    // Eager-loaded relation: each author carries an array of their books.
+    books:    Schema.Array(Book),
+  }),
+})

package/templates/apps/api-data-advanced/queries/books.search.query.server.ts

@@ -0,0 +1,17 @@
+// EXECUTOR (server-only): returns a query builder. `.matching('bookSearch',
+// input.q)` compiles to the dialect's FTS predicate (postgres tsvector,
+// mysql/mariadb MATCH…AGAINST, sqlite FTS5, mssql ranked-LIKE) — resolving
+// the index's covered columns + config from the `bookSearch` declaration on
+// the `books` table.
+//
+// We do NOT add a tenant filter by hand — `books` carries the `tenant()`
+// mixin, so the runtime AND-merges `eq('tenantId', subject.tenantId)` into
+// the predicate automatically.
+
+import type { AppContext } from '@voltro/runtime'
+import { database } from '../database/index'
+
+const execute = (input: { q: string }, _ctx: AppContext) =>
+  database.books.matching('bookSearch', input.q).limit(50)
+
+export default execute

package/templates/apps/api-data-advanced/queries/books.search.query.ts

@@ -0,0 +1,39 @@
+// Full-text book search — demonstrates `.matching(...)` FTS + declarative
+// query result caching.
+//
+// DESCRIPTOR (browser-safe): NO node/database/server imports. The codegen
+// pulls this into rpcGroup.generated.ts, which the web client loads
+// value-level — so it must stay free of server-only modules.
+//
+// `cache` opts into server-side snapshot caching with auto-invalidation: the
+// framework caches the snapshot and drops it whenever a mutation writes any
+// table the query depends on (here, `books`). `scope` is REQUIRED and is a
+// security decision — this query is tenant-filtered (the `tenant()` mixin on
+// `books` AND-merges the caller's tenantId), so it depends on the caller →
+// `scope: 'subject'` (the cache key includes the subject id, no cross-tenant
+// leak). NEVER `global` on a subject-filtered query.
+//
+// The `cache` field is backend-agnostic: this snapshot lives in the
+// in-process `memory` cache by default and in Redis (cross-instance) the
+// moment you flip `CACHE_BACKEND=redis` / app.config `cache: 'redis'` — the
+// query code below does not change. `voltro add redis` wires that for you.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const searchBooks = defineQuery({
+  name:   'books.search',
+  source: 'books',
+  input:  Schema.Struct({ q: Schema.String }),
+  output: Schema.Struct({
+    id:       Schema.String,
+    authorId: Schema.String,
+    title:    Schema.String,
+    summary:  Schema.String,
+    genre:    Schema.String,
+    tags:     Schema.Array(Schema.String),
+    slug:     Schema.String,
+    tenantId: Schema.String,
+  }),
+  cache: { ttl: '30s', swr: '5m', scope: 'subject' },
+})

package/templates/apps/api-data-advanced/seeds/catalog.seed.ts

@@ -0,0 +1,101 @@
+// Boot-lifecycle seed — a couple of authors + their books so the catalog has
+// data the moment `voltro dev` boots. Idempotent via `upsertByUnique`, so
+// re-running on every boot is safe (the fingerprint ledger also dedupes).
+//
+// NOTE: the seed store is the RAW store — it has no authenticated subject, so
+// the `tenant()` auto-fill doesn't fire. We pass `tenantId` explicitly here
+// (and seed the demo tenant row first). The dev AuthMiddleware default resolves
+// the `acme` tenant from the `x-tenant` header, so seeding under `acme` lines
+// up with what queries see out of the box.
+//
+// `bio` is the `.encrypted()` column — we pass plaintext; the store middleware
+// encrypts it on write (requires governancePlugin({ fieldEncryption: true })).
+// `tags` is the `array(text())` column — pass a plain JS array. `slug` is the
+// DB-computed `.generatedAs(...)` column — DON'T pass it; the engine fills it.
+
+import { defineSeed } from '@voltro/database'
+
+const TENANT_ID = 'acme'
+
+export default defineSeed({
+  id:        'catalog',
+  name:      'Library catalog demo data',
+  lifecycle: 'boot',
+  steps: ({ step }) => [
+    step('tenant', async ({ upsertByUnique }) => {
+      await upsertByUnique(
+        'tenants',
+        { id: TENANT_ID },
+        { id: TENANT_ID, name: 'Acme Library', createdAt: new Date() },
+      )
+      return { rowsTouched: 1 }
+    }),
+
+    step('authors-and-books', async ({ upsertByUnique }) => {
+      let touched = 0
+
+      const ursula = await upsertByUnique(
+        'authors',
+        { id: 'author_leguin' },
+        {
+          id:       'author_leguin',
+          name:     'Ursula K. Le Guin',
+          bio:      'American author best known for works of speculative fiction.',
+          tenantId: TENANT_ID,
+        },
+      )
+      touched += 1
+
+      const carl = await upsertByUnique(
+        'authors',
+        { id: 'author_sagan' },
+        {
+          id:       'author_sagan',
+          name:     'Carl Sagan',
+          bio:      'Astronomer and science communicator.',
+          tenantId: TENANT_ID,
+        },
+      )
+      touched += 1
+
+      const books = [
+        {
+          id:       'book_leftHand',
+          authorId: ursula.row['id'] as string,
+          title:    'The Left Hand of Darkness',
+          summary:  'A lone envoy on a frozen world where inhabitants have no fixed sex.',
+          genre:    'sciFi',
+          tags:     ['classic', 'gender', 'winter'],
+          tenantId: TENANT_ID,
+        },
+        {
+          id:       'book_earthsea',
+          authorId: ursula.row['id'] as string,
+          title:    'A Wizard of Earthsea',
+          summary:  'A young mage learns the true cost of power and names.',
+          genre:    'fantasy',
+          tags:     ['magic', 'coming-of-age'],
+          tenantId: TENANT_ID,
+        },
+        {
+          id:       'book_cosmos',
+          authorId: carl.row['id'] as string,
+          title:    'Cosmos',
+          summary:  'A sweeping tour of the universe and our place in it.',
+          genre:    'nonfiction',
+          tags:     ['astronomy', 'science'],
+          tenantId: TENANT_ID,
+        },
+      ]
+
+      for (const book of books) {
+        // `slug` is omitted — the `.generatedAs(...)` STORED column is filled
+        // by the DB engine from `title`.
+        await upsertByUnique('books', { id: book.id }, book)
+        touched += 1
+      }
+
+      return { rowsTouched: touched }
+    }),
+  ],
+})

package/templates/apps/api-data-advanced/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-data-advanced",
+  "kind": "api",
+  "summary": "Advanced schema modeling: *.entity.ts/*.relations.ts split with relations + eager loading, full-text search, dbEnum, array + generated + encrypted columns, and declarative query caching. A small library/catalog (authors + books).",
+  "tags": ["api", "backend", "schema", "relations", "fts", "enum", "encryption", "cache", "advanced"]
+}

package/templates/apps/api-data-advanced/tests/queries.test.ts

@@ -0,0 +1,124 @@
+// Unit tests with `@voltro/testing` — no database, no running server.
+//
+//   1. `authors.withBooks` — the runnable primitive. The executor returns a
+//      `database.authors.with({ books: … })` query BUILDER; we run its
+//      `.descriptor` through `ctx.store.query`, which (a) resolves the eager
+//      `books` relation against the in-memory store and (b) AND-merges the
+//      caller's tenant scope — the exact isolation the runtime applies. So we
+//      assert both eager-loading AND tenant isolation.
+//   2. `books.search` — descriptor-pinned. Its executor calls `.matching(...)`
+//      (dialect FTS: postgres tsvector / mysql MATCH…AGAINST / sqlite FTS5).
+//      The in-memory test store does NOT evaluate `descriptor.fullTextSearch`,
+//      so a run there would silently return UNFILTERED rows — a misleading
+//      assertion. FTS behavior is proven by an integration test against a real
+//      dialect; here we pin the wire contract (name / source / input+output
+//      decode) instead of faking a search.
+//
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect, beforeAll } from 'vitest'
+import { Schema } from 'effect'
+import { registerCoreTables, registerRelations } from '@voltro/database'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database, actors, tenants } from '../database/index' // registers authors / books (tables)
+import { authorsRelations } from '../database/authors.relations'
+import { booksRelations } from '../database/books.relations'
+import authorsWithBooksExecute from '../queries/authors.withBooks.query.server'
+import { searchBooks } from '../queries/books.search.query'
+
+// Two boot steps `voltro dev` runs that the unit harness (`voltro test`) does
+// NOT, both needed for the eager-load walker:
+//   1. registerCoreTables — the audit()/tenant() mixins add createdBy/updatedBy/
+//      tenantId reference() columns whose thunks resolve `actors`/`tenants` via
+//      this registry. `inferForeignKey` walks EVERY reference() column on `books`
+//      to find the FK back to `authors`, so it dereferences those mixin columns —
+//      which throw unless the core tables are registered.
+//   2. registerRelations — `*.relations.ts` files only DEFINE specs; runtime
+//      module discovery (registerDiscoveredRelations) is what REGISTERS them.
+// We do both here — the exact wiring the dev/serve dispatcher does at boot — so
+// `.with({ books })` resolves against the in-memory store just as at runtime.
+beforeAll(() => {
+  registerCoreTables({ actors: () => actors, tenants: () => tenants })
+  registerRelations(authorsRelations)
+  registerRelations(booksRelations)
+})
+
+// `bio` is an `.encrypted()` column. We seed it `null` (the descriptor allows
+// NullOr) — a plaintext/null value passes the read cipher through untouched, so
+// no governance cipher needs wiring for these reads.
+const book = (over: Partial<Record<string, unknown>> & { id: string; authorId: string; tenantId: string }) => ({
+  title:   'Untitled',
+  summary: '',
+  genre:   'fiction',
+  tags:    [] as ReadonlyArray<string>,
+  slug:    'untitled',
+  ...over,
+})
+
+describe('authors.withBooks', () => {
+  it('returns the tenant’s authors with their books eager-loaded', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store: mockStore({
+        authors: [{ id: 'author_1', name: 'Ada', bio: null, tenantId: 'acme' }],
+        books: [
+          book({ id: 'book_1', authorId: 'author_1', tenantId: 'acme', title: 'Analytical Engine' }),
+          book({ id: 'book_2', authorId: 'author_1', tenantId: 'acme', title: 'Notes' }),
+        ],
+      }),
+    })
+
+    const rows = await ctx.store.query(authorsWithBooksExecute({}, ctx).descriptor)
+
+    expect(rows).toHaveLength(1)
+    const ada = rows[0] as { id: string; name: string; books: ReadonlyArray<{ title: string }> }
+    expect(ada.name).toBe('Ada')
+    expect(ada.books.map((b) => b.title).sort()).toEqual(['Analytical Engine', 'Notes'])
+  })
+
+  it('isolates tenants — t2 never sees t1 authors (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store: mockStore({
+        authors: [{ id: 'author_t1', name: 'Secret', bio: null, tenantId: 't1' }],
+        books:   [book({ id: 'book_t1', authorId: 'author_t1', tenantId: 't1' })],
+      }),
+    })
+
+    // Same store, re-scoped to t2 — the runtime AND-merges eq('tenantId','t2'),
+    // so t1's author is invisible.
+    const seenByT2 = await ctx.withTenant('t2', (c) =>
+      c.store.query(authorsWithBooksExecute({}, c).descriptor),
+    )
+    expect(seenByT2).toHaveLength(0)
+  })
+})
+
+describe('books.search (query descriptor)', () => {
+  it('declares the expected wire name + source table', () => {
+    expect(searchBooks.name).toBe('books.search')
+    expect(searchBooks.source).toBe('books')
+  })
+
+  it('accepts a valid { q } input and rejects a malformed one', () => {
+    const decode = Schema.decodeUnknownSync(searchBooks.input)
+    expect(decode({ q: 'effect' })).toEqual({ q: 'effect' })
+    expect(() => decode({})).toThrow() // missing q
+  })
+
+  it('decodes a well-formed book row against the output schema', () => {
+    const decode = Schema.decodeUnknownSync(searchBooks.output)
+    const row = decode({
+      id: 'book_1',
+      authorId: 'author_1',
+      title: 'Effect in Action',
+      summary: 'A book.',
+      genre: 'nonfiction',
+      tags: ['effect', 'ts'],
+      slug: 'effect-in-action',
+      tenantId: 'acme',
+    })
+    expect(row.tags).toEqual(['effect', 'ts'])
+    expect(() => decode({ id: 'book_1' })).toThrow() // missing required fields
+  })
+})

package/templates/apps/api-data-advanced/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/apps/api-durable/README.md

@@ -0,0 +1,81 @@
+# {{projectName}} / {{appName}}
+
+Voltro backend scaffold (template: **api-durable**).
+
+A cohesive **order-fulfillment** domain that exercises the framework's
+entire **durable-execution surface** in one app — durable workflows with
+a human-approval gate, event triggers, a cron schedule, a table
+subscriber, a materialized aggregate, and a run-once startup hook. It
+boots with **zero infrastructure** (`store: 'memory'`).
+
+## Boot
+
+```bash
+pnpm install                                  # at the repo root
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000
+# → ws://localhost:4000/ws
+```
+
+No env or services required. `store: 'memory'` resets on every
+supervised restart — switch `app.config.ts` to `store: 'postgres'`
+(and `docker compose up` from the repo root) when you want durable
+state + multi-instance cluster workflow runners.
+
+## What it demonstrates
+
+| File | Primitive | Role |
+|---|---|---|
+| `app.config.ts`                                | app config        | `store: 'memory'`, zero-infra boot. |
+| `database/schema.ts`                           | schema            | core `actors`/`tenants` + an `orders` table (`tenant()` + `.reactive()`). |
+| `mutations/orders.place.mutation.*`            | mutation          | insert an order, then **emit `order.placed`** post-commit via `ctx.events.emit`. Tenant write-guard. |
+| `triggers/order.placed.trigger.tsx`            | event trigger     | maps event `order.placed` → **start** the `orders.fulfill` workflow. |
+| `workflows/order.fulfill.workflow.*`           | durable workflow  | `step('reserve-stock')` (with **`withCompensation`** saga rollback) → `sleep` → **`awaitSignal('approval')`** human gate → `step('ship')` / mark rejected. |
+| `mutations/orders.approve.mutation.*`          | mutation          | inject the `approval` signal into the parked run via `ctx.workflows.signal(...)`. |
+| `schedules/nightlyReport.cron.tsx`             | schedule          | `defineSchedule` cron `0 2 * * *` (UTC), tallies open orders. |
+| `subscribers/orderChanges.subscribe.ts`        | subscriber        | `defineSubscriber({ table: 'orders', on: 'any' })` post-commit reaction. |
+| `aggregates/orderStats.aggregate.ts`           | aggregate         | `defineAggregate` materialized per-tenant/per-status order roll-up, refreshed every minute. |
+| `startup/warm.startup.tsx`                      | startup hook      | run-once boot hook holding a resource + `onShutdown` teardown. |
+
+## The end-to-end flow
+
+1. **Place an order** → `orders.place` inserts the row and emits
+   `order.placed` *after the transaction commits* (so a rollback never
+   starts a workflow for a non-existent order).
+2. **The trigger fires** → `order.placed.trigger.tsx` starts the durable
+   `orders.fulfill` workflow with `{ orderId, tenantId }`.
+3. **The workflow runs durably** → reserves stock, waits a (short)
+   journaled delay, then **parks on `awaitSignal('approval')`**.
+4. **A human approves** → `orders.approve` derives the workflow's
+   deterministic executionId (from its `idempotencyKey`) and injects the
+   `approval` signal; the parked run wakes (sub-second) and either ships
+   or marks the order rejected.
+
+Meanwhile the **subscriber** logs every `orders` write, the **aggregate**
+keeps a live per-status tally, the **schedule** reports nightly, and the
+**startup hook** holds a process-lifetime resource.
+
+## Try it
+
+Over the rpc surface (e.g. from a `voltro dev` web client, or
+`POST /rpc` / the inspect `invoke` endpoint):
+
+```jsonc
+// 1. place — starts the fulfillment workflow via order.placed
+{ "tag": "orders.place",   "input": { "tenantId": "acme", "customerName": "Ada", "amountCents": 4200 } }
+// 2. approve — wakes the parked awaitSignal('approval') gate
+{ "tag": "orders.approve", "input": { "tenantId": "acme", "orderId": "order_…", "approved": true } }
+```
+
+Watch the run in the dashboard's **Workflows** tab (the `awaitSignal`
+gate also has a "Send signal…" button), and the order's status walk
+`placed → reserved → shipped` live.
+
+## Notes
+
+- All primitives are **auto-discovered by file convention** — nothing is
+  registered in `app.config.ts`.
+- `query` / `mutation` / `action` / `workflow` keep the **descriptor /
+  executor split**: the browser-safe `*.ts` / `*.tsx` descriptor never
+  imports `@voltro/database`, `@voltro/runtime`, `node:*`, or the
+  workflow executor's server graph. The `.server.*` executors do.

package/templates/apps/api-durable/aggregates/orderStats.aggregate.ts

@@ -0,0 +1,49 @@
+// `orderStats` — a materialized aggregate (`*.aggregate.ts`).
+//
+// The framework owns the lifecycle: it runs `build` on the `refresh`
+// interval, stores the rows in an auto-managed backing table, and serves
+// them via `ctx.aggregates.orderStats.read(...)`. Use an aggregate when
+// the SOURCE query is expensive but the RESULT is small + bounded — a
+// per-status order roll-up here.
+//
+// `output` MUST match each returned row's shape. `build` runs as the
+// system (no per-request subject), so it reads across every tenant; the
+// `tenantId` column is part of the grouping so reads stay per-tenant.
+
+import { defineAggregate } from '@voltro/runtime'
+import { column, count } from '@voltro/database'
+import { Schema } from 'effect'
+import { database } from '../database/schema'
+
+export const OrderStat = Schema.Struct({
+  tenantId: Schema.String,
+  status:   Schema.String,
+  orders:   Schema.Number,
+})
+export type OrderStat = Schema.Schema.Type<typeof OrderStat>
+
+export default defineAggregate({
+  name:    'orderStats',
+  refresh: '1m',                 // re-run every minute (interval shorthand)
+  output:  OrderStat,
+  build: async (ctx) => {
+    const rows = await ctx.store.query(
+      database.orders
+        .groupBy(['tenantId', 'status'])
+        // Grouped columns must be EXPLICITLY projected via `column(...)`
+        // in the aggregate spec — they are NOT auto-included (SQL rule:
+        // a selected non-aggregate column must be in GROUP BY).
+        .aggregate({
+          tenantId: column('tenantId'),
+          status:   column('status'),
+          orders:   count(),
+        })
+        .descriptor,
+    )
+    return rows.map((r) => ({
+      tenantId: (r as { tenantId: string }).tenantId,
+      status:   (r as { status: string }).status,
+      orders:   (r as { orders: number }).orders,
+    }))
+  },
+})

package/templates/apps/api-durable/app.config.ts

@@ -0,0 +1,41 @@
+// Backend app for the {{projectName}} project. Read by `voltro dev`.
+//
+// This template demonstrates the framework's DURABLE-EXECUTION surface
+// end-to-end on an order-fulfillment domain. Everything is wired so it
+// boots with ZERO infra:
+//
+//   - `store: 'memory'`  — no docker, no postgres. Workflows run with
+//     the in-process durable engine (replay within one process; swap to
+//     `'postgres'` for multi-instance cluster runners). Memory resets on
+//     every supervised restart, which is fine for kicking the tyres.
+//
+// What's in here (all auto-discovered by file convention — nothing is
+// registered in this config):
+//
+//   mutations/orders.place.mutation.*    — insert an order, then emit a
+//                                          post-commit `order.placed` event
+//   triggers/order.placed.trigger.tsx    — event → start `orders.fulfill`
+//   workflows/order.fulfill.workflow.*   — step → sleep → awaitSignal
+//                                          (human approval) → step
+//   mutations/orders.approve.mutation.*  — inject the `approval` signal
+//   schedules/nightlyReport.cron.tsx     — nightly summary cron
+//   subscribers/orderChanges.subscribe.ts— react to every orders write
+//   aggregates/orderStats.aggregate.ts   — materialized per-status roll-up
+//   startup/warm.startup.tsx             — run-once boot hook
+//
+// Add your own env below; it's validated at boot (fail-fast) and read on
+// the server via `serverEnv` / `getSecret` from '@voltro/env/server'.
+import { defineEnv, envVar } from '@voltro/env'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // Add your own, e.g.:
+  //   STRIPE_KEY: envVar.string({ access: 'secret' }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  env,
+}

package/templates/apps/api-durable/database/schema.ts

@@ -0,0 +1,65 @@
+// Schema for the {{projectName}} backend.
+//
+// Tables are auto-discovered: every exported `table(...)` in this file
+// (or any `*.entity.ts` / `*.schema.ts` file) is registered by
+// `voltro dev` — no manual barrel. `actors` + `tenants` are the
+// framework's core tables: the built-in `audit()` / `tenant()` /
+// `softDelete()` mixins reference them, so they must be declared (the
+// CLI wires them into the mixin registry once it finds them).
+//
+// `orders` carries the `tenant()` mixin (→ tenantId + audit columns,
+// auto-stamped by the runtime) and `.reactive()` so the `orderChanges`
+// subscriber + any live subscription wake on every write.
+
+import {
+  databaseHandle,
+  id,
+  integer,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// ---------- Core tables (required by the audit / tenant mixins) ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})
+
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})
+
+// ---------- Application table — order-fulfillment domain ----------
+
+export const orders = table('orders', {
+  id:          id({ prefix: 'order' }),
+  // The fulfillment lifecycle. `oneOf` narrows the row type to the
+  // literal union AND emits a cross-dialect CHECK constraint.
+  status:      text().oneOf([
+    'placed',     // created, fulfillment workflow kicked off
+    'reserved',   // stock reserved (workflow step 1)
+    'approved',   // human approval signal accepted
+    'rejected',   // human approval signal rejected
+    'shipped',    // shipped (workflow final step)
+  ]).default('placed'),
+  customerName: text(),
+  amountCents:  integer(),
+})
+  // tenant() pulls audit() transitively → adds tenantId + createdAt /
+  // updatedAt / createdBy / updatedBy (auto-stamped by the runtime).
+  .with(tenant())
+  // Opt into the matcher engine: the `orderChanges` subscriber + any
+  // live subscription against `orders` fire on every mutation write.
+  .reactive()
+
+export type Order = InferRow<typeof orders>
+
+export const database = databaseHandle({ actors, tenants, orders })