@voltro/cli 0.1.0

package/templates/apps/api-versioning/actions/documents.asOf.action.server.ts

@@ -0,0 +1,13 @@
+import type { AppContext } from '@voltro/runtime'
+import { rowAsOf } from '@voltro/plugin-versioning'
+
+const execute = async (input: { id: string; at: number }, ctx: AppContext) => {
+  const snapshot = await rowAsOf(ctx.store, 'documents', input.id, ctx.request.subject.tenantId, input.at)
+  if (snapshot === null) return null
+  return {
+    title: snapshot['title'] as string,
+    content: snapshot['content'] as string,
+  }
+}
+
+export default execute

package/templates/apps/api-versioning/actions/documents.asOf.action.ts

@@ -0,0 +1,14 @@
+// Time-travel: the document's value as of a past instant (`at`, epoch ms).
+// Returns null if it didn't exist (or was deleted) then.
+
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const documentAsOf = defineAction({
+  name: 'documents.asOf',
+  input: Schema.Struct({ id: Schema.String, at: Schema.Number }),
+  output: Schema.NullOr(Schema.Struct({
+    title: Schema.String,
+    content: Schema.String,
+  })),
+})

package/templates/apps/api-versioning/actions/documents.history.action.server.ts

@@ -0,0 +1,15 @@
+import type { AppContext } from '@voltro/runtime'
+import { rowHistory } from '@voltro/plugin-versioning'
+
+const execute = async (input: { id: string }, ctx: AppContext) => {
+  const rows = await rowHistory(ctx.store, 'documents', input.id, ctx.request.subject.tenantId)
+  return rows.map((r) => ({
+    version: r.version,
+    op: r.op,
+    title: (r.data?.['title'] as string | undefined) ?? null,
+    content: (r.data?.['content'] as string | undefined) ?? null,
+    changedAt: r.changedAt,
+  }))
+}
+
+export default execute

package/templates/apps/api-versioning/actions/documents.history.action.ts

@@ -0,0 +1,17 @@
+// Lists every recorded version of a document — what it looked like after each
+// change. (`audit()` tells you WHO/WHEN; this tells you WHAT it changed to.)
+
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const documentHistory = defineAction({
+  name: 'documents.history',
+  input: Schema.Struct({ id: Schema.String }),
+  output: Schema.Array(Schema.Struct({
+    version: Schema.Number,
+    op: Schema.String,
+    title: Schema.NullOr(Schema.String),
+    content: Schema.NullOr(Schema.String),
+    changedAt: Schema.Number,
+  })),
+})

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

@@ -0,0 +1,24 @@
+// Row-history backend for the {{projectName}} project.
+//
+// `versioningPlugin({ tables })` rides the post-commit ChangeEvent tap and
+// records a FULL snapshot of every insert/update/delete on the listed tables
+// into row history. Read it back with `rowHistory(store, table, id)` (every
+// version) and `rowAsOf(store, table, id, when)` (the value at a past instant
+// — time-travel). This is what-changed-to-what; `audit()` is who/when.
+// Memory history store — zero infra.
+import { defineEnv, envVar } from '@voltro/env'
+import { versioningPlugin } from '@voltro/plugin-versioning'
+
+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: [
+    versioningPlugin({ tables: ['documents'] }),
+  ],
+  env,
+}

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

@@ -0,0 +1,38 @@
+// Schema for the {{projectName}} versioning backend — a `documents` table whose
+// every change is snapshotted into row history (see app.config.ts).
+// `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 documents = table('documents', {
+  id:      id({ prefix: 'doc' }),
+  title:   text(),
+  content: text(),
+})
+  .with(tenant())
+  .reactive()
+
+export type Document = InferRow<typeof documents>
+
+export const database = databaseHandle({ actors, tenants, documents })

package/templates/apps/api-versioning/mutations/documents.create.mutation.server.ts

@@ -0,0 +1,8 @@
+import type { AppContext } from '@voltro/runtime'
+
+// Plain insert — tenant() auto-fills tenantId. The versioning plugin records
+// version 1 from the post-commit change event.
+const execute = async (input: { title: string; content: string }, ctx: AppContext) =>
+  ctx.store.insert('documents', { title: input.title, content: input.content })
+
+export default execute

package/templates/apps/api-versioning/mutations/documents.create.mutation.ts

