sigmap 8.27.0 → 8.28.0

package/CHANGELOG.md

@@ -10,6 +10,18 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.28.0] — 2026-08-18
+
+Minor release — **"Arity Guard" (v8.28, D1)**: verification now checks not just *does this function exist* but *is it being called with a plausible number of arguments* — the payoff of the v8.27 balanced scanner.
+
+### Added
+- **Arity-checked verification (#529, PR #530):** new `src/verify/arity.js` — `parseParams` turns a signature's exact parameter list into an arity range (`=` defaults and TS `?`-optionals lower `min`; `...rest`/`*args`/`**kwargs` mark the signature variadic; destructuring patterns count as one parameter; depth- and quote-aware throughout), `buildArityIndex` builds a per-name range from top-level callables in exact-param languages only (JS/TS via the balanced scanner, Python via AST; names whose signatures disagree across files are marked ambiguous and never checked; indented members excluded), `extractCallArgCounts` reads calls from answer code over masked text (nested calls and comma-containing strings count correctly; argument emptiness judged on the original text; dotted calls, definitions, `new`-expressions, and control keywords skipped), `checkArity` (variadic signatures flag only too-few). Wired into the Hallucination Guard as detector 3b — **`arity-mismatch` at medium confidence**, with the repo signature + file as the suggestion; `verify_suggestion` (MCP) and `sigmap verify-ai-output` inherit automatically; `opts.arityIndex` keeps hermetic callers unchanged. Conservative by construction: uniquely-resolved · top-level · non-variadic · undotted · known-symbol calls in JS/TS/Python code blocks only — unknowns stay `fake-symbol`. `KNOWN_LIMITATIONS.md` documents the checks and their gates.
+
+### Changed
+- 6 new integration tests incl. end-to-end through a real context file (136 test files); bundle rebuilt (151 modules); zero new dependencies.
+
+---
+
 ## [8.27.0] — 2026-08-18
 
 Minor release — **"Tokenizer Core I" (v8.27, G4 increment 1)**: the hand-rolled balanced scanner lands and JS/TS extraction stops truncating at the first `)` — the first slice of the v9.0 grounding track and the stated precondition for arity-checked verification (D1).

package/README.md

@@ -122,7 +122,7 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.27-main (21 repositories, including R language)
+Benchmark : sigmap-v8.28-main (21 repositories, including R language)
 Date      : 2026-08-18
 
 Hit@5          : 81.1%   (grep-agent baseline 44.0%  — 1.73× lift)

package/gen-context.js

@@ -15385,7 +15385,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '8.27.0',
+    version: '8.28.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -19579,6 +19579,190 @@ __factories["./src/util/truncate"] = function(module, exports) {
   
 };
 
