@voltro/cli 0.1.0

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

@@ -0,0 +1,33 @@
+// Content-moderation backend for the {{projectName}} project.
+//
+// `moderationPlugin` runs on the rpc interceptors BEFORE the handler: it checks
+// the named input fields against a provider and, per rule, either BLOCKS the
+// call (typed `ContentRejected` — the write never commits) or FLAGS it for
+// review (the write commits, the item lands in the review queue). `keywordProvider`
+// is a zero-dep deny-list; `aiProvider()` is an optional LLM classifier.
+// Config-only, zero infra.
+import { defineEnv, envVar } from '@voltro/env'
+import { moderationPlugin, keywordProvider } from '@voltro/plugin-moderation'
+
+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: [
+    moderationPlugin({
+      provider: keywordProvider(['spam', 'scam', 'phishing', 'malware']),
+      rules: [
+        // BLOCK: a post whose title/body trips the deny-list is rejected
+        // (ContentRejected) before it's ever written.
+        { match: 'posts.create', fields: ['title', 'body'], action: 'block' },
+        // FLAG: a comment is still written, but flagged for review.
+        { match: 'comments.create', fields: ['body'], action: 'flag' },
+      ],
+    }),
+  ],
+  env,
+}

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

@@ -0,0 +1,45 @@
+// Schema for the {{projectName}} moderation backend — `posts` (block rule) and
+// `comments` (flag rule). `actors` + `tenants` are the framework core tables.
+
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+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'),
+})
+
+export const posts = table('posts', {
+  id:    id({ prefix: 'post' }),
+  title: text(),
+  body:  text(),
+})
+  .with(tenant())
+  .reactive()
+
+export const comments = table('comments', {
+  id:   id({ prefix: 'cmt' }),
+  body: text(),
+})
+  .with(tenant())
+  .reactive()
+
+export type Post = InferRow<typeof posts>
+export type Comment = InferRow<typeof comments>
+
+export const database = databaseHandle({ actors, tenants, posts, comments })

package/templates/apps/api-moderation/mutations/comments.create.mutation.server.ts

@@ -0,0 +1,8 @@
+import type { AppContext } from '@voltro/runtime'
+
+// Plain insert — a `flag` rule lets the write through (and records the flag);
+// only a `block` rule would have stopped us. tenant() auto-fills tenantId.
+const execute = async (input: { body: string }, ctx: AppContext) =>
+  ctx.store.insert('comments', { body: input.body })
+
+export default execute

package/templates/apps/api-moderation/mutations/comments.create.mutation.ts

@@ -0,0 +1,20 @@
+// Creates a comment. The `flag`-action moderation rule (app.config.ts) checks
+// the body, but unlike `block` it does NOT reject — the comment is written and
+// flagged for review (the dashboard's Moderation panel surfaces the queue).
+// So there's no moderation error on this procedure.
+
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createComment = defineMutation({
+  name: 'comments.create',
+  target: { table: 'comments', op: 'insert' },
+  input: Schema.Struct({
+    body: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    body: Schema.String,
+    tenantId: Schema.String,
+  }),
+})

package/templates/apps/api-moderation/mutations/posts.create.mutation.server.ts

@@ -0,0 +1,9 @@
+import type { AppContext } from '@voltro/runtime'
+
+// Plain insert — the `block` moderation rule already rejected banned content
+// before we got here, so this only runs on clean input. tenant() auto-fills
+// tenantId from the subject.
+const execute = async (input: { title: string; body: string }, ctx: AppContext) =>
+  ctx.store.insert('posts', { title: input.title, body: input.body })
+
+export default execute

package/templates/apps/api-moderation/mutations/posts.create.mutation.ts

@@ -0,0 +1,25 @@
+// Creates a post. The `block`-action moderation rule (app.config.ts) checks
+// title + body BEFORE this handler runs; banned content fails typed
+// `ContentRejected` and the write never commits. There's no moderation code
+// in the handler. Declaring `error: ContentRejected` surfaces it to the client
+// typed. `ContentRejected` comes from the browser-safe `/errors` subpath.
+
+import { defineMutation } from '@voltro/protocol'
+import { ContentRejected } from '@voltro/plugin-moderation/errors'
+import { Schema } from 'effect'
+
+export const createPost = defineMutation({
+  name: 'posts.create',
+  target: { table: 'posts', op: 'insert' },
+  input: Schema.Struct({
+    title: Schema.NonEmptyString,
+    body: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    tenantId: Schema.String,
+  }),
+  error: ContentRejected,
+})

