@zackbart/connecta 0.40.0 → 0.42.0

package/dist/catalog-cache.js

@@ -1,3 +1,5 @@
+import { traceFor } from "./timing-trace.js";
+import { markCatalogGeneration } from "./catalog-freshness.js";
 import { detach, runEdge } from "./runtime/run.js";
 import { Deferred, Effect } from "effect";
 import { authFlow, authCall, authInvoke, authValue, authMethod, authProgram, registerAuth, authStorage, authStorageMany, authMap, authAwait, } from "./auth/native.js";
@@ -236,6 +238,21 @@ export function observeCatalogExpiry(ctx, method, ttlMs, expiresAt, staleFallbac
 // failure for five minutes. Resources never use stale inventories. A fallback
 // carries its original expired deadline and cannot authorize auth recovery.
 const STALE_FALLBACK_MS = 300_000;
+/**
+ * How long past its expiry a complete tool catalog stays listable when its
+ * connector does not answer discovery in time. The listing only: a call always
+ * resolves through STALE_FALLBACK_MS at most. One day matches the longest TTL a
+ * deployment can configure, so this retains nothing it could not already hold.
+ * A refusal retires it sooner, for that credential: see `fenceTools`.
+ */
+const STALE_DISCOVERY_MS = 86_400_000;
+/** A fence outlives every entry it could be keeping from reuse. */
+const CATALOG_FENCE_TTL_SECONDS = (MAX_CACHE_TTL_MS + STALE_DISCOVERY_MS) / 1000;
+/** What a refusal's fence is keyed by, beside the catalog: one credential's slot within one generation. */
+const catalogFenceFingerprint = (sharing, partition, authPartition, credentialIdentity) => authCall(fingerprintSerializedCatalog, [
+    // A shared credential gets one answer whoever asks, so one fence covers all its callers.
+    JSON.stringify(["fence", sharing === "shared" ? authPartition : partition, credentialIdentity ?? null]),
+]);
 /** Catalog chunks one storage read fetches together. */
 const CHUNKS_PER_READ = 8;
 export function attachCatalogCache(ctx, value) {
@@ -446,6 +463,51 @@ function rememberValidated(key, value, bytes) {
     validatedCatalogs.set(key, { value, bytes });
     validatedBytes += bytes;
 }
+const catalogLocation = authMethod((ctx, config, authPartition) => authFlow(function* () {
+    const policy = serviceFor(ctx, CatalogPolicy);
+    const partition = JSON.stringify([
+        policy?.partition ?? JSON.stringify(callerOf(ctx) ?? null),
+        ctx.baseUrl,
+        ctx.publicUrl,
+        authPartition,
+    ]);
+    const sharedPartition = JSON.stringify([
+        "host-shared",
+        policy?.sharedPartition ?? JSON.stringify([ctx.baseUrl, ctx.publicUrl, callerOf(ctx)?.pool]),
+        authPartition,
+    ]);
+    const configHash = (yield authCall(fingerprintSerializedCatalog, [
+        JSON.stringify([
+            config,
+            policy?.defaultTtlMs ?? 300000,
+            policy?.minTtlMs ?? 0,
+            policy?.maxTtlMs ?? MAX_CACHE_TTL_MS,
+        ]),
+    ])).fingerprint;
+    return { partition, sharedPartition, configHash };
+}));
+/** Prefetch candidates only; authority, identity and acceptance stay fresh. */
+export const prefetchCatalog = authMethod((ctx, connectorId, config, authPartition, sharing, credentialIdentity, negotiationKey) => authFlow(function* () {
+    const { partition, sharedPartition, configHash } = yield authCall(catalogLocation, [ctx, config, authPartition]);
+    const slots = sharing === "shared" ? [partition, sharedPartition] : [partition];
+    const suffixes = [
+        (yield catalogFenceFingerprint(sharing, partition, authPartition, credentialIdentity)).fingerprint,
+    ];
+    for (const slot of slots)
+        suffixes.push((yield authCall(fingerprintSerializedCatalog, [
+            JSON.stringify(["tools/list", slot, credentialIdentity ?? null]),
+        ])).fingerprint);
+    const storage = serviceFor(ctx, CatalogPolicy)?.storage ?? ctx.storage;
+    yield ownerReads(Context.get(viewServices(ctx), RequestScope)).prefetch([
+        { storage: ctx.storage, key: negotiationKey },
+        { storage, key: responseCacheKeys.generation(connectorId) },
+    ], (storage, keys) => authStorageMany(storage, keys), {
+        storage,
+        generationKey: responseCacheKeys.generation(connectorId),
+        prefix: responseCacheKeys.locatorPrefix(connectorId, configHash),
+        suffixes,
+    });
+}));
 /** Keys ignore self-reported serverInfo and bind the configured connector instead. */
 export function catalogClientOptions(ctx, connectorId, config, authPartition, connectionSignal, owner, sharing = "private", resolveCredentialIdentity, connectionless = false) {
     return runEdge(authProgram(catalogClientOptionsNative, [
@@ -475,29 +537,11 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
     // canonical request owner, never the initiating call's live services.
     const cacheMethod = (program) => authMethod((...args) => program(...args).pipe(Effect.provideService(RequestScope, request)));
     const policy = serviceFor(ctx, CatalogPolicy);
-    const partition = JSON.stringify([
-        policy?.partition ?? JSON.stringify(callerOf(ctx) ?? null),
-        ctx.baseUrl,
-        ctx.publicUrl,
-        authPartition,
-    ]);
-    const sharedPartition = JSON.stringify([
-        "host-shared",
-        policy?.sharedPartition ?? JSON.stringify([ctx.baseUrl, ctx.publicUrl, callerOf(ctx)?.pool]),
-        authPartition,
-    ]);
+    const { partition, sharedPartition, configHash } = yield authCall(catalogLocation, [ctx, config, authPartition]);
     const storage = policy?.storage ?? ctx.storage;
     let storeIdentity = catalogStores.get(storage);
     if (!storeIdentity)
         catalogStores.set(storage, (storeIdentity = crypto.randomUUID()));
-    const configHash = (yield authCall(fingerprintSerializedCatalog, [
-        JSON.stringify([
-            config,
-            policy?.defaultTtlMs ?? 300000,
-            policy?.minTtlMs ?? 0,
-            policy?.maxTtlMs ?? MAX_CACHE_TTL_MS,
-        ]),
-    ])).fingerprint;
     const scope = cacheScope(ctx, connectorId, owner);
     let unavailable = false;
     const connectionGeneration = {};
@@ -597,6 +641,58 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
         ])).fingerprint;
         return stopped() ? undefined : responseCacheKeys.entry(prefix, digest);
     }));
