@voltro/protocol 0.64.0 → 0.65.0

package/CHANGELOG.md

@@ -39,6 +39,73 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.65.0] — 2026-09-04
+
+### ⚠ BREAKING
+
+- **@voltro/plugin-ai-flows** — `@voltro/plugin-ai-flows` declares `internal: true` on its `flow.run` workflow, so it no longer becomes a start rpc. Every start is server-side and always was: the plugin's own guarded procedures, the cadence tick, and `chainTo`'s `workflows.child`. There is no meaningful client start — the payload carries `runId`, the id of a row the caller must already have created.
+
+  Leaving the decision off was not a lax default. An app installs the plugin by re-exporting the descriptor from its own `flow.run.workflow.tsx`, which makes it one of the app's DISCOVERED workflows — exactly the set the boot gate judges — so under `security.defaultDeny` (on by default) the app's boot was REFUSED, naming a workflow the app had no way to decide about. A first-party descriptor must satisfy the framework's own gate, and a test now holds every workflow any first-party package ships to that.
+
+  Migration: start a flow through the plugin's guarded procedures. Server code is unaffected.
+
+  **`voltro update` carries you across this** — codemod `0.65.0/01_ai-flows-run-is-internal`. 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.65.0).
+- **@voltro/runtime, @voltro/protocol, @voltro/cli, @voltro/voltro** — `EffectStore` gains `one`, `maybeOne` and `first` — the same single-row reads `ctx.store` offers, taking a builder or a descriptor.
+
+  Their absence made two `voltro doctor` rules mutually unsatisfiable: `row-not-found` prescribes `.maybeOne(builder)`, `store-effect-lift` prescribes `yield* EffectStore`, and the Effect surface had no `.maybeOne`. Following both produced `Property 'maybeOne' does not exist on type 'EffectStoreOps'`. Nothing was hard about it — the object the service closes over has always been the full fluent store, and every call site was already casting to say so; only the declared type was narrower. `transactional` inherits the wider surface.
+
+  `one` fails with `NoRowFound` on its own channel rather than collapsing into `StoreOperationFailed`, for the reason the catch boundary already gives about `TenantRowNotFound`: stringifying a deliberate, catchable refusal is how it stops being one. There is no `onMissing` on the Effect surface — `Effect.catchTag('NoRowFound', …)` says the same thing and keeps the channel exact.
+
+  `NoRowFound` moves to `@voltro/protocol` (re-exported from `@voltro/runtime`, so nothing that imported it moves). The agent guide already said it was declarable in a descriptor's `error:` union, and a descriptor is browser-loaded while `@voltro/runtime` is on the browser-safety guard's server-only list — so following that sentence produced a refused boot. The package it sat in was the only thing making the guidance false.
+
+  **`voltro update` carries you across this** — codemod `0.65.0/02_effect-store-and-guard-unions`. 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.65.0).
+
+### Added
+
+- **@voltro/protocol, @voltro/runtime, @voltro/voltro** — `guards: [{ authenticated: true }]` — the access decision that says "the caller must have an identity", and nothing narrower.
+
+  It was the third case the vocabulary could not express, and every substitute was wrong in a different way. `{ scope: … }` refuses every real user in an app that issues no raw scopes, which is what authority resolved per team in the executor looks like. A relationship guard has no tuple to match on the first call, when the resource does not exist yet. And `openAccess` is untrue wherever the auth fallback is a deliberate anonymous subject — the honest reason would read "whoever can open the socket may spend our model budget". Apps were writing a resource policy whose entire content was "you are logged in".
+
+  `checkGuards` already distinguished this internally: its return type has always been `ScopeError | Unauthenticated | null`. The guard makes the distinction sayable. It ENFORCES, so it satisfies `security.defaultDeny` — unlike `openAccess`, which declares that nothing is checked — and it composes: every entry in `guards:` must pass.
+
+  Both enforcement loops carry it, the synchronous one and the Effect one that runs whenever a policy or resource-scoped guard is present. The approval serialiser stores it too: a variant it dropped would be an identity requirement that quietly stopped applying the moment a decision went through an approval.
+
+  The golden churn here is one member added to `AnyGuardSpec` / `AnyCheckSpec`. Nothing already written changes meaning; only a switch that is EXHAUSTIVE over the union needs an arm, and that case is carried by the manual codemod `0.65.0/02_effect-store-and-guard-unions` alongside the store-layer change it ships with.
+
+### Changed
+
+- **@voltro/cli** — Four `voltro doctor` corrections, each where the rule's premise was narrower than the code it read:
+
+  - `n-plus-one` follows a dependent chain through ORDINARY bindings. It compared the next read's text against the names earlier reads were DIRECTLY assigned to, so `const row = rows[0]` between two reads made the second look independent — and a finite chain whose next key comes out of the previous row was reported as an N+1 you are writing, which `Effect.all` cannot fix. - `input/uncapped-array` reads the `input:` expression alone, plus the schemas it names. It scanned the whole file, so a descriptor whose input holds no array and whose output returns `items: Schema.Array(Item)` was reported — and a `maxItems` on a RESPONSE bounds nothing a request can ask for. - `mutation/target-op-mismatch` treats `target: [...]` as the set of allowed ops per table. Comparing each declared target ALONE asked "does the executor do anything but insert", answered yes because delete was also declared, and reported a complete declaration. - `bulk-write-in-loop` recommends only APIs that exist. It named `insertManyIgnore` and `upsertMany`, neither of which the store has; `insertIgnore` and `upsert` resolve a conflict per row and have no set-based form, so the advice is now to keep the loop inside one transaction and bound the input.
+- **@voltro/cli** — `voltro update`'s codemod preview splits the count in the summary line: `6 in range for 0.63.0 → 0.64.0 — 6 print written steps for you to apply`. The per-entry markers were already there and the legend explained them, but both sit BELOW the count, so "6 codemods" formed the expectation of six automatic rewrites before the reader reached either. Six manual codemods is six pieces of hand work, and that is the number somebody schedules an afternoon around.
+
+### Fixed
+
+- **@voltro/cli** — `open-reason-unverified` had three defects that between them let it be silenced by rewording while missing the case it exists for:
+
+  - The reason literal was matched with one quote class that forbade every quote character INSIDE the string, so a reason naming its guard in backticks did not parse and the rule returned without opening the executor at all. - `can` is a framework guard name AND an ordinary English word, so any reason containing "anyone can call it" named a guard the executor did not have. A lowercase word now counts only when written as code — `can()` or in backticks. - The executor test was token PRESENCE, which the import line alone satisfies. It requires a CALL, the same shape the sibling rule already used.
+
+  `input/uncapped-array` covers `*.query.ts` as well. A read does not write, which is what the old wording was about, but that does not make it bounded: a hundred thousand ids in one `getByIds` is the caller choosing the size of the query, and the body limit bounds bytes rather than entries.
+
+  `store-effect-lift` names both preconditions its promise depends on — that a typed error only reaches the caller once the descriptor DECLARES it, and that the class comes from `@voltro/protocol`. Naming a benefit and neither precondition is how a rule earns a large diff with nothing observable at the end of it.
+- **@voltro/runtime** — An `.encrypted()` column written through `upsert` is bound to the row that RECEIVES it. On the conflict path that row is the existing one, whose id is not the id the caller offered, so the ciphertext went to disk authenticated against an id that row does not have — and AES-GCM then refused it: `FieldDecryptionError … Unsupported state or unable to authenticate data`.
+
+  The damage was not the failed call. The row keeps the mis-bound value, so every later read of it throws too, and the write reports success on the way in. The conflict is now resolved before the encrypt (`upsertDestinationId`, shared by both codec wrappers), which costs one extra read and only for a call that actually writes a secret.
+
+  It bites wherever the row carries an id at encrypt time — always on the memory store, and on every SQL dialect when the id is the caller's rather than the database's, since `EXCLUDED.<col>` / `VALUES(<col>)` / `MERGE` all carry the offered bytes onto the existing row.
+
+  `updateMany` through the BOOT store now refuses an `.encrypted()` column instead of writing a binding nothing can authenticate: a set-based write has no row, and the request-scoped store is the one that expands it per row.
+- **@voltro/cli** — `.framework/dist/server/` — the SSR bundle and the precompiled app config — is marked `{"type":"module"}` like the api and start bundles already were, so a production `voltro start` no longer opens with `MODULE_TYPELESS_PACKAGE_JSON` for an artefact the app did not write. All three directories go through one `writeEsmPackageMarker`, and a guard now asks every module that runs a bundler whether it marks what it wrote.
+- **@voltro/cli** — `voltro new workflow` scaffolds a descriptor that declares `internal: true`, with the three options in a comment above it. The template emitted no access decision at all, so the file it wrote refused the app's own boot under `security.defaultDeny` — a scaffold whose first act is to break the build.
+- **@voltro/database, @voltro/runtime, @voltro/protocol, @voltro/voltro** — `StoreOperationFailed.cause` no longer carries the driver's sentence or a stack trace. It was `String(error)` on a `FiberFailure`, which is the message AND the stack — so an absolute server path reached every caller that declared the error, and every subscriber on a stream carrying it.
+
+  The words were the worse half. `@voltro/database`'s own header already states why a driver message may not be forwarded: postgres attaches `Failing row contains (…)` — the entire row, `.sensitive()` columns included — to a not-null and a check violation, mysql echoes the duplicate value, mssql the truncated one. That rule was written for `ConstraintViolation` and the error beside it broke it.
+
+  `wireSafeCause` builds the field now: the constraint KIND and its constraint/column NAME, or the driver's code, and nothing that was ever a value. The full detail is logged server-side instead, so diagnosis is not traded away for the fix.
+- **@voltro/cli** — The inspect action behind the dashboard's workflow "resume" refuses a run that is not suspended, instead of reporting a resume that did not happen. The engine resumes only a run carrying a terminal `Suspended` reply; the action called it, ignored the answer, flipped the row to `running` and recorded a `run-resumed` event regardless. For a run already stuck in `running` — the state somebody presses that button in — every visible sign said it had worked, including a fabricated entry in the timeline of the run being investigated.
+
+---
+
 ## [0.64.0] — 2026-09-04
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -89,15 +89,15 @@ export declare interface AnyApprovalPolicy {
     readonly reason?: string;
 }
 
