@voltro/runtime 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -4,6 +4,8 @@ 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';
@@ -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. */
@@ -765,6 +766,14 @@ export declare interface AppContext {
      * 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 (...)`.
@@ -811,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;
@@ -843,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`
@@ -936,6 +969,27 @@ export declare const awaitServerListening: (server: ReturnType<typeof createServ
 /** 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
@@ -974,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
@@ -1006,16 +1060,24 @@ cache?: {
  * revoked grant CLOSES the stream rather than continuing to serve it.
  * Omitted for a query that declares no guards.
  */
-reauthorize?: (subject: Subject) => () => Promise<unknown>) => Stream.Stream<SubscriptionEvent<T>, never, SubjectService | ConnectionInfo>;
+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, reauthorize: (() => Promise<unknown>) | 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;
@@ -1126,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 }
@@ -1199,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;
 
@@ -1212,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
@@ -1269,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;
 
@@ -1279,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
@@ -1337,10 +1534,10 @@ export declare interface DataLoader {
      * 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_4 | null>;
+    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_4 | null>>;
+    loadMany(table: string, ids: ReadonlyArray<string>): Promise<ReadonlyArray<Row | null>>;
 }
 
 export { DataStore }
@@ -1364,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.
@@ -1392,6 +1591,16 @@ 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>;
 
 /**
@@ -1493,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
@@ -1512,7 +1721,9 @@ export declare class Dispatcher {
     cacheBinding?: SnapshotCacheBinding, 
     /** Re-run the query's `guards:` before every delivery — see
      *  `ActiveSubscription.reauthorize`. Omitted for unguarded queries. */
-    reauthorize?: () => Promise<unknown>): Promise<() => void>;
+    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.
@@ -1574,11 +1785,13 @@ export declare interface DispatcherDependencies {
 }
 
 export declare interface DrainDeps {
-    readonly store: Pick<DataStore, 'query' | 'update'>;
+    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;
 }
 
 /**
@@ -1620,9 +1833,9 @@ export declare interface EffectStoreOps {
      *  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_4>(descriptor: QueryDescriptor<R>) => Effect.Effect<ReadonlyArray<R>, 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>;
+    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>;
@@ -1668,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). */
@@ -1709,6 +1929,32 @@ export declare interface FluentStore extends Omit<MutationStore, 'update' | 'del
      * 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({...})`. */
@@ -1739,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;
 
@@ -1776,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;
 
@@ -1784,14 +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. */
@@ -1891,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)
@@ -1900,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;
@@ -1912,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
@@ -2143,6 +2403,9 @@ 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 }
@@ -2275,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
@@ -2290,6 +2567,13 @@ export declare const makeCoordinatedScheduler: (deps: CoordinatedScheduleDeps) =
  */
 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
@@ -2320,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
@@ -2386,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
@@ -2617,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`
@@ -2711,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
@@ -2742,8 +3076,68 @@ 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.
@@ -2752,12 +3146,36 @@ export declare interface OutboxFacade {
      * 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'>;
+    readonly store: Pick<DataStore, 'insert' | 'query' | 'update'>;
     readonly subject: Subject;
     readonly traceId: string | null;
     /** Nudge the drain worker once the transaction commits. Optional: without
@@ -2800,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;
 
@@ -2827,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>>;
 
@@ -2903,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;
@@ -3071,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
@@ -3152,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
@@ -3315,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;
@@ -3329,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
@@ -3399,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:
@@ -3419,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.
@@ -3437,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
@@ -3483,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. */
@@ -3521,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 {
@@ -3537,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;
@@ -3731,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)
@@ -3781,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;
@@ -4085,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 {
@@ -4108,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. */
@@ -4118,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). */
@@ -4127,11 +4702,11 @@ 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>;
+    first(): Promise<Row | null>;
     /**
      * Terminal: EXACTLY one row. Fails with `NoRowFound` on zero matches —
      * and equally on two or more.
@@ -4143,7 +4718,7 @@ export declare class SelectBuilder {
      * wire buys a loud failure at the point the assumption breaks. Use
      * `.first()` / `.maybeOne()` when you genuinely want "any match".
      */
-    one(): Promise<Row_4>;
+    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. */
@@ -4156,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). */
@@ -4168,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;
 
@@ -4246,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;
 }
 
 /**
@@ -4305,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
@@ -4322,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;
 }
 
 /**
@@ -4458,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 }
 
 /**
@@ -4557,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;
 }
 
@@ -4602,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. */
@@ -4898,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;
@@ -4919,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). */
@@ -5047,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;