agentfootprint 6.23.0 → 6.25.0

package/dist/esm/lib/influence-core/similarity.js

@@ -0,0 +1,79 @@
+/**
+ * pairwiseSimilarity — pairwise cosine over a set of texts
+ * (RFC-002 C1's core: tool descriptions → matrix + ranked pairs).
+ *
+ * Pattern: pure async function, embedder-injected. No thresholds, no
+ *          verdicts, no lint rules — those are C1's `analyzeToolCatalog`
+ *          policy layer ON TOP of this geometry. The core stays
+ *          reusable for any "how confusable are these texts" question.
+ * Role:    `src/lib/influence-core/` leaf. No agent/runtime imports.
+ *
+ * Honest claim: similarity is embedding geometry over the DESCRIPTIONS
+ * — a confusability HEURISTIC, not a measurement of the model's actual
+ * selection function (RFC-002 §2; tier 3 validates the proxy via
+ * choice-entropy sampling).
+ */
+import { cosineSimilarity } from '../../memory/embedding/cosine.js';
+/**
+ * Embed every item once (deduplicated batch) and compute the full
+ * cosine matrix plus ranked upper-triangle pairs (descending; ties
+ * keep input pair order).
+ *
+ * Invariants (pinned by property tests):
+ *  - `matrix[i][j] === matrix[j][i]` — computed once, mirrored.
+ *  - `matrix[i][i] === 1` EXACTLY — set by definition, so
+ *    self-similarity is an invariant rather than a float artifact
+ *    (and duplicate texts at different ids still compare via cosine).
+ *  - N items → N·(N−1)/2 pairs.
+ */
+export async function pairwiseSimilarity(args) {
+    const { items, embedder } = args;
+    assertUniqueIds(items);
+    const ids = items.map((item) => item.id);
+    if (items.length === 0)
+        return { ids, matrix: [], pairs: [] };
+    // Deduplicated embedding pass (identical descriptions embed once).
+    const distinct = [...new Set(items.map((item) => item.text))];
+    const vectors = embedder.embedBatch
+        ? await embedder.embedBatch({
+            texts: distinct,
+            ...(args.signal ? { signal: args.signal } : {}),
+        })
+        : await sequentialEmbed(embedder, distinct, args.signal);
+    const vectorByText = new Map();
+    for (let i = 0; i < distinct.length; i++)
+        vectorByText.set(distinct[i], vectors[i]);
+    const itemVecs = items.map((item) => vectorByText.get(item.text));
+    // Upper triangle once, mirrored; diagonal exactly 1 by definition.
+    const matrix = items.map(() => new Array(items.length).fill(0));
+    const pairs = [];
+    for (let i = 0; i < items.length; i++) {
+        matrix[i][i] = 1;
+        for (let j = i + 1; j < items.length; j++) {
+            const similarity = cosineSimilarity(itemVecs[i], itemVecs[j]);
+            matrix[i][j] = similarity;
+            matrix[j][i] = similarity;
+            pairs.push({ a: ids[i], b: ids[j], similarity });
+        }
+    }
+    // Stable sort — ties keep (i, j) input order.
+    pairs.sort((p, q) => q.similarity - p.similarity);
+    return { ids, matrix, pairs };
+}
+async function sequentialEmbed(embedder, texts, signal) {
+    const out = [];
+    for (const text of texts) {
+        out.push(await embedder.embed({ text, ...(signal ? { signal } : {}) }));
+    }
+    return out;
+}
+function assertUniqueIds(items) {
+    const seen = new Set();
+    for (const item of items) {
+        if (seen.has(item.id)) {
+            throw new Error(`pairwiseSimilarity: duplicate item id '${item.id}' — ids must be unique`);
+        }
+        seen.add(item.id);
+    }
+}
+//# sourceMappingURL=similarity.js.map

package/dist/esm/lib/influence-core/similarity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/similarity.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/influence-core/types.js

