@voltro/cli 0.1.0

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

@@ -0,0 +1,100 @@
+# {{projectName}} / {{appName}}
+
+Voltro backend scaffold (template: **api-kv**).
+
+The **durable key-value** template. It demonstrates `ctx.kv` — the framework's
+storage primitive for state you **can't recompute** — on a small
+**external-event-sync** domain: a sync **cursor** (a watermark) and TTL-bounded
+**idempotency markers** that dedupe redelivered events. It boots with **zero
+infrastructure** (`store: 'memory'`).
+
+## The one idea
+
+Three storage primitives, three contracts — pick by what a loss costs you:
+
+| Primitive | Holds | If you lose it | Backend default |
+|---|---|---|---|
+| `ctx.cache` | recomputable derived views | free — recompute | memory (evicts for capacity) |
+| **`ctx.kv`** | **the cursor + idempotency markers** | **re-process / double-process** | **database (durable, never evicted)** |
+| `ctx.store` | the synced rows | re-fetchable from the source | your SQL store |
+
+A cursor is the textbook `ctx.kv` case: it isn't derived from anything you still
+have, so a cache (which evicts) is wrong and a hand-managed table row is
+overkill. This template shows why.
+
+## Boot
+
+```bash
+pnpm install                                  # at the repo root
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000
+# → ws://localhost:4000/ws
+```
+
+No env or services required. On `store: 'memory'`, `ctx.kv` runs on its
+`database` backend in-process — durable within the run, reset on restart.
+Switch `app.config.ts` to `store: 'postgres'` and the cursor + markers survive
+restarts and are shared across replicas. To put **just the KV** on Redis (a
+persistent one), set `kv: 'redis'` / `KV_BACKEND=redis` — the handler code does
+not change.
+
+## What it demonstrates
+
+| File | Primitive | `ctx.kv` surface |
+|---|---|---|
+| `app.config.ts`                        | app config | zero-infra boot; the optional `kv:` / `cache:` backend knobs. |
+| `database/schema.ts`                   | schema     | the `synced_events` rows (store) — deliberately NOT the cursor. |
+| `actions/sync.pull.action.*`           | action     | **`getOrElse`** (cursor) → **`has`** / **`set(…, { ttlMs })`** (markers) → **`set`** (advance cursor). |
+| `actions/sync.status.action.*`         | action (Effect) | **`yield* Kv`** — `getOrElse` (cursor) + **`list`** (count live markers). |
+| `actions/sync.reset.action.*`          | action     | **`delete`** (cursor) + **`list`** / **`delete`** (markers). |
+| `queries/events.list.query.*`          | query      | reactive stream of the synced ROWS (store, for contrast). |
+
+## The end-to-end flow
+
+1. **`sync.pull`** reads the durable cursor with `getOrElse` (default `0` on the
+   first-ever call), pulls the next page from the (simulated) upstream, and for
+   each event: `has(marker)` → skip if seen, else `store.insert` the row +
+   `set(marker, { ttlMs })`. Finally it `set`s the cursor to the new watermark.
+2. **`sync.status`** reads the cursor and `list`s the live markers.
+3. **`sync.reset`** `delete`s the cursor. A following `sync.pull` re-reads from
+   `0` but **skips everything** — the markers survive independently, so
+   idempotency holds across a cursor rewind. Pass `{ markers: true }` to also
+   drop the markers and force a full re-ingest.
+
+## Try it
+
+Over the rpc surface (a `voltro dev` web client, `POST /rpc`, or the inspect
+`invoke` endpoint):
+
+```jsonc
+{ "tag": "sync.pull",   "input": { "limit": 5 } }   // → { pulled: 5, skipped: 0, cursor: 5 }
+{ "tag": "sync.pull",   "input": { "limit": 5 } }   // → { pulled: 5, skipped: 0, cursor: 10 }
+{ "tag": "sync.status", "input": {} }               // → { cursor: 10, activeMarkers: 10 }
+{ "tag": "sync.reset",  "input": {} }               // → { cursorCleared: true, markersCleared: 0 }
+{ "tag": "sync.pull",   "input": { "limit": 5 } }   // → { pulled: 0, skipped: 5, cursor: 5 }  ← markers survived
+```
+
+Watch the synced rows stream in live via the `events.list` subscription (the
+dashboard's data tab, or any web client).
+
+## TTL & tenant namespacing
+
+- **TTL** — markers are written with `{ ttlMs }` (a 24h idempotency window).
+  Expiry is lazy: an expired marker reads as a miss and is dropped on the next
+  `has`/`get`. The cursor has **no** TTL — it's permanent until deleted.
+- **Tenant namespacing** — `ctx.kv` keys are app-global; the facade never
+  namespaces for you. Every key here folds in `ctx.request.subject.tenantId`
+  (`sync:${tenantId}:…`) so two tenants' cursors/markers never collide.
+
+## Notes
+
+- All primitives are **auto-discovered by file convention** — nothing is
+  registered in `app.config.ts`.
+- `action` / `query` keep the **descriptor / executor split**: the browser-safe
+  `*.ts` descriptor never imports `@voltro/database`, `@voltro/runtime`, or
+  `node:*`; the `.server.ts` executor does the work.
+- Durable KV has **two handler surfaces**, both wired in every runtime
+  (`voltro dev` AND `voltro serve`): the async **`ctx.kv`** facade (used by
+  `sync.pull` / `sync.reset`) and the Effect-native **`Kv`** service via
+  `yield* Kv` (used by `sync.status`). They share one resolved store, so pick by
+  whether your handler is async or an `Effect` — the state is identical.

package/templates/apps/api-kv/actions/sync.pull.action.server.ts

@@ -0,0 +1,75 @@
+// `sync.pull` — EXECUTOR (server-only, default export).
+//
+// The heart of the template: durable `ctx.kv` used for the two kinds of state
+// you CAN'T recompute in an external sync.
+//
+//   1. the CURSOR  — a watermark past everything already pulled. Lose it and
+//      you re-process (or skip) events. Read with getOrElse, advanced with set.
+//   2. the MARKERS — one per external id, so a redelivered event isn't ingested
+//      twice. Written with a TTL (a bounded idempotency window). has() checks
+//      one without deserializing.
+//
+// The event ROWS themselves go to `ctx.store` — they're re-fetchable from the
+// source, so a relational table is their home (query/join/report on them).
+
+import type { AppContext } from '@voltro/runtime'
+
+// Stand-in for a real upstream (a webhook backlog, a 3rd-party API page).
+// Deterministic + pure so the template boots with zero infra and no network —
+// event N has externalId `ext-N`. A real handler would `fetch()` here instead.
+const fetchSince = (sequence: number, limit: number) =>
+  Array.from({ length: limit }, (_unused, i) => {
+    const seq = sequence + i + 1
+    return {
+      externalId: `ext-${seq}`,
+      kind:       seq % 3 === 0 ? 'updated' : 'created',
+      payload:    JSON.stringify({ seq }),
+      sequence:   seq,
+    }
+  })
+
+// Idempotency window: how long a "seen" marker lives. Long enough to dedupe
+// redelivery, not forever — a bounded lifetime on an otherwise-durable store.
+const MARKER_TTL_MS = 24 * 60 * 60_000 // 24h
+
+const execute = async (input: { limit?: number }, ctx: AppContext) => {
+  // KV keys are app-global — fold the tenant in so two tenants never collide.
+  const tenantId = ctx.request.subject.tenantId ?? 'anon'
+  const cursorKey = `sync:${tenantId}:cursor`
+  const limit = Math.min(input.limit ?? 5, 50)
+
+  // Durable cursor — getOrElse writes the default (0) ONLY on a genuine
+  // first-run miss; on every later call it returns the stored watermark.
+  const cursor = await ctx.kv.getOrElse<number>(cursorKey, () => 0)
+
+  let pulled = 0
+  let skipped = 0
+  let highest = cursor
+
+  for (const evt of fetchSince(cursor, limit)) {
+    const markerKey = `sync:${tenantId}:seen:${evt.externalId}`
+    if (await ctx.kv.has(markerKey)) {
+      // Already ingested within the TTL window — the source redelivered it.
+      skipped++
+    } else {
+      await ctx.store.insert('synced_events', {
+        externalId: evt.externalId,
+        kind:       evt.kind,
+        payload:    evt.payload,
+        sequence:   evt.sequence,
+        tenantId,
+      })
+      // Mark seen, with a TTL. Value carries the sequence for traceability.
+      await ctx.kv.set(markerKey, evt.sequence, { ttlMs: MARKER_TTL_MS })
+      pulled++
+    }
+    highest = Math.max(highest, evt.sequence)
+  }
+
+  // Advance the durable watermark past everything we just saw.
+  await ctx.kv.set(cursorKey, highest)
+
+  return { pulled, skipped, cursor: highest }
+}
+
+export default execute

package/templates/apps/api-kv/actions/sync.pull.action.ts

@@ -0,0 +1,25 @@
+// `sync.pull` — DESCRIPTOR (browser-safe: schema + name only; NO
+// node/database/server imports — the codegen pulls this into the client
+// rpcGroup bundle).
+//
+// Pull the next page of events from the (simulated) upstream. This is an
+// ACTION, not a mutation/query: it does arbitrary imperative work and returns
+// a computed summary rather than a single optimistic row or a reactive table
+// scan. The durable `ctx.kv` cursor + idempotency markers live in the
+// executor (`.server.ts`).
+
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const syncPull = defineAction({
+  name: 'sync.pull',
+  input: Schema.Struct({
+    // How many upstream events to pull this call (default 5, capped in the executor).
+    limit: Schema.optional(Schema.Int.pipe(Schema.greaterThan(0))),
+  }),
+  output: Schema.Struct({
+    pulled:  Schema.Int, // newly ingested (marker written)
+    skipped: Schema.Int, // already seen within the idempotency window
+    cursor:  Schema.Int, // the durable watermark after this call
+  }),
+})

package/templates/apps/api-kv/actions/sync.reset.action.server.ts

@@ -0,0 +1,25 @@
+// `sync.reset` — EXECUTOR (server-only, default export).
+//
+// Shows the delete side of the KV surface: delete(key) → boolean (did it
+// exist?), and list(prefix) + delete() to sweep a set of keys. `ctx.kv.clear()`
+// would drop this app's ENTIRE KV namespace in one call — too broad here, since
+// we only want this tenant's sync keys.
+
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (input: { markers?: boolean }, ctx: AppContext) => {
+  const tenantId = ctx.request.subject.tenantId ?? 'anon'
+
+  const cursorCleared = await ctx.kv.delete(`sync:${tenantId}:cursor`)
+
+  let markersCleared = 0
+  if (input.markers) {
+    for (const key of await ctx.kv.list(`sync:${tenantId}:seen:`)) {
+      if (await ctx.kv.delete(key)) markersCleared++
+    }
+  }
+
+  return { cursorCleared, markersCleared }
+}
+
+export default execute

package/templates/apps/api-kv/actions/sync.reset.action.ts

@@ -0,0 +1,22 @@
+// `sync.reset` — DESCRIPTOR (browser-safe).
+//
+// Rewind the sync. By default it clears ONLY the cursor — a following
+// `sync.pull` then re-reads from the start but SKIPS everything, because the
+// idempotency markers survive independently (proof the two KV concerns don't
+// depend on each other). Pass `markers: true` to also drop the markers, which
+// makes the next `sync.pull` re-ingest from scratch.
+
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const syncReset = defineAction({
+  name: 'sync.reset',
+  input: Schema.Struct({
+    // Also delete the idempotency markers (default: keep them).
+    markers: Schema.optional(Schema.Boolean),
+  }),
+  output: Schema.Struct({
+    cursorCleared:  Schema.Boolean, // did a cursor exist?
+    markersCleared: Schema.Int,     // how many markers were dropped
+  }),
+})

package/templates/apps/api-kv/actions/sync.status.action.server.ts

@@ -0,0 +1,28 @@
+// `sync.status` — EXECUTOR (server-only, default export), written in EFFECT mode.
+//
+// The same durable KV, reached the Effect-native way: `yield* Kv` from
+// `@voltro/kv` instead of the async `ctx.kv` facade. The framework provides the
+// `Kv` service to every handler runtime in BOTH boot paths (`voltro dev` and
+// `voltro serve`), so this resolves identically in dev and prod. The methods
+// mirror the facade but return `Effect`s (get yields an `Option`; the rest yield
+// plain values). Pick whichever style fits — an async handler would use
+// `ctx.kv` exactly as `sync.pull` does.
+
+import { Effect } from 'effect'
+import { Kv } from '@voltro/kv'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const kv = yield* Kv
+    const tenantId = ctx.request.subject.tenantId ?? 'anon'
+
+    const cursor = yield* kv.getOrElse(`sync:${tenantId}:cursor`, () => 0)
+    // list(prefix) → every live (non-expired) key under the prefix — here, the
+    // outstanding idempotency markers for this tenant.
+    const markers = yield* kv.list(`sync:${tenantId}:seen:`)
+
+    return { cursor, activeMarkers: markers.length }
+  })
+
+export default execute

