@voltro/web 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -39,6 +39,74 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.36.0] — 2026-08-13
+
+### ⚠ BREAKING
+
+- **@voltro/integration-http, @voltro/plugin-atlassian** — A 401 from an upstream now produces `code: 'unauthorized'`, not `code: 'session_expired'`. The connection vault's own failure — where we DO know the credential is unusable — becomes `code: 'credential_unusable'`.
+
+  `session_expired` asserted a cause the status cannot support. A 401 says the credential was not accepted and says nothing about why: expired, revoked, insufficient scope and MALFORMED all produce it. A consumer's plugin sent ciphertext as a bearer token (a separate defect, fixed in the same release), the upstream answered 401, this name called it an expired session, and their health check acted on the name and deleted a valid session. Login loop, with every symptom pointing at a revoked credential.
+
+  Names get acted on, which is the whole reason to split them:
+
+  - `'unauthorized'` — the upstream refused. Non-transient, so still never retried; `status` rides along so a caller that knows more about its own upstream can decide for itself. Deciding for them is what this gives up. - `'credential_unusable'` — the connection vault could not produce a credential (no grant, revoked grant, refresh failed). Here the claim is ours to make, because the failure is ours rather than the far end's.
+
+  The 401 message stopped saying "session expired" too. It now says the credential was refused and that the reason is not in the response — which is the honest sentence and the one that would have saved the day this cost.
+
+  Its test asserts the CLAIM rather than banning the word: the first version forbade `/expired/i` and went red against the corrected message, which lists expiry as one of several things a 401 can mean. That distinction is the point of the change, so the assertion had to be about `session expired` specifically.
+
+  **`voltro update` carries you across this** — codemod `0.35.1/01_unauthorized-replaces-session-expired`.
+
+### Added
+
+- **@voltro/web** — **`apiSurface: compatible` — why the three altered golden lines cannot break a caller.** `LoaderContext` and `LoaderFn` each gained a type parameter WITH a default, so an unparameterised reference still resolves. The one that needed proving is `query?`, which went from a written-out signature to `LoaderQuery<Procedures>` — and `LoaderQuery` is a conditional whose false branch is character-for-character the previous signature. `unknown` does not extend `ProcedureTypeMap`, so the defaulted instantiation takes that branch.
+
+  Proved with `tsc` rather than by reading it: a probe asserting mutual assignability between `LoaderQuery<unknown>` and the old signature compiles, and inverting the probe fails — with tsc printing the resolved type as `<T = unknown>(tag: string, input?: Record<string, unknown> | undefined) => Promise<T>`, which is the old signature verbatim.
+
+  `LoaderContext` takes the app's procedure map, so a loader's `query` infers its input and output from the descriptor instead of returning `unknown`.
+
+  ```ts
+  import type { AppProcedures } from '<your-api>/rpcGroup'
+  
+  export const loader = async ({ query }: LoaderContext<AppProcedures>) => {
+    const rows = await query?.('bookmarks.list', { limit: 100 })
+    //    ^ inferred; an unknown tag or a wrong input shape is a compile error
+  }
+  ```
+
+  `AppProcedures` is generated already and has been for a while — it was wired to `createHooks` on the CLIENT and to nothing on the server, so every loader call site spelled its own output type by hand and a typo in a tag compiled. A consumer reported it twice.
+
+  The extraction reuses `ProcedureInput` / `ProcedureOutput` from `@voltro/client` rather than re-deriving them: a second answer to "what does this tag return" drifts the first time a descriptor field is renamed, and both answers look right in isolation.
+
+  Opt-in, and non-breaking: with no map named, the signature is the previous `<T = unknown>(tag: string, …)`. The framework cannot import an app's generated file, which is the same reason `createHooks<AppProcedures>` takes it explicitly.
+
+  Covered by a `.test-d.ts`, because the failure mode is "it compiles when it should not" and no runtime assertion can observe that. Two of its cases exist because the first version was vacuous: an `interface` fixture does not satisfy the map constraint (no implicit index signature — the codegen emits an alias for exactly this reason), so the typed branch fell back silently and every `@ts-expect-error` came back unused.
+
+### Fixed
+
+- **@voltro/cli** — The store a plugin receives through `bindDataStore` now carries the storage codec, so an `.encrypted()` column read through it decrypts.
+
+  A consumer measured both stores inside one request: `ctx.store` gave a 44-character plaintext PAT, and the store their plugin's `credentialsResolver` received gave 113 characters of `enc:v1:…`. Ciphertext is a syntactically valid bearer token, so nothing threw. Jira answered 401, `@voltro/integration-http` named that `session_expired`, their PAT health check did the reasonable thing with that name and deleted the session, and the user got login → dashboard → login forever. A configuration error in the costume of an authentication refusal, where every symptom pointed at the one explanation that was wrong.
+
+  The part worth recording is that `bootStoreCodec.ts` was written for exactly this, after it happened at two other seams, and its header predicts this consumer's symptom verbatim: "a route reading an `.encrypted()` column got the literal string `enc:v1:…` back … the failure reads as 'wrong credential'". The fix was applied per-seam. `bindDataStore` was not one of the seams anybody listed, so it happened a third time — and a per-seam test stayed green throughout, because it covered the two seams somebody remembered.
+
+  `bootStoreHandouts.test.ts` asserts the rule instead: no boot path hands a plugin the raw driver, on either boot path, with the wrapper applied before the handout. The codec needs no Subject — it is how a column is spelled on disk versus in JS — so there was never anything a boot-level store could not carry.
+
+  Also relevant to anyone who followed the 0.28.0 codemod: that codemod told apps to stop carrying a credential on the Subject and look it up in the resolver instead. Doing exactly that is what put an app on this seam, so the instruction and `.encrypted()` were not simultaneously satisfiable through it.
+- **@voltro/runtime, @voltro/cli** — The rpc/WebSocket query and stream arms now resolve row visibility before the executor sees a context. Fixes a 0.35.0 regression that made every read throw for an app with a registered row filter, and the older leak underneath it.
+
+  0.35.0 shipped two things for the row filter: the registration moved to `globalThis` (so a duplicate `@voltro/runtime` instance cannot hide it), and a scoped store built without a resolved scope started throwing instead of silently serving unfiltered rows. The first was a real fix for a real hazard. The second was correct in principle and immediately fatal in practice, because the framework itself had a path that did exactly what it now refuses.
+
+  The consumer who reported the original leak ran the two-line check we asked for and `getRowFilter()` was visible from their request path — so the instance split was NOT their cause, and our hypothesis was wrong. Their measurement is what found the real one: the refusal fired, meaning the registration was FOUND and `ctx.rowFilter` was still undefined at the store. Nothing was missing; a step was.
+
+  Four arms reach a request context. `makeOneShotQueryRunner` (REST) and `makeQuerySubscriber` (SSE) both `await withRowFilter(...)` and say so in a comment. The rpc query handler and the stream handler — each hand-copied into both boot paths — handed the raw request straight through. So a user's executor received a context whose `ctx.store` applied no row filter, on the two arms that carry the most traffic. It survived because subscriptions are refiltered per DELIVERY, which made a descriptor-returning query look correct end to end while the executor's own reads were not.
+
+  `withScopedRequest` is the seam that fixes it once: a request that already carries a scope passes through untouched (resolving twice would run the app's `load` twice per request), an app with NO filter stays fully synchronous, and an app with one gets an Effect — which every one of these call sites already accepts. A boot-path parity test pins both stream arms and the shared producer.
+
+  The refusal also stopped firing for a SYSTEM subject. That is not a softening: `resolveRowFilterScopeFor` returns `NO_ROW_FILTER` for a system subject, so the only correct value was already determined, and several legitimate paths (schedules, resumed workflows, the webhook trigger context) build a context directly with no scope. Demanding a decision there is what took the api down.
+
+---
+
 ## [0.35.0] — 2026-08-13
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -2,6 +2,9 @@ import { ComponentType } from 'react';
 import { Context } from 'react';
 import { ImgHTMLAttributes } from 'react';
 import { MouseEvent as MouseEvent_2 } from 'react';
+import { ProcedureInput } from '@voltro/client';
+import { ProcedureOutput } from '@voltro/client';
+import { ProcedureTypeMap } from '@voltro/client';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { Ref } from 'react';
@@ -500,7 +503,7 @@ export declare class LoaderCache {
 
 export declare const loaderCacheKey: (pattern: string, params: Readonly<Record<string, string>>) => string;
 
-export declare interface LoaderContext {
+export declare interface LoaderContext<Procedures = unknown> {
     readonly params: Readonly<Record<string, string>>;
     readonly pathname: string;
     /**
@@ -541,8 +544,24 @@ export declare interface LoaderContext {
      *  Present ONLY when the loader runs server-side (`voltro start` /
      *  `voltro dev` SSR). `undefined` for client-side loader invocations —
      *  in the browser, use `useSubscription` in the component for live data
-     *  instead; the loader's `query` is for SSR first-paint + `meta`. */
-    readonly query?: <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>;
+     *  instead; the loader's `query` is for SSR first-paint + `meta`.
+     *
+     *  UNTYPED by default, and typed by naming your app's procedure map — the
+     *  same map `createHooks` already takes, and the same extraction, so the two
+     *  cannot disagree about what a tag returns:
+     *
+     *      import type { AppProcedures } from '<your-api>/rpcGroup'
+     *
+     *      export const loader = async ({ query }: LoaderContext<AppProcedures>) => {
+     *        const rows = await query?.('bookmarks.list', { limit: 100 })
+     *        //    ^ inferred from the descriptor, and an unknown tag is an error
+     *      }
+     *
+     *  The default parameter keeps every existing loader compiling: with no map
+     *  the signature is the old `<T = unknown>(tag: string, …)`. It is opt-in for
+     *  the same reason `createHooks<AppProcedures>` is — the framework cannot
+     *  import an app's generated file, so the app has to name it. */
+    readonly query?: LoaderQuery<Procedures>;
 }
 
 /**
@@ -569,7 +588,17 @@ declare type LoaderEntry<T = unknown> = {
     readonly error: unknown;
 };
 
-export declare type LoaderFn<T = unknown> = (ctx: LoaderContext) => Promise<T> | T;
+export declare type LoaderFn<T = unknown, Procedures = unknown> = (ctx: LoaderContext<Procedures>) => Promise<T> | T;
+
+/**
+ * The loader's server-side `query`, typed by a procedure map when one is given.
+ *
+ * Reuses `ProcedureInput` / `ProcedureOutput` from `@voltro/client` rather than
+ * re-deriving them. A second extraction would be a second answer to "what does
+ * this tag return", and the two would drift the first time a descriptor field
+ * is renamed — the shape this repo already has scars from.
+ */
+export declare type LoaderQuery<Procedures = unknown> = Procedures extends ProcedureTypeMap ? <Tag extends keyof Procedures & string>(tag: Tag, ...input: Record<string, never> extends ProcedureInput<Procedures[Tag]> ? [input?: ProcedureInput<Procedures[Tag]>] : [input: ProcedureInput<Procedures[Tag]>]) => Promise<ProcedureOutput<Procedures[Tag]>> : <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>;
 
 /** The URL path a logical page takes for a given locale under URL-prefix
  *  routing: the default locale keeps the bare path, every other locale gets a

package/dist/ssr.d.ts

@@ -1,6 +1,9 @@
 import { ComponentType } from 'react';
 import { PipeableStream } from 'react-dom/server';
 import { PreloadSeed } from '@voltro/client';
+import { ProcedureInput } from '@voltro/client';
+import { ProcedureOutput } from '@voltro/client';
+import { ProcedureTypeMap } from '@voltro/client';
 import { ReactNode } from 'react';
 import { seedPreloadedSubscription } from '@voltro/client';
 import { StoreSeed } from '@voltro/client';
@@ -207,7 +210,7 @@ declare type InteractiveMode = 'full' | 'islands' | 'none';
 /** True for exactly the object {@link defer} returns. */
 export declare const isDeferredLoaderResult: (value: unknown) => value is DeferredLoaderResult;
 
-declare interface LoaderContext {
+declare interface LoaderContext<Procedures = unknown> {
     readonly params: Readonly<Record<string, string>>;
     readonly pathname: string;
     /**
@@ -248,11 +251,37 @@ declare interface LoaderContext {
      *  Present ONLY when the loader runs server-side (`voltro start` /
      *  `voltro dev` SSR). `undefined` for client-side loader invocations —
      *  in the browser, use `useSubscription` in the component for live data
-     *  instead; the loader's `query` is for SSR first-paint + `meta`. */
-    readonly query?: <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>;
+     *  instead; the loader's `query` is for SSR first-paint + `meta`.
+     *
+     *  UNTYPED by default, and typed by naming your app's procedure map — the
+     *  same map `createHooks` already takes, and the same extraction, so the two
+     *  cannot disagree about what a tag returns:
+     *
+     *      import type { AppProcedures } from '<your-api>/rpcGroup'
+     *
+     *      export const loader = async ({ query }: LoaderContext<AppProcedures>) => {
+     *        const rows = await query?.('bookmarks.list', { limit: 100 })
+     *        //    ^ inferred from the descriptor, and an unknown tag is an error
+     *      }
+     *
+     *  The default parameter keeps every existing loader compiling: with no map
+     *  the signature is the old `<T = unknown>(tag: string, …)`. It is opt-in for
+     *  the same reason `createHooks<AppProcedures>` is — the framework cannot
+     *  import an app's generated file, so the app has to name it. */
+    readonly query?: LoaderQuery<Procedures>;
 }
 
-declare type LoaderFn<T = unknown> = (ctx: LoaderContext) => Promise<T> | T;
+declare type LoaderFn<T = unknown, Procedures = unknown> = (ctx: LoaderContext<Procedures>) => Promise<T> | T;
+
+/**
+ * The loader's server-side `query`, typed by a procedure map when one is given.
+ *
+ * Reuses `ProcedureInput` / `ProcedureOutput` from `@voltro/client` rather than
+ * re-deriving them. A second extraction would be a second answer to "what does
+ * this tag return", and the two would drift the first time a descriptor field
+ * is renamed — the shape this repo already has scars from.
+ */
+declare type LoaderQuery<Procedures = unknown> = Procedures extends ProcedureTypeMap ? <Tag extends keyof Procedures & string>(tag: Tag, ...input: Record<string, never> extends ProcedureInput<Procedures[Tag]> ? [input?: ProcedureInput<Procedures[Tag]>] : [input: ProcedureInput<Procedures[Tag]>]) => Promise<ProcedureOutput<Procedures[Tag]>> : <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>;
 
 declare interface PageDescriptor<TLoaderData = unknown> {
     /** URL pattern, e.g. `/`, `/about`, `/users/[id]`, `/docs/[...slug]`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/web",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "The Voltro web framework — file-based routing, render modes (SSR / SSG / islands), the page-export contract, data hooks, and the browser mount.",
   "keywords": [
     "voltro",
@@ -53,8 +53,8 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.35.0",
-    "@voltro/ui": "0.35.0"
+    "@voltro/client": "0.36.0",
+    "@voltro/ui": "0.36.0"
   },
   "peerDependencies": {
     "@effect/platform": "^0.97.0",