@@ -0,0 +1,35 @@
+/**
+ * influence-core types — the ONE embedding-based scoring contract.
+ *
+ * Pattern: Strategy seam (plug-and-play meta-pattern) — the frame and
+ *          rule engine are the library's; the `Embedder` is consumer-
+ *          injected, exactly like NarrativeFormatter / reliability /
+ *          permission / commentary strategies.
+ * Role:    `src/lib/` leaf module. Shared by the FDL paper pipeline
+ *          (Visible Reasoning, Eq. 1–6), RFC-002's tool-catalog lint +
+ *          margin recorder (C1/C4/C5), and RFC-003 Part B's LLM-edge
+ *          weigher (D7). Extracted as RFC-003 block D6 so all three
+ *          consumers share one scoring engine and one embedding cache.
+ *
+ * ## Honest claim (RFC-002 §2, the FDL discipline)
+ *
+ * Every score produced under these types is a PROXY computed from
+ * embedding geometry — cosine similarity over consumer-injected
+ * embeddings. None of it reads model internals. Scores mean "high
+ * semantic alignment", never "the model chose/answered BECAUSE".
+ * Scores are not additive across items and are not causal attribution
+ * — counterfactual ablation (RFC-003 stage 4) is where causal claims
+ * live.
+ */
+/** Paper defaults: α=0.40, β=0.30, γ=0.20, δ=0.10 (sum to 1.0). */
+export const DEFAULT_INFLUENCE_WEIGHTS = Object.freeze({
+    fa: 0.4,
+    avg: 0.3,
+    persist: 0.2,
+    depth: 0.1,
+});
+/** Paper default for the PERSIST threshold T (Eq. 3). */
+export const DEFAULT_PERSISTENCE_THRESHOLD = 0.3;
+/** RFC-002 §4 default: margins below this flag the choice as `narrow`. */
+export const DEFAULT_MARGIN_THRESHOLD = 0.05;
+//# sourceMappingURL=types.js.map

package/dist/esm/lib/influence-core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA0BH,mEAAmE;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAqB,MAAM,CAAC,MAAM,CAAC;IACvE,EAAE,EAAE,GAAG;IACP,GAAG,EAAE,GAAG;IACR,OAAO,EAAE,GAAG;IACZ,KAAK,EAAE,GAAG;CACX,CAAC,CAAC;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC"}

package/dist/esm/lib/tool-lint/analyze.js

