@voltro/cli 0.57.0 → 0.59.0

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

@@ -222,7 +222,7 @@ 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-Bl9HqtV7.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -802,6 +802,60 @@
         "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.59.0",
+        "id": "0.59.0/01_sourcemaps_moved_to_the_top_level",
+        "title": "`web.sourcemaps` moved to the top level of app.config.ts",
+        "kind": "transform"
+      },
+      {
+        "version": "0.59.0",
+        "id": "0.59.0/02_costsource_gained_unpriced",
+        "title": "`costSource` gained `unpriced`, and AI usage is counted in a unit",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -884,24 +938,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.57.0",
-    "@voltro/cache": "0.57.0",
-    "@voltro/client": "0.57.0",
-    "@voltro/content": "0.57.0",
-    "@voltro/data-transfer": "0.57.0",
-    "@voltro/database": "0.57.0",
-    "@voltro/env": "0.57.0",
-    "@voltro/kv": "0.57.0",
-    "@voltro/logger": "0.57.0",
-    "@voltro/plugin-auth": "0.57.0",
-    "@voltro/plugin-broadcast": "0.57.0",
-    "@voltro/plugin-mail": "0.57.0",
-    "@voltro/plugin-storage": "0.57.0",
-    "@voltro/plugin-webhooks": "0.57.0",
-    "@voltro/protocol": "0.57.0",
-    "@voltro/runtime": "0.57.0",
-    "@voltro/serverless": "0.57.0",
-    "@voltro/workflow": "0.57.0",
+    "@voltro/ai": "0.59.0",
+    "@voltro/cache": "0.59.0",
+    "@voltro/client": "0.59.0",
+    "@voltro/content": "0.59.0",
+    "@voltro/data-transfer": "0.59.0",
+    "@voltro/database": "0.59.0",
+    "@voltro/env": "0.59.0",
+    "@voltro/kv": "0.59.0",
+    "@voltro/logger": "0.59.0",
+    "@voltro/plugin-auth": "0.59.0",
+    "@voltro/plugin-broadcast": "0.59.0",
+    "@voltro/plugin-mail": "0.59.0",
+    "@voltro/plugin-storage": "0.59.0",
+    "@voltro/plugin-webhooks": "0.59.0",
+    "@voltro/protocol": "0.59.0",
+    "@voltro/runtime": "0.59.0",
+    "@voltro/serverless": "0.59.0",
+    "@voltro/workflow": "0.59.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.57.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.59.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.57.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.59.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",

package/templates/agent-docs/ai.md

@@ -172,6 +172,52 @@ 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`.
+
+Plus **`raw`** — the entry exactly as it came over the wire.
+
+The normalised fields are the shared answer to the questions every app on the gateway asks. `raw` is for the ones only one app asks: a chips row built from the vendor's own `tags`, a pricing display that shows a structure we have not normalised, `zdr` and `no_training` kept apart instead of folded into `dataPolicy`.
+
+```ts
+const models = await readGatewayCatalog({ modality: 'language' })
+const chips = models[0]?.raw?.tags            // vendor's own vocabulary
+const audioRate = (models[0]?.raw?.pricing as { audio_per_second?: string })?.audio_per_second
+```
+
+Without it, an app with its own display fetches `/v1/models` a second time and keeps a second parser of the same response — and then has to decide again, at every field the gateway adds, whether to wait for a framework release. That is the decision `raw` removes, which is why it is one field rather than three more normalised ones.
+
+It is absent on the injected-provider path (the seam a test uses), for the same reason `capabilities` is: that path never saw a response, and an empty object would turn "no wire data" into the claim "the wire carried nothing".
+
+`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.
@@ -1623,6 +1669,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 +2527,167 @@ 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.
+
+#### Taking over a built-in name
+
+`mock`, `openai`, `gateway` and `anthropic` resolve without a registration, and shadowing one by accident would make the same config mean different things depending on which module loaded first. So it takes a flag:
+
+```ts
+registerSpeechProvider('openai', myOpenAiTts, { replaceBuiltin: true })
+```
+
+The flag exists because a provider name is not always an alias you choose. `openai` is the value the gateway puts in its model ids, so it is what a stored catalog's rows carry and what a picker submits — an app told to pick another name cannot, without rewriting persisted rows and live sessions. Refusing outright did not protect that app; it made it keep its own dispatch for every provider, not just the colliding one.
+
+What the refusal was protecting is kept: the intent is now in the call, so an override is a decision someone wrote down rather than an accident of load order. Registered providers are resolved **before** built-ins — otherwise the flag would let you register a name and never reach it.
+
+### Cost — speech is not billed in tokens
+
+`generateSpeech` never records a ledger row itself; it returns `usage` and you pass it to `recordAiUsage`, the same as `generateText`. The difference is the unit. Every speech vendor meters characters of input or seconds of audio, so a `usage` shape that only knew tokens could not hold the call at all — speech spend was not un-priced, it was **absent**.
+
+A registered provider returns a `MeteredUsage`:
+
+```ts
+synthesize: (request) => Effect.succeed({
+  audio,
+  usage: { unit: 'characters', input: request.text.length },
+})
+```
+
+```ts
+yield* recordAiUsage(store, {
+  provider: 'elevenlabs', model: 'eleven_turbo_v3', operation: 'generateSpeech',
+  usage: { unit: 'characters', input: 4200 },
+  price: { inputPer1M: 30, outputPer1M: 0 },   // your rate, in your unit
+})
+```
+
+The ledger row carries `unit` beside the two counts. **A non-token unit is never priced by the token table**: without a `price` or an `actualCostUsd` the row is written `costSource: 'unpriced'` with the real count and a zero cost, because a per-1M-token rate applied to a character count produces a number indistinguishable from a real one. Sum the count columns grouped by `unit`, never across it.
+
+## 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? |

package/templates/agent-docs/cli.md

@@ -1455,13 +1455,14 @@ web: {
   // `dist/assets/` to the prefix on deploy. Filenames are content-hashed, so a
   // previous deploy's assets stay valid for a visitor mid-navigation.
   assetPrefix: 'https://cdn.example.com/_assets',
-
-  // Emit `.map` files WITHOUT a `//# sourceMappingURL` comment, so nothing in
-  // the shipped JS points at them. For `plugin-sentry`: upload them in your
-  // deploy step and DELETE them before the image is built. `voltro start`
-  // refuses to serve a `.map` regardless, so a forgotten delete is not a leak.
-  sourcemaps: 'hidden',
 },
+
+// Top level, NOT under `web:` — it covers every bundle the build minifies
+// (browser, SSR, start, and an api app's serve bundle). Emits `.map` files with
+// no `//# sourceMappingURL` comment, so nothing shipped points at them.
+// `plugin-sentry` can upload and sweep them for you; `voltro start` refuses to
+// serve a `.map` regardless, so a forgotten delete is not a leak.
+sourcemaps: 'hidden',
 http: {
   // Node hangs up an idle keep-alive connection after 5s; every proxy in front
   // holds one longer, and the request that lands in that window comes back as

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/transactions.md

@@ -263,6 +263,54 @@ await ctx.store.upsert('orgSlugs', {
 Requires a composite UNIQUE constraint on the table — declare it via
 `.unique([cols])` in the schema (see [Indexes](/docs/database/indexes#composite-unique-constraints)).
 
+### The row you get back is the row that was there
+
+When an upsert on a non-`id` key MATCHES, it updates the existing row — and that
+row keeps its own `id`. The `id` you passed is the one that would have been used
+had it inserted, so a fresh id on every call is the normal shape:
+
+```ts
+await ctx.store.upsert('projectHours', {
+  teamId: 't-1', year: 2026, hours: 111,
+}, {
+  conflictColumns: ['teamId', 'year'],
+  update: ['hours'],
+})
+```
+
+The returned row carries the id of whichever row now holds those values. Compare
+values, not ids, if you need to know whether you inserted or updated.
+
+On MySQL and MariaDB this costs one extra guarantee, because the dialect cannot
+express the question. Postgres names its target — `ON CONFLICT (teamId, year)`
+fires on that index and nothing else — while `ON DUPLICATE KEY UPDATE` fires on
+whichever unique key the incoming row violates, which may not be the one you
+named. The store therefore checks afterwards that the row it reached carries your
+conflict values, and refuses the write if it does not: that row would have
+absorbed your values while your row was never written. The refusal names the
+differing column; the values go to the server log rather than into a sentence
+that may reach a user.
+
+A conflict column the database GENERATES cannot be checked this way — its value
+is never in the row you sent. The remaining columns are still compared; if a
+conflict key consists ENTIRELY of generated columns there is nothing to compare,
+and the upsert refuses rather than guessing.
+
+### Generated columns in a conflict key
+
+A partial-unique index on MySQL/MariaDB is usually a STORED generated column plus
+NULL-distinct semantics — the key constrains only the rows the expression marks.
+An upsert can conflict on such a key, but only on the path where the DATABASE
+evaluates the expression: the single-statement form, reached on MariaDB when the
+row is a complete INSERT row and `update` is a column list.
+
+The other path looks the row up by value first — it has to, because a function
+`update` needs the existing row to compute its patch — and the value of a
+generated column is not in the row you passed. There is no substitute for it, so
+that combination refuses and names the column rather than guessing at one.
+Postgres has no such split: `ON CONFLICT` names its index and the server
+evaluates the column.
+
 ## `insertIgnore` — keep existing on conflict
 
 For idempotent write patterns where you want to ensure a row exists

package/templates/agent-docs/observability.md

@@ -513,7 +513,7 @@ others. The answer is `fleet`-scoped and says what it is missing:
 }
 ```
 
-Three properties are deliberate:
+Four properties are deliberate:
 
 - **A replica that has written nothing is `missing`, not absent.** Dropping it
   would make a partial answer look complete — the same unlabelled sample, one
@@ -521,9 +521,20 @@ Three properties are deliberate:
 - **A stale row is reported with its `ageMs`, not filtered out.** Removing it
   hides that the answer is partial; keeping it unmarked presents fiction as
   current.
+- **A row from a replica that is GONE is `departed`, not stale.** These are
+  different facts with different next steps: a stale row belongs to a replica
+  membership still lists, so it is running and has stopped refreshing — a fault,
+  and a reason for `complete: false`. A departed row belongs to a process that
+  exited; that is what a scale-down looks like, and it is not a reason for
+  anything. Conflating them made `complete` unreachable after any replica had
+  ever exited. They are still listed, with their age, because a reader who
+  cannot see them cannot tell a fleet that scaled down from a table being
+  written by something nobody is tracking.
 - **Mixed versions are named** in `completeness.versions` when the responders
   disagree. A rolling deploy spans two shapes, and averaging them silently is
-  wrong in a way nothing downstream can detect.
+  wrong in a way nothing downstream can detect. Departed replicas are excluded
+  from the tally — a process that has been dead for hours reporting a "version
+  split" is a line somebody acts on.
 
 **If there is no shared store, the request is refused with `501`** and a reason
 — never answered with this replica's own numbers. Handing back a sample to

package/templates/agent-docs/plugins/auth-supabase.md

@@ -87,6 +87,27 @@ const resolve = composeAuthStrategies([
 | `defaultTenantId` | (none) | Fallback for single-tenant deployments. |
 | `scopesFromClaims` | (none) | Map claims (Supabase `role`, or an `app_metadata` permissions array) → `Subject.scopes`. |
 
+### `jwtSecret` may be a function — and should be, if you build an image
+
+`voltro build` imports `app.config.ts`, so anything the config CONSTRUCTS runs at
+build time. `jwtSecret: process.env.SUPABASE_JWT_SECRET` therefore makes an image
+build need a production credential for a bundle that will not contain one, and a
+placeholder is not an option — the framework ships no secret values, and an
+`ARG SUPABASE_JWT_SECRET` in a Dockerfile is exactly that.
+
+Pass a function instead:
+
+```ts
+supabaseStrategy({ jwtSecret: () => process.env.SUPABASE_JWT_SECRET })
+```
+
+The build never calls it. The BOOT does, once, through the strategy pass both
+`voltro dev` and `voltro serve` share — so an unset variable still refuses to
+start, with the strategy's id in the message. Deferring the read does not defer
+the failure to the first request: an auth strategy that cannot verify a token
+accepts nobody, and a process that started anyway serves a login that can never
+succeed.
+
 Algorithms follow the mode — JWKS pins `['RS256', 'ES256']`, `jwtSecret` pins `['HS256']`; the two are mutually exclusive, so there is no alg-confusion downgrade surface (an RS256 setup can't be tricked into accepting an HS256-forged token). `none` is never accepted.
 
 ## Environment variables