@zackbart/connecta 0.34.0 → 0.34.1

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this package are documented here.
 
+## 0.34.1 — 2026-10-19
+
+Connecta 0.34.1 is a patch release with a security fix. The Cloudflare provider passed stored AI Search crawler headers through unredacted, including on the routes 0.34.0 already served, so any caller allowed to read those resources could see header values that may carry credentials. 0.34.1 withholds them, along with conditional firewall match credentials, Vercel daemon probe headers, setup-form defaults and payment client secrets, and refuses Cloudforce One match responses that have no published schema before any request is sent. Deployments that use the Cloudflare or Vercel providers should upgrade.
+
+Connectors can now set `readOnly: true` (#895). A read-only connector serves only reviewed reads on every endpoint, maintainers' plain `/mcp` included; write and unclassified tools are hidden from discovery and refused on every call path. It combines with endpoint and pool `readOnly`, and the default is unchanged. The Stripe guide now shows both setups side by side: OAuth to Stripe's hosted MCP, or a secret or restricted key through the REST connector, with or without `readOnly`. A new maintained Intercom provider supports personal OAuth or a shared bearer token in the US or EU region; its schemas are not pinned yet because Intercom's catalog requires authentication to list.
+
+Catalog drift no longer counts as connector health (#867): a drifted connector reads Connected and stays out of Needs attention, while drift details remain on the connector page and in Activity. Connector cards, counts and the attention list keep their last verdict and position while details reload, and the top bar is more compact. Drift detection itself is corrected (#884): reordered schema arrays no longer report false changes for schemas pinned in the new format (existing pins keep their original hashing until re-reviewed), plan-gated tools can be marked optional, schema coverage is reported honestly, failed fingerprints mark verification unavailable instead of keeping a clean report, and per-person connectors keep separate observations. The Linear, Mixpanel, RevenueCat and Stripe reviews are reconciled with their live hosted catalogs and pin schemas; Mixpanel's Get-Events, Get-Dashboard, List-Cohorts and Get-Metric serve as reads again without deployment overrides, so a `classification: { mixpanel: { "Get-Events": "read" } }` override can be removed. Upgrading from 0.34.0 needs no configuration, storage migration or token rotation.
+
+### Added
+
+- Add a maintained Intercom hosted MCP provider with explicit US/EU region selection, personal OAuth or shared bearer-token auth, reviewed tool classifications, and guidance for sensitive support data and optional Fin Operator actions. Permission-gated Fin tools are optional for missing-tool drift while present tools retain classification checks. Schema coverage reports present reviewed tools as unpinned. Schema digests remain unpinned because anonymous catalog discovery requires authentication.
+- Add optional connector-level `readOnly` to every connector and maintained provider, enforcing read-only discovery and calls on every endpoint. Show the policy in the operator UI and clarify Stripe OAuth and API-key setup.
+
+### Fixed
+
+- Correct catalog drift reporting with schema coverage and verification states,
+  identity-partitioned observations, optional gated tools, and versioned schema
+  set canonicalization that preserves existing pins. Detect documented tool
+  access changes and stale unclassified acknowledgements in provider checks.
+  Operator refresh responses include the catalog comparison from that refresh,
+  so hashing failures and changed schemas cannot return an earlier clean report.
+  Provider pin assertions select the stored digest format, and a generated-roster
+  guard verifies every pin against captured schemas and rejects input/output drift.
+- Reconcile the maintained Linear catalog with hosted label lifecycle, inbox, saved view, triage, and diff tools. Preserve plan-gated customer requests, review the documented customer-needs read, and pin the observed hosted schemas so later changes fail closed.
+- Refresh reviewed hosted Mixpanel schemas so Get-Events, Get-Dashboard, List-Cohorts, and Get-Metric remain available to read-only endpoints without deployment overrides. Review the limited-beta Get-Audit-Log as a read, retain Fill-Event-Metadata as a write, and classify Get-Experiment as destructive because its optional computations can persist results and auto-conclude experiments.
+- Keep catalog drift informational, keep each connector's last verdict on every operator view while its details are read again so cards, counts and the attention list stop bouncing, keep attention rows in configuration order as their verdicts settle, safely hold prototype-named connector IDs, keep card and detail headers and Overview attention text on single lines with accessible ellipsis, including long connector ids, auth scopes and Read-only badges, reserve the card action footer and empty tool bar row, and compact the top bar for long deployment names and all page tabs.
+- Refresh Vercel and Cloudflare REST contracts and value-safety reviews, withhold conditional firewall match credentials, stored AI Search crawler headers and daemon probe headers, setup-form defaults, and payment client secrets, refuse schemaless Cloudforce match responses before dispatch, admit two stateless Cloudflare POST reads, classify hosted Cloudflare documentation search as read-only, and reconcile Vercel's complete hosted tool inventory.
+- Review RevenueCat subscription-group listing, audience preview, and paywall screenshot rendering as reads, pin four live schemas, and clarify permission-gated catalogs and conservative credential-validation routing.
+- Refresh Stripe hosted MCP tool reviews for money movement, recipient setup, Atlas formation, and renamed feedback; remove retired reviews, pin captured schemas for drift detection, and document account, mode, and human-confirmation requirements.
+
 ## 0.34.0 — 2026-10-16
 
 Connecta 0.34.0 rebuilds the operator UI around an Overview with connector health, endpoints, people and agents, a Needs attention list with fix prompts, and a connection map (#867). Maintainers now land on Overview at `/`; Endpoints moves to `/endpoints`, and `/access` redirects there. Update bookmarks, links and browser automation that expected Endpoints at `/`. Members still get their member page on every operator page path. The upgrade steps are in `documentation/migration-0.34.md`.

package/README.md

@@ -29,7 +29,7 @@ only the answer comes back.
 
 ## What you can connect
 
-Maintained connections: <!-- providers:start -->Basecamp, Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Infisical, Linear, Mixpanel, Notion, Overflow, Planning Center, RevenueCat, Stripe, Tithe.ly, Vercel, and Wispr Flow<!-- providers:end -->.
+Maintained connections: <!-- providers:start -->Basecamp, Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Infisical, Intercom, Linear, Mixpanel, Notion, Overflow, Planning Center, RevenueCat, Stripe, Tithe.ly, Vercel, and Wispr Flow<!-- providers:end -->.
 Plus any remote MCP server or HTTP API you describe.
 
 ## Who can use it
@@ -104,7 +104,8 @@ has the full layout.
 ## Reads and writes
 
 Every endpoint is writable or read-only, and you choose explicitly. A
-read-only endpoint hides write tools and refuses every write. On a writable
+read-only endpoint hides write tools and refuses every write. You can also make
+one connection read-only across all endpoints. On a writable
 one, your agent's host decides what to approve.
 
 ## Where it runs

package/bin/version.mjs

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.34.0";
+export const CONNECTA_VERSION = "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 } : {}),

package/dist/connectors/api-connector.d.ts

@@ -112,6 +112,8 @@ export interface ApiOptions {
      * construct.
      */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     /** Optional per-runtime downstream call-admission policy. */
     callAdmission?: ConnectorCallAdmissionPolicy;
     /**
@@ -146,6 +148,7 @@ export interface ApiOptions {
 /** The closed options api() accepts; see `assertKnownOptions`. */
 export declare const API_OPTIONS: import("../config-schema.js").Field<unknown, unknown, true> & {
     readonly shape: {
+        readOnly: import("../config-schema.js").Field<boolean, boolean | undefined, true>;
         callAdmission: Omit<import("../config-schema.js").Field<unknown, ConnectorCallAdmissionPolicy | undefined, true>, "parse"> & {
             parse(value: unknown, path: string): ConnectorCallAdmissionPolicy;
             readonly shape: import("../config-schema.js").Shape & {

package/dist/connectors/api-connector.js

@@ -3,7 +3,7 @@ import { attachFailureFacts, carryFailureFacts, errorLabel } from "../operator-r
 import { compileValidator, validateCatalogToolInput } from "../validate.js";
 import { array, assertKnownOptions, instance, keys, optionsOf, strings } from "../config-schema.js";
 import { describedEndpoint, describedOrigin, describedTools } from "../described.js";
-import { CALL_ADMISSION, CREDENTIAL, USAGE_GUIDE } from "./option-shapes.js";
+import { READ_ONLY, CALL_ADMISSION, CREDENTIAL, USAGE_GUIDE } from "./option-shapes.js";
 import { assertStaticToolNames } from "../tool-name.js";
 import { registerInvocationAuth } from "../invocation-auth.js";
 import { redactCatalog, redactSentSecrets, sentSecretsFetch, trackCredentialReads } from "../sent-secrets.js";
@@ -41,6 +41,7 @@ function checkToolContract(id, tool) {
 /** The closed options api() accepts; see `assertKnownOptions`. */
 export const API_OPTIONS = optionsOf()({
     ...keys("title", "description", "authScope", "maxResultBytes", "testCredential", "testCredentials", "validateArgs"),
+    readOnly: READ_ONLY,
     callAdmission: CALL_ADMISSION,
     usageGuide: USAGE_GUIDE,
     credential: CREDENTIAL,
@@ -90,6 +91,8 @@ function describedApiAuth(opts) {
  */
 export function apiConnector(id, opts, oauth) {
     opts = assertKnownOptions(opts, `api(${JSON.stringify(id)})`, API_OPTIONS);
+    if (opts.readOnly !== undefined)
+        READ_ONLY.parse(opts.readOnly, `Connector(${JSON.stringify(id)}).readOnly`);
     if (opts.callAdmission !== undefined)
         CALL_ADMISSION.parse(opts.callAdmission, `api(${JSON.stringify(id)}).callAdmission`);
     assertStaticToolNames(opts.tools, `api(${JSON.stringify(id)}).tools`);
@@ -124,6 +127,7 @@ export function apiConnector(id, opts, oauth) {
         ...defined({
             description: opts.description,
             authScope: opts.authScope,
+            readOnly: opts.readOnly,
             maxResultBytes: opts.maxResultBytes,
             callAdmission: opts.callAdmission,
             usageGuide: opts.usageGuide,