@voltro/plugin-ai-flows 0.68.0 → 0.69.0

package/CHANGELOG.md

@@ -39,6 +39,228 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.69.0] — 2026-09-10
+
+### ⚠ BREAKING
+
+- **@voltro/runtime** — A typed store error now reaches the caller as itself instead of being re-wrapped as `StoreOperationFailed`.
+
+  The Effect store's catch boundary passed two of the six `StoreError` variants through by name and wrapped everything else. The wrapper builds `cause` with `wireSafeCause`, which reads DRIVER fields — and a typed error carries none, so it landed on its own class name. A consumer's postgres answered `23503` with `ai_generation_requests_createdBy_fkey`; the store classified it into a `ConstraintViolation` carrying that name, and the client received `StoreOperationFailed { cause: "ConstraintViolation" }`. The constraint name was extracted correctly and then discarded by re-wrapping — the half that turns a half-hour search into a one-line diagnosis, and the half `cause` promises in its own doc comment.
+
+  `ConstraintViolation`, `TableValidationFailed` and `ServerOnlyColumnWrite` now arrive typed, with their constraint, issues and columns intact. The rule is over the SET — every `StoreError` variant — because naming variants individually is what produced this.
+
+  **Check your descriptors' `error:` unions.** A handler that declared only `StoreOperationFailed` to catch constraint failures will now see a `ConstraintViolation` it does not declare, which reaches the client as an untagged internal error instead. Declare the variant you actually want to catch, or `StoreError` for all of them.
+
+  **`voltro update` carries you across this** — codemod `0.69.0/06_typed-store-errors-are-not-rewrapped`. 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.69.0).
+- **@voltro/runtime, @voltro/voltro** — Issuing an API key now plants its `actors` row, and `ApiKeyStore` gained a required `ensureActor`.
+
+  `actors.kind` is declared by the framework as `'user' | 'serviceAccount' | 'apiKey' | 'system'` and `audit()` makes every `createdBy` a foreign key onto that table — so an API key is explicitly an audit subject. `issue()` wrote only `_voltro_api_keys`, so the row never existed: measured in a consumer's database, `actors with kind='apiKey'` came back 0, and the first audit-stamped insert by a key-authenticated caller died on the foreign key. `apiKeys:` and `audit()` are both on by default and were not combinable.
+
+  The row is planted BEFORE the key row, so a failure leaves no usable key rather than one that authenticates and then dies on its first audited write. Its id equals the key id, which is what `apiKeyStrategy` presents as `subject.id` — the `actors.id == subject.id` convention the core table documents. Revoking leaves the row: it is the author of everything that key wrote.
+
+  `@voltro/voltro` is named too because it re-exports the runtime surface, so the break reaches an app importing from the aggregate exactly as it reaches one importing from `@voltro/runtime`. (`memoryApiKeyStore`'s return type also widened to expose the planted rows for tests — an intersection, still assignable to `ApiKeyStore`, so that half breaks nobody.)
+
+  `ensureActor` is REQUIRED rather than optional. An optional hook would be the same defect with a nicer name — the mistake was omission, and an optional field is omissible. Both framework stores implement it; only an app with its own `ApiKeyStore` has anything to do.
+
+  **`voltro update` carries you across this** — codemod `0.69.0/05_api-key-store-plants-its-actor`. 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.69.0).
+- **@voltro/ai, @voltro/plugin-billing, @voltro/plugin-comments** — `ai`, `@ai-sdk/provider`, `@ai-sdk/gateway` and `stripe` are peer dependencies now — and `@voltro/plugin-comments` stops shipping its own `effect`.
+
+  `@voltro/ai` declared `ai: ^7.0.92` under `dependencies`. An app that configures a provider directly declares `ai` itself, and one that pinned it below our floor got a SECOND physical copy — with it a second `@ai-sdk/provider-utils`. Those types are branded with a symbol, so two structurally identical copies are not assignable to each other:
+
+  Argument of type '…provider-utils@5.0.39/…ToolSet | undefined' is not assignable to parameter of type '…provider-utils@5.0.33/…ToolSet | undefined'
+
+  Nothing fails at install and nothing fails at runtime. It surfaces as a typecheck error, only at the seams where an SDK type crosses the package boundary — which for `@voltro/ai` is thirteen types in its own api golden, `ToolSet` among them. `effect` has been a peer from the start for exactly this argument; it had never been applied to the SDKs whose types cross the same line.
+
+  **The criterion is narrower than "the type crosses the boundary", and the difference is what keeps this from becoming churn.** Counted over the repo, 21 packages have a third-party dependency whose types appear in their api golden. A second copy needs a second DECLARER, so the question is whether the APP is expected to declare the package too. It is for `effect` (every handler imports it), for `ai` / `@ai-sdk/*` (you declare them to configure a provider) and for `stripe` (`normalizeStripeEvent` takes an event built by the app's own SDK instance). It is not for `@effect/sql`, the dialect drivers, `ioredis`, `@opentelemetry/*` or `@radix-ui/*` — one range is declared in one place and one copy resolves.
+
+  `scripts/check-boundary-peers.mjs` (CI + `pnpm check:boundary-peers`) asserts that rule and PRINTS the judged-invisible set on every run, because a check that has quietly narrowed reads exactly like a clean one. It ships a `--selftest` that re-introduces `ai` as a dependency and requires the rule to fire.
+
+  `@voltro/plugin-comments` was the one package declaring `effect` under `dependencies` while every other peers it — the two-copies rule the repo already holds absolutely, with a single unapplied exception.
+
+  Most apps do nothing: the installer resolves a peer it can satisfy. An install that now warns about an unmet peer is the change working — it is saying that your pin and ours do not intersect, which is what silently produced the second copy before.
+
+  **`voltro update` carries you across this** — codemod `0.69.0/03_sdk-peers-are-declared-by-the-app`. 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.69.0).
+- **@voltro/plugin-storage** — The self-service upload routes refuse a caller with no identity, unless the app declares `storagePlugin({ anonymousUploads: true })`.
+
+  Those routes are `openAccess`, and each justified itself in source with "the ticket binds the calling subject + tenant, caps size, and the finalize path runs limits + scan". Every clause after the first depends on there BEING a calling subject, and `openAccess` does not establish one — an unauthenticated request resolves to an anonymous subject carrying `id: null`. So a visitor could mint a ticket with `sub: null, tenant: null`, and the object it finalized belonged to no owner and sat in no tenant: unreachable by every later owner check, tenant filter and quota, with a subject binding that compares `null` against `null` and therefore passes for every subsequent caller.
+
+  The framework already refuses exactly that comparison one level up — `defineMutation` rejects `requiresApproval` beside `openAccess` because "two anonymous callers both compare as `null`". Same shape, one layer down.
+
+  Whether a caller must be identified is not a wire question and the descriptor cannot answer it: only the app knows whether it wants a public intake. So the WIRE stays open — `openAccess` is unchanged and still means "anyone who can reach this may call it" — and the identity requirement lives in the plugin, where the app's own answer is in scope. `anonymousUploads` defaults to false; an app that turns it on is choosing ownerless objects deliberately, and should pair it with `limits` and a `scan`.
+
+  It is fixed over the SET rather than at the route that shows it best. Five handlers took the subject straight off the request — the ticket mint, the presigned mint, the resumable begin, the multipart begin and the direct upload — and `ctx.request.subject.id` reads as locally correct at every one of them; a sixth is one paste away. There is one resolver now, `ingestUrl` is routed through it too so write attribution has a single spelling in the file, and a test asserts over the source that no `sub:` or `ownerId:` takes its value from the request.
+
+  The finalize and multipart-completion comparisons said "the token is bound to the minting subject; a different caller can't finalize it", which is false for a ticket that was minted anonymously. That is one named function now, and it says what the binding actually is in that case: possession of the signed, short-lived token, and nothing else.
+
+  **`voltro update` carries you across this** — codemod `0.69.0/02_anonymous-uploads-must-be-declared`. 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.69.0).
+- **@voltro/database** — `releaseMigrationLock` is gone; `acquireMigrationLock` returns the release.
+
+  Because the MySQL migration lock was being released while the migration was still running.
+
+  Every dialect but sqlite implements it as a SESSION-scoped object — `GET_LOCK`, `pg_advisory_lock`, `sp_getapplock @LockOwner = 'Session'` — and all three die with the connection that took them. Taken through the pooled client, that stated an intent the plumbing did not keep. Measured on MySQL 8, with a second connection watching both the lock and the process list:
+
+  direkt nach acquire gehalten von conn 131 +500ms lock=FREI conn 131 lebt=false
+
+  The holder was gone inside half a second — closed, not returned to the pool — so the server dropped the lock and two `voltro db apply` runs against one server could both proceed past the thing that exists to stop exactly that. Postgres survived the same window, which is a driver's idle policy rather than a property: `@effect/sql-pg` keeps its connections and `@effect/sql-mysql2` does not. The lock now RESERVES its connection for as long as it is held, on every session-scoped dialect. sqlite is exempt and must stay exempt — its lock is a no-op and reserving its single connection would starve the work.
+
+  `acquireMigrationLock` returns the release instead of there being a free `releaseMigrationLock(sql, scope)`. A free release cannot know which connection took the lock, and on all three dialects a release on the wrong connection is a no-op that reports success — which is what it had been doing.
+
+  **Fixing that alone would have wedged every migration after a failed one**, and that is the more important half. `applyPlan` and the file-based runner released the lock from a `try/finally` inside `Effect.gen`, and a `finally` there does NOT run when a yielded effect FAILS: Effect short-circuits without resuming the generator. Measured — a deliberately failing operation reached neither the finalizer nor the release. The hole is as old as those functions and was invisible for as long as the release did nothing and the lock dissolved on its own. Two defects cancelling reads exactly like neither existing. Every acquisition is bracketed with `Effect.acquireUseRelease` now, which also covers defects and interruption, and a guard asserts it over the SET of call sites rather than the one that was found — three had the same shape, and the shape looks correct.
+
+  The fakes gained the `reserve` a `SqlClient` always owed, from one shared definition rather than six copies. It suspends: a real connection method BUILDS an effect rather than running the statement, and a fake that records on call instead of on run reports `RELEASE_LOCK` before the DDL it follows — a fake inventing an ordering violation, which reads exactly like a real one.
+
+  **`voltro update` carries you across this** — codemod `0.69.0/01_migration-lock-returns-its-release`. 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.69.0).
+- **@voltro/protocol** — `workflowToRpc` preserves the literal workflow name and the payload schema, so a workflow no longer widens the generated client.
+
+  It was typed `Rpc.Rpc<string, Schema.Schema.Any, …>`. A by-name lookup in an rpc group matches members by tag and every tag is assignable to `string`, so that one member joined the lookup for every OTHER procedure: a single workflow erased typed access to the entire group.
+
+  Filed BREAKING under this file's own "more precise is still BREAKING" rule — nothing was removed, the client simply gained the type information it should always have had, and that is strictly more ways to fail `tsc`. Apps without a workflow are unaffected.
+
+  Migration: run `voltro codegen` (or boot `voltro dev`), then typecheck. The new errors are real disagreements — a payload that never matched its schema and failed at runtime instead, a now-redundant cast, or a cast that refuses because the two shapes genuinely differ. Do not silence any of them with `as unknown as`; that restores exactly the blindness this removes.
+
+  **`voltro update` carries you across this** — codemod `0.69.0/04_workflow-rpc-types-are-precise`. 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.69.0).
+
+### Added
+
+- **@voltro/database, @voltro/runtime** — `upsertRowOutcome(store, table, row, options)` — the upsert, plus whether it INSERTED or UPDATED.
+
+  `upsert` returns the row and not what happened to it, so an app that has to report "created" reads first and then upserts. Measured on a real ingest: one extra query per row, purely to set a flag — and a window, because another writer between the read and the write makes the answer wrong.
+
+  It costs nothing to answer. The store wrapper mints the row's `id` before the statement, and on the conflict path every dialect hands back the EXISTING row's id — a fact `upsertBinding`'s header already relied on for the encrypted-column binding. Two ids that differ ARE the answer. No dialect implements anything: the outcome is decided from what the wrapper already had in hand.
+
+  **`'inserted'` is never a stand-in for "could not tell",** and that is the half worth reading. The free comparison needs an id the wrapper minted — a caller-supplied id is unchanged on both paths, and a database-assigned one does not exist yet — so in those two cases the destination is READ first and the answer stays exact. Only a call that asked for the outcome pays for it; plain `upsert` is byte-for-byte the call it was.
+
+  That required separating two facts `upsertDestinationId` had collapsed. It returns the OFFERED id both when nothing conflicts and when the conflicting row's id happens to BE the offered one — identical answers for binding a ciphertext, opposite answers for "what did this do". `upsertConflictId` reports existence; the destination is derived from it.
+
+  The helper is `async` so its refusal (a hand-written `DataStore` without the method) arrives as a rejection rather than a synchronous throw: a function whose type says `Promise` and which sometimes throws before returning one splits every caller's error handling in two.
+
+  **No `upsertMany`.** The batch form was asked for alongside this, and the reported batches are ~30 rows — at that size the round trips are not the cost, the missing `created` flag was, and it is now free. A conflict-write batch still belongs in ONE `store.transactional` with a capped input, which is what the `bulk-write-in-loop` advice says.
+- **@voltro/cli** — `VOLTRO_DASHBOARD=on` — the counterpart `off` never had.
+
+  The launcher skips the dashboard when stdout is not a TTY, which is a good stand-in for "nobody is watching": CI, a smoke run, a piped script. It stops being one the moment a task runner is in the way. `turbo run dev` — how a multi-app project is normally brought up — captures each task's output to prefix it (24 731 prefixed lines in one gate log), so `isTTY` is false for a developer sitting right in front of it, and the dashboard could not be turned on at all.
+
+  Measured on the same non-TTY boot, before and after:
+
+  without dashboard not launched: stdout is not a TTY (CI/smoke) with auto-launching dashboard at http://localhost:5179
+
+  It overrides only the guess. The recursion guard, the launch lock and the port-in-use check are measurements rather than proxies and still apply — so two apps started together still share one dashboard, and the second reports `already-running` instead of racing for the port.
+
+  The skip reason names the variable, because a guess you cannot overrule is a wall.
+- **@voltro/devtools-ui** — Show automatic data synchronization as a connection status, highlight changed cells and new visible rows, and briefly retain confirmed deleted rows in red. Query navigation stays quiet, active editors retain focus, and reduced motion uses a static tint. Local and Cloud providers carry CDC deletion identities.
+- **@voltro/ui-shadcn, @voltro/devtools-ui** — Cloud and local Devtools now share `SignalWorkspace`, `SignalWorkspaceHeader` and `AppInspectorHeader`: one masthead, background, heading rhythm and app identity. Local navigation and live charts keep their full functionality while using the shared workspace styling and semantic theme colors.
+- **@voltro/database** — `insertManyRows(store, table, rows)` — `insertRow`'s batch, typed on the element.
+
+  It forwards to `store.insertMany` unchanged, so the chunking, the dialect behaviour and the conflict semantics stay exactly what the string-keyed call already did. What it adds is the type link the string-keyed form cannot have: every element is checked against the table's insert row, so an element missing a required column, misspelling one, or passing a `number` where the column is a timestamp is a compile error at the call site rather than a dialect error somewhere inside the batch.
+
+  The batch needed its own helper rather than a loop over `insertRow` because of where the mismatches actually come from: a batch is usually MAPPED — from a parsed import, an API page — and the loop body's inferred element type is only as good as whatever produced the array. That is the shape a mapped `Date` versus `number` survives review in.
+
+  The set-based conflict forms (`insertManyIgnore`, `upsertMany`) remain unbuilt, for the reasons already recorded against them; this is a typing gap, not a conflict-handling one.
+
+### Fixed
+
+- **@voltro/protocol** — An auth strategy that declares a `claimsBearerPrefix` is now asked BEFORE strategies that declare none, for a token carrying that prefix.
+
+  Turning on `apiKeys:` made every API key unusable as soon as a JWT strategy sat in the chain. Two reasonable pieces produced a third thing nobody chose: `apiKeys:` appends the framework key strategy LAST, and `jwtBearerStrategy` — so all six catalog strategies (supabase, auth0, clerk, kinde, oidc, workos) — claims EVERY `Authorization: Bearer`. A token it cannot verify comes back `failed`, not `skip`, and a `failed` ends the chain by design, because a credential another IdP rejected could be an attack masquerading as ours. So a valid key was refused by the JWT verifier before the key strategy was ever asked. Nothing logged an error; the key simply never worked.
+
+  The boot check could not see it: it warns when TWO strategies declare the same prefix, and the JWT strategy declares none while claiming everything.
+
+  `failed` still ends the chain — that property is untouched. What changed is who is asked first: a declared prefix is a strategy saying "this token shape is mine", which is more specific than claiming everything by declaring nothing. A token matching no declared prefix leaves the chain in exactly the order the app wrote it, so a real JWT is still claimed, and still rejected, by its own verifier.
+- **@voltro/cli** — `voltro build` fails when the SSR bundle it just wrote cannot be imported — and `build: { ssrExternal: [...] }` is the exit that `ssr.noExternal: true` did not have.
+
+  The web SSR build bundles everything the graph reaches so a production image needs nothing from `node_modules`. A CommonJS dependency pulled into that ES module carries its `__dirname` / `__filename` along, and neither exists there. Measured against a real app: the build is GREEN, the bundle is written, and the artefact dies on its first import with `ReferenceError: __dirname is not defined in ES module scope`. The same dependency externalised: exit 0.
+
+  Two things were missing, and only fixing both helps. `noExternal: true` was hard-wired with no config evaluation beside it, so an app had no way to keep one package a runtime import — there was no app-side workaround at all. And the build reported success, so the failure arrived at deploy time as a boot crash three layers from its cause.
+
+  The externalisation is deliberately NOT automatic. Externalising on the framework's own initiative puts a package back among the image's runtime requirements; an image built on the promise that it needs nothing from `node_modules` would then fail to boot for a second reason, with nothing said about either.
+
+  **The detector reads the artefact, and it was wrong once before it was right.** Run over the 357 built ESM files in this repo it flagged exactly one — a false positive, in `@voltro/cli`'s own bundle, on the line
+
+  "import { join as __join, dirname as __dirname } from 'node:path'"
+
+  which is a string the build WRITES into a generated file. That is the same trap this repo already recorded once, for a different rule in the same package: a regex cannot tell a specifier from a specifier-shaped string. String literals are blanked before the scan and an import alias counts as a definition.
+
+  The correction had a second edge. A parameter arm added for the CommonJS wrapper (`function (…, __dirname)`) read `join(__dirname, 'assets')` as a declaration — a call argument and a parameter are the same characters — and silenced the exact reference the check exists for. It is gone; no shim of that shape appears in any of the 357 files, so it bought nothing and cost the rule. Both directions are asserted, and the false positive is kept as a fixture.
+- **@voltro/devtools-ui, @voltro/ui-shadcn** — Keep the dashboard masthead, tabs and inspector context compact so working tables start higher in the viewport. Group the app return link, identity, address and status in one responsive header shared by local and Cloud inspectors.
+- **@voltro/devtools-ui, @voltro/ui-shadcn** — Use the shared styled Checkbox for dashboard filters, workflow confirmations, inspect access and schema-driven checkbox forms, matching Cloud configuration controls while preserving native label, keyboard and form behavior. Checked and indeterminate fills now retain the primary color in dark mode.
+- **@voltro/cli** — The auto-launched dashboard died 85 ms after it was announced, silently.
+
+  `bin/voltro.mjs` is the only entry that registers the tsx ESM loader, and the CLI cannot run without it — it imports the app's own `app.config.ts` at runtime. The launcher derived the child's bin from `process.argv[1]` and handled ONE spelling: `<cli>/src/bin.ts` → `<cli>/bin/voltro.mjs`. Everything else fell through to argv[1] itself.
+
+  But `bin/voltro.mjs` re-execs, so inside the CLI argv[1] is the entry BEHIND it. Measured on a normal boot:
+
+  argv[1] = …/packages/cli/dist/bin.js bin = …/packages/cli/dist/bin.js
+
+  That is what every installed user runs, and every maintainer tree that has been built once. The child was handed the bundled entry with no loader and died on its first TypeScript import:
+
+  ERR_MODULE_NOT_FOUND: Cannot find module '…/packages/logger/src/logger' imported from '…/packages/logger/src/index.ts'
+
+  Nothing said so. The child is spawned with `stdio: 'ignore'` and nothing watched its exit, so the last word was the launcher's own `dashboard launched at http://localhost:5179` — a URL that answered nothing. The `/src/bin.ts` branch is why this was invisible from inside the framework repo: running unbuilt from source is the one case that worked.
+
+  The bin is resolved by walking up from the launcher's own module until `bin/voltro.mjs` is found, so `src/` and `dist/` reach the same answer — the point being that it must not depend on which of the two is running. Verified end to end from a `voltro dev` boot: `dashboard launched`, then HTTP 200 with the dashboard's own title.
+- **@voltro/cli** — The recommended dashboard install line contradicted the stability contract.
+
+  `pnpm add -D @voltro/dashboard` writes a caret range. The contract at the top of `CHANGELOG.md` tells users to pin exact versions and never `^`, and a project that follows it ends up with one dependency spelled differently from all the others — because we told it to. The message and both docs pages now say `--save-exact`.
+- **@voltro/cli** — An interrupted dashboard build made the launcher choose the one mode that cannot run in it — and then said nothing when the child died.
+
+  The mode was chosen by `existsSync(.framework/dist/index.html)`. A build writes that file EARLY and writes `dist/server/ssrEntry.js` LATE, so a build that dies in between — the prerender step is the one that does — leaves a tree that looks built. Measured on exactly such a tree:
+
+  serving the Voltro dashboard on :5199 … mode: start fatal: production `voltro start` requires a precompiled SSR bundle at …/.framework/dist/server/ssrEntry.js but it is missing
+
+  Keyed on the bundle instead, the same tree falls back to `dev`: vite ready in 169 ms, the port answers.
+
+  There were TWO deciders, spelled differently — the auto-launcher and the standalone `voltro dashboard` — and both were wrong the same way. One `dashboardIsPrebuilt` now, asserted over the set, because a third is one paste away.
+
+  **And the death was silent.** The launcher spawns with `stdio: 'ignore'`, which throws the child's own diagnosis away, and had no `exit` or `error` handler at all. So the last word on a dead dashboard was the parent's own `auto-launching dashboard at http://localhost:…` — a promise that was already false by the time anyone read it. A non-zero exit is reported now, and a signal stays quiet because that is how Ctrl-C reaches the whole process group.
+- **@voltro/devtools-ui** — Rework the shared data explorer around compact resizable columns, debounced search, explicit filter application, accessible record editing and searchable references. Preserve database defaults when creating rows, distinguish empty text from null, retain invalid drafts and write failures, confirm destructive actions and unsaved changes, and expose an optional host refresh callback for current snapshots.
+- **@voltro/devtools-ui** — Resize the data explorer's table list independently, read complete table names in delayed themed tooltips, and resize columns with visible pointer/keyboard handles. Double-click a divider to restore its default width.
+- **@voltro/cli** — Resolve local dashboard stream credentials for the inspected app in both dev and production, matching snapshot reads, and flush the development stream handshake immediately so live data updates can connect without repeated authorization failures.
+- **@voltro/devtools-ui** — Make inspector tasks directly discoverable through a grouped sidebar, replace flat route cards with a shared expandable route explorer, and keep Data explorer visible for frontend apps through an API data-source picker. Bound the mobile table list and support keyboard activation of editable cells and foreign-key navigation.
+- **@voltro/client** — A `title` annotation on a schema field now becomes the field's label — where the title is one somebody wrote.
+
+  `schemaToFields` / `schemaToColumns` derived every label from the humanised property name and ignored `title` entirely, so an app that had already annotated its schema (for OpenAPI output, say) had to say the same thing twice through `formField({ label })`, with the two free to drift.
+
+  `title` could not simply be read, and the reason is worth stating because the obvious rule is wrong. effect writes its OWN titles into that field, and it writes them INLINE on the property node — not only into a `$defs` entry behind a `$ref`. Measured:
+
+  Schema.NonEmptyString.annotations({ description: 'Der Kundenname' }) -> { title: 'nonEmptyString', description: 'Der Kundenname', … } Schema.String.pipe(Schema.minLength(2)) -> { title: 'minLength(2)', … }
+
+  So "use the title unless it arrived through a `$ref`" puts `minLength(2)` on a form field. What separates the two is the SHAPE of the name effect generates: a lowerCamel type name, optionally carrying the filter's arguments in parens. A title matching that is declined; everything else is the author's.
+
+  Two properties keep that honest. The failure direction is safe — a declined title falls back to the humanised name, which is what every field got before, so the rule can never do worse than the old behaviour. And it is not left as a claim about a dependency: the test regenerates the corpus through a live `JSONSchema.make` and fails if any generated title stops matching, so a change in effect goes red in the suite instead of wrong on somebody's form.
+
+  `formField({ label })` still wins over both — it is the one channel effect cannot write into.
+- **@voltro/cli** — `voltro update` no longer rewrites a package.json that does not consume the framework.
+
+  Reported after an upgrade changed `services/api/package.json` — an independent Strapi 4 backend with NO voltro dependency — from React 18 to 19. Nothing in the command's output named the file, and the app avoided it on the next round by setting versions by hand and running its own installer, which is a sidestep and not a fix.
+
+  The peer alignment already had three conditions, and all three are about the DEPENDENCY: only a peer the manifest already declares, only when its floor is below ours, only ranges both sides can parse. Every one of them was satisfied here — React was declared, 18 is below 19, both ranges parse. None of them asked whether the package was ours to edit.
+
+  It is not a new judgement, it is an unapplied one. `planWorkspaceBump` — the `@voltro/*` half of the same command — has always dropped manifests that declare no `@voltro/*` dep. The peer alignment was added later and did not inherit it. It does now: a manifest is in scope when it declares `voltro` or any `@voltro/*` in its dependencies, devDependencies or peerDependencies, and one package being out of scope does not take its siblings with it.
+
+  `consumesVoltro` is deliberately the whole test. A peer requirement comes FROM a `@voltro/*` package; a workspace member that declares none is not bound by it, however many packages it happens to share a name with.
+- **@voltro/cli** — `input/uncapped-array` is silent on `internal: true`, and `raw-fetch` is silent on a `fetch` an SDK asked for as an option.
+
+  Both rules were reporting a set their own sentence does not describe, and both were found by an app that read every remaining finding instead of filing them.
+
+  **`input/uncapped-array` says "the caller chooses how many".** `internal: true` takes a procedure off the wire, so there is no such caller — only the app's own code calling its own procedure. Measured on one codebase: after every wire procedure was bounded, 212 findings remained and ALL 212 were internal. So the rule spent its entire remaining output on the case its premise excludes, which is how a rule stops being read. `imperative-scope` has skipped `internal: true` for the same reason; this applies the existing decision rather than making a new one. A procedure on the wire is reported exactly as before, which is the half that keeps the exemption from being a hole.
+
+  **`raw-fetch` recommends `yield* HttpClient`.** Several provider factories take a `fetch`-shaped function as an option (`createGoogleGenerativeAI({ fetch })`). Inside it the URL is the SDK's, never a caller's, so the SSRF half has nothing to bite on — and the remedy is not available either: the seam requires a plain callback, so `yield* HttpClient` names an API that cannot be used at that call site. A rule whose only remedy does not apply teaches the reader to skim the line, which is the one place a genuinely caller-supplied URL would have been named.
+
+  The seam is SUBTRACTED, not exempted: only calls inside the function that is the value of a `fetch:` property are discounted, so a file that supplies such a seam AND calls `fetch` on its own account is still reported for the second one. Without that, adding one option object would switch the rule off for a file.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/database** — The migration lock is released by its bracket and nowhere else.
+
+  Correcting unreleased work in this same release, so no shipped behaviour changes: `applyPlan` gained an `Effect.acquireUseRelease` bracket and KEPT the `try { … } finally { yield* held.release }` it replaced. The overlap was documented as free — "releasing twice is harmless: the second `RELEASE_LOCK` finds nothing held on that connection".
+
+  That holds for `RELEASE_LOCK` and for `pg_advisory_unlock`. It is false for the third dialect: `sp_releaseapplock` RAISES on a lock the session does not hold, so every mssql apply died on the second release with `Cannot release the application lock … because it is not currently held`. A claim about three dialects, verified on two.
+
+  Removing it is also the better release POINT — the `finally` ran before the convergence proof, handing the lock back while the work it protects was still running. The bracket holds it to the end and covers failure, defect and interruption, which a `finally` inside `Effect.gen` does not.
+
+  `migrationLockIsBracketed.test.ts` asserted that an acquisition IS bracketed; it now also asserts there is exactly ONE release. Those are different claims and only the first was being made, which is how this rode through.
+
+---
+
 ## [0.68.0] — 2026-09-09
 
 ### ⚠ 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/plugin-ai-flows itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (69 packages).