@@ -0,0 +1,21 @@
+// Creates a document — version 1 in its history. The versioning plugin
+// snapshots the insert automatically (no code here); read it back via the
+// documents.history / documents.asOf actions.
+
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createDocument = defineMutation({
+  name: 'documents.create',
+  target: { table: 'documents', op: 'insert' },
+  input: Schema.Struct({
+    title: Schema.NonEmptyString,
+    content: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    content: Schema.String,
+    tenantId: Schema.String,
+  }),
+})

package/templates/apps/api-versioning/mutations/documents.update.mutation.server.ts

@@ -0,0 +1,9 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (input: { id: string; content: string }, ctx: AppContext) => {
+  const row = await ctx.store.update('documents', input.id, { content: input.content })
+  if (row === null) throw { status: 404, message: `document ${input.id} not found` }
+  return row
+}
+
+export default execute

package/templates/apps/api-versioning/mutations/documents.update.mutation.ts

@@ -0,0 +1,21 @@
+// Edits a document's content — a new version in its history. Each update is
+// snapshotted, so you can list every version or read the value as of any past
+// instant.
+
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const updateDocument = defineMutation({
+  name: 'documents.update',
+  target: { table: 'documents', op: 'update' },
+  input: Schema.Struct({
+    id: Schema.String,
+    content: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    content: Schema.String,
+    tenantId: Schema.String,
+  }),
+})

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

@@ -0,0 +1,6 @@
+{
+  "id": "api-versioning",
+  "kind": "api",
+  "summary": "Row history + time-travel — @voltro/plugin-versioning snapshots every insert/update/delete on the listed tables via the post-commit change tap; read every version with rowHistory() and the value at a past instant with rowAsOf(). audit() is who/when; this is what-changed-to-what. Memory store, zero infra.",
+  "tags": ["api", "versioning", "history", "audit-trail", "time-travel", "plugin"]
+}

package/templates/apps/api-versioning/tests/documents.create.test.ts

@@ -0,0 +1,37 @@
+// Unit test with `@voltro/testing` — no database, no running server. The base
+// `documents.create` mutation is a plain tenant()-scoped insert, so it's fully
+// unit-runnable. The row-HISTORY / as-of reads are populated by the versioning
+// plugin's post-commit tap (not wired into the unit store), so those are
+// integration-tested elsewhere; here we cover the write + tenant isolation that
+// every version-1 snapshot is built from. Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema'   // registers documents / actors / tenants
+import createDocument from '../mutations/documents.create.mutation.server'
+
+describe('documents.create', () => {
+  it('inserts a document, auto-stamped to the caller tenant', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ documents: [] }),
+    })
+    const row = await createDocument({ title: 'Spec', content: 'v1 body' }, ctx)
+
+    expect(row['title']).toBe('Spec')
+    expect(row['content']).toBe('v1 body')
+    expect(row['tenantId']).toBe('acme')          // tenant() stamped it
+    expect(row['id'] as string).toMatch(/^doc_/)   // TypeID auto-injected
+  })
+
+  it('isolates tenants — t2 never sees t1 documents (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ documents: [] }),
+    })
+    await createDocument({ title: 'secret', content: '' }, ctx)
+
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.documents.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+})

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

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

package/templates/apps/api-webhooks/.env

@@ -0,0 +1,6 @@
+# DEV-ONLY signing secret for the incoming `orders` webhook. The convention is
+# VOLTRO_WEBHOOK_SECRET_<UPPER_ID> — for `id: 'orders'` that's _ORDERS. The
+# external caller signs `<unix>.<rawBody>` with this and sends
+# `X-Webhook-Signature: t=<ts>,v1=<hmac-sha256-hex>`. Rotate it for production
+# (the partner gets the new value out of band).
+VOLTRO_WEBHOOK_SECRET_ORDERS=devonly-webhook-secret-change-me

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

