@zackbart/connecta 0.7.9 → 0.8.1

package/src/registry.ts

@@ -11,27 +11,46 @@ import {
   type CredentialVault,
 } from "./credentials.js";
 import { ConnectorCallError } from "./errors.js";
-import {
-  CredentialHealthChecker,
-  type CredentialCheckOptions,
-  type CredentialCheckResult,
-  type CredentialHealthConfig,
-  type CredentialHealthRecord,
-} from "./credential-health.js";
 import {
   ConnectorCallAdmissionController,
   type CallAdmissionPermit,
   type ConnectorCallAdmissionSnapshot,
 } from "./call-admission.js";
-import type { DeferredWork } from "./connector-scope.js";
-import { splitAddress, type Toolkit } from "./toolkits.js";
+import {
+  fingerprintSerializedCatalog,
+  snapshotCatalog,
+  type CatalogSnapshot,
+} from "./catalog-fingerprint.js";
+import {
+  MAX_CATALOG_CHUNK_BYTES,
+  MAX_CATALOG_TOOLS,
+  MAX_SERIALIZED_CATALOG_BYTES,
+} from "./catalog-limits.js";
+import { mapSettledWithConcurrency } from "./concurrency.js";
 
 const ID_RE = /^[a-z0-9_-]+$/;
 const DEFAULT_TTL_SECONDS = 300;
 const DEFAULT_STALE_SECONDS = 3600;
-export const DEFAULT_MAX_RESULT_BYTES = 50_000;
+const CATALOG_CHUNK_TTL_GRACE_SECONDS = 300;
+const DEFAULT_MAX_RESULT_BYTES = 50_000;
+const encoder = new TextEncoder();
 /** Independent final-envelope boundary for `batch_call`. */
-export const DEFAULT_MAX_BATCH_RESULT_BYTES = 100_000;
+const DEFAULT_MAX_BATCH_RESULT_BYTES = 100_000;
+
+/**
+ * Split `"<connectorId>.<toolName>"` on the first dot. Connector ids contain
+ * no dots, so a downstream tool name may.
+ */
+function splitAddress(
+  address: string,
+): { connectorId: string; toolName: string } | null {
+  const dot = address.indexOf(".");
+  if (dot <= 0 || dot === address.length - 1) return null;
+  return {
+    connectorId: address.slice(0, dot),
+    toolName: address.slice(dot + 1),
+  };
+}
 
 /**
  * Smallest accepted inline-result cap. One byte is pathological but harmless:
@@ -76,17 +95,41 @@ export function resolveMaxResultBytes(
 
 interface CacheEntry {
   tools: ToolDef[];
+  fingerprint: string;
   exp: number; // epoch ms
   staleUntil: number;
 }
 
+interface LegacyPersistedCatalog {
+  tools: ToolDef[];
+  /** Optional only for catalogs written before fingerprints were introduced. */
+  fingerprint?: string;
+  fetchedAt: number;
+  expiresAt: number;
+  staleUntil: number;
+}
+
+interface PersistedCatalogManifest {
+  version: 2;
+  revision: string;
+  toolCount: number;
+  byteCount: number;
+  chunkCount: number;
+  fetchedAt: number;
+  expiresAt: number;
+  staleUntil: number;
+}
+
 interface PersistedCatalog {
   tools: ToolDef[];
+  fingerprint: string;
   fetchedAt: number;
   expiresAt: number;
   staleUntil: number;
 }
 
