vigiles 14.7.0 → 14.8.0

package/dist/audit-score.d.ts

@@ -26,7 +26,7 @@
  * A category that can't be assessed scores `null` (n/a) and is EXCLUDED from the
  * overall — never a false 0. Pure over the `ScanReport`, so it's fully testable.
  */
-import { type PluginScore } from "./leaderboard.js";
+import { type PluginScore } from "./score-core.js";
 import type { ScanReport } from "./scan.js";
 export type CategoryKey = "Truthfulness" | "Triggering" | "Structure" | "Safety" | "Tested";
 export interface CategoryScore {

package/dist/audit-score.js

@@ -30,7 +30,7 @@ exports.formatAuditScore = formatAuditScore;
  * A category that can't be assessed scores `null` (n/a) and is EXCLUDED from the
  * overall — never a false 0. Pure over the `ScanReport`, so it's fully testable.
  */
-const leaderboard_js_1 = require("./leaderboard.js");
+const score_core_js_1 = require("./score-core.js");
 // Per-item penalties are the SHARED leaderboard weights (imported above) so the
 // category rings and the single health number can never drift. W_UNTESTED is
 // audit-only — untested surfaces are advisory (shown, never scored into overall).
@@ -64,12 +64,12 @@ function truthfulness(r) {
     const { score, findings } = scoreFrom([
         {
             n: r.danglingRefs.length,
-            weight: leaderboard_js_1.W_DANGLING_REF,
+            weight: score_core_js_1.W_DANGLING_REF,
             label: "broken intra-plugin reference(s)",
         },
         {
             n: missingHooks,
-            weight: leaderboard_js_1.W_MISSING_HOOK,
+            weight: score_core_js_1.W_MISSING_HOOK,
             label: "hook script(s) missing (never run)",
         },
     ]);
@@ -80,12 +80,12 @@ function triggering(r) {
     const { score, findings } = scoreFrom([
         {
             n: noDesc,
-            weight: leaderboard_js_1.W_NO_DESCRIPTION,
+            weight: score_core_js_1.W_NO_DESCRIPTION,
             label: "skill(s) with no usable description (can't trigger)",
         },
         {
             n: r.descriptionOverlaps.length,
-            weight: leaderboard_js_1.W_OVERLAP,
+            weight: score_core_js_1.W_OVERLAP,
             label: "near-identical skill description(s) (wrong one fires)",
         },
     ]);
@@ -99,42 +99,42 @@ function structure(r) {
     const { score, findings } = scoreFrom([
         {
             n: deadTools,
-            weight: leaderboard_js_1.W_DANGLING_REF,
+            weight: score_core_js_1.W_DANGLING_REF,
             label: "unavailable agent tool(s) (typo / never-available)",
         },
         {
             n: deadMcpTools,
-            weight: leaderboard_js_1.W_DANGLING_REF,
+            weight: score_core_js_1.W_DANGLING_REF,
             label: "agent MCP tool(s) whose server isn't declared",
         },
         {
             n: r.hookEventIssues.length,
-            weight: leaderboard_js_1.W_MISSING_HOOK,
+            weight: score_core_js_1.W_MISSING_HOOK,
             label: "hook(s) on an unknown event (never fire)",
         },
         {
             n: r.mcpIssues.length,
-            weight: leaderboard_js_1.W_DANGLING_REF,
+            weight: score_core_js_1.W_DANGLING_REF,
             label: "MCP server(s) that can't start (no command/url)",
         },
         {
             n: r.mcpHookIssues.length,
-            weight: leaderboard_js_1.W_DANGLING_REF,
+            weight: score_core_js_1.W_DANGLING_REF,
             label: "mcp_tool hook(s) incomplete / undeclared server",
         },
         {
             n: r.frontmatterIssues.length,
-            weight: leaderboard_js_1.W_NO_DESCRIPTION,
+            weight: score_core_js_1.W_NO_DESCRIPTION,
             label: "surface(s) missing required frontmatter",
         },
         {
             n: r.frontmatterValueIssues.length,
-            weight: leaderboard_js_1.W_NO_CONTRACT,
+            weight: score_core_js_1.W_NO_CONTRACT,
             label: "agent(s) with an invalid model/color (silent fallback)",
         },
         {
             n: deadDisallowed,
-            weight: leaderboard_js_1.W_NO_CONTRACT,
+            weight: score_core_js_1.W_NO_CONTRACT,
             label: "disallowedTools typo(s) that block nothing",
         },
     ]);
@@ -185,7 +185,7 @@ function safety(r) {
     const { score, findings } = scoreFrom([
         {
             n: hard.length,
-            weight: leaderboard_js_1.W_TRIFECTA,
+            weight: score_core_js_1.W_TRIFECTA,
             label: "unit(s) holding all three lethal-trifecta legs (prompt-injection exfil path)",
         },
     ]);
@@ -193,7 +193,7 @@ function safety(r) {
     // note but never graded (mirrors the Structure inherits-all advisory).
     const advisory = r.trifectaFindings
         .filter((f) => f.finding.severity === "advisory")
-        .map((f) => `${f.name} inherits all tools — maximal trifecta blast radius (advisory)`);
+        .map((f) => `${f.name} inherits all tools — the "lethal trifecta" (reads data, reaches the web, runs commands), so a prompt injection could exfiltrate secrets (advisory)`);
     return {
         key: "Safety",
         score,
@@ -217,7 +217,7 @@ function tested(r) {
  * an instruction file as a surface.)
  */
 function isEmptyAudit(r) {
-    return (0, leaderboard_js_1.isEmptyMachine)(r) && !r.instructions;
+    return (0, score_core_js_1.isEmptyMachine)(r) && !r.instructions;
 }
 /**
  * Bucket a scan report into the five deterministic Lighthouse categories as a
@@ -237,7 +237,7 @@ function auditScore(report) {
         ];
         return {
             overall: 0,
-            grade: (0, leaderboard_js_1.gradeFor)(0),
+            grade: (0, score_core_js_1.gradeFor)(0),
             categories: categories.map((key) => ({
                 key,
                 score: null,
@@ -258,8 +258,8 @@ function auditScore(report) {
     // of the rings — averaging would let a real problem in one category be diluted
     // by clean siblings. The rings above stay a diagnostic breakdown; Tested
     // (advisory) is never summed in (untested surfaces don't drag the grade).
-    const { score: overall } = (0, leaderboard_js_1.computeIntegrityScore)((0, leaderboard_js_1.reportDeductions)(report));
-    return { overall, grade: (0, leaderboard_js_1.gradeFor)(overall), categories, empty: false };
+    const { score: overall } = (0, score_core_js_1.computeIntegrityScore)((0, score_core_js_1.reportDeductions)(report));
+    return { overall, grade: (0, score_core_js_1.gradeFor)(overall), categories, empty: false };
 }
 // A 22-cell bar gauge ("ring" in the terminal; the real rings are the HTML).
 const BAR_CELLS = 22;

package/dist/audit-verdict.d.ts

@@ -40,7 +40,7 @@
  */
 import { type AuditScore } from "./audit-score.js";
 import type { Recommendation } from "./optimize.js";
-import { type PluginScore } from "./leaderboard.js";
+import { type PluginScore } from "./score-core.js";
 import type { ScanReport } from "./scan.js";
 /**
  * The inputs the verdict needs — exactly the pieces {@link buildAuditReport}

package/dist/audit-verdict.js

@@ -42,7 +42,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeVerdict = computeVerdict;
 const audit_score_js_1 = require("./audit-score.js");
-const leaderboard_js_1 = require("./leaderboard.js");
+const score_core_js_1 = require("./score-core.js");
 // The grade-band FLOORS (A ≥90 … D ≥60; below 60 is F), mirroring gradeFor.
 const GRADE_FLOORS = [60, 70, 80, 90];
 /** The smallest band floor strictly above `overall`, or null when already an A. */
@@ -195,7 +195,7 @@ function overallWithout(report, recs) {
  */
 function dominantDeduction(report) {
     let best = null;
-    for (const d of (0, leaderboard_js_1.reportDeductions)(report)) {
+    for (const d of (0, score_core_js_1.reportDeductions)(report)) {
         if (d.n <= 0)
             continue;
         const cost = d.n * d.weight;
@@ -238,7 +238,7 @@ function buildSentence(input, pointsToNextGrade, fixesToNextGrade) {
         return `A — nothing blocking the grade; ${numberWord(n)} deterministic ${fixNoun(n)} would harden it further.`;
     }
     // The next band's grade is gradeFor(its FLOOR); the floor is base + the gap.
-    const nextGrade = (0, leaderboard_js_1.gradeFor)(score.overall + pointsToNextGrade);
+    const nextGrade = (0, score_core_js_1.gradeFor)(score.overall + pointsToNextGrade);
     // Reachable by the deterministic fix list: fix-count-forward (the actionable framing).
     if (fixesToNextGrade !== null) {
         return `${capitalize(numberWord(fixesToNextGrade))} ${fixNoun(fixesToNextGrade)} away from ${article(nextGrade)} ${nextGrade}.`;

package/dist/core/assert-never.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `assertNever` — the exhaustive-switch guard, in its own NODE-FREE leaf so a
+ * consumer can import it WITHOUT pulling `core/hash.ts` (which imports
+ * `node:crypto` for `sha256short`) into a browser bundle. The deterministic audit
+ * engine reaches this via `core/effects.ts`; `hash.ts` re-exports it so every
+ * existing `import { assertNever } from "./hash.js"` is unchanged.
+ */
+export declare function assertNever(x: never): never;
+//# sourceMappingURL=assert-never.d.ts.map

package/dist/core/assert-never.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNever = assertNever;
+/**
+ * `assertNever` — the exhaustive-switch guard, in its own NODE-FREE leaf so a
+ * consumer can import it WITHOUT pulling `core/hash.ts` (which imports
+ * `node:crypto` for `sha256short`) into a browser bundle. The deterministic audit
+ * engine reaches this via `core/effects.ts`; `hash.ts` re-exports it so every
+ * existing `import { assertNever } from "./hash.js"` is unchanged.
+ */
+function assertNever(x) {
+    throw new Error(`Unexpected value: ${String(x)}`);
+}
+//# sourceMappingURL=assert-never.js.map

package/dist/core/description-overlap.js

@@ -17,7 +17,7 @@ exports.findDescriptionOverlaps = findDescriptionOverlaps;
  * copy-pasted description with a word or two changed) — never on a parallel but
  * distinct pair. Warn-level, reports the PAIR (not a unilateral defect).
  */
-const proofs_js_1 = require("./proofs.js");
+const ncd_js_1 = require("./ncd.js");
 /**
  * The NCD cutoff below which two descriptions count as a near-duplicate. 0.2 sits
  * safely under the sweep's most-similar legitimately-distinct pair (0.25), so
@@ -35,7 +35,7 @@ function findDescriptionOverlaps(surfaces, cutoff = exports.OVERLAP_NCD_CUTOFF)
     const overlaps = [];
     for (let i = 0; i < surfaces.length; i++) {
         for (let j = i + 1; j < surfaces.length; j++) {
-            const d = (0, proofs_js_1.ncd)(surfaces[i].description, surfaces[j].description);
+            const d = (0, ncd_js_1.ncd)(surfaces[i].description, surfaces[j].description);
             if (d >= cutoff)
                 continue;
             const a = surfaces[i].name;

package/dist/core/effects.js

@@ -5,7 +5,7 @@ exports.effectSurface = effectSurface;
 exports.purityViolations = purityViolations;
 exports.pureContractViolations = pureContractViolations;
 exports.decidePurityGate = decidePurityGate;
-const hash_js_1 = require("./hash.js");
+const assert_never_js_1 = require("./assert-never.js");
 const bash_effects_js_1 = require("./bash-effects.js");
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -83,7 +83,7 @@ function effectSurface(tools, dialect) {
                 unknown.add(base);
                 break;
             default:
-                (0, hash_js_1.assertNever)(effect);
+                (0, assert_never_js_1.assertNever)(effect);
         }
     }
     const purity = hasWildcard || hasBash || unknown.size > 0
@@ -170,7 +170,7 @@ function purityViolations(tools, dialect, declared) {
                 });
                 break;
             default:
-                (0, hash_js_1.assertNever)(effect);
+                (0, assert_never_js_1.assertNever)(effect);
         }
     }
     return violations;

package/dist/core/hash.d.ts

@@ -1,8 +1,7 @@
+export { assertNever } from "./assert-never.js";
 declare const __brand: unique symbol;
 export type SHA256Hash = string & {
     readonly [__brand]: "SHA256Hash";
 };
 export declare function sha256short(data: string | Buffer): SHA256Hash;
-export declare function assertNever(x: never): never;
-export {};
 //# sourceMappingURL=hash.d.ts.map

package/dist/core/hash.js

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNever = void 0;
 exports.sha256short = sha256short;
-exports.assertNever = assertNever;
 const node_crypto_1 = require("node:crypto");
+// `assertNever` lives in a node-free leaf (no crypto), re-exported here so every
+// existing `import { assertNever } from "./hash.js"` is unchanged while a
+// browser-bound module can import it from ./assert-never.js without pulling crypto.
+var assert_never_js_1 = require("./assert-never.js");
+Object.defineProperty(exports, "assertNever", { enumerable: true, get: function () { return assert_never_js_1.assertNever; } });
 const HASH_LENGTH = 16;
 function sha256short(data) {
     return (0, node_crypto_1.createHash)("sha256")
@@ -10,7 +15,4 @@ function sha256short(data) {
         .digest("hex")
         .slice(0, HASH_LENGTH);
 }
-function assertNever(x) {
-    throw new Error(`Unexpected value: ${String(x)}`);
-}
 //# sourceMappingURL=hash.js.map

package/dist/core/hook-block-ineffective.d.ts

@@ -1,3 +1,51 @@
+/**
+ * Hook-block-ineffective detector — the #1 verified hook pain ("false confidence").
+ *
+ * A safety hook that LOOKS like it blocks but SILENTLY DOESN'T. Two shapes:
+ *
+ * 1. **wrong-event** — the script tries to block (contains `exit 2`, a legacy
+ *    `"decision":"block"` JSON, or a `"permissionDecision":"deny"`) but is
+ *    registered on an event where a block is SILENTLY IGNORED ENTIRELY —
+ *    SessionStart / SessionEnd / Notification / PreCompact, where exit 2 writes
+ *    stderr only to the user (no veto, no model feedback). The author believes a
+ *    gate is in place; nothing happens. (#19009 names the class.) NB `PostToolUse`
+ *    is deliberately NOT flagged: there exit 2 feeds stderr back to the model — a
+ *    legitimate FEEDBACK channel (a nudge/lint hook), not a failed block, and the
+ *    block-vs-feedback intent isn't deterministically separable.
+ *
+ * 2. **wrong-field** — the hook IS on a permission-gated event (e.g. PreToolUse)
+ *    but emits the LEGACY top-level `"decision":"block"` field instead of the
+ *    required `hookSpecificOutput.permissionDecision:"deny"`. A copied template
+ *    (PostToolUse style → PreToolUse registration) is the usual cause; the deny
+ *    is silently discarded, nothing is blocked.
+ *
+ * Both shapes cause identical user-visible behaviour: the hook "works" (exits,
+ * no crash) but never actually stops anything. The only signal is "why did this
+ * run anyway?" after an incident.
+ *
+ * FP-SAFETY — conservative literal patterns only, `warn` severity by default:
+ *   - `exit 2` is matched by a shell-context regex that requires surrounding
+ *     whitespace/control chars to avoid false-positives on `exit 200` or a
+ *     `git status --exit-code 2` argument.
+ *   - JSON decision patterns are matched literally (no partial JSON walking).
+ *   - Nothing is flagged on an unknown event (we only know which events CAN
+ *     block because the caller injected that set).
+ *
+ * HARNESS-NEUTRAL — the sets of blocking events and permission-decision events
+ * are INJECTED from the dialect (never hard-coded here). The caller supplies the
+ * Claude Code sets; a Codex adapter supplies its own. This is the same
+ * dependency-injection pattern used by `verifyHookEvents` and `verifyToolContract`
+ * (core ⊄ adapter — one-detector-no-drift).
+ *
+ * ONE detector reused by scan + the `hook-block-ineffective` lint rule (two
+ * callers, no drift). See `research/hook-pain-points.md` for the verified corpus
+ * and `docs/compiled-hooks.md` for the authoritative fix (compiled hooks make
+ * this whole class unrepresentable).
+ *
+ * Node-free: the `readFileSync` IO is REQUIRED (injected by the caller — the disk
+ * scan passes `node:fs`, the browser engine a map-backed read), so this module
+ * never statically imports `node:fs` and bundles clean in a browser.
+ */
 /** The two "looks like it blocks but doesn't" failure shapes. */
 export type HookBlockKind = "wrong-event" | "wrong-field";
 /** One false-confidence finding: a hook that appears to block but silently won't. */
@@ -41,11 +89,12 @@ export interface HookBlockOptions {
      */
     readonly permissionDecisionEvents: ReadonlySet<string>;
     /**
-     * Injectable file read (default: node:fs `readFileSync(p, "utf8")`).
-     * Returns `""` on any error so a missing / unreadable script doesn't crash
-     * the detector — it simply produces no findings for that entry.
+     * REQUIRED file read (the disk caller injects `node:fs`
+     * `readFileSync(p, "utf8")`; the browser engine a map-backed read). Should
+     * return `""` on any error so a missing / unreadable script doesn't crash the
+     * detector — it simply produces no findings for that entry.
      */
-    readonly readFileSync?: (p: string) => string;
+    readonly readFileSync: (p: string) => string;
 }
 /**
  * Detect false-confidence "blocks" across a set of hook entries.
@@ -55,8 +104,8 @@ export interface HookBlockOptions {
  * (event, kind, scriptPath) pairs are de-duped.
  *
  * @param entries - The hook registrations to inspect (event + command/script).
- * @param opts    - Injected sets of blocking/permission events, and an optional
- *                  `readFileSync` (default: node:fs).
+ * @param opts    - Injected sets of blocking/permission events, and the required
+ *                  `readFileSync` (disk caller: node:fs; browser: map-backed).
  */
 export declare function hookBlockIssues(entries: readonly HookScriptEntry[], opts: HookBlockOptions): HookBlockFinding[];
 //# sourceMappingURL=hook-block-ineffective.d.ts.map

package/dist/core/hook-block-ineffective.js

@@ -1,6 +1,4 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.hookBlockIssues = hookBlockIssues;
 /**
  * Hook-block-ineffective detector — the #1 verified hook pain ("false confidence").
  *
@@ -44,8 +42,13 @@ exports.hookBlockIssues = hookBlockIssues;
  * callers, no drift). See `research/hook-pain-points.md` for the verified corpus
  * and `docs/compiled-hooks.md` for the authoritative fix (compiled hooks make
  * this whole class unrepresentable).
+ *
+ * Node-free: the `readFileSync` IO is REQUIRED (injected by the caller — the disk
+ * scan passes `node:fs`, the browser engine a map-backed read), so this module
+ * never statically imports `node:fs` and bundles clean in a browser.
  */
-const node_fs_1 = require("node:fs");
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hookBlockIssues = hookBlockIssues;
 // ---------------------------------------------------------------------------
 // Block-mechanism patterns (conservative / FP-safe)
 // ---------------------------------------------------------------------------
@@ -79,14 +82,6 @@ const PERMISSION_DENY = /"permissionDecision"\s*:\s*"(deny|ask)"/;
 // ---------------------------------------------------------------------------
 // Detector
 // ---------------------------------------------------------------------------
-function defaultReadFile(p) {
-    try {
-        return (0, node_fs_1.readFileSync)(p, "utf8");
-    }
-    catch {
-        return "";
-    }
-}
 /**
  * Detect false-confidence "blocks" across a set of hook entries.
  *
@@ -95,12 +90,12 @@ function defaultReadFile(p) {
  * (event, kind, scriptPath) pairs are de-duped.
  *
  * @param entries - The hook registrations to inspect (event + command/script).
- * @param opts    - Injected sets of blocking/permission events, and an optional
- *                  `readFileSync` (default: node:fs).
+ * @param opts    - Injected sets of blocking/permission events, and the required
+ *                  `readFileSync` (disk caller: node:fs; browser: map-backed).
  */
 function hookBlockIssues(entries, opts) {
     const { noEffectEvents, permissionDecisionEvents } = opts;
-    const readFile = opts.readFileSync ?? defaultReadFile;
+    const readFile = opts.readFileSync;
     const findings = [];
     const seen = new Set();
     for (const entry of entries) {

package/dist/core/mcp-contract-message.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The pure, node-free half of the live MCP contract-tool check: the error shape
+ * and its human-readable formatter, split out of `core/mcp.ts` (which statically
+ * imports `node:child_process` + `./refs.js` for the SPAWN path) so a consumer
+ * that only needs the message — the deterministic audit report — doesn't drag the
+ * live-verification machinery into its bundle. `mcp.ts` re-exports both, so its
+ * existing consumers are unchanged; `verifyMcpContractTools` (the spawn) stays
+ * there. Node-free by construction (a local `assertNever`, no `node:` import).
+ */
+export type McpContractToolReason = "server-unreachable" | "tool-missing";
+export interface McpContractToolError {
+    /** The full `mcp__server__tool` reference (restriction suffix stripped). */
+    readonly tool: string;
+    readonly server: string;
+    /** The tool segment (what's looked up on the server). */
+    readonly toolName: string;
+    readonly reason: McpContractToolReason;
+    readonly suggestions: string[];
+}
+/** Human-readable message for a contract-tool error (with "did you mean"). */
+export declare function mcpContractToolMessage(e: McpContractToolError): string;
+//# sourceMappingURL=mcp-contract-message.d.ts.map

package/dist/core/mcp-contract-message.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * The pure, node-free half of the live MCP contract-tool check: the error shape
+ * and its human-readable formatter, split out of `core/mcp.ts` (which statically
+ * imports `node:child_process` + `./refs.js` for the SPAWN path) so a consumer
+ * that only needs the message — the deterministic audit report — doesn't drag the
+ * live-verification machinery into its bundle. `mcp.ts` re-exports both, so its
+ * existing consumers are unchanged; `verifyMcpContractTools` (the spawn) stays
+ * there. Node-free by construction (a local `assertNever`, no `node:` import).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpContractToolMessage = mcpContractToolMessage;
+function assertNever(x) {
+    throw new Error(`Unexpected value: ${String(x)}`);
+}
+/** Human-readable message for a contract-tool error (with "did you mean"). */
+function mcpContractToolMessage(e) {
+    switch (e.reason) {
+        case "server-unreachable":
+            return `MCP tool "${e.tool}" — server "${e.server}" failed to start`;
+        case "tool-missing":
+            return `MCP tool "${e.tool}" not found on server "${e.server}"${e.suggestions.length > 0
+                ? ` — did you mean ${e.suggestions.map((s) => `"${s}"`).join(", ")}?`
+                : ""}`;
+        default:
+            return assertNever(e.reason);
+    }
+}
+//# sourceMappingURL=mcp-contract-message.js.map

package/dist/core/mcp.d.ts

@@ -1,3 +1,7 @@
+import { mcpContractToolMessage } from "./mcp-contract-message.js";
+import type { McpContractToolError, McpContractToolReason } from "./mcp-contract-message.js";
+export { mcpContractToolMessage };
+export type { McpContractToolError, McpContractToolReason };
 export interface McpServerConfig {
     readonly command: string;
     readonly args?: readonly string[];
@@ -43,19 +47,7 @@ export declare function loadMcpServers(cwd: string): Record<string, McpServerCon
  * to an undeclared server, an unreachable server, or a missing tool is an error.
  */
 export declare function verifyMcpRefs(markdown: string, mcpServers: Record<string, McpServerConfig>, timeoutMs?: number): Promise<McpRefError[]>;
-export type McpContractToolReason = "server-unreachable" | "tool-missing";
-export interface McpContractToolError {
-    /** The full `mcp__server__tool` reference (restriction suffix stripped). */
-    readonly tool: string;
-    readonly server: string;
-    /** The tool segment (what's looked up on the server). */
-    readonly toolName: string;
-    readonly reason: McpContractToolReason;
-    readonly suggestions: string[];
-}
 export declare function verifyMcpContractTools(tools: readonly string[], servers: Record<string, McpServerConfig>, dialect: import("./dialect.js").HarnessDialect, timeoutMs?: number): Promise<McpContractToolError[]>;
-/** Human-readable message for a contract-tool error (with "did you mean"). */
-export declare function mcpContractToolMessage(e: McpContractToolError): string;
 /** Human-readable message for an MCP reference error (with "did you mean"). */
 export declare function mcpRefMessage(e: McpRefError): string;
 //# sourceMappingURL=mcp.d.ts.map

package/dist/core/mcp.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpContractToolMessage = void 0;
 exports.listMcpTools = listMcpTools;
 exports.verifyMcpTool = verifyMcpTool;
 exports.parseMcpRefs = parseMcpRefs;
 exports.loadMcpServers = loadMcpServers;
 exports.verifyMcpRefs = verifyMcpRefs;
 exports.verifyMcpContractTools = verifyMcpContractTools;
-exports.mcpContractToolMessage = mcpContractToolMessage;
 exports.mcpRefMessage = mcpRefMessage;
 /**
  * Minimal MCP client over stdio — start a server, do the JSON-RPC handshake, and
@@ -24,6 +24,8 @@ const node_path_1 = require("node:path");
 const refs_js_1 = require("./refs.js");
 const hash_js_1 = require("./hash.js");
 const mcp_tool_js_1 = require("./mcp-tool.js");
+const mcp_contract_message_js_1 = require("./mcp-contract-message.js");
+Object.defineProperty(exports, "mcpContractToolMessage", { enumerable: true, get: function () { return mcp_contract_message_js_1.mcpContractToolMessage; } });
 function dispatch(line, pending) {
     let msg;
     try {
@@ -283,19 +285,6 @@ async function verifyMcpContractTools(tools, servers, dialect, timeoutMs = 10000
     }
     return errors;
 }
-/** Human-readable message for a contract-tool error (with "did you mean"). */
-function mcpContractToolMessage(e) {
-    switch (e.reason) {
-        case "server-unreachable":
-            return `MCP tool "${e.tool}" — server "${e.server}" failed to start`;
-        case "tool-missing":
-            return `MCP tool "${e.tool}" not found on server "${e.server}"${e.suggestions.length > 0
-                ? ` — did you mean ${e.suggestions.map((s) => `"${s}"`).join(", ")}?`
-                : ""}`;
-        default:
-            return (0, hash_js_1.assertNever)(e.reason);
-    }
-}
 /** Human-readable message for an MCP reference error (with "did you mean"). */
 function mcpRefMessage(e) {
     switch (e.reason) {

package/dist/core/ncd.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Normalized Compression Distance — information-theoretic similarity.
+ *
+ *   NCD(x, y) = (C(xy) - min(C(x), C(y))) / max(C(x), C(y))
+ *
+ * Range: [0, 1+ε] where 0 = identical information content.
+ * Deterministic. No model dependency. Approximates the universal distance metric.
+ *
+ * Reference: Li, Chen, Li, Ma, Vitányi (2004) "The Similarity Metric"
+ */
+export declare function ncd(a: string, b: string): number;
+//# sourceMappingURL=ncd.d.ts.map

package/dist/core/ncd.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ncd = ncd;
+/**
+ * Normalized Compression Distance (NCD) — the model-free similarity engine.
+ *
+ * Extracted from proofs.ts as a NODE-FREE leaf: it depends only on `gzipSync`
+ * (aliased to `pako` in the browser build) and `TextEncoder` (a Web/Node global),
+ * so the description-overlap detector can reach it WITHOUT dragging proofs.ts's
+ * `node:crypto` (hash.js) import into the in-browser audit bundle. proofs.ts
+ * re-exports `ncd` for its existing consumers; the detector imports it from here.
+ *
+ * `TextEncoder` (not `Buffer.from`) keeps the byte input identical across Node and
+ * the browser and removes the node-only `Buffer` global — utf-8 bytes are the same
+ * either way, so gzip sees identical input and the compressed length matches.
+ */
+const node_zlib_1 = require("node:zlib");
+const utf8 = new TextEncoder();
+/**
+ * Compressed size of a string via gzip — approximates Kolmogorov complexity
+ * (the length of the shortest program that produces the string).
+ */
+function compressedSize(s) {
+    return (0, node_zlib_1.gzipSync)(utf8.encode(s), { level: 9 }).length;
+}
+/**
+ * Normalized Compression Distance — information-theoretic similarity.
+ *
+ *   NCD(x, y) = (C(xy) - min(C(x), C(y))) / max(C(x), C(y))
+ *
+ * Range: [0, 1+ε] where 0 = identical information content.
+ * Deterministic. No model dependency. Approximates the universal distance metric.
+ *
+ * Reference: Li, Chen, Li, Ma, Vitányi (2004) "The Similarity Metric"
+ */
+function ncd(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    const ca = compressedSize(a);
+    const cb = compressedSize(b);
+    const cab = compressedSize(a + b);
+    const minC = Math.min(ca, cb);
+    const maxC = Math.max(ca, cb);
+    if (maxC === 0)
+        return 0;
+    return (cab - minC) / maxC;
+}
+//# sourceMappingURL=ncd.js.map

package/dist/core/plugin-dir-layout.d.ts

@@ -6,13 +6,13 @@ export interface PluginLayoutFinding {
     readonly message: string;
 }
 export interface PluginLayoutOptions {
-    /** Injectable: does this path exist? (default: node:fs existsSync) */
-    readonly existsSync?: (p: string) => boolean;
+    /** REQUIRED, injected: does this path exist? (disk: node:fs existsSync) */
+    readonly existsSync: (p: string) => boolean;
     /**
-     * Injectable: is this path a directory? (default: node:fs
+     * REQUIRED, injected: is this path a directory? (disk: node:fs
      * statSync(p).isDirectory(), returning false on any throw)
      */
-    readonly isDirectory?: (p: string) => boolean;
+    readonly isDirectory: (p: string) => boolean;
 }
 /**
  * Surface directories found nested INSIDE the manifest directory, where they are
@@ -26,5 +26,5 @@ export interface PluginLayoutOptions {
  * Returns `[]` when the manifest dir doesn't exist or holds no misplaced surface
  * dirs.
  */
-export declare function pluginDirLayoutIssues(manifestDir: string, surfaceDirNames: readonly string[], opts?: PluginLayoutOptions): PluginLayoutFinding[];
+export declare function pluginDirLayoutIssues(manifestDir: string, surfaceDirNames: readonly string[], opts: PluginLayoutOptions): PluginLayoutFinding[];
 //# sourceMappingURL=plugin-dir-layout.d.ts.map