@voltro/protocol 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -31,11 +31,19 @@ export declare interface ActionProcedureDescriptor<Name extends string, Input ex
     readonly target: TargetSpec | ReadonlyArray<TargetSpec> | undefined;
     /** Declarative authorization guard(s) — enforced before the executor runs,
      *  failing with a typed `ScopeError`. Absent → no framework-level authz. */
-    readonly guards: Guards | undefined;
+    readonly guards: DeclaredAccess | undefined;
+    /** The declared reason this procedure needs NO authorization check —
+     *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
+     *  the only two shapes `security.defaultDeny` accepts. */
+    readonly openAccess: string | undefined;
     /** Opt this action into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this action into the auto-synthesized agent toolset (innovation/07). */
     readonly exposeAsTool: ExposeAsTool | undefined;
+    /** Require a SECOND human to approve before this action takes effect. The gate
+     *  runs in the dispatch spine after `guards:` and BEFORE the executor's
+     *  external I/O — the only point at which nothing has happened yet. */
+    readonly requiresApproval: AnyApprovalPolicy | undefined;
     /** True when the procedure is kept OFF the wire — no client-group entry and no
      *  route in dev or serve. See `internal` on the definer's options. */
     /**
@@ -73,8 +81,16 @@ export declare const advisoryResourceGuardWarning: (tags: ReadonlyArray<string>)
 
 export declare const anonymousSubject: (tenantId: string | null) => Subject;
 
-/** A guard entry is either a scope check or a relationship check. */
-export declare type AnyCheckSpec = GuardCheckSpec | PolicyCheckSpec;
+/** The erased policy a descriptor carries (input generic dropped). */
+export declare interface AnyApprovalPolicy {
+    readonly approvers: Guards;
+    readonly expiresIn?: string;
+    readonly reason?: string;
+}
+
+/** A guard entry is a scope check, a relationship check, or a declared
+ *  no-check-needed decision. */
+export declare type AnyCheckSpec = GuardCheckSpec | PolicyCheckSpec | OpenAccessSpec;
 
 /** Any declared event, with the generics erased — for registries and audits. */
 export declare type AnyEventDescriptor = EventDescriptor<string, Schema.Schema.Any, Schema.Schema.Any>;
@@ -113,6 +129,13 @@ export declare const APIKEY_ISSUE_OTHER_SCOPE = "apikeys:issue:other";
  */
 export declare const APIKEY_ISSUE_SELF_SCOPE = "apikeys:issue:self";
 
+/** The subject a decision produces, plus what the decision took away. `removed`
+ *  is never non-empty for a `grant`. */
+export declare interface AppliedScopes {
+    readonly subject: Subject;
+    readonly removed: ReadonlyArray<string>;
+}
+
 /**
  * Apply a `RowPatch` to `prev`, producing `next`. Exact inverse of
  * `diffRows`: `applyRowPatch(prev, diffRows(prev, next))` deep-equals
@@ -128,6 +151,275 @@ export declare const APIKEY_ISSUE_SELF_SCOPE = "apikeys:issue:self";
  */
 export declare const applyRowPatch: (prev: ReadonlyArray<PatchRow>, patch: RowPatch) => ReadonlyArray<PatchRow>;
 