@@ -0,0 +1,235 @@
+/**
+ * analyzeToolCatalog — the tool-catalog confusability lint
+ * (RFC-002 block C1, the adoption front door).
+ *
+ * Pattern: policy layer over `pairwiseSimilarity` (influence-core) — the
+ *          geometry is computed there; thresholds, verdicts, hints and
+ *          the structural rule pack live here. Everything is consumer-
+ *          injectable with our defaults (the plug-and-play meta-pattern).
+ * Role:    `src/lib/tool-lint/`. ZERO stack buy-in — plain
+ *          `{ name, description?, inputSchema? }[]` in, report out.
+ *          `catalogFromTools` adapts the library's own `Tool[]`;
+ *          `coerceCatalog` (cli.ts) normalizes OpenAI/Anthropic/MCP
+ *          shapes.
+ *
+ * ## What is embedded (and why)
+ *
+ * `confusabilityText(tool)` = tokenized name + ': ' + description. The
+ * model differentiates tools by name AND description together, so two
+ * tools with near-identical names and overlapping descriptions ARE the
+ * confusability case (`get_fcns_database` vs `influx_get_fcns_database`)
+ * — embedding only the prose would miss the name signal.
+ *
+ * ## Calibration (RFC-002 §3 — read this before trusting verdicts)
+ *
+ * Absolute cosine ranges are PER-EMBEDDER. The default threshold (0.85)
+ * is a starting point for real sentence embedders. The test/demo
+ * `mockEmbedder` (character-frequency) compresses unrelated prose into
+ * ~0.85–0.97 — with it, use `MOCK_EMBEDDER_CALIBRATION` and trust only
+ * the RELATIVE ordering in `report.similarity.ranked` (the acceptance
+ * fixtures assert ordering, never absolute scores).
+ */
+import { pairwiseSimilarity } from '../influence-core/index.js';
+import { defaultStructuralRules } from './rules.js';
+/** Default `confusabilityThreshold` — a starting point for REAL sentence
+ *  embedders (unrelated tool descriptions typically land 0.3–0.7).
+ *  Calibrate per embedder; meaningless for the mock (see below). */
+export const DEFAULT_CONFUSABILITY_THRESHOLD = 0.85;
+/** Default `watchBand` below the threshold. */
+export const DEFAULT_WATCH_BAND = 0.05;
+/**
+ * Threshold/band calibrated for the char-frequency `mockEmbedder` on
+ * realistic tool prose (seed corpus: the Neo SAN catalog). The mock
+ * compresses unrelated descriptions into ~0.85–0.97 cosine, so expect
+ * false positives even at 0.94 — with the mock, the RELATIVE ordering
+ * of `report.similarity.ranked` is the trustworthy signal; absolute
+ * verdicts are only honest with a real embedder + per-embedder
+ * calibration.
+ */
+export const MOCK_EMBEDDER_CALIBRATION = Object.freeze({
+    confusabilityThreshold: 0.94,
+    watchBand: 0.02,
+});
+/**
+ * Adapt the library's `Tool[]` (from `defineTool` / `Agent.tool`) to the
+ * lint's plain catalog shape. Trivial on purpose: `Tool.schema` already
+ * IS `{ name, description, inputSchema }`.
+ */
+export function catalogFromTools(tools) {
+    return tools.map((tool) => ({
+        name: tool.schema.name,
+        description: tool.schema.description,
+        inputSchema: tool.schema.inputSchema,
+    }));
+}
+/**
+ * The text the confusability analysis embeds for one tool: the name with
+ * `_`/`-`/camelCase boundaries opened into words, then the description.
+ * Exported so consumers can reproduce or replace the construction.
+ */
+export function confusabilityText(tool) {
+    const name = tool.name
+        .replace(/[_-]+/g, ' ')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .trim();
+    const description = tool.description?.trim() ?? '';
+    return description.length > 0 ? `${name}: ${description}` : name;
+}
+/**
+ * Lint a tool catalog: pairwise confusability over what the model reads
+ * (when an embedder is supplied) + the structural rule pack. Returns a
+ * report whose `ok` is the CI gate.
+ *
+ * Duplicate tool names are themselves reported as structural errors
+ * (rule `duplicate-name`, built-in precondition — a catalog where two
+ * tools share a name is broken before any similarity question); the
+ * duplicates are dropped from the similarity analysis (first one wins).
+ */
+export async function analyzeToolCatalog(tools, options = {}) {
+    const confusabilityThreshold = options.confusabilityThreshold ?? DEFAULT_CONFUSABILITY_THRESHOLD;
+    const watchBand = options.watchBand ?? DEFAULT_WATCH_BAND;
+    const rules = options.rules ?? defaultStructuralRules;
+    const failOn = options.failOn ?? 'error';
+    // ── built-in precondition: duplicate names ──
+    const structural = [];
+    const seen = new Set();
+    const unique = [];
+    for (const tool of tools) {
+        if (seen.has(tool.name)) {
+            structural.push({
+                rule: 'duplicate-name',
+                tool: tool.name,
+                severity: 'error',
+                message: 'two tools share this name — the model cannot address them distinctly',
+            });
+        }
+        else {
+            seen.add(tool.name);
+            unique.push(tool);
+        }
+    }
+    // ── structural rule pack ──
+    for (const tool of unique) {
+        for (const rule of rules) {
+            structural.push(...rule.check(tool, unique));
+        }
+    }
+    // ── pairwise confusability (embedder-gated) ──
+    let ranked = [];
+    const confusable = [];
+    const watch = [];
+    const analyzed = options.embedder !== undefined && unique.length >= 2;
+    if (options.embedder !== undefined && unique.length >= 2) {
+        const byName = new Map(unique.map((tool) => [tool.name, tool]));
+        const result = await pairwiseSimilarity({
+            items: unique.map((tool) => ({ id: tool.name, text: confusabilityText(tool) })),
+            embedder: options.embedder,
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        ranked = result.pairs;
+        for (const pair of result.pairs) {
+            if (pair.similarity >= confusabilityThreshold) {
+                confusable.push({
+                    kind: 'confusable',
+                    a: pair.a,
+                    b: pair.b,
+                    similarity: pair.similarity,
+                    // byName lookups are safe: pair ids come from `unique` itself.
+                    hint: differentiationHint(byName.get(pair.a), byName.get(pair.b)),
+                });
+            }
+            else if (pair.similarity >= confusabilityThreshold - watchBand) {
+                watch.push({
+                    kind: 'watch',
+                    a: pair.a,
+                    b: pair.b,
+                    similarity: pair.similarity,
+                    hint: differentiationHint(byName.get(pair.a), byName.get(pair.b)),
+                });
+            }
+        }
+    }
+    const errors = structural.filter((f) => f.severity === 'error').length;
+    const warnings = structural.length - errors;
+    const gateFailures = failOn === 'warn' ? structural.length : errors;
+    return {
+        ok: confusable.length === 0 && gateFailures === 0,
+        toolCount: tools.length,
+        similarity: {
+            analyzed,
+            confusable,
+            watch,
+            ranked,
+            thresholds: { confusabilityThreshold, watchBand },
+        },
+        structural,
+        summary: { confusable: confusable.length, watch: watch.length, errors, warnings },
+    };
+}
+// ── differentiating-axis hint (heuristic, honest) ────────────────────
+const STOPWORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'are',
+    'by',
+    'for',
+    'from',
+    'get',
+    'in',
+    'into',
+    'is',
+    'its',
+    'of',
+    'on',
+    'or',
+    'the',
+    'to',
+    'which',
+    'with',
+]);
+function nameTokens(name) {
+    return name
+        .replace(/[_-]+/g, ' ')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+}
+function descriptionTokens(tool) {
+    return new Set((tool.description ?? '')
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/)
+        .filter((t) => t.length >= 3 && !STOPWORDS.has(t)));
+}
+/**
+ * Suggest the DIFFERENTIATING AXIS for a flagged pair. Heuristic: when
+ * the names are near-twins (≤2 distinct tokens), the qualifier IS the
+ * axis — the descriptions must say when to choose each variant. When the
+ * names differ, surface the few description terms each tool does NOT
+ * share, as the place to anchor an explicit choice condition.
+ */
+export function differentiationHint(a, b) {
+    const aTokens = nameTokens(a.name);
+    const bTokens = nameTokens(b.name);
+    const aOnly = aTokens.filter((t) => !bTokens.includes(t));
+    const bOnly = bTokens.filter((t) => !aTokens.includes(t));
+    const shared = aTokens.filter((t) => bTokens.includes(t));
+    if (shared.length >= 2 && aOnly.length + bOnly.length <= 2) {
+        const diff = [...aOnly, ...bOnly].map((t) => `'${t}'`).join(' vs ') || 'nothing — the names match';
+        return (`names differ only by ${diff} — make the descriptions say WHEN to choose each ` +
+            `(different backend/data source? live vs historical? freshness?), ` +
+            `e.g. "Use for …; prefer ${b.name} when …"`);
+    }
+    const aDesc = descriptionTokens(a);
+    const bDesc = descriptionTokens(b);
+    const aDistinct = [...aDesc].filter((t) => !bDesc.has(t)).slice(0, 3);
+    const bDistinct = [...bDesc].filter((t) => !aDesc.has(t)).slice(0, 3);
+    if (aDistinct.length === 0 && bDistinct.length === 0) {
+        return `the descriptions are near-duplicates — rewrite one to state when it, and not ${b.name}, is the right call`;
+    }
+    return (`descriptions overlap heavily; the distinct terms are ` +
+        `${a.name}: [${aDistinct.join(', ')}] vs ${b.name}: [${bDistinct.join(', ')}] — ` +
+        `lead with an explicit choice condition ("use when …") built on those`);
+}
+//# sourceMappingURL=analyze.js.map

