@zackbart/connecta 0.24.1 → 0.24.3

package/CHANGELOG.md

@@ -2,6 +2,175 @@
 
 All notable changes to this package are documented here.
 
+## 0.24.3 — 2026-09-16
+
+A bug-fix release from a full audit of the execution path, invocation, catalog
+rendering, downstream OAuth, and the route table, plus the one MCP 2026-07-28
+requirement the previous inventory had missed. Two changes can be felt by a
+deployment: `/mcp` now validates the browser `Origin` header, so a browser MCP
+client hosted on an origin other than `publicUrl` or loopback needs
+`allowedOrigins`; and the overload and shutdown JSON-RPC error codes moved
+from `-32001`/`-32002` to `-31001`/`-31002`. Everything else is a fix a
+deployment can take without action. No storage format changed, but
+`fileStorage` now refuses a second process on the same state file, which a
+deployment sharing one file between two processes was never safe doing.
+
+### Added
+
+- **`allowedOrigins`.** `/mcp` and every `/mcp/<pool>` path refuse a
+  disallowed `Origin` with a fixed 403 before redirects, admission, auth, or
+  preflight, as the Streamable HTTP transport requires against DNS rebinding.
+  The default admits the `publicUrl` origin and HTTP(S) loopback at any port;
+  a list replaces the default; `"*"` keeps unrestricted CORS. Clients that
+  send no `Origin` are unaffected. Allowed preflight now returns 204 without
+  admission or auth and echoes valid requested `mcp-param-*` header names.
+- **Host-owned refresh recovery.** A valid token response is a consumed
+  refresh token. When the request that owned a refresh is cancelled,
+  redirected to authorization, or invalidated before the SDK saves the
+  response, the coordinator persists the rotation itself, holds contenders
+  behind the pending-mutation marker until that write lands, and hands them
+  the saved rotation. A retired refresh token is never redeemed twice, and two
+  deterministic waves of eight overlapping scopes pin one grant per wave
+  (#526).
+- Downstream JSON-RPC `-32602` refusals map to `invalid_args`, and 4xx
+  responses with a JSON message keep that message, bounded, without inferring
+  retryability from prose. 429 stays `rate_limited` and 408 becomes `timeout`.
+- `Retry-After` accepts the HTTP-date form as well as delta-seconds.
+- Personal connectors admit calls through their principal registry's own
+  budget instead of sharing one root budget; shutdown closes both, and
+  eviction never discards a live budget.
+- `records/mcp-2026-07-28.md` gains rows for Origin validation, deterministic
+  `tools/list` order, the bearer challenge, SEP-2243 parameter headers, and
+  trace propagation, and corrects the stale extensions row.
+- **Bounded `get_result` stash.** `results.maxStashBytes` (default 8 MiB)
+  and `results.maxStashEntries` (default 64) bound the paging stash per
+  runtime, with accounting that reserves capacity before concurrent writes
+  finish and reclaims expired entries before reuse. A refused stash keeps the
+  call successful with its preview and the paging-unavailable notice.
+- **Byte-range paging.** Stashed results are stored as a byte-addressable
+  envelope, so `get_result` decodes only the requested page instead of
+  re-encoding the whole result on every call. Entries stashed before the
+  upgrade still page until their TTL expires.
+- **Identity-partitioned results.** The stash partition derives from any
+  authenticated subject or principal, no longer only from providers that
+  declare `activityActorNamespace`. Open deployments share one partition.
+- **Sanitized `unavailable` detail.** Unreachable downstreams may carry
+  `details.host` (origin only) and `details.code` (a closed allowlist of
+  network errnos, or `timeout`) so an outage is distinguishable from a typo
+  without leaking a path, query, or credential. Activity stays payload-free.
+- **`fileStorage` writer lock.** A second instance or process opening the
+  same state file fails at construction naming the holder. The lock is
+  heartbeat-based, so a container restart that reuses a pid cannot wedge a
+  deployment, and each write uses a unique temp file. The returned store now
+  has `close()`.
+- **Logs survive every executor failure.** QuickJS streams console entries
+  to the parent, so a program that is cancelled, killed at the deadline,
+  crashed, or lost to an IPC failure still returns what it printed.
+
+### Changed
+
+- `/health` no longer names connectors: drift reports are keyed by a truncated
+  SHA-256 of the connector id and downstream admission is summed without ids.
+  `connecta doctor` keeps its stale-allowlist signal.
+- Overload and shutdown JSON-RPC codes are `-31001` and `-31002`, outside the
+  reserved range, per the specification's allocation policy.
+- `connecta.search` and `connecta.describe` spend the same host-call budget as
+  `connecta.call`; only `connecta.emit` is exempt (L4, M7).
+- One per-call deadline now covers catalog resolution, admission, and the
+  connector call, so a hung connector fails with a catchable `timeout` instead
+  of consuming the whole execution wall clock.
+- Compact describe caps each shape at 8,192 UTF-8 bytes and sets
+  `inputSchemaTruncated` / `outputSchemaTruncated`; use `format: "json"` for
+  the exact schema.
+- Top-level discovery measures the complete tool result, both copies and JSON
+  escaping, against the 256,000-byte ceiling.
+- Downstream `isError` text is bounded at 512 UTF-8 bytes, and error framing
+  fits the call's result cap in both result modes.
+- Open deployments warn whenever any connector is configured, since `api()`
+  headers can carry secrets without declaring credential hooks.
+
+### Fixed
+
+- **A long downstream error could leak the sandbox's per-run secret to guest
+  code and let a program forge a typed failure.** The QuickJS bridge sliced a
+  rejected host call at 4,000 characters, which clipped the authenticated
+  failure frame mid-JSON. Details are bounded before framing, the bridge
+  refuses an oversized frame whole, the prelude hides a malformed frame, and
+  the raw transport lives in a private closure so guest code cannot swap
+  `Error` or reach the bridge.
+- **A completed destructive call was reported as a retryable failure when the
+  `get_result` stash write failed.** The truncated preview is returned with a
+  paging-unavailable notice, activity records success, and
+  `result_processing_failed` is never retryable.
+- **The OAuth refresh gate wedged permanently** when a token fetch succeeded
+  but the SDK's save never ran, answering 503 to every later refresh in the
+  isolate until a forced reauthorization.
+- **Compact schema rendering went quartic on `allOf`-of-`$ref` schemas.** A
+  3.5 KB downstream schema took over four seconds of synchronous CPU, and the
+  describe path produced a 1.9 MB string from 1.8 KB. Rendering now spends a
+  shared 2,000-visit budget with memoized `$ref` expansion.
+- `call_tool` in MCP result mode returned `{"content":[]}` for a downstream
+  result carrying only `structuredContent`; a text block is now synthesized,
+  and a `null` structured value survives unwrapping.
+- In-program `connecta.search` returned `offset: null` and an empty page for a
+  non-numeric offset, and threw a raw `TypeError` for a non-string query; both
+  are `invalid_args`.
+- Caller-authored text in `get_result`, `authorize_connector`, `skills`, and
+  `search_tools` refusals is bounded; a `connector` over 512 bytes is
+  `invalid_args`. A failed stash read is a typed `unavailable`.
+- Legacy `mcp-session-id` DELETE now runs on credential rotation, generation
+  change, disconnect, and abandoned connects, not only on scope close.
+- Pool names outside `[a-z0-9_-]` fell through to a generic 404 without CORS
+  or authentication; every `/mcp/` suffix now reaches the identical pool 404
+  after auth.
+- The absent-grant warning set was unbounded and keyed by caller-derivable
+  text; it is capped at 1,024 entries.
+- `requiredInputKeys` could name keys the schema did not declare.
+- Validation error detail embedded whole enums; drift digests recursed without
+  a depth bound; refresh token responses were read without a byte ceiling;
+  credential revision races could loop without bound.
+- Containment matching for escaped failures ignores messages under eight
+  characters, and a QuickJS host-result reply that cannot be serialized settles
+  the call instead of hanging until the wall deadline.
+- Every `connecta.call` attempt spends one host call on entry, so unknown
+  addresses cannot loop for free; the escaped-failure list keeps the most
+  recent 64; an empty terminal error string is a failure, not a success.
+- The compact renderer renders `prefixItems` as a tuple, marks
+  `dependentSchemas` and `if`/`then`/`else` shapes conditional with the
+  truncation flag, and resolves `$dynamicRef` like `$ref`.
+- The guarded transport's no-body-stream path enforces the byte ceiling on
+  `text()` and `json()`.
+- The pool-name timing oracle is accepted and documented; `authorize_connector`
+  honoring tool-level grants is documented and pinned.
+
+## 0.24.2 — 2026-09-16
+
+`connectorAccess` can now grant individual tools, and a deployment can declare
+named pools served at `/mcp/<pool>`. Nothing changes for a deployment that
+returns `"all"` or connector ids and declares no pools.
+
+### Added
+
+- **Named tool pools at `/mcp/<pool>`.** `ConnectaConfig.pools` declares a
+  slice of connector ids and exact `connector.tool` addresses plus a `grant`
+  predicate over the authenticated identity, denied by default. The endpoint
+  serves the pool intersected with the identity's `connectorAccess`, so it can
+  only narrow. An undeclared name, a refusing grant, and a throwing grant are
+  one identical 404. Misdeclared pools refuse to boot. Clerk's 401 challenge
+  and protected-resource metadata follow the pool path so OAuth discovery
+  matches the URL the client used. Ethos records the decision.
+
+- **Tool-level grants in `identity.connectorAccess`.** Entries may be a
+  connector id (every tool) or an exact `connector.tool` address (that tool
+  only); grants are additive. The scoped registry view filters below the
+  catalog service, so `search_tools`, `describe_tools`, `call_tool`,
+  `call_destructive_tool`, a program's `connecta.search` and `connecta.call`,
+  and the connection UI all see the same list, and an ungranted tool fails as
+  `unknown_tool` exactly like an absent one. There is no wildcard: a remote
+  catalog that drifts cannot widen a grant. An address the catalog lacks is
+  unreachable and warned once per isolate. An unparseable entry refuses the
+  request with 403 rather than failing open.
+
 ## 0.24.1 — 2026-09-08
 
 ### Added

package/dist/auth/bearer.js

@@ -39,6 +39,8 @@ export function bearerToken(secret, options = {}) {
                     status: 401,
                     headers: {
                         "Content-Type": "application/json",
+                        // A configured secret has no OAuth metadata or issuer to
+                        // advertise; interactive adapters own resource discovery.
                         "WWW-Authenticate": "Bearer",
                     },
                 }),