@@ -0,0 +1,106 @@
+# {{capProjectName}} {{capAppName}} — first-class webhooks
+
+Webhooks **both ways**, wired turnkey: a **signature-verified incoming receiver**
+that rejects forged traffic before your code runs, and an **outgoing event** a
+mutation emits to subscribed targets through a durable, signed, retried delivery
+workflow. Boots **zero-infra** (`store: 'memory'`).
+
+Webhooks are **file-convention**, not a `plugins:[]` entry — drop a
+`*.webhook.tsx`, it's auto-discovered.
+
+## What ships
+
+```text
+apps/acme/api/
+├── .env                                  # VOLTRO_WEBHOOK_SECRET_ORDERS (dev signing secret)
+├── database/schema.ts                    # orders + webhookTables() bookkeeping
+├── webhooks/orders.webhook.tsx           # INCOMING — signature-verified receiver
+├── events/order.completed.webhook.tsx    # OUTGOING — defineOutgoingEvent
+├── mutations/orders.fulfill.mutation.ts  # create order + emit (+ .server.ts)
+└── queries/orders.list.query.ts          # reactive list (+ .server.ts)
+```
+
+## Incoming — verified before your handler runs
+
+```tsx
+// webhooks/orders.webhook.tsx → mounts at POST /webhooks/orders
+import { defineIncomingWebhook } from '@voltro/plugin-webhooks'
+import { genericProvider } from '@voltro/plugin-webhooks/providers'
+
+export default defineIncomingWebhook({
+  id: 'orders', provider: genericProvider(), payload: Schema.Struct({ … }),
+  handler: async (ctx) => { /* ctx.body is validated; ctx.idempotencyKey set */ },
+})
+```
+
+The framework's middleware runs **before** `handler`: verify the HMAC over
+`<ts>.<rawBody>` (→ `401`), reject a stale timestamp (→ `401`), decode the body
+against `payload` (→ `422`), claim the `Idempotency-Key` (a replay → `200
+{duplicate:true}`, handler skipped). You never hand-roll a signature check, and
+forged traffic never reaches your code. Built-in provider presets:
+`stripeProvider` / `githubProvider` / `slackProvider` / `genericProvider` (or
+`defineWebhookProvider` for a custom partner).
+
+The signing secret comes from `VOLTRO_WEBHOOK_SECRET_<UPPER_ID>` — here
+`VOLTRO_WEBHOOK_SECRET_ORDERS` (shipped DEV-ONLY in `.env`).
+
+### Try it (curl)
+
+```bash
+SECRET='devonly-webhook-secret-change-me'
+BODY='{"event":"order.created","orderId":"o_1","sku":"WIDGET","totalCents":1999}'
+TS=$(date +%s)
+SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.*= //')
+
+# valid signature → 200, handler runs
+curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:4000/webhooks/orders \
+  -H "X-Webhook-Signature: t=$TS,v1=$SIG" -H 'content-type: application/json' \
+  -H 'Idempotency-Key: evt_1' --data "$BODY"            # → 200
+
+# no signature → 401 ; forged signature → 401 ; valid sig + wrong shape → 422
+curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:4000/webhooks/orders \
+  -H 'content-type: application/json' --data "$BODY"     # → 401
+```
+
+## Outgoing — emit to subscribed targets
+
+```ts
+// events/order.completed.webhook.tsx
+export default defineOutgoingEvent({ id: 'order.completed', payload: Schema.Struct({ … }), version: 1 })
+
+// mutations/orders.fulfill.mutation.server.ts — after the row commits:
+const { eventId, deliveries } = await useWebhooks(ctx).emit('order.completed', { orderId, tenantId, … })
+```
+
+External systems subscribe at runtime — `ctx.webhooks.subscribe({ event:
+'order.completed', url })` (one row in `_voltro_webhook_targets`). On `emit`, the
+framework fans out to every matching target through a **durable delivery
+workflow** — HMAC-signing the outbound request, retrying with backoff, honouring
+`Retry-After`; each attempt lands in `_voltro_webhook_deliveries`. The `emit`
+returns immediately (the POSTs run in the background); `deliveries` is one entry
+per matched target (empty until someone subscribes).
+
+```bash
+# Fulfill an order → emits order.completed (0 targets until a subscriber registers)
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"orders.fulfill","input":{"sku":"WIDGET","totalCents":4999}}'
+```
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| A real partner (Stripe/GitHub/Slack) | swap `genericProvider()` → `stripeProvider()` etc.; set `VOLTRO_WEBHOOK_SECRET_<ID>` |
+| Durable targets + delivery history | `store: 'postgres'` (the `_voltro_webhook_*` tables survive restarts) |
+| A subscribe API | a mutation calling `ctx.webhooks.subscribe({ event, url, secret?, retry? })` |
+| A custom signature scheme | `defineWebhookProvider({ id, signature, idempotency })` |
+
+## Anti-patterns
+
+- **Trusting webhook input without verification.** The framework rejects unsigned
+  incoming requests by default — don't set `signature: undefined` unless a
+  network trust boundary (IP allow-list, VPC) gates the route.
+- **Mutating domain state synchronously in the outgoing emit path.** Mutate in the
+  mutation, THEN emit — delivery is async by design (rollback drops the queued send).
+- **Re-using the idempotency TTL as the provider's retry window.** Pick TTL ≥ 2×
+  the provider's max retry window so the dedup catches the slowest retry.

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

