@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/real-solidity-analyzer-UCI2KWUB.js

@@ -0,0 +1,2608 @@
+import {
+  buildResolutionTables
+} from "./chunk-2DE27DVC.js";
+import {
+  fileClaimForTarget
+} from "./chunk-EWMWK7WN.js";
+import {
+  ASTEngine
+} from "./chunk-3ZTOHHSW.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import {
+  BINDING_SEP
+} from "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-MLKGABMK.js";
+
+// src/ast/solidity-reserved-tokens.ts
+var RESERVED_TOKENS = /* @__PURE__ */ new Set([
+  "_",
+  "abstract",
+  "add",
+  "addmod",
+  "address",
+  "and",
+  "anonymous",
+  "as",
+  "assembly",
+  "at",
+  "balance",
+  "basefee",
+  "blobbasefee",
+  "blobfee",
+  "blobhash",
+  "blockhash",
+  "bool",
+  "break",
+  "byte",
+  "bytes",
+  "bytes1",
+  "bytes10",
+  "bytes11",
+  "bytes12",
+  "bytes13",
+  "bytes14",
+  "bytes15",
+  "bytes16",
+  "bytes17",
+  "bytes18",
+  "bytes19",
+  "bytes2",
+  "bytes20",
+  "bytes21",
+  "bytes22",
+  "bytes23",
+  "bytes24",
+  "bytes25",
+  "bytes26",
+  "bytes27",
+  "bytes28",
+  "bytes29",
+  "bytes3",
+  "bytes30",
+  "bytes31",
+  "bytes32",
+  "bytes4",
+  "bytes5",
+  "bytes6",
+  "bytes7",
+  "bytes8",
+  "bytes9",
+  "call",
+  "callcode",
+  "calldata",
+  "calldatacopy",
+  "calldataload",
+  "calldatasize",
+  "caller",
+  "callvalue",
+  "case",
+  "catch",
+  "chainid",
+  "coinbase",
+  "constant",
+  "constructor",
+  "continue",
+  "contract",
+  "create",
+  "create2",
+  "days",
+  "default",
+  "delegatecall",
+  "delete",
+  "difficulty",
+  "div",
+  "do",
+  "else",
+  "emit",
+  "enum",
+  "eq",
+  "error",
+  "ether",
+  "event",
+  "exp",
+  "extcodecopy",
+  "extcodehash",
+  "extcodesize",
+  "external",
+  "fallback",
+  "false",
+  "finney",
+  "fixed",
+  "for",
+  "from",
+  "function",
+  "gas",
+  "gaslimit",
+  "gasprice",
+  "global",
+  "gt",
+  "gwei",
+  "hex",
+  "hours",
+  "if",
+  "immutable",
+  "import",
+  "indexed",
+  "int",
+  "int104",
+  "int112",
+  "int120",
+  "int128",
+  "int136",
+  "int144",
+  "int152",
+  "int16",
+  "int160",
+  "int168",
+  "int176",
+  "int184",
+  "int192",
+  "int200",
+  "int208",
+  "int216",
+  "int224",
+  "int232",
+  "int24",
+  "int240",
+  "int248",
+  "int256",
+  "int32",
+  "int40",
+  "int48",
+  "int56",
+  "int64",
+  "int72",
+  "int8",
+  "int80",
+  "int88",
+  "int96",
+  "interface",
+  "internal",
+  "invalid",
+  "is",
+  "iszero",
+  "keccak256",
+  "layout",
+  "leave",
+  "let",
+  "library",
+  "log0",
+  "log1",
+  "log2",
+  "log3",
+  "log4",
+  "lt",
+  "mapping",
+  "mcopy",
+  "memory",
+  "minutes",
+  "mload",
+  "mod",
+  "modifier",
+  "msize",
+  "mstore",
+  "mstore8",
+  "mul",
+  "mulmod",
+  "new",
+  "not",
+  "number",
+  "or",
+  "origin",
+  "override",
+  "payable",
+  "pop",
+  "pragma",
+  "prevrandao",
+  "private",
+  "public",
+  "pure",
+  "receive",
+  "return",
+  "returndatacopy",
+  "returndatasize",
+  "returns",
+  "revert",
+  "sar",
+  "sdiv",
+  "seconds",
+  "selfbalance",
+  "selfdestruct",
+  "sgt",
+  "shl",
+  "shr",
+  "signextend",
+  "sload",
+  "slt",
+  "smod",
+  "solidity",
+  "sstore",
+  "staticcall",
+  "stop",
+  "storage",
+  "string",
+  "struct",
+  "sub",
+  "switch",
+  "szabo",
+  "timestamp",
+  "tload",
+  "transient",
+  "true",
+  "try",
+  "tstore",
+  "type",
+  "ufixed",
+  "uint",
+  "uint104",
+  "uint112",
+  "uint120",
+  "uint128",
+  "uint136",
+  "uint144",
+  "uint152",
+  "uint16",
+  "uint160",
+  "uint168",
+  "uint176",
+  "uint184",
+  "uint192",
+  "uint200",
+  "uint208",
+  "uint216",
+  "uint224",
+  "uint232",
+  "uint24",
+  "uint240",
+  "uint248",
+  "uint256",
+  "uint32",
+  "uint40",
+  "uint48",
+  "uint56",
+  "uint64",
+  "uint72",
+  "uint8",
+  "uint80",
+  "uint88",
+  "uint96",
+  "unchecked",
+  "unicode",
+  "using",
+  "var",
+  "view",
+  "virtual",
+  "weeks",
+  "wei",
+  "while",
+  "xor",
+  "years"
+]);
+var isPrimitiveTypeToken = (name) => {
+  const has = (prefix) => name.length > prefix.length && name.startsWith(prefix) && isAllDigits(name.slice(prefix.length));
+  if (name === "bool" || name === "string" || name === "address" || name === "byte" || name === "bytes" || name === "fixed" || name === "ufixed") return true;
+  return has("uint") || has("int") || has("bytes");
+};
+var isAllDigits = (text) => {
+  if (text.length === 0) return false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (c < 48 || c > 57) return false;
+  }
+  return true;
+};
+var isReservedTarget = (type, target, metadata) => {
+  if (target.length === 0) return false;
+  const meta = metadata ?? {};
+  const viaMember = meta.isMemberCall === true || meta.isMemberReference === true || meta.isTypeReference === true;
+  if (type === "calls") {
+    if (viaMember) return false;
+    return RESERVED_TOKENS.has(target);
+  }
+  if (type === "instantiates") return RESERVED_TOKENS.has(target);
+  if (type === "uses") {
+    if (viaMember) return false;
+    return RESERVED_TOKENS.has(target);
+  }
+  return false;
+};
+var ENGINE_FUNCTION_NAMES = /* @__PURE__ */ new Set([
+  "require",
+  "assert",
+  "gasleft",
+  "sha256",
+  "ripemd160",
+  "ecrecover",
+  "suicide",
+  "keccak256",
+  "sha3",
+  "gas",
+  "blockhash",
+  "blobhash",
+  "selfdestruct",
+  "addmod",
+  "mulmod"
+]);
+var EVM_BUILTIN_NAMES = /* @__PURE__ */ new Set([
+  "stop",
+  "add",
+  "sub",
+  "mul",
+  "div",
+  "sdiv",
+  "mod",
+  "smod",
+  "exp",
+  "not",
+  "lt",
+  "gt",
+  "slt",
+  "sgt",
+  "eq",
+  "iszero",
+  "and",
+  "or",
+  "xor",
+  "byte",
+  "shl",
+  "shr",
+  "sar",
+  "addmod",
+  "mulmod",
+  "signextend",
+  "keccak256",
+  "pop",
+  "mload",
+  "mstore",
+  "mstore8",
+  "sload",
+  "sstore",
+  "mcopy",
+  "tload",
+  "tstore",
+  "msize",
+  "gas",
+  "address",
+  "balance",
+  "selfbalance",
+  "caller",
+  "callvalue",
+  "calldataload",
+  "calldatasize",
+  "calldatacopy",
+  "extcodesize",
+  "extcodecopy",
+  "extcodehash",
+  "returndatasize",
+  "returndatacopy",
+  "create",
+  "create2",
+  "call",
+  "callcode",
+  "delegatecall",
+  "staticcall",
+  "return",
+  "revert",
+  "selfdestruct",
+  "invalid",
+  "log0",
+  "log1",
+  "log2",
+  "log3",
+  "log4",
+  "datasize",
+  "dataoffset",
+  "dataload",
+  "setimmutable",
+  "loadimmutable",
+  "linkersymbol",
+  "memoryguard",
+  "verbatim",
+  "chainid",
+  "basefee",
+  "blobbasefee",
+  "blobhash",
+  "origin",
+  "gasprice",
+  "blockhash",
+  "coinbase",
+  "timestamp",
+  "number",
+  "difficulty",
+  "prevrandao",
+  "gaslimit"
+]);
+var STORE_REFUSED_SYMBOL_NAMES = /* @__PURE__ */ new Set([
+  "this",
+  "super",
+  "self",
+  "Self",
+  "me",
+  "My",
+  "destructor",
+  "root",
+  "program",
+  "source_file",
+  "module_declaration",
+  "package_manifest",
+  "GlobalScope",
+  "SCSS_FILE_SCOPE",
+  "unknown"
+]);
+
+// src/ast/real-solidity-analyzer.ts
+var isSpaceCode = (code) => code === 32 || code >= 9 && code <= 13 || code === 160 || code === 5760 || code >= 8192 && code <= 8202 || code === 8232 || code === 8233 || code === 8239 || code === 8287 || code === 12288 || code === 65279;
+var isPlausibleSymbolName = (name) => {
+  if (name.length === 0) return false;
+  for (let i = 0; i < name.length; i++) {
+    const c = name.charCodeAt(i);
+    const ok = c >= 48 && c <= 57 || c >= 65 && c <= 90 || c >= 97 && c <= 122 || c === 95 || c === 36 || c === 46 || c === 40 || c === 41;
+    if (!ok) return false;
+  }
+  return true;
+};
+var skipLeadingSpace = (text) => {
+  let i = 0;
+  while (i < text.length && isSpaceCode(text.charCodeAt(i))) i++;
+  return text.slice(i);
+};
+var unquote = (text) => {
+  if (text.length < 2) return text;
+  const first = text.charCodeAt(0);
+  if (first !== 34 && first !== 39) return text;
+  if (text.charCodeAt(text.length - 1) !== first) return text;
+  return text.slice(1, -1);
+};
+var GLOBAL_OBJECTS = /* @__PURE__ */ new Set(["msg", "block", "tx", "super", "this"]);
+var RealSolidityAnalyzer = class {
+  analyze(rootNode, content, filePath, context) {
+    const projectIndex = context?.projectIndex;
+    let inheritanceKindsResolvedProjectWide = 0;
+    const typeKindByName = /* @__PURE__ */ new Map();
+    const DECLARATION_NODE_TYPES = /* @__PURE__ */ new Set([
+      "contract_declaration",
+      "interface_declaration",
+      "library_declaration",
+      "function_definition",
+      "modifier_definition",
+      "constructor_definition",
+      "fallback_receive_definition",
+      "struct_declaration",
+      "enum_declaration",
+      "event_definition",
+      "error_declaration",
+      "user_defined_type_definition",
+      "state_variable_declaration",
+      "variable_declaration"
+    ]);
+    const natSpecParamCheck = (doc, paramNames, hasReturn) => {
+      const undocumented = paramNames.filter((n) => n !== "");
+      const overDocumented = [];
+      let returnWithoutReturn = false;
+      const documented = /* @__PURE__ */ new Set();
+      for (const line of doc.split("\n")) {
+        const t = line.trim();
+        if (!t.startsWith("@")) continue;
+        let end = 1;
+        while (end < t.length) {
+          const c = t.charAt(end);
+          if (c === " " || c === "	") break;
+          end++;
+        }
+        const tag = t.slice(0, end);
+        if (tag === "@param") {
+          let rest = end;
+          while (rest < t.length && (t.charAt(rest) === " " || t.charAt(rest) === "	")) rest++;
+          let nameEnd = rest;
+          while (nameEnd < t.length && t.charAt(nameEnd) !== " " && t.charAt(nameEnd) !== "	") nameEnd++;
+          const nm = t.slice(rest, nameEnd);
+          if (nm === "") continue;
+          documented.add(nm);
+          if (!paramNames.includes(nm)) overDocumented.push(nm);
+        } else if (tag === "@return") {
+          if (!hasReturn) returnWithoutReturn = true;
+        }
+      }
+      for (const n of documented) {
+        const at = undocumented.indexOf(n);
+        if (at >= 0) undocumented.splice(at, 1);
+      }
+      return { undocumented, overDocumented, returnWithoutReturn };
+    };
+    const readSolcLicence = (root) => {
+      const run = [];
+      for (let i = 0; i < root.namedChildCount; i++) {
+        const c = root.namedChild(i);
+        if (!c) continue;
+        if (c.type === "comment") {
+          run.push(c);
+          continue;
+        }
+        break;
+      }
+      for (const c of run) {
+        const text = readNatSpec(c.text).text;
+        if (text === "") continue;
+        for (const line of text.split("\n")) {
+          const t = line.trim();
+          if (!t.startsWith("SPDX-License-Identifier:")) continue;
+          const id = t.slice("SPDX-License-Identifier:".length).trim();
+          if (id !== "") return id;
+        }
+      }
+      return null;
+    };
+    const readNatSpec = (raw) => {
+      const lines2 = raw.split("\n");
+      const out = [];
+      let sawNatspec = false;
+      for (const line of lines2) {
+        let t = line;
+        while (t.length > 0 && t.charAt(0) === " ") t = t.slice(1);
+        if (t.startsWith("*/")) t = t.slice(2);
+        else if (t.startsWith("/**")) {
+          t = t.slice(3);
+          sawNatspec = true;
+        } else if (t.startsWith("///")) {
+          t = t.slice(3);
+          sawNatspec = true;
+        } else if (t.startsWith("//")) t = t.slice(2);
+        else if (t.startsWith("*")) t = t.slice(1);
+        if (t.startsWith(" ")) t = t.slice(1);
+        out.push(t);
+      }
+      while (out.length > 0 && out[out.length - 1].trim() === "") out.pop();
+      while (out.length > 0 && out[0].trim() === "") out.shift();
+      return {
+        text: out.join("\n").trim(),
+        kind: sawNatspec ? raw.indexOf("/**") === 0 ? "natspec-block" : "natspec-line" : "line"
+      };
+    };
+    const natSpecTags = (text) => {
+      const tags = [];
+      for (const line of text.split("\n")) {
+        const t = line.trim();
+        if (!t.startsWith("@")) continue;
+        let end = 1;
+        while (end < t.length) {
+          const c = t.charAt(end);
+          if (c === " " || c === "	") break;
+          end++;
+        }
+        tags.push(t.slice(0, end));
+      }
+      return tags;
+    };
+    const docByNode = /* @__PURE__ */ new Map();
+    let commentsRead = 0;
+    let commentsAttached = 0;
+    let documentedSymbols = 0;
+    let symbolsWithComplexity = 0;
+    let natSpecUndocumentedParams = 0;
+    let natSpecOverDocumentedParams = 0;
+    let natSpecReturnWithoutReturn = 0;
+    let symbolsWithUndocumentedParams = 0;
+    let symbolsWithOverDocumentedParams = 0;
+    const overDocumentedSamples = [];
+    const returnWithoutReturnSamples = [];
+    let symbolsWithQualifiedCalls = 0;
+    {
+      const attachRun = (run, anchor) => {
+        if (run.length === 0 || anchor === null) return;
+        if (!DECLARATION_NODE_TYPES.has(anchor.type)) return;
+        const parts = [];
+        let kind = "line";
+        for (const c of run) {
+          const read = readNatSpec(c.text);
+          if (read.text === "") continue;
+          parts.push(read.text);
+          if (read.kind !== "line") kind = read.kind;
+          commentsAttached++;
+        }
+        if (parts.length === 0) return;
+        const prior = docByNode.get(anchor.id);
+        if (prior === void 0) {
+          docByNode.set(anchor.id, { text: parts.join("\n"), kind, parts });
+        } else {
+          prior.parts.push(...parts);
+          prior.text = prior.parts.join("\n");
+          if (kind !== "line") prior.kind = kind;
+        }
+      };
+      const stack = [rootNode];
+      while (stack.length > 0) {
+        const p = stack.pop();
+        for (let i = 0; i < p.childCount; i++) {
+          const c = p.child(i);
+          if (c) stack.push(c);
+        }
+        let run = [];
+        let anchor = null;
+        const flush = () => {
+          if (run.length > 0) attachRun(run, anchor);
+          run = [];
+          anchor = null;
+        };
+        for (let i = 0; i < p.namedChildCount; i++) {
+          const c = p.namedChild(i);
+          if (!c) continue;
+          if (c.type === "comment") {
+            commentsRead++;
+            const last = run.length > 0 ? run[run.length - 1] : null;
+            if (last !== null && c.startPosition.row > last.endPosition.row + 1) flush();
+            run.push(c);
+            continue;
+          }
+          anchor = c;
+          flush();
+        }
+        flush();
+      }
+    }
+    const recoveryLines = /* @__PURE__ */ new Set();
+    {
+      const stack = [rootNode];
+      while (stack.length > 0) {
+        const n = stack.pop();
+        if (n.type === "ERROR" || n.isMissing) {
+          for (let r = n.startPosition.row + 1; r <= n.endPosition.row + 1; r++) recoveryLines.add(r);
+        }
+        for (let i = 0; i < n.childCount; i++) {
+          const c = n.child(i);
+          if (c) stack.push(c);
+        }
+      }
+    }
+    const symbols = [];
+    const relationships = [];
+    const imports = [];
+    const exports = [];
+    const relKeys = /* @__PURE__ */ new Set();
+    const frameworks = /* @__PURE__ */ new Set(["Solidity"]);
+    const patterns = /* @__PURE__ */ new Set();
+    const fileName = this.basenameOf(filePath);
+    const lines = content.split("\n");
+    const licence = readSolcLicence(rootNode);
+    symbols.push({
+      name: fileName,
+      kind: ASTEngine.SymbolKind.Module,
+      range: this.nodeToRange(rootNode),
+      visibility: "public",
+      ...licence !== null ? { license: licence } : {},
+      metadata: {
+        soliditySpecific: true,
+        isCompilationUnit: true,
+        ...licence !== null ? { license: licence } : {}
+      }
+    });
+    let cyclomaticComplexity = 1;
+    const frames = [{ owner: fileName, scope: fileName, containerLine: 1, yul: false, branches: 0, sym: null, qualifiedCalls: [], bindings: /* @__PURE__ */ new Set() }];
+    const top = () => frames[frames.length - 1];
+    const atFileScope = () => frames.length === 1;
+    const nodeKey = (n) => `${n.startIndex}:${n.endIndex}`;
+    const openedFrames = /* @__PURE__ */ new Set();
+    const interfaceNames = /* @__PURE__ */ new Set();
+    const typeNamesInFile = /* @__PURE__ */ new Set();
+    const membersByType = /* @__PURE__ */ new Map();
+    const basesByContract = /* @__PURE__ */ new Map();
+    const modifierNamesInFile = /* @__PURE__ */ new Set();
+    const declaredTypeNamesForCalls = /* @__PURE__ */ new Set();
+    const declaredVariableTypes = /* @__PURE__ */ new Map();
+    const noteVariableType = (name, type) => {
+      if (name === "" || type === void 0 || type === "") return;
+      const set = declaredVariableTypes.get(name);
+      if (set === void 0) declaredVariableTypes.set(name, /* @__PURE__ */ new Set([type]));
+      else set.add(type);
+    };
+    const containerElementTypes = /* @__PURE__ */ new Map();
+    const noteContainerElementType = (name, typeNode) => {
+      if (!typeNode || name === "") return;
+      const text = skipLeadingSpace(typeNode.text).trim();
+      if (!text.startsWith("mapping") && !text.endsWith("]")) return;
+      const udts = findDescendants(typeNode, "user_defined_type");
+      const last = udts[udts.length - 1];
+      const head = udtName(last);
+      if (head !== "") containerElementTypes.set(name, head);
+    };
+    let projectResolutionTables = null;
+    const projectTables = () => {
+      if (projectResolutionTables === null) projectResolutionTables = buildResolutionTables(projectIndex);
+      return projectResolutionTables;
+    };
+    const overrideCandidates = [];
+    const topLevelExports = [];
+    const importEdges = [];
+    let engineCallsSuppressed = 0;
+    const storeRefusedNames = /* @__PURE__ */ new Set();
+    let storeRefusedDeclarations = 0;
+    let symbolsSuppressedOnRecoveryLines = 0;
+    let getterSymbols = 0;
+    let extendsUnresolvedAsInterface = 0;
+    const evidenceClassFor = (type, isImport = false, confidence = 1) => {
+      if (isImport) return "import_based";
+      switch (type) {
+        case ASTEngine.RelationshipType.Contains:
+        case ASTEngine.RelationshipType.Extends:
+        case ASTEngine.RelationshipType.Implements:
+        case ASTEngine.RelationshipType.Exports:
+        case ASTEngine.RelationshipType.Instantiates:
+          return "structural";
+        case ASTEngine.RelationshipType.Overrides:
+          return "inferred";
+        default:
+          return "usage_contextual";
+      }
+    };
+    const caseAudit = process.env.BB_SOLIDITY_CASE_AUDIT === "1";
+    const __hits = {};
+    const __emits = {};
+    let __cur = "(pre)";
+    const addRel = (source, target, type, confidence, line, metadata = {}, opts = {}) => {
+      if (caseAudit) __emits[__cur] = (__emits[__cur] ?? 0) + 1;
+      if (!source || !target) return;
+      if (opts.bindingTarget) {
+        const at = target.lastIndexOf(BINDING_SEP);
+        if (at <= 0 || at + BINDING_SEP.length >= target.length) return;
+        if (target.indexOf(BINDING_SEP) !== at) return;
+        const ownerPart = target.slice(0, at);
+        const leafPart = target.slice(at + BINDING_SEP.length);
+        if (!isPlausibleSymbolName(ownerPart) || !isPlausibleSymbolName(leafPart)) return;
+      } else if (!opts.pathTarget && !isPlausibleSymbolName(target)) return;
+      if (!Number.isFinite(line) || line < 1) return;
+      if (recoveryLines.has(line)) return;
+      if (isReservedTarget(type, target, metadata)) return;
+      if (type === ASTEngine.RelationshipType.Calls && ENGINE_FUNCTION_NAMES.has(target)) {
+        engineCallsSuppressed++;
+        return;
+      }
+      const key = `${source}\0${type}\0${opts.dedupeAs ?? target}\0${line}`;
+      if (relKeys.has(key)) return;
+      relKeys.add(key);
+      const isImport = metadata.import === true;
+      relationships.push({
+        source,
+        target,
+        type,
+        confidence,
+        line_number: line,
+        // Caller metadata LAST so an explicit `evidenceClass` at a call site wins.
+        metadata: { evidenceClass: evidenceClassFor(type, isImport, confidence), soliditySpecific: true, ...metadata }
+      });
+    };
+    const symbolMap = /* @__PURE__ */ new Map();
+    const pushSymbol = (name, kind, node, meta = {}, parameters) => {
+      const clean = name.trim();
+      if (clean === "") return null;
+      const line = node.startPosition.row + 1;
+      const doc = docByNode.get(node.id);
+      if (doc !== void 0 && meta.docstring === void 0) {
+        meta.docstring = doc.text;
+        meta.docstringKind = doc.kind;
+        meta.comments = doc.parts;
+        const tags = natSpecTags(doc.text);
+        if (tags.length > 0) meta.docTags = tags;
+        documentedSymbols++;
+        if (parameters !== void 0 && Array.isArray(parameters)) {
+          const check = natSpecParamCheck(
+            doc.text,
+            parameters.map((pp) => pp.name).filter((n) => typeof n === "string"),
+            typeof meta.returnType === "string" && meta.returnType !== ""
+          );
+          if (check.undocumented.length > 0) {
+            meta.undocumentedParameters = check.undocumented;
+            natSpecUndocumentedParams += check.undocumented.length;
+            symbolsWithUndocumentedParams++;
+          }
+          if (check.overDocumented.length > 0) {
+            meta.overDocumentedParameters = check.overDocumented;
+            natSpecOverDocumentedParams += check.overDocumented.length;
+            symbolsWithOverDocumentedParams++;
+            overDocumentedSamples.push(`${fileName}:${line} ${clean} documents @param ${check.overDocumented.join(", ")}`);
+          }
+          meta.returnDocumentedWithoutReturn = check.returnWithoutReturn;
+          if (check.returnWithoutReturn) {
+            natSpecReturnWithoutReturn++;
+            returnWithoutReturnSamples.push(`${fileName}:${line} ${clean} has @return but returns nothing`);
+          }
+        }
+      }
+      const owner = top().owner;
+      const key = `${owner}\0${clean}\0${kind}`;
+      const existing = symbolMap.get(key);
+      if (existing) return existing;
+      const sym = {
+        name: clean,
+        kind,
+        range: this.nodeToRange(node),
+        scope: owner,
+        ownerName: owner,
+        visibility: meta.visibility ?? "public",
+        parameters,
+        // SOL-16 — top-level as well as in metadata, because `docstring` is a
+        // FIRST-CLASS field on UniversalSymbol and the store reads `s.docstring`
+        // (pool-worker.ts:673). Metadata alone left `brain_symbol.docstring` NULL for
+        // every Solidity symbol while the analyzer believed it had published
+        // documentation — the field existed in the payload and nothing read it.
+        // SOL-17 — first-class symbol field, so it crosses the worker boundary and
+        // reaches the store rather than living only in metadata.
+        ...Array.isArray(meta.decorators) ? { decorators: meta.decorators } : {},
+        // SOL-18 — `ownerKind` is a first-class symbol field (`pool-worker` forwards
+        // it), so it is set top-level as well as in metadata, for the same reason
+        // `docstring` is.
+        ...typeof meta.ownerKind === "string" ? { ownerKind: meta.ownerKind } : {},
+        // SOL-23 — top-level as well, because `parseFile` returns every symbol with
+        // `metadata: undefined` (pool-worker drops the object at the worker boundary),
+        // so a value only in metadata is invisible to a fixture — which is exactly how
+        // the first version of this feature looked like it had never run.
+        ...typeof meta.stateLocation === "string" ? { stateLocation: meta.stateLocation } : {},
+        ...Array.isArray(meta.undocumentedParameters) ? { undocumentedParameters: meta.undocumentedParameters } : {},
+        ...Array.isArray(meta.overDocumentedParameters) ? { overDocumentedParameters: meta.overDocumentedParameters } : {},
+        ...typeof meta.returnDocumentedWithoutReturn === "boolean" ? { returnDocumentedWithoutReturn: meta.returnDocumentedWithoutReturn } : {},
+        ...typeof meta.docstring === "string" ? { docstring: meta.docstring } : {},
+        // Each of these is read out of `meta`, which is `Record<string, unknown>`, so
+        // each is narrowed on its own rather than carried along by the docstring check:
+        // `meta.docstringKind` being a string says nothing about `meta.docTags`. The
+        // runtime shapes are unchanged -- only the proof that they hold is now stated.
+        ...typeof meta.docstringKind === "string" ? { docstringKind: meta.docstringKind } : {},
+        ...Array.isArray(meta.docTags) ? { docTags: meta.docTags } : {},
+        // Also top-level: pool-worker's parseFile return shape does not carry
+        // `metadata` on symbols at all, so anything only in metadata is invisible
+        // to every consumer of this API — which is how `docstringKind` read `-`
+        // on the first successful run of this feature.
+        ...Array.isArray(meta.comments) ? { comments: meta.comments } : {},
+        metadata: { soliditySpecific: true, ...meta }
+      };
+      if (typeof meta.isAbstract === "boolean") sym.isAbstract = meta.isAbstract;
+      if (typeof meta.returnType === "string" && meta.returnType) sym.returnType = meta.returnType;
+      symbols.push(sym);
+      symbolMap.set(key, sym);
+      return sym;
+    };
+    const declareSymbol = (name, kind, node, line, meta = {}, parameters, containsLine = line) => {
+      const clean = name.trim();
+      if (clean === "") return null;
+      const doc = docByNode.get(node.id);
+      if (doc !== void 0 && meta.docstring === void 0) {
+        meta.docstring = doc.text;
+        meta.docstringKind = doc.kind;
+        meta.comments = doc.parts;
+        const tags = natSpecTags(doc.text);
+        if (tags.length > 0) meta.docTags = tags;
+        documentedSymbols++;
+        if (parameters !== void 0 && Array.isArray(parameters)) {
+          const check = natSpecParamCheck(
+            doc.text,
+            parameters.map((pp) => pp.name).filter((n) => typeof n === "string"),
+            typeof meta.returnType === "string" && meta.returnType !== ""
+          );
+          if (check.undocumented.length > 0) {
+            meta.undocumentedParameters = check.undocumented;
+            natSpecUndocumentedParams += check.undocumented.length;
+            symbolsWithUndocumentedParams++;
+          }
+          if (check.overDocumented.length > 0) {
+            meta.overDocumentedParameters = check.overDocumented;
+            natSpecOverDocumentedParams += check.overDocumented.length;
+            symbolsWithOverDocumentedParams++;
+            overDocumentedSamples.push(`${fileName}:${line} ${clean} documents @param ${check.overDocumented.join(", ")}`);
+          }
+          meta.returnDocumentedWithoutReturn = check.returnWithoutReturn;
+          if (check.returnWithoutReturn) {
+            natSpecReturnWithoutReturn++;
+            returnWithoutReturnSamples.push(`${fileName}:${line} ${clean} has @return but returns nothing`);
+          }
+        }
+      }
+      if (STORE_REFUSED_SYMBOL_NAMES.has(clean)) {
+        storeRefusedDeclarations++;
+        storeRefusedNames.add(clean);
+        return null;
+      }
+      if (recoveryLines.has(line)) {
+        symbolsSuppressedOnRecoveryLines++;
+        return null;
+      }
+      const ownerKindName = typeKindByName.get(top().owner);
+      if (ownerKindName !== void 0 && meta.ownerKind === void 0) {
+        meta.ownerKind = ownerKindName;
+      }
+      if (kind === ASTEngine.SymbolKind.Class || kind === ASTEngine.SymbolKind.Interface) {
+        const kw = typeof meta.declarationKeyword === "string" ? meta.declarationKeyword : "";
+        typeKindByName.set(
+          clean,
+          kind === ASTEngine.SymbolKind.Interface ? "interface" : kw === "library" ? "library" : "contract"
+        );
+      }
+      const key = `${top().owner}\0${clean}\0${kind}`;
+      if (symbolMap.has(key)) return null;
+      const pushed = pushSymbol(clean, kind, node, meta, parameters);
+      const owner = top().owner;
+      if (owner && owner !== clean) {
+        addRel(owner, clean, ASTEngine.RelationshipType.Contains, 1, containsLine ?? line, {});
+      }
+      return pushed;
+    };
+    const findChildren = (node, type) => {
+      const out = [];
+      if (!node) return out;
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c && c.type === type) out.push(c);
+      }
+      return out;
+    };
+    const findFirstChild = (node, type) => {
+      const found = findChildren(node, type);
+      return found.length > 0 ? found[0] : null;
+    };
+    const findDescendant = (node, type) => {
+      if (!node) return null;
+      const work2 = [node];
+      while (work2.length > 0) {
+        const n = work2.shift();
+        if (n.type === type) return n;
+        for (let i = 0; i < n.namedChildCount; i++) {
+          const c = n.namedChild(i);
+          if (c) work2.push(c);
+        }
+      }
+      return null;
+    };
+    const findDescendants = (root, type) => {
+      const out = [];
+      const work2 = [root];
+      while (work2.length > 0) {
+        const n = work2.pop();
+        if (n !== root && n.type === type) out.push(n);
+        for (let i = 0; i < n.namedChildCount; i++) {
+          const c = n.namedChild(i);
+          if (c) work2.push(c);
+        }
+      }
+      return out;
+    };
+    const udtName = (node) => {
+      if (!node) return "";
+      if (node.type === "identifier") return node.text;
+      if (node.type !== "user_defined_type") return "";
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c && c.type === "identifier") return c.text;
+      }
+      return "";
+    };
+    const typeTextOf = (node) => {
+      if (!node) return "";
+      const udt = findFirstChild(node, "user_defined_type");
+      if (udt) return udtName(udt);
+      return skipLeadingSpace(node.text).trim();
+    };
+    const calleeNameOf = (node, depth = 0, viaMember = false) => {
+      if (!node || depth > 6) return null;
+      const line = node.startPosition.row + 1;
+      switch (node.type) {
+        case "identifier":
+          return { name: node.text, line, viaMember };
+        case "member_expression": {
+          const prop = node.childForFieldName("property");
+          return prop ? calleeNameOf(prop, depth + 1, true) : null;
+        }
+        case "struct_expression":
+          return calleeNameOf(node.childForFieldName("type"), depth + 1, viaMember);
+        case "user_defined_type": {
+          const n = udtName(node);
+          return n === "" ? null : { name: n, line, viaMember };
+        }
+        case "array_access":
+          return calleeNameOf(node.childForFieldName("base"), depth + 1, viaMember);
+        case "expression":
+        case "payable_conversion_expression":
+        case "parenthesized_expression": {
+          for (let i = 0; i < node.namedChildCount; i++) {
+            const c = node.namedChild(i);
+            if (!c) continue;
+            const got = calleeNameOf(c, depth + 1, viaMember);
+            if (got) return got;
+          }
+          return null;
+        }
+        default:
+          return null;
+      }
+    };
+    const innerCalleeOf = (node, depth = 0) => {
+      if (!node || depth > 6) return null;
+      if (node.type === "identifier" || node.type === "member_expression" || node.type === "user_defined_type") return node;
+      if (node.type === "struct_expression") {
+        return innerCalleeOf(node.childForFieldName("type"), depth + 1);
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (!c) continue;
+        const got = innerCalleeOf(c, depth + 1);
+        if (got) return got;
+      }
+      return null;
+    };
+    const memberObjectName = (node) => {
+      const obj = node.childForFieldName("object");
+      if (!obj) return "";
+      if (obj.type === "identifier") return obj.text;
+      if (obj.type === "expression" && obj.namedChildCount > 0) {
+        const c = obj.namedChild(0);
+        if (c && c.type === "identifier") return c.text;
+      }
+      return "";
+    };
+    const conversionTypeOf = (node) => {
+      if (!node) return "";
+      if (node.type === "expression" && node.namedChildCount > 0) return conversionTypeOf(node.namedChild(0));
+      if (node.type !== "call_expression") return "";
+      const fn = node.childForFieldName("function") ?? node.namedChild(0);
+      const inner = fn && fn.type === "expression" && fn.namedChildCount > 0 ? fn.namedChild(0) : fn;
+      if (!inner) return "";
+      if (inner.type === "identifier") return inner.text;
+      if (inner.type === "user_defined_type") return udtName(inner);
+      return "";
+    };
+    const indexedBaseOf = (node) => {
+      if (!node) return "";
+      if (node.type === "expression" && node.namedChildCount > 0) return indexedBaseOf(node.namedChild(0));
+      if (node.type !== "array_access") return "";
+      const base = node.namedChild(0);
+      if (!base) return "";
+      if (base.type === "identifier") return base.text;
+      if (base.type === "expression" && base.namedChildCount > 0) {
+        const c = base.namedChild(0);
+        if (c && c.type === "identifier") return c.text;
+      }
+      return "";
+    };
+    const isClaimedCallee = (node) => {
+      let cur = node;
+      for (let hop = 0; hop < 6 && cur; hop++) {
+        if (claimedCallees.has(cur.id)) return true;
+        cur = cur.parent;
+      }
+      return false;
+    };
+    const isClaimedCalleeDirect = (node) => {
+      const parent = node.parent;
+      return parent !== null && claimedCallees.has(parent.id);
+    };
+    const isEngineMemberObject = (object) => {
+      if (!object) return false;
+      if (object.type === "identifier" && GLOBAL_OBJECTS.has(object.text)) return true;
+      if (object.type === "meta_type_expression") return true;
+      if (object.type === "expression" && object.namedChildCount > 0) {
+        const c = object.namedChild(0);
+        if (c && c.type === "meta_type_expression") return true;
+        if (c && c.type === "identifier" && GLOBAL_OBJECTS.has(c.text)) return true;
+      }
+      return false;
+    };
+    const collectParameters = (node) => {
+      const lists = [];
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (!c) continue;
+        if (c.type === "parameter") lists.push(c);
+        else if (c.type === "return_type_definition") lists.push(...findChildren(c, "parameter"));
+      }
+      const out = [];
+      for (const p of lists) {
+        const nameNode = p.childForFieldName("name");
+        if (!nameNode) continue;
+        out.push({ name: nameNode.text, type: typeTextOf(p.childForFieldName("type")) });
+      }
+      return out;
+    };
+    const modifiersOf = (node) => {
+      const meta = {};
+      const hasChildType = (t) => {
+        for (let i = 0; i < node.childCount; i++) {
+          const c = node.child(i);
+          if (c && c.type === t) return true;
+        }
+        return false;
+      };
+      for (let i = 0; i < node.childCount; i++) {
+        const c = node.child(i);
+        if (!c) continue;
+        if (c.type === "state_mutability") meta.stateMutability = c.text;
+        else if (c.type === "visibility") meta.visibility = c.text;
+        else if (c.type === "virtual") meta.isVirtual = true;
+        else if (c.type === "override_specifier") meta.hasOverrideSpecifier = true;
+        else if (c.type === "constant") meta.isConstant = true;
+        else if (c.type === "immutable") meta.isImmutable = true;
+      }
+      const first = node.childCount > 0 ? node.child(0) : null;
+      meta.isAbstract = first !== null && first.type === "abstract";
+      const ret = node.childForFieldName("return_type");
+      if (ret) {
+        const types = findChildren(ret, "parameter").map((p) => typeTextOf(p.childForFieldName("type")));
+        if (types.length === 1) meta.returnType = types[0];
+        else if (types.length > 1) meta.returnType = `(${types.join(", ")})`;
+      }
+      meta.hasBody = findFirstChild(node, "function_body") !== null;
+      const applied = [];
+      for (const inv of findChildren(node, "modifier_invocation")) {
+        const id = findFirstChild(inv, "identifier");
+        if (id) applied.push(id.text);
+      }
+      if (applied.length > 0) meta.decorators = applied;
+      return meta;
+    };
+    const noteMember = (owner, name) => {
+      if (owner === fileName || owner === "") return;
+      let set = membersByType.get(owner);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        membersByType.set(owner, set);
+      }
+      set.add(name);
+    };
+    const isBranchNode = (node) => {
+      switch (node.type) {
+        case "if_statement":
+        case "for_statement":
+        case "while_statement":
+        case "do_while_statement":
+        case "ternary_expression":
+        case "catch_clause":
+        case "yul_if_statement":
+        case "yul_switch_statement":
+          return true;
+        case "binary_expression": {
+          for (let i = 0; i < node.childCount; i++) {
+            const c = node.child(i);
+            if (c && (c.type === "&&" || c.type === "||")) return true;
+          }
+          return false;
+        }
+        default:
+          return false;
+      }
+    };
+    const openFrame = (node, owner, scope, line, yul = false, isType = false, sym = null) => {
+      openedFrames.add(nodeKey(node));
+      const CALLABLE_DEFINITION_TYPES = /* @__PURE__ */ new Set([
+        "function_definition",
+        "constructor_definition",
+        "fallback_receive_definition",
+        "modifier_definition"
+      ]);
+      let bindings = /* @__PURE__ */ new Set();
+      if (CALLABLE_DEFINITION_TYPES.has(node.type)) {
+        for (const p of collectParameters(node)) {
+          bindings.add(p.name);
+          noteVariableType(p.name, p.type);
+        }
+      }
+      frames.push({ owner, scope, containerLine: line, yul, isType, branches: 1, sym, qualifiedCalls: [], bindings });
+    };
+    const bindingOwnerOf = (name) => {
+      for (let i = frames.length - 1; i >= 1; i--) {
+        if (frames[i].bindings.has(name)) return frames[i].scope;
+      }
+      return null;
+    };
+    const enclosingTypeOf = () => {
+      for (let i = frames.length - 1; i >= 1; i--) if (frames[i].isType) return frames[i].owner;
+      return "";
+    };
+    {
+      const prepass = [rootNode];
+      while (prepass.length > 0) {
+        const n = prepass.pop();
+        if (n.type === "ERROR" || n.isMissing) continue;
+        switch (n.type) {
+          case "modifier_definition": {
+            const nameNode = n.childForFieldName("name");
+            if (nameNode) modifierNamesInFile.add(nameNode.text);
+            break;
+          }
+          case "contract_declaration":
+          case "interface_declaration":
+          case "library_declaration":
+          case "struct_declaration":
+          case "enum_declaration":
+          case "user_defined_type_definition": {
+            const nameNode = n.childForFieldName("name");
+            if (nameNode) declaredTypeNamesForCalls.add(nameNode.text);
+            break;
+          }
+        }
+        for (let i = n.namedChildCount - 1; i >= 0; i--) {
+          const c = n.namedChild(i);
+          if (c) prepass.push(c);
+        }
+      }
+    }
+    const work = [{ node: rootNode, exit: false }];
+    const claimedCallees = /* @__PURE__ */ new Set();
+    while (work.length > 0) {
+      const { node, exit } = work.pop();
+      if (exit) {
+        if (openedFrames.has(nodeKey(node))) {
+          const done = frames.pop();
+          if (done.sym !== null) {
+            done.sym.metadata.complexity = done.branches;
+            done.sym.complexity = done.branches;
+            symbolsWithComplexity++;
+            if (done.qualifiedCalls.length > 0) {
+              const uniq = [...new Set(done.qualifiedCalls)].sort();
+              done.sym.qualified_calls = uniq;
+              done.sym.qualifiedCalls = uniq;
+              done.sym.metadata.qualifiedCalls = uniq;
+              symbolsWithQualifiedCalls++;
+            }
+          }
+          openedFrames.delete(nodeKey(node));
+        }
+        continue;
+      }
+      if (node.type === "ERROR" || node.isMissing) continue;
+      if (isBranchNode(node)) {
+        cyclomaticComplexity++;
+        top().branches++;
+      }
+      let descend = true;
+      if (caseAudit) {
+        __hits[node.type] = (__hits[node.type] ?? 0) + 1;
+        __cur = node.type;
+      }
+      switch (node.type) {
+        // ----------------------------------------------------- file structure
+        case "source_file":
+          break;
+        case "pragma_directive": {
+          patterns.add(`pragma:${skipLeadingSpace(node.text).slice(0, 40)}`);
+          break;
+        }
+        case "import_directive": {
+          const srcNode = node.childForFieldName("source");
+          const rawPath = srcNode ? unquote(skipLeadingSpace(srcNode.text)) : "";
+          const alias = node.childForFieldName("alias");
+          const braced = [];
+          let braceDepth = 0;
+          for (let i = 0; i < node.childCount; i++) {
+            const c = node.child(i);
+            if (!c) continue;
+            if (c.type === "{") braceDepth++;
+            else if (c.type === "}") braceDepth--;
+            else if (braceDepth === 1 && c.type === "identifier") braced.push(c.text);
+          }
+          const anySource = findFirstChild(node, "any_source_type") !== null;
+          const plainName = node.childForFieldName("import_name");
+          const line = node.startPosition.row + 1;
+          const names = braced.length > 0 ? braced : plainName ? [plainName.text] : [];
+          for (const n of names) importEdges.push({ name: n, path: rawPath, line });
+          if (names.length === 0 && alias) {
+            importEdges.push({ name: alias.text, path: rawPath, line, isNamespace: true });
+          } else if (names.length === 0 && !alias) {
+            importEdges.push({ name: "*", path: rawPath, line });
+          }
+          imports.push({
+            source: rawPath,
+            imported: alias ? alias.text : anySource ? "*" : names[0] ?? rawPath,
+            line,
+            isDefault: names.length === 0 && !alias,
+            metadata: { soliditySpecific: true, namedImports: names, isNamespaceImport: anySource }
+          });
+          break;
+        }
+        // ------------------------------------------------------ SOL-24: WITHDRAWN
+        //
+        // `using L for T` was published as `mixes_in` for part of 2026-10-27 and the
+        // emission is WITHDRAWN. Why it looked right: the directive names a member set
+        // and declares no conformance, so `extends`/`implements` are false and `uses`
+        // (a name READ) seemed too weak.
+        //
+        // WHY IT IS FALSE, AND THE VOCABULARY'S OWN WORDS ARE THE TEST. `mixes_in`
+        // (src/ast/types.ts) is "a class COMPOSES a mixin into its SUPERTYPE CHAIN …
+        // the mixin is a supertype member" — the members enter the composing type, and
+        // the whole fleet uses it that way: PHP trait `use` flattens the trait's
+        // members into the class's method table (real-php-analyzer.ts isTraitUse), Go
+        // embedding promotes the embedded type's methods and fields into the struct
+        // (real-go-analyzer.ts), and the consumers of this value say so out loud
+        // (src/intelligence/graph/graph-engine.ts ranks `mixes_in` as a supertype
+        // composition, between `implements` and `renders`).
+        //
+        // SOLIDITY'S DIRECTIVE DOES NOT DO THAT. L's functions are never members of T:
+        // no member is added to T's declared surface, T's ABI and inheritance chain are
+        // untouched, and `t.f()` compiles as `L.f(t)` only where the directive is in
+        // scope (`global` widening the scope, not the type). The composing ACTOR is the
+        // SCOPE, not the type, so the row's source would be the wrong actor as well as
+        // the wrong relation. Publishing it would have put `Price -> MathLib` in a
+        // bucket two instruments read as "Price composes a supertype".
+        //
+        // THE DEPENDENCY IS NOT LOST: the `type_alias` case above already publishes the
+        // library as a `references` edge, which is the true relation (the file read the
+        // name). The construct population is measured, not dropped: 124 `using_directive`
+        // sites in 76 files, of which 27 have a declared host and one library, 0 of which
+        // add a member to the type — validation/m14/measurements/solidity-extended-census.json
+        // and script/m14/tmp/sol24-mixes-counters.mts. The ruling and its falsifier live
+        // in script/m14/spec/solidity-completeness.json (coverage.excluded.mixes_in).
+        //
+        // ⇒ A NODE TYPE WITH NO CASE HERE IS THE HONEST SHAPE OF THIS REFUSAL: an empty
+        // `case` would look like a counter that was meant to fire.
+        // ------------------------------------------------------ declarations
+        case "contract_declaration":
+        case "interface_declaration":
+        case "library_declaration": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          const kind = node.type === "interface_declaration" ? ASTEngine.SymbolKind.Interface : ASTEngine.SymbolKind.Class;
+          if (node.type === "interface_declaration") interfaceNames.add(name);
+          typeNamesInFile.add(name);
+          declareSymbol(name, kind, node, line, {
+            ...modifiersOf(node),
+            declarationKeyword: node.type.slice(0, -"_declaration".length)
+          });
+          if (atFileScope()) topLevelExports.push({ name, line });
+          const bases = [];
+          for (const spec of findChildren(node, "inheritance_specifier")) {
+            const anc = spec.childForFieldName("ancestor");
+            const baseName = udtName(anc);
+            if (baseName === "") continue;
+            bases.push(baseName);
+            const isInterface = interfaceNames.has(baseName);
+            if (!isInterface && typeNamesInFile.has(baseName)) {
+            } else if (!isInterface && !typeNamesInFile.has(baseName) && projectIndex?.typeKinds.get(baseName) === void 0) {
+              extendsUnresolvedAsInterface++;
+            }
+            const projectKind = isInterface || typeNamesInFile.has(baseName) ? void 0 : projectIndex?.typeKinds.get(baseName);
+            if (projectKind !== void 0) inheritanceKindsResolvedProjectWide++;
+            const projectIsInterface = projectKind === "interface";
+            const kindUnresolved = !isInterface && !typeNamesInFile.has(baseName) && projectKind === void 0;
+            addRel(
+              name,
+              baseName,
+              isInterface || projectIsInterface ? ASTEngine.RelationshipType.Implements : ASTEngine.RelationshipType.Extends,
+              kindUnresolved ? 0.9 : 1,
+              (anc ?? spec).startPosition.row + 1,
+              {
+                isSolidityInheritance: true,
+                interfaceResolvedInFile: isInterface,
+                ...kindUnresolved ? {
+                  // The tier, stated at the site that knows the claim is undecided.
+                  evidenceClass: "inferred",
+                  kindUnresolved: true,
+                  assumedKind: ASTEngine.RelationshipType.Extends,
+                  reasonCode: "base-not-declared-in-file",
+                  // SOL-27 — AND THE CLAIM THE PROJECT CAN ANSWER. `kindUnresolved` means NEITHER
+                  // this file NOR the project index declares the base — the fact the arbiter checks
+                  // (a claim is consulted only where `decls === 0`). MEASURED: 38 unresolved
+                  // `extends`, led by `Test` 33 (forge-std's base contract, outside the corpus).
+                  externalTarget: true,
+                  externalVia: "base"
+                } : {},
+                // SOL-21 — how the kind was settled, so a consumer can tell a settled
+                // cross-file kind from an in-file one. `undefined` for the in-file case,
+                // which is the pre-existing shape and needs no new key.
+                ...projectKind !== void 0 ? {
+                  kindResolvedProjectWide: true,
+                  baseDeclarationKind: projectKind
+                } : {},
+                ...spec.childForFieldName("ancestor_arguments") ? { hasBaseConstructorArgs: true } : {}
+              }
+            );
+          }
+          basesByContract.set(name, bases);
+          openFrame(node, name, name, line, false, true);
+          break;
+        }
+        case "struct_declaration": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          declareSymbol(name, ASTEngine.SymbolKind.Struct, node, line, { declarationKeyword: "struct" });
+          if (atFileScope()) topLevelExports.push({ name, line });
+          openFrame(node, name, top().scope, line);
+          break;
+        }
+        case "enum_declaration": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          declareSymbol(name, ASTEngine.SymbolKind.Enum, node, line, { declarationKeyword: "enum" });
+          if (atFileScope()) topLevelExports.push({ name, line });
+          openFrame(node, name, top().scope, line);
+          break;
+        }
+        // grammar.js:285 — `enum_body: commaSep(alias($.identifier, $.enum_value))`.
+        // An `enum_value` has NO fields: the name IS the node's own text, because
+        // the grammar aliased the identifier to the value node. Reading a `name:`
+        // field here returns null and silently publishes nothing.
+        case "enum_value": {
+          const name = node.text.trim();
+          if (name === "") break;
+          const line = node.startPosition.row + 1;
+          declareSymbol(name, ASTEngine.SymbolKind.EnumMember, node, line, { declarationKeyword: "enum value" });
+          break;
+        }
+        case "struct_member": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const line = nameNode.startPosition.row + 1;
+          declareSymbol(nameNode.text, ASTEngine.SymbolKind.Property, node, line, {
+            declarationKeyword: "struct member",
+            declaredType: typeTextOf(node.childForFieldName("type"))
+          });
+          break;
+        }
+        case "function_definition": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          const kind = atFileScope() ? ASTEngine.SymbolKind.Function : ASTEngine.SymbolKind.Method;
+          const meta = modifiersOf(node);
+          const overrideSpec = findFirstChild(node, "override_specifier");
+          if (overrideSpec) {
+            const explicit = findChildren(overrideSpec, "user_defined_type").map((u) => udtName(u)).filter((s) => s !== "");
+            const anyBase = basesByContract.get(top().owner) ?? [];
+            const inFile = explicit.filter((b) => typeNamesInFile.has(b));
+            meta.overrideExternal = inFile.length === 0;
+            overrideCandidates.push({ memberName: name, owner: top().owner, line, explicit, anyBase });
+            for (const b of explicit) {
+              if (!typeNamesInFile.has(b)) {
+                addRel(
+                  top().scope,
+                  b,
+                  ASTEngine.RelationshipType.References,
+                  0.8,
+                  line,
+                  { isOverrideBase: true, overrideBaseExternal: true }
+                );
+              }
+            }
+          }
+          const modSym = declareSymbol(name, kind, node, line, meta, collectParameters(node));
+          noteMember(top().owner, name);
+          openFrame(node, name, name, line, false, false, modSym);
+          break;
+        }
+        case "modifier_definition": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          modifierNamesInFile.add(name);
+          const meta = modifiersOf(node);
+          if (findFirstChild(node, "override_specifier")) {
+            meta.overrideExternal = true;
+            overrideCandidates.push({
+              memberName: name,
+              owner: top().owner,
+              line,
+              explicit: [],
+              anyBase: basesByContract.get(top().owner) ?? []
+            });
+          }
+          const fnSym = declareSymbol(name, ASTEngine.SymbolKind.Method, node, line, meta, collectParameters(node));
+          noteMember(top().owner, name);
+          openFrame(node, name, name, line, false, false, fnSym);
+          break;
+        }
+        // SOL-4 — the name is READ off the `constructor` keyword token. Unlike
+        // PowerShell's `Deployment(...)`, Solidity writes the word, so this is not
+        // a synthesised name and the line is the real name line.
+        case "constructor_definition": {
+          const line = node.startPosition.row + 1;
+          const name = "constructor";
+          const ctorSym = declareSymbol(
+            name,
+            ASTEngine.SymbolKind.Constructor,
+            node,
+            line,
+            modifiersOf(node),
+            collectParameters(node)
+          );
+          noteMember(top().owner, name);
+          openFrame(node, name, name, line, false, false, ctorSym);
+          break;
+        }
+        // SOL-4 — `receive` and `fallback` share ONE grammar rule
+        // (fallback_receive_definition), split by the leading keyword token.
+        case "fallback_receive_definition": {
+          const first = node.childCount > 0 ? node.child(0) : null;
+          const name = first !== null && first.type === "receive" ? "receive" : "fallback";
+          const line = node.startPosition.row + 1;
+          const fbSym = declareSymbol(
+            name,
+            ASTEngine.SymbolKind.Method,
+            node,
+            line,
+            { ...modifiersOf(node), isFallbackOrReceive: true },
+            collectParameters(node)
+          );
+          noteMember(top().owner, name);
+          openFrame(node, name, name, line, false, false, fbSym);
+          break;
+        }
+        case "event_definition": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          const paramNodes = findChildren(node, "event_parameter");
+          const params = [];
+          const indexed = [];
+          let isAnonymous = false;
+          for (let i = 0; i < node.childCount; i++) {
+            const c = node.child(i);
+            if (c && c.type === "anonymous") isAnonymous = true;
+          }
+          for (const p of paramNodes) {
+            const n = p.childForFieldName("name");
+            params.push({
+              name: n ? n.text : "",
+              type: typeTextOf(p.childForFieldName("type"))
+            });
+            for (let i = 0; i < p.childCount; i++) {
+              const c = p.child(i);
+              if (c && c.type === "indexed" && n) indexed.push(n.text);
+            }
+          }
+          declareSymbol(name, ASTEngine.SymbolKind.Event, node, line, {
+            declarationKeyword: "event",
+            indexedParameters: indexed,
+            isAnonymous
+          }, params);
+          noteMember(top().owner, name);
+          if (atFileScope()) topLevelExports.push({ name, line });
+          break;
+        }
+        // A custom error is a named, declared, ABI-visible entity with its own
+        // parameter list. `Type` is the kind that says "a named type-ish
+        // declaration" without claiming it is a class. Recorded as a decision in
+        // the F9 spec, not an accident of convenience.
+        case "error_declaration": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          const params = findChildren(node, "error_parameter").map((p) => ({
+            name: p.childForFieldName("name")?.text ?? "",
+            type: typeTextOf(p.childForFieldName("type"))
+          }));
+          declareSymbol(
+            name,
+            ASTEngine.SymbolKind.Type,
+            node,
+            line,
+            { declarationKeyword: "error" },
+            params
+          );
+          noteMember(top().owner, name);
+          if (atFileScope()) topLevelExports.push({ name, line });
+          break;
+        }
+        case "state_variable_declaration": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          const meta = modifiersOf(node);
+          meta.declaredType = typeTextOf(node.childForFieldName("type"));
+          noteVariableType(name, typeof meta.declaredType === "string" ? meta.declaredType : "");
+          noteContainerElementType(name, node.childForFieldName("type"));
+          if (node.childForFieldName("location")) {
+            meta.stateLocation = node.childForFieldName("location").text;
+          }
+          if (STORE_REFUSED_SYMBOL_NAMES.has(name)) {
+            storeRefusedDeclarations++;
+            storeRefusedNames.add(name);
+            break;
+          }
+          if (meta.visibility === "public") {
+            meta.getterSynthesised = true;
+            meta.getterVisibility = "public";
+            meta.getterIsPayable = meta.stateMutability === "payable";
+            const getterName = `${name}()`;
+            const getter = pushSymbol(getterName, ASTEngine.SymbolKind.Method, node, {
+              ...meta,
+              isSynthesisedGetter: true,
+              declarationKeyword: "public state variable getter",
+              getterFor: name,
+              ...meta.stateMutability === "view" || !meta.stateMutability ? { stateMutability: meta.stateMutability ?? "view" } : {}
+            });
+            if (getter) {
+              getterSymbols++;
+              const getterOwner = top().owner;
+              if (getterOwner && getterOwner !== getterName) {
+                addRel(getterOwner, getterName, ASTEngine.RelationshipType.Contains, 1, line, {
+                  isSynthesisedGetter: true,
+                  getterOfVariable: name
+                });
+              }
+              addRel(
+                name,
+                getterName,
+                ASTEngine.RelationshipType.References,
+                1,
+                line,
+                { isGetterFor: true, getterOfVariable: name }
+              );
+            }
+          }
+          declareSymbol(name, ASTEngine.SymbolKind.Property, node, line, meta);
+          noteMember(top().owner, name);
+          break;
+        }
+        // grammar.js:177 — a FILE-SCOPE-only declaration, one of the twelve
+        // members of `_declaration`. Inside a contract the same source text is a
+        // `state_variable_declaration`, which is why 352 of those and only 6 of
+        // these exist in the corpus.
+        case "constant_variable_declaration": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          declareSymbol(
+            name,
+            ASTEngine.SymbolKind.Constant,
+            node,
+            line,
+            { ...modifiersOf(node), isConstant: true, declaredType: typeTextOf(node.childForFieldName("type")) }
+          );
+          topLevelExports.push({ name, line });
+          break;
+        }
+        case "user_defined_type_definition": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          declareSymbol(name, ASTEngine.SymbolKind.TypeAlias, node, line, {
+            declarationKeyword: "type",
+            underlyingType: findFirstChild(node, "primitive_type")?.text ?? ""
+          });
+          typeNamesInFile.add(name);
+          if (atFileScope()) topLevelExports.push({ name, line });
+          break;
+        }
+        // ------------------------------------------------------------- locals
+        case "variable_declaration": {
+          const nameNode = node.childForFieldName("name");
+          if (!nameNode) break;
+          const line = nameNode.startPosition.row + 1;
+          const isImmutable = findFirstChild(node, "immutable") !== null;
+          const declaredType = typeTextOf(node.childForFieldName("type"));
+          noteVariableType(nameNode.text, declaredType);
+          noteContainerElementType(nameNode.text, node.childForFieldName("type"));
+          declareSymbol(
+            nameNode.text,
+            isImmutable ? ASTEngine.SymbolKind.Constant : ASTEngine.SymbolKind.Variable,
+            node,
+            line,
+            {
+              declaredType,
+              ...node.childForFieldName("value") ? { hasInitialiser: true } : {},
+              isImmutable
+            }
+          );
+          break;
+        }
+        // ----------------------------------------------------------------- Yul
+        case "yul_variable_declaration": {
+          const left = node.childForFieldName("left");
+          if (!left) break;
+          const names = left.type === "identifier" ? [left] : findDescendants(left, "identifier");
+          for (const n of names) {
+            declareSymbol(
+              n.text,
+              ASTEngine.SymbolKind.Variable,
+              n,
+              n.startPosition.row + 1,
+              { isYul: true, declaredType: "yul" }
+            );
+          }
+          break;
+        }
+        case "yul_function_definition": {
+          const idents = findChildren(node, "yul_identifier");
+          const nameNode = idents.length > 0 ? idents[0] : findDescendant(node, "yul_identifier");
+          if (!nameNode) break;
+          const name = nameNode.text;
+          const line = nameNode.startPosition.row + 1;
+          const params = idents.slice(1).map((p) => ({ name: p.text, type: "yul" }));
+          declareSymbol(name, ASTEngine.SymbolKind.Function, node, line, { isYul: true }, params);
+          noteMember(top().owner, name);
+          openFrame(node, top().owner, name, line, true);
+          for (const p of params) top().bindings.add(p.name);
+          break;
+        }
+        // SOL-8 — a `yul_evm_builtin` is an OPCODE, not a function. The skip is
+        // lossless: the lexer always spells a bare `add` as the builtin, so a
+        // user-defined Yul function can never carry that name.
+        case "yul_function_call": {
+          const fn = node.childForFieldName("function");
+          if (fn && fn.type === "yul_identifier") {
+            addRel(
+              top().scope,
+              fn.text,
+              ASTEngine.RelationshipType.Calls,
+              0.9,
+              fn.startPosition.row + 1,
+              { isYulCall: true }
+            );
+          }
+          break;
+        }
+        case "yul_path": {
+          const segs = findChildren(node, "yul_identifier");
+          const segTexts = segs.length > 0 ? segs : findChildren(node, "identifier");
+          segTexts.forEach((seg, i) => {
+            if (EVM_BUILTIN_NAMES.has(seg.text)) return;
+            const yulBindOwner = segTexts.length === 1 && i === 0 ? bindingOwnerOf(seg.text) : null;
+            const yulLine = seg.startPosition.row + 1;
+            const yulBareRefused = isReservedTarget(
+              ASTEngine.RelationshipType.Uses,
+              seg.text,
+              { isYulPathSegment: true, isYulVariableRead: true }
+            );
+            if (yulBindOwner !== null && !yulBareRefused) {
+              addRel(
+                top().scope,
+                `${yulBindOwner}${BINDING_SEP}${seg.text}`,
+                ASTEngine.RelationshipType.Uses,
+                0.7,
+                yulLine,
+                { isYulPathSegment: true, isYulVariableRead: true, localBinding: true },
+                { bindingTarget: true, dedupeAs: seg.text }
+              );
+              return;
+            }
+            addRel(top().scope, seg.text, ASTEngine.RelationshipType.Uses, 0.7, yulLine, {
+              isYulPathSegment: true,
+              ...i === 0 ? { isYulVariableRead: true } : { isYulMemberReference: true }
+            });
+          });
+          break;
+        }
+        // ---------------------------------------------------------- inheritance
+        // Handled at the contract level, where the frame is pushed and the SOL-5
+        // kind decision is made. Descending in here would emit every base twice.
+        case "inheritance_specifier": {
+          descend = false;
+          break;
+        }
+        // ------------------------------------------------------- type mentions
+        case "user_defined_type": {
+          const parent = node.parent;
+          const ptype = parent ? parent.type : "";
+          if (ptype === "inheritance_specifier" || ptype === "override_specifier" || ptype === "new_expression" || ptype === "struct_expression" || ptype === "catch_clause" || ptype === "meta_type_expression") break;
+          const name = udtName(node);
+          if (name !== "" && !GLOBAL_OBJECTS.has(name)) {
+            addRel(
+              top().scope,
+              name,
+              ASTEngine.RelationshipType.Uses,
+              0.85,
+              node.startPosition.row + 1,
+              { isTypeReference: true, typeReferenceSite: ptype }
+            );
+          }
+          break;
+        }
+        // `using L for T` / `using {f as +} for T global` — the aliased entity.
+        case "type_alias": {
+          const id = findFirstChild(node, "identifier");
+          if (id) {
+            addRel(
+              top().scope,
+              id.text,
+              ASTEngine.RelationshipType.References,
+              0.85,
+              id.startPosition.row + 1,
+              { isUsingDirectiveTarget: true }
+            );
+          }
+          break;
+        }
+        // `using {eqCallType as ==} for CallType global;` — NEVER FIRED before
+        // SOL-16. It looked for DIRECT `identifier` children, but the grammar nests
+        // the name: `using_alias (user_defined_type (identifier))
+        // (user_definable_operator)`, so `findChildren(node, "identifier")` was always
+        // empty and the loop body never ran. Found by a per-case emit census over the
+        // 389-file corpus — 4 `using_alias` nodes, all four in
+        // contracts/account/utils/draft-ERC7579Utils.sol, 0 edges — which is the same
+        // signature as the `revert_statement` dead branch, and the reason the census is
+        // worth running rather than reading the code.
+        //
+        // The name is read the way every other type reference in this analyzer reads
+        // one, through `udtName`, so it cannot disagree with the rest.
+        case "using_alias": {
+          const name = udtName(findDescendant(node, "user_defined_type"));
+          if (name !== "") {
+            addRel(
+              top().scope,
+              name,
+              ASTEngine.RelationshipType.References,
+              0.85,
+              (findDescendant(node, "user_defined_type") ?? node).startPosition.row + 1,
+              { isUsingAliasFunction: true }
+            );
+          }
+          break;
+        }
+        // `catch MyError(string memory reason)` names a declared error.
+        case "catch_clause": {
+          const id = findFirstChild(node, "identifier");
+          if (id) {
+            addRel(
+              top().scope,
+              id.text,
+              ASTEngine.RelationshipType.References,
+              0.85,
+              id.startPosition.row + 1,
+              { isCaughtError: true }
+            );
+          }
+          break;
+        }
+        // `type(uint).max` / `type(C).creationCode` — the TYPE is the reference;
+        // `max`/`creationCode` are members of the meta type, not of the project.
+        case "meta_type_expression": {
+          const udt = findDescendant(node, "user_defined_type");
+          const name = udtName(udt);
+          if (name !== "" && typeNamesInFile.has(name)) {
+            addRel(
+              top().scope,
+              name,
+              ASTEngine.RelationshipType.References,
+              0.85,
+              udt.startPosition.row + 1,
+              { isMetaType: true }
+            );
+          }
+          descend = false;
+          break;
+        }
+        // ------------------------------------------------------------- calls
+        case "call_expression": {
+          const fn = node.childForFieldName("function");
+          if (fn) claimedCallees.add(fn.id);
+          const got = calleeNameOf(fn);
+          if (got && got.name !== "") {
+            const calleeNode = got.viaMember ? innerCalleeOf(fn) : null;
+            const qObj = calleeNode ? memberObjectName(calleeNode) : "";
+            if (qObj !== "" && qObj !== "abi" && qObj !== "type" && !ENGINE_FUNCTION_NAMES.has(got.name)) {
+              top().qualifiedCalls.push(`${qObj}.${got.name}`);
+            }
+            const callBindOwnerRaw = got.viaMember ? null : bindingOwnerOf(got.name);
+            const callBareRefused = callBindOwnerRaw !== null && (isReservedTarget(ASTEngine.RelationshipType.Calls, got.name, { isSolidityCall: true }) || ENGINE_FUNCTION_NAMES.has(got.name));
+            const callBindOwner = callBareRefused ? null : callBindOwnerRaw;
+            const callTarget = callBindOwner !== null ? `${callBindOwner}${BINDING_SEP}${got.name}` : got.name;
+            const calleeObjectNode = calleeNode ? calleeNode.childForFieldName("object") : null;
+            const callObjectBase = got.viaMember && qObj === "" ? indexedBaseOf(calleeObjectNode) : "";
+            const callObjectConversion = got.viaMember && qObj === "" && callObjectBase === "" ? conversionTypeOf(calleeObjectNode) : "";
+            addRel(top().scope, callTarget, ASTEngine.RelationshipType.Calls, 0.9, got.line, {
+              isSolidityCall: true,
+              ...callBindOwner !== null ? { localBinding: true } : {},
+              // The member flag is REPORTED BY THE NAME RESOLVER, never by a second
+              // traversal that re-decides the same question. The first version ran a
+              // separate `isMemberLike(fn)` over the callee's DIRECT children, which
+              // cannot see a `member_expression` nested under a `struct_expression`'s
+              // `type:` field — so `t.call{value: 1}("")` resolved the name `call`
+              // and then failed to say it was a member call, and the reserved-token
+              // rule deleted the edge it had just resolved. `call`, `balance` and
+              // `delegatecall` are EVM opcode TOKENS and also members of Solidity's
+              // built-in types, so that deletion was silent and total. The name and
+              // the fact about where it came from now cannot disagree.
+              ...got.viaMember ? { isMemberCall: true } : {},
+              // SOL-15 — the OBJECT a member call hangs off. `abi.encode(…)` and
+              // `token.balanceOf(…)` are both `member_expression` callees, and only
+              // the object separates a language builtin from a project member. Read
+              // HERE, at the emit, because the post-pass has the callee NAME and
+              // nothing else: `encode` alone cannot say which of the two it was.
+              ...got.viaMember ? { calleeObject: qObj } : {},
+              // W14 — the CONTAINER an index receiver reads from, kept apart from `calleeObject`
+              // because the object of the member expression is `_m[k]`, not `_m`.
+              ...callObjectBase !== "" ? { calleeObjectBase: callObjectBase } : {},
+              // W14b — the TYPE a conversion receiver names (`IAccessManager(x).get()`).
+              ...callObjectConversion !== "" ? { calleeObjectConversion: callObjectConversion } : {},
+              // SOL-15 — the enclosing TYPE, captured here because the relationship's
+              // SOURCE is the enclosing scope's LEAF name (`everything`, not
+              // `Child.everything`), so the owner cannot be recovered from the row
+              // afterwards. The first version tried, got no owner, and classified
+              // every call as `inFileTypeMember` — a wrong answer produced by a
+              // missing field rather than a wrong rule, which is the harder kind of
+              // bug to see because the rule looks fine.
+              ...enclosingTypeOf() !== "" ? { calleeOwner: enclosingTypeOf() } : {},
+              ...fn && findFirstChild(fn, "struct_expression") !== null ? { hasCallOptions: true } : {}
+            }, callBindOwner !== null ? { bindingTarget: true, dedupeAs: got.name } : {});
+          }
+          break;
+        }
+        // `emit Transfer(...)` is NOT a call_expression — the grammar models the
+        // whole thing as `emit_statement` with a `name:` field, and 168 exist in
+        // the corpus. A callee pass over `call_expression` alone would publish
+        // ZERO event edges for the entire language.
+        case "emit_statement": {
+          const nameNode = node.childForFieldName("name");
+          if (nameNode) claimedCallees.add(nameNode.id);
+          const got = calleeNameOf(nameNode);
+          if (got && got.name !== "") {
+            addRel(
+              top().scope,
+              got.name,
+              ASTEngine.RelationshipType.Calls,
+              0.9,
+              got.line,
+              { isEventEmission: true }
+            );
+          }
+          break;
+        }
+        // `revert MyError(...)` — a custom error is a CALL. The name is the first
+        // NAMED child when it is a bare identifier; `revert("msg")` has no such
+        // child, which is the structural difference (measured on the tree, not
+        // assumed: `revert E(m)` puts the identifier and the `revert_arguments` as
+        // SIBLINGS).
+        // A CUSTOM ERROR is a call, and this case NEVER FIRED before SOL-15 measured
+        // it. It tested `node.namedChild(0).type === "identifier"`, but the grammar
+        // puts an `expression` WRAPPER there for all three spellings —
+        // `revert Boom(1);`, `revert Solo;` and `revert("x");` each report
+        // `expression` — so the guard was false for every possible input and the
+        // branch was decoration. The corpus has custom errors declared in
+        // `contracts/interfaces/draft-IERC6093.sol` and elsewhere, and not one
+        // reached the graph as a call.
+        //
+        // The name is the same leaf the callee resolver reads, so `revert Boom(1)`
+        // resolves through the call's `function` field and `revert Solo` through the
+        // wrapper, and `revert("x")` resolves to nothing at all — a string is not a
+        // name, which is the correct outcome rather than a missed row.
+        case "revert_statement": {
+          const first = node.namedChildCount > 0 ? node.namedChild(0) : null;
+          const calleeNode = first === null ? null : first.type === "call_expression" ? innerCalleeOf(first.childForFieldName("function")) : innerCalleeOf(first);
+          const got = calleeNameOf(calleeNode);
+          if (got && got.name !== "") {
+            addRel(
+              top().scope,
+              got.name,
+              ASTEngine.RelationshipType.Calls,
+              0.9,
+              got.line,
+              {
+                isCustomErrorRevert: true,
+                ...enclosingTypeOf() !== "" ? { calleeOwner: enclosingTypeOf() } : {}
+              }
+            );
+          }
+          break;
+        }
+        // `onlyOwner` in a function header, `Base(msg.sender)` in a constructor
+        // header. grammar.js:765 — `modifier_invocation` is `$._identifier_path`
+        // plus optional arguments, with NO field, so the name is the first
+        // `identifier` child. `descend` stays TRUE so the arguments are read.
+        //
+        // TWO CONSTRUCTS WEAR ONE NODE TYPE, and the tree cannot tell them apart:
+        // an APPLIED MODIFIER (`function f() onlyOwner`) and a BASE-CONSTRUCTOR CALL
+        // (`constructor() Base(1)`). They are the same node with the same field-less
+        // `identifier` child, so a test on the spelling cannot separate them — the
+        // discriminator is RESOLUTION against the declaration name space (the prepass
+        // above, plus the project index when one is present):
+        //
+        //   target resolves to a declared `modifier_definition` → DECORATES.
+        //     The modifier is applied code that runs around the declaration's body;
+        //     the decorated declaration is the source and the modifier is the target,
+        //     the direction the vocabulary states ("a decorated declaration is
+        //     decorated BY the decorator"). NOT a `calls` edge: an application is not
+        //     a call site, and the fleet's relabel precedent is one site, one label.
+        //   target resolves to a declared contract/interface/library → stays `calls`.
+        //     It is the base constructor being invoked, not an annotation.
+        //   neither → stays `calls` with `isModifierInvocation`, unresolved: the file
+        //     and the index cannot say what the name is, so no decorates claim is made.
+        //
+        // MEASURED, whole admitted population (script/m14/solidity-extended-census.ts):
+        // 144 decorates sites, 78 base-constructor calls, 0 ambiguous, 0 unresolved.
+        // The 78 all sit in constructor definitions, and the 4 modifier applications
+        // that also sit there are separated by the same resolution rule, not by the
+        // enclosing declaration.
+        case "modifier_invocation": {
+          const id = findFirstChild(node, "identifier");
+          if (id) {
+            const name = id.text;
+            const line = id.startPosition.row + 1;
+            const inFileModifier = modifierNamesInFile.has(name);
+            const inFileType = declaredTypeNamesForCalls.has(name);
+            let projectType = false;
+            let projectMember = false;
+            let projectSymbol = false;
+            if (!inFileModifier && !inFileType && projectIndex) {
+              projectType = projectIndex.typeKinds.has(name);
+              if (!projectType) {
+                projectMember = projectTables().memberOwners.has(name);
+                projectSymbol = !projectMember && projectIndex.symbolNames.has(name);
+              }
+            }
+            if (inFileModifier || projectMember || projectSymbol) {
+              addRel(
+                top().scope,
+                name,
+                ASTEngine.RelationshipType.Decorates,
+                inFileModifier || projectMember ? 0.9 : 0.8,
+                line,
+                {
+                  isModifierInvocation: true,
+                  isAppliedModifier: true,
+                  modifierResolution: inFileModifier ? "in-file" : projectMember ? "project-member" : "project-symbol",
+                  // W15b — the ENCLOSING TYPE, so a modifier applied on a contract whose base
+                  // declares it can be resolved through that contract's inheritance closure. The
+                  // edge had no owner at all, which is why the 17 cross-file modifier rows could
+                  // not use the mechanism SOL-25 applied to calls.
+                  ...enclosingTypeOf() !== "" ? { decoratesOwner: enclosingTypeOf() } : {}
+                }
+              );
+            } else {
+              addRel(top().scope, name, ASTEngine.RelationshipType.Calls, 0.85, line, {
+                isModifierInvocation: true,
+                ...inFileType || projectType ? { isBaseConstructorCall: true } : {}
+              });
+            }
+          }
+          break;
+        }
+        case "new_expression": {
+          const udt = findDescendant(node, "user_defined_type");
+          const name = udtName(udt);
+          if (name !== "") {
+            addRel(
+              top().scope,
+              name,
+              ASTEngine.RelationshipType.Instantiates,
+              0.95,
+              (udt ?? node).startPosition.row + 1,
+              { isNewExpression: true }
+            );
+          }
+          break;
+        }
+        // SOL-10 — the OTHER struct spelling: `S { a: 1 }` in a primary-expression
+        // position is a struct construction, and its NAME is in the `type:` field.
+        // When it is a call's callee the `call_expression` case owns it, so
+        // `isCalleeOf` is what keeps `t.call{value: 1}(...)` from emitting twice.
+        case "struct_expression": {
+          if (isClaimedCallee(node)) break;
+          const got = calleeNameOf(node.childForFieldName("type"));
+          if (got && got.name !== "") {
+            addRel(
+              top().scope,
+              got.name,
+              ASTEngine.RelationshipType.Calls,
+              0.9,
+              got.line,
+              { isStructConstructor: true }
+            );
+          }
+          descend = false;
+          break;
+        }
+        // --------------------------------------------------------- references
+        case "member_expression": {
+          const prop = node.childForFieldName("property");
+          if (!prop) break;
+          if (isClaimedCallee(node)) break;
+          const objectNode = node.childForFieldName("object");
+          if (isEngineMemberObject(objectNode)) break;
+          const object = memberObjectName(node);
+          const objectBase = object === "" ? indexedBaseOf(objectNode) : "";
+          addRel(
+            top().scope,
+            prop.text,
+            ASTEngine.RelationshipType.Uses,
+            0.8,
+            prop.startPosition.row + 1,
+            {
+              isMemberReference: true,
+              ...object !== "" ? { viaObject: object } : {},
+              ...objectBase !== "" ? { viaObjectBase: objectBase } : {}
+            }
+          );
+          break;
+        }
+        case "identifier": {
+          const parent = node.parent;
+          if (!parent || parent.type !== "expression") break;
+          if (isClaimedCalleeDirect(node)) break;
+          if (top().yul) break;
+          if (GLOBAL_OBJECTS.has(node.text)) break;
+          {
+            const bindOwner = bindingOwnerOf(node.text);
+            const bareLine = node.startPosition.row + 1;
+            const bareRefused = isReservedTarget(ASTEngine.RelationshipType.Uses, node.text, { isVariableReference: true });
+            if (bindOwner !== null && !bareRefused) {
+              addRel(
+                top().scope,
+                `${bindOwner}${BINDING_SEP}${node.text}`,
+                ASTEngine.RelationshipType.Uses,
+                0.75,
+                bareLine,
+                { isVariableReference: true, localBinding: true },
+                { bindingTarget: true, dedupeAs: node.text }
+              );
+            } else {
+              addRel(
+                top().scope,
+                node.text,
+                ASTEngine.RelationshipType.Uses,
+                0.75,
+                bareLine,
+                { isVariableReference: true }
+              );
+            }
+          }
+          break;
+        }
+        // ------------------------------------------------------------- silence
+        // Named here so the F9 spec points at code rather than at an absence, and
+        // so each reason lives beside the switch. Every one of these is either a
+        // literal, a keyword, a wrapper, or a node whose whole content is
+        // semantics the graph does not model.
+        case "comment":
+        case "string":
+        case "string_literal":
+        case "hex_string_literal":
+        case "unicode_string_literal":
+        case "number_literal":
+        case "number_unit":
+        case "boolean_literal":
+        case "true":
+        case "false":
+        case "primitive_type":
+        case "type_name":
+        case "assembly_flags":
+        case "assembly_statement":
+        case "yul_evm_builtin":
+        case "yul_boolean":
+        case "yul_string_literal":
+        case "yul_hex_string_literal":
+        case "yul_hex_number":
+        case "yul_decimal_number":
+        case "yul_break":
+        case "yul_continue":
+        case "yul_leave":
+        case "yul_label":
+        case "layout_specifier":
+        case "state_location":
+        case "virtual":
+        case "immutable":
+        case "visibility":
+        case "state_mutability":
+        case "override_specifier":
+        case "unchecked":
+        case "enum_body":
+        case "struct_body":
+        case "contract_body":
+        case "function_body":
+        case "statement":
+        case "expression":
+        case "expression_statement":
+        case "block_statement":
+        case "yul_block":
+        case "yul_assignment":
+        case "if_statement":
+        case "while_statement":
+        case "for_statement":
+        case "break_statement":
+        case "continue_statement":
+        case "do_while_statement":
+        case "return_statement":
+        case "return_parameter":
+        case "revert_arguments":
+        case "solidity_pragma_token":
+        case "solidity_version":
+        case "solidity_version_comparison_operator":
+        case "pragma_value":
+        case "any_pragma_token":
+        case "any_source_type":
+        case "inline_array_expression":
+          break;
+        default: {
+          break;
+        }
+      }
+      if (descend) {
+        work.push({ node, exit: true });
+        for (let i = node.childCount - 1; i >= 0; i--) {
+          const c = node.child(i);
+          if (c) work.push({ node: c, exit: false });
+        }
+      }
+    }
+    let overridesEmitted = 0;
+    let overridesEmittedExternal = 0;
+    let overridesUnresolved = 0;
+    let overridesAmbiguousBaseCount = 0;
+    for (const cand of overrideCandidates) {
+      const bases = cand.explicit.length > 0 ? cand.explicit : cand.anyBase.length === 1 ? cand.anyBase : [];
+      if (bases.length === 0) {
+        overridesUnresolved++;
+        overridesAmbiguousBaseCount++;
+        continue;
+      }
+      let hit = false;
+      for (const base of bases) {
+        if (base === cand.owner) continue;
+        if (!symbolMap.has(`${cand.owner}\0${cand.memberName}\0method`)) continue;
+        const members = membersByType.get(base);
+        const inFile = members !== void 0 && members.has(cand.memberName);
+        const companion = context?.overrideCompanion?.get(base);
+        const viaCompanion = !inFile && companion !== void 0 && companion.has(cand.memberName);
+        const external = !inFile;
+        addRel(cand.memberName, base, ASTEngine.RelationshipType.Overrides, external ? 0.75 : 0.9, cand.line, {
+          overridesMember: cand.memberName,
+          baseType: base,
+          ...cand.explicit.length > 0 ? { baseNamedByOverrideSpecifier: true } : { baseFromContractHeader: true },
+          ...external ? {
+            externalBase: true,
+            // A single header base is as strong as an explicit list: the compiler
+            // requires SOME base to declare the member and there is only one
+            // candidate. The reasonCode distinguishes them rather than merging
+            // two different proofs under one label.
+            reasonCode: cand.explicit.length > 0 ? "named-by-override-specifier" : viaCompanion ? "companion-index" : "single-header-base",
+            ...viaCompanion ? { crossFileVerified: true } : {}
+          } : {}
+        });
+        overridesEmitted++;
+        if (external) overridesEmittedExternal++;
+        hit = true;
+      }
+      if (!hit) overridesUnresolved++;
+    }
+    const memberClosure = (owner, seen = /* @__PURE__ */ new Set()) => {
+      const out = /* @__PURE__ */ new Set();
+      if (seen.has(owner)) return out;
+      seen.add(owner);
+      for (const m of membersByType.get(owner) ?? []) out.add(m);
+      for (const b of basesByContract.get(owner) ?? []) {
+        for (const m of memberClosure(b, seen)) out.add(m);
+      }
+      return out;
+    };
+    const closures = /* @__PURE__ */ new Map();
+    for (const owner of membersByType.keys()) closures.set(owner, memberClosure(owner));
+    const callKinds = {
+      conversion: 0,
+      namespaceBuiltin: 0,
+      modifierInvocation: 0,
+      baseConstructorCall: 0,
+      localFunction: 0,
+      inheritedMember: 0,
+      inFileTypeMember: 0,
+      crossFileInheritedMember: 0,
+      projectMemberCandidate: 0,
+      eventEmission: 0,
+      errorRevert: 0,
+      structConstructor: 0,
+      external: 0,
+      localBinding: 0,
+      receiverTypedMember: 0,
+      inheritedMemberQualified: 0,
+      libraryStaticCall: 0
+    };
+    const projectAllMembers = /* @__PURE__ */ new Map();
+    const projectMemberOwners = /* @__PURE__ */ new Map();
+    const projectMemberDeclarer = /* @__PURE__ */ new Map();
+    const projectMemberDeclarers = /* @__PURE__ */ new Map();
+    if (projectIndex) {
+      const { memberOwners, allMembers, memberDeclarer, memberDeclarers } = buildResolutionTables(projectIndex);
+      for (const [t, ms] of allMembers) projectAllMembers.set(t, ms);
+      for (const [m, ts] of memberOwners) projectMemberOwners.set(m, ts);
+      for (const [t, byName] of memberDeclarer) projectMemberDeclarer.set(t, byName);
+      for (const [m, n] of memberDeclarers) projectMemberDeclarers.set(m, n);
+    }
+    for (const rel of relationships) {
+      if (rel.type !== ASTEngine.RelationshipType.Calls) continue;
+      const md = rel.metadata;
+      let target = rel.target ?? "";
+      const owner = typeof md.calleeOwner === "string" ? md.calleeOwner : "";
+      const ownDirect = new Set(membersByType.get(owner) ?? []);
+      const ownInherited = /* @__PURE__ */ new Set();
+      for (const b of basesByContract.get(owner) ?? []) {
+        for (const m of memberClosure(b)) ownInherited.add(m);
+      }
+      let kind = (() => {
+        if (md.localBinding === true) return "localBinding";
+        if (md.isEventEmission === true) return "eventEmission";
+        if (md.isCustomErrorRevert === true) return "errorRevert";
+        if (md.isStructConstructor === true) return "structConstructor";
+        if (md.isBaseConstructorCall === true) return "baseConstructorCall";
+        if (isPrimitiveTypeToken(target)) return "conversion";
+        const obj = typeof md.calleeObject === "string" ? md.calleeObject : "";
+        if (obj === "abi" || obj === "type" || obj === "super" || obj === "this") return "namespaceBuiltin";
+        if (modifierNamesInFile.has(target)) return "modifierInvocation";
+        if (ownDirect.has(target)) return "localFunction";
+        if (ownInherited.has(target)) return "inheritedMember";
+        if (obj !== "") {
+          for (const [otherOwner, set] of membersByType) {
+            if (otherOwner === owner) continue;
+            if (set.has(target)) return "inFileTypeMember";
+          }
+        }
+        if (projectIndex) {
+          const closed = projectAllMembers.get(owner);
+          if (closed?.has(target)) return "crossFileInheritedMember";
+          const owners = projectMemberOwners.get(target);
+          if (owners) return "projectMemberCandidate";
+        }
+        return "external";
+      })();
+      md.calleeKind = kind;
+      if (kind === "external" && target !== "" && rel.metadata.externalTarget !== true) {
+        md.externalTarget = true;
+        md.externalVia = "call";
+      }
+      const namespaceObject = typeof md.calleeObject === "string" ? md.calleeObject : "";
+      if (kind === "namespaceBuiltin" && (namespaceObject === "abi" || namespaceObject === "type") && target !== "" && !target.includes(".")) {
+        rel.target = `${namespaceObject}.${target}`;
+        target = rel.target;
+        md.languageNamespace = [namespaceObject];
+      }
+      if (projectIndex && typeof md.calleeObject === "string" && md.isMemberCall === true && target !== "" && !target.includes(".")) {
+        const objectName = md.calleeObject;
+        if (objectName !== "" && !declaredVariableTypes.has(objectName) && (projectIndex.symbolCounts.get(objectName) ?? 0) === 1) {
+          const declarer = projectMemberDeclarer.get(objectName)?.get(target);
+          if (declarer !== void 0 && declarer !== null) {
+            rel.target = `${declarer}.${target}`;
+            target = rel.target;
+            md.ownerType = declarer;
+            md.calleeKind = "libraryStaticCall";
+            kind = "libraryStaticCall";
+          }
+        }
+      }
+      const calleeObject = typeof md.calleeObject === "string" ? md.calleeObject : "";
+      const receiverName = calleeObject !== "" ? calleeObject : typeof md.calleeObjectBase === "string" ? md.calleeObjectBase : "";
+      const conversionReceiver = typeof md.calleeObjectConversion === "string" ? md.calleeObjectConversion : "";
+      if (projectIndex && (receiverName !== "" || conversionReceiver !== "") && target !== "" && !target.includes(".")) {
+        const types = declaredVariableTypes.get(receiverName);
+        const element = containerElementTypes.get(receiverName);
+        const receiverType = types !== void 0 && types.size !== 1 ? void 0 : element ?? (types !== void 0 ? [...types][0] : void 0);
+        const isContainer = conversionReceiver !== "" || element !== void 0;
+        const effectiveReceiverType = conversionReceiver !== "" ? conversionReceiver : receiverType;
+        const mayNameOneDeclaration = isContainer ? (projectIndex.symbolCounts.get(effectiveReceiverType ?? "") ?? 0) === 1 : (projectMemberDeclarers.get(target) ?? 0) > 1;
+        if (effectiveReceiverType !== void 0 && mayNameOneDeclaration) {
+          const declarer = projectMemberDeclarer.get(effectiveReceiverType)?.get(target);
+          if (declarer !== void 0 && declarer !== null) {
+            rel.target = `${declarer}.${target}`;
+            target = rel.target;
+            md.receiverType = effectiveReceiverType;
+            md.ownerType = declarer;
+            md.calleeKind = "receiverTypedMember";
+            kind = "receiverTypedMember";
+          }
+        }
+      }
+      if (projectIndex && (kind === "crossFileInheritedMember" || kind === "inheritedMember") && owner !== "" && target !== "" && !target.includes(".")) {
+        if ((projectMemberDeclarers.get(target) ?? 0) > 1) {
+          const declarer = projectMemberDeclarer.get(owner)?.get(target);
+          if (declarer !== void 0 && declarer !== null && declarer !== owner) {
+            rel.target = `${declarer}.${target}`;
+            target = rel.target;
+            md.ownerType = declarer;
+            md.calleeKind = "inheritedMemberQualified";
+            kind = "inheritedMemberQualified";
+          }
+        }
+      }
+      callKinds[kind] = (callKinds[kind] ?? 0) + 1;
+    }
+    if (projectIndex) {
+      for (const rel of relationships) {
+        if (rel.type !== ASTEngine.RelationshipType.Uses) continue;
+        const md = rel.metadata;
+        if (md.isMemberReference !== true) continue;
+        const viaObject = typeof md.viaObject === "string" ? md.viaObject : "";
+        const receiverName = viaObject !== "" ? viaObject : typeof md.viaObjectBase === "string" ? md.viaObjectBase : "";
+        if (receiverName === "") continue;
+        const target = rel.target ?? "";
+        if (target === "" || target.includes(".")) continue;
+        const types = declaredVariableTypes.get(receiverName);
+        const element = types === void 0 ? containerElementTypes.get(receiverName) : void 0;
+        const receiverType = types !== void 0 && types.size === 1 ? [...types][0] : element;
+        if (receiverType === void 0) continue;
+        const declarer = projectMemberDeclarer.get(receiverType)?.get(target);
+        if (declarer === void 0 || declarer === null) continue;
+        rel.target = `${declarer}.${target}`;
+        md.receiverType = receiverType;
+        md.ownerType = declarer;
+      }
+    }
+    if (projectIndex) {
+      for (const rel of relationships) {
+        if (rel.type !== ASTEngine.RelationshipType.Decorates) continue;
+        const md = rel.metadata;
+        if (typeof md.decoratesOwner !== "string" || md.decoratesOwner === "") continue;
+        const target = rel.target ?? "";
+        if (target === "" || target.includes(".")) continue;
+        if ((projectMemberDeclarers.get(target) ?? 0) <= 1) continue;
+        const owner = md.decoratesOwner;
+        const declarer = projectMemberDeclarer.get(owner)?.get(target);
+        if (declarer === void 0 || declarer === null || declarer === owner) continue;
+        if ((projectIndex.symbolCounts.get(declarer) ?? 0) !== 1) continue;
+        rel.target = `${declarer}.${target}`;
+        md.ownerType = declarer;
+        md.modifierResolution = "inherited-member";
+      }
+    }
+    const exportedNames = /* @__PURE__ */ new Set();
+    for (const { name, line } of topLevelExports) {
+      if (exportedNames.has(name)) continue;
+      exportedNames.add(name);
+      addRel(
+        fileName,
+        name,
+        ASTEngine.RelationshipType.Exports,
+        1,
+        line,
+        { isCompilationUnitSurface: true }
+      );
+      exports.push({
+        name,
+        range: this.lineRange(line),
+        metadata: { soliditySpecific: true, isFileScopeDeclaration: true }
+      });
+    }
+    {
+      const seenImportPath = /* @__PURE__ */ new Set();
+      for (const e of importEdges) {
+        if (!e.path || seenImportPath.has(e.path)) continue;
+        seenImportPath.add(e.path);
+        const claim = typeof context?.projectRoot === "string" && context.projectRoot.length > 0 ? fileClaimForTarget({
+          projectRoot: context.projectRoot,
+          filePath,
+          admittedExtensions: ["sol"],
+          written: e.path
+        }) : null;
+        addRel(fileName, e.path, ASTEngine.RelationshipType.Imports, 1, e.line, {
+          import: true,
+          importPath: e.path,
+          ...claim !== null ? { importProjectFile: claim } : {},
+          // SOL-28 — AND WHEN THE PATH IS NOT A PROJECT FILE, THE SOURCE-PATH CLAIM IS THE TRUE ONE:
+          // nothing the project ADMITS resolves to this written path (`forge-std/Test.sol`,
+          // `@openzeppelin/contracts/utils/math/Math.sol`). Its polarity is the inverse of the file
+          // claim's and the project's own admitted list is the whole evidence.
+          ...claim === null ? { sourcePathClaim: [e.path] } : {},
+          ...e.isNamespace ? { isNamespaceImport: true } : {}
+        }, { pathTarget: true });
+      }
+    }
+    for (const e of importEdges) {
+      if (e.name === "*") {
+        addRel(fileName, e.path, ASTEngine.RelationshipType.References, 1, e.line, {
+          import: true,
+          isNamespaceImport: true
+        });
+        continue;
+      }
+      addRel(fileName, e.name, ASTEngine.RelationshipType.References, 1, e.line, {
+        import: true,
+        importPath: e.path,
+        // A namespace import IS a namespace import, and the ALIASED form
+        // (`import * as Utils from …`) was not labelled as one — only the bare form
+        // carried the marker. So nothing in the output said which edges came from a
+        // namespace import, and the marker selected the wrong set: a filter keyed on
+        // `isNamespaceImport` removed the bare import (which the F9 gate already
+        // suppresses) and left the aliased one standing.
+        ...e.isNamespace ? { isNamespaceImport: true } : {}
+      });
+    }
+    const detectedPatterns = [...patterns];
+    const detectedFrameworks = [...frameworks];
+    if (projectIndex) {
+      for (const rel of relationships) {
+        const md = rel.metadata;
+        if (md.projectIndexSupplied === void 0) md.projectIndexSupplied = true;
+      }
+    }
+    return {
+      language: "solidity",
+      symbols,
+      relationships,
+      imports,
+      exports,
+      errors: [],
+      metadata: {
+        complexity: symbols.length + relationships.length,
+        linesOfCode: lines.length,
+        cyclomaticComplexity,
+        framework: detectedFrameworks[0],
+        patterns: detectedPatterns,
+        detectedFrameworks,
+        frameworkPatterns: detectedPatterns.map((p) => ({
+          framework: "Solidity",
+          patterns: [{ type: "usage", detected: true, description: p }]
+        })),
+        architecturalInsights: [],
+        architecturalScore: Math.min(100, 60 + relationships.length),
+        codeQuality: "Excellent",
+        hasTypeInference: false,
+        hasFrameworkIntelligence: true,
+        analysisVersion: "6.0-sol-module-owners-lines-tiers",
+        // Reported rather than hidden — see the F9 spec and the surface measure.
+        commentsRead,
+        commentsAttached,
+        documentedSymbols,
+        symbolsWithComplexity,
+        symbolsWithQualifiedCalls,
+        ...caseAudit ? { __caseHits: __hits, __caseEmits: __emits } : {},
+        inheritanceKindsResolvedProjectWide,
+        natSpecCheck: {
+          symbolsWithUndocumentedParams,
+          symbolsWithOverDocumentedParams,
+          undocumentedParams: natSpecUndocumentedParams,
+          overDocumentedParams: natSpecOverDocumentedParams,
+          returnDocumentedWithoutReturn: natSpecReturnWithoutReturn,
+          overDocumentedSamples: overDocumentedSamples.slice(0, 10),
+          returnWithoutReturnSamples: returnWithoutReturnSamples.slice(0, 10),
+          _note: "SOL-23. Documentation checked against the signature, both halves in the same tree. `undocumentedParameters` is usually benign \u2014 plenty of code documents only the interesting parameters. The other two are real errors in the source: a `@param` naming a parameter the function does not have, and a `@return` on a function that returns nothing. Reported as counts and samples, never as relationships: there is no second symbol and no second file for an edge to connect, and an edge to a parameter that may not exist would put a target in the graph no project declares."
+        },
+        callKinds,
+        overridesEmitted,
+        overridesEmittedExternal,
+        overridesUnresolved,
+        overridesAmbiguousBaseCount,
+        engineCallsSuppressed,
+        getterSymbols,
+        storeRefusedDeclarations,
+        storeRefusedNames: [...storeRefusedNames].sort(),
+        symbolsSuppressedOnRecoveryLines,
+        // The SET, not just the count, and for a testable reason: SOL-6's mutant
+        // has to reinstate what the narrower rule would have emitted, and a revert
+        // written from a count alone cannot be written generically — it would have
+        // to hard-code the fixture's line, which measures the fixture rather than
+        // the behaviour. The list is also the same fact at a resolution a reader
+        // wants: which lines of this file the parser could not handle.
+        recoveryLinesList: [...recoveryLines].sort((a, b) => a - b),
+        implementsCrossFileUnresolved: extendsUnresolvedAsInterface
+        // Not `Partial<FileMetadata>`: the declared return type is
+        // `FileMetadata & Partial<FileMetadata>`, and casting to the Partial half made
+        // `complexity` optional even though it is set two lines into this literal, which
+        // is what the assignment rejected. `FileMetadata` also carries
+        // `[key: string]: any`, so the Solidity-specific keys above need no exemption.
+      }
+    };
+  }
+  // ---------------------------------------------------------------- helpers
+  /** SOL-1 — the file's own basename, extension included. */
+  basenameOf(filePath) {
+    const normalized = filePath.split("\\").join("/");
+    const base = normalized.slice(normalized.lastIndexOf("/") + 1);
+    return base.length > 0 ? base : "contract.sol";
+  }
+  lineRange(line) {
+    return {
+      startLine: line,
+      startColumn: 1,
+      endLine: line,
+      endColumn: 1,
+      startIndex: 0,
+      endIndex: 0
+    };
+  }
+  nodeToRange(node) {
+    return {
+      startLine: node.startPosition.row + 1,
+      startColumn: node.startPosition.column + 1,
+      endLine: node.endPosition.row + 1,
+      endColumn: node.endPosition.column + 1,
+      startIndex: node.startIndex,
+      endIndex: node.endIndex
+    };
+  }
+};
+export {
+  RealSolidityAnalyzer
+};