@voltro/react-native 0.38.0 → 0.39.1

package/CHANGELOG.md

@@ -39,6 +39,282 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.39.1] — 2026-08-16
+
+### Fixed
+
+- **@voltro/runtime, @voltro/cli** — An app-registered tuple source is no longer replaced by the framework default.
+
+  Both boot paths carried this comment, verbatim:
+
+  > An app whose relationships live in its own tables overrides with > `setTupleSource`.
+
+  and then called `setTupleSource(default)` **unconditionally**. That call runs AFTER the app's startups — `runBootLifecycle` at `dev.ts:3910` and `serveCommand.ts:869`, against the registration at `dev.ts:4065` and `serveApi.ts:937` — and `setTupleSource` is last-write-wins. So the framework won every time: an app registering its own source in a `*.startup.tsx`, which is what the docs tell it to do, had it silently replaced.
+
+  The consequence is not subtle. Every relationship guard would then be answered from `_voltro_rebac_tuples` — empty, for exactly the app that keeps its relations in its own tables — so every guard DENIES, fail-closed, with a `no tuple source` warning that never fires because a source *is* registered: the wrong one.
+
+  The comment was not wrong about the design; it described the design while the code removed it. Same shape as the `DORMANCY_WAKEUP_TENANT` scar — equal by value at both call sites, so nothing could fail, and the comment was the only place the intent survived.
+
+  `registerDefaultTupleSource` fills the gap only when nobody else did, and returns whether it acted so the boot can say which source is live instead of leaving an operator to guess. `setTupleSource` itself is unchanged: an app calling it twice still gets the second one, because narrowing that would trade one silent surprise for another.
+
+  Found while re-checking a consumer's claim that a different item was still open. It was not — but it sits beside this, and this is the one that would have bitten them. Pinned in both directions: a unit test for the registrar, and a source guard asserting neither boot path installs `loadResourceTuples` through `setTupleSource` again. Red-verified by restoring the original line.
+- **@voltro/cli** — `voltro doctor` no longer reports "scope vocabulary: none found" when it could not read the config at all.
+
+  A consumer HAD configured `doctor.scopeVocabulary` and still read `none found`. The cause was not their vocabulary: `app.config.ts` could not be imported outside their pod — an auth strategy demands its secret while the config is evaluated — so the vocabulary was never read. Inside the pod the message disappears and the rule runs.
+
+  "You have no vocabulary" and "I could not look" are different states, and only the first is a statement about their app. This section already made exactly that distinction one member earlier — its own comment reads **DORMANT AND CLEAN MUST NOT PRINT THE SAME** — and then collapsed the third.
+
+  The signal existed and was not connected. `offlineManifest` deliberately survives an unimportable config (a doctor run must not die on one), so the empty vocabulary arrived looking like a real absence, while the same failure was reported a hundred lines earlier under plugin tables. The consumer read the section about scopes and searched at the wrong end — which is the correct way to read a report.
+
+  The rule now probes importability before claiming an absence, and says so:
+
+  ```
+  •  scope vocabulary: NOT EVALUATED — `app.config.ts` could not be imported.
+     This is not a statement about your scopes: the rule never got to read them.
+     … The same import failure is reported above for plugin tables; both sections
+     have this one cause.
+  ```
+
+  The dormant case keeps its own wording, so a quiet run on an app that genuinely publishes no vocabulary is not relabelled as a broken config.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/cache, @voltro/kv** — The RESP TTL tests in `@voltro/cache` and `@voltro/kv` stopped measuring the machine. Test-only; no product code changed.
+
+  Both wrote a key with `ttlMs: 150`, asserted it was still there, then slept 300 ms and asserted it was gone. The second half is fine — waiting LONGER only strengthens "it expired". The first half was a race: the write and the read are two round-trips, so on a loaded runner the key legitimately expired before the liveness assertion, and the test reported a defect that was not there. It failed exactly that way on a release gate, in the keydb engine, while passing locally with 24/24 green.
+
+  Now: a 2 s window, so liveness has real headroom rather than 150 ms of it, and the expiry is awaited as a CONDITION (`awaitGone` polls) rather than as a duration. Idle machines finish in about the TTL; loaded ones take as long as they need; a key that never expires still fails, because the ceiling is a failure mode and not a timing assumption.
+
+  Fixed in BOTH packages in one change. The two files carried the identical construction, and this repo's standing lesson is that a fix landing in one copy of a duplicated shape leaves the other one broken — `@voltro/kv` had not failed yet, which is a statement about luck rather than about the test.
+
+  `@voltro/kv`'s header also pointed at `../cache/test/docker-compose.yml` for bringing the engines up. That path does not exist; there is one compose file, at the repo root.
+
+---
+
+## [0.39.0] — 2026-08-16
+
+### Added
+
+- **@voltro/client, @voltro/web, @voltro/cli** — A preload that fails server-side now says so in the hydration payload, so a page can tell "still loading" from "actually empty".
+
+  Reported by a consumer whose session cookie had outlived the IdP's token lifetime — for them, practically every first page view of the day. Every `preload` on the page failed at once, the api having resolved the caller to anonymous:
+
+  WARN [voltro:dev:web] preload seed failed tag=projects.getById … ScopeError — missing required scope 'project:r:o'
+
+  The page rendered a skeleton title over an empty table, and that WARN was the only record anywhere. **The client saw exactly what it sees for a page that declares no preload at all** — both arrive as the absence of a seed — so no app could distinguish the two without inventing a convention of its own. The reporting consumer did exactly that, page by page.
+
+  `usePreloadedSubscription` now returns `preloadFailed: true` in that case:
+
+  ```tsx
+  const projects = usePreloadedSubscription<Project[]>('api', 'projects.list')
+  
+  if (projects.loading) return <Skeleton/>
+  if (projects.preloadFailed) return <Spinner label="Loading…"/>   // not empty — unasked
+  return <Table rows={projects.data}/>
+  ```
+
+  It says nothing about WHY, deliberately: the server's failure text is a refused call's error message and belongs in the server log, which is the one place a browser cannot read. A boolean is the whole contract. It also says nothing about the LIVE subscription, which usually recovers on its own — the browser reconnects with a credential the SSR request did not have. So the honest reading is "the first paint has no server data, and that was not for lack of asking", which is exactly enough to choose a spinner over an empty state.
+
+  `seedPreloadedSubscriptionFailure` is exported from `@voltro/web/ssr` beside `seedPreloadedSubscription` for a loader that runs its own preloads.
+
+  Two shape notes, both deliberate:
+
+  - **The field is widened on THIS hook, not on `SubscriptionState`**, so no existing `useSubscription` call site is un-narrowed by it — the same scoping rule the `skip`/`idle` overload follows. - **`seedFailure` is REQUIRED on the internal preload runner, not optional.** This is the hook whose omission WAS the defect, and an optional hook is an omissible one — the same mistake with a nicer name that cost us `startOutboxRunner`'s teardown. Making it required is what listed all three render paths (dev, start, static prerender) at the compiler rather than at review.
+- **@voltro/web, @voltro/cli** — `LoaderContext.isServer`, and the type now says a loader runs TWICE.
+
+  Reported after two days of debugging: a loader carried a server-only call, and nothing in `LoaderContext` said the same function runs again in the browser on every in-app navigation. The consumer read "runs once per request" into the gap, which is the reading the wording invited.
+
+  **The docs were worse than a gap — they contradicted themselves.** The loaders page opened with "the page's server-side data hook" and its first code sample carried the comment `// Server-side fetch — runs on the Node side, never in the browser`, while 230 lines further down the same page said "on a client-side navigation … the loader runs in the browser". A reader who hits the false line first stops looking. Both are corrected, in both languages, and the precondition is now the first thing the page states.
+
+  **Why it survived two days is the part worth repeating:** a client-only failure is invisible to every probe that does not NAVIGATE. A fresh page load, a `curl`, any SSR check all take the server path and pass. Only clicking a link inside the running app reaches the other one.
+
+  `ctx.isServer` is the supported discriminator, because the two things that look like they answer the same question do not:
+
+  - `query` is absent in the browser, so `if (ctx.query)` appears to work — but it branches on the ABSENCE OF A FUNCTION, which says nothing about why it is absent and breaks the moment anything else becomes conditional; - `headers` is `{}` in the browser, **not** `undefined`, so `if (ctx.headers)` is TRUE on both paths. The reporter checked exactly that, and it silently did nothing.
+
+  It is REQUIRED rather than optional: an optional boolean is omissible, and a server path that forgot it would read as `undefined` — falsy — and claim to be the browser, which is the precise failure the field exists to prevent. The compiler names every client construction site; the three SERVER render paths build their context as untyped literals, so `loaderIsServer.test.ts` derives those by shape and fails on one that omits it (red-verified against a removed line, which named the file and offset).
+- **@voltro/react-native, @voltro/client, @voltro/web, @voltro/cli** — React Native gets the whole client, not half of it. `startMobileApis()` connects and re-dials over the **same** supervisor `@voltro/web` uses — the supervisor moved into `@voltro/client` rather than being copied, because a second copy of its stale-seed gate (the rule that stops one subject's rows appearing in the next subject's screens) is a second thing to keep correct. Web's two browser-specific behaviours are injected options now: the devtools status entry and the dev-only wedge reload.
+
+  `voltro codegen` in a mobile app writes `.framework/mobileApis.generated.ts` from `voltro.mobile.ts` — which apis the app talks to, and where each one's rpc group and descriptors come from. Only the binding is generated; the procedure types ride the import of the api's own `rpcGroup`, so a schema change needs no regeneration. The ws URL is a runtime parameter and deliberately not baked in: `localhost` on a phone is the phone, and `resolveDevWsUrl()` takes the LAN host Expo already knows.
+
+  `createAsyncStoragePersistence()` makes `defineStore({ persist })` work on a device. A store reads during render and a render cannot await, so it hydrates into memory once — awaited before the first screen — then serves reads synchronously and writes through, coalescing per tick. A storage with no `getAllKeys()` and no declared `keys` refuses rather than hydrating empty: an empty cache is indistinguishable from a first run.
+
+  `useMobileConnectionStatus()` takes an optional `onlineSource`. Its default reads `navigator.onLine`, which React Native does not have — so on a device it answered "online" forever, airplane mode included. Pass `netInfoOnlineSource(NetInfo)`. `isInternetReachable` is believed only when it is a boolean, because NetInfo reports `null` while its probe is out and reading that as offline flashes a banner on every cold start.
+
+  Two type declarations were WRONG, and running the mobile template through the scaffold harness is what said so — nothing else in the repo typechecks a generated entry, on web either.
+
+  `ClientDescriptorMap` was a structural copy of `@voltro/protocol`'s `ClientDescriptor` that narrowed `source` to one string while the real descriptors carry several. It is now that type, not a copy of it. And an api's `group` is the erased `RpcGroup.Any`: `RpcGroup` is declared `in out` in @effect/rpc, so the CONCRETE group codegen emits was never assignable to `RpcGroup<Rpc.Any>` — the boundary rejected the only value anyone passes it. Erasing at the boundary and restoring at the call site is what `ApiHandle.client` already does; the one cast is where the rpc client is built.
+
+  `dispatchDeepLink()` is new for the same class of defect. `matchFirstDeepLink` returns a descriptor from a heterogeneous array, so its handler declares `Record<string, never>` params while the match hands back `Record<string, string>` — the result could not be invoked by anyone.
+
+  `apiSurface: compatible` — every changed declaration either widens what a producer may pass or replaces a type that misdescribed its own values. Code written against the narrow `source` was already wrong at runtime, and no call that compiled before stops compiling. `useMobileConnectionStatus` gained an optional parameter.
+
+  Not verified here, and not implied: that the loop runs on a device. Everything above is unit-tested without a simulator, and only a simulator can prove Metro. That is an Expo/EAS CI step.
+- **@voltro/runtime** — A `TupleSource` receives the whole `subject`, not just `subjectId`.
+
+  Reported precisely, from a guard review rather than an outage. `subjectId` cannot express a CREDENTIAL that is narrower than the person holding it, and an API key is exactly that: the key's binding lives in the subject's `metadata` (`keyType`, `teamId`), while `subject.id` is the OWNING USER. A tuple source could therefore only resolve the owner's memberships and was blind to which team the key was minted for — so an owner who belongs to two teams passed the guard for both. The comment beside their hand-written check says what that costs:
+
+  > Without the binding check below a key minted for team A worked on every team > in the org.
+
+  Nothing was ever wrong in their app, because they kept the executor-side check. The defect is that a DECLARED guard could not replace it:
+
+  ```ts
+  setTupleSource(async (req) => {
+    const boundTeam = req.subject.metadata?.teamId
+    if (boundTeam !== undefined && boundTeam !== req.resourceId) return []
+    return loadResourceTuples(store, req.subjectId, req.resourceType, req.resourceId)
+  })
+  ```
+
+  A guard that must always run paired with a hand-written check is not a declaration — it is a comment with a type signature. And the pairing is exactly the thing nobody re-derives when they delete the "redundant" half a year later; the reporter had already written the reason into their parity test to stop that happening.
+
+  `subject` is typed as the full union deliberately: its system and anonymous members carry no `scopes` or `metadata`, so the narrowing is the caller's to do and is visible where it happens.
+- **@voltro/cli** — A declared relationship guard whose `resourceType` is not registered now refuses the boot instead of denying every caller forever.
+
+  The report described the shape exactly: an app arms its authorization from a startup (`defineResourcePolicy` + `setTupleSource`). If that registration does not happen, the app boots **clean**, takes traffic, and every procedure with a declared guard refuses from then on. Fail-closed, so nothing leaks — and a total outage of the guarded surface whose only signal is a log line nobody reads, because the boot was green. At their size: 39 procedures — team settings, hours import, role administration.
+
+  Since 0.38.0 a `*.startup.tsx` that THROWS already refuses the boot, so the sequence they described is closed. This gate exists because that fix covers only the throwing case, while the same silent outage arrives by three doors no startup-error handling can see:
+
+  - the startup registers some types and not the one a guard names — a typo in a `resourceType` is not a compile error, it is a string on one side and a string on the other; - the file was renamed out of the discovery pattern, so it never ran and never threw; - the registration was conditional on something false at boot.
+
+  All three end in the same place, and the framework can rule out all three by asking one question it already holds both halves of: which `resourceType`s does the discovered surface NAME, and which are REGISTERED?
+
+  The refusal names the type, the count and the procedures that demanded it — grouped by type, because the fix is one `defineResourcePolicy` per type while the damage is per procedure. It also names the spelling trap, since nothing else in the system compares those two strings.
+
+  **Why refuse rather than warn**, because "fail-closed already, so it is safe" is the plausible objection: safe is not working. The procedures are DOWN, and down-with-a-warning is precisely the state being reported. A refusal is recoverable in seconds and impossible to miss.
+
+  It runs after the startups have settled, on both boot paths — not beside `assertProcedureAccessDecisions`, which reads declarations and can run at discovery. This one reads a registry the app fills during its startups, and placing it earlier would have failed every app that registers from one, which is all of them. A check that fails on everything gets deleted rather than fixed.
+
+### Fixed
+
+- **@voltro/client** — A timer no longer discards the optimistic preview of a write the server confirmed. **A rollback happens if and only if the write FAILED.**
+
+  Measured by a consumer on a Gantt bar: drag it, the server writes, the mutation reports success — and five seconds later the bar jumps back. They suspected the server first and proved it was holding the data correctly, reasons included, before finding that the client was throwing the confirmed patch away itself.
+
+  The cause was one line: `confirmByMutation` armed a `setTimeout` calling `revertByMutation` — **the same function the FAILURE path calls**. Success and failure ended in the same discard, one immediately and the other five seconds later.
+
+  What makes it unambiguous is WHEN that timer could fire at all. Any server event already retires confirmed patches through the seamless hand-off, so the window only ever expired while `base` was still STALE. The revert therefore replaced a value that reflects the committed write with one the client knows does not:
+
+  | | keep the patch | revert (before) | |---|---|---| | delta arrives later | invisible hand-off | 5s of stale, then a jump back and forth | | delta never arrives | matches what is saved | **contradicts what is saved, permanently** |
+
+  The bottom-right cell is the damage: the user watches their saved change disappear and either redoes it or plans on a state they believe was not stored. A "leaked" patch is gone on the next subscription; a silent revert is healed by nothing.
+
+  Expiry is now a **resync**: the client re-issues that subscription, keeps the patch, and says so loudly on the error bus (`voltro logs`) — the silence was the second half of the report, because in the UI this is indistinguishable from "the server did not save it", which is the false trail they followed first.
+
+  **Two more seams of the same defect, both found while fixing it:**
+
+  - **An `error` event retired confirmed patches.** An error does not advance `base` — it sets `baseError` and leaves the rows where they were — so dropping there discarded a committed write's preview for nothing. - **A resync whose snapshot comes back UNCHANGED must not retire them either.** The first version of this fix had exactly that hole: it re-asked the server, the answer was byte-identical, and the patch was dropped anyway — the reported bug reached by a longer route. The hand-off rule is now explicit (`supersedesConfirmedPatches`): a delta always supersedes, an error never does, and a snapshot only when it actually MOVED the base.
+
+  The rule is pinned against the source, not only behaviourally: no `setTimeout` in the cache may name a revert. The defect was never inside a function — it was which function a timer pointed at, and a behavioural test only sees that if somebody thought to write the case. Nobody had: `CONFIRMED_PATCH_TTL_MS` was named nowhere in the test file, which the reporter also pointed out. It is now, red-verified by restoring the original line.
+- **@voltro/ui-shadcn** — `AnimatedNumber` rendered `0` into static markup. It initialised its state to zero and counted up on hydration, so every statically rendered page SHIPPED the zero — the landing site's own stats row went out as "0 … 0 … 0% … 0", which is what a crawler, an answer engine and any reader with JavaScript off saw. A number that only exists after hydration is not a number on the page.
+
+  It now renders the target value (so the server's markup and the first client render agree — no hydration mismatch) and drops to zero inside the observer callback, at the one moment the animation is actually about to run. The count-up is decoration layered on a correct page rather than the only way to see the value.
+
+  The test that covered this asserted `toBe('0')` before scrolling — it was pinning the defect. It asserts the final value now, with the reason written next to it, plus a second case for the count-up itself.
+
+  `CodeCompare`'s corner tags take an `eyebrow` prop instead of hardcoding "Before" / "With Voltro". This kit renders a bilingual site, and an English label over German copy is the same defect as any other hardcoded string. The English default keeps every existing call working.
+- **@voltro/cli** — `voltro dev` reports the db-pool budget too, and the out-of-pool count is right on every dialect.
+
+  The line was `voltro serve`-only, and the module said so with its reasoning: a dev machine has one process and no replicas, so `max × replicas` is noise. It even asked a future reader not to "fix the parity gap" by moving it.
+
+  The reasoning was fine and its PREMISE was false. `voltro dev` is not always a dev machine — at least one consumer runs it as their deployment, two API pods against a shared pooler, and `retentionSweep.ts` already reasons about that same consumer in its own header. Two modules cannot both be right about what `voltro dev` is. The cost was not theoretical: that consumer REPORTED the out-of-pool `LISTEN` connection, we answered it in this line, and they could not see the answer, because the one boot path they run does not print it.
+
+  So the exception is conditional rather than per-command now. `voltro serve` always reports; `voltro dev` reports when the environment shows the process is not a laptop — `REPLICA_COUNT` (a process cannot know how many of itself are running, so a platform set it), `DB_MAX_CONNECTIONS` / `PG_MAX_CONNECTIONS` (somebody is already reasoning about this number), or `DB_REPLICA_URLS` (which multiplies the pools inside ONE process — the case most likely to be mis-budgeted, because it does not look like a fleet). A bare `voltro dev` with nothing set stays silent, which is the half of the original decision that was right.
+
+  **And the out-of-pool arithmetic was wrong for two dialects.** It was derived inline as `dialect === 'postgres' && CDC !== '0'`. The mysql/mariadb ROW-binlog reader speaks the REPLICATION protocol, which is a separate connection from the SQL pool by construction, so a mariadb deployment read a line that under-reported its own process by one. It is counted now. mssql Change Tracking is NOT counted, and that zero is verified rather than omitted — it reads through the store's own `SqlClient` and its module says "the CT reader needs no second pool".
+
+  Both boot paths go through one `reportDbPoolLine`, and the CDC derivation takes the ARMED state as a parameter instead of re-reading the env: a binlog reader stands down when every app table is `.nonReactive()`, and billing a connection nobody opened is the same class of error as missing one.
+- **@voltro/cli** — The 0.37.0 strict-input note under-sold the one case that breaks hardest, and the correction is RE-ISSUED rather than edited.
+
+  0.37.0 made an undeclared input field reject the call. Its note described the general case correctly and then, under WHAT DOES NOT CHANGE, said "an empty input to a procedure that declares none is still fine". True about sending `{}`, and it reads as reassurance to the owner of an `input: Schema.Struct({})` — whose procedure is the one shape that did NOT move from "silently drops the extra field" to "rejects it". It moved from accepting EVERYTHING to accepting nothing, because an empty `TypeLiteral` has no expected keys for excess-property checking to compare against. The strongest-looking declaration was the only one enforcing nothing.
+
+  A consumer measured the upgrade across 2 705 procedures and found three real breaks. The most expensive was exactly this: a `getMy` declaring `Schema.Struct({})` while a shared table hook always sent `{ limit }`. Before, the limit was discarded and the call worked; after, the live subscription AND the SSR seed of that page both die.
+
+  **Why a new codemod and not an edit.** `selectCodemods` filters `from < version <= to`, so anyone who has already crossed 0.37.0 — including the consumer who reported this — will never see that note again, whatever it says. A correction filed there reaches only users who have not upgraded yet, i.e. not the ones holding the broken app. `0.39.0/01_empty-input-schema-rejects-every-field` carries it to the people who need it. (The 0.37.0 note is corrected too, for users still short of it. That edit is necessary and not sufficient, and the difference between those two words is why there are two files.)
+
+  Its `appliesTo` is deliberately BROADER than the original's. 0.37.0's fires on a spread into a procedure input or the untyped string form of `ctx.query` — the constructs that carry a field the author never typed, which is the right gate for the general case and the wrong one here. The payload does not have to be invisible for this to break: the reporting consumer reached it through an untyped wrapper hook passing an explicit `{ limit }`. So this one gates on the DECLARATION — an empty struct anywhere in the app — which is the population that actually changed behaviour.
+- **@voltro/cli** — All three ways a mutating inspect request can be refused now name the variable, the header, AND where the value comes from.
+
+  A consumer verifying a row filter hit this one:
+
+  401 {"error":"unauthorized","reason":"inspect: POST needs the write credential — send it as the `x-voltro-inspect-write` header alongside the bearer. The read token authorises reads only."}
+
+  Their words for it: the message is good, and the missing half is **where the value comes from**. They knew what to send and not what to send AS. They gave up on our tooling and hand-signed a session token instead.
+
+  That half is exactly the part a user cannot guess, because in dev nobody ever typed it: `voltro dev` MINTS `VOLTRO_INSPECT_WRITE_TOKEN` into the project's gitignored `.env.local`. Every arm says so now.
+
+  **It is a function over the set, not a fix to the reported member** — this is the third message on this surface to be fixed one at a time. The three refusals were three hand-written strings of decreasing usefulness:
+
+  - `unset` — named the variable. Fine. - `absent` — named the header and not the variable. The reported one. - `mismatch` — `inspect: write-credential mismatch`, which named neither, and is the case where knowing WHICH of the two values to look at is the entire remedy. Nobody had reported it, which is not evidence that it was fine.
+
+  They come from one `inspectWriteHint(refusal, method)` beside the existing read- token hint, so the next arm cannot be added without the vocabulary. The method is folded in because the surface answers for `/erase` and for `/routes` in the same words, and a caller who did not know their call was a mutation is the caller most likely to be reading it.
+- **@voltro/cli** — `ctx.isServer` reaches a LAYOUT loader too, on every server path. It was threaded into the page loader and left off the segment chain, so a layout loader read `undefined` — falsy, i.e. it concluded it was in the browser while server-rendering.
+
+  Three of the five constructions never passed it: the prerender context in `build.ts`, the dev SSR renderer's layout call, and the test fixture pinning the shape. The two that did are the ones a `tsc` run named, because `SegmentLoaderContext` — the CLI's mirror of `LoaderContext` — had not grown the field at all.
+
+  Making it REQUIRED rather than optional is what found the other three, and it is the same reasoning the flag itself ships with: an optional `isServer` cannot distinguish "the server forgot to pass it" from "this is the browser", and both spellings of that mistake claim the browser. A field whose whole job is to answer one question must not have a third answer.
+
+  `webDevSegmentChain.test.ts` asserts the loader argument with an exact `toEqual`, so a field added to one loader's context and not the other fails there. That assertion is the reason this is one release and not two: `tsc` was already green on the test file while the run would have gone red.
+- **@voltro/cli** — The pre-bundled api client is fingerprinted from the DESCRIPTOR SOURCES, so a schema change reaches the browser.
+
+  Reported: a consumer changed an input schema on a descriptor and `voltro dev` kept serving the old client. The failure is quiet in the worst way — the CLIENT rejects the call, so the api logs nothing, because no request ever arrives.
+
+  Vite pre-bundles the workspace api client and its optimize-cache hash keys on the lockfile and package.json, never on a pre-bundled dep's source content. So the framework fingerprints the client itself and flips `optimizeDeps.force`. That machinery was right and it was watching the wrong file:
+
+  **`rpcGroup.generated.ts` imports each descriptor by export name and lifts it. It contains no schemas.** Codegen's own header says so. The generated file is therefore byte-identical across any schema edit, and BOTH mechanisms were structurally blind to it — the across-boot check hashed it, and the in-session watcher watched it.
+
+  The in-session watcher's own comment already described the symptom ("the browser kept decoding responses against the stale schema"): the cache-busting half was fixed when that was hit, and the DETECTION half kept asking the file that cannot answer. So it never fired. The consumer's third reason — "runs only at boot" — is not quite right, and it does not matter: the in-session mechanism exists and was blind for the same reason. One fingerprint feeds both now.
+
+  It hashes every `*.query.ts` / `*.mutation.ts` / `*.action.ts` / `*.stream.ts` / `*.event.ts` and every `*.workflow.tsx` descriptor, plus the generated group itself (which is what moves when a procedure is added or removed without a descriptor file changing content). Paths are hashed with contents, so a rename cannot come out as a no-op. `*.server.ts` executors are deliberately excluded — they never reach the browser, and including them would force a re-optimize on every handler edit, which is the whole working day and is how a forced re-optimize gets turned off.
+
+  **The `proxyTarget` skip is gone from both.** It stood in for "is this api external", and a workspace api served on its own origin has no `proxyTarget` while still being edited locally. `findWorkspaceApiDir` returning a directory is the question that was meant. It survives in exactly one place — the ws proxy, where without a target there is nothing to proxy to — and the test asserts that count rather than its absence.
+- **@voltro/cli** — `voltro probe access` now names the one thing that makes its red meaningless.
+
+  The command asks "does a declared guard refuse a caller presenting nothing". It turns out that under `voltro dev` a caller presenting nothing is not anonymous: dev resolves a login-less request to a FALLBACK TENANT (`$TENANT ?? 'acme'`). An app whose scopes derive from the tenant therefore admits, and the probe reported `ANSWERED an unauthenticated call` against a guard that is perfectly fine.
+
+  That is not an occasional false positive, it is a structural one: the local registry only ever holds `voltro dev` / `voltro start` processes — `voltro serve` does not register — so every target the command picks up WITHOUT `--url` is in exactly that state.
+
+  The failure block now says so, and says what to do instead:
+
+  voltro probe access --url http://<host>:<port>
+
+  against a `voltro serve` process, where an anonymous request carries `tenantId: null` — the case a guard actually has to refuse.
+
+  Found by running the command as a FINDER for the first time rather than as a test: it flagged a shipped template, and the flag was wrong in dev and right about production, for two different reasons. A tool whose red needs a paragraph of context should carry the paragraph.
+- **@voltro/protocol** — A rejected rpc payload no longer answers with the procedure's whole input type.
+
+  Measured by a consumer against 0.38.0, anonymously, with no session at all:
+
+  POST /rpc {"tag":"workAreas.create","payload":{"name":"x"}} → { readonly name: string; readonly storeId?: string | null | undefined; readonly type: "department" | "location" | "zone" | "station"; readonly parentId?: string | null | undefined; … } └─ ["type"] └─ is missing
+
+  That procedure declares `guards: [{ scope: 'workArea:c:o' }]`. The refusal never happened — the payload decode runs first and failed first — so the caller got a field-by-field description of a write they are not allowed to make. On an app with ~700 write procedures that is a free enumeration of the entire write surface for anyone who can reach the port: no session, nothing that looks like rate-limit abuse, and no log line.
+
+  The rendered TITLE is now the procedure name, and the issue PATH is untouched:
+
+  workAreas.create input └─ ["type"] └─ is missing
+
+  So the half that made the 0.37.0 strict-input change cheap to adopt — WHICH key, and whether it is missing or unexpected — survives intact, while the types and the enum members do not. The excess-property case still lists the accepted key NAMES, deliberately: the caller already sent the key, that list is what makes the fix a one-line read, and names without types were not what was reported.
+
+  **What this does NOT do, stated because the report asked for it.** It does not run `guards:` before the decode. In `@effect/rpc`, a `Request` is decoded against the payload schema and answered on failure without ever reaching `server.write` — so it never reaches the handler and never reaches `applyMiddleware`. Auth middleware runs strictly after the decode, and there is no point in that path holding both a resolved subject and an undecoded payload. Evaluating guards first means replacing the protocol layer, not annotating a schema, and `voltro probe access` therefore still reports a guarded procedure whose input it cannot guess as `inconclusive` rather than `refused`.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/datetime, @voltro/local-first, @voltro/react-native** — `@voltro/datetime`, `@voltro/local-first` and `@voltro/react-native` shipped with no api-extractor golden, so the public-surface drift tripwire did not cover them — and the docs-audit finding that motivated this landed in exactly that gap (the docs promised a `useTimezone()` hook that `@voltro/datetime` never exported, and no gate could see it). All three are wired now, root + subpath entry (`./context`, `./react`, `./schema`): six goldens, `api:check` green on each, and no existing golden changed (the new `paths` entries every sibling map gained are purely additive).
+
+  Root cause fixed in the generator rather than by hand: `gen-api-extractor.mjs` now creates the package's `etc/` directory with the wiring. api-extractor refuses to create its own report folder, so a package wired without one failed at its first `api:report` instead of at generation — which is how these three went live uncovered. Internal: no consumer-facing behaviour changes.
+- **@voltro/cli** — `gen-api-extractor.mjs --check` verifies the api-surface wiring instead of writing it, and runs in CI (and therefore in `pnpm gate`, which derives its steps from `ci.yml`). It fails when a published entry point has no api-extractor config, no golden, an EMPTY golden, a stale config/golden for a dropped export, or no `api:check` script.
+
+  It is derived from `publishConfig.exports` inside the generator's own loop — not a curated list and not a second copy of the derivation — so a package that joins the workspace is covered without anyone remembering to add it. It carries a floor (60 packages) for the reason every check in `scripts/` has one: the failure mode of a wiring check is a green line over a walk that found nothing.
+
+  Verified by injecting each defect and watching it go red (missing golden, empty golden), confirming exit code 1, and confirming `--check` mutates no file. Internal: tooling only.
+- **@voltro/cli** — `rpcSurfaceFingerprint.ts` wrote its composite-key separator as a literal NUL byte instead of ``. Same runtime value, no behaviour change — the file's own 16 tests pass identically before and after.
+
+  It matters because of what the byte does to the FILE rather than to the hash: a source file containing a NUL is binary to every text tool, so `grep` skips it and prints nothing, which is indistinguishable from a clean file. This repo has been bitten by exactly that — a 1020-line module that every grep-based audit had silently skipped, including one searching for a string that file declares.
+
+  The guard (`noLiteralNulInSources.test.ts`) caught it on the release gate, in a file added earlier in this same release. The rule was already written down; what enforced it was the test.
+
+---
+
 ## [0.38.0] — 2026-08-14
 
 ### ⚠ BREAKING

package/THIRD-PARTY-NOTICES.md

@@ -5,7 +5,7 @@ property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/react-native itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (5 packages).
+Generated from the resolved runtime dependency closure (6 packages).
 
 ---
 
@@ -37,6 +37,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## jose@6.2.8
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2018 Filip Skokan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## layerr@3.0.0
 
 License: MIT

package/dist/index.d.ts

@@ -1,3 +1,69 @@
+import { ApiHandle } from '@voltro/client';
+import { ClientDescriptorMap } from '@voltro/client';
+import { MountedApi } from '@voltro/client';
+import { ResolvableHeaders } from '@voltro/client';
+import { ResolvedClient } from '@voltro/client';
+import { StoreStorageProvider } from '@voltro/client';
+import { SupervisorHandle } from '@voltro/client';
+
+/**
+ * The async storage this adapter writes through to — `AsyncStorage` from
+ * `@react-native-async-storage/async-storage` satisfies it as-is, as does a
+ * thin wrapper over `expo-secure-store`.
+ *
+ * It is a STRUCTURAL type on purpose: this package does not depend on any
+ * storage library, so an app can pass whichever one it already has (or a fake,
+ * which is how this is tested).
+ */
+export declare interface AsyncKeyValueStorage {
+    readonly getItem: (key: string) => Promise<string | null>;
+    readonly setItem: (key: string, value: string) => Promise<void>;
+    readonly removeItem: (key: string) => Promise<void>;
+    /** Optional: used by `hydrate()` when no explicit key list is given. */
+    readonly getAllKeys?: () => Promise<ReadonlyArray<string>>;
+    /** Optional: a batched read, used when available. */
+    readonly multiGet?: (keys: ReadonlyArray<string>) => Promise<ReadonlyArray<readonly [string, string | null]>>;
+}
+
+export declare interface AsyncStoragePersistence {
+    /**
+     * Load the persisted keys into memory. Await this BEFORE rendering; install
+     * the provider afterwards.
+     *
+     * Idempotent: a second call re-reads, which is what a "reload from disk"
+     * would need. Safe to call concurrently — the in-flight promise is shared.
+     */
+    readonly hydrate: () => Promise<void>;
+    /** True once `hydrate()` has completed at least once. */
+    readonly hydrated: () => boolean;
+    /** Install this with `setStoreStorage()` from `@voltro/client`. */
+    readonly provider: StoreStorageProvider;
+    /**
+     * Resolve when every queued write has settled. For tests, and for an app that
+     * wants to flush before backgrounding — not required for correctness, since
+     * writes are queued per key and the last one wins.
+     */
+    readonly flush: () => Promise<void>;
+    /** Keys currently held in memory. Diagnostics; not a stable ordering. */
+    readonly keys: () => ReadonlyArray<string>;
+}
+
+export declare interface AsyncStoragePersistenceOptions {
+    readonly storage: AsyncKeyValueStorage;
+    /**
+     * Which keys to hydrate. Give this when your storage holds more than Voltro's
+     * stores — hydrating a device's entire key space to serve four store keys is
+     * a slow boot for no benefit.
+     *
+     * Omitted, the adapter asks `getAllKeys()`; if the storage has no
+     * `getAllKeys`, omitting this is an ERROR at `hydrate()` rather than a silent
+     * empty hydration, because an empty hydration looks exactly like a first run.
+     */
+    readonly keys?: ReadonlyArray<string>;
+    /** Called when a write-through fails. Default: `console.warn`. */
+    readonly onError?: (key: string, error: unknown) => void;
+}
+
 export declare type BackgroundSyncAction = {
     readonly type: 'foreground';
 } | {
@@ -36,6 +102,25 @@ export declare interface BackgroundSyncState {
 
 export declare type BackgroundSyncStatus = 'idle' | 'syncing' | 'success' | 'error';
 
+/** The browser's `navigator.onLine` + its events. The default, and the reason
+ *  the same screen still behaves under jsdom or in a web preview. */
+export declare const browserOnlineSource: OnlineSource;
+
+/**
+ * Build a React-Native persistence adapter over an async key-value storage.
+ *
+ * ```ts
+ * import AsyncStorage from '@react-native-async-storage/async-storage'
+ * import { setStoreStorage } from '@voltro/client'
+ * import { createAsyncStoragePersistence } from '@voltro/react-native'
+ *
+ * const persistence = createAsyncStoragePersistence({ storage: AsyncStorage })
+ * await persistence.hydrate()          // BEFORE the first render
+ * setStoreStorage(persistence.provider)
+ * ```
+ */
+export declare const createAsyncStoragePersistence: (options: AsyncStoragePersistenceOptions) => AsyncStoragePersistence;
+
 /**
  * The descriptor a `*.deepLink.ts` file default-exports. `_tag` marks it for
  * the (future) discovery walk without relying on structural guessing.
@@ -63,6 +148,11 @@ export declare type DeepLinkParams<Pattern extends string> = Pattern extends `${
     readonly [K in Param]: string;
 } : Record<string, never>;
 
+/** The default constructor: React Native's global `WebSocket`. Exported so the
+ *  refusal below is testable — an untestable error message is one nobody has
+ *  ever read. */
+export declare const defaultWebSocketConstructor: (url: string, protocols?: string | ReadonlyArray<string>) => WebSocket;
+
 /**
  * Declare a deep link.
  *
@@ -149,6 +239,24 @@ export declare const DEVICES_TABLE = "_voltro_devices";
  */
 export declare type DeviceUpsert<Result = unknown> = (registration: DeviceRegistration) => Promise<Result>;
 
+/**
+ * Match `path` against the table and RUN the winning handler. Returns the
+ * captured params, or `null` when nothing matched.
+ *
+ * This exists because `matchFirstDeepLink` alone is not usable for the thing it
+ * is for. Its descriptors come from a HETEROGENEOUS array, so `Pattern` erases
+ * to `string`, and `DeepLinkParams<string>` is `Record<string, never>` — the
+ * handler it hands back rejects the params it hands back with it. Every caller
+ * had to cast, and the template's did not, which nothing noticed because no
+ * harness typechecked the template.
+ *
+ * The erasure happens ONCE, here, where it is defensible: at runtime a matched
+ * pattern's params ARE `Record<string, string>`, and the per-pattern type is a
+ * derivation of a literal the caller no longer has. `runDeepLink` keeps the
+ * fully-typed single-descriptor path for a caller that does.
+ */
+export declare const dispatchDeepLink: (descriptors: ReadonlyArray<DeepLinkDescriptor>, path: string) => Record<string, string> | null;
+
 /**
  * Subscribe to "app returned to the foreground". Returns an unsubscribe.
  *
@@ -190,6 +298,19 @@ export declare const matchFirstDeepLink: (descriptors: ReadonlyArray<DeepLinkDes
     readonly params: Record<string, string>;
 } | null;
 
+/** One api this app talks to. `group` and `descriptors` come from the api's
+ *  generated rpc surface — on mobile, from the file `voltro codegen` writes
+ *  into the app (`.framework/mobileApis.generated.ts`). */
+export declare interface MobileApiBinding {
+    readonly name: string;
+    readonly group: MountedApi['group'];
+    readonly descriptors: ClientDescriptorMap;
+    /** `ws(s)://host:port/ws`. On a device this is NOT localhost — see
+     *  {@link resolveDevWsUrl}. */
+    readonly wsUrl: string;
+    readonly headers?: ResolvableHeaders | undefined;
+}
+
 export declare interface MobileConnectionControls {
     /** Report that a call failed — bumps `failureCount`, flips to `degraded`. */
     readonly reportFailure: () => void;
@@ -199,7 +320,7 @@ export declare interface MobileConnectionControls {
 
 export declare interface MobileConnectionState {
     readonly status: MobileConnectionStatus;
-    /** `navigator.onLine` (true when unknowable, e.g. SSR / headless RN). */
+    /** Reachability as reported by the configured {@link OnlineSource}. */
     readonly online: boolean;
     /** Consecutive reported failures with no success since. 0 when healthy. */
     readonly failureCount: number;
@@ -208,6 +329,37 @@ export declare interface MobileConnectionState {
 
 export declare type MobileConnectionStatus = 'connected' | 'degraded' | 'offline';
 
+/** The subset of the NetInfo module used. `fetch()` seeds the first value,
+ *  `addEventListener` reports changes and returns an unsubscribe. */
+export declare interface NetInfoLike {
+    readonly addEventListener: (listener: (state: NetInfoState) => void) => () => void;
+    readonly fetch?: () => Promise<NetInfoState>;
+}
+
+/**
+ * Reachability from `@react-native-community/netinfo` (or Expo's re-export).
+ *
+ * ```ts
+ * import NetInfo from '@react-native-community/netinfo'
+ * const status = useMobileConnectionStatus({ onlineSource: netInfoOnlineSource(NetInfo) })
+ * ```
+ *
+ * `isInternetReachable` is only believed when it is a BOOLEAN. NetInfo reports
+ * `null` while its reachability probe is still outstanding, and treating that
+ * as `false` makes an app flash "offline" for a moment on every cold start and
+ * on every network change — so a `null` falls back to `isConnected`, which is
+ * the link-layer answer and is available immediately.
+ */
+export declare const netInfoOnlineSource: (netInfo: NetInfoLike) => OnlineSource;
+
+/** The shape of `@react-native-community/netinfo`'s state that matters here.
+ *  Structural, so this package depends on no native module. */
+export declare interface NetInfoState {
+    readonly isConnected: boolean | null;
+    /** `null` while the probe is still out — see the treatment below. */
+    readonly isInternetReachable?: boolean | null;
+}
+
 /**
  * The mobile client posture. Spread into the client config on RN:
  *
@@ -232,6 +384,19 @@ export declare interface OfflineFirstDefaults {
 
 export declare const offlineFirstDefaults: OfflineFirstDefaults;
 
+/**
+ * A source of reachability. `subscribe` reports every change and returns an
+ * unsubscribe; `read` gives the value to start from.
+ *
+ * Injected rather than detected, because detection is exactly what went wrong:
+ * a `typeof navigator === 'undefined' ? true : …` fallback answers "online" on
+ * every platform that does not implement the API it is testing for.
+ */
+export declare interface OnlineSource {
+    readonly read: () => boolean;
+    readonly subscribe: (onChange: (online: boolean) => void) => () => void;
+}
+
 /**
  * Register (or re-register, on token rotation) the current device.
  *
@@ -259,6 +424,21 @@ export declare const registerDevice: <Result = unknown>(upsert: DeviceUpsert<Res
  */
 export declare const resolveDeviceRegistration: (input: DeviceRegistrationInput, env?: DeviceRegistrationEnv) => DeviceRegistration;
 
+/**
+ * Turn a dev-machine host into a ws URL a DEVICE can reach.
+ *
+ * The trap this exists for: `localhost` on a phone is the PHONE. An app pointed
+ * at `ws://localhost:4000/ws` in development connects to nothing, times out,
+ * and retries forever — which reads as a broken framework rather than a wrong
+ * host. Expo already knows the LAN address of the machine running Metro
+ * (`expo-constants`' `hostUri`, e.g. `192.168.1.20:8081`), so pass that in and
+ * this swaps in the api's port.
+ *
+ * A simulator is the exception — it shares the host's loopback — but using the
+ * LAN address works there too, so there is no branch to get wrong.
+ */
+export declare const resolveDevWsUrl: (hostUri: string | undefined, port: number, path?: string) => string;
+
 /**
  * Match `path` against a descriptor and, on a hit, invoke its handler with the
  * captured params. Returns the params (so callers know it matched) or `null`.
@@ -287,6 +467,52 @@ export declare interface ShouldSyncOptions {
     readonly enabled: boolean;
 }
 
+/**
+ * Connect every api and keep them connected.
+ *
+ * ```ts
+ * const supervisor = startMobileApis({
+ *   apis: mobileApis(wsUrl),
+ *   onChange: (clients, initialized) => setState({ clients, initialized }),
+ * })
+ * // on unmount:
+ * supervisor.dispose()
+ * ```
+ *
+ * `reconnect()` on the returned handle forces a fresh socket for every api —
+ * call it after a sign-in or a tenant switch so the connection re-resolves who
+ * it is. The supervisor blanks caches across that swap on purpose: the next
+ * subject may be entitled to less than the previous one.
+ */
+export declare const startMobileApis: (options: StartMobileApisOptions) => SupervisorHandle;
+
+export declare interface StartMobileApisOptions {
+    readonly apis: ReadonlyArray<MobileApiBinding>;
+    /** Called whenever the live client set changes: initial connect, a reconnect
+     *  swap, teardown. Mirror it into state and render once `initialized`. */
+    readonly onChange: (clients: ReadonlyMap<string, ResolvedClient>, initialized: boolean) => void;
+    /**
+     * How to construct a WebSocket. Defaults to the global one React Native
+     * provides. Injected so this module can be tested without a socket — and so
+     * an app on a runtime with a different WebSocket can say so.
+     */
+    readonly webSocketConstructor?: (url: string, protocols?: string | ReadonlyArray<string>) => WebSocket;
+    /** Override the retry schedule (default: 500ms doubling, capped at 5s). */
+    readonly retryDelayMs?: (attempt: number) => number;
+}
+
+/**
+ * Turn the supervisor's live client set into the `apis` map the client provider
+ * takes.
+ *
+ * This lives in the package rather than in the template because it is where the
+ * two halves meet — the BINDING (name, descriptors, url) and the live
+ * connection — and a template copy would be an untested one. An api that has not
+ * connected yet is simply absent from the map; the hooks render their loading
+ * state, which is the honest answer while a phone is on a train.
+ */
+export declare const toApiHandles: (apis: ReadonlyArray<MobileApiBinding>, clients: ReadonlyMap<string, ResolvedClient>) => ReadonlyMap<string, ApiHandle>;
+
 /**
  * Register a periodic + foreground-triggered sync callback.
  *
@@ -322,6 +548,8 @@ export declare interface UseBackgroundSyncResult extends BackgroundSyncState {
     readonly sync: () => void;
 }
 
+export declare const useMobileConnectionStatus: (options?: UseMobileConnectionStatusOptions) => MobileConnectionState & MobileConnectionControls;
+
 /**
  * Observe mobile connection health.
  *
@@ -330,12 +558,32 @@ export declare interface UseBackgroundSyncResult extends BackgroundSyncState {
  * {status !== 'connected' && <OfflineBanner status={status} />}
  * ```
  *
- * Standalone by design (see the file header): it derives `offline` from
- * `navigator.onLine` + its events, and `degraded` from failures the app reports
- * — it does not reach into any transport. Coming back online clears the failure
+ * Standalone by design (see the file header): it derives `offline` from the
+ * injected {@link OnlineSource}, and `degraded` from failures the app reports —
+ * it does not reach into any transport. Coming back online clears the failure
  * count, on the same reasoning as the web hook: those failures were the offline
  * window itself.
  */
-export declare const useMobileConnectionStatus: () => MobileConnectionState & MobileConnectionControls;
+export declare interface UseMobileConnectionStatusOptions {
+    /** Where "online" comes from. Defaults to the browser source; pass
+     *  `netInfoOnlineSource(NetInfo)` on a device. */
+    readonly onlineSource?: OnlineSource;
+}
+
+/**
+ * Wrap a WebSocket constructor so the supervisor hears what the socket does.
+ *
+ * Exported because it is the ONE piece of this module that can be tested
+ * without a device: the socket itself is constructed lazily, deep inside the
+ * Effect socket layer, when the client first connects — so a test that asserts
+ * "a socket was created" asserts nothing until there is a real connection to
+ * make. What CAN be pinned here is that a socket, once created, reports open,
+ * close and error onward. Without those three the retry loop is never told
+ * anything and a dropped connection stays dropped, silently, forever.
+ *
+ * RN needs no connect-timeout shim (web has one): a failed connect on a device
+ * fires `error` and then `close`.
+ */
+export declare const wireSocket: (construct: (url: string, protocols?: string | ReadonlyArray<string>) => WebSocket, onOpen: () => void, onIssue: (kind: "close" | "error" | "connect-timeout") => void) => (url: string, protocols?: string | ReadonlyArray<string>) => WebSocket;
 
 export { }

package/dist/index.js

@@ -1,7 +1,8 @@
 import { a as e, i as t, n, r, t as i } from "./devices-BjXAU-8I.js";
 import { useCallback as a, useEffect as o, useReducer as s, useRef as c, useState as l } from "react";
+import { buildApiRuntime as u, startApiSupervisor as d } from "@voltro/client";
 //#region src/deepLink.ts
-var u = (e) => {
+var f = (e) => {
 	let t = e.pattern;
 	if (t.length === 0 || t[0] !== "/") throw Error(`defineDeepLink: pattern must start with "/" (got "${t}")`);
 	return {
@@ -9,7 +10,7 @@ var u = (e) => {
 		pattern: t,
 		handler: e.handler
 	};
-}, d = (e) => {
+}, p = (e) => {
 	let t = e, n = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\//.exec(t);
 	if (n) {
 		let e = t.slice(n[0].length), r = n[1].toLowerCase();
@@ -26,8 +27,8 @@ var u = (e) => {
 			return e;
 		}
 	});
-}, f = (e, t) => {
-	let n = d(e), r = d(t);
+}, m = (e, t) => {
+	let n = p(e), r = p(t);
 	if (n.length !== r.length) return null;
 	let i = {};
 	for (let e = 0; e < n.length; e++) {
@@ -39,19 +40,24 @@ var u = (e) => {
 		} else if (t !== "*" && t !== a) return null;
 	}
 	return i;
-}, p = (e, t) => {
-	let n = f(e.pattern, t);
+}, h = (e, t) => {
+	let n = m(e.pattern, t);
 	return n === null ? null : (e.handler(n), n);
-}, m = (e, t) => {
+}, g = (e, t) => {
 	for (let n of e) {
-		let e = f(n.pattern, t);
+		let e = m(n.pattern, t);
 		if (e !== null) return {
 			descriptor: n,
 			params: e
 		};
 	}
 	return null;
-}, h = {
+}, _ = (e, t) => {
+	let n = g(e, t);
+	if (n === null) return null;
+	let r = n.descriptor.handler;
+	return r(n.params), n.params;
+}, v = {
 	status: "idle",
 	isForeground: !0,
 	lastSyncAt: void 0,
@@ -59,7 +65,7 @@ var u = (e) => {
 	lastError: void 0,
 	successCount: 0,
 	failureCount: 0
-}, g = (e, t) => {
+}, y = (e, t) => {
 	switch (t.type) {
 		case "foreground": return e.isForeground ? e : {
 			...e,
@@ -90,11 +96,11 @@ var u = (e) => {
 			failureCount: e.failureCount + 1
 		};
 		case "reset": return {
-			...h,
+			...v,
 			isForeground: e.isForeground
 		};
 	}
-}, _ = (e, t, n, r = !1) => !(!n.enabled || e.status === "syncing" || !r && !e.isForeground || !r && n.intervalMs > 0 && e.lastAttemptAt !== void 0 && t - e.lastAttemptAt < n.intervalMs), v = (e, t) => {
+}, b = (e, t, n, r = !1) => !(!n.enabled || e.status === "syncing" || !r && !e.isForeground || !r && n.intervalMs > 0 && e.lastAttemptAt !== void 0 && t - e.lastAttemptAt < n.intervalMs), x = (e, t) => {
 	if (typeof document > "u" || typeof window > "u") return () => {};
 	let n = () => {
 		document.visibilityState === "visible" ? e() : t();
@@ -102,25 +108,25 @@ var u = (e) => {
 	return document.addEventListener("visibilitychange", n), window.addEventListener("focus", e), () => {
 		document.removeEventListener("visibilitychange", n), window.removeEventListener("focus", e);
 	};
-}, y = 5 * 6e4, b = (e, t = {}) => {
-	let n = t.intervalMs ?? y, r = t.syncOnForeground ?? !0, i = t.enabled ?? !0, l = t.now ?? Date.now, u = t.subscribeForeground ?? v, [d, f] = s(g, h), p = c(e);
+}, S = 3e5, C = (e, t = {}) => {
+	let n = t.intervalMs ?? S, r = t.syncOnForeground ?? !0, i = t.enabled ?? !0, l = t.now ?? Date.now, u = t.subscribeForeground ?? x, [d, f] = s(y, v), p = c(e);
 	p.current = e;
 	let m = c(d);
 	m.current = d;
-	let b = c(!0), x = a((e) => {
-		_(m.current, l(), {
+	let h = c(!0), g = a((e) => {
+		b(m.current, l(), {
 			intervalMs: n,
 			enabled: i
 		}, e) && (f({
 			type: "syncStarted",
 			at: l()
 		}), Promise.resolve().then(() => p.current()).then(() => {
-			b.current && f({
+			h.current && f({
 				type: "syncSucceeded",
 				at: l()
 			});
 		}).catch((e) => {
-			b.current && f({
+			h.current && f({
 				type: "syncFailed",
 				at: l(),
 				error: e instanceof Error ? e.message : String(e)
@@ -131,33 +137,33 @@ var u = (e) => {
 		n,
 		l
 	]);
-	o(() => (b.current = !0, () => {
-		b.current = !1;
+	o(() => (h.current = !0, () => {
+		h.current = !1;
 	}), []), o(() => u(() => {
-		f({ type: "foreground" }), r && x(!0);
+		f({ type: "foreground" }), r && g(!0);
 	}, () => f({ type: "background" })), [
 		u,
 		r,
-		x
+		g
 	]), o(() => {
 		if (!i || n <= 0) return;
-		let e = setInterval(() => x(!1), n);
+		let e = setInterval(() => g(!1), n);
 		return () => clearInterval(e);
 	}, [
 		i,
 		n,
-		x
+		g
 	]);
-	let S = a(() => x(!0), [x]);
+	let _ = a(() => g(!0), [g]);
 	return {
 		...d,
-		sync: S
+		sync: _
 	};
-}, x = {
+}, w = {
 	localFirst: !0,
 	optimistic: !0,
 	syncOnForeground: !0,
-	syncIntervalMs: 5 * 6e4,
+	syncIntervalMs: 3e5,
 	showSyncStatus: !0,
 	retryBackoffMs: [
 		1e3,
@@ -165,32 +171,151 @@ var u = (e) => {
 		15e3,
 		6e4
 	]
-}, S = (e, t) => e ? t > 0 ? "degraded" : "connected" : "offline", C = () => typeof navigator > "u" || navigator.onLine, w = () => {
-	let [e, t] = l(C), [n, r] = l(0), [i, s] = l(void 0), u = c(!0);
-	o(() => (u.current = !0, () => {
-		u.current = !1;
-	}), []), o(() => {
-		if (typeof window > "u") return;
-		let e = () => {
-			t(!0), r(0);
-		}, n = () => t(!1);
-		return window.addEventListener("online", e), window.addEventListener("offline", n), () => {
-			window.removeEventListener("online", e), window.removeEventListener("offline", n);
+}, T = (e, t) => e ? t > 0 ? "degraded" : "connected" : "offline", E = {
+	read: () => typeof navigator > "u" || navigator.onLine,
+	subscribe: (e) => {
+		if (typeof window > "u") return () => {};
+		let t = () => e(!0), n = () => e(!1);
+		return window.addEventListener("online", t), window.addEventListener("offline", n), () => {
+			window.removeEventListener("online", t), window.removeEventListener("offline", n);
 		};
-	}, []);
-	let d = a(() => {
-		u.current && (r((e) => e + 1), s(Date.now()));
-	}, []), f = a(() => {
-		u.current && r(0);
+	}
+}, D = (e) => {
+	let t = (e) => typeof e.isInternetReachable == "boolean" ? e.isInternetReachable : e.isConnected === !0, n = !0;
+	return {
+		read: () => n,
+		subscribe: (r) => {
+			let i = e.addEventListener((e) => {
+				n = t(e), r(n);
+			});
+			return e.fetch?.().then((e) => {
+				n = t(e), r(n);
+			}).catch(() => {}), i;
+		}
+	};
+}, O = (e) => {
+	let t = e?.onlineSource ?? E, [n, r] = l(() => t.read()), [i, s] = l(0), [u, d] = l(void 0), f = c(!0);
+	o(() => (f.current = !0, () => {
+		f.current = !1;
+	}), []), o(() => t.subscribe((e) => {
+		r(e), e && s(0);
+	}), [t]);
+	let p = a(() => {
+		f.current && (s((e) => e + 1), d(Date.now()));
+	}, []), m = a(() => {
+		f.current && s(0);
 	}, []);
 	return {
-		status: S(e, n),
-		online: e,
-		failureCount: n,
-		lastFailureAt: i,
-		reportFailure: d,
-		reportSuccess: f
+		status: T(n, i),
+		online: n,
+		failureCount: i,
+		lastFailureAt: u,
+		reportFailure: p,
+		reportSuccess: m
 	};
+}, k = (e) => {
+	let { storage: t, keys: n } = e, r = e.onError ?? ((e, t) => {
+		console.warn(`[voltro] persisting '${e}' failed`, t);
+	}), i = /* @__PURE__ */ new Map(), a = !1, o = null, s = /* @__PURE__ */ new Map(), c = null, l = async () => {
+		for (; s.size > 0;) {
+			let [e, n] = s.entries().next().value;
+			s.delete(e);
+			try {
+				n === null ? await t.removeItem(e) : await t.setItem(e, n);
+			} catch (t) {
+				r(e, t);
+			}
+		}
+	}, u = () => {
+		c === null && (c = Promise.resolve().then(l).finally(() => {
+			c = null;
+		}));
+	}, d = async (e) => {
+		if (e.length === 0) return;
+		if (t.multiGet) {
+			let n = await t.multiGet(e);
+			for (let [e, t] of n) t === null ? i.delete(e) : i.set(e, t);
+			return;
+		}
+		let n = await Promise.all(e.map((e) => t.getItem(e)));
+		e.forEach((e, t) => {
+			let r = n[t];
+			r == null ? i.delete(e) : i.set(e, r);
+		});
+	}, f = () => {
+		if (o !== null) return o;
+		let e = (async () => {
+			let e;
+			if (n !== void 0) e = n;
+			else if (t.getAllKeys) e = await t.getAllKeys();
+			else throw Error("createAsyncStoragePersistence: the storage has no getAllKeys(), so the keys to hydrate cannot be discovered. Pass an explicit `keys: [...]` listing the persisted stores' keys.");
+			await d(e), a = !0;
+		})();
+		return o = e, e.finally(() => {
+			o = null;
+		});
+	}, p = {
+		getItem: (e) => i.get(e) ?? null,
+		setItem: (e, t) => {
+			i.set(e, t), s.set(e, t), u();
+		},
+		removeItem: (e) => {
+			i.delete(e), s.set(e, null), u();
+		}
+	};
+	return {
+		hydrate: f,
+		hydrated: () => a,
+		provider: () => p,
+		flush: async () => {
+			for (; c !== null || s.size > 0;) await (c ?? Promise.resolve()), c === null && s.size > 0 && u();
+		},
+		keys: () => [...i.keys()]
+	};
+}, A = (e, t) => {
+	let n = globalThis.WebSocket;
+	if (n === void 0) throw Error("startMobileApis: no global WebSocket. React Native provides one; if you are running these bindings somewhere else, pass `webSocketConstructor`.");
+	return t === void 0 ? new n(e) : new n(e, t);
+}, j = (e, t, n) => (r, i) => {
+	let a = e(r, i);
+	return a.addEventListener("open", () => t()), a.addEventListener("close", () => n("close")), a.addEventListener("error", () => n("error")), a;
+}, M = (e) => {
+	let t = e.webSocketConstructor ?? A;
+	return d({
+		apis: e.apis.map((e) => ({
+			name: e.name,
+			group: e.group,
+			descriptors: e.descriptors,
+			wsUrl: e.wsUrl,
+			...e.headers === void 0 ? {} : { headers: e.headers }
+		})),
+		...e.retryDelayMs === void 0 ? {} : { retryDelayMs: e.retryDelayMs },
+		onChange: e.onChange,
+		buildClient: async (e, n, r, i) => await u({
+			name: e.name,
+			wsUrl: e.wsUrl,
+			group: e.group,
+			...e.headers === void 0 ? {} : { headers: e.headers },
+			webSocketConstructor: j(t, r, i)
+		})
+	});
+}, N = (e, t, n = "/ws") => {
+	let r = (e ?? "").split(":")[0];
+	return r === void 0 || r === "" || r === "localhost" || r === "127.0.0.1" ? `ws://localhost:${t}${n}` : `ws://${r}:${t}${n}`;
+}, P = (e, t) => {
+	let n = /* @__PURE__ */ new Map();
+	for (let r of e) {
+		let e = t.get(r.name);
+		e !== void 0 && n.set(r.name, {
+			runtime: e.runtime,
+			cache: e.cache,
+			client: e.client,
+			descriptors: r.descriptors,
+			inspectBaseUrl: r.wsUrl.replace(/^ws/, "http").replace(/\/ws$/, ""),
+			errorBus: e.errorBus
+		});
+	}
+	return n;
 };
 //#endregion
-export { i as DEVICES_TABLE, n as DEVICE_PLATFORMS, g as backgroundSyncReducer, u as defineDeepLink, S as deriveConnectionStatus, h as initialBackgroundSyncState, r as isDevicePlatform, f as matchDeepLink, m as matchFirstDeepLink, x as offlineFirstDefaults, t as registerDevice, e as resolveDeviceRegistration, p as runDeepLink, _ as shouldSync, b as useBackgroundSync, w as useMobileConnectionStatus };
+export { i as DEVICES_TABLE, n as DEVICE_PLATFORMS, y as backgroundSyncReducer, E as browserOnlineSource, k as createAsyncStoragePersistence, A as defaultWebSocketConstructor, f as defineDeepLink, T as deriveConnectionStatus, _ as dispatchDeepLink, v as initialBackgroundSyncState, r as isDevicePlatform, m as matchDeepLink, g as matchFirstDeepLink, D as netInfoOnlineSource, w as offlineFirstDefaults, t as registerDevice, N as resolveDevWsUrl, e as resolveDeviceRegistration, h as runDeepLink, b as shouldSync, M as startMobileApis, P as toApiHandles, C as useBackgroundSync, O as useMobileConnectionStatus, j as wireSocket };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/react-native",
-  "version": "0.38.0",
+  "version": "0.39.1",
   "description": "React Native bindings for the framework: device-registration primitive, background-sync state machine, offline-first client defaults + connection-status surface, and the deep-link declaration shape — the credential-free mobile plumbing on top of the RN-safe React client.",
   "keywords": [
     "voltro",
@@ -38,7 +38,8 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.38.0"
+    "@voltro/client": "0.39.1",
+    "@voltro/database": "0.39.1"
   },
   "peerDependencies": {
     "react": "^19.0.0"