+/**
+ * Apply a decision to a Subject, touching nothing but `scopes`.
+ *
+ * An `anonymous` subject has no `scopes` field in its schema and is returned
+ * untouched under BOTH kinds — writing one onto it would produce a value that
+ * no longer decodes as the Subject it claims to be.
+ */
+export declare const applyScopeDecision: (subject: Subject, decision: Exclude<ScopeDecision, {
+    kind: "unavailable";
+}>) => AppliedScopes;
+
+/** The union the `__voltro.approvals.decide` built-in advertises. */
+export declare const ApprovalDecisionErrors: Schema.Union<[typeof ApprovalNotFound, typeof ApprovalSelfApproval, typeof ApprovalExpired, typeof ApprovalNotPending, typeof ApprovalForbidden, typeof ApprovalUnavailable]>;
+
+/**
+ * The union every approval-requiring descriptor advertises on the wire.
+ *
+ * Merged in `mutationToRpc` / `actionToRpc` at the SAME lifter the server group
+ * and the generated client group both call — the identical argument
+ * `withGuardError` makes for `ScopeError`: a denial the framework can produce
+ * before the executor MUST be in the error union or it crosses as an untyped
+ * defect and the client cannot branch on it.
+ */
+export declare const ApprovalErrors: Schema.Union<[typeof ApprovalRequired, typeof ApprovalRejected, typeof ApprovalExpired, typeof ApprovalUnavailable]>;
+
+/** Past `expiresAt`. Fails closed: neither approvable nor executable. */
+export declare class ApprovalExpired extends ApprovalExpired_base {
+}
+
+declare const ApprovalExpired_base: Schema.TaggedErrorClass<ApprovalExpired, "ApprovalExpired", {
+    readonly _tag: Schema.tag<"ApprovalExpired">;
+} & {
+    approvalId: typeof Schema.String;
+    expiredAt: typeof Schema.String;
+}>;
+
+/** The would-be approver does not satisfy the intent's own `approvers` guards. */
+export declare class ApprovalForbidden extends ApprovalForbidden_base {
+}
+
+declare const ApprovalForbidden_base: Schema.TaggedErrorClass<ApprovalForbidden, "ApprovalForbidden", {
+    readonly _tag: Schema.tag<"ApprovalForbidden">;
+} & {
+    approvalId: typeof Schema.String;
+    /** The scope whose absence denied them, when the denial was scope-shaped. */
+    required: Schema.NullOr<typeof Schema.String>;
+    message: typeof Schema.String;
+}>;
+
+/** The identity of an approval intent, as a wire string. */
+export declare type ApprovalId = string;
+
+/** No approval row with that id (wrong id, or swept past retention). */
+export declare class ApprovalNotFound extends ApprovalNotFound_base {
+}
+
+declare const ApprovalNotFound_base: Schema.TaggedErrorClass<ApprovalNotFound, "ApprovalNotFound", {
+    readonly _tag: Schema.tag<"ApprovalNotFound">;
+} & {
+    approvalId: typeof Schema.String;
+}>;
+
+/** Already decided (or already consumed) — a decision is made once. */
+export declare class ApprovalNotPending extends ApprovalNotPending_base {
+}
+
+declare const ApprovalNotPending_base: Schema.TaggedErrorClass<ApprovalNotPending, "ApprovalNotPending", {
+    readonly _tag: Schema.tag<"ApprovalNotPending">;
+} & {
+    approvalId: typeof Schema.String;
+    status: typeof Schema.String;
+}>;
+
+/**
+ * Declare that a mutation/action needs a SECOND human before it takes effect.
+ *
+ * ```ts
+ * export default defineMutation({
+ *   name: 'invoices.refund',
+ *   guards: [{ scope: 'invoices:refund' }],
+ *   requiresApproval: {
+ *     approvers: [{ scope: 'invoices:approve' }],
+ *     expiresIn: '4h',
+ *     reason: 'refunds move money out of the account',
+ *   },
+ *   // …
+ * })
+ * ```
+ *
+ * The first call records the intent and fails with a typed `ApprovalRequired`
+ * carrying the approval id. Once an authorised, DIFFERENT subject approves it,
+ * the identical call succeeds — once.
+ */
+export declare interface ApprovalPolicy<Input = unknown> {
+    /**
+     * WHO MAY APPROVE. The same `guards:` vocabulary the procedure itself uses,
+     * evaluated against the APPROVER's effective scope set at decision time.
+     *
+     * Required and non-empty. An approval step whose authority is "anyone" is not
+     * a control — it is a second click, and it reads in review like a control.
+     * `defineMutation` refuses an empty list at declaration for the same reason
+     * `guards: []` is refused.
+     */
+    readonly approvers: Guards<Input>;
+    /**
+     * How long the pending intent stays approvable — an interval string (`'30m'`,
+     * `'4h'`, `'7d'`).
+     *
+     * Absent → the app's `approvals.expiresIn` tunable, else 24 h. There is no
+     * "never expires": an approval queue with no floor is a list of decisions
+     * nobody made, and the framework FAILS CLOSED past the deadline (an expired
+     * intent can be neither approved nor executed — the requester re-submits and
+     * a fresh decision is asked for).
+     */
+    readonly expiresIn?: string;
+    /** Shown to the approver — why this call needs a second person. */
+    readonly reason?: string;
+}
+
+/**
+ * An approver said NO, and this is the requester learning about it.
+ *
+ * Reported on the retry rather than pushed, because the requester's call is
+ * what has to stop happening. Reported ONCE: the gate frees the intent's content
+ * key as it raises this, so a deliberate re-submit afterwards opens a genuinely
+ * new decision instead of silently reusing a dead one — a rejection is a verdict
+ * on one request, not a permanent ban on the operation.
+ */
+export declare class ApprovalRejected extends ApprovalRejected_base {
+}
+
+declare const ApprovalRejected_base: Schema.TaggedErrorClass<ApprovalRejected, "ApprovalRejected", {
+    readonly _tag: Schema.tag<"ApprovalRejected">;
+} & {
+    approvalId: typeof Schema.String;
+    decidedBy: Schema.NullOr<typeof Schema.String>;
+    note: Schema.NullOr<typeof Schema.String>;
+}>;
+
+/**
+ * The call was RECORDED as a pending approval and did NOT run.
+ *
+ * This is the answer the caller gets meanwhile, and it is a typed failure rather
+ * than a success with a status field on purpose: a mutation that returns its
+ * normal output shape when nothing happened is the single easiest thing for a
+ * client to mis-handle, and every existing client already branches on `_tag`.
+ */
+export declare class ApprovalRequired extends ApprovalRequired_base {
+}
+
+declare const ApprovalRequired_base: Schema.TaggedErrorClass<ApprovalRequired, "ApprovalRequired", {
+    readonly _tag: Schema.tag<"ApprovalRequired">;
+} & {
+    approvalId: typeof Schema.String;
+    procedure: typeof Schema.String;
+    /** ISO instant past which this intent can no longer be approved. */
+    expiresAt: typeof Schema.String;
+    /** The scope(s) an approver must hold — so the UI can say who to ask. */
+    requiredScopes: Schema.Array$<typeof Schema.String>;
+    /** The declared `reason`, when the descriptor gave one. */
+    reason: Schema.NullOr<typeof Schema.String>;
+    /** True when THIS call created the intent; false when it found the one an
+     *  earlier identical call had already recorded. Lets a client tell "I just
+     *  asked" from "still waiting". */
+    created: typeof Schema.Boolean;
+}>;
+
+export declare const APPROVALS_DECIDE_TAG: "__voltro.approvals.decide";
+
+export declare const APPROVALS_PENDING_TAG: "__voltro.approvals.pending";
+
+/**
+ * `__voltro.approvals.decide` — approve or reject ONE pending intent.
+ *
+ * `openAccess` here for a structurally different reason from the query's, and
+ * the distinction is worth keeping straight: the authority IS real and IS
+ * checked, it just cannot be expressed on the descriptor. Which scopes an
+ * approver needs is a property of the PENDING ROW (copied from the target
+ * procedure's own `requiresApproval.approvers` when the intent was recorded), so
+ * one descriptor-level scope would have to be the union of every
+ * approval-requiring procedure in the app — a scope that grants strictly more
+ * than any single approval does, which is the rubber stamp in its most damaging
+ * form.
+ *
+ * So the check is per row, in the executor, against the intent's own guards,
+ * plus the unconditional self-approval refusal.
+ */
+export declare const approvalsDecideDescriptor: MutationProcedureDescriptor<"__voltro.approvals.decide", Schema.Struct<{
+    approvalId: typeof Schema.String;
+    decision: Schema.Literal<["approve", "reject"]>;
+    note: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    approvalId: typeof Schema.String;
+    status: Schema.Literal<["approved", "rejected"]>;
+}>, Schema.Union<[ ApprovalNotFound, ApprovalSelfApproval, ApprovalExpired, ApprovalNotPending, ApprovalForbidden, ApprovalUnavailable]>>;
+
+/**
+ * The approver IS the requester.
+ *
+ * Refused unconditionally, with no opt-out flag. The whole content of
+ * "a second human" is that it is a second one; a framework that shipped
+ * `allowSelfApproval: true` would be shipping a control that every app under
+ * deadline pressure turns off, and the audit row would still read "approved".
+ */
+export declare class ApprovalSelfApproval extends ApprovalSelfApproval_base {
+}
+
+declare const ApprovalSelfApproval_base: Schema.TaggedErrorClass<ApprovalSelfApproval, "ApprovalSelfApproval", {
+    readonly _tag: Schema.tag<"ApprovalSelfApproval">;
+} & {
+    approvalId: typeof Schema.String;
+    subjectId: Schema.NullOr<typeof Schema.String>;
+}>;
+
+/**
+ * `__voltro.approvals.pending` — the calling subject's approval work.
+ *
+ * Reactive on `_voltro_approvals`, which is what answers "what does the caller
+ * see meanwhile": the requester watches their own row flip `pending →
+ * approved` and re-fires the mutation, and the approver's queue appears without
+ * a poll.
+ *
+ * `openAccess`, not a scope guard, deliberately. There is no scope that means
+ * "may see my own approval work" — every caller has some — and inventing one
+ * would be exactly the rubber-stamp guard the `openAccess` doc warns about. The
+ * answer is SUBJECT-SCOPED IN THE EXECUTOR: a row appears only if the caller
+ * requested it or satisfies its recorded `approvers` guards, so an anonymous
+ * caller sees an empty list.
+ */
+export declare const approvalsPendingQueryDescriptor: QueryProcedureDescriptor<"__voltro.approvals.pending", Schema.Struct<{
+    limit: Schema.optional<typeof Schema.Number>;
+}>, Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    procedure: typeof Schema.String;
+    kind: Schema.Literal<["mutation", "action"]>;
+    requestedBy: Schema.NullOr<typeof Schema.String>;
+    status: Schema.Literal<["pending", "approved", "rejected", "expired", "consumed"]>;
+    reason: Schema.NullOr<typeof Schema.String>;
+    requiredScopes: Schema.Array$<typeof Schema.String>;
+    requestedAt: typeof Schema.String;
+    expiresAt: typeof Schema.String;
+    decidedBy: Schema.NullOr<typeof Schema.String>;
+    decidedAt: Schema.NullOr<typeof Schema.String>;
+    note: Schema.NullOr<typeof Schema.String>;
+    relation: Schema.Literal<["to-decide", "requested"]>;
+}>>, typeof Schema.Never>;
+
+/** The lifecycle states a `_voltro_approvals` row moves through. */
+export declare type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'consumed';
+
+/**
+ * The procedure declares `requiresApproval` and the framework could not reach
+ * the approvals store — so it cannot record the intent and cannot know whether
+ * one was granted.
+ *
+ * FAIL CLOSED. Running the mutation because the bookkeeping is unavailable is
+ * exactly the shape of hole the declaration exists to close; the requester sees
+ * a refusal they can report, which is the useful outcome.
+ */
+export declare class ApprovalUnavailable extends ApprovalUnavailable_base {
+}
+
+declare const ApprovalUnavailable_base: Schema.TaggedErrorClass<ApprovalUnavailable, "ApprovalUnavailable", {
+    readonly _tag: Schema.tag<"ApprovalUnavailable">;
+} & {
+    procedure: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+
 /**
  * Throws `Unauthenticated` when the resolved Subject is anonymous (no
  * real user identity). Handlers that require a signed-in caller put
@@ -297,6 +589,15 @@ declare const BusinessRuleViolation_base: Schema.TaggedErrorClass<BusinessRuleVi
     severity: Schema.Literal<["error", "warning"]>;
 }>;
 
+/** The result of a cached resolution. `fresh` distinguishes a resolution that
+ *  actually ran from a replayed verdict — the audit hook fires on the former
+ *  only, so a narrowed subject logs once per window instead of once per
+ *  request. */
+export declare interface CachedScopeDecision {
+    readonly decision: ScopeDecision;
+    readonly fresh: boolean;
+}
+
 /**
  * Validate `plugin.framework` (npm-semver range) against the running
  * voltro version. Returns either `{ ok: true }` or
@@ -325,12 +626,14 @@ export declare const checkFrameworkCompat: (pluginName: string, range: string |
 /**
  * Check a descriptor's declared `guards:` against a subject's EFFECTIVE scopes.
  * Returns a typed `ScopeError` naming the first unmet scope, or `null` when
- * every guard is satisfied (or there are no guards). Pure + synchronous — the
- * runtime calls it in the dispatch spine BEFORE the executor (and, for
- * mutations, before the transaction opens). The `admin:full` bypass passes
- * everything.
+ * every guard is satisfied. Pure + synchronous — the runtime calls it in the
+ * dispatch spine BEFORE the executor (and, for mutations, before the
+ * transaction opens). The `admin:full` bypass passes everything.
+ *
+ * No guards at all is ALLOWED unless the caller passes `defaultDeny` — see the
+ * note above for why that decision is not made process-globally here.
  */
-export declare const checkGuards: (subject: Subject, guards: ReadonlyArray<AnyCheckSpec> | undefined) => ScopeError | null;
+export declare const checkGuards: (subject: Subject, guards: ReadonlyArray<AnyCheckSpec> | undefined, options?: GuardCheckOptions) => ScopeError | null;
 
 /**
  * The resource-aware counterpart of `checkGuards`. Identical semantics when no
@@ -347,7 +650,7 @@ export declare const checkGuards: (subject: Subject, guards: ReadonlyArray<AnyCh
  * every guard passes. The runtime calls this in the dispatch spine BEFORE the
  * executor (mutations: before the transaction opens).
  */
-export declare const checkGuardsEffect: (subject: Subject, guards: ReadonlyArray<AnyCheckSpec> | undefined, input: unknown) => Effect.Effect<ScopeError | null>;
+export declare const checkGuardsEffect: (subject: Subject, guards: ReadonlyArray<AnyCheckSpec> | undefined, input: unknown, options?: GuardCheckOptions) => Effect.Effect<ScopeError | null>;
 
 export declare interface ClientDescriptor {
     readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'workflow';
@@ -438,16 +741,61 @@ export declare const composeAuthStrategies: (strategies: ReadonlyArray<AuthStrat
      * bag could overwrite the framework's claim about who a request was. The
      * strategy owns identity; this owns authority.
      *
-     * Returned scopes are UNIONED with whatever the strategy already set, so a
-     * resolver cannot silently remove a scope either.
+     * **It is now the ONLY place a session's authority comes from.** The
+     * framework's session cookie carries `SubjectIdentity` — no scopes — so for
+     * a cookie-authenticated caller the strategy establishes nothing to union
+     * with, and whatever this returns IS the caller's authority. Remove a role
+     * and the next resolution reflects it; there is nothing frozen left to
+     * override. An app that gates on scopes and wires no resolver has callers
+     * with no scopes, which is the fail-closed direction.
+     *
+     * **Return shape.** A bare `ReadonlyArray<string>` means
+     * `{ kind: 'grant' }` — unioned, exactly as before. Return
+     * `{ kind: 'authoritative', scopes }` to make this resolver the complete
+     * answer, which is how you narrow a subject whose scopes came from a TOKEN
+     * (a JWT's `scopesFromClaims`, an api key's record) rather than a cookie.
+     * Return `{ kind: 'unavailable', reason }` when the lookup itself failed —
+     * the request then fails closed with `Unauthenticated` and the reason
+     * reaches `onStrategyFailed`, instead of an empty array being mistaken for
+     * a policy decision.
      *
      * Runs only on a MATCHED subject — never for anonymous, where there is no
-     * identity to look a role up for. It is on the request path, so cache it
-     * (a per-connection or short-TTL map keyed by subject id); the framework
-     * deliberately does not cache for you, because only the app knows how
-     * quickly a role change must take effect.
+     * identity to look a role up for. It is on the request path and the
+     * framework caches it for you (`scopeCache`, 30s by default, invalidatable
+     * — see below); a resolver whose answer depends on anything other than the
+     * subject's identity must set `scopeCache: false`.
+     */
+    readonly resolveScopes?: (subject: Subject, input: AuthStrategyInput) => Promise<ScopeResolverResult> | ScopeResolverResult;
+    /**
+     * How resolved authority is cached. Omit for the default window
+     * (`DEFAULT_SCOPE_CACHE_TTL_MS`, 30s — the same window the session
+     * revocation check uses, so the two store reads miss together).
+     *
+     *   - `ScopeCacheOptions` — tune the window in place: `{ ttlMs: 0 }`
+     *     resolves on every request, staleness zero.
+     *   - a `ScopeCache` from `makeScopeCache()` — you keep the handle and call
+     *     `invalidate(scopeCacheKey(subject))` from whatever changes a role.
+     *     Zero staleness on this process, `ttlMs` on other replicas.
+     *   - `false` — no caching at all. Required when the resolver reads
+     *     anything beyond the subject's identity (a header, a request path),
+     *     because the cache key is the identity and nothing else.
      */
-    readonly resolveScopes?: (subject: Subject, input: AuthStrategyInput) => Promise<ReadonlyArray<string>> | ReadonlyArray<string>;
+    readonly scopeCache?: ScopeCache | ScopeCacheOptions | false;
+    /**
+     * Called when an `authoritative` resolution REMOVED scopes the strategy had
+     * established — the audit trail for narrowing.
+     *
+     * Narrowing is a security-relevant event and it must not be inferable only
+     * by its absence. It fires on a fresh resolution, not on a cache replay, so
+     * a narrowed caller logs once per window rather than once per request.
+     */
+    readonly onScopesNarrowed?: (event: {
+        strategyId: string;
+        subjectType: Subject["type"];
+        subjectId: string | null;
+        removed: ReadonlyArray<string>;
+        granted: ReadonlyArray<string>;
+    }) => void;
     /**
      * Hands every strategy the app's store on `input.store`.
      *
@@ -478,6 +826,15 @@ export declare const CONNECTION_START_TAG: "__voltro.connections.start";
 
 export declare const CONNECTION_SUBMIT_TOKEN_TAG: "__voltro.connections.submitToken";
 
+export declare interface ConnectionCredential {
+    /** Cookies to set or replace INSIDE the connection's `Cookie` header. Other
+     *  cookies on the connection are left alone. */
+    readonly cookies?: Readonly<Record<string, string>>;
+    /** Headers to set or replace outright (`authorization`, a custom token
+     *  header). Matched case-insensitively. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+
 /** `__voltro.connections.disconnect` — forget the calling subject's credential
  *  for this connection. Deletes the row; the provider-side grant (if any) is
  *  the provider's to revoke. */
@@ -763,6 +1120,28 @@ export declare interface CoordinatedTickOutcome {
     readonly nextDueInMs?: number;
 }
 
+/**
+ * What a descriptor CARRIES: the author's guards, or the erased form of their
+ * `openAccess:` decision — never both.
+ *
+ * The option a user writes is still `Guards` (an `OpenAccessSpec` is not
+ * something to hand-write into `guards:`; there is one spelling for the
+ * decision and it is the `openAccess:` field). The DESCRIPTOR type is wider
+ * because that is where the normalised decision lands, and because every
+ * enforcement path reads the descriptor's array and nothing else.
+ */
+export declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec>;
+
+/** Every channel declared in this process, by routing key. */
+export declare const declaredReactivityChannelKeys: () => ReadonlySet<string>;
+
+/** Default cap on cached subjects before the cache sweeps + trims. */
+export declare const DEFAULT_SCOPE_CACHE_MAX_ENTRIES = 10000;
+
+/** Default scope-cache window. Matches the session-revocation window on
+ *  purpose: the two per-request store reads then expire together. */
+export declare const DEFAULT_SCOPE_CACHE_TTL_MS = 30000;
+
 export declare const defineAction: <const Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All = typeof Schema.Never>(options: {
     readonly name: Name;
     readonly input: Input;
@@ -772,6 +1151,24 @@ export declare const defineAction: <const Name extends string, Input extends Sch
      *  scope(s) or the action fails with a typed `ScopeError` before the executor
      *  runs. `ScopeError` is auto-merged into the wire error union. */
     readonly guards?: Guards<Schema.Schema.Type<Input>>;
+    /**
+     * Declare that this procedure needs NO authorization check — and say why.
+     *
+     * The other half of `security.defaultDeny`. With the flag on, a procedure
+     * that declares neither `guards:` nor this is refused at boot, by name: an
+     * access decision nobody made is the SEC-1 hole, not a default.
+     *
+     * Use it for the endpoints that really are open — a health check, a public
+     * price list, a signup precheck. Do NOT reach for a scope every caller
+     * already holds just to satisfy the gate: that guard reads as protection and
+     * enforces nothing, and it is the failure mode this field exists to prevent.
+     *
+     * The reason is required and is the point — it is what a reviewer reads and
+     * what `voltro doctor` prints beside the tag.
+     *
+     *     openAccess: 'public pricing page — reads no caller data'
+     */
+    readonly openAccess?: string;
     /** Table(s) this action READS. Declaring it is what lets `voltro check` know
      *  the table is alive — without it, a table only an action touches reads as
      *  an orphan. See `ActionProcedureDescriptor.source`. */
@@ -782,6 +1179,15 @@ export declare const defineAction: <const Name extends string, Input extends Sch
     readonly publicApi?: PublicApiSpec;
     /** Expose this action as an agent tool (innovation/07). */
     readonly exposeAsTool?: ExposeAsTool;
+    /**
+     * Require a SECOND human to approve before this action takes effect.
+     *
+     * Same contract as a mutation's, and the gate runs at the same point relative
+     * to the work: after `guards:`, BEFORE the executor. For an action that is the
+     * only point at which nothing has happened yet — there is no transaction to
+     * roll back an outbound HTTP call.
+     */
+    readonly requiresApproval?: ApprovalPolicy<Schema.Schema.Type<Input>>;
     /**
      * Keep this procedure OFF the wire entirely.
      *
@@ -862,6 +1268,27 @@ export declare const defineEvent: <const Name extends string, Key extends Schema
      * makes throughput scale with the audience instead of the publish rate.
      */
     readonly guards?: Guards<Schema.Schema.Type<Key>>;
+    /**
+     * Declare that this event needs NO authorization check — and say why.
+     *
+     * The other half of `security.defaultDeny`, exactly as on a procedure. With
+     * the flag on, an event that declares neither `guards:` nor this is refused
+     * at boot, by name: an access decision nobody made is the SEC-1 hole, not a
+     * default — and an event with no decision is subscribable by ANY
+     * authenticated session that can open the socket.
+     *
+     * Use it for the events that really are open — a public scoreboard tick, a
+     * status broadcast, a service-health pulse. Do NOT reach for a scope every
+     * caller already holds just to satisfy the gate: that guard reads as
+     * protection and enforces nothing, and it is the failure mode this field
+     * exists to prevent.
+     *
+     * The reason is required and is the point — it is what a reviewer reads and
+     * what `voltro doctor` prints beside the tag.
+     *
+     *     openAccess: 'public scoreboard — carries no caller data'
+     */
+    readonly openAccess?: string;
     /**
      * Deliver recently-buffered events on a FIRST attach. Default `false`, and the
      * default is the interesting half.
@@ -912,10 +1339,41 @@ export declare const defineMutation: <const Name extends string, Input extends S
      *  scope(s) or the mutation fails with a typed `ScopeError` BEFORE the
      *  transaction opens. `ScopeError` is auto-merged into the wire error union. */
     readonly guards?: Guards<Schema.Schema.Type<Input>>;
+    /**
+     * Declare that this procedure needs NO authorization check — and say why.
+     *
+     * The other half of `security.defaultDeny`. With the flag on, a procedure
+     * that declares neither `guards:` nor this is refused at boot, by name: an
+     * access decision nobody made is the SEC-1 hole, not a default.
+     *
+     * Use it for the endpoints that really are open — a health check, a public
+     * price list, a signup precheck. Do NOT reach for a scope every caller
+     * already holds just to satisfy the gate: that guard reads as protection and
+     * enforces nothing, and it is the failure mode this field exists to prevent.
+     *
+     * The reason is required and is the point — it is what a reviewer reads and
+     * what `voltro doctor` prints beside the tag.
+     *
+     *     openAccess: 'public pricing page — reads no caller data'
+     */
+    readonly openAccess?: string;
     /** Project this mutation as a public REST endpoint (innovation/11). */
     readonly publicApi?: PublicApiSpec;
     /** Expose this mutation as an agent tool (innovation/07). */
     readonly exposeAsTool?: ExposeAsTool;
+    /**
+     * Require a SECOND human to approve before this mutation takes effect.
+     *
+     * The first call records a durable pending intent and fails with a typed
+     * `ApprovalRequired` carrying its id; the transaction never opens. Once an
+     * authorised, DIFFERENT subject approves, the IDENTICAL call succeeds exactly
+     * once (the approval is consumed).
+     *
+     * Composes with `guards:` rather than replacing them — the requester still has
+     * to be allowed to ASK. Refused together with `openAccess:` (see
+     * `assertApprovalPolicyCoherent`).
+     */
+    readonly requiresApproval?: ApprovalPolicy<Schema.Schema.Type<Input>>;
     /**
      * Keep this procedure OFF the wire entirely.
      *
@@ -1001,14 +1459,37 @@ export declare const defineQuery: <const Name extends string, Input extends Sche
      *  auto-optimistic patch routing from mutations targeting any of those
      *  tables. For a COMPUTED query (handler returns a shaped value) it is the
      *  reactive trigger set: the handler re-runs when ANY listed table changes
-     *  — pass an array to depend on several (e.g. a matrix joining two tables). */
-    readonly source?: string | ReadonlyArray<string>;
+     *  — pass an array to depend on several (e.g. a matrix joining two tables).
+     *
+     *  A `reactivityChannel(...)` is accepted here too, for state that pushes
+     *  without living in a table. Pass the CHANNEL, not its key string: the
+     *  import edge is what makes a channel `source:` impossible to leave stale,
+     *  which a table name (a bare string) can always be. */
+    readonly source?: ReactivitySource | ReadonlyArray<ReactivitySource>;
     /** Opt into server-side snapshot caching with auto-invalidation. */
     readonly cache?: QueryCacheConfig;
     /** Declarative authorization guard(s) — the caller must hold the named
      *  scope(s) or the query fails with a typed `ScopeError` before the executor
      *  runs. `ScopeError` is auto-merged into the wire error union. */
     readonly guards?: Guards<Schema.Schema.Type<Input>>;
+    /**
+     * Declare that this procedure needs NO authorization check — and say why.
+     *
+     * The other half of `security.defaultDeny`. With the flag on, a procedure
+     * that declares neither `guards:` nor this is refused at boot, by name: an
+     * access decision nobody made is the SEC-1 hole, not a default.
+     *
+     * Use it for the endpoints that really are open — a health check, a public
+     * price list, a signup precheck. Do NOT reach for a scope every caller
+     * already holds just to satisfy the gate: that guard reads as protection and
+     * enforces nothing, and it is the failure mode this field exists to prevent.
+     *
+     * The reason is required and is the point — it is what a reviewer reads and
+     * what `voltro doctor` prints beside the tag.
+     *
+     *     openAccess: 'public pricing page — reads no caller data'
+     */
+    readonly openAccess?: string;
     /** Project this query as a public REST endpoint (innovation/11). */
     readonly publicApi?: PublicApiSpec;
     /** Expose this query as an agent tool (innovation/07). */
@@ -1074,6 +1555,24 @@ export declare const defineStream: <const Name extends string, Input extends Sch
      * push. Same shape and same semantics as a query's.
      */
     readonly guards?: Guards;
+    /**
+     * Declare that this procedure needs NO authorization check — and say why.
+     *
+     * The other half of `security.defaultDeny`. With the flag on, a procedure
+     * that declares neither `guards:` nor this is refused at boot, by name: an
+     * access decision nobody made is the SEC-1 hole, not a default.
+     *
+     * Use it for the endpoints that really are open — a health check, a public
+     * price list, a signup precheck. Do NOT reach for a scope every caller
+     * already holds just to satisfy the gate: that guard reads as protection and
+     * enforces nothing, and it is the failure mode this field exists to prevent.
+     *
+     * The reason is required and is the point — it is what a reviewer reads and
+     * what `voltro doctor` prints beside the tag.
+     *
+     *     openAccess: 'public pricing page — reads no caller data'
+     */
+    readonly openAccess?: string;
 }) => StreamProcedureDescriptor<Name, Input, Element, Error>;
 
 export declare interface DeleteTarget<Input = unknown> extends NestedTargetFields<Input> {
@@ -1200,9 +1699,14 @@ export declare interface EventDescriptor<Name extends string, Key extends Schema
     readonly name: Name;
     readonly key: Key;
     readonly payload: Payload;
-    /** Who may LISTEN. Re-checked when the subject changes, not per delivery —
-     *  see `EventDefinition.guards` for why that distinction is deliberate. */
-    readonly guards: Guards<Schema.Schema.Type<Key>> | undefined;
+    /** Who may LISTEN — the author's guards, or the erased form of their
+     *  `openAccess:` decision, never both (see `DeclaredAccess`). Re-checked when
+     *  the subject changes, not per delivery — see `EventDefinition.guards` for
+     *  why that distinction is deliberate. */
+    readonly guards: DeclaredAccess<Schema.Schema.Type<Key>> | undefined;
+    /** The declared `openAccess:` reason, when there is one — what the boot gate
+     *  and `voltro doctor` read. The enforcement paths read `guards`. */
+    readonly openAccess: string | undefined;
     /** Deliver buffered events on a FIRST attach. Default false. */
     readonly rewind: boolean | undefined;
     /** `'each'` (default) or `'latest'` — see the definer. */
@@ -1481,6 +1985,14 @@ export declare const getPolicyGuardResolver: () => PolicyGuardResolver | undefin
 /** The currently-registered resource-scope resolver, or `undefined`. */
 export declare const getResourceScopeResolver: () => ResourceScopeResolver | undefined;
 
+/** Ask for default-deny semantics on one `checkGuards` call. */
+export declare interface GuardCheckOptions {
+    /** Refuse a procedure that declares no access decision at all. */
+    readonly defaultDeny?: boolean;
+    /** The procedure's tag, so the refusal can name it. */
+    readonly procedure?: string;
+}
+
 export declare interface GuardCheckSpec {
     readonly scope: string | ReadonlyArray<string>;
     readonly mode?: 'all' | 'any';
@@ -1506,17 +2018,43 @@ export declare interface GuardSpec<Input = unknown> {
      *  scope); `'any'` = OR (hold at least one). Ignored for a single scope. */
     readonly mode?: 'all' | 'any';
     /**
-     * PURE `input → resource id` extractor for a row/resource-scoped guard.
-     * Browser-safe (no DB, no server import) — exactly like `target.identify`.
-     * The framework passes the extracted id to a resource-aware scope resolver
-     * (a future ReBAC / `accessPolicy()` resolver) so the check can be scoped to
-     * THAT resource. With only the default (subject-global) resolver installed
-     * the id is advisory and the guard checks the subject's global scopes. Omit
-     * for a plain subject-scope guard.
+     * PURE `input → resource id` extractor. Browser-safe (no DB, no server
+     * import) — exactly like `target.identify`. Omit for a plain subject-scope
+     * guard.
+     *
+     * **On a `GuardSpec` this id is ADVISORY.** A scope guard answers "what may
+     * this subject do at all", against the subject's global scope set; the id is
+     * carried for logging and for a future subject-scope resolver that narrows by
+     * resource. It does not, on its own, make the check per-resource.
+     *
+     * **If your authority is per-resource, you want {@link PolicyGuardSpec}, not
+     * this field** — `guards: [{ action, resourceType, resource }]`, backed by
+     * `defineResourcePolicy` + a tuple source you register. That is built, wired
+     * on both boot paths, fail-closed without a resolver, and documented under
+     * *Authentication → Authorization*. An app whose relationships already live
+     * in its own tables (a `teamMembers` row, say) registers its own tuple source
+     * rather than copying data across; see `policyGuardResolver.ts`.
+     *
+     * That paragraph is here because its absence cost a consumer their access
+     * gate. This comment used to describe the resolver as "a future ReBAC /
+     * `accessPolicy()` resolver" — written before the ReBAC path shipped and
+     * never updated. They read the type, quoted the sentence, concluded there was
+     * "nothing in between" declaring an untruth and turning the gate off, and set
+     * `security: { defaultDeny: false }` on an app with 565 undecided procedures.
+     * The capability they needed was two fields away. A doc comment that says
+     * "future" about something shipped is not a small inaccuracy: it is the only
+     * thing a careful reader has, and it argued them out of a feature.
      */
     readonly resource?: (input: Input) => string | undefined;
 }
 
+/** Does this descriptor declare an access decision — a guard, or a deliberate
+ *  `openAccess:`? The boot gate's predicate; `false` is the SEC-1 shape. */
+export declare const hasAccessDecision: (descriptor: {
+    readonly guards?: ReadonlyArray<unknown> | undefined;
+    readonly openAccess?: string | undefined;
+}) => boolean;
+
 export declare const hasCallbackRoutes: (s: AuthStrategy) => s is AuthStrategyWithCallback;
 
 /** True if the subject holds `scope` (or the `admin:full` bypass), checking
@@ -1562,8 +2100,22 @@ export declare interface HttpRequestContext {
     readonly path: string;
     /** Lowercased request headers. */
     readonly headers: Readonly<Record<string, string>>;
-    /** Best-effort remote address. `undefined` when running behind a
-     *  proxy without `x-forwarded-for`. */
+    /**
+     * The client address, resolved through the app's `security.trustedProxies`
+     * policy — the SAME value `PluginHttpRouteRequest.remoteAddr`, the rate
+     * limiter, the geo-block and every audit row use (`resolveClientAddress`).
+     * Use this, never `headers['x-forwarded-for']`.
+     *
+     * This is a pre-auth shield's whole key, so getting it from the header is
+     * not a smaller mistake here than elsewhere — it is the one place it is
+     * worst. `x-forwarded-for` is a request header: any client can write it, so
+     * a token bucket keyed on it is bypassed by one extra header per request.
+     * The resolution here ignores the header entirely unless a trusted proxy is
+     * declared, and then believes only the hops that are one.
+     *
+     * `undefined` when the socket address is unavailable (a unix socket, an
+     * in-process test harness that constructs the request by hand).
+     */
     readonly remoteAddr: string | undefined;
 }
 
@@ -1664,12 +2216,31 @@ export declare const isEventDescriptor: (value: unknown) => value is AnyEventDes
  *  diffed by id and falls back to shipping the full data. */
 export declare const isIdKeyed: (rows: ReadonlyArray<Readonly<Record<string, unknown>>>) => rows is ReadonlyArray<PatchRow>;
 
+/** Runtime narrowing for the declared-open variant. */
+export declare const isOpenAccess: (g: AnyCheckSpec) => g is OpenAccessSpec;
+
 /** Runtime narrowing for the relationship variant. */
 export declare const isPolicyCheck: (g: AnyCheckSpec) => g is PolicyCheckSpec;
 
 /** Narrow a guard entry to the relationship variant. */
 export declare const isPolicyGuard: <I>(g: AnyGuardSpec<I>) => g is PolicyGuardSpec<I>;
 
+/** Whether `value` is a channel object (not its key). */
+export declare const isReactivityChannel: (value: unknown) => value is ReactivityChannel;
+
+/**
+ * Whether `key` is addressed to the channel namespace.
+ *
+ * A PREFIX test, deliberately not a registry lookup — the two answer different
+ * questions and only one of them belongs on the delivery path. At runtime the
+ * question is "is this a table name or a channel key", and getting it wrong in
+ * the strict direction drops a real push. Whether the channel was DECLARED is a
+ * boot question, and `undeclaredChannelKeys` answers it there — the same
+ * asymmetry tables already have (an unregistered table name still delivers;
+ * the boot audit is what reports it).
+ */
+export declare const isReactivityChannelKey: (key: string) => boolean;
+
 export declare const isSystemSubject: (subject: Subject) => boolean;
 
 /**
@@ -1690,6 +2261,17 @@ export declare const isWireReachable: (descriptor: {
     readonly internal?: boolean | undefined;
 }) => boolean;
 
+/**
+ * Build a scope cache. Hand it to `composeAuthStrategies({ scopeCache })` and
+ * keep the handle: `invalidate(scopeCacheKey(subject))` from the mutation that
+ * grants or removes a role is what makes the staleness window zero.
+ *
+ * `composeAuthStrategies` builds one internally when you don't, so the default
+ * posture is cached-with-a-window rather than a store read per request — but a
+ * cache nobody holds cannot be invalidated, which is why this is exported.
+ */
+export declare const makeScopeCache: (options?: ScopeCacheOptions) => ScopeCache;
+
 /**
  * How large one encoded envelope may be, on EVERY dialect.
  *
@@ -1710,6 +2292,10 @@ export declare const MAX_EVENT_ENVELOPE_BYTES = 7500;
 /** In-memory store — the default for single-process dev + the test double. */
 export declare const memoryIdempotencyStore: () => IdempotencyStore;
 
+/** The refusal a missing access decision produces. Exported so the boot gate
+ *  and the call-time path cannot describe the same defect differently. */
+export declare const missingAccessDecision: (procedure?: string) => ScopeError;
+
 export declare interface MutationProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
     readonly kind: 'mutation';
     readonly name: Name;
@@ -1724,11 +2310,19 @@ export declare interface MutationProcedureDescriptor<Name extends string, Input
     /** Declarative authorization guard(s) — enforced before the transaction
      *  opens, failing with a typed `ScopeError`. Absent → no framework-level
      *  authz (author gates in-handler, or the mutation is unguarded). */
-    readonly guards: Guards | undefined;
+    readonly guards: DeclaredAccess | undefined;
+    /** The declared reason this procedure needs NO authorization check —
+     *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
+     *  the only two shapes `security.defaultDeny` accepts. */
+    readonly openAccess: string | undefined;
     /** Opt this mutation into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this mutation into the auto-synthesized agent toolset (innovation/07). */
     readonly exposeAsTool: ExposeAsTool | undefined;
+    /** Require a SECOND human to approve before this mutation takes effect. The
+     *  gate runs in the dispatch spine after `guards:` and before the transaction
+     *  opens; the pending intent is a durable `_voltro_approvals` row. */
+    readonly requiresApproval: AnyApprovalPolicy | undefined;
     /** True when the procedure is kept OFF the wire — no client-group entry and no
      *  route in dev or serve. See `internal` on the definer's options. */
     /**
@@ -1780,6 +2374,17 @@ export declare interface NestedTargetFields<Input = unknown> {
  */
 export declare const normalizeDescriptor: (descriptor: ProcedureDescriptor) => ClientDescriptor;
 
+/**
+ * A `source:` as the DESCRIPTOR stores it — channels resolved to their keys,
+ * with the caller's shape preserved.
+ *
+ * Shape-preserving on purpose: a single `source: 'notes'` must stay the string
+ * `'notes'` and not become `['notes']`. It is serialised into the capability
+ * manifest and into every api golden, so widening the shape would rewrite those
+ * artefacts for every query in every app to express nothing.
+ */
+export declare const normalizeSource: (source: ReactivitySource | ReadonlyArray<ReactivitySource> | undefined) => string | ReadonlyArray<string> | undefined;
+
 /**
  * What a plugin contributes to the OTel layer via `contributeObservability`.
  * The OTel types are intentionally `unknown` so this browser-safe protocol
@@ -1799,6 +2404,31 @@ export declare interface ObservabilityContribution {
     readonly sampler?: unknown;
 }
 
+/**
+ * The runtime-erased form of a procedure's `openAccess:` — a DECLARED decision
+ * that this procedure needs no authorization check, and the reason.
+ *
+ * It is a guard entry rather than a bare descriptor field on purpose. Every
+ * enforcement path in the framework — `servePipeline`'s `enforceGuards`,
+ * `bindStream`, `bindEvent`, `@voltro/testing`'s `invoke` — is handed the
+ * `guards` ARRAY and nothing else. A decision that does not live in that array
+ * is invisible to all of them, so "guarded" and "deliberately open" would be
+ * distinguishable in the source and identical at the point that enforces.
+ *
+ * It always passes. The value is the WHY, and the why is the point: it is what
+ * a reviewer reads, what `voltro doctor` prints, and what makes an open
+ * procedure a decision somebody made rather than a field somebody forgot.
+ */
+export declare interface OpenAccessSpec {
+    /** Why this procedure is callable without an authorization check. Non-empty
+     *  by construction — `defineQuery` & co. refuse an empty reason. */
+    readonly open: string;
+}
+
+/** Build the erased `openAccess:` entry. The definers call this; an app writes
+ *  `openAccess: '<why>'` on the descriptor and never sees the spec. */
+export declare const openAccessSpec: (reason: string) => OpenAccessSpec;
+
 /** Split a route back into its three parts. */
 export declare const parseEventRoute: (route: string) => {
     readonly tenantId: string | null;
@@ -1817,6 +2447,35 @@ export declare type PatchRow = Readonly<Record<string, unknown>> & {
  *  needs to re-parse a number out of a path. */
 export declare const pathToId: (path: string) => string;
 
+export declare const PendingApproval: Schema.Struct<{
+    id: typeof Schema.String;
+    /** The rpc tag whose execution is pending. */
+    procedure: typeof Schema.String;
+    kind: Schema.Literal<["mutation", "action"]>;
+    /** Subject id of whoever asked. Never the approver. */
+    requestedBy: Schema.NullOr<typeof Schema.String>;
+    status: Schema.Literal<["pending", "approved", "rejected", "expired", "consumed"]>;
+    /** The declared reason from the descriptor, if any. */
+    reason: Schema.NullOr<typeof Schema.String>;
+    /** Scope(s) an approver must hold. */
+    requiredScopes: Schema.Array$<typeof Schema.String>;
+    requestedAt: typeof Schema.String;
+    expiresAt: typeof Schema.String;
+    decidedBy: Schema.NullOr<typeof Schema.String>;
+    decidedAt: Schema.NullOr<typeof Schema.String>;
+    /** The approver's note, when they left one. */
+    note: Schema.NullOr<typeof Schema.String>;
+    /**
+     * How this row relates to the CALLING subject — the whole point of the feed.
+     * `'to-decide'` = they may act on it; `'requested'` = they asked for it.
+     * A row is never both: self-approval is refused, so a requester never
+     * qualifies as its approver.
+     */
+    relation: Schema.Literal<["to-decide", "requested"]>;
+}>;
+
+export declare type PendingApproval = Schema.Schema.Type<typeof PendingApproval>;
+
 /**
  * Called once at app boot, after `voltro dev` resolves the plugin
  * list and before the rpc server starts accepting connections. Use
@@ -1913,6 +2572,23 @@ export declare interface PluginChangeEvent {
     readonly new: Record<string, unknown> | null;
     /** Row before the change — present on update + delete, null on insert. */
     readonly old: Record<string, unknown> | null;
+    /**
+     * Set when the transport could not carry this change's images and they were
+     * RECONSTRUCTED — a row over postgres' 8000-byte `pg_notify` cap. Absent on
+     * every ordinary event.
+     *
+     * A tap must read it before trusting an image as a snapshot:
+     *
+     *   - `'rehydrated'` — `new` is the row RE-READ from the database. Correct to
+     *     index, mirror or forward; NOT necessarily the image the write that
+     *     fired this event produced (a later write may already have landed).
+     *   - `'tombstone'` — a delete whose `old` is the PRIMARY KEY and nothing
+     *     else. Enough to remove the row; never a record of what it contained.
+     *     A history/versioning tap must not store it as a snapshot.
+     *   - `'unrecovered'` — both images are null and the content is gone. The
+     *     change happened; re-read or resync if you need it.
+     */
+    readonly oversized?: 'rehydrated' | 'tombstone' | 'unrecovered';
     /** How the event reached this process: absent/'inline' = this process's
      *  own write; 'injected' = delivered over a cross-instance transport
      *  (broadcast bus / CDC consumer). Combine with `changeScope` to act
@@ -1945,6 +2621,14 @@ export declare interface PluginChangeEvent {
      * join table is a member removal, a cascade or an expiry.
      */
     readonly procedure?: string;
+    /**
+     * The write was made BY AN AGENT acting as `subjectId` — the fourth member of
+     * the shape the comment above tracks (`WriteAttribution` → `ChangeEvent` →
+     * here). A tap that logs "who changed this" reads WRONG without it: the
+     * subject is the person the agent acted as, by construction, so an agent
+     * write and a human write are otherwise identical rows.
+     */
+    readonly via?: 'agent';
     /** The store's change visibility (see `DataStore.changeScope`):
      *  'local' — own writes inline (skip origin 'injected' for
      *  exactly-once-on-the-writer); 'fleet' — every replica sees the full
@@ -2113,6 +2797,42 @@ export declare interface PluginHttpRoute {
      *  any sub-path (`/_voltro/storage/abc123`). */
     readonly path: string;
     readonly handle: (req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+    /**
+     * Opt this route's path OUT of the listener's cross-site origin check.
+     *
+     * Every state-changing request (anything but GET/HEAD/OPTIONS) is
+     * origin-checked by default, because the default assumption has to be that a
+     * route can be reached with the browser's ambient session cookie — and a
+     * route that can is CSRF-reachable. Declaring `'exempt'` is a claim that this
+     * route CANNOT be: its caller must present something a browser will not
+     * attach cross-site.
+     *
+     * The test to apply, and it is the only one:
+     *
+     *   > If an attacker's page makes a browser send this request with the
+     *   > victim's cookies attached, does anything happen?
+     *
+     * If the answer is "no, the request still needs a signature / a bearer token
+     * / a signed ticket the attacker does not have", the route is exempt.
+     * Otherwise it is not, and no amount of "but it is behind the dashboard"
+     * makes it so.
+     *
+     * The first-party exemptions and why each qualifies:
+     *   - `@voltro/plugin-sso-saml` `/saml` — the IdP delivers the assertion as a
+     *     genuine cross-site browser form POST; authority is the signed
+     *     SAMLResponse, not the cookie.
+     *   - `@voltro/plugin-storage` `/…/upload` + `/…/upload/resumable` — a signed
+     *     upload ticket in the query string, and the route ships its own CORS
+     *     allowlist because a cross-origin upload is the point.
+     *   - `@voltro/plugin-billing` `/billing/webhook` — an HMAC-verified provider
+     *     callback.
+     *   - `@voltro/plugin-scim` `/scim/v2` — bearer-only, refuses to mount without
+     *     a token.
+     *
+     * Granularity is the PATH PREFIX the route mounts, not the sub-path its
+     * handler branches on: exempting `/saml` exempts `POST /saml/anything`.
+     */
+    readonly originGuard?: 'exempt';
 }
 
 export declare interface PluginHttpRouteRequest {
@@ -2175,6 +2895,22 @@ export declare interface PluginHttpRouteRequest {
      * this store reads them.
      */
     readonly store?: DataStore;
+    /**
+     * The client address, resolved through the app's `security.trustedProxies`
+     * policy — the SAME value the rate limiter, the geo-block and every audit row
+     * use (`resolveClientAddress`). Use this, never `headers['x-forwarded-for']`.
+     *
+     * `x-forwarded-for` is a request header: any client can write it. Reading it
+     * raw means a caller picks the IP that lands in your `sessions.ipAddress`
+     * column, which is the one field a breach investigation leans on. Three
+     * first-party routes did exactly that until SEC-8 was extended down to this
+     * surface. The resolution here ignores the header entirely unless a trusted
+     * proxy is declared, and then believes only the hops that are one.
+     *
+     * `undefined` when the socket address is unavailable (a unix socket, an
+     * in-process test harness that constructs the request by hand).
+     */
+    readonly remoteAddr?: string | undefined;
 }
 
 /**
@@ -2291,6 +3027,55 @@ export declare type PluginInspectResponse = {
  */
 export declare type PluginInstallHook = (ctx: PluginLifecycleContext) => Effect.Effect<void, unknown> | Promise<void> | void;
 
+/**
+ * The two things a plugin's `name` is asked to encode — and they are NOT the
+ * same question, which is why they are two fields.
+ *
+ * A plugin's name decides its rpc-tag prefix (`pluginAlias`) and its inspect
+ * URL slug (`pluginSlug`). Two different app-side problems land on it:
+ *
+ * - **`alias` — "your namespace collides with mine."** An app that already
+ *   publishes `notifications.*` routes cannot install a plugin that also wants
+ *   `notifications.*`; the collision is fatal at codegen. `alias` REPLACES the
+ *   namespace, so the app keeps its own name and the plugin moves.
+ * - **`instance` — "I want two of these."** A second cdc-out pipeline, a
+ *   second mail transport. The base name stays (so it is still recognisably
+ *   that plugin) and gains a `#suffix` discriminator.
+ *
+ * Both were already in the tree, one of them eleven times. The `#suffix`
+ * ternary was copy-pasted verbatim into eleven plugins, and `alias` existed on
+ * exactly one (`ai-flows`) with its own hand-rolled shape — so the two
+ * mechanisms had no defined interaction at all. This is the one implementation.
+ *
+ * **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.
+ *
+ * @param base     the plugin's canonical package name, e.g. `'@voltro/plugin-cdc-out'`
+ * @param alias    replaces the whole namespace — an app-chosen name
+ * @param instance discriminates one installation from another (`#suffix`)
+ *
+ * ```ts
+ * pluginInstanceName({ base: '@voltro/plugin-cdc-out' })
+ * //=> '@voltro/plugin-cdc-out'        tag `cdcOut.*`      slug `cdc-out`
+ * pluginInstanceName({ base: '@voltro/plugin-cdc-out', instance: 'analytics' })
+ * //=> '@voltro/plugin-cdc-out#analytics'  tag `cdcOut.*`  slug `cdc-out--analytics`
+ * pluginInstanceName({ base: '@voltro/plugin-cdc-out', alias: 'mirror' })
+ * //=> 'mirror'                        tag `mirror.*`      slug `mirror`
+ * pluginInstanceName({ base: '@voltro/plugin-cdc-out', alias: 'mirror', instance: 'analytics' })
+ * //=> 'mirror#analytics'              tag `mirror.*`      slug `mirror--analytics'
+ * ```
+ */
+export declare const pluginInstanceName: (args: {
+    readonly base: string;
+    readonly alias?: string | undefined;
+    readonly instance?: string | undefined;
+}) => string;
+
 /**
  * Per-app context handed to lifecycle hooks. The shape is intentionally
  * thin — the framework's deeper services (DataStore, Logger, etc.) are
@@ -2444,14 +3229,41 @@ export declare interface PluginRpcRoute {
      * The executor returns the query's VALUE (an array / object) — the same
      * shape it returns for a poll; the framework recomputes it on change. Omit
      * for a plain (poll-only) plugin query, a mutation, or an action. For a
-     * query that mirrors a plugin table, set this to that table's name (e.g.
-     * `@voltro/plugin-presence` sets `_voltro_presence`, which is reactive).
+     * query that mirrors a plugin table, set this to that table's name.
+     *
+     * For plugin state that is NOT in a table, declare a
+     * `reactivityChannel(...)` and pass the CHANNEL here — do not declare a table
+     * you never write in order to own the name. `@voltro/plugin-presence` did
+     * exactly that for a release, and the empty `_voltro_presence` table it left
+     * in every user's database is what the channel primitive replaced.
      *
      * `| undefined` is explicit so a plugin can spread a browser-safe query
      * DESCRIPTOR (which always carries `source: … | undefined`) into a route
      * literal under `exactOptionalPropertyTypes` without a cast.
      */
-    readonly source?: string | ReadonlyArray<string> | undefined;
+    readonly source?: ReactivitySource | ReadonlyArray<ReactivitySource> | undefined;
+    /**
+     * The route's ACCESS DECISION — the same two-field vocabulary user
+     * procedures carry, because a plugin route is dispatched through the exact
+     * same spine. Spreading a browser-safe descriptor
+     * (`{ ...listDescriptor, execute }`) carries the decision automatically; the
+     * lift (`pluginRoutes.ts`) forwards it onto the descriptor the runtime
+     * enforces.
+     *
+     * `| undefined` on both, like `source`: a spread descriptor always carries
+     * the properties, and `exactOptionalPropertyTypes` would otherwise refuse
+     * the spread without a cast.
+     *
+     * A route that declares NEITHER is the SEC-1 shape — callable by any
+     * authenticated session, and REFUSED per-request by the dispatch spine when
+     * the app runs with `security.defaultDeny` (the default). First-party
+     * plugins declare a decision on every route; third-party plugins must too.
+     */
+    readonly guards?: DeclaredAccess | undefined;
+    /** Deliberate no-check marker with the REASON — see `openAccess:` on
+     *  `defineQuery`/`defineMutation`/`defineAction`. Mutually exclusive with a
+     *  non-empty `guards`. */
+    readonly openAccess?: string | undefined;
     /**
      * Effect-only executor. The base layer is provided by the framework
      * (DataStore, HttpClient, the plugin's own service Tags) — the
@@ -2617,6 +3429,21 @@ export declare interface PublicApiSpec {
     readonly stream?: 'snapshot' | 'sse';
 }
 
+/**
+ * Push every subscriber of `channel`.
+ *
+ * Returns whether the store could deliver it. A store that cannot inject (a
+ * limited fake, a transactional view) is a no-op rather than a throw: a missing
+ * seam must not be able to take down the write that called this, and the read
+ * that follows is still correct.
+ *
+ * This exists so no caller hand-builds the event. The one that did wrote
+ * `injectExternalChange({ … } as never)` — and `as never` on a wiring object is
+ * how the webhook trigger context came to differ between the two boot paths
+ * while both compiled.
+ */
+export declare const publishReactivity: (store: ReactivityPublisher | undefined, channel: ReactivityChannel) => boolean;
+
 /** Publish a server-primitive error. Cheap + sync; a broken reporter can
  *  never break the caller (each listener is isolated). Safe no-op when
  *  nothing is subscribed — primitives call it unconditionally. */
@@ -2682,7 +3509,11 @@ export declare interface QueryProcedureDescriptor<Name extends string, Input ext
     readonly cache: QueryCacheConfig | undefined;
     /** Declarative authorization guard(s) — enforced before the executor runs,
      *  failing with a typed `ScopeError`. Absent → no framework-level authz. */
-    readonly guards: Guards | undefined;
+    readonly guards: DeclaredAccess | undefined;
+    /** The declared reason this procedure needs NO authorization check —
+     *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
+     *  the only two shapes `security.defaultDeny` accepts. */
+    readonly openAccess: string | undefined;
     /** Opt this query into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this query into the auto-synthesized agent toolset (innovation/07). */
@@ -2760,6 +3591,56 @@ export declare const queryToRpc: <Name extends string, Input extends Schema.Sche
     revision: Schema.optional<typeof Schema.Number>;
 }>]>, Schema.Schema.All>, typeof Schema.Never, never>;
 
+/** The `channel:` namespace. Every channel key starts with it. */
+export declare const REACTIVITY_CHANNEL_PREFIX = "channel:";
+
+/**
+ * A declared reactivity channel — a push target with no table behind it.
+ *
+ * Create one with `reactivityChannel(name)`; pass it as a query's `source:`.
+ */
+export declare interface ReactivityChannel {
+    readonly kind: 'reactivity-channel';
+    /** The name as declared, without the namespace. */
+    readonly name: string;
+    /** The routing key — what the dispatcher indexes and `source:` resolves to. */
+    readonly key: string;
+    /** The key, so a channel interpolates into a message as its routing key. */
+    toString(): string;
+}
+
+/**
+ * Declare a reactivity channel.
+ *
+ * Idempotent by name: calling it twice returns the SAME object. A module
+ * evaluated twice (hot reload, a dual-instance resolve) must not produce two
+ * channels that compare unequal while routing to one key.
+ *
+ *     export const presenceRoster = reactivityChannel('presence')
+ *     // …
+ *     defineQuery({ name: 'presence.list', source: presenceRoster, … })
+ *     // …
+ *     publishReactivity(store, presenceRoster)
+ */
+export declare const reactivityChannel: (name: string) => ReactivityChannel;
+
+/**
+ * The one method of a store this needs — structural, so publishing does not
+ * pull `@voltro/database`'s `DataStore` into a caller that had no reason for it.
+ */
+export declare interface ReactivityPublisher {
+    readonly injectExternalChange?: (event: {
+        readonly table: string;
+        readonly op: 'insert' | 'update' | 'delete';
+        readonly new: Record<string, unknown>;
+        readonly old: Record<string, unknown>;
+        readonly origin?: 'inline' | 'injected';
+    }) => void;
+}
+
+/** What a query may declare as its reactive source. */
+export declare type ReactivitySource = string | ReactivityChannel;
+
 /** 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>;
@@ -2988,6 +3869,72 @@ export declare interface ScheduleFireContext {
  */
 export declare type ScheduleFireInterceptor = (next: () => Promise<void>, ctx: ScheduleFireContext) => Promise<void>;
 
+export declare interface ScopeCache {
+    /** The effective window in milliseconds. */
+    readonly ttlMs: number;
+    /** Resolve through the cache. `compute` runs only on a miss. */
+    readonly resolve: (key: string, compute: () => Promise<ScopeDecision>) => Promise<CachedScopeDecision>;
+    /** Drop one subject's cached authority — call this from whatever changes a
+     *  role, and the change is live on this process immediately. */
+    readonly invalidate: (key: string) => void;
+    /** Drop every cached verdict — for a change that alters a ROLE's definition
+     *  rather than one user's membership, where the affected subjects aren't
+     *  enumerable. */
+    readonly invalidateAll: () => void;
+}
+
+/**
+ * The cache key for a subject's authority: type, tenant, id.
+ *
+ * `tenantId` is in the key and it is load-bearing. A user who switches tenants
+ * keeps their `id`, and their authority is per-tenant — key on the id alone and
+ * a switch serves the previous tenant's scopes for a whole window. Use this
+ * when calling `invalidate` so the key you drop is the key that was written.
+ */
+export declare const scopeCacheKey: (subject: Subject | SubjectIdentity) => string;
+
+export declare interface ScopeCacheOptions {
+    /** Cache window in milliseconds. Default 30 000. `0` disables caching (every
+     *  request resolves). Overridden by `VOLTRO_AUTH_SCOPE_CACHE_TTL_MS` only
+     *  when this is left unset — an explicit number in code wins over the env. */
+    readonly ttlMs?: number;
+    /** Upper bound on cached subjects. Default 10 000. */
+    readonly maxEntries?: number;
+    /** Clock override (epoch ms). Testing seam. */
+    readonly now?: () => number;
+}
+
+/** Compose multiple strategies into a single resolver function. The
+ *  composer evaluates them in declaration order; first `matched`
+ *  wins; first `failed` short-circuits to anonymous (does NOT fall
+ *  through — see StrategyResolution doc).
+ *
+ *  NOTHING may answer ahead of this chain. The per-connection soft-reauth
+ *  override used to (`getConnectionSubject`, `@voltro/runtime`), and that is
+ *  precisely what made a rebound connection immune to session revocation, to
+ *  `resolveScopes` and to the scope cache. It patches the connection's HEADERS
+ *  now and this chain runs unchanged — see `ConnectionCredential` above.
+ *
+ *  Returns an async resolver `(input) => Promise<Subject>`.
+ */
+/** A resolver's verdict on a subject's authority. */
+export declare type ScopeDecision = 
+/** Union these onto what the strategy established. */
+    {
+    readonly kind: 'grant';
+    readonly scopes: ReadonlyArray<string>;
+}
+/** These are the caller's COMPLETE authority — anything else is removed. */
+| {
+    readonly kind: 'authoritative';
+    readonly scopes: ReadonlyArray<string>;
+}
+/** The authority source could not be reached. Fails the request closed. */
+| {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+
 export declare class ScopeError extends ScopeError_base {
 }
 
@@ -2998,6 +3945,11 @@ declare const ScopeError_base: Schema.TaggedErrorClass<ScopeError, "ScopeError",
     message: typeof Schema.String;
 }>;
 
+/** What `resolveScopes` may return. A bare array is the shorthand for
+ *  `{ kind: 'grant', scopes }` — the common case, and the reading an existing
+ *  resolver already has. */
+export declare type ScopeResolverResult = ReadonlyArray<string> | ScopeDecision;
+
 export declare interface ServerErrorEvent {
     /** The thrown value (Error | tagged error | anything). */
     readonly error: unknown;
@@ -3036,6 +3988,16 @@ export declare const setPolicyGuardResolver: (resolver: PolicyGuardResolver | un
  */
 export declare const setResourceScopeResolver: (resolver: ResourceScopeResolver | undefined) => void;
 
+/**
+ * Every routing key a `source:` names, flattened.
+ *
+ * The one normaliser. `source` has been read with an inline
+ * `typeof s === 'string' ? [s] : s` at nine sites, which was already a decision
+ * written nine times; adding a second accepted shape to each of them is how the
+ * ninth ends up handling channels differently from the first.
+ */
+export declare const sourceKeys: (source: ReactivitySource | ReadonlyArray<ReactivitySource> | undefined) => ReadonlyArray<string>;
+
 export declare type StrategyResolution = {
     readonly kind: 'matched';
     readonly subject: Subject;
@@ -3084,7 +4046,11 @@ export declare interface StreamProcedureDescriptor<Name extends string, Input ex
     /** WHO MAY LISTEN. Checked at subscribe AND re-checked before every element,
      *  the same as a query's — a stream is a long-lived grant and the scopes that
      *  justified it can be withdrawn while it is still open. */
-    readonly guards: Guards | undefined;
+    readonly guards: DeclaredAccess | undefined;
+    /** The declared reason this procedure needs NO authorization check —
+     *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
+     *  the only two shapes `security.defaultDeny` accepts. */
+    readonly openAccess: string | undefined;
 }
 
 export declare const streamToRpc: <Name extends string, Input extends Schema.Schema.Any, Element extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: StreamProcedureDescriptor<Name, Input, Element, Err>, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Element, Schema.Schema.All>, typeof Schema.Never, never>;
@@ -3121,6 +4087,44 @@ export declare const Subject: Schema.Union<[Schema.Struct<{
 
 export declare type Subject = typeof Subject.Type;
 
+export declare const SubjectIdentity: Schema.Union<[Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["user"]>;
+    tenantId: typeof Schema.String;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["apiKey"]>;
+    tenantId: typeof Schema.String;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["serviceAccount"]>;
+    tenantId: typeof Schema.String;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["anonymous"]>;
+    id: typeof Schema.Null;
+    tenantId: Schema.NullOr<typeof Schema.String>;
+}>, Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["system"]>;
+    tenantId: typeof Schema.Null;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>]>;
+
+export declare type SubjectIdentity = typeof SubjectIdentity.Type;
+
+/**
+ * Drop a Subject's authority, keeping everything that identifies it.
+ *
+ * Total and lossy on purpose — there is no variant it can fail on and no
+ * option to keep the scopes. A caller that wants to mint a credential from a
+ * Subject goes through here, so "did this cookie carry authority?" has one
+ * answer at every mint site instead of one per site.
+ */
+export declare const subjectIdentity: (subject: Subject) => SubjectIdentity;
+
 /** A strategy's verdict on a request.
  *  - `matched`: this strategy claims the request; here's the Subject.
  *  - `skip`: not my request (e.g. cookie absent); try next strategy.
@@ -3342,6 +4346,23 @@ declare const Unauthenticated_base: Schema.TaggedErrorClass<Unauthenticated, "Un
     reason: Schema.optional<typeof Schema.String>;
 }>;
 
+/**
+ * Channel keys named by a `source:` that no `reactivityChannel()` declared.
+ *
+ * The channel half of the stale-`source:` audit. It should be structurally
+ * unreachable when the channel is authored as an object — you cannot import a
+ * declaration that does not exist — so it exists for the two ways round that:
+ * a hand-written `source: 'channel:presence'` string, and a channel whose
+ * declaring module the boot did not load.
+ */
+export declare const undeclaredChannelKeys: (procedures: ReadonlyArray<{
+    readonly name: string;
+    readonly source: string | ReadonlyArray<string> | undefined;
+}>) => ReadonlyArray<{
+    readonly procedure: string;
+    readonly key: string;
+}>;
+
 export declare const UNDO_APPLY_TAG: "__voltro.undo.apply";
 
 export declare const UNDO_LOG_TAG: "__voltro.undo.log";
@@ -3461,6 +4482,31 @@ export declare interface VoltroPlugin {
      * (`@voltro/audit#analytics`).
      */
     readonly name: string;
+    /**
+     * The plugin's CANONICAL name, before the app renamed it — set this whenever
+     * `name` can come from an app-supplied `alias`.
+     *
+     * It exists because without it an alias silently half-works, and that was the
+     * shipped state. `effectiveRouteTag` prefixes a route with the plugin's
+     * alias UNLESS the route name already contains a dot — an escape hatch for a
+     * plugin wanting a deeper namespace. But every first-party plugin declares
+     * its routes fully qualified (`name: 'notifications.inbox'`, 96 such
+     * 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.
+     *
+     * With `baseName` set, both tag derivations strip a leading
+     * `<default-alias>.` before applying the EFFECTIVE alias, so
+     * `notifications.inbox` under `alias: 'inbox'` becomes `inbox.inbox` rather
+     * than staying put. A dotted name that does NOT start with the default alias
+     * is left alone — that is the genuine escape hatch, and it survives.
+     *
+     * Derived, not declared per route, so the 96 declarations stay as they are
+     * and cannot drift out of step with the strip.
+     */
+    readonly baseName?: string;
     /**
      * Plugin version — the package's own semver. Distinct from
      * `framework` (the FRAMEWORK range the plugin works with). Used by