@voltro/cli 0.1.0

package/templates/apps/api-backend-storage/actions/uploadDocument.action.server.ts

@@ -0,0 +1,21 @@
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { StorageService } from '@voltro/plugin-storage'
+
+const execute = (input: { bytesBase64: string; contentType: string; filename: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const storage = yield* StorageService
+    const bytes = new Uint8Array(Buffer.from(input.bytesBase64, 'base64'))
+    const ref = yield* storage.put({
+      bytes,
+      contentType: input.contentType,
+      visibility: 'private',
+      ownerId: ctx.request.subject.id,
+      tenantId: ctx.request.subject.tenantId,
+      key: `documents/${ctx.request.subject.id ?? 'anon'}/${input.filename}`,
+      access: [{ roles: ['admin'] }, { tenant: true }],
+    })
+    return { id: ref.id }
+  })
+
+export default execute

package/templates/apps/api-backend-storage/actions/uploadDocument.action.ts

@@ -0,0 +1,20 @@
+// `storage.uploadDocument` — stores a PRIVATE document. The owner is
+// always allowed; this policy additionally grants the `admin` role and
+// same-tenant subjects. Fetch the bytes via the plugin's access-checked
+// `storage.mintUrl` route, or grant a specific user/group from the
+// dashboard's Storage tab.
+
+import { Schema } from 'effect'
+import { defineAction } from '@voltro/protocol'
+
+export const uploadDocument = defineAction({
+  name: 'storage.uploadDocument',
+  input: Schema.Struct({
+    bytesBase64: Schema.String,
+    contentType: Schema.String,
+    filename: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+  }),
+})

package/templates/apps/api-backend-storage/app.config.ts

@@ -0,0 +1,38 @@
+// Backend app for the {{projectName}} project. Read by `voltro dev`.
+//
+// `store: 'memory'` is the dev-friendly default — fast startup, no
+// docker. Switch to `'postgres'` when you wire `docker compose up`
+// from the repo root (file metadata + grants persist there).
+//
+// This variant ships file storage out of the box via
+// `@voltro/plugin-storage`. The `memory` provider keeps blobs in-process
+// (zero-config, dev only) — swap to `'s3'` / `'minio'` (+ S3_* env) for
+// real object storage, or `'filesystem'` for on-disk dev.
+//
+//   - PUBLIC objects are served direct from the bucket/CDN (set
+//     `cdnBaseUrl`); the app's serve route is only a dev fallback.
+//   - PRIVATE objects are gated by an access policy (owner / roles /
+//     groups / scopes / tenant / api-key / password / custom guard) PLUS
+//     per-object grants you manage from the dashboard's Storage tab.
+import { defineEnv, envVar } from '@voltro/env'
+import { storagePlugin } from '@voltro/plugin-storage'
+
+// Typed environment — declare your env once; it's validated at boot (fail-fast)
+// and read on the server via `serverEnv` / `getSecret` from '@voltro/env/server'.
+// `access` is required: 'public' (browser-safe) or 'secret' (server-only, never
+// bundled). Run `voltro env` to see the manifest. See the Environment docs.
+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:  '{{projectNamePascal}}{{appNamePascal}}',
+  store: 'memory' as const,
+  env,
+  plugins: [
+    storagePlugin({ provider: 'memory' }),
+  ],
+}

package/templates/apps/api-backend-storage/database/schema.ts

