@voltro/runtime 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,8 +1,11 @@
+import { AnyCheckSpec } from '@voltro/protocol';
 import { AuthStrategy } from '@voltro/protocol';
 import { CaughtUpVerdict } from '@voltro/database';
 import { ChangeEvent } from '@voltro/database';
 import { clearRetentions } from '@voltro/database';
 import { ConnectionInfo } from '@voltro/protocol';
+import { ConnectionKind } from '@voltro/protocol';
+import { ConnectionState } from '@voltro/protocol';
 import { Context } from 'effect';
 import { createServer } from 'node:http';
 import { Cron } from 'effect';
@@ -12,7 +15,6 @@ import { DialectReplicationAdapter } from '@voltro/database';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
 import { FieldCipher } from '@voltro/database';
-import { GuardCheckSpec } from '@voltro/protocol';
 import * as http from 'node:http';
 import { HttpClient } from '@effect/platform';
 import { HttpRequestInterceptor } from '@voltro/protocol';
@@ -40,7 +42,7 @@ import { registerRetention } from '@voltro/database';
 import { RestRouteDescriptor } from '@voltro/protocol/rest';
 import { RetentionSpec } from '@voltro/database';
 import { retentionTtlMsFromEnv } from '@voltro/database';
-import { Row as Row_4 } from '@voltro/database';
+import { Row } from '@voltro/database';
 import { Rpc } from '@effect/rpc';
 import { RpcGroup } from '@effect/rpc';
 import { RpcInterceptor } from '@voltro/protocol';
