@zackbart/connecta 0.28.1 → 0.30.0

package/dist/registry.js

@@ -1,27 +1,28 @@
-import { Cause, Clock, Deferred, Duration, Effect, Exit, Option, Result, } from "effect";
-import { storedCredentialShape, } from "./credential-rules.js";
-import { ConnectorCallError, msg } from "./errors.js";
+import { markCatalogFreshness, carryCatalogFreshness } from "./catalog-freshness.js";
+import { activityRequest } from "./activity-request.js";
+import { attachCatalogCache, catalogExpiry, customCatalogFallback, storeCustomCatalogFallback, catalogFetchedAt, invalidateCatalogCache, observeUncachedCatalogRefresh, } from "./catalog-cache.js";
+import { CONFIG_DEFAULTS } from "./config-defaults.js";
+import { assertStaticToolNames, hasControlCharacters } from "./tool-name.js";
+import { Clock, Duration, Effect, Random } from "effect";
+import { storedCredentialShape } from "./credential-rules.js";
+import { ConnectorCallError } from "./errors.js";
+import { boundedStatus, failureRecord, failureStatus, logFailure, ownStatus } from "./operator-record.js";
 import { ConnectorCallAdmissionController, aggregateCallAdmissionSnapshots, } from "./call-admission.js";
-import { boundedCatalogDrift } from "./catalog-drift.js";
-import { fingerprintSerializedCatalog, snapshotCatalog, } from "./catalog-fingerprint.js";
-import { MAX_CATALOG_CHUNK_BYTES, MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES, } from "./catalog-limits.js";
+import { boundedCatalogDrift, catalogReviewOf, classifyCatalog, observeReviewedDrift, observedCatalogDrift, } from "./catalog-drift.js";
+import { MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES } from "./catalog-limits.js";
 import { ObservedOutputSchemas } from "./result-shapes.js";
-import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, } from "./skills.js";
+import { redactCatalog, sentSecretsFor, sentSecretsForRequest, trackCredentialReads } from "./sent-secrets.js";
+import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary } from "./skills.js";
 import { attachOAuthSealer, vaultOAuthSealer } from "./oauth-sealing.js";
 import { attachOAuthPartition, oauthPartitionIdle } from "./oauth-partition.js";
 import { attachCaller } from "./connector-caller.js";
-import { closeScopeOnExit } from "./runtime/connector-scope.js";
-import { detach, runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { runEdge } from "./runtime/run.js";
 import { SharedRead } from "./runtime/shared-read.js";
-import { Logger as LoggerService } from "./runtime/services.js";
-import { runOnPartition, storageDelete, storageGet, storageSet, } from "./runtime/storage.js";
-import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs } from "./timeout.js";
-import { isExplicitlyReadOnly } from "./tool-safety.js";
+import { runOnPartition, storageCompareAndSet, storageDelete, storageGet, storageSet } from "./runtime/storage.js";
+import { jsonCodec, OAUTH_HANDOFF_TTL_SECONDS, oauthHandoffKeys, resultKeys, scopes, stashLedgerKeys, stashExpiryKeys, } from "./storage/keys.js";
+import { classifyTool } from "./tool-safety.js";
 const ID_RE = /^[a-z0-9_-]+$/;
-const DEFAULT_TTL_SECONDS = 300;
-const DEFAULT_STALE_SECONDS = 3600;
-const CATALOG_CHUNK_TTL_GRACE_SECONDS = 300;
-const DEFAULT_MAX_RESULT_BYTES = 24_000;
+const DEFAULT_MAX_RESULT_BYTES = CONFIG_DEFAULTS.calls.maxResultBytes;
 const encoder = new TextEncoder();
 /**
  * Split `"<connectorId>.<toolName>"` on the first dot. Connector ids contain
@@ -50,7 +51,7 @@ export const MIN_MAX_RESULT_BYTES = 1;
 /**
  * The one definition of a usable `maxResultBytes`: a finite whole number of at
  * least {@link MIN_MAX_RESULT_BYTES} bytes. Shared by all three intake points
- * — `calls.maxResultBytes`, the per-connector override, and `get_result`'s
+ * — `calls.maxResultBytes`, the per-connector override, and `connecta.result`'s
  * `maxBytes` argument — so a value that is valid at one is valid at all.
  *
  * Everything else is rejected rather than coerced, because each rejected shape
@@ -64,105 +65,179 @@ export function isValidMaxResultBytes(value) {
 }
 /**
  * Resolve a configured cap against the value it inherits, dropping anything
- * `isValidMaxResultBytes` rejects. Operator-facing surfaces pair this with a
- * startup warning (see `Registry.checkResultCaps`) so the fallback is never
- * silent; the resolution itself stays total so no call site has to cope with
- * a broken cap.
+ * `isValidMaxResultBytes` rejects. Construction already refuses an unusable
+ * cap (`Registry.assertResultCaps`); the resolution stays total so no call
+ * site has to cope with a broken one.
  */
 export function resolveMaxResultBytes(value, inherited) {
-    return value !== undefined && isValidMaxResultBytes(value)
-        ? value
-        : inherited;
+    return value !== undefined && isValidMaxResultBytes(value) ? value : inherited;
 }
