@voltro/plugin-auth-clerk 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -39,6 +39,547 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.27.0] — 2026-08-05
+
+### Added
+
+- **@voltro/plugin-audit, @voltro/plugin-versioning** — `scope` — the app's own scoping dimension on `_voltro_audit_log` **and** `_voltro_row_history`, supplied by a `resolveScope` option on each plugin.
+
+  The last thing between a consumer and deleting a 2900-row, 300-call-site hand-rolled audit trail. Their trail and its retention are per-TEAM; a tenant has many teams, so `.with(tenant())` is one level too coarse and every view they render filters by team first. It is the same column `_voltro_webhook_targets.scope` already carries: opaque json in, opaque json out, equality filtering.
+
+  **Deliberately not `metadata`.** They offered to carry `teamId` there and filter in memory, and were right to dislike it: `metadata` is documented as the app's free-form note — the noun a diff cannot contain — so filtering on it builds a read path against a column whose contract says it is not one. Two columns, two jobs.
+
+  The app supplies the value, because the framework does not know what a team is — which is the whole reason the column is opaque. `auditPlugin` derives it from the call (`(ctx) => ({ teamId: ctx.subject.metadata?.teamId })`); `versioningPlugin` from the changed ROW (`(row) => ({ teamId: row.teamId })`), because that is what that plugin has and where a per-table dimension lives. Configure both or half of every view is unfiltered.
+
+  Neither resolver can fail the write it annotates: an underivable scope is `null`, the same answer as not configuring one.
+
+  codemod: none
+- **@voltro/plugin-notifications** — `notificationsPlugin({ resolveSubjectId })` — the app names its own addressing unit.
+
+  An inbox belonged to `subject.id`. That is the framework's answer and not always the app's: a shift change, an absence request or a task reminder is addressed to a PERSON, and a person does not necessarily have an auth user. A reporter measured it on 14 670 rows — 4 677 addressable through a user, and **668 live, read rows belonging to four people who have none**.
+
+  The worse half is what follows a migration without it: every producer resolves person → user and **silently delivers nothing** for anyone missing one. That is the failure this plugin's own docstring warns about, one level up and structural rather than accidental.
+
+  One function, thirteen call sites — the same seam `auth.resolveScopes` already offers for this shape. Absent keeps `subject.id`, so nothing changes for an app whose units line up. A resolver that returns `undefined`, an empty string, or throws falls back to the subject rather than failing the read: an inbox must not go down because one caller has no employee record, or because a lookup hit a database that was briefly unavailable.
+
+  **`useEvent` already returns what the same report asked for.** `{ status, missed, lastMiss }`, where `status === 'live'` is the connected flag — the ask was for discoverability, not an API, so the docs now name the case that motivated it: a wall display nobody is standing at keeps rendering the last thing it received, and from across the room stale and current look identical.
+
+  codemod: none
+- **@voltro/plugin-presence** — The presence tracker gets a perf suite — the last of the four realtime surfaces without pinned numbers — and the four are now documented side by side.
+
+  The presence figures existed in the docs (a heartbeat, a 10 k roster) and were measured once by hand, which cannot fail. Same gap the event bus had, closed the same way: a `*.perf.test.ts` that prints what it measured and asserts the SHAPE rather than the microseconds.
+
+  Measured across all four, each asserted by a test:
+
+  | primitive | operation | cost | scales with | | --- | --- | --- | --- | | Events | `ctx.events.publish` | 4.3 µs (~232 k/s) | nothing | | Events | delivery to a subscriber | 0.027 µs | subscribers, cheaply | | Presence | a heartbeat | 0.16 µs | nothing | | Presence | a roster read, 10 k members | 547 µs | the ROOM | | Records | a live-query re-diff, 5 000 rows | 3 062 µs | the RESULT SET | | Broadcast | cross-replica over real Redis | p50 1.1 ms · p99 11.2 ms | the network |
+
+  **The comparison is what was missing, not the numbers.** Publishing an event costs about a thousandth of re-diffing a large live query, and that ratio is what should decide between them — a 60 Hz value belongs in an event, because the same value written to a table wakes every subscriber of every query reading it and each pays the full walk.
+
+  Two of the four are flat and two are not. That is the property the tests assert: the per-member cost of a roster read must not grow with the room, and the per-row cost of a diff must not grow with the result set. Either one growing is the difference between expensive and unusable.
+
+  codemod: none
+- **@voltro/cli** — A capability matrix for the realtime surface — fifteen things people build, each mapped to the primitive that carries it, each asserted by a test.
+
+  "Nothing is missing" is not a checkable sentence. This turns it into one: `realtimeCapabilities.test.ts` asserts every row's primitive is still exported, so a capability that loses its primitive to a rename goes red in CI rather than being discovered by whoever tries to build it.
+
+  It caught one on its first run — the matrix claimed `useUpload` lived in `@voltro/plugin-storage` and it is in `@voltro/client`. A row pointing at the wrong package is exactly what a table in a document does silently.
+
+  It asserts EXPORTS rather than behaviour on purpose. Behaviour is what the other suites are for, and duplicating them here would make this a slower copy of them. What it catches is the gap between "we support that" and "the thing that supports it still exists".
+
+  The same table is in the docs, with the three capabilities people usually reach for wrongly called out: a value changing many times a second is an EVENT and not a row (writing it to a table wakes every subscriber of every query reading that table, each paying a full re-diff); "who is online" is presence rather than a table; and "did anything get lost" has a computed answer in `missed`, so nobody needs to build a heartbeat of their own to find out.
+
+  codemod: none
+- **@voltro/cli** — The ten hard questions a realtime system is judged on, with this framework's answer and — enforced by a test — the proof behind each.
+
+  `realtimeProperties.test.ts` fails if a row's proof disappears: a property may not be CLAIMED without something in the repository that demonstrates it. Red-verified by re-pointing one row at a test that does not exist.
+
+  The questions, because they are the deliverable rather than the mechanism: is a missed delivery reported or silently dropped; can a late arrival tell "nothing happened" from "I was not listening"; is a SUBSCRIPTION authorized or only the connection; does a subscription outlive its credential; does the link heal itself after an outage; does a degraded network lose messages or only slow them; does fan-out cost grow with subscribers; are channels typed or strings; is a declared event nobody publishes reported; is cross-replica traffic separated per app by default.
+
+  **Why this replaces a benchmark against hosted competitors.** A table of our measured numbers beside someone else's published ones is not a comparison, it is two things in a row. Measuring a hosted product honestly needs its accounts, regions, tiers and retry policies, and a wrong number about someone else's product is worse than no number. What decides a choice is not the microseconds anyway — it is whether the system answers these questions at all, and every answer above is checkable against this repository by anyone.
+
+  codemod: none
+- **@voltro/cli** — A real competitive measurement — against socket.io, on this machine, in the same topology.
+
+  This was declined twice on the grounds that a benchmark needs the competitor's accounts and regions. That reasoning holds for hosted products and **does not hold for socket.io**, which is an npm package: it can be installed, run and measured here with the same method. Declining it was over-broad.
+
+  Back to back, two server instances sharing one Redis, client on B, emits on A:
+
+  | | p50 | p99 | delivered | | --- | --- | --- | --- | | Voltro cross-replica | **1.29 ms** | 6.80 ms | 200/200 | | socket.io + redis-adapter | 1.89 ms | **3.81 ms** | 200/200 |
+
+  **~32% faster at the median, ~44% worse at the tail.** Both lossless. The p99 is ours to improve and is published rather than omitted, because a benchmark you only show when you win is advertising.
+
+  **The topology is what makes it a comparison.** The first attempt measured socket.io on a plain localhost websocket with no adapter and came out 3x faster — which proved nothing: that is one hop, ours is two through a broker. It would have flattered socket.io and been dishonest in their favour, which is the same defect as flattering ourselves.
+
+  Also measured and NOT published as a headline: socket.io's `emit` to 100 subscribers costs 13.7 µs against our 2.7 µs, but at that point ours has already run every listener while socket.io has only enqueued to 100 sockets — zero had arrived when the measurement ended. Two different quantities; comparing them would have been the same mistake in the other direction.
+
+  `scripts/bench/socketio-cross-replica.mjs` carries the method and the numbers so they can be re-taken. Deliberately a script, not a test: keeping a competitor in the dependency tree to hold a number green is the wrong trade.
+
+  codemod: none
+- **@voltro/plugin-webhooks** — **A subscription is a SET of events, and the service now has a word for it.**
+
+  `subscribe({ events: [...] })` creates the rows in one call; a `{ scope }` selector addresses them as a group wherever a target id is accepted — `pauseTarget`, `resumeTarget`, `updateTarget`, `deleteTarget`, `rotateSecret`, `listDeliveries`.
+
+  A row is one event, but a subscription — as every webhook UI models it, ours included — is one URL with a list of event checkboxes. Without a name for the group, five checkboxes are five rows and every operation a user thinks of as single becomes a fan-out the app writes by hand: N pauses, N updates, N delivery reads merged and re-sorted, and a rotate that is delete + re-subscribe.
+
+  **The shared secret is why this is correctness and not ergonomics.** The receiver verifies ONE signature for ONE url, so N rows for one endpoint must sign identically — and there was no way to say so. `subscribe` mints a secret per call, `SubscribeResult` surfaces it once, `TargetPatch` cannot set it. So ticking a sixth event meant reading the secret column back out of `_voltro_webhook_targets` through the app's own database handle. That is exactly the coupling `listDeliveries` was added to remove, re-entered through a different door one release later.
+
+  `subscribe` now mints one secret for the whole set, and `rotateSecret({ scope })` rotates every row to the same new value — which also replaces the delete-and-re-subscribe that minted new target ids and orphaned the delivery history.
+
+  **`secret` is deliberately still not patchable.** Adding it to `TargetPatch` would close the same gap by making a live credential app-writable, trading a coupling for a weaker invariant. The reporter proposed the constraint and declined that shortcut themselves.
+
+  A scope matching no row is an error rather than a no-op: "pause the endpoint" that pauses nothing and reports success is the silent shape this selector exists to avoid.
+
+  codemod: none
+
+### Fixed
+
+- **@voltro/cli** — Cross-replica delivery is now tested over a network that is not loopback.
+
+  This closes the one item repeatedly written off as needing external infrastructure — "two real pods over a real network". That was the wrong variable. What a loopback number cannot show is a path with LATENCY, JITTER and a bandwidth ceiling, and injecting those is not only possible in the test stack, it is BETTER than a real network for a test: reproducible, and degradable on purpose.
+
+  `toxiproxy-test` joins `test/docker-compose.yml` as a degradable path to `redis-test`. Measured through it:
+
+  | condition | p50 | p99 | delivered | | --- | --- | --- | --- | | 20 ms ± 10 jitter | 26 ms | 89 ms | 200/200 | | + a 50 KB/s ceiling | 188 ms | 354 ms | 200/200 |
+
+  Seven times slower at the median under the second, and not one envelope lost. That is the property the new suite asserts: **degradation costs latency, never messages.**
+
+  The latency BUDGET is deliberately left in the healthy-path suite. Asserting it here would produce a test that goes red when the network is bad rather than when the code is — and the second row above is exactly that case.
+
+  codemod: none
+- **@voltro/plugin-audit, @voltro/cli, @voltro/runtime** — **`@voltro/plugin-audit` could not boot — a release blocker, reported within a day.** 0.26.0 attached `interceptAction` and `interceptQuery` and declared neither scope, so the boot permission audit (`level: fatal`) refused to start EVERY app carrying the plugin, whether or not it had opted into query auditing. The audit inspects the presence of a hook, not what it does, so the identity passthrough counted.
+
+  The manifest declares both now — and `interceptQuery` is **attached** only when `recordQueries` is on, with its scope declared conditionally the way `store:write` already is. That is the reporter's suggestion and it is the better half of the fix: listing the scope unconditionally clears the boot while making every deployment DECLARE that it intercepts queries when almost none do, and a permission manifest is worth reading only if it describes what the plugin actually touches.
+
+  Their diagnosis of why it escaped is what the guard is built from: *a plugin's own test suite exercises the plugin, not a boot with the plugin installed*. The same shape as the `gc-snapshots` dialect bug one round earlier — the check that would have caught it is the one nobody ran on the affected path. There is now a test over the WHOLE `packages/plugin-*` set asserting that every hook a plugin ships has its scope named in its source, red-verified by reproducing 0.26.0.
+
+  **The stale-`source:` warning fired on the framework's own tables.** It resolved against the app's discovered entities, so every table the framework contributes conditionally — `_voltro_agent_messages` / `_voltro_agent_threads` behind a `*.agent.tsx`, and every plugin's `extendSchema.tables` — read as missing. The reporter got two warnings on every boot, for two sources that were correct, about a table the framework itself had created.
+
+  Their argument for why that is worse than cosmetic is the one that shaped the fix: this warning exists because a stale `source` is otherwise silent, so its entire value is being trusted. Firing on correct rows teaches the reader it is noise, and the next real one arrives into a warning nobody reads.
+
+  It resolves against the full live set now — app entities + plugin `extendSchema.tables` + framework tables, the same set auto-migrate emits DDL for — which means it runs after that set is assembled rather than inside `loadDiscovered`. Both boot paths do it, pinned by an ordering test.
+
+  codemod: none
+- **@voltro/plugin-broadcast, @voltro/cli** — The broadcast namespace is normalised silently, and the silence reintroduces the hazard the namespace removes.
+
+  Found by probing the broadcast surface the way the events and records surfaces were probed. `broadcastPlugin` accepted all nine bad shapes tried — whitespace, a bare `>`, a trailing dot, an empty string, no options at all — and the sanitiser handles every one of them correctly. **No declaration-time refusal is warranted, and that is the finding**, not a gap.
+
+  What the probe surfaced is one step on: `my app` and `my.app` BOTH resolve to `my-app`. Two deployments configured DIFFERENTLY therefore share a channel, which is precisely what this option exists to prevent — arrived at by way of the option itself. The docs already say that staging and production of one app share a name and only this variable separates them, which is exactly the case where someone types two values believing they differ.
+
+  Nothing refuses: the resolved value is broker-safe either way, and failing a boot over a dot would be worse than the collapse. Both boot paths log the substitution when it changes what was written, and the message names the COLLAPSE rather than only the substitution — the substitution alone reads as cosmetic. Silent when the value survives unchanged, and silent for the derived app-name default, which is not something an operator can act on.
+
+  codemod: none
+- **@voltro/plugin-broadcast, @voltro/cli** — **`broadcastPlugin()` with `REDIS_URL` set no longer stays silently on `memory`.** `REDIS_URL` counted for RESOLUTION but not for INFERENCE — it took an explicit `connection` option to be considered — so the plugin fell through to the in-process bus while the branch that would have read the variable sat directly below. Two doc strings promised the fallback ("inferred from … `REDIS_URL`", "falls back to `REDIS_URL`").
+
+  The asymmetry is what made it expensive rather than merely wrong: cache, kv and ratelimit all follow `<NAME>_REDIS_URL` → `REDIS_URL`, so an operator sets one variable, reads `cache backend resolved: redis` in the boot log, and concludes the bus did the same. A reporter did exactly that, on a single-replica deployment where the difference is unobservable — it appears on scale-up, as "some screens miss some events".
+
+  The caution the opt-in encoded is obsolete: every channel now carries the app-derived namespace, so attaching to a shared server no longer means two apps read each other's traffic. The test that pinned the old decision is reversed with that reasoning in it rather than deleted.
+
+  **The producer scan sees a locally bound publisher.** `\.publish\s*\(` misses
+
+  const publish = ctx.publish if (publish === undefined) return await publish(descriptor, {}, payload)
+
+  — which is not a corner case but the shape a handler writes when it guards the optional publisher. A reporter spent a quarter hour hunting for a missing publish they had just written, because the warning said their working event was dead. A false negative here is a missed warning; a false POSITIVE is a warning that lies about working code, and that is the expensive direction.
+
+  A bare `publish(` now counts, but only in a file that mentions `ctx.publish` or `ctx.events` — `publish` is too common a name to accept unqualified, and the qualifier also covers the `async ({ publish })` destructuring the dotted form misses for the same reason. Both directions tested.
+
+  codemod: none
+- **@voltro/plugin-broadcast** — `broadcastPlugin` refuses a request it cannot honour instead of downgrading it silently.
+
+  Probed the way the events, records and presence surfaces were: five plausible mistakes, **five accepted**, and every one produced the same outcome — the in-process memory bus with a successful boot.
+
+  | written | got | said | | --- | --- | --- | | `provider: 'redes'` (typo) | memory | nothing | | `url: 'http://x'` | memory | nothing | | `url: ''` | memory | nothing | | `provider: 'redis'`, no url anywhere | memory | nothing |
+
+  On one replica each of these is indistinguishable from working. They appear on the second, as "some screens miss some events" — which is the report that led here, and it cost a consumer a deployment.
+
+  The asymmetry that decides it: **an app that configures nothing has taken a default, and memory is the honest answer. An app that writes `provider: 'redis'` has stated a requirement**, and answering a requirement with a downgrade is the shape removed everywhere else in this codebase.
+
+  So configuring nothing still takes memory, an explicit `provider: 'memory'` is still honoured — saying it out loud must not be worse than saying nothing — and a bare redis url still resolves without naming the provider. What throws is only the case where the request cannot be met: an unknown name (listing the valid ones, so the fix does not need the docs), a url whose scheme names no provider, and a named provider with no url anywhere (naming the variables that would satisfy it).
+
+  Red-verified: with the refusal removed, the two tests that assert it go red.
+
+  codemod: none
+- **@voltro/cli** — Cross-replica delivery is now tested across a broker OUTAGE, not only a healthy or a degraded link.
+
+  The suites here proved delivery on a working link, and one proved it on a throttled one. None broke the link. That is the failure an operator actually meets — a redis restart, a failover, a partition that heals — and it was the last untested shape in the realtime stack.
+
+  **The property asserted is recovery, not delivery.** A broker that is down cannot carry messages, and claiming otherwise would be exactly the sort of guarantee this repo keeps removing. What must hold is that the link heals BY ITSELF: after the outage, delivery resumes with no process restart, no app-side retry and no resubscribe. A subscriber that silently stays dead after a blip is the worst realtime failure there is, because the screen keeps rendering and nothing reports it.
+
+  The test proves the link worked BEFORE it breaks it, so a zero at the end cannot be blamed on a link that never worked. Red-verified: leaving the proxy disabled gives 0 recovered deliveries instead of 10.
+
+  Also probed, and correct as found: a throwing listener does not kill the publish, does not stop its healthy siblings receiving, and does not leave the bus unusable afterwards. The 5 MB payload the bus accepts is fine — the size gate sits at the public seam (`ctx.events.publish`) and measures the ENCODED wire form, which is the representation that can actually be rejected downstream.
+
+  codemod: none
+- **@voltro/protocol, @voltro/runtime, @voltro/cli** — **The credential bound covered one auth shape and the sentence did not say so.**
+
+  We wrote that "an event subscription can no longer outlive the credential that authorized it" and, a release later, that "the bound now covers EVERY realtime primitive". Both were true only for the `voltro:session` cookie: `sessionExpiryFromHeaders` read that cookie and nothing else, so for an app authenticating with Bearer JWTs the bound was always `undefined` — a no-op that reads as a guarantee.
+
+  A reporter found it by expecting black screens an hour after a deploy and getting none. Their framing is the one to keep: **the guarantee was not false, it was scoped to an auth shape the sentence did not name** — and we had corrected a different sentence in the same release for exactly that reason.
+
+  There was also no seam to close it with. `StrategyResolution` was `{ matched, subject }`, so the strategy — the only place in the system that verified the token and holds its `exp` — could not report it.
+
+  It can now: `{ kind: 'matched', subject, credentialExpiresAt? }`, optional, with absent still meaning no bound. The shared JWT strategy reports its verified `exp`, which covers all six catalog providers (auth0, clerk, kinde, oidc, supabase, workos) in one place rather than six near-identical lines that drift.
+
+  The expiry rides WITH the subject through the chain and is recorded on the per-connection channel that already carries subject overrides, so `ConnectionInfo` reads it instead of re-deriving from headers. Two sites deriving one fact is what let the cookie path and the bearer path disagree. Both boot paths do it, in the same change.
+
+  Tested for both shapes — including that `resolveScopes`, which rebuilds the subject, does not drop it. That would have reopened the hole for every app using the seam we point people at for this kind of augmentation.
+
+  codemod: none
+- **@voltro/cli** — **Records and presence are now PROVEN cross-replica, not asserted.**
+
+  Asking one question across the whole surface — *which primitive is proven cross-replica against a real broker?* — gave an answer no amount of bug-fixing had:
+
+  | primitive | before | | --- | --- | | events | seven suites: partition, broker outage, degraded network | | records | **none** | | presence | **none** — zero broker use in all three of its suites |
+
+  "Multi-replica works" was proven for events and asserted for the other two, and they run through different code: events go bus → bridge → subscriber, records go `store.onChange` → broadcast → the peer's `injectExternalChange` → dispatcher → subscription. Only one had been driven end to end.
+
+  **Presence** now proves what a consumer had to measure by hand with `redis-cli PUBSUB NUMSUB` because the framework was telling them the opposite: a member tracked on A appears in B's roster, opaque `meta` survives the hop, and a leave on A removes it from B. A roster that only ever GROWS across instances is the failure that looks like success.
+
+  **Records** cost three wrong attempts, and the reason is worth more than the test. Two independent in-memory stores cannot model this: `injectExternalChange` NOTIFIES without persisting — deliberately, because replicas share a DATABASE and the peer re-reads storage they have in common. With separate stores the notification arrives (measured: called exactly once) and the re-read finds nothing, so no delta is emitted. Correct behaviour against an incorrect topology — and reported as a defect it would have sent someone hunting the bus for a bug that is not there. The suite runs one postgres, two stores, two dispatchers.
+
+  Two harness errors along the way are recorded in the files rather than quietly fixed: `tracker.track()` alone is a LOCAL write (the route calls `announce(track(...))`), and a predicate literal is `{ column, op, value }` — using `kind` instead of `op` matched nothing, so the missing delta was correct. Both would have been reported as framework defects.
+
+  codemod: none
+- **@voltro/cli** — The `no-consumer` half of the event audit sees sibling apps.
+
+  It read the API app's own tree, and in a monorepo the `useEvent` calls are not there — they are in the web apps beside it. A reporter had ten declared events, all ten consumed, all ten calls in ONE file in a sibling app, and got ten `no-consumer` warnings. A check that is wrong ten times out of ten carries no signal, and they ranked the two halves themselves: the producer half found them a dead trigger node that had not fired since a migration; the consumer half found nothing and spent the attention the producer half needed.
+
+  The siblings are not guessed from directory layout. `pnpm-workspace.yaml` declares them, so this reads what the workspace already says — a project outside a workspace costs nothing, which is the common single-app case.
+
+  Bounded at 4000 files, and LOUDLY: hitting the bound logs that a `no-consumer` line below may mean "we stopped looking" rather than "nothing consumes it". A silently truncated scan is the same false confidence one layer down, which is the defect this whole audit exists to remove.
+
+  codemod: none
+- **@voltro/protocol** — `defineEvent` refuses four authoring mistakes it used to accept.
+
+  Found by probing what it lets through rather than by reading it: nine plausible mistakes were tried, nine were accepted. The surface had exactly two refusals, one of which (`latest` + `webhook`) is a model for the rest.
+
+  **Whitespace in a name is the severe one — a production-only silence.** The name becomes a broker SUBJECT segment, and NATS refuses a subject containing whitespace and delivers nothing, with no error on the publishing side. An app that works on Redis stops working when the transport changes: silently, on one broker only. Refused at declaration, where the author can still see the string, and the message names the dot form to use instead.
+
+  **`guards: []`** is refused because the enforcement in `bindEvent` runs only for a non-empty list — so it reads at the call site as if the event were protected and secures nothing. That is the declared-and-inert shape this codebase keeps finding; an omitted field is the honest spelling for unguarded.
+
+  **`webhook.rateLimit.perMinute: 0`** defers every delivery forever, and there is no "unlimited" spelling for the field, so 0 is almost always someone reaching for one. **`webhook.version: 0`** would make a subscriber pinned to 1 read the event as *behind* — the opposite of what a version bump means.
+
+  Each message says what is wrong, why, and what to write instead; a test asserts that every refusal is more than one line, because a message that only names the rule leaves the reader guessing at the reason, and the reason is usually what they needed.
+
+  codemod: none
+- **@voltro/database, @voltro/runtime, @voltro/cli, @voltro/plugin-presence** — **`pluginRef` declarations survive `table()` and are readable as `table.appliedPluginRefs`.** They did not, and the consequence reached further than the reporter could see.
+
+  `pluginRefSpecOf` reads a column BUILDER; `table()` materialises builders into plain field descriptors. So the declaration vanished the instant the table existed, and the column read as an ordinary `text()`.
+
+  A consumer's CRUD generator and their contract test both derive "which column carries the tenant" from the schema, both asked `type === 'reference'`, and a `pluginRef` column answered no — so generated junction handlers dropped the tenant sub-query and a favourite could point at another tenant's row. Their test missed it for the same reason the generator did: **a checker sharing the assumption of the thing it checks.** They caught it only because they happened to teach discovery about `pluginRef` before the generator; the other order ships the regression.
+
+  **On our side it was worse and they could not have known.** The framework's own orphan-rule collector walked the column bag asking `pluginRefSpecOf`, got `undefined` every time, and produced ZERO rules on every real schema — so `orphanPolicy: 'delete'` did nothing, for the second release running. Its wiring test stayed green because it asserted the collector was CALLED, never that it returned anything.
+
+  A test against a real `table()` then found a THIRD defect immediately: the collector read `spec.target().name`, and a table's property is `tableName`, so every target resolved to undefined and the boot refusal fired for every `pluginRef`. The fixtures returned `{ name }` — confirming the wrong assumption rather than testing it.
+
+  That confusion had spread. The stale-`source:` resolver in BOTH boot paths built its table set the same way, producing an empty set — and `unresolvedSources` returns nothing for an empty set by design, so the warning silently stopped firing. **The fix for one false positive had turned the other into silence.** A narrow source guard now catches the shape; its own first run flagged a correct workflow read, which is recorded in the file, because a guard that opens with a false positive gets muted.
+
+  **The presence broker warning fires after the bus attaches.** It ran at plugin activation, and the broadcast bus attaches later — the reporter measured 634 ms, then confirmed with `PUBSUB NUMSUB` that presence was cross-instance while the log said otherwise. The check is deferred and re-reads the transport at fire time. This exact warning had just found them a real misconfiguration and then kept reporting the fault after the repair, which is how a warning spends the credibility it earned.
+
+  codemod: none
+- **@voltro/plugin-presence** — `presencePlugin` refuses a `timeoutMs` that expires members between heartbeats.
+
+  The presence surface, probed the way events, records and broadcast were: five plausible mistakes tried, five accepted. Zero and a negative are the obvious two; the one worth the rule is a value SMALLER than the client's heartbeat, because that is the mistake with a plausible motive ("expire people quickly") and a silent failure.
+
+  `timeoutMs` is one half of a contract whose other half lives in the client. A member is online for `timeoutMs` after its last heartbeat, and `usePresence` beats every 15s by default. Below that, every member expires between beats — the roster flaps empty and nothing reports it, because an empty roster is also what "nobody is here" looks like.
+
+  A consumer wrote that pairing down themselves ("our 10s heartbeat is the other half of the contract"), which is evidence the rule is real AND that it was left to the reader to work out. It is stated in both languages now, and the message names the CLIENT side, since a message naming only the server value sends the reader looking for the number in another package.
+
+  A long window is still fine — a signage terminal beating once a minute is a real deployment. The rule is a floor, not a range.
+
+  codemod: none
+- **@voltro/protocol** — `defineQuery` refuses three contradictions it used to accept — the same probe that found four on `defineEvent`, run against the records surface.
+
+  That symmetry is the point rather than a coincidence. `guards: []` was refused on events an hour after it was accepted on queries, and a rule that holds for one primitive and not another is worse than no rule: the framework's answer then depends on which file the author happened to open.
+
+  - **`guards: []`** reads at the call site as if the procedure were protected and enforces nothing — the check runs only for a non-empty list. - **An empty `source`** (`''`, `[]`, or a blank entry) declares reactivity and subscribes to nothing: one snapshot, never an update, indistinguishable from "nothing changed". It is worse than a STALE source, which the boot warning can at least name — this one names no table at all, so nothing can report it. - **`internal: true` + `overridesPlugin`** removes the plugin's route and puts something not wire-reachable in its place, so callers get a 404 for something that used to work with no diff that says so. It extends the existing `assertWireSurfaceConsistent` contract rather than adding a second rule beside it.
+
+  Also settled, by reading the runtime rather than declining again: **`rewind` needs no rule.** It replays the pruned ring on attach — with `each` that is "catch up on what you missed", with `latest` it is "here is the current value". Both are meaningful, so the combination that looked suspicious is fine, and a test now pins that decision so the next reader does not re-open it.
+
+  codemod: none
+- **@voltro/cli** — The one multi-replica scenario with no test: a replica that goes away, misses traffic, and comes back. The existing suites prove two replicas REACH each other, not what happens when one stops being able to.
+
+  It covers both directions of the claim that `missed` is COMPUTED and never estimated. **Under-reporting** is the silence this primitive exists to remove. **Over-reporting** is the freshly-started replica announcing a loss for messages it was never owed — measured once at 5000, and the reason every delivery carries `prior`.
+
+  The accounting identity is the assertion: every envelope owed after the resume point is either replayed or reported, and the two must sum to what was owed.
+
+  **The first version of that test was vacuous, and the reason is worth recording because it is the fourth instance this session.** It published six envelopes into the default ring of 64, so the ring held everything, `missed` was always 0, and the identity was true by arithmetic for any implementation at all — sabotaging the computation to under-report by one left it green. The ring is now deliberately SMALLER than the traffic (`ringSize: 3`, ten publishes), the non-vacuity assertions come FIRST, and the same sabotage now fails it 8-to-9.
+
+  `describeIfReachable`, verified both ways: with `REDIS_PORT=1` it reports two named skips rather than returning green having tested nothing.
+
+  codemod: none
+- **@voltro/runtime** — A resume replay could be **overtaken** by live traffic, delivering serials out of order.
+
+  Found by testing the case a busy app produces and the reconnect tests do not: a backlog being replayed at the same moment new envelopes are accepted, because a real reconnect does not pause the publisher. Measured — resuming from `n=3` over a ring of 8, with an ordinary re-entrant publish from the listener at `n=6`, delivered `[4, 5, 6, 9, 7, 8]`.
+
+  The cause is an ordering that is right for a different reason. The listener is registered BEFORE the replay on purpose: it closes the window between reading the ring and going live, so nothing published in between is lost. What it does not do on its own is keep the two streams in sequence — a live delivery reaches the listener immediately and jumps ahead of the entries still queued behind it.
+
+  Out-of-order is worse than loss for anything that folds state: a display applying an older frame after a newer one shows the past and stays there. And `n` arriving non-monotonically undermines the serial every gap number is computed from.
+
+  Live deliveries are now buffered for the duration of the replay and flushed after it, in arrival order, synchronously before `subscribe` returns — an async flush would reopen the window the early registration exists to close. Both properties hold: nothing is missed, and nothing overtakes.
+
+  The new tests also pin two things the quiet reconnect case cannot see: no serial is delivered twice when an envelope is in the ring at the moment of attach, and traffic arriving during a replay is not reported as a gap.
+
+  codemod: none
+- **@voltro/cli** — The socket.io comparison published one run per side. Both its numbers were noise, and it is corrected here with five runs each.
+
+  | | p50 median | p50 range | p99 median | p99 range | | --- | --- | --- | --- | --- | | Voltro cross-replica | **0.68 ms** | 0.58–0.86 | 7.01 ms | 4.50–13.36 | | socket.io + redis-adapter | 1.31 ms | 1.16–1.73 | **4.52 ms** | 4.33–7.83 |
+
+  The earlier table claimed "32% faster at the median, 44% worse at the tail". The median advantage is nearer **2x** — the p50 ranges do not overlap at all — and the tail gap sits INSIDE the overlap, so it is weaker evidence than a single pair of numbers made it look.
+
+  **A single measurement presented as a fact is the defect this framework spends its time removing, and it was committed in its own benchmark.** The correction is the finding.
+
+  **Where the tail comes from, measured rather than guessed.** Splitting the publish path: our own code — building the envelope, the Effect fiber per message, the handoff — costs p50 **0.056 ms** / p99 **0.444 ms**. Waiting for Redis to acknowledge costs p50 1.17 ms / p99 6.43 ms.
+
+  So roughly 0.4 ms of a 7 ms tail is ours and the rest is the broker round-trip, which socket.io pays too. The `Effect.runPromise` per message was the leading hypothesis and the measurement cleared it. There is no code-level tail defect to fix — on this machine the number is dominated by Docker's network stack.
+
+  codemod: none
+
+---
+
+## [0.26.0] — 2026-08-04
+
+### ⚠ BREAKING
+
+- **@voltro/protocol, @voltro/plugin-webhooks, @voltro/cli** — `defineEvent({ webhook: { retry } })` is removed. It never did anything.
+
+  The field was typed, documented as "default retry policy for new subscriptions", and read by nothing — `grep` for `spec.retry` across the repo returned no hits. Setting it produced no error, no warning and no effect: the value was dropped where an event descriptor is projected into an outgoing webhook descriptor, and a comment there explained why (the plugin's `RetryPolicy` is a richer shape than the two numbers the protocol carried, so forwarding it blind would install a policy nobody wrote). A test pinned that dropping as correct.
+
+  The reasoning was sound and the result was still wrong, because none of it reached the user: they wrote a typed option and got silence. This is the third instance of that exact shape in this feature — `broadcast({ channel })` was declared, named in its own doc comment as the multi-deployment answer, and forwarded by nothing; an event's `guards` were accepted, serialised into the manifest, reported by doctor and counted in the devtools panel while nothing enforced them. Two were found by consumers. This one was found by walking the option surface and asking, per field, who reads it.
+
+  Retry belongs on the SUBSCRIPTION, where the full `RetryPolicy` shape is available and typed. If you set it on the event, delete it — nothing changes at runtime, because nothing was reading it.
+
+  **The guard that exists for this class did not catch it, and that is the more important half.** `declaredOptionsEnforced.test.ts` checks a hand-maintained list of options; it can only re-verify the ones somebody remembered to add, and it covers no nested field at all. It was green throughout. Deriving that list from the type rather than curating it is filed as follow-up — the same lesson as `procedureWireReachability.test.ts`, which was satisfied at every site it knew about while the defect sat at a site it did not consider one.
+- **@voltro/workflow** — The `retry:` field on a workflow `step({...})` is now **ENFORCED**, not dashboard metadata. The framework compiles the declared policy to an Effect `Schedule` and retries `execute` accordingly — so `step({ retry: { maxAttempts: 5 } })` actually retries five times, no hand-written `Effect.retry` needed.
+
+  It became a real, innovative policy while it was at it — the conditions you actually want, default-correct:
+
+  - **Error classification** — `retryableErrors: ['ProviderDown', 'RateLimited']` (retry only these typed-error `_tag`s; everything else fails fast) or `retryable: (error) => boolean`. Retry the transient, fail the permanent. - **A time BUDGET, not just a count** — `maxElapsed: '5 minutes'` stops retrying once that much wall-clock has elapsed, even if attempts remain. A deadline. - **Jitter** — `jitter` (ON by default) spreads retries so a fleet doesn't re-hit a recovering dependency in lockstep. - **Capped backoff** — `maxDelay` ceilings exponential growth; `strategy` (`exponential` / `fixed` / `linear`), `baseDelay`, `factor`, `step`. - **Provider-driven backoff** — `respectRetryAfter` honors a `retryAfterMillis` / `retryAfter` hint on the error as a floor (a 429 `Retry-After`).
+
+  Retries run inside the one step and are transparent to the durable engine; the step's final outcome is recorded, and the serialisable knobs still feed the dashboard. `stepModule.retry(…, Schedule)` remains for full hand-written `Schedule` control.
+
+  **BREAKING, and check the first half before the second.**
+
+  **A step that declared `retry:` and nothing else ran ONCE. It now runs up to `maxAttempts` times.** In 0.25.0 the field's own type said so — *"Pure metadata — does NOT change retry behavior on its own"* — so trusting it was correct. If `execute` is not idempotent (a charge, an email, an outbound POST), that is real duplicate work beginning on this upgrade, with nothing in your code changed to cause it. Per step: make the effect idempotent, or set `maxAttempts: 1`, or narrow with `retryableErrors: [...]` so only transient failures retry.
+
+  The second half is the one you can see in your own source: the old docs told you to ALSO wrap the step in `stepModule.retry` / `Effect.retry`, and a step that did both now retries TWICE. Keep the declarative `retry:` (it also drives the dashboard) and drop the redundant wrapper — or, if your hand-written `Schedule` did something the policy can't express, keep it and drop `retry:` from that step.
+
+  `codemod: 0.26.0/02_step-retry-enforced` (manual) prints both, and fires for any project declaring `retry:` on a step — not only those with a manual wrapper.
+
+### Added
+
+- **@voltro/plugin-audit, @voltro/plugin-versioning** — **The audit trail can name its own actor, and it covers more than mutations.**
+
+  *B1 — the actor is a snapshot now, not a reference.* The argument that decides this lives inside ONE row: `_voltro_row_history.data` is a full-row snapshot, deliberately, so it survives what happens to its source — while the same row's `changedBy` is a foreign key that does not. One record, two philosophies: the row's state preserved forever, its author only until someone exercises a right to be forgotten.
+
+  That right is one we grant. `@voltro/plugin-governance`'s `governance.erase` (`delete | anonymize`) is ours and recommended, so a deployment can install auditPlugin + versioningPlugin + governancePlugin and have the third render the first two unreadable for precisely the subjects an investigation is about. Anonymisation is the worse half because it looks like it worked: the join SUCCEEDS and returns "Anonymised" for every entry that actor ever produced, retroactively rewriting history that was correct when written. A rename does the same, silently.
+
+  Both tables gain `actor json {id,type,displayName,email}`, resolved from the `actors` row at WRITE time — the moment the identity is still true. `email` is read opportunistically, because the framework's own columns are `id`/`kind`/`displayName` and apps commonly extend it; insisting on a fixed shape would make the field useless where it is needed most. Resolution is best-effort and never fails the mutation it records, and absent stays absent — a fabricated placeholder is the thing this column exists to prevent.
+
+  `_voltro_audit_log` also gains `metadata json` the app writes: the noun a diff cannot contain. "Anna removed Bernd from the Frontend sub-team" is one row-delete plus a membership row, and no column-level detail reconstructs the sentence a compliance reader needs.
+
+  *B2 — actions and queries are audited too.* The interceptor was mutation-only, measured by the reporter against their own data: all ten rows carried mutation tags, so a successful login, a GDPR export and a third-party write from an action left no trace at all. For a compliance trail that is a LARGER hole than a missing name — the question "who exported this" had no row to be missing one on. `interceptAction` and `interceptQuery` were available slots the plugin simply never filled.
+
+  Actions record by default (they write). Queries are opt-in via `recordQueries`, because a read-heavy app writes one row per read and a trail that drowns in reads is worse than one missing them — nobody searches it. Turn it on for the surfaces where the READ is the sensitive act, usually with `include`.
+
+  codemod: none
+- **@voltro/runtime** — The credential bound now covers EVERY realtime primitive, not just events.
+
+  An event stream got it first; live queries and `*.stream.ts` streams are the same kind of standing grant and did not have it. All three now end when the credential that authorized them expires, and the clients' existing reconnect re-opens them as a NEW request — fresh subject, guards re-run for real.
+
+  It is ONE function (`boundByCredential`) that all three call rather than the same three lines in three binders. A value derived independently at several sites is the shape this repo has been bitten by repeatedly: every site looks correct and they disagree the moment one is edited.
+
+  Where the halves sit, because they are easy to conflate: the per-delivery guard re-check catches RESOURCE revocation (its resolver does a live lookup); the credential bound catches the ROLE case, whose scopes were captured when the subscription opened and never change. Neither covers the other.
+
+  codemod: none
+- **@voltro/runtime** — An event stream now re-authorizes on EVERY delivery, as a live query already did. Events were the weaker of the two for the same kind of grant.
+
+  `servePipeline` states the reasoning for the identical case and it applies verbatim: a subscription is a LONG-LIVED grant, and the scopes that justified it can be withdrawn while it is still open — a role revoked, a resource un-shared, a membership ended. Without a re-check the socket keeps delivering what the subject may no longer read. Live queries have re-authorized per delivery for some time; event streams were checked once, at subscribe, and never again.
+
+  **This corrects a conclusion drawn in this repo one change earlier.** That change argued a re-check was unbuildable at this seam because the subject is captured per request, so re-checking it always confirms. True of the scopes ON the subject — and wrong as a general claim, because `checkGuardsEffect` runs the async RESOURCE-SCOPE resolver, which does a live lookup. For a resource-scoped guard (`{ scope: 'arena:read', from: 'arenaId' }`, the shape events use) the re-check catches revocation for real. The two mechanisms cover different halves: this catches resource revocation, and the credential bound added alongside it catches the role case by refusing to outlive the token.
+
+  A denial ENDS the stream rather than dropping the delivery. A silently skipped delivery is indistinguishable from "nothing happened", which is the one outcome this primitive exists to eliminate; the client is told, and its reconnect gets the refusal as a typed error. An unguarded event pays nothing — the closure short-circuits before any effect is built.
+
+  Red-verified, and the first version of that verification FAILED to go red: the test asserted only that the stream failed, and `Effect.timeout` also fails, so a stream that never ended satisfied it. It asserts the failure VALUE now — a scope denial, explicitly not a timeout.
+
+  codemod: none
+- **@voltro/plugin-notifications** — `archive` / `unarchive`, `markUnread` and `markAllRead` — the four procedures that were keeping an app off this plugin.
+
+  The reporter's comparison was fair and worth repeating: our surface is richer than theirs on the parts we have (quiet hours, channel preferences, delivery logs) and was missing the ones a user touches most. **Archive was not merely a missing procedure — the word appeared nowhere in this plugin's types.** `readAt` covers read; the delivery table's `status` is the delivery outcome (`sent | failed | skipped`). Neither is an archive, and archiving is the action that empties an inbox. An inbox nobody can clear is one they stop opening.
+
+  `archivedAt` is therefore its own column and its own state: archiving does not mark an item read, and an archived-but-unread item still counts toward `unreadCount`. A UI that conflates them cannot show what a user did.
+
+  `markUnread` exists because an inbox without a way back is a one-way ratchet, and `markAllRead` because marking two hundred items one at a time is not a feature. It reports how many rows it changed — a caller showing "12 marked read" must not be told 200 because that is how many rows exist.
+
+  All four are subject-scoped like `markRead`: an inbox action must not reach across subjects because an id happens to be guessable.
+
+  codemod: none
+- **@voltro/database, @voltro/runtime** — `pluginRef(table, { orphanPolicy })` — point at a plugin-owned row from an app table, with a declared rule.
+
+  ```ts
+  favouriteOf: pluginRef(aiFlowsTable, { orphanPolicy: 'delete' })
+  sharedFlow:  pluginRef(aiFlowsTable, { orphanPolicy: 'null' }).nullable()
+  ```
+
+  No foreign key is emitted, and that part was already right: the plugin owns its table and may rename it — the `_voltro_` migration did exactly that across ten tables — so a cross-boundary FK would turn every rename into a coordinated migration of every app pointing at it. `ai_flow_runs.flowRef` is a plain string for the same reason, and `plugin-storage` ships `assetRef({ fk: false })`.
+
+  **What was lost with the FK is not the constraint but the ORPHANING RULE**, and a reporter's census shows the shape of it: 711 app→app references carrying an `orphanPolicy`, against 2 pointers at plugin rows. Not because pointing across the boundary is rare — because there was no pattern, so each one becomes a hand-written subscriber that cleans up on delete. Bespoke referential integrity, re-implemented per app, and nothing notices when someone forgets one.
+
+  Four decisions, each answering an edge case they raised:
+
+  - **Tenant — fail closed.** A referencing row whose tenant differs from the deleted row's, or which has none, is left alone. Deleting across a tenant boundary because a scope was missing is the one outcome worse than an orphan. - **Soft delete — opt in per reference** (`onSoftDelete`). A soft delete is a state the target can undo, so cascading on it destroys rows a restore cannot bring back; and plugin tables are inconsistent here by design (`_voltro_ai_flows` has `deletedAt`, `_voltro_ai_flow_runs` does not), so a guess would be wrong for half of them. - **Rename — the target is a table VALUE**, resolved through the handle the plugin exports, so a rename carries the rule with it. Referencing by string would reintroduce the coupling the missing FK exists to avoid. - **`'keep'` is a policy, not the absence of one.** Same behaviour as omitting it, arrived at deliberately and reviewable as such. The default stays `'keep'` — a default that deleted rows would be a footgun.
+
+  codemod: none
+- **@voltro/protocol, @voltro/runtime** — `defineStream` accepts `guards:`, and they are enforced.
+
+  A stream was the ONE realtime primitive that could not express authorization at all. Queries, mutations and actions carry `guards:`; `StreamProcedureDescriptor` had no such field. Whatever protection a `*.stream.ts` had was hand-written inside its executor, where nothing could verify it existed — not the boot audit, not `voltro doctor`, not a reviewer reading the descriptor. The absence was invisible in exactly the way that matters: a stream with no authorization and a stream whose authorization lives in its body look identical from outside.
+
+  Checked at subscribe AND before every element, the same as a query's, for the same reason `servePipeline` already gives: a stream is a long-lived grant and the scopes that justified it can be withdrawn while it is still open. The guard INPUT is the call's decoded input, so a resource-scoped guard (`{ scope: 'feed:read', from: 'id' }`) sees which resource was asked for.
+
+  A denial ENDS the stream rather than dropping the element. A skipped element is indistinguishable from "nothing to send", and the client must learn it lost access rather than infer it from silence. An unguarded stream pays nothing.
+
+  Deliberately NOT wired into the manifest, doctor or the devtools panel in this change. The event-`guards` defect was reporting surfaces showing protection that nothing enforced; enforcement without reporting is the safe direction of that same asymmetry — it works and is merely not displayed yet.
+
+  codemod: none
+- **@voltro/protocol, @voltro/runtime, @voltro/cli** — An event subscription can no longer outlive the credential that authorized it.
+
+  Guards are checked once, at subscribe. That is not an oversight to patch: the subject comes from THAT request's layer, so re-checking it later inside the stream asks the same captured object and always gets the same answer. A "re-check on subject change" built at that seam would be a control path that always confirms — worse than no check, because it looks like one.
+
+  The honest bound is a fact the token already carries. `ConnectionInfoValue` gains `credentialExpiresAt` (unix seconds, verified — an unverified decode would let a client forge a far-future expiry and lift the very ceiling this imposes), and `bindEvent` ends the stream there. Absent means no bound, so the failure direction is the behaviour that already existed.
+
+  **It is seamless, and that costs nothing to build.** `useEvent` already treats a clean end as a reconnect reason — a server never legitimately finishes a stream a client still wants — so it re-opens immediately. A reconnect is a NEW request: the subject is resolved afresh and the guards run again for real. Still entitled, it continues and the app sees nothing; no longer entitled, the reconnect is refused loudly instead of delivering forever on a dead credential. No application-side reconnect handling.
+
+  `sessionExpiryFromHeaders` is a SHARED helper both boot paths call, and `SESSION_COOKIE_NAME` moved to `@voltro/protocol/session` so it has one definition rather than one per reader — dev and serve deriving one value twice is how the two paths come to disagree silently.
+
+  This bounds EXPIRY, not revocation. A role revoked mid-session is not observed until the credential runs out, and the docs say so in both languages rather than implying more. Revocation belongs at the session seam — a revoke event that ends the connection is one place instead of one per primitive, and this reconnect machinery would then carry it for free.
+
+  codemod: none
+- **@voltro/plugin-webhooks** — Three additions that were the whole distance between a consumer and deleting their own webhook tables.
+
+  **`scope` — an opaque app dimension on `_voltro_webhook_targets`.** Stored and returned verbatim, never interpreted; `listTargets(event, scope)` filters on equality against it. `.with(tenant())` is one level too coarse for real deployments: their endpoints are scoped to a TEAM and a tenant has many teams, so every read filters by it and every write guards on it.
+
+  The precedent is theirs, and it decided a migration: `_voltro_presence.meta` is json the framework stores and never interprets, and it is the ONLY reason their presence migration was lossless — three denormalised columns went straight in. An earlier review of theirs called that plugin lossy and they withdrew it. The general form they derived is the right one: **a plugin that stores rows in an app's database on the app's behalf needs one place for the app's own dimension.**
+
+  **`listDeliveries` / `getDelivery`.** There was no service method over `_voltro_webhook_deliveries`, so a management view could only query the table directly — which they declined, correctly: the 0.24.0 `agent_messages` rename taught them what app code coupled to a framework table name costs, and that one was survivable only because it was a rename. `listDeliveries` omits `payload` and `responseBody` so a list view does not pull response bodies for 200 rows; `getDelivery` adds them. Timestamps are normalised to ISO regardless of what the dialect returned, and an unparseable payload comes back verbatim rather than throwing — a management view must render a malformed row, not 500.
+
+  **`updateTarget` and `testTarget`.** Editing a URL previously meant delete + re-subscribe, which rotates the secret (every receiver reconfigured) and orphans the delivery history. The patch writes only the keys present, so an absent key leaves the column alone while an explicit `null` clears it; `event` and `secret` stay unpatchable (a different event is a different subscription, and the secret has `rotateSecret`). `testTarget` sends ONE delivery, bypassing fan-out and the filter — a filter excluding the probe would make a healthy endpoint look dead — but NOT `active`, so a paused target queues exactly as an emit would and the test tells the truth about production.
+
+  codemod: none
+- **@voltro/cli, @voltro/runtime, @voltro/workflow** — **Cross-replica workflow WAKE** — a triggered workflow now starts ~immediately across replicas, instead of waiting up to the storage-poll interval. When you trigger a workflow whose cluster shard is owned by ANOTHER replica, that replica used to pick the run up only on its next poll tick (up to 10s), because Voltro's single-runner topology has no runner-to-runner push. Now, on a trigger the framework publishes a tiny "wake" onto the SAME Redis/NATS broadcast bus a multi-replica deployment already runs for cross-replica reactivity; every replica subscribes and, on a wake, re-polls cluster storage right away — so the shard owner reads the new run now.
+
+  - **Dialect-agnostic** — it rides the broker, not the SQL dialect, so it works identically on postgres / mysql / mariadb / mssql (unlike a pg-only LISTEN/NOTIFY). No effect on sqlite (single-process, already immediate). - **Degrades cleanly** — with no broadcast broker (single replica, or the in-process memory transport), there's nothing to wire and the poll interval (`VOLTRO_WORKFLOW_POLL_INTERVAL`) remains the bound. The wake is a latency optimisation, never a correctness dependency: a dropped wake just falls back to the poll. - Built by ONE shared builder wired into BOTH `voltro dev` and `voltro serve` (boot-path parity), fires on the fire-and-forget `start` / `child` triggers, and skips its own wake (the triggering replica already polled locally).
+
+  `codemod: none` — additive; new opt-in behaviour that activates only when a cross-replica broker is present.
+- **@voltro/runtime, @voltro/workflow, @voltro/cli** — Workflow dead-letter management — a dead-letter VIEW + `discard`. Because the framework applies no retry of its own, a `failed` run is terminal: it is the dead-letter. `voltro workflows list --dead-letter` shows the queue of unhandled failures (`status = 'failed' AND discardedAt IS NULL`); `voltro workflows discard <id>` acknowledges one so it drops off that view. Discard is an ACK, not a re-classification — the run stays `status: 'failed'` (outcome + audit trail survive) and gains a `discardedAt` timestamp (mirrors how `cancelled` coexists with the status); `--status failed` still lists it, marked `discarded`. Discarding a non-failed run is refused; discarding is idempotent. New `discardedAt`/`discardedBy` columns on `_voltro_workflow_runs` (ride the declarative differ — no codemod), a `discard` inspect action + `--dead-letter` list filter, and `discardedAt` on the `WorkflowRunSummary` / `deadLettered` on `WorkflowRunListFilter`. Note: like the other workflow inspect ACTIONS (retry/cancel/…), discard is wired on the `voltro dev` inspect surface. `codemod: none` — additive schema + a new opt-in CLI/inspect surface; no user-authored code is affected.
+- **@voltro/workflow, @voltro/cli** — Workflow failover across replicas is now **tunable and proven**. When a replica running a durable workflow crashes, a surviving replica takes the run over and continues it from the last completed step (completed steps replay from the journal, not re-run) — on any SQL store (postgres / mysql / mariadb / mssql). That already worked; what's new:
+
+  - **Two operator knobs** for how fast a survivor reclaims a crashed replica's in-flight work — which is a lease-expiry floor (~35s default), NOT a polling one, so lowering it is the lever, and a push mechanism wouldn't help: `VOLTRO_WORKFLOW_FAILOVER_LEASE` (seconds; default 35) and `VOLTRO_WORKFLOW_FAILOVER_HEARTBEAT` (seconds; default 10, keep ≈ lease/3). Lower the lease for faster failover, at the cost of false-positive reclaims if a healthy replica stalls (GC / DB-latency) longer than the lease. Exposed as `failoverLeaseSeconds` / `failoverHeartbeatSeconds` on the workflow engine layer and read from env by `voltro serve`. - **A live multi-PROCESS failover test** (`@voltro/sql-postgres`) that boots two real cluster-runner processes against one postgres, SIGKILLs the one running a 3-step workflow mid-step, and asserts the survivor resumes it from the journal — the completed step ran exactly ONCE across the crash. This exercises the hard-crash (lease-expiry) path a clean shutdown can't, and is the guarantee behind the docs. - Production-hardening docs (en + de) now cover the failover model, the `POD_IP` requirement, the at-least-once step boundary, and the tuning tradeoff.
+
+  `codemod: none` — additive config; nothing user-authored changes.
+- **@voltro/workflow, @voltro/cli** — `VOLTRO_WORKFLOW_POLL_INTERVAL` (seconds → `messagePollSeconds` on the workflow engine layer) tunes NEW-message pickup latency across replicas. When you trigger a workflow whose shard is owned by the SAME replica, it starts immediately (a same-process push); when ANOTHER replica owns the shard, that replica picks it up on its next storage poll — up to 10s by default (Voltro's single-runner topology has no cross-runner push). Lower this for latency-sensitive multi-replica workloads, at the cost of more idle poll queries; it has no effect on a single replica. This is distinct from the failover knobs (a crash-reclaim lease, not new-message latency). The lower-idle-load alternative is a pg LISTEN/NOTIFY wake, not yet wired. `codemod: none` — additive.
+- **@voltro/workflow, @voltro/runtime, @voltro/cli, @voltro/devtools-ui, @voltro/voltro** — <!-- apiSurface: compatible — reasoned, not rubber-stamped. Three golden lines churn, all WIDENINGS (the direction the gate's rule is not about), and the actual consumers typecheck green against them: 1. `WorkflowRunEventType` gained `'run-redriven'` (in @voltro/workflow AND the @voltro/voltro re-export). It is a framework-EMITTED union — a reader gets a superset; every value that was one of the old members still is one. 2. `workflowEngineLayer`'s return went from `Layer<WorkflowEngine>` to `Layer<WorkflowEngine | Sharding | MessageStorage>` — it now EXPOSES the two cluster services it already built internally (so the re-drive adapter can reach the same instance). It is a framework-internal engine builder wired only by dev.ts / serveCommand (both cast loosely); every value-level use (`provideMerge`, `ManagedRuntime.make`) still compiles. @voltro/runtime + @voltro/cli, its real consumers, were typechecked after the change — green. Nothing was removed or narrowed. -->
+
+  `redrive` — re-drive a terminally-`failed` workflow run from the step it died on, reusing its durable journal. The operator counterpart to `retry` (fresh execution, empty journal) and to `resume` (which only re-drives a *suspended* run): a plain `failed` run is a terminal `Complete(Failure)` in the cluster store that `resume` will not touch. Fix the downstream cause, then `voltro workflows redrive <runId>` (or `ctx.workflows.redrive(runId)`, or the inspect `redrive` action) and the engine re-delivers the run — every completed step **replays from the journal** (NOT re-executed) while the failed step(s) re-run. Ideal for a long multi-step pipeline where redoing steps 1…N‑1 is expensive or unsafe and you did NOT pre-declare `suspendOnFailure`.
+
+  Under the hood a single isolated adapter (`@voltro/workflow/cluster` `redriveFailedRun`) reaches into `@effect/cluster`'s `MessageStorage`/`Sharding` to clear the terminal `run` reply plus each failed step's journaled reply, then re-polls storage — the same primitive the engine's own `resume` uses, minus its suspended-only guard. A live cluster **contract test** boots a real engine, fails a multi-step run, re-drives it, and asserts the completed step did NOT re-run, so an engine upgrade that moves those internals fails loudly instead of silently corrupting a re-drive.
+
+  Works in `voltro dev` AND `voltro serve` — dead-letter recovery matters where incidents happen. Refuses a run that is not a not-yet-discarded failure (use `retry` for a fresh run, `resume` for a suspended one), and declines cleanly (`redriven: false` + a `reason`) when there is no durable journal (e.g. the memory store). Records a `run-redriven` lifecycle event. `codemod: none` — a new opt-in action + SDK method; no user-authored code is affected.
+- **@voltro/workflow** — `suspendOnFailure` — resume a workflow from where it failed, reusing completed steps. Declare `suspendOnFailure: true` on a workflow and a failure of its top-level body no longer becomes a terminal `failed` run — it **suspends** with the durable journal intact, so `voltro workflows resume <id>` (or `ctx.workflows.resume`) re-drives it from the point of failure: every completed activity replays from the journal (NOT re-executed) and only the failed activity runs again. This is the durable-execution way to make a long multi-step workflow recoverable across a transient downstream outage without re-doing prior work — the opposite of `retry`, which starts a fresh execution with an empty journal. Maps to `@effect/workflow`'s `SuspendOnFailure` annotation. A suspended-on-failure run records `status='suspended'` WITH the failure reason (`errorTag`/`errorMessage` + a `suspend-on-failure` event, and it reaches the error reporter), so it is distinguishable from a plain sleep/signal suspension; it shows under `--status suspended`, NOT in the dead-letter view (it is recoverable, not dead). Default `false` — a failure stays terminal. `codemod: none` — a new opt-in workflow option; no user-authored code is affected.
+
+### Fixed
+
+- **@voltro/runtime, @voltro/cli, @voltro/plugin-webhooks** — Three gaps named in the previous change set, closed.
+
+  **`onSoftDelete` could not fire.** A soft delete is not a `delete` event — it is an UPDATE that sets `deletedAt` — and the rule matcher only looked at `op === 'delete'`, so the option existed and the event it needed never arrived. The matcher detects the null → non-null TRANSITION on `deletedAt` (the value alone would re-fire on every later write to a tombstoned row) and the boot wiring forwards updates as well as deletes.
+
+  The tests were green throughout, because they passed `softDeleted: true` alongside `op: 'delete'` — a shape the change channel never produces. They proved the flag worked against something that does not exist.
+
+  **`assertNoTagCollisions` ran only in `voltro dev`.** A plugin/app tag clash aborted boot in development and was checked nowhere in production, so a collision dev refuses could ship and whether it shadowed a route or crashed depended on what codegen happened to emit. It runs in `serve` now, honouring `overridesPlugin` identically from the same descriptors.
+
+  **`listDeliveries` filtered after the read.** `status` and `since` cannot go into the predicate, so taking exactly `limit` and then filtering silently returned too few — ask for 200 deliveries since Monday and you get however many of the newest 200 rows fall in that window, with no signal the answer was truncated from the wrong end. It over-fetches when a post-read filter is in play, then applies the limit.
+
+  That last test also passed against the old code at first: the fake store ignored `take` entirely, so nothing about paging was being tested. Modelling `take` made it red-verifiable, and it is — 1 row instead of 5 without the fix.
+
+  codemod: none
+- **@voltro/cli, @voltro/runtime** — Two defects reported from a MariaDB deployment.
+
+  **`gc-snapshots` and `restore-snapshot` were postgres-only, silently.** `table_schema = 'public'` was hardcoded at four sites. On MySQL/MariaDB the schema IS the database name, so every one matched nothing — and "matched nothing" prints the same line as "there is nothing": the reporter had a real `presence__dropped_20260803032340` while the tool said "dropped 0" and exited 0.
+
+  It compounds because `VOLTRO_SOFT_DROP=1` is the right default for an unattended migrate job, so every drop becomes a snapshot and they accumulate forever when the reclaim tool cannot see them — the safety net becomes litter.
+
+  Two sites were in `gc-snapshots`, which is what was reported. The other two are in **`restore-snapshot`**, which nobody had reached yet: that is the command you run AFTER something went wrong, and it would have answered "no snapshot found" for one that exists. Beneath the predicate sat a second postgres assumption the first one hid — `"double-quoted"` identifiers, which MySQL/MariaDB reject, so even a matching query could not have executed. Both are dialect-resolved now (`quoteIdent` was already imported and unused).
+
+  **A stale `source:` is now reported at boot.** `source` is matched by NAME against change events, so one naming a table that no longer exists leaves the query not broken but permanently QUIET — it serves its first snapshot and never updates, which is indistinguishable from "nothing has changed". The reporter hit it on the 0.24.0 agent rename: two queries kept the old string and the app booted clean with zero warnings. It is a string, so `tsc` cannot see it, and the codemod's promise that a missed rename "fails loudly with relation does not exist" is true of a SQL reference and false of this.
+
+  Resolved against the declared table set — which the boot already holds, so it is free — with a did-you-mean for the prefix-rename case that produced it. It WARNS rather than refusing: a table can legitimately live outside the declared schema, and a boot failure for those would be the worse trade. Computed in `loadDiscovered`, so dev / serve / doctor / check all see it, with a parity test that fails if it is wired into only one boot path.
+
+  Both red-verified against their own reverted fix.
+
+  codemod: none
+- **@voltro/runtime** — The events docs promised an authorization guarantee the code does not provide.
+
+  "Guards are re-checked when the subject changes, not per delivery. Revoke a role and the stream ends." There is exactly ONE `checkGuardsEffect` call on the event path — in `bindEvent`, at subscribe — and no subject-change hook, no revocation path that touches a live subscription. A subject whose role is revoked keeps receiving, and this primitive reconnects forever by design, so "until the stream ends" can be a very long time.
+
+  The documentation now says what happens: checked once, at subscribe, never again; if a permission change must take effect immediately, do not model the authorization boundary with an event subscription. en + de, agent-docs regenerated.
+
+  Correcting the sentence rather than implementing the re-check is deliberate, and the reasoning is the same one that made this worth finding: a security guarantee that is stated and not kept is worse than one that is absent, because readers build on the sentence. Re-checking on subject change is a real feature with real design questions (what ends the stream, how a subject change is even observed on a long-lived socket) and it should not be improvised inside a doc fix.
+
+  Same shape as the three defects already fixed in this pass — `webhook.retry`, `presencePlugin({ sweepIntervalMs })`, and the guards themselves, which were accepted, serialised into the manifest, reported by doctor and counted in the devtools panel while nothing enforced them. That one was about whether the check runs at all; this one is about how long its answer stays true.
+
+  codemod: none
+- **@voltro/runtime, @voltro/protocol, @voltro/cli** — **`ctx.events` is typed as what it actually is.** It was declared as the old string-emitter facade (`emit(name, data)`) long after that facade stopped being installed there, so the documented and taught call — `ctx.events.publish(descriptor, key, payload)` — was a `tsc` error while the runtime carried only `publish`. A consumer could not tell which of the two was lying and measured it with a cron probe:
+
+  EVENT_PROBE {"eventKeys":["publish"],"publishType":"function","emitType":"undefined"}
+
+  Exactly the inverse of the declared type. Their workaround was a cast in the one primitive whose entire justification is typing.
+
+  What let it drift is the part worth recording: the builder installed the publisher with `as never`, so the compiler had the answer the whole time and was told not to give it — beside a comment in the same file stating that `emit` is gone. A context field is the one place this repo already treats such a cast as a defect in its own right; it is removed, so `tsc` is the guard now.
+
+  **`overridesPlugin: true` on a query / mutation / action.** Correcting the premise first, because it matters for anyone reading the same report: sharing a NAMESPACE with a plugin already composes. `assertNoTagCollisions` compares FULL tags, so `notifications.list` beside the plugin's `notifications.inbox` has always been fine. Only an identical name collides, and that stays an error — two handlers behind one tag is not something a caller can reason about.
+
+  What was missing is the deliberate replacement. The two escapes available before were to rename your procedure or to `alias` the whole plugin away, and both move the split from a domain boundary to "who built it" — for a frontend developer, the worst possible partition. The flag drops the plugin's route rather than merely permitting the pair (permitting it would leave two handlers bound, the state the check exists to prevent) and logs which routes it replaced.
+
+  Explicit, never inferred: silently letting the app win would mean a plugin upgrade that adds a route could shadow an app procedure with no diff to read.
+
+  Three smaller ones from the same report: the `defineSchedule` timezone error now says that an ABSENT field is a `tsc` error and reaching the message means an EMPTY one (usually `process.env.TZ ?? ''`); the empty-relations warning names the `_relations.register.ts` entry that must go with the file; and `db apply` no longer says "nothing to apply" one line above "installing change triggers on 500 table(s)" — it says "no DDL to apply", which is what it meant.
+
+  codemod: none
+- **@voltro/plugin-presence** — `presencePlugin({ sweepIntervalMs })` is now read. It was declared, documented as "Sweep interval for stale rows. Default 60s.", and the sweep ran on `timeoutMs / 3` regardless — so setting it did nothing, and the stated default was wrong as well: with the 30s window the real interval was 10s, not 60s. The one number a reader could have checked the option against disagreed too.
+
+  It defaults to a third of `timeoutMs` (a vanished member is gone within roughly 1.3x the online window, which is the right relationship for almost every room) and an explicit value now wins.
+
+  The interval was also derived at TWO sites — the one the sweep ran on and the one reported to the inspect surface — computed identically and independently. That is how a reported value and a real one drift apart with neither site looking wrong; it is derived once now.
+
+  Found by walking the plugin option surface and asking, per field, who reads it — the same pass that found `webhook.retry`. Fourth instance of this class in this feature. `declaredOptionsEnforced.test.ts` pins it, red-verified against the reverted fix.
+
+  codemod: none
+- **@voltro/client** — `useEvent` crashed instead of waiting when its api had not resolved yet. Every other hook survives that window because it reads through `LoadingSubscriptionCache`, whose `subscribe` is a non-fetching no-op; `useEvent` forks its own fiber on the api handle's runtime, and the loading baseline's runtime is a stub with `runPromise` and nothing else — so a mount without a `<VoltroRuntimeProvider>` above it, or during the boot window before the client resolves, died with `runtimeRef.current.runFork is not a function`.
+
+  It now stays `idle` until the api resolves, then subscribes. The gate is worth more than the crash it removes: this subscription retries a dropped connection forever on purpose, and the loading baseline's client is a proxy that throws on every call — so a fork that had "worked" would have spun rather than failed.
+
+  The gate asks whether the runtime can fork rather than comparing the handle against the stub by identity, because a host that loads a bundled copy of `@voltro/client` alongside the resolved one — `@voltro/web`'s dist does — has its own stub object, and identity would answer "resolved" for a stub. Capability is true of every real runtime and false of every stub, in any number of copies.
+
+  codemod: none
+- **@voltro/database, @voltro/runtime, @voltro/cli, @voltro/plugin-versioning, @voltro/plugin-audit** — Two features shipped one commit earlier were declared and inert. Both are now wired, and both are the exact defect class the change set they arrived in was about — declared, and nothing reads it.
+
+  **`pluginRef` was a library, not a feature.** `applyPluginRefRules` and `pluginRefSpecOf` had no caller anywhere. An app could declare `orphanPolicy: 'delete'` and the rule would never run: the column worked, the engine was correct, and nothing connected them. It is collected at boot from the registered tables and applied on the post-commit change channel, out of band so it can never back-pressure the change stream.
+
+  `collectPluginRefRules` also implements the edge case that was only a comment before: a `pluginRef` naming a table no installed plugin registers **refuses at boot**, naming both sides. A declared rule against an absent plugin would sit there looking enforced.
+
+  **`_voltro_row_history.actor` was always null.** The column existed and the row builder read `event.actor` — which nothing ever set. The versioning plugin now resolves the snapshot from the `actors` row it already has store access to.
+
+  `resolveActorSnapshot` moved to `@voltro/database` for that: two plugins need it, it is the only package both depend on, and `actors` is a core table declared there. Putting it in the runtime was the first attempt and wrong — plugin-audit deliberately does not depend on the runtime.
+
+  Both are guarded by WIRING tests, not only unit tests of the engines: in both cases the engine was correct and entirely inert, which no unit test could see. Red-verified by removing the wiring.
+
+  codemod: none
+- **@voltro/workflow** — **Multi-replica workflow runners now get a DISTINCT cluster identity** — a real sharding + failover correctness fix. `workflowEngineLayer` set only the cluster runner's *listen* address (from `POD_IP`), never its *advertised* address, and the advertised address IS the identity `@effect/cluster` keys `cluster_runners` and every owned shard on. So every replica fell back to the library default (`localhost:34431`) and they all registered as the SAME runner: one identity owning all 300 shards, no distribution, and failover that "worked" only because the colliding processes happened to poll the same rows.
+
+  Now both the advertised (`runnerAddress`) and listen addresses are set from the `POD_IP`-derived identity, so two pods with distinct `POD_IP`s are two distinct runners — shards distribute across them (verified: 3 runners → 100 shards each, was 1 → 300) and a crashed replica's shards are genuinely handed off to a survivor. Surfaced by a new multi-process chaos test that needs three real, distinct runners to hand a run off twice.
+
+  Requires `POD_IP` (or `VOLTRO_WORKFLOW_RUNNER_HOST`) injected per pod — the same requirement the boot already warns about; it now actually determines identity, not just the (inert, under SingleRunner) listen address. `codemod: none` — no user-authored code changes; `cluster_runners` is ephemeral and re-registers on boot, so stale old-identity rows age out on their own.
+
+---
+
 ## [0.25.0] — 2026-08-04
 
 ### ⚠ BREAKING

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-auth-clerk",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Clerk-backed AuthStrategy for the Voltro framework. Verifies Clerk-issued __session JWTs via the Frontend API JWKS. Conforms to @voltro/protocol AuthStrategy so it composes with other IdP plugins.",
   "keywords": [
     "voltro",
@@ -32,7 +32,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/protocol": "0.25.0"
+    "@voltro/protocol": "0.27.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"