@zackbart/connecta 0.24.4 → 0.25.0

package/dist/registry.js

@@ -1,19 +1,22 @@
-import { closeConnectorScope, } from "./connector-scope.js";
+import { Cause, Clock, Deferred, Effect, Exit, 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 { closeScopeOnExit } from "./runtime/connector-scope.js";
+import { detach, runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { Logger as LoggerService } from "./runtime/services.js";
+import { runOnPartition, storageDelete, storageGet, storageSet, } from "./runtime/storage.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
@@ -67,6 +70,22 @@ export function resolveMaxResultBytes(value, inherited) {
         : inherited;
 }
 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 +96,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,6 +125,8 @@ 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.
@@ -181,9 +207,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 +378,7 @@ export class Registry {
                 getAll: readValues,
             };
         }
-        return {
+        const context = {
             storage: namespaced(this.opts.storage, `conn:${id}:`),
             logger: this.opts.logger,
             baseUrl,
@@ -354,6 +386,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 +492,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;
+    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; })));
             }
-            finally {
-                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 +636,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,18 +787,29 @@ 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) {
         const generation = this.catalogGeneration(id);
@@ -801,16 +862,12 @@ 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;
     }
@@ -819,36 +876,23 @@ export class Registry {
      * The first caller owns the scope and deadline; every later caller joins the
      * result without gaining access to that context.
      */
-    startCatalogRefresh(id, generation, start, finish) {
+    startCatalogRefresh(id, generation, work) {
         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(() => {
+            return { flight: existing };
+        const flight = {
+            generation,
+            outcome: Deferred.makeUnsafe(),
+        };
+        this.catalogRefreshes.set(id, flight);
+        const owner = Effect.onExit(work, (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);
-        }
-        return flight;
+            // Last, because joined fibers resume inside this call.
+            Deferred.doneUnsafe(flight.outcome, exit);
+        }));
+        return { flight, owner };
     }
     /** Force a live listTools refresh and replace both catalog cache layers. */
     async refreshTools(id, baseUrl, requestScope, callOptions = {}) {
@@ -857,8 +901,14 @@ 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;
+        const { flight, owner } = this.startCatalogRefresh(id, this.catalogGeneration(id), Effect.tryPromise({
+            try: () => this.refreshToolsWithContext(id, connector, this.contextFor(id, baseUrl, requestScope, callOptions)),
+            catch: (error) => error,
+        }));
+        // The owner lists in its own request. A joiner waits through an edge of
+        // its own, and whatever it does with the tools happens after that, back in
+        // its request (see "Effect inside" in documentation/architecture.md).
+        return runEdge(owner ?? Deferred.await(flight.outcome));
     }
     observeCatalogAccess(id, state) {
         this.catalogAccess.set(id, {
@@ -872,44 +922,46 @@ 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 = 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),
+                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, Effect.scoped(refresh));
+        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.
+        flight.deferredTail ??= runEdge(Deferred.await(flight.outcome)).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 +989,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)}`);
@@ -1122,14 +1174,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) {