+// ── ./src/verify/arity ──
+__factories["./src/verify/arity"] = function(module, exports) {
+  
+  /**
+   * Arity-checked verification (D1, #529).
+   *
+   * With JS/TS params exact (v8.27 balanced scanner) and Python params from the
+   * AST, the signature index carries real parameter lists — so verification can
+   * check not just "does this function exist" but "is this call's argument
+   * count plausible". Deliberately conservative: only uniquely-resolved,
+   * non-variadic, top-level functions from exact-param languages are checked,
+   * and dotted method calls are never flagged.
+   */
+
+  const path = require('path');
+  const { maskCode, readBalanced } = __require('./src/extractors/scan');
+
+  // Files whose signature params are exact (JS/TS via scan.js, Python via AST).
+  const EXACT_PARAM_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py']);
+
+  const CTRL_KEYWORDS = new Set([
+    'if', 'for', 'while', 'switch', 'catch', 'return', 'typeof', 'await',
+    'do', 'else', 'try', 'finally', 'new', 'in', 'of', 'not', 'and', 'or',
+    'print', 'super', 'this',
+  ]);
+
+  // Top-level callable sig shapes (indented member sigs are excluded on purpose
+  // — method calls are dotted in answers and dotted calls are skipped anyway).
+  const CALLABLE_RES = [
+    /^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/,
+    /^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?\(/,
+    /^(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/,
+  ];
+
+  /** Strip the `  :start-end` anchor and `  # hint` tail from a sig line. */
+  function cleanSig(sig) {
+    return String(sig).replace(/\s{2}#\s.*$/, '').replace(/\s*:\d+(?:-\d+)?\s*$/, '');
+  }
+
+  /**
+   * Parse a parameter-list string into an arity range.
+   * Depth- and quote-aware top-level comma split; `=` defaults and trailing `?`
+   * lower `min`; `...rest` / `*args` / `**kwargs` mark the signature variadic;
+   * destructuring patterns count as one parameter.
+   * @param {string} paramText text between the signature's parens
+   * @returns {{ min: number, max: number, variadic: boolean }}
+   */
+  function parseParams(paramText) {
+    const text = String(paramText || '').trim();
+    if (!text) return { min: 0, max: 0, variadic: false };
+    const masked = maskCode(text);
+    const pieces = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < masked.length; i++) {
+      const ch = masked[i];
+      if (ch === '(' || ch === '[' || ch === '{') depth++;
+      else if (ch === ')' || ch === ']' || ch === '}') depth--;
+      else if (ch === ',' && depth === 0) { pieces.push({ raw: text.slice(start, i), masked: masked.slice(start, i) }); start = i + 1; }
+    }
+    pieces.push({ raw: text.slice(start), masked: masked.slice(start) });
+
+    let min = 0;
+    let max = 0;
+    let variadic = false;
+    for (const piece of pieces) {
+      const p = piece.raw.trim();
+      if (!p) continue;
+      if (/^(\.\.\.|\*)/.test(p)) { variadic = true; continue; }
+      max++;
+      // Optional: a top-level `=` default (scan the masked piece at depth 0) or
+      // a `?`-suffixed name (TS optional, survives type stripping as `x?`).
+      let d = 0;
+      let optional = /^[A-Za-z_$][\w$]*\s*\?$/.test(p);
+      const pm = piece.masked;
+      for (let i = 0; i < pm.length && !optional; i++) {
+        const ch = pm[i];
+        if (ch === '(' || ch === '[' || ch === '{') d++;
+        else if (ch === ')' || ch === ']' || ch === '}') d--;
+        else if (ch === '=' && d === 0 && pm[i + 1] !== '>' && pm[i - 1] !== '=' && pm[i - 1] !== '!' && pm[i - 1] !== '<' && pm[i - 1] !== '>') optional = true;
+      }
+      if (!optional) min++;
+    }
+    return { min, max, variadic };
+  }
+
+  /**
+   * Build a per-name arity index from a SigMap signature index.
+   * Only top-level callables from exact-param languages are included; a name
+   * whose signatures disagree across files is marked ambiguous (never checked).
+   * @param {Map<string, string[]>} sigIndex Map<file, sigs[]>
+   * @returns {Map<string, { min, max, variadic, file, sig } | 'ambiguous'>}
+   */
+  function buildArityIndex(sigIndex) {
+    const index = new Map();
+    if (!sigIndex || !(sigIndex instanceof Map)) return index;
+    for (const [file, sigs] of sigIndex.entries()) {
+      if (!EXACT_PARAM_EXTS.has(path.extname(file))) continue;
+      for (const sig of sigs || []) {
+        const cleaned = cleanSig(sig);
+        let name = null;
+        for (const re of CALLABLE_RES) {
+          const m = cleaned.match(re);
+          if (m) { name = m[1]; break; }
+        }
+        if (!name) continue;
+        const openIdx = cleaned.indexOf('(', cleaned.indexOf(name));
+        if (openIdx === -1) continue;
+        const masked = maskCode(cleaned);
+        const closeIdx = readBalanced(masked, openIdx);
+        if (closeIdx === -1) continue;
+        const arity = parseParams(cleaned.slice(openIdx + 1, closeIdx));
+        const entry = { ...arity, file, sig: cleaned.trim() };
+        const existing = index.get(name);
+        if (existing === undefined) index.set(name, entry);
+        else if (existing === 'ambiguous') continue;
+        else if (existing.min !== entry.min || existing.max !== entry.max || existing.variadic !== entry.variadic) {
+          index.set(name, 'ambiguous');
+        }
+      }
+    }
+    return index;
+  }
+
+  /**
+   * Extract call sites with argument counts from answer code.
+   * Dotted/property calls and keyword-preceded definitions are skipped for
+   * precision; nested calls and comma-containing strings count correctly
+   * because the scan is over masked text.
+   * @param {string} code
+   * @returns {{ name: string, args: number, line: number }[]}
+   */
+  function extractCallArgCounts(code) {
+    const src = String(code || '');
+    const masked = maskCode(src);
+    const calls = [];
+    const re = /([A-Za-z_$][\w$]*)\s*\(/g;
+    let m;
+    while ((m = re.exec(masked)) !== null) {
+      const name = m[1];
+      if (CTRL_KEYWORDS.has(name)) continue;
+      let k = m.index - 1;
+      while (k >= 0 && (masked[k] === ' ' || masked[k] === '\t')) k--;
+      if (k >= 0 && (masked[k] === '.' || masked[k] === '$')) continue;
+      const before = masked.slice(Math.max(0, m.index - 12), m.index);
+      if (/(?:function|def|class|new)\s+$/.test(before)) continue;
+      const openIdx = m.index + m[0].length - 1;
+      const closeIdx = readBalanced(masked, openIdx);
+      if (closeIdx === -1) continue;
+      const inner = masked.slice(openIdx + 1, closeIdx);
+      let args = 0;
+      // Emptiness is judged on the ORIGINAL text — masking blanks string
+      // contents, so `f("a,b")` would otherwise look like zero arguments.
+      if (src.slice(openIdx + 1, closeIdx).trim()) {
+        args = 1;
+        let depth = 0;
+        for (let i = 0; i < inner.length; i++) {
+          const ch = inner[i];
+          if (ch === '(' || ch === '[' || ch === '{') depth++;
+          else if (ch === ')' || ch === ']' || ch === '}') depth--;
+          else if (ch === ',' && depth === 0) args++;
+        }
+      }
+      calls.push({ name, args, line: src.slice(0, m.index).split('\n').length });
+    }
+    return calls;
+  }
+
+  /**
+   * Check one call against the arity index.
+   * @returns {null | { min, max, variadic, file, sig }} the offended entry, or null when fine/unknowable
+   */
+  function checkArity(name, argCount, arityIndex) {
+    const entry = arityIndex.get(name);
+    if (!entry || entry === 'ambiguous') return null;
+    if (entry.variadic) return argCount < entry.min ? entry : null;
+    if (argCount < entry.min || argCount > entry.max) return entry;
+    return null;
+  }
+
+  module.exports = { parseParams, buildArityIndex, extractCallArgCounts, checkArity, cleanSig, EXACT_PARAM_EXTS };
+  
+};
+
 // ── ./src/verify/closest-match ──
 __factories["./src/verify/closest-match"] = function(module, exports) {
   
@@ -19753,6 +19937,7 @@ __factories["./src/verify/hallucination-guard"] = function(module, exports) {
   const parsers = __require('./src/verify/parsers');
   const { closestMatch, buildSymbolCandidates, formatSuggestion } = __require('./src/verify/closest-match');
   const { buildLibraryIndex } = __require('./src/verify/lib-index');
+  const { buildArityIndex, extractCallArgCounts, checkArity } = __require('./src/verify/arity');
 
   // A path that looks like a test file (JS/TS spec/test, Python test_/_test, or
   // a tests/__tests__ directory). Used to flag fake-test-file separately.
@@ -19808,9 +19993,11 @@ __factories["./src/verify/hallucination-guard"] = function(module, exports) {
     const set = new Set();
     let fileKeys = [];
     let symbolCandidates = [];
+    let sigIndex = null;
     try {
       const { buildSigIndex } = __require('./src/retrieval/ranker');
       const idx = buildSigIndex(cwd);
+      sigIndex = idx;
       fileKeys = [...idx.keys()];
       for (const sigs of idx.values()) {
         for (const sig of sigs) {
@@ -19821,7 +20008,7 @@ __factories["./src/verify/hallucination-guard"] = function(module, exports) {
       }
       symbolCandidates = buildSymbolCandidates(idx);
     } catch (_) {}
-    return { set, fileKeys, symbolCandidates };
+    return { set, fileKeys, symbolCandidates, sigIndex };
   }
 
   /** Load declared dependency names from package.json. */
@@ -19910,6 +20097,7 @@ __factories["./src/verify/hallucination-guard"] = function(module, exports) {
     let fileBasenames = opts.fileBasenames;
     let symbolCandidates = opts.symbolCandidates || [];
     let fileCandidates = opts.fileCandidates || [];
+    let arityIndex = opts.arityIndex || null;
     if (!symbolSet) {
       const built = buildSymbolSet(cwd);
       symbolSet = built.set;
@@ -19918,6 +20106,9 @@ __factories["./src/verify/hallucination-guard"] = function(module, exports) {
       ));
       symbolCandidates = built.symbolCandidates;
       fileCandidates = built.fileKeys;
+      if (!arityIndex && built.sigIndex) {
+        try { arityIndex = buildArityIndex(built.sigIndex); } catch (_) {}
+      }
     }
     if (!fileBasenames) fileBasenames = new Set();
 
@@ -20036,6 +20227,32 @@ __factories["./src/verify/hallucination-guard"] = function(module, exports) {
       }
     }
 
+    // 3b. arity-mismatch (D1, #529) — a call to a KNOWN repo function whose
+    // argument count falls outside the signature's [min, max]. Conservative by
+    // construction: only uniquely-resolved, top-level functions from
+    // exact-param languages (JS/TS via the balanced scanner, Python via AST);
+    // variadic signatures only flag too-few; dotted calls never flag.
+    if (arityIndex && arityIndex.size > 0) {
+      for (const block of parsers.extractCodeBlocks(answerText)) {
+        if (block.lang && !/^(js|jsx|ts|tsx|javascript|typescript|python|py)$/i.test(block.lang)) continue;
+        for (const call of extractCallArgCounts(block.content)) {
+          if (!symbolSet.has(call.name)) continue; // unknown symbols stay fake-symbol territory
+          const entry = checkArity(call.name, call.args, arityIndex);
+          if (!entry) continue;
+          const range = entry.variadic ? `at least ${entry.min}`
+            : (entry.min === entry.max ? String(entry.max) : `${entry.min}–${entry.max}`);
+          add({
+            type: 'arity-mismatch',
+            value: `${call.name}(${call.args} args)`,
+            line: block.line + call.line - 1,
+            message: `${call.name}() called with ${call.args} argument(s) — repo signature takes ${range}`,
+            confidence: 'medium',
+            suggestion: `${entry.sig}  (${entry.file})`,
+          });
+        }
+      }
+    }
+
     // 4. fake-npm-script
     if (hasPkg && scripts.size > 0) {
       for (const { name, line } of parsers.extractNpmScripts(answerText)) {
@@ -20997,7 +21214,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.27.0';
+const VERSION = '8.28.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {

package/llms-full.txt

@@ -11,13 +11,13 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.27.0 | Benchmark: sigmap-v8.27-main (2026-08-18)
+# Version: 8.28.0 | Benchmark: sigmap-v8.28-main (2026-08-18)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
 ---
 
-## Core metrics (benchmark: sigmap-v8.27-main, 2026-08-18)
+## Core metrics (benchmark: sigmap-v8.28-main, 2026-08-18)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|

package/llms.txt

@@ -11,7 +11,7 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.27.0 | Benchmark: sigmap-v8.27-main (2026-08-18)
+# Version: 8.28.0 | Benchmark: sigmap-v8.28-main (2026-08-18)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -23,7 +23,7 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - No blast-radius awareness before editing a hub file — `--impact` shows every file a change touches.
 - Pasted stack traces, CI logs, and JSON bloat the prompt — `squeeze` minimizes them and enriches the top frame from the symbol index.
 
-## Core metrics (benchmark: sigmap-v8.27-main, 2026-08-18)
+## Core metrics (benchmark: sigmap-v8.28-main, 2026-08-18)
 
 - hit@5 retrieval: 81.1% vs 44.0% single-shot grep baseline (1.73× lift)
 - Token reduction: 96.8% average across benchmark repos

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "8.27.0",
+  "version": "8.28.0",
   "description": "The deterministic, verifiable grounding layer for AI code work — a zero-dependency signature-and-evidence map that grounds Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP agents against your real code (repo + installed libraries) so they stop hallucinating files, imports & APIs. Runs offline via npx; byte-stable output; ~97% token reduction as proof.",
   "main": "packages/core/index.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "8.27.0",
+  "version": "8.28.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "8.27.0",
+  "version": "8.28.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '8.27.0',
+  version: '8.28.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 

package/src/verify/arity.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * Arity-checked verification (D1, #529).
+ *
+ * With JS/TS params exact (v8.27 balanced scanner) and Python params from the
+ * AST, the signature index carries real parameter lists — so verification can
+ * check not just "does this function exist" but "is this call's argument
+ * count plausible". Deliberately conservative: only uniquely-resolved,
+ * non-variadic, top-level functions from exact-param languages are checked,
+ * and dotted method calls are never flagged.
+ */
+
+const path = require('path');
+const { maskCode, readBalanced } = require('../extractors/scan');
+
+// Files whose signature params are exact (JS/TS via scan.js, Python via AST).
+const EXACT_PARAM_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py']);
+
+const CTRL_KEYWORDS = new Set([
+  'if', 'for', 'while', 'switch', 'catch', 'return', 'typeof', 'await',
+  'do', 'else', 'try', 'finally', 'new', 'in', 'of', 'not', 'and', 'or',
+  'print', 'super', 'this',
+]);
+
+// Top-level callable sig shapes (indented member sigs are excluded on purpose
+// — method calls are dotted in answers and dotted calls are skipped anyway).
+const CALLABLE_RES = [
+  /^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/,
+  /^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?\(/,
+  /^(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/,
+];
+
+/** Strip the `  :start-end` anchor and `  # hint` tail from a sig line. */
+function cleanSig(sig) {
+  return String(sig).replace(/\s{2}#\s.*$/, '').replace(/\s*:\d+(?:-\d+)?\s*$/, '');
+}
+
+/**
+ * Parse a parameter-list string into an arity range.
+ * Depth- and quote-aware top-level comma split; `=` defaults and trailing `?`
+ * lower `min`; `...rest` / `*args` / `**kwargs` mark the signature variadic;
+ * destructuring patterns count as one parameter.
+ * @param {string} paramText text between the signature's parens
+ * @returns {{ min: number, max: number, variadic: boolean }}
+ */
+function parseParams(paramText) {
+  const text = String(paramText || '').trim();
+  if (!text) return { min: 0, max: 0, variadic: false };
+  const masked = maskCode(text);
+  const pieces = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < masked.length; i++) {
+    const ch = masked[i];
+    if (ch === '(' || ch === '[' || ch === '{') depth++;
+    else if (ch === ')' || ch === ']' || ch === '}') depth--;
+    else if (ch === ',' && depth === 0) { pieces.push({ raw: text.slice(start, i), masked: masked.slice(start, i) }); start = i + 1; }
+  }
+  pieces.push({ raw: text.slice(start), masked: masked.slice(start) });
+
+  let min = 0;
+  let max = 0;
+  let variadic = false;
+  for (const piece of pieces) {
+    const p = piece.raw.trim();
+    if (!p) continue;
+    if (/^(\.\.\.|\*)/.test(p)) { variadic = true; continue; }
+    max++;
+    // Optional: a top-level `=` default (scan the masked piece at depth 0) or
+    // a `?`-suffixed name (TS optional, survives type stripping as `x?`).
+    let d = 0;
+    let optional = /^[A-Za-z_$][\w$]*\s*\?$/.test(p);
+    const pm = piece.masked;
+    for (let i = 0; i < pm.length && !optional; i++) {
+      const ch = pm[i];
+      if (ch === '(' || ch === '[' || ch === '{') d++;
+      else if (ch === ')' || ch === ']' || ch === '}') d--;
+      else if (ch === '=' && d === 0 && pm[i + 1] !== '>' && pm[i - 1] !== '=' && pm[i - 1] !== '!' && pm[i - 1] !== '<' && pm[i - 1] !== '>') optional = true;
+    }
+    if (!optional) min++;
+  }
+  return { min, max, variadic };
+}
+
+/**
+ * Build a per-name arity index from a SigMap signature index.
+ * Only top-level callables from exact-param languages are included; a name
+ * whose signatures disagree across files is marked ambiguous (never checked).
+ * @param {Map<string, string[]>} sigIndex Map<file, sigs[]>
+ * @returns {Map<string, { min, max, variadic, file, sig } | 'ambiguous'>}
+ */
+function buildArityIndex(sigIndex) {
+  const index = new Map();
+  if (!sigIndex || !(sigIndex instanceof Map)) return index;
+  for (const [file, sigs] of sigIndex.entries()) {
+    if (!EXACT_PARAM_EXTS.has(path.extname(file))) continue;
+    for (const sig of sigs || []) {
+      const cleaned = cleanSig(sig);
+      let name = null;
+      for (const re of CALLABLE_RES) {
+        const m = cleaned.match(re);
+        if (m) { name = m[1]; break; }
+      }
+      if (!name) continue;
+      const openIdx = cleaned.indexOf('(', cleaned.indexOf(name));
+      if (openIdx === -1) continue;
+      const masked = maskCode(cleaned);
+      const closeIdx = readBalanced(masked, openIdx);
+      if (closeIdx === -1) continue;
+      const arity = parseParams(cleaned.slice(openIdx + 1, closeIdx));
+      const entry = { ...arity, file, sig: cleaned.trim() };
+      const existing = index.get(name);
+      if (existing === undefined) index.set(name, entry);
+      else if (existing === 'ambiguous') continue;
+      else if (existing.min !== entry.min || existing.max !== entry.max || existing.variadic !== entry.variadic) {
+        index.set(name, 'ambiguous');
+      }
+    }
+  }
+  return index;
+}
+
+/**
+ * Extract call sites with argument counts from answer code.
+ * Dotted/property calls and keyword-preceded definitions are skipped for
+ * precision; nested calls and comma-containing strings count correctly
+ * because the scan is over masked text.
+ * @param {string} code
+ * @returns {{ name: string, args: number, line: number }[]}
+ */
+function extractCallArgCounts(code) {
+  const src = String(code || '');
+  const masked = maskCode(src);
+  const calls = [];
+  const re = /([A-Za-z_$][\w$]*)\s*\(/g;
+  let m;
+  while ((m = re.exec(masked)) !== null) {
+    const name = m[1];
+    if (CTRL_KEYWORDS.has(name)) continue;
+    let k = m.index - 1;
+    while (k >= 0 && (masked[k] === ' ' || masked[k] === '\t')) k--;
+    if (k >= 0 && (masked[k] === '.' || masked[k] === '$')) continue;
+    const before = masked.slice(Math.max(0, m.index - 12), m.index);
+    if (/(?:function|def|class|new)\s+$/.test(before)) continue;
+    const openIdx = m.index + m[0].length - 1;
+    const closeIdx = readBalanced(masked, openIdx);
+    if (closeIdx === -1) continue;
+    const inner = masked.slice(openIdx + 1, closeIdx);
+    let args = 0;
+    // Emptiness is judged on the ORIGINAL text — masking blanks string
+    // contents, so `f("a,b")` would otherwise look like zero arguments.
+    if (src.slice(openIdx + 1, closeIdx).trim()) {
+      args = 1;
+      let depth = 0;
+      for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (ch === '(' || ch === '[' || ch === '{') depth++;
+        else if (ch === ')' || ch === ']' || ch === '}') depth--;
+        else if (ch === ',' && depth === 0) args++;
+      }
+    }
+    calls.push({ name, args, line: src.slice(0, m.index).split('\n').length });
+  }
+  return calls;
+}
+
+/**
+ * Check one call against the arity index.
+ * @returns {null | { min, max, variadic, file, sig }} the offended entry, or null when fine/unknowable
+ */
+function checkArity(name, argCount, arityIndex) {
+  const entry = arityIndex.get(name);
+  if (!entry || entry === 'ambiguous') return null;
+  if (entry.variadic) return argCount < entry.min ? entry : null;
+  if (argCount < entry.min || argCount > entry.max) return entry;
+  return null;
+}
+
+module.exports = { parseParams, buildArityIndex, extractCallArgCounts, checkArity, cleanSig, EXACT_PARAM_EXTS };

package/src/verify/hallucination-guard.js

@@ -22,6 +22,7 @@ const path = require('path');
 const parsers = require('./parsers');
 const { closestMatch, buildSymbolCandidates, formatSuggestion } = require('./closest-match');
 const { buildLibraryIndex } = require('./lib-index');
+const { buildArityIndex, extractCallArgCounts, checkArity } = require('./arity');
 
 // A path that looks like a test file (JS/TS spec/test, Python test_/_test, or
 // a tests/__tests__ directory). Used to flag fake-test-file separately.
@@ -77,9 +78,11 @@ function buildSymbolSet(cwd) {
   const set = new Set();
   let fileKeys = [];
   let symbolCandidates = [];
+  let sigIndex = null;
   try {
     const { buildSigIndex } = require('../retrieval/ranker');
     const idx = buildSigIndex(cwd);
+    sigIndex = idx;
     fileKeys = [...idx.keys()];
     for (const sigs of idx.values()) {
       for (const sig of sigs) {
@@ -90,7 +93,7 @@ function buildSymbolSet(cwd) {
     }
     symbolCandidates = buildSymbolCandidates(idx);
   } catch (_) {}
-  return { set, fileKeys, symbolCandidates };
+  return { set, fileKeys, symbolCandidates, sigIndex };
 }
 
 /** Load declared dependency names from package.json. */
@@ -179,6 +182,7 @@ function verify(answerText, cwd, opts = {}) {
   let fileBasenames = opts.fileBasenames;
   let symbolCandidates = opts.symbolCandidates || [];
   let fileCandidates = opts.fileCandidates || [];
+  let arityIndex = opts.arityIndex || null;
   if (!symbolSet) {
     const built = buildSymbolSet(cwd);
     symbolSet = built.set;
@@ -187,6 +191,9 @@ function verify(answerText, cwd, opts = {}) {
     ));
     symbolCandidates = built.symbolCandidates;
     fileCandidates = built.fileKeys;
+    if (!arityIndex && built.sigIndex) {
+      try { arityIndex = buildArityIndex(built.sigIndex); } catch (_) {}
+    }
   }
   if (!fileBasenames) fileBasenames = new Set();
 
@@ -305,6 +312,32 @@ function verify(answerText, cwd, opts = {}) {
     }
   }
 
+  // 3b. arity-mismatch (D1, #529) — a call to a KNOWN repo function whose
+  // argument count falls outside the signature's [min, max]. Conservative by
+  // construction: only uniquely-resolved, top-level functions from
+  // exact-param languages (JS/TS via the balanced scanner, Python via AST);
+  // variadic signatures only flag too-few; dotted calls never flag.
+  if (arityIndex && arityIndex.size > 0) {
+    for (const block of parsers.extractCodeBlocks(answerText)) {
+      if (block.lang && !/^(js|jsx|ts|tsx|javascript|typescript|python|py)$/i.test(block.lang)) continue;
+      for (const call of extractCallArgCounts(block.content)) {
+        if (!symbolSet.has(call.name)) continue; // unknown symbols stay fake-symbol territory
+        const entry = checkArity(call.name, call.args, arityIndex);
+        if (!entry) continue;
+        const range = entry.variadic ? `at least ${entry.min}`
+          : (entry.min === entry.max ? String(entry.max) : `${entry.min}–${entry.max}`);
+        add({
+          type: 'arity-mismatch',
+          value: `${call.name}(${call.args} args)`,
+          line: block.line + call.line - 1,
+          message: `${call.name}() called with ${call.args} argument(s) — repo signature takes ${range}`,
+          confidence: 'medium',
+          suggestion: `${entry.sig}  (${entry.file})`,
+        });
+      }
+    }
+  }
+
   // 4. fake-npm-script
   if (hasPkg && scripts.size > 0) {
     for (const { name, line } of parsers.extractNpmScripts(answerText)) {