@zackbart/connecta 0.28.1 → 0.29.0

package/dist/catalog-drift.js

@@ -1,55 +1,128 @@
 // Web-API only, like the rest of the core: a manifest comparison that ran on
 // Node but not on Workers would leave half the deployments unable to tell a
 // stale allowlist from a current one.
-import { boundedEchoText } from "./errors.js";
-/**
- * Byte budget for the one string a drift report carries. An ISO timestamp is
- * 24 bytes; anything near this bound is a plugin sending something else.
- */
-const MAX_OBSERVED_AT_BYTES = 64;
+import { classifyTool } from "./tool-safety.js";
+import { failureRecord, logFailure } from "./operator-record.js";
 /** A count, or 0 when the seam returned something that is not one. */
 function boundedCount(value) {
-    return typeof value === "number" && Number.isFinite(value)
-        ? Math.max(0, Math.trunc(value))
-        : 0;
+    return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
 }
+/** An ISO-8601 date-time with a zone, as `Date.parse` reads it on every runtime. */
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
 /**
- * Rebuild a drift report as four counts and a bounded timestamp.
+ * The report's time, re-serialized from the instant it names, so the string
+ * that leaves is always connecta's own ISO-8601 UTC form, never the seam's.
+ */
+function observationTime(value) {
+    if (typeof value !== "string" || !ISO_INSTANT.test(value))
+        return undefined;
+    const time = Date.parse(value);
+    return Number.isFinite(time) ? new Date(time).toISOString() : undefined;
+}
+/**
+ * Rebuild a drift report as bounded counts and a canonical timestamp.
  *
  * `Connector.catalogDrift()` sits on the open plugin seam, and what it returns
- * lands in the body of unauthenticated `/health` and on connector status.
- * TypeScript constrains neither an extra enumerable property nor the length of
- * `observedAt` at runtime, so "counts and nothing else" is *made* true here —
- * at the boundary where third-party output becomes a response — rather than
- * trusted. The activity path reconstructs its five fields for the same reason.
+ * 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
+ * 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
+ * otherwise put any text there. The activity path reconstructs its five
+ * fields for the same reason.
  */
 export function boundedCatalogDrift(report) {
     if (!report || typeof report !== "object")
         return undefined;
+    const observedAt = observationTime(report.observedAt);
+    if (observedAt === undefined)
+        return undefined;
     return {
-        observedAt: boundedEchoText(typeof report.observedAt === "string" ? report.observedAt : "", MAX_OBSERVED_AT_BYTES),
+        observedAt,
         unclassifiedTools: boundedCount(report.unclassifiedTools),
         unservedTools: boundedCount(report.unservedTools),
         annotationConflicts: boundedCount(report.annotationConflicts),
         schemaChanges: boundedCount(report.schemaChanges),
+        ...(boundedCount(report.droppedTools ?? 0) > 0 ? { droppedTools: boundedCount(report.droppedTools ?? 0) } : {}),
     };
 }
 const encoder = new TextEncoder();
