@zackbart/connecta 0.24.4 → 0.26.0

package/dist/registry.js

@@ -1,19 +1,26 @@
-import { closeConnectorScope, } from "./connector-scope.js";
+import { Cause, Clock, Deferred, Duration, Effect, Exit, Option, Result, } from "effect";
 import { storedCredentialShape, } from "./credential-rules.js";
 import { ConnectorCallError, msg } from "./errors.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 { mapSettledWithConcurrency } from "./concurrency.js";
 import { ObservedOutputSchemas } from "./result-shapes.js";
 import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, } from "./skills.js";
-import { withDeadline } from "./timeout.js";
+import { attachOAuthSealer, vaultOAuthSealer } from "./oauth-sealing.js";
+import { attachCaller } from "./connector-caller.js";
+import { closeScopeOnExit } from "./runtime/connector-scope.js";
+import { detach, runEdge, withDeadlineEffect } 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";
 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 = 50_000;
+const DEFAULT_MAX_RESULT_BYTES = 24_000;
 const encoder = new TextEncoder();
 /**
  * Split `"<connectorId>.<toolName>"` on the first dot. Connector ids contain
@@ -66,7 +73,34 @@ export function resolveMaxResultBytes(value, inherited) {
         ? 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)}`))));
+}
 function namespaced(storage, prefix) {
     return {
         get: (k) => storage.get(prefix + k),
@@ -77,6 +111,11 @@ function namespaced(storage, prefix) {
                 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),
+            }
+            : {}),
     };
 }
 const MAX_PERSONAL_REGISTRIES = 1_024;
@@ -101,9 +140,11 @@ export class Registry {
     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 promise without retaining the request.
+    /** Same-request cold loads share one read without retaining the request.
      * See documentation/architecture.md#the-two-lifetimes. */
     requestCatalogLoads = new WeakMap();
     /** One live refresh per connector across agent and operator requests. */
@@ -181,9 +222,15 @@ export class Registry {
         }
         if (this.personalRegistries.size >= MAX_PERSONAL_REGISTRIES) {
             // Eviction must not reset a live rolling budget or orphan queued calls.
-            const idle = [...this.personalRegistries].find(([, candidate]) => [...candidate.callAdmission.values()].every(admission => admission.isIdle()));
+            // 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.
+            const idle = [...this.personalRegistries].find(([, candidate]) => [...candidate.callAdmission.values()].every(admission => admission.isIdle()) &&
+                candidate.catalogRefreshes.size === 0 &&
+                candidate.catalogMutations.size === 0);
             if (!idle) {
-                throw new Error("Personal connector capacity is exhausted; retry after calls and rolling budgets drain.");
+                throw new Error("Personal connector capacity is exhausted; retry after calls, rolling budgets, and catalog refreshes drain.");
             }
             idle[1].closeCallAdmission();
             this.personalRegistries.delete(idle[0]);
@@ -346,7 +393,7 @@ export class Registry {
                 getAll: readValues,
             };
         }
