@zackbart/connecta 0.33.0 → 0.34.1

package/dist/catalog-drift.d.ts

@@ -1,12 +1,11 @@
 import type { CatalogDriftCounts, CatalogDriftReport, Connector, Logger, ToolClassification, ToolDef } from "./types.js";
 /**
- * Rebuild a drift report as bounded counts and a canonical timestamp.
+ * Rebuild a drift report as bounded counts, closed verification facts, and a timestamp.
  *
  * `Connector.catalogDrift()` sits on the open plugin seam, and what it returns
- * lands in the body of unauthenticated `/health`, on connector status, in the
- * operator page, and in `connecta doctor`. TypeScript constrains neither an
- * extra enumerable property nor what `observedAt` holds at runtime, so "counts
- * and a time and nothing else" is *made* true here — at the boundary where
+ * lands on authenticated connector status and the operator page. TypeScript
+ * constrains neither extra enumerable properties nor `observedAt` at runtime.
+ * Counts, closed verification facts, and a time are rebuilt at the boundary where
  * third-party output becomes a response — rather than trusted. A report whose
  * `observedAt` names no instant is no observation connecta can date, and is
  * dropped whole (INV-6): a plugin forwarding a downstream's report could
@@ -29,11 +28,12 @@ interface VettedToolRecord {
      * Digest of the input and output schemas that release read, or undefined
      * when no release has recorded them. Undefined is not "unchanged": a
      * manifest with no digest cannot report a schema change, and says so by
-     * counting none. The credential-free provider check does not create or
-     * update schema digests; the live `tools/list` response remains the schema
+     * counting none and reporting the unpinned coverage. The provider check never
+     * creates or updates schema digests; live `tools/list` remains the schema
      * agents receive ([#351](https://github.com/zackbart/connecta/issues/351)).
      */
     schemaDigest?: string;
+    optional?: boolean;
 }
 /**
  * The vetted manifest one hosted-MCP proxy ships: every tool name a release
@@ -59,6 +59,8 @@ export interface VettedCatalogInput {
      * read them; an invented digest reports drift that never happened.
      */
     schemaDigests?: Readonly<Record<string, string>>;
+    /** Reviewed names that may be absent under plan/permission gating. */
+    optionalTools?: ReadonlySet<string>;
 }
 /**
  * Digest the schemas of one downstream tool.
@@ -67,13 +69,17 @@ export interface VettedCatalogInput {
  * `src/catalog-fingerprint.ts`: that one is deliberately conservative because a
  * spurious cache write is cheap, while a spurious drift finding spends a
  * maintainer's attention on a downstream that reordered its JSON keys.
+ * New pins use `sha256-sets-v1:` and sort required, enum, and type arrays only
+ * at schema keyword locations. Tuple arrays and JSON data keep their order.
+ * Legacy `sha256:` pins use the original literal-array form, so an upgrade
+ * cannot silently invalidate a reviewed provider manifest.
  * Description and annotations are excluded — a reworded description is P1's
  * business, and an annotation change is already its own drift category.
  *
  * Rejects rather than digesting part of a schema: a digest that ignored some
  * leaf would let a reviewed read keep its verdict after that leaf changed.
  */
-export declare function vettedSchemaDigest(tool: ToolDef): Promise<string>;
+export declare function vettedSchemaDigest(tool: ToolDef, format?: "sets-v1" | "legacy"): Promise<string>;
 /**
  * Build a provider's manifest from the lists it already maintains.
  *
@@ -92,6 +98,11 @@ export declare function reviewedCatalog(classification: ToolClassification, owne
  * after review.
  */
 export declare function reviewedClassification(classification: ToolClassification, owner: string): ToolClassification;
+/** One whole-schema verification shared by reporting and serving this listing. */
+export interface CatalogSchemaVerification {
+    changed: ReadonlySet<string>;
+    available: boolean;
+}
 /**
  * Compare a live catalog with the manifest and count what moved.
  *
@@ -110,25 +121,18 @@ export declare function catalogReviewOf(connector: Connector): VettedCatalog | u
  * Classify downstream facts with a review: what the registry serves on every
  * read, from whichever cache layer the facts came from.
  *
- * Every tool returned is a fresh object, so nothing a caller does to one can
- * reach the facts, `memo`, or a later read. `memo` holds digest verification
- * per facts array; the registry passes one only for deep-frozen arrays it
- * owns. A failed verification is not kept, so the next read tries again, and
- * meanwhile no digested review vouches for a read (INV-1).
+ * Every tool returned is fresh. The registry supplies the same whole-schema
+ * verification it observed for this listing, including failures. Standalone
+ * callers verify here. No failed verification survives onto a later listing,
+ * and meanwhile no digested review vouches for a read (INV-1).
  */
