@voltro/protocol 0.54.0 → 0.56.0

package/dist/identity.d.ts

@@ -0,0 +1,168 @@
+/**
+ * What an inspect readout should call this process's mode.
+ *
+ * A projection of `bootPath`, not a second decision — the two boot paths each
+ * wrote a literal here, and one of them wrote the wrong one for years.
+ * `build`, `cli` and `test` collapse to `'cli'`: none of them serves traffic,
+ * and pretending otherwise would be the same category error in reverse.
+ */
+export declare const appMode: () => "dev" | "serve" | "start" | "cli";
+
+/**
+ * The framework version this process runs, or `undefined` when it could not be
+ * determined. The ONE answer — there were three, and one of them read
+ * `npm_package_version`, which is the APP's version, not the framework's.
+ *
+ * Deliberately NOT `processIdentity().version`, though it returns the same
+ * value. Asking for the version must not resolve the identity: a boot path
+ * holds the version in a module-level constant, so routing it through the
+ * identity froze `bootPath` at import time — before the command that knows it
+ * had run — and the resolver then warned about its own caller. A version is
+ * not a fact about which replica this is.
+ */
+export declare const frameworkVersion: () => string | undefined;
+
+/**
+ * Just the instance id — this PROCESS, not the name it wears.
+ *
+ * The distinction matters wherever a monotonic counter is compared across
+ * restarts. A replica id is a NAME and names survive: a StatefulSet pod keeps
+ * `POD_NAME`, and `VOLTRO_REPLICA_ID` is stable by definition. A counter does
+ * not survive — it starts at 1 again — so anything that reads "is this newer
+ * than what I have from X" must key on the process, or it silently answers "no"
+ * for as long as the dead process's high-water mark stands.
+ */
+export declare const instanceId: () => string;
+
+/**
+ * Which command this process is.
+ *
+ * `serve` and `start` are separate because they are separate commands with
+ * separate capabilities — `voltro start` is web-only and refuses an api — and
+ * collapsing them is what made an inspect readout name a command the process
+ * could not have been started by. Only ever affects the LOCAL fallback id.
+ */
+export declare type ProcessBootPath = 'dev' | 'serve' | 'start' | 'build' | 'cli' | 'test';
+
+export declare interface ProcessIdentity {
+    /**
+     * The place in the fleet: `VOLTRO_REPLICA_ID` → `POD_NAME` → `HOSTNAME` →
+     * `<bootPath>-<pid>`.
+     *
+     * STABLE ACROSS RESTARTS in a real deployment — a pod that dies and comes
+     * back is the same replica. Pair it with `startedAt` to talk about one
+     * process.
+     */
+    readonly replicaId: string;
+    /**
+     * One PROCESS: `<replicaId>@<startedAt>.<nonce>`. A restart changes it.
+     *
+     * The nonce is not decoration. `startedAt` has millisecond resolution, so
+     * two generations of one replica that start inside the same millisecond
+     * produce the same string — and an aggregation keyed on it would then merge
+     * two processes' state into one, which is precisely the arithmetic across
+     * generations the generation exists to prevent. Rare in a deployment,
+     * routine in a test worker, and a wrong merge is silent either way.
+     */
+    readonly instanceId: string;
+    /** This process's start, on ITS OWN clock. An identity, never compared to
+     *  another process's clock — see `instanceMembership`. */
+    readonly startedAt: number;
+    /** The framework version. `undefined` when it could not be determined —
+     *  which must not read the same as a version, so it is not `'0.0.0'`. */
+    readonly version: string | undefined;
+    /** The app's own version, when a boot path knows it. */
+    readonly appVersion: string | undefined;
+    readonly bootPath: ProcessBootPath;
+    /**
+     * `host:port` another replica can reach this one's inspect surface on, or
+     * `undefined`.
+     *
+     * Deliberately not derived from the bind address: a process bound to
+     * `0.0.0.0:4000` is not reachable AT `0.0.0.0`, and a loopback address is
+     * reachable only by itself. `resolveRunnerIdentity` already carries this
+     * distinction as `localhostRisk` for the cluster runner; this is the same
+     * fact for the inspect surface.
+     */
+    readonly reachableAt: string | undefined;
+    /** True only when `reachableAt` is set AND is not loopback. */
+    readonly reachable: boolean;
+}
+
+/** This process's identity. Stable for the lifetime of the process. */
+export declare const processIdentity: () => ProcessIdentity;
+
+/**
+ * Does the ENVIRONMENT say this process is one of several?
+ *
+ * A shape question, not a count: it answers "is a process-local default going to
+ * be wrong here", which is the only thing the callers need. Several defaults in
+ * this framework are correct for one process and quietly wrong for a fleet — a
+ * process-local rate-limit store multiplies the limit by the replica count, a
+ * process-local read-your-writes position store makes a user's own write
+ * invisible on the next request, an in-process broadcast bus carries nothing
+ * across pods. Each of those warns on THIS evidence rather than on a guess.
+ *
+ * Lives here, beside the process identity, because it reads the same env and
+ * because the alternative was three copies: it began in `@voltro/cli`'s
+ * reactivity audit, and a plugin cannot import the CLI.
+ *
+ * Returns the SIGNAL as a human-readable string (so the warning can cite what it
+ * saw) or `null` for "nothing says so".
+ */
+export declare const replicaEvidence: (env?: Record<string, string | undefined>) => string | null;
+
+/** Just the replica id — the common case, and the ONLY spelling of it. */
+export declare const replicaId: () => string;
+
+/** Reset for tests. A process has one identity; a test worker runs many. */
+export declare const resetProcessIdentityForTest: (bootPath?: ProcessBootPath) => void;
+
+/**
+ * Resolve the advertised host the same way the cluster runner does, so an
+ * operator does not have to configure two things that mean one thing.
+ */
+export declare const resolveAdvertisedHost: (env?: NodeJS.ProcessEnv) => {
+    readonly host: string;
+    readonly declared: boolean;
+};
+
+/**
+ * Where a PEER can reach this process's inspect surface, as `host:port`.
+ *
+ * The boot path knows the port; the host comes from `POD_IP` /
+ * `VOLTRO_INSPECT_ADVERTISE_HOST` and is a loopback address when neither is
+ * set. Passing a loopback host is not an error — it is recorded and reported
+ * as `reachable: false`, which is what lets a fleet request answer "this one
+ * cannot be reached" instead of waiting for a timeout.
+ */
+export declare const setProcessAdvertisedAddress: (hostPort: string | undefined, 
+/**
+ * Whether the HOST was declared by the operator rather than fallen back to.
+ *
+ * This is the difference between a loopback address that is a guess and one
+ * that is a statement. `POD_IP` unset means we do not know where we are and
+ * `127.0.0.1` is our shrug — a peer must not try it. An operator who sets
+ * `VOLTRO_INSPECT_ADVERTISE_HOST` has told us, and telling us `127.0.0.1` is
+ * a legitimate thing to say when the peers really are on this machine.
+ *
+ * Same shape as every other declaration in this framework: we do not
+ * second-guess one, and we do not treat a fallback as one.
+ */
+declared?: boolean) => void;
+
+/** The app's own version, when the boot path knows it. */
+export declare const setProcessAppVersion: (version: string | undefined) => void;
+
+/**
+ * Name which command this process is. Call as early as a boot path can.
+ *
+ * Only ever affects the LOCAL fallback (`dev-1234` vs `serve-1234`); in any
+ * deployment `POD_NAME` or `HOSTNAME` decides and this is cosmetic. Called
+ * after the identity has already been handed out, it does NOT rewrite it — an
+ * id that changes mid-process is worse than a slightly wrong label — and says
+ * so loudly, because silence is worse than both.
+ */
+export declare const setProcessBootPath: (kind: ProcessBootPath) => void;
+
+export { }