+const CATALOG_CHUNK_IO_CONCURRENCY = 4;
+
 export interface HealthObservation {
   lastSuccessAt?: string;
   lastFailureAt?: string;
@@ -96,28 +139,21 @@ export interface HealthObservation {
 }
 
 /**
- * Recent real-call outcomes per connector, as observed by ONE view.
- *
- * The deployment keeps one log, and each toolkit keeps its own. That split is a
- * scope boundary, not bookkeeping: `lastError` is a downstream error string
- * that routinely names the tool that failed, and `list_connectors` returns the
- * observation verbatim. Sharing one log would let a toolkit read back the tools
- * and failures of a sibling toolkit through a connector they happen to share —
- * and let a sibling's failures flip this view's reported status. A scoped view
- * reads back only the calls it made itself.
+ * Recent real-call outcomes per connector.
  */
-export class HealthLog {
+class HealthLog {
   private readonly observations = new Map<string, HealthObservation>();
 
   recordSuccess(id: string, latencyMs: number): void {
     const previous = this.observations.get(id);
-    this.observations.set(id, {
+    const observation: HealthObservation = {
       ...previous,
       lastSuccessAt: new Date().toISOString(),
       lastLatencyMs: latencyMs,
       consecutiveFailures: 0,
-      lastError: undefined,
-    });
+    };
+    delete observation.lastError;
+    this.observations.set(id, observation);
   }
 
   recordFailure(id: string, latencyMs: number, error: unknown): void {
@@ -155,8 +191,6 @@ export interface RegistryOptions {
    * of bytes >= 1; anything else warns and falls back to 100_000.
    */
   maxBatchResultBytes?: number;
-  /** Tuning for the credential liveness checks (issue #24). */
-  credentialHealth?: CredentialHealthConfig;
 }
 
 function namespaced(storage: KVStorage, prefix: string): KVStorage {
@@ -171,7 +205,7 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
-type ConnectorOperationOptions = Pick<
+export type ConnectorOperationOptions = Pick<
   ConnectorContext,
   "signal" | "timeoutMs"
 >;
@@ -181,12 +215,9 @@ type ConnectorOperationOptions = Pick<
  * (`src/meta-tools.ts`) and the `execute_code` sandbox bridge (`src/execute.ts`)
  * is typed against THIS, never against the concrete `Registry`.
  *
- * That indirection is the toolkit boundary (issue #22): a scoped connection is
- * handed a `ScopedRegistry` instead of the registry, and every meta-tool
- * inherits the scope from one place. Reaching for a registry method that isn't
- * here is a compile error, and adding one here is a compile error until
- * `ScopedRegistry` filters it — so a new meta-tool cannot quietly step around
- * the boundary.
+ * The read-only seam remains useful even without scoped views: meta-tools can
+ * consume registry behavior without depending on the concrete implementation
+ * or its construction-only methods.
  */
 export interface RegistryView {
   /** Deployment-wide result-size cap threaded to the meta-tools. */
@@ -217,10 +248,7 @@ export interface RegistryView {
     requestScope?: object,
     callOptions?: ConnectorOperationOptions,
   ): ConnectorContext;
-  /**
-   * Acquire the connector's shared downstream-call permit. Scoped views
-   * delegate to the base registry so every toolkit contends on the same pool.
-   */
+  /** Acquire the connector's shared downstream-call permit. */
   admitCall(
     id: string,
     input: { toolName: string; args: unknown; signal?: AbortSignal },
@@ -230,15 +258,9 @@ export interface RegistryView {
   recordFailure(id: string, latencyMs: number, error: unknown): void;
   healthFor(id: string): HealthObservation | undefined;
   hasObservedSuccess(id: string): boolean;
-  /** When ANY view last saw a successful call to `id`, deployment-wide. */
   observedSuccessAt(id: string): string | undefined;
-  /** Last credential-liveness verdict for `id`. Cached; no downstream I/O. */
-  credentialHealthFor(id: string): Promise<CredentialHealthRecord | undefined>;
-  /** Store a liveness verdict a live status check just produced. */
-  recordCredentialHealth(
-    id: string,
-    record: CredentialHealthRecord,
-  ): Promise<void>;
+  /** Local declared-vs-stored credential mismatch, with no downstream I/O. */
+  credentialDriftFor(id: string): Promise<string | undefined>;
   statusFor(
     id: string,
     baseUrl: string,
@@ -265,6 +287,11 @@ export class Registry implements RegistryView {
   private readonly catalogGenerations = new Map<string, number>();
   /** Serialize persisted catalog set/delete operations within this isolate. */
   private readonly catalogMutations = new Map<string, Promise<void>>();
+  /** Same-request cold loads share one promise without retaining the request. */
+  private readonly requestCatalogLoads = new WeakMap<
+    object,
+    Map<string, Promise<ToolDef[]>>
+  >();
   /** Deployment-wide observations — every call, whatever view made it. */
   private readonly health = new HealthLog();
   private readonly ttlMs: number;
@@ -274,8 +301,6 @@ export class Registry implements RegistryView {
   readonly maxResultBytes: number;
   /** Final batch envelope cap threaded to the meta-tools. */
   readonly maxBatchResultBytes: number;
-  /** Proactive liveness checks over stored downstream credentials (issue #24). */
-  private readonly credentialHealth: CredentialHealthChecker;
 
   constructor(
     connectors: Connector[],
@@ -317,18 +342,6 @@ export class Registry implements RegistryView {
       opts.maxResultBytes,
       opts.maxBatchResultBytes,
     );
-    this.credentialHealth = new CredentialHealthChecker(
-      {
-        listConnectors: () => this.listConnectors(),
-        getConnector: (id) => this.getConnector(id),
-        contextFor: (id, baseUrl, requestScope) =>
-          this.contextFor(id, baseUrl, requestScope),
-        storage: opts.storage,
-        logger: opts.logger,
-        credentialVault: opts.credentialVault,
-      },
-      opts.credentialHealth,
-    );
   }
 
   /**
@@ -500,47 +513,304 @@ export class Registry implements RegistryView {
     return `catalog:${id}`;
   }
 
-  private validCatalog(raw: string | null): PersistedCatalog | null {
+  private catalogChunkKey(id: string, revision: string, index: number): string {
+    return `${this.catalogKey(id)}:chunk:${revision}:${index}`;
+  }
+
+  private validLegacyCatalog(value: unknown): LegacyPersistedCatalog | null {
+    if (!value || typeof value !== "object") return null;
+    const catalog = value as Partial<LegacyPersistedCatalog>;
+    if (
+      !Array.isArray(catalog.tools) ||
+      typeof catalog.fetchedAt !== "number" ||
+      typeof catalog.expiresAt !== "number" ||
+      typeof catalog.staleUntil !== "number" ||
+      (catalog.fingerprint !== undefined &&
+        typeof catalog.fingerprint !== "string") ||
+      !this.validCatalogTools(catalog.tools)
+    ) {
+      return null;
+    }
+    return catalog as LegacyPersistedCatalog;
+  }
+
+  private validCatalogTools(value: unknown[]): value is ToolDef[] {
+    return value.every(
+      (tool) =>
+        tool !== null &&
+        typeof tool === "object" &&
+        typeof (tool as ToolDef).name === "string",
+    );
+  }
+
+  private validCatalogManifest(
+    value: unknown,
+  ): PersistedCatalogManifest | null {
+    if (!value || typeof value !== "object") return null;
+    const manifest = value as Partial<PersistedCatalogManifest>;
+    const maxChunks =
+      Math.ceil(MAX_SERIALIZED_CATALOG_BYTES / MAX_CATALOG_CHUNK_BYTES) + 1;
+    if (
+      manifest.version !== 2 ||
+      typeof manifest.revision !== "string" ||
+      !/^sha256:[0-9]{1,8}:[0-9a-f]{64}$/.test(manifest.revision) ||
+      !Number.isInteger(manifest.toolCount) ||
+      manifest.toolCount! < 0 ||
+      manifest.toolCount! > MAX_CATALOG_TOOLS ||
+      !Number.isInteger(manifest.byteCount) ||
+      manifest.byteCount! < 2 ||
+      manifest.byteCount! > MAX_SERIALIZED_CATALOG_BYTES ||
+      !manifest.revision.startsWith(`sha256:${manifest.byteCount}:`) ||
+      !Number.isInteger(manifest.chunkCount) ||
+      manifest.chunkCount! < 1 ||
+      manifest.chunkCount! > maxChunks ||
+      typeof manifest.fetchedAt !== "number" ||
+      typeof manifest.expiresAt !== "number" ||
+      typeof manifest.staleUntil !== "number"
+    ) {
+      return null;
+    }
+    return manifest as PersistedCatalogManifest;
+  }
+
+  private parseCatalogManifest(
+    raw: string | null,
+  ): PersistedCatalogManifest | null {
+    if (!raw) return null;
+    try {
+      return this.validCatalogManifest(JSON.parse(raw));
+    } catch {
+      return null;
+    }
+  }
+
+  private splitCatalogChunks(snapshot: CatalogSnapshot): string[] {
+    const chunks: string[] = [];
+    const decoder = new TextDecoder("utf-8", {
+      fatal: true,
+      ignoreBOM: true,
+    });
+    let offset = 0;
+    while (offset < snapshot.serializedBytes.byteLength) {
+      let end = Math.min(
+        offset + MAX_CATALOG_CHUNK_BYTES,
+        snapshot.serializedBytes.byteLength,
+      );
+      // Move a boundary that landed inside a multibyte UTF-8 sequence back to
+      // the next character start. Every stored string then remains valid UTF-8.
+      while (
+        end < snapshot.serializedBytes.byteLength &&
+        ((snapshot.serializedBytes[end] ?? 0) & 0xc0) === 0x80
+      ) {
+        end--;
+      }
+      chunks.push(
+        decoder.decode(snapshot.serializedBytes.subarray(offset, end)),
+      );
+      offset = end;
+    }
+    return chunks;
+  }
+
+  private async readCatalog(
+    id: string,
+    raw: string | null,
+    now: number,
+  ): Promise<PersistedCatalog | null> {
     if (!raw) return null;
+    let parsed: unknown;
     try {
-      const value = JSON.parse(raw) as Partial<PersistedCatalog>;
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      (parsed as { version?: unknown }).version !== 2
+    ) {
+      const legacy = this.validLegacyCatalog(parsed);
+      if (!legacy || legacy.staleUntil <= now) return null;
+      const snapshot = await snapshotCatalog(legacy.tools);
+      if (
+        legacy.tools.length > MAX_CATALOG_TOOLS ||
+        snapshot.serializedBytes.byteLength > MAX_SERIALIZED_CATALOG_BYTES ||
+        (legacy.fingerprint !== undefined &&
+          legacy.fingerprint !== snapshot.fingerprint)
+      ) {
+        this.opts.logger.warn(
+          `[connecta] connector "${id}" legacy catalog is oversized or has a fingerprint mismatch; ignoring persisted catalog.`,
+        );
+        return null;
+      }
+      return {
+        tools: legacy.tools,
+        fingerprint: snapshot.fingerprint,
+        fetchedAt: legacy.fetchedAt,
+        expiresAt: legacy.expiresAt,
+        staleUntil: legacy.staleUntil,
+      };
+    }
+
+    const manifest = this.validCatalogManifest(parsed);
+    if (!manifest) {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog manifest is invalid; ignoring persisted catalog.`,
+      );
+      return null;
+    }
+    if (manifest.staleUntil <= now) return null;
+
+    const chunkReads = await mapSettledWithConcurrency(
+      Array.from({ length: manifest.chunkCount }, (_, index) => index),
+      CATALOG_CHUNK_IO_CONCURRENCY,
+      (index) =>
+        this.opts.storage.get(
+          this.catalogChunkKey(id, manifest.revision, index),
+        ),
+    );
+    const chunks: string[] = [];
+    let chunkBytes = 0;
+    for (const [index, result] of chunkReads.entries()) {
+      if (result.status === "rejected") throw result.reason;
+      const chunk = result.value;
+      if (chunk === null) {
+        this.opts.logger.warn(
+          `[connecta] connector "${id}" catalog chunk ${index + 1}/${manifest.chunkCount} is missing; ignoring persisted catalog.`,
+        );
+        return null;
+      }
+      const byteLength = encoder.encode(chunk).byteLength;
+      chunkBytes += byteLength;
       if (
-        !Array.isArray(value.tools) ||
-        typeof value.fetchedAt !== "number" ||
-        typeof value.expiresAt !== "number" ||
-        typeof value.staleUntil !== "number" ||
-        !value.tools.every(
-          (tool) =>
-            tool !== null &&
-            typeof tool === "object" &&
-            typeof (tool as ToolDef).name === "string",
-        )
+        byteLength > MAX_CATALOG_CHUNK_BYTES ||
+        chunkBytes > manifest.byteCount
       ) {
+        this.opts.logger.warn(
+          `[connecta] connector "${id}" catalog chunk bounds do not match its manifest; ignoring persisted catalog.`,
+        );
         return null;
       }
-      return value as PersistedCatalog;
+      chunks.push(chunk);
+    }
+
+    const serializedTools = chunks.join("");
+    const stored = await fingerprintSerializedCatalog(serializedTools);
+    if (
+      stored.byteLength !== manifest.byteCount ||
+      stored.fingerprint !== manifest.revision
+    ) {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog fingerprint mismatch; ignoring persisted catalog.`,
+      );
+      return null;
+    }
+
+    let tools: unknown;
+    try {
+      tools = JSON.parse(serializedTools);
     } catch {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog chunks are torn; ignoring persisted catalog.`,
+      );
       return null;
     }
+    if (!Array.isArray(tools) || !this.validCatalogTools(tools)) {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog chunks contain invalid tools; ignoring persisted catalog.`,
+      );
+      return null;
+    }
+    if (tools.length !== manifest.toolCount) {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog tool count does not match its manifest; ignoring persisted catalog.`,
+      );
+      return null;
+    }
+    return {
+      tools,
+      fingerprint: stored.fingerprint,
+      fetchedAt: manifest.fetchedAt,
+      expiresAt: manifest.expiresAt,
+      staleUntil: manifest.staleUntil,
+    };
   }
 
-  private async storeCatalog(id: string, tools: ToolDef[]): Promise<void> {
+  private async storeCatalog(
+    id: string,
+    snapshot: CatalogSnapshot,
+  ): Promise<void> {
     if (!this.persistToolCatalog) return;
     const fetchedAt = Date.now();
-    const catalog: PersistedCatalog = {
-      tools,
+    const expiresAt = fetchedAt + this.ttlMs;
+    const staleUntil = expiresAt + this.staleMs;
+    const ttlSeconds = Math.max(
+      60,
+      Math.ceil((this.ttlMs + this.staleMs) / 1000),
+    );
+    const chunks = this.splitCatalogChunks(snapshot);
+    const chunkWrites = await mapSettledWithConcurrency(
+      chunks,
+      CATALOG_CHUNK_IO_CONCURRENCY,
+      (chunk, index) =>
+        this.opts.storage.set(
+          this.catalogChunkKey(id, snapshot.fingerprint, index),
+          chunk,
+          { ttlSeconds: ttlSeconds + CATALOG_CHUNK_TTL_GRACE_SECONDS },
+        ),
+    );
+    for (const result of chunkWrites) {
+      if (result.status === "rejected") throw result.reason;
+    }
+    // The manifest is the only publication point. A failed/partial chunk write
+    // therefore leaves the previous manifest authoritative (or no catalog);
+    // unreachable chunks carry a bounded TTL and require no prefix scan.
+    const manifest: PersistedCatalogManifest = {
+      version: 2,
+      revision: snapshot.fingerprint,
+      toolCount: snapshot.tools.length,
+      byteCount: snapshot.serializedBytes.byteLength,
+      chunkCount: chunks.length,
       fetchedAt,
-      expiresAt: fetchedAt + this.ttlMs,
-      staleUntil: fetchedAt + this.ttlMs + this.staleMs,
+      expiresAt,
+      staleUntil,
     };
-    await this.opts.storage.set(this.catalogKey(id), JSON.stringify(catalog), {
-      ttlSeconds: Math.max(
-        60,
-        Math.ceil((this.ttlMs + this.staleMs) / 1000),
-      ),
+    await this.opts.storage.set(this.catalogKey(id), JSON.stringify(manifest), {
+      ttlSeconds,
     });
   }
 
+  private async deleteCatalog(id: string): Promise<void> {
+    let raw: string | null = null;
+    let readError: unknown;
+    try {
+      raw = await this.opts.storage.get(this.catalogKey(id));
+    } catch (err) {
+      readError = err;
+    }
+    const manifest = this.parseCatalogManifest(raw);
+    // The root is authoritative, so attempt its deletion even when the
+    // best-effort read needed for physical chunk cleanup failed.
+    await this.opts.storage.delete(this.catalogKey(id));
+    if (!manifest) {
+      if (readError) throw readError;
+      return;
+    }
+    let firstError: unknown;
+    for (let index = 0; index < manifest.chunkCount; index++) {
+      try {
+        await this.opts.storage.delete(
+          this.catalogChunkKey(id, manifest.revision, index),
+        );
+      } catch (err) {
+        firstError ??= err;
+      }
+    }
+    if (readError) throw readError;
+    if (firstError) throw firstError;
+  }
+
   private catalogGeneration(id: string): number {
     return this.catalogGenerations.get(id) ?? 0;
   }
@@ -580,25 +850,43 @@ export class Registry implements RegistryView {
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
+    if (connector.staticTools) return connector.staticTools;
     const generation = this.catalogGeneration(id);
-    const tools = connector.staticTools
-      ? connector.staticTools
-      : await connector.listTools(
-          this.contextFor(id, baseUrl, requestScope, callOptions),
-        );
+    const tools = await connector.listTools(
+      this.contextFor(id, baseUrl, requestScope, callOptions),
+    );
     // The caller that began this refresh may still use its result, but a
     // credential/OAuth change that landed while listTools was in flight means
     // the listing must not enter either shared cache layer.
     if (generation !== this.catalogGeneration(id)) return tools;
-    const now = Date.now();
+    if (tools.length > MAX_CATALOG_TOOLS) {
+      const message =
+        `Connector "${id}" returned ${tools.length} tools, over the ` +
+        `${MAX_CATALOG_TOOLS}-tool catalog ceiling; refusing the complete catalog.`;
+      this.opts.logger.warn(`[connecta] ${message}`);
+      throw new Error(message);
+    }
     const previous = this.cache.get(id);
+    const snapshot = await snapshotCatalog(tools);
+    if (generation !== this.catalogGeneration(id)) return tools;
+    if (snapshot.serializedBytes.byteLength > MAX_SERIALIZED_CATALOG_BYTES) {
+      const message =
+        `Connector "${id}" returned a ${snapshot.serializedBytes.byteLength}-byte ` +
+        `serialized catalog, over the ${MAX_SERIALIZED_CATALOG_BYTES}-byte ceiling; ` +
+        "refusing the complete catalog.";
+      this.opts.logger.warn(`[connecta] ${message}`);
+      throw new Error(message);
+    }
+    const now = Date.now();
     const catalogChanged =
-      !previous || JSON.stringify(previous.tools) !== JSON.stringify(tools);
+      !previous || previous.fingerprint !== snapshot.fingerprint;
     const shouldPersist =
-      !connector.staticTools &&
-      (catalogChanged || previous.exp <= now || this.invalidated.has(id));
+      catalogChanged ||
+      (previous !== undefined && previous.exp <= now) ||
+      this.invalidated.has(id);
     this.cache.set(id, {
       tools,
+      fingerprint: snapshot.fingerprint,
       exp: now + this.ttlMs,
       staleUntil: now + this.ttlMs + this.staleMs,
     });
@@ -607,7 +895,7 @@ export class Registry implements RegistryView {
       await this.enqueueCatalogMutation(id, async () => {
         if (generation !== this.catalogGeneration(id)) return;
         try {
-          await this.storeCatalog(id, tools);
+          await this.storeCatalog(id, snapshot);
         } catch (err) {
           this.opts.logger.warn(
             `[connecta] connector "${id}" catalog persistence failed: ${msg(err)}`,
@@ -619,7 +907,7 @@ export class Registry implements RegistryView {
   }
 
   /** Cached listTools with in-memory + persisted serializable catalog layers. */
-  async getTools(
+  private async loadTools(
     id: string,
     baseUrl: string,
     requestScope?: object,
@@ -639,8 +927,10 @@ export class Registry implements RegistryView {
       const generation = this.catalogGeneration(id);
       let persisted: PersistedCatalog | null = null;
       try {
-        persisted = this.validCatalog(
+        persisted = await this.readCatalog(
+          id,
           await this.opts.storage.get(this.catalogKey(id)),
+          now,
         );
       } catch (err) {
         this.opts.logger.warn(
@@ -654,6 +944,7 @@ export class Registry implements RegistryView {
       if (persisted && persisted.staleUntil > now) {
         this.cache.set(id, {
           tools: persisted.tools,
+          fingerprint: persisted.fingerprint,
           exp: persisted.expiresAt,
           staleUntil: persisted.staleUntil,
         });
@@ -679,6 +970,46 @@ export class Registry implements RegistryView {
     }
   }
 
+  /**
+   * Coalesce one connector's cold load inside one inbound request. The WeakMap
+   * neither roots the request scope nor lets its connector context escape into
+   * another request; settled entries are also removed eagerly.
+   *
+   * The first caller's `callOptions` govern the shared load: a later caller's
+   * signal or timeout neither cancels nor extends it, and an abort by the
+   * first caller rejects every coalesced caller. Within one request that is
+   * the deal being made — one fetch, one deadline.
+   */
+  async getTools(
+    id: string,
+    baseUrl: string,
+    requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
+  ): Promise<ToolDef[]> {
+    const connector = this.connectors.get(id);
+    if (!connector) throw new Error(`Unknown connector "${id}"`);
+    if (connector.staticTools) return connector.staticTools;
+    if (!requestScope) {
+      return this.loadTools(id, baseUrl, requestScope, callOptions);
+    }
+
+    let loads = this.requestCatalogLoads.get(requestScope);
+    if (!loads) {
+      loads = new Map();
+      this.requestCatalogLoads.set(requestScope, loads);
+    }
+    const existing = loads.get(id);
+    if (existing) return existing;
+    const loading = this.loadTools(id, baseUrl, requestScope, callOptions);
+    loads.set(id, loading);
+    try {
+      return await loading;
+    } finally {
+      if (loads.get(id) === loading) loads.delete(id);
+      if (loads.size === 0) this.requestCatalogLoads.delete(requestScope);
+    }
+  }
+
   /** Return a cached catalog without performing storage or network I/O. */
   peekTools(id: string): ToolDef[] | undefined {
     const connector = this.connectors.get(id);
@@ -699,83 +1030,30 @@ export class Registry implements RegistryView {
     return this.health.get(id);
   }
 
-  /**
-   * Whether ANY view of this deployment has seen a successful call to `id` —
-   * a bare boolean, never the observation. Connector liveness (reachable,
-   * credentials still valid) is a deployment-level fact, not a per-view one, so
-   * `list_connectors` may classify a connector as ok/unknown from it. The
-   * observation itself — `lastError` above all, which names the tool that
-   * failed — stays strictly per view.
-   */
+  /** Whether this deployment has seen a successful call to `id`. */
   hasObservedSuccess(id: string): boolean {
     return this.observedSuccessAt(id) !== undefined;
   }
 
-  /**
-   * The timestamp behind `hasObservedSuccess`, on the same deployment-wide
-   * terms and for the same reason: it says only *when* the connector last
-   * answered, never what was called or what failed. Credential health reads it
-   * to decide whether a failed verdict has been overtaken by real traffic.
-   */
+  /** The timestamp behind `hasObservedSuccess`. */
   observedSuccessAt(id: string): string | undefined {
     return this.health.get(id)?.lastSuccessAt;
   }
 
-  /**
-   * The last credential-liveness verdict for `id` — the layer that lets a cached
-   * status read report `auth_required` before a real call discovers it. Read
-   * from storage (mirrored in memory for a few seconds) rather than held in
-   * memory alone, because on Workers the isolate that ran the check is usually
-   * not the isolate answering this read.
-   */
-  credentialHealthFor(id: string): Promise<CredentialHealthRecord | undefined> {
-    return this.credentialHealth.healthFor(id);
-  }
-
-  recordCredentialHealth(
-    id: string,
-    record: CredentialHealthRecord,
-  ): Promise<void> {
-    return this.credentialHealth.record(id, record);
-  }
-
-  /**
-   * Check stored downstream credentials now and return one outcome per
-   * connector considered. THE operator-facing entry point behind
-   * `Connecta.checkCredentials()`: wire it to a Worker cron trigger or a Node
-   * interval. Never rejects; connectors checked recently are reported as
-   * `fresh` unless `force` is set.
-   */
-  checkCredentialHealth(
-    baseUrl: string,
-    opts?: CredentialCheckOptions,
-    defer?: DeferredWork,
-  ): Promise<CredentialCheckResult[]> {
-    return this.credentialHealth.check(baseUrl, opts, defer);
-  }
-
-  /**
-   * The traffic-triggered sweep: a promise for the caller to defer (Workers:
-   * `ctx.waitUntil`), or `undefined` when nothing is due — which is the common
-   * case and costs no I/O. Called by the server after an authenticated request;
-   * the checker owns the rate limiting.
-   */
-  sweepCredentialHealthIfDue(
-    baseUrl: string,
-    defer?: DeferredWork,
-  ): Promise<CredentialCheckResult[]> | undefined {
-    return this.credentialHealth.sweepIfDue(baseUrl, defer);
-  }
-
-  /**
-   * Drop a connector's liveness verdict, because its credential just changed
-   * under us (OAuth callback completed, credential stored or removed on
-   * /credentials). A
-   * stale `auth_required` must not outlive the re-authorization that fixed it —
-   * that is the difference between recovery working and needing a restart.
-   */
-  clearCredentialHealth(id: string): Promise<void> {
-    return this.credentialHealth.clear(id);
+  async credentialDriftFor(id: string): Promise<string | undefined> {
+    const credential = this.connectors.get(id)?.credential;
+    const vault = this.opts.credentialVault;
+    if (!credential || !vault) return undefined;
+    try {
+      const values = await vault.getAll(id);
+      const shape = storedCredentialShape(credential, values);
+      return shape.state === "mismatch" ? shape.message : undefined;
+    } catch (error) {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" credential shape read failed: ${msg(error)}`,
+      );
+      return undefined;
+    }
   }
 
   /** Best-effort connector status for list_connectors. */
@@ -803,291 +1081,33 @@ export class Registry implements RegistryView {
     }
   }
 
-  /** Drop a connector's cached tool list (e.g. after auth completes). */
-  invalidate(id: string): void {
+  private markCatalogInvalid(id: string): void {
     this.advanceCatalogGeneration(id);
     this.cache.delete(id);
     this.invalidated.add(id);
-    if (this.persistToolCatalog) {
-      void this.enqueueCatalogMutation(id, async () => {
-        try {
-          await this.opts.storage.delete(this.catalogKey(id));
-        } catch (err) {
-          this.opts.logger.warn(
-            `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
-          );
-        }
-      });
-    }
-  }
-
-  /** Drop both in-memory and persisted tool catalogs. */
-  async invalidateStored(id: string): Promise<void> {
-    this.advanceCatalogGeneration(id);
-    this.cache.delete(id);
-    this.invalidated.add(id);
-    if (this.persistToolCatalog) {
-      await this.enqueueCatalogMutation(id, async () => {
-        try {
-          await this.opts.storage.delete(this.catalogKey(id));
-        } catch (err) {
-          this.opts.logger.warn(
-            `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
-          );
-        }
-      });
-    }
   }
-}
 
-/**
- * Per-toolkit HealthLogs, keyed by registry and then by toolkit name.
- *
- * Module-scoped rather than a `Registry` member on purpose: `Registry`'s type
- * is part of the public API surface (`Connecta.registry`), and this is internal
- * factoring only `ScopedRegistry` may touch. The WeakMap keeps the logs alive
- * exactly as long as their registry, and the inner map is bounded by the
- * number of configured toolkits.
- */
-const toolkitHealthLogs = new WeakMap<Registry, Map<string, HealthLog>>();
-
-/** The long-lived log one toolkit records into; created on first use. */
-function toolkitHealthLog(base: Registry, toolkitName: string): HealthLog {
-  let logs = toolkitHealthLogs.get(base);
-  if (!logs) {
-    logs = new Map<string, HealthLog>();
-    toolkitHealthLogs.set(base, logs);
-  }
-  let log = logs.get(toolkitName);
-  if (!log) {
-    log = new HealthLog();
-    logs.set(toolkitName, log);
-  }
-  return log;
-}
-
-/**
- * THE toolkit enforcement point (issue #22).
- *
- * A filtered VIEW of one long-lived `Registry`: same connectors, same tool
- * caches, same health — narrowed to the connectors and tool addresses one
- * toolkit selects. `serveMcp` builds it once per scoped connection and hands it
- * to `registerMetaTools`/`registerExecuteTool`, so `list_connectors`,
- * `search_tools`, `describe_tools`, `call_tool`, `call_destructive_tool`,
- * `batch_call`, `authorize_connector`, `get_result`, `skills`, and the
- * `execute_code` host bridge all inherit the boundary from here instead of
- * re-implementing nine checks.
- *
- * Two invariants make it reviewable:
- *
- * 1. **Indistinguishability.** Out-of-scope input fails through the SAME code
- *    path, with the same error class and message, as input naming something
- *    that does not exist at all. An out-of-scope CONNECTOR disappears from
- *    `resolveAddress`/`getConnector` (→ `Unknown address` / `Unknown
- *    connector`); an out-of-scope TOOL disappears from the catalog this view
- *    returns (→ `Unknown tool "<t>" on connector "<c>"`), which is exactly the
- *    error a misspelled tool name already produced. Scoping deliberately does
- *    NOT reject at `resolveAddress` for tools: that would answer with the
- *    connector-level message and make "hidden here" distinguishable from
- *    "never existed".
- * 2. **It filters views, never state.** Every read delegates to the shared
- *    registry and filters the returned array, so the tool cache, the persisted
- *    catalog, and the health map stay whole and shared across scopes.
- */
-export class ScopedRegistry implements RegistryView {
-  /** This toolkit's own health observations — see HealthLog. */
-  private readonly health: HealthLog;
-
-  constructor(
-    private readonly base: Registry,
-    private readonly toolkit: Toolkit,
-  ) {
-    this.health = toolkitHealthLog(base, toolkit.name);
-  }
-
-  get maxResultBytes(): number {
-    return this.base.maxResultBytes;
-  }
-
-  get maxBatchResultBytes(): number {
-    return this.base.maxBatchResultBytes;
-  }
-
-  /** In scope AND actually registered. */
-  private visible(id: string): boolean {
-    return (
-      this.toolkit.hasConnector(id) && this.base.getConnector(id) !== undefined
-    );
-  }
-
-  /** Byte-identical to what the unscoped registry throws for an unknown id. */
-  private unknownConnector(id: string): Error {
-    return new Error(`Unknown connector "${id}"`);
-  }
-
-  private inScopeTools(id: string, tools: ToolDef[]): ToolDef[] {
-    return tools.filter((tool) => this.toolkit.hasTool(id, tool.name));
-  }
-
-  listConnectors(): Connector[] {
-    return this.base
-      .listConnectors()
-      .filter((connector) => this.toolkit.hasConnector(connector.id));
-  }
-
-  getConnector(id: string): Connector | undefined {
-    return this.visible(id) ? this.base.getConnector(id) : undefined;
-  }
-
-  resolveAddress(
-    address: string,
-  ): { connector: Connector; toolName: string } | null {
-    const resolved = this.base.resolveAddress(address);
-    if (!resolved) return null;
-    // Connector-level only — see invariant 1 above.
-    return this.toolkit.hasConnector(resolved.connector.id) ? resolved : null;
-  }
-
-  async getTools(
-    id: string,
-    baseUrl: string,
-    requestScope?: object,
-    callOptions: ConnectorOperationOptions = {},
-  ): Promise<ToolDef[]> {
-    if (!this.visible(id)) throw this.unknownConnector(id);
-    return this.inScopeTools(
-      id,
-      await this.base.getTools(id, baseUrl, requestScope, callOptions),
-    );
-  }
-
-  async refreshTools(
-    id: string,
-    baseUrl: string,
-    requestScope?: object,
-    callOptions: ConnectorOperationOptions = {},
-  ): Promise<ToolDef[]> {
-    if (!this.visible(id)) throw this.unknownConnector(id);
-    return this.inScopeTools(
-      id,
-      await this.base.refreshTools(id, baseUrl, requestScope, callOptions),
-    );
-  }
-
-  peekTools(id: string): ToolDef[] | undefined {
-    if (!this.visible(id)) return undefined;
-    const tools = this.base.peekTools(id);
-    return tools ? this.inScopeTools(id, tools) : undefined;
-  }
-
-  contextFor(
-    id: string,
-    baseUrl: string,
-    requestScope: object = {},
-    callOptions: ConnectorOperationOptions = {},
-  ): ConnectorContext {
-    // Unreachable through the meta-tools (they resolve first), so a throw here
-    // is a loud backstop rather than a silent grant of connector storage and
-    // credentials to a scope that may not see the connector.
-    if (!this.visible(id)) throw this.unknownConnector(id);
-    return this.base.contextFor(id, baseUrl, requestScope, callOptions);
-  }
-
-  admitCall(
-    id: string,
-    input: { toolName: string; args: unknown; signal?: AbortSignal },
-  ): Promise<CallAdmissionPermit> {
-    if (!this.visible(id)) return Promise.reject(this.unknownConnector(id));
-    return this.base.admitCall(id, input);
-  }
-
-  /**
-   * Stashed oversized results are bound to the scope that produced them: a
-   * scoped session cannot page a result it could not have produced, and an id
-   * from another scope reads back as the ordinary "Unknown or expired result
-   * id". Unscoped sessions keep the historical `results:` prefix untouched.
-   */
-  resultsStorage(): KVStorage {
-    return namespaced(
-      this.base.resultsStorage(),
-      `toolkit:${this.toolkit.name}:`,
-    );
-  }
-
-  // Outcomes are recorded twice on purpose: the deployment-wide log keeps the
-  // operator surfaces complete, while the toolkit's own log is the ONLY one
-  // this view reads back — so `list_connectors` here never reports a sibling
-  // toolkit's failures, or the tool names their error strings carry.
-  recordSuccess(id: string, latencyMs: number): void {
-    if (!this.visible(id)) return;
-    this.base.recordSuccess(id, latencyMs);
-    this.health.recordSuccess(id, latencyMs);
-  }
-
-  recordFailure(id: string, latencyMs: number, error: unknown): void {
-    if (!this.visible(id)) return;
-    this.base.recordFailure(id, latencyMs, error);
-    this.health.recordFailure(id, latencyMs, error);
-  }
-
-  healthFor(id: string): HealthObservation | undefined {
-    return this.visible(id) ? this.health.get(id) : undefined;
-  }
-
-  /**
-   * Deliberately NOT per view: whether the connector has ever answered is a
-   * fact about the connector, not about a team's traffic, and withholding it
-   * would report every remote connector as "unknown" to a scoped session that
-   * has not called it yet. It carries no tool name, error text, or count — the
-   * per-view isolation of those, above, is unchanged.
-   */
-  hasObservedSuccess(id: string): boolean {
-    return this.visible(id) ? this.base.hasObservedSuccess(id) : false;
-  }
-
-  /** Deployment-wide for the same reason as `hasObservedSuccess` above. */
-  observedSuccessAt(id: string): string | undefined {
-    return this.visible(id) ? this.base.observedSuccessAt(id) : undefined;
-  }
-
-  /**
-   * Also deliberately NOT per view, for the same reason as
-   * `hasObservedSuccess`: whether the credential connecta stores for a connector
-   * still works is a fact about the deployment's credential, not about a team's
-   * traffic. Withholding it would leave a scoped session unable to see that the
-   * connector it shares needs re-authorization. The verdict carries the
-   * connector's own connector-level reason — never a tool name — so the per-view
-   * isolation of `lastError` above is unchanged.
-   */
-  credentialHealthFor(id: string): Promise<CredentialHealthRecord | undefined> {
-    return this.visible(id)
-      ? this.base.credentialHealthFor(id)
-      : Promise.resolve(undefined);
-  }
-
-  async recordCredentialHealth(
-    id: string,
-    record: CredentialHealthRecord,
-  ): Promise<void> {
-    if (!this.visible(id)) return;
-    await this.base.recordCredentialHealth(id, record);
+  private deleteStoredCatalog(id: string): Promise<void> {
+    return this.enqueueCatalogMutation(id, async () => {
+      try {
+        await this.deleteCatalog(id);
+      } catch (err) {
+        this.opts.logger.warn(
+          `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
+        );
+      }
+    });
   }
 
-  async statusFor(
-    id: string,
-    baseUrl: string,
-    requestScope: object = {},
-    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
-  ): Promise<ConnectorStatus> {
-    // Same shape the unscoped registry returns for an unregistered id.
-    if (!this.visible(id)) {
-      return { state: "error", message: "Unknown connector" };
-    }
-    return this.base.statusFor(id, baseUrl, requestScope, callOptions);
+  /** Drop a connector's cached tool list (e.g. after auth completes). */
+  invalidate(id: string): void {
+    this.markCatalogInvalid(id);
+    if (this.persistToolCatalog) void this.deleteStoredCatalog(id);
   }
 
+  /** Drop both in-memory and persisted tool catalogs. */
   async invalidateStored(id: string): Promise<void> {
-    if (!this.visible(id)) return;
-    await this.base.invalidateStored(id);
+    this.markCatalogInvalid(id);
+    if (this.persistToolCatalog) await this.deleteStoredCatalog(id);
   }
 }