-export declare function classifyCatalog(catalog: VettedCatalog, connectorId: string, facts: readonly ToolDef[], logger: Logger, memo?: WeakMap<readonly ToolDef[], ReadonlySet<string>>, overrides?: Readonly<Record<string, "read" | "write">>): Promise<ToolDef[]>;
+export declare function classifyCatalog(catalog: VettedCatalog, connectorId: string, facts: readonly ToolDef[], logger: Logger, overrides?: Readonly<Record<string, "read" | "write">>, verification?: CatalogSchemaVerification): Promise<ToolDef[]>;
 /**
- * Compare a listing a refresh just received with the connector's review, and
- * keep the counts as its latest observation.
- *
- * The check happens where the tools are already in hand, while serving a
- * refresh the deployment asked for. It adds no request of its own, which is
- * the whole boundary: connecta watches a contract while it is serving a
- * refresh, and never initiates one to go looking
- * ([#179](https://github.com/zackbart/connecta/issues/179),
- * [#343](https://github.com/zackbart/connecta/issues/343)).
+ * Observe tools already fetched by a listing. No probe, persistence, or catalog
+ * payload: registry-owned partition tokens isolate deployment and subject.
+ * A digest failure replaces old success, while classification fails closed.
  */
-export declare function observeReviewedDrift(connector: Connector, catalog: VettedCatalog, listed: readonly ToolDef[], logger: Logger): Promise<void>;
-/** The latest drift {@link observeReviewedDrift} kept for `connector`. */
-export declare function observedCatalogDrift(connector: Connector): CatalogDriftReport | undefined;
+export declare function observeReviewedDrift(connector: Connector, catalog: VettedCatalog | undefined, listed: readonly ToolDef[], logger: Logger, partition?: object, droppedTools?: number): Promise<CatalogSchemaVerification | undefined>;
+/** Look up only this runtime/catalog partition; never start a listing. */
+export declare function observedCatalogDrift(connector: Connector, partition?: object): CatalogDriftReport | undefined;
 export {};

package/dist/catalog-drift.js