+    const fenceKey = cacheMethod((operation, generation) => authFlow(function* () {
+        const { fingerprint } = (yield catalogFenceFingerprint(sharing, partition, authPartition, operation.credentialIdentity));
+        return responseCacheKeys.entry(responseCacheKeys.namespace(connectorId, configHash, generation), fingerprint);
+    }));
+    // Whether an expired catalog may stand in now. Read past this request's
+    // memo: a refusal or invalidation in another isolate retires it at once.
+    const staleAllowed = cacheMethod((operation) => authFlow(function* () {
+        if (operation.stopped() || !(yield authCall(namespace, [operation])))
+            return false;
+        const key = (yield authCall(fenceKey, [operation, operation.generation.value]));
+        const fence = (yield authCall(operation.io, [
+            cacheMethod(() => reads.read(storage, key, authStorage(storage, "get", [key]), true)),
+        ]));
+        return fence === null && !operation.stopped();
+    }));
+    // Read before the listing dispatches: a refusal after this point writes a
+    // value this listing never saw. An older memoized read only lifts less.
+    const readListingFence = cacheMethod((operation) => authFlow(function* () {
+        const { listing, stopped, io } = operation;
+        if (!listing || listing.fence !== undefined || stopped())
+            return;
+        // A generation claimed later holds no fence this listing could know of.
+        if (!listing.generationStored) {
+            listing.fence = null;
+            return;
+        }
+        const key = (yield authCall(fenceKey, [operation, listing.generation.value]));
+        listing.fence = (yield authCall(io, [
+            cacheMethod(() => reads.read(storage, key, authStorage(storage, "get", [key]))),
+        ]));
+    }));
+    // A complete listing's answer lifts the fence captured before it was
+    // asked, and only that one: a refusal that landed while it ran wrote
+    // another, which stays. With nothing captured it lifts nothing, so the
+    // next listing that reads the fence first does it instead.
+    const liftFence = cacheMethod((operation) => authFlow(function* () {
+        const { listing, stopped, io } = operation;
+        if (!listing?.fence || stopped())
+            return;
+        try {
+            const key = (yield authCall(fenceKey, [operation, operation.generation.value]));
+            const lifted = (yield authCall(io, [
+                cacheMethod(() => authStorage(storage, "compareAndSet", [key, listing.fence, null])),
+            ]));
+            if (lifted)
+                listing.fence = null;
+        }
+        catch (error) {
+            if (!stopped())
+                logFailure(ctx.logger, "catalog fence failed", failureRecord({ connector: connectorId }, error));
+        }
+    }));
     const manifest = (raw) => {
         if (!raw)
             return undefined;
@@ -676,6 +772,8 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
         get: cacheMethod((key) => authFlow(function* () {
             const operation = capture();
             const { ctx, stopped, io } = operation;
+            const trace = traceFor(ctx.requestScope);
+            trace?.record("catalog.cache.lookup");
             const root = (yield authCall(address, [key, operation]));
             if (!root || stopped())
                 return undefined;
@@ -692,10 +790,18 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                     ]));
                     roots.push(responseCacheKeys.entry(responseCacheKeys.namespace(connectorId, configHash, operation.generation.value), fingerprint));
                 }
