@voltro/cli 0.34.0 → 0.35.0

package/templates/agent-docs/plugins.md

@@ -1512,7 +1512,8 @@ The mirror is **opt-in** (omit `mirrorTables` → events-only) and **idempotent*
 
 - **Retried, not dropped.** A failing mirror write is retried with exponential backoff (`retryAttempts`, default 5). A write that outlives its retries is queued for **repair**: a timer re-reads the row's *current* state from your database and re-applies it, so the mirror converges on the truth rather than on a stale change that happened to be in flight.
 - **Ordered per row.** Writes for the same primary key are applied one at a time, in commit order, and every write carries a **version** stamped when the change left the store — never a clock read inside the warehouse client. A change that arrives late therefore *loses*: ClickHouse's `ReplacingMergeTree(version)` keeps the highest version, and the DuckDB / postgres mirrors apply the update only when the incoming version is newer. Different rows are still mirrored concurrently.
-- **A delete is a tombstone, not a row removal.** Filter `is_deleted = false` (`is_deleted = 0` / `FINAL` on ClickHouse). A physical delete would leave nothing for a late, stale insert of the same key to lose against — the row would silently come back.
+- **A delete is a tombstone, not a row removal.** Filter `is_deleted = false` (`is_deleted = 0` / `FINAL` on ClickHouse). A physical delete would leave nothing for a late, stale insert of the same key to lose against — the row would silently come back. The tombstone also keeps its version, which is what lets a replacement replica seed a key's numbering after a delete.
+- **N replicas converge to ONE row per change.** Under postgres CDC / mysql binlog every replica observes every change and mirrors it, so a change is written N times — but the version is derived from the CHANGE (the warehouse's own high-water mark for the key, plus the change's position in the fleet stream), never from a replica's clock. The N duplicates are byte-identical, and the sink's version guard collapses them for free: no leader election, and no clock-skew window in which an older image could out-version a newer one. A replica that boots mid-stream reads each key's high-water mark from the warehouse before its first write, so it continues the fleet's numbering instead of restarting it.
 - **Never surfaces to the request.** The OLTP write that produced the change has already committed; a warehouse outage is isolated into the log channel and the metrics below.
 - **A graceful shutdown is not a crash.** On SIGINT / SIGTERM the mirror stops taking new changes and then **settles** what is already queued and in flight, before the sink itself is disposed. That drain is bounded (3 s of the teardown budget you set with `VOLTRO_SHUTDOWN_GRACE_MS`, default 10 s): a warehouse that has stopped answering cannot hold the process open until the orchestrator's SIGKILL, which would lose strictly more. The two outcomes log differently — `analytics mirror drained` at info, or a `warn` naming what was still pending when the deadline cut it, because that is the moment those counters can still be read.
 - **Not durable across a crash.** The repair queue lives in memory. A change still awaiting repair when the process dies — SIGKILL, an OOM, a host failure — is lost, as is one evicted after `repairQueueLimit`. Both are logged at error level and counted by `voltro_analytics_mirror_dropped_total` — if that counter is non-zero, the affected tables need a re-seed.
@@ -1530,6 +1531,7 @@ Every number the mirror picks on your behalf has a default and an environment ov
 | `VOLTRO_ANALYTICS_MIRROR_RETRY_MAX_MS` | `30000` | Ceiling for the doubling backoff. |
 | `VOLTRO_ANALYTICS_MIRROR_REPAIR_INTERVAL_MS` | `60000` | How often the repair loop re-drives exhausted changes (`0` disables it). |
 | `VOLTRO_ANALYTICS_MIRROR_REPAIR_QUEUE_LIMIT` | `10000` | Maximum keys held for repair before the oldest is dropped and counted. |
+| `VOLTRO_ANALYTICS_MIRROR_VERSION_STATE_LIMIT` | `100000` | Maximum keys whose fleet-scope version state stays in memory; an evicted key re-seeds from the warehouse on its next change. |
 
 ## Default — no sink configured
 

package/templates/agent-docs/scheduling.md

@@ -569,6 +569,23 @@ Backfill runs **before** the live timer is armed, so a caught-up firing never ra
 
 Missed slots recorded under `latest` show up in the dashboard with the `missed` status — visible evidence of the gap, not a silent hole.
 
+## Backfilling an explicit range — `voltro schedule backfill`
+
+Boot backfill only walks forward from the **last recorded run**, and cluster-cron coordination caps its own catch-up at one day. A longer outage — or a schedule added after the fact that should have "always existed" — needs an explicit operator instruction naming the range:
+
+```sh
+voltro schedule backfill hourly-sync --from 2026-08-10T00:00:00Z --to 2026-08-12T00:00:00Z
+```
+
+Every cron occurrence in `(from, to]` fires **sequentially, in order, each against its own cron-derived `scheduledAt`** — a handler (or a `workflow:` payload function) reading `ctx.scheduledAt` computes against its slot, not "now". Firings record as `trigger: 'manual'` in `_voltro_schedule_runs`, so the catch-up is a legible ledger; a failed slot records its failure and the next slot still fires.
+
+The verb is **bounded and confirmable**, because a range verb that can enqueue 100k runs is an outage generator:
+
+- Above **25** occurrences it refuses and prints the count — re-run with `--yes` after reading the number.
+- Above the per-request cap (default **1,000**, raisable with `--limit` up to a hard ceiling of 10,000) it refuses outright, firing **nothing** — never a silent prefix that reports completeness. Run bigger catch-ups in slices.
+
+The same verb is `POST /_voltro/inspect/schedules/:name/backfill` with `{ "from", "to", "confirm", "limit" }` (a refusal answers `409` with the count and reason), on `voltro dev` and `voltro serve` alike — it needs the inspect surface open (`VOLTRO_INSPECT_TOKEN`).
+
 
 
 ---

package/templates/agent-docs/security.md

@@ -47,8 +47,8 @@ as protection and enforces nothing.
 The whole app can opt out with one field — `security: { defaultDeny: false }` in
 `app.config.ts`. There is no environment variable for it: the only direction
 anyone reaches for is off, and an env var is how that becomes permanent in one CI
-job with no diff to review. Full detail, including what the gate does not cover
-(a plugin's own procedures), in
+job with no diff to review. Full detail — including how plugin routes are
+covered per-request in the dispatch spine rather than by the boot gate — in
 [Authorization](/docs/authentication/authorization).
 
 ## Outbound HTTP is SSRF-guarded by default