@zackbart/connecta 0.34.1 → 0.35.0

package/guides/safety-and-trust.md

@@ -0,0 +1,153 @@
+# Safety and trust
+
+Connecta helps limit tool access. It does not approve every action or
+guarantee that returned business data is safe to share. Your operator—the
+person or team running the server—chooses accounts, access, and approval rules.
+
+With authentication configured, Connecta checks who is calling and which
+tools they can use. Without configured authentication, the main `/mcp`
+endpoint serves its whole tool list to anyone who can reach it.
+
+The [operator documentation](../documentation/README.md) owns exact setup
+and behavior. This guide explains the boundaries and their limits.
+
+## A timeout can leave a change's status unknown
+
+A **write** changes something: a record, payment, permission, or other service
+state. The service might apply it even when no answer comes back. Check the
+current record or service history before trying again.
+
+For tools classified as writes, once Connecta sends a change, it never
+automatically sends it again. This includes a timeout or a lost response.
+That does not promise the service completed it exactly once. A new request
+or a rerun of a program can repeat the action.
+
+```mermaid
+sequenceDiagram
+    participant A as Agent
+    participant C as Connecta
+    participant S as Service
+    A->>C: Request a write
+    C->>S: Send once
+    S->>S: The write may have applied
+    S--xC: Response lost or deadline reached
+    C-->>A: Outcome unknown, do not blindly repeat
+    A->>C: Check current state or history
+    C->>S: Read available evidence
+    S-->>C: Current state or history
+    C-->>A: Investigate further if still uncertain
+```
+
+An **unknown outcome** means Connecta cannot prove whether the change
+happened. A read may help, but may not settle it. If the answer is still
+unclear, stop and investigate.
+
+Do not repeat a successful change just to recover its output either.
+The [write contract](../documentation/code-mode.md#writes) and
+[result recovery guide](../documentation/meta-tools.md#paging-with-connectaresult)
+explain how to check the service or retrieve retained output.
+
+## Read-only blocks actions that change data
+
+A read-only pool hides tools marked as writes and refuses attempts to call
+them before sending anything. Guessing a tool name or asking from a program
+does not bypass it. A whole service connection can also be read-only; a
+writable pool cannot reopen that connection for writes.
+
+```mermaid
+flowchart LR
+    Call["Requested action"] --> Allowed{"Pool allows this tool?"}
+    Allowed -->|No| Refuse["Refuse"]
+    Allowed -->|Yes| Write{"Marked as a write?"}
+    Write -->|No| Run["Check inputs and send"]
+    Write -->|Yes| ReadOnly{"Pool or connection read-only?"}
+    ReadOnly -->|Yes| Refuse
+    ReadOnly -->|No| Run
+```
+
+Read-only protection and the single-attempt rule depend on truthful
+classification: the labels identifying actions that change data. Missing
+or contradictory read hints count as writes, but a service can mislabel an
+action and an operator can override its label. Use restricted service
+credentials as another boundary where possible.
+
+The AI app owns approvals. It may ask based on an earlier tool label. If a
+read becomes a write, a writable pool can execute it without a fresh
+approval; a read-only pool refuses it. Connecta does not pause a program to
+ask a person partway through.
+
+See [read-only setup](../documentation/integrating.md#make-one-connection-read-only)
+and the [write policy](../documentation/code-mode.md#writes) for exact rules.
+
+## Keep credentials private and enable the vault
+
+The agent receives tool results without needing the service credential used
+to make the call. Redaction removes known secrets from output, but is not a
+general detector for every secret or piece of personal data in a record.
+
+With the encrypted credential vault configured, Connecta seals stored
+downstream credentials and OAuth tokens and binds each to its connector and
+owner. Without a vault, stored OAuth tokens are kept in plaintext, so enable
+the vault **before connecting accounts**. Follow
+[shared credential setup](../documentation/auth.md#connect-a-shared-credential)
+and [OAuth storage rules](../documentation/auth.md#downstream-oauth-state-at-rest).
+
+Maintained integrations also withhold reviewed sensitive values. A value
+shown as `[redacted]` is unavailable, not a usable credential. Redaction
+covers known values and supported forms; a malicious service can transform
+data into forms outside that coverage.
+
+Connecta's activity, status, and logs omit arguments, results, program source,
+and raw downstream error text. Your AI app, proxies, and other logging systems
+need their own data-handling policies. Keep agent tokens in the app's secret
+store, outside prompts, source files, and logs.
+
+The [operator data contract](../documentation/operator-ui.md#operator-data-contract)
+explains activity disclosure.
+
+## A credential proves an agent, not a person
+
+Anyone holding an agent's `cta_` token can act as that agent. Vercel workload
+identity uses a signed project token instead. It removes the separately
+provisioned Connecta secret, while still trusting whoever can obtain the
+project token.
+
+```mermaid
+flowchart TB
+    Saved["Agent-token holder"] --> Agent["Declared agent"]
+    Project["Trusted Vercel project-token holder"] --> Agent
+    Agent --> Pools["Configured pools"]
+    Pools --> Accounts["Assigned service accounts"]
+```
+
+Trust project code, build steps, and services receiving a Vercel token with
+the same agent access. Preview or development environments should be enabled
+only if they deserve that access too. A token holder may obtain fresh tokens,
+so access can outlast the original token's expiry.
+
+When both methods are enabled, stopping one leaves the other active.
+Removing the declared agent stops both. Revocation does not recall requests
+already admitted. Neither method identifies the human chatting with the agent.
+
+The [token guide](../documentation/auth.md#issue-rotate-or-revoke-an-agent-token)
+and [Vercel trust guide](../documentation/auth.md#vercel-workload-credentials)
+own availability, project/environment choices, and revocation details.
+
+## What the operator remains responsible for
+
+| Decision                       | Why it matters                                                                                       |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| Inbound authentication         | Without configured `auth`, plain `/mcp` serves the whole catalog to anyone who can reach it.         |
+| Enable the credential vault    | Encrypt stored credentials and OAuth tokens before connecting accounts.                              |
+| Pool membership and tools      | Each member can use every action that pool grants.                                                   |
+| Service permissions            | A shared credential uses the same account for every member.                                          |
+| Approval policy                | A writable pool can run unattended; the Eve helper defaults to that behavior.                        |
+| Tool classification            | Labels must match the service's actual behavior.                                                     |
+| Deployment and secret handling | Enable the credential vault; protect storage, encryption keys, backups, ingress, and the agent host. |
+| Conversation routing           | Keep private results out of broader chats.                                                           |
+| Uncertain changes              | Check the service before requesting another change.                                                  |
+
+For concrete steps, use [deployment operations](../documentation/deploying.md),
+[agent pool layout](../documentation/auth.md#organizing-an-agents-pools), and
+[Connecting agents](./connecting-agents.md). The [security policy](../SECURITY.md)
+explains how to report a problem.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of six meta-tools.",
@@ -33,6 +33,7 @@
     "bin",
     "dist",
     "documentation",
+    "guides",
     "examples/worker",
     "templates",
     "README.md",
@@ -74,10 +75,6 @@
       "types": "./dist/auth/cloudflare-access.d.ts",
       "import": "./dist/auth/cloudflare-access.js"
     },
-    "./providers/basecamp": {
-      "types": "./dist/providers/basecamp/index.d.ts",
-      "import": "./dist/providers/basecamp/index.js"
-    },
     "./providers/breeze": {
       "types": "./dist/providers/breeze/index.d.ts",
       "import": "./dist/providers/breeze/index.js"
@@ -110,26 +107,6 @@
       "types": "./dist/providers/gmail/index.d.ts",
       "import": "./dist/providers/gmail/index.js"
     },
-    "./providers/infisical": {
-      "types": "./dist/providers/infisical/index.d.ts",
-      "import": "./dist/providers/infisical/index.js"
-    },
-    "./providers/intercom": {
-      "types": "./dist/providers/intercom/index.d.ts",
-      "import": "./dist/providers/intercom/index.js"
-    },
-    "./providers/linear": {
-      "types": "./dist/providers/linear/index.d.ts",
-      "import": "./dist/providers/linear/index.js"
-    },
-    "./providers/mixpanel": {
-      "types": "./dist/providers/mixpanel/index.d.ts",
-      "import": "./dist/providers/mixpanel/index.js"
-    },
-    "./providers/notion": {
-      "types": "./dist/providers/notion/index.d.ts",
-      "import": "./dist/providers/notion/index.js"
-    },
     "./providers/overflow": {
       "types": "./dist/providers/overflow/index.d.ts",
       "import": "./dist/providers/overflow/index.js"
@@ -138,10 +115,6 @@
       "types": "./dist/providers/planning-center/index.d.ts",
       "import": "./dist/providers/planning-center/index.js"
     },
-    "./providers/revenuecat": {
-      "types": "./dist/providers/revenuecat/index.d.ts",
-      "import": "./dist/providers/revenuecat/index.js"
-    },
     "./providers/sheets": {
       "types": "./dist/providers/sheets/index.d.ts",
       "import": "./dist/providers/sheets/index.js"
@@ -162,10 +135,6 @@
       "types": "./dist/providers/vercel/index.d.ts",
       "import": "./dist/providers/vercel/index.js"
     },
-    "./providers/wispr-flow": {
-      "types": "./dist/providers/wispr-flow/index.d.ts",
-      "import": "./dist/providers/wispr-flow/index.js"
-    },
     "./ui": {
       "types": "./dist/ui.d.ts",
       "import": "./dist/ui.js"
@@ -198,8 +167,10 @@
     "test:browser:install": "playwright install chromium",
     "test:browser": "playwright test",
     "test:browser:snapshots": "node scripts/update-operator-snapshots.mjs",
+    "goldens:update": "node scripts/update-goldens.mjs",
+    "pregoldens:update": "node scripts/generate-version.mjs && pnpm run build:operator-ui",
     "pretest:browser:snapshots": "pnpm run build:operator-ui",
-    "test:node": "vitest run --project node",
+    "test:node": "vitest run --config vitest.config.node.ts",
     "test:workers": "vitest run --project workers",
     "check:docs": "node scripts/check-doc-links.mjs",
     "check:lint": "oxlint -D correctness --report-unused-disable-directives .",
@@ -209,19 +180,20 @@
     "check:package": "node scripts/check-package.mjs",
     "check:declarations": "node scripts/check-declarations.mjs --dist .",
     "check:bundle": "node scripts/bundle-size.mjs",
-    "providers:check": "tsx scripts/drift-check.mjs --specs --docs",
+    "providers:check": "tsx scripts/drift-check.mjs --specs --manual",
     "drift:check": "tsx scripts/drift-check.mjs",
     "eval:selftest": "tsx eval/selftest.ts",
     "eval:agent": "tsx eval/run-agent.ts",
     "eval:smoke": "tsx eval/run-smoke.ts",
     "eval:perf": "tsx eval/run-perf.ts",
     "eval:report": "tsx eval/report.ts",
-    "check:core": "pnpm run format:check && pnpm run check:providers-generated && pnpm run check:docs && pnpm run check:changes && pnpm run check:operator-ui && pnpm run check:clerk-sdk && pnpm run check:lint && pnpm run check:unused && pnpm run typecheck && pnpm run test && pnpm run build && pnpm run check:declarations && pnpm run check:bundle && pnpm run check:examples",
-    "check:fast": "node scripts/check-fast.mjs",
-    "check": "pnpm run check:core && pnpm run test:browser",
-    "release:check": "pnpm run check && pnpm run check:security && pnpm run check:package",
+    "check:static": "node --test scripts/check-provider-exemptions.test.mjs && pnpm run format:check && pnpm run check:providers-generated && pnpm run check:docs && pnpm run check:changes && pnpm run check:operator-ui && pnpm run check:clerk-sdk && pnpm run check:lint && pnpm run check:unused && pnpm run typecheck",
+    "check:build": "pnpm run build && pnpm run check:declarations && pnpm run check:bundle",
+    "check:fast": "pnpm run check:static && vitest run --config vitest.config.node.ts --changed origin/main --passWithNoTests",
+    "check": "pnpm run check:static && pnpm run test && pnpm run check:build",
+    "release:check": "pnpm run release:check:core && pnpm run release:check:eve",
     "prepack": "pnpm run check",
-    "check:changes": "node scripts/changelog.mjs --check && node scripts/check-node-suites.mjs && node --test scripts/changelog.test.mjs",
+    "check:changes": "node scripts/changelog.mjs --check && node --test scripts/changelog.test.mjs",
     "changelog:assemble": "node scripts/changelog.mjs",
     "providers:generate": "tsx scripts/generate-providers.mjs",
     "check:providers-generated": "tsx scripts/generate-providers.mjs --check",
@@ -232,25 +204,29 @@
     "pretest:browser": "pnpm run build:operator-ui",
     "pretypecheck": "node scripts/generate-version.mjs && pnpm run build:operator-ui",
     "precheck:bundle": "pnpm run build:operator-ui",
-    "precheck:fast": "pnpm run check:operator-ui",
     "eval:regrade": "tsx eval/regrade.ts",
     "eval:compare": "tsx eval/compare.ts",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
-    "providers:spec": "tsx scripts/generate-openapi.mjs"
+    "providers:spec": "tsx scripts/generate-openapi.mjs",
+    "check:eve-package": "node scripts/check-eve-package.mjs",
+    "release:check:core": "pnpm run check && pnpm run test:browser && pnpm run check:examples && pnpm run check:security && pnpm run check:package",
+    "release:check:eve": "pnpm --filter @zackbart/connecta-eve run check && pnpm run check:eve-package && pnpm run check:security:eve",
+    "check:security:eve": "pnpm --dir packages/connecta-eve audit --audit-level moderate"
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/server": "2.3.1",
     "acorn": "^8.19.0",
-    "effect": "^4.0.0",
-    "zod": "^4.4.3"
+    "effect": "4.0.5",
+    "zod": "^4.6.6"
   },
   "peerDependencies": {
     "@clerk/backend": "^3.12.0",
     "@cloudflare/codemode": "^0.4.4 || ^0.5.0",
-    "quickjs-emscripten": "^0.32.0"
+    "quickjs-emscripten": "^0.32.0",
+    "undici": "6.29.1"
   },
   "peerDependenciesMeta": {
     "@clerk/backend": {
@@ -261,6 +237,9 @@
     },
     "quickjs-emscripten": {
       "optional": true
+    },
+    "undici": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -268,6 +247,7 @@
     "@cloudflare/codemode": "^0.5.0",
     "@cloudflare/vitest-pool-workers": "^0.18.8",
     "@cloudflare/workers-types": "^4.20250101.0 || ^5.0.0",
+    "@effect/platform-node": "4.0.5",
     "@fontsource-variable/hanken-grotesk": "^5.3.0",
     "@fontsource-variable/jetbrains-mono": "^5.3.0",
     "@playwright/test": "^1.62.0",
@@ -281,8 +261,8 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
+    "alchemy": "2.0.0-beta.83",
     "cmdk": "^1.1.1",
-    "commonmark": "^0.31.2",
     "esbuild": "^0.28.0",
     "knip": "^6.29.0",
     "oxfmt": "0.72.0",
@@ -293,6 +273,7 @@
     "tailwindcss": "^4.3.3",
     "tsx": "^4.23.1",
     "typescript": "^5.9.3",
+    "undici": "6.29.1",
     "vitest": "^4.1.6",
     "wrangler": "^4.114.0"
   }

package/templates/node/.env.example

@@ -26,6 +26,9 @@ CONNECTA_DATABASE=
 # may write a credential; machine access tokens grant no interactive authority.
 CLERK_PUBLISHABLE_KEY=
 CLERK_SECRET_KEY=
+# Optional with Clerk: the one Clerk Organization (org_...) whose members this
+# deployment admits, when one Clerk instance serves several deployments.
+CLERK_ORGANIZATION_ID=
 # Required with Clerk: comma-separated Clerk user ids of the maintainers, who
 # alone use plain /mcp and the operator UI.
 CONNECTA_MAINTAINERS=

package/templates/node/README.md

@@ -18,6 +18,21 @@ npm run --silent rotate-token -- local-machine
 npm start
 ```
 
+Keep the template's pinned `undici` dependency and its `listen` import from
+`@zackbart/connecta/node`. `listen` installs the owned HTTP transport used by
+every maintained-provider request, reads included, remote MCP writes, and
+downstream OAuth token, registration and revocation POSTs.
+Without `listen()`, maintained-provider writes, reviewed POST reads and remote
+MCP writes are refused before sending; downstream OAuth credential POSTs also
+require the owned sender. It connects directly by default. For an HTTP(S) CONNECT
+proxy, configure `listen(connecta, { port, proxy: "http://proxy.example.com:8080" })`
+in `src/index.ts`. Ambient proxy variables and host dispatchers do not configure
+the owned sender. Remote MCP reads and OAuth discovery GETs retain native fetch
+and need their own host proxy policy. An uncertain refresh requires fresh
+authorization rather than replaying the spent token. See
+[Node transport requirements](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#start-on-node)
+for proxy credentials and TLS trust.
+
 The manifest approves only `esbuild@0.28.2` to run its install script. `tsx`
 uses esbuild to run this TypeScript source, so that script is part of the
 prescribed runtime path. npm 11 therefore installs without an unreviewed-script
@@ -173,6 +188,11 @@ Enable `aud_claim_enabled: true` in Clerk's instance OAuth application settings
 (`PATCH /v1/instance/oauth_application_settings` in Clerk's Backend API), then
 read the setting back. Both JWT and opaque OAuth tokens are supported.
 Leave `allowedOAuthClientIds` omitted or `[]` to require bound tokens.
+To share one Clerk instance across deployments, give each deployment its own
+Clerk Organization and set `CLERK_ORGANIZATION_ID` to its `org_` id: only that
+Organization's members sign in, and maintainers and pool members still come
+from `src/connecta.config.ts`. [Clerk Organizations](https://github.com/zackbart/connecta/blob/main/documentation/auth.md#one-clerk-instance-one-organization-per-deployment)
+lists the Clerk setup and the isolation tradeoff.
 
 Connecta's protected-resource metadata advertises the exact public `/mcp` or
 `/mcp/<pool>` URL as `resource` and Clerk as the authorization server. MCP
@@ -216,8 +236,8 @@ node -e "console.log(crypto.randomBytes(32).toString('base64'))"
 Keep this key outside the database. Losing it makes saved values unreadable;
 upgrades must reuse it. The shipped `time` connector declares no credential
 slot. Add `credential: { label: "API token" }` to an `api()` connector and read
-it through `await ctx.credential?.get()`, or use a Notion
-connector with `auth: { type: "token" }`, which declares its own slot. Maintainers manage the slot on that
+it through `await ctx.credential?.get()`, or use a Stripe
+connector with `auth: { type: "apiKey" }`, which declares its own slot. Maintainers manage the slot on that
 connector's Connection tab (`/connectors/<id>`); there is no separate Credentials tab.
 
 In 0.25.0, this vault also seals downstream OAuth tokens on their first read.

package/templates/node/docker-compose.yml

@@ -28,6 +28,7 @@ services:
       # on when set and off when empty.
       CLERK_PUBLISHABLE_KEY: ${CLERK_PUBLISHABLE_KEY:-}
       CLERK_SECRET_KEY: ${CLERK_SECRET_KEY:-}
+      CLERK_ORGANIZATION_ID: ${CLERK_ORGANIZATION_ID:-}
       CONNECTA_MAINTAINERS: ${CONNECTA_MAINTAINERS:-}
       CONNECTA_CREDENTIAL_KEY: ${CONNECTA_CREDENTIAL_KEY:-}
       CONNECTA_ACTIVITY: ${CONNECTA_ACTIVITY:-}

package/templates/node/package.json

@@ -18,8 +18,9 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.34.1",
-    "quickjs-emscripten": "0.32.0"
+    "@zackbart/connecta": "0.35.0",
+    "quickjs-emscripten": "0.32.0",
+    "undici": "6.29.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/templates/node/src/connecta.config.ts

@@ -25,6 +25,7 @@ export interface Env {
   CONNECTA_DATABASE?: string;
   CLERK_PUBLISHABLE_KEY?: string;
   CLERK_SECRET_KEY?: string;
+  CLERK_ORGANIZATION_ID?: string;
   CONNECTA_MAINTAINERS?: string;
   CONNECTA_CREDENTIAL_KEY?: string;
   CONNECTA_ACTIVITY?: string;
@@ -43,6 +44,10 @@ export default defineConfig((env: Env) => {
   if (Boolean(clerkPublishableKey) !== Boolean(clerkSecretKey)) {
     throw new Error("Operator sign-in needs both CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY.");
   }
+  const clerkOrganizationId = set("CLERK_ORGANIZATION_ID");
+  if (clerkOrganizationId && !clerkSecretKey) {
+    throw new Error("CLERK_ORGANIZATION_ID needs CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY.");
+  }
   const clerk =
     clerkPublishableKey && clerkSecretKey
       ? clerkAuth({
@@ -51,6 +56,9 @@ export default defineConfig((env: Env) => {
           // Enable Clerk aud_claim_enabled; hosts request the MCP URL as
           // resource. Bound JWT and opaque tokens are the default.
           publicUrl,
+          // One Clerk instance can serve many deployments, one Organization
+          // each: with CLERK_ORGANIZATION_ID set, only its members sign in.
+          ...(clerkOrganizationId ? { organizationId: clerkOrganizationId } : {}),
           // Restrict who may sign in with `allowedDomains: ["acme.com"]`, or
           // `gate` for anything a domain cannot express. Absent, every
           // authenticated Clerk user is admitted.

package/dist/catalog-drift.d.ts

@@ -1,138 +0,0 @@
-import type { CatalogDriftCounts, CatalogDriftReport, Connector, Logger, ToolClassification, ToolDef } from "./types.js";
-/**
- * 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 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
- * 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;
-/**
- * What a release decided a tool does. `"read-only"` is observational;
- * `"destructive"` modifies or removes state that already exists; `"additive"`
- * only brings something new into being. Both writes leave the read-only path
- * — the distinction decides whether the connection asserts `destructiveHint`,
- * which shapes the approval copy a human reads.
- */
-type VettedVerdict = "read-only" | "additive" | "destructive";
-/** One tool as a release reviewed it. */
-interface VettedToolRecord {
-    verdict: VettedVerdict;
-    /**
-     * 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 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
- * reviewed, what it reviewed it as, and — where a release recorded them — the
- * schemas it read. This is the single per-provider source P13 asks for, so the
- * classification the connector applies and the classification a drift check
- * compares against cannot disagree.
- */
-export interface VettedCatalog {
-    unlisted?: "hide";
-    /** Manifest format. Bumped when the comparison itself changes shape. */
-    version: 1;
-    tools: ReadonlyMap<string, VettedToolRecord>;
-}
-export interface VettedCatalogInput {
-    /** Names whose contract is observational rather than mutating. */
-    reads: ReadonlySet<string>;
-    /** Names that write, with the verdict that shapes the approval copy. */
-    writes: ReadonlyMap<string, "additive" | "destructive">;
-    /**
-     * Schemas this release reviewed, as `name` → digest from
-     * {@link vettedSchemaDigest}. Omit entirely until a release has actually
-     * 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.
- *
- * Canonical rather than literal, unlike the catalog fingerprint in
- * `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, format?: "sets-v1" | "legacy"): Promise<string>;
-/**
- * Build a provider's manifest from the lists it already maintains.
- *
- * Throws when a name is classified twice, because a tool that is both a read
- * and a write is a review mistake that must not boot: the annotation the
- * connector would apply depends on which branch runs first, and "safe by
- * 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;
-/** 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.
- *
- * 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 declare function detectCatalogDrift(catalog: VettedCatalog, tools: readonly ToolDef[]): Promise<CatalogDriftCounts>;
-/**
- * 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 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, overrides?: Readonly<Record<string, "read" | "write">>, verification?: CatalogSchemaVerification): Promise<ToolDef[]>;
-/**
- * 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 | 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 {};