package/dist/identity.js

@@ -0,0 +1,106 @@
+import { createLogger as e } from "@voltro/logger";
+import { readFileSync as t } from "node:fs";
+import { dirname as n, join as r } from "node:path";
+import { fileURLToPath as i } from "node:url";
+//#region src/processIdentity.ts
+var a = e({ scope: "voltro:identity" }), o = Symbol.for("@voltro/runtime/processIdentity"), s = globalThis, c = () => Math.random().toString(36).slice(2, 8), l = s[o] ?? (s[o] = {
+	bootPath: "cli",
+	startedAt: Date.now(),
+	nonce: c(),
+	versionResolved: !1
+}), u = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"::1",
+	"0.0.0.0",
+	""
+]), d = (e) => {
+	if (e.startsWith("[")) return e.slice(1, e.indexOf("]"));
+	let t = e.lastIndexOf(":");
+	return t === -1 ? e : e.slice(0, t);
+}, f = () => {
+	let e = globalThis;
+	return typeof e.__VOLTRO_FRAMEWORK_VERSION__ == "string" && e.__VOLTRO_FRAMEWORK_VERSION__.length > 0 ? e.__VOLTRO_FRAMEWORK_VERSION__ : void 0;
+}, p = () => {
+	if (l.versionResolved) return l.version;
+	l.versionResolved = !0;
+	let e = f();
+	if (e !== void 0) return l.version = e, l.version;
+	let a = n(i(import.meta.url));
+	for (let e of [r(a, "..", "package.json"), r(a, "..", "..", "package.json")]) try {
+		let n = JSON.parse(t(e, "utf8"));
+		if (n.name === "@voltro/protocol" && typeof n.version == "string") return l.version = n.version, l.version;
+	} catch {}
+	return l.version;
+}, m = (e) => {
+	if (l.frozen !== void 0 && l.frozen.bootPath !== e) {
+		a.warn(`process identity was already resolved as ${l.frozen.replicaId} (bootPath=${l.frozen.bootPath}); keeping it rather than becoming ${e}. Call setProcessBootPath before anything reads the identity.`, {
+			resolved: l.frozen.replicaId,
+			was: l.frozen.bootPath,
+			requested: e
+		});
+		return;
+	}
+	l.bootPath = e;
+}, h = (e) => {
+	l.appVersion = e, l.frozen !== void 0 && (l.frozen = {
+		...l.frozen,
+		appVersion: e
+	});
+}, g = (e, t = !1) => {
+	l.advertised = e, l.advertisedDeclared = t, l.frozen !== void 0 && (l.frozen = {
+		...l.frozen,
+		reachableAt: e,
+		reachable: _(e, t)
+	});
+}, _ = (e, t) => e !== void 0 && (t || !u.has(d(e))), v = (e = process.env) => {
+	let t = e.VOLTRO_INSPECT_ADVERTISE_HOST;
+	if (t !== void 0 && t !== "") return {
+		host: t,
+		declared: !0
+	};
+	let n = e.POD_IP;
+	return n !== void 0 && n !== "" ? {
+		host: n,
+		declared: !0
+	} : {
+		host: "127.0.0.1",
+		declared: !1
+	};
+}, y = () => {
+	if (l.frozen !== void 0) return l.frozen;
+	let e = process.env, t = e.VOLTRO_REPLICA_ID ?? e.POD_NAME ?? e.HOSTNAME ?? `${l.bootPath}-${process.pid}`, n = l.advertised, r = {
+		replicaId: t,
+		instanceId: `${t}@${l.startedAt}.${l.nonce}`,
+		startedAt: l.startedAt,
+		version: p(),
+		appVersion: l.appVersion,
+		bootPath: l.bootPath,
+		reachableAt: n,
+		reachable: _(n, l.advertisedDeclared === !0)
+	};
+	return l.frozen = r, r;
+}, b = () => y().replicaId, x = () => y().instanceId, S = (e = process.env) => {
+	let t = Number(e.REPLICA_COUNT);
+	if (Number.isFinite(t) && t >= 1) return t > 1 ? `REPLICA_COUNT=${t}` : null;
+	for (let [t, n] of [
+		["KUBERNETES_SERVICE_HOST", "Kubernetes"],
+		["POD_IP", "Kubernetes (downward API)"],
+		["POD_NAME", "Kubernetes (downward API)"],
+		["FLY_ALLOC_ID", "Fly.io"],
+		["FLY_MACHINE_ID", "Fly.io"],
+		["ECS_CONTAINER_METADATA_URI_V4", "AWS ECS"],
+		["ECS_CONTAINER_METADATA_URI", "AWS ECS"],
+		["K_REVISION", "Cloud Run / Knative"],
+		["CONTAINER_APP_REPLICA_NAME", "Azure Container Apps"],
+		["RENDER_INSTANCE_ID", "Render"]
+	]) if ((e[t] ?? "") !== "") return `${t} is set (${n})`;
+	return null;
+}, C = (e = "test") => {
+	l.frozen = void 0, l.bootPath = e, l.startedAt = Date.now(), l.nonce = c(), l.appVersion = void 0, l.advertised = void 0, l.advertisedDeclared = !1;
+}, w = () => p(), T = () => {
+	let e = y().bootPath;
+	return e === "dev" || e === "serve" || e === "start" ? e : "cli";
+};
+//#endregion
+export { T as appMode, w as frameworkVersion, x as instanceId, y as processIdentity, S as replicaEvidence, b as replicaId, C as resetProcessIdentityForTest, v as resolveAdvertisedHost, g as setProcessAdvertisedAddress, h as setProcessAppVersion, m as setProcessBootPath };

