@voltro/cli 0.30.1 → 0.31.0

package/templates/agent-docs/plugins/tinybird.md

@@ -0,0 +1,92 @@
+# Tinybird
+
+> Hosted-ClickHouse AnalyticsSink over Tinybird's Events API + Pipes — pay-as-you-go OLAP without operating a cluster.
+
+
+
+---
+
+<!-- source: en/plugins/tinybird.md -->
+## Tinybird
+
+_Hosted-ClickHouse AnalyticsSink over Tinybird's Events API + Pipes — pay-as-you-go OLAP without operating a cluster._
+
+`@voltro/plugin-tinybird` is the hosted-ClickHouse `AnalyticsSink` — it ingests
+via Tinybird's **Events API** and reads via **Pipes** (saved SQL endpoints), so
+you get ClickHouse-grade OLAP on a pay-as-you-go service instead of operating a
+cluster yourself. It's for teams that ALREADY have a Tinybird workspace; if you
+want a zero-setup external OLAP sink that owns its own schema, use
+[`@voltro/plugin-clickhouse`](/docs/plugins/clickhouse) instead. For the shared
+`AnalyticsSink` API and the `useAnalytics()` read methods, see
+[Analytics & warehouse sinks](/docs/plugins/analytics).
+
+## Install
+
+```
+pnpm add @voltro/plugin-tinybird
+```
+
+## Wiring
+
+```ts
+// app.config.ts
+import { tinybirdAnalytics } from '@voltro/plugin-tinybird'
+
+export default {
+  type:      'api' as const,
+  name:      'myApi',
+  store:     'postgres' as const,
+  analytics: tinybirdAnalytics({
+    token:      process.env.TINYBIRD_TOKEN!,
+    region:     'eu',                 // 'eu' | 'us-east' | 'us-west' | 'asia-southeast'
+    datasource: 'voltro_events',
+  }),
+}
+```
+
+`track()` POSTs events to the Datasource via the Events API; `aggregate` /
+`timeseries` / `topN` call your Pipes. There's no boot-time initialize — the
+Datasource is auto-created on the first event, and the Pipes must already exist.
+The trade-off is **deferred failure**: a bad token or missing Pipe boots clean
+and surfaces as a typed `AnalyticsError` on the first call.
+
+## Required Pipes
+
+The plugin EXPECTS three canonical Pipes to exist in your workspace (create them
+once via the `tb` CLI or the UI). It does NOT synthesize them — Tinybird's
+`.pipe` DSL is too rich to generate from a generic spec:
+
+- `events_aggregate` — params: `event`, `from`, `to`, `metric_expr`, `filter_sql`
+- `events_timeseries` — same + `bucket_fn`
+- `events_topn` — same + `group_expr`, `limit`
+
+## Options
+
+`tinybirdAnalytics(options)`:
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `token` | `string` | — (**required**) | Tinybird workspace token. |
+| `region` | `string` | `'eu'` | `'eu'` / `'us-east'` / `'us-west'` / `'asia-southeast'`. Selects the API base URL. |
+| `apiUrl` | `string` | derived from `region` | Custom API base URL — overrides `region` (self-hosted Tinybird or preview envs). |
+| `datasource` | `string` | `'voltro_events'` | The plugin POSTs events to `/v0/events?name=<datasource>`. |
+| `pipes` | `{ aggregate?, timeseries?, topN? }` | the three canonical names | Override Pipe names if your team uses a different convention. |
+
+`datasource` + the Pipe names are validated as identifiers at boot (they're
+interpolated into request URLs), so a path-traversal name fails loudly rather
+than building a bad URL.
+
+> **Connection details come from `options`, not env.** The plugin reads no
+> `TINYBIRD_*` variables itself — the example wires `process.env` into the
+> options. Use `@voltro/env`'s `defineEnv` to declare the token as a secret.
+
+## Provider escape hatch
+
+For direct Pipe access beyond the cross-provider contract, import the `Tinybird`
+Tag and `yield*` it for the configured client. Using the Tag binds your handler
+to Tinybird — stay on `useAnalytics()` for provider-portable code.
+
+## See also
+
+- [Analytics & warehouse sinks](/docs/plugins/analytics) — the shared
+  `AnalyticsSink` contract, the `useAnalytics()` read API, and `composeAnalytics`.