@@ -0,0 +1,57 @@
+// 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).
+//
+// Add the `tenant()` mixin to a table to make it tenant-scoped — the
+// runtime AND-merges `eq('tenantId', subject.tenantId)` into every
+// subscription predicate, so cross-tenant reads can't leak.
+
+import {
+  boolean,
+  databaseHandle,
+  id,
+  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 tables — rename / replace with your own ----------
+
+export const notes = table('notes', {
+  id:    id({ prefix: 'note' }),
+  title: text(),
+  body:  text(),
+  done:  boolean().default(false),
+})
+  // tenant() pulls audit() transitively → adds tenantId + createdAt /
+  // updatedAt / createdBy / updatedBy (auto-stamped by the runtime).
+  .with(tenant())
+  // Opt into the matcher engine: subscriptions against `notes` get a
+  // fresh snapshot/delta whenever a mutation writes the table.
+  .reactive()
+
+export type Note = InferRow<typeof notes>
+
+export const database = databaseHandle({ actors, tenants, notes })

package/templates/apps/api-backend-storage/mutations/notes.create.mutation.server.ts

@@ -0,0 +1,19 @@
+import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (
+  input: { tenantId: string; title: string; body: string },
+  ctx: AppContext,
+) => {
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+  // Framework auto-injects a `note_…` id from the table's id() decl.
+  return ctx.store.insert('notes', {
+    title: input.title,
+    body: input.body,
+    done: false,
+    tenantId: input.tenantId,
+    createdAt: new Date(),
+  })
+}
+
+export default execute

package/templates/apps/api-backend-storage/mutations/notes.create.mutation.ts

@@ -0,0 +1,37 @@
+// Creates a note. The handler's `assertOwnTenant` guard rejects
+// cross-tenant spoofing — input.tenantId MUST match the resolved
+// subject's tenantId, else the rpc layer surfaces a typed
+// `TenantMismatch` error.
+
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { Schema } from 'effect'
+
+export const createNote = defineMutation({
+  name: 'notes.create',
+  target: {
+    table: 'notes',
+    op: 'insert',
+    shape: (input: { tenantId: string; title: string; body: string }) => ({
+      title: input.title,
+      body: input.body,
+      done: false,
+      tenantId: input.tenantId,
+      createdAt: new Date(),
+    }),
+  },
+  input: Schema.Struct({
+    tenantId: Schema.String,
+    title: Schema.NonEmptyString,
+    body: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    done: Schema.Boolean,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+  error: TenantMismatch,
+})

package/templates/apps/api-backend-storage/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "dependencies": {
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/plugin-storage": "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-backend-storage/queries/notes.query.server.ts

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'notes' as const,
+    predicate: undefined,
+    order: [{ column: 'createdAt' as const, direction: 'desc' as const }],
+    take: 100,
+    skip: undefined,
+    projection: undefined,
+  },
+})
+
+export default execute

package/templates/apps/api-backend-storage/queries/notes.query.ts

@@ -0,0 +1,20 @@
+// Streaming subscription: every change to `notes` for the caller's
+// tenant lands as a delta. The runtime AND-merges tenant scope into
+// the predicate via the `tenant()` mixin on the table — no manual
+// `eq('tenantId', ...)` needed in the handler.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name: 'notes.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    done: Schema.Boolean,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

package/templates/apps/api-backend-storage/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-backend-storage",
+  "kind": "api",
+  "summary": "Voltro backend with file storage wired: @voltro/plugin-storage with public (CDN-direct) + private (policy + per-object grants) objects, plus upload examples you browse/share from the dashboard. Same minimal base as api-backend.",
+  "tags": ["api", "backend", "storage", "files", "uploads", "starter"]
+}

package/templates/apps/api-backend-storage/tests/notes.create.test.ts

@@ -0,0 +1,50 @@
+// Unit test with `@voltro/testing` — no database, no running server. Importing
+// `../database/schema` registers the `notes` / `actors` / `tenants` tables
+// globally, so `makeTestContext` auto-wires them into the in-memory store.
+// `ctx.store` is the SAME mixin-wrapped store the handler gets in production,
+// so tenant auto-scoping + audit auto-fill behave exactly as at runtime.
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema' // registers notes / actors / tenants
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import createNote from '../mutations/notes.create.mutation.server'
+
+describe('notes.create', () => {
+  it('inserts a note stamped to the caller tenant', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    const row = await createNote({ tenantId: 'acme', title: 'Hello', body: 'World' }, ctx)
+
+    expect(row['title']).toBe('Hello')
+    expect(row['tenantId']).toBe('acme')  // assertOwnTenant let it through + stamped
+    expect(row['done']).toBe(false)
+    expect(String(row['id'])).toMatch(/^note_/) // TypeID auto-injected from id()
+  })
+
+  it('rejects a cross-tenant spoof — input.tenantId must match the subject', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    await expect(
+      createNote({ tenantId: 'other-tenant', title: 'spoof', body: '' }, ctx),
+    ).rejects.toBeInstanceOf(TenantMismatch)
+  })
+
+  it('isolates tenants — t2 never sees t1 rows (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ notes: [] }),
+    })
+    await createNote({ tenantId: 't1', title: 'secret', body: '' }, ctx)
+
+    // Re-scope the SAME store to a different tenant — the real WHERE filter
+    // (eq tenantId) hides t1's row from t2.
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.notes.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+})

