@voltro/cli 0.1.0

package/templates/apps/api-saas/mutations/projects.create.mutation.ts

@@ -0,0 +1,18 @@
+// Create a project — the SaaS bundle in ONE handler. The billing plugin
+// auto-merges its typed `EntitlementExceeded` (+ `BillingError`) into this
+// procedure's wire-error union, so the client decodes the over-quota failure
+// typed WITHOUT a manual `error:` declaration here.
+
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createProject = defineMutation({
+  name:   'projects.create',
+  target: { table: 'projects', op: 'insert' },
+  input:  Schema.Struct({ name: Schema.NonEmptyString }),
+  output: Schema.Struct({
+    id:       Schema.String,
+    name:     Schema.String,
+    tenantId: Schema.String,
+  }),
+})

package/templates/apps/api-saas/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "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/plugin-analytics-postgres": "0.1.0",
+    "@voltro/plugin-billing": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/plugin-notifications": "0.1.0",
+    "@voltro/plugin-presence": "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-saas/queries/projects.list.query.server.ts

@@ -0,0 +1,7 @@
+import type { AppContext } from '@voltro/runtime'
+import { database } from '../database/schema'
+
+const route = (_input: Record<string, never>, _ctx: AppContext) =>
+  database.projects.orderBy('createdAt', 'desc').limit(100)
+
+export default route

package/templates/apps/api-saas/queries/projects.list.query.ts

@@ -0,0 +1,18 @@
+// Reactive list of the tenant's projects. The runtime AND-merges
+// `eq('tenantId', subject.tenantId)` (the table carries `tenant()`), so this
+// never leaks across tenants — no manual filter needed.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listProjects = defineQuery({
+  name:   'projects.list',
+  source: 'projects',
+  input:  Schema.Struct({}),
+  output: Schema.Array(Schema.Struct({
+    id:        Schema.String,
+    name:      Schema.String,
+    tenantId:  Schema.String,
+    createdAt: Schema.Date,
+  })),
+})

package/templates/apps/api-saas/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-saas",
+  "kind": "api",
+  "summary": "The SaaS plugin bundle in one domain: billing entitlements (quota gate), in-app + console notifications, analytics events, and live presence — wired turnkey. One projects.create mutation exercises billing + analytics + notifications together.",
+  "tags": ["api", "saas", "billing", "notifications", "analytics", "presence", "plugins"]
+}

package/templates/apps/api-saas/tests/projects.create.test.ts

@@ -0,0 +1,47 @@
+// Unit test with `@voltro/testing` — no database, no running server, no billing
+// backend. The `projects.create` executor runs in Effect mode and `yield*`s the
+// billing (requireEntitlement), analytics, and notifications plugin services —
+// those live in the per-request plugin layer, which the unit harness does NOT
+// wire, so we do not fake them. Instead we PIN the descriptor's wire contract
+// (the shape the client codegen depends on) and prove the tenant() scoping that
+// keeps one SaaS tenant's projects invisible to another — the headline feature.
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { Schema } from 'effect'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema'   // registers projects / actors / tenants
+import { createProject } from '../mutations/projects.create.mutation'
+
+describe('projects.create descriptor', () => {
+  it('decodes a valid input and rejects a blank name', () => {
+    const decode = Schema.decodeUnknownSync(createProject.input)
+    expect(decode({ name: 'Acme App' })).toEqual({ name: 'Acme App' })
+    // `name: Schema.NonEmptyString` — an empty string fails the wire decode.
+    expect(() => decode({ name: '' })).toThrow()
+  })
+
+  it('encodes the output shape the client expects', () => {
+    const encode = Schema.encodeUnknownSync(createProject.output)
+    const wire = encode({ id: 'proj_1', name: 'Acme App', tenantId: 'acme' })
+    expect(wire).toEqual({ id: 'proj_1', name: 'Acme App', tenantId: 'acme' })
+  })
+})
+
+describe('projects tenant isolation', () => {
+  it('t2 never sees t1 projects (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ projects: [] }),
+    })
+    // Raw insert through the mixin store — tenant() auto-stamps tenantId=t1.
+    const row = await ctx.store.insert('projects', { name: 'secret' })
+    expect(row['tenantId']).toBe('t1')
+
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.projects.descriptor))
+    expect(seenByT2).toHaveLength(0)
+    // …and t1 still sees its own row.
+    const seenByT1 = await ctx.store.query(database.projects.descriptor)
+    expect(seenByT1).toHaveLength(1)
+  })
+})