package/templates/apps/api-kv/actions/sync.status.action.ts

@@ -0,0 +1,17 @@
+// `sync.status` — DESCRIPTOR (browser-safe).
+//
+// Read-only view of the durable sync state: where the cursor sits and how many
+// idempotency markers are still live. The executor is written in Effect mode
+// (`yield* Kv`) to show the Effect-native surface alongside the async `ctx.kv`.
+
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const syncStatus = defineAction({
+  name: 'sync.status',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    cursor:        Schema.Int, // the durable watermark
+    activeMarkers: Schema.Int, // idempotency markers not yet expired
+  }),
+})

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

@@ -0,0 +1,48 @@
+// Backend app for the {{projectName}} project. Read by `voltro dev`.
+//
+// This is the DURABLE KEY-VALUE template. It demonstrates `ctx.kv` — the
+// framework's second storage primitive, for state you CAN'T recompute — on a
+// small external-event-sync domain. `ctx.kv` is the opposite contract to
+// `ctx.cache`: entries are NEVER evicted for capacity; they live until you
+// delete them or their (optional) TTL lapses.
+//
+// The three storage primitives, side by side (the whole point of this template):
+//   • ctx.store — the relational rows you sync in (queryable, joinable). LOSS = re-fetchable.
+//   • ctx.kv    — the sync CURSOR + idempotency MARKERS. LOSS = re-process / double-process. Durable.
+//   • ctx.cache — recomputable derived views. LOSS = free (recompute). Not used here; see the api-data-advanced template.
+//
+// What's in here (all auto-discovered by file convention — nothing is
+// registered in this config):
+//
+//   database/schema.ts                — `syncedEvents` table (the rows we ingest)
+//   actions/sync.pull.action.*        — THE STAR: getOrElse(cursor) → dedupe via
+//                                       has()/set(marker,{ttlMs}) → insert row →
+//                                       set(cursor). The full write surface.
+//   actions/sync.status.action.*      — Effect-mode handler (`yield* Kv`): read
+//                                       the cursor + count markers via list().
+//   actions/sync.reset.action.*       — delete(cursor) + list()/delete() the markers.
+//   queries/events.list.query.*       — reactive list of the synced rows (store, not kv).
+//
+// `store: 'memory'` keeps boot zero-infra: `ctx.kv` runs on the `database`
+// backend (the framework's `_voltro_kv` table) which, on the memory store, is
+// in-process — durable within the run, reset on restart. Switch to `'postgres'`
+// and the cursor/markers survive restarts and are shared across replicas.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Typed environment — declared once, validated at boot (fail-fast).
+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,
+  // OPTIONAL infra knobs (both default to a zero-infra backend):
+  //   kv:    'redis' — durable ctx.kv on a PERSISTENT redis (default 'database').
+  //   cache: 'redis' — distributed query/result cache (this template uses no cache).
+  // Env `KV_BACKEND` / `CACHE_BACKEND` override. See docs → Caching → Key-value backends.
+  // kv:    'redis' as const,
+  // cache: 'redis' as const,
+  env,
+}

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