package/templates/apps/api-backend-storage/tsconfig.json

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

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

@@ -0,0 +1,17 @@
+# DEV-ONLY environment for the {{projectName}} api.
+#
+# `voltro dev` loads this file into the process environment at boot, BEFORE the
+# env-validation gate and BEFORE plugins activate. That's how the governance
+# plugin's field-encryption cipher resolves its key (it reads the Secrets-
+# Resolver, i.e. process.env — a typed-env `default` would NOT reach it).
+#
+# ⚠️  The key below is a PUBLIC, DEV-ONLY placeholder shipped with the template.
+#     NEVER use it in production. Generate a real one and set it in your
+#     deployment's environment / secrets manager:
+#
+#         openssl rand -hex 32
+#
+#     Lose the key → lose the data (AES-256-GCM fails closed, never silent
+#     corruption). Rotating it makes every existing `.encrypted()` value
+#     unreadable.
+VOLTRO_FIELD_ENCRYPTION_KEY=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff

package/templates/apps/api-data-advanced/README.md

@@ -0,0 +1,88 @@
+# {{projectName}} / {{appName}}
+
+Voltro backend scaffold (template: **api-data-advanced**).
+
+A small **library/catalog** (authors + books) that closes the advanced
+schema-DSL gaps — features that are documented but shown in no other
+template: the `*.entity.ts` / `*.relations.ts` split with eager loading,
+full-text search, `dbEnum`, array / generated / encrypted columns, and
+declarative query caching.
+
+## Boot
+
+```bash
+pnpm install                # at the repo root
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000
+# → ws://localhost:4000/ws
+```
+
+Boots with **zero setup**: the `.encrypted()` `authors.bio` column needs an
+AES-256-GCM key, and the shipped `.env` supplies a **DEV-ONLY** placeholder so
+`voltro dev` comes up immediately. `voltro dev` then auto-migrates the schema
+and runs the boot seed, so the catalog has two authors + three books right away.
+
+> ⚠️ **Before production**, replace the key in `.env` with a real one and move
+> it into your deployment's secret store — never ship the placeholder. Generate
+> one with `openssl rand -hex 32`. **Lose the key → lose the ciphertext** (GCM
+> fails closed); **rotating it** makes every existing `.encrypted()` value
+> unreadable.
+
+## Environment
+
+| Var | Access | Why |
+|---|---|---|
+| `VOLTRO_FIELD_ENCRYPTION_KEY` | secret | AES-256-GCM key for the `.encrypted()` `authors.bio` column (32-byte hex). `governancePlugin({ fieldEncryption: true })` resolves it through the **Secrets-Resolver** — i.e. the process environment, which the shipped `.env` populates (a `defineEnv` `default` would NOT reach the cipher). Boot fails loud if an `.encrypted()` column exists but the cipher can't resolve a key. |
+| `LOG_LEVEL` | public | `debug \| info \| warn \| error` (default `info`). |
+
+## What this demonstrates
+
+| Feature | Where | Notes |
+|---|---|---|
+| `*.entity.ts` / `*.relations.ts` split | `database/*.entity.ts`, `database/*.relations.ts` | One table per file; relations declared OUTSIDE the table descriptor. |
+| `relations()` + eager `.with()` | `authors.relations.ts`, `books.relations.ts`, `queries/authors.withBooks.query.server.ts` | `database.authors.with({ books: true })` → each author carries a `books[]` array in ONE SQL roundtrip. |
+| Full-text search | `books.entity.ts` (`.fullTextIndex('bookSearch', ['title','summary'])`) + `queries/books.search.query.server.ts` (`.matching('bookSearch', q)`) | One declaration, three backends (postgres tsvector, mysql/mariadb FULLTEXT, sqlite FTS5, mssql ranked-LIKE). |
+| `dbEnum(...)` | `books.entity.ts` (`bookGenre`) | Native `CREATE TYPE … ENUM` on postgres; native `ENUM(...)` on mysql/mariadb; CHECK fallback elsewhere. |
+| `array(text())` | `books.entity.ts` (`tags`) | Native `text[]` on postgres; JSON-string codec on other dialects — the API stays "a JS array". |
+| `.generatedAs(expr, { stored })` | `books.entity.ts` (`slug`) | DB-computed, persisted, indexable column derived from `title`. Don't write it — the engine fills it. |
+| `.encrypted()` | `authors.entity.ts` (`bio`) | Transparent AES-256-GCM at rest via `governancePlugin({ fieldEncryption: true })` in `app.config.ts`. |
+| Declarative query caching | `queries/books.search.query.ts` (`cache: { ttl, swr, scope }`) | Server snapshot cache with auto-invalidation on writes to `books`; `scope: 'subject'` because the query is tenant-filtered. |
+| Boot seed | `seeds/catalog.seed.ts` | Idempotent `upsertByUnique` authors + books. |
+
+## Files
+
+```
+app.config.ts                          governancePlugin({ fieldEncryption: true })
+database/
+  actors.entity.ts                     core audit-subject table
+  tenants.entity.ts                    core tenant boundary
+  authors.entity.ts                    name + .encrypted() bio
+  books.entity.ts                      dbEnum genre, array tags, generated slug, FTS index
+  authors.relations.ts                 author → many books
+  books.relations.ts                   book → one author
+  index.ts                             databaseHandle({...}) + relation registration
+queries/
+  books.search.query.ts(.server)       FTS via .matching(...) + cache
+  authors.withBooks.query.ts(.server)  eager-load via .with({ books: true })
+seeds/
+  catalog.seed.ts                      demo authors + books
+```
+
+## Try it
+
+The dev AuthMiddleware resolves the `acme` tenant from the `x-tenant`
+header (the seed writes under `acme`). Subscribe to the queries from a
+web app via `useSubscription('app', 'books.search', { q: 'magic' })` and
+`useSubscription('app', 'authors.withBooks')`, or invoke them over HTTP
+through `POST /_voltro/inspect/invoke` for a one-shot snapshot.
+
+## Switching to a real SQL store
+
+`store: 'memory'` keeps boot zero-infra. Switch `app.config.ts` to
+`store: 'postgres'` (and `docker compose up` a postgres) to see the
+native DDL the migrator emits for each feature — `CREATE TYPE`,
+`text[]`, the STORED generated column, and the tsvector + GIN FTS index.
+The handler code is unchanged across every dialect.
+
+Drop more `*.entity.ts` / `*.query.ts` / `*.mutation.ts` / `*.action.ts`
+files anywhere in this tree — discovery is by file convention.