@@ -20,13 +20,12 @@ function observationTime(value) {
     return Number.isFinite(time) ? new Date(time).toISOString() : undefined;
 }
 /**
- * Rebuild a drift report as bounded counts and a canonical timestamp.
+ * Rebuild a drift report as bounded counts, closed verification facts, and a timestamp.
  *
  * `Connector.catalogDrift()` sits on the open plugin seam, and what it returns
- * lands in the body of unauthenticated `/health`, on connector status, in the
- * operator page, and in `connecta doctor`. TypeScript constrains neither an
- * extra enumerable property nor what `observedAt` holds at runtime, so "counts
- * and a time and nothing else" is *made* true here — at the boundary where
+ * lands on authenticated connector status and the operator page. TypeScript
+ * constrains neither extra enumerable properties nor `observedAt` at runtime.
+ * Counts, closed verification facts, and a time are rebuilt at the boundary where
  * third-party output becomes a response — rather than trusted. A report whose
  * `observedAt` names no instant is no observation connecta can date, and is
  * dropped whole (INV-6): a plugin forwarding a downstream's report could
@@ -41,6 +40,18 @@ export function boundedCatalogDrift(report) {
         return undefined;
     return {
         observedAt,
+        ...(typeof report.reviewedBaseline === "boolean" ? { reviewedBaseline: report.reviewedBaseline } : {}),
+        ...(report.verification === "complete" || report.verification === "unavailable"
+            ? { verification: report.verification }
+            : {}),
+        ...(report.schemaCoverage && typeof report.schemaCoverage === "object"
+            ? {
+                schemaCoverage: {
+                    pinned: boundedCount(report.schemaCoverage.pinned),
+                    unpinned: boundedCount(report.schemaCoverage.unpinned),
+                },
+            }
+            : {}),
         unclassifiedTools: boundedCount(report.unclassifiedTools),
         unservedTools: boundedCount(report.unservedTools),
         annotationConflicts: boundedCount(report.annotationConflicts),
@@ -66,59 +77,98 @@ function canonicalKeys(value) {
     const sorted = Object.fromEntries(entries);
     return Object.keys(sorted).map((key) => [key, sorted[key]]);
 }
-/**
- * Deterministic JSON with object keys sorted, so key order is not a schema
- * change. Iterative and complete: every leaf at every depth reaches the
- * digest, and a schema deeper than the host stack cannot exhaust it. Throws
- * past {@link MAX_SCHEMA_DIGEST_NODES}, and on any value JSON cannot carry.
- */
-function canonicalJson(root) {
+const SCHEMA_MAPS = new Set([
+    "properties",
+    "patternProperties",
+    "$defs",
+    "definitions",
+    "dependentSchemas",
+    "dependencies",
+]);
+const SCHEMA_ARRAYS = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+const SCHEMA_CHILDREN = new Set([
+    "items",
+    "additionalItems",
+    "additionalProperties",
+    "unevaluatedProperties",
+    "unevaluatedItems",
+    "contains",
+    "propertyNames",
+    "not",
+    "if",
+    "then",
+    "else",
+    "contentSchema",
+]);
+function childMode(mode, key, value) {
+    if (mode === "root" || mode === "map")
+        return "schema";
+    if (mode !== "schema")
+        return "data";
+    if (key === "required" || key === "enum" || key === "type")
+        return "set";
+    if (SCHEMA_MAPS.has(key))
+        return "map";
+    if (SCHEMA_ARRAYS.has(key) || (key === "items" && Array.isArray(value)))
+        return "schema-array";
+    return SCHEMA_CHILDREN.has(key) ? "schema" : "data";
+}
+function canonicalJson(root, sets) {
     const out = [];
-    const stack = [{ value: root }];
+    const stack = [{ value: root, mode: sets ? "root" : "data", out }];
     let nodes = 0;
     while (stack.length > 0) {
         const task = stack.pop();
+        const out = task.out;
         if ("text" in task) {
             out.push(task.text);
             continue;
         }
-        if (++nodes > MAX_SCHEMA_DIGEST_NODES) {
-            throw new Error(`schema has more than ${MAX_SCHEMA_DIGEST_NODES} values; refusing to digest it in part.`);
+        if ("members" in task) {
+            out.push("[", task.members
+                .map((member) => member.join(""))
+                .sort()
+                .join(","), "]");
+            continue;
         }
-        const value = task.value;
-        if (value === null || value === undefined) {
+        if (++nodes > MAX_SCHEMA_DIGEST_NODES)
+            throw new Error(`schema has more than ${MAX_SCHEMA_DIGEST_NODES} values; refusing to digest it in part.`);
+        const { value, mode } = task;
+        if (value === null || value === undefined)
             out.push("null");
-        }
-        else if (typeof value === "string" || typeof value === "boolean") {
+        else if (typeof value === "string" || typeof value === "boolean")
             out.push(JSON.stringify(value));
-        }
-        else if (typeof value === "number") {
+        else if (typeof value === "number")
             out.push(Number.isFinite(value) ? JSON.stringify(value) : "null");
-        }
-        else if (typeof value === "function" || typeof value === "symbol") {
-            // Only array items reach here; object keys holding these are dropped.
+        else if (typeof value === "function" || typeof value === "symbol")
             out.push("null");
-        }
-        else if (typeof value !== "object") {
+        else if (typeof value !== "object")
             throw new Error(`schema holds a ${typeof value}, which JSON cannot carry.`);
-        }
         else if (Array.isArray(value)) {
-            out.push("[");
-            stack.push({ text: "]" });
-            for (let index = value.length - 1; index >= 0; index -= 1) {
-                stack.push({ value: value[index] });
-                if (index > 0)
-                    stack.push({ text: "," });
+            if (mode === "set") {
+                const members = Array.from({ length: value.length }, () => []);
+                stack.push({ members, out });
+                for (let index = value.length - 1; index >= 0; index--)
+                    stack.push({ value: value[index], mode: "data", out: members[index] });
+            }
+            else {
+                out.push("[");
+                stack.push({ text: "]", out });
+                for (let index = value.length - 1; index >= 0; index--) {
+                    stack.push({ value: value[index], mode: mode === "schema-array" ? "schema" : "data", out });
+                    if (index > 0)
+                        stack.push({ text: ",", out });
+                }
             }
         }
         else {
             out.push("{");
-            stack.push({ text: "}" });
+            stack.push({ text: "}", out });
             const entries = canonicalKeys(value);
-            for (let index = entries.length - 1; index >= 0; index -= 1) {
+            for (let index = entries.length - 1; index >= 0; index--) {
                 const [key, item] = entries[index];
-                stack.push({ value: item });
-                stack.push({ text: `${index > 0 ? "," : ""}${JSON.stringify(key)}:` });
+                stack.push({ value: item, mode: childMode(mode, key, item), out });
+                stack.push({ text: `${index > 0 ? "," : ""}${JSON.stringify(key)}:`, out });
             }
         }
     }
@@ -131,19 +181,23 @@ function canonicalJson(root) {
  * `src/catalog-fingerprint.ts`: that one is deliberately conservative because a
  * spurious cache write is cheap, while a spurious drift finding spends a
  * maintainer's attention on a downstream that reordered its JSON keys.
+ * New pins use `sha256-sets-v1:` and sort required, enum, and type arrays only
+ * at schema keyword locations. Tuple arrays and JSON data keep their order.
+ * Legacy `sha256:` pins use the original literal-array form, so an upgrade
+ * cannot silently invalidate a reviewed provider manifest.
  * Description and annotations are excluded — a reworded description is P1's
  * business, and an annotation change is already its own drift category.
  *
  * Rejects rather than digesting part of a schema: a digest that ignored some
  * leaf would let a reviewed read keep its verdict after that leaf changed.
  */
-export async function vettedSchemaDigest(tool) {
+export async function vettedSchemaDigest(tool, format = "sets-v1") {
     const bytes = encoder.encode(canonicalJson({
         inputSchema: tool.inputSchema ?? null,
         outputSchema: tool.outputSchema ?? null,
-    }));
+    }, format === "sets-v1"));
     const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
-    return `sha256:${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+    return `${format === "sets-v1" ? "sha256-sets-v1" : "sha256"}:${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
 }
 /**
  * Build a provider's manifest from the lists it already maintains.
@@ -160,6 +214,7 @@ export function vettedCatalog(input) {
         const digest = digestFor(name);
         tools.set(name, {
             verdict: "read-only",
+            ...(input.optionalTools?.has(name) ? { optional: true } : {}),
             ...(digest !== undefined ? { schemaDigest: digest } : {}),
         });
     }
@@ -170,6 +225,7 @@ export function vettedCatalog(input) {
         const digest = digestFor(name);
         tools.set(name, {
             verdict,
+            ...(input.optionalTools?.has(name) ? { optional: true } : {}),
             ...(digest !== undefined ? { schemaDigest: digest } : {}),
         });
     }
@@ -178,6 +234,10 @@ export function vettedCatalog(input) {
             throw new Error(`vettedCatalog() recorded a schema digest for unclassified tool "${name}".`);
         }
     }
+    for (const name of input.optionalTools ?? []) {
+        if (!tools.has(name))
+            throw new Error(`vettedCatalog() marked unclassified tool "${name}" optional.`);
+    }
     return { version: 1, tools };
 }
 const VERDICTS = {
@@ -190,8 +250,8 @@ const PUBLIC_VERDICTS = {
     additive: "write",
     destructive: "destructive",
 };
-const SCHEMA_DIGEST = /^sha256:[0-9a-f]{64}$/;
-const REVIEWED_TOOL_KEYS = new Set(["verdict", "reason", "schemaDigest"]);
+const SCHEMA_DIGEST = /^sha256(?:-sets-v1)?:[0-9a-f]{64}$/;
+const REVIEWED_TOOL_KEYS = new Set(["verdict", "reason", "schemaDigest", "optional"]);
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -232,7 +292,7 @@ function parseClassification(classification, owner) {
             if (!REVIEWED_TOOL_KEYS.has(key))
                 fail(`tool "${name}" has unknown key "${key}".`);
         }
-        const { verdict: publicVerdict, reason, schemaDigest: digest } = record;
+        const { verdict: publicVerdict, reason, schemaDigest: digest, optional } = record;
         const verdict = typeof publicVerdict === "string" && Object.hasOwn(VERDICTS, publicVerdict) ? VERDICTS[publicVerdict] : undefined;
         if (verdict === undefined) {
             fail(`tool "${name}" needs verdict "read", "write", or "destructive".`);
@@ -241,10 +301,13 @@ function parseClassification(classification, owner) {
             fail(`tool "${name}" reason must be a non-empty string.`);
         }
         if (digest !== undefined && (typeof digest !== "string" || !SCHEMA_DIGEST.test(digest))) {
-            fail(`tool "${name}" schemaDigest must be "sha256:" and 64 lowercase hex digits.`);
+            fail(`tool "${name}" schemaDigest must be "sha256:" or "sha256-sets-v1:" and 64 lowercase hex digits.`);
         }
+        if (optional !== undefined && typeof optional !== "boolean")
+            fail(`tool "${name}" optional must be a boolean.`);
         tools.set(name, {
             verdict,
+            ...(typeof optional === "boolean" ? { optional } : {}),
             ...(typeof digest === "string" ? { schemaDigest: digest } : {}),
         });
         frozen[name] =
@@ -253,6 +316,7 @@ function parseClassification(classification, owner) {
                 : Object.freeze({
                     verdict: PUBLIC_VERDICTS[verdict],
                     ...(typeof reason === "string" ? { reason } : {}),
+                    ...(typeof optional === "boolean" ? { optional } : {}),
                     ...(typeof digest === "string" ? { schemaDigest: digest } : {}),
                 });
     }
@@ -360,7 +424,8 @@ async function changedSchemas(catalog, tools) {
     const changed = new Set();
     for (const definition of tools) {
         const recorded = catalog.tools.get(definition.name)?.schemaDigest;
-        if (recorded !== undefined && recorded !== (await vettedSchemaDigest(definition))) {
+        if (recorded !== undefined &&
+            recorded !== (await vettedSchemaDigest(definition, recorded.startsWith("sha256:") ? "legacy" : "sets-v1"))) {
             changed.add(definition.name);
         }
     }
@@ -387,8 +452,8 @@ function countDrift(catalog, tools, changed) {
             annotationConflicts += 1;
     }
     let unservedTools = 0;
-    for (const name of catalog.tools.keys()) {
-        if (!served.has(name))
+    for (const [name, record] of catalog.tools) {
+        if (!record.optional && !served.has(name))
             unservedTools += 1;
     }
     return {
@@ -432,18 +497,20 @@ export function catalogReviewOf(connector) {
  * Classify downstream facts with a review: what the registry serves on every
  * read, from whichever cache layer the facts came from.
  *
- * Every tool returned is a fresh object, so nothing a caller does to one can
- * reach the facts, `memo`, or a later read. `memo` holds digest verification
- * per facts array; the registry passes one only for deep-frozen arrays it
- * owns. A failed verification is not kept, so the next read tries again, and
- * meanwhile no digested review vouches for a read (INV-1).
+ * Every tool returned is fresh. The registry supplies the same whole-schema
+ * verification it observed for this listing, including failures. Standalone
+ * callers verify here. No failed verification survives onto a later listing,
+ * and meanwhile no digested review vouches for a read (INV-1).
  */
-export async function classifyCatalog(catalog, connectorId, facts, logger, memo, overrides) {
-    let lapsed = memo?.get(facts);
+export async function classifyCatalog(catalog, connectorId, facts, logger, overrides, verification) {
+    let lapsed = verification
+        ? verification.available
+            ? verification.changed
+            : digestedTools(catalog, facts)
+        : undefined;
     if (!lapsed) {
         try {
             lapsed = await changedSchemas(catalog, facts);
-            memo?.set(facts, lapsed);
         }
         catch (error) {
             lapsed = digestedTools(catalog, facts);
@@ -455,39 +522,57 @@ export async function classifyCatalog(catalog, connectorId, facts, logger, memo,
         .filter((fact) => catalog.unlisted !== "hide" || catalog.tools.has(fact.name))
         .map((fact) => servedTool(catalog, fact, unverified, overrides?.[fact.name]));
 }
-/**
- * The drift each reviewed connector object showed on its last listing in this
- * runtime. Keyed by the connector rather than by registry, so a principal's
- * registry and the root report one observation, as they serve one connector.
- */
+/** Counts only, retained weakly by connector and an explicit runtime/catalog partition. */
 const observations = new WeakMap();
 /**
- * Compare a listing a refresh just received with the connector's review, and
- * keep the counts as its latest observation.
- *
- * The check happens where the tools are already in hand, while serving a
- * refresh the deployment asked for. It adds no request of its own, which is
- * the whole boundary: connecta watches a contract while it is serving a
- * refresh, and never initiates one to go looking
- * ([#179](https://github.com/zackbart/connecta/issues/179),
- * [#343](https://github.com/zackbart/connecta/issues/343)).
+ * Observe tools already fetched by a listing. No probe, persistence, or catalog
+ * payload: registry-owned partition tokens isolate deployment and subject.
+ * A digest failure replaces old success, while classification fails closed.
  */
-export async function observeReviewedDrift(connector, catalog, listed, logger) {
-    try {
-        const changed = await changedSchemas(catalog, listed);
-        observations.set(connector, {
-            observedAt: new Date().toISOString(),
-            ...countDrift(catalog, listed, changed),
-        });
+export async function observeReviewedDrift(connector, catalog, listed, logger, partition = connector, droppedTools = 0) {
+    let verification;
+    let report = {
+        observedAt: new Date().toISOString(),
+        reviewedBaseline: catalog !== undefined,
+        unclassifiedTools: 0,
+        unservedTools: 0,
+        annotationConflicts: 0,
+        schemaChanges: 0,
+        ...(droppedTools > 0 ? { droppedTools } : {}),
+    };
+    if (catalog) {
+        const reviewed = listed.filter((tool) => catalog.tools.has(tool.name));
+        const pinned = digestedTools(catalog, reviewed).size;
+        const schemaCoverage = { pinned, unpinned: reviewed.length - pinned };
+        try {
+            verification = { changed: await changedSchemas(catalog, listed), available: true };
+            report = {
+                ...report,
+                ...countDrift(catalog, listed, verification.changed),
+                schemaCoverage,
+                verification: "complete",
+            };
+        }
+        catch (error) {
+            verification = { changed: new Set(), available: false };
+            report = {
+                ...report,
+                ...countDrift(catalog, listed, verification.changed),
+                schemaCoverage,
+                verification: "unavailable",
+            };
+            logFailure(logger, "catalog drift check failed", failureRecord({ connector: connector.id }, error));
+        }
     }
-    catch (error) {
-        // A drift check is a report about a catalog, never a condition for
-        // serving one. Keep the last good observation rather than replacing it
-        // with a lie, and let the refresh through; classification fails closed.
-        logFailure(logger, "catalog drift check failed", failureRecord({ connector: connector.id }, error));
+    let partitions = observations.get(connector);
+    if (!partitions) {
+        partitions = new WeakMap();
+        observations.set(connector, partitions);
     }
+    partitions.set(partition, report);
+    return verification;
 }
-/** The latest drift {@link observeReviewedDrift} kept for `connector`. */
-export function observedCatalogDrift(connector) {
-    return observations.get(connector);
+/** Look up only this runtime/catalog partition; never start a listing. */
+export function observedCatalogDrift(connector, partition = connector) {
+    return observations.get(connector)?.get(partition);
 }

package/dist/catalog-service.js

@@ -465,7 +465,7 @@ export class CatalogService {
     // that asked for it. On a read-only endpoint a write is absent from search
     // and describe, as if the connector never had it. Guides are not filtered.
     discoveryCatalogs(ids, route) {
-        return Effect.forEach(ids, (id) => Effect.result(withDeadlineEffect((signal) => this.readOnly
+        return Effect.forEach(ids, (id) => Effect.result(withDeadlineEffect((signal) => this.readOnly || this.registry.getConnector(id)?.readOnly === true
             ? Effect.map(this.catalog(id, { signal }), (tools) => tools.filter((tool) => tool.classification === "read"))
             : this.catalog(id, { signal }), {
             ...(this.requestSignal ? { signal: this.requestSignal } : {}),
@@ -582,7 +582,7 @@ export class CatalogService {
         }
         return withAuthorizationHandoff(this.requestScope, error);
     }
-    async search(args) {
+    async search(args, onCatalogReference) {
         if (args.query !== undefined && typeof args.query !== "string") {
             throw new DiscoveryPolicyError("invalid_args", "query must be a string. Omit it or use an empty string to browse the catalog.");
         }
@@ -915,6 +915,20 @@ export class CatalogService {
                 : "No single tool matched every term in the catalogs that answered. Split distinct intents into separate searches.";
         };
         const guidance = searchGuidance();
+        // Counts, ranking, and term analysis use the whole searched corpus, not
+        // just this page's tools. Bind every searched connector, including failed
+        // catalogs and off-page matches, so paging cannot reveal a hidden
+        // connector's contribution. Keep provenance host-only.
+        for (const connector of connectors)
+            onCatalogReference?.(connector.id);
+        for (const entry of entries)
+            onCatalogReference?.(entry.connector.id, entry.tool.name);
+        for (const connector of absence?.configuredConnectors ?? [])
+            onCatalogReference?.(connector);
+        // An unknown scope's guidance lists the visible roster without searching it.
+        if (reportsQueryAnalysis && args.connector && !scopedConnector)
+            for (const connector of visibleConnectors)
+                onCatalogReference?.(connector.id);
         return {
             catalogErrors,
             ...(absence ? { absence } : {}),

package/dist/config-value-sources.js

@@ -74,7 +74,12 @@ export function describeConfigSources(snapshot, raw) {
                     ? provided(raw.pools?.[key]?.readOnly ?? raw.readOnly)
                     : field === "owner"
                         ? provided(raw.pools?.[key]?.owner)
-                        : provided(raw.pools);
+                        : field === "description"
+                            ? provided(raw.pools?.[key]?.description)
+                            : provided(raw.pools);
+        else if (group === "modules" && key === "activity" && field === "store" && parts[3] !== "kind")
+            // A store option such as retentionDays is set only when the store says so.
+            source = factorySource(factorySources(raw.activity?.store), parts.slice(3)) ?? "default";
         else if (group === "modules") {
             source = provided(key === "ui" ? raw.ui : key === "vault" ? raw.vault : key === "activity" ? raw.activity : raw.accessTokens);
         }

package/dist/config.d.ts

@@ -181,10 +181,19 @@ declare const pool: {
      * The Google Workspace address agents in this pool act as, on a Workspace
      * connector whose `subject` is a mapping function. Humans always act as
      * themselves through that mapping, and a fixed `subject` address applies to
-     * everyone. Without an owner, an agent's Workspace calls fail
-     * `auth_required`.
+     * everyone. Without an owner, a mapping-subject Workspace connector is
+     * absent for this pool's agents, as a personal connector is; people in the
+     * pool still see it.
      */
     owner: import("./config-schema.js").Field<string, string | undefined, true>;
+    /**
+     * What this pool is for, in plain words for the model: appended to the MCP
+     * `initialize` instructions at `/mcp/<name>` and `/agent/<name>`, so a
+     * caller learns its scope ("Team tier: shared tools only."). Trimmed, 1 to
+     * 500 characters, no line breaks or control characters. It grants and hides nothing; plain
+     * `/mcp` never shows it.
+     */
+    description: import("./config-schema.js").Field<string, string | undefined, true>;
 };
 declare const connectaConfig: {
     connectors: import("./config-schema.js").Field<Connector[], readonly Connector[], false>;
@@ -210,6 +219,7 @@ declare const connectaConfig: {
     pools: import("./config-schema.js").Field<Record<string, {
         readOnly?: boolean | undefined;
         owner?: string | undefined;
+        description?: string | undefined;
         tools: readonly string[];
         members: readonly MemberRef[];
     }>, Readonly<Record<string, {
@@ -217,6 +227,7 @@ declare const connectaConfig: {
         readonly tools: readonly string[];
         readonly members: readonly MemberRef[];
         readonly owner: string | undefined;
+        readonly description: string | undefined;
     }>> | undefined, true>;
     /** Exact connector id -> tool name -> verdict. Unknown names fail at catalog publication. */
     classification: import("./config-schema.js").Field<Record<string, Record<string, "read" | "write">>, Readonly<Record<string, Readonly<Record<string, "read" | "write">>>> | undefined, true>;