@@ -0,0 +1,62 @@
+// Schema for the {{projectName}} backend.
+//
+// Tables are auto-discovered: every exported `table(...)` here (or in any
+// `*.entity.ts` / `*.schema.ts` file) is registered by `voltro dev`.
+// `actors` + `tenants` are the framework's core tables the `tenant()` /
+// `audit()` mixins reference, so they must be declared.
+//
+// IMPORTANT contrast (the whole reason this template exists): the ROWS below
+// live in `ctx.store` — they're re-fetchable from the external source, so a
+// relational table is the right home. The sync CURSOR and the idempotency
+// MARKERS do NOT live here — they're state you can't recompute, so they live
+// in `ctx.kv` (durable, never evicted). Don't model a cursor as a table row
+// you hand-manage; that's exactly what `ctx.kv` is for.
+
+import {
+  databaseHandle,
+  id,
+  integer,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// ---------- Core tables (required by the tenant / audit 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 — the events we ingest from the source ----------
+
+export const syncedEvents = table('synced_events', {
+  id:         id({ prefix: 'evt' }),
+  // The external id we deduped on — carried through so you can trace a row
+  // back to its source record.
+  externalId: text(),
+  kind:       text(),
+  payload:    text(),
+  // The source sequence number this row came from (the cursor advances past it).
+  sequence:   integer(),
+})
+  // tenant() pulls audit() transitively → tenantId + created/updated columns,
+  // auto-stamped by the runtime from the caller's subject.
+  .with(tenant())
+  // Opt into the matcher engine so the `events.list` subscription wakes on
+  // every insert.
+  .reactive()
+
+export type SyncedEvent = InferRow<typeof syncedEvents>
+
+export const database = databaseHandle({ actors, tenants, syncedEvents })

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

@@ -0,0 +1,28 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/kv": "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-kv/queries/events.list.query.server.ts

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

package/templates/apps/api-kv/queries/events.list.query.ts

@@ -0,0 +1,23 @@
+// `events.list` — DESCRIPTOR (browser-safe).
+//
+// A reactive subscription over the synced ROWS (which live in `ctx.store`, not
+// `ctx.kv`). This is the contrast the template is built around: the rows are
+// relational data you query/stream; the cursor + markers that produced them are
+// durable KV. The runtime AND-merges the caller's tenant scope via the
+// `tenant()` mixin — no manual `eq('tenantId', …)` needed.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listEvents = defineQuery({
+  name: 'events.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id:         Schema.String,
+    externalId: Schema.String,
+    kind:       Schema.String,
+    sequence:   Schema.Number,
+    tenantId:   Schema.String,
+    createdAt:  Schema.Date,
+  }),
+})

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