@@ -0,0 +1,16 @@
+// Api app config — first-class webhooks. Read by `voltro dev`.
+//
+// Webhooks are FILE-CONVENTION, not a plugins:[] entry — `*.webhook.tsx` files
+// are auto-discovered (the incoming `orders` receiver + the outgoing
+// `order.completed` event), and the bookkeeping tables come from
+// `webhookTables()` in database/schema.ts. The only wiring is the signing
+// secret in `.env` (VOLTRO_WEBHOOK_SECRET_ORDERS).
+//
+// `store: 'memory'` keeps first-run zero-infra; the durable delivery workflow
+// runs in-process. Swap to `store: 'postgres'` for cross-restart durability.
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+}

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

@@ -0,0 +1,49 @@
+// Schema for the {{projectName}} webhooks backend.
+//
+// `webhookTables()` contributes the framework's two bookkeeping tables —
+// `_voltro_webhook_targets` (who subscribed to an outgoing event) and
+// `_voltro_webhook_deliveries` (each delivery attempt). They're auto-migrated
+// alongside your own tables; you register them by exporting them here.
+
+import {
+  databaseHandle,
+  id,
+  integer,
+  table,
+  text,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+import { webhookTables } from '@voltro/plugin-webhooks/mixin'
+
+// ---------- 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 orders = table('orders', {
+  id:         id({ prefix: 'order' }),
+  sku:        text(),
+  totalCents: integer(),
+  status:     text().oneOf(['pending', 'fulfilled']).default('pending'),
+})
+  .with(tenant())
+  .reactive()
+
+export type Order = InferRow<typeof orders>
+
+// ---------- Webhook bookkeeping (framework-managed) ----------
+const [webhookTargets, webhookDeliveries] = webhookTables()
+export { webhookTargets, webhookDeliveries }
+
+export const database = databaseHandle({
+  actors, tenants, orders,
+  webhookTargets, webhookDeliveries,
+})

package/templates/apps/api-webhooks/events/order.completed.webhook.tsx

@@ -0,0 +1,22 @@
+// OUTGOING event — an event THIS app emits. External systems subscribe at
+// runtime via `ctx.webhooks.subscribe({ event: 'order.completed', url })`;
+// each subscriber is a row in `_voltro_webhook_targets`. When a handler calls
+// `useWebhooks(ctx).emit('order.completed', payload)`, the framework fans out
+// to every matching target through a DURABLE delivery workflow — HMAC-signing
+// the outbound request, retrying with backoff, honouring Retry-After. Each
+// attempt is recorded in `_voltro_webhook_deliveries`.
+
+import { defineOutgoingEvent } from '@voltro/plugin-webhooks'
+import { Schema } from 'effect'
+
+export default defineOutgoingEvent({
+  id:          'order.completed',
+  description: 'An order moved to "fulfilled" — payment captured, items shipped.',
+  payload: Schema.Struct({
+    orderId:    Schema.String,
+    tenantId:   Schema.String,
+    sku:        Schema.String,
+    totalCents: Schema.Number,
+  }),
+  version: 1,
+})

package/templates/apps/api-webhooks/mutations/orders.fulfill.mutation.server.ts

@@ -0,0 +1,37 @@
+// Create a fulfilled order, THEN emit the outgoing `order.completed` event.
+//
+// `ctx.workflows.start` / emit are post-commit safe inside a mutation: the row
+// commits first, then the event fans out to subscribed targets — so a rollback
+// never ships a webhook for an order that didn't persist. `emit` returns
+// immediately (the HTTP POSTs run in the background delivery workflow); the
+// `deliveries` array is one entry per matched target (empty until someone
+// subscribes via ctx.webhooks.subscribe).
+
+import type { AppContext } from '@voltro/runtime'
+import { useWebhooks } from '@voltro/plugin-webhooks'
+
+const execute = async (input: { sku: string; totalCents: number }, ctx: AppContext) => {
+  // status set explicitly — a column DEFAULT only fills in on a SQL store.
+  const row = await ctx.store.insert('orders', {
+    sku: input.sku, totalCents: input.totalCents, status: 'fulfilled',
+  })
+
+  const order = {
+    id:         row['id'] as string,
+    sku:        row['sku'] as string,
+    totalCents: row['totalCents'] as number,
+    status:     row['status'] as string,
+    tenantId:   row['tenantId'] as string,
+  }
+
+  // Fan out to every subscribed target (durable, signed, retried in the bg).
+  const webhooks = useWebhooks(ctx)
+  const { eventId, deliveries } = await webhooks.emit('order.completed', {
+    orderId: order.id, tenantId: order.tenantId, sku: order.sku, totalCents: order.totalCents,
+  })
+  console.log(`[webhook:emit] order.completed event=${eventId} → ${deliveries.length} target(s)`)
+
+  return order
+}
+
+export default execute