@@ -285,14 +287,14 @@ export declare class AggregateMaintainer {
     private readonly groups;
     constructor(shape: AggregateShape);
     /** Seed from the full base row-set (boot / after a rescan-from-scratch). */
-    seed(baseRows: ReadonlyArray<Row_3>): void;
+    seed(baseRows: ReadonlyArray<Row_4>): void;
     /**
      * Apply one delta. Returns the groups (if any) whose min/max extreme was
      * deleted and so MUST be rebuilt via `resolveRescan` before the next read.
      */
     applyChange(delta: CdcDelta): ReadonlyArray<string>;
     /** Rebuild the flagged groups from the current base rows (min/max recovery). */
-    resolveRescan(rescanGroups: ReadonlyArray<string>, baseRows: ReadonlyArray<Row_3>): void;
+    resolveRescan(rescanGroups: ReadonlyArray<string>, baseRows: ReadonlyArray<Row_4>): void;
     /** The current materialized result — one entry per non-empty group. */
     materialize(): ReadonlyArray<MaintainedGroup>;
     private groupValues;
@@ -654,6 +656,8 @@ export declare interface AnalyticsTopEntry {
     readonly value: number;
 }
 
+declare type AnyRow = Record<string, unknown>;
+
 export declare const API_KEYS_TABLE = "_voltro_api_keys";
 
 /** Admin-gated management routes (issue / list / revoke) for the built-in keys.
@@ -678,18 +682,15 @@ export declare interface ApiKeyServiceShape {
     /** Mint a new key. Returns the raw token ONCE. */
     readonly issue: (input: IssueInput) => Promise<IssuedApiKey>;
     /** Hash-lookup used by the auth strategy: returns the key's identity if
-     *  usable (not revoked / expired), and stamps `lastUsedAt`. */
-    readonly resolveByHash: (hash: string, now?: number) => Promise<{
-        id: string;
-        tenantId: string;
-        scopes: ReadonlyArray<string>;
-    } | null>;
+     *  usable (not revoked / expired), and stamps `lastUsedAt`.
+     *
+     *  `createdBy` travels with it because a key always has an accountable
+     *  human, and downstream needs to know WHICH one: a personal CLI key and a
+     *  shared CI credential are the same shape on the wire, and telling them
+     *  apart is what makes per-person accounting possible at all. */
+    readonly resolveByHash: (hash: string, now?: number) => Promise<ResolvedApiKey | null>;
     /** Verify a raw token (hashes then resolves). */
-    readonly verify: (token: string, now?: number) => Promise<{
-        id: string;
-        tenantId: string;
-        scopes: ReadonlyArray<string>;
-    } | null>;
+    readonly verify: (token: string, now?: number) => Promise<ResolvedApiKey | null>;
     /** Revoke a key (irreversible). */
     readonly revoke: (id: string, now?: number) => Promise<boolean>;
     /** Rotate: revoke the old key + issue a replacement with the same name/scopes/tenant. */
@@ -758,6 +759,36 @@ export declare interface AppContext {
      *  triggers. `emit(name, payload)` records the event and fans out to
      *  matching workflow triggers. */
     readonly events?: EventsAppContext;
+    /**
+     * Transactional outbox (`ctx.outbox`). Absent when the app declares no
+     * `*.outbox.ts` handler — an enqueue with nobody to deliver it would be a
+     * side effect the app believes happened and which never will, so the field
+     * simply isn't there rather than silently accepting writes.
+     */
+    readonly outbox?: OutboxFacade;
+    /**
+     * Connection vault (`ctx.connections`) — per-subject third-party
+     * credentials. Present when the app declares at least one `*.connection.ts`.
+     * `ctx.connections.get('jira')` returns the CALLING subject's credential,
+     * refreshed if it was near expiry; there is no parameter for "some other
+     * subject", by construction.
+     */
+    readonly connections?: ConnectionsFacade;
+    /**
+     * Request-scoped batching (`ctx.load` / `ctx.loadMany`). Coalesces
+     * same-tick reads of one table into a single `WHERE id IN (...)`.
+     *
+     * For assembly whose SHAPE depends on the data — a tree walk where each
+     * level's ids come from the level above — which `relations()` + `.with()`
+     * cannot express statically. Reach for the relation first; this is the
+     * fallback, not the default.
+     *
+     * Scoped to the request on purpose: a longer-lived cache would serve one
+     * subject's rows to another (a data-isolation bug on a tenant-scoped store,
+     * not a performance detail) and would go stale across a mutation.
+     */
+    readonly load: DataLoader['load'];
+    readonly loadMany: DataLoader['loadMany'];
 }
 
 /**
@@ -789,6 +820,17 @@ export declare const applyInverse: (store: UndoApplyStore, op: InverseOp) => Pro
  *  `synthesizeInverse`), as the caller's transaction wraps them. */
 export declare const applyInverses: (store: UndoApplyStore, ops: ReadonlyArray<InverseOp>) => Promise<void>;
 
+/** AND-merge the row filter for `table` onto an existing predicate. */
+export declare const applyRowFilter: (scope: RowFilterScope, table: string, predicate: Predicate | undefined) => Predicate | undefined;
+
+/** Apply a resolved scope to a whole descriptor. Used by the dispatcher, which
+ *  re-derives a subscription's read descriptor from its unfiltered base before
+ *  every delivery. */
+export declare const applyRowFilterToDescriptor: <D extends {
+    readonly table: string;
+    readonly predicate?: Predicate | undefined;
+}>(scope: RowFilterScope, descriptor: D) => D;
+
 export declare const applySoftDeleteScope: (descriptor: QueryDescriptor, softDeleteScopedTables: ReadonlySet<string>) => QueryDescriptor;
 
 export declare const applyTenantScope: (descriptor: QueryDescriptor, tenantScopedTables: ReadonlySet<string>, tenantId: string | null | undefined) => QueryDescriptor;
@@ -821,6 +863,19 @@ export declare interface AppSupervisor {
  *  deny so it surfaces to the client typed. */
 export declare const assertCan: (subject: RebacSubject, action: string, resource: RebacResource, deps: CanDeps) => void;
 
+/**
+ * Refuse to boot an app that declares connections without a field cipher.
+ *
+ * Without this the first `encryptField` call throws at REQUEST time — which
+ * means a deployment looks healthy, accepts a user through a whole OAuth
+ * consent screen, and fails only at the moment it would have persisted the
+ * token. Moving the check to boot makes a missing key an operator-visible
+ * startup failure instead of a per-user mystery. It is deliberately NOT a
+ * warning: a warning here degrades to plaintext storage the moment someone
+ * "fixes" the throw.
+ */
+export declare const assertConnectionCipherConfigured: (definitions: ReadonlyArray<ConnectionDefinition>) => void;
+
 /**
  * Async cache surface exposed as `ctx.cache` to non-Effect handlers — the
  * facade over the Effect-native `Cache` service from `@voltro/cache`
@@ -911,6 +966,30 @@ export declare interface AttachAnalyticsMirrorOptions {
  */
 export declare const awaitServerListening: (server: ReturnType<typeof createServer>, timeoutMs?: number) => Promise<void>;
 
+/** Exponential backoff with a ceiling — 1s, 2s, 4s … capped at 5 minutes. */
+export declare const backoffMs: (attempt: number) => number;
+
+/** Mint a single-use handshake grant and build the provider's consent URL. */
+export declare const beginOAuthConnect: (deps: BeginOAuthDeps) => Promise<BeginOAuthResult>;
+
+export declare interface BeginOAuthDeps {
+    readonly store: VaultStore;
+    readonly definition: OAuth2ConnectionDefinition;
+    readonly subjectId: string;
+    readonly tenantId: string | null;
+    readonly redirectTo?: string;
+    /** Absolute base URL the provider will redirect back to, e.g.
+     *  `https://app.example.com`. Used only when the declaration omits an
+     *  explicit `redirectUri`. */
+    readonly publicUrl: string;
+    readonly now?: () => Date;
+}
+
+export declare interface BeginOAuthResult {
+    readonly authorizeUrl: string;
+    readonly state: string;
+}
+
 /**
  * Override the subject for an active connection. Called from the
  * `auth.signin` (or any "I just authenticated this caller") handler
@@ -949,7 +1028,7 @@ export declare const bindStream: <Element, Err = unknown>(buildStream: (context:
  * the single explicit type-erasure boundary between the framework's
  * dynamic data layer and the rpc layer's static schemas.
  */
-export declare const bindSubscription: <T = ReadonlyArray<Row_4>>(buildDescriptor: (context: RuntimeContext) => QueryDescriptor | ComputedQuery | Effect.Effect<QueryDescriptor | ComputedQuery, unknown, never>, dispatcher: Dispatcher, spanName?: string, 
+export declare const bindSubscription: <T = ReadonlyArray<Row>>(buildDescriptor: (context: RuntimeContext) => QueryDescriptor | ComputedQuery | Effect.Effect<QueryDescriptor | ComputedQuery, unknown, never>, dispatcher: Dispatcher, spanName?: string, 
 /**
  * Optional resolver: given the materialised descriptor (after any
  * `.using()` hint), return the `MatcherIndexHint` the matcher should
@@ -973,16 +1052,32 @@ cache?: {
     readonly swrMs: number | undefined;
     readonly scope: "subject" | "global";
     readonly baseKey: string;
-}) => Stream.Stream<SubscriptionEvent<T>, never, SubjectService | ConnectionInfo>;
+}, 
+/**
+ * Per-subject authorization re-check, built by
+ * `makeQueryReauthorizer(query, input)` in the serve pipeline. Subscribing
+ * passes `guards:` once; this re-runs them before every delivery so a
+ * revoked grant CLOSES the stream rather than continuing to serve it.
+ * Omitted for a query that declares no guards.
+ */
+reauthorize?: (subject: Subject) => () => Promise<unknown>, 
+/**
+ * Per-delivery row-visibility resolver. Rarely passed: when omitted, one is
+ * DERIVED from the registered row filter (see `defaultRefilter`), so an
+ * entrypoint cannot end up with unfiltered subscriptions by forgetting to
+ * thread it — which is precisely how a row filter ends up applying to
+ * queries and mutations but not to the live stream.
+ */
+refilter?: (subject: Subject) => () => Promise<RowFilterScope>) => Stream.Stream<SubscriptionEvent<T>, never, SubjectService | ConnectionInfo>;
 
-export declare const bindSubscriptionUntyped: (descriptor: QueryDescriptor, dispatcher: Dispatcher, context: RuntimeContext, indexHint: MatcherIndexHint | undefined, label: string, cacheBinding: SnapshotCacheBinding | undefined) => Stream.Stream<SubscriptionEvent<ReadonlyArray<Row_4>>, never, never>;
+export declare const bindSubscriptionUntyped: (descriptor: QueryDescriptor, dispatcher: Dispatcher, context: RuntimeContext, indexHint: MatcherIndexHint | undefined, label: string, cacheBinding: SnapshotCacheBinding | undefined, reauthorize: (() => Promise<unknown>) | undefined, refilter?: (() => Promise<RowFilterScope>) | undefined) => Stream.Stream<SubscriptionEvent<ReadonlyArray<Row>>, never, never>;
 
 export declare interface BrandedScheduleDefinition extends ScheduleDefinition {
     readonly [SCHEDULE_BRAND]: true;
 }
 
 /** Build the full state from a base row-set (seed + per-group rescan). */
-export declare const buildIvmState: (shape: AggregateShape, rows: ReadonlyArray<Row_2>) => IvmState;
+export declare const buildIvmState: (shape: AggregateShape, rows: ReadonlyArray<Row_3>) => IvmState;
 
 /** Build the preview diff from a mutation's captured change-set. Pure. */
 export declare const buildPreview: (changes: ReadonlyArray<CdcChange>) => PreviewDiff;
@@ -1093,8 +1188,8 @@ export declare interface CdcChange {
 /** A CDC change as the matcher delivers it. */
 export declare interface CdcDelta {
     readonly op: 'insert' | 'update' | 'delete';
-    readonly old?: Row_2 | null;
-    readonly new?: Row_2 | null;
+    readonly old?: Row_3 | null;
+    readonly new?: Row_3 | null;
 }
 
 export { ChangeEvent }
@@ -1166,6 +1261,10 @@ export declare type CircuitState = 'closed' | 'open' | 'half-open';
  */
 export declare const classifyShape: (c: CandidateShape) => ShapeClassification;
 
+/** Test seam — the in-flight map is module state; a test that asserts
+ *  single-flight must be able to start from empty. */
+export declare const clearConnectionRefreshFlights: () => void;
+
 /** Test/boot reset. */
 export declare const clearResourcePolicies: () => void;
 
@@ -1179,6 +1278,30 @@ export declare const clearSystemStoreHandle: () => void;
  *  branded definition can trust this won't throw. */
 export declare const compileCron: (def: ScheduleDefinition) => Cron.Cron;
 
+/**
+ * Consume a handshake grant and store the resulting credential.
+ *
+ * The grant row is deleted BEFORE the exchange, not after: a `state` is
+ * single-use, and deleting it up front means a replayed callback (the user
+ * double-clicks, a crawler follows the URL) cannot start a second exchange
+ * even if the first is still in flight.
+ */
+export declare const completeOAuthConnect: (deps: CompleteOAuthDeps) => Promise<CompleteOAuthResult>;
+
+export declare interface CompleteOAuthDeps {
+    readonly store: VaultStore;
+    readonly registry: ConnectionRegistry;
+    readonly state: string;
+    readonly code: string;
+    readonly publicUrl: string;
+    readonly now?: () => Date;
+}
+
+export declare interface CompleteOAuthResult {
+    readonly connectionId: string;
+    readonly redirectTo: string;
+}
+
 /**
  * Combine multiple analytics specs into one composite spec at
  * app.config.ts time. The framework's boot path materialises each
@@ -1236,6 +1359,105 @@ declare interface ComputedQuery {
     readonly recompute: () => Promise<unknown>;
 }
 
+export declare const CONNECTION_GRANTS_TABLE = "_voltro_connection_grants";
+
+/** What a declaration can learn about the account it just connected. Optional
+ *  — a connection with no `identify` still works, it just has no display name. */
+export declare interface ConnectionAccount {
+    readonly accountId?: string;
+    readonly accountLabel?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+
+export declare interface ConnectionBuiltinDeps {
+    readonly registry: ConnectionRegistry;
+    /** Absolute origin the OAuth provider redirects back to. */
+    readonly publicUrl: string;
+}
+
+/** Default callback path for a connection. The `<id>` segment is why
+ *  `defineConnection` constrains the id shape. */
+export declare const connectionCallbackPath: (connectionId: string) => string;
+
+export declare type ConnectionDefinition = OAuth2ConnectionDefinition | PatConnectionDefinition;
+
+declare interface ConnectionDefinitionCommon {
+    /** Stable id — the value handlers pass to `ctx.connections.get(...)` and the
+     *  path segment of the callback route. */
+    readonly id: string;
+    /** Human label for the connect UI. Defaults to `id`. */
+    readonly label?: string;
+}
+
+/** The slice of AppContext the connection executors need. */
+export declare interface ConnectionExecutorCtx {
+    readonly store: DataStore;
+    readonly request?: {
+        readonly subject?: {
+            readonly id?: string | null;
+            readonly tenantId?: string | null;
+        } | null;
+    };
+}
+
+/** The subset of `fetch` the vault uses. Structurally satisfied by the global
+ *  `fetch` and by `@voltro/integration-http`'s `FetchLike`; declared locally so
+ *  the runtime takes no dependency on the http package for a two-field type. */
+export declare type ConnectionFetch = (url: string, init: {
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+}) => Promise<{
+    readonly status: number;
+    readonly text: () => Promise<string>;
+}>;
+
+/** `label` with the id as fallback. */
+export declare const connectionLabel: (definition: ConnectionDefinition) => string;
+
+/** The subject has no credential on file for this connection (or it was
+ *  revoked and cleared). The caller's move is to prompt a connect. */
+export declare class ConnectionNotConnected extends Error {
+    readonly connectionId: string;
+    readonly subjectId: string;
+    readonly _tag = "ConnectionNotConnected";
+    constructor(connectionId: string, subjectId: string);
+}
+
+export declare interface ConnectionRegistry {
+    readonly get: (connectionId: string) => ConnectionDefinition | undefined;
+    readonly list: () => ReadonlyArray<ConnectionDefinition>;
+}
+
+/** Resolve `connectionId` for `subject`, refreshed. */
+export declare type ConnectionResolver = (subject: Pick<Subject, 'id'>, connectionId: string) => Promise<ResolvedConnection>;
+
+export declare const CONNECTIONS_TABLE = "_voltro_connections";
+
+export declare interface ConnectionsFacade {
+    /**
+     * The calling subject's credential for `connectionId`, refreshed if it was
+     * near expiry. Throws `ConnectionNotConnected` when there is nothing on file
+     * (prompt a connect) or `ConnectionHandshakeFailed` when a refresh was owed
+     * and failed.
+     */
+    get(connectionId: string): Promise<ResolvedConnection>;
+    /** Same, but `null` instead of throwing when not connected — for the common
+     *  "use it if we have it" branch. A failing REFRESH still throws: silently
+     *  degrading a connected-but-broken account to "not connected" would hide a
+     *  revoked grant behind a feature quietly doing nothing. */
+    tryGet(connectionId: string): Promise<ResolvedConnection | null>;
+    /** Every declared connection with the caller's status — the same projection
+     *  `__voltro.connections.list` serves, for server-side rendering. */
+    list(): Promise<ReadonlyArray<ConnectionState>>;
+}
+
+export declare interface ConnectionsFacadeDeps {
+    readonly store: DataStore;
+    readonly registry: ConnectionRegistry;
+    readonly subject: Subject;
+}
+
 /** Test-only — number of streams currently registered for a client. */
 export declare const _connectionStreamCount: (clientId: number) => number;
 
@@ -1246,6 +1468,14 @@ export declare const connectionSubjectsSnapshot: () => ReadonlyArray<{
     tenantId: string | null;
 }>;
 
+/** A resolved token set. `expiresAt` is an absolute epoch-ms deadline. */
+export declare interface ConnectionTokens {
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    readonly expiresAt?: number;
+    readonly scopes: ReadonlyArray<string>;
+}
+
 export declare interface CoordinatedScheduleDeps {
     /** The exactly-once gate. `singleCoordinator` for one-process
      *  deployments; `makeAdvisoryLockCoordinator(store, replicaId)` for
@@ -1295,6 +1525,21 @@ export declare const currentRoutingContext: () => RoutingContext | undefined;
 /** The trace context active on the current async stack, if any. */
 export declare const currentTraceContext: () => LogTraceContext | undefined;
 
+export declare interface DataLoader {
+    /**
+     * Load one row by primary key. Calls made in the same tick for the same
+     * table are coalesced into ONE `WHERE id IN (...)`.
+     *
+     * Returns `null` for a missing row rather than throwing — a loader is used
+     * to assemble, and a missing edge in a graph walk is usually data, not an
+     * error. Use `.one()` when absence IS an error.
+     */
+    load(table: string, id: string): Promise<Row | null>;
+    /** Load many by key, in the order asked. Missing rows come back as `null`,
+     *  so the result lines up positionally with the input. */
+    loadMany(table: string, ids: ReadonlyArray<string>): Promise<ReadonlyArray<Row | null>>;
+}
+
 export { DataStore }
 
 /** DataStore-backed store over `_voltro_api_keys`. */
@@ -1316,6 +1561,8 @@ export declare const decryptField: (value: string) => string;
  *  small enough to stop a pathological body being buffered into memory. */
 export declare const DEFAULT_MAX_RPC_BODY_BYTES: number;
 
+export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
+
 /**
  * Construct an aggregate definition. The returned object brands itself
  * so the cli's file-discovery pass picks it up from default exports.
@@ -1344,8 +1591,28 @@ export declare const DEFAULT_MAX_RPC_BODY_BYTES: number;
  */
 export declare const defineAggregate: <Row>(input: AggregateDefinitionInput<Row>) => AggregateDefinition<Row>;
 
+/**
+ * Declare a connection. One per `*.connection.ts` file, default-exported.
+ *
+ * This is a pure declaration — no IO, no registration side effect. The CLI's
+ * boot discovery imports the file, reads the default export, and registers it;
+ * that keeps the declaration testable in isolation and keeps a stray import of
+ * a connection file from mutating global state.
+ */
+export declare const defineConnection: <D extends ConnectionDefinition>(definition: D) => D;
+
 export declare const defineEventTrigger: <EventPayload = unknown, WorkflowPayload = EventPayload>(spec: Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag">) => WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>;
 
+/**
+ * Declare who delivers an effect. One per `*.outbox.ts` file.
+ *
+ * The handler runs AFTER the enqueuing transaction committed, outside it, and
+ * may do external I/O — that is the entire point. It must be IDEMPOTENT:
+ * delivery is at-least-once, so a process that dies between "the remote
+ * accepted it" and "we marked it delivered" will retry.
+ */
+export declare const defineOutboxHandler: (definition: OutboxHandlerDefinition) => OutboxHandlerDefinition;
+
 /** Declare a reaction. Validates that the MANDATORY guard is present — an
  *  ungated reaction is a spend-storm footgun, so this fails LOUD at boot. */
 export declare const defineReaction: (def: ReactionDefinition) => ReactionDefinition;
@@ -1435,7 +1702,7 @@ export declare class Dispatcher {
      * Returns an `unsubscribe` function the caller MUST invoke when the
      * subscriber goes away (client disconnect, stream finalization, etc.).
      */
-    subscribe(descriptor: QueryDescriptor, emit: (event: SubscriptionEvent<ReadonlyArray<Row_4>>) => void, context: RuntimeContext, 
+    subscribe(descriptor: QueryDescriptor, emit: (event: SubscriptionEvent<ReadonlyArray<Row>>) => void, context: RuntimeContext, 
     /**
      * Optional matcher-side index hint. When set, the registry hashes
      * it into the fingerprint AND the matcher uses it for tuple
@@ -1451,7 +1718,28 @@ export declare class Dispatcher {
     /** Snapshot-cache binding (Layer 3). When present AND `deps.cache` is
      *  wired, the initial snapshot is served through the cache, tagged with
      *  the dependent-table set, and kept warm by the recompute path. */
-    cacheBinding?: SnapshotCacheBinding): Promise<() => void>;
+    cacheBinding?: SnapshotCacheBinding, 
+    /** Re-run the query's `guards:` before every delivery — see
+     *  `ActiveSubscription.reauthorize`. Omitted for unguarded queries. */
+    reauthorize?: () => Promise<unknown>, 
+    /** Re-resolve row visibility per delivery — see `ActiveSubscription.refilter`. */
+    refilter?: () => Promise<RowFilterScope>): Promise<() => void>;
+    /**
+     * Tear a subscription down because authorization was WITHDRAWN mid-stream,
+     * and tell the client why.
+     *
+     * A denial is not a transient failure, so it must not be handled like one.
+     * The re-query paths deliberately keep a failing subscriber on its last
+     * good snapshot (a bad predicate shouldn't wedge the stream) — but doing
+     * that for a revoked subject would leave authorized data sitting in a
+     * client that is no longer entitled to it, with no signal that anything
+     * changed. Emitting the typed `ScopeError` and closing is the honest
+     * outcome: the client surfaces the denial and can re-subscribe if the
+     * grant comes back.
+     */
+    private revokeSubscription;
+    /** `revokeSubscription` for the computed path. Same reasoning. */
+    private revokeComputed;
     /**
      * Register a COMPUTED-query subscription. The handler already ran once
      * (its value is `computed.value`); we emit that as the initial snapshot,
@@ -1496,6 +1784,33 @@ export declare interface DispatcherDependencies {
     readonly cache?: SnapshotCache;
 }
 
+export declare interface DrainDeps {
+    readonly store: Pick<DataStore, 'query' | 'update' | 'insert' | 'delete'>;
+    readonly handlers: ReadonlyMap<string, OutboxHandlerDefinition>;
+    readonly now?: () => Date;
+    /** Max rows per drain pass. */
+    readonly batchSize?: number;
+    /** Per-entry cap on retained attempt rows. See {@link OUTBOX_ATTEMPT_LOG_CAP}. */
+    readonly attemptLogCap?: number;
+}
+
+/**
+ * One drain pass: claim due rows, run their handler, record the outcome.
+ *
+ * A row whose handler is unknown is left PENDING rather than dead-lettered —
+ * the usual cause is a deploy where the enqueuing code shipped before the
+ * handler, and discarding those would turn a rollout ordering detail into
+ * permanent data loss.
+ */
+export declare const drainOutbox: (deps: DrainDeps) => Promise<DrainResult>;
+
+export declare interface DrainResult {
+    readonly delivered: number;
+    readonly failed: number;
+    readonly dead: number;
+    readonly skipped: number;
+}
+
 /**
  * Up to `limit` wakeups that are due now (`wakeAt <= now`), earliest
  * first. Pending rows are read ordered by `wakeAt`, so the earliest —
@@ -1514,9 +1829,13 @@ export declare class EffectStore extends EffectStore_base {
 declare const EffectStore_base: Context.TagClass<EffectStore, "@voltro/EffectStore", EffectStoreOps>;
 
 export declare interface EffectStoreOps {
-    readonly query: (descriptor: QueryDescriptor) => Effect.Effect<ReadonlyArray<Row_4>, StoreError>;
-    readonly insert: (table: string, row: Row_4) => Effect.Effect<Row_4, StoreError>;
-    readonly update: (table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>) => Effect.Effect<Row_4 | null, StoreError>;
+    /** Typed the same way `FluentStore.query` is — the row type rides in on the
+     *  descriptor, so an Effect-form handler reads real fields instead of
+     *  casting off `Record<string, unknown>`. Falls back to `Row` for a
+     *  hand-built descriptor. */
+    readonly query: <R = Row>(descriptor: QueryDescriptor<R>) => Effect.Effect<ReadonlyArray<R>, StoreError>;
+    readonly insert: (table: string, row: Row) => Effect.Effect<Row, StoreError>;
+    readonly update: (table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>) => Effect.Effect<Row | null, StoreError>;
     readonly delete: (table: string, primaryKey: string) => Effect.Effect<boolean, StoreError>;
     /** Bypass soft-delete. See `MutationStore.hardDelete`. */
     readonly hardDelete: (table: string, primaryKey: string) => Effect.Effect<boolean, StoreError>;
@@ -1530,6 +1849,15 @@ export declare const emptySchemaRegistry: SchemaRegistry;
  *  columns use). Throws if no cipher is registered. */
 export declare const encryptField: (plaintext: string) => string;
 
+export declare interface EnqueueOptions {
+    /** Drop this enqueue if an undelivered row already carries the same key. */
+    readonly idempotencyKey?: string;
+    /** Override the handler's `maxAttempts` for this one effect. */
+    readonly maxAttempts?: number;
+    /** Delay the first attempt (ms from now). */
+    readonly delayMs?: number;
+}
+
 /** The always-available default — reads `process.env`. Sync under the hood,
  *  Promise-wrapped to satisfy the async contract. */
 export declare const envSecretsBackend: SecretsBackend;
@@ -1553,6 +1881,13 @@ export declare interface EventsFacadeOptions {
     readonly makeId?: (prefix: 'wfe' | 'wfed') => string;
 }
 
+/** Exchange an authorization code (from the callback) for a token set. */
+export declare const exchangeAuthorizationCode: (definition: OAuth2ConnectionDefinition, input: {
+    readonly code: string;
+    readonly redirectUri: string;
+    readonly codeVerifier?: string | null;
+}, now?: () => number) => Promise<ConnectionTokens>;
+
 /** Build an Effect `ExternalSpan` parent from a `traceparent` header so
  *  inbound HTTP work continues the caller's trace. Returns undefined
  *  when the header is missing/invalid (no parent → a fresh root span). */
@@ -1575,7 +1910,51 @@ export declare interface FieldChange {
  */
 export declare const fingerprintFor: (table: string, predicate: Predicate, indexHint?: string) => string;
 
-export declare interface FluentStore extends Omit<MutationStore, 'update' | 'delete'> {
+export declare interface FluentStore extends Omit<MutationStore, 'update' | 'delete' | 'query'> {
+    /**
+     * Execute a query descriptor and return the matching rows — TYPED.
+     *
+     * The row type rides in on the descriptor (`QueryDescriptor<R>`), so
+     * `ctx.store.query(database.notes.where(...).descriptor)` gives you
+     * `ReadonlyArray<Note>`, not `ReadonlyArray<Record<string, unknown>>`. The
+     * builder always knew the shape; it used to be dropped exactly here, which
+     * is why reading a field meant writing `row['title'] as string` — one
+     * downstream app accumulated 2,032 of those casts.
+     *
+     * A hand-built descriptor still resolves to `Row`, i.e. the previous
+     * behaviour. This never types LESS than before.
+     *
+     * The driver-level `DataStore.query` stays untyped on purpose — it is the
+     * SPI every dialect store implements, and it genuinely does return untyped
+     * rows off the wire. The type is re-applied here, at the handler boundary.
+     */
+    query<R = Row_5>(descriptor: QueryDescriptor<R>): Promise<ReadonlyArray<R>>;
+    /**
+     * Terminal: EXACTLY one row, TYPED. Fails with `NoRowFound` on zero matches
+     * and equally on two or more.
+     *
+     * This exists because the two things we recommend did not compose. The typed
+     * read path lives on the typed builder (`database.users.where(...)`), while
+     * `.one()` lived only on the string-keyed `select('users')` builder, which
+     * yields untyped `Row`. So adopting `.one()` meant re-introducing the very
+     * casts the typed path removes — you could have typed rows OR the terminal,
+     * not both. That is not a "last mile" gap for sophisticated apps; it is two
+     * features from the same release failing to meet.
+     *
+     * Takes the builder itself or its `.descriptor` — both read fine:
+     *
+     *     const user = await ctx.store.one(database.users.where(eq('id', id)))
+     *
+     * Scoping is identical to `query()` (tenant + soft-delete apply), because it
+     * IS `query()` underneath — the probe just asks for one row more than it
+     * needs so "the first of several" cannot masquerade as "the one you meant".
+     */
+    one<R = Row_5>(query: QueryLike<R>): Promise<R>;
+    /** Terminal: the first matching row or `null`, TYPED. Use when "any match" is
+     *  genuinely what you mean. */
+    first<R = Row_5>(query: QueryLike<R>): Promise<R | null>;
+    /** Alias of `first` — the first matching row or `null`, TYPED. */
+    maybeOne<R = Row_5>(query: QueryLike<R>): Promise<R | null>;
     /** Fluent, scope-applying read builder: `select('notes').where(...).all()`. */
     select(table: string): SelectBuilder;
     /** Fluent predicate update: `update('notes').where('id', id).set({...})`. */
@@ -1606,6 +1985,9 @@ export declare interface FluentStoreBackend {
     readonly delete: DataStore['delete'];
 }
 
+/** Forget the calling subject's credential. Returns whether a row was removed. */
+export declare const forgetCredential: (store: VaultStore, connectionId: string, subjectId: string) => Promise<boolean>;
+
 /** Serialise a span's context as a `traceparent` header value. */
 export declare const formatTraceparent: (ctx: TraceContext) => string;
 
@@ -1643,6 +2025,9 @@ export declare const gauge: (name: string, description?: string) => Metric.Metri
 /** Generate a fresh token `<prefix><40-char-base64url>`. */
 export declare const generateApiKeyToken: (prefix?: string) => string;
 
+/** The registered resolver, if the app declared any connections. */
+export declare const getConnectionResolver: () => ConnectionResolver | undefined;
+
 /** Look up the override for a connection. Returns `undefined` if no override is set. */
 export declare const getConnectionSubject: (clientId: number) => Subject | undefined;
 
@@ -1651,12 +2036,22 @@ export declare const getFieldCipher: () => FieldCipher | undefined;
 
 export declare const getResourcePolicy: (resourceType: string) => ResourcePolicy | undefined;
 
+/** The registered row filter, or `undefined`. */
+export declare const getRowFilter: () => RowFilter<never> | undefined;
+
 /** The per-process recorder (created lazily from `VOLTRO_TIMELINE`). The change
  *  tap feeds it; the inspect endpoint reads it. */
 export declare const getTimelineRecorder: () => TimelineRecorder;
 
+export declare const getTupleSource: () => TupleSource | undefined;
+
+/** How long a started handshake stays claimable. Long enough for a slow
+ *  consent screen (and a password-manager detour), short enough that a stolen
+ *  state value is worthless by the time it is found. */
+export declare const GRANT_TTL_MS: number;
+
 /** Stable group key from the groupBy column values (JSON to disambiguate types). */
-export declare const groupKeyOf: (row: Row_2, groupBy: ReadonlyArray<string> | undefined) => string;
+export declare const groupKeyOf: (row: Row_3, groupBy: ReadonlyArray<string> | undefined) => string;
 
 /** Per-group accumulator. `count` is always kept (to know when a group empties
  *  and to compute avg); `sum` for sum/avg; `extreme` for min/max. */
@@ -1756,7 +2151,7 @@ export declare class IndexedMatcher implements Matcher {
 
 export declare class InMemoryDataStore implements DataStore {
     #private;
-    constructor(initial?: Record<string, ReadonlyArray<Row_4>>, namespace?: string | null);
+    constructor(initial?: Record<string, ReadonlyArray<Row>>, namespace?: string | null);
     /**
      * Return a namespace-bound view. The view shares THIS store's table
      * map, emitter, and id counters (one process, one in-memory database)
@@ -1765,11 +2160,11 @@ export declare class InMemoryDataStore implements DataStore {
      * table that never carried the `tenant()` mixin.
      */
     withNamespace(namespace: string | null): DataStore;
-    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row_4>>;
-    insert(table: string, row: Row_4): Promise<Row_4>;
-    insertMany(table: string, rows: ReadonlyArray<Row_4>): Promise<ReadonlyArray<Row_4>>;
-    patchJson(table: string, primaryKey: string, path: string, value: unknown): Promise<Row_4 | null>;
-    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row_4 | null>;
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
+    insert(table: string, row: Row): Promise<Row>;
+    insertMany(table: string, rows: ReadonlyArray<Row>): Promise<ReadonlyArray<Row>>;
+    patchJson(table: string, primaryKey: string, path: string, value: unknown): Promise<Row | null>;
+    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row | null>;
     delete(table: string, primaryKey: string): Promise<boolean>;
     updateMany(table: string, patch: Readonly<Record<string, unknown>>, options: {
         where: Predicate;
@@ -1777,13 +2172,13 @@ export declare class InMemoryDataStore implements DataStore {
     deleteMany(table: string, options: {
         where: Predicate;
     }): Promise<number>;
-    upsert(table: string, row: Row_4, options: {
+    upsert(table: string, row: Row, options: {
         conflictColumns: ReadonlyArray<string>;
-        update?: ReadonlyArray<string> | ((existing: Row_4) => Readonly<Record<string, unknown>>);
-    }): Promise<Row_4>;
-    insertIgnore(table: string, row: Row_4, options: {
+        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
+    }): Promise<Row>;
+    insertIgnore(table: string, row: Row, options: {
         conflictColumns: ReadonlyArray<string>;
-    }): Promise<Row_4>;
+    }): Promise<Row>;
     transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
     onChange(listener: (event: ChangeEvent) => void): () => void;
     /** Cross-instance reactivity seam — emit an externally-sourced event to
@@ -1858,6 +2253,25 @@ export declare interface InspectStream {
 
 export { inspectWorkflow }
 
+/**
+ * Install the resolver that answers `guards: [{ action, resourceType }]`.
+ *
+ * Called once at boot by both entrypoints. Every denial path is explicit
+ * because each one is a place where a plausible implementation would instead
+ * pass:
+ *
+ *   - unknown resource type → DENY. A guard naming a policy that was never
+ *     registered is a misconfiguration, and a misconfigured authorization
+ *     check must not be a permissive one.
+ *   - no tuple source → DENY. Nothing can answer the question.
+ *   - tuple source throws → DENY, and log it. A database blip must not become
+ *     an open door.
+ *
+ * `can()` itself already handles the `admin:full` bypass, anonymous denial and
+ * cross-tenant denial, so this layer does not re-implement them.
+ */
+export declare const installPolicyGuardResolver: () => void;
+
 /** Fire every registered interrupt for `clientId` (called on disconnect). */
 export declare const interruptConnectionStreams: (clientId: number) => void;
 
@@ -1989,10 +2403,20 @@ export declare class LinearScanMatcher implements Matcher {
     stats(): MatcherStats;
 }
 
+/** Every connection the app declares, projected for ONE subject. */
+export declare const listConnectionStates: (store: VaultStore, registry: ConnectionRegistry, subjectId: string) => Promise<ReadonlyArray<ConnectionState>>;
+
 export declare const listResourcePolicies: () => ReadonlyArray<ResourcePolicy>;
 
 export { listRetentions }
 
+export declare interface LoaderDeps {
+    readonly store: Pick<DataStore, 'query'>;
+    /** Coalesce window. Loads issued within the same microtask batch together;
+     *  the default (a resolved promise tick) needs no timers. */
+    readonly schedule?: (flush: () => void) => void;
+}
+
 /** Load the tuples for one (subject, resource) — the interceptor's tuple source.
  *  Returns [] for an anonymous subject (→ `can` denies anyway). */
 export declare const loadResourceTuples: (store: DataStore, subjectId: string | null, resourceType: string, resourceId: string) => Promise<ReadonlyArray<RelationTuple>>;
@@ -2114,6 +2538,20 @@ export declare const makeAsyncKv: ({ store, env }: KvFacadeOptions) => Promise<K
  */
 export declare const makeBufferingSpanProcessor: (onSpanEnd: (record: TraceSpanRecordLike) => void) => SpanProcessor;
 
+/** Build a registry from the discovered declarations. Duplicate ids throw —
+ *  two files claiming one id means whichever loaded last silently wins and the
+ *  other file looks live but is dead. */
+export declare const makeConnectionRegistry: (definitions: ReadonlyArray<ConnectionDefinition>) => ConnectionRegistry;
+
+/** Build the process resolver over a store + registry. The CLI hands the
+ *  result to `setConnectionResolver`. */
+export declare const makeConnectionResolver: (deps: {
+    readonly store: DataStore;
+    readonly registry: ConnectionRegistry;
+}) => ConnectionResolver;
+
+export declare const makeConnectionsFacade: (deps: ConnectionsFacadeDeps) => ConnectionsFacade;
+
 /**
  * Factory the CLI binds into the plugin bind-ctx: closes over the
  * process-wide coordinator + replicaId so a plugin calls the ergonomic
@@ -2123,6 +2561,19 @@ export declare const makeBufferingSpanProcessor: (onSpanEnd: (record: TraceSpanR
  */
 export declare const makeCoordinatedScheduler: (deps: CoordinatedScheduleDeps) => ((name: string, intervalMs: number, effect: () => void | Promise<void>) => CoordinatedScheduleHandle);
 
+/**
+ * Build a request-scoped loader. One instance per AppContext — see the module
+ * header for why this must not be shared across requests.
+ */
+export declare const makeDataLoader: (deps: LoaderDeps) => DataLoader;
+
+/** `__voltro.connections.disconnect` — forget the caller's credential. */
+export declare const makeDisconnectConnectionExecutor: (deps: ConnectionBuiltinDeps) => (input: {
+    readonly connectionId: string;
+}, ctx: ConnectionExecutorCtx) => Promise<{
+    readonly ok: boolean;
+}>;
+
 /**
  * Build the Layer that provides `EffectStore` from a `MutationStore`.
  * dev.ts (CLI) and any standalone test setup uses this to wire up the
@@ -2153,6 +2604,9 @@ export declare const makeIdleGate: (graceMs: number, now?: () => number) => Idle
 
 export declare const makeLazyWorkflowFacade: (resolve: () => WorkflowsAppContext | undefined) => WorkflowsAppContext;
 
+/** `__voltro.connections.list` — every declared connection, for the caller. */
+export declare const makeListConnectionsExecutor: (deps: ConnectionBuiltinDeps) => (_input: Record<string, never>, ctx: ConnectionExecutorCtx) => Promise<ReadonlyArray<ConnectionState>>;
+
 /**
  * Build the shared mutation runner. Used by BOTH the rpc WS handler and
  * the `/_voltro/inspect/invoke` endpoint (and the prod entrypoint) so they
@@ -2168,6 +2622,8 @@ export declare const makeLazyWorkflowFacade: (resolve: () => WorkflowsAppContext
  */
 export declare const makeMutationRunner: (deps: MutationRunnerDeps) => (mutation: MutationLike, input: unknown, requestContext: ServeRequestContext) => Promise<unknown>;
 
+export declare const makeOutboxFacade: (deps: OutboxFacadeDeps) => OutboxFacade;
+
 export declare const makePostCommitWorkflowFacade: (base: WorkflowsAppContext, afterCommit: (work: () => Promise<unknown>) => void) => WorkflowsAppContext;
 
 /**
@@ -2188,6 +2644,27 @@ export declare const makeProcessAdapter: (supervisor: AppSupervisor) => WakeAdap
  */
 export declare const makeQueryDescriptorProducer: <D>(deps: QueryProducerDeps<D>) => (query: MutationLike, input: unknown) => (requestContext: ServeRequestContext) => D | ComputedQuery | Effect.Effect<D | ComputedQuery, unknown, never>;
 
+/**
+ * Build the per-subscription authorization re-check.
+ *
+ * `guards:` are enforced once when a subscription is opened. That is not
+ * enough on its own: a subscription is a LONG-LIVED grant, and the scopes
+ * that justified it can be withdrawn while it is still open (a role
+ * revoked, a resource un-shared, a membership ended). Without a re-check
+ * the socket keeps delivering rows the subject may no longer read until
+ * the client happens to disconnect.
+ *
+ * So every delivery re-runs the same `checkGuardsEffect` the subscribe-time
+ * gate ran — including the async resource-scope resolver, which is where a
+ * per-row/per-team revocation actually shows up. Returns `null` when the
+ * subject still passes, or the typed `ScopeError` that denied it.
+ *
+ * Returns a closure that always resolves `null` when the descriptor carries
+ * no guards, so the caller needs no branch and an unguarded query pays only
+ * a resolved promise.
+ */
+export declare const makeQueryReauthorizer: (query: MutationLike, input: unknown) => (subject: Subject) => () => Promise<unknown>;
+
 export declare const makeRouterActivity: () => RouterActivity;
 
 /**
@@ -2196,6 +2673,23 @@ export declare const makeRouterActivity: () => RouterActivity;
  */
 export declare const makeSchemaRegistry: (tables: ReadonlyArray<RegistryTableLike>) => SchemaRegistry;
 
+/** `__voltro.connections.start` — mint the consent URL for an oauth2 flow. */
+export declare const makeStartConnectionExecutor: (deps: ConnectionBuiltinDeps) => (input: {
+    readonly connectionId: string;
+    readonly redirectTo?: string;
+}, ctx: ConnectionExecutorCtx) => Promise<{
+    readonly authorizeUrl: string;
+    readonly state: string;
+}>;
+
+/** `__voltro.connections.submitToken` — store a pasted personal access token. */
+export declare const makeSubmitTokenExecutor: (deps: ConnectionBuiltinDeps) => (input: {
+    readonly connectionId: string;
+    readonly token: string;
+}, ctx: ConnectionExecutorCtx) => Promise<{
+    readonly ok: boolean;
+}>;
+
 /**
  * The factory the serve entrypoints inject into `makeMutationRunner`'s
  * `undoCapture` dep. Collects changes from the wrapped tx; `persist` writes ONE
@@ -2366,7 +2860,7 @@ export declare interface MutationLike {
     readonly descriptor: {
         readonly name: string;
         readonly source?: string | ReadonlyArray<string> | undefined;
-        readonly guards?: ReadonlyArray<GuardCheckSpec> | undefined;
+        readonly guards?: ReadonlyArray<AnyCheckSpec> | undefined;
     };
     executor(input: unknown, ctx: unknown): unknown;
 }
@@ -2427,6 +2921,10 @@ export declare const nextFiring: (def: ScheduleDefinition, after?: Date) => Date
  */
 export declare const nextWakeup: (store: DataStore) => Promise<Wakeup | null>;
 
+/** A scope that constrains nothing — the shape used when no filter is
+ *  registered, or for a system subject. */
+export declare const NO_ROW_FILTER: RowFilterScope;
+
 /**
  * The real single-node supervisor: `spawn`s the app command and considers
  * it healthy once `healthUrl` returns 2xx. Stopping sends `stopSignal`
@@ -2495,14 +2993,25 @@ export declare const noopAnalyticsSpec: AnalyticsSinkSpec;
  *  misses, writes are dropped. Mirrors the cache's `noopCache`. */
 export declare const noopKv: AsyncKv;
 
-/** Thrown by `.one()` when a query that must match exactly one row found
- *  none. Distinct from a found-but-wrong row — this is strictly "0 rows". */
-export declare class NoRowFound extends Error {
-    readonly table: string;
-    readonly _tag = "NoRowFound";
-    constructor(table: string);
+/**
+ * `.one()` matched a number of rows other than exactly one.
+ *
+ * `found` distinguishes the two failure modes without a second error type:
+ * `0` is "the row you required is missing", `2` is "your filter is not as
+ * unique as you assumed" (the terminal probes with LIMIT 2, so `2` means
+ * "at least two" — it never counts the whole set just to report a number).
+ */
+export declare class NoRowFound extends NoRowFound_base {
+    get message(): string;
 }
 
+declare const NoRowFound_base: Schema.TaggedErrorClass<NoRowFound, "NoRowFound", {
+    readonly _tag: Schema.tag<"NoRowFound">;
+} & {
+    table: typeof Schema.String;
+    found: typeof Schema.Number;
+}>;
+
 export declare interface Notification {
     readonly subscriberId: string;
     readonly fingerprint: string;
@@ -2510,6 +3019,32 @@ export declare interface Notification {
     readonly newMatched: boolean;
 }
 
+export declare interface OAuth2ConnectionDefinition extends ConnectionDefinitionCommon {
+    readonly kind: 'oauth2';
+    readonly authorizeUrl: string;
+    readonly tokenUrl: string;
+    readonly clientId: string;
+    /** Runtime secret. Never logged, never sent to the browser, never bundled —
+     *  `*.connection.ts` is server-only and is NOT part of the rpcGroup codegen. */
+    readonly clientSecret: string;
+    readonly scopes?: ReadonlyArray<string>;
+    /** Exact redirect URI registered with the provider. Defaults to
+     *  `<publicUrl>/_voltro/connections/<id>/callback`. */
+    readonly redirectUri?: string;
+    /** Extra fixed query params on the authorize URL (`audience`, `prompt`, …). */
+    readonly authorizeParams?: Record<string, string>;
+    /** PKCE (S256). On by default — it costs one hash and closes the
+     *  authorization-code interception hole for public clients. */
+    readonly pkce?: boolean;
+    /** Renew when the token is within this many ms of expiry. Default 60_000 —
+     *  enough headroom that an in-flight request can't race the deadline. */
+    readonly refreshSkewMs?: number;
+    /** Injectable transport (tests, proxies). Defaults to the global `fetch`. */
+    readonly fetchImpl?: ConnectionFetch;
+    /** Resolve who the freshly-minted token belongs to, for display. */
+    readonly identify?: (tokens: ConnectionTokens) => Promise<ConnectionAccount>;
+}
+
 /**
  * Listen for re-bind events. Returns an unsubscribe function. Used by
  * the dispatcher to re-scope active subscriptions when a connection's
@@ -2520,13 +3055,17 @@ export declare const onBindConnectionSubject: (listener: (clientId: number, subj
 
 /** Thrown by `.expectVersion(n).set(...)` when the optimistic-lock guard
  *  matched no row (the row was concurrently updated or deleted). */
-export declare class OptimisticLockError extends Error {
-    readonly table: string;
-    readonly expected: number;
-    readonly _tag = "OptimisticLockError";
-    constructor(table: string, expected: number);
+export declare class OptimisticLockError extends OptimisticLockError_base {
+    get message(): string;
 }
 
+declare const OptimisticLockError_base: Schema.TaggedErrorClass<OptimisticLockError, "OptimisticLockError", {
+    readonly _tag: Schema.tag<"OptimisticLockError">;
+} & {
+    table: typeof Schema.String;
+    expected: typeof Schema.Number;
+}>;
+
 export declare interface OrchestratorTickDeps {
     readonly store: DataStore;
     readonly supervisor: AppSupervisor;
@@ -2537,6 +3076,135 @@ export declare interface OrchestratorTickDeps {
     readonly log?: WakeOrchestratorLogger;
 }
 
+/**
+ * Retention, part 1 of 2 — the PER-ENTRY cap.
+ *
+ * The automatic path is already bounded by `maxAttempts` (default 8), so the
+ * only way one entry's history grows without limit is repeated manual resends
+ * of the same row — a support workflow that can genuinely run for years. Once an
+ * entry passes this many attempts, recording a new one trims the oldest, so the
+ * log is a bounded ring per entry: the recent attempts are what a history UI
+ * shows, and the 200th-oldest failure of a chronically broken effect is not
+ * worth a row.
+ *
+ * The check is keyed off the attempt NUMBER, which the drain already knows, so
+ * the normal (never-resent) path pays no extra query at all — it can never
+ * reach the cap.
+ *
+ * Part 2 is the time-based bound: the CLI's boot sweep registers a retention
+ * spec over `startedAt` (default 30 days, `VOLTRO_OUTBOX_ATTEMPTS_TTL_HOURS`).
+ * Both exist because they bound different failure modes — the cap stops ONE hot
+ * entry, the TTL stops the accumulation of MANY cold ones — and only the cap
+ * works on every dialect (the sweep is postgres-gated).
+ */
+export declare const OUTBOX_ATTEMPT_LOG_CAP = 50;
+
+export declare const OUTBOX_ATTEMPTS_TABLE = "_voltro_outbox_attempts";
+
+export declare const OUTBOX_TABLE = "_voltro_outbox";
+
+/** Terminal outcome of ONE attempt. `dead` is a failure that also exhausted the
+ *  budget — kept separate from `failed` so a listing can render "gave up here"
+ *  without cross-referencing the parent row's status. */
+export declare type OutboxAttemptOutcome = 'delivered' | 'failed' | 'dead';
+
+/**
+ * One row per delivery ATTEMPT — the queryable history behind `_voltro_outbox`.
+ *
+ * The outbox row alone answers "did this eventually land"; it cannot answer
+ * "what did the remote say on attempt 3", "how long did it take", "who resent
+ * it", which is what a delivery-history UI renders. Columns are chosen from
+ * that render, not from what is convenient to write:
+ *
+ *   - a listing row needs: when, which effect, attempt #, outcome, duration,
+ *     and (for a failure) the error — all here, no JOIN;
+ *   - `effect` / `subjectId` / `tenantId` are DENORMALISED so the history stays
+ *     readable (and tenant-scopable) after the parent outbox row is purged by
+ *     retention, and so a per-tenant listing needs no join;
+ *   - `response` carries the handler's own return value, which is where an
+ *     HTTP-shaped handler puts `{ status, body }` — the framework does not
+ *     model HTTP, so it snapshots whatever the handler chose to return rather
+ *     than inventing status/response columns only some handlers can fill.
+ *
+ * Append-only. Bounded two ways — see `recordAttempt` + the retention
+ * registration in the CLI's boot sweep.
+ */
+export declare const outboxAttemptsTable: TableLike;
+
+/** How an attempt came to be made. `automatic` = the drain picked the row up on
+ *  its own schedule; `manual` = a human/API asked for it via `resend()`. The
+ *  distinction is the point of the field: without it a support-triggered
+ *  redelivery is indistinguishable from a backoff retry, and "did we send this
+ *  twice because of us or because of them" becomes unanswerable. */
+export declare type OutboxAttemptTrigger = 'automatic' | 'manual';
+
+export declare interface OutboxFacade {
+    /**
+     * Persist the intent to run `effect` after this transaction commits.
+     *
+     * Returns the outbox row id, which doubles as the delivery id a client can
+     * watch to render external-side-effect progress ("saving… syncing… synced").
+     */
+    enqueue(effect: string, payload: Record<string, unknown>, options?: EnqueueOptions): Promise<string>;
+    /**
+     * Re-arm one entry for delivery NOW, on purpose, attributed to the caller.
+     *
+     * Legitimate because the delivery contract is already at-least-once and
+     * handlers must therefore be idempotent — a manual resend is the SAME hazard
+     * the contract already requires handlers to absorb, not a new one. What it is
+     * not allowed to be is invisible: the next attempt is recorded with
+     * `trigger: 'manual'` plus the requesting subject and reason, so an operator
+     * redelivery can never be mistaken for a backoff retry when someone later
+     * asks why the remote saw the effect twice.
+     *
+     * Three deliberate choices:
+     *   - It RE-ARMS the existing row rather than enqueuing a new one. A copy
+     *     would carry the same `idempotencyKey` (breaking the dedupe invariant),
+     *     duplicate the payload, and split one entry's history across two ids.
+     *   - It grants a SMALL fresh budget (`attempts`, default 1) instead of
+     *     resetting the counter. A dead row has `attempts >= maxAttempts`, so
+     *     without this it would re-die untried; and "try again now" is what the
+     *     button means — not "restart the whole eight-attempt backoff schedule".
+     *   - It refuses a row that is mid-flight (`delivering`), where re-arming
+     *     races the in-progress attempt into a same-process double delivery this
+     *     layer CAN prevent (unlike the cross-replica one).
+     */
+    resend(outboxId: string, options?: ResendOptions): Promise<void>;
+}
+
+export declare interface OutboxFacadeDeps {
+    /** The REQUEST's store. Inside a mutation this is the transactional view —
+     *  which is what makes the enqueue atomic with the domain write. */
+    readonly store: Pick<DataStore, 'insert' | 'query' | 'update'>;
+    readonly subject: Subject;
+    readonly traceId: string | null;
+    /** Nudge the drain worker once the transaction commits. Optional: without
+     *  it the row still delivers on the next poll tick, just later. */
+    readonly afterCommit?: (work: () => Promise<unknown>) => void;
+    /** Wake the drain loop. */
+    readonly nudge?: () => void;
+    readonly now?: () => Date;
+}
+
+export declare interface OutboxHandlerContext {
+    readonly payload: Record<string, unknown>;
+    readonly attempt: number;
+    readonly subjectId: string | null;
+    readonly tenantId: string | null;
+    readonly traceId: string | null;
+}
+
+export declare interface OutboxHandlerDefinition {
+    readonly effect: string;
+    readonly handler: (ctx: OutboxHandlerContext) => Promise<unknown>;
+    /** Give up after this many attempts, then dead-letter. Default 8. */
+    readonly maxAttempts?: number;
+}
+
+export declare type OutboxStatus = 'pending' | 'delivering' | 'delivered' | 'dead';
+
+export declare const outboxTable: TableLike;
+
 declare interface P2COptions {
     /**
      * Random selector — `Math.random()` by default. Tests inject a
@@ -2550,6 +3218,18 @@ declare interface P2COptions {
  *  treated as "no parent"). */
 export declare const parseTraceparent: (header: string | undefined | null) => TraceContext | null;
 
+export declare interface PatConnectionDefinition extends ConnectionDefinitionCommon {
+    readonly kind: 'pat';
+    /** Where to send the user to mint a token — rendered as a help link. */
+    readonly instructionsUrl?: string;
+    /**
+     * Verify a pasted token before storing it. Rejecting here is what turns
+     * "the user typed it wrong" into an immediate error instead of a mysterious
+     * 401 from a background job three hours later. Throwing fails the submit.
+     */
+    readonly validate?: (token: string) => Promise<ConnectionAccount>;
+}
+
 /** The 3-arg signature a plugin sees on its bind-ctx. */
 export declare type PluginScheduleCoordinated = (name: string, intervalMs: number, effect: () => void | Promise<void>) => CoordinatedScheduleHandle;
 
@@ -2577,6 +3257,11 @@ export declare interface PreviewStore {
     transactional: <T>(fn: (tx: unknown) => Promise<T>) => Promise<T>;
 }
 
+/** Project a stored row into the wire shape. Deliberately total over the
+ *  columns the descriptor declares — and deliberately silent about the token
+ *  columns, which have no wire representation at all. */
+export declare const projectConnectionState: (definition: ConnectionDefinition, row: AnyRow | undefined) => ConnectionState;
+
 /** Exact-match property filter. Values are AND'd. */
 export declare type PropertyFilter = Readonly<Record<string, string | number | boolean | null>>;
 
@@ -2653,6 +3338,12 @@ export declare interface PublicApiKey {
     readonly createdAt: number;
 }
 
+/** A typed builder or its descriptor — the single-row terminals accept either,
+ *  so a call site never has to reach for `.descriptor` just to use them. */
+export declare type QueryLike<R = Row_5> = QueryDescriptor<R> | {
+    readonly descriptor: QueryDescriptor<R>;
+};
+
 export declare interface QueryProducerDeps<D> {
     readonly buildContext: (request: ServeRequestContext) => {
         readonly store: unknown;
@@ -2821,7 +3512,7 @@ export declare const recordTimelineEvent: (change: CdcChange & {
 }) => void;
 
 /** Blank sensitive-looking columns. Returns a new object; null passes through. */
-export declare const redactRow: (row: Row | null | undefined) => Row | null;
+export declare const redactRow: (row: Row_2 | null | undefined) => Row_2 | null;
 
 /**
  * Options for `redisRywPositionStore`. The store needs TWO Redis
@@ -2902,6 +3593,15 @@ export declare const redoUndoInvocation: (input: {
     readonly ok: boolean;
 }>;
 
+/** How long a refresh claim is held before another replica may take it. Long
+ *  enough for a slow token endpoint, short enough that a crashed replica does
+ *  not block renewal for long. */
+export declare const REFRESH_LEASE_MS = 30000;
+
+/** Swap a refresh token for a fresh set. Providers that ROTATE return a new
+ *  refresh token; the caller persists whatever comes back. */
+export declare const refreshAccessToken: (definition: OAuth2ConnectionDefinition, refreshToken: string, now?: () => number) => Promise<ConnectionTokens>;
+
 /**
  * Register an interrupt for a stream bound to `clientId`. Returns a
  * deregister fn the stream's scope finalizer must call on normal end (so
@@ -3065,13 +3765,13 @@ export declare class ReplicatedDataStore implements DataStore {
     private readonly recordRouting?;
     private readonly now;
     constructor(options: ReplicatedDataStoreOptions);
-    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row_4>>;
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
     private routeToReplica;
     private routeWaitMode;
-    insert(table: string, row: Row_4): Promise<Row_4>;
-    insertMany(table: string, rows: ReadonlyArray<Row_4>): Promise<ReadonlyArray<Row_4>>;
-    patchJson(table: string, primaryKey: string, path: string, value: unknown): Promise<Row_4 | null>;
-    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row_4 | null>;
+    insert(table: string, row: Row): Promise<Row>;
+    insertMany(table: string, rows: ReadonlyArray<Row>): Promise<ReadonlyArray<Row>>;
+    patchJson(table: string, primaryKey: string, path: string, value: unknown): Promise<Row | null>;
+    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row | null>;
     delete(table: string, primaryKey: string): Promise<boolean>;
     updateMany(table: string, patch: Readonly<Record<string, unknown>>, options: {
         where: Predicate;
@@ -3079,13 +3779,13 @@ export declare class ReplicatedDataStore implements DataStore {
     deleteMany(table: string, options: {
         where: Predicate;
     }): Promise<number>;
-    upsert(table: string, row: Row_4, options: {
+    upsert(table: string, row: Row, options: {
         conflictColumns: ReadonlyArray<string>;
-        update?: ReadonlyArray<string> | ((existing: Row_4) => Readonly<Record<string, unknown>>);
-    }): Promise<Row_4>;
-    insertIgnore(table: string, row: Row_4, options: {
+        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
+    }): Promise<Row>;
+    insertIgnore(table: string, row: Row, options: {
         conflictColumns: ReadonlyArray<string>;
-    }): Promise<Row_4>;
+    }): Promise<Row>;
     transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
     onChange(listener: (event: ChangeEvent) => void): () => void;
     /** Cross-instance reactivity seam — delegates to the primary, where the
@@ -3149,12 +3849,49 @@ export declare interface ReplicatedDataStoreOptions {
     readonly now?: () => number;
 }
 
+export declare interface ResendOptions {
+    /** Operator's note, recorded on the resulting attempt row. */
+    readonly reason?: string;
+    /** How many attempts the resend is worth. Default 1 — see `resend`. */
+    readonly attempts?: number;
+}
+
 /** Test/dev-only — clear ALL overrides. Don't call from app code. */
 export declare const _resetConnectionSubjectsForTest: () => void;
 
 /** Reset to the env default (tests). */
 export declare const resetSecretsBackend: () => void;
 
+/**
+ * Resolve the calling subject's credential for one connection, refreshed.
+ *
+ * This is what a plugin or handler asks for. It never returns an expired
+ * token: either it hands back one that is valid past the skew window, or it
+ * throws. There is no "here's a token, good luck" third case, because the
+ * whole reason apps hand-roll a retry-on-401 is that such a case exists.
+ */
+export declare const resolveConnection: (deps: ResolveConnectionDeps) => Promise<ResolvedConnection>;
+
+export declare interface ResolveConnectionDeps {
+    readonly store: VaultStore;
+    readonly definition: ConnectionDefinition;
+    readonly subjectId: string;
+    readonly now?: () => number;
+    /** Injectable sleep so the wait-for-another-replica path is testable without
+     *  real time. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Resolve one subject's credential from anywhere on the server — a plugin's
+ * `credentialsResolver`, a cron, an outbox handler.
+ *
+ * Throws (rather than returning null) when no vault is registered: an app that
+ * asks for a connection it never declared has a configuration bug, and
+ * returning "not connected" would present it as a user problem.
+ */
+export declare const resolveConnectionForSubject: (subject: Pick<Subject, "id">, connectionId: string) => Promise<ResolvedConnection>;
+
 /**
  * Resolve the current process's region from the environment. Checks,
  * in priority order:
@@ -3169,6 +3906,27 @@ export declare const resetSecretsBackend: () => void;
  */
 export declare const resolveCurrentRegion: (env?: NodeJS.ProcessEnv) => string | undefined;
 
+/** What the auth strategy learns from a presented key. */
+export declare interface ResolvedApiKey {
+    readonly id: string;
+    readonly tenantId: string;
+    /** The user who created the key, when one is recorded. Null for a key minted
+     *  outside a user session (bootstrap / admin tooling). */
+    readonly createdBy: string | null;
+    readonly scopes: ReadonlyArray<string>;
+}
+
+/** A usable credential, handed to a plugin / handler. */
+export declare interface ResolvedConnection {
+    readonly connectionId: string;
+    readonly kind: ConnectionKind;
+    readonly accessToken: string;
+    readonly expiresAt: Date | null;
+    readonly scopes: ReadonlyArray<string>;
+    readonly accountId: string | null;
+    readonly accountLabel: string | null;
+}
+
 /**
  * Walk a query descriptor's eager-load tree and return the FULL set
  * of tables whose changes could affect the resolved snapshot.
@@ -3187,10 +3945,26 @@ export declare const resolveCurrentRegion: (env?: NodeJS.ProcessEnv) => string |
  */
 export declare const resolveDependentTables: (descriptor: QueryDescriptor) => ReadonlySet<string>;
 
+export declare const resolveRedirectUri: (definition: OAuth2ConnectionDefinition, publicUrl: string) => string;
+
 /** Rebuild the flagged groups from the (already-committed) base rows + merge —
  *  the caller's resolution of a min/max rescan signal. `baseRows` is the full
  *  current table (or at least every row in the rescan groups). */
-export declare const resolveRescan: (shape: AggregateShape, state: IvmState, rescanGroups: ReadonlyArray<string>, baseRows: ReadonlyArray<Row_2>) => IvmState;
+export declare const resolveRescan: (shape: AggregateShape, state: IvmState, rescanGroups: ReadonlyArray<string>, baseRows: ReadonlyArray<Row_3>) => IvmState;
+
+/**
+ * Resolve the request-scoped filter for `subject`.
+ *
+ * Fails CLOSED in the one way that matters: if `load` throws, every constrained
+ * read is refused rather than silently unfiltered. A row filter that degrades to
+ * "no filter" under load failure is worse than none, because the system keeps
+ * serving and nothing looks wrong.
+ *
+ * Refusal is expressed as a predicate that matches nothing, not as an error, so
+ * a failure surfaces as an empty result rather than a 500 on every page — and
+ * the failure itself is reported through `onError` so it cannot pass unnoticed.
+ */
+export declare const resolveRowFilterScope: (subject: Subject, onError?: (error: unknown) => void) => Effect.Effect<RowFilterScope>;
 
 /** Resolve a secret through the active backend. Falls back to `process.env`
  *  when the backend returns nothing, so a partially-populated remote backend
@@ -3233,7 +4007,7 @@ export { retentionTtlMsFromEnv }
  *   - delete → the row was removed, so add `old` back.
  * Pure. Applied newest-first to walk from "now" to a past point.
  */
-export declare const reverseEventOverRows: (rows: ReadonlyArray<Row>, e: TimelineEvent) => ReadonlyArray<Row>;
+export declare const reverseEventOverRows: (rows: ReadonlyArray<Row_2>, e: TimelineEvent) => ReadonlyArray<Row_2>;
 
 /** The ids that were visible before but are not now — what a live-revocation
  *  delta removes from an open subscription. */
@@ -3271,12 +4045,14 @@ export declare interface RoutingContext {
     readonly forcePrimary?: boolean;
 }
 
-declare type Row = Record<string, unknown>;
+export { Row }
 
-declare type Row_2 = Readonly<Record<string, unknown>>;
+declare type Row_2 = Record<string, unknown>;
 
 declare type Row_3 = Readonly<Record<string, unknown>>;
 
+declare type Row_4 = Readonly<Record<string, unknown>>;
+
 declare type Row_5 = Readonly<Record<string, unknown>>;
 
 export declare interface RowDiff {
@@ -3287,6 +4063,28 @@ export declare interface RowDiff {
     readonly fields: Readonly<Record<string, FieldChange>>;
 }
 
+/**
+ * The per-request filter, resolved from a subject.
+ *
+ * `Ctx` is whatever your `load` returns — typically the ids the predicate needs
+ * (team ids, project ids, a role map). The framework never inspects it.
+ */
+export declare interface RowFilter<Ctx = unknown> {
+    /** Resolve everything the predicates need, ONCE per request. May read the
+     *  store. A failure DENIES (see `resolveRowFilterContext`). */
+    readonly load: (subject: Subject) => Effect.Effect<Ctx, unknown>;
+    /**
+     * The filter for one table, derived purely from the loaded context. Return
+     * `undefined` for a table this filter does not constrain — most tables.
+     *
+     * Must be PURE and SYNC: it runs on every read.
+     */
+    readonly predicate: (ctx: Ctx, table: string) => Predicate | undefined;
+}
+
+/** What a scoped store needs: a sync `table → Predicate?` lookup. */
+export declare type RowFilterScope = (table: string) => Predicate | undefined;
+
 /** One `_voltro_row_history` row, structurally (from @voltro/plugin-versioning). */
 export declare interface RowHistoryEntry {
     readonly value?: unknown;
@@ -3481,6 +4279,23 @@ export declare interface RuntimeContext {
  */
 export declare const runWakeLoop: (deps: WakeOrchestratorDeps, intervalMs?: number) => WakeLoopHandle;
 
+/**
+ * Run a full-transaction thunk, replaying it on a transient DB error
+ * (deadlock / lock-wait). Non-transient failures throw on the first try.
+ * Backoff escalates with random jitter so concurrent victims don't
+ * re-collide in lockstep.
+ *
+ * `delay` overrides that backoff. The only caller that does is the unit-test
+ * harness (`@voltro/testing`'s `invoke`), which reproduces the replay against
+ * an in-memory store: there is no lock manager to de-correlate against there,
+ * so a real sleep would buy nothing and would stall a suite using fake timers.
+ * Exported for exactly that — one retry implementation, not a second one that
+ * drifts from this classification.
+ */
+export declare const runWithDeadlockRetry: <T>(work: () => Promise<T>, options?: {
+    readonly delay?: (attempt: number) => Promise<void>;
+}) => Promise<T>;
+
 /**
  * Run `work` inside a routing scope. Every `query()` call against a
  * `ReplicatedDataStore` from inside `work` (or its async children)
@@ -3531,6 +4346,14 @@ export declare interface RywPositionStore {
     size(): number;
 }
 
+/**
+ * Reject anything but a same-origin path. The callback ends in a 302 to this
+ * value, so accepting `https://evil.example` would turn every app that
+ * declares a connection into an open redirector — a phishing primitive handed
+ * out for free with a feature about credentials.
+ */
+export declare const sanitizeRedirectTo: (value: string | undefined) => string;
+
 /** Brand so the CLI's discovery loop can duck-type a `*.cron.tsx`
  *  default export without importing the concrete class. */
 declare const SCHEDULE_BRAND: unique symbol;
@@ -3835,6 +4658,8 @@ export declare interface SchemaRegistry {
 declare interface ScopeCtx {
     readonly subject: Subject;
     readonly schemaRegistry: SchemaRegistry;
+    /** Row-level security scope for this request — see `./rowFilter`. */
+    readonly rowFilter?: RowFilterScope;
 }
 
 export declare interface SecretsBackend {
@@ -3858,7 +4683,7 @@ export declare class SelectBuilder {
     private query;
     private skipTenant;
     private skipSoftDelete;
-    constructor(backend: FluentStoreBackend, scope: ScopeCtx, table: string, query: Query<Row_4>, skipTenant?: boolean, skipSoftDelete?: boolean);
+    constructor(backend: FluentStoreBackend, scope: ScopeCtx, table: string, query: Query<Row>, skipTenant?: boolean, skipSoftDelete?: boolean);
     private clone;
     /** `.where(eq(...))` (predicate AST) OR `.where(col, value)` /
      *  `.where(col, op, value)` (ergonomic). Multiple calls AND-merge. */
@@ -3868,7 +4693,7 @@ export declare class SelectBuilder {
     offset(n: number): SelectBuilder;
     select(...columns: ReadonlyArray<string>): SelectBuilder;
     using(indexName: string): SelectBuilder;
-    with(spec: Parameters<Query<Row_4>['with']>[0]): SelectBuilder;
+    with(spec: Parameters<Query<Row>['with']>[0]): SelectBuilder;
     groupBy(columns: ReadonlyArray<string>): SelectBuilder;
     matching(indexName: string, query: string): SelectBuilder;
     /** Drop the automatic tenant filter (cross-tenant staff reads). */
@@ -3877,13 +4702,23 @@ export declare class SelectBuilder {
     withDeleted(): SelectBuilder;
     private scopedQuery;
     /** Terminal: all matching rows. */
-    all(): Promise<ReadonlyArray<Row_4>>;
+    all(): Promise<ReadonlyArray<Row>>;
     /** Terminal: the first matching row or `null`. */
-    maybeOne(): Promise<Row_4 | null>;
+    maybeOne(): Promise<Row | null>;
     /** Alias of `maybeOne` — the first row or `null`. */
-    first(): Promise<Row_4 | null>;
-    /** Terminal: exactly one row; throws `NoRowFound` on zero matches. */
-    one(): Promise<Row_4>;
+    first(): Promise<Row | null>;
+    /**
+     * Terminal: EXACTLY one row. Fails with `NoRowFound` on zero matches —
+     * and equally on two or more.
+     *
+     * The over-fetch to LIMIT 2 is deliberate. A `LIMIT 1` probe cannot tell
+     * "the one row you meant" from "the first of several", so a filter that
+     * silently stopped being unique would keep returning an arbitrary row and
+     * the bug would surface far away from its cause. One extra row on the
+     * wire buys a loud failure at the point the assumption breaks. Use
+     * `.first()` / `.maybeOne()` when you genuinely want "any match".
+     */
+    one(): Promise<Row>;
     /** Terminal: COUNT(*) of matching rows (real aggregate, not a fetch). */
     count(): Promise<number>;
     /** Terminal: does any row match? Uses a `LIMIT 1` probe. */
@@ -3896,6 +4731,16 @@ export declare interface ServeRequestContext {
     readonly subject: unknown;
     readonly traceId: string;
     readonly spanId?: string;
+    /**
+     * Row-level visibility for this request, resolved by `withRowFilter` and read
+     * by the context builder when it wraps the store.
+     *
+     * Carried on the REQUEST because resolving it may read the database while the
+     * context builder is synchronous. Making the builder async would ripple
+     * through every entrypoint; resolving here, already inside an async
+     * boundary, does not.
+     */
+    readonly rowFilter?: RowFilterScope;
 }
 
 /** A plugin interceptor — wraps the base run Effect (Effect-native chain). */
@@ -3908,9 +4753,19 @@ export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown,
     readonly spanId?: string;
 }) => Effect.Effect<unknown, unknown, never>;
 
+/** Register the process-wide connection resolver (or clear with `undefined`).
+ *  Called by the CLI at boot; tests call it directly. */
+export declare const setConnectionResolver: (resolver: ConnectionResolver | undefined) => void;
+
 /** Register the field cipher (or clear with `undefined`). */
 export declare const setFieldCipher: (cipher: FieldCipher | undefined) => void;
 
+/**
+ * Register (or clear, with `undefined`) the process-global row filter. Call
+ * once at boot. Last write wins.
+ */
+export declare const setRowFilter: <Ctx>(filter: RowFilter<Ctx> | undefined) => void;
+
 /** Install the process-wide secrets backend (called once at boot). */
 export declare const setSecretsBackend: (backend: SecretsBackend) => void;
 
@@ -3922,6 +4777,14 @@ export declare const setSystemStoreHandle: (handle: SystemStoreHandle) => void;
 /** Test seam — swap (or reset with `undefined`) the process recorder. */
 export declare const setTimelineRecorderForTest: (recorder: TimelineRecorder | undefined) => void;
 
+/**
+ * Register (or clear) the process-global tuple source. Last write wins.
+ *
+ * Registering a source is what ACTIVATES relationship guards. Until then they
+ * deny — see `installPolicyGuardResolver`.
+ */
+export declare const setTupleSource: (source: TupleSource | undefined) => void;
+
 export declare const sha256Hex: (input: string) => string;
 
 export declare type ShapeClassification = {
@@ -3978,10 +4841,10 @@ export declare interface SingleNodeOrchestratorOptions {
  * tables invalidates the entry via the invalidation bus.
  */
 export declare interface SnapshotCache {
-    readonly wrap: (binding: SnapshotCacheBinding, tags: ReadonlyArray<string>, compute: () => Promise<ReadonlyArray<Row_4>>) => Promise<ReadonlyArray<Row_4>>;
+    readonly wrap: (binding: SnapshotCacheBinding, tags: ReadonlyArray<string>, compute: () => Promise<ReadonlyArray<Row>>) => Promise<ReadonlyArray<Row>>;
     /** Write-through from the live recompute, so the cache is never staler
      *  than the freshest live subscriber. Fire-and-forget. */
-    readonly put: (binding: SnapshotCacheBinding, tags: ReadonlyArray<string>, rows: ReadonlyArray<Row_4>) => void;
+    readonly put: (binding: SnapshotCacheBinding, tags: ReadonlyArray<string>, rows: ReadonlyArray<Row>) => void;
 }
 
 /**
@@ -4037,6 +4900,26 @@ export declare interface StartupContext {
 /** The default export shape every `*.startup.ts` must provide. */
 export declare type StartupFn = (ctx: StartupContext) => void | Promise<void>;
 
+/**
+ * Write (or replace) the calling subject's credential, encrypted.
+ *
+ * `upsert` on the `(connectionId, subjectId)` unique keeps re-connecting a
+ * replace rather than an accumulation of stale rows — which matters because a
+ * second row would make "which token is current" a question the resolver would
+ * have to answer with a heuristic.
+ */
+export declare const storeCredential: (input: StoreCredentialInput) => Promise<Row>;
+
+export declare interface StoreCredentialInput {
+    readonly store: VaultStore;
+    readonly definition: ConnectionDefinition;
+    readonly subjectId: string;
+    readonly tenantId: string | null;
+    readonly tokens: ConnectionTokens;
+    readonly account?: ConnectionAccount;
+    readonly now?: () => Date;
+}
+
 /**
  * Discriminated union of all framework-owned store errors. Use it on
  * a mutation's `error:` schema when you want every kind surfaced
@@ -4054,6 +4937,14 @@ export declare interface StoreMiddlewareContext {
      * natively, or there are no array columns to translate).
      */
     readonly dialect?: DialectId;
+    /**
+     * Row-level security scope for THIS request's subject, resolved once by the
+     * context builder (`resolveRowFilterScope`). Omitted → no row filtering,
+     * which is right when the app registered none. A filter that failed to load
+     * arrives here as a deny-all scope, never as `undefined` — the difference
+     * between "nothing to filter" and "we could not tell" must not collapse.
+     */
+    readonly rowFilter?: RowFilterScope;
 }
 
 /**
@@ -4190,6 +5081,11 @@ export declare interface SubscriptionSnapshot {
     readonly subscriberCount: number;
 }
 
+/** Drop handshake grants past their TTL. Wired into the boot retention sweep;
+ *  a grant is worthless the moment it expires and keeping them turns a hot
+ *  table into an audit liability. */
+export declare const sweepExpiredGrants: (store: VaultStore, now?: Date) => Promise<number>;
+
 export { sweepRetention }
 
 /**
@@ -4289,8 +5185,8 @@ export declare interface TimelineEvent {
     readonly table: string;
     readonly op: 'insert' | 'update' | 'delete';
     /** Redacted row images. `old` present on update/delete; `new` on insert/update. */
-    readonly old: Row | null;
-    readonly new: Row | null;
+    readonly old: Row_2 | null;
+    readonly new: Row_2 | null;
     readonly tenantId: string | null;
 }
 
@@ -4334,7 +5230,7 @@ export declare class TimelineRecorder {
      * Read-only. Correct as long as the ring still holds the events after
      * `asOfSeq` (bounded by `capacity`).
      */
-    replay(table: string, asOfSeq: number, currentRows: ReadonlyArray<Row>): ReadonlyArray<Row>;
+    replay(table: string, asOfSeq: number, currentRows: ReadonlyArray<Row_2>): ReadonlyArray<Row_2>;
 }
 
 /** Time window. `to` defaults to now. */
@@ -4492,6 +5388,20 @@ export declare const triggerWorkflow: <EventPayload = unknown, WorkflowPayload =
  */
 export declare const tryClaimWakeup: (store: DataStore, ref: WakeupRef) => Promise<boolean>;
 
+/**
+ * Reads the relationship tuples for one (subject, resource).
+ *
+ * Registered once at boot. The default implementation reads
+ * `_voltro_rebac_tuples`; an app whose relationships live in its own tables
+ * (a `teamMembers` row, say) registers its own instead of copying data into a
+ * framework table.
+ */
+export declare type TupleSource = (req: {
+    readonly subjectId: string | null;
+    readonly resourceType: string;
+    readonly resourceId: string;
+}) => Promise<ReadonlyArray<RelationTuple>> | ReadonlyArray<RelationTuple>;
+
 /**
  * Remove the override for a connection. Called by the WS-close
  * finalizer (or explicit logout flows). Idempotent.
@@ -4616,6 +5526,8 @@ export declare const useAggregate: <Row>(def: AggregateDefinition<Row>) => Effec
  */
 export declare const useAnalytics: () => Effect.Effect<AnalyticsSinkImpl, never, AnalyticsSink>;
 
+declare type VaultStore = Pick<DataStore, 'query' | 'insert' | 'update' | 'updateMany' | 'delete' | 'upsert'>;
+
 /** The pure core of live revocation: given a subject + action + a row-set,
  *  return ONLY the rows the subject may still see. The reactive matcher calls
  *  this on a permission-changing write and diffs against the prior visible set;
@@ -4637,6 +5549,39 @@ export declare const VOLTRO_SOFT_DELETE_MIXIN_ID: "voltro/softDelete";
 
 export declare const VOLTRO_TENANT_MIXIN_ID: "voltro/tenant";
 
+/**
+ * `_voltro_connection_grants` — an IN-FLIGHT oauth2 handshake. Separate from
+ * the credential table on purpose: a handshake is a short-lived, single-use
+ * anti-CSRF token with a different lifecycle (seconds, deleted on use) from a
+ * credential (months, updated in place). Folding it into a `status:'pending'`
+ * row on the credential table would mean a failed handshake leaves a row that
+ * the resolver + the list projection both have to learn to ignore.
+ *
+ * `state` is what carries identity across the redirect: the browser comes back
+ * from the provider with no session guarantee, so the row — minted for a known
+ * subject before the redirect — is the only trustworthy statement of who the
+ * arriving code belongs to.
+ */
+export declare const _voltroConnectionGrantsTable: TableLike;
+
+/**
+ * `_voltro_connections` — ONE row per (connection, subject). The stored
+ * credential.
+ *
+ * `accessToken` / `refreshToken` hold CIPHERTEXT (`enc:v1:…`), never the raw
+ * token. They are plain `text()` rather than `.encrypted()` columns on purpose:
+ * `.encrypted()` decrypts inside the `ctx.store` mixin middleware, and the
+ * vault must be readable from the resolver path, the OAuth callback route, and
+ * the refresh worker — none of which hold a request-scoped `ctx.store`. Using
+ * `encryptField` / `decryptField` explicitly keeps ONE cipher and one key while
+ * letting every one of those paths read the column. (Same reason the api-key
+ * and session paths use the standalone helpers.)
+ *
+ * Reactive so `__voltro.connections.list` updates an open settings page the
+ * moment a callback lands, with no polling.
+ */
+export declare const _voltroConnectionsTable: TableLike;
+
 /** `_voltro_rebac_tuples` — the relationship tuples `can()` reads. One row =
  *  "`subjectId` has `relation` on `<resourceType>:<resourceId>`". Grant by
  *  inserting; revoke by deleting (a delete is the live-revocation trigger). */
@@ -4765,6 +5710,17 @@ export declare type WebhooksAppContext = unknown;
  *  builder. */
 export declare type WhereOp = '=' | '!=' | '<>' | '>' | '>=' | '<' | '<=' | 'in' | 'like' | 'contains' | 'fts';
 
+/**
+ * Resolve this request's row-filter scope. A no-op (same object back) when the
+ * app registered no filter, so an app that uses none pays nothing.
+ *
+ * Every runner calls this before building a context. A read path that skipped
+ * it would have no row-level security and would look exactly like one that
+ * does — which is why it lives in the shared spine rather than in each
+ * entrypoint.
+ */
+export declare const withRowFilter: <R extends ServeRequestContext>(request: R) => Promise<R>;
+
 export declare interface WorkflowCallerContext {
     readonly subject?: unknown;
     readonly traceId?: string | null;