-/** Deterministic JSON: object keys sorted, so key order is not a schema change. */
-function canonicalize(value, depth = 0) {
-    // Drift is advisory. Beyond this bound compare an explicit marker instead
-    // of letting a downstream schema exhaust the host stack.
-    if (depth > 64)
-        return "[schema depth truncated]";
-    if (Array.isArray(value)) {
-        return value.map((item) => canonicalize(item, depth + 1));
+/**
+ * Most JSON values one tool's schemas may hold before its digest refuses to
+ * compute. A digest vouches for a whole schema or for nothing, so a schema
+ * past the bound is not hashed in part: the computation throws, and the
+ * caller serves every digested review unverified (INV-1).
+ */
+const MAX_SCHEMA_DIGEST_NODES = 100_000;
+/** Object keys in the order `JSON.stringify` emits a key-sorted object. */
+function canonicalKeys(value) {
+    const entries = Object.entries(value).filter(([, item]) => item !== undefined && typeof item !== "function" && typeof item !== "symbol");
+    entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    // A plain object enumerates integer-like keys first, in numeric order.
+    // Recorded digests were taken from a key-sorted object, so reproduce its
+    // enumeration rather than the sort alone.
+    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 out = [];
+    const stack = [{ value: root }];
+    let nodes = 0;
+    while (stack.length > 0) {
+        const task = stack.pop();
+        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.`);
+        }
+        const value = task.value;
+        if (value === null || value === undefined) {
+            out.push("null");
+        }
+        else if (typeof value === "string" || typeof value === "boolean") {
+            out.push(JSON.stringify(value));
+        }
+        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.
+            out.push("null");
+        }
+        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: "," });
+            }
+        }
+        else {
+            out.push("{");
+            stack.push({ text: "}" });
+            const entries = canonicalKeys(value);
+            for (let index = entries.length - 1; index >= 0; index -= 1) {
+                const [key, item] = entries[index];
+                stack.push({ value: item });
+                stack.push({ text: `${index > 0 ? "," : ""}${JSON.stringify(key)}:` });
+            }
+        }
     }
-    if (value === null || typeof value !== "object")
-        return value;
-    const entries = Object.entries(value)
-        .filter(([, item]) => item !== undefined)
-        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    return Object.fromEntries(entries.map(([key, item]) => [key, canonicalize(item, depth + 1)]));
+    return out.join("");
 }
 /**
  * Digest the schemas of one downstream tool.
@@ -60,16 +133,17 @@ function canonicalize(value, depth = 0) {
  * maintainer's attention on a downstream that reordered its JSON keys.
  * 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) {
-    const bytes = encoder.encode(JSON.stringify(canonicalize({
+    const bytes = encoder.encode(canonicalJson({
         inputSchema: tool.inputSchema ?? null,
         outputSchema: tool.outputSchema ?? null,
-    })));
+    }));
     const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
-    return `sha256:${[...digest]
-        .map((byte) => byte.toString(16).padStart(2, "0"))
-        .join("")}`;
+    return `sha256:${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
 }
 /**
  * Build a provider's manifest from the lists it already maintains.
@@ -106,61 +180,161 @@ export function vettedCatalog(input) {
     }
     return { version: 1, tools };
 }
+const VERDICTS = {
+    read: "read-only",
+    write: "additive",
+    destructive: "destructive",
+};
+const PUBLIC_VERDICTS = {
+    "read-only": "read",
+    additive: "write",
+    destructive: "destructive",
+};
+const SCHEMA_DIGEST = /^sha256:[0-9a-f]{64}$/;
+const REVIEWED_TOOL_KEYS = new Set(["verdict", "reason", "schemaDigest"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /**
- * Fill in downstream silence; keep reviewed destructive tools fail-closed.
+ * Validate a public {@link ToolClassification} once, reading every value a
+ * single time, into the manifest the registry classifies with and a
+ * deep-frozen copy of the record.
  *
- * Silence is what a vetted classification is for, and an explicit downstream
- * annotation otherwise wins in both directions. `destructiveHint: true` or
- * `readOnlyHint: false` on a classified read is the downstream telling us this
- * release's allowlist is stale; `readOnlyHint: true` on a name no release has
- * classified says the same thing from the other side. The single place a
- * vetted verdict still overrides the downstream is a name this release
- * reviewed and filed destructive: there connecta knows what the tool does, and
- * a claim to the contrary is a downstream bug rather than news
+ * Every structural mistake throws, naming `owner`, because a classification
+ * that half-applies is worse than one that refuses to boot (INV-11). Unknown
+ * keys throw too: a misspelled `verdict` must not quietly leave a write
+ * unclassified.
+ */
+function parseClassification(classification, owner) {
+    function fail(detail) {
+        throw new Error(`[connecta] ${owner} classify ${detail}`);
+    }
+    if (!isRecord(classification))
+        fail("must be an object with a tools record.");
+    for (const key of Object.keys(classification)) {
+        if (key !== "tools" && key !== "unlisted")
+            fail(`has unknown key "${key}"; only "tools" and "unlisted" are accepted.`);
+    }
+    const unlisted = classification.unlisted;
+    if (unlisted !== undefined && unlisted !== "hide")
+        fail('unlisted must be "hide" when set.');
+    const input = classification.tools;
+    if (!isRecord(input))
+        fail("tools must be a record of tool name to verdict.");
+    const tools = new Map();
+    const frozen = {};
+    for (const [name, entry] of Object.entries(input)) {
+        if (!name || name.trim() !== name) {
+            fail(`tool name "${name}" is empty or has surrounding whitespace.`);
+        }
+        const record = typeof entry === "string" ? { verdict: entry } : isRecord(entry) ? { ...entry } : {};
+        for (const key of Object.keys(record)) {
+            if (!REVIEWED_TOOL_KEYS.has(key))
+                fail(`tool "${name}" has unknown key "${key}".`);
+        }
+        const { verdict: publicVerdict, reason, schemaDigest: digest } = 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".`);
+        }
+        if (reason !== undefined && (typeof reason !== "string" || !reason.trim())) {
+            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.`);
+        }
+        tools.set(name, {
+            verdict,
+            ...(typeof digest === "string" ? { schemaDigest: digest } : {}),
+        });
+        frozen[name] =
+            typeof entry === "string"
+                ? PUBLIC_VERDICTS[verdict]
+                : Object.freeze({
+                    verdict: PUBLIC_VERDICTS[verdict],
+                    ...(typeof reason === "string" ? { reason } : {}),
+                    ...(typeof digest === "string" ? { schemaDigest: digest } : {}),
+                });
+    }
+    return {
+        catalog: { version: 1, tools, ...(unlisted ? { unlisted } : {}) },
+        frozen: Object.freeze({ tools: Object.freeze(frozen), ...(unlisted ? { unlisted } : {}) }),
+    };
+}
+/** Validate a {@link ToolClassification} and build the manifest it describes. */
+export function reviewedCatalog(classification, owner) {
+    return parseClassification(classification, owner).catalog;
+}
+/**
+ * Validate a {@link ToolClassification} and return a deep-frozen copy of it:
+ * what a connector carries as `classification`, so neither the caller's
+ * original object nor a write through the connector can change a verdict
+ * after review.
+ */
+export function reviewedClassification(classification, owner) {
+    return parseClassification(classification, owner).frozen;
+}
+/**
+ * One reviewed tool as served: a fresh object, never one a connector, a
+ * cache, or an earlier read holds.
+ *
+ * A listed read fills downstream silence, and an explicit write annotation on
+ * it wins: `destructiveHint: true` or `readOnlyHint: false` on a classified
+ * read is the downstream telling us the review is stale. A listed write or
+ * destructive tool stays a write whatever the downstream claims; there
+ * connecta knows what the tool does, and a claim to the contrary is a
+ * downstream bug rather than news
  * ([#310](https://github.com/zackbart/connecta/issues/310),
- * [#315](https://github.com/zackbart/connecta/issues/315)).
+ * [#315](https://github.com/zackbart/connecta/issues/315)). A tool no review
+ * lists keeps only an explicit read annotation, the downstream's own word
+ * being the only evidence there is. A reviewed tool whose recorded schema
+ * digest the live tool no longer matches, or could not be checked against,
+ * keeps no reviewed verdict and is a write.
  */
-function applyVettedSafety(catalog, definition) {
+function servedTool(catalog, fact, lapsed, override) {
+    const definition = structuredClone(fact);
+    const reviewed = catalog.tools.get(fact.name);
+    definition.classification = classifyTool(fact, override, reviewed
+        ? {
+            verdict: PUBLIC_VERDICTS[reviewed.verdict],
+            stale: lapsed.has(fact.name),
+        }
+        : undefined);
     const downstream = definition.annotations ?? {};
     const record = catalog.tools.get(definition.name);
+    const annotate = (annotations) => ({
+        ...definition,
+        annotations: override === undefined
+            ? annotations
+            : { ...annotations, readOnlyHint: override === "read", destructiveHint: override === "write" },
+    });
+    if (record?.verdict === "destructive") {
+        return annotate({ ...downstream, readOnlyHint: false, destructiveHint: true });
+    }
+    if (record && lapsed.has(definition.name)) {
+        // A review vouches for the schema it read. When the live schema no longer
+        // matches that digest, or the digest could not be checked, the verdict is
+        // about some other tool: the read becomes a write until a release reviews
+        // it again (INV-1).
+        return annotate({ ...downstream, readOnlyHint: false });
+    }
     if (record?.verdict === "read-only") {
-        if (downstream.destructiveHint === true ||
-            downstream.readOnlyHint === false) {
-            return definition;
+        if (downstream.destructiveHint === true || downstream.readOnlyHint === false) {
+            return annotate(downstream);
         }
-        return {
-            ...definition,
-            annotations: {
-                ...downstream,
-                readOnlyHint: true,
-                destructiveHint: downstream.destructiveHint ?? false,
-            },
-        };
+        return annotate({
+            ...downstream,
+            readOnlyHint: true,
+            destructiveHint: downstream.destructiveHint ?? false,
+        });
     }
-    if (record?.verdict === "destructive") {
-        return {
-            ...definition,
-            annotations: {
-                ...downstream,
-                readOnlyHint: false,
-                destructiveHint: true,
-            },
-        };
+    if (record?.verdict === "additive") {
+        return annotate({ ...downstream, readOnlyHint: false });
     }
-    // Maintained additive creates and tools this release has never seen land
-    // here alike. Fill-in only: a silent tool is not read-only, so drift still
-    // fails closed onto `call_destructive_tool`, and neither population gets a
-    // `destructiveHint` it has not earned. A tool that arrives explicitly
-    // read-only keeps that annotation — on a name no release has reviewed, the
-    // downstream's own word is the only evidence there is, and rewriting it
-    // would be an overrule rather than a fill-in.
-    return {
-        ...definition,
-        annotations: {
-            ...downstream,
-            readOnlyHint: downstream.readOnlyHint ?? false,
-        },
-    };
+    // Fill-in only: a silent tool is not read-only, so drift fails closed onto
+    // `call_destructive_tool`, and it gets no `destructiveHint` it has not
+    // earned. An explicit read claim on a name no review lists is believed.
+    return annotate({ ...downstream, readOnlyHint: downstream.readOnlyHint ?? false });
 }
 /**
  * Whether the downstream's own annotation contradicts what a release reviewed.
@@ -172,22 +346,35 @@ function applyVettedSafety(catalog, definition) {
 function contradicts(record, definition) {
     const downstream = definition.annotations ?? {};
     if (record.verdict === "read-only") {
-        return (downstream.readOnlyHint === false || downstream.destructiveHint === true);
+        return downstream.readOnlyHint === false || downstream.destructiveHint === true;
     }
     return downstream.readOnlyHint === true;
 }
 /**
- * Compare a live catalog with the manifest and count what moved.
- *
- * Counts only, and by construction: there is nowhere here to put a tool name,
- * a schema, or a downstream string, so no later surface has to remember to
- * strip one. Reads nothing but the tools it was handed — the caller already
- * fetched them to serve a request, and this function never fetches anything.
+ * Names of served tools whose schemas no longer match the digest a release
+ * recorded for them. A manifest that recorded no digest for a tool cannot have
+ * an opinion about its schema, so it does not pay for a hash either. Throws
+ * when a digest cannot be computed; the caller decides what that means.
  */
-export async function detectCatalogDrift(catalog, tools) {
+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))) {
+            changed.add(definition.name);
+        }
+    }
+    return changed;
+}
+/** Every served tool whose review recorded a digest: what cannot be verified. */
+function digestedTools(catalog, tools) {
+    return new Set(tools
+        .filter((definition) => catalog.tools.get(definition.name)?.schemaDigest !== undefined)
+        .map((definition) => definition.name));
+}
+function countDrift(catalog, tools, changed) {
     let unclassifiedTools = 0;
     let annotationConflicts = 0;
-    let schemaChanges = 0;
     const served = new Set();
     for (const definition of tools) {
         served.add(definition.name);
@@ -198,12 +385,6 @@ export async function detectCatalogDrift(catalog, tools) {
         }
         if (contradicts(record, definition))
             annotationConflicts += 1;
-        // A manifest that recorded no digest for this tool cannot have an opinion
-        // about its schema, so it does not pay for a hash either.
-        if (record.schemaDigest !== undefined &&
-            record.schemaDigest !== (await vettedSchemaDigest(definition))) {
-            schemaChanges += 1;
-        }
     }
     let unservedTools = 0;
     for (const name of catalog.tools.keys()) {
@@ -214,43 +395,99 @@ export async function detectCatalogDrift(catalog, tools) {
         unclassifiedTools,
         unservedTools,
         annotationConflicts,
-        schemaChanges,
+        schemaChanges: changed.size,
     };
 }
 /**
- * Wrap a hosted-MCP connector in its vetted manifest: the classification the
- * catalog is normalized with, and the drift check that rides the same listing.
+ * Compare a live catalog with the manifest and count what moved.
  *
- * The check happens where the tools are already in hand and still unmodified —
- * after the downstream answered, before the classification is applied. It adds
- * no request of its own, which is the whole boundary: connecta watches a
- * contract while it is serving a refresh the deployment asked for, and never
- * initiates one to go looking ([#179](https://github.com/zackbart/connecta/issues/179),
+ * Counts only, and by construction: there is nowhere here to put a tool name,
+ * a schema, or a downstream string, so no later surface has to remember to
+ * strip one. Reads nothing but the tools it was handed — the caller already
+ * fetched them to serve a request, and this function never fetches anything.
+ */
+export async function detectCatalogDrift(catalog, tools) {
+    return countDrift(catalog, tools, await changedSchemas(catalog, tools));
+}
+/**
+ * Each connector object's review, validated the first time a registry reads
+ * it. Read once per object, so a getter or a record mutated later cannot
+ * hand a later registry (a principal's, say) a different review.
+ */
+const reviews = new WeakMap();
+/**
+ * The review `connector.classification` declares, or undefined when it
+ * declares none. Throws on a malformed one (INV-11).
+ */
+export function catalogReviewOf(connector) {
+    let review = reviews.get(connector);
+    if (review === undefined) {
+        const classification = connector.classification;
+        review = classification === undefined ? null : reviewedCatalog(classification, `connector "${connector.id}"`);
+        reviews.set(connector, review);
+    }
+    return review ?? undefined;
+}
+/**
+ * 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).
+ */
+export async function classifyCatalog(catalog, connectorId, facts, logger, memo, overrides) {
+    let lapsed = memo?.get(facts);
+    if (!lapsed) {
+        try {
+            lapsed = await changedSchemas(catalog, facts);
+            memo?.set(facts, lapsed);
+        }
+        catch (error) {
+            lapsed = digestedTools(catalog, facts);
+            logFailure(logger, "schema digest check failed; serving digested reviews as writes", failureRecord({ connector: connectorId }, error));
+        }
+    }
+    const unverified = lapsed;
+    return facts
+        .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.
+ */
+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)).
  */
-export function withVettedCatalog(connector, catalog) {
-    let observed;
-    return {
-        ...connector,
-        async listTools(ctx) {
-            const downstream = await connector.listTools(ctx);
-            try {
-                observed = {
-                    observedAt: new Date().toISOString(),
-                    ...(await detectCatalogDrift(catalog, downstream)),
-                };
-            }
-            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.
-                ctx.logger.warn(`[connecta] connector "${connector.id}" catalog drift check failed: ` +
-                    (error instanceof Error ? error.message : String(error)));
-            }
-            return downstream.map((definition) => applyVettedSafety(catalog, definition));
-        },
-        catalogDrift() {
-            return observed;
-        },
-    };
+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),
+        });
+    }
+    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));
+    }
+}
+/** The latest drift {@link observeReviewedDrift} kept for `connector`. */
+export function observedCatalogDrift(connector) {
+    return observations.get(connector);
 }

package/dist/catalog-fingerprint.js

@@ -1,9 +1,7 @@
 const encoder = new TextEncoder();
 async function fingerprintBytes(bytes) {
-    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
-    const hex = [...digest]
-        .map((byte) => byte.toString(16).padStart(2, "0"))
-        .join("");
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new Uint8Array(bytes)));
+    const hex = [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
     return `sha256:${bytes.byteLength}:${hex}`;
 }
 /** Fingerprint an already serialized catalog without parsing/reserializing it. */

package/dist/catalog-freshness.js

@@ -0,0 +1,13 @@
+// Host-only provenance follows catalog copies, never connector definitions or
+// serialized listings. Unknown provenance cannot authorize post-entry recovery.
+const deadlines = new WeakMap();
+export function markCatalogFreshness(tools, freshUntil) {
+    deadlines.set(tools, freshUntil);
+    return tools;
+}
+export function carryCatalogFreshness(source, copy) {
+    return markCatalogFreshness(copy, deadlines.get(source) ?? 0);
+}
+export function catalogIsFresh(tools) {
+    return (deadlines.get(tools) ?? 0) > Date.now();
+}

package/dist/catalog-limits.js

@@ -1,8 +1,8 @@
 /** Complete-catalog ceiling shared by dynamically listed connector catalogs. */
 export const MAX_CATALOG_TOOLS = 100_000;
 /**
- * Large enough to cross a single Workers KV value boundary while keeping the
- * serialized form at one quarter of a 128 MiB Worker heap.
+ * Large enough to span many stored chunks while keeping the serialized form
+ * at one quarter of a 128 MiB Worker heap.
  */
 export const MAX_SERIALIZED_CATALOG_BYTES = 32 * 1024 * 1024;
 /** Persisted values stay comfortably below platform per-value limits. */