package/dist/esm/lib/tool-lint/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../../../../src/lib/tool-lint/analyze.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/tool-lint/cli.js

@@ -0,0 +1,198 @@
+/**
+ * Tool-lint CLI core (RFC-002 block C3 — the CI gate).
+ *
+ * Pattern: humble shell — `bin/agentfootprint-lint-tools.mjs` is a
+ *          3-line wrapper; ALL behavior (arg parsing, catalog coercion,
+ *          report, exit code) lives here so it is unit-testable without
+ *          spawning a process.
+ * Role:    `src/lib/tool-lint/`. Reads ONE JSON file of tools, prints a
+ *          report, returns the process exit code:
+ *            0 — report.ok
+ *            1 — findings failed the gate (!ok)
+ *            2 — usage / input error (bad flags, unreadable file,
+ *                unrecognized JSON shape)
+ *
+ * ## Embedder & gating honesty
+ *
+ * The CLI has no way to receive a consumer embedder, so it uses the
+ * built-in deterministic mock (char-frequency, offline, dependency-free)
+ * for the similarity RANKING — and, by default, does NOT gate on it:
+ * without `--threshold`, similarity is report-only (relative ordering +
+ * watch hints) and the exit code reflects structural findings alone.
+ * Pass `--threshold` to make confusable pairs fail the gate — you own
+ * the calibration at that point (start from
+ * `MOCK_EMBEDDER_CALIBRATION.confusabilityThreshold` = 0.94). For real
+ * embedder gating, use `analyzeToolCatalog` from
+ * `agentfootprint/observe` in a small script instead.
+ */
+import { readFile } from 'node:fs/promises';
+import { mockEmbedder } from '../../memory/embedding/mockEmbedder.js';
+import { analyzeToolCatalog, MOCK_EMBEDDER_CALIBRATION } from './analyze.js';
+import { formatToolCatalogReport } from './format.js';
+const USAGE = `usage: agentfootprint-lint-tools <tools.json> [options]
+
+  <tools.json>          JSON file with your tool catalog. Accepted shapes:
+                          [{ name, description, inputSchema? }]          (plain / MCP tool)
+                          { tools: [...] }                               (MCP tools/list result)
+                          [{ type: 'function', function: {...} }]       (OpenAI)
+                          [{ name, description, input_schema }]         (Anthropic)
+
+  --threshold <num>     gate on confusable pairs at this cosine (mock-embedder
+                        starting point: ${MOCK_EMBEDDER_CALIBRATION.confusabilityThreshold}). Without it, similarity is
+                        REPORT-ONLY and only structural findings gate.
+  --watch-band <num>    advisory band below the threshold (default ${MOCK_EMBEDDER_CALIBRATION.watchBand} with --threshold)
+  --strict              structural warnings also fail the gate
+  --no-similarity       skip the similarity analysis entirely
+  --top <n>             ranked pairs to print (default 10)
+  --json                print the full report as JSON instead of text
+
+exit codes: 0 ok · 1 findings failed the gate · 2 usage/input error`;
+/**
+ * Normalize any of the recognized tool-list JSON shapes to the lint's
+ * plain catalog. Throws (with a shape description) on unrecognized
+ * input — the CLI maps that to exit code 2.
+ */
+export function coerceCatalog(json) {
+    // { tools: [...] } — MCP `tools/list` result envelope.
+    const list = Array.isArray(json)
+        ? json
+        : json !== null &&
+            typeof json === 'object' &&
+            Array.isArray(json.tools)
+            ? json.tools
+            : undefined;
+    if (list === undefined) {
+        throw new Error('expected a JSON array of tools or { tools: [...] }');
+    }
+    return list.map((raw, index) => {
+        if (raw === null || typeof raw !== 'object') {
+            throw new Error(`tools[${index}] is not an object`);
+        }
+        const entry = raw;
+        // OpenAI: { type: 'function', function: { name, description, parameters } }
+        const fn = entry.type === 'function' && entry.function !== null && typeof entry.function === 'object'
+            ? entry.function
+            : entry;
+        const name = fn.name;
+        if (typeof name !== 'string' || name.length === 0) {
+            throw new Error(`tools[${index}] has no string 'name'`);
+        }
+        const description = typeof fn.description === 'string' ? fn.description : undefined;
+        // inputSchema (MCP/ours) | input_schema (Anthropic) | parameters (OpenAI)
+        const schema = fn.inputSchema ?? fn.input_schema ?? fn.parameters;
+        const inputSchema = schema !== null && typeof schema === 'object'
+            ? schema
+            : undefined;
+        return {
+            name,
+            ...(description !== undefined ? { description } : {}),
+            ...(inputSchema !== undefined ? { inputSchema } : {}),
+        };
+    });
+}
+function parseArgs(argv) {
+    let file;
+    let threshold;
+    let watchBand;
+    let strict = false;
+    let similarity = true;
+    let top = 10;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const numberFlag = (name) => {
+            const value = Number(argv[++i]);
+            if (!Number.isFinite(value))
+                throw new Error(`${name} expects a number`);
+            return value;
+        };
+        if (arg === '--threshold')
+            threshold = numberFlag('--threshold');
+        else if (arg === '--watch-band')
+            watchBand = numberFlag('--watch-band');
+        else if (arg === '--strict')
+            strict = true;
+        else if (arg === '--no-similarity')
+            similarity = false;
+        else if (arg === '--top')
+            top = numberFlag('--top');
+        else if (arg === '--json')
+            json = true;
+        else if (arg === '--help' || arg === '-h')
+            throw new Error(USAGE);
+        else if (arg.startsWith('-'))
+            throw new Error(`unknown flag '${arg}'\n\n${USAGE}`);
+        else if (file === undefined)
+            file = arg;
+        else
+            throw new Error(`unexpected extra argument '${arg}'\n\n${USAGE}`);
+    }
+    if (file === undefined)
+        throw new Error(USAGE);
+    return {
+        file,
+        ...(threshold !== undefined ? { threshold } : {}),
+        ...(watchBand !== undefined ? { watchBand } : {}),
+        strict,
+        similarity,
+        top,
+        json,
+    };
+}
+/**
+ * Run the lint CLI. Returns the exit code (never calls `process.exit` —
+ * the bin wrapper assigns it to `process.exitCode`).
+ */
+export async function runToolLintCli(argv, io = {
+    // eslint-disable-next-line no-console
+    stdout: (line) => console.log(line),
+    // eslint-disable-next-line no-console
+    stderr: (line) => console.error(line),
+}) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        io.stderr(error.message);
+        return 2;
+    }
+    let catalog;
+    try {
+        catalog = coerceCatalog(JSON.parse(await readFile(args.file, 'utf8')));
+    }
+    catch (error) {
+        io.stderr(`agentfootprint-lint-tools: ${args.file}: ${error.message}`);
+        return 2;
+    }
+    // Without --threshold the mock-embedder similarity is REPORT-ONLY:
+    // rank pairs at an unreachable threshold (no 'confusable'/'watch'
+    // verdicts) so only the relative-ordering section prints.
+    const gateOnSimilarity = args.threshold !== undefined;
+    const threshold = args.threshold ?? Infinity;
+    const watchBand = args.watchBand ?? (gateOnSimilarity ? MOCK_EMBEDDER_CALIBRATION.watchBand : 0);
+    const report = await analyzeToolCatalog(catalog, {
+        ...(args.similarity ? { embedder: mockEmbedder() } : {}),
+        confusabilityThreshold: threshold,
+        watchBand,
+        failOn: args.strict ? 'warn' : 'error',
+    });
+    if (args.json) {
+        io.stdout(JSON.stringify(report, null, 2));
+    }
+    else {
+        if (args.similarity) {
+            io.stdout(gateOnSimilarity
+                ? '⚠ similarity uses the built-in deterministic mock embedder — you own the ' +
+                    'calibration of --threshold (cosine ranges are per-embedder; mock compresses ' +
+                    'prose to ~0.85–0.97). Trust relative ordering first.'
+                : 'ℹ similarity is REPORT-ONLY (no --threshold): ranked pairs below are the ' +
+                    'relative-ordering view from the built-in mock embedder. Pass --threshold ' +
+                    `(mock starting point ${MOCK_EMBEDDER_CALIBRATION.confusabilityThreshold}) to gate on confusable pairs.`);
+            io.stdout('');
+        }
+        io.stdout(formatToolCatalogReport(report, { topPairs: args.top }));
+    }
+    return report.ok ? 0 : 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/esm/lib/tool-lint/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../../src/lib/tool-lint/cli.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/tool-lint/format.js