package/templates/apps/api-moderation/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-moderation": "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-moderation/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-moderation",
+  "kind": "api",
+  "summary": "Pre-commit content moderation — @voltro/plugin-moderation checks named input fields BEFORE the handler: a block rule rejects banned content with typed ContentRejected (write never commits), a flag rule writes it but queues it for review. keywordProvider (zero-dep deny-list) or aiProvider. Memory store, zero infra.",
+  "tags": ["api", "moderation", "content", "trust-safety", "plugin"]
+}

package/templates/apps/api-moderation/tests/posts.create.test.ts

@@ -0,0 +1,79 @@
+// Unit test for `posts.create` — driven through `@voltro/testing`.
+//
+// Content moderation is enforced by the plugin's rpc INTERCEPTOR (a block rule
+// wired in app.config.ts), which runs BEFORE this executor and rejects banned
+// content with a typed `ContentRejected` — a dispatch-time middleware, NOT the
+// executor. `invoke` reproduces only the input-Schema decode, not middleware
+// (see its header), so we DON'T fake the interceptor: we test the executor's own
+// observable behavior (the tenant-stamped insert) + pin the descriptor's
+// declared `ContentRejected` error shape. Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { Schema } from 'effect'
+import { makeTestContext, mockStore, invoke } from '@voltro/testing'
+import { database } from '../database/schema' // registers actors / tenants / posts / comments
+import { createPost } from '../mutations/posts.create.mutation'
+import createPostHandler from '../mutations/posts.create.mutation.server'
+import { ContentRejected } from '@voltro/plugin-moderation/errors'
+
+const subject = { type: 'user', id: 'u1', tenantId: 'acme' } as const
+
+describe('posts.create', () => {
+  it('inserts a post stamped with the caller tenant + a post_ TypeID', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ posts: [] }) })
+
+    const row = (await invoke(
+      createPost,
+      createPostHandler,
+      { title: 'Hello', body: 'World' },
+      ctx,
+    )) as { id: string; title: string; body: string; tenantId: string }
+
+    expect(row.title).toBe('Hello')
+    expect(row.body).toBe('World')
+    expect(row.tenantId).toBe('acme') // tenant() stamped it from the subject
+    expect(row.id).toMatch(/^post_/)
+
+    // The row is really in the store — the live tenant-scoped query sees it.
+    const rows = await ctx.store.query(database.posts.descriptor)
+    expect(rows).toHaveLength(1)
+  })
+
+  it('rejects an empty title at the input-schema decode (NonEmptyString)', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ posts: [] }) })
+
+    await expect(
+      invoke(createPost, createPostHandler, { title: '', body: '' }, ctx),
+    ).rejects.toThrow()
+  })
+
+  it('isolates tenants — a second tenant never sees the first tenant post', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store: mockStore({ posts: [] }),
+    })
+    await invoke(createPost, createPostHandler, { title: 'secret', body: '' }, ctx)
+
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.posts.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+
+  it('pins the descriptor: name, input decode + the declared ContentRejected error', async () => {
+    // The moderation error is a dispatch-time interceptor concern, not reachable
+    // from the executor here — so we pin the CONTRACT the client relies on: the
+    // rpc tag, that the input Schema decodes a valid post, and that the typed
+    // ContentRejected error the interceptor raises is declared on the procedure.
+    expect(createPost.name).toBe('posts.create')
+
+    const decoded = Schema.decodeUnknownSync(createPost.input)({ title: 'ok', body: 'b' })
+    expect(decoded).toEqual({ title: 'ok', body: 'b' })
+
+    const rejected = new ContentRejected({
+      tag: 'posts.create',
+      categories: ['profanity'],
+      reason: 'banned term',
+    })
+    expect(rejected).toBeInstanceOf(ContentRejected)
+    expect(Schema.is(ContentRejected)(rejected)).toBe(true)
+  })
+})

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

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

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