package/templates/agent-docs/plugins/versioning.md

@@ -0,0 +1,226 @@
+# Row versioning
+
+> Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries.
+
+
+
+---
+
+<!-- source: en/plugins/versioning.md -->
+## Row versioning
+
+_Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries._
+
+`@voltro/plugin-versioning` keeps a complete value history of selected tables. Where [`audit()`](/docs/plugins/audit) records *who* changed a row and *when*, versioning records *what* — a full snapshot of the row on every insert / update / delete — and lets you read any row **as of** a past instant. It rides the framework's post-commit ChangeEvent tap, so it captures every write that goes through the store with no per-handler wiring.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { versioningPlugin } from '@voltro/plugin-versioning'
+
+export default {
+  type: 'api' as const, name: 'api',
+  plugins: [versioningPlugin({})],
+}
+```
+
+Every committed change to a listed table appends a row to `_voltro_row_history` (`tableName`, `rowId`, monotonic `version`, `op`, the full `data` snapshot, `changedBy`, `changedAt`, `traceId`, `subjectId`, `procedure`).
+
+
+### What gets versioned — opt OUT, not in
+
+`versioningPlugin({})` covers **every table your app declares**. There is no list to write and none to maintain.
+
+```ts
+versioningPlugin({})                              // every app table
+versioningPlugin({ exclude: [domainEvents] })     // opt one out
+versioningPlugin({ include: [aiFlowsTable] })     // add a PLUGIN's table
+```
+
+Both take table **values**, not names — a misspelling is a compile error at the call site, exactly as with `reference(() => table)`.
+
+That shape replaced a `tables: string[]` list, and both of its failure modes were silent: you listed six tables, forgot the seventh, and nothing ever told you its history was missing; and nothing cross-checked the strings, so `'invoces'` recorded nothing forever while the plugin reported itself active at boot. Forgetting is now the safe direction.
+
+**Framework- and plugin-owned tables (`_voltro_*`, `cluster_*`) are OUT by default.** There are 34 of them, and the busiest — the CDC log, the event log, the undo log, workflow events, webhook rate windows — are append-only. A full row snapshot per write there is the history of a history, at the highest write rate in the system. Name one in `include` to version it anyway; that also works for a plugin table your app never declares, which is the supported way to version one.
+
+A table named in both `include` and `exclude` throws at construction — only you know which was the mistake.
+
+**Check the boot line once after upgrading.** It prints the RESOLVED count, not the configured one:
+
+```txt
+versioning active · tables: 41 · historyTable: _voltro_row_history · retentionDays: 365
+```
+
+If 41 surprises you, `exclude` is the knob. The retention sweep (`VOLTRO_ROW_HISTORY_TTL_HOURS`) still bounds age.
+
+## What this is NOT — the grain
+
+Versioning records **row changes, not domain events**. One entry per row per write, named by *table*. If your product has a user-facing audit feature whose entries are named after an aggregate root — one `Team` event for a call that writes `teams` + `roles` + `userTeams` + `userTeamRoles` — this is the layer **underneath** that, not a replacement for it.
+
+The distinction is worth reading before you plan a migration onto it. A consumer with 331 hand-written audit calls set out to delete them all in favour of this tap and found three hours in that the grain is different: a table-keyed tap does not produce an aggregate-keyed trail with better coverage, it produces a *different artifact*. Their conclusion — and ours — is that the two compose:
+
+- **versioning** answers "what did row R look like before, and after" — for every write, whether or not anyone remembered to record it;
+- an **aggregate trail** (the [audit sink](/docs/plugins/audit), one row per mutation invocation) answers "what business operation happened, to which entity, and did it succeed";
+- `traceId` joins them, so one request reads as one story.
+
+What the tap *does* remove is the silent-data-loss failure mode. A forgotten hand-written call used to mean the change was recorded nowhere; with the tap it costs the aggregate *name*, not the record.
+
+
+### `procedure` — which call, not just which trace
+
+A row diff carries no intent. The same `DELETE` on a join table is a member being
+removed, a team being deleted, or a membership expiring — and `before`/`after`
+cannot separate them, because the difference is not in the data.
+
+So the history row records the **rpc tag** of the call that caused it:
+
+```
+tableName  userTeams
+rowId      ut_7f2…
+op         delete
+procedure  teams.removeSubTeamMember     ← which call it WAS
+traceId    4bf92f35…                     ← which call it was
+subjectId  usr_anna
+```
+
+`traceId` joins this row to everything else that happened in the same request;
+`procedure` says what the request was trying to do. A UI rendering history for a
+human needs the second one, and no diff can supply it.
+
+Absent for a write with no procedure behind it — a seed, a `*.startup.tsx`, a
+migration — with the same meaning as an absent `traceId`.
+
+## The correlation bridge — joining *what changed* to *who called*
+
+`ChangeEvent` carries the calling `traceId` and `subjectId`, so a history row can be joined to the [audit sink](/docs/plugins/audit) row for the **same call**. Before this, both trails existed and shipped and nothing connected them: versioning knew what changed, the audit sink knew who called and whether they were refused, and no key spanned the two.
+
+```ts
+import { historyByTrace, historyBySubject } from '@voltro/plugin-versioning'
+
+// What did this call change? (`byTrace`)
+const touched = await historyByTrace(ctx.store, traceId, ctx.request.subject.tenantId)
+
+// What has this actor changed, most recent first? (`bySubject`, bounded)
+const byActor = await historyBySubject(ctx.store, actorId, ctx.request.subject.tenantId, 100)
+```
+
+Both are **tenant-scoped** like `rowHistory` — pass the caller's `tenantId`, and `undefined` skips the filter for system/admin paths only. `historyBySubject` takes a `limit` (default 100) because an actor's history is unbounded, and an entry point that returns all of it is one you call once in production and never again. Effect handlers use `historyByTraceEffect` / `historyBySubjectEffect`.
+
+Both questions were previously unanswerable at any speed — `byRow` is the only other index, and entering through it means *already knowing which row you are asking about*, which is the wrong way round during an incident.
+
+**`subjectId` is the CALLER, and it is not the same claim as `changedBy`.** `changedBy` falls back to the row's own `audit()` stamp, which is a proxy with three failure modes: it only exists on tables carrying `audit()`; it names the actor but never the call, so two writes by one person a second apart are indistinguishable; and it is `null` for every write through `AuthStrategyInput.store` / `PluginHttpRouteRequest.store`, since audit stamping is part of the Subject-dependent half the [boot store](/docs/authentication/strategies) omits. A login route writes through exactly that seam. `subjectId` has none of the three, so it is preferred and the stamp is the fallback.
+
+**Absent means the write had no request behind it** — a seed, a `*.startup.tsx`, a schedule, a workflow step — or that it arrived from another replica, where stamping the local ambient trace would attribute a remote write to a local call. Treat "neither field" as *system*, unambiguously.
+
+## `timing` — when the history row is written
+
+```ts
+versioningPlugin({ timing: 'in-transaction' })
+```
+
+| | `'post-commit'` (default) | `'in-transaction'` |
+|---|---|---|
+| When | after the domain write commits | inside the same transaction |
+| Can lose an entry | yes — a crash in the window between COMMIT and the write | no |
+| Can fail your mutation | no | **yes**, if the history insert fails |
+| Cost | none on the write path | **two round-trips** + longer lock hold, per covered write |
+
+**Two round-trips, not one.** Each covered write reads `MAX(version)` for the row and then appends. The read shipped as an omission — the recorder wrote a constant `version: 0` and a design note argued that ordering could come from `changedAt`. It could not: `changedAt` is millisecond-resolution, so two writes to one row inside one transaction tie routinely, and `rowAsOf` / `diffVersions` read the NUMBER. A trail that is merely late can be reasoned about; a mis-ordered one cannot. Budget accordingly — a mutation writing 3 covered rows pays ~6 round-trips of history overhead, and a bulk update over N rows pays 2N, as lock-hold time.
+
+Version numbers are 1-based in **both** timings, so switching `timing` does not shift them.
+
+**What `'in-transaction'` promises:** if the change committed, the entry is there. Post-commit cannot promise that — between COMMIT and the forked write there is a window, and a process that dies inside it leaves the change permanent and the trail silent. You then cannot tell *"no entry because nothing happened"* from *"no entry because we crashed"*, which is what makes a lossy trail useless as evidence. Retrying does not help: the process that would retry is the one that died.
+
+**The price is not optional.** That guarantee is only obtainable by being willing to REFUSE. When the history insert fails — disk, lock timeout, constraint, dropped connection — a transaction offers exactly two outcomes: the mutation fails with it, or the error is swallowed and the change commits without its entry, which is post-commit's hole with the cost already paid. There is no third option, so a rare, explained rejection is the shape of the guarantee rather than a defect.
+
+**Why the default is still `'post-commit'`.** In-transaction makes `_voltro_row_history` a hard dependency of every write path it covers: its availability becomes your write path's availability, and every covered write holds its locks longer. Post-commit loses at worst *one entry*; in-transaction can, at worst, stop writes to the covered tables entirely. For a compliance trail the second trade is the right one — for the undo / time-travel use this plugin also serves, it is not.
+
+### Under CDC, and inside a transaction
+
+Both work, and both took a fix. The event a subscriber receives under
+`changeStrategy: 'cdc'` (the default on postgres and mariadb) is rebuilt from a
+NOTIFY payload or a binlog row image, neither of which can carry a request
+context — the write path now hands its identity across that boundary explicitly.
+A write made on ANOTHER replica has no local identity to hand over and arrives
+with neither field, which is the correct answer: absent means *no request
+context on this replica*, not *nobody knows*.
+
+Inside a transaction the identity used to be lost outright, which mattered more
+than it sounds: framework mutations are auto-transactional, so that was every
+handler write.
+
+### Ordering, when you join to the audit sink
+
+With `'in-transaction'` the version rows commit **before** the rpc interceptor records the call's outcome — the audit row is what says whether the call succeeded, so it can only be written once that is known. A reader joining on `traceId` may therefore briefly see version rows with no audit-sink row.
+
+That is the correct order, not a race to engineer around: the change is durable, and the verdict on it arrives a moment later. Read the audit row as the authority on *outcome*, never as proof that a change happened.
+
+### Two limits that hold in BOTH timings
+
+- **`store.raw()` is absent from the trail.** The framework does not parse hand-written SQL, so a raw write produces no change event and no history row. Enabling `'in-transaction'` does not make coverage total.
+- **A write made outside a transaction is recorded immediately after, not atomically.** A bare `ctx.store.updateMany(...)` is not in a transaction; framework mutations are auto-transactional, so a handler's writes do get the guarantee.
+
+`'in-transaction'` requires a SQL store and **refuses the in-memory one at boot** rather than silently doing nothing — `memory` is the default dev store, and an option that appears to work where it is cheapest to try and stops working where it matters is worse than one that says so.
+
+### What a snapshot contains — `.encrypted()` vs `.serverOnly()`
+
+**`.encrypted()` columns are kept, and they are ciphertext.** A snapshot stores exactly what the source column stores:
+
+```json
+{ "id": "sess_1", "secret": "enc:v1:a56iziEV9THLhzmJ:Vk0ux+0bECleTLBJkCa0Rg==:3AtMwP" }
+```
+
+So versioning a table with encrypted columns **does not widen exposure** — the history is exactly as readable as the row it came from. This is worth stating because "full row snapshot" reads alarming next to `.encrypted()`, and the cautious reader excludes the table. One did, and only found out by measuring.
+
+**`.serverOnly()` columns ARE withheld**, and for a sharper reason than "a second copy": `crud.*` strips those columns from every row it returns, and a snapshot would smuggle the value back past that stripping inside a `json()` blob, where no column-level rule applies. A marker meaning *never serialize this to a client* cannot survive being re-exported through a different column's contents.
+
+The withheld names are listed under `data._omitted`, so a reader can tell *"this column was withheld"* from *"this column did not exist then"*:
+
+```json
+{ "id": "sess_1", "label": "mac", "_omitted": ["tokenHash"] }
+```
+
+`.sensitive()` is not involved either way — it is an export-masking marker for values that are legitimately readable in the app.
+## Querying the timeline
+
+```ts
+import { rowHistory, rowAsOf } from '@voltro/plugin-versioning'
+
+// Every version of a row, oldest → newest — TENANT-SCOPED to the caller:
+const history = await rowHistory(ctx.store, 'posts', postId, ctx.request.subject.tenantId)
+// history[n] = { version, op, data, changedBy, changedAt, tenantId }
+
+// The row's value as it was at a past moment (null if it didn't exist / was deleted then):
+const lastMonth = await rowAsOf(ctx.store, 'posts', postId, ctx.request.subject.tenantId, new Date('2026-05-01'))
+```
+
+Pass the caller's `tenantId` — reads are **tenant-scoped**: a row's value timeline is visible only to its own tenant (a `null`-tenant row from an untenanted source table stays visible to all; an anonymous caller sees only those). `rowAsOf` returns the latest version at or before the instant; a version that was a delete reads back as `null` (the row wasn't present then). Pure helpers (`selectAsOf`, `nextVersionNumber`, `diffSnapshots`) are exported + unit-tested. Effect handlers use the twins `rowHistoryEffect` / `rowAsOfEffect` (and `restoreAsOfEffect` / `diffVersionsEffect`) instead of hand-wrapping.
+
+## Restore & diff
+
+```ts
+import { restoreAsOf, diffVersions } from '@voltro/plugin-versioning'
+
+// Roll the LIVE row back to its state at a past instant (tenant-scoped like
+// rowAsOf — no visible state then ⇒ null, nothing written). The restore goes
+// through the store, so it is recorded as a NEW version.
+const restored = await restoreAsOf(ctx.store, 'posts', postId, ctx.request.subject.tenantId, when)
+
+// Field-level delta between two versions ({ field: { from, to } }), or null
+// when either version isn't visible to the caller's tenant (or was pruned).
+const delta = await diffVersions(ctx.store, 'posts', postId, ctx.request.subject.tenantId, 1, 3)
+```
+
+## Retention
+
+`_voltro_row_history` is append-only — one full-row-JSON version per write — so it grows with write volume. It is bounded by the framework's retention sweep: **365 days by default**, tunable via `VOLTRO_ROW_HISTORY_TTL_HOURS` (raise for longer compliance windows, lower to cap storage; the resolved window is logged at boot). For hot rows, the `maxVersionsPerRow` option additionally caps the per-row COUNT — after each recorded change, versions older than the newest N are pruned. The TTL bounds age; the cap bounds depth.
+
+## Notes
+
+- **History is append-only** and non-blocking — the recorder runs on the framework-supervised change tap (an `Effect` the runtime forks), so a slow recorder can't block writes, and a record failure surfaces on the tap's typed error channel (logged, not silently swallowed). A concurrent same-row write racing the version numbering is retried (bounded) instead of dropped. For a hard audit guarantee pair it with `audit()` + a transactional write.
+- It snapshots whatever goes through `ctx.store` — out-of-band DB writes (raw `psql`) are not seen.
+
+## Permissions
+
+`store:write` (writes the history table) + `store:changes:read` (the ChangeEvent tap).