package/templates/apps/api-data-advanced/app.config.ts

@@ -0,0 +1,56 @@
+// Backend app for the {{projectName}} project. Read by `voltro dev`.
+//
+// This template demonstrates the framework's ADVANCED schema-DSL surface
+// on a small library/catalog domain (authors + books):
+//   - the *.entity.ts / *.relations.ts split (one table per file),
+//   - relations() + eager `.with({ books: true })` loading,
+//   - full-text search via `.fullTextIndex(...)` + `.matching(...)`,
+//   - `dbEnum(...)` native enum columns,
+//   - `array(text())` columns + a stored `.generatedAs(...)` column,
+//   - `.encrypted()` field encryption (AES-256-GCM at rest),
+//   - declarative query result caching (`cache` on `defineQuery`).
+//
+// `store: 'memory'` keeps boot zero-infra (no docker). The schema DSL is
+// identical across every SQL backend — switch to `'postgres'` to see the
+// native ENUM / tsvector-FTS / text[] DDL the migrator emits. On `memory`
+// the same features run through the in-process store (FTS degrades to a
+// substring scan, arrays round-trip as JS arrays, encryption still applies).
+//
+// `governancePlugin({ fieldEncryption: true })` registers the AES-256-GCM
+// cipher that makes the `authors.bio` `.encrypted()` column work — without
+// it, boot fails loud ("an `.encrypted()` column exists but no cipher is
+// registered"). The key is read from the secret `VOLTRO_FIELD_ENCRYPTION_KEY`
+// via the Secrets-Resolver (which reads the process environment). The shipped
+// `.env` carries a DEV-ONLY key so the template boots out of the box — see the
+// README to generate a real one for production. Lose the key → lose the
+// ciphertext (GCM fails closed).
+import { defineEnv, envVar } from '@voltro/env'
+import { governancePlugin } from '@voltro/plugin-governance'
+
+// Typed environment — declare your env once; it's validated at boot (fail-fast)
+// and read on the server via `serverEnv` / `getSecret` from '@voltro/env/server'.
+// `access` is required: 'public' (browser-safe) or 'secret' (server-only, never
+// bundled). Run `voltro env` to see the manifest. See the Environment docs.
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // The 32-byte hex key the field-encryption cipher uses. NO `default` here on
+  // purpose: governancePlugin resolves it through the Secrets-Resolver (which
+  // reads `process.env`), NOT this typed-env default — a default would satisfy
+  // the boot gate while the cipher still failed to resolve. The shipped `.env`
+  // supplies a DEV-ONLY value so `voltro dev` boots; for production generate a
+  // real key (`openssl rand -hex 32`) and set VOLTRO_FIELD_ENCRYPTION_KEY in
+  // the environment. Lose the key → lose the ciphertext (GCM fails closed).
+  VOLTRO_FIELD_ENCRYPTION_KEY: envVar.string({ access: 'secret' }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  env,
+  plugins: [
+    // Registers the cipher for `.encrypted()` columns. Key from the secret
+    // VOLTRO_FIELD_ENCRYPTION_KEY (or pass { fieldEncryption: { secretKey } }).
+    governancePlugin({ fieldEncryption: true }),
+  ],
+}

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