-/** A guard entry is a scope check, a relationship check, or a declared
- *  no-check-needed decision. */
-export declare type AnyCheckSpec = GuardCheckSpec | PolicyCheckSpec | OpenAccessSpec;
+/** A guard entry is a scope check, a relationship check, an identity check, or
+ *  a declared no-check-needed decision. */
+export declare type AnyCheckSpec = GuardCheckSpec | PolicyCheckSpec | AuthenticatedCheckSpec | OpenAccessSpec;
 
 /** Any declared event, with the generics erased — for registries and audits. */
 export declare type AnyEventDescriptor = EventDescriptor<string, Schema.Schema.Any, Schema.Schema.Any>;
 
-/** A guard is either a scope check or a relationship check. */
-export declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input>;
+/** A guard is a scope check, a relationship check, or an identity check. */
+export declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input> | AuthenticatedGuardSpec;
 
 export declare const APIKEY_ISSUE_ORG_SCOPE = "apikeys:issue:org";
 
@@ -460,6 +460,36 @@ export declare interface AuthCallbackRouter {
     readonly post: (path: string, handler: AuthRouteHandler) => void;
 }
 
+/**
+ * The runtime-erased form of `AuthenticatedGuardSpec` — "somebody must be
+ * there, and nothing narrower". See that type for why the vocabulary needed it.
+ */
+export declare interface AuthenticatedCheckSpec {
+    readonly authenticated: true;
+}
+
+/**
+ * "The caller must have an identity" — and nothing narrower.
+ *
+ * The third case the vocabulary was missing, and the gap was not theoretical.
+ * An app whose authority lives per-team in its executors holds NO raw scopes on
+ * the identity, so `{ scope }` refuses every real user; a relationship guard
+ * cannot help when the resource does not exist yet (the first message of a new
+ * thread); and `openAccess` would be a lie whenever the auth fallback is a
+ * deliberate anonymous subject. The one thing left to decide — is anybody
+ * there — had no spelling, so apps wrote a resource policy whose entire content
+ * was "you are logged in".
+ *
+ * `checkGuards` has always distinguished this internally: its return type is
+ * `ScopeError | Unauthenticated | null`. This makes the distinction sayable.
+ *
+ * It is a real DECISION, so it satisfies `security.defaultDeny` — unlike
+ * `openAccess`, it also enforces something.
+ */
+export declare interface AuthenticatedGuardSpec {
+    readonly authenticated: true;
+}
+
 /**
  * The framework's per-request auth middleware. Attach to an RpcGroup with
  * `group.middleware(AuthMiddleware)` to require every call to flow through
@@ -2488,6 +2518,12 @@ export declare interface InsertTarget<Input = unknown, Row = unknown, Item = Rec
     readonly shapeItem?: ((input: Input, optimisticId: string) => Item) | undefined;
 }
 
+/** Runtime narrowing for the identity variant. */
+export declare const isAuthenticatedCheck: (g: AnyCheckSpec) => g is AuthenticatedCheckSpec;
+
+/** Narrow a guard entry to the identity variant. */
+export declare const isAuthenticatedGuard: <I>(g: AnyGuardSpec<I>) => g is AuthenticatedGuardSpec;
+
 export declare const isEventDescriptor: (value: unknown) => value is AnyEventDescriptor;
 
 /** True when every row in the set carries an `id`. The dispatcher uses
@@ -2683,6 +2719,34 @@ export declare const normalizeDescriptor: (descriptor: ProcedureDescriptor) => C
  */
 export declare const normalizeSource: (source: ReactivitySource | ReadonlyArray<ReactivitySource> | undefined) => string | ReadonlyArray<string> | undefined;
 