@@ -0,0 +1,6 @@
+{
+  "id": "api-kv",
+  "kind": "api",
+  "summary": "Durable key-value state (`ctx.kv`) on an external-event-sync domain: a sync cursor you can't recompute, TTL-bounded idempotency markers to dedupe redelivered events, and the store-vs-kv-vs-cache contrast. Exercises the full ctx.kv surface (getOrElse / has / set+TTL / set / list / delete) in async AND Effect handlers.",
+  "tags": ["api", "kv", "key-value", "durable", "state", "idempotency", "cursor", "sync"]
+}

package/templates/apps/api-kv/tests/sync.test.ts

@@ -0,0 +1,103 @@
+// Unit tests with `@voltro/testing` — the headline of this template is the
+// durable KV behavior, so we exercise it thoroughly against the REAL in-memory
+// `ctx.kv` that `makeTestContext` provides (same contract as the production KV:
+// durable, TTL-honouring, never capacity-evicted).
+//
+//   - `sync.pull` reads/advances a durable cursor and writes per-event
+//     idempotency markers → asserted across TWO calls (the cursor must carry
+//     over so the second call continues past it, not re-pull from 0).
+//   - `sync.reset` clears the cursor (and optionally the markers).
+//
+// `sync.status` is written in Effect mode (`yield* Kv` from `@voltro/kv`), which
+// needs the `Kv` service layer provided — an integration concern, not a plain
+// unit run — so it is intentionally not driven here.
+//
+// The simulated upstream is deterministic: event N has externalId `ext-N` and
+// sequence N, so pulling `limit` fresh events advances the cursor by exactly
+// `limit`. Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema'   // registers synced_events / actors / tenants
+import syncPull from '../actions/sync.pull.action.server'
+import syncReset from '../actions/sync.reset.action.server'
+
+const subject = { type: 'user', id: 'user_1', tenantId: 'acme' } as const
+
+describe('sync.pull (durable cursor + idempotency markers)', () => {
+  it('first pull ingests N events, inserts the rows, and advances the cursor to N', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ synced_events: [] }) })
+
+    const result = await syncPull({ limit: 3 }, ctx)
+
+    expect(result.pulled).toBe(3)
+    expect(result.skipped).toBe(0)
+    expect(result.cursor).toBe(3)
+
+    // The event rows landed in the relational store, tenant-stamped.
+    const rows = await ctx.store.query(database.syncedEvents.descriptor)
+    expect(rows).toHaveLength(3)
+    expect(rows.every((r) => r['tenantId'] === 'acme')).toBe(true)
+    expect((rows.map((r) => r['externalId']) as ReadonlyArray<string>).sort()).toEqual([
+      'ext-1',
+      'ext-2',
+      'ext-3',
+    ])
+
+    // The durable cursor persisted in ctx.kv.
+    expect(await ctx.kv.get<number>('sync:acme:cursor')).toBe(3)
+  })
+
+  it('a second pull continues PAST the cursor rather than re-pulling from 0', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ synced_events: [] }) })
+
+    const first = await syncPull({ limit: 2 }, ctx)
+    expect(first.cursor).toBe(2)
+
+    const second = await syncPull({ limit: 2 }, ctx)
+
+    // Continues at 3..4 — all fresh (distinct externalIds), none skipped.
+    expect(second.pulled).toBe(2)
+    expect(second.skipped).toBe(0)
+    expect(second.cursor).toBe(4)
+
+    const rows = await ctx.store.query(database.syncedEvents.descriptor)
+    expect(rows).toHaveLength(4) // 2 + 2, no duplicates
+    expect((rows.map((r) => r['sequence']) as ReadonlyArray<number>).sort((a, b) => a - b)).toEqual([
+      1, 2, 3, 4,
+    ])
+  })
+})
+
+describe('sync.reset', () => {
+  it('clears the durable cursor so the next pull restarts from 0', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ synced_events: [] }) })
+
+    await syncPull({ limit: 2 }, ctx)
+    expect(await ctx.kv.get<number>('sync:acme:cursor')).toBe(2)
+
+    const reset = await syncReset({}, ctx)
+    expect(reset.cursorCleared).toBe(true)        // the key existed and was removed
+    expect(await ctx.kv.has('sync:acme:cursor')).toBe(false)
+
+    // Cursor gone → the next pull re-reads from the getOrElse default (0).
+    const afterReset = await syncPull({ limit: 1 }, ctx)
+    expect(afterReset.cursor).toBe(1)
+  })
+
+  it('reports cursorCleared=false when there was no cursor to clear', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ synced_events: [] }) })
+    const reset = await syncReset({}, ctx)
+    expect(reset.cursorCleared).toBe(false)
+    expect(reset.markersCleared).toBe(0)
+  })
+
+  it('sweeps the idempotency markers when { markers: true }', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ synced_events: [] }) })
+    await syncPull({ limit: 3 }, ctx) // writes 3 seen-markers
+
+    const reset = await syncReset({ markers: true }, ctx)
+    expect(reset.markersCleared).toBe(3)
+    expect(await ctx.kv.list('sync:acme:seen:')).toHaveLength(0)
+  })
+})

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

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

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

