@voltro/protocol 0.85.0 → 0.86.0

package/dist/event.js

@@ -0,0 +1,104 @@
+import { RequestedTenantRefused as e } from "./tenantSelection.js";
+import { Unauthenticated as t } from "./auth.js";
+import { NoSuchResource as n, ScopeError as r, declaresResourceGuard as i, isOpenAccess as a, openAccessSpec as o } from "./scopes.js";
+import { strictInput as s } from "./strictInput.js";
+import { hasEnforcedGuard as c } from "./procedure.js";
+import { Schema as l } from "effect";
+import { Rpc as u } from "effect/rpc";
+//#region src/event.ts
+var d = 7500, f = (e) => typeof e == "object" && !!e && e.kind === "event", p = (e) => {
+	if (e.name.length === 0) throw Error("defineEvent: `name` must not be empty");
+	if (/\s/.test(e.name)) throw Error(`defineEvent("${e.name}"): \`name\` must not contain whitespace.\n  The name is used as a broker subject segment. NATS refuses a subject with
+  whitespace and delivers nothing — silently, and only on that broker, so an
+  app that works on Redis stops working when the transport changes.
+  Use a dot for namespacing: "orders.paid".`);
+	if (e.guards !== void 0 && e.guards.length === 0) throw Error(`defineEvent("${e.name}"): \`guards: []\` is empty, so it enforces nothing —\n  but it reads at the call site as if the event were protected. Omit the field
+  for an unguarded event, or list the scopes that may subscribe.`);
+	if (e.openAccess !== void 0) {
+		if (e.openAccess.trim() === "") throw Error(`defineEvent("${e.name}"): \`openAccess\` needs a REASON, not an empty string. It is\n  the sentence a reviewer reads to decide whether anyone should really be able to
+  subscribe without an authorization check — e.g. \`openAccess: 'public scoreboard,
+  no caller data'\`.`);
+		if (e.guards !== void 0 && e.guards.length > 0) throw Error(`defineEvent("${e.name}"): \`openAccess\` and \`guards\` are two different access\n  decisions, so declaring both says the event is protected AND open. Keep the guards
+  if a subscriber must hold a scope; drop them if anyone may listen.`);
+	}
+	if (e.webhook?.rateLimit !== void 0 && e.webhook.rateLimit.perMinute < 1) throw Error(`defineEvent("${e.name}"): \`webhook.rateLimit.perMinute\` is ${e.webhook.rateLimit.perMinute}, which defers every delivery forever.\n  There is no "unlimited" spelling here — omit \`rateLimit\` for no ceiling.`);
+	if (e.webhook?.version !== void 0 && e.webhook.version < 1) throw Error(`defineEvent("${e.name}"): \`webhook.version\` must be >= 1 (default 1).\n  A subscriber pinned to 1 would read this event as BEHIND its own version,
+  which is the opposite of what a version bump is for.`);
+	if (e.delivery === "latest" && e.webhook !== void 0) throw Error(`defineEvent(${e.name}): \`delivery: 'latest'\` cannot be combined with \`webhook\`.\n  \`latest\` means a superseded delivery did not matter — but a webhook delivery is a
+  durable side effect at a third party, and one already sent cannot be superseded.
+  A high-rate event with an HTTP audience is also 60 deliveries per second per target;
+  the rate limit DEFERS the excess as pending rows, so it grows a table instead of failing.
+  Split them: publish the high-rate event for clients, and publish a separate, coarser
+  event (a summary, a state change) for the outside world.`);
+	return {
+		kind: "event",
+		name: e.name,
+		key: e.key,
+		payload: e.payload,
+		guards: e.openAccess === void 0 ? e.guards : [o(e.openAccess.trim())],
+		openAccess: e.openAccess,
+		rewind: e.rewind,
+		webhook: e.webhook,
+		delivery: e.delivery
+	};
+}, m = (e) => l.Struct({
+	_tag: l.Literal("event"),
+	origin: l.String,
+	n: l.Number,
+	emittedAt: l.Number,
+	payload: e
+}), h = l.Struct({
+	_tag: l.Literal("gap"),
+	missed: l.Number,
+	reason: l.Literals(["buffer", "resume"])
+}), g = l.Struct({ _tag: l.Literal("attached") }), _ = (e) => l.Union([
+	g,
+	m(e),
+	h
+]), v = l.Struct({
+	origin: l.String,
+	n: l.Number
+}), y = (e) => l.Struct({
+	key: e,
+	resume: l.optional(l.Array(v))
+}), b = (o, d) => {
+	let f = o.guards !== void 0 && o.guards.some((e) => !a(e)) ? l.Union([
+		r,
+		t,
+		e
+	]) : l.Union([t, e]), p = i(o.guards) ? l.Union([f, n]) : f, m = d && d.length > 0 ? l.Union([p, ...d]) : p;
+	return u.make(o.name, {
+		payload: s(y(o.key), o.name, c(o.guards)),
+		success: _(o.payload),
+		error: m,
+		stream: !0
+	});
+}, x = class extends l.TaggedError()("EventPayloadInvalid", {
+	event: l.String,
+	message: l.String
+}) {}, S = class extends l.TaggedError()("EventKeyInvalid", {
+	event: l.String,
+	message: l.String
+}) {}, C = class extends l.TaggedError()("EventPayloadTooLarge", {
+	event: l.String,
+	bytes: l.Number,
+	limit: l.Number
+}) {}, w = (e) => {
+	if (typeof e != "object" || !e) return JSON.stringify(e) ?? "null";
+	let t = Object.entries(e), n = 0;
+	for (let e of t) e[1] !== void 0 && (t[n++] = e);
+	return t.length = n, t.sort(([e], [t]) => e < t ? -1 : +(e > t)), JSON.stringify(t);
+}, T = "\0", E = (e, t, n) => [
+	e ?? "~",
+	t,
+	w(n)
+].join("\0"), D = (e) => {
+	let [t = "~", n = "", r = ""] = e.split("\0");
+	return {
+		tenantId: t === "~" ? null : t,
+		event: n,
+		key: r
+	};
+}, O = (e) => e.split("\0").join(" · ");
+//#endregion
+export { T as EVENT_ROUTE_SEP, S as EventKeyInvalid, x as EventPayloadInvalid, C as EventPayloadTooLarge, d as MAX_EVENT_ENVELOPE_BYTES, p as defineEvent, w as encodeEventKey, g as eventAttached, m as eventEnvelope, h as eventGap, v as eventResumePoint, E as eventRoute, _ as eventStreamEvent, y as eventSubscribeInput, b as eventToRpc, O as formatEventRoute, f as isEventDescriptor, D as parseEventRoute };

