@voltro/cli 0.56.0 → 0.58.0

package/dist/{webhooksCommand-uuPu8qQX.js → webhooksCommand-BPJQOGTe.js}

@@ -222,8 +222,8 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-B9Gz0k85.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
-	return r((await n(await t(e))).events.map((e) => ({
+	let { walk: t, loadDiscovered: n } = await import("./dev-Dff_pdik.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	return r((await n(await t(e), { root: e })).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor
 	}))).map((e) => x(e.descriptor));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -802,6 +802,48 @@
         "title": "`voltro serve` on a WEB app now refuses — use `voltro start`",
         "kind": "manual"
       },
+      {
+        "version": "0.58.0",
+        "id": "0.58.0/01_system_writes_stamp_no_actor",
+        "title": "A `runAsSystem` write stamps no actor id instead of \"system\"",
+        "kind": "manual"
+      },
+      {
+        "version": "0.58.0",
+        "id": "0.58.0/02_workflow_caller_context_carries_a_scope",
+        "title": "ResolvedWorkflowCallerContext carries the run's resolved row-filter scope",
+        "kind": "manual"
+      },
+      {
+        "version": "0.58.0",
+        "id": "0.58.0/03_fleet_view_reports_departed_replicas",
+        "title": "A fleet view separates DEPARTED replicas from stale ones",
+        "kind": "manual"
+      },
+      {
+        "version": "0.58.0",
+        "id": "0.58.0/04_rpc_errors_reach_reporters",
+        "title": "rpc failures are published on the client error bus",
+        "kind": "manual"
+      },
+      {
+        "version": "0.58.0",
+        "id": "0.58.0/05_sentry_traces_on_by_default",
+        "title": "Sentry performance traces are on by default",
+        "kind": "manual"
+      },
+      {
+        "version": "0.58.0",
+        "id": "0.58.0/06_jwt_secret_may_be_a_function",
+        "title": "jwtSecret may be a function, so a build needs no production credential",
+        "kind": "manual"
+      },
+      {
+        "version": "0.58.0",
+        "id": "0.58.0/07_rerank_takes_a_provider_config",
+        "title": "rerank reaches the gateway through a ProviderConfig",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -884,24 +926,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.56.0",
-    "@voltro/cache": "0.56.0",
-    "@voltro/client": "0.56.0",
-    "@voltro/content": "0.56.0",
-    "@voltro/data-transfer": "0.56.0",
-    "@voltro/database": "0.56.0",
-    "@voltro/env": "0.56.0",
-    "@voltro/kv": "0.56.0",
-    "@voltro/logger": "0.56.0",
-    "@voltro/plugin-auth": "0.56.0",
-    "@voltro/plugin-broadcast": "0.56.0",
-    "@voltro/plugin-mail": "0.56.0",
-    "@voltro/plugin-storage": "0.56.0",
-    "@voltro/plugin-webhooks": "0.56.0",
-    "@voltro/protocol": "0.56.0",
-    "@voltro/runtime": "0.56.0",
-    "@voltro/serverless": "0.56.0",
-    "@voltro/workflow": "0.56.0",
+    "@voltro/ai": "0.58.0",
+    "@voltro/cache": "0.58.0",
+    "@voltro/client": "0.58.0",
+    "@voltro/content": "0.58.0",
+    "@voltro/data-transfer": "0.58.0",
+    "@voltro/database": "0.58.0",
+    "@voltro/env": "0.58.0",
+    "@voltro/kv": "0.58.0",
+    "@voltro/logger": "0.58.0",
+    "@voltro/plugin-auth": "0.58.0",
+    "@voltro/plugin-broadcast": "0.58.0",
+    "@voltro/plugin-mail": "0.58.0",
+    "@voltro/plugin-storage": "0.58.0",
+    "@voltro/plugin-webhooks": "0.58.0",
+    "@voltro/protocol": "0.58.0",
+    "@voltro/runtime": "0.58.0",
+    "@voltro/serverless": "0.58.0",
+    "@voltro/workflow": "0.58.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -749,7 +749,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.56.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.58.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.56.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.58.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_manifest.json

@@ -8,7 +8,7 @@
       "group": null,
       "description": "How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework.",
       "path": "agent-docs/ai.md",
-      "files": 11
+      "files": 12
     },
     {
       "id": "authentication",
@@ -260,7 +260,7 @@
       "group": null,
       "description": "Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue.",
       "path": "agent-docs/schema-driven-ui.md",
-      "files": 23
+      "files": 24
     },
     {
       "id": "security",

package/templates/agent-docs/ai.md

@@ -172,6 +172,38 @@ const models = await getAvailableModels({ modality: 'language' })   // filter op
 
 Pricing is normalised to **USD per 1,000,000 tokens**, the same shape as the cost toolkit's `ModelPrice` — so a catalog entry can feed the [cost ledger](/docs/ai/cost-tracking) directly (`estimateCostUsd(usage, { model, price })`). `getAvailableModels` is `async` (a plain Promise, not an Effect) and `gatewayProvider` is injectable for tests, so a picker query can call it without a live gateway in CI.
 
+### The full catalog — `readGatewayCatalog`
+
+`getAvailableModels` asks the AI SDK's gateway provider, whose entry type carries six fields. The HTTP response carries **twenty-one**. `readGatewayCatalog()` reads the response:
+
+```ts
+import { readGatewayCatalog, canExecute } from '@voltro/ai'
+
+const models = await readGatewayCatalog({ modality: 'language' })
+const usable = models.filter(canExecute).filter((m) => m.capabilities?.vision)
+```
+
+Each entry adds `capabilities`, `modalities`, `contextWindow`, `maxOutputTokens`, `releasedAt`, `knowledgeCutoff` and `dataPolicy`.
+
+`capabilities` is **unioned from three fields that each half-say it** — `tags`, `supported_parameters` and `modalities` — because they overlap and regularly disagree: a model tagged `reasoning` does not always carry the parameter, and the other way round. Taking either alone produces a false negative, and a false "cannot" removes a model from a picker with no way for anyone to find out why. That union is framework knowledge; without it every app writes the same forty lines, differently.
+
+`dataPolicy` carries `zeroRetention` and `noTraining` (`'all' | 'some' | 'none'`). They decide whether a model may see customer text, and an unreadable value reads as `'none'` — the question is "may this", and an unparseable answer is not a yes.
+
+`capabilities` and `modalities` are **optional**, and that is deliberate: they are populated on every HTTP read, and absent only when an entry came from the injected `gatewayProvider` a test uses. Defaulting them to all-false would turn "not known" into the claim "this model has no vision".
+
+### What the runtime can actually run — `executableModalities`
+
+The catalog names eight modalities; a build can execute the ones it has primitives for. Offering a model it cannot run produces a control that writes into nothing, so ask rather than keep a list:
+
+```ts
+import { executableModalities, canExecute } from '@voltro/ai'
+
+executableModalities()      // Set { language, embedding, image, video, speech, reranking, transcription }
+canExecute(model)           // false for `realtime` today
+```
+
+A hand-maintained list of runnable kinds goes stale the moment a primitive ships, and it goes stale silently — the app keeps hiding a modality that now works. This set is tied to the exports that justify each entry, so shipping a primitive without adding it turns a test red.
+
 ## Per-config key + base URL
 
 Every `ProviderConfig` accepts an optional `apiKey` and `baseURL`. When EITHER is set, the framework builds a **dedicated provider instance** from it (`createOpenAI({ apiKey })` / `createAnthropic(...)` / `createGateway(...)`) instead of the env-default singleton. Omit both → it falls back to the standard env var. The mock provider ignores both.
@@ -1326,7 +1358,7 @@ defaults to treating an `AgentEvent`-shaped `{ _tag: 'done' | 'error' }` as the
 end of the run. Override `isTerminal` when your element type signals completion
 some other way, or the hook will keep trying to resume a finished stream.
 
-For multi-node deployments use `dataStoreResumableStreamStore(ctx.store)` — it persists to the framework's own database (`streamEventsTable` + `streamStateTable`, register them in your `database/index.ts`) and elects exactly ONE producer per `streamId` via an atomic claim, so only one node runs the model while every node's consumers tail the shared log. Sweep finished streams with `gcResumableStreams(store, { olderThan })`.
+For multi-node deployments use `dataStoreResumableStreamStore(ctx.store)` — it persists to the framework's own database (`_voltro_stream_events` + `_voltro_stream_state`, created for you: the table assembly adds both for any app that depends on `@voltro/ai`, so `voltro dev` / `voltro db apply` / `voltro migrate` all plan them) and elects exactly ONE producer per `streamId` via an atomic claim, so only one node runs the model while every node's consumers tail the shared log. Sweep finished streams with `gcResumableStreams(store, { olderThan })`.
 
 For the fastest path, `redisResumableStreamStore(redis, { ttlSeconds })` backs the log with a Redis LIST (`RPUSH`/`LRANGE`) plus a `SET … NX` producer claim — TTL evicts finished/abandoned streams without a sweep. `@voltro/ai` takes no Redis dependency; you inject a tiny `ResumableRedis` client (five methods: `setNx` / `rpush` / `lrange` / `set` / `exists`) adapting ioredis / node-redis. All three backends satisfy the same `ResumableStreamStore` interface, so they swap without touching the producer/consumer code.
 
@@ -1623,6 +1655,19 @@ const top5 = reranked.map((r) => r.document)
 
 Re-rankers are slower than vector search but much more accurate. Use the cheap vector search to narrow to ~20 candidates, then the rerank model to pick the top 5. Total latency: ~150-300ms vs. 50ms for vector-only. The default `provider: 'mock'` scores by lexical overlap — deterministic and key-free for tests; the `cohere` / `voyage` providers resolve their SDK lazily (install the provider package to use them).
 
+### Through the gateway
+
+`provider` also takes a `ProviderConfig`, the shape every other primitive here takes — so one `AI_GATEWAY_API_KEY` reaches every reranking model in the catalog instead of each vendor's own key:
+
+```ts
+const reranked = yield* rerank({
+  query, documents: candidates, getText: (d) => d.body, topN: 5,
+  provider: { name: 'gateway', model: 'cohere/rerank-v4-pro' },
+})
+```
+
+The string shorthands (`'cohere'`, `'voyage'`) stay for the direct-key route. They are deliberately not folded into `ProviderConfig`: that union is shared with `generateText` and friends, and adding `cohere` there would let you name a provider that has no language model — a config error the type currently catches.
+
 ## Citing sources
 
 The model needs source info in its context to cite:
@@ -2468,3 +2513,132 @@ infrastructure. It does **not** execute the literal generated TypeScript against
 database — the **deployed** app does that, running the real artifacts on a real
 store. So the preview is a true feel for how the app behaves, not a bit-for-bit
 run of the code.
+
+
+
+---
+
+<!-- source: en/ai/media.md -->
+## Media modalities
+
+_Speech, transcription, images and video — one provider config, one error type, one cost ledger. Plus the seam for a speech provider the gateway does not carry._
+
+The gateway catalog names eight modalities. Four of them are media, and each has a primitive with the same shape as the rest of `@voltro/ai`: a `ProviderConfig`, an `AiError` failure channel, and usage that reaches the same [cost ledger](/docs/ai/cost-tracking).
+
+| Modality | Primitive |
+|---|---|
+| `image` | `generateImage` |
+| `video` | `generateVideo` |
+| `speech` | `generateSpeech` |
+| `transcription` | `transcribe` |
+
+## `transcribe` — audio to text
+
+```ts
+import { transcribe } from '@voltro/ai'
+
+const { text, segments } = yield* transcribe({
+  source: { storageRef: recording.ref },
+  resolveRef: (ref) => ctx.storage.read(ref),
+  timestamps: 'segment',
+  language: 'de',
+})
+```
+
+### The source is a reference, not bytes
+
+Audio is large and usually already somewhere. Pushing a ninety-minute recording through an rpc frame to hand it back to a provider is the wrong direction, so `source` takes three shapes and they are genuinely different:
+
+- **`{ storageRef }`** — the case to reach for. The app resolves it, because the app's storage is what knows about tenancy, signing and lifetime. The resolver is **injected** (`resolveRef`) rather than imported, so `@voltro/ai` never learns about buckets.
+- **`{ url }`** — fetched by `transcribe`. Convenient, but the bytes do pass through the process: the SDK takes bytes or base64 and never a location.
+- **`{ bytes, mediaType }`** — already in hand. The one that costs memory by construction.
+
+### Timestamps and speakers
+
+`timestamps: 'none' | 'segment' | 'word'` is a request, not a default — providers charge for the detail. `diarize: true` asks for speaker separation; a provider that cannot do it returns segments without `speaker` rather than failing.
+
+`segments` is **absent** when the provider returned none, never `[]`. An empty array is a claim ("this audio has no speech"); absent is the truth ("the provider did not say").
+
+## `generateSpeech` — text to audio
+
+```ts
+const { audio } = yield* generateSpeech({
+  text: 'Willkommen.',
+  provider: { name: 'gateway', model: 'openai/tts-1-hd' },
+  voice: 'alloy',
+  outputFormat: 'mp3',
+})
+```
+
+### A provider the gateway does not carry
+
+The gateway serves nine speech models. A real voice catalog runs to hundreds behind vendors it does not carry — Cartesia, ElevenLabs, Google Cloud TTS — and an app with its own adapter for those had nowhere to plug it in, so it called its own synthesizer and skipped the primitive entirely, losing the shared error type and cost path with it.
+
+Register the adapter instead:
+
+```ts
+import { registerSpeechProvider, generateSpeech } from '@voltro/ai'
+
+registerSpeechProvider('elevenlabs', {
+  listVoices: () => …,
+  synthesize: (request) => …,
+})
+
+yield* generateSpeech({ text, provider: { name: 'elevenlabs', model: 'eleven_turbo_v3' }, voice })
+```
+
+This ships **no** adapters, on purpose: bundling an ElevenLabs client would put the framework in the business of tracking somebody else's REST API, and the app already has the adapter. What the app deletes is its dispatch, not its adapters.
+
+A registered provider receives every option the primitive already had — `voice`, `outputFormat`, `speed`, `language`, `instructions`, `providerOptions` — or the seam would be a narrower primitive wearing the same name. Built-in names (`mock`, `openai`, `gateway`, `anthropic`) cannot be shadowed: silently overriding one would make the same config mean different things depending on which module loaded first.
+
+## As a durable step — `transcribeStep`
+
+A ninety-minute recording is not a request. `aiStep` and `aiObjectStep` have had
+`offload: true` since they shipped, and transcription — the modality that runs
+longest — is where it matters most:
+
+```ts
+const { text, language } = yield* transcribeStep({
+  name: 'transcribe-recording',
+  source: { storageRef: recording.ref },
+  resolveRef: (ref) => ctx.storage.read(ref),
+  offload: true,
+})
+```
+
+Offloaded, the run parks on a durable signal and frees its worker; the dispatcher
+performs the call and resumes it. The queue row carries the **source**, never the
+bytes — putting the audio in the row would reintroduce exactly the cost
+offloading exists to remove. A ref source therefore needs `resolveTranscriptionRef`
+wired on the dispatcher too, since that is the process doing the read.
+
+The journal keeps `text`, `language` and `durationSec` and **not** `segments`: a
+journal is read back on every replay, and segments for a long recording would
+make each replay pay for the transcript again. The segments belong wherever the
+app puts the transcript.
+
+## On the client — `useTranscription`
+
+The entrance is a file, so the two halves are one hook:
+
+```tsx
+const t = useTranscription('app', { action: 'media.transcribe' })
+
+await t.transcribe(file)
+t.phase       // 'idle' | 'uploading' | 'transcribing' | 'done' | 'error'
+t.progress    // 0..1 while uploading, undefined once the model is running
+t.result      // { text, language, durationSec, segments? }
+```
+
+`progress` is scoped to the phase on purpose. A single number across both reaches
+`1` when the **upload** finishes, while the model has not started — a bar that
+says finished is worse than no bar, so the transcribing phase reports `undefined`
+and an indeterminate spinner is the honest control.
+
+The hook opens no transport: the upload is `useUpload`'s and the transcription is
+an action **you** declare, guard and point at a model. It owns the reduction,
+which is the part every app was rewriting.
+
+## What is not here yet
+
+`realtime` — the catalog's six duplex speech-to-speech models — has no primitive. The reason is not the model surface, which the gateway exposes; it is that rpc has no client→server stream. Every streaming kind in Voltro (`subscription`, `stream`, `event`) is server→client, so relaying a duplex session over the existing authenticated connection needs a transport capability that does not exist yet. `canExecute({ modality: 'realtime' })` answers `false`, which is what keeps it out of a picker until it does.

package/templates/agent-docs/authentication.md

@@ -2199,6 +2199,17 @@ A subscription is a long-lived grant. Its guards — scope and relationship alik
 — are re-evaluated before each delivery, so revoking a relation mid-session ends
 the stream with the typed error instead of continuing to push rows.
 
+The same holds for a `*.stream.ts`: its guards are checked when the stream is
+opened — **before the executor runs** — and again before each element. The
+subscribe-time check comes first for a reason that is not symmetry: a stream's
+executor is where the work happens, so a gate placed after it refuses the result
+of something that has already been done and paid for. A denial ends the stream
+with the typed error rather than dropping elements, because a skipped element is
+indistinguishable from "nothing to send".
+
+Every primitive that accepts `guards:` enforces them: queries, mutations,
+actions, events and streams.
+
 ## Every procedure decides — `guards:` or `openAccess:`
 
 A procedure that declares neither is **refused at boot**. `guards:` used to
@@ -2573,6 +2584,29 @@ wrapStoreWithMixinBehaviour(store, { subject, schemaRegistry, rowFilter: NO_ROW_
 do this; a system subject bypasses row filters by design, and it is now written
 down rather than inferred from an absence.
 
+You do not write it in your own schedules or subscribers. They run as a `system`
+subject and are exempt by that fact — not by appearing on a list. The distinction
+is worth stating, because the list was tried first: the resolution was taken
+through "all four request-context arms", and the arm that is not a request fell
+out of a list of request arms without anybody forgetting it. No entry added to a
+list closes that; the subject type is what every non-request path has in common.
+
+A workflow splits along exactly that line, which is why it is the useful example.
+A BOOTSTRAP run — one with no recorded caller — is the system and bypasses. A run
+started BY A USER is not, and it reads through THAT user's filter, resolved when
+the step executes rather than restored from the row that started it. A workflow
+resumed three days later must not act on what its caller could see when they
+started it, for the same reason it must not act on the permissions they held
+then. If the scope cannot be resolved, the attempt fails rather than quietly
+reading fewer rows.
+
+`ctx.storeForTenant(id)` is the one derived view worth naming separately. Called
+from a schedule it runs as a `serviceAccount` subject rather than the system one
+— deliberately, so a subject whose null tenant means *every* tenant cannot widen
+back out of the tenant it was just confined to. The row-filter bypass travels
+across that narrowing; the tenant confinement does not. A per-tenant sweep
+therefore reads exactly one tenant's rows, unfiltered.
+
 ## What does *not* bypass it
 
 | | Bypasses the row filter? |
@@ -2691,31 +2725,46 @@ comment, and this one is load-bearing: the resume grant is issued on its
 strength. Omit `tables:` entirely and nothing is verified and nothing resumes —
 the conservative default.
 
-## Eager loads are refused, not silently unfiltered
+## Eager loads are narrowed too
 
 A relation pulled in with `.with(...)` is resolved **below** the seam that
-applies the filter: the stores expand the eager tree themselves (the memory
-store recurses through its own raw read; the SQL stores fold the relation into
-one join). So a filtered table reached through a relation would come back
-unfiltered.
+AND-merges the filter onto a read's base table: the stores expand the eager tree
+themselves (the memory store recurses through its own raw read; the SQL stores
+fold the relation into one join or JSON aggregate). So for a while a filtered
+table reached through a relation came back unfiltered, and then — once that was
+found — the read refused rather than serve those rows.
 
-Rather than serve those rows, the read **refuses**, naming the table and both
-ways out:
+Neither is the case now. The middleware writes your filter's predicate into each
+narrowed branch's `where`, which is where a caller could have put it themselves,
+so every resolver on every dialect applies it without knowing a row filter
+exists:
 
+```ts
+// what you wrote
+notes.with({ readers: true })
+
+// what the store resolves, when your filter narrows `readers`
+notes.with({ readers: { where: /* your filter's predicate for `readers` */ } })
 ```
-row filter: 'readers' is reached through an eager load on 'notes', and an eager
-relation is resolved BELOW the row filter — its rows would come back
-unfiltered. Refusing the read rather than serving it.
-  → read 'readers' as its own query (it is filtered there), or
-  → drop 'readers' from this .with(...) if the relation does not need
-    row-level narrowing.
-```
 
-Only relations reaching a table your filter actually narrows are affected —
-every other eager load is untouched. Applying the filter inside eager
-compilation is the real fix and it is a per-dialect change; until then this is
-a refusal rather than a leak, for the same reason the module refuses to
-fail open.
+Your own `where` is kept and the filter goes **under** it, so a branch you
+narrowed stays narrower and nothing a caller writes can widen the filter.
+Nested `.with(...)` is narrowed at every level. A relation reaching a table your
+filter does not narrow is untouched.
+
+**One case still refuses: a filtered `manyToMany` JUNCTION.** A branch `where`
+is a predicate on the relation's TARGET, and a filter narrowing the junction has
+nowhere to be expressed — so that read raises rather than joining junction rows
+the filter would have removed:
+
+```
+row filter: the junction table 'noteTags' behind relation 'tags' on 'notes' is
+row-filtered, and a many-to-many junction is read below the seam that could
+narrow it — its rows would be joined unfiltered. Refusing the read rather than
+serving it.
+  → read 'noteTags' as its own query (it is filtered there), or
+  → drop 'tags' from this .with(...).
+```
 
 ## Row filters vs. guards
 

package/templates/agent-docs/cli.md

@@ -1856,6 +1856,8 @@ It covers both halves of the stack:
 | server | a `token` / `secret` / `password` column with no encryption | `.encrypted()` |
 | server | a notify / webhook helper called at a mutation's tail | `defineSubscriber` / `defineReaction` |
 | server | a `*.subscribe.ts` handler that writes or publishes, with no `once:` | `once: true` on `defineSubscriber` |
+| server | an executor builds a field its descriptor's `output` does not declare | add it to `output` — the struct IS the serializer |
+| server | a mutation writes a NULLABLE column through an input field that cannot be `null` | `Schema.optional(Schema.NullOr(...))` |
 | server | `hasMore` + `limit + 1` | `paginateById` |
 | server | `.getTime()` / `.toISOString()` mapping a row on the way out | `timestampMs` / `timestampMsOrNull` from `@voltro/database/wire` in the descriptor's `output` struct |
 | client | per-field `useState` + a submit flag | `useFormBinding` |
@@ -1900,6 +1902,25 @@ decision was made, not which way. It reads the handler through the AST, so
 like an inline arrow; a handler IMPORTED from another module is not judged at
 all, since its body is not in the file being read.
 
+**Two rules read a DECLARATION against a DECLARATION, and are therefore exact.**
+`executor-builds-an-undeclared-field` compares the object literal an executor
+returns with its descriptor's `output` struct: since the struct IS the
+serializer, a key it does not declare is stripped on the way out, so every
+reader downstream gets `undefined` and renders a blank with nothing logged
+anywhere. `nullable-column-a-mutation-cannot-clear` compares a mutation's target
+table's nullable columns with its input schema — a nullable column written
+through a field that cannot be `null` can be set once and never emptied.
+
+Both REFUSE rather than guess, and the refusals are the interesting part. A
+spread on either side of the output comparison (`{ ...row, extra }`, or a
+`...Base` inside the declared struct) means the key set is not knowable from the
+source; reporting the visible half would name the field the author can already
+see and miss the ones they cannot. An output that is a named schema rather than
+a literal struct is unjudgeable, not empty — the second reading would make every
+field a finding. And a table declaration the scan cannot find produces no
+finding at all, because "this table has no nullable columns" and "I could not
+look" lead to opposite conclusions.
+
 It stays quiet on a reader on purpose. `once:` on a cache-warming subscriber
 would silence it on every replica but one, which is worse than the repetition it
 removes — only the handler's author knows which of the two they wrote.
@@ -2368,6 +2389,33 @@ voltro check             --url https://api.example.com
 
 `--token` (or `VOLTRO_INSPECT_TOKEN`) supplies the bearer; `VOLTRO_INSPECT_URL` sets a default target so you can drop the flag. Works for `inspect`, `logs`, `traces`, `workflows`, `cluster` and `check`.
 
+### `logs` and `traces` need a ring on the target — off by default
+
+A deployed app runs `voltro serve`, and `voltro serve` keeps **no** in-process log ring or span buffer unless you ask for one. Without it both commands answer:
+
+```
+voltro logs: NOTHING WAS SEARCHED — the target could not be read: HTTP 404
+endpoint not enabled on this instance — This instance keeps no in-process logs ring…
+```
+
+That headline is the point: *"no records matched the given filters"* would have sent you off widening `--tail` forever. Turn a ring on per app:
+
+```ts
+// app.config.ts
+export default defineAppConfig({
+  inspect: {
+    logs:   true,              // default size
+    traces: { size: 2_000 },   // or name it
+  },
+})
+```
+
+or per deployment, without a rebuild: `VOLTRO_INSPECT_LOGS=2000`, `VOLTRO_INSPECT_TRACES=on`, `=off` to override a config that declared one.
+
+**Why off by default.** A ring is memory on every replica, forever, for data most deployments already collect from stdout through their platform's pipeline. That pipeline stays the main road; the ring answers the different question — *what has THIS instance been doing in the last few minutes* — and it answers it for a hosted app, where reading a pod's stdout is not an option.
+
+**What a ring does not do.** It holds a bounded number of records on ONE replica. Against a fleet you are reading 1/N, and it is not retention: a restart empties it. `voltro dev` keeps both rings unconditionally — this switch is about what production does.
+
 ## `voltro probe access` — is a declared guard actually enforced?
 
 `voltro check` reads an app's manifest and reports a procedure with **no access

package/templates/agent-docs/configuration.md

@@ -202,10 +202,35 @@ is accepted but only reachable from server-side render code, and the boot
 ## Plugins declare their env
 
 A plugin that reads environment variables declares them via `declaredEnv` on its
-`VoltroPlugin` (metadata only — the plugin still reads its own values). This
-makes a plugin's env needs visible in the manifest, `.env.example`, and the
-dashboard. The first-party plugins already declare theirs, so the manifest is
-complete out of the box.
+`VoltroPlugin`. The plugin still reads its own values; declaring them makes its
+env needs visible in the manifest, `.env.example`, and the dashboard. The
+first-party plugins already declare theirs, so the manifest is complete out of
+the box.
+
+**`required: true` is a boot CONTRACT, not documentation.** Every required entry
+is resolved before any plugin activates, and one that does not resolve **aborts
+the boot** with the plugin named:
+
+```
+plugin environment validation failed (1 variable):
+  • STRIPE_SECRET_KEY — required by @voltro/plugin-billing, and nothing set it
+      Stripe API secret key.
+  → set the variable, or pass the value as a plugin option if the plugin takes one, or
+    declare it yourself in app.config.ts's `env` (an app declaration overrides a plugin's).
+```
+
+That is the point of failing at the boot: a deployment variable which silently
+stops being set — a rotated secret, a typo in a values file, a CI variable nobody
+created — is routine, and the alternative is finding out from the first customer.
+
+A `secret: true` variable resolves through the configured **secrets backend**,
+not just `process.env`. A backend that cannot answer fails the boot too, reported
+as *unreadable* rather than as an absent variable — those are different facts and
+need different next steps.
+
+Your own `defineEnv` declaration of the same variable **overrides the plugin's**:
+declare it there to give it a default, or to mark it optional because you pass
+the value as a plugin option instead.
 
 ## Anti-pattern
 

package/templates/agent-docs/data.md

@@ -5458,6 +5458,36 @@ error: Schema.Union(ConstraintViolation, MyDomainError),
 
 If you do not, it still reaches the client — collapsed to `InternalError` like any undeclared error, but carrying its own sentence (`ConstraintViolation: foreign key tasks_laneId_fkey on tasks: the referenced row does not exist`) rather than the opaque `Failed to execute statement` a raw `SqlError` produces.
 
+### When the FRAMEWORK refuses the write
+
+A few refusals are ours rather than the database's. The MySQL-family upsert has
+one: `ON DUPLICATE KEY UPDATE` fires on whichever unique key the incoming row
+violates, which may not be the one your `conflictColumns` named, so the store
+checks afterwards and rolls back when the statement reached a row those columns
+could not have selected. The database was perfectly happy — we are the ones
+saying no.
+
+These arrive as `ConstraintViolation` too, on the same failure channel and with
+the same `kind`, so nothing downstream needs a second branch. They were plain
+throws until 0.58.0, which made them **defects**: the client received a `Defect`
+wrapping a stringified `InternalError`, with no tag to match on, for a condition
+an app can genuinely branch on.
+
+They carry one extra field:
+
+```ts
+{ _tag: 'ConstraintViolation',
+  kind: 'unique', table: 'projectHours', operation: 'upsert',
+  detail: 'MysqlStore.upsert: the row written to …' }
+```
+
+`detail` is a sentence the framework authored, and it replaces the generated one
+in `message`. It is populated only for these refusals — never from a driver
+message, and never with a row value. That is the same rule the generated sentence
+follows: on several dialects the driver's own text contains row data, so it is
+not forwarded. A sentence we wrote carries exactly what we put in it.
+
+
 ## Loader errors
 
 Loaders run in the web app — they receive `{ params, query, headers, signal }`, NOT a server `ctx` with `.store`. A loader reaches the backend through `query(...)` (the `POST /rpc` path, server-side only). It short-circuits with the branded control-flow signals `NotFoundError` / `RedirectError`:

package/templates/agent-docs/database/scaling.md

@@ -368,10 +368,19 @@ A changelog table that every replica polls (`SELECT … WHERE seq > :last`) woul
 ```
 
 ```
-[voltro:dev] reactivity: cross-instance fan-out is OFF for dialect 'mssql'. A write on one replica
+[voltro:dev] reactivity: cross-instance fan-out is OFF for dialect 'cockroach'. A write on one replica
 will NOT reach clients on other replicas. Add @voltro/plugin-broadcast (Redis / NATS) to close the gap…
 ```
 
+**The line reports what is RUNNING, not what the dialect could run.** It is derived from the store's resolved change scope, so a dialect that *can* carry changes natively but has capture switched off — `CDC=0`, or an app where every table is `.nonReactive()` — is reported as the gap it is, naming the cause rather than the dialect:
+
+```
+[voltro:dev] reactivity: cross-instance fan-out is OFF. 'mariadb' can carry changes natively
+(binlog CDC) but change capture is not running — CDC=0, or every table is .nonReactive()…
+```
+
+Read that line, not the dialect, when you need to know whether the N² amplification below applies to you: without a native transport there is no second delivery to suppress.
+
 When BOTH a native path and the broadcast plugin are wired (e.g. postgres + broadcast), both stay active — and they carry **different things**. The native path carries table changes to every replica. The bus carries reactivity *channels* (`publishReactivity`), which are not database writes and so have no native transport at all.
 
 ```