package/templates/apps/api-webhooks/mutations/orders.fulfill.mutation.ts

@@ -0,0 +1,15 @@
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const fulfillOrder = defineMutation({
+  name:   'orders.fulfill',
+  target: { table: 'orders', op: 'insert' },
+  input:  Schema.Struct({ sku: Schema.NonEmptyString, totalCents: Schema.Number }),
+  output: Schema.Struct({
+    id:         Schema.String,
+    sku:        Schema.String,
+    totalCents: Schema.Number,
+    status:     Schema.String,
+    tenantId:   Schema.String,
+  }),
+})

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

@@ -0,0 +1,28 @@
+{
+  "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-webhooks": "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-webhooks/queries/orders.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.orders.orderBy('createdAt', 'desc').limit(100)
+
+export default route

package/templates/apps/api-webhooks/queries/orders.list.query.ts

@@ -0,0 +1,15 @@
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listOrders = defineQuery({
+  name:   'orders.list',
+  source: 'orders',
+  input:  Schema.Struct({}),
+  output: Schema.Array(Schema.Struct({
+    id:         Schema.String,
+    sku:        Schema.String,
+    totalCents: Schema.Number,
+    status:     Schema.String,
+    tenantId:   Schema.String,
+  })),
+})

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

@@ -0,0 +1,6 @@
+{
+  "id": "api-webhooks",
+  "kind": "api",
+  "summary": "First-class webhooks both ways: a signature-verified INCOMING receiver (*.webhook.tsx, genericProvider HMAC) that rejects unsigned/forged requests before your handler runs, plus an OUTGOING defineOutgoingEvent a mutation emits to subscribed targets via a durable delivery workflow.",
+  "tags": ["api", "webhooks", "integrations", "hmac", "signature", "stripe", "events"]
+}

package/templates/apps/api-webhooks/tests/orders.fulfill.test.ts

@@ -0,0 +1,51 @@
+// Unit test with `@voltro/testing` — no database, no running server, no webhook
+// delivery. The `orders.fulfill` executor emits an outgoing `order.completed`
+// event via `useWebhooks(ctx).emit(...)` — that fans out through the webhooks
+// plugin's durable delivery workflow (real HTTP POSTs, retries, signing), which
+// is dispatch-time infrastructure the unit harness does NOT wire, so we do not
+// fake it. Instead we PIN the descriptor's wire contract and prove the tenant()
+// scoping on the `orders` table. 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 orders + webhook tables
+import { fulfillOrder } from '../mutations/orders.fulfill.mutation'
+
+describe('orders.fulfill descriptor', () => {
+  it('decodes a valid input and rejects a blank sku', () => {
+    const decode = Schema.decodeUnknownSync(fulfillOrder.input)
+    expect(decode({ sku: 'SKU-1', totalCents: 4200 })).toEqual({ sku: 'SKU-1', totalCents: 4200 })
+    // `sku: Schema.NonEmptyString` — an empty string fails the wire decode.
+    expect(() => decode({ sku: '', totalCents: 4200 })).toThrow()
+  })
+
+  it('encodes the output shape the client expects', () => {
+    const encode = Schema.encodeUnknownSync(fulfillOrder.output)
+    const wire = encode({
+      id: 'order_1', sku: 'SKU-1', totalCents: 4200, status: 'fulfilled', tenantId: 'acme',
+    })
+    expect(wire).toEqual({
+      id: 'order_1', sku: 'SKU-1', totalCents: 4200, status: 'fulfilled', tenantId: 'acme',
+    })
+  })
+})
+
+describe('orders tenant isolation', () => {
+  it('t2 never sees t1 orders (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ orders: [] }),
+    })
+    // Raw insert through the mixin store — tenant() auto-stamps tenantId=t1.
+    // `status` set explicitly (a column DEFAULT only fills on a SQL store).
+    const row = await ctx.store.insert('orders', { sku: 'SKU-1', totalCents: 4200, status: 'fulfilled' })
+    expect(row['tenantId']).toBe('t1')
+    expect(row['id'] as string).toMatch(/^order_/)
+
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.orders.descriptor))
+    expect(seenByT2).toHaveLength(0)
+    const seenByT1 = await ctx.store.query(database.orders.descriptor)
+    expect(seenByT1).toHaveLength(1)
+  })
+})