package/dist/idempotency.js

@@ -0,0 +1,66 @@
+import { Schema as e } from "effect";
+//#region src/idempotency.ts
+var t = (e, t, n) => `${e ?? "(global)"}|${t.toUpperCase()}|${n}`, n = (e, t, n, r) => r === void 0 ? `${e ?? "(global)"}|${t ?? "(anon)"}|WS|${n}` : `WS-connection:${JSON.stringify([
+	e ?? null,
+	t ?? null,
+	n,
+	r
+])}`, r = class extends e.TaggedError()("MutationConnectionRequired", { traceId: e.String }) {
+	get message() {
+		return "this mutation requires a live native WebSocket connection";
+	}
+}, i = async (e, t, n, r, i, o = a) => {
+	let s = await e.claim(t, n, i, r, o);
+	return s === "claimed" ? { kind: "fresh" } : s.status === "completed" && s.response ? {
+		kind: "replay",
+		response: s.response
+	} : { kind: "conflict" };
+}, a = 3e4, o = (e, t, n, r = a, i = Date.now) => {
+	let o = setInterval(() => {
+		e.renew(t, n, i()).catch(() => {});
+	}, Math.max(1, Math.floor(r / 3)));
+	return o.unref?.(), () => clearInterval(o);
+}, s = (e, t, n, r, i) => e.complete(t, n, r, i), c = (e, t, n) => e.release(t, n), l = () => {
+	let e = /* @__PURE__ */ new Map(), t = (e, t) => `${e}\u0000${t}`;
+	return {
+		get: async (n, r) => e.get(t(n, r)) ?? null,
+		claim: async (n, r, i, a, o) => {
+			let s = e.get(t(n, r));
+			return s && i - s.createdAt < u(s.status, a, o) ? s : (e.set(t(n, r), {
+				scope: n,
+				key: r,
+				status: "in_flight",
+				response: null,
+				createdAt: i
+			}), "claimed");
+		},
+		complete: async (n, r, i, a) => {
+			e.set(t(n, r), {
+				scope: n,
+				key: r,
+				status: "completed",
+				response: i,
+				createdAt: a
+			});
+		},
+		release: async (n, r) => {
+			e.delete(t(n, r));
+		},
+		renew: async (n, r, i) => {
+			let a = e.get(t(n, r));
+			a?.status === "in_flight" && e.set(t(n, r), {
+				...a,
+				createdAt: i
+			});
+		}
+	};
+}, u = (e, t, n) => e === "completed" ? t : Math.min(t, n), d = class extends e.TaggedError()("MutationInFlight", {
+	traceId: e.String,
+	retryAfterMs: e.Number
+}) {
+	get message() {
+		return `a request with this idempotency key is still in flight — replay the same key after ${this.retryAfterMs}ms`;
+	}
+}, f = 1e3;
+//#endregion
+export { a as DEFAULT_IN_FLIGHT_LEASE_MS, f as MUTATION_IN_FLIGHT_RETRY_AFTER_MS, r as MutationConnectionRequired, d as MutationInFlight, i as beginIdempotent, c as failIdempotent, s as finishIdempotent, u as freshFor, o as holdIdempotentClaim, t as idempotencyScope, l as memoryIdempotencyStore, n as wsMutationIdempotencyScope };