@@ -0,0 +1,14 @@
+// Core table — the universal audit subject (whoever/whatever initiated a
+// write: a user, a service account, an API key, or the system). Every
+// `createdBy` / `updatedBy` / `deletedBy` references it, so the `audit()` /
+// `tenant()` / `softDelete()` mixins require it to exist. Declared one-per-
+// file with the `*.entity.ts` convention — the CLI auto-discovers it.
+
+import { id, table, text, timestamp } from '@voltro/database'
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})

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

@@ -0,0 +1,30 @@
+// Authors — demonstrates `.encrypted()` field encryption.
+//
+// `bio` is flagged `.encrypted()`: the store middleware transparently
+// encrypts it on write (AES-256-GCM) and decrypts on read, so handlers
+// always see plaintext while the column stores an opaque `enc:v1:…` string
+// on disk on every dialect.
+//
+// ‼️ This column ONLY works because `app.config.ts` wires
+//    `governancePlugin({ fieldEncryption: true })`, which registers the
+//    cipher (key from the secret VOLTRO_FIELD_ENCRYPTION_KEY). Boot fails
+//    loud if an `.encrypted()` column exists but no cipher is registered.
+//
+// An `.encrypted()` column is ciphertext on disk — you CANNOT filter or
+// sort by its plaintext in SQL. Encrypt only what you read back whole
+// (PII, tokens, notes). A book search never touches `bio`, so this is safe.
+
+import { id, table, text } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy/mixin'
+
+export const authors = table('authors', {
+  id:   id({ prefix: 'author' }),
+  name: text(),
+  // Encrypted at rest. Requires governancePlugin({ fieldEncryption: true }).
+  bio:  text().encrypted().nullable(),
+})
+  // tenant() pulls audit() transitively → adds tenantId + createdAt /
+  // updatedAt / createdBy / updatedBy (auto-stamped by the runtime).
+  .with(tenant())
+  // Opt into the matcher engine so subscriptions react to writes.
+  .reactive()

package/templates/apps/api-data-advanced/database/authors.relations.ts

@@ -0,0 +1,15 @@
+// Relations are declared OUTSIDE the table descriptor, in a `*.relations.ts`
+// file (convention). The framework registers them at boot; the query
+// builder's `.with({ books: true })` chain uses them to eager-load.
+//
+// An author has MANY books. The `foreignKey` auto-derives because exactly
+// one `reference()` column on `books` (`authorId`) points back at `authors`
+// — no explicit override needed.
+
+import { relations } from '@voltro/database'
+import { authors } from './authors.entity'
+import { books } from './books.entity'
+
+export const authorsRelations = relations(authors, ({ many }) => ({
+  books: many(books),
+}))

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