package/dist/index.d.ts

@@ -629,8 +629,11 @@ export declare interface CachedScopeDecision {
  *   - `x.y.z`         — exact
  *   - `*`             — any
  */
-export declare const checkFrameworkCompat: (pluginName: string, range: string | undefined, runningVersion: string) => {
+export declare const checkFrameworkCompat: (pluginName: string, range: string | undefined, 
+/** `undefined` when the running version could not be determined. */
+runningVersion: string | undefined) => {
     ok: true;
+    unverified?: string;
 } | {
     ok: false;
     reason: string;
@@ -696,6 +699,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 +2662,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
@@ -2727,6 +2746,33 @@ export declare interface PluginBindContext {
      * task early. The framework also stops every armed task at shutdown.
      */
     readonly scheduleCoordinated: (name: string, intervalMs: number, effect: () => void | CoordinatedTickOutcome | Promise<void | CoordinatedTickOutcome>, options?: CoordinatedTaskOptions) => CoordinatedScheduleHandle;
+    /**
+     * Claim ONE change fleet-wide. `true` = this replica may run the effect;
+     * `false` = another replica has it, or the claim could not be taken.
+     *
+     * The counterpart of `scheduleCoordinated` for the OTHER thing that fires on
+     * every replica: a change tap. `onChangeEvent` is delivered to every replica —
+     * that is what makes a `changeScope: 'fleet'` store cross-instance — so a tap
+     * that COUNTS or SENDS multiplies by the replica count. `plugin-billing`
+     * accrued a usage unit per metered row change and a tenant on two pods was
+     * billed twice; the plugin whose entire job is counting had no way to say
+     * "once".
+     *
+     * `scope` namespaces the key (use the plugin's own name); `key` must name the
+     * CHANGE. Derive it with `changeDigest` + `OccurrenceCounter`
+     * (`@voltro/database`) rather than inventing one — a fleet change carries no
+     * LSN, no commit id and no `traceId`, so content plus its position among
+     * content-identical repeats is the only thing two replicas provably agree on.
+     *
+     * AT MOST once: the claim is taken before the effect, so a replica that wins
+     * and dies takes the change with it, and a claim that cannot be written is
+     * taken by nobody. Fail-closed, like the rate slot and the budget guard.
+     *
+     * Required rather than optional, and deliberately: an absent gate reads
+     * exactly like a gate that passed, and the whole point of this field is a
+     * count.
+     */
+    readonly claimChange: (scope: string, key: string) => Promise<boolean>;
 }
 
 /**
@@ -3257,11 +3303,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 +3561,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 +3989,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 +4825,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 +5220,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 +5651,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;