@voltro/ai 0.58.0 → 0.60.0

package/CHANGELOG.md

@@ -39,6 +39,119 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.60.0] — 2026-08-31
+
+### ⚠ BREAKING
+
+- **@voltro/plugin-sentry** — **A declared failure no longer reaches Sentry by default, and the source-map upload now injects debug ids.** Two separate defects, both found by the same deployment on its first day of real server-side events.
+
+  **1. The contract was being reported as an incident.** The rpc interceptor skipped only clean interrupts; everything else went to `captureException`. So a failure declared in a procedure's `error:` union — the thing the client gets typed and branches on — arrived as `level: error`, `handled: yes`. The first server-side issue a deployment ever received was a person clicking a team they are not a member of.
+
+  Effect separates a failure from a defect, this framework leans on that split deliberately (a store refusal was made typed so an app could branch on it; an unlookupable conflict key was deliberately left a defect, because it is a broken call rather than a condition in the data), and a descriptor carries it in `error:`. Reporting both as an incident discarded that one layer up.
+
+  `shouldCapture` now skips a cause that is failures-ONLY. A defect is reported as before, including a defect that travelled beside a failure — the rule is failures-only rather than "any failure present" precisely so one cannot hide the other. `captureFailures: true` restores the old behaviour; a predicate keeps the ones that are signal.
+
+  **The browser half moved with it**, or the option would have been half-wired: a rejected call is an rpc error on the client too, published to the client error bus and captured by the browser bridge. `initSentryBrowser` takes the same option and applies it to `rpc.*` events carrying a `_tag`. Route render failures and `reportClientError` calls are never filtered — nobody declared those.
+
+  **2. `sentry-cli sourcemaps upload` does NOT write debug ids.** `inject` is a separate subcommand; `upload` only uses ids that are already present, and falls back to matching on the artifact NAME when they are not. That fallback cannot work for a server bundle: the artifact is named from `--url-prefix` (`~/chunk- ABC.js`) while the frame carries the absolute path the node process loaded, and nothing rewrites either side.
+
+  Measured downstream: 4300 artifacts uploaded, release finalised, every frame still minified. Nothing was red — the exact shape this code's own header warns about, an upload that matched nothing looking like one that worked. The comment above the uploader asserted the injection happened, which made it a description standing where a check belonged.
+
+  `inject` now runs first, over the same directories, and `sourcemapDebugIds.test.ts` drives the real binary to assert an id lands in both the JS and the map. `--url-prefix` stays as the fallback for the browser bundle, whose frames really are URLs.
+
+  The boot line names the new setting (`sentry active … captureFailures=false`), because a default the framework picks for you is one nobody finds again.
+
+  **`voltro update` carries you across this** — codemod `0.60.0/01_declared_failures_are_not_incidents`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.60.0).
+
+### Added
+
+- **@voltro/cli, @voltro/plugin-sentry** — **The web server process now initialises Sentry and reports its own errors.**
+
+  A framework app runs two server processes. `voltro serve` is the api, where `sentryPlugin()` initialises the SDK through the plugin lifecycle. `voltro start` is the web server — SSR, loaders, ISR, the revalidation legs — and it has no plugin lifecycle, so it had none.
+
+  That was not a cosmetic difference in boot output. A web pod legitimately logs less than an api pod, because it has no store, no rpc, no scheduler, no workflows and no plugins. What it also had was **no error reporting**: an SSR shell throw is caught, logged and answered with a 500, so no browser ever renders it and the client-side ErrorBoundary bridge cannot see it either. Both ends of the integration worked and the middle was dark — while the docs' "React render error ✅ auto" row, true of the client path, read as covering all of them.
+
+  Set `SENTRY_DSN` on the web deployment and the boot says `sentry active` with the same message and the same field names as the api half, from the same function — `initSentryServer` in `@voltro/plugin-sentry/server`, which the api plugin now calls too. One init, because a copy of `skipOpenTelemetrySetup`, the traces default, the overrides-first spread and the degrade-on-missing-SDK path would have drifted the moment either half gained a case.
+
+  Three deliberate asymmetries, each because the two processes are not the same thing:
+
+  - **`traces: false` on the web side.** The api contributes a span processor to the framework's tracer; the web server has no tracer at all, so tracing on would put `traces: true` in a boot line while nothing produces a span. - **No DSN is SILENT here.** On the api side `sentryPlugin()` is a declaration and an inert one contradicts it. There is no declaration here. - **`@voltro/plugin-sentry` must be installed in the WEB app.** With a DSN set and the package missing, the boot names the command rather than failing — monitoring must never be what stops a deploy.
+
+  Measured against a real production `voltro start`, both branches. Note that production `voltro start` loads the app's precompiled start bundle, so a web deployment picks this up when that bundle is rebuilt — the framework version alone is not enough.
+
+### Fixed
+
+- **@voltro/workflow, @voltro/runtime, @voltro/database, @voltro/cli, @voltro/plugin-sentry** — **Six raw writes removed from production log streams — and the guard that was supposed to catch them rewritten, because it was green for two independent reasons.**
+
+  A pod tail showed `[voltro:workflow] shard-lock coordination: row-based (dialect=mariadb, mode=row)` sitting between JSON records. `@voltro/logger` is what makes a line JSON in a pod and pretty on a TTY; a `process.stderr.write` bypasses that decision at exactly the place nobody looks, because a dev terminal renders both the same.
+
+  Fixed at the source: the workflow cluster layer (2), `rpcServer`'s computed-cache warning, the subscription outbox's and the RYW store's `warn`/`onError` defaults — those two are not fallbacks, the callers pass nothing, so the default IS the production path — and the migration file discovery's skip notice, which lands in the migrate job's stream.
+
+  **The guard is the part worth reading.** `prodLogDiscipline.test.ts` existed for this exact class and reported clean, for two reasons that had to be fixed separately:
+
+  - Its file set was a hand-written list of five. A guard that opts files IN says nothing about any file added after it was written. - Its matcher was LINE-LOCAL, so `process.stderr.write(` on one line and the `` `[tag] `` on the next never matched — 4 of the 9 call sites in the repo are written that way, including one in a file that WAS on the list. The guard had been pointed straight at an offender and called it clean.
+
+  It is opt-OUT now: every server-side package's source is scanned, exceptions carry a reason, and a second test fails if an exception's call site disappears — an allowlist entry for code that is gone reads as a rule with a hole in it.
+
+  Verified against a real `voltro serve` under `NODE_ENV=production`: 35 records, zero framework lines that are not JSON.
+
+---
+
+## [0.59.0] — 2026-08-30
+
+### ⚠ BREAKING
+
+- **@voltro/cli** — **`web.sourcemaps` moved to the top level of `app.config.ts`, and now covers every bundle the build minifies.**
+
+  It reached exactly one of them before: the vite CLIENT build. `voltro build` minifies four — the browser bundle, the SSR bundle, the `voltro start` bundle, and for an api app the precompiled entry plus the serve bundle that `voltro serve` actually runs — and none of the other three had a `sourcemap` option or a config path that could ask for one. `keepNames` rescues the identifiers that are read as strings and nothing else, so a frame out of the artefact production runs read `at Qo (serveEntry.js:236:76405)`.
+
+  The docs closed that hole with a sentence instead of a field: *server stack traces are un-minified already*. The built file says otherwise, and the server half is where it costs most — a schedule, a workflow step, a subscriber or a REST route has no browser caller whose frame could stand in for it.
+
+  A second field (`api.sourcemaps`) would have made the same mistake twice. "Do I want resolvable frames from this app" has one answer; how many bundles the build happens to emit is not the caller's business.
+
+  Three details that come with it:
+
+  - **The old spelling is REFUSED, not ignored.** A moved option that is silently dropped goes green, stops emitting maps, and is found by someone reading an unresolvable frame months later. - **Each output directory uploads under the prefix that matches how its files are named** — `~/assets` for the browser bundle, `~/` for the bundles a node process loaded. One prefix across both is wrong for one of them. - **The upload and sweep run at every exit of the build**, not after the client bundle. Sweeping there would have deleted the client maps before the server ones existed, leaving those neither uploaded nor deleted.
+
+  `minifiedBundlesCarryMaps.test.ts` asserts the property over the SET: every bundler options object in the CLI that turns minification on must also decide `sourcemap`. That is what was missing — not one option, three, because nothing was watching the class.
+
+  **`voltro update` carries you across this** — codemod `0.59.0/01_sourcemaps_moved_to_the_top_level`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.59.0).
+- **@voltro/ai** — **Speech has a cost path, and a built-in provider name can be taken over.**
+
+  Three changes, one thread: the speech seam existed and nothing could reach it.
+
+  **`registerSpeechProvider(name, provider, { replaceBuiltin: true })`.** Refusing `mock` / `openai` / `gateway` / `anthropic` outright was wrong, and the case that shows it is one the refusal could not see: a provider name is not always an alias the app chooses. `openai` is the segment 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. It keeps its own dispatch instead, for every provider rather than the colliding one. What the refusal protected is kept by putting the intent in the call.
+
+  **Registered providers resolve BEFORE built-ins.** The dispatch decided from a hard-coded list of built-in names, so without this the flag would let you register `openai` and never route to it — declared, documented, wired at zero call sites.
+
+  **`MeteredUsage` — a tally in characters or seconds.** Every speech vendor meters one of those; none meters tokens. A ledger that only knew tokens could not hold a speech call at all, so speech spend was not un-priced, it was *absent*. The token shape is untouched (it is what the AI SDK returns); the new shape is separate rather than a unit tacked onto `AiUsage`, because writing a character count into a field called `inputTokens` puts a lie in a row someone reads later.
+
+  `_voltro_ai_usage` gains a `unit` column, and `costSource` gains `'unpriced'`: a non-token unit with no supplied price is written with the real count and a zero cost rather than a fabricated one, since 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.
+
+  BREAKING for a caller that had narrowed `CostBreakdown['costSource']` to two values or reads `estimateCostUsd`'s return positionally. No call site changes SHAPE — the token path takes the same arguments and returns the same numbers — but a narrowing is user-authored code, so this carries a `manual` codemod rather than `none`: nothing here can be transformed (whether the third member belongs in your union is your decision), and the reader who needs it is exactly the one a "touches no user-authored code" line would have sent away. It also names the query that does not fail but answers wrongly: summing `_voltro_ai_usage` counts ACROSS units now adds characters to tokens.
+
+  **`voltro update` carries you across this** — codemod `0.59.0/02_costsource_gained_unpriced`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.59.0).
+
+### Added
+
+- **@voltro/ai** — **`GatewayModelInfo.raw`** — the `/v1/models` entry exactly as it came over the wire, beside the normalised fields.
+
+  Normalising is the right default: the union of `tags`, `supported_parameters` and `modalities` is framework knowledge, and every app on the gateway was writing those forty lines differently. But normalising is lossy by construction, and the fields it drops are not decoration — a picker built on the vendor's own capability tags, a pricing display that shows a structure we have not normalised, `zdr` and `no_training` kept apart instead of folded into `dataPolicy`.
+
+  Without `raw`, such an app fetches the endpoint a second time and maintains a second parser of the same response. One field rather than three more normalised ones, because the alternative asks the same question again at every field the gateway adds.
+
+  Absent on the injected-provider path, for the same reason `capabilities` is: that seam never saw a response, and an empty object would turn "no wire data" into the claim that the wire carried nothing.
+
+### Fixed
+
+- **@voltro/cli** — **`@sentry/cli` 3.x loads.** The loader read one export spelling — `module.exports = SentryCli`, which is 2.x. 3.x ships `exports.SentryCli = SentryCli`, so `mod.default` is a namespace object rather than the class, and a build with a source-map upload configured stopped with *could not be loaded*.
+
+  The framework cannot pin its way out of this: `@sentry/cli` is FSL-1.1-MIT, so it is not ours to depend on and the app installs it — which means `pnpm add -D @sentry/cli`, the command we ourselves print, resolves the latest. Reading one spelling turned our own documented instruction into a failing build.
+
+  All four positions are accepted now (both spellings, each of which `import()` presents twice), and the two failures are told apart: a package that resolved but had no readable constructor no longer says *install it*. That reading is what cost a pipeline — locally `require()` resolves and the binary is there, so nothing about the install looks wrong.
+
+---
+
 ## [0.58.0] — 2026-08-30
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -373,7 +373,7 @@ export declare interface AiUsageRecordInput {
     readonly model: string;
     readonly operation: string;
     readonly agent?: string | null;
-    readonly usage: AiUsage;
+    readonly usage: AiUsage | MeteredUsage;
     /** Override the price table (negotiated/volume pricing or unknown model). */
     readonly price?: ModelPrice;
     /** The ACTUAL per-call cost reported by the provider/gateway (USD). When set,
@@ -573,6 +573,9 @@ export declare const buildCopilotSystemPrompt: (schema: CopilotSchema) => string
  *  `execute` tools ignore it. */
 export declare const buildSdkTools: (tools: Record<string, AnyTool>, ctx?: ToolContext) => ToolSet;
 
+/** The names `generateSpeech` resolves without a registration. */
+export declare const BUILTIN_SPEECH_PROVIDERS: ReadonlyArray<string>;
+
 /**
  * Cancel an in-flight stream by id. Aborts its controller (the SDK call stops +
  * the stream emits a terminal `cancelled` error). Returns `true` if a live
@@ -734,7 +737,9 @@ export declare interface CostBreakdown {
      *  the ACTUAL per-call cost (authoritative); `estimated` = derived from the
      *  static price table (or zero for an unknown model). Analytics can flag
      *  estimated rows + a model that priced at zero. */
-    readonly costSource: 'gateway' | 'estimated';
+    readonly costSource: 'gateway' | 'estimated' | 'unpriced';
+    /** What `inputTokens`/`outputTokens` are counts OF. */
+    readonly unit: UsageUnit;
 }
 
 /** Open a new thread (the store generates the id). */
@@ -1018,7 +1023,7 @@ export declare const embedMany: (texts: ReadonlyArray<string>, config?: Embeddin
  * unknown model (or the `mock` provider) resolves to zero cost rather
  * than throwing, so cost accounting never breaks a call.
  */
-export declare const estimateCostUsd: (usage: AiUsage, opts: {
+export declare const estimateCostUsd: (usage: AiUsage | MeteredUsage, opts: {
     readonly model: string;
     readonly price?: ModelPrice;
     readonly actualCostUsd?: number;
@@ -1219,6 +1224,26 @@ export declare interface GatewayModelInfo {
      * through is a decision nobody makes.
      */
     readonly dataPolicy?: ModelDataPolicy;
+    /**
+     * The entry exactly as it came over the wire.
+     *
+     * The normalised fields above 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 `tags`, a pricing display that shows the vendor's own
+     * structure, `zdr` and `no_training` kept apart rather than folded into
+     * `dataPolicy`.
+     *
+     * Without it, an app with its own display fetches `/v1/models` a SECOND time
+     * and maintains a SECOND parser of the same response — and then has to decide
+     * again, at every new field the gateway adds, whether to wait for us. That is
+     * the decision this field removes, which is why it is one field and not three
+     * more normalised ones.
+     *
+     * Absent on the injected-provider path for the same reason `capabilities` is:
+     * that seam never saw a response, and inventing an empty object would turn
+     * "no wire data" into the claim "the wire carried nothing".
+     */
+    readonly raw?: RawGatewayModel;
 }
 
 /**
@@ -1410,8 +1435,21 @@ export declare interface GenerateSpeechOptions {
 
 export declare interface GenerateSpeechResult {
     readonly audio: GeneratedAudio;
-    /** The speech model spec reports no usage; present for surface parity. */
-    readonly usage?: MediaUsage;
+    /**
+     * What the call consumed.
+     *
+     * The speech model SPEC reports none, so a gateway-routed call still leaves
+     * this undefined. A REGISTERED provider is the other case, and it is not a
+     * property of the model any more: an app's own adapter knows the billed
+     * quantity, because its vendor invoices on it — characters for ElevenLabs,
+     * Cartesia and OpenAI, seconds for others.
+     *
+     * So it takes a `MeteredUsage` too, and that is what makes speech spend
+     * reachable: without a shape that can say "4200 characters", the number the
+     * adapter already has has nowhere to go, and `recordAiUsage` never sees the
+     * call at all. Not un-priced — absent from the ledger.
+     */
+    readonly usage?: MediaUsage | MeteredUsage;
     readonly providerMetadata?: unknown;
 }
 
@@ -1676,6 +1714,8 @@ export declare const isEvalDefinition: (value: unknown) => value is EvalDefiniti
  */
 export declare const isExternalWrite: (tool: McpToolInfo, namespace: string, policy: McpToolPolicy) => boolean;
 
+export declare const isMeteredUsage: (u: AiUsage | MeteredUsage) => u is MeteredUsage;
+
 /** Is this a rendered prompt or a bare string? The discriminator `aiStep` uses
  *  so `prompt:` can accept either without a wrapper type at every call site. */
 export declare const isRenderedPrompt: (value: unknown) => value is RenderedPrompt;
@@ -2047,6 +2087,23 @@ export declare type MessagePart = {
     readonly data: string;
 };
 
+/**
+ * A tally in a unit that is not tokens.
+ *
+ * Deliberately NOT `AiUsage` with a unit tacked on. Writing a character count
+ * into a field called `inputTokens` puts a lie in a ledger row that someone
+ * reads later, and a dashboard summing that column across units is wrong in a
+ * way nothing reports. The token shape is left exactly as it was — it is what
+ * the AI SDK returns, and text callers change nothing.
+ */
+export declare interface MeteredUsage {
+    readonly unit: Exclude<UsageUnit, 'tokens'>;
+    /** What went in — characters of text, say. */
+    readonly input?: number | undefined;
+    /** What came out — seconds of audio, say. */
+    readonly output?: number | undefined;
+}
+
 /** A scripted inline file the mock model emits on a turn (usually an image).
  *  `data` is base64 (a short ascii string works for assertions). */
 export declare interface MockFile {
@@ -2176,6 +2233,13 @@ export declare interface ModelPrice {
 /** The current merged price map (defaults + installed overrides). Overrides win. */
 export declare const modelPricing: () => Record<string, ModelPrice>;
 
+/** Both shapes, flattened to the two counts + the unit they are counts of. */
+export declare const normaliseUsage: (usage: AiUsage | MeteredUsage) => {
+    readonly unit: UsageUnit;
+    readonly input: number;
+    readonly output: number;
+};
+
 /**
  * Wrap a `streamText` `Stream<AgentEvent>` with the same `voltro.ai.call` span +
  * metrics. The stream never fails — usage arrives on the terminal `done` event,
@@ -2619,11 +2683,31 @@ export declare const registeredSpeechProviders: () => ReadonlyArray<string>;
  * Register a speech provider under a name.
  *
  * The name then works in `generateSpeech({ provider: { name, model, voice } })`.
- * It must not collide with a built-in (`mock`, `openai`, `gateway`,
- * `anthropic`): silently shadowing one would make a config mean something
- * different depending on import order.
+ * Taking over a built-in name needs `{ replaceBuiltin: true }` — see the option.
  */
-export declare const registerSpeechProvider: (name: string, provider: SpeechProvider) => void;
+export declare const registerSpeechProvider: (name: string, provider: SpeechProvider, options?: RegisterSpeechProviderOptions) => void;
+
+export declare interface RegisterSpeechProviderOptions {
+    /**
+     * Take over a BUILT-IN name (`openai`, `gateway`, `anthropic`, `mock`).
+     *
+     * Refusing these outright was wrong, and the case that showed it is one the
+     * refusal could not see: a provider name is not always an alias the app
+     * chooses. `openai` is the value the GATEWAY puts in its model ids, so it is
+     * what an app's stored catalog rows carry and what its picker submits. Told
+     * to pick another name, such an app cannot — it would have to rewrite
+     * persisted rows and live sessions — so it keeps its own dispatch instead,
+     * and the primitive stays unused for every provider, not just the colliding
+     * one.
+     *
+     * What the refusal was actually protecting is worth keeping: a SILENT shadow,
+     * where the same config means different things depending on which module
+     * loaded first. This flag keeps that property by putting the intent in the
+     * call. An override is then a decision someone wrote down, not an accident of
+     * import order.
+     */
+    readonly replaceBuiltin?: boolean;
+}
 
 /**
  * Register (or reuse) the `AbortController` for `streamId`. `streamText` calls
@@ -2648,6 +2732,9 @@ export declare interface RenderedPrompt extends PromptStamp {
     readonly definition: PromptDefinition;
 }
 
+/** Whether `name` is a registration standing in front of a built-in. */
+export declare const replacesBuiltinSpeechProvider: (name: string) => boolean;
+
 /**
  * Gate an AI call against a per-tenant USD budget with an ATOMIC reservation —
  * the cap precedent is billing's `requireEntitlement` / storage's
@@ -3525,6 +3612,16 @@ export declare type TranscriptionTimestamps = 'none' | 'segment' | 'word';
  */
 export declare const unregisterStream: (streamId: string) => void;
 
+/**
+ * What a call was billed in.
+ *
+ * Text is tokens. Speech is not: every speech vendor meters CHARACTERS of input
+ * or SECONDS of audio, and none of them meters tokens. A ledger that only knows
+ * tokens therefore cannot hold a speech call at all — which is why speech spend
+ * was invisible rather than merely un-priced.
+ */
+export declare type UsageUnit = 'tokens' | 'characters' | 'seconds';
+
 /**
  * Validate a proposal against the schema and (on success) build a read-only
  * `QueryDescriptor`. EVERY table/column the proposal names must exist in the