@voltro/plugin-webhooks 0.87.0 → 0.88.0

package/CHANGELOG.md

@@ -41,6 +41,166 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.88.0] — 2026-11-02
+
+### ⚠ BREAKING
+
+- **Direct computed-cache key callers handle unencodable subjects** — `@voltro/runtime`, `@voltro/voltro`
+
+  `computedCacheKey()` can return `bypass: 'subject-not-encodable'` for claims that cannot safely identify a cache entry. Direct consumers with exhaustive bypass switches must handle this case by running without caching. `voltro update` identifies the direct imports to review. Queries using the native `cache:` declaration and `invoke()` tests need no manual key or code change.
+- **The framework runs on effect 4.1.0** — `@voltro/cli`, `@voltro/devtools`, `@voltro/runtime`, `@voltro/database`, `@voltro/voltro`, `@voltro/sql-sqlite`, `@voltro/sql-mysql`, `@voltro/sql-mssql`, `@voltro/sql-postgres`
+
+  Every `@voltro/*` package now pins `effect` and its `@effect/*` companions to 4.1.0. Apps pin the same version and run `voltro add patches`: it writes the 4.1.0 patch files, retires the `patchedDependencies` entries an earlier CLI shipped for 4.0.1 (pnpm refuses an install over an unused patch) and moves the lockstep overrides. Two former patch fixes ship upstream in 4.1.0 (SQL Server request cancellation, the SQL Server message-storage MERGE). On SQL Server the shared transaction key now applies to every client in the process, not only the first one built.
+
+  `chunkRowsForInsert` from `@voltro/database` returns non-empty chunks (`NonEmptyReadonlyArray`), the shape effect 4.1's `sql.insert` requires; an empty input yields no chunk instead of one empty chunk.
+
+  SQL statement spans are named after their database, following the OpenTelemetry database conventions: the database name, else the server address, else the system name (`postgresql`, `mysql`, `microsoft.sql_server`, `sqlite`). Before, every statement span was `sql.execute`. Trace queries and dashboards that match that name should match the `db.query.text` attribute instead; the devtools trace panel and durable-trace sampling already do.
+
+  **`voltro update` carries you across this** — codemod `0.88.0/01_effect-4-1`. 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.88.0).
+- **Runtime patch pins preserve third-party Effect majors** — `@voltro/cli`
+
+  `voltro add patches` scopes Effect pins to their current major instead of replacing unrelated libraries' Effect 3 dependencies. It migrates exact pins previously shipped by the framework, preserves unrelated policies, and refuses conflicting custom policies before writing files. In pnpm workspaces it names competing nonempty root `resolutions` or `pnpm.overrides` and explains their explicit reconciliation. Peer repair refuses cross-major global policy changes. Bun workspaces require Bun >=1.4.4 and a supported `packageManager` pin or `engines.bun` floor; upgrade the actual tool and older declarations before retrying, because Bun 1.2.0 ignored the scoped companion pin. `voltro update` carries the review as `0.88.0/06_effect-override-scope`.
+- **Keep test runners out of production KV and workflow dependency closures** — `@voltro/kv`, `@voltro/workflow`
+
+  The test-only HotStore and workflow conformance suites now require their caller to supply runner operations. Pass `{ describe, it, expect }` as the third argument to `hotStoreConformance`, and `{ describe, test, expect, beforeAll, afterEach }` as the second argument to `runClusterEngineSuite` and `runJournalEncryptionSuite`. The exported structural runner interfaces have no dependency on Vitest. Both production packages remove their optional Vitest peer; an application's development runner can no longer enter a production deployment through those peer links. Keep Vitest in the test application's own devDependencies. Runtime KV/workflow calls and `runHotStoreSqlParity` are unchanged. `voltro update` identifies direct suite imports for review.
+- **REST test handlers publish events under the request tenant** — `@voltro/testing`, `@voltro/cli`
+
+  When crossing 0.87.0, custom `makeTestApp({ restRoutes })` handlers receive a request-scoped `ctx.app` instead of the root fixture context. Event assertions must subscribe to that request tenant: the default anonymous request uses `acme` or `x-tenant`; an explicit `anonymous: 'no-tenant'` uses `''`, distinct from the event bus subscriber's default `null`. Pass the app's anonymous policy, select the subscriber tenant explicitly and assert delivered payloads even when HTTP success and `notified` already pass. Direct `invoke` retains its supplied context identity, and projected `publicApi` handlers already use request-scoped invocation. Plugin HTTP routes are not mounted by this request harness. `voltro update` locates raw request harness calls and prints the review steps.
+
+### Added
+
+- **voltro add patches --ai accepts ai 7.0.156** — `@voltro/cli`, `@voltro/ai`
+
+  `voltro add patches --ai 7.0.156` wires the AI SDK declaration correction for `@ai-sdk/provider-utils` 5.0.70, regenerated with the original build from the release commit; JavaScript stays byte-identical to the published package. 7.0.105 and 7.0.132 remain selectable. `@voltro/ai` is built and tested against ai 7.0.156.
+- **The retained invoice observations table is exported from the billing package** — `@voltro/plugin-billing`
+
+  `billingRetainedInvoiceObservationsTable` is exported from `@voltro/plugin-billing` beside the other billing tables, so an app can reference it.
+- **plugin-billing accepts stripe 23** — `@voltro/plugin-billing`
+
+  The `stripe` peer range is `^22.6.1 || ^23.0.1`. stripe 23 pins Stripe API version `2026-09-30.endive`; the plugin still sends no `apiVersion` of its own, so the SDK's pinned version applies.
+
+### Changed
+
+- **A booting server holds requests until the app is ready instead of answering 503** — `@voltro/runtime`, `@voltro/voltro`
+
+  `voltro serve`, `voltro start` and `voltro dev` used to answer every request that arrived before the boot finished with a plain-text `503 starting`. On a platform that scales to zero, that request is the visitor who woke the instance, and a browser does not act on `Retry-After` for a navigation. Requests and WebSocket upgrades that arrive while the app boots now wait and are handed to the app in arrival order once it is ready. The wait is bounded by `VOLTRO_BOOT_HOLD_MS` (default `30000`, at most five minutes, `0` restores the immediate `503`) and by 512 waiting requests. A request the wait cannot cover still gets `503` with `Retry-After: 1`, and a browser navigation gets a minimal page that reloads itself. `/internal/startup` reports waiting requests as `held`, and `bindBootListener` accepts `holdMs` and `maxHeld`. Probes are unchanged, so nothing changes under Kubernetes.
+- **DocsLayout navigation nests collapsible groups with page counts** — `@voltro/ui-shadcn`
+
+  `DocsLayout` renders its sidebar as one tree: headerless groups are flat start links, other groups and sub-groups are collapsible rows with page counts, `DocsNavSubGroup` accepts nested `subgroups` and `trailingEntries`, the current page's link carries `aria-current="page"` (forwarded through `ShellLinkProps`), and the rail scrolls the active link into view after navigation.
+- **Native Redis connections use ioredis 6 and keep the RESP2 protocol** — `@voltro/kv`, `@voltro/runtime`, `@voltro/cli`
+
+  The native Redis transport moved to ioredis 6, which defaults to RESP3. Registry connections set `protocol: 2`, so command replies, Pub/Sub and Lua results keep their shapes.
+- **Connection drivers install only with the server runtime** — `@voltro/kv`, `@voltro/runtime`
+
+  `ioredis`, `@upstash/redis` and `@nats-io/transport-node` are optional peers of `@voltro/kv` and dependencies of `@voltro/runtime`. API apps keep all three without a step; web apps and SDKs that reach `@voltro/kv` only through types no longer download server drivers. Code that opens a connection without `@voltro/runtime` adds its driver, and a missing driver now fails naming the package.
+- **The mobile template targets Expo SDK 58** — `@voltro/cli`
+
+  New mobile apps scaffold on Expo SDK 58 with React Native 0.88.1 and React 19.3.0, using the versions SDK 58 bundles for its native modules.
+- **plugin-sentry runs on Sentry 11 and exports server spans over OTLP** — `@voltro/plugin-sentry`
+
+  Sentry 11 removed `SentrySpanProcessor`. The plugin now exports the framework's spans to the OTLP endpoint Sentry derives from the DSN and links errors and logs to the active span with `openTelemetryIntegration()`; the Sentry SDK records no spans of its own. `tracesSampleRate` keeps its meaning and is applied per trace id at the export. Server traces need the optional `@opentelemetry/sdk-trace-base` and `@opentelemetry/exporter-trace-otlp-http` packages (they replace `@sentry/opentelemetry`); without them the plugin warns and reports errors and breadcrumbs only. `init.tracesSampleRate` and `init.enableOpenTelemetrySetup` are ignored, and `init.skipOpenTelemetrySetup` no longer exists in Sentry 11.
+
+### Fixed
+
+- **Deferred workflow starts retain their original caller receipt** — `@voltro/workflow`, `@voltro/cli`
+
+  A controlled workflow start now returns its existing queued receipt when another replica exhausts submission retries, or shared capacity moves, before its acceptance callback dispatches. It no longer reports an ordinary start failure while the committed submission remains unresolved. Execution identity, caller input, capacity ownership and retry limits stay unchanged; definite rejection and invalid ownership still fail explicitly.
+
+- **Aggregate counters are non-negative safe integers on every dialect** — `@voltro/database`
+
+  A `count()` / `countDistinct()` / ranking counter now decodes to a number only when it is a non-negative safe integer; a fractional, negative, non-numeric or larger value is refused instead of passed through or rounded. SQLite and Turso decode counters too when the queried table has decimal columns, where they used to stay strings.
+- **Cache clear honors connection namespace prefixes** — `@voltro/kv`, `@voltro/cache`
+
+  Clearing a cache through a named, namespaced Redis connection now binds logical cache keys to that connection's physical namespace. Redis-family engines and the local transport preserve neighboring caches and invalidation fences, while refusing foreign prefixes and forged key sets. The existing atomic cache command format remains unchanged.
+- **Cache commands use the selected app's configuration and connections** — `@voltro/cli`
+
+  `voltro cache status`, `flush` and `invalidate` resolve `app.config.ts`, environment overrides and named Redis connections exactly like Dev and Serve, including an optional target app directory. Invalid configuration fails instead of silently reporting memory, in-process transports refuse CLI mutation, and diagnostics omit endpoint URLs and credentials.
+- **Generated cache examples boot and upgrade reviews name affected lines** — `@voltro/cli`
+
+  The seeded core API example now uses an object cache declaration. Forced guide refresh discovers both flat and project-grouped app layouts, replacing stale nested examples without executing configs or crossing an app boundary. The shared cache/KV migration review lists authored code locations, including asserted backend literals, and a new review reaches applications that already crossed the original migration. It also identifies stale core guides for refresh; protected hand-maintained guides stay under their owner's control.
+- **Subject query caches follow current authority** — `@voltro/runtime`, `@voltro/testing`
+
+  Subject-scoped computed queries key the complete subject claims and raw and resolved permission sets. Removing an admin grant, changing roles or switching tenant or credential type cannot reuse a result admitted under earlier authority. Authentication refreshes before lookup, and a change while a read is pending refuses retention and delivery. Connection-local state is never covered by subject scope; handlers that read it do not retain their results. The same decisions apply to `invoke` tests, memory caches and Redis caches.
+- **Preserve connection declaration errors across module boundaries** — `@voltro/kv`
+
+  Redis, NATS, Storage, Analytics and SQL registries retain typed configuration diagnostics across module and VM boundaries instead of mislabeling them as dynamic credential failures. Errors returned by credential resolvers remain redacted.
+- **Bind demo API tenants consistently in browser and server renders** — `@voltro/cli`
+
+  The fullstack, admin, SSR API and public status templates now send their explicit demo tenant to header-based anonymous APIs. SSR API and status pages use the same binding for server-side RPC reads, so a fresh scaffold renders successfully and its browser subscriptions select the same data. API refusals for missing tenants and access checks remain enforced. These demo bindings select rows and do not authenticate users; private production data requires verified authentication. Fresh-consumer diagnostics retain uppercase error log lines.
+- **Two voltro dev processes starting together mint one set of secrets, not two** — `@voltro/cli`
+
+  `voltro dev` mints missing project secrets into `.env.local`. Two processes on one project starting at the same time (two local replicas, a dev server beside a test boot) each minted their own values; with field encryption the database recorded one key and refused the second process at boot. Minting now runs under a lock and adopts a value another process wrote meanwhile; a lock left by a crashed mint is taken over.
+- **Event warnings follow workspace package exports** — `@voltro/cli`
+
+  Development event wiring warnings now recognise sibling `useEvent` consumers imported through package exports, TypeScript path aliases, named and namespace re-exports, and static local aliases. Each subscription is matched to its descriptor so an unused import or another API's same-named module does not hide a missing consumer. Workspace discovery supports declared pnpm, npm, Yarn and Bun members and excludes nested projects and build output.
+- **Index audit preserves partial row coverage and uniqueness** — `@voltro/database`
+
+  The index audit recommends dropping an index only when another B-tree index preserves its row coverage and uniqueness. Partial unique indexes no longer make full indexes appear redundant; specialized index methods and unproved predicate relationships are excluded, and recommendations name only the safe replacement direction.
+- **Migration logs identify which operations their count includes** — `@voltro/database`
+
+  Development auto-migration logs now identify their applied-operation count as the planner pass, excluding framework bootstrap and file-based migrations. A schema plan taken before boot can include work completed by those earlier stages; run a new plan after boot to verify that no operations remain.
+- **Filter completed workflow pool owners before recovery transport** — `@voltro/cli`, `@voltro/voltro`, `@voltro/workflow`
+
+  Pool release recovery now persists its terminal settlement on submission and restart owners and filters those markers through indexed SQL predicates. Finished owner history no longer crosses the wire on every idle pass or after process restart. Lost release acknowledgements, held owners and missing evidence remain recoverable and reported; immutable owners and permit tombstones remain for receipt and replay safety. Normal framework schema migration adds two nullable settlement markers and their indexes; existing history is checked once in bounded pages. Settlement indexes use explicit short names within SQL identifier limits. Reconciliation cadence is unchanged.
+- **Presence transport warnings follow actual subscription readiness** — `@voltro/plugin-presence`
+
+  Presence reports pending binding or subscription acquisition without a false missing-provider warning after five seconds. It reports cross-instance readiness only after acquiring the broadcast subscription, while local-only bindings and failed subscriptions still warn. Closing or replacing a binding prevents stale callbacks and releases subscriptions acquired afterward.
+- **Self-updates finish after the old CLI installation is removed** — `@voltro/cli`, `@voltro/runtime`
+
+  `voltro update` loads its completion helpers before installing the target version, so removing the running CLI package no longer turns a successful upgrade into a missing-module failure. Error reporting uses the shared lightweight `@voltro/runtime/boot-refusal` entry loaded before dispatch; genuine failures keep their original message and exit code without loading the server dependency graph for help or version commands.
+- **Compiled API servers start without a source-analysis dependency** — `@voltro/cli`
+
+  The development event-consumer audit loads its source compiler only when scanning. A compiled API server can start after relocation without app sources or a direct `ts-morph` dependency. Package-export consumer discovery keeps its existing scope and does not execute application modules.
+- **SignalHeader centers its brand in the masthead** — `@voltro/ui-shadcn`
+
+  The `SignalHeader` brand slot is a centered flex row, so a brand link no longer sits on the text baseline and renders a few pixels above the masthead's center.
+- **Update reports changed runtime patch assets before boot** — `@voltro/cli`
+
+  `voltro update` compares configured pnpm Effect and SQL-driver patches with the target CLI's assets during its codemod step, including `--codemods-only`. Changed bytes produce refresh and install instructions even without workflows. Same-version checks also report drift. Custom patch paths are named and files remain untouched.
+- **Upgrade reviews omit locator counts and unchanged REST type plumbing** — `@voltro/cli`
+
+  The aggregate review excludes locator chains and local locator aliases while retaining uncertain query receivers. The idempotency review lists REST context constructions, context factories and guard definitions instead of every context or guard parameter annotation. Aliased imported calls in JavaScript custom hosts remain visible.
+
+### Internal (no consumer-facing effect)
+
+- **Effect audits distinguish regression data from executable legacy APIs**
+
+  Effect migration audits allow test data to describe a foreign dependency's retained major. Removed package imports and obsolete bound API calls remain findings in tests and application code, while production migration-residue checks remain unchanged.
+- **The doctor's table nullability manifest covers the billing history tables** — `@voltro/cli`
+
+  The generated nullability manifest `voltro doctor` reads was missing the invoice-history and customer-account tables the billing plugin added; it is regenerated from the declarations.
+- **Installation checks refuse ambient workspaces and source overrides**
+
+  Installation checks require standalone directories before creating projects. Artifact consumers use shipped template and documentation assets without inheriting maintainer source overrides or Node module loaders. Registry, package-manager and explicit application settings remain available.
+- **Installation checks require healthy applications and usable modules**
+
+  Installation checks require API readiness, successful web responses and transformed JavaScript modules while the development process remains running. HTTP errors and HTML fallbacks cannot satisfy those checks. Diagnostics distinguish application startup from shutdown.
+- **Keep CLI fixture temporary roots and child outcomes explicit**
+
+  Automatic sidecar tests inspect the actual operating-system temporary directory and release their bound owner even when an assertion fails. Schema-boot fixtures retain the child's exit signal and assert the real exit tuple alongside readiness and migration counts, so a signal cannot become a false successful process result. Production security and signal guards remain unchanged.
+
+  Workflow recovery tests distinguish the recorded failure budget from concurrent dispatches already in flight. They retain the same prepared execution identity, require one body execution, and verify that stopped or accepted submissions cannot dispatch again.
+- **Native SQL checks isolate schema ownership across fixtures**
+
+  Wallet and shop checks own separate server databases so concurrent schema creation cannot contend with another fixture's live writes. Independent pools within a fixture still share the real database. Cleanup closes all acquired pools before dropping only the owned namespace, and a native regression verifies isolation with identical wallet identities.
+- **Native reload checks retain manifests published during SQL observation**
+
+  Native geometry checks establish the expected-version receiver before reload activation. A real transport regression holds the consumer until the new manifest arrives, so asynchronous SQL observation cannot hide a missed publication. Frame deadlines retain their original call sites.
+- **Native snapshot probes join their scheduled driver**
+
+  Held-source stream probes quiesce and join the actual Host driver before directly pumping its captured graph. This prevents a scheduled turn from concurrently entering that graph and closing the fixture's native Session. Listener, SQL, controller, wire delivery, rights withdrawal and final cleanup assertions remain active; ordinary stream cases retain the running driver.
+- **Bound the reviewed Sentry tool exception and retain every dependency instance**
+
+  The owner-reviewed exception accepts only sentry 0.45.0 under FSL-1.1-Apache-2.0 as unmodified external tooling for the Sentry integration. This does not classify FSL as permissive or remove its competing-use restriction. The runtime license walk checks every resolved instance, so an accepted version cannot hide a second version or license. Generated notices and the SBOM use actual package identities. Containment checks cover framework, workspace and scaffold patch files plus declared patches with arbitrary filenames; the API bundler leaves the tool external.
+- **Stack scaffold checks require major-scoped runtime alignment**
+
+  The normal stack scaffold regression parses its generated workspace policy and verifies both Effect 4 selectors while refusing unqualified Effect and companion pins. Patch declaration and actual patch-byte checks remain, so the regression follows the preserved foreign-major contract instead of demanding its earlier unsafe global override. Its synthetic workspace declares its own pnpm version, making Compose baseline coverage independent of the test runner's package-manager environment.
+- **Dependency security checks verify installed source remediations**
+
+  Dependency security checks accept a reviewed source remediation only after verifying exact patch and implementation hashes, patched references in every lockfile document, actual caller resolution and runtime behavior. Deepmerge's returned-object prototype protection preserves ordinary configuration merging. Unaffected dependency graphs receive no exception, and a local source remediation is never reported as an upstream fixed version.
+
+---
+
 ## [0.87.0] — 2026-10-31
 
 ### ⚠ BREAKING