-/**
- * What a joiner hears from a flight that will not answer for it: one that
- * passed its bound, or failed for a reason that was its owner's alone. It
- * never reaches a caller; a joiner that hears it makes a fresh attempt.
- */
-class AbandonedCatalogRefresh extends Error {
-    constructor(id) {
-        super(`The catalog refresh of "${id}" was abandoned.`);
-        this.name = "AbandonedCatalogRefresh";
-    }
-}
-const CATALOG_CHUNK_IO_CONCURRENCY = 4;
-/**
- * Run `operation` over every chunk index or chunk with the fixed chunk I/O
- * bound, settling each: one failure neither interrupts its siblings nor
- * leaves their storage calls running behind the caller. Results keep input
- * order, so the first failure by index is the one a caller reports.
- */
-function forEachChunk(items, operation) {
-    return Effect.forEach(items, (item, index) => Effect.result(operation(item, index)), { concurrency: CATALOG_CHUNK_IO_CONCURRENCY });
-}
-/**
- * A persisted-catalog mutation that logs its storage failure rather than
- * failing, so its turn in the mutation queue always ends.
- */
-function warnOnFailure(mutation, failed) {
-    return Effect.catch(mutation, (err) => LoggerService.use((logger) => Effect.sync(() => logger.warn(`[connecta] ${failed}: ${msg(err)}`))));
+/** Freeze registry-owned facts so review digest memoization remains valid. */
+function frozenFacts(tools) {
+    const pending = [tools];
+    while (pending.length > 0) {
+        const value = pending.pop();
+        if (typeof value !== "object" || value === null || Object.isFrozen(value))
+            continue;
+        Object.freeze(value);
+        for (const item of Object.values(value))
+            pending.push(item);
+    }
+    return tools;
 }
 function namespaced(storage, prefix) {
     return {
+        capabilities: storage.capabilities,
         get: (k) => storage.get(prefix + k),
         set: (k, v, o) => storage.set(prefix + k, v, o),
         delete: (k) => storage.delete(prefix + k),
-        ...(storage.list
-            ? {
-                list: async (keyPrefix) => (await storage.list(prefix + keyPrefix)).map((key) => key.slice(prefix.length)),
-            }
-            : {}),
-        ...(storage.compareAndSet
-            ? {
-                compareAndSet: (k, expected, next, o) => storage.compareAndSet(prefix + k, expected, next, o),
-            }
-            : {}),
+        list: async (keyPrefix) => (await storage.list(prefix + keyPrefix)).map((key) => key.slice(prefix.length)),
+        compareAndSet: (k, expected, next, o) => storage.compareAndSet(prefix + k, expected, next, o),
     };
 }
 const MAX_PERSONAL_REGISTRIES = 1_024;
 const MAX_ABSENT_GRANT_WARNINGS = 1_024;
-const OAUTH_HANDOFF_TTL_SECONDS = 15 * 60;
+/**
+ * Compare-and-set attempts one stash makes on the ledger. A lost swap means
+ * another stash changed the ledger first, never that capacity ran out, so
+ * the loser re-reads and plans again after a jittered, growing pause: of 64
+ * simultaneous claims, each one either books a charge or meets a full ledger.
+ * Exhausting the attempts takes seconds of sustained contention on the one
+ * ledger record, and then the caller keeps its preview.
+ */
+const STASH_LEDGER_ATTEMPTS = 32;
+/** First backoff window after a lost swap; it doubles up to the cap. */
+const STASH_LEDGER_BACKOFF_MS = 4;
+const STASH_LEDGER_BACKOFF_CAP_MS = 250;
+/** Whole chunk-write phase, measured from booking, including the header. */
+const STASH_WRITE_TIMEOUT_MS = 30_000;
+/** Total cleanup/release or settlement budget, including ledger retries. */
+const STASH_COMPLETION_TIMEOUT_MS = 15_000;
+/** Stop waiting without starting background storage work after the deadline. */
+function completeStash(effect) {
+    return effect.pipe(Effect.asVoid, Effect.timeoutOrElse({ duration: Duration.millis(STASH_COMPLETION_TIMEOUT_MS), orElse: () => Effect.void }), 
+    // onError finalizers are otherwise uninterruptible, including their I/O.
+    Effect.interruptible);
+}
+/**
+ * Live charges in a stored ledger. Anything malformed reads as empty: the
+ * ledger bounds an advisory cache, and the next successful swap replaces it.
+ */
+function stashCharges(raw) {
+    if (raw === null)
+        return [];
+    let parsed;
+    try {
+        parsed = jsonCodec.decode(raw);
+    }
+    catch {
+        return [];
+    }
+    const entries = parsed?.entries;
+    if (!Array.isArray(entries))
+        return [];
+    return entries.filter((entry) => Array.isArray(entry) &&
+        entry.length === 3 &&
+        typeof entry[0] === "string" &&
+        Number.isSafeInteger(entry[1]) &&
+        entry[1] >= 0 &&
+        Number.isSafeInteger(entry[2]));
+}
+/** Caller time can nominate a charge for pruning, but only storage proves expiry. */
+function liveStashCharges(raw, now) {
+    return Effect.gen(function* () {
+        const live = [];
+        const expired = new Map();
+        for (const entry of stashCharges(raw)) {
+            const deadline = entry[2];
+            if (deadline > now) {
+                live.push(entry);
+                continue;
+            }
+            let proven = expired.get(deadline);
+            if (proven === undefined) {
+                // A successful absolute-expiry write followed by an absent read proves
+                // storage has passed this deadline, even when the caller runs ahead.
+                // These probes expire at the deadline they check; no cleanup is needed.
+                const key = stashExpiryKeys.deadline(deadline);
+                yield* storageSet(key, "live", { expiresAtMs: deadline });
+                proven = (yield* storageGet(key)) === null;
+                expired.set(deadline, proven);
+            }
+            if (!proven)
+                live.push(entry);
+        }
+        return live;
+    });
+}
+/** Rewrite the ledger with bounded retries; every stored charge already expires. */
+function swapStashLedger(plan) {
+    return Effect.gen(function* () {
+        const ledger = stashLedgerKeys.ledger;
+        for (let attempt = 0; attempt < STASH_LEDGER_ATTEMPTS; attempt++) {
+            if (attempt > 0) {
+                const window = Math.min(STASH_LEDGER_BACKOFF_CAP_MS, STASH_LEDGER_BACKOFF_MS * 2 ** (attempt - 1));
+                yield* Effect.sleep(Duration.millis(Math.floor((yield* Random.next) * window) + 1));
+            }
+            const outcome = yield* Effect.gen(function* () {
+                const raw = yield* storageGet(ledger);
+                const now = yield* Clock.currentTimeMillis;
+                const planned = plan(yield* liveStashCharges(raw, now), now);
+                if (planned.entries !== undefined) {
+                    const entries = planned.entries;
+                    // The ledger row itself expires with its last charge. A delayed CAS
+                    // cannot create an immortal row or restart any reservation's lifetime.
+                    const next = entries.length ? jsonCodec.encode({ v: 1, entries }) : null;
+                    const expiresAtMs = entries.reduce((latest, entry) => Math.max(latest, entry[2]), entries[0]?.[2] ?? now);
+                    if (!(yield* storageCompareAndSet(ledger, raw, next, { expiresAtMs })))
+                        return undefined;
+                }
+                return { status: "applied", result: planned.result };
+            }).pipe(Effect.catch(() => Effect.succeed(undefined)));
+            if (outcome !== undefined)
+                return outcome;
+        }
+        // The final CAS can commit and then throw too. Confirm a read-only plan
+        // once more, especially an already-booked reservation, without another CAS.
+        return yield* Effect.gen(function* () {
+            const raw = yield* storageGet(ledger);
+            const now = yield* Clock.currentTimeMillis;
+            const planned = plan(yield* liveStashCharges(raw, now), now);
+            return planned.entries === undefined
+                ? { status: "applied", result: planned.result }
+                : { status: "exhausted" };
+        }).pipe(Effect.catch(() => Effect.succeed({ status: "exhausted" })));
+    });
+}
 async function sha256Hex(value) {
     const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
-    return [...bytes]
-        .map((byte) => byte.toString(16).padStart(2, "0"))
-        .join("");
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 /**
- * Holds the connector set, resolves addresses, and caches per-connector tool
- * lists in memory with a TTL. Connector failures are isolated: a broken
+ * Holds the connector set, resolves addresses, and coalesces tool listings
+ * within one request. Remote MCP clients own persisted response caching. Connector failures are isolated: a broken
  * connector surfaces status "error"; the rest keep working.
  */
 export class Registry {
     opts;
     connectors = new Map();
     callAdmission = new Map();
-    cache = new Map();
-    invalidated = new Set();
-    /** Per-connector epoch preventing a pre-invalidation refresh from publishing. */
-    catalogGenerations = new Map();
-    // The last queued mutation per connector, as the turn its own request
-    // completes once its storage work is done; see enqueueCatalogMutation.
-    /** Serialize persisted catalog set/delete operations within this isolate. */
-    catalogMutations = new Map();
-    /** Same-request cold loads share one read without retaining the request.
-     * See documentation/architecture.md#the-two-lifetimes. */
+    /** Coalesce listings only within one request and authorization partition. */
     requestCatalogLoads = new WeakMap();
-    /** One live refresh per connector across agent and operator requests. */
-    catalogRefreshes = new Map();
+    catalogObservedAt = new Map();
     /** Last payload-free agent catalog access in this runtime. */
     catalogAccess = new Map();
-    /** Last drift counts reported to activity, per connector, in this runtime. */
-    reportedDrift = new Map();
+    /** Count-only intake findings, including catalogs loaded from storage. */
+    droppedToolNames = new Map();
+    /**
+     * Schema digest verification per reviewed facts array. Only the registry's
+     * own deep-frozen arrays are keys, so an entry stays true while they live.
+     */
+    verifiedFacts = new WeakMap();
     observedOutputSchemas;
-    ttlMs;
-    staleMs;
-    persistToolCatalog;
     /** Result-size guard cap threaded to the meta-tools. */
     maxResultBytes;
-    /** Only keys, byte counts, and expiry survive requests; never write promises. */
-    resultStash = new Map();
-    resultStashBytes = 0;
+    classification;
     configuredConnectors;
     personalRegistries = new Map();
     oauthPartition = {};
@@ -173,13 +248,9 @@ export class Registry {
         this.opts = opts;
         this.configuredConnectors = [...connectors];
         this.observedOutputSchemas = new ObservedOutputSchemas();
-        this.ttlMs =
-            (opts.toolCacheTtlSeconds ?? DEFAULT_TTL_SECONDS) * 1000;
-        this.staleMs =
-            (opts.toolCatalogStaleSeconds ?? DEFAULT_STALE_SECONDS) * 1000;
-        this.persistToolCatalog = opts.persistToolCatalog ?? true;
         this.maxResultBytes = resolveMaxResultBytes(opts.maxResultBytes, DEFAULT_MAX_RESULT_BYTES);
         for (const c of connectors) {
+            assertStaticToolNames(c.staticTools ?? [], `Connector(${JSON.stringify(c.id)}).staticTools`);
             if ("handleRequest" in c) {
                 throw new Error(`Connector "${c.id}" declares removed handleRequest. ` +
                     "Move custom HTTP routes into the deployment's fetch handler.");
@@ -190,29 +261,46 @@ export class Registry {
             if (this.connectors.has(c.id)) {
                 throw new Error(`Duplicate connector id "${c.id}"`);
             }
-            if (c.authScope !== undefined &&
-                c.authScope !== "shared" &&
-                c.authScope !== "personal") {
+            if (c.authScope !== undefined && c.authScope !== "shared" && c.authScope !== "personal") {
                 throw new Error(`Invalid authScope on connector "${c.id}": expected "shared" or "personal"`);
             }
-            const configuredGuideSummary = typeof c.usageGuide === "object"
-                ? normalizeGuideSummary(c.usageGuide.summary ?? "")
-                : undefined;
-            if (configuredGuideSummary !== undefined &&
-                configuredGuideSummary.length > GUIDE_SUMMARY_LENGTH) {
+            const configuredGuideSummary = typeof c.usageGuide === "object" ? normalizeGuideSummary(c.usageGuide.summary ?? "") : undefined;
+            if (configuredGuideSummary !== undefined && configuredGuideSummary.length > GUIDE_SUMMARY_LENGTH) {
                 throw new Error(`Connector "${c.id}" usageGuide.summary is ` +
                     `${configuredGuideSummary.length} characters after whitespace ` +
                     `normalization; the discovery bound is ${GUIDE_SUMMARY_LENGTH}. ` +
                     "Shorten it or omit it to derive one.");
             }
+            // Validated here, before any request (INV-11), and read once per
+            // connector object.
+            if (catalogReviewOf(c) && c.staticTools) {
+                throw new Error(`Connector "${c.id}" declares both staticTools and a classification; ` + "annotate static tools directly.");
+            }
             this.connectors.set(c.id, c);
             if (c.callAdmission) {
                 this.callAdmission.set(c.id, new ConnectorCallAdmissionController(c.id, c.callAdmission));
             }
         }
+        this.classification = Object.assign(Object.create(null), Object.fromEntries(Object.entries(opts.classification ?? {}).map(([id, tools]) => [
+            id,
+            Object.freeze(Object.assign(Object.create(null), tools)),
+        ])));
+        Object.freeze(this.classification);
+        for (const [id, overrides] of Object.entries(this.classification)) {
+            for (const [name, verdict] of Object.entries(overrides)) {
+                if (!name || (verdict !== "read" && verdict !== "write")) {
+                    throw new Error(`ConnectaConfig.classification.${id}.${name}: expected "read" or "write"`);
+                }
+            }
+            const connector = this.connectors.get(id);
+            if (!connector)
+                throw new Error(`ConnectaConfig.classification: unknown connector "${id}"`);
+            if (connector.staticTools)
+                this.validateClassification(id, connector.staticTools, overrides);
+        }
+        this.assertResultCaps(opts.maxResultBytes);
         if (opts.constructionChecks !== false) {
             this.checkConventions(opts.logger);
-            this.checkResultCaps(opts.logger, opts.maxResultBytes);
         }
     }
     personalRegistry(principalKey) {
@@ -224,15 +312,9 @@ export class Registry {
         }
         if (this.personalRegistries.size >= MAX_PERSONAL_REGISTRIES) {
             // Eviction must not reset a live rolling budget or orphan queued calls.
-            // Nor may it drop catalog work in flight: a replacement for the same
-            // principal starts with no generations and no mutation queue, so a
-            // refresh the evicted registry finishes later would persist a listing
-            // that a credential change on the replacement had just deleted.
             // OAuth status/start work bypasses both gates, and accepted rotations
             // may still be saving after their caller leaves. Preserve its partition.
-            const idle = [...this.personalRegistries].find(([, candidate]) => [...candidate.callAdmission.values()].every(admission => admission.isIdle()) &&
-                candidate.catalogRefreshes.size === 0 &&
-                candidate.catalogMutations.size === 0 &&
+            const idle = [...this.personalRegistries].find(([, candidate]) => [...candidate.callAdmission.values()].every((admission) => admission.isIdle()) &&
                 oauthPartitionIdle(candidate.oauthPartition));
             if (!idle) {
                 throw new Error("Personal connector capacity is exhausted; retry after calls, rolling budgets, and catalog refreshes drain.");
@@ -242,10 +324,15 @@ export class Registry {
         }
         const registry = new Registry(this.configuredConnectors.filter((connector) => connector.authScope === "personal"), {
             ...this.opts,
-            storage: namespaced(this.opts.storage, `principal:${principalKey}:`),
+            classification: Object.fromEntries(Object.entries(this.classification).filter(([id]) => this.connectors.get(id)?.authScope === "personal")),
+            storage: namespaced(this.opts.storage, scopes.principal(principalKey)),
             credentialOwner: principalKey,
+            catalogStorage: this.opts.catalogStorage ?? this.opts.storage,
             constructionChecks: false,
         });
+        // Counts only, like the connector-wide reviewed drift observation. No
+        // principal, credentials, or catalog payload crosses this registry boundary.
+        registry.droppedToolNames = this.droppedToolNames;
         if (this.callAdmissionClosed)
             registry.closeCallAdmission();
         this.personalRegistries.set(principalKey, registry);
@@ -253,9 +340,7 @@ export class Registry {
     }
     /** Build the only connector view an authenticated request receives. */
     scoped(scope) {
-        const requested = scope.connectorIds === "all"
-            ? new Set(this.connectors.keys())
-            : new Set(scope.connectorIds);
+        const requested = scope.connectorIds === "all" ? new Set(this.connectors.keys()) : new Set(scope.connectorIds);
         for (const id of requested) {
             if (!this.connectors.has(id)) {
                 throw new Error(`Identity access resolver returned unknown connector "${id}"`);
@@ -264,7 +349,7 @@ export class Registry {
         return new ScopedRegistryView(this, requested, scope);
     }
     scopedStorage(subjectKey) {
-        return namespaced(this.opts.storage, `subject:${subjectKey}:`);
+        return namespaced(this.opts.storage, scopes.subject(subjectKey));
     }
     /**
      * A granted `connector.tool` address the live catalog does not contain is
@@ -282,87 +367,70 @@ export class Registry {
             if (oldest !== undefined)
                 this.warnedAbsentGrants.delete(oldest);
         }
+        if (hasControlCharacters(toolName)) {
+            logFailure(this.opts.logger, "connectorAccess grant is unreachable", failureRecord({ connector: connectorId }));
+            return;
+        }
         // Grant names are operator data but may carry any non-control character;
         // quote them so a line terminator a log reader honours cannot forge a line.
         const quoted = JSON.stringify(key).replace(/[\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16)}`);
         this.opts.logger.warn(`connectorAccess grants ${quoted} but connector "${connectorId}" lists no such tool; the grant is unreachable`);
     }
-    oauthHandoffKey(connectorId, stateHash) {
-        return `oauth-handoff:v1:${connectorId}:${stateHash}`;
-    }
     async storeOAuthHandoff(connectorId, state, principalKey) {
-        const key = this.oauthHandoffKey(connectorId, await sha256Hex(state));
+        const key = oauthHandoffKeys.handoff(connectorId, await sha256Hex(state));
         for (let attempt = 0; attempt < 32; attempt++) {
             const existing = await this.opts.storage.get(key);
             if (existing && existing !== principalKey) {
                 throw new Error(`Connector "${connectorId}" reused one OAuth state across principals`);
             }
-            const expiry = { ttlSeconds: OAUTH_HANDOFF_TTL_SECONDS };
-            if (this.opts.storage.compareAndSet) {
-                // Bind ownership atomically, including renewal of the same owner's
-                // handoff. Two owners reading a miss must not overwrite each other.
-                if (!await this.opts.storage.compareAndSet(key, existing, principalKey, expiry))
-                    continue;
-            }
-            else {
-                await this.opts.storage.set(key, principalKey, expiry);
-            }
-            return;
+            // Bind ownership atomically, including renewal of the same owner's
+            // handoff. Two owners reading a miss must not overwrite each other.
+            if (await this.opts.storage.compareAndSet(key, existing, principalKey, {
+                ttlSeconds: OAUTH_HANDOFF_TTL_SECONDS,
+            }))
+                return;
         }
         throw new Error(`OAuth handoff for "${connectorId}" is busy; retry authorization`);
     }
     async oauthCallbackView(connectorId, state) {
-        const connector = this.connectors.get(connectorId);
-        if (!connector)
-            return null;
-        if (connector.authScope !== "personal")
-            return { registry: this };
         if (!state)
             return null;
-        const principalKey = await this.opts.storage.get(this.oauthHandoffKey(connectorId, await sha256Hex(state)));
-        if (!principalKey)
+        const principalKey = await this.opts.storage.get(oauthHandoffKeys.handoff(connectorId, await sha256Hex(state)));
+        const connector = this.connectors.get(connectorId);
+        if (!connector || !principalKey)
             return null;
         return {
-            registry: this.scoped({
-                connectorIds: [connectorId],
-                subjectKey: principalKey,
-                principalKey,
-            }),
+            registry: connector.authScope === "personal"
+                ? this.scoped({
+                    connectorIds: [connectorId],
+                    subjectKey: principalKey,
+                    principalKey,
+                })
+                : this,
             principalKey,
         };
     }
-    async clearOAuthHandoff(connectorId, state) {
+    async consumeOAuthHandoff(connectorId, state, principalKey) {
         if (!state)
-            return;
-        await this.opts.storage.delete(this.oauthHandoffKey(connectorId, await sha256Hex(state)));
+            return false;
+        const key = oauthHandoffKeys.handoff(connectorId, await sha256Hex(state));
+        return this.opts.storage.compareAndSet(key, principalKey, null);
     }
     /**
-     * Warn once per unusable result cap, at construction time — the same
-     * "runs fine but is surely unintended" channel as the insecure-config
-     * warnings in `createConnecta`. A rejected cap can't be honoured, and
-     * honouring it *approximately* is exactly the inversion issue #32 is about,
-     * so the value is dropped in favour of what it inherits and the operator is
-     * told which one is actually in force.
+     * Refuse an unusable result cap at construction, like every other
+     * structural mistake (INV-11). A rejected cap can't be honoured, and
+     * honouring it *approximately* is exactly the inversion issue #32 is about;
+     * falling back with a warning let a deployment boot on a value nobody
+     * chose.
      */
-    checkResultCaps(logger, configured) {
+    assertResultCaps(configured) {
         if (configured !== undefined && !isValidMaxResultBytes(configured)) {
-            logger.warn(`[connecta] calls.maxResultBytes ${configured} is not a whole number of ` +
-                `bytes >= ${MIN_MAX_RESULT_BYTES}: it would serve an empty, ` +
-                "oversized, or unguarded result instead of truncating. Using the " +
-                `default ${DEFAULT_MAX_RESULT_BYTES} instead.`);
+            throw new Error(`ConnectaConfig.calls.maxResultBytes must be a whole number of bytes >= ${MIN_MAX_RESULT_BYTES}.`);
         }
         for (const c of this.connectors.values()) {
-            if (c.maxResultBytes !== undefined &&
-                !isValidMaxResultBytes(c.maxResultBytes)) {
-                // The number quoted here is `this.maxResultBytes` because that is
-                // literally what a call falls back to: meta-tools reads the inherited
-                // cap off `RegistryView.maxResultBytes`, so the warned value and the
-                // runtime value are the same field rather than two copies of it.
-                logger.warn(`[connecta] connector "${c.id}" sets maxResultBytes ` +
-                    `${c.maxResultBytes}, which is not a whole number of bytes >= ` +
-                    `${MIN_MAX_RESULT_BYTES}. Ignoring the override — the connector ` +
-                    `inherits the deployment-wide cap calls fall back to ` +
-                    `(${this.maxResultBytes}).`);
+            if (c.maxResultBytes !== undefined && !isValidMaxResultBytes(c.maxResultBytes)) {
+                throw new Error(`Connector "${c.id}" maxResultBytes must be a whole number of bytes >= ` +
+                    `${MIN_MAX_RESULT_BYTES}; omit it to inherit the deployment-wide cap.`);
             }
         }
     }
@@ -393,7 +461,13 @@ export class Registry {
     getConnector(id) {
         return this.connectors.get(id);
     }
-    contextFor(id, baseUrl, requestScope = {}, callOptions = {}) {
+    getResourceConnector(id) {
+        return this.getConnector(id);
+    }
+    canReadConnectorSkills(id) {
+        return this.connectors.has(id);
+    }
+    contextFor(id, baseUrl, requestScope = {}, callOptions = {}, scope) {
         const credentialConfig = this.connectors.get(id)?.credential;
         let credentialAccess;
         if (this.opts.credentialVault && credentialConfig) {
@@ -415,13 +489,42 @@ export class Registry {
             };
         }
         const context = {
-            storage: namespaced(this.opts.storage, `conn:${id}:`),
+            storage: namespaced(this.opts.storage, scopes.connector(id)),
             logger: this.opts.logger,
             baseUrl,
+            ...(this.opts.publicUrl !== undefined ? { publicUrl: this.opts.publicUrl } : {}),
+            ...(this.opts.oauthClientName !== undefined ? { oauthClientName: this.opts.oauthClientName } : {}),
             ...(credentialAccess ? { credential: credentialAccess } : {}),
             requestScope,
             ...callOptions,
         };
+        attachCaller(context, scope?.caller);
+        attachCatalogCache(context, {
+            storage: this.opts.catalogStorage ?? this.opts.storage,
+            partition: JSON.stringify([
+                scope?.principalKey ?? this.opts.credentialOwner ?? null,
+                scope?.subjectKey ?? null,
+                scope?.caller?.identity ?? null,
+                scope?.caller?.authenticated ?? false,
+                scope?.caller?.pool ?? null,
+            ]),
+            sharedPartition: JSON.stringify([baseUrl, this.opts.publicUrl ?? null, scope?.caller?.pool ?? null]),
+            defaultTtlMs: (this.opts.toolCacheTtlSeconds ?? CONFIG_DEFAULTS.discovery.catalogTtlSeconds) * 1000,
+            minTtlMs: (this.opts.catalogMinTtlSeconds ?? CONFIG_DEFAULTS.discovery.catalogMinTtlSeconds) * 1000,
+            maxTtlMs: (this.opts.catalogMaxTtlSeconds ?? CONFIG_DEFAULTS.discovery.catalogMaxTtlSeconds) * 1000,
+            ...(this.opts.catalogDriftActivity?.recordChange
+                ? {
+                    onCompletedCatalogRefresh: (refresh, ctx) => this.recordCatalogDrift(refresh.previous, refresh.next, {
+                        id,
+                        connector: this.connectors.get(id),
+                        ctx,
+                        privateCatalog: refresh.private,
+                    }),
+                }
+                : {}),
+        });
+        sentSecretsFor(context);
+        trackCredentialReads(context);
         attachOAuthPartition(context, this.oauthPartition);
         // Downstream OAuth state is sealed under the vault key, bound to this
         // connector and owner. The sealer rides beside the context, not on it.
@@ -446,71 +549,28 @@ export class Registry {
                 snapshots.get(id)?.push(admission.snapshot());
             }
         }
-        return Object.fromEntries([...snapshots].map(([id, values]) => [
-            id, aggregateCallAdmissionSnapshots(values),
-        ]));
+        return Object.fromEntries([...snapshots].map(([id, values]) => [id, aggregateCallAdmissionSnapshots(values)]));
     }
     /**
-     * Payload-free drift counts for the open health endpoint, so `connecta
-     * doctor` can report a stale allowlist without asking any downstream
-     * anything. Only connectors that ship a vetted manifest *and* have already
-     * served a refresh *in this runtime* appear — a process or isolate that has
-     * answered no catalog request yet honestly reports nothing, and drift is not
-     * persisted the way the catalog itself is.
-     *
-     * Every report is rebuilt by {@link boundedCatalogDrift} on the way out:
-     * `Connector.catalogDrift()` is the open plugin seam, and this snapshot is
-     * serialized into an unauthenticated response.
+     * The drift a connector last showed in this runtime: the registry's own
+     * observation against a connector's `classification`, otherwise whatever
+     * the connector's `catalogDrift()` seam reports, bounded either way.
      */
-    catalogDriftSnapshot() {
-        const snapshot = {};
-        for (const connector of this.connectors.values()) {
-            const report = boundedCatalogDrift(connector.catalogDrift?.());
-            if (report)
-                snapshot[connector.id] = report;
-        }
-        return snapshot;
-    }
-    /**
-     * Turn the observation a refresh just took into at most one activity event.
-     *
-     * Emitted on change rather than on every refresh: an identical report every
-     * TTL is a heartbeat, not news, and the current counts are already on
-     * connector status. A first observation that is clean is not an event
-     * either — nothing moved — but a later return to clean is, because "the
-     * drift is gone" is exactly what an operator watching the timeline is
-     * waiting for.
-     */
-    observeCatalogDrift(connector) {
-        const report = boundedCatalogDrift(connector.catalogDrift?.());
-        if (!report)
-            return;
-        const previous = this.reportedDrift.get(connector.id);
-        // Bounded counts, so a seam returning NaN cannot make every refresh look
-        // like a change and emit an event per refresh forever.
-        const counts = {
-            unclassifiedTools: report.unclassifiedTools,
-            unservedTools: report.unservedTools,
-            annotationConflicts: report.annotationConflicts,
-            schemaChanges: report.schemaChanges,
+    catalogDriftOf(connector) {
+        const report = boundedCatalogDrift(catalogReviewOf(connector) ? observedCatalogDrift(connector) : connector.catalogDrift?.());
+        const dropped = this.droppedToolNames.get(connector.id);
+        if (!dropped)
+            return report;
+        return {
+            ...(report ?? {
+                unclassifiedTools: 0,
+                unservedTools: 0,
+                annotationConflicts: 0,
+                schemaChanges: 0,
+            }),
+            observedAt: dropped.observedAt,
+            ...(dropped.count > 0 ? { droppedTools: dropped.count } : {}),
         };
-        const unchanged = previous !== undefined &&
-            previous.unclassifiedTools === counts.unclassifiedTools &&
-            previous.unservedTools === counts.unservedTools &&
-            previous.annotationConflicts === counts.annotationConflicts &&
-            previous.schemaChanges === counts.schemaChanges;
-        if (unchanged)
-            return;
-        const clean = counts.unclassifiedTools === 0 &&
-            counts.unservedTools === 0 &&
-            counts.annotationConflicts === 0 &&
-            counts.schemaChanges === 0;
-        this.reportedDrift.set(connector.id, counts);
-        if (previous === undefined && clean)
-            return;
-        this.opts.catalogDriftActivity?.recordDrift?.(this.opts.catalogDriftActivity
-            ? { ...this.opts.catalogDriftActivity, logger: this.opts.logger }
-            : undefined, { connectorId: connector.id, ...counts });
     }
     /** Reject queued/future downstream admission; active permits release safely. */
     closeCallAdmission() {
@@ -521,75 +581,128 @@ export class Registry {
             registry.closeCallAdmission();
     }
     /**
-     * Reserve capacity and write one ASCII paging envelope in this runtime.
+     * Reserve capacity and write one ASCII paging envelope.
+     *
+     * `chunks[n]` lands on `resultKeys.chunk(id, n)` inside `partition` — the
+     * layout connecta.result reads back, so a page fetches only the chunks it covers
+     * instead of the whole stored result (issue #540). Chunking is a read-cost
+     * decision, not a capacity one: however many keys an envelope occupies, it
+     * is one stash entry charged its total ASCII length.
      *
-     * `chunks[0]` lands on `<prefix><key>` and `chunks[n]` on `<prefix><key>#<n>`
-     * — the layout get_result reads back, so a page fetches only the chunks it
-     * covers instead of the whole stored result (issue #540). Chunking is a
-     * read-cost decision, not a capacity one: however many keys an envelope
-     * occupies, it is one stash entry charged its total ASCII length.
+     * The bounds are the deployment's, not this isolate's. Every charge is a
+     * row in one ledger record in storage, booked by compare-and-set before any
+     * chunk is written, so every isolate and process sharing the store sees the
+     * same entries and bytes. A pending write keeps its finite charge reserved.
+     * Writes stop after 30 seconds; absolute chunk expiries cannot pass the
+     * booked deadline even on late commit. Rejected responses leave writes
+     * unconfirmed and retain their charge. Cleanup/release and settlement each
+     * stop waiting after 15 seconds. Storage TTL reclaims the rows.
      */
-    stashResult(key, chunks, ttlSeconds, prefix = "results:") {
-        // The fiber runs synchronously up to its first storage call. With nothing
-        // expired to reclaim, that is the first chunk write, after the
-        // reservation: a concurrent stash already sees this one's charge.
+    stashResult(id, chunks, ttlSeconds, partition = scopes.results) {
         return runOnPartition(Effect.gen({ self: this }, function* () {
-            const maxBytes = this.opts.results?.maxStashBytes ?? 8 * 1024 * 1024;
-            const maxEntries = this.opts.results?.maxStashEntries ?? 64;
+            const maxBytes = this.opts.results?.maxStashBytes ?? CONFIG_DEFAULTS.results.maxStashBytes;
+            const maxEntries = this.opts.results?.maxStashEntries ?? CONFIG_DEFAULTS.results.maxStashEntries;
             // The paging envelope is ASCII, so its string length is its stored byte count.
             const bytes = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
             if (bytes > maxBytes || maxEntries === 0)
                 return false;
-            const now = yield* Clock.currentTimeMillis;
-            for (const [oldKey, entry] of this.resultStash) {
-                if (entry.busy || entry.expiresAt > now)
-                    continue;
-                entry.busy = true;
-                // TTL alone cannot reclaim a lazy backend. Keep the charge until
-                // deletion succeeds, including writes which persisted before throwing;
-                // a failed delete fails this stash, and the entry waits for the next.
-                yield* Effect.gen({ self: this }, function* () {
-                    for (const staleKey of entry.keys)
-                        yield* storageDelete(staleKey);
-                    this.resultStash.delete(oldKey);
-                    this.resultStashBytes -= entry.bytes;
-                }).pipe(Effect.ensuring(Effect.sync(() => { entry.busy = false; })));
-            }
-            if (this.resultStash.size >= maxEntries || this.resultStashBytes + bytes > maxBytes)
+            const keys = chunks.map((_, index) => partition + resultKeys.chunk(id, index));
+            // IDs belong to reservations, not reusable result IDs or subjects.
+            const charge = crypto.randomUUID();
+            const ttlMs = ttlSeconds * 1000;
+            if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0)
+                return false;
+            const booking = yield* swapStashLedger((live, now) => {
+                // A committed CAS with a lost response is already our booking, even
+                // at full capacity. Reuse its deadline instead of adding a second slot.
+                const own = live.find((entry) => entry[0] === charge);
+                if (own)
+                    return { result: own[2] };
+                const used = live.reduce((sum, entry) => sum + entry[1], 0);
+                if (live.length >= maxEntries || used + bytes > maxBytes)
+                    return { result: undefined };
+                const deadline = now + STASH_WRITE_TIMEOUT_MS + ttlMs;
+                if (!Number.isSafeInteger(deadline))
+                    return { result: undefined };
+                return { entries: [...live, [charge, bytes, deadline]], result: deadline };
+            });
+            if (booking.status === "exhausted" || booking.result === undefined)
                 return false;
-            const fullKey = prefix + key;
-            const keys = chunks.map((_, index) => index === 0 ? fullKey : `${fullKey}#${index}`);
-            const entry = { keys, bytes, expiresAt: Infinity, busy: true };
-            this.resultStash.set(fullKey, entry);
-            this.resultStashBytes += bytes;
-            // Trailing chunks first: the header chunk is what makes an id readable, so
-            // a write that fails midway leaves no envelope pointing at absent chunks.
-            yield* Effect.gen(function* () {
+            const deadline = booking.result;
+            const writeDeadline = deadline - ttlMs;
+            const chunkExpiry = deadline - STASH_WRITE_TIMEOUT_MS;
+            const owns = (entry) => entry[0] === charge;
+            const settle = swapStashLedger((live) => live.some((entry) => owns(entry) && entry[2] > chunkExpiry)
+                ? {
+                    entries: live.map((entry) => (owns(entry) ? [charge, bytes, Math.min(entry[2], chunkExpiry)] : entry)),
+                    result: undefined,
+                }
+                : { result: undefined });
+            let pendingWrite = false;
+            // A rejected or timed-out driver call may still commit after deletion.
+            // Only a confirmed write response clears pendingWrite.
+            const release = completeStash(Effect.gen(function* () {
+                const deleted = yield* Effect.gen(function* () {
+                    for (const key of keys)
+                        yield* storageDelete(key);
+                    return true;
+                }).pipe(Effect.catch(() => Effect.succeed(false)));
+                if (pendingWrite)
+                    return;
+                if (deleted) {
+                    const released = yield* swapStashLedger((live) => live.some(owns)
+                        ? { entries: live.filter((entry) => !owns(entry)), result: undefined }
+                        : { result: undefined });
+                    if (released.status === "applied")
+                        return;
+                }
+                yield* settle;
+            }));
+            // Trailing chunks first, then the header. The caller receives no result
+            // ID after failure or timeout, including a late header commit.
+            const remaining = Math.max(0, writeDeadline - (yield* Clock.currentTimeMillis));
+            const written = yield* Effect.gen(function* () {
                 for (let index = keys.length - 1; index >= 0; index--) {
-                    yield* storageSet(keys[index], chunks[index], { ttlSeconds });
+                    const before = yield* Clock.currentTimeMillis;
+                    if (before >= writeDeadline || before >= chunkExpiry)
+                        return false;
+                    pendingWrite = true;
+                    yield* storageSet(keys[index], chunks[index], { expiresAtMs: chunkExpiry }).pipe(Effect.tap(() => Effect.sync(() => {
+                        pendingWrite = false;
+                    })));
+                    if ((yield* Clock.currentTimeMillis) >= writeDeadline)
+                        return false;
                 }
-            }).pipe(
-            // A failed write expires at once, still charged, so the next stash
-            // reclaims every key it may have persisted before failing.
-            Effect.onExit((exit) => Clock.currentTimeMillis.pipe(Effect.map((writtenAt) => {
-                entry.expiresAt = Exit.isSuccess(exit)
-                    ? writtenAt + ttlSeconds * 1000
-                    : 0;
-                entry.busy = false;
-            }))));
-            return true;
+                return true;
+            }).pipe(Effect.timeoutOrElse({ duration: Duration.millis(remaining), orElse: () => Effect.succeed(false) }), Effect.onError(() => release.pipe(Effect.ignore)));
+            if (!written)
+                yield* release;
+            else
+                yield* completeStash(settle);
+            return written;
         }), this.opts);
     }
     /**
-     * Storage namespaced to the meta-tool result store (`results:` prefix), kept
-     * separate from any connector's `conn:<id>:` namespace. Backs get_result.
+     * Storage namespaced to the root result partition, kept separate from any
+     * connector's namespace. Backs connecta.result.
      */
+    resultIdentity() {
+        return { subject: null, principal: null, endpoint: "/mcp", origin: null };
+    }
+    recheckResultAccess(_address, _classification, _signal, _access) {
+        return Promise.resolve(true);
+    }
     resultsStorage() {
-        return namespaced(this.opts.storage, "results:");
+        return namespaced(this.opts.storage, scopes.results);
     }
-    credentialUiAvailable() { return Boolean(this.opts.credentialUi); }
-    async bindOAuthHandoff() {
-        // Shared OAuth already resolves in deployment-wide connector storage.
+    credentialUiAvailable() {
+        return Boolean(this.opts.credentialUi);
+    }
+    async bindOAuthHandoff(id, authorizationUrl, principalKey) {
+        const state = new URL(authorizationUrl).searchParams.get("state");
+        if (!state || !principalKey)
+            throw new Error("OAuth requires state and an initiating user");
+        await this.storeOAuthHandoff(id, state, principalKey);
     }
     observedOutputSchema(connectorId, definition) {
         return this.observedOutputSchemas.get(connectorId, definition);
@@ -607,608 +720,143 @@ export class Registry {
             return null;
         return { connector, toolName: parts.toolName };
     }
-    catalogKey(id) {
-        return `catalog:${id}`;
-    }
-    catalogChunkKey(id, revision, index) {
-        return `${this.catalogKey(id)}:chunk:${revision}:${index}`;
-    }
-    validCatalogTools(value) {
-        return value.every((tool) => tool !== null &&
-            typeof tool === "object" &&
-            typeof tool.name === "string");
-    }
-    validCatalogManifest(value) {
-        if (!value || typeof value !== "object")
-            return null;
-        const manifest = value;
-        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;
-    }
-    parseCatalogManifest(raw) {
-        if (!raw)
-            return null;
+    /** Compare only the fingerprints accepted in this exact cache partition. */
+    recordCatalogDrift(previous, next, attribution) {
+        if (!previous)
+            return;
+        const { id, connector, ctx, privateCatalog } = attribution;
+        const before = new Map(previous.map((tool) => [tool.name, tool.fact]));
+        const after = new Map(next.map((tool) => [tool.name, tool.fact]));
+        const addedTools = [...after.keys()].filter((name) => !before.has(name)).length;
+        const removedTools = [...before.keys()].filter((name) => !after.has(name)).length;
+        const changedTools = [...after].filter(([name, fact]) => before.has(name) && before.get(name) !== fact).length;
+        if (addedTools || removedTools || changedTools)
+            this.opts.catalogDriftActivity?.recordChange?.({ ...this.opts.catalogDriftActivity, logger: this.opts.logger, ...(ctx.defer ? { defer: ctx.defer } : {}) }, {
+                connectorId: id,
+                drift: { kind: "catalog_changed", addedTools, removedTools, changedTools },
+                privateCatalog,
+                ...(connector.authScope === "personal" ? { personal: true } : {}),
+            }, activityRequest(ctx.requestScope));
+    }
+    async loadDownstreamTools(id, baseUrl, requestScope, callOptions = {}, scope) {
+        const connector = this.connectors.get(id);
+        if (!connector)
+            throw new Error(`Unknown connector "${id}"`);
+        if (connector.staticTools)
+            return markCatalogFreshness(connector.staticTools, Infinity);
+        const ctx = this.contextFor(id, baseUrl, requestScope, callOptions, scope);
+        let listed;
         try {
-            return this.validCatalogManifest(JSON.parse(raw));
+            listed = await connector.listTools(ctx);
         }
-        catch {
-            return null;
+        catch (error) {
+            const fallback = error instanceof ConnectorCallError && error.code === "unavailable"
+                ? await customCatalogFallback(ctx, id).catch(() => undefined)
+                : undefined;
+            if (!fallback)
+                throw sentSecretsForRequest(ctx.requestScope ?? ctx).redact(error);
+            listed = fallback;
         }
-    }
-    splitCatalogChunks(snapshot) {
-        const chunks = [];
-        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;
+        const tools = redactCatalog(ctx, listed).map(({ classification: _ignored, ...fact }) => fact);
+        if (tools.length > MAX_CATALOG_TOOLS ||
+            encoder.encode(JSON.stringify(tools)).byteLength > MAX_SERIALIZED_CATALOG_BYTES) {
+            throw new ConnectorCallError("connector_call_failed", "Downstream catalog exceeds the complete-catalog ceiling.", { retryable: false });
         }
-        return chunks;
-    }
-    // The persisted catalog's one reader: the manifest at `catalog:<id>`, then
-    // the chunks it names. A storage failure fails the effect, and the caller
-    // logs it; a manifest or chunk that is invalid, missing, torn, or does not
-    // match its fingerprint is logged here and read as no catalog, because a
-    // catalog is complete or it is nothing.
-    readCatalog(id, now) {
-        return Effect.gen({ self: this }, function* () {
-            const raw = yield* storageGet(this.catalogKey(id));
-            if (!raw)
-                return null;
-            let parsed;
+        const facts = frozenFacts(structuredClone(tools));
+        const accepted = this.acceptToolNames(facts);
+        this.observeDroppedToolNames(connector, facts.length - accepted.length);
+        const review = catalogReviewOf(connector);
+        if (review)
+            await observeReviewedDrift(connector, review, accepted, this.opts.logger);
+        if (catalogFetchedAt(ctx) === undefined) {
             try {
-                parsed = JSON.parse(raw);
-            }
-            catch {
-                return null;
+                await storeCustomCatalogFallback(ctx, id, facts);
             }
-            const logger = yield* LoggerService;
-            const manifest = this.validCatalogManifest(parsed);
-            if (!manifest) {
-                logger.warn(`[connecta] connector "${id}" catalog manifest is invalid; ignoring persisted catalog.`);
-                return null;
-            }
-            if (manifest.staleUntil <= now)
-                return null;
-            const chunkReads = yield* forEachChunk(Array.from({ length: manifest.chunkCount }, (_, index) => index), (index) => storageGet(this.catalogChunkKey(id, manifest.revision, index)));
-            const chunks = [];
-            let chunkBytes = 0;
-            for (const [index, read] of chunkReads.entries()) {
-                if (Result.isFailure(read))
-                    return yield* Effect.fail(read.failure);
-                const chunk = read.success;
-                if (chunk === null) {
-                    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 (byteLength > MAX_CATALOG_CHUNK_BYTES ||
-                    chunkBytes > manifest.byteCount) {
-                    logger.warn(`[connecta] connector "${id}" catalog chunk bounds do not match its manifest; ignoring persisted catalog.`);
-                    return null;
-                }
-                chunks.push(chunk);
-            }
-            const serializedTools = chunks.join("");
-            const stored = yield* Effect.tryPromise({
-                try: () => fingerprintSerializedCatalog(serializedTools),
-                catch: (error) => error,
-            });
-            if (stored.byteLength !== manifest.byteCount ||
-                stored.fingerprint !== manifest.revision) {
-                logger.warn(`[connecta] connector "${id}" catalog fingerprint mismatch; ignoring persisted catalog.`);
-                return null;
+            catch (error) {
+                logFailure(this.opts.logger, "catalog refresh observation failed", failureRecord({ connector: id }, error));
             }
-            let tools;
             try {
-                tools = JSON.parse(serializedTools);
+                await observeUncachedCatalogRefresh(ctx, id, facts);
             }
-            catch {
-                logger.warn(`[connecta] connector "${id}" catalog chunks are torn; ignoring persisted catalog.`);
-                return null;
+            catch (error) {
+                logFailure(this.opts.logger, "catalog refresh observation failed", failureRecord({ connector: id }, error));
             }
-            if (!Array.isArray(tools) || !this.validCatalogTools(tools)) {
-                logger.warn(`[connecta] connector "${id}" catalog chunks contain invalid tools; ignoring persisted catalog.`);
-                return null;
-            }
-            if (tools.length !== manifest.toolCount) {
-                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,
-            };
-        });
-    }
-    // Persist one complete catalog: every chunk, then the manifest. A snapshot
-    // only reaches here after the tool and byte ceilings accepted it whole.
-    storeCatalog(id, snapshot) {
-        return Effect.gen({ self: this }, function* () {
-            if (!this.persistToolCatalog)
-                return;
-            const fetchedAt = yield* Clock.currentTimeMillis;
-            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 = yield* forEachChunk(chunks, (chunk, index) => storageSet(this.catalogChunkKey(id, snapshot.fingerprint, index), chunk, {
-                ttlSeconds: ttlSeconds + CATALOG_CHUNK_TTL_GRACE_SECONDS,
-            }));
-            for (const write of chunkWrites) {
-                if (Result.isFailure(write))
-                    return yield* Effect.fail(write.failure);
-            }
-            // 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 = {
-                version: 2,
-                revision: snapshot.fingerprint,
-                toolCount: snapshot.tools.length,
-                byteCount: snapshot.serializedBytes.byteLength,
-                chunkCount: chunks.length,
-                fetchedAt,
-                expiresAt,
-                staleUntil,
-            };
-            yield* storageSet(this.catalogKey(id), JSON.stringify(manifest), {
-                ttlSeconds,
-            });
-        });
-    }
-    // Remove the persisted catalog: the manifest and every chunk it names, all
-    // at once under the chunk I/O bound. Every delete is attempted; the effect
-    // fails with the manifest read's error first, then the manifest delete's,
-    // then the first chunk delete's by index.
-    deleteCatalog(id) {
-        return Effect.gen({ self: this }, function* () {
-            const read = yield* Effect.result(storageGet(this.catalogKey(id)));
-            const manifest = Result.isSuccess(read)
-                ? this.parseCatalogManifest(read.success)
-                : null;
-            // The root is authoritative, so attempt its deletion even when the
-            // best-effort read needed for physical chunk cleanup failed. It need
-            // not land first: a reader that finds the root but not a chunk has an
-            // incomplete catalog, which is never served, and an eventually
-            // consistent store could show it that way whatever the order.
-            const keys = [
-                this.catalogKey(id),
-                ...Array.from({ length: manifest?.chunkCount ?? 0 }, (_, index) => this.catalogChunkKey(id, manifest.revision, index)),
-            ];
-            const deleted = yield* forEachChunk(keys, (key) => storageDelete(key));
-            if (Result.isFailure(read))
-                return yield* Effect.fail(read.failure);
-            const failed = deleted.find(Result.isFailure);
-            if (failed)
-                return yield* Effect.fail(failed.failure);
-        });
-    }
-    catalogGeneration(id) {
-        return this.catalogGenerations.get(id) ?? 0;
-    }
-    advanceCatalogGeneration(id) {
-        this.catalogGenerations.set(id, this.catalogGeneration(id) + 1);
-    }
-    /**
-     * Keep this isolate's writes and invalidations ordered. Without the queue, an
-     * old refresh can finish its storage.set after a credential change deletes
-     * the catalog and resurrect the pre-change listing.
-     */
-    async enqueueCatalogMutation(id, operation) {
-        // Mutations run in arrival order, each taking its turn from the one
-        // queued before it. That one may belong to another request, and
-        // completing a Deferred resumes its waiters inside the completing call,
-        // so the wait is an edge of its own and this request's storage work
-        // starts only after it. (Effect's Semaphore would do neither: it resumes
-        // a waiter from the releasing fiber, and a newcomer can take the permit
-        // before a waiter that queued earlier.) An operation logs its own storage
-        // failure, so a turn always ends.
-        const previous = this.catalogMutations.get(id);
-        const turn = Deferred.makeUnsafe();
-        this.catalogMutations.set(id, turn);
-        try {
-            if (previous) {
-                // A cross-request Deferred alone looks hung to workerd. Keep a timer
-                // owned by this request until the preceding mutation hands over its
-                // turn; the race interrupts the timer as soon as the wait settles.
-                await runEdge(Effect.raceFirst(Deferred.await(previous), Effect.forever(Effect.sleep(Duration.seconds(1)))));
-            }
-            await runOnPartition(operation, this.opts);
-        }
-        finally {
-            if (this.catalogMutations.get(id) === turn) {
-                this.catalogMutations.delete(id);
-            }
-            Deferred.doneUnsafe(turn, Exit.void);
-        }
-    }
-    async refreshToolsWithContext(id, connector, ctx, skipPublicationWhenAborted = false, flight) {
-        const generation = this.catalogGeneration(id);
-        const tools = await connector.listTools(ctx);
-        // The listing a maintained proxy just served is also the only catalog
-        // comparison connecta ever makes. It rides this refresh whether or not the
-        // result reaches a cache, because what drifted drifted.
-        this.observeCatalogDrift(connector);
-        // A deferred deadline may close the owned scope while a connector that
-        // ignores abort is still listing. The completed list remains a valid drift
-        // observation, but must not overwrite a newer same-generation refresh.
-        // Blocking callers do not set this flag and retain their prior publication
-        // behavior when an inbound abort races a completed listing.
-        // Every returned listing must pass the ceilings, even when invalidation
-        // or abandonment means it can no longer enter either shared cache layer.
-        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 (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);
-        }
-        // The caller that began this refresh may still use its bounded result,
-        // but credential changes, abandoned flights, and deferred cancellation
-        // prevent publication. Recheck after snapshotting, which is asynchronous.
-        if (!this.mayPublish(id, generation, flight) ||
-            (skipPublicationWhenAborted && ctx.signal?.aborted)) {
-            return tools;
         }
-        const now = Date.now();
-        const catalogChanged = !previous || previous.fingerprint !== snapshot.fingerprint;
-        const shouldPersist = 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,
+        this.catalogObservedAt.set(id, catalogFetchedAt(ctx) ?? Date.now());
+        const provenance = catalogExpiry(ctx);
+        const freshUntil = provenance && !provenance.staleFallback ? provenance.expiresAt : 0;
+        this.catalogAccess.set(id, {
+            state: freshUntil > Date.now() ? "fresh" : "stale",
+            observedAt: new Date().toISOString(),
         });
-        this.invalidated.delete(id);
-        if (shouldPersist) {
-            await this.enqueueCatalogMutation(id, 
-            // The generation is read when the turn comes, not when it is queued:
-            // an invalidation queued meanwhile has already deleted the catalog.
-            warnOnFailure(Effect.suspend(() => generation === this.catalogGeneration(id)
-                ? this.storeCatalog(id, snapshot)
-                : Effect.void), `connector "${id}" catalog persistence failed`));
-        }
-        return tools;
+        return markCatalogFreshness(facts, freshUntil);
     }
-    /**
-     * Whether a refresh may still enter the shared cache layers: its generation
-     * is current, and the flight it runs in has been neither abandoned nor
-     * outlived its bound. Asked at each publication point, since listing and
-     * snapshotting both yield, and a late result must never overwrite the one a
-     * fresh attempt published in the meantime.
-     */
-    mayPublish(id, generation, flight) {
-        return (generation === this.catalogGeneration(id) &&
-            (!flight || (!flight.abandoned && Date.now() < flight.abandonAt)));
-    }
-    /**
-     * Publish one shared refresh before starting its connector work. The first
-     * caller owns the scope and signal, and the flight lives `boundMs` from now
-     * at most; every later caller joins the result without gaining access to
-     * that context. A flight found past its bound is abandoned here, and this
-     * caller starts the fresh attempt.
-     */
-    startCatalogRefresh(id, generation, boundMs, work, ownerLeft = () => false) {
-        const existing = this.catalogRefreshes.get(id);
-        if (existing?.generation === generation) {
-            if (Date.now() < existing.abandonAt)
-                return { flight: existing };
-            this.abandonCatalogRefresh(id, existing);
-        }
-        const flight = {
-            generation,
-            abandonAt: Date.now() + boundMs,
-            abandoned: false,
-            outcome: Deferred.makeUnsafe(),
-        };
-        this.catalogRefreshes.set(id, flight);
-        const owner = Effect.onExit(work(flight), (exit) => Effect.sync(() => {
-            if (this.catalogRefreshes.get(id) === flight) {
-                this.catalogRefreshes.delete(id);
-            }
-            // A failure that was the owner's alone is no answer for anyone
-            // else: its own cancellation (its signal, read here in its own
-            // request), or anything that arrives once the flight is past its
-            // bound. Joiners make a fresh attempt under their own deadlines.
-            const ownersAlone = Exit.isFailure(exit) &&
-                (flight.abandoned ||
-                    Date.now() >= flight.abandonAt ||
-                    ownerLeft());
-            // Last, because joined fibers resume inside this call.
-            Deferred.doneUnsafe(flight.outcome, ownersAlone ? Exit.fail(new AbandonedCatalogRefresh(id)) : exit);
-        }));
-        return { flight, owner };
+    /** The served catalog excludes control-character names; raw caches stay complete. */
+    acceptToolNames(tools) {
+        const accepted = tools.filter((tool) => !hasControlCharacters(tool.name));
+        return accepted.length === tools.length ? tools : accepted;
     }
-    /**
-     * Give up on a flight that outlived its bound. Later readers start a fresh
-     * attempt, its joiners are told to, and nothing its owner lists from now on
-     * reaches a cache. The owner's work is left alone: it belongs to another
-     * request, which nothing here may reach into, and it can no longer publish.
-     */
-    abandonCatalogRefresh(id, flight) {
-        if (flight.abandoned)
-            return;
-        flight.abandoned = true;
-        if (this.catalogRefreshes.get(id) === flight) {
-            this.catalogRefreshes.delete(id);
+    /** Observe intake once, never while serving an older cached listing. */
+    observeDroppedToolNames(connector, count) {
+        if (count > 0 || this.droppedToolNames.has(connector.id)) {
+            this.droppedToolNames.set(connector.id, { count, observedAt: new Date().toISOString() });
         }
-        this.opts.logger.warn(`[connecta] connector "${id}" catalog refresh outlived its bound; abandoning it for a fresh attempt.`);
-        Deferred.doneUnsafe(flight.outcome, Exit.fail(new AbandonedCatalogRefresh(id)));
     }
     /**
-     * Wait on another caller's flight, no longer than its bound. Succeeds with
-     * its tools, or with `undefined` when it will not answer for this caller —
-     * past its bound, when this waiter abandons it, or failed for its owner
-     * alone — so the caller makes a fresh attempt. The timer is this waiter's
-     * own: on workerd it is what keeps a request that waits on another alive,
-     * and bounded.
+     * One connector's catalog as served: the cached downstream facts, classified
+     * on every read by the connector's `classification`, into fresh objects.
+     * Safety is derived here and nowhere else, so no cache layer can carry a
+     * stale verdict — from an older review, an older release, or a stale
+     * fallback — and nothing a caller or decorator does to a served tool reaches
+     * the next read.
      */
-    joinCatalogRefresh(id, flight) {
-        return Effect.suspend(() => Deferred.await(flight.outcome).pipe(Effect.timeoutOption(Duration.millis(Math.max(0, flight.abandonAt - Date.now()))), Effect.flatMap((joined) => Option.isSome(joined)
-            ? Effect.succeed(joined.value)
-            : Effect.sync(() => {
-                this.abandonCatalogRefresh(id, flight);
-                return undefined;
-            })), Effect.catch((error) => error instanceof AbandonedCatalogRefresh
-            ? Effect.succeed(undefined)
-            : Effect.fail(error))));
-    }
-    /** Force a live listTools refresh and replace both catalog cache layers. */
-    async refreshTools(id, baseUrl, requestScope, callOptions = {}) {
+    async loadTools(id, baseUrl, requestScope, callOptions = {}, scope) {
+        const tools = await this.loadDownstreamTools(id, baseUrl, requestScope, callOptions, scope);
         const connector = this.connectors.get(id);
         if (!connector)
             throw new Error(`Unknown connector "${id}"`);
-        if (connector.staticTools)
-            return connector.staticTools;
-        // A flight lives as long as its owner will wait for it. Past that, the
-        // owner may have answered and gone, and on workerd its I/O went with it.
-        const boundMs = normalizeTimeoutMs(callOptions.timeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
-        for (;;) {
-            const { flight, owner } = this.startCatalogRefresh(id, this.catalogGeneration(id), boundMs, (flight) => Effect.tryPromise({
-                try: () => this.refreshToolsWithContext(id, connector, this.contextFor(id, baseUrl, requestScope, callOptions), false, flight),
-                catch: (error) => error,
-            }), () => callOptions.signal?.aborted === true);
-            // The owner lists in its own request. A joiner waits through an edge of
-            // its own, under its own signal, and whatever it does with the tools
-            // happens after that, back in its request (see "Effect inside" in
-            // documentation/architecture.md). A flight that will not answer for it
-            // sends it round again, to join a fresh attempt or to own one.
-            if (owner)
-                return runEdge(owner);
-            const joined = await runEdge(this.joinCatalogRefresh(id, flight), {
-                signal: callOptions.signal,
-            });
-            if (joined)
-                return joined;
-        }
-    }
-    observeCatalogAccess(id, state) {
-        this.catalogAccess.set(id, {
-            state,
-            observedAt: new Date().toISOString(),
-        });
-    }
-    /**
-     * Start or join one shared refresh. A newly deferred task owns its scope,
-     * deadline, and teardown; no inbound signal or request scope crosses into it.
-     */
-    deferCatalogRefresh(id, baseUrl, expectedGeneration, options) {
-        const connector = this.connectors.get(id);
-        const defer = options.defer;
-        if (!connector || connector.staticTools || !defer)
-            return;
-        // The refresh this request starts, if none of this generation is live.
-        // Its scope is closed however it ends, deadline included, before the
-        // flight completes.
-        const refresh = (flight) => withDeadlineEffect((signal) => Effect.gen({ self: this }, function* () {
-            const current = this.cache.get(id);
-            if (current && current.exp > Date.now())
-                return current.tools;
-            if (expectedGeneration !== this.catalogGeneration(id) ||
-                this.invalidated.has(id)) {
-                return yield* Effect.fail(new Error(`Deferred catalog refresh of "${id}" was invalidated before it started.`));
-            }
-            const ctx = this.contextFor(id, baseUrl, {}, {
-                signal,
-                timeoutMs: options.refreshTimeoutMs,
-            });
-            yield* closeScopeOnExit(connector, ctx, defer);
-            return yield* Effect.tryPromise({
-                try: () => this.refreshToolsWithContext(id, connector, ctx, true, flight),
-                catch: (error) => error,
-            });
-        }), {
-            timeoutMs: options.refreshTimeoutMs,
-            timeoutError: new Error(`deferred catalog refresh of "${id}" timed out after ${options.refreshTimeoutMs}ms`),
-        });
-        const logFailure = (err) => {
-            this.opts.logger.warn(`[connecta] connector "${id}" deferred catalog refresh failed: ${msg(err)}`);
+        const accepted = this.acceptToolNames(tools);
+        const overrides = this.classification[id];
+        this.validateClassification(id, accepted, overrides);
+        const review = catalogReviewOf(connector);
+        return carryCatalogFreshness(tools, review
+            ? await classifyCatalog(review, id, accepted, this.opts.logger, this.verifiedFacts, overrides)
+            : accepted.map((tool) => this.publishUnreviewedTool(id, tool)));
+    }
+    publishUnreviewedTool(id, tool) {
+        const override = this.classification[id]?.[tool.name];
+        return {
+            ...structuredClone(tool),
+            classification: classifyTool(tool, override),
+            ...(override !== undefined
+                ? {
+                    annotations: {
+                        ...structuredClone(tool.annotations),
+                        readOnlyHint: override === "read",
+                        destructiveHint: override === "write",
+                    },
+                }
+                : {}),
         };
-        const { flight, owner } = this.startCatalogRefresh(id, expectedGeneration, options.refreshTimeoutMs, (flight) => Effect.scoped(refresh(flight)));
-        if (owner) {
-            // Runs past this response, under the runtime's waitUntil below.
-            flight.deferredTail = detach(Effect.catchCause(owner, (cause) => Effect.sync(() => logFailure(Cause.squash(cause)))));
-        }
-        // A stale reader that joins a blocking refresh logs its failure once for
-        // every reader after it, and waits through an edge of its own, no longer
-        // than the flight's bound.
-        flight.deferredTail ??= runEdge(this.joinCatalogRefresh(id, flight)).then(() => { }, logFailure);
-        try {
-            defer(flight.deferredTail);
-        }
-        catch (err) {
-            this.opts.logger.warn(`[connecta] connector "${id}" deferred catalog refresh could not attach to the runtime: ${msg(err)}`);
-        }
     }
-    /** Cached listTools with in-memory + persisted serializable catalog layers. */
-    async loadTools(id, baseUrl, requestScope, callOptions = {}, readOptions) {
-        const connector = this.connectors.get(id);
-        if (!connector)
-            throw new Error(`Unknown connector "${id}"`);
-        if (connector.staticTools)
-            return connector.staticTools;
-        const now = Date.now();
-        const requestGeneration = this.catalogGeneration(id);
-        const hit = this.cache.get(id);
-        if (hit && hit.exp > now) {
-            if (readOptions?.defer)
-                this.observeCatalogAccess(id, "fresh");
-            return hit.tools;
-        }
-        let stale = hit && hit.staleUntil > now
-            ? { tools: hit.tools, staleUntil: hit.staleUntil }
-            : undefined;
-        if (this.persistToolCatalog && !this.invalidated.has(id)) {
-            const generation = this.catalogGeneration(id);
-            let persisted = null;
-            try {
-                persisted = await runOnPartition(this.readCatalog(id, now), this.opts);
-            }
-            catch (err) {
-                this.opts.logger.warn(`[connecta] connector "${id}" catalog read failed: ${msg(err)}`);
-            }
-            if (generation !== this.catalogGeneration(id)) {
-                persisted = null;
-                stale = undefined;
-            }
-            // Storage can yield while another request finishes a live refresh. Read
-            // the shared cache again before an older manifest gets any authority.
-            // The candidate with the later fresh deadline wins; both candidates have
-            // already passed their own fingerprint and completeness checks.
-            const reconciledAt = Date.now();
-            const current = this.cache.get(id);
-            const usableCurrent = current && current.staleUntil > reconciledAt ? current : undefined;
-            if (usableCurrent) {
-                stale = {
-                    tools: usableCurrent.tools,
-                    staleUntil: usableCurrent.staleUntil,
-                };
-                if (usableCurrent.exp > reconciledAt) {
-                    if (readOptions?.defer)
-                        this.observeCatalogAccess(id, "fresh");
-                    return usableCurrent.tools;
-                }
-            }
-            if (persisted &&
-                persisted.staleUntil > reconciledAt &&
-                (!usableCurrent || persisted.expiresAt > usableCurrent.exp)) {
-                this.cache.set(id, {
-                    tools: persisted.tools,
-                    fingerprint: persisted.fingerprint,
-                    exp: persisted.expiresAt,
-                    staleUntil: persisted.staleUntil,
-                });
-                if (persisted.expiresAt > reconciledAt) {
-                    if (readOptions?.defer)
-                        this.observeCatalogAccess(id, "fresh");
-                    return persisted.tools;
-                }
-                stale = {
-                    tools: persisted.tools,
-                    staleUntil: persisted.staleUntil,
-                };
-            }
-        }
-        if (stale &&
-            stale.staleUntil > Date.now() &&
-            readOptions?.defer &&
-            requestGeneration === this.catalogGeneration(id) &&
-            !this.invalidated.has(id)) {
-            this.deferCatalogRefresh(id, baseUrl, requestGeneration, readOptions);
-            // Invalidation can land synchronously while the refresh is attached.
-            // Repeat the authority check at the exact stale publication point.
-            if (stale.staleUntil > Date.now() &&
-                requestGeneration === this.catalogGeneration(id) &&
-                !this.invalidated.has(id)) {
-                this.observeCatalogAccess(id, "stale");
-                return stale.tools;
-            }
-        }
-        try {
-            const tools = await this.refreshTools(id, baseUrl, requestScope, callOptions);
-            if (readOptions?.defer)
-                this.observeCatalogAccess(id, "fresh");
-            return tools;
-        }
-        catch (err) {
-            if (stale &&
-                stale.staleUntil > Date.now() &&
-                requestGeneration === this.catalogGeneration(id) &&
-                !this.invalidated.has(id)) {
-                if (readOptions?.defer)
-                    this.observeCatalogAccess(id, "stale");
-                this.opts.logger.warn(`[connecta] connector "${id}" catalog refresh failed; serving stale catalog: ${msg(err)}`);
-                return stale.tools;
-            }
-            throw err;
+    /** Construction-only view for the secret-free static config description. */
+    describeStaticTools(id) {
+        const tools = this.connectors.get(id)?.staticTools;
+        return tools?.map((tool) => this.publishUnreviewedTool(id, tool));
+    }
+    validateClassification(id, tools, overrides) {
+        const known = new Set(tools.map((tool) => tool.name));
+        for (const name of Object.keys(overrides ?? {})) {
+            if (!known.has(name))
+                throw new Error(`ConnectaConfig.classification: connector "${id}" has no tool "${name}"`);
         }
     }
-    /**
-     * Coalesce one connector's catalog traversal 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 read owns its signal, and each caller waits under its own: one that
-     * is cancelled while others wait leaves with its own failure, and the read
-     * is cancelled only when every caller has gone (src/runtime/shared-read.ts).
-     *
-     * The deployment-wide flight below this layer coalesces the actual live
-     * refresh across requests. Its owner's context governs the listing, and its
-     * owner's deadline bounds it; later callers join only its result, never its
-     * request scope, and a failure that was the owner's alone sends them to a
-     * fresh attempt rather than to them.
-     */
-    async getTools(id, baseUrl, requestScope, callOptions = {}, readOptions) {
+    async getTools(id, baseUrl, requestScope, callOptions = {}, scope) {
         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, readOptions);
+            return this.loadTools(id, baseUrl, requestScope, callOptions, scope);
         }
         let loads = this.requestCatalogLoads.get(requestScope);
         if (!loads) {
@@ -1216,19 +864,20 @@ export class Registry {
             this.requestCatalogLoads.set(requestScope, loads);
         }
         const requestLoads = loads;
-        let load = requestLoads.get(id);
+        const key = JSON.stringify([id, scope?.principalKey, scope?.subjectKey, scope?.caller]);
+        let load = requestLoads.get(key);
         if (!load) {
-            const started = new SharedRead((signal) => this.loadTools(id, baseUrl, requestScope, { ...callOptions, signal }, readOptions), 
+            const started = new SharedRead((signal) => this.loadTools(id, baseUrl, requestScope, { ...callOptions, signal }, scope), 
             // Settled or cancelled, the read leaves the map before any caller
             // resumes, so the next one asks the caches afresh.
             () => {
-                if (requestLoads.get(id) === started)
-                    requestLoads.delete(id);
+                if (requestLoads.get(key) === started)
+                    requestLoads.delete(key);
                 if (requestLoads.size === 0) {
                     this.requestCatalogLoads.delete(requestScope);
                 }
             });
-            requestLoads.set(id, started);
+            requestLoads.set(key, started);
             load = started;
         }
         return runEdge(load.join(callOptions.signal));
@@ -1244,16 +893,21 @@ export class Registry {
             return shape.state === "mismatch" ? shape.message : undefined;
         }
         catch (error) {
-            this.opts.logger.warn(`[connecta] connector "${id}" credential shape read failed: ${msg(error)}`);
+            logFailure(this.opts.logger, "credential shape read failed", failureRecord({ connector: id }, error));
             return undefined;
         }
     }
+    /** Age of a complete cache entry; reads never refresh it. */
+    catalogAgeMs(id) {
+        const observedAt = this.catalogObservedAt.get(id);
+        return observedAt === undefined ? null : Math.max(0, Date.now() - observedAt);
+    }
     /** Best-effort connector status for the operator UI. */
-    async statusFor(id, baseUrl, requestScope = {}, callOptions = {}) {
+    async statusFor(id, baseUrl, requestScope = {}, callOptions = {}, scope) {
         const connector = this.connectors.get(id);
         if (!connector)
-            return { state: "error", message: "Unknown connector" };
-        const ctx = this.contextFor(id, baseUrl, requestScope, callOptions);
+            return ownStatus({ state: "error", message: "Unknown connector" });
+        const ctx = this.contextFor(id, baseUrl, requestScope, callOptions, scope);
         // Whatever the state turns out to be, it carries the drift the last
         // refresh saw. Reading it is a lookup, not a probe: a connector that has
         // listed nothing yet reports nothing, and status never lists on its own to
@@ -1262,56 +916,60 @@ export class Registry {
         // is third-party output, and status is read by the operator UI and copied
         // into responses.
         const withObservations = (status) => {
-            const report = boundedCatalogDrift(connector.catalogDrift?.());
+            const report = this.catalogDriftOf(connector);
             const access = this.catalogAccess.get(id);
             // Connector.status is an open plugin seam. Rebuild its public fields so
             // a connector cannot smuggle payload through either registry-owned
-            // observation when this runtime has not made one.
-            const boundedStatus = {
-                state: status.state,
-                ...(status.message !== undefined ? { message: status.message } : {}),
-            };
-            return {
-                ...boundedStatus,
+            // observation when this runtime has not made one, nor through its
+            // message, which survives only when connecta wrote it (INV-6).
+            return Object.assign(boundedStatus(status), {
                 ...(report ? { catalogDrift: report } : {}),
                 ...(access ? { catalogAccess: { ...access } } : {}),
-            };
+            });
         };
+        // Credential declarations own their readiness even when a static catalog
+        // or a plugin status would otherwise report success. Never probe an empty slot.
+        if (connector.credential) {
+            try {
+                const values = (await this.opts.credentialVault?.getAll(id, this.opts.credentialOwner)) ?? null;
+                const shape = storedCredentialShape(connector.credential, values);
+                if (shape.state === "missing")
+                    return withObservations(ownStatus({ state: "credential_required" }));
+                if (shape.state === "mismatch")
+                    return withObservations(ownStatus({ state: "auth_required" }));
+            }
+            catch (err) {
+                return withObservations(failureStatus(id, err));
+            }
+        }
         if (connector.status) {
             try {
                 return withObservations(await connector.status(ctx));
             }
             catch (err) {
-                return withObservations({ state: "error", message: msg(err) });
+                return withObservations(failureStatus(id, err));
             }
         }
         try {
-            await this.getTools(id, baseUrl, requestScope, callOptions);
+            await this.getTools(id, baseUrl, requestScope, callOptions, scope);
             return withObservations({ state: "ok" });
         }
         catch (err) {
-            return withObservations({ state: "error", message: msg(err) });
+            return withObservations(failureStatus(id, err));
         }
     }
-    markCatalogInvalid(id) {
-        this.advanceCatalogGeneration(id);
-        this.cache.delete(id);
-        this.invalidated.add(id);
-    }
-    deleteStoredCatalog(id) {
-        return this.enqueueCatalogMutation(id, warnOnFailure(this.deleteCatalog(id), `connector "${id}" catalog invalidation failed`));
-    }
-    /** Drop a connector's cached tool list (e.g. after auth completes). */
+    /** Rotate the storage generation; in-flight old readers cannot republish it. */
     invalidate(id) {
-        this.markCatalogInvalid(id);
-        if (this.persistToolCatalog)
-            void this.deleteStoredCatalog(id);
+        void this.invalidateStored(id);
     }
-    /** Drop both in-memory and persisted tool catalogs. */
     async invalidateStored(id) {
-        this.markCatalogInvalid(id);
-        if (this.persistToolCatalog)
-            await this.deleteStoredCatalog(id);
+        this.catalogObservedAt.delete(id);
+        try {
+            await invalidateCatalogCache(this.opts.catalogStorage ?? this.opts.storage, id);
+        }
+        catch (error) {
+            logFailure(this.opts.logger, "catalog invalidation failed", failureRecord({ connector: id }, error));
+        }
     }
 }
 class ScopedRegistryView {
@@ -1322,9 +980,7 @@ class ScopedRegistryView {
     /** An evicted view's admission controller must remain closed. */
     admissionPersonal;
     get personal() {
-        return this.scope.principalKey
-            ? this.root.personalRegistry(this.scope.principalKey)
-            : undefined;
+        return this.scope.principalKey ? this.root.personalRegistry(this.scope.principalKey) : undefined;
     }
     constructor(root, allowed, scope) {
         this.root = root;
@@ -1333,9 +989,7 @@ class ScopedRegistryView {
         this.maxResultBytes = root.maxResultBytes;
         // Check capacity at construction, then resolve the current registry on
         // use. A retained view must not revive one evicted while it was idle.
-        this.admissionPersonal = scope.principalKey
-            ? root.personalRegistry(scope.principalKey)
-            : undefined;
+        this.admissionPersonal = scope.principalKey ? root.personalRegistry(scope.principalKey) : undefined;
     }
     registryFor(id, admission = false) {
         if (!this.allowed.has(id))
@@ -1350,9 +1004,17 @@ class ScopedRegistryView {
     listConnectors() {
         return this.root.listConnectors().filter((connector) => this.registryFor(connector.id) !== undefined);
     }
+    canReadConnectorSkills(id) {
+        return (this.registryFor(id) !== undefined && !this.scope.toolAccess?.has(id) && !this.scope.guardedToolAccess?.has(id));
+    }
     getConnector(id) {
         return this.registryFor(id)?.getConnector(id);
     }
+    getResourceConnector(id) {
+        if (this.scope.toolAccess?.has(id) || this.scope.guardedToolAccess?.has(id))
+            return undefined;
+        return this.getConnector(id);
+    }
     resolveAddress(address) {
         const parsed = splitAddress(address);
         if (!parsed)
@@ -1365,7 +1027,7 @@ class ScopedRegistryView {
         if (!registry) {
             throw new Error(`Unknown connector "${args[0]}"`);
         }
-        const tools = await registry.getTools(...args);
+        const tools = await registry.getTools(args[0], args[1], args[2], args[3], this.scope);
         const guarded = this.scope.guardedToolAccess?.get(args[0]);
         const granted = this.scope.toolAccess?.get(args[0]) ?? guarded;
         if (!granted)
@@ -1373,8 +1035,7 @@ class ScopedRegistryView {
         // Every consumer — search, describe, call_tool, and a program's
         // connecta.call — resolves through this list, so an ungranted tool is
         // indistinguishable from one the connector never had.
-        const visible = tools.filter((tool) => granted.has(tool.name) &&
-            (!guarded?.has(tool.name) || isExplicitlyReadOnly(tool)));
+        const visible = tools.filter((tool) => granted.has(tool.name) && (!guarded?.has(tool.name) || tool.classification === "read"));
         if (visible.length < granted.size) {
             const present = new Set(tools.map((tool) => tool.name));
             for (const name of granted) {
@@ -1382,13 +1043,13 @@ class ScopedRegistryView {
                     this.root.noteAbsentGrant(args[0], name);
             }
         }
-        return visible;
+        return carryCatalogFreshness(tools, visible);
     }
     contextFor(...args) {
         const registry = this.registryFor(args[0]);
         if (!registry)
             throw new Error(`Unknown connector "${args[0]}"`);
-        return attachCaller(registry.contextFor(...args), this.scope.caller);
+        return registry.contextFor(args[0], args[1], args[2], args[3], this.scope);
     }
     admitCall(...args) {
         const registry = this.registryFor(args[0], true);
@@ -1397,19 +1058,26 @@ class ScopedRegistryView {
         }
         return registry.admitCall(...args);
     }
-    stashResult(key, chunks, ttlSeconds) {
-        return this.root.stashResult(key, chunks, ttlSeconds, this.scope.subjectKey ? `subject:${this.scope.subjectKey}:` : "results:");
+    stashResult(id, chunks, ttlSeconds) {
+        return this.root.stashResult(id, chunks, ttlSeconds, this.scope.subjectKey ? scopes.subject(this.scope.subjectKey) : scopes.results);
+    }
+    resultIdentity() {
+        return {
+            subject: this.scope.subjectKey ?? null,
+            principal: this.scope.principalKey ?? null,
+            endpoint: this.scope.endpoint ?? "/mcp",
+            origin: this.scope.origin ?? null,
+        };
+    }
+    recheckResultAccess(address, classification, signal, access) {
+        return this.scope.currentResultAccess?.(address, classification, signal, access) ?? Promise.resolve(true);
     }
     resultsStorage() {
-        return this.scope.subjectKey
-            ? this.root.scopedStorage(this.scope.subjectKey)
-            : this.root.resultsStorage();
+        return this.scope.subjectKey ? this.root.scopedStorage(this.scope.subjectKey) : this.root.resultsStorage();
     }
     credentialDriftFor(id) {
         const registry = this.registryFor(id);
-        return registry
-            ? registry.credentialDriftFor(id)
-            : Promise.resolve(undefined);
+        return registry ? registry.credentialDriftFor(id) : Promise.resolve(undefined);
     }
     observedOutputSchema(connectorId, definition) {
         return this.registryFor(connectorId)?.observedOutputSchema(connectorId, definition);
@@ -1417,30 +1085,23 @@ class ScopedRegistryView {
     observeOutputShape(connectorId, definition, value) {
         this.registryFor(connectorId)?.observeOutputShape(connectorId, definition, value);
     }
+    catalogAgeMs(id) {
+        return this.registryFor(id)?.catalogAgeMs(id) ?? null;
+    }
     statusFor(...args) {
         const registry = this.registryFor(args[0]);
         return registry
-            ? registry.statusFor(...args)
+            ? registry.statusFor(args[0], args[1], args[2], args[3], this.scope)
             : Promise.resolve({ state: "error", message: "Unknown connector" });
     }
     invalidateStored(id) {
         const registry = this.registryFor(id);
         return registry ? registry.invalidateStored(id) : Promise.resolve();
     }
-    credentialUiAvailable() { return this.root.credentialUiAvailable(); }
-    async bindOAuthHandoff(id, authorizationUrl) {
-        const connector = this.getConnector(id);
-        if (connector?.authScope !== "personal" || !this.scope.principalKey)
-            return;
-        let state = null;
-        try {
-            state = new URL(authorizationUrl).searchParams.get("state");
-        }
-        catch {
-            return;
-        }
-        if (state) {
-            await this.root.storeOAuthHandoff(id, state, this.scope.principalKey);
-        }
+    credentialUiAvailable() {
+        return this.root.credentialUiAvailable();
+    }
+    async bindOAuthHandoff(id, authorizationUrl, principalKey) {
+        await this.root.bindOAuthHandoff(id, authorizationUrl, principalKey ?? this.scope.principalKey);
     }
 }