-                const values = (yield authCall(io, [cacheMethod(() => authStorageMany(storage, roots))]));
+                const fence = (yield authCall(fenceKey, [operation, operation.generation.value]));
+                yield reads.prefetch([...roots, fence].map((key) => ({ storage, key })), (storage, keys) => authStorageMany(storage, keys));
+                (yield authCall(readListingFence, [operation]));
+                const values = [];
+                for (const root of roots)
+                    values.push(yield reads.read(storage, root, authStorage(storage, "get", [root])));
                 listing.manifests ??= new Map();
                 roots.forEach((root, i) => listing.manifests.set(root, values[i] ?? null));
             }
+            // A refused credential is listed anew, whatever its catalog's age.
+            if (listing?.fence && key.method === "tools/list")
+                return undefined;
             const m = manifest(listing?.manifests?.has(root)
                 ? listing.manifests.get(root)
                 : (yield authCall(io, [
@@ -704,7 +810,7 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             if (stopped() ||
                 !m ||
                 (m.expiresAt <= Date.now() &&
-                    (key.method !== "tools/list" || m.expiresAt + STALE_FALLBACK_MS <= Date.now())))
+                    (key.method !== "tools/list" || m.expiresAt + STALE_DISCOVERY_MS <= Date.now())))
                 return undefined;
             // Up to CHUNKS_PER_READ chunks per round trip, so one answer stays a
             // few megabytes; the generation fence below still decides whether
@@ -735,8 +841,10 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             // Hash the chunks again above, never trust the manifest alone.
             const reuseKey = JSON.stringify([storeIdentity, root, partition, m.fingerprint]);
             let accepted = validatedCatalogs.get(reuseKey)?.value;
+            trace?.record(accepted ? "catalog.validated.hit" : "catalog.validated.miss");
             if (!accepted) {
                 const result = JSON.parse(value);
+                trace?.record("catalog.decode", 0, fingerprint.byteLength);
                 const items = catalogItems(method, result);
                 if (!Array.isArray(items) ||
                     items.length > MAX_CATALOG_TOOLS ||
@@ -744,6 +852,7 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                     (result.resultType !== undefined && result.resultType !== "complete"))
                     return undefined;
                 const validated = (yield authInvoke(catalogSchema(method)["~standard"], "validate", [result]));
+                trace?.record("catalog.validate");
                 if (stopped() || validated.issues)
                     return undefined;
                 accepted = validated.value;
@@ -751,12 +860,16 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             // Redaction depends on this request's sent credentials. It must
             // still run, and returns detached objects from the frozen facts.
             const clean = intake(ctx, method, accepted);
+            trace?.record("catalog.intake");
+            trace?.record("catalog.chunks", 0, fingerprint.byteLength, 0, 0, m.chunkCount);
             rememberValidated(reuseKey, accepted, fingerprint.byteLength);
             if (m.expiresAt <= Date.now()) {
+                trace?.record("catalog.cache.expired");
                 if (method === "tools/list" && (!staleTools || staleTools.manifest.fetchedAt < m.fetchedAt))
                     staleTools = { result: clean, manifest: m };
                 return undefined;
             }
+            trace?.record("catalog.cache.hit");
             observeCatalogFetch(ctx, m.fetchedAt, method);
             observeCatalogExpiry(ctx, method, clean.ttlMs, m.expiresAt);
             return { value: JSON.stringify(clean), stamp: m.stamp, expiresAt: m.expiresAt, scope: m.scope };
@@ -775,6 +888,8 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                     (yield authCall(io, [
                         cacheMethod(() => authStorage(storage, "delete", [root])),
                     ]));
+                if (method === "tools/list")
+                    (yield authCall(liftFence, [operation]));
                 return 0;
             }
             if (!Array.isArray(catalogItems(method, result)) ||
@@ -794,7 +909,7 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
             let offset = 0;
             let chunkCount = 0;
-            const ttlSeconds = () => Math.max(0.001, (expiresAt + (method === "tools/list" ? STALE_FALLBACK_MS : 0) - Date.now()) / 1000);
+            const ttlSeconds = () => Math.max(0.001, (expiresAt + (method === "tools/list" ? STALE_DISCOVERY_MS : 0) - Date.now()) / 1000);
             while (offset < bytes.length) {
                 if (stopped() || expiresAt <= Date.now())
                     return 0;
@@ -846,6 +961,27 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                     return 0;
                 if (published) {
                     lastStamp = stamp;
+                    // Tool chunks outlive their manifest by the stale limit, so a
+                    // superseded revision is removed now rather than retained for
+                    // a day. A reader holding it misses and lists again; a failed
+                    // removal leaves the chunks to their TTL.
+                    const superseded = manifest(previous);
+                    if (superseded && superseded.revision !== revision) {
+                        try {
+                            for (let index = 0; index < superseded.chunkCount && !stopped(); index++)
+                                (yield authCall(io, [
+                                    cacheMethod(() => authStorage(storage, "delete", [
+                                        responseCacheKeys.chunk(root, superseded.revision, index),
+                                    ])),
+                                ]));
+                        }
+                        catch (error) {
+                            if (!stopped())
+                                logFailure(ctx.logger, "catalog chunk cleanup failed", failureRecord({ connector: connectorId }, error));
+                        }
+                    }
+                    if (method === "tools/list")
+                        (yield authCall(liftFence, [operation]));
                     return stamp;
                 }
             }
@@ -891,7 +1027,7 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
     // The queue retains only a Promise turn. Awaiting it in this caller's
     // request preserves workerd I/O ownership; the listing program stays native.
     let tail = Promise.resolve();
-    const withListing = cacheMethod((listingCtx, read) => authFlow(function* () {
+    const withListing = cacheMethod((listingCtx, read, bound) => authFlow(function* () {
         const previous = tail;
         let release;
         tail = new Promise((resolve) => {
@@ -912,9 +1048,17 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             staleTools = undefined;
             const operation = capture();
             try {
-                if (resolveCredentialIdentity)
+                if (bound && "credentialIdentity" in bound)
+                    listing.credentialIdentity = bound.credentialIdentity;
+                else if (resolveCredentialIdentity)
                     listing.credentialIdentity = yield authInvoke(operation, "io", [resolveCredentialIdentity]);
-                if (!operation.stopped()) {
+                if (bound?.fence !== undefined)
+                    listing.fence = bound.fence;
+                if (bound?.generationStored !== undefined) {
+                    listing.generationStored = bound.generationStored;
+                    listing.generation.value = bound.generation;
+                }
+                else if (!operation.stopped()) {
                     try {
                         // Memoized: it locates the listing's entries, which the
                         // fresh fence in get accepts or refuses.
@@ -933,7 +1077,9 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                         logFailure(listingCtx.logger, "catalog read failed", failureRecord({ connector: connectorId }, error));
                     }
                 }
-                return yield authCall(read, []);
+                const result = yield authCall(read, []);
+                markCatalogGeneration(listingCtx.requestScope, connectorId, listing.generation.value);
+                return result;
             }
             finally {
                 listing.ended = true;
@@ -948,6 +1094,24 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                 void previous.then(release);
         }
     }));
+    // Capture what an attempt is about to run under. `pinned` names a
+    // credential the caller has already read for it.
+    const bindListing = cacheMethod((listingCtx, pinned, readFence = false) => authCall(withListing, [
+        listingCtx,
+        cacheMethod(() => authFlow(function* () {
+            const operation = capture();
+            if (readFence)
+                (yield authCall(readListingFence, [operation]));
+            const listing = operation.listing;
+            return {
+                credentialIdentity: listing.credentialIdentity,
+                generation: listing.generation.value,
+                generationStored: listing.generationStored ?? false,
+                fence: listing.fence,
+            };
+        })),
+        pinned,
+    ]));
     // A complete, unexpired tools/list entry, read before any connection
     // exists. This is the SDK's own two-probe read: the private slot
     // `[serverIdentity, cachePartition]`, then a shared connector's public
@@ -976,12 +1140,101 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             return Array.isArray(result.tools) ? result : undefined;
         })),
     ]));
+    // The newest complete tools/list entry this caller could be served, fresh
+    // or within STALE_DISCOVERY_MS of expiry, with its original times. Reads
+    // only, through the same address, fingerprint, generation and credential
+    // fences as a listing, so another owner's entry, an invalidated generation
+    // or a rotated credential is a miss. Never a source for call resolution.
+    const peekTools = cacheMethod((listingCtx, serverIdentity = "") => authCall(withListing, [
+        listingCtx,
+        cacheMethod(() => authFlow(function* () {
+            if (!active?.generationStored)
+                return undefined;
+            const read = (slot) => authInvoke(store, "get", [
+                { method: "tools/list", params: "", partition: JSON.stringify([serverIdentity, slot]) },
+            ]);
+            let entry = (yield read(partition));
+            let stale = staleTools;
+            if (entry === undefined && sharing === "shared") {
+                staleTools = undefined;
+                const shared = (yield read(""));
+                entry = shared?.scope === "public" ? shared : undefined;
+                // Set by the read above, which control flow analysis cannot see.
+                const sharedStale = staleTools;
+                if (sharedStale?.manifest.scope === "public" &&
+                    (!stale || stale.manifest.fetchedAt < sharedStale.manifest.fetchedAt))
+                    stale = sharedStale;
+            }
+            if (entry?.expiresAt !== undefined && entry.expiresAt > Date.now()) {
+                const result = JSON.parse(entry.value);
+                if (!Array.isArray(result.tools))
+                    return undefined;
+                return {
+                    result,
+                    fetchedAt: catalogFetchedAt(listingCtx) ?? Date.now(),
+                    expiresAt: entry.expiresAt,
+                };
+            }
+            const operation = capture();
+            if (!stale ||
+                !(yield authCall(staleAllowed, [operation])) ||
+                stale.manifest.expiresAt + STALE_DISCOVERY_MS <= Date.now())
+                return undefined;
+            return { result: stale.result, fetchedAt: stale.manifest.fetchedAt, expiresAt: stale.manifest.expiresAt };
+        })),
+    ]));
+    // The downstream refused this credential, which says more than a TTL can:
+    // nothing cached for it may stand in again until a listing succeeds. One
+    // key beside the catalog, durable across requests and isolates, in the
+    // namespace of the generation the refused attempt ran under, so a change
+    // of credential or a disconnect discards it with the entries it guards. An
+    // attempt that found no generation fences the one claimed since, if any:
+    // that is where a listing beside it published. Nothing is stored while no
+    // generation is, since then nothing is cached to retire. A failed write is
+    // logged and never masks the refusal.
+    const writeFence = cacheMethod((operation) => authFlow(function* () {
+        const { listing, stopped, io } = operation;
+        if (!listing || stopped())
+            return;
+        try {
+            const generation = listing.generationStored
+                ? listing.generation.value
+                : (yield authCall(io, [cacheMethod(() => generationRead(false))]));
+            if (!generation || stopped())
+                return;
+            const key = (yield authCall(fenceKey, [operation, generation]));
+            (yield authCall(io, [
+                cacheMethod(() => authStorage(storage, "set", [
+                    key,
+                    crypto.randomUUID(),
+                    { ttlSeconds: CATALOG_FENCE_TTL_SECONDS },
+                ])),
+            ]));
+        }
+        catch (error) {
+            if (!stopped())
+                logFailure(ctx.logger, "catalog fence failed", failureRecord({ connector: connectorId }, error));
+        }
+    }));
+    // The refusal of the listing now running, as that listing was bound.
+    const fenceListing = cacheMethod(() => authCall(writeFence, [capture()]));
+    // The refusal of an attempt bound earlier, outside any listing.
+    const fenceTools = cacheMethod((listingCtx, bound) => authCall(withListing, [listingCtx, cacheMethod(() => authCall(writeFence, [capture()])), bound]));
+    // For a listing that never reads the cache before it dispatches.
+    const captureFence = cacheMethod(() => authFlow(function* () {
+        const operation = capture();
+        try {
+            (yield authCall(readListingFence, [operation]));
+        }
+        catch (error) {
+            if (!operation.stopped())
+                logFailure(ctx.logger, "catalog fence failed", failureRecord({ connector: connectorId }, error));
+        }
+    }));
     const fallbackTools = cacheMethod(() => authFlow(function* () {
         const operation = capture();
         if (!staleTools ||
-            operation.stopped() ||
-            !(yield authCall(namespace, [operation])) ||
-            operation.stopped() ||
+            !(yield authCall(staleAllowed, [operation])) ||
             staleTools.manifest.expiresAt + STALE_FALLBACK_MS <= Date.now())
             return;
         const { result, manifest } = staleTools;
@@ -994,6 +1247,11 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
         completeCatalogRefresh,
         fallbackTools,
         cachedTools,
+        peekTools,
+        bindListing,
+        captureFence,
+        fenceListing,
+        fenceTools,
         responseCacheStore: store,
         cachePartition: partition,
         defaultCacheTtlMs: policy?.defaultTtlMs ?? CONFIG_DEFAULTS.discovery.catalogTtlSeconds * 1000,
@@ -1005,36 +1263,54 @@ function isCatalogMethod(method) {
     return method === "tools/list" || method === "resources/list" || method === "resources/templates/list";
 }
 function customCatalogCache(ctx, connectorId) {
-    return runEdge(authProgram(customCatalogCacheNative, [
-        ctx,
-        connectorId,
-    ]));
+    return runEdge(authProgram(customCatalogCacheNative, [ctx, connectorId]));
 }
-const customCatalogCacheNative = /* @__PURE__ */ registerAuth(customCatalogCache, (ctx, connectorId) => authFlow(function* () {
+const customCatalogAuth = authMethod((ctx) => authFlow(function* () {
     const credential = (yield authValue(() => ctx.credential?.getAll()));
     // Credential values enter the stored partition only through a keyed digest.
-    const auth = credential == null
+    return credential == null
         ? (yield authCall(fingerprintSerializedCatalog, ["null"])).fingerprint
         : (yield authCall(secretDigest, [ctx, JSON.stringify(credential)]));
+}));
+const customCatalogCacheNative = /* @__PURE__ */ registerAuth(customCatalogCache, (ctx, connectorId) => authFlow(function* () {
+    const auth = (yield authCall(customCatalogAuth, [ctx]));
     const cache = (yield authCall(catalogClientOptions, [ctx, connectorId, "custom-connector", auth]));
     const key = {
         method: "tools/list",
         partition: JSON.stringify(["custom-connector", cache.cachePartition]),
     };
-    return { cache, key };
+    return { cache, key, auth };
 }));
-/** Custom listings always fetch. Only an authenticated owner may retain a
- * complete private fallback; unscoped/operator reads start no cache I/O. */
-export function storeCustomCatalogFallback(ctx, connectorId, tools) {
-    return runEdge(authProgram(storeCustomCatalogFallbackNative, [ctx, connectorId, tools]));
+/**
+ * Before a custom listing dispatches: only an authenticated owner may retain a
+ * complete private fallback, and unscoped/operator reads start no cache I/O.
+ * Its answer is recorded against this ticket, never a later read of the store.
+ */
+export function bindCustomCatalogListing(ctx, connectorId) {
+    return runEdge(authProgram(bindCustomCatalogListingNative, [ctx, connectorId]));
+}
+const bindCustomCatalogListingNative = /* @__PURE__ */ registerAuth(bindCustomCatalogListing, (ctx, connectorId) => authFlow(function* () {
+    if (!catalogTtlMs(ctx, undefined) || !callerOf(ctx)?.authenticated)
+        return;
+    const custom = (yield authCall(customCatalogCache, [ctx, connectorId]));
+    const bound = (yield authInvoke(custom.cache, "bindListing", [ctx, undefined, true]));
+    return { ...custom, bound };
+}));
+/** Custom listings always fetch; the ticket says whether and where one is retained. */
+export function storeCustomCatalogFallback(ctx, tools, listing) {
+    return runEdge(authProgram(storeCustomCatalogFallbackNative, [ctx, tools, listing]));
 }
-const storeCustomCatalogFallbackNative = /* @__PURE__ */ registerAuth(storeCustomCatalogFallback, (ctx, connectorId, tools) => authFlow(function* () {
+const storeCustomCatalogFallbackNative = /* @__PURE__ */ registerAuth(storeCustomCatalogFallback, (ctx, tools, listing) => authFlow(function* () {
     const ttlMs = catalogTtlMs(ctx, undefined);
     observeCatalogFetch(ctx, Date.now());
     observeCatalogExpiry(ctx, "tools/list", ttlMs);
-    if (!ttlMs || !callerOf(ctx)?.authenticated)
+    if (!ttlMs || !listing)
         return;
-    const { cache, key } = (yield authCall(customCatalogCache, [ctx, connectorId]));
+    // The connector read its own credential, so a change while it ran leaves
+    // this answer belonging to neither: it is retained for neither.
+    if ((yield authCall(customCatalogAuth, [ctx])) !== listing.auth)
+        return;
+    const { cache, key, bound } = listing;
     (yield authInvoke(cache, "withListing", [
         ctx,
         authMethod(() => authFlow(function* () {
@@ -1055,8 +1331,41 @@ const storeCustomCatalogFallbackNative = /* @__PURE__ */ registerAuth(storeCusto
                 },
             ]));
         })),
+        bound,
     ]));
 }));
+/** A custom connector's retained catalog, for discovery only. Same owner rule as its fallback. */
+export function customCatalogPeek(ctx, connectorId) {
+    return runEdge(authProgram(customCatalogPeekNative, [ctx, connectorId]));
+}
+const customCatalogPeekNative = /* @__PURE__ */ registerAuth(customCatalogPeek, (ctx, connectorId) => authFlow(function* () {
+    if (!callerOf(ctx)?.authenticated)
+        return;
+    const { cache } = (yield authCall(customCatalogCache, [ctx, connectorId]));
+    const entry = (yield authInvoke(cache, "peekTools", [ctx, "custom-connector"]));
+    return entry
+        ? { tools: entry.result.tools, fetchedAt: entry.fetchedAt, expiresAt: entry.expiresAt }
+        : undefined;
+}));
+/**
+ * A custom connector's refusal. It reads its own credential, by any route, so
+ * only one unchanged since the ticket identifies what was refused: that
+ * catalog stands in for nothing until a listing succeeds. A change, or a failed
+ * read, leaves it unknown, so every catalog retained for this connector goes.
+ */
+export function fenceCustomCatalog(ctx, connectorId, listing) {
+    return runEdge(authProgram(fenceCustomCatalogNative, [ctx, connectorId, listing]));
+}
+const fenceCustomCatalogNative = /* @__PURE__ */ registerAuth(fenceCustomCatalog, (ctx, connectorId, listing) => authFlow(function* () {
+    const current = (yield authCall(customCatalogAuth, [ctx]).pipe(Effect.catch(() => Effect.succeed(undefined))));
+    if (current === listing.auth)
+        (yield authInvoke(listing.cache, "fenceTools", [ctx, listing.bound]));
+    else
+        (yield authCall(invalidateCatalogCache, [
+            serviceFor(ctx, CatalogPolicy)?.storage ?? ctx.storage,
+            connectorId,
+        ]));
+}));
 export function customCatalogFallback(ctx, connectorId) {
     return runEdge(authProgram(customCatalogFallbackNative, [ctx, connectorId]));
 }

package/dist/catalog-freshness.js

@@ -6,8 +6,33 @@ export function markCatalogFreshness(tools, freshUntil) {
     return tools;
 }
 export function carryCatalogFreshness(source, copy) {
+    const stale = staleCatalogs.get(source);
+    if (stale)
+        staleCatalogs.set(copy, stale);
     return markCatalogFreshness(copy, deadlines.get(source) ?? 0);
 }
+const staleCatalogs = new WeakMap();
+/** Host-only, beside freshness: a stale listing is never fresh and never grants anything. */
+export function markCatalogStale(tools, staleness) {
+    staleCatalogs.set(tools, staleness);
+    return tools;
+}
+export function catalogStaleness(tools) {
+    return staleCatalogs.get(tools);
+}
 export function catalogIsFresh(tools) {
     return (deadlines.get(tools) ?? 0) > Date.now();
 }
+// Primitive accepted-generation evidence lives only beside the current request.
+const generations = new WeakMap();
+export function markCatalogGeneration(scope, connector, generation) {
+    if (!scope || generation === undefined)
+        return;
+    let values = generations.get(scope);
+    if (!values)
+        generations.set(scope, (values = new Map()));
+    values.set(connector, generation);
+}
+export function catalogGenerationFor(scope, connector) {
+    return generations.get(scope)?.get(connector);
+}