-        return {
+        const context = {
             storage: namespaced(this.opts.storage, `conn:${id}:`),
             logger: this.opts.logger,
             baseUrl,
@@ -354,6 +401,11 @@ export class Registry {
             requestScope,
             ...callOptions,
         };
+        // Downstream OAuth state is sealed under the vault key, bound to this
+        // connector and owner. The sealer rides beside the context, not on it.
+        return this.opts.credentialVault
+            ? attachOAuthSealer(context, vaultOAuthSealer(this.opts.credentialVault, id, this.opts.credentialOwner, this.opts.logger))
+            : context;
     }
     admitCall(id, input) {
         const admission = this.callAdmission.get(id);
@@ -455,53 +507,56 @@ export class Registry {
      * read-cost decision, not a capacity one: however many keys an envelope
      * occupies, it is one stash entry charged its total ASCII length.
      */
-    async stashResult(key, chunks, ttlSeconds, prefix = "results:") {
-        const maxBytes = this.opts.results?.maxStashBytes ?? 8 * 1024 * 1024;
-        const maxEntries = this.opts.results?.maxStashEntries ?? 64;
-        // 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 = Date.now();
-        for (const [oldKey, entry] of this.resultStash) {
-            if (entry.busy || entry.expiresAt > now)
-                continue;
-            entry.busy = true;
-            try {
-                // TTL alone cannot reclaim a lazy backend. Keep the charge until deletion
-                // succeeds, including writes which persisted before throwing.
-                for (const staleKey of entry.keys)
-                    await this.opts.storage.delete(staleKey);
-                this.resultStash.delete(oldKey);
-                this.resultStashBytes -= entry.bytes;
-            }
-            finally {
-                entry.busy = false;
+    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.
+        return runOnPartition(Effect.gen({ self: this }, function* () {
+            const maxBytes = this.opts.results?.maxStashBytes ?? 8 * 1024 * 1024;
+            const maxEntries = this.opts.results?.maxStashEntries ?? 64;
+            // 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)
-            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;
-        try {
+            if (this.resultStash.size >= maxEntries || this.resultStashBytes + bytes > maxBytes)
+                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.
-            for (let index = keys.length - 1; index >= 0; index--) {
-                await this.opts.storage.set(keys[index], chunks[index], { ttlSeconds });
-            }
-            entry.expiresAt = Date.now() + ttlSeconds * 1000;
+            yield* Effect.gen(function* () {
+                for (let index = keys.length - 1; index >= 0; index--) {
+                    yield* storageSet(keys[index], chunks[index], { ttlSeconds });
+                }
+            }).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;
-        }
-        catch (error) {
-            entry.expiresAt = 0;
-            throw error;
-        }
-        finally {
-            entry.busy = false;
-        }
+        }), this.opts);
     }
     /**
      * Storage namespaced to the meta-tool result store (`results:` prefix), kept
@@ -596,135 +651,145 @@ export class Registry {
         }
         return chunks;
     }
-    async readCatalog(id, raw, now) {
-        if (!raw)
-            return null;
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
-        const manifest = this.validCatalogManifest(parsed);
-        if (!manifest) {
-            this.opts.logger.warn(`[connecta] connector "${id}" catalog manifest is invalid; ignoring persisted catalog.`);
-            return null;
-        }
-        if (manifest.staleUntil <= now)
-            return null;
-        const chunkReads = await mapSettledWithConcurrency(Array.from({ length: manifest.chunkCount }, (_, index) => index), CATALOG_CHUNK_IO_CONCURRENCY, (index) => this.opts.storage.get(this.catalogChunkKey(id, manifest.revision, index)));
-        const chunks = [];
-        let chunkBytes = 0;
-        for (const [index, result] of chunkReads.entries()) {
-            if (result.status === "rejected")
-                throw result.reason;
-            const chunk = result.value;
-            if (chunk === null) {
-                this.opts.logger.warn(`[connecta] connector "${id}" catalog chunk ${index + 1}/${manifest.chunkCount} is missing; ignoring persisted catalog.`);
+    // 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;
+            try {
+                parsed = JSON.parse(raw);
             }
-            const byteLength = encoder.encode(chunk).byteLength;
-            chunkBytes += byteLength;
-            if (byteLength > MAX_CATALOG_CHUNK_BYTES ||
-                chunkBytes > manifest.byteCount) {
-                this.opts.logger.warn(`[connecta] connector "${id}" catalog chunk bounds do not match its manifest; ignoring persisted catalog.`);
+            catch {
                 return null;
             }
-            chunks.push(chunk);
-        }
-        const serializedTools = chunks.join("");
-        const stored = await fingerprintSerializedCatalog(serializedTools);
-        if (stored.byteLength !== manifest.byteCount ||
-            stored.fingerprint !== manifest.revision) {
-            this.opts.logger.warn(`[connecta] connector "${id}" catalog fingerprint mismatch; ignoring persisted catalog.`);
-            return null;
-        }
-        let tools;
-        try {
-            tools = JSON.parse(serializedTools);
-        }
-        catch {
-            this.opts.logger.warn(`[connecta] connector "${id}" catalog chunks are torn; ignoring persisted catalog.`);
-            return null;
-        }
-        if (!Array.isArray(tools) || !this.validCatalogTools(tools)) {
-            this.opts.logger.warn(`[connecta] connector "${id}" catalog chunks contain invalid tools; ignoring persisted catalog.`);
-            return null;
-        }
-        if (tools.length !== manifest.toolCount) {
-            this.opts.logger.warn(`[connecta] connector "${id}" catalog tool count does not match its manifest; ignoring persisted catalog.`);
-            return null;
-        }
-        return {
-            tools,
-            fingerprint: stored.fingerprint,
-            fetchedAt: manifest.fetchedAt,
-            expiresAt: manifest.expiresAt,
-            staleUntil: manifest.staleUntil,
-        };
-    }
-    async storeCatalog(id, snapshot) {
-        if (!this.persistToolCatalog)
-            return;
-        const fetchedAt = Date.now();
-        const expiresAt = fetchedAt + this.ttlMs;
-        const staleUntil = expiresAt + this.staleMs;
-        const ttlSeconds = Math.max(60, Math.ceil((this.ttlMs + this.staleMs) / 1000));
-        const chunks = this.splitCatalogChunks(snapshot);
-        const chunkWrites = await mapSettledWithConcurrency(chunks, CATALOG_CHUNK_IO_CONCURRENCY, (chunk, index) => this.opts.storage.set(this.catalogChunkKey(id, snapshot.fingerprint, index), chunk, { ttlSeconds: ttlSeconds + CATALOG_CHUNK_TTL_GRACE_SECONDS }));
-        for (const result of chunkWrites) {
-            if (result.status === "rejected")
-                throw result.reason;
-        }
-        // The manifest is the only publication point. A failed/partial chunk write
-        // therefore leaves the previous manifest authoritative (or no catalog);
-        // unreachable chunks carry a bounded TTL and require no prefix scan.
-        const manifest = {
-            version: 2,
-            revision: snapshot.fingerprint,
-            toolCount: snapshot.tools.length,
-            byteCount: snapshot.serializedBytes.byteLength,
-            chunkCount: chunks.length,
-            fetchedAt,
-            expiresAt,
-            staleUntil,
-        };
-        await this.opts.storage.set(this.catalogKey(id), JSON.stringify(manifest), {
-            ttlSeconds,
+            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;
+            }
+            let tools;
+            try {
+                tools = JSON.parse(serializedTools);
+            }
+            catch {
+                logger.warn(`[connecta] connector "${id}" catalog chunks are torn; ignoring persisted catalog.`);
+                return null;
+            }
+            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,
+            };
         });
     }
-    async deleteCatalog(id) {
-        let raw = null;
-        let readError;
-        try {
-            raw = await this.opts.storage.get(this.catalogKey(id));
-        }
-        catch (err) {
-            readError = err;
-        }
-        const manifest = this.parseCatalogManifest(raw);
-        // The root is authoritative, so attempt its deletion even when the
-        // best-effort read needed for physical chunk cleanup failed.
-        await this.opts.storage.delete(this.catalogKey(id));
-        if (!manifest) {
-            if (readError)
-                throw readError;
-            return;
-        }
-        let firstError;
-        for (let index = 0; index < manifest.chunkCount; index++) {
-            try {
-                await this.opts.storage.delete(this.catalogChunkKey(id, manifest.revision, index));
+    // 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);
             }
-            catch (err) {
-                firstError ??= err;
+            // 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 always, then the chunks it
+    // names. Every delete is attempted; the effect fails with the manifest
+    // read's error first, then the first chunk delete's.
+    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.
+            yield* storageDelete(this.catalogKey(id));
+            let firstError;
+            for (let index = 0; manifest && index < manifest.chunkCount; index++) {
+                const deleted = yield* Effect.result(storageDelete(this.catalogChunkKey(id, manifest.revision, index)));
+                if (Result.isFailure(deleted))
+                    firstError ??= deleted;
             }
-        }
-        if (readError)
-            throw readError;
-        if (firstError)
-            throw firstError;
+            if (Result.isFailure(read))
+                return yield* Effect.fail(read.failure);
+            if (firstError)
+                return yield* Effect.fail(firstError.failure);
+        });
     }
     catalogGeneration(id) {
         return this.catalogGenerations.get(id) ?? 0;
@@ -737,20 +802,31 @@ export class Registry {
      * old refresh can finish its storage.set after a credential change deletes
      * the catalog and resurrect the pre-change listing.
      */
-    enqueueCatalogMutation(id, operation) {
-        const previous = this.catalogMutations.get(id) ?? Promise.resolve();
-        const next = previous.catch(() => { }).then(operation);
-        this.catalogMutations.set(id, next);
-        void next
-            .finally(() => {
-            if (this.catalogMutations.get(id) === next) {
+    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)
+                await runEdge(Deferred.await(previous));
+            await runOnPartition(operation, this.opts);
+        }
+        finally {
+            if (this.catalogMutations.get(id) === turn) {
                 this.catalogMutations.delete(id);
             }
-        })
-            .catch(() => { });
-        return next;
+            Deferred.doneUnsafe(turn, Exit.void);
+        }
     }
-    async refreshToolsWithContext(id, connector, ctx, skipPublicationWhenAborted = false) {
+    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
@@ -765,9 +841,10 @@ export class Registry {
         if (skipPublicationWhenAborted && ctx.signal?.aborted)
             return tools;
         // The caller that began this refresh may still use its result, but a
-        // credential/OAuth change that landed while listTools was in flight means
-        // the listing must not enter either shared cache layer.
-        if (generation !== this.catalogGeneration(id))
+        // credential/OAuth change that landed while listTools was in flight, or a
+        // flight abandoned while it listed, means the listing must not enter
+        // either shared cache layer.
+        if (!this.mayPublish(id, generation, flight))
             return tools;
         if (tools.length > MAX_CATALOG_TOOLS) {
             const message = `Connector "${id}" returned ${tools.length} tools, over the ` +
@@ -777,7 +854,7 @@ export class Registry {
         }
         const previous = this.cache.get(id);
         const snapshot = await snapshotCatalog(tools);
-        if (generation !== this.catalogGeneration(id) ||
+        if (!this.mayPublish(id, generation, flight) ||
             (skipPublicationWhenAborted && ctx.signal?.aborted)) {
             return tools;
         }
@@ -801,54 +878,97 @@ export class Registry {
         });
         this.invalidated.delete(id);
         if (shouldPersist) {
-            await this.enqueueCatalogMutation(id, async () => {
-                if (generation !== this.catalogGeneration(id))
-                    return;
-                try {
-                    await this.storeCatalog(id, snapshot);
-                }
-                catch (err) {
-                    this.opts.logger.warn(`[connecta] connector "${id}" catalog persistence failed: ${msg(err)}`);
-                }
-            });
+            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;
     }
     /**
-     * Publish one shared refresh promise before starting its connector work.
-     * The first caller owns the scope and deadline; every later caller joins the
-     * result without gaining access to that context.
+     * 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.
      */
-    startCatalogRefresh(id, generation, start, finish) {
+    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)
-            return existing;
-        let resolveWork;
-        let rejectWork;
-        const work = new Promise((resolve, reject) => {
-            resolveWork = resolve;
-            rejectWork = reject;
-        });
-        let flight;
-        const promise = work
-            .finally(async () => {
-            if (finish)
-                await finish();
-        })
-            .finally(() => {
+        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);
             }
-        });
-        flight = { generation, promise };
-        this.catalogRefreshes.set(id, flight);
-        try {
-            Promise.resolve(start()).then(resolveWork, rejectWork);
-        }
-        catch (err) {
-            rejectWork(err);
+            // 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 };
+    }
+    /**
+     * 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);
         }
-        return flight;
+        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.
+     */
+    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 = {}) {
@@ -857,8 +977,27 @@ export class Registry {
             throw new Error(`Unknown connector "${id}"`);
         if (connector.staticTools)
             return connector.staticTools;
-        const ctx = this.contextFor(id, baseUrl, requestScope, callOptions);
-        return this.startCatalogRefresh(id, this.catalogGeneration(id), () => this.refreshToolsWithContext(id, connector, ctx)).promise;
+        // 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, {
@@ -872,44 +1011,47 @@ export class Registry {
      */
     deferCatalogRefresh(id, baseUrl, expectedGeneration, options) {
         const connector = this.connectors.get(id);
-        if (!connector || connector.staticTools || !options.defer)
+        const defer = options.defer;
+        if (!connector || connector.staticTools || !defer)
             return;
-        let flight = this.catalogRefreshes.get(id);
-        if (flight?.generation !== expectedGeneration)
-            flight = undefined;
-        if (!flight) {
-            const requestScope = {};
-            let ctx;
-            flight = this.startCatalogRefresh(id, expectedGeneration, () => withDeadline((signal) => {
-                const current = this.cache.get(id);
-                if (current && current.exp > Date.now()) {
-                    return Promise.resolve(current.tools);
-                }
-                if (expectedGeneration !== this.catalogGeneration(id) ||
-                    this.invalidated.has(id)) {
-                    return Promise.reject(new Error(`Deferred catalog refresh of "${id}" was invalidated before it started.`));
-                }
-                ctx = this.contextFor(id, baseUrl, requestScope, {
-                    signal,
-                    timeoutMs: options.refreshTimeoutMs,
-                });
-                return this.refreshToolsWithContext(id, connector, ctx, true);
-            }, {
+        // 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,
-                timeoutError: new Error(`deferred catalog refresh of "${id}" timed out after ${options.refreshTimeoutMs}ms`),
-            }), async () => {
-                if (ctx)
-                    await closeConnectorScope(connector, ctx, options.defer);
             });
-        }
-        if (!flight.deferredTail) {
-            // Attach the rejection handler before handing the tail to waitUntil.
-            flight.deferredTail = flight.promise.then(() => { }, (err) => {
-                this.opts.logger.warn(`[connecta] connector "${id}" deferred catalog refresh failed: ${msg(err)}`);
+            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 { 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 {
-            options.defer(flight.deferredTail);
+            defer(flight.deferredTail);
         }
         catch (err) {
             this.opts.logger.warn(`[connecta] connector "${id}" deferred catalog refresh could not attach to the runtime: ${msg(err)}`);
@@ -937,7 +1079,7 @@ export class Registry {
             const generation = this.catalogGeneration(id);
             let persisted = null;
             try {
-                persisted = await this.readCatalog(id, await this.opts.storage.get(this.catalogKey(id)), now);
+                persisted = await runOnPartition(this.readCatalog(id, now), this.opts);
             }
             catch (err) {
                 this.opts.logger.warn(`[connecta] connector "${id}" catalog read failed: ${msg(err)}`);
@@ -1023,9 +1165,15 @@ export class Registry {
      * 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 first caller's context and deadline govern;
-     * later callers join only its result, never its request scope.
+     * 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) {
         const connector = this.connectors.get(id);
@@ -1041,20 +1189,23 @@ export class Registry {
             loads = new Map();
             this.requestCatalogLoads.set(requestScope, loads);
         }
-        const existing = loads.get(id);
-        if (existing)
-            return existing;
-        const loading = this.loadTools(id, baseUrl, requestScope, callOptions, readOptions);
-        loads.set(id, loading);
-        try {
-            return await loading;
-        }
-        finally {
-            if (loads.get(id) === loading)
-                loads.delete(id);
-            if (loads.size === 0)
-                this.requestCatalogLoads.delete(requestScope);
+        const requestLoads = loads;
+        let load = requestLoads.get(id);
+        if (!load) {
+            const started = new SharedRead((signal) => this.loadTools(id, baseUrl, requestScope, { ...callOptions, signal }, readOptions), 
+            // 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.size === 0) {
+                    this.requestCatalogLoads.delete(requestScope);
+                }
+            });
+            requestLoads.set(id, started);
+            load = started;
         }
+        return runEdge(load.join(callOptions.signal));
     }
     async credentialDriftFor(id) {
         const credential = this.connectors.get(id)?.credential;
@@ -1122,14 +1273,7 @@ export class Registry {
         this.invalidated.add(id);
     }
     deleteStoredCatalog(id) {
-        return this.enqueueCatalogMutation(id, async () => {
-            try {
-                await this.deleteCatalog(id);
-            }
-            catch (err) {
-                this.opts.logger.warn(`[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`);
-            }
-        });
+        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). */
     invalidate(id) {
@@ -1186,15 +1330,17 @@ class ScopedRegistryView {
             throw new Error(`Unknown connector "${args[0]}"`);
         }
         const tools = await registry.getTools(...args);
-        const granted = this.scope.toolAccess?.get(args[0]);
+        const guarded = this.scope.guardedToolAccess?.get(args[0]);
+        const granted = this.scope.toolAccess?.get(args[0]) ?? guarded;
         if (!granted)
             return tools;
         // 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));
+        const visible = tools.filter((tool) => granted.has(tool.name) &&
+            (!guarded?.has(tool.name) || isExplicitlyReadOnly(tool)));
         if (visible.length < granted.size) {
-            const present = new Set(visible.map((tool) => tool.name));
+            const present = new Set(tools.map((tool) => tool.name));
             for (const name of granted) {
                 if (!present.has(name))
                     this.root.noteAbsentGrant(args[0], name);
@@ -1206,7 +1352,7 @@ class ScopedRegistryView {
         const registry = this.registryFor(args[0]);
         if (!registry)
             throw new Error(`Unknown connector "${args[0]}"`);
-        return registry.contextFor(...args);
+        return attachCaller(registry.contextFor(...args), this.scope.caller);
     }
     admitCall(...args) {
         const registry = this.registryFor(args[0]);