@voltro/protocol 0.53.0 → 0.55.0

package/dist/index.d.ts

@@ -696,6 +696,10 @@ export declare interface ClientTarget {
      *  `path` is set. 2nd arg is the optimistic id (insert) or the current item
      *  (update) — `unknown` here since the erased view spans both; normalize casts. */
     readonly shapeItem?: ((input: Record<string, unknown>, currentOrOptimisticId: unknown) => Record<string, unknown>) | undefined;
+    /** Declared junction relations (see {@link TargetRelations}). Pure DATA —
+     *  three strings per relation — so it crosses to the browser unchanged and
+     *  drives junction auto-optimistic there. */
+    readonly relations?: TargetRelations | undefined;
 }
 
 export declare const composeAuthStrategies: (strategies: ReadonlyArray<AuthStrategy>, options?: {
@@ -2655,6 +2659,18 @@ export declare type PendingApproval = Schema.Schema.Type<typeof PendingApproval>
  */
 export declare type PluginActivateHook = (ctx: PluginLifecycleContext) => Effect.Effect<void, unknown> | Promise<void> | void;
 
+/**
+ * Derive the short alias used as the rpc-tag prefix for a plugin's routes.
+ * Pure — depends only on the plugin name.
+ *
+ * Examples:
+ *   '@voltro/plugin-audit'    → 'audit'
+ *   '@scope/plugin-rateLimit' → 'rateLimit'
+ *   'plain-name'              → 'plainName'
+ *   '@voltro/audit'           → 'audit'  (no plugin- prefix)
+ */
+export declare const pluginAlias: (pluginName: string) => string;
+
 /**
  * Server-only context delivered to `bindDataStore`, ALONGSIDE the store,
  * AFTER the framework has opened its store + pool. Gives a plugin the
@@ -3257,11 +3273,18 @@ export declare type PluginInstallHook = (ctx: PluginLifecycleContext) => Effect.
  *
  * **What an alias costs, stated because it is not obvious and nothing else
  * says it:** the local and cloud dashboards fetch a plugin's inspect panel at
- * `/_voltro/inspect/plugins/<slug>/…` with the DEFAULT slug compiled in. Alias
- * a plugin that ships `inspectEndpoints` and the endpoints keep working, the
- * rpc tags move as intended, and the dashboard panel 404s — because the panel
- * is in a different repository and cannot follow. Alias to dodge a tag
- * collision; do not alias a plugin whose dashboard panel you use.
+ * `/_voltro/inspect/plugins/<slug>/…` with the DEFAULT slug compiled in, and
+ * they are in different repositories, so they cannot follow an alias. That
+ * used to mean an aliased plugin kept working while its panel 404'd. It no
+ * longer does: `makePluginInspectRegistry` also mounts each plugin's inspect
+ * endpoints under its CANONICAL slug, so the compiled-in path stays correct
+ * however the app renames the plugin.
+ *
+ * The residue is `instance`, not `alias`. Two installs are two panels with one
+ * canonical name, so they get NO shared mount — showing either under the
+ * canonical path would hand a dashboard the other install's rows under a name
+ * that looks right. Each is reachable at its own slug, which
+ * `/_voltro/inspect/plugins` reports as `inspectSlug`.
  *
  * @param base     the plugin's canonical package name, e.g. `'@voltro/plugin-cdc-out'`
  * @param alias    replaces the whole namespace — an app-chosen name
@@ -3508,6 +3531,55 @@ export declare interface PluginSchemaContribution {
     readonly migrations?: ReadonlyArray<PluginMigration>;
 }
 
+/**
+ * Derive the URL slug for a plugin's HTTP-facing surfaces (the inspect mount
+ * `/_voltro/inspect/plugins/<slug>/…`). Unlike `pluginAlias` (an identifier
+ * for rpc tags / codegen, camelCase), the slug stays KEBAB-CASE — the shape
+ * every dashboard fetches (`plugins/cdc-out/sinks`, never `plugins/cdcOut/…`)
+ * and the shape the package name already carries. Instance-suffixed names
+ * (`@voltro/plugin-cdc-out#analytics`) map `#` → `--` so the slug stays a
+ * fetchable URL path segment.
+ *
+ * Examples:
+ *   '@voltro/plugin-audit'            → 'audit'
+ *   '@voltro/plugin-cdc-out'          → 'cdc-out'
+ *   '@scope/plugin-rateLimit'         → 'rate-limit'
+ *   '@voltro/plugin-cdc-out#analytics'→ 'cdc-out--analytics'
+ */
+export declare const pluginSlug: (pluginName: string) => string;
+
+/**
+ * The wire tag a plugin's own client code must call for one of its routes.
+ *
+ * `pluginTag('@voltro/plugin-notifications', 'inbox')` is `'notifications.inbox'`
+ * in a default app and `'inbox.inbox'` in an app that installed the plugin as
+ * `notificationsPlugin({ alias: 'inbox' })`. Every hook a plugin ships goes
+ * through this instead of spelling its own namespace, because the namespace is
+ * the app's to choose and the hook is the half of the move that a literal
+ * string cannot follow.
+ *
+ * **Resolution, and the one case that fails closed.** A base may have several
+ * registered aliases when an app installs the same plugin twice
+ * (`instance: 'analytics'` → `notifications#analytics`):
+ *
+ *   - exactly one registered alias → that one;
+ *   - several, exactly one of which carries no `#` → the un-suffixed install.
+ *     Two installs of a plugin have a primary and a secondary, and a hook with
+ *     no way to name an install means the primary;
+ *   - several, none or more than one un-suffixed → **throws**. The hook is being
+ *     asked which of two servers it addresses and has no basis to pick; a guess
+ *     here writes to the wrong install's tables, which is worse than a stack
+ *     trace naming both candidates. Call the tag explicitly (`useSubscription(api,
+ *     'notifications#analytics.inbox')`) to say which you mean.
+ *   - none registered → the canonical `pluginAlias(base)`. This is the path a
+ *     unit test rendering a hook in isolation takes, and the path an app takes
+ *     before its generated rpcGroup has loaded. It is NOT a fail-open guess: an
+ *     app that aliased and somehow lost its registration calls a tag the client
+ *     group does not contain, and the transport refuses it by name rather than
+ *     routing it somewhere plausible.
+ */
+export declare const pluginTag: (baseName: string, route: string) => string;
+
 /**
  * A scaffold template a plugin contributes to `voltro init` /
  * `voltro add-app`. Templates are listed under the plugin's name in
@@ -3887,10 +3959,29 @@ export declare type ReactivitySource = TableName | ReactivityChannel;
  */
 export declare type ReactivitySourceValue = string | ReactivityChannel;
 
+/**
+ * Declare, for this realm, what namespace each installed plugin actually
+ * answers to. Emitted into `rpcGroup.generated.ts` by the codegen — one call
+ * per api, mapping each plugin's CANONICAL base name to its EFFECTIVE alias.
+ *
+ * Emitted unconditionally whenever an app installs a plugin that contributes
+ * client routes, not only when something was aliased. A registration that only
+ * appeared in the aliased case would be a second code path exercised by nobody,
+ * and the default case is where a regression would hide.
+ *
+ * Accumulates rather than overwrites: two apis in one browser bundle each
+ * register their own map, and an app may install one plugin twice (`instance`).
+ * The disambiguation happens at READ time — see `pluginTag`.
+ */
+export declare const registerPluginAliases: (aliases: Readonly<Record<string, string>>) => void;
+
 /** Gate a handler on a scope; fails with a typed `ScopeError` if missing.
  *  Checks the EFFECTIVE set so role-derived scopes count. */
 export declare const requireScope: (subject: Subject, scope: string) => Effect.Effect<void, ScopeError>;
 
+/** Drop every registration. Tests only — production registers once at module load. */
+export declare const resetPluginAliases: () => void;
+
 /** The question the runtime asks a registered resource-scope resolver. */
 export declare interface ResourceScopeRequest {
     /** The authenticated caller. */
@@ -4704,21 +4795,52 @@ declare const TableValidationFailed_base: Schema.TaggedErrorClass<TableValidatio
 
 export declare type Target<Input = unknown, Row = unknown> = TargetSpec<Input, Row> | ReadonlyArray<TargetSpec<Input, Row>>;
 
+/**
+ * ONE declared many-to-many relation of a write target: the junction table
+ * plus its two reference columns.
+ *
+ * **Why the columns are declared and not derived.** The server can derive
+ * them (`store.relationLinks` reads the junction's `reference()` targets),
+ * and it still does — but the same declaration drives JUNCTION AUTO-OPTIMISTIC
+ * in the BROWSER, and the browser has no table registry to derive from
+ * (`@voltro/database` is server-only by construction). Guessing a column name
+ * from the table name is the failure mode this codebase refuses everywhere
+ * else, so the pair is stated. It is not taken on trust: before it writes, the
+ * server compares the declaration against the junction's real reference
+ * columns and refuses — naming the right pair — if they disagree. A wrong
+ * declaration is a boot-loud error, never a silent client/server divergence.
+ */
+export declare interface TargetRelation {
+    /** The junction (link) table. */
+    readonly junction: string;
+    /** The junction's reference column pointing at the TARGET's own table. */
+    readonly anchorColumn: string;
+    /** The junction's other reference column — the linked row's id. */
+    readonly targetColumn: string;
+}
+
 /**
  * Declared many-to-many RELATIONS of a write target: `{ inputField:
- * junctionTable }`. After the executor succeeds — inside the SAME
+ * TargetRelation }`. After the executor succeeds — inside the SAME
  * transaction — the framework reconciles the junction's links for the
  * written row against `input[inputField]` (an array of target ids) via the
  * diff-based `store.relationLinks`, so a form's multi-reference field saves
- * in one mutation with no hand-written junction code. The anchor column is
- * derived from the junction's `reference()` targets (a self-junction is
- * refused, never guessed).
+ * in one mutation with no hand-written junction code.
+ *
+ * The SAME declaration drives the client's junction auto-optimistic: the
+ * cache reconciles the junction rows of every subscription sourced on
+ * `junction` the moment the mutation is sent, so a multi-reference field
+ * flips as instantly as a scalar one instead of waiting for the server delta.
+ * Those patches ride the ordinary optimistic lane (staged under the mutation
+ * id): reverted on failure, kept on success until the base actually moves.
  *
  * An ABSENT input field leaves the links untouched (absent ≠ empty — an
  * empty array is the explicit "clear them all"). The row id is the
- * executor's `output.id`, falling back to `input.id`.
+ * executor's `output.id`, falling back to `input.id`; the client, which
+ * cannot see `output` yet, uses `input.id` (and, for an insert, the same
+ * optimistic id it stamped on the new row).
  */
-export declare type TargetRelations = Readonly<Record<string, string>>;
+export declare type TargetRelations = Readonly<Record<string, TargetRelation>>;
 
 export declare type TargetSpec<Input = unknown, Row = unknown> = InsertTarget<Input, Row> | UpdateTarget<Input, Row> | DeleteTarget<Input>;
 
@@ -5068,8 +5190,10 @@ export declare interface VoltroPlugin {
      * declarations across seven plugins), so the escape hatch fires on all of
      * them and the alias moves NOTHING on the rpc surface. A user aliasing
      * `notifications` to escape a collision with their own `notifications.*`
-     * routes would still collide — and would additionally lose the dashboard
-     * panel, which fetches the default slug. Worse than not shipping the field.
+     * routes would still collide — and, at that time, would additionally have
+     * lost the dashboard panel, which fetches the default slug. Worse than not
+     * shipping the field. (The panel half is fixed since: see the canonical
+     * mount in `makePluginInspectRegistry`.)
      *
      * With `baseName` set, both tag derivations strip a leading
      * `<default-alias>.` before applying the EFFECTIVE alias, so
@@ -5497,6 +5621,34 @@ export declare const wireErrorUnion: (descriptor: {
     readonly requiresApproval?: AnyApprovalPolicy | undefined;
 }, kind: "query" | "mutation" | "action" | "stream") => Schema.Schema.All;
 
+/**
+ * Re-tag a procedure descriptor for the wire.
+ *
+ * Every lifter below is `Rpc.make(descriptor.name, …)`, so the tag a procedure
+ * answers to on the wire is the one baked into the DESCRIPTOR — not the one the
+ * caller thinks it is emitting. That is fine for app-authored procedures, whose
+ * descriptor and tag have one source. It was wrong for PLUGIN routes: an app
+ * that installs a plugin under an `alias` moves the namespace, the server
+ * registers the moved tag, and the generated client lifted the plugin's
+ * descriptor unchanged — so the browser sent the tag the plugin AUTHORED to a
+ * server that had stopped serving it. The identifier moved, the descriptor map
+ * key moved, the type key moved; the only string the transport reads did not.
+ *
+ * The codegen wraps every plugin-contributed descriptor with this, always —
+ * including the un-aliased case, where it is an identity in effect. A wrap that
+ * only appeared under an alias would be a branch nothing exercises, and the
+ * un-aliased case is the one a regression would hide in.
+ *
+ * Returns a COPY. The descriptor is imported by reference from the plugin's
+ * browser-safe module and may be lifted by several apps in one process; mutating
+ * `name` in place would re-tag it for all of them.
+ */
+export declare const withRpcTag: <D extends {
+    readonly name: string;
+}, const T extends string>(descriptor: D, tag: T) => Omit<D, "name"> & {
+    readonly name: T;
+};
+
 export declare const workflowCancelDescriptor: ActionProcedureDescriptor<"__voltro.workflow.cancel", Schema.Struct<{
     workflowName: typeof Schema.String;
     executionId: typeof Schema.String;