@zackbart/connecta 0.28.1 → 0.29.0

package/dist/catalog-drift.d.ts

@@ -1,13 +1,17 @@
-import type { CatalogDriftCounts, CatalogDriftReport, Connector, ToolDef } from "./types.js";
+import type { CatalogDriftCounts, CatalogDriftReport, Connector, Logger, ToolClassification, ToolDef } from "./types.js";
 /**
- * Rebuild a drift report as four counts and a bounded timestamp.
+ * 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 declare function boundedCatalogDrift(report: CatalogDriftReport | undefined): CatalogDriftReport | undefined;
 /**
@@ -39,6 +43,7 @@ interface VettedToolRecord {
  * compares against cannot disagree.
  */
 export interface VettedCatalog {
+    unlisted?: "hide";
     /** Manifest format. Bumped when the comparison itself changes shape. */
     version: 1;
     tools: ReadonlyMap<string, VettedToolRecord>;
@@ -64,6 +69,9 @@ export interface VettedCatalogInput {
  * 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 declare function vettedSchemaDigest(tool: ToolDef): Promise<string>;
 /**
@@ -75,6 +83,15 @@ export declare function vettedSchemaDigest(tool: ToolDef): Promise<string>;
  * default" cannot be decided by ordering.
  */
 export declare function vettedCatalog(input: VettedCatalogInput): VettedCatalog;
+/** Validate a {@link ToolClassification} and build the manifest it describes. */
+export declare function reviewedCatalog(classification: ToolClassification, owner: string): VettedCatalog;
+/**
+ * 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 declare function reviewedClassification(classification: ToolClassification, owner: string): ToolClassification;
 /**
  * Compare a live catalog with the manifest and count what moved.
  *
@@ -85,15 +102,33 @@ export declare function vettedCatalog(input: VettedCatalogInput): VettedCatalog;
  */
 export declare function detectCatalogDrift(catalog: VettedCatalog, tools: readonly ToolDef[]): Promise<CatalogDriftCounts>;
 /**
- * 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.
+ * The review `connector.classification` declares, or undefined when it
+ * declares none. Throws on a malformed one (INV-11).
+ */
+export declare function catalogReviewOf(connector: Connector): VettedCatalog | 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 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[]>;
+/**
+ * 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 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),
+ * 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 declare function withVettedCatalog(connector: Connector, catalog: VettedCatalog): Connector;
+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 {};