@voltro/cli 0.51.0 → 0.53.0

package/templates/agent-docs/cli.md

@@ -29,7 +29,7 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 | [Data transfer](/docs/cli/data) | `data` (`export` / `import` / `unpack` / `inspect` / `backup` / `restore`) — directory + single-file `.vbundle` bundles, streaming assets, masking, at-rest encryption |
 | Ops / infra | `cache` (`status` / `flush` / `invalidate`), `add` (`redis`), `baseline` (`list` / `status` / `set`), `schedule` (`run <name>` — fire a registered schedule on demand; `--process` / `--trigger manual\|external` / `--url`), `schedule-manifest`, [`storage`](/docs/plugins/storage) (`doctor` / `cors`) |
 | AI / data | `embeddings backfill <table> --text <field> --vector <field>` — (re)embed rows the `vectorEmbedding()` mixin missed (pre-existing rows / a model change); `--dry-run` to preview; [`eval`](/docs/ai/agents#evaluating-recorded-runs-voltro-eval) — replay recorded agent runs against golden cases + judge, exit 1 on regression (a deploy gate; `--json` / `--branch` / `--threshold`) |
-| Integrate | [`webhooks`](/docs/plugins/webhooks#voltro-webhooks-consumer--the-package-your-subscribers-install) (`consumer` / `events`) — generate the ZERO-dependency Standard-Webhooks verification package your subscribers install, from your own declared events (`--out` / `--name`); list the events a subscriber can register for (`--json`) |
+| Integrate | [`webhooks`](/docs/plugins/webhooks#voltro-webhooks-consumer-the-package-your-subscribers-install) (`consumer` / `events`) — generate the ZERO-dependency Standard-Webhooks verification package your subscribers install, from your own declared events (`--out` / `--name`); list the events a subscriber can register for (`--json`) |
 | [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` |
 | [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled; `info` (`--json`) — CLI / node / package-manager / dialect + every installed `@voltro/*` version, flagging lockstep skew (exits 1 on skew) |
 | Harness | `test`, `e2e` |
@@ -142,6 +142,12 @@ config value always winning:
 | `VOLTRO_CSP_HTML` | CSP for HTML responses (under `strict` it defaults to the same policy as `VOLTRO_CSP`). `off` drops just this one. |
 | `VOLTRO_HSTS` | `Strict-Transport-Security` value. `off` drops just this one. |
 | `VOLTRO_MAX_RPC_BODY_BYTES` | Cap on the buffered `POST /rpc` JSON body (default 8 MiB) — an oversized body is refused `413` and never buffered past the cap. File uploads ride plugin routes with their own limits. |
+| `VOLTRO_MAX_BODY_BYTES` | Cap on every OTHER body read — plugin HTTP routes, REST routes, incoming webhooks (default 8 MiB, matching the rpc cap). The config-file spelling is `http.maxBodyBytes` in `app.config.ts`; per-route overrides (`defineRestRoute({ maxBodyBytes })`, a webhook handler's `maxBodyBytes`) win over both. Oversize is `413` for `Content-Length` and chunked alike. |
+
+Response compression for the buffered non-rpc surfaces (and `voltro start`'s
+HTML) is configured in the same `http:` block — `http.compression.{enabled,minBytes}`
+(default on, 1 KiB threshold; `POST /rpc` is never compressed). Details + the
+BREACH reasoning: [Security → compression](/docs/security/overview#response-compression-and-where-breach-sits).
 
 Generate any of the secret vars above with `voltro secret generate <purpose>` (see [`secret`](#command-quick-reference)) — it picks the right length and format. A lower environment's secrets must always differ from production's.
 
@@ -317,36 +323,48 @@ fails to update.
 
 ```
 observed: 12/34 procedures exercised (35%)
+  1 declared/observed mismatch among the 12 that ran
   mutation(orders.place) (api/orders/place.mutation.ts)
     writes 'inventory' (update) but declares no target for it
     subscriptions on that table are not invalidated by this mutation
     fix: add { table: 'inventory', op: 'update' } to this procedure's targets
-  22 unexercised — no recording, so nothing is claimed about them
+  20 never ran — no observation exists, so nothing is claimed about them
+  2 ran with no table access recorded — indistinguishable from touching nothing, so nothing is claimed about them either
 ```
 
-Three things about that output are deliberate:
+Four things about that output are deliberate:
 
 - **Coverage comes first.** Three findings at 8% coverage and three at 95% are
   different claims. Hiding the denominator is how a check starts overstating
   what it knows.
-- **`unexercised` is a third state, not a finding.** A procedure no test and no
-  dev session ever ran has *no observation* — which is not the same as "touches
-  nothing". It is counted and never reported as a problem.
+- **Every result line carries the count it is a result about.** `1 mismatch
+  among the 12 that ran` — never a bare verdict. A sentence that still reads as
+  a conclusion once it is cut out of this block will eventually be cut out of
+  it, and quoted as a clean bill of health for a surface nobody measured.
+- **The counts partition the declared set — they add up to the total, always.**
+  There are two ways to say nothing about a procedure, and both get a line:
+  it never ran, or it ran and no table access was recorded for it. A procedure
+  that appeared in no line at all would be indistinguishable from a defect in
+  `check` itself, so the two kinds of blindness are named separately and never
+  folded into the findings.
 - **Observed diagnostics never fail the build.** An observation is evidence
   about the runs that happened, not a proof about the ones that didn't, and
   `check`'s exit code gates CI. They are always warnings.
 
-A fourth thing is not visible in that output and matters more than any of the
-three: **the recorder only knows what ran.** A boot is not a run. An idle dev
+A fifth thing is not visible in that output and matters more than any of the
+four: **the recorder only knows what ran.** A boot is not a run. An idle dev
 instance that started, served nothing and stopped produces
 
 ```
-observed: 0/2755 procedures exercised (0%)
-  2753 unexercised — no recording, so nothing is claimed about them
+observed: 0/34 procedures exercised (0%)
+  nothing was compared — a declaration is only checked against a procedure that RAN
+  34 never ran — no observation exists, so nothing is claimed about them
 ```
 
-which is the honest answer and also a useless one — the section says nothing
-about 99.9% of the surface. If you want this as a CI gate, the recording pass has
+Note what that is NOT: it is not "no mismatches found". At zero coverage there
+is no result to report, so the section reports the absence of the comparison
+instead. The honest answer is also a useless one — it says nothing about any of
+the surface. If you want this as a CI gate, the recording pass has
 to be a run that actually *calls* the procedures. `voltro e2e` is one: it spawns
 `voltro dev` for the api, which turns recording on, and then drives the specs. A
 harness of your own that boots the app in its own process needs
@@ -365,6 +383,29 @@ handlers: a static pass over code that reaches the store through shared helpers,
 behind conditionals, has a long tail of both false positives and false negatives
 — and a check that is *sometimes* wrong is one people stop reading.
 
+#### Declared vs LIVE — against a running server
+
+When `check` runs against a live api (a local `voltro dev`, or a deployed one
+via `--url`), it also diffs the tags your source declares — plugin routes
+included — against the server's actual rpc registry:
+
+```
+declared vs live: 2 of 214 source-declared tags are NOT registered on the server
+  ⚠ presence.heartbeat — a generated client calls this and gets "Unknown request tag"
+  ⚠ presence.list — a generated client calls this and gets "Unknown request tag"
+  fix: if the server runs older code, redeploy; if it is current, plugin route registration was dropped — check the boot line "plugin routes registered"
+```
+
+Only the source→live direction is a finding — a tag the server carries that your
+source does not declare is normal runtime synthesis (agents, undo, approvals).
+This exists because exactly that gap has shipped once: every
+plugin-contributed procedure dead under `voltro serve`, with nothing anywhere
+saying so — the only evidence was a `Defect` frame in the browser console of
+whoever happened to look. (That registration defect is fixed; the diff is the
+runtime backstop for the next one, e.g. a stale deploy.) The server now also
+logs every `Defect` frame it sends (`rpc defect sent to client`), so an unknown
+tag is an operator-visible event rather than a client-only one.
+
 The HTTP surface is reachable directly too — e.g. `curl -s localhost:4000/_voltro/inspect/rpc | jq` (there is no `/_voltro/inspect/queries` endpoint; it's `rpc` for procedures, `routes` for the web page tree, `subscriptions` for active subscribers).
 
 ## Where to read next
@@ -1364,7 +1405,7 @@ Point the Kubernetes liveness probe at `/internal/liveness` and the readiness pr
 For WebSocket connections to land on the same backend (required for in-process subscription state):
 
 - Reverse proxy: `lb_policy ip_hash` (Caddy) / `ip_hash` (nginx).
-- Or use `@voltro/plugin-cluster` to share subscription state across instances → any-load-balancer-works.
+- Cross-instance subscription invalidation is built in on Postgres (LISTEN/NOTIFY) and MySQL/MariaDB (binlog CDC); on any other dialect add [`@voltro/plugin-broadcast`](/docs/plugins/broadcast) (Redis/NATS). With that in place a reconnect may land on any replica and still sees every change — sticky sessions then only keep one live connection pinned, they are not a correctness requirement.
 
 ## `voltro build api --target <swift|kotlin>` — native SDK generation
 
@@ -1796,6 +1837,47 @@ matching rule lives inside the CLI, so you cannot re-derive the list with your
 own grep. `--json` prints the complete scan, nothing elided, with no preflight
 output mixed in:
 
+### Unimported `@voltro/*` dependencies
+
+A declared framework dependency nobody imports still gets installed, walked on
+every `voltro update`, and read as evidence the package is in use — its
+breaking-change notes included. The usual origin is a migration: the app moves
+off a framework package to a third-party one, and the `package.json` entry
+stays. `voltro doctor` checks every `@voltro/*` in `dependencies` and
+`devDependencies` for an import site:
+
+```
+unimported deps · 8 @voltro/* package(s) declared, 214 file(s) scanned
+  ⚠ @voltro/i18n — declared in dependencies, imported nowhere
+      a dependency nobody imports still gets installed, updated, and read as
+      evidence the package is in use — its breaking-change notes included.
+      Remove it, or if it IS imported through an assembled specifier the scan
+      cannot see, keep it and ignore this line — the rule is advisory.
+  · (2 loaded by the framework itself: @voltro/cli, @voltro/sql-postgres)
+```
+
+Scoped to `@voltro/*` deliberately: for third-party packages the same question
+has a long tail of legitimate no-import shapes, and a rule that is sometimes
+wrong is one people stop reading. Three states are distinguished, and each is
+printed:
+
+- **Exempt, by name** — packages the framework loads on your declaration
+  (`@voltro/cli` is the binary; `@voltro/devtools` is mounted by `voltro dev`;
+  the `@voltro/sql-*` dialect drivers are loaded from your config). An
+  exemption you cannot see is a finding you cannot question.
+- **Not measurable yet** — `@voltro/client` / `@voltro/web` are normally
+  imported by *generated* code. On a tree where codegen has never run, their
+  absence is a missing measurement, not a dead dependency; the section says so
+  and tells you to run `voltro dev` once.
+- **Unimported** — advisory, never fatal. A mention in a comment or an error
+  string does not count as an import (a commented-out import is exactly the
+  residue this looks for), and an import assembled at runtime from string
+  pieces is invisible to the scan — the finding text says both.
+
+The full report is in `voltro doctor --json` under `unimportedDeps`
+(`null` when there is no `package.json` to read — "could not check" and
+"checked, clean" never print the same).
+
 ### Duplicate package instances
 
 `voltro doctor` also reports any identity-sensitive package resolved at more than
@@ -2850,7 +2932,7 @@ Not every run can take it, and a run that cannot **says why** rather than quietl
 taking the slower path:
 
 - a store the framework cannot send DDL to (the in-memory store).
-- a **write recorder** on any table in the set — `versioningPlugin({ timing:
+- a **write recorder** on any table in the set — `rowHistoryPlugin({ timing:
   'in-transaction' })` and friends. A recorder is keyed by table name, so a
   staged write would find none and the recorder would silently not run. Its
   promise is "if the change committed, the entry is there", so the run keeps the
@@ -2906,7 +2988,7 @@ ITSELF is not a cycle: one statement carries the whole table.
 
 ### A `replace` does not write per-row history
 
-Write recorders — `versioningPlugin({ timing: 'in-transaction' })` and anything
+Write recorders — `rowHistoryPlugin({ timing: 'in-transaction' })` and anything
 else registered through the same seam — are **suspended for a `replace`**. A
 replace sets a state; it does not change rows, so a per-row history entry would
 describe something that did not happen. On a large bundle that is not a detail:

package/templates/agent-docs/configuration.md

@@ -126,6 +126,11 @@ just as secret and just as required, but inventing one produces a value that
 merely *looks* right and authenticates nobody — better that the boot gate fails
 and a human fetches the real one.
 
+Encodings: `base64url` and `hex` mint 32 random bytes; `p256` mints a valid
+P-256 private scalar (what web push's `VOLTRO_VAPID_PRIVATE_KEY` needs — a
+plugin can declare its own mintables the same way, which is how a configured
+`webPushChannel()` gets its key without you declaring anything).
+
 Minting is **development only**. `voltro serve`, `build` and `start` never mint:
 in production a missing secret is a boot failure, which is the whole point.
 Generate deployment values with `voltro secret generate <purpose>`.
@@ -302,6 +307,18 @@ This updates what code that reads a secret **per use** sees: outbound API keys r
 `setSecretsBackend(backend)` installs a backend for a test; `resetSecretsBackend()` restores the env default. `resolveSecretsBackend(config)` is the pure resolver the boot path uses to turn the `secrets` config value into a backend.
 
 
+## `VOLTRO_OG_SECRET` — conditional, multi-replica only
+
+The signed on-demand OG-image route (ssr pages exporting
+[`ogImage`](/docs/routing/loaders-and-meta#og-images-from-a-template-ogimage))
+signs its URLs with `VOLTRO_OG_SECRET`. The requirement is CONDITIONAL: a
+single process mints a per-boot secret and is self-consistent — only a
+multi-replica deploy needs the env var (the signing replica and the fetching
+replica differ), and a deploy boot with ssr `ogImage` pages and no secret
+refuses loudly rather than serving images that 403 on every other replica.
+Any long random value; same on every replica; never a default.
+
+
 
 ---