@@ -0,0 +1,59 @@
+// Books — the centrepiece of the advanced schema-DSL tour. One table,
+// five specialized column features:
+//
+//   - `authorId`  → reference(() => authors)  (FK + auto B-tree index)
+//   - `genre`     → dbEnum(...).column()      (native ENUM type)
+//   - `tags`      → array(text())             (native text[] on postgres,
+//                                              JSON fallback elsewhere)
+//   - `slug`      → text().generatedAs(..., { stored: true })
+//                                             (DB-computed, persisted, indexable)
+//   - `.fullTextIndex('bookSearch', [...])`   (FTS over title + summary;
+//                                              query with `.matching(...)`)
+
+import { array, dbEnum, id, reference, table, text } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy/mixin'
+import { authors } from './authors.entity'
+
+// A native ENUM type. Declared once (module-level) so it's a reusable handle:
+//   - postgres → CREATE TYPE book_genre AS ENUM (...). ADD VALUE is O(1).
+//   - mysql / mariadb → native ENUM('fiction', ...) column.
+//   - mssql / sqlite → NVARCHAR / TEXT + CHECK fallback.
+// Distinct from `text().oneOf([...])`, which is a CROSS-DIALECT CHECK on every
+// backend — reach for `dbEnum` on postgres-primary apps for the cheap
+// ADD-VALUE migration. The `as const` is required for the literal-union type.
+export const bookGenre = dbEnum('book_genre', [
+  'fiction',
+  'nonfiction',
+  'fantasy',
+  'sciFi',
+  'mystery',
+  'biography',
+] as const)
+
+export const books = table('books', {
+  id:       id({ prefix: 'book' }),
+  authorId: reference(() => authors),                       // FK → authors, auto-indexed
+  title:    text(),
+  summary:  text(),
+  // Native ENUM column, defaulting to 'fiction'.
+  genre:    bookGenre.column().default('fiction'),
+  // Array column → `text[]` on postgres; JSON-string codec elsewhere. The
+  // user-facing API stays "I get back a JS string array" on every dialect.
+  tags:     array(text()).default([]),
+  // DB-computed STORED column — a URL-friendly slug derived from `title` in
+  // the DB engine on INSERT + UPDATE. `stored: true` persists it on disk so
+  // it's indexable. Same-row columns only (it can't see subject/tenant —
+  // that's what `.computed(row => ...)` is for). The expression is raw SQL
+  // emitted verbatim, so it must stay portable (double-quoted identifier).
+  slug:     text().generatedAs(`lower("title")`, { stored: true }),
+})
+  // Full-text search index over title + summary. One declaration, three
+  // backends (postgres tsvector+GIN, mysql/mariadb FULLTEXT, sqlite FTS5;
+  // mssql ranked-LIKE fallback). Query it with `.matching('bookSearch', q)`.
+  .fullTextIndex('bookSearch', ['title', 'summary'], {
+    config:  'english',
+    weights: { title: 'A', summary: 'B' },
+  })
+  // tenant() pulls audit() transitively (tenantId + audit columns).
+  .with(tenant())
+  .reactive()

package/templates/apps/api-data-advanced/database/books.relations.ts

@@ -0,0 +1,10 @@
+// A book belongs to ONE author. The inverse of authors→books.
+// `one(authors)` resolves the `authorId` FK automatically.
+
+import { relations } from '@voltro/database'
+import { authors } from './authors.entity'
+import { books } from './books.entity'
+
+export const booksRelations = relations(books, ({ one }) => ({
+  author: one(authors),
+}))

package/templates/apps/api-data-advanced/database/index.ts

@@ -0,0 +1,23 @@
+// The database handle + barrel. Imports every entity + exports
+// `databaseHandle({...})`. Tables are auto-discovered by the CLI from the
+// `*.entity.ts` files; the handle is what server code queries through
+// (`database.books.matching(...)`, `database.authors.with({ books: true })`).
+//
+// Importing the `*.relations.ts` files here is what registers the relations
+// at boot so the eager-load `.with(...)` walker can resolve them.
+
+import { databaseHandle, type InferRow } from '@voltro/database'
+import { actors } from './actors.entity'
+import { tenants } from './tenants.entity'
+import { authors } from './authors.entity'
+import { books } from './books.entity'
+
+// Register relations (side-effecting imports).
+import './authors.relations'
+import './books.relations'
+
+export { actors, tenants, authors, books }
+export type Author = InferRow<typeof authors>
+export type Book = InferRow<typeof books>
+
+export const database = databaseHandle({ actors, tenants, authors, books })