@wootsup/mcp 0.1.0-rc.9 → 0.3.0

package/dist/modules/apimapper/toolslist-size.js

@@ -0,0 +1,192 @@
+// toolslist-size.ts — W3 Stage-5 token-Δ measurement (Task B)
+//
+// Measures the `tools/list` catalog overhead — the static tool descriptions +
+// JSON schemas an MCP client receives once per session, before any tool is
+// called. This is the DOMINANT token cost center of an API Mapper session.
+//
+// Two figures, both derived from the CURRENT build (canonical counts asserted
+// live in gateway/gateway.test.ts — A2, 2026-06-03):
+//
+//   - POST-W3 `tools/list`        — the 19 surface tools the server now exposes
+//                                   (15 module essentials + `apimapper_advanced`
+//                                   + the 3 src/index.ts top-level tools).
+//   - PRE-W3-equivalent `tools/list` — what `tools/list` WOULD be if all 79
+//                                   tools were exposed flat (the pre-Gateway
+//                                   state): the 19 surface tools minus the
+//                                   gateway tool, plus the 60 advanced-registry
+//                                   tool configs — 78 flat tools. (Pre-W3 the
+//                                   `apimapper_advanced` gateway did not exist.)
+//
+// Per-tool serialization mirrors what the MCP SDK puts on the wire for one
+// `tools/list` entry: `{ name, description, inputSchema, annotations }`, where
+// `inputSchema` is the JSON Schema projected from the tool's Zod raw-shape
+// (the same `z.toJSONSchema` projection `gateway/advanced-tool.ts` uses for
+// discovery mode). `title` and `_meta` are omitted: they are small, present on
+// both sides, and cancel out in the delta — keeping the measurement focused on
+// the description + schema payload that actually scales with the tool count.
+//
+// Determinism: given the same build, every figure is byte-for-byte identical.
+// Pinned by toolslist-size.test.ts.
+import * as os from "node:os";
+import * as path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { loadModules } from "@getimo/mcp-toolkit";
+import { z } from "zod";
+import { apimapperRestModule } from "./index.js";
+import { collectModuleTools } from "./gateway/test-support.js";
+import { registerListProfilesTool, registerUseProfileTool, } from "./use-profile.js";
+import { ProfileStore } from "../../auth/profiles.js";
+/**
+ * Reads a tool config's `inputSchema` as a Zod raw-shape. Mirrors `shapeOf`
+ * in `gateway/advanced-tool.ts` — a registered `inputSchema` is the raw shape
+ * object; a zero-arg tool has none.
+ */
+function shapeOf(inputSchema) {
+    if (inputSchema && typeof inputSchema === "object") {
+        return inputSchema;
+    }
+    return {};
+}
+/**
+ * Projects one tool to its `tools/list` JSON-Schema-bearing catalog entry.
+ * The `inputSchema` is JSON-Schema-projected the same way the SDK and the
+ * gateway's discovery mode do, so the byte count reflects the real wire shape.
+ */
+export function toCatalogEntry(name, tool) {
+    let inputSchema;
+    try {
+        inputSchema = z.toJSONSchema(z.object(shapeOf(tool.inputSchema)));
+    }
+    catch {
+        // A schema that cannot be JSON-projected still yields a usable entry; the
+        // description carries the rest. Matches the gateway discovery-mode guard.
+        inputSchema = { type: "object" };
+    }
+    return {
+        name,
+        description: tool.description,
+        inputSchema,
+        annotations: tool.annotations,
+    };
+}
+/**
+ * Serializes a list of catalog entries and tallies the UTF-8 byte length of
+ * each entry's `JSON.stringify`. The total is the `tools/list` payload size
+ * for that surface.
+ */
+function measure(entries) {
+    const perTool = entries
+        .map((entry) => ({
+        name: entry.name,
+        bytes: Buffer.byteLength(JSON.stringify(entry), "utf8"),
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const totalBytes = perTool.reduce((sum, t) => sum + t.bytes, 0);
+    return { toolCount: perTool.length, totalBytes, perTool };
+}
+/** A no-op keychain: registration stores the dep but never invokes it here. */
+const STUB_KEYCHAIN = {
+    set: async () => undefined,
+    get: async () => null,
+    delete: async () => undefined,
+};
+/**
+ * Captures the 3 top-level tools registered in `src/index.ts` —
+ * `apimapper_rest_modules_status`, `apimapper_use_profile`,
+ * `apimapper_list_profiles` — by replaying their registration against a
+ * recording registrar. `src/index.ts` registers these directly on the
+ * McpServer (not via the module / CapturingServer), so they must be added to
+ * the catalog explicitly for an accurate `tools/list` count.
+ *
+ * The use-profile registrations only *store* their `{ store, keychain }` deps;
+ * they are never invoked at registration time, so a real `ProfileStore` over a
+ * throwaway dir + a stub keychain is sufficient to capture the configs.
+ */
+function captureTopLevelTools() {
+    const captured = new Map();
+    const recorder = {
+        registerTool(name, config) {
+            const cfg = config;
+            captured.set(name, {
+                handler: () => ({ content: [] }),
+                description: cfg.description,
+                inputSchema: cfg.inputSchema,
+                annotations: cfg.annotations,
+            });
+        },
+    };
+    // apimapper_rest_modules_status — registered inline in src/index.ts. Its
+    // config is replicated here verbatim (zero-arg readOnly status tool). The
+    // toolslist-size.test.ts cross-checks the captured name set, so drift
+    // between this replica and src/index.ts surfaces as a failing pin.
+    recorder.registerTool("apimapper_rest_modules_status", {
+        title: "Adapter Modules Status",
+        description: "Module-loading status for this MCP adapter (which sub-modules registered cleanly). " +
+            "For runtime connectivity + auth checks against the API Mapper REST surface, use apimapper_health.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false, title: "MCP Modules Status" },
+    });
+    // apimapper_use_profile + apimapper_list_profiles — registered via the
+    // use-profile module functions. Replaying the real registration functions
+    // captures their exact live config (description + Zod inputSchema).
+    // F-1.1 (Pass-1 consolidation): platform-portable temp path. The store is a
+    // throwaway used purely for tool-list shape capture during the measurement.
+    const store = new ProfileStore(path.join(os.tmpdir(), "__w3_toolslist_measure__"));
+    registerUseProfileTool(recorder, { store, keychain: STUB_KEYCHAIN });
+    registerListProfilesTool(recorder, { store, keychain: STUB_KEYCHAIN });
+    return captured;
+}
+/**
+ * Builds the full 79-tool catalog from the current build and measures the
+ * post-W3 vs pre-W3-equivalent `tools/list` payload sizes.
+ *
+ * Surface composition (verified against `gateway/essentials.ts` + `src/index.ts`,
+ * pinned live in `gateway/gateway.test.ts` — A2):
+ *   - module tools  : 15 essentials + `apimapper_advanced` = 16 (on the real
+ *                     McpServer) + 60 advanced (gateway registry)            = 76
+ *   - top-level tools: rest_modules_status + use_profile + list_profiles      =  3
+ *                                                                      total = 79
+ *
+ * POST-W3 `tools/list` = the 16 module-real tools + the 3 top-level tools = 19.
+ * PRE-W3 flat `tools/list` = the 18 non-gateway surface tools + the 60 advanced
+ * tools = 78 (the `apimapper_advanced` gateway did not exist pre-W3).
+ */
+export async function measureToolsList() {
+    const server = new McpServer({
+        name: "toolslist-size-measure",
+        version: "0.0.0",
+    });
+    await loadModules(server, [apimapperRestModule]);
+    // collectModuleTools unifies the real-server essentials (incl. the gateway
+    // tool) with the captured advanced-registry tools.
+    const moduleTools = collectModuleTools(server, apimapperRestModule);
+    const topLevelTools = captureTopLevelTools();
+    const advancedRegistry = apimapperRestModule.getAdvancedRegistry();
+    const advancedNames = new Set(advancedRegistry ? advancedRegistry.keys() : []);
+    // POST-W3 surface: every tool in `tools/list` today — module-real tools that
+    // are NOT in the advanced registry (i.e. essentials + the gateway) plus the
+    // 3 top-level tools.
+    const postEntries = [];
+    for (const [name, tool] of Object.entries(moduleTools)) {
+        if (advancedNames.has(name))
+            continue; // advanced — gated behind the gateway
+        postEntries.push(toCatalogEntry(name, tool));
+    }
+    for (const [name, tool] of topLevelTools) {
+        postEntries.push(toCatalogEntry(name, tool));
+    }
+    // PRE-W3-equivalent flat surface: the post-W3 surface MINUS the gateway tool
+    // (it did not exist pre-W3) PLUS every advanced tool exposed flat.
+    const preEntries = postEntries.filter((e) => e.name !== "apimapper_advanced");
+    for (const [name, tool] of Object.entries(moduleTools)) {
+        if (!advancedNames.has(name))
+            continue; // only the advanced tools
+        preEntries.push(toCatalogEntry(name, tool));
+    }
+    const postW3 = measure(postEntries);
+    const preW3Flat = measure(preEntries);
+    const bytesSaved = preW3Flat.totalBytes - postW3.totalBytes;
+    const fractionSaved = preW3Flat.totalBytes > 0 ? bytesSaved / preW3Flat.totalBytes : 0;
+    return { postW3, preW3Flat, bytesSaved, fractionSaved };
+}
+//# sourceMappingURL=toolslist-size.js.map

package/dist/modules/apimapper/toolslist-size.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolslist-size.js","sourceRoot":"","sources":["../../../src/modules/apimapper/toolslist-size.ts"],"names":[],"mappings":"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"}

package/dist/modules/apimapper/types.d.ts

@@ -39,6 +39,27 @@ export interface Credential {
     auth_type: string;
     oauth_provider?: string | null;
     oauth_token_expires_at?: string | null;
+    /**
+     * Wave-12 F1 (Cold-AI #6) — canonical token-validity surface emitted by the
+     * PHP `/credentials` endpoint (`CredentialRepository::calculateStatus`).
+     * Values: 'active' | 'expiring' | 'expired' | 'broken'.
+     *
+     * - 'active' covers credentials with a refresh-token even if their
+     *   short-lived access token's `oauth_token_expires_at` is in the past —
+     *   they auto-renew on next use.
+     * - 'expired' is the only state where the customer truly needs to reconnect.
+     *
+     * The onboarding suggestion engine MUST prefer this field over the raw
+     * `oauth_token_expires_at` heuristic to avoid false-positive reconnect
+     * prompts for refreshable tokens (Google, GitHub, etc.).
+     */
+    status?: "active" | "expiring" | "expired" | "broken" | string | null;
+    /**
+     * Hard-expiry timestamp emitted ONLY for credentials WITHOUT a refresh-token
+     * (e.g. Meta/Instagram 60-day expiry). When this field is null/absent on an
+     * OAuth credential, the token is auto-refreshable and not user-visibly expirable.
+     */
+    token_hard_expires_at?: string | null;
     provider?: string | null;
     created_at?: string;
     updated_at?: string;
@@ -53,14 +74,8 @@ export interface FlowNode {
     data?: Record<string, unknown>;
     [k: string]: unknown;
 }
-export interface FlowEdge {
-    id: string;
-    source: string;
-    target: string;
-    sourceHandle?: string;
-    targetHandle?: string;
-    [k: string]: unknown;
-}
+import type { FlowEdge } from "./node-schema.js";
+export type { FlowEdge };
 export interface Flow {
     id: string;
     name: string;
@@ -109,3 +124,24 @@ export interface LicenseStatus {
     activation_count?: number;
     max_activations?: number;
 }
+/**
+ * Bridge a typed-domain array to the toolkit's structurally-typed table-row
+ * shape.
+ *
+ * The mcp-core `tableResult()` (and other table builders) accept
+ * `Record<string, unknown>[]` for ASCII-table serialization. Our domain
+ * interfaces (`Connection`, `Credential`, `Flow`, `LibraryItem`, …) are
+ * nominal types without an index signature, so they are not structurally
+ * assignable to `Record<string, unknown>` even though every concrete row
+ * happens to satisfy it at runtime.
+ *
+ * Rather than scatter `items as unknown as Record<string, unknown>[]`
+ * across call-sites — each one looking like a code smell — this is the
+ * single documented interop point. Call-sites stay cast-free and the
+ * narrowing decision lives in ONE place that reviewers can audit.
+ *
+ * This is NOT a license to widen domain types — fields used downstream
+ * (column `key`s in the table config) are still type-checked against the
+ * domain interface separately.
+ */
+export declare function toRows<T extends object>(items: readonly T[]): Record<string, unknown>[];

package/dist/modules/apimapper/types.js

@@ -10,5 +10,30 @@
 //   - LocalSource wire fmt   = camelCase (contentType) with "platform/type" id ("wordpress/posts")
 //
 // These types reflect the actual REST contract verified against the PHP controllers.
-export {};
+// =============================================================================
+// Domain → toolkit interop bridge (F-1.2 — Pass-1 consolidation)
+// =============================================================================
+/**
+ * Bridge a typed-domain array to the toolkit's structurally-typed table-row
+ * shape.
+ *
+ * The mcp-core `tableResult()` (and other table builders) accept
+ * `Record<string, unknown>[]` for ASCII-table serialization. Our domain
+ * interfaces (`Connection`, `Credential`, `Flow`, `LibraryItem`, …) are
+ * nominal types without an index signature, so they are not structurally
+ * assignable to `Record<string, unknown>` even though every concrete row
+ * happens to satisfy it at runtime.
+ *
+ * Rather than scatter `items as unknown as Record<string, unknown>[]`
+ * across call-sites — each one looking like a code smell — this is the
+ * single documented interop point. Call-sites stay cast-free and the
+ * narrowing decision lives in ONE place that reviewers can audit.
+ *
+ * This is NOT a license to widen domain types — fields used downstream
+ * (column `key`s in the table config) are still type-checked against the
+ * domain interface separately.
+ */
+export function toRows(items) {
+    return items;
+}
 //# sourceMappingURL=types.js.map

package/dist/modules/apimapper/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/apimapper/types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,EAAE;AACF,yEAAyE;AACzE,iGAAiG;AACjG,oFAAoF;AACpF,wEAAwE;AACxE,iFAAiF;AACjF,sEAAsE;AACtE,6EAA6E;AAC7E,mGAAmG;AACnG,EAAE;AACF,qFAAqF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/apimapper/types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,EAAE;AACF,yEAAyE;AACzE,iGAAiG;AACjG,oFAAoF;AACpF,wEAAwE;AACxE,iFAAiF;AACjF,sEAAsE;AACtE,6EAA6E;AAC7E,mGAAmG;AACnG,EAAE;AACF,qFAAqF;AAmJrF,gFAAgF;AAChF,iEAAiE;AACjE,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,MAAM,CAAmB,KAAmB;IAC1D,OAAO,KAAwD,CAAC;AAClE,CAAC"}

package/dist/modules/apimapper/use-profile.d.ts

@@ -31,4 +31,25 @@ export interface UseProfileDeps {
  */
 export declare function defaultProbeIdentity(profile: Profile, token: string): Promise<IdentityProbeResult>;
 export declare function registerUseProfileTool(server: ToolRegistrar | McpServer, deps: UseProfileDeps): void;
+/**
+ * Dependencies for `registerListProfilesTool`. Matches the
+ * `UseProfileDeps` shape so callers can pass the same object — `keychain`
+ * is currently unused but kept in the signature for symmetry with
+ * apimapper_use_profile (so the wiring in src/index.ts is consistent and
+ * the contract can evolve without breaking callers).
+ */
+export interface ListProfilesDeps {
+    store: ProfileStore;
+    keychain: Keychain;
+}
+/**
+ * Register the `apimapper_list_profiles` tool. Read-only — returns the
+ * configured profile registry with an `is_active` flag derived from the
+ * ProfileStore active pointer.
+ *
+ * Closes the broken xref in `apimapper_use_profile`'s "profile not found"
+ * hint, which previously pointed AI clients at this tool when it did not
+ * yet exist.
+ */
+export declare function registerListProfilesTool(server: ToolRegistrar | McpServer, deps: ListProfilesDeps): void;
 export {};

package/dist/modules/apimapper/use-profile.js

@@ -12,7 +12,7 @@
 // Dependencies (store/keychain/probe) are injected for testability — the
 // real wire-through happens in src/index.ts where the server is constructed.
 import { z } from "zod";
-import { formatResult, readOnly } from "@getimo/mcp-toolkit";
+import { formatResult, mutating, readOnly } from "@getimo/mcp-toolkit";
 import { createPlatform, } from "../../platform/index.js";
 import { createPlatformClient } from "./client.js";
 // ── Real probe (used in production) ──────────────────────────────────────
@@ -85,7 +85,16 @@ export function registerUseProfileTool(server, deps) {
                 .default(false)
                 .describe("Skip the live /identity probe. Use for offline activation when the site is unreachable."),
         },
-        annotations: readOnly(),
+        // A6-P2 (W1.26 follow-up): handler writes ProfileStore state
+        // (`store.setActive` + `store.update(lastVerifiedIdentity)`), so the
+        // tool is NOT read-only per MCP spec ("readOnlyHint: does not modify
+        // its environment"). `mutating()` correctly carries
+        // `idempotentHint: true` — re-activating the same profile is a no-op
+        // beyond refreshing the verified-identity timestamp.
+        // W1.26.b: closed-world — effects are bounded to the local profile
+        // registry; identity probe is an internal Bearer + /identity call,
+        // not a third-party service mutation.
+        annotations: mutating({ title: "Switch Active Profile", openWorld: false }),
     }, async (args) => {
         const { name, noProbe = false } = args;
         // ── 1. Profile lookup ────────────────────────────────────────────
@@ -177,4 +186,49 @@ export function registerUseProfileTool(server, deps) {
         return formatResult(payload, false, { maxChars: 3000 });
     });
 }
+/**
+ * Register the `apimapper_list_profiles` tool. Read-only — returns the
+ * configured profile registry with an `is_active` flag derived from the
+ * ProfileStore active pointer.
+ *
+ * Closes the broken xref in `apimapper_use_profile`'s "profile not found"
+ * hint, which previously pointed AI clients at this tool when it did not
+ * yet exist.
+ */
+export function registerListProfilesTool(server, deps) {
+    const registrar = server;
+    registrar.registerTool("apimapper_list_profiles", {
+        title: "List Configured Profiles",
+        description: "List all configured site profiles (name, siteUrl, platform) with an " +
+            "is_active flag indicating which one is currently active. " +
+            "Use this to discover available profile names before calling " +
+            "apimapper_use_profile to switch the active profile. " +
+            "Read-only — does not contact any site." +
+            "\n\nResponse shape:\n" +
+            "  { profile_count, active_profile, profiles: [{ name, siteUrl, platform, is_active, lastVerifiedAt? }] }",
+        inputSchema: {},
+        annotations: readOnly({ title: "List Configured Profiles", openWorld: false }),
+    }, async () => {
+        const all = await deps.store.list();
+        const active = await deps.store.getActive();
+        const activeName = active?.name ?? null;
+        const profiles = all.map((p) => {
+            const entry = {
+                name: p.name,
+                siteUrl: p.siteUrl,
+                platform: p.platform,
+                is_active: p.name === activeName,
+            };
+            if (p.lastVerifiedIdentity) {
+                entry.lastVerifiedAt = "set";
+            }
+            return entry;
+        });
+        return formatResult({
+            profile_count: profiles.length,
+            active_profile: activeName,
+            profiles,
+        }, false, { maxChars: 3000 });
+    });
+}
 //# sourceMappingURL=use-profile.js.map

package/dist/modules/apimapper/use-profile.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-profile.js","sourceRoot":"","sources":["../../../src/modules/apimapper/use-profile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-profile.js","sourceRoot":"","sources":["../../../src/modules/apimapper/use-profile.ts"],"names":[],"mappings":"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"}

package/dist/modules/apimapper/whitelist-drift.d.ts

@@ -0,0 +1,85 @@
+/** How a tool's request body relates to the PHP route. */
+export type ToolBodyKind = "structured" | "envelope";
+/** One body-sending tool's route binding. */
+export interface ToolWireBinding {
+    /** HTTP method + normalised path, e.g. "POST /connections". Joins the manifest. */
+    route: string;
+    /** The literal wire body keys the tool sends (envelope tools list their wrapper key). */
+    bodyKeys: readonly string[];
+    kind: ToolBodyKind;
+}
+/**
+ * Curated bridge: body-sending tool → route + wire body keys.
+ *
+ * ONLY tools that send a request body appear here. Read-only (GET) tools and
+ * path/query-only tools carry no body-drift surface and are listed in the
+ * manifest's `_local_tools` (when they hit no route at all) or are simply
+ * absent (when they hit a GET route — GET routes never drift on body keys).
+ *
+ * `envelope` tools forward a free-form record (`patch` / `pipeline` / a settings
+ * map) whose individual keys are validated on the PHP side (e.g.
+ * ConnectionAdminController::ALLOWED_PATCH_KEYS). Their wrapper key is recorded
+ * so the test confirms the tool is accounted for; per-key validation lives in
+ * the PHP layer and is covered by PHP-side tests.
+ */
+export declare const TOOL_WIRE_MAP: Readonly<Record<string, ToolWireBinding>>;
+/** The PHP-accepted-params manifest fixture shape. */
+export interface PhpAcceptedManifest {
+    /** "<METHOD> <path>" → accepted request-body keys. */
+    routes: Record<string, string[]>;
+    /** tool → { wire-key → justification } for keys the PHP route does not read. */
+    _allowed_drift: Record<string, Record<string, string>>;
+    /** tool → reason: tools with no REST route (purely client-side / aggregate). */
+    _local_tools: Record<string, string>;
+    /** route → { php-key → reason } for keys PHP accepts that no tool sends. */
+    _inverse_ignore?: Record<string, Record<string, string>>;
+    _meta?: Record<string, unknown>;
+}
+/** A single forward-direction drift: a wire key the PHP route does not accept. */
+export interface DriftFinding {
+    tool: string;
+    route: string;
+    key: string;
+}
+/** A single inverse-direction advisory: a PHP-accepted key no tool sends. */
+export interface InverseFinding {
+    route: string;
+    key: string;
+}
+export interface DriftReport {
+    /** Dangerous direction: tool sends a key PHP neither accepts nor allow-lists. */
+    drift: DriftFinding[];
+    /** Advisory: PHP accepts a key no tool sends (minus `_inverse_ignore`). */
+    inverse: InverseFinding[];
+    /** Live tools missing from BOTH TOOL_WIRE_MAP and `_local_tools` (coverage gap). */
+    uncovered: string[];
+    /** Entries in TOOL_WIRE_MAP / `_local_tools` no longer present in the live surface. */
+    stale: string[];
+}
+/**
+ * Resolve the committed fixture path. From this module
+ * (`<pkg>/{src,dist}/modules/apimapper/whitelist-drift.{ts,js}`) the package
+ * root is three directories up; the fixture is `tests/fixtures/...` under it.
+ * The depth is identical for the source layout (vitest/tsx) and the built
+ * `dist/` layout, so the same relative offset works in both.
+ */
+export declare function manifestPath(): string;
+/** Load + validate the committed PHP-accepted-params manifest. */
+export declare function loadManifest(path?: string): PhpAcceptedManifest;
+/**
+ * Enumerate every registered MCP tool name. Mirrors the runtime tool surface:
+ *   - module essentials forwarded to a real McpServer,
+ *   - the gateway-captured advanced tools,
+ *   - the profile / status tools registered in src/index.ts AFTER module load.
+ *
+ * The src/index.ts trio is appended explicitly: they are registered on the real
+ * server outside the module's register(), so a module-only enumeration would
+ * miss them. They are pure local/profile tools (no REST body) and live in
+ * `_local_tools`; listing them here keeps the coverage check honest.
+ */
+export declare function collectLiveTools(): string[];
+/**
+ * Compute the drift report from the live tool surface + the curated wire map +
+ * the PHP-accepted manifest. Pure — no I/O.
+ */
+export declare function computeDrift(liveTools: readonly string[], manifest: PhpAcceptedManifest): DriftReport;