package/dist/identity.js

@@ -33,15 +33,11 @@ var a = e({ scope: "voltro:identity" }), o = Symbol.for("@voltro/runtime/process
 	} 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;
+	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
+	}) : l.bootPath = e;
 }, h = (e) => {
 	l.appVersion = e, l.frozen !== void 0 && (l.frozen = {
 		...l.frozen,

package/dist/index.d.ts

@@ -546,7 +546,7 @@ export declare interface AuthenticatedGuardSpec {
  * an auth resolver before reaching its handler. The application provides
  * the resolver via `Layer.succeed(AuthMiddleware, AuthMiddleware.of(fn))`,
  * where `fn` receives `{headers, payload, rpc, clientId}` and returns an
- * `Effect<Subject, Unauthenticated>` — typically by inspecting headers / Bearer token and
+ * `Effect<Subject, Unauthenticated | RequestedTenantRefused>` — typically by inspecting headers / Bearer token and
  * looking the caller up.
  *
  * `provides: SubjectService` means the resolver's return value is placed
@@ -562,7 +562,7 @@ export declare interface AuthenticatedGuardSpec {
 export declare class AuthMiddleware extends AuthMiddleware_base {
 }
 
-declare const AuthMiddleware_base: RpcMiddleware.ServiceClass<AuthMiddleware, "@voltro/AuthMiddleware", SubjectService, typeof Unauthenticated, never, never, false>;
+declare const AuthMiddleware_base: RpcMiddleware.ServiceClass<AuthMiddleware, "@voltro/AuthMiddleware", SubjectService, Schema.Union<readonly [typeof Unauthenticated, typeof RequestedTenantRefused]>, never, never, false>;
 
 export declare type AuthRouteHandler = (req: AuthRouteRequest) => Promise<AuthRouteResponse>;
 
@@ -726,6 +726,11 @@ export declare type AuthSubjectGuardVerdict = {
  */
 export declare const beginIdempotent: (store: IdempotencyStore, scope: string, key: string, ttlMs: number, now: number, inFlightLeaseMs?: number) => Promise<IdempotencyOutcome>;
 
+/** Bind a process-local authority refresh to an independent subject snapshot.
+ * Neither the resolver nor its credentials become serializable subject fields.
+ * Request and durable-execution hosts use the same identity-preserving refresh. */
+export declare const bindSubjectAuthority: (subject: Subject, resolve: () => Promise<Subject>) => Subject;
+
 /** Bounded insertion-order storage. Appending overwrites one slot when full;
  * reads never expose its circular physical order or retained array. */
 export declare class BoundedRing<T> implements Iterable<T> {
@@ -809,7 +814,10 @@ export declare const checkGuards: (subject: Subject, guards: ReadonlyArray<AnyCh
  * guard has a `resource`, it extracts the resource id from `input` and asks the
  * resolver whether the caller holds each scope on THAT resource. A globally-held
  * scope (or the `admin:full` bypass) still satisfies without a resolver call;
- * only the gap ("no global grant") falls through to the resolver. A failed
+ * only the gap ("no global grant") falls through to the resolver. A guard with
+ * `resourceOnly: true` always requires the resource resolver's verdict, even
+ * for globally-held scopes or `admin:full`, and refuses if its resource or
+ * resolver is unavailable. A failed
  * resolver Effect is treated as a denial (fail-closed).
  *
  * Returns a typed `ScopeError` naming the first unmet scope, or `null` when
@@ -893,15 +901,15 @@ export declare const composeAuthStrategies: (strategies: ReadonlyArray<AuthStrat
     /** What an unauthenticated caller is — see {@link AnonymousPolicy}.
      *  Default `'no-tenant'`. Ignored when `fallback` is supplied. */
     readonly anonymous?: AnonymousPolicyOrDevTenant;
-    /**
-     * The subject's memberships — the ONE source, strategy-independent. Read
-     * only when a stored tenant selection exists for the subject and names a
-     * tenant other than the credential's, and then on every such request: a
-     * membership revoked a moment ago must not keep a selection alive, and a
-     * switch made a moment ago must be visible on the next call, so there is
-     * no staleness window to configure here. Requires `tenantSelection`.
-     */
+    /** Fresh strategy-independent memberships. Explicit requested tenants are
+     * checked on every resolution, including the credential tenant. Stored
+     * selections read memberships only when they differ from the credential.
+     * Requires `tenantSelection` or `requestedTenant`. */
     readonly memberships?: MembershipsSource;
+    /** Request-local tenant hint, checked against fresh `memberships` before
+     * scopes and guards. Explicit targets bypass the stored selection without
+     * changing it. Invalid hints fail closed, never fall back. */
+    readonly requestedTenant?: RequestedTenantSource;
     /**
      * Where a subject's tenant selection is stored. Read for every matched
      * user / apiKey / serviceAccount subject (one point lookup); a stored
@@ -1413,6 +1421,9 @@ export declare const createRowPatchApplier: () => {
     readonly reset: () => void;
 };
 
+/** The latest authenticated authority for a request or live subscription. */
+export declare const currentSubjectAuthority: (subject: Subject) => Subject;
+
 /**
  * What a descriptor CARRIES: the author's guards, or the erased form of their
  * `openAccess:` decision — never both.
@@ -1990,6 +2001,38 @@ export declare interface DeleteTarget<Input = unknown> extends NestedTargetField
     readonly identify?: ((input: Input) => string | ReadonlyArray<string>) | undefined;
 }
 
+/** The HMR custom event `voltro dev` publishes its activity on. */
+export declare const DEV_ACTIVITY_EVENT = "voltro:dev-activity";
+
+/** What `voltro dev` reports over {@link DEV_ACTIVITY_EVENT}. A `document`
+ *  message describes ONE document request (`id` is per server process); a
+ *  `compile` message says whether Vite is transforming browser modules. */
+export declare type DevActivityMessage = {
+    readonly type: 'document';
+    readonly id: number;
+    /** Path + search exactly as the browser asked for it. */
+    readonly url: string;
+    /** `start` once, when the request arrives; then whichever the server
+     *  is doing as it changes — `compiling` while Vite transforms modules
+     *  for it, `rendering` once a server render runs, `waiting` for
+     *  anything else (Vite's own html, a middleware). */
+    readonly phase: 'start' | 'waiting' | 'compiling' | 'rendering';
+} | {
+    readonly type: 'document';
+    readonly id: number;
+    readonly url: string;
+    readonly phase: 'end';
+    /** `document`: the browser got a page to show. `redirect`: it will ask
+     *  for `location` next. `no-document`: nothing will replace this page
+     *  (204/205, an attachment). `aborted`: the browser went away first. */
+    readonly outcome: 'document' | 'redirect' | 'no-document' | 'aborted';
+    readonly location?: string;
+} | {
+    readonly type: 'compile';
+    readonly consumer: 'client';
+    readonly active: boolean;
+};
+
 /** Pair, list and revoke devices (`devices: true`) for the caller's tenant.
  *  One scope, not three: a device always acts as itself, in the pairer's
  *  tenant, so there is no self / org / other distinction to draw.
@@ -2059,6 +2102,13 @@ export declare const encodeRestError: (format: RestFormat, error: RestFormatErro
  */
 export declare const encodeRestSuccess: (format: RestFormat, value: unknown, ctx: RestFormatContext) => RestFormatResponse;
 
+export declare interface EnqueueOptions {
+    /** Deduplicate while an earlier intent is still pending, not permanently. */
+    readonly idempotencyKey?: string;
+    readonly maxAttempts?: number;
+    readonly delayMs?: number;
+}
+
 /**
  * The text to SHOW for a failure value — its `message`, else its `_tag`, else
  * `String(value)`.
@@ -2076,8 +2126,8 @@ export declare const errorMessage: (err: unknown) => string;
 /**
  * Read the `_tag` off a thrown error value, or `undefined` when it has none.
  *
- * It lives here, beside `toRpc`, because `toRpc` is what puts the tag on the
- * wire — one file owns both ends of that contract. It used to live in
+ * It lives in protocol because `toRpc` (procedure.ts) is what puts the tag on
+ * the wire — one package owns both ends of that contract. It used to live in
  * `@voltro/client`, and being there had a cost nobody could see from inside the
  * framework: an app's shared error handler lived in a package that pulled only
  * `@voltro/i18n`, so reading a tag meant taking a dependency on the whole client
@@ -2481,10 +2531,10 @@ export declare const formatEventRoute: (route: string) => string;
  * test pins it against `wireErrorUnion` per kind, so the two cannot drift.
  */
 export declare const FRAMEWORK_WIRE_ERRORS: {
-    readonly query: readonly [typeof ScopeError, typeof Unauthenticated];
-    readonly stream: readonly [typeof ScopeError, typeof Unauthenticated];
-    readonly action: readonly [typeof ScopeError, typeof Unauthenticated, typeof ValidationError, typeof ValidationErrors];
-    readonly mutation: readonly [typeof ScopeError, typeof Unauthenticated, typeof BusinessRuleViolation, typeof MutationInFlight, typeof VersionConflict, typeof ValidationError, typeof ValidationErrors];
+    readonly query: readonly [typeof ScopeError, typeof Unauthenticated, typeof RequestedTenantRefused];
+    readonly stream: readonly [typeof ScopeError, typeof Unauthenticated, typeof RequestedTenantRefused];
+    readonly action: readonly [typeof ScopeError, typeof Unauthenticated, typeof RequestedTenantRefused, typeof ValidationError, typeof ValidationErrors];
+    readonly mutation: readonly [typeof ScopeError, typeof Unauthenticated, typeof RequestedTenantRefused, typeof BusinessRuleViolation, typeof MutationInFlight, typeof VersionConflict, typeof ValidationError, typeof ValidationErrors];
 };
 
 /** The error values {@link FRAMEWORK_WIRE_ERRORS} admits for `Kind`. */
@@ -2545,6 +2595,9 @@ export declare interface GuardCheckSpec {
      * global-scope check (the extractor is advisory), exactly as before.
      */
     readonly resource?: (input: unknown) => string | undefined;
+    /** Require an explicit resource resolver verdict, even for globally held
+     * scopes and `admin:full`. Missing resolver/resource refuses access. */
+    readonly resourceOnly?: boolean;
 }
 
 /**
@@ -2983,6 +3036,25 @@ export declare const missingAccessDecision: (procedure?: string) => ScopeError;
  *  fits several tries. */
 export declare const MUTATION_IN_FLIGHT_RETRY_AFTER_MS = 1000;
 
+/** Transaction-bound context for a plugin's required database contribution.
+ * The executor result is available before the business transaction commits. */
+export declare interface MutationCommitContext extends RpcInterceptorContext {
+    readonly kind: 'mutation';
+    readonly store: DataStore;
+    readonly output: unknown;
+    /** Same enqueue facade as the executor, bound to this replay attempt. */
+    readonly outbox?: OutboxEnqueueFacade;
+    /** Runner invocation time, including guards and rolled-back retries. */
+    readonly startedAt?: number;
+    /** Elapsed milliseconds before required contribution work. */
+    readonly durationMs?: number;
+}
+
+/** Required transactional work, not an external side effect. A failure rolls
+ * back the mutation. The hook may run again after a rolled-back contention
+ * attempt, so all effects must remain on the supplied transaction store. */
+export declare type MutationCommitHook = (context: MutationCommitContext) => Effect.Effect<void, unknown>;
+
 /** A connection-scoped RPC cannot execute or replay without a live WebSocket.
  * This is a transport precondition, not an authorization or membership grant. */
 export declare class MutationConnectionRequired extends MutationConnectionRequired_base {
@@ -3252,6 +3324,30 @@ export declare const openAccessSpec: (reason: string) => OpenAccessSpec;
  */
 export declare const orderByBearerPrefix: (strategies: ReadonlyArray<AuthStrategy>, headers: Readonly<Record<string, string | undefined>>) => ReadonlyArray<AuthStrategy>;
 
+/** Enqueue-only capability bound to the caller's actual transaction store. */
+export declare interface OutboxEnqueueFacade {
+    /** Returns the stable delivery identity. Delivery happens after commit. */
+    enqueue(effect: string, payload: Record<string, unknown>, options?: EnqueueOptions): Promise<string>;
+}
+
+/** Stable delivery context, shared by app and plugin handlers. */
+export declare interface OutboxHandlerContext {
+    readonly outboxId: string;
+    readonly idempotencyKey: string | null;
+    readonly payload: Record<string, unknown>;
+    readonly attempt: number;
+    readonly subjectId: string | null;
+    readonly tenantId: string | null;
+    readonly traceId: string | null;
+}
+
+/** Delivery happens after commit and may repeat; handlers must be idempotent. */
+export declare interface OutboxHandlerDefinition<R = never> {
+    readonly effect: string;
+    readonly handler: (context: OutboxHandlerContext) => Promise<unknown> | Effect.Effect<unknown, unknown, R>;
+    readonly maxAttempts?: number;
+}
+
 export declare interface Pairing {
     /** The api's base url as the DEVICE reaches it — a LAN address, never `localhost`. */
     readonly api: string;
@@ -3826,6 +3922,9 @@ export declare interface PluginHttpRoute {
      * handler branches on: exempting `/saml` exempts `POST /saml/anything`.
      */
     readonly originGuard?: 'exempt';
+    readonly cors?: RestCors;
+    /** Bearer-only routes must discard cookie authority before authentication. */
+    readonly credentials?: 'bearer';
 }
 
 /**
@@ -4257,7 +4356,7 @@ export declare type PluginMigrationSqlClient = SqlClient.SqlClient;
  * boot log + `/_voltro/inspect/plugins` so operators audit what each
  * plugin asks for before installing.
  */
-export declare type PluginPermission = 'rpc:intercept:mutation' | 'rpc:intercept:query' | 'rpc:intercept:action' | 'rpc:intercept:workflow' | 'schedule:fire' | 'schedule:read' | 'workflow:step' | 'http:intercept' | 'inspect:read' | 'inspect:write' | 'dashboard:mount' | 'store:write' | 'migration:run' | 'store:changes:read' | `secrets:read:${string}` | `network:outbound:${string}` | `plugin:hook:${string}`;
+export declare type PluginPermission = 'rpc:intercept:mutation' | 'rpc:intercept:query' | 'rpc:intercept:action' | 'rpc:intercept:workflow' | 'schedule:fire' | 'schedule:read' | 'workflow:step' | 'http:intercept' | 'inspect:read' | 'inspect:write' | 'dashboard:mount' | 'outbox:handle' | 'store:write' | 'migration:run' | 'store:changes:read' | `secrets:read:${string}` | `network:outbound:${string}` | `plugin:hook:${string}`;
 
 /** What a plugin collects and uses — folded by `voltro compliance generate`
  *  into PrivacyInfo.xcprivacy and the Play Data-safety answers. A plugin that
@@ -4950,7 +5049,7 @@ export declare const queryToRpc: <Name extends string, Input extends Schema.Top,
     }>;
 }>, Schema.Struct<{
     readonly _tag: Schema.Literal<"error">;
-    readonly error: Schema.Unknown;
+    readonly error: Schema.decodeTo<Schema.Unknown, Schema.Codec<Schema.Json, Schema.Json, never, never>, never, never>;
     readonly revision: Schema.optional<Schema.Number>;
 }>]>, Schema.Top>, Schema.Never, never, never>;
 
@@ -5031,6 +5130,20 @@ export declare type ReactivitySourceValue = string | ReactivityChannel;
 
 export declare const readPairing: (storage: PairingStorage) => Promise<Pairing | null>;
 
+/**
+ * Reauthenticate a live grant through its original strategy chain. Tenant and
+ * principal identity stay bound to the original subscription: changing either
+ * requires a new subscription, never reuse of an already scoped descriptor.
+ * Runtime-owned subjects without a request binding retain their explicit grant.
+ */
+export declare const reauthorizeSubject: (subject: Subject, prepare?: (fresh: Subject) => Promise<void>) => Promise<Subject>;
+
+/** Recheck a live grant through fresh authentication and derived authority. */
+export declare const recheckGuardsEffect: (subject: Subject, guards: ReadonlyArray<AnyCheckSpec> | undefined, input: unknown, options?: GuardCheckOptions) => Effect.Effect<ScopeError | Unauthenticated | RequestedTenantRefused | NoSuchResource | null>;
+
+/** Refresh derived authority without replaying unrelated RPC plugin hooks. */
+export declare const refreshEffectiveScopes: (original: Subject, fresh: Subject) => Promise<void>;
+
 /** Every error a plugin registers, as one union (`never` before codegen). */
 export declare type RegisteredPluginError = VoltroPluginErrors[keyof VoltroPluginErrors];
 
@@ -5063,6 +5176,25 @@ export declare const registerPluginAliases: (aliases: Readonly<Record<string, st
  */
 export declare const reportableError: (err: unknown) => Error;
 
+/** An authenticated request cannot use its requested workspace. This is
+ * scoped access refusal, not evidence that the credential or session ended.
+ * Consumers must keep unrelated workspace sessions intact. */
+export declare class RequestedTenantRefused extends RequestedTenantRefused_base {
+}
+
+declare const RequestedTenantRefused_base: Schema.Class<RequestedTenantRefused, Schema.TaggedStruct<"RequestedTenantRefused", {
+    readonly reason: Schema.Literals<readonly ["target-unavailable", "invalid-target", "memberships-unavailable", "not-a-member", "subject-has-no-tenant"]>;
+}>, YieldableError>;
+
+/** A request's tenant hint, read only after a strategy authenticates the caller.
+ * Return null for the credential / stored selection. A non-null target is
+ * checked against fresh memberships on every resolution, including when it
+ * equals the credential's tenant. It never writes a persistent selection.
+ * Do not return a tenant default for an absent hint: that would silently change
+ * the authority of requests which did not select a workspace.
+ */
+export declare type RequestedTenantSource = (subject: Subject, input: AuthStrategyInput) => Promise<string | null> | string | null;
+
 /** 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>;
@@ -5179,6 +5311,16 @@ declare interface RestCache {
     readonly audience?: (output: unknown, input: unknown, subject: Subject) => 'public' | 'private';
 }
 
+/** Cross-origin browser access for one route. Origins are exact, including opaque `null`. */
+declare interface RestCors {
+    readonly origins: ReadonlyArray<string>;
+    readonly headers?: ReadonlyArray<string>;
+    readonly methods?: ReadonlyArray<RestMethod>;
+    /** Preflight cache lifetime in seconds. */
+    readonly maxAge?: number;
+    readonly exposeHeaders?: ReadonlyArray<string>;
+}
+
 export declare type RestDates = 'iso' | 'epoch-ms';
 
 export declare type RestEnvelope = 'none' | 'data' | 'jsonapi';
@@ -5279,6 +5421,13 @@ export declare type RestNaming = 'camelCase' | 'snake_case';
 
 export declare type RestPagination = 'link-header' | 'body-cursor';
 
+/** Uses the mounted rate-limit plugin's store, algorithms and dynamic policy. */
+declare interface RestRateLimit {
+    readonly limit: number;
+    readonly window: string;
+    readonly by?: 'subject' | 'tenant' | 'apiKey' | 'ip' | 'global';
+}
+
 /** A schema-encoded REST body with an application-selected HTTP status and
  *  response headers. The marker keeps ordinary domain objects unambiguous.
  *  `output` still validates/encodes `body`; use `Schema.Void` with a 204 when
@@ -5377,6 +5526,10 @@ declare interface RestRouteDescriptor<I, O> {
      */
     readonly version?: `v${number}`;
     readonly guards?: ReadonlyArray<RestGuard>;
+    readonly cors?: RestCors;
+    /** Only an explicit bearer header may authenticate; cookies are removed before auth and context construction. */
+    readonly credentials?: 'bearer';
+    readonly rateLimit?: RestRateLimit;
     /**
      * This route STREAMS (Server-Sent Events) rather than resolving one value — its
      * handler returns `sse(...)`. Declared on the descriptor, not left implicit in
@@ -5436,6 +5589,35 @@ declare interface RestRouteProjection {
     readonly format: RestFormat;
 }
 
+/**
+ * Default ctx resolver used when the serve pipeline doesn't inject one
+ * (e.g. unit tests). Real mounts pass a resolver that reads the framework's
+ * auth subject + the bound DataStore.
+ */
+declare interface RestServeBindings {
+    /** Bound once from the app's mounted rate-limit plugin. */
+    readonly rateLimit?: (policy: RestRateLimit, ctx: RestRouteContext, route: RestRouteDescriptor<any, any>) => Effect.Effect<void, unknown>;
+    /** Resolve the calling subject from the request headers. */
+    readonly resolveSubject?: (headers: Readonly<Record<string, string>>) => Subject | Promise<Subject>;
+    /** The bound framework DataStore. */
+    readonly store?: unknown;
+    /** Build the full per-request app context after authentication. */
+    readonly buildContext?: (subject: Subject, headers: Readonly<Record<string, string>>) => unknown | Promise<unknown>;
+    /**
+     * HTTP idempotency — when set, a mutating request (POST/PUT/PATCH/DELETE)
+     * carrying the `header` is deduplicated: the first call runs + caches its
+     * response; a replay within `ttlMs` returns the cached response
+     * (`Idempotency-Replayed: true`); an in-flight duplicate gets `409`. Scoped
+     * per (tenant, method, path). The serve path injects the store + config from
+     * `app.config.ts`'s `idempotency` field.
+     */
+    readonly idempotency?: {
+        readonly store: IdempotencyStore;
+        readonly header: string;
+        readonly ttlMs: number;
+    };
+}
+
 /**
  * What a REST handler returns to stream its response instead of resolving one
  * value: `sse((emit) => unsubscribe)`. The route's schema `output` is not used
@@ -5584,6 +5766,10 @@ export declare type RpcInterceptor = (next: Effect.Effect<unknown, unknown>, con
  * them automatically.
  */
 export declare interface RpcInterceptorContext {
+    /** Enqueue a settled invocation outcome on the host's root store, outside
+     * the business transaction. Required transactional success capture must use
+     * MutationCommitContext.outbox instead. Older/custom hosts may omit this. */
+    readonly enqueueOutcome?: OutboxEnqueueFacade['enqueue'];
     /** Procedure tag, e.g. `todos.create`. */
     readonly tag: string;
     /** Discriminator — `'mutation' | 'query' | 'action' | 'workflow'`. */
@@ -5977,6 +6163,9 @@ export declare const sessionValueFromHeaders: (headers: Readonly<Record<string,
  */
 export declare const setEffectiveScopes: (subject: Subject, scopes: ReadonlyArray<string>) => void;
 
+/** Register a request's dynamic role/permission resolver for live delivery. */
+export declare const setEffectiveScopesRefresher: (subject: Subject, refresh: (fresh: Subject) => Promise<void>) => void;
+
 /** Register (or clear) the process-global policy-guard resolver. Last write
  *  wins. The runtime installs one backed by the resource-policy registry and
  *  the registered tuple source. */
@@ -6430,7 +6619,7 @@ export declare const subscriptionEvent: <D extends Schema.Top>(data: D) => Schem
     }>;
 }>, Schema.Struct<{
     readonly _tag: Schema.Literal<"error">;
-    readonly error: Schema.Unknown;
+    readonly error: Schema.decodeTo<Schema.Unknown, Schema.Codec<Schema.Json, Schema.Json, never, never>, never, never>;
     readonly revision: Schema.optional<Schema.Number>;
 }>]>;
 
@@ -6710,7 +6899,7 @@ export declare const toRpc: <Name extends string, Input extends Schema.Top, Outp
     }>;
 }>, Schema.Struct<{
     readonly _tag: Schema.Literal<"error">;
-    readonly error: Schema.Unknown;
+    readonly error: Schema.decodeTo<Schema.Unknown, Schema.Codec<Schema.Json, Schema.Json, never, never>, never, never>;
     readonly revision: Schema.optional<Schema.Number>;
 }>]>, Schema.Top>, Schema.Never, never, never> | Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Output, Schema.Top, never, never> | Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Output, Schema.Top>, Schema.Never, never, never>;
 
@@ -6865,6 +7054,9 @@ export declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Rec
     readonly shapeItem?: ((input: Input, current: Item) => Item) | undefined;
 }
 
+/** Refuse malformed runtime contributions before starting a worker. */
+export declare function validateOutboxHandlerDefinition(value: unknown, owner: string): asserts value is OutboxHandlerDefinition<unknown>;
+
 /**
  * A server-side validation failure pinned to ONE field.
  *
@@ -7048,6 +7240,16 @@ export declare interface VoltroPlugin {
      * (schema-only / lifecycle-only plugins are fine).
      */
     readonly interceptMutation?: RpcInterceptor;
+    /** Runs after successful executor and business-rule evaluation, before the
+     * transaction commits. Use only the supplied store for required records or
+     * durable intents. External I/O is prohibited; transaction retries replay
+     * this hook. Requires rpc:intercept:mutation and store:write permissions.
+     * Ordinary RPC interceptors retain their existing outside-transaction scope. */
+    readonly beforeMutationCommit?: MutationCommitHook;
+    /** Post-commit delivery handlers, registered with the shared app worker in
+     * Dev and serve. Requires outbox:handle; effects must not collide with app,
+     * framework or other plugin contributions. Handlers must be idempotent. */
+    readonly outboxHandlers?: ReadonlyArray<OutboxHandlerDefinition<unknown>>;
     /**
      * Wraps every QUERY (streaming subscription handler) call. Same
      * composition semantics as `interceptMutation`. Most observability
@@ -7332,6 +7534,8 @@ export declare interface VoltroPlugin {
      * SDK here). Returns of `undefined`/empty are no-ops.
      */
     readonly contributeObservability?: (ctx: PluginLifecycleContext) => Promise<ObservabilityContribution | undefined> | ObservabilityContribution | undefined;
+    /** Enforce a hand-authored REST route's quota through this plugin. */
+    readonly restRateLimit?: RestServeBindings['rateLimit'];
     /**
      * Told the app's mounted REST surface — hand-authored `restRoutes` AND the
      * routes projected from `publicApi` annotations — once the boot has built it,