@@ -0,0 +1,46 @@
+# {{projectName}} / {{appName}}
+
+Voltro API scaffold (template: **api-moderation**) — pre-commit content
+moderation with `@voltro/plugin-moderation`.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000  (store: memory — zero infra)
+```
+
+## What this shows
+
+- **Two actions, two outcomes** — `moderationPlugin` checks named input fields
+  on the rpc interceptors, BEFORE the handler:
+  - **block** (`posts.create`, fields `title`/`body`): banned content fails
+    typed `ContentRejected` and the write **never commits**.
+  - **flag** (`comments.create`, field `body`): the comment IS written, but
+    flagged for review (the dashboard's **Moderation** panel surfaces the queue).
+- **Pluggable provider** — `keywordProvider([...])` is a zero-dep deny-list;
+  `aiProvider()` is an optional LLM classifier (fails open). Swap one for the
+  other in `app.config.ts` — the rules don't change.
+- **In-handler redaction** — when you need to rewrite rather than reject, the
+  `moderate(text)` helper returns a verdict you can act on inside a handler
+  (the interceptor can't rewrite input).
+
+## Try it
+
+```bash
+# banned word in a post → blocked, nothing written:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"posts.create","input":{"title":"hi","body":"buy cheap spam now"}}'
+# → { ok:false, error:{ _tag:"ContentRejected", reason:"matched denied term(s): spam" } }
+
+# clean post → written:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"posts.create","input":{"title":"hi","body":"a normal post"}}'
+# → { ok:true, result:{ id, … } }
+
+# banned word in a comment → WRITTEN but flagged (flag rule doesn't block):
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"comments.create","input":{"body":"this is spam"}}'
+# → { ok:true, result:{ id, … } }   (and queued for review)
+```