@voltro/plugin-flags 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -39,6 +39,144 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.55.0] — 2026-08-27
+
+### ⚠ BREAKING
+
+- **@voltro/protocol, @voltro/client, @voltro/runtime, @voltro/cli** — **A multi-reference field now flips as instantly as a scalar one.** A mutation target's declared `relations:` reconciled the junction inside the server's transaction and nothing else: the client learned about the link change only when the delta came back. On the same submit, the renamed title flipped immediately and the assigned stores did not — the half of the promise that was never stated.
+
+  The declaration now drives BOTH. `useMutation`'s auto-optimistic stages a patch on every subscription sourced on the junction table, reconciling that anchor's links against `input[field]` — surplus links removed, new ones staged, surviving links left untouched with their real ids (a diff, mirroring `store.relationLinks(...).set`, not a drop-and-restage that would blink every unchanged row).
+
+  The patches ride the ordinary optimistic lane, staged under the mutation id, so the rollback rule holds by construction: reverted on failure, kept on success until the base actually moves. Nothing here is on a timer.
+
+  **Migration — `relations:` values are objects now:**
+
+  ```ts
+  // before
+  target: { table: 'employees', op: 'update',
+    relations: { assignedStores: 'employee_assigned_stores' } }
+  
+  // after
+  target: { table: 'employees', op: 'update',
+    relations: { assignedStores: {
+      junction: 'employee_assigned_stores',
+      anchorColumn: 'employeeId',   // the junction reference() pointing at `employees`
+      targetColumn: 'storeId',      // the junction's other reference()
+    } } }
+  ```
+
+  The columns are declaration data because the optimistic patch runs in the BROWSER, which has no table registry to derive them from — `@voltro/database` is server-only by construction, and guessing a column from a table name is exactly what `store.relationLinks` refuses to do. They are not taken on trust: before it writes, the server compares the declaration against the junction's real reference columns and refuses, naming the correct pair, if they disagree. A wrong declaration is a loud error carrying its own fix, never a client that patches one column while the server writes another.
+
+  Semantics unchanged and now shared by both sides: an absent input field touches nothing (absent ≠ empty), an empty array is the explicit clear. The client uses `input.id` for an update and, for an insert, the same optimistic id it stamped on the new row — the server's `output.id` is not knowable before the response.
+
+  **`voltro update` carries you across this** — codemod `0.55.0/01_target-relations-declare-columns`. 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.55.0).
+- **@voltro/client, @voltro/ui, @voltro/ui-shadcn, @voltro/web, @voltro/cli** — **A rich-text field, and the sanitizing contract is the point of it.** `RichTextDocument` (`@voltro/client`) is the value; `widget: 'rich-text'` renders it; `<RichTextView>` (`@voltro/ui`, re-exported by `@voltro/web`) displays it.
+
+  The contract, stated plainly because the alternatives all look reasonable until you name who the attacker is:
+
+  - **The value is a closed document tree, not an HTML string.** There is no `html` node, no raw-markup escape hatch, no attribute bag. Anything that is not one of the declared node types fails to decode. - **The boundary is the `Schema` decode**, which is the server's existing, non-bypassable input boundary — the same one every mutation input already passes through. So the guarantee is not "somebody remembered to sanitize this"; it is that a document which reached the database is one of these shapes. - **A link's `href` is the one field that points outward, and it is allowlisted** — `http(s)`, `mailto:`, a `#fragment`, a `/path`; nothing else. Control characters and whitespace are stripped before the check, because `java\tscript:` navigates exactly like `javascript:` and a check on the raw string passes it. - **Client-side is not a boundary and is not treated as one.** The widget's parser runs in the browser for the editing experience; every property it maintains is re-established by the decode on the server. - **Rendering never uses `dangerouslySetInnerHTML`.** Nodes become React elements, text becomes React children — so markup typed into the box is markup the reader SEES. `<RichTextView>` also drops an href that would not survive a decode, for the value that never went through one.
+
+  Rejected, for the record: sanitizing an HTML string on write (ships an HTML parser and the mXSS surface that comes with it), escaping at render (makes safety a property of every read site), and declaring an unenforced boundary (a convention, not a guarantee).
+
+  The built-in widget is a `<textarea>` over a small, CLOSED markdown subset — headings, `**bold**`, `*italic*`, `` `code` ``, `[text](href)`, lists, blockquote, fenced code — with everything unrecognised left as literal text. That also closes the no-JS loop: the textarea posts source, `/form/*` parses it, and the same decode validates it. A WYSIWYG belongs at rung 2 (register a `rich-text` widget); the stored value shape does not change.
+
+  **Not** the collaborative case: `crdtDoc()` + `useCrdtEditor` remains the multi-writer path (a CRDT bytes column, a sync lane, Tiptap). This is one column, one writer, ordinary JSON the server can validate and diff, and no new dependency in the default kit.
+
+  **Migration:** `WidgetKind` gained `'rich-text'`. Only a registry typed as a TOTAL map (`Record<WidgetKind, Widget>`) notices — add one entry pointing at the exported `RichTextWidget`. Partial registries need nothing.
+
+  Also fixed alongside: the capability manifest's `MANIFEST_WIDGET_KINDS` is a hand copy of `WidgetKind` (a CLI module cannot import `@voltro/client`) and had silently drifted by two kinds since 0.53.0, telling coding agents a smaller set than the renderer accepts. It is complete again and pinned by a test that reads the union out of the client's source.
+
+  **`voltro update` carries you across this** — codemod `0.55.0/02_widget-kind-gained-rich-text`. 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.55.0).
+
+### Added
+
+- **@voltro/database, @voltro/data-transfer, @voltro/cli, @voltro/voltro** — A staged `--mode replace` now RECORDS the scratch tables it creates, and a boot collects the ones nobody is coming back for.
+
+  Staging tables are `_voltro_staging_`-prefixed, so the differ correctly ignores them — and nothing else mentioned them either. A run that died between the load and the swap left a full copy of a bundle that only a hand-written introspection could find, on a database whose boot said nothing. The marker row now names the set, carries a heartbeat the run refreshes while rows land, and records whether the run was started `--no-atomic`. That is what lets a boot tell the three cases apart: silent past the threshold and not resumable → the tables are dropped; still beating → an import is loading into them, here or on another replica; resumable → its staging IS the resume point and is left alone however stale. `VOLTRO_STAGING_STALE_MINUTES` moves the threshold (default 30). A staging record is reported, never a refusal — a staged replace destroys nothing until one short server-side swap, so refusing a boot over it would be an alarm on a healthy database. `voltro data clear-staging` reads the same records and labels each table with what its own run says, instead of listing them flat under a warning that it could not tell a leftover from an import in flight.
+
+  Two smaller things came with it. The raw-SQL seam the staged swap runs on (`DataStore.run`) is a DECLARED optional capability now, in the shape `emptyTables` established, with a parity assertion across the four dialect stores — it was duck-typed against an interface that never mentioned it, so a store that dropped it would have fallen out of the feature detection and taken the slower path forever, on that one dialect, in silence. And a registered staging clone can no longer reach the differ's DECLARED side: `--mode replace` registers each staging table as a clone of its target for the length of the load (a typed write resolves its columns by name), and a plan computed while an import was in flight proposed `create-table _voltro_staging_notes`.
+
+  Also measured rather than assumed: the staging table `createStagingSql` builds on **sqlite** (`CREATE TABLE … AS SELECT * FROM t WHERE 0`) and on **SQL Server** (`SELECT * INTO … WHERE 1 = 0`) carries the target's columns and ZERO foreign keys, which is what the load needs. Those were the two dialects the postgres and mysql-family measurements had not covered.
+- **@voltro/client, @voltro/ui, @voltro/web** — **`useFormField(path)` finds its binding.** `<FormBindingProvider binding={form}>` (mounted for you by `<AutoForm>`) makes the narrow per-field subscription reachable without threading the binding down to every field component as a prop. That thread was blocking incremental adoption: a codebase moving a hundred-plus forms one at a time keeps its own field context and swaps engines per form, and being asked to prop-drill to ~30 field components at once meant taking the binding and declining the optimisation they had the most to gain from.
+
+  **Message ids a real catalogue needed**, each because the generic answer is worse at the point of use:
+
+  - `betweenLength {min,max}` when a field carries BOTH bounds — "at least 2" is a half-truth for a rule that is "between 2 and 50" — and `exactLength {amount}` when they are equal. Read from the schema, not the failing issue: piping nests the later refinement outermost, so the sibling bound is not reachable from the issue that failed. - `invalidEmail` / `invalidUrl` / `invalidUuid` when the refinement declares a JSON-Schema `format`. A bare regex cannot name its own rule, and "Invalid format" beside an email box tells nobody anything. - `minDate` / `maxDate`, because a date bound rendered as a number bound reads "must be at least 2026-01-01". - `invalidFileType` / `fileTooLarge` — not produced by any refinement, carried so an app's own `ctx.validation.fail('doc', 'validation.fileTooLarge')` renders a sentence rather than an id.
+
+  `apiSurface: compatible` — `useFormField` goes from a const arrow to an overloaded function so it can take `(path)` as well as `(binding, path)`. The golden line for the old signature is replaced rather than removed: every existing `useFormField(form, path)` call compiles unchanged, because that overload is still declared first-class. Only code capturing the function's exact TYPE (rather than calling it) sees a difference.
+
+  **Counting rules pass `count`.** `minItems` / `maxItems` carry `{ count }` beside `{min}`/`{max}`: i18next selects a plural form on a parameter named exactly `count`, so ids passing only `{min}` could not be pluralised at all.
+- **@voltro/runtime, @voltro/cli** — **The resume census — `/_voltro/inspect/subscriptions` now carries `resume`.** Per query label: how many subscriptions recorded a delta-resume ring, and how many were excluded, counted per reason (`computed`, `row-filter`, `eager-load`, `uncanonical-input`, `not-offered`). `voltro dev` also logs each verdict once per label under the `voltro:resume` scope — debug is the default level outside production, so it is already on where the tuning happens and off where it is served.
+
+  It exists because the two failure shapes are indistinguishable from outside. A subscription excluded by a row filter and one whose executor returns a **value** rather than a descriptor both reconnect with a fresh snapshot and rows on the screen, so an app measuring its own reconnects cannot tell which of its queries a `tables:` declaration is even capable of helping. The answer is which of the two bind paths the executor took, and nothing on the wire carries it.
+
+  The reasons are the load-bearing part, not the counts: `computed` means no declaration can ever change this query, `row-filter` means the filter narrows its source and the exclusion is the point, and `eager-load` is reported ONLY when the base table is not itself narrowed — so that verdict always means "drop the `.with(...)` and this one resumes". Counts rather than one verdict per label, because resumability is not purely a property of the label: an input that does not canonicalise is a property of the value, so one query can be resumable for one subscriber and excluded for the next. A label nobody has subscribed to is ABSENT rather than reported as zero — "nothing has subscribed yet" and "every query is excluded" must not read the same.
+
+  **And a correction to what `tables:` was documented to buy.** The 0.54.0 notes, the `tables:` doc comment and the row-level-security page all said one registration cost delta-resume on every query descriptor in an app, with a count beside it. The count was real; the sentence around it claimed those descriptors would have HAD the feature, and that was never measured. A query only has a delta chain when its executor returns a descriptor — one that maps its rows or wraps them in a page envelope re-runs an opaque handler and emits snapshots, filter or no filter. So the number a declaration gives back is the number of descriptor-returning subscriptions, not the number of queries. The docs now say that where the decision is made, and the census is how you find out which shape each of yours took.
+
+### Changed
+
+- `dataTransfer.stagingStaleMinutes` in `app.config.ts` — how long a staged import's silence has to last before a boot treats its scratch tables as abandoned. Previously `VOLTRO_STAGING_STALE_MINUTES` only; the env var still overrides the declaration, on the rule every other tunable here follows.
+
+  The reason this was not already a field was recorded as "the boot check runs off the store alone, before the app config is threaded to it". That described the function's signature, not the boot: both paths already held the config three lines above the call. Resolution lives inside `stagingLeftoversAtBoot` rather than at either call site, so the two cannot disagree about what a declared value means, and a source-reading assertion fails if either path stops handing the config over.
+
+### Fixed
+
+- **@voltro/protocol, @voltro/cli, @voltro/client, @voltro/plugin-notifications, @voltro/plugin-comments, @voltro/plugin-presence, @voltro/plugin-search, @voltro/plugin-flags** — **Installing a plugin under an `alias` now moves its client too.** `alias` exists for one problem — your app already publishes `notifications.*` and cannot install a plugin that wants the same namespace — and it has to move four surfaces or it is worse than not existing. It moved three.
+
+  The two that did not:
+
+  - **The generated client sent the tag the PLUGIN authored.** Every lifter is `Rpc.make(descriptor.name, …)`, so the wire tag comes from the descriptor, not from the tag the codegen computed. Under `alias: 'inbox'` the exported identifier became `inboxInboxRpc`, the `appDescriptors` key became `inbox.inbox`, the type key became `inbox.inbox` — and the browser still asked a server that had stopped serving it for `notifications.inbox`. The codegen now lifts every plugin descriptor through `withRpcTag(…)`, unconditionally, so the aliased and un-aliased cases are one code path rather than a branch nothing exercises. - **The plugin's own hooks spelled their namespace as a literal.** `useInbox()`, `useUpload()`, `useComments()`, `usePresence()`, `useFlag()`, `useSearch()` all carried strings like `'notifications.inbox'`, which no alias could reach. `voltro dev` now writes a `registerPluginAliases({ … })` declaration into `rpcGroup.generated.ts` — the module the web client already loads value-level — and every plugin hook resolves its tag through `pluginTag(baseName, route)` from `@voltro/protocol` at call time, not at module load. Aliasing a plugin needs no change at any call site.
+
+  Two installs of one plugin (`name: 'ops'`) with no un-suffixed primary make `pluginTag` **refuse** rather than pick: a hook has no way to name an install, and guessing would address the wrong one silently. The error names both candidates and points at the full-tag call that says which you mean.
+
+  `pluginAlias` / `pluginSlug` moved from the CLI into `@voltro/protocol` (and are re-exported from their old path) because the browser has to derive the same namespace the server registered, and a second copy on the client would be a second definition of the rule with nothing comparing them.
+
+  Also corrected, in the same seam: the list of plugins that deliberately do NOT accept `tables: false` read as exhaustive and omitted `_voltro_storage_grants`, which decides who may read an object. It is named now — along with the reason the option would not have reached it anyway (storage's tables are framework tables, not `extendSchema` contributions).
+- `voltro build` could not produce an api serve bundle on 0.53.0 or 0.54.0.
+
+  `@voltro/content`'s `get.ts` reaches its render pipeline through a dynamic `import('./serverLoad')`. That is deliberate — an unresolvable-at-build-time specifier is what keeps marked and the shiki grammars out of a consumer's client chunk graph. But `serverLoad` was not in the package's entry map, so nothing emitted `dist/serverLoad.js`, and `dist/index.js` shipped an import of a file beside it that was not there.
+
+  It resolved in this repo every time, because the workspace `exports` point at `src/` and `serverLoad.ts` sits next to `get.ts`. A consumer resolves `publishConfig.exports` to `dist/index.js`, and the same line cannot resolve. esbuild does not honour `@vite-ignore` — that is a vite directive — so the serve bundle refused to ship. The refusal was right; nothing had ever triggered it.
+
+  Two things worth knowing, both measured rather than reasoned:
+
+  - **The build was stopped by a dependency that contributes nothing to it.** An api serve bundle reaches `@voltro/content` through `serveCommand → dev → webDev → contentWiring`, and esbuild resolves before it tree-shakes. After shaking, the content pipeline is **0 bytes** of a 14.42 MB bundle. So an api app with no markdown anywhere was blocked by a markdown loader whose code it would never have carried. - **Shipping the file does not bloat anything.** Same measurement with the fixed package resolved as a consumer resolves it: 14.42 MB, content still 0 bytes. The dynamic import stays shaken away.
+
+  `scripts/check-dist-internal-specifiers.mjs` now bundles every emitted file of every publishable package — from `.publish/`, the tree users receive — with bare specifiers external, and fails if any relative specifier does not resolve. GATE-2 (`publint`) answers "does a declared subpath resolve"; this is one level below it, where `./serverLoad` lives.
+- **@voltro/client** — Three places still taught the pre-fix contract for a cold-start failure.
+
+  `SubscriptionFailed` gives it its own state — `loading: false`, `failed: true`, `error` non-optional — precisely so a component branching on `loading` alone cannot render a skeleton forever. But `SubscriptionMeta.error`'s doc comment and two docs pages still said the opposite ("leaves `loading` TRUE … check `error` to break out of it"), which is the sentence a deployment quoted back at us as evidence for the defect that had already been fixed.
+
+  A comment that predicts a trap the code no longer has is worse than no comment: it teaches the defensive shape as if it were still required, and it invites the reading that `loading` is unreliable. All four now describe the state that exists, with the old behaviour kept only as the history that explains why the field is there.
+- **@voltro/client, @voltro/web, @voltro/cli, @voltro/ui** — Four defects a real migration found, all of which passed `tsc` and a full test suite and only showed up against a running system.
+
+  **A server render derived a different form than the browser.** Nothing mounts a runtimes provider during SSR, so `useFormBinding` resolved its input schema from an EMPTY descriptor map: no fields, `required: false`. The browser then rendered the real ones and React discarded the subtree — "Hydration failed" on every server-rendered page carrying a bound form, with the diff pointing at a `Mui-required` class. `@voltro/client` keeps a process-global SSR descriptor registry now, and both boot paths fill it before rendering (`voltro dev` and `voltro start`, pinned as a parity test — a CLI module cannot import `@voltro/client`, so the call goes through `@voltro/web/ssr`, which both already load).
+
+  **A rejected `submit()` had nowhere to go.** A form calls it from an `onSubmit` handler that cannot await it, so the rejection surfaced as `Uncaught (in promise)` while the form sat there looking saved. `submit()` resolves `undefined` now and the failure is state: `state.submitError`, plus an optional `onError`. That covers a composed `onSubmit` whose follow-up write fails on its OWN mutation handle — a failure the binding never saw, and the common shape (create the row, then its first child).
+
+  **Undeclared fields went on the wire.** The binding validated the mapped input and then sent the object unchanged; the client decode ignores excess properties while the server has refused them since 0.37, so a form carrying anything beyond the mutation's input passed validation and was rejected on the wire with a message pointing at no field. The payload is restricted to the declared keys now — the rule the no-JS path already followed, so the two submits agree — with a dev warning naming what was dropped.
+
+  **`setValue` with an unchanged value produced a new `values`.** Every React state source is expected to no-op on that; this one did not, so an effect depending on `values` that re-set a field to the value it already held never settled ("Maximum update depth exceeded" on a form mirroring toggles out of a multi-select).
+- A plugin's dashboard panel no longer disappears when the app aliases the plugin.
+
+  `alias` moves `plugin.name`, and the inspect mount is derived from it, so `alias: 'inbox'` on notifications moved its panel to `/_voltro/inspect/plugins/inbox/...` while both dashboards ask for `/plugins/notifications/...` with the path compiled in. They live in other repositories and cannot follow. The field's own doc comment stated this as a cost you accept — in nine plugins, the protocol helper and the docs.
+
+  `makePluginInspectRegistry` now mounts each plugin's `inspectEndpoints` under its CANONICAL slug as well, in a second pass so an effective mount always wins the path. Added only where unambiguous: a base name carried by more than one installed plugin gets no shared mount, because showing either install under it would hand a dashboard the other one's rows under a name that looks right — the hazard `pluginTag` refuses rather than guesses. `/_voltro/inspect/plugins` now reports `baseName` and `inspectSlug` per plugin, which is how a caller reaches a specific install.
+- **@voltro/cli, @voltro/data-transfer** — **`voltro data restore --drill` failed every healthy backup of a real app.** It compared the restored schema's fingerprint against the backup stamp's `schemaFingerprint`, which records the SOURCE database's whole live schema — and the artifact never carries that schema. `pg_dump` / `mariadb-dump` exclude `_voltro_replace_in_progress` and `_voltro_data_transfers` on purpose, and the backup command opens a run row in the second one before it dumps, so on any database the framework has run against, the artifact is two tables short of the value it was being measured against. The drill answered:
+
+  FAIL — restored N table(s), but the schema fingerprint (…) does NOT match the backup's stamp (…). The restore did not reproduce the schema that was backed up — the artifact is inconsistent.
+
+  about an artifact that was exactly right. A drill exists to be wired to a CI cron, and one that is red on every healthy input gets switched off — taking its two real failures with it.
+
+  The stamp now carries a second value, `dumpFingerprint`: the same snapshot minus `dumpExcludedTables(dialect)` — what a faithful restore must reproduce. The drill compares against that. A stamp written before this field degrades to a PARTIAL pass that says so, rather than falling back to the value that produces the false failure. `dumpExcludedTables` is per-dialect because only two of the five backup paths carry an exclusion flag at all: the sqlite/turso copy and the mssql export carry everything, and subtracting a set from those would invent the same bug in the other direction.
+
+  **The drill also checks the one boot-fatal condition a schema comparison cannot see.** `voltro serve`'s boot gate reads the newest `_voltro_migration_plans` row and refuses with `prod-mismatch` when there is none — so a ledger table that restores with exactly the right columns and zero rows is a database no source tree can boot, and its fingerprint is identical to a healthy one's. That is now a FAIL with the reason named. A restored database with no ledger table at all is not a voltro-managed schema and is reported as such, not failed.
+
+  There is deliberately no app boot in the drill. The boot gate is a comparison, not a startup sequence, so the part that generalises is reachable with a SELECT; booting a fixture app instead would prove something about our fixture rather than about your backup.
+
+---
+
 ## [0.54.0] — 2026-08-27
 
 ### ⚠ BREAKING
@@ -114,9 +252,11 @@ _Changes staged for the next release accumulate here (rolled up from
   Each message is processed inside a `queue.consume` span whose parent is the incoming `traceparent`, parsed by the same `externalSpanFromTraceparent` the inbound-webhook path uses — so a malformed or all-zero header means "no parent" (a fresh root span), never a failed message. The span covers the whole message including retries and the dead-letter publish, and carries the OTel `messaging.*` attributes plus `voltro.queue.outcome`. The topic is an attribute, not part of the span name.
 
   Known limit, measured rather than assumed: a span opened from DETACHED work does not reach an OTLP exporter, because the framework's tracer is a `Layer` provided only inside the rpc server's scope. This is framework-wide (`cdcOut.deliver` and `plugin.<name>.schedule-fire` are the same shape) and is stated in the queue docs rather than implied away. The metrics are unaffected — the metric registry is a process global.
-- **@voltro/runtime, @voltro/voltro** — `setRowFilter({ …, tables: ['bookmarks', 'recentSearches'] })` — declare which tables your filter may narrow, and delta-resume survives everywhere else.
+- **@voltro/runtime, @voltro/voltro** — `setRowFilter({ …, tables: ['documents', 'comments'] })` — declare which tables your filter may narrow, and delta-resume survives everywhere else.
+
+  Delta-resume is excluded for a subscription whose row set is re-resolved per delivery: replaying deltas could serve rows the subject has since lost. But the question the runtime could ask was only "is a filter registered in this process?", so ONE registration disabled cheap reconnects for every subscription in the app, including every one whose source the filter could never narrow.
 
-  Delta-resume is excluded for a subscription whose row set is re-resolved per delivery: replaying deltas could serve rows the subject has since lost. But the question the runtime could ask was only "is a filter registered in this process?", so ONE registration disabled cheap reconnects for every subscription in the app — a deployment measured a filter narrowing 4 tables costing the feature on all 173 of their query descriptors, 55 of whose source tables the filter never touches.
+  It does not reach every query. A subscription only has a delta chain when its executor returns a DESCRIPTOR; one that returns a mapped value or a page envelope re-runs an opaque handler and emits snapshots, with or without a filter. `tables:` costs nothing and applies the moment such a query returns a builder — but the count it gives back is the count of descriptor-returning subscriptions, not of queries. The resume census on `/_voltro/inspect/subscriptions` reports which shape each of your queries took.
 
   The exclusion is per table now. A declared filter keeps resume for every subscription whose source is not in its set; an undeclared filter keeps today's conservative behaviour (the runtime cannot know which tables the predicate may reach, and "unknown" must read as "yes").
 

package/dist/index.d.ts

@@ -420,10 +420,12 @@ export declare interface FlagsPluginOptions {
      * `name` below: `alias` REPLACES the namespace, `name` distinguishes two
      * installations within it.
      *
-     * The cost, stated because nothing else states it: the local and cloud
-     * dashboards fetch this plugin's panel at the DEFAULT slug, so an aliased
-     * install keeps working while its dashboard panel 404s. Alias to escape a
-     * collision, not for taste.
+     * The dashboard panel follows: the plugin's inspect endpoints keep a mount
+     * under its CANONICAL name alongside the aliased one, so aliasing does not
+     * take the panel away. The one case it cannot cover is two installs of this
+     * plugin — one canonical name, two panels — which get no shared mount at
+     * all, on purpose. Read `inspectSlug` from `/_voltro/inspect/plugins` to
+     * reach a specific install.
      */
     readonly alias?: string;
     /**

package/dist/index.js

@@ -1,25 +1,25 @@
-import { evaluateDescriptor as e, evaluateVariantsDescriptor as t, flagsRpcClientImports as n } from "./rpc.js";
-import { i as r, n as i, r as a, t as o } from "./define-D9Eet7wA.js";
-import { FlagDisabled as s } from "./errors.js";
-import { Effect as c } from "effect";
-import { definePlugin as l, pluginInstanceName as u } from "@voltro/protocol";
-import { boolean as d, derivedRowId as f, id as p, integer as m, json as h, queryFor as g, registerRetention as _, retentionTtlMsFromEnv as v, table as y, text as b, timestamp as x } from "@voltro/database";
+import { BASE_NAME as e, evaluateDescriptor as t, evaluateVariantsDescriptor as n, flagsRpcClientImports as r } from "./rpc.js";
+import { i, n as a, r as o, t as s } from "./define-D9Eet7wA.js";
+import { FlagDisabled as c } from "./errors.js";
+import { Effect as l } from "effect";
+import { definePlugin as u, pluginInstanceName as d } from "@voltro/protocol";
+import { boolean as f, derivedRowId as p, id as m, integer as h, json as g, queryFor as _, registerRetention as v, retentionTtlMsFromEnv as y, table as b, text as x, timestamp as S } from "@voltro/database";
 //#region src/evaluate.ts
-var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
+var C = (e) => typeof e == "boolean" ? { enabled: e } : e, w = (e, t) => {
 	let n = 2166136261, r = `${e}:${t}`;
 	for (let e = 0; e < r.length; e++) n ^= r.charCodeAt(e), n = Math.imul(n, 16777619);
 	return n >>> 0;
-}, ee = (e, t) => C(e, t) % 100, w = (e, t) => C(`${e}:variant`, t) % 1e4, T = (e, t) => {
+}, T = (e, t) => w(e, t) % 100, ee = (e, t) => w(`${e}:variant`, t) % 1e4, E = (e, t) => {
 	if (e.subjectIds && !(t.id != null && e.subjectIds.includes(t.id)) || e.tenantIds && !(t.tenantId != null && e.tenantIds.includes(t.tenantId)) || e.subjectTypes && !(t.type != null && e.subjectTypes.includes(t.type))) return !1;
 	if (e.metadata) {
 		let n = t.metadata ?? {};
 		for (let [t, r] of Object.entries(e.metadata)) if (String(n[t]) !== r) return !1;
 	}
 	return !0;
-}, E = (e) => typeof e == "number" ? e : Date.parse(e), D = (e, t) => (e.rolloutBy === "tenant" ? t.tenantId : t.id) ?? "anon", O = (e, t) => {
-	if (e.activateAt != null && t < E(e.activateAt) || e.deactivateAt != null && t >= E(e.deactivateAt)) return { active: !1 };
+}, D = (e) => typeof e == "number" ? e : Date.parse(e), O = (e, t) => (e.rolloutBy === "tenant" ? t.tenantId : t.id) ?? "anon", k = (e, t) => {
+	if (e.activateAt != null && t < D(e.activateAt) || e.deactivateAt != null && t >= D(e.deactivateAt)) return { active: !1 };
 	if (e.ramp) {
-		let { from: n, to: r, startAt: i, endAt: a } = e.ramp, o = E(i), s = E(a);
+		let { from: n, to: r, startAt: i, endAt: a } = e.ramp, o = D(i), s = D(a);
 		if (t <= o) return {
 			active: !0,
 			rollout: n
@@ -35,71 +35,71 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		};
 	}
 	return { active: !0 };
-}, k = (e, t, n, r = Date.now()) => {
-	let i = S(t);
+}, A = (e, t, n, r = Date.now()) => {
+	let i = C(t);
 	if (i.enabled === !1) return !1;
 	let a;
 	if (i.schedule) {
-		let e = O(i.schedule, r);
+		let e = k(i.schedule, r);
 		if (!e.active) return !1;
 		a = e.rollout;
 	}
-	if (i.targeting && i.targeting.length > 0 && !i.targeting.some((e) => T(e, n))) return !1;
+	if (i.targeting && i.targeting.length > 0 && !i.targeting.some((e) => E(e, n))) return !1;
 	let o = a ?? i.rollout ?? 100;
 	if (o < 100 && o > 0) {
-		if (!(ee(e, D(i, n)) < o)) return !1;
+		if (!(T(e, O(i, n)) < o)) return !1;
 	} else if (o <= 0) return !1;
-	return i.variants && i.variants.length > 0 && i.offVariant != null ? A(e, i, n).name !== i.offVariant : !0;
-}, te = (e) => {
+	return i.variants && i.variants.length > 0 && i.offVariant != null ? M(e, i, n).name !== i.offVariant : !0;
+}, j = (e) => {
 	let t = e.reduce((e, t) => e + (t.weight ?? 1), 0) || e.length, n = 0;
 	return e.map((r, i) => (n += r.weight ?? 1, i === e.length - 1 ? 1e4 : Math.round(n / t * 1e4)));
-}, A = (e, t, n) => {
+}, M = (e, t, n) => {
 	let r = t.variants ?? [];
 	if (r.length === 0) throw Error(`flag "${e}" has no variants`);
-	let i = w(e, D(t, n)), a = te(r);
+	let i = ee(e, O(t, n)), a = j(r);
 	for (let e = 0; e < r.length; e++) if (i < a[e]) return r[e];
 	return r[r.length - 1];
-}, j = (e, t, n, r = Date.now()) => {
-	let i = S(t), a = k(e, t, n, r);
+}, N = (e, t, n, r = Date.now()) => {
+	let i = C(t), a = A(e, t, n, r);
 	if (!i.variants || i.variants.length === 0) return {
 		name: a ? "on" : "off",
 		value: a,
 		enabled: a
 	};
-	let o = A(e, i, n);
+	let o = M(e, i, n);
 	return {
 		name: o.name,
 		value: o.value,
 		enabled: a
 	};
-}, ne = (e, t, n = Date.now()) => {
+}, te = (e, t, n = Date.now()) => {
 	let r = {};
-	for (let [i, a] of Object.entries(e)) r[i] = k(i, a, t, n);
+	for (let [i, a] of Object.entries(e)) r[i] = A(i, a, t, n);
 	return r;
-}, re = (e, t, n = Date.now()) => {
+}, ne = (e, t, n = Date.now()) => {
 	let r = {};
-	for (let [i, a] of Object.entries(e)) r[i] = j(i, a, t, n);
+	for (let [i, a] of Object.entries(e)) r[i] = N(i, a, t, n);
 	return r;
-}, M = "_voltro_feature_flag_audit", N = "_voltro_feature_flags", P = y(N, {
-	id: p({ prefix: "flag" }),
-	key: b().unique(),
-	enabled: d().default(!0),
-	rollout: m().nullable(),
-	rolloutBy: b().nullable(),
-	targeting: h().nullable(),
-	variants: h().nullable(),
-	offVariant: b().nullable(),
-	schedule: h().nullable(),
-	description: b().nullable(),
-	updatedAt: x().default("now").onUpdate("now")
-}), F = y(M, {
-	id: p({ prefix: "flagaud" }),
-	flag: b(),
-	enabled: d(),
-	previousEnabled: d().nullable(),
-	actorId: b().nullable(),
-	at: x().default("now")
-}).index("byFlagAuditFlag", ["flag"]).index("byFlagAuditAt", ["at"]), I = (e, t) => {
+}, P = "_voltro_feature_flag_audit", F = "_voltro_feature_flags", I = b(F, {
+	id: m({ prefix: "flag" }),
+	key: x().unique(),
+	enabled: f().default(!0),
+	rollout: h().nullable(),
+	rolloutBy: x().nullable(),
+	targeting: g().nullable(),
+	variants: g().nullable(),
+	offVariant: x().nullable(),
+	schedule: g().nullable(),
+	description: x().nullable(),
+	updatedAt: S().default("now").onUpdate("now")
+}), L = b(P, {
+	id: m({ prefix: "flagaud" }),
+	flag: x(),
+	enabled: f(),
+	previousEnabled: f().nullable(),
+	actorId: x().nullable(),
+	at: S().default("now")
+}).index("byFlagAuditFlag", ["flag"]).index("byFlagAuditAt", ["at"]), re = (e, t) => {
 	let n = { ...e };
 	for (let e of t) {
 		let t = {
@@ -115,7 +115,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		n[e.key] = t;
 	}
 	return n;
-}, L = new class {
+}, R = new class {
 	flags = {};
 	set(e) {
 		this.flags = e;
@@ -126,19 +126,19 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 	get(e) {
 		return this.flags[e];
 	}
-}(), R = (e, t) => z(e, t) !== null, z = (e, t) => {
-	let n = L.get(e);
+}(), z = (e, t) => B(e, t) !== null, B = (e, t) => {
+	let n = R.get(e);
 	if (n === void 0) return null;
-	let r = S(n), i = r.enabled !== !1;
-	return L.set({
-		...L.all(),
+	let r = C(n), i = r.enabled !== !1;
+	return R.set({
+		...R.all(),
 		[e]: {
 			...r,
 			enabled: t
 		}
 	}), i;
-}, B = (e) => Object.entries(e).map(([e, t]) => {
-	let n = S(t);
+}, V = (e) => Object.entries(e).map(([e, t]) => {
+	let n = C(t);
 	return {
 		key: e,
 		enabled: n.enabled !== !1,
@@ -148,7 +148,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		description: n.description
 	};
 }), ie = (e, t) => {
-	let n = S(t);
+	let n = C(t);
 	return {
 		key: e,
 		enabled: n.enabled !== !1,
@@ -161,7 +161,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		description: n.description ?? null
 	};
 }, ae = (e) => ({
-	loadOverrides: async () => (await e.query(g(P).descriptor)).map((e) => ({
+	loadOverrides: async () => (await e.query(_(I).descriptor)).map((e) => ({
 		key: String(e.key),
 		enabled: e.enabled === !0 || e.enabled === 1,
 		rollout: e.rollout == null ? null : Number(e.rollout),
@@ -174,7 +174,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 	})),
 	upsertOverride: async (t) => {
 		let n = {
-			id: f("flag", t.key),
+			id: p("flag", t.key),
 			key: t.key,
 			enabled: t.enabled,
 			rollout: t.rollout,
@@ -186,7 +186,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 			description: t.description,
 			updatedAt: /* @__PURE__ */ new Date()
 		};
-		await e.upsert(N, n, { conflictColumns: ["key"] });
+		await e.upsert(F, n, { conflictColumns: ["key"] });
 	}
 }), oe = (e) => ({
 	flag: String(e.flag),
@@ -196,7 +196,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 	at: e.at instanceof Date ? e.at : new Date(String(e.at))
 }), se = (e) => ({
 	record: async (t) => {
-		await e.insert(M, {
+		await e.insert(P, {
 			id: `flagaud_${t.at.getTime()}_${Math.random().toString(36).slice(2, 10)}`,
 			flag: t.flag,
 			enabled: t.enabled,
@@ -206,12 +206,12 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		});
 	},
 	list: async (t) => {
-		let n = g(F).orderBy("at", "desc");
+		let n = _(L).orderBy("at", "desc");
 		t?.limit != null && (n = n.limit(t.limit));
 		let r = (await e.query(n.descriptor)).map(oe);
 		return t?.flag == null ? r : r.filter((e) => e.flag === t.flag);
 	}
-}), V = (e, t) => {
+}), H = (e, t) => {
 	let n = new Map(t.map((e) => [e.name, e])), r = [];
 	for (let t of e) {
 		let e = t.experiment;
@@ -250,24 +250,24 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		}
 	}
 	return r;
-}, H = (e, t) => {
-	let n = V(e, t);
+}, U = (e, t) => {
+	let n = H(e, t);
 	if (n.length === 0) return;
 	let r = n.map((e) => `  · flag "${e.flag}" → experiment "${e.experiment}": ${e.problem}`);
 	throw Error(`@voltro/plugin-flags: ${n.length} flag→experiment link problem(s):\n${r.join("\n")}`);
-}, U = 864e5, W = (e) => typeof e == "number" ? e : Date.parse(e), G = (e, t) => {
-	let n = S(e);
+}, W = 864e5, G = (e) => typeof e == "number" ? e : Date.parse(e), K = (e, t) => {
+	let n = C(e);
 	if (n.enabled === !1) return {
 		shape: "constantOff",
 		reason: "enabled: false — resolves false for every caller"
 	};
 	if (n.schedule) {
 		let { activateAt: e, deactivateAt: r } = n.schedule;
-		if (r != null && t >= W(r)) return {
+		if (r != null && t >= G(r)) return {
 			shape: "expired",
 			reason: `schedule.deactivateAt (${String(r)}) has passed — the flag can never be on again`
 		};
-		if (e != null && t < W(e)) return {
+		if (e != null && t < G(e)) return {
 			shape: "notYetActive",
 			reason: `schedule.activateAt (${String(e)}) is in the future — pending, not dead`
 		};
@@ -277,7 +277,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		shape: "constantOff",
 		reason: `rollout: ${r} — nobody is in the rollout`
 	};
-	let i = (n.targeting?.length ?? 0) > 0, a = (n.variants?.length ?? 0) > 1, o = n.schedule !== void 0 && (n.schedule.ramp !== void 0 || n.schedule.deactivateAt != null && t < W(n.schedule.deactivateAt));
+	let i = (n.targeting?.length ?? 0) > 0, a = (n.variants?.length ?? 0) > 1, o = n.schedule !== void 0 && (n.schedule.ramp !== void 0 || n.schedule.deactivateAt != null && t < G(n.schedule.deactivateAt));
 	return r >= 100 && !i && !a && !o ? {
 		shape: "constantOn",
 		reason: "rollout 100 with no targeting, no variants and no live schedule — resolves true for every caller"
@@ -290,14 +290,14 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 			o ? "a live schedule" : void 0
 		].filter((e) => e !== void 0).join(", ")})`
 	};
-}, K = [
+}, ce = [
 	"Reachability is not decided. \"Not evaluated since <date>\" is a measurement; \"this code path is dead\" is not decidable in general. A seasonal flag, a flag behind a route nobody visited this month, and a flag whose last call site was deleted are indistinguishable from here.",
 	"Only SERVER-side reads are counted as use: isFlagEnabled / requireFlag / flagValue and a gatedBy interception. A flag consulted only in the browser via useFlag() / useFlagValue() reads from the bulk set the server already sent, so it never reaches this report as a named read.",
 	"A \"bulk\" observation means the flag was INCLUDED in a flags.evaluate / flags.variants response. It does not mean any client read that key — one useFlags() poll evaluates the whole registry.",
 	"The window is bounded by retention (see coverage.retentionDays). Nothing older is evidence: a flag last read BEFORE the window has no observation at all and reads \"neverObserved\", which is exactly what a flag declared this morning reads.",
 	"\"neverObserved\" is not a removal candidate. A flag declared yesterday and a flag abandoned last year produce the identical row; only a flag that WAS observed and then stopped (\"stale\") is proven unused."
-], ce = (e) => {
-	let t = e.now ?? Date.now(), n = e.staleAfterDays, r = t - n * U, i = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Map(), o;
+], le = (e) => {
+	let t = e.now ?? Date.now(), n = e.staleAfterDays, r = t - n * W, i = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Map(), o;
 	for (let t of e.usage) {
 		let e = t.lastAt.getTime();
 		if (!Number.isFinite(e)) continue;
@@ -305,7 +305,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		let n = t.source === "bulk" ? a : i, r = n.get(t.flag);
 		(r === void 0 || e > r) && n.set(t.flag, e);
 	}
-	let s = o === void 0 ? 0 : Math.floor((t - o) / U);
+	let s = o === void 0 ? 0 : Math.floor((t - o) / W);
 	return {
 		coverage: {
 			tracking: e.tracking,
@@ -315,7 +315,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 			staleAfterDays: n
 		},
 		findings: Object.entries(e.flags).map(([o, c]) => {
-			let { shape: l, reason: u } = G(c, t), d = i.get(o), f = a.get(o), p = [u], m;
+			let { shape: l, reason: u } = K(c, t), d = i.get(o), f = a.get(o), p = [u], m;
 			e.tracking ? d !== void 0 && d >= r ? (m = "evaluated", p.push(`last server-side read ${new Date(d).toISOString()}`)) : d === void 0 ? (m = "neverObserved", p.push(s > 0 ? `no server-side read in the ${s}-day observation window` : "no server-side read observed yet (the observation window is empty)"), f !== void 0 && p.push("the flag WAS delivered to a client in a bulk flags.evaluate response — which does not prove it was read")) : (m = "stale", p.push(`last server-side read ${new Date(d).toISOString()}, more than ${n} day(s) ago, over an observation window of ${s} day(s)`)) : (m = "untracked", p.push("evaluation tracking is off — no usage evidence exists for this deployment"));
 			let h = l === "constantOn" || l === "constantOff" || l === "expired";
 			return h && p.push("the definition alone makes this flag a constant — it selects nothing"), {
@@ -330,23 +330,23 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 				why: p
 			};
 		}),
-		limits: K
+		limits: ce
 	};
-}, q = "_voltro_feature_flag_usage", J = y(q, {
-	id: p({ prefix: "flagusg" }),
-	flag: b(),
-	day: b(),
-	source: b(),
-	lastAt: x()
+}, q = "_voltro_feature_flag_usage", J = b(q, {
+	id: m({ prefix: "flagusg" }),
+	flag: x(),
+	day: x(),
+	source: x(),
+	lastAt: S()
 }).unique([
 	"flag",
 	"day",
 	"source"
-]).index("byFlagUsageLastAt", ["lastAt"]).index("byFlagUsageFlag", ["flag"]), le = (e) => e.toISOString().slice(0, 10), ue = (e) => {
+]).index("byFlagUsageLastAt", ["lastAt"]).index("byFlagUsageFlag", ["flag"]), ue = (e) => e.toISOString().slice(0, 10), de = (e) => {
 	let t = 2166136261;
 	for (let n = 0; n < e.length; n++) t ^= e.charCodeAt(n), t = Math.imul(t, 16777619);
 	return (t >>> 0).toString(16).padStart(8, "0");
-}, de = (e, t, n) => `flagusg_${t.replace(/-/g, "")}_${n === "targeted" ? "t" : "b"}_${ue(e)}`, Y = new class {
+}, fe = (e, t, n) => `flagusg_${t.replace(/-/g, "")}_${n === "targeted" ? "t" : "b"}_${de(e)}`, Y = new class {
 	on = !1;
 	pending = /* @__PURE__ */ new Map();
 	liveCounts = /* @__PURE__ */ new Map();
@@ -384,12 +384,12 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 	reset() {
 		this.on = !1, this.pending.clear(), this.liveCounts.clear();
 	}
-}(), X = (e, t, n) => Y.record(e, t, n), fe = (e) => e === "bulk" ? "bulk" : "targeted", pe = (e) => ({
+}(), X = (e, t, n) => Y.record(e, t, n), pe = (e) => e === "bulk" ? "bulk" : "targeted", me = (e) => ({
 	upsertMany: async (t) => {
 		for (let n of t) {
-			let t = le(n.lastAt);
+			let t = ue(n.lastAt);
 			await e.upsert(q, {
-				id: de(n.flag, t, n.source),
+				id: fe(n.flag, t, n.source),
 				flag: n.flag,
 				day: t,
 				source: n.source,
@@ -401,13 +401,13 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 			] });
 		}
 	},
-	load: async () => (await e.query(g(J).descriptor)).map((e) => ({
+	load: async () => (await e.query(_(J).descriptor)).map((e) => ({
 		flag: String(e.flag),
 		day: String(e.day),
-		source: fe(e.source),
+		source: pe(e.source),
 		lastAt: e.lastAt instanceof Date ? e.lastAt : new Date(String(e.lastAt))
 	}))
-}), me = 3e5, he = (e) => {
+}), he = 3e5, ge = (e) => {
 	let t = e.intervalMs ?? 3e5, n = !1, r = async () => {
 		let t = Y.drain();
 		if (t.length !== 0) try {
@@ -431,9 +431,9 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 			n || (n = !0, clearInterval(i), await r());
 		}
 	};
-}, ge = (e = process.env, t = 90) => {
-	let n = v(e.VOLTRO_FLAG_USAGE_TTL_HOURS, 24 * t);
-	return _({
+}, _e = (e = process.env, t = 90) => {
+	let n = y(e.VOLTRO_FLAG_USAGE_TTL_HOURS, 24 * t);
+	return v({
 		table: q,
 		timeColumn: "lastAt",
 		source: "plugin",
@@ -441,88 +441,88 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		envVar: "VOLTRO_FLAG_USAGE_TTL_HOURS"
 	}), n;
 }, Z = (e) => "request" in e && e.request?.subject || "subject" in e && e.subject || {}, Q = (e, t) => {
-	let n = L.get(t);
-	return X(t, "targeted"), n !== void 0 && k(t, n, Z(e));
-}, _e = (e, t) => Q(e, t) ? c.void : c.fail(new s({ flag: t })), ve = (e, t) => {
-	let n = L.get(t.key);
-	return X(t.key, "targeted"), n === void 0 ? t.defaultValue : r(t, j(t.key, n, Z(e)));
-}, ye = (e, t) => {
-	let n = L.get(t.key);
-	return X(t.key, "targeted"), n === void 0 ? null : j(t.key, n, Z(e)).name;
-}, be = (e, t) => e === t || e.startsWith("/") && e.endsWith("/") && new RegExp(e.slice(1, -1)).test(t), $ = "@voltro/plugin-flags", xe = (r = {}) => {
-	let a = r.gatedBy ?? {}, o = u({
+	let n = R.get(t);
+	return X(t, "targeted"), n !== void 0 && A(t, n, Z(e));
+}, ve = (e, t) => Q(e, t) ? l.void : l.fail(new c({ flag: t })), ye = (e, t) => {
+	let n = R.get(t.key);
+	return X(t.key, "targeted"), n === void 0 ? t.defaultValue : i(t, N(t.key, n, Z(e)));
+}, be = (e, t) => {
+	let n = R.get(t.key);
+	return X(t.key, "targeted"), n === void 0 ? null : N(t.key, n, Z(e)).name;
+}, xe = (e, t) => e === t || e.startsWith("/") && e.endsWith("/") && new RegExp(e.slice(1, -1)).test(t), $ = e, Se = (e = {}) => {
+	let i = e.gatedBy ?? {}, o = d({
 		base: $,
-		alias: r.alias,
-		instance: r.name
-	}), d = r.typedFlags ?? [], f = /* @__PURE__ */ new Map();
-	for (let e of d) {
-		if (f.has(e.key)) throw Error(`${$}: two typedFlags declare the key ${JSON.stringify(e.key)}`);
-		if (r.flags?.[e.key] !== void 0) throw Error(`${$}: ${JSON.stringify(e.key)} is declared BOTH in \`flags\` and in \`typedFlags\`. One key, one declaration — the typed one would otherwise be silently overwritten by the untyped baseline.`);
-		f.set(e.key, e);
+		alias: e.alias,
+		instance: e.name
+	}), s = e.typedFlags ?? [], f = /* @__PURE__ */ new Map();
+	for (let t of s) {
+		if (f.has(t.key)) throw Error(`${$}: two typedFlags declare the key ${JSON.stringify(t.key)}`);
+		if (e.flags?.[t.key] !== void 0) throw Error(`${$}: ${JSON.stringify(t.key)} is declared BOTH in \`flags\` and in \`typedFlags\`. One key, one declaration — the typed one would otherwise be silently overwritten by the untyped baseline.`);
+		f.set(t.key, t);
 	}