+/**
+ * `.one()` matched a number of rows other than exactly one.
+ *
+ * `found` distinguishes the two failure modes without a second error type:
+ * `0` is "the row you required is missing", `2` is "your filter is not as
+ * unique as you assumed" (the terminal probes with LIMIT 2, so `2` means
+ * "at least two" — it never counts the whole set just to report a number).
+ *
+ * It lives HERE, not in `@voltro/runtime`, and the reason is a promise the
+ * framework was already making. The agent guide says "`NoRowFound` is
+ * declarable in the descriptor's `error:` union" — and a descriptor is loaded
+ * by the BROWSER, while `@voltro/runtime` is on the browser-safety guard's
+ * server-only list. So following that sentence produced a refused boot. The
+ * class is browser-safe by construction (a `Schema.TaggedError` over two
+ * scalars), so the package it sat in was the only thing making the guidance
+ * false. `@voltro/runtime` re-exports it, so nothing that imported it moves.
+ */
+export declare class NoRowFound extends NoRowFound_base {
+    get message(): string;
+}
+
+declare const NoRowFound_base: Schema.TaggedErrorClass<NoRowFound, "NoRowFound", {
+    readonly _tag: Schema.tag<"NoRowFound">;
+} & {
+    table: typeof Schema.String;
+    found: typeof Schema.Number;
+}>;
+
 /**
  * What a plugin contributes to the OTel layer via `contributeObservability`.
  * The OTel types are intentionally `unknown` so this browser-safe protocol
@@ -4632,7 +4696,12 @@ declare const StoreOperationFailed_base: Schema.TaggedErrorClass<StoreOperationF
     operation: typeof Schema.String;
     /** The table the op targeted. */
     table: typeof Schema.String;
-    /** `String(originalError)` — round-trip-safe diagnostic form. */
+    /**
+     * A BOUNDED description: the constraint kind and its constraint/column
+     * NAME, or the driver's code. Never the driver's sentence and never a
+     * stack — `wireSafeCause` builds it, and the reasoning is there. The full
+     * detail is logged server-side instead.
+     */
     cause: typeof Schema.String;
 }>;