@@ -0,0 +1,106 @@
+# {{capProjectName}} {{capAppName}} — observability + testing
+
+The production-readiness slice in one backend: **Prometheus metrics**, **Sentry
+error tracking**, **distributed tracing**, and a **`@voltro/testing` unit test**
+— so a real service is observable AND covered from day one.
+
+## What it demonstrates
+
+- **Prometheus** ([`@voltro/plugin-prometheus`](https://voltro.cloud/docs/observability/metrics)) —
+  `GET /metrics` in the text exposition format. The framework already records
+  `voltro_rpc_*` / `voltro_http_*` / subscription / cache metrics; `notes.create`
+  adds a **custom counter** (`app_notes_created_total`) that shows up automatically.
+- **Sentry** ([`@voltro/plugin-sentry`](https://voltro.cloud/docs/observability/errors)) —
+  rpc / REST / workflow / render errors reported correlated to the active
+  `traceId`. **Inert without `SENTRY_DSN`**, so it ships wired — set the env to turn it on.
+- **Tracing** — on by default in `voltro dev` (DevTools Traces panel + `traceId`
+  on every log line). Set `OTEL_EXPORTER_OTLP_ENDPOINT` to ship to Jaeger / Tempo / Honeycomb.
+- **Testing** ([`@voltro/testing`](https://voltro.cloud/docs/testing)) — a unit
+  test that runs the `notes.create` handler with `makeTestContext` + `mockStore`
+  (no DB, no server) and asserts the **real** tenant scoping.
+
+## Run it
+
+```bash
+voltro dev .
+```
+
+### Metrics
+
+```bash
+# Create a note (custom counter increments)
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' \
+  -d '{"tag":"notes.create","input":{"title":"Hello","body":"World"}}'
+
+# Scrape Prometheus — your custom counter + the framework's rpc metrics
+curl -s http://localhost:4000/metrics | grep -E 'app_notes_created_total|voltro_rpc_requests_total'
+# app_notes_created_total 1
+# voltro_rpc_requests_total{tag="notes.create",status="ok"} 1
+```
+
+Point Prometheus / Grafana Agent at `/metrics`; gate it with
+`prometheusPlugin({ token })` / `PROMETHEUS_TOKEN` for a public deploy.
+
+### Errors → Sentry
+
+Set `SENTRY_DSN` (api) — then any handler throw, REST 5xx, workflow failure, or
+React render/loader error is captured, tagged with the request's `traceId`. For
+the full browser→backend waterfall, add the `sentry` field to a paired web app's
+`app.config.ts` (see the docs).
+
+### A custom metric
+
+```ts
+// mutations/notes.create.mutation.server.ts
+import { Effect, Metric } from 'effect'
+import { counter } from '@voltro/runtime'
+
+const notesCreated = counter('app_notes_created_total', 'Notes created.')
+Effect.runSync(Metric.increment(notesCreated))   // shows up in /metrics + the dashboard
+```
+
+## Test it
+
+The template ships a unit test (`tests/notes.create.test.ts`) and the dev deps
+(`@voltro/testing`, `vitest`). After `pnpm install`:
+
+```bash
+voltro test               # vitest against this app
+```
+
+```ts
+const ctx = makeTestContext({
+  subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+  store:   mockStore({ notes: [] }),
+})
+const row = await createNote({ title: 'Hello', body: 'World' }, ctx)
+expect(row.tenantId).toBe('acme')   // tenant() stamped it — the REAL store, no DB
+```
+
+`ctx.store` is the same mixin-wrapped store production uses, so tenant
+auto-scoping, soft-delete filtering, and audit auto-fill all behave identically —
+in milliseconds, with no docker. `ctx.withTenant('t2', …)` re-scopes the same
+data to prove cross-tenant isolation. See `@voltro/testing` for `MockClock` /
+`MockEmail` / `mockAi` / `makeWorkflowRunner` / `runDialectParity`.
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| Metrics survive a public deploy | `prometheusPlugin({ token })` + scrape over TLS |
+| Errors in Sentry | set `SENTRY_DSN`; add `sentryPlugin({ traces: true })` for performance traces |
+| Spans in your tracer | `OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318` |
+| Vendor-native (Datadog) | add `@voltro/plugin-datadog` — agentless metrics + correlated logs/traces |
+| CI gate | run `voltro test` in CI; add `runDialectParity` for hand-written SQL |
+
+## Anti-patterns
+
+- **Re-creating the counter per call.** Declare `counter(...)` at MODULE level —
+  a per-call `counter()` resets the series. (The runtime dedupes by name, but
+  module-level is the clear intent.)
+- **Assuming Sentry needs code to wire each primitive.** The plugin subscribes
+  to the framework's server-error bus once — rpc, REST, workflows, schedules,
+  subscribers, webhooks, and startups are all covered. You just set the DSN.
+- **Reaching for a real DB in unit tests.** `makeTestContext` + `mockStore` give
+  the real store behaviour in-memory. Save a live database for `voltro e2e`.

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

@@ -0,0 +1,32 @@
+// Api app config — the observability + testing showcase. Read by `voltro dev`.
+//
+// Two observability plugins, both turnkey:
+//   • prometheusPlugin() — exposes GET /metrics in the text exposition format.
+//     The framework already records rpc / http / subscription / cache metrics
+//     into Effect's global MetricRegistry; the plugin just exports them. Your
+//     OWN counters (see mutations/notes.create) show up there too, automatically.
+//   • sentryPlugin() — reports rpc-handler + REST + workflow + render errors,
+//     correlated to the active trace. INERT without SENTRY_DSN, so it's safe to
+//     ship wired: set the env to turn it on, no code change.
+//
+// Tracing is on by default in `voltro dev` (a buffer-only tracer powers the
+// DevTools Traces panel + traceId-in-logs); set OTEL_EXPORTER_OTLP_ENDPOINT to
+// ship spans to Jaeger / Tempo / Honeycomb.
+//
+// `store: 'memory'` keeps first-run zero-infra.
+
+import { prometheusPlugin } from '@voltro/plugin-prometheus'
+import { sentryPlugin } from '@voltro/plugin-sentry'
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  plugins: [
+    // GET /metrics → Prometheus text. Optional bearer gate: prometheusPlugin({ token })
+    // / PROMETHEUS_TOKEN. processMetrics defaults on (RSS + CPU).
+    prometheusPlugin(),
+    // Inert until SENTRY_DSN is set; then errors flow correlated to the traceId.
+    sentryPlugin(),
+  ],
+}

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

@@ -0,0 +1,38 @@
+// Schema for the {{projectName}} observability backend — a minimal tenant-scoped
+// `notes` domain. The point of this template is what surrounds it: Prometheus
+// metrics, Sentry error tracking, tracing, and a unit test (see tests/).
+
+import {
+  boolean,
+  databaseHandle,
+  id,
+  table,
+  text,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// ---------- Core tables ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+})
+
+export const tenants = table('tenants', { id: id(), name: text() })
+
+// ---------- Application table ----------
+
+export const notes = table('notes', {
+  id:    id({ prefix: 'note' }),
+  title: text(),
+  body:  text(),
+  done:  boolean().default(false),
+})
+  .with(tenant())   // tenantId + audit columns, auto-stamped
+  .reactive()
+
+export type Note = InferRow<typeof notes>
+
+export const database = databaseHandle({ actors, tenants, notes })

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

@@ -0,0 +1,33 @@
+// Create a note + record a CUSTOM Prometheus metric.
+//
+// `counter(name, desc)` registers a metric in Effect's global MetricRegistry —
+// the same registry GET /metrics (prometheusPlugin) and the DevTools Metrics
+// panel both read, so your counter shows up in both with no extra wiring.
+// We keep the handler ASYNC (so the test can `await execute(input, ctx)`) and
+// bump the counter with a tiny `Effect.runSync` — Metric.increment is a
+// synchronous effect.
+
+import { Effect, Metric } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { counter } from '@voltro/runtime'
+
+// Module-level so it's the SAME metric across every call (not re-created).
+const notesCreated = counter('app_notes_created_total', 'Notes created via notes.create.')
+
+const execute = async (input: { title: string; body: string }, ctx: AppContext) => {
+  Effect.runSync(Metric.increment(notesCreated))   // → app_notes_created_total in /metrics
+  // tenant() auto-stamps tenantId (+ audit columns) from ctx.request.subject.
+  // `done: false` is set explicitly — a column DEFAULT only fills in on a SQL
+  // store; the memory store leaves an omitted column null, which would fail the
+  // `done: Schema.Boolean` output encode over the rpc wire.
+  const row = await ctx.store.insert('notes', { title: input.title, body: input.body, done: false })
+  return {
+    id:       row['id'] as string,
+    title:    row['title'] as string,
+    body:     row['body'] as string,
+    done:     row['done'] as boolean,
+    tenantId: row['tenantId'] as string,
+  }
+}
+
+export default execute

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

@@ -0,0 +1,15 @@
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createNote = defineMutation({
+  name:   'notes.create',
+  target: { table: 'notes', op: 'insert' },
+  input:  Schema.Struct({ title: Schema.NonEmptyString, body: Schema.String }),
+  output: Schema.Struct({
+    id:       Schema.String,
+    title:    Schema.String,
+    body:     Schema.String,
+    done:     Schema.Boolean,
+    tenantId: Schema.String,
+  }),
+})

package/templates/apps/api-observability/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/plugin-multitenancy": "0.1.0",
+    "@voltro/plugin-prometheus": "0.1.0",
+    "@voltro/plugin-sentry": "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-observability/queries/notes.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.notes.orderBy('createdAt', 'desc').limit(100)
+
+export default route

package/templates/apps/api-observability/queries/notes.list.query.ts

@@ -0,0 +1,14 @@
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name:   'notes.list',
+  source: 'notes',
+  input:  Schema.Struct({}),
+  output: Schema.Array(Schema.Struct({
+    id:    Schema.String,
+    title: Schema.String,
+    body:  Schema.String,
+    done:  Schema.Boolean,
+  })),
+})

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

@@ -0,0 +1,6 @@
+{
+  "id": "api-observability",
+  "kind": "api",
+  "summary": "Production-readiness in one backend: Prometheus metrics (GET /metrics + a custom counter), Sentry error tracking (inert without a DSN), distributed tracing, AND a @voltro/testing example (makeTestContext + mockStore, run with voltro test).",
+  "tags": ["api", "observability", "prometheus", "metrics", "sentry", "testing", "tracing"]
+}

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

@@ -0,0 +1,36 @@
+// Unit test with `@voltro/testing` — no database, no running server, no real
+// model calls. `makeTestContext` hands the handler the SAME mixin-wrapped
+// `ctx.store` it 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 createNote from '../mutations/notes.create.mutation.server'
+
+describe('notes.create', () => {
+  it('inserts a note, auto-stamped to the caller tenant', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    const row = await createNote({ title: 'Hello', body: 'World' }, ctx)
+
+    expect(row.title).toBe('Hello')
+    expect(row.tenantId).toBe('acme')      // tenant() stamped it from the subject
+    expect(row.id).toMatch(/^note_/)       // TypeID auto-injected
+  })
+
+  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({ title: 'secret', body: '' }, ctx)
+
+    // Re-scope the SAME store to a different tenant — `withTenant` hands the
+    // callback a re-scoped `c`; query THAT (the real WHERE filter hides t1's row).
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.notes.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+})

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

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

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

@@ -0,0 +1,49 @@
+# {{projectName}} / {{appName}}
+
+Voltro API scaffold (template: **api-ratelimit**) — per-endpoint /
+per-subject / per-tenant rate limiting with `@voltro/plugin-ratelimit`.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000  (store: memory — zero infra)
+```
+
+## What this shows
+
+- **Limits as config** — `rateLimitPlugin` runs on the rpc interceptors (the
+  only surface that sees every call AND the resolved subject). A `default`
+  fallback applies everywhere; `rules` override per endpoint:
+  - `match` — an exact tag or a `/regex/`; `kind` narrows to mutation/query/action.
+  - `algorithm` — `sliding-window` (default), `fixed-window`, or
+    `token-bucket` (with `burst`).
+  - `by` — the bucket key: `subject` (default), `tenant`, `apiKey`, `global`,
+    or a composite array.
+- **Typed `RateLimited`** — over-limit calls fail a `RateLimited` error
+  (`{ tag, limit, retryAfterMs, resetAtMs }`). The plugin merges it into every
+  procedure's wire error union, so the client decodes it typed and can show a
+  "try again in N seconds".
+
+This template caps `notes.create` at **3/min per tenant** (token-bucket,
+burst 3): the first three calls land, the fourth is rejected.
+
+## Try it
+
+```bash
+# Fire it four times for tenant 'acme' — the 4th trips the limit:
+for i in 1 2 3 4; do
+  curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+    -d "{\"tag\":\"notes.create\",\"input\":{\"tenantId\":\"acme\",\"title\":\"n$i\",\"body\":\"x\"}}" \
+    | python3 -c 'import sys,json;d=json.load(sys.stdin);print(i, d.get("ok"), (d.get("error") or {}).get("name",""))' i=$i 2>/dev/null || true
+done
+# → 1 True ; 2 True ; 3 True ; 4 False RateLimited
+```
+
+## Multi-node
+
+`store: 'memory'` is single-process. For a cluster, switch to `'postgres'`
+(state under a row lock, reuses `DB_*`/`PG_*`) or `'redis'` (fastest — one
+atomic Lua script; reads `CACHE_REDIS_URL` / `REDIS_URL`). All shared stores
+fail OPEN on a backend error.