@@ -0,0 +1,61 @@
+/**
+ * formatToolCatalogReport — human-readable rendering of a lint report.
+ *
+ * Pattern: pure presenter. One report → one string; used verbatim by the
+ *          CLI (`agentfootprint-lint-tools`) and the examples so output
+ *          stays byte-identical across surfaces.
+ * Role:    `src/lib/tool-lint/` leaf. No I/O.
+ */
+export function formatToolCatalogReport(report, options = {}) {
+    const topPairs = options.topPairs ?? 10;
+    const maxWatch = options.maxWatch ?? 10;
+    const lines = [];
+    const { similarity, structural, summary } = report;
+    lines.push(`tool-catalog lint — ${report.toolCount} tools · ` +
+        `${summary.confusable} confusable · ${summary.watch} watch · ` +
+        `${summary.errors} errors · ${summary.warnings} warnings`);
+    if (similarity.analyzed) {
+        lines.push('', `confusability (threshold ${similarity.thresholds.confusabilityThreshold}, ` +
+            `watch band ${similarity.thresholds.watchBand}):`);
+        if (similarity.confusable.length === 0 && similarity.watch.length === 0) {
+            lines.push('  no pairs at or near the threshold');
+        }
+        for (const pair of similarity.confusable) {
+            lines.push(`  ✗ CONFUSABLE ${pair.similarity.toFixed(4)}  ${pair.a} <> ${pair.b}`);
+            lines.push(`      hint: ${pair.hint}`);
+        }
+        for (const pair of similarity.watch.slice(0, maxWatch)) {
+            lines.push(`  ~ watch      ${pair.similarity.toFixed(4)}  ${pair.a} <> ${pair.b}`);
+            lines.push(`      hint: ${pair.hint}`);
+        }
+        if (similarity.watch.length > maxWatch) {
+            lines.push(`  … and ${similarity.watch.length - maxWatch} more watch pairs (see report.similarity.watch)`);
+        }
+        if (topPairs > 0 && similarity.ranked.length > 0) {
+            lines.push('', `  most-similar pairs (relative ordering — top ${topPairs}):`);
+            for (const pair of similarity.ranked.slice(0, topPairs)) {
+                lines.push(`    ${pair.similarity.toFixed(4)}  ${pair.a} <> ${pair.b}`);
+            }
+        }
+    }
+    else {
+        lines.push('', 'confusability: skipped (no embedder supplied — structural rules only)');
+    }
+    if (structural.length > 0) {
+        lines.push('', 'structural findings:');
+        for (const finding of structural) {
+            const where = finding.param ? `${finding.tool}.${finding.param}` : finding.tool;
+            const mark = finding.severity === 'error' ? '✗' : '~';
+            lines.push(`  ${mark} ${finding.severity.padEnd(5)} [${finding.rule}] ${where}`);
+            lines.push(`      ${finding.message}`);
+            if (finding.suggestion)
+                lines.push(`      suggest: ${finding.suggestion}`);
+        }
+    }
+    else {
+        lines.push('', 'structural findings: none');
+    }
+    lines.push('', report.ok ? 'RESULT: ok' : 'RESULT: FAIL');
+    return lines.join('\n');
+}
+//# sourceMappingURL=format.js.map

package/dist/esm/lib/tool-lint/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../../src/lib/tool-lint/format.ts"],"names":[],"mappings":"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"}