+Generated from the resolved runtime dependency closure (66 packages).
 
 ---
 
@@ -29,26 +29,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 ```
 
-## @ai-sdk/gateway@4.0.74
-
-License: Apache-2.0
-
-```
-Copyright 2023 Vercel, Inc.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-```
-
 ## @ai-sdk/openai@4.0.58
 
 License: Apache-2.0
@@ -3636,214 +3616,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## @vercel/oidc@3.2.0
-
-License: Apache-2.0
-
-```
-Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2017 Vercel, Inc.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-```
-
 ## @workflow/serde@4.1.0
 
 License: Apache-2.0
@@ -3854,26 +3626,6 @@ Apache License 2.0
 See the LICENSE file in the root of this repository.
 ```
 
-## ai@7.0.92
-
-License: Apache-2.0
-
-```
-Copyright 2023 Vercel, Inc.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-```
-
 ## cluster-key-slot@1.1.1
 
 License: Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-ai-flows",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "AI Flows — durable multi-step AI pipelines (deterministic + agentic) with human-in-the-loop, chaining, and cadence. Author flows in code (defineFlow) or as data (visual editor rows); one engine runs both on @voltro/workflow durability, @voltro/ai generation, storage artifacts, and notifications.",
   "keywords": [
     "voltro",
@@ -58,16 +58,16 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/ai": "0.68.0",
-    "@voltro/client": "0.68.0",
-    "@voltro/database": "0.68.0",
-    "@voltro/env": "0.68.0",
-    "@voltro/plugin-audit": "0.68.0",
-    "@voltro/plugin-multitenancy": "0.68.0",
-    "@voltro/plugin-soft-delete": "0.68.0",
-    "@voltro/protocol": "0.68.0",
-    "@voltro/runtime": "0.68.0",
-    "@voltro/workflow": "0.68.0"
+    "@voltro/ai": "0.69.0",
+    "@voltro/client": "0.69.0",
+    "@voltro/database": "0.69.0",
+    "@voltro/env": "0.69.0",
+    "@voltro/plugin-audit": "0.69.0",
+    "@voltro/plugin-multitenancy": "0.69.0",
+    "@voltro/plugin-soft-delete": "0.69.0",
+    "@voltro/protocol": "0.69.0",
+    "@voltro/runtime": "0.69.0",
+    "@voltro/workflow": "0.69.0"
   },
   "peerDependencies": {
     "effect": "^3.22.1"