package/templates/apps/api-saas/tsconfig.json

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

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

@@ -0,0 +1,68 @@
+# {{projectName}} / {{appName}}
+
+Voltro API scaffold (template: **api-search**) — full-text search that stays
+in sync with your tables, powered by `@voltro/plugin-search`.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000  (store: memory — zero infra)
+```
+
+The boot log shows `search: backfilled 4 article(s) into the index` — the
+demo seed's rows, indexed and ready to search.
+
+## What this shows
+
+- **Index stays in sync, automatically** — `searchPlugin` taps the post-commit
+  ChangeEvent stream: every `articles` insert/update upserts its doc into the
+  index, every delete removes it. No app code — create an article and it's
+  searchable on the next request.
+- **Tenant-scoped results** — the index spec's `tenantField: 'tenantId'` makes
+  the synthesized `search.query` rpc auto-filter to the caller's tenant. One
+  tenant can never see another's hits.
+- **Backfill existing rows** — `startup/searchBackfill.startup.tsx` calls
+  `backfillIndex(...)` on boot to seed the index from rows already in the table
+  (the seed data, or every row after a restart / engine switch).
+- **One config line to go to production** — `lib/search.ts` uses
+  `memoryBackend()` (in-process, zero infra). Swap it for `{ engine:
+  'typesense' | 'meilisearch' | 'algolia', url, apiKey }` and nothing else
+  changes — the indexing + query code is identical.
+
+## Try it
+
+The plugin synthesizes a `search.query` rpc. Hit it over the inspect surface:
+
+```bash
+# Search the seeded articles (tenant 'acme' via the x-tenant default):
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"search.query","input":{"index":"articles","q":"tenant"}}'
+
+# Create an article — it's indexed on commit, then searchable:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"articles.create","input":{"tenantId":"acme","title":"Reactive queries","body":"Subscriptions push deltas live.","tag":"guide"}}'
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"search.query","input":{"index":"articles","q":"reactive"}}'
+```
+
+## On the web side
+
+A browser hook ships at `@voltro/plugin-search/web`:
+
+```tsx
+import { useSearch } from '@voltro/plugin-search/web'
+const { results, search, pending } = useSearch('articles')
+// search('reactive') → results auto-scoped to the signed-in tenant
+```
+
+## Files
+
+- `lib/search.ts` — the shared backend instance + the `articles` index spec.
+- `app.config.ts` — wires `searchPlugin({ backend, indexes })`.
+- `database/schema.ts` — the `articles` table (tenant-scoped, reactive).
+- `mutations/articles.create.*` — writes that auto-index via the tap.
+- `queries/articles.list.*` — a live list to sit next to the search box.
+- `seeds/articles.seed.ts` — demo data.
+- `startup/searchBackfill.startup.tsx` — backfills the index on boot.

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

@@ -0,0 +1,31 @@
+// Search backend for the {{projectName}} project — full-text search over a
+// table, kept in sync automatically.
+//
+// `searchPlugin` taps the post-commit ChangeEvent stream: every insert/update
+// to a source table upserts its doc into the index, every delete removes it —
+// no app code. The synthesized `search.query` rpc returns hits, auto-filtered
+// to the caller's tenant. `store: 'memory'` keeps this zero-infra for dev.
+import { defineEnv, envVar } from '@voltro/env'
+import { searchPlugin } from '@voltro/plugin-search'
+import { searchBackend, articlesIndex } from './lib/search'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  plugins: [
+    // `backend: searchBackend` is the SAME instance lib/search.ts shares with
+    // the boot startup's backfill. Swap it for a vendor engine in lib/search.ts
+    // ({ engine: 'typesense' | 'meilisearch' | 'algolia', url, apiKey }) for
+    // prod — the indexing + query code stays identical.
+    searchPlugin({
+      backend: searchBackend,
+      indexes: { articles: articlesIndex },
+    }),
+  ],
+  env,
+}

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

@@ -0,0 +1,47 @@
+// Schema for the {{projectName}} search backend.
+//
+// `articles` is the searchable domain. The search plugin mirrors every
+// write to it into a search index (see app.config.ts + lib/search.ts); the
+// table itself is an ordinary `tenant()`-scoped reactive table.
+
+import {
+  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 table ----------
+
+export const articles = table('articles', {
+  id:    id({ prefix: 'art' }),
+  title: text(),
+  body:  text(),
+  tag:   text(),           // a coarse category — also a search filter
+})
+  // tenant() adds tenantId + audit columns (auto-stamped). The search
+  // index's `tenantField: 'tenantId'` scopes every query to the caller.
+  .with(tenant())
+  .reactive()
+
+export type Article = InferRow<typeof articles>
+
+export const database = databaseHandle({ actors, tenants, articles })

package/templates/apps/api-search/lib/search.ts

@@ -0,0 +1,27 @@
+// The search wiring, shared so app.config (the plugin) and the boot startup
+// (the backfill) use the SAME backend instance + index spec.
+//
+// `memoryBackend()` is an in-process index — zero infra, perfect for dev. It's
+// a closure over a Map, so two `memoryBackend()` calls would be two SEPARATE
+// indexes; sharing ONE instance here is what lets the startup's `backfillIndex`
+// seed the very index the plugin's `search.query` reads from. Swap it for
+// `{ engine: 'typesense', url, apiKey }` (or meilisearch / algolia) for prod —
+// nothing else changes.
+import { memoryBackend, type IndexSpec, type SearchDoc } from '@voltro/plugin-search'
+
+export const searchBackend = memoryBackend()
+
+// One index over the `articles` table. `map` flattens a row → a search doc
+// (must include `id`); `tenantField` makes `search.query` auto-filter to the
+// caller's tenant, so one tenant can never see another's hits.
+export const articlesIndex: IndexSpec = {
+  index: 'articles',
+  map: (row): SearchDoc => ({
+    id: row['id'] as string,
+    title: row['title'] as string,
+    body: row['body'] as string,
+    tag: row['tag'] as string,
+    tenantId: row['tenantId'] as string,
+  }),
+  tenantField: 'tenantId',
+}

package/templates/apps/api-search/mutations/articles.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; tag: string },
+  ctx: AppContext,
+) => {
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+  // The framework auto-injects an `art_…` id. The insert commits, then the
+  // search plugin's tap indexes it — nothing to do here for search.
+  return ctx.store.insert('articles', {
+    title: input.title,
+    body: input.body,
+    tag: input.tag,
+    tenantId: input.tenantId,
+  })
+}
+
+export default execute

package/templates/apps/api-search/mutations/articles.create.mutation.ts

@@ -0,0 +1,35 @@
+// Creates an article. On commit, the search plugin's ChangeEvent tap mirrors
+// the new row into the index — so it's searchable immediately, no extra call.
+// `assertOwnTenant` rejects cross-tenant spoofing (typed `TenantMismatch`).
+
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { Schema } from 'effect'
+
+export const createArticle = defineMutation({
+  name: 'articles.create',
+  target: {
+    table: 'articles',
+    op: 'insert',
+    shape: (input: { tenantId: string; title: string; body: string; tag: string }) => ({
+      title: input.title,
+      body: input.body,
+      tag: input.tag,
+      tenantId: input.tenantId,
+    }),
+  },
+  input: Schema.Struct({
+    tenantId: Schema.String,
+    title: Schema.NonEmptyString,
+    body: Schema.String,
+    tag: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    tag: Schema.String,
+    tenantId: Schema.String,
+  }),
+  error: TenantMismatch,
+})

package/templates/apps/api-search/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "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-multitenancy": "0.1.0",
+    "@voltro/plugin-search": "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-search/queries/articles.list.query.server.ts

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'articles' 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-search/queries/articles.list.query.ts

@@ -0,0 +1,19 @@
+// A live list of the tenant's articles. Useful next to the search box to show
+// the full set; the search.query rpc (synthesized by searchPlugin) is what you
+// hit for a query string. tenant() scopes both to the caller automatically.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listArticles = defineQuery({
+  name: 'articles.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    tag: Schema.String,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

package/templates/apps/api-search/seeds/articles.seed.ts

@@ -0,0 +1,41 @@
+// Boot-lifecycle seed — a few articles so search returns results the moment
+// `voltro dev` boots. Idempotent via `upsertByUnique` (+ the fingerprint
+// ledger), so re-running on every boot is safe.
+//
+// The seed store is the RAW store (no authenticated subject), so the `tenant()`
+// auto-fill doesn't fire — we pass `tenantId` explicitly and seed the demo
+// tenant row first, under `acme` (the dev AuthMiddleware's default tenant).
+
+import { defineSeed } from '@voltro/database'
+
+const TENANT_ID = 'acme'
+
+export default defineSeed({
+  id:        'articles',
+  name:      'Demo articles for search',
+  lifecycle: 'boot',
+  steps: ({ step }) => [
+    step('tenant', async ({ upsertByUnique }) => {
+      await upsertByUnique(
+        'tenants',
+        { id: TENANT_ID },
+        { id: TENANT_ID, name: 'Acme', createdAt: new Date() },
+      )
+      return { rowsTouched: 1 }
+    }),
+
+    step('articles', async ({ upsertByUnique }) => {
+      const now = new Date()
+      const rows = [
+        { id: 'art_voltro', title: 'Getting started with Voltro', body: 'Reactive end-to-end, multi-tenant by design — scaffold an app and ship.', tag: 'guide' },
+        { id: 'art_search', title: 'Full-text search that stays in sync', body: 'The search plugin mirrors every write into the index via the post-commit change tap.', tag: 'guide' },
+        { id: 'art_tenant', title: 'Tenant isolation', body: 'Queries auto-filter to the caller tenant — search results included, no leakage.', tag: 'concept' },
+        { id: 'art_effect', title: 'Effect under the hood', body: 'Handlers compose with Effect for typed errors, retries, and timeouts.', tag: 'concept' },
+      ]
+      for (const r of rows) {
+        await upsertByUnique('articles', { id: r.id }, { ...r, tenantId: TENANT_ID, createdAt: now })
+      }
+      return { rowsTouched: rows.length }
+    }),
+  ],
+})

package/templates/apps/api-search/startup/searchBackfill.startup.tsx

@@ -0,0 +1,24 @@
+// Boot startup — seed the search index from rows already in the table.
+//
+// The live ChangeEvent tap (wired by searchPlugin) indexes every write AFTER
+// boot. THIS catches what's already there: the demo seed's rows, or — with a
+// persistent store or a freshly-switched vendor engine — every existing row.
+// It uses the SAME `searchBackend` instance the plugin queries (shared via
+// lib/search.ts), so the docs it writes are exactly what `search.query` reads.
+
+import type { StartupContext } from '@voltro/runtime'
+import { backfillIndex } from '@voltro/plugin-search'
+import { database } from '../database/schema'
+import { searchBackend, articlesIndex } from '../lib/search'
+
+export default async ({ store, log }: StartupContext): Promise<void> => {
+  // `database.articles.descriptor` is the builder's "select all" descriptor —
+  // a properly-formed query (don't hand-roll a raw `{ table, order: undefined }`,
+  // which trips the store's order/limit handling).
+  const rows = (await store.query(
+    database.articles.descriptor,
+  )) as ReadonlyArray<Record<string, unknown>>
+
+  const count = await backfillIndex(searchBackend, articlesIndex, rows)
+  log.info(`search: backfilled ${count} article(s) into the index`)
+}

package/templates/apps/api-search/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-search",
+  "kind": "api",
+  "summary": "Full-text search that stays in sync — @voltro/plugin-search mirrors every table write into an index via the post-commit change tap; the synthesized search.query rpc returns tenant-scoped hits. Memory backend (zero infra); swap for Typesense/Meilisearch/Algolia with one config line.",
+  "tags": ["api", "search", "full-text", "typesense", "meilisearch", "algolia", "plugin"]
+}

package/templates/apps/api-search/tests/articles.create.test.ts

@@ -0,0 +1,69 @@
+// Unit test with `@voltro/testing` — no database, no running server, no search
+// backend. The `articles.create` executor is a tenant-guarded insert: on commit
+// the search plugin's ChangeEvent tap mirrors the row into the index, but that
+// tap is dispatch-time infrastructure (Typesense/Meili/Algolia in prod, the
+// in-memory backend in dev) and is NOT wired into the unit store — so we do not
+// fake it. We cover the DB write + the cross-tenant write guard that gates it,
+// and pin the descriptor's typed error. Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { database } from '../database/schema'   // registers articles / actors / tenants
+import { createArticle } from '../mutations/articles.create.mutation'
+import createArticleHandler from '../mutations/articles.create.mutation.server'
+
+describe('articles.create', () => {
+  it('inserts an article for the caller\'s own tenant', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ articles: [] }),
+    })
+    const row = await createArticleHandler(
+      { tenantId: 'acme', title: 'Hello', body: 'World', tag: 'news' },
+      ctx,
+    )
+
+    expect(row['title']).toBe('Hello')
+    expect(row['tag']).toBe('news')
+    expect(row['tenantId']).toBe('acme')
+    expect(row['id'] as string).toMatch(/^art_/)
+  })
+
+  it('rejects a cross-tenant write with a typed TenantMismatch (the spoof guard)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ articles: [] }),
+    })
+    // Input claims a DIFFERENT tenant than the subject → assertOwnTenant throws.
+    // The executor is async, so the throw surfaces as a rejected promise.
+    await expect(
+      createArticleHandler(
+        { tenantId: 'evil', title: 'x', body: '', tag: '' },
+        ctx,
+      ),
+    ).rejects.toThrow(TenantMismatch)
+
+    // Nothing was written.
+    const rows = await ctx.store.query(database.articles.descriptor)
+    expect(rows).toHaveLength(0)
+  })
+
+  it('isolates tenants — t2 never sees t1 articles', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ articles: [] }),
+    })
+    await createArticleHandler({ tenantId: 't1', title: 'secret', body: '', tag: '' }, ctx)
+
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.articles.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+
+  it('pins the descriptor error contract — articles.create declares TenantMismatch', () => {
+    // The descriptor is value-imported into the browser rpcGroup, so the client
+    // decodes this typed failure without a manual error union.
+    expect(createArticle.name).toBe('articles.create')
+    expect(createArticle.error).toBe(TenantMismatch)
+  })
+})

package/templates/apps/api-search/tsconfig.json

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

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

@@ -0,0 +1,51 @@
+# {{projectName}} / {{appName}}
+
+Voltro API scaffold (template: **api-versioning**) — full row history +
+time-travel with `@voltro/plugin-versioning`.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000  (store: memory — zero infra)
+```
+
+## What this shows
+
+- **Every change snapshotted** — `versioningPlugin({ tables: ['documents'] })`
+  rides the post-commit ChangeEvent tap and records a FULL snapshot of every
+  insert/update/delete. No code in your handlers.
+- **Read it back through handlers** —
+  - `documents.history` → `rowHistory(ctx.store, 'documents', id)` — every
+    version, oldest to newest.
+  - `documents.asOf` → `rowAsOf(ctx.store, 'documents', id, at)` — the value as
+    of a past instant (epoch ms), or `null` if it didn't exist then.
+- **Distinct from audit** — `audit()` records WHO/WHEN a row changed; this
+  records WHAT it changed to, so you can diff or restore a prior version.
+
+## Try it
+
+```bash
+# create (v1), then edit (v2):
+ID=$(curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"documents.create","input":{"title":"Spec","content":"draft v1"}}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d "{\"tag\":\"documents.update\",\"input\":{\"id\":\"$ID\",\"content\":\"final v2\"}}" >/dev/null
+
+# every version:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d "{\"tag\":\"documents.history\",\"input\":{\"id\":\"$ID\"}}"
+# → [ { version:1, op:"insert", content:"draft v1", changedAt }, { version:2, op:"update", content:"final v2", … } ]
+
+# the value as of v1's timestamp → "draft v1" (time-travel):
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d "{\"tag\":\"documents.asOf\",\"input\":{\"id\":\"$ID\",\"at\":<v1.changedAt>}}"
+```
+
+## Production
+
+The memory history store is single-process. With a SQL store, history persists
+in `_voltro_row_history`. List the tables you want versioned — high-churn
+tables grow history fast, so version what you need to diff/restore, not
+everything.