@@ -3231,6 +3391,15 @@ _Changes staged for the next release accumulate here (rolled up from
 - **Prepare the exact XYFlow type correction before normal installation** — `@voltro/cli`
 
   `voltro add patches --xyflow 12.12.0` prepares the original XYFlow declaration correction and its complete license/notice before a normal package-manager or UI installation. Existing conflicting project patch assets are preserved and rejected before writes.
+- **Dispatchers drain accepted reads before store disposal** — `@voltro/runtime`, `@voltro/cli`
+
+  Runtime adds `Dispatcher.closeAndDrain()` to join accepted reads and deliveries before store disposal. Normal Dev and Serve API shutdown await it; synchronous `close()` remains available.
+- **Workflow cluster hosts declare shard groups and ClusterCron routing groups** — `@voltro/workflow`, `@voltro/cli`
+
+  Workflow cluster hosts can explicitly declare available/assigned shard groups and ClusterCron routing groups. Omitted settings retain existing routing; persistent journal migration is a separate prerequisite for changing groups.
+- **PostgreSQL workflow hosts can persist routing-generation admission** — `@voltro/workflow`, `@voltro/cli`
+
+  PostgreSQL workflow engine hosts can opt into persisted routing-generation admission with `journalRouting`; actual durable MessageStorage operations use the ownership guard. Full API-role wiring and maintenance rollout remain separate requirements.
 
 ### Changed
 
@@ -24321,9 +24490,3 @@ public registry yet.
 
 Subsequent releases record their deltas from here under dated headings, with
 `⚠ BREAKING` first.
-
-- Runtime adds `Dispatcher.closeAndDrain()` to join accepted reads and deliveries before store disposal. Normal Dev and Serve API shutdown await it; synchronous `close()` remains available.
-
-- Workflow cluster hosts can explicitly declare available/assigned shard groups and ClusterCron routing groups. Omitted settings retain existing routing; persistent journal migration is a separate prerequisite for changing groups.
-
-- PostgreSQL workflow engine hosts can opt into persisted routing-generation admission with `journalRouting`; actual durable MessageStorage operations use the ownership guard. Full API-role wiring and maintenance rollout remain separate requirements.