-	d.some((e) => e.experiment !== void 0) && H(d, r.experiments ?? []);
-	let p = { ...r.flags ?? {} };
-	for (let e of d) p[e.key] = e.definition;
-	let m = r.store === "postgres", h, g, _, v, y = [], b = r.usage ?? {}, x = b.track ?? m;
+	s.some((e) => e.experiment !== void 0) && U(s, e.experiments ?? []);
+	let p = { ...e.flags ?? {} };
+	for (let e of s) p[e.key] = e.definition;
+	let m = e.store === "postgres", h, g, _, v, y = [], b = e.usage ?? {}, x = b.track ?? m;
 	if (x && !m) throw Error(`${$}: usage.track requires store: 'postgres' — there is nowhere to record an evaluation on the memory tier, and a dead-flag report that silently observed nothing is exactly the defect it exists to find.`);
 	let S = b.staleAfterDays ?? 30, C = b.retentionDays ?? 90;
 	if (S > C) throw Error(`${$}: usage.staleAfterDays (${S}) exceeds usage.retentionDays (${C}), so the observation window can never be long enough to prove a flag stale and every verdict would be withheld.`);
-	let ee = (e) => {
-		let t = I(p, e), n = [];
+	let w = (e) => {
+		let t = re(p, e), n = [];
 		for (let [e, r] of f) {
-			let a = t[e];
-			if (a === void 0) continue;
-			let o = i(r, typeof a == "boolean" ? { enabled: a } : a);
+			let i = t[e];
+			if (i === void 0) continue;
+			let o = a(r, typeof i == "boolean" ? { enabled: i } : i);
 			o.ok || (n.push(o.refusal), t[e] = r.definition);
 		}
-		y = n, L.set(t);
-	}, w = async () => {
-		h && ee(await h.loadOverrides());
-	}, T = (e) => {
-		if (a[e] !== void 0) return a[e];
-		for (let [t, n] of Object.entries(a)) if (t !== e && be(t, e)) return n;
+		y = n, R.set(t);
+	}, T = async () => {
+		h && w(await h.loadOverrides());
+	}, ee = (e) => {
+		if (i[e] !== void 0) return i[e];
+		for (let [t, n] of Object.entries(i)) if (t !== e && xe(t, e)) return n;
 	}, E = (e, t) => {
-		let n = T(t.tag);
-		return n === void 0 || Q({ subject: t.subject }, n) ? e : c.fail(new s({ flag: n }));
-	}, D = Object.keys(a).length > 0, O = (e) => {
+		let n = ee(t.tag);
+		return n === void 0 || Q({ subject: t.subject }, n) ? e : l.fail(new c({ flag: n }));
+	}, D = Object.keys(i).length > 0, O = (e) => {
 		for (let t of e) X(t, "bulk");
 	}, k = {
-		...e,
+		...t,
 		description: "Resolve every feature flag for the calling subject.",
-		execute: (e, t) => c.sync(() => {
-			let e = L.all();
-			return O(Object.keys(e)), ne(e, t.request.subject ?? {});
+		execute: (e, t) => l.sync(() => {
+			let e = R.all();
+			return O(Object.keys(e)), te(e, t.request.subject ?? {});
 		})
-	}, te = {
-		...t,
+	}, A = {
+		...n,
 		description: "Resolve every feature flag to its served variant for the calling subject.",
-		execute: (e, t) => c.sync(() => {
-			let e = L.all();
-			return O(Object.keys(e)), re(e, t.request.subject ?? {});
+		execute: (e, t) => l.sync(() => {
+			let e = R.all();
+			return O(Object.keys(e)), ne(e, t.request.subject ?? {});
 		})
-	}, A = (e) => ({
+	}, j = (e) => ({
 		kind: "json",
 		data: e
-	}), j = (e, t) => ({
+	}), M = (e, t) => ({
 		kind: "json",
 		status: e,
 		data: { error: t }
-	}), M = async () => {
+	}), N = async () => {
 		let e = [];
 		if (x && _) try {
 			e = await _.load();
 		} catch {
 			e = [];
 		}
-		return ce({
-			flags: L.all(),
+		return le({
+			flags: R.all(),
 			usage: e,
 			tracking: x,
 			liveCounts: Y.liveTargetedCounts(),
 			staleAfterDays: S,
 			retentionDays: C
 		});
-	}, N = () => {
+	}, P = () => {
 		let e = {};
 		for (let [t, n] of f) e[t] = {
 			valueType: n.valueType,
@@ -530,17 +530,17 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 			experiment: n.experiment ?? null
 		};
 		return e;
-	}, R = [
+	}, F = [
 		{
 			method: "GET",
 			path: "/list",
 			description: "Every resolved flag (key, enabled, rollout, description) plus the dead-flag lifecycle report: per-flag shape + usage verdict, the observation coverage window, and the limits of what the report can prove.",
-			handler: () => c.promise(async () => {
-				let e = await M();
-				return A({
-					flags: B(L.all()),
+			handler: () => l.promise(async () => {
+				let e = await N();
+				return j({
+					flags: V(R.all()),
 					lifecycle: e,
-					typed: N(),
+					typed: P(),
 					overrideRefusals: y
 				});
 			})
@@ -549,26 +549,26 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 			method: "POST",
 			path: "/toggle",
 			description: "Flip a flag's kill-switch on/off (live registry; durable on the postgres tier). Logs an audit row.",
-			handler: (e) => c.gen(function* () {
+			handler: (e) => l.gen(function* () {
 				let t;
 				try {
 					t = JSON.parse(e.body || "{}");
 				} catch {
-					return j(400, "invalid JSON body");
+					return M(400, "invalid JSON body");
 				}
-				if (!t.key || typeof t.enabled != "boolean") return j(400, "key (string) + enabled (boolean) required");
-				let n = z(t.key, t.enabled);
-				if (n === null) return j(404, `unknown flag "${t.key}"`);
-				let r = h ? L.get(t.key) : void 0;
-				return h && r !== void 0 && (yield* c.promise(() => h.upsertOverride(ie(t.key, r)))), g && (yield* c.promise(() => g.record({
+				if (!t.key || typeof t.enabled != "boolean") return M(400, "key (string) + enabled (boolean) required");
+				let n = B(t.key, t.enabled);
+				if (n === null) return M(404, `unknown flag "${t.key}"`);
+				let r = h ? R.get(t.key) : void 0;
+				return h && r !== void 0 && (yield* l.promise(() => h.upsertOverride(ie(t.key, r)))), g && (yield* l.promise(() => g.record({
 					flag: t.key,
 					enabled: t.enabled,
 					previousEnabled: n,
 					actorId: typeof t.actor == "string" ? t.actor : null,
 					at: /* @__PURE__ */ new Date()
-				}))), A({
+				}))), j({
 					ok: !0,
-					flags: B(L.all())
+					flags: V(R.all())
 				});
 			})
 		},
@@ -576,16 +576,16 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 			method: "GET",
 			path: "/audit",
 			description: "The kill-switch flip audit trail, newest-first. `?flag=<key>` filters; `?limit=<n>` caps (postgres tier only).",
-			handler: (e) => c.gen(function* () {
-				if (!g) return A({
+			handler: (e) => l.gen(function* () {
+				if (!g) return j({
 					audit: [],
 					note: "audit trail requires store: \"postgres\""
 				});
-				let t = new URL(e.url, "http://local"), n = t.searchParams.get("flag"), r = t.searchParams.get("limit"), i = r != null && Number.isFinite(Number(r)) ? Number(r) : 100, a = yield* c.promise(() => g.list({
+				let t = new URL(e.url, "http://local"), n = t.searchParams.get("flag"), r = t.searchParams.get("limit"), i = r != null && Number.isFinite(Number(r)) ? Number(r) : 100, a = yield* l.promise(() => g.list({
 					...n == null ? {} : { flag: n },
 					limit: i
 				}));
-				return A({ audit: a.map((e) => ({
+				return j({ audit: a.map((e) => ({
 					flag: e.flag,
 					enabled: e.enabled,
 					previousEnabled: e.previousEnabled,
@@ -594,7 +594,7 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 				})) });
 			})
 		}
-	], oe = [
+	], z = [
 		...D ? [
 			"rpc:intercept:mutation",
 			"rpc:intercept:query",
@@ -604,16 +604,16 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 		"inspect:read",
 		"inspect:write"
 	];
-	return l({
+	return u({
 		name: o,
 		baseName: $,
 		description: "Feature flags — targeting, % rollout, kill-switch, declarative gating + client evaluation.",
-		permissions: oe,
-		routes: [k, te],
-		rpcClientDescriptors: n,
-		inspectEndpoints: R,
+		permissions: z,
+		routes: [k, A],
+		rpcClientDescriptors: r,
+		inspectEndpoints: F,
 		errorSchemas: [{
-			schema: s,
+			schema: c,
 			import: {
 				module: "@voltro/plugin-flags/errors",
 				name: "FlagDisabled"
@@ -625,38 +625,38 @@ var S = (e) => typeof e == "boolean" ? { enabled: e } : e, C = (e, t) => {
 			interceptAction: E
 		} : {},
 		...m ? { extendSchema: { tables: x ? [
-			P,
-			F,
+			I,
+			L,
 			J
-		] : [P, F] } } : {},
+		] : [I, L] } } : {},
 		...m ? { bindDataStore: (e) => {
-			h = ae(e), g = se(e), x && (_ = pe(e));
+			h = ae(e), g = se(e), x && (_ = me(e));
 		} } : {},
-		...m ? { onChangeEvent: (e) => e.table === "_voltro_feature_flags" ? c.tryPromise(() => w()) : c.void } : {},
-		onActivate: (e) => c.gen(function* () {
-			L.set(p), m && h && (yield* c.promise(w));
-			let t;
-			x && _ && (t = ge(process.env, C), Y.enable(), v = he({
+		...m ? { onChangeEvent: (e) => e.table === "_voltro_feature_flags" ? l.tryPromise(() => T()) : l.void } : {},
+		onActivate: (t) => l.gen(function* () {
+			R.set(p), m && h && (yield* l.promise(T));
+			let n;
+			x && _ && (n = _e(process.env, C), Y.enable(), v = ge({
 				store: _,
 				intervalMs: b.flushIntervalMs ?? 3e5,
-				log: { warn: (t, n) => e.logger.warn(t, n) }
+				log: { warn: (e, n) => t.logger.warn(e, n) }
 			}));
-			for (let t of y) e.logger.warn("feature flag override REFUSED — the code-declared definition stands", {
-				flag: t.key,
-				reason: t.reason
+			for (let e of y) t.logger.warn("feature flag override REFUSED — the code-declared definition stands", {
+				flag: e.key,
+				reason: e.reason
 			});
-			e.logger.info("feature flags active", {
+			t.logger.info("feature flags active", {
 				count: Object.keys(p).length,
 				typed: f.size,
-				gated: Object.keys(a).length,
-				store: r.store ?? "memory",
-				usage: x ? `tracking (stale after ${S}d, observations kept ${Math.round((t ?? 0) / 864e5)}d)` : "off — no dead-flag evidence is collected"
+				gated: Object.keys(i).length,
+				store: e.store ?? "memory",
+				usage: x ? `tracking (stale after ${S}d, observations kept ${Math.round((n ?? 0) / 864e5)}d)` : "off — no dead-flag evidence is collected"
 			});
 		}),
-		onDeactivate: () => c.promise(async () => {
-			await v?.stop(), v = void 0, Y.disable(), L.set({});
+		onDeactivate: () => l.promise(async () => {
+			await v?.stop(), v = void 0, Y.disable(), R.set({});
 		})
 	});
 };
 //#endregion
-export { me as DEFAULT_FLAG_USAGE_FLUSH_MS, K as FLAG_LIFECYCLE_LIMITS, q as FLAG_USAGE_TABLE, s as FlagDisabled, H as assertFlagExperimentLinks, V as checkFlagExperimentLinks, G as classifyShape, pe as dataStoreFlagUsageStore, o as defineFlag, B as describeFlags, ne as evaluateAll, re as evaluateAllVariants, k as evaluateFlag, O as evaluateSchedule, j as evaluateVariant, P as featureFlagsTable, F as flagAuditTable, ce as flagLifecycleReport, L as flagRegistry, Y as flagUsageBuffer, de as flagUsageRowId, J as flagUsageTable, ve as flagValue, ye as flagVariant, xe as flagsPlugin, z as flipFlagEnabled, i as gateOverride, Q as isFlagEnabled, a as isTypedFlag, I as mergeOverrides, X as recordFlagEvaluation, ge as registerFlagUsageRetention, _e as requireFlag, A as resolveVariant, R as setFlagEnabled, he as startFlagUsageFlush, S as toDefinition, r as typedValueOf, le as utcDay };
+export { he as DEFAULT_FLAG_USAGE_FLUSH_MS, ce as FLAG_LIFECYCLE_LIMITS, q as FLAG_USAGE_TABLE, c as FlagDisabled, U as assertFlagExperimentLinks, H as checkFlagExperimentLinks, K as classifyShape, me as dataStoreFlagUsageStore, s as defineFlag, V as describeFlags, te as evaluateAll, ne as evaluateAllVariants, A as evaluateFlag, k as evaluateSchedule, N as evaluateVariant, I as featureFlagsTable, L as flagAuditTable, le as flagLifecycleReport, R as flagRegistry, Y as flagUsageBuffer, fe as flagUsageRowId, J as flagUsageTable, ye as flagValue, be as flagVariant, Se as flagsPlugin, B as flipFlagEnabled, a as gateOverride, Q as isFlagEnabled, o as isTypedFlag, re as mergeOverrides, X as recordFlagEvaluation, _e as registerFlagUsageRetention, ve as requireFlag, M as resolveVariant, z as setFlagEnabled, ge as startFlagUsageFlush, C as toDefinition, i as typedValueOf, ue as utcDay };

package/dist/rpc.d.ts

@@ -2,6 +2,18 @@ import { PluginRpcClientDescriptor } from '@voltro/protocol';
 import { QueryProcedureDescriptor } from '@voltro/protocol';
 import { Schema } from 'effect';
 
+/**
+ * The plugin's canonical package name — the key an app's `alias` is recorded
+ * under, and what `./web`'s hooks resolve their tags through.
+ *
+ * It lives in this BROWSER-SAFE module rather than in `index.ts` because both
+ * halves need it and only one of them may reach the server graph: `index.ts`
+ * passes it to `pluginInstanceName` / `baseName`, and `web.ts` passes it to
+ * `pluginTag`. A second copy in `web.ts` would be a second definition of the
+ * plugin's identity with nothing comparing them.
+ */
+export declare const BASE_NAME = "@voltro/plugin-flags";
+
 export declare const evaluateDescriptor: QueryProcedureDescriptor<"flags.evaluate", Schema.Struct<{}>, Schema.Record$<typeof Schema.String, typeof Schema.Boolean>, typeof Schema.Never>;
 
 export declare const evaluateVariantsDescriptor: QueryProcedureDescriptor<"flags.variants", Schema.Struct<{}>, Schema.Record$<typeof Schema.String, Schema.Struct<{

package/dist/rpc.js

@@ -1,7 +1,7 @@
 import { Schema as e } from "effect";
 import { defineQuery as t } from "@voltro/protocol";
 //#region src/rpc.ts
-var n = t({
+var n = "@voltro/plugin-flags", r = t({
 	name: "flags.evaluate",
 	input: e.Struct({}),
 	output: e.Record({
@@ -9,19 +9,19 @@ var n = t({
 		value: e.Boolean
 	}),
 	openAccess: "per-caller flag evaluation: returns only the values computed for the calling subject; every session (incl. anonymous) evaluates its own flags"
-}), r = e.Struct({
+}), i = e.Struct({
 	name: e.String,
 	value: e.Unknown,
 	enabled: e.Boolean
-}), i = t({
+}), a = t({
 	name: "flags.variants",
 	input: e.Struct({}),
 	output: e.Record({
 		key: e.String,
-		value: r
+		value: i
 	}),
 	openAccess: "per-caller variant resolution: returns only the variants served to the calling subject; every session (incl. anonymous) evaluates its own flags"
-}), a = [{
+}), o = [{
 	tag: "flags.evaluate",
 	kind: "query",
 	import: {
@@ -37,4 +37,4 @@ var n = t({
 	}
 }];
 //#endregion
-export { n as evaluateDescriptor, i as evaluateVariantsDescriptor, a as flagsRpcClientImports };
+export { n as BASE_NAME, r as evaluateDescriptor, a as evaluateVariantsDescriptor, o as flagsRpcClientImports };

package/dist/web.js

@@ -1,12 +1,14 @@
-import { i as e } from "./define-D9Eet7wA.js";
-import { useSubscription as t } from "@voltro/client";
+import { BASE_NAME as e } from "./rpc.js";
+import { i as t } from "./define-D9Eet7wA.js";
+import { pluginTag as n } from "@voltro/protocol";
+import { useSubscription as r } from "@voltro/client";
 //#region src/web.ts
-var n = (e = "app") => {
-	let { data: n } = t(e, "flags.evaluate", {});
-	return n ?? {};
-}, r = (e, t = "app") => n(t)[e] === !0, i = (e = "app") => {
-	let { data: n } = t(e, "flags.variants", {});
-	return n ?? {};
-}, a = (e, t = "app") => i(t)[e], o = (t, n = "app") => e(t, i(n)[t.key]);
+var i = (t) => n(e, t), a = (e = "app") => {
+	let { data: t } = r(e, i("evaluate"), {});
+	return t ?? {};
+}, o = (e, t = "app") => a(t)[e] === !0, s = (e = "app") => {
+	let { data: t } = r(e, i("variants"), {});
+	return t ?? {};
+}, c = (e, t = "app") => s(t)[e], l = (e, n = "app") => t(e, s(n)[e.key]);
 //#endregion
-export { r as useFlag, o as useFlagValue, n as useFlags, a as useVariant, i as useVariants };
+export { o as useFlag, l as useFlagValue, a as useFlags, c as useVariant, s as useVariants };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-flags",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "Feature flags — per-subject / per-tenant targeting, deterministic % rollouts, kill-switch. Gate mutations/queries/actions declaratively or guard in-handler; evaluate flags client-side for UI gating. Config-as-code (memory) or runtime-toggleable (postgres).",
   "keywords": [
     "voltro",
@@ -48,10 +48,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.54.0",
-    "@voltro/database": "0.54.0",
-    "@voltro/logger": "0.54.0",
-    "@voltro/protocol": "0.54.0"
+    "@voltro/client": "0.55.0",
+    "@voltro/database": "0.55.0",
+    "@voltro/logger": "0.55.0",
+    "@voltro/protocol": "0.55.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"