package/dist/auth/clerk.d.ts

@@ -27,10 +27,5 @@ export interface ClerkAuthOptions {
     /** Optional hosted Account Portal sign-up URL for operator pages. Absolute https only. */
     signUpUrl?: string;
 }
-/**
- * Clerk inbound auth.
- *
- * `allowedDomains` and `gate` decide who is admitted; both must pass.
- */
 export declare function clerkAuth(opts: ClerkAuthOptions): InboundAuth;
 export {};

package/dist/auth/clerk.js

@@ -207,6 +207,11 @@ function emailDomain(email) {
  *
  * `allowedDomains` and `gate` decide who is admitted; both must pass.
  */
+/** `"/<pool>"` for a pool endpoint path, null for `/mcp` and anything else. */
+function mcpPoolSuffix(pathname) {
+    const match = /^\/mcp(\/[a-z0-9_-]+)$/.exec(pathname);
+    return match ? match[1] : null;
+}
 export function clerkAuth(opts) {
     assertNoRetiredToolkitOptions("clerkAuth", opts);
     // Before the Clerk client, so a malformed key fails as a connecta
@@ -284,9 +289,13 @@ export function clerkAuth(opts) {
         pendingActivityLabels.set(userId, lookup);
         return lookup;
     };
-    const unauthorized = (baseUrl, tokenPresent) => {
+    const unauthorized = (baseUrl, tokenPresent, request) => {
         const error = tokenPresent ? `error="invalid_token", ` : "";
-        const meta = `${resolveBase(baseUrl)}/.well-known/oauth-protected-resource`;
+        // A pool endpoint is its own protected resource: the challenge names the
+        // metadata document whose `resource` matches the URL the client used, or
+        // RFC 9728 tells it to reject the mismatch.
+        const pool = mcpPoolSuffix(new URL(request.url).pathname);
+        const meta = `${resolveBase(baseUrl)}/.well-known/oauth-protected-resource${pool ? `/mcp${pool}` : ""}`;
         return new Response(JSON.stringify({ error: "unauthorized" }), {
             status: 401,
             headers: {
@@ -384,10 +393,14 @@ export function clerkAuth(opts) {
                 return new Response(null, { status: 204, headers: CORS_HEADERS });
             }
             const base = resolveBase(baseUrl);
+            const pool = pathname.startsWith("/.well-known/oauth-protected-resource/mcp/")
+                ? mcpPoolSuffix(pathname.slice("/.well-known/oauth-protected-resource".length))
+                : null;
             if (pathname === "/.well-known/oauth-protected-resource" ||
-                pathname === "/.well-known/oauth-protected-resource/mcp") {
+                pathname === "/.well-known/oauth-protected-resource/mcp" ||
+                pool) {
                 return Response.json({
-                    resource: `${base}/mcp`,
+                    resource: `${base}/mcp${pool ?? ""}`,
                     authorization_servers: [frontendApiUrl],
                     bearer_methods_supported: ["header"],
                     scopes_supported: scopes,
@@ -430,7 +443,7 @@ export function clerkAuth(opts) {
                         ` tokenShape=${tokenShape(request)}`);
                     return {
                         ok: false,
-                        response: unauthorized(baseUrl, tokenPresent),
+                        response: unauthorized(baseUrl, tokenPresent, request),
                     };
                 }
                 // Session JWTs carry `azp` (the origin they were minted for); pin it
@@ -444,7 +457,7 @@ export function clerkAuth(opts) {
                         console.warn(`[connecta] session token azp mismatch: azp=${azp} expected=${origin}`);
                         return {
                             ok: false,
-                            response: unauthorized(baseUrl, tokenPresent),
+                            response: unauthorized(baseUrl, tokenPresent, request),
                         };
                     }
                 }
@@ -452,10 +465,10 @@ export function clerkAuth(opts) {
             }
             catch (error) {
                 console.warn(`[connecta] clerk authenticateRequest threw: ${error instanceof Error ? error.message : String(error)} tokenShape=${tokenShape(request)}`);
-                return { ok: false, response: unauthorized(baseUrl, true) };
+                return { ok: false, response: unauthorized(baseUrl, true, request) };
             }
             if (!userId) {
-                return { ok: false, response: unauthorized(baseUrl, true) };
+                return { ok: false, response: unauthorized(baseUrl, true, request) };
             }
             if (!(await checkGate(userId))) {
                 return { ok: false, response: forbidden() };

package/dist/auth/downstream-oauth.d.ts

@@ -13,6 +13,16 @@ interface OAuthRefreshFlight {
     release: (outcome: OAuthRefreshFlightOutcome) => void;
     stopObservingOwnerAbort: () => void;
     mutationId: object;
+    writing: boolean;
+    /**
+     * Set once the token endpoint answered with valid tokens: the authorization
+     * server has consumed the rotating refresh token, so if the SDK's own
+     * saveTokens never arrives (owner cancelled, redirected, or invalidated),
+     * `fail` persists this copy itself rather than stranding the marker or
+     * letting a contender redeem the retired token.
+     */
+    acceptedTokens?: OAuthTokens;
+    persist?: (tokens: OAuthTokens) => Promise<void>;
 }
 /**
  * Share one rotating-token redemption within one connector runtime and OAuth
@@ -41,6 +51,8 @@ export declare class OAuthRefreshCoordinator {
     /** @internal Opaque basis for issuer-aware provider token reads. */
     successfulRefreshIdentity(generation: string): object | undefined;
     coordinatedFetch(provider: KvOAuthProvider, baseFetch: FetchLike, requestSignal?: AbortSignal): FetchLike;
+    /** Start storage only while this owner still holds its exact flight. */
+    beginMutation(generation: string, flight: OAuthRefreshFlight): boolean;
     /** Publish one exact owner's successful save without disturbing a newer try. */
     succeedMutation(generation: string, flight: OAuthRefreshFlight): void;
     /** Give joined callers a fetch/flow failure, without rejecting the gate. */
@@ -92,7 +104,6 @@ export declare class KvOAuthProvider implements OAuthClientProvider {
     flowGeneration(): Promise<string>;
     /** @internal Record the refresh attempt this provider owns. */
     captureRefreshFlight(generation: string, flight: OAuthRefreshFlight): void;
-    private succeedRefreshFlight;
     private failRefreshFlight;
     /** True when another request saved a refresh result after this flow's read. */
     refreshBasisChanged(current: OAuthTokens, generation: string): boolean;

package/dist/auth/downstream-oauth.js

@@ -63,18 +63,66 @@ function sdkAcceptsOAuthTokens(value) {
     }
     return true;
 }
-async function refreshResponseFailure(response) {
+const MAX_REFRESH_RESPONSE_BYTES = 65_536;
+class OversizedRefreshResponse extends Error {
+    constructor() {
+        super(`OAuth refresh response exceeded ${MAX_REFRESH_RESPONSE_BYTES} bytes.`);
+    }
+}
+async function readRefreshResponse(response) {
+    if (Number(response.headers.get("content-length")) > MAX_REFRESH_RESPONSE_BYTES) {
+        void response.body?.cancel().catch(() => { });
+        throw new OversizedRefreshResponse();
+    }
+    const reader = response.clone().body?.getReader();
+    if (!reader)
+        return undefined;
+    const decoder = new TextDecoder();
+    let size = 0;
+    let text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_REFRESH_RESPONSE_BYTES) {
+                // A cloned body's cancellation can await its sibling. Cancel both,
+                // without making the refusal wait for the provider to finish sending.
+                void reader.cancel().catch(() => { });
+                void response.body?.cancel().catch(() => { });
+                throw new OversizedRefreshResponse();
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+        return JSON.parse(text + decoder.decode());
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * Classify the token endpoint's answer once, on a clone, and keep the parsed
+ * tokens: a valid response has already consumed the rotating refresh token, so
+ * the host persists it (`coordinatedFetch`) rather than trusting the SDK's
+ * later `saveTokens` to arrive on a request that may already be cancelled.
+ */
+async function refreshResponseOutcome(response) {
     if (!response.ok) {
-        return new Error(`OAuth refresh failed with HTTP ${response.status}.`);
+        return { failure: new Error(`OAuth refresh failed with HTTP ${response.status}.`) };
     }
+    let parsed;
     try {
-        return sdkAcceptsOAuthTokens(await response.clone().json())
-            ? undefined
-            : new Error("OAuth refresh response did not match the token schema.");
+        parsed = await readRefreshResponse(response);
     }
-    catch {
-        return new Error("OAuth refresh response did not contain JSON tokens.");
+    catch (error) {
+        if (error instanceof OversizedRefreshResponse)
+            throw error;
+        return { failure: new Error("OAuth refresh response did not contain JSON tokens.") };
     }
+    return sdkAcceptsOAuthTokens(parsed)
+        ? { tokens: parsed }
+        : { failure: new Error("OAuth refresh response did not match the token schema.") };
 }
 function refreshMutationPendingResponse() {
     return Response.json({
@@ -189,7 +237,9 @@ export class OAuthRefreshCoordinator {
             const requestedRefreshToken = init?.body instanceof URLSearchParams
                 ? init.body.get("refresh_token")
                 : new URLSearchParams(String(init?.body ?? "")).get("refresh_token");
-            while (true) {
+            for (let attempt = 0; attempt < 64; attempt++) {
+                if (requestSignal?.aborted)
+                    throw aborted(requestSignal);
                 const revisionBeforeReads = this.stateRevision;
                 const activeGeneration = await provider.generation();
                 this.observeAuthoritativeGeneration(activeGeneration);
@@ -258,6 +308,8 @@ export class OAuthRefreshCoordinator {
                     release: (outcome) => release(outcome),
                     stopObservingOwnerAbort: () => { },
                     mutationId: {},
+                    writing: false,
+                    persist: (tokens) => provider.saveTokens(tokens),
                 };
                 this.flights.set(generation, flight);
                 this.advanceStateRevision();
@@ -280,18 +332,35 @@ export class OAuthRefreshCoordinator {
                 }
                 try {
                     const response = await baseFetch(input, requestSignal ? { ...init, signal: requestSignal } : init);
-                    // These responses never reach a successful saveTokens callback. Give
+                    // Failed responses never reach a successful saveTokens callback. Give
                     // current waiters a bounded failure now while leaving the owner's
                     // response untouched for the SDK to parse and classify itself.
-                    const failure = await refreshResponseFailure(response);
-                    if (failure) {
-                        this.fail(generation, flight, failure);
+                    const outcome = await refreshResponseOutcome(response);
+                    if (outcome.failure) {
+                        this.fail(generation, flight, outcome.failure);
+                        return response;
                     }
-                    else if (requestSignal?.aborted ||
-                        !this.markMutationPending(generation, flight)) {
-                        throw requestSignal?.aborted
-                            ? aborted(requestSignal)
-                            : new Error("OAuth refresh ended before tokens could be saved.");
+                    // A valid response means the authorization server has consumed the
+                    // rotating refresh token. The SDK's saveTokens normally persists it;
+                    // keep this copy so `fail` can persist it instead if that callback
+                    // never comes (the SDK merges the old refresh token the same way).
+                    const rotatedRefreshToken = outcome.tokens.refresh_token ?? currentTokens?.refresh_token;
+                    flight.acceptedTokens = {
+                        ...outcome.tokens,
+                        ...(rotatedRefreshToken !== undefined
+                            ? { refresh_token: rotatedRefreshToken }
+                            : {}),
+                    };
+                    if (!this.markMutationPending(generation, flight)) {
+                        // Already settled (the owner was cancelled first). Still write the
+                        // rotation: losing it would leave a dead credential.
+                        void flight.persist?.(flight.acceptedTokens).catch(() => { });
+                        throw new Error("OAuth refresh ended before tokens could be saved.");
+                    }
+                    if (requestSignal?.aborted) {
+                        // Same recovery as an abort landing later: `fail` persists.
+                        this.fail(generation, flight, aborted(requestSignal));
+                        throw aborted(requestSignal);
                     }
                     return response;
                 }
@@ -300,8 +369,16 @@ export class OAuthRefreshCoordinator {
                     throw error;
                 }
             }
+            return refreshMutationPendingResponse();
         };
     }
+    /** Start storage only while this owner still holds its exact flight. */
+    beginMutation(generation, flight) {
+        if (this.flights.get(generation) !== flight)
+            return false;
+        flight.writing = true;
+        return true;
+    }
     /** Publish one exact owner's successful save without disturbing a newer try. */
     succeedMutation(generation, flight) {
         if (this.finishMutation(generation, flight)) {
@@ -312,6 +389,37 @@ export class OAuthRefreshCoordinator {
     }
     /** Give joined callers a fetch/flow failure, without rejecting the gate. */
     fail(generation, flight, error) {
+        // Only saveTokens owns a live credential write. If it has started, its
+        // success/failure callback clears the marker even after owner cancellation.
+        if (flight.writing) {
+            this.settle(generation, flight, { status: "failed", error });
+            return;
+        }
+        // The token endpoint already answered with valid tokens but the SDK will
+        // not save them (the owner was cancelled, redirected, or invalidated).
+        // The old refresh token is spent, so the host persists the rotation
+        // itself and keeps contenders behind the marker until it lands. Joined
+        // callers then receive the saved rotation, never a retired token to
+        // redeem again. saveTokens' own bookkeeping settles the flight when the
+        // provider still holds it; otherwise settle here once the write ends.
+        const tokens = flight.acceptedTokens;
+        if (tokens !== undefined &&
+            flight.persist !== undefined &&
+            this.pendingMutations.get(generation) === flight.mutationId) {
+            flight.writing = true;
+            void flight.persist(tokens).then(() => {
+                if (this.finishMutation(generation, flight)) {
+                    this.settle(generation, flight, { status: "refreshed" });
+                }
+            }, (writeError) => {
+                if (this.finishMutation(generation, flight)) {
+                    this.settle(generation, flight, { status: "failed", error: writeError });
+                }
+            });
+            return;
+        }
+        // A response alone is not a write and must never strand the generation.
+        this.finishMutation(generation, flight);
         this.settle(generation, flight, { status: "failed", error });
     }
     /** Finish an exact failed credential write, then publish its failure. */
@@ -417,23 +525,11 @@ export class KvOAuthProvider {
     captureRefreshFlight(generation, flight) {
         this.refreshFlight = { generation, flight };
     }
-    succeedRefreshFlight() {
-        const owned = this.refreshFlight;
-        this.refreshFlight = undefined;
-        if (owned) {
-            this.refreshCoordinator?.succeedMutation(owned.generation, owned.flight);
-        }
-    }
-    failRefreshFlight(error, mutationFinished = false) {
+    failRefreshFlight(error) {
         const owned = this.refreshFlight;
         this.refreshFlight = undefined;
         if (owned) {
-            if (mutationFinished) {
-                this.refreshCoordinator?.failMutation(owned.generation, owned.flight, error);
-            }
-            else {
-                this.refreshCoordinator?.fail(owned.generation, owned.flight, error);
-            }
+            this.refreshCoordinator?.fail(owned.generation, owned.flight, error);
         }
     }
     /** True when another request saved a refresh result after this flow's read. */
@@ -650,14 +746,30 @@ export class KvOAuthProvider {
         return tokens;
     }
     async saveTokens(tokens, ctx) {
+        // A retired flight (the owner was cancelled or superseded after the
+        // token response) still writes: the authorization server has already
+        // consumed the old refresh token, so dropping the rotated one would leave a
+        // dead credential. writeValue itself refuses when the generation moved.
+        // Only the coordinator bookkeeping belongs to the exact live flight.
+        const owned = this.refreshFlight;
+        const coordinated = owned !== undefined &&
+            this.refreshCoordinator?.beginMutation(owned.generation, owned.flight) === true;
         try {
             await this.writeValue("oauth:tokens", tokens, (value) => JSON.stringify(value), ctx?.issuer);
-            this.succeedRefreshFlight();
+            if (coordinated)
+                this.refreshCoordinator?.succeedMutation(owned.generation, owned.flight);
         }
         catch (error) {
-            this.failRefreshFlight(error, true);
+            if (coordinated)
+                this.refreshCoordinator?.failMutation(owned.generation, owned.flight, error);
             throw error;
         }
+        finally {
+            // The write owns this identity even if an SDK failure callback has
+            // already detached the provider's flight while storage was pending.
+            if (this.refreshFlight === owned)
+                this.refreshFlight = undefined;
+        }
     }
     /**
      * OAuth `state`. The SDK calls this (when present) and appends the value to
@@ -701,9 +813,9 @@ export class KvOAuthProvider {
         return stored.value;
     }
     async redirectToAuthorization(authorizationUrl) {
-        if (!this.allowAuthorization)
-            throw new UnauthorizedError("Authorization required. Use authorize_connector or Connect to start consent.");
         try {
+            if (!this.allowAuthorization)
+                throw new UnauthorizedError("Authorization required. Use authorize_connector or Connect to start consent.");
             await this.writeValue("oauth:pending", authorizationUrl.toString(), (raw) => raw);
             this.failRefreshFlight(new Error("OAuth refresh required reauthorization before tokens were saved."));
         }

package/dist/call-admission.d.ts

@@ -36,6 +36,8 @@ export interface ConnectorCallAdmissionSnapshot {
         max: number;
     };
 }
+/** Sum gauges and counters without publishing connector or principal keys. */
+export declare function aggregateCallAdmissionSnapshots(snapshots: readonly ConnectorCallAdmissionSnapshot[]): ConnectorCallAdmissionSnapshot;
 /**
  * Per-runtime, per-connector call admission. State contains only bounded
  * partition keys, counters, timestamps, signals, and promise continuations;
@@ -64,6 +66,8 @@ export declare class ConnectorCallAdmissionController {
     acquire(input: Readonly<ConnectorCallAdmissionInput> & {
         signal?: AbortSignal;
     }): Promise<CallAdmissionPermit>;
+    /** A principal registry may be evicted only after calls and budgets drain. */
+    isIdle(): boolean;
     snapshot(): ConnectorCallAdmissionSnapshot;
     close(): void;
     private admit;

package/dist/call-admission.js

@@ -22,6 +22,27 @@ export class CallAdmissionError extends ConnectorCallError {
 export function isCallAdmissionError(error) {
     return error instanceof CallAdmissionError;
 }
+/** Sum gauges and counters without publishing connector or principal keys. */
+export function aggregateCallAdmissionSnapshots(snapshots) {
+    const aggregate = {
+        rules: 0, partitions: 0, active: 0, queued: 0, closed: snapshots.length > 0,
+        totals: { admitted: 0, queued: 0, rejected: 0, rateLimited: 0, cancelled: 0 },
+        queueWaitMs: { count: 0, total: 0, max: 0 },
+    };
+    for (const snapshot of snapshots) {
+        for (const key of ["rules", "partitions", "active", "queued"]) {
+            aggregate[key] += snapshot[key];
+        }
+        aggregate.closed &&= snapshot.closed;
+        for (const key of ["admitted", "queued", "rejected", "rateLimited", "cancelled"]) {
+            aggregate.totals[key] += snapshot.totals[key];
+        }
+        aggregate.queueWaitMs.count += snapshot.queueWaitMs.count;
+        aggregate.queueWaitMs.total += snapshot.queueWaitMs.total;
+        aggregate.queueWaitMs.max = Math.max(aggregate.queueWaitMs.max, snapshot.queueWaitMs.max);
+    }
+    return aggregate;
+}
 function positiveWhole(value, name) {
     if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
         throw new TypeError(`${name} must be a positive whole number.`);
@@ -194,6 +215,11 @@ export class ConnectorCallAdmissionController {
                 waiter.onAbort();
         });
     }
+    /** A principal registry may be evicted only after calls and budgets drain. */
+    isIdle() {
+        this.evictIdlePartitions(Date.now());
+        return this.partitions.size === 0;
+    }
     snapshot() {
         let active = 0;
         let queued = 0;

package/dist/catalog-drift.js

@@ -36,15 +36,20 @@ export function boundedCatalogDrift(report) {
 }
 const encoder = new TextEncoder();
 /** Deterministic JSON: object keys sorted, so key order is not a schema change. */
-function canonicalize(value) {
-    if (Array.isArray(value))
-        return value.map(canonicalize);
+function canonicalize(value, depth = 0) {
+    // Drift is advisory. Beyond this bound compare an explicit marker instead
+    // of letting a downstream schema exhaust the host stack.
+    if (depth > 64)
+        return "[schema depth truncated]";
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalize(item, depth + 1));
+    }
     if (value === null || typeof value !== "object")
         return value;
     const entries = Object.entries(value)
         .filter(([, item]) => item !== undefined)
         .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    return Object.fromEntries(entries.map(([key, item]) => [key, canonicalize(item)]));
+    return Object.fromEntries(entries.map(([key, item]) => [key, canonicalize(item, depth + 1)]));
 }
 /**
  * Digest the schemas of one downstream tool.