@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/real-lua-analyzer-G7NHLYKS.js

@@ -0,0 +1,1957 @@
+import {
+  FILE_CLAIM_MAX_BYTES,
+  dirOf,
+  fileClaimForTarget,
+  foldProjectPath
+} from "./chunk-EWMWK7WN.js";
+import {
+  ASTEngine
+} from "./chunk-3ZTOHHSW.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-MLKGABMK.js";
+
+// src/ast/real-lua-analyzer.ts
+import * as path from "path";
+var LUA54_TABLES = /* @__PURE__ */ new Set([
+  "string",
+  "table",
+  "math",
+  "io",
+  "os",
+  "coroutine",
+  "debug",
+  "utf8"
+]);
+var LUA54_GLOBALS = /* @__PURE__ */ new Set([
+  "assert",
+  "collectgarbage",
+  "dofile",
+  "error",
+  "getmetatable",
+  "ipairs",
+  "load",
+  "loadfile",
+  "next",
+  "pairs",
+  "pcall",
+  "print",
+  "rawequal",
+  "rawget",
+  "rawlen",
+  "rawset",
+  "require",
+  "select",
+  "setmetatable",
+  "tonumber",
+  "tostring",
+  "type",
+  "warn",
+  "xpcall",
+  "_G",
+  "_VERSION"
+]);
+function luaModuleBases(fileRel) {
+  const dir = dirOf(fileRel);
+  const segs = fileRel.split("/");
+  const all = [{ label: "root", base: "" }, { label: "fileDir", base: dir }];
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (segs[i] === "lua") {
+      all.push({ label: "luaRoot", base: segs.slice(0, i + 1).join("/") + "/" });
+      break;
+    }
+  }
+  all.push({ label: "fileDir+lua", base: dir + "lua/" });
+  const seen = /* @__PURE__ */ new Set();
+  return all.filter((b) => {
+    if (seen.has(b.base)) return false;
+    seen.add(b.base);
+    return true;
+  });
+}
+function luaModuleFileCandidates(moduleName, fileRel) {
+  const stem = moduleName.trim().split(".").join("/");
+  if (stem.length === 0) return [];
+  const out = [];
+  for (const { base } of luaModuleBases(fileRel)) {
+    for (const suffix of [".lua", "/init.lua"]) {
+      const folded = foldProjectPath(base, stem + suffix);
+      if (folded !== null && !out.includes(folded)) out.push(folded);
+    }
+  }
+  return out;
+}
+var RealLuaAnalyzer = class {
+  analyze(rootNode, content, filePath, context) {
+    const projectRootRaw = String(context?.projectRoot ?? "");
+    const filePathRaw = String(filePath ?? "");
+    const rooted = projectRootRaw.length > 0 && filePathRaw.length > 0 && path.isAbsolute(projectRootRaw) && path.isAbsolute(filePathRaw);
+    const ctx = {
+      symbols: [],
+      relationships: [],
+      imports: [],
+      exports: [],
+      errors: [],
+      globalVariables: /* @__PURE__ */ new Set(),
+      declaredTables: /* @__PURE__ */ new Set(),
+      unpublishedSurface: [],
+      frameworks: /* @__PURE__ */ new Set(),
+      patterns: /* @__PURE__ */ new Set(),
+      seenRelationships: /* @__PURE__ */ new Set(),
+      coroutineCalls: 0,
+      declarationsByLabel: /* @__PURE__ */ new Map(),
+      membersByOwner: /* @__PURE__ */ new Map(),
+      supertypeLinks: /* @__PURE__ */ new Map(),
+      factorySupertypeLines: /* @__PURE__ */ new Map(),
+      declaredFunctions: /* @__PURE__ */ new Set(),
+      wrapperFactories: /* @__PURE__ */ new Set(),
+      stdlibCandidates: [],
+      stdlibGlobalCandidates: [],
+      ...rooted ? { projectRoot: projectRootRaw, filePath: filePathRaw } : {},
+      moduleFileClaims: /* @__PURE__ */ new Map()
+    };
+    this.collectErrors(rootNode, ctx);
+    this.collectDeclaredTables(rootNode, ctx);
+    this.collectSupertypeLinks(rootNode, ctx);
+    this.collectFactorySupertypeLinks(rootNode, ctx);
+    this.collectDecoratorFacts(rootNode, ctx);
+    const rootFrame = { localNames: /* @__PURE__ */ new Set(), inFunction: false };
+    const stack = [{ node: rootNode, frame: rootFrame }];
+    while (stack.length > 0) {
+      const entry = stack.pop();
+      const node = entry.node;
+      const frame = entry.frame;
+      if (node.isMissing) continue;
+      this.processNode(node, frame, ctx);
+      let childFrame = frame;
+      if (node.type === "function_declaration" || node.type === "function_definition") {
+        const functionName = node.type === "function_declaration" ? this.functionName(node) : void 0;
+        const locals = new Set(frame.localNames);
+        for (const parameter of this.extractParameters(node)) locals.add(parameter.name);
+        if (functionName || node.type === "function_definition") {
+          const nameNode = node.childForFieldName("name");
+          const bareOwner = (nameNode ? this.functionOwner(nameNode) : void 0) ?? functionName ?? frame.owner ?? frame.callable;
+          const selfName = (nameNode ? this.splitMemberName(nameNode, functionName ?? "").name : functionName) || frame.selfName;
+          childFrame = {
+            callable: functionName ?? frame.callable,
+            owner: bareOwner,
+            selfName,
+            localNames: locals,
+            inFunction: true
+          };
+        }
+      }
+      for (let i = node.namedChildCount - 1; i >= 0; i--) {
+        const child = node.namedChild(i);
+        if (child) stack.push({ node: child, frame: childFrame });
+      }
+    }
+    this.addContainsRelationships(ctx);
+    this.addFactorySupertypeEdges(ctx);
+    this.addOverrideRelationships(ctx);
+    this.markStdlibExternal(ctx);
+    const detectedFrameworks = [...ctx.frameworks];
+    const detectedPatterns = [...ctx.patterns];
+    return {
+      language: "lua",
+      symbols: ctx.symbols,
+      relationships: ctx.relationships,
+      imports: ctx.imports,
+      exports: ctx.exports,
+      errors: ctx.errors,
+      metadata: {
+        // M60 LUA-35. Present ONLY when there is something to say, and every field
+        // is derived from the parse: `shape` from the node type, `detail` from the
+        // node's own text, `line` from its start position, `why` a fixed reason per
+        // shape. Nothing here is a constant shaped like a measurement, which is the
+        // LUA-11 rule — a count or score that did not vary with the file would be
+        // worse than an absent field, and this is a list that is empty whenever the
+        // module's surface is nameable.
+        ...ctx.unpublishedSurface.length ? { unpublishedSurface: ctx.unpublishedSurface } : {},
+        complexity: ctx.symbols.length + ctx.relationships.length,
+        linesOfCode: this.lineCount(content),
+        cyclomaticComplexity: this.calculateCyclomaticComplexity(rootNode),
+        framework: detectedFrameworks[0],
+        patterns: detectedPatterns,
+        detectedFrameworks,
+        frameworkPatterns: detectedFrameworks.map((framework) => ({
+          framework,
+          patterns: [{ type: "usage", detected: true, description: `${framework} usage detected` }]
+        })),
+        architecturalInsights: this.generateArchitecturalInsights(ctx),
+        architecturalScore: this.calculateArchitecturalScore(ctx),
+        codeQuality: this.assessCodeQuality(ctx),
+        hasTypeInference: false,
+        // M60 LUA-11: performanceScore and memoryEfficiency were the literals
+        // 85 and 85 — the two most checkable-looking numbers in this block and
+        // the two that were invented. They are gone under those NAMES as well as
+        // those values, because a derived number published as "performanceScore"
+        // is still a lie: it claims to measure performance, and this analyzer
+        // measures no time at all. What replaces them is named for what it is —
+        // relationshipDensity and retainedRowKb — and each is either derived
+        // from the analysed file or ABSENT.
+        relationshipDensity: this.relationshipDensity(ctx),
+        retainedRowKb: this.retainedRowKb(ctx),
+        // M60 LUA-02: counted from the CALLS the walk actually saw, not from a
+        // symbol flag nothing ever set — which made this a structural zero.
+        coroutineUsage: this.countCoroutineSymbols(ctx),
+        analysisVersion: "4.0.0-lua-m12.32"
+      }
+    };
+  }
+  processNode(node, frame, ctx) {
+    switch (node.type) {
+      case "function_declaration":
+        this.extractFunction(node, frame, ctx, this.isLocalFunction(node));
+        break;
+      case "variable_declaration":
+        if (this.isLocalVariableDeclaration(node)) this.extractLocalDeclaration(node, frame, ctx);
+        this.extractDecoratorApplication(node, frame, ctx);
+        break;
+      case "assignment_statement":
+        this.extractAssignment(node, frame, ctx);
+        this.extractDecoratorApplication(node, frame, ctx);
+        break;
+      case "function_call":
+        this.processCall(node, frame, ctx);
+        break;
+      case "return_statement":
+        this.extractExport(node, frame, ctx);
+        break;
+      case "for_statement":
+        this.registerLoopBindings(node, frame);
+        break;
+      case "identifier":
+        this.detectFrameworks(node.text, ctx);
+        this.emitNameRead(node, frame, ctx);
+        break;
+      case "dot_index_expression":
+      case "method_index_expression":
+      case "bracket_index_expression":
+        this.emitMemberRead(node, frame, ctx);
+        break;
+    }
+  }
+  /**
+   * M60 LUA-40 — `uses`: a name this scope READS.
+   *
+   * Measured before it was written (script/m60/lua-ontology-census.ts, probe
+   * B4-bare-name-read): 295,019 bare-name reads across 3,250 corpus files. The
+   * type was absent, so the largest read surface the language has was invisible.
+   *
+   * The rule is a ROLE, read off the parent node, never a text shape. Each
+   * exclusion is a different relationship that is already published or is not a
+   * declaration at all:
+   *
+   *   callee of a function_call      -> that is `calls`, published by processCall
+   *   a `variable_list` child        -> a DECLARATION, published as a symbol and
+   *                                     as `contains`
+   *   the LHS of an assignment       -> a WRITE, not a read
+   *   a `field`'s key                 -> a table-literal KEY, a declaration site
+   *   a `function_declaration` name  -> a member DECLARATION
+   *   the RECEIVER of an index expr  -> part of a qualified name; that read is
+   *                                     `references` (LUA-41), and publishing both
+   *                                     would double-count one fact under two labels
+   *   a `parameters` child           -> a parameter BINDING, not a use of it
+   *
+   * Confidence is 0.9, not 1.0, and the reason is not a hedge: the node proves
+   * the file READS A NAME. Which binding that name denotes — a local, an
+   * upvalue, a global, a stdlib function, a field of a required module — is not
+   * written anywhere in the tree. The machine-readable reason code the honesty
+   * contract §4 requires for anything under 1.0 is `evidenceClass:
+   * "usage_contextual"`, which is this codebase's existing word for a link
+   * established by a NAME in a value position (real-css-analyzer.ts:737).
+   */
+  /**
+   * M60 LUA-45: node identity, the only way that works on this runtime.
+   *
+   * `web-tree-sitter` returns a FRESH wrapper object on every access, so
+   * `parent.namedChild(0) === node` is false even when both name the same span —
+   * measured on validation/m14/fixtures/lua/name-reads.lua, where the receiver
+   * test silently never fired and published 3 edges it exists to suppress:
+   * `apply -> config` at L22, `apply -> helper` at L24 and `never -> helper` at
+   * L29. Every one of them states a qualified access twice under two labels.
+   *
+   * The identity that IS stable is the SPAN, which is what this compares. It is
+   * the family's own idiom and not a local invention: real-c-analyzer.ts:2336,
+   * :2525 and :6012 all compare `startIndex`/`endIndex` for exactly this reason.
+   * `type` is compared too because a span can be covered by more than one node
+   * type in a grammar that reuses a token, and a wrong-type match here would
+   * suppress a real edge.
+   */
+  isSameNode(a, b) {
+    if (!a || !b) return false;
+    return a.type === b.type && a.startIndex === b.startIndex && a.endIndex === b.endIndex;
+  }
+  emitNameRead(node, frame, ctx) {
+    const parent = node.parent;
+    if (!parent) return;
+    const pt = parent.type;
+    if (pt === "function_call") {
+      if (this.isSameNode(parent.childForFieldName("name"), node) || this.isSameNode(parent.namedChild(0), node)) return;
+    } else if (pt === "variable_list" || pt === "parameters") {
+      return;
+    } else if (pt === "assignment_statement") {
+      if (this.isSameNode(parent.namedChild(0), node)) return;
+    } else if (pt === "field") {
+      if (this.isSameNode(parent.childForFieldName("name"), node)) return;
+    } else if (pt === "function_declaration") {
+      if (this.isSameNode(parent.childForFieldName("name"), node)) return;
+    } else if (pt === "dot_index_expression" || pt === "method_index_expression") {
+      if (this.isSameNode(parent.namedChild(0), node)) return;
+      if (this.isSameNode(parent.namedChild(parent.namedChildCount - 1), node)) return;
+    } else if (pt === "bracket_index_expression") {
+      if (this.isSameNode(parent.namedChild(0), node)) return;
+    }
+    this.addRelationship(
+      ctx,
+      frame.callable || "global",
+      node.text,
+      ASTEngine.RelationshipType.Uses,
+      { luaSpecific: true, relationshipType: "lua_name_read" },
+      node,
+      { confidence: 0.9 }
+    );
+  }
+  /**
+   * M60 LUA-41 — `references`: a MEMBER of a table read without calling it.
+   *
+   * Measured first, the same way: probe B3-member-read counted 198,720 qualified
+   * reads across 2,643 files. A qualified read is the shape the family's
+   * `references` is for and the shape this lane was missing: css's `var(--x)`
+   * asserts a dependency on a NAME that may be declared in another file, and
+   * `M.field` asserts exactly that — `M` is written, `field` is written, and
+   * which module owns `field` is not written anywhere.
+   *
+   * The same four exclusions as `calls`/`contains` already rely on, each for the
+   * same reason: a member's CALLEE is a `calls` edge (processCall), a member's
+   * DECLARATION is a symbol plus a `contains` edge, a member ASSIGNED TO is a
+   * write, and a `field`'s key is a table-literal key.
+   *
+   * A COMPUTED index (`dao[method or context .. "_by_" .. endpoint_key]`) has no
+   * name, and LUA-22's payload lesson applies unchanged: a literal STRING index
+   * does (`dao["rows"]`, read as `rows`), a number and a variable-held key do not.
+   *
+   * The TARGET is the member's own field name, which is what every other lua edge
+   * uses for a member (LUA-13/LUA-15: `obj:method()` yields target `method`), and
+   * the RECEIVER is recorded in metadata so a consumer that needs the qualified
+   * path has it without this edge having to claim an identity it cannot prove.
+   * The cost of that choice is measured and declared: two tables in one file can
+   * both have a member `run`, and the bare name fuses them. The qualified path is
+   * recorded per edge, so the ambiguity is recoverable rather than lost.
+   */
+  emitMemberRead(node, frame, ctx) {
+    const parent = node.parent;
+    if (parent) {
+      const pt = parent.type;
+      if (pt === "function_call" && (this.isSameNode(parent.childForFieldName("name"), node) || this.isSameNode(parent.namedChild(0), node))) return;
+      if (pt === "function_declaration" && this.isSameNode(parent.childForFieldName("name"), node)) return;
+      if (pt === "field" && this.isSameNode(parent.childForFieldName("name"), node)) return;
+      if (pt === "variable_list") return;
+    }
+    let member;
+    let memberNode;
+    if (node.type === "bracket_index_expression") {
+      const key = node.childForFieldName("field");
+      if (key?.type !== "string") return;
+      member = this.stringValue(key);
+      memberNode = key;
+    } else {
+      const last = node.namedChildCount > 0 ? node.namedChild(node.namedChildCount - 1) : void 0;
+      if (last?.type !== "identifier") return;
+      member = last.text;
+      memberNode = last;
+    }
+    if (!member || !memberNode) return;
+    const receiver = this.nameBearing(node.childForFieldName("table"));
+    this.addRelationship(
+      ctx,
+      frame.callable || "global",
+      member,
+      ASTEngine.RelationshipType.References,
+      {
+        luaSpecific: true,
+        relationshipType: "lua_member_read",
+        ...receiver ? { receiver } : {}
+      },
+      memberNode,
+      { confidence: 0.9 }
+    );
+  }
+  extractFunction(node, frame, ctx, isLocal) {
+    const nameNode = node.childForFieldName("name") || node.namedChild(0);
+    if (!nameNode) return;
+    const label = nameNode.text;
+    if (!label) return;
+    const { name, owner } = this.splitMemberName(nameNode, label);
+    const parameters = this.extractParameters(node);
+    const isMethod = !!owner;
+    const lexicallyLocal = isLocal || !!frame.callable;
+    const symbol = {
+      name,
+      kind: isMethod ? ASTEngine.SymbolKind.Method : ASTEngine.SymbolKind.Function,
+      range: this.nodeToRange(node),
+      scope: lexicallyLocal ? frame.callable || "global" : "global",
+      visibility: lexicallyLocal ? "private" : "public",
+      parameters,
+      ownerName: owner,
+      ownerKind: owner ? ASTEngine.SymbolKind.Class : void 0,
+      // M60 LUA-37: the enclosing body's own symbol name, so a declaration nested
+      // in this one can be contained BY IT rather than by its label. See
+      // addContainsRelationships, which reads this and never reads `scope`.
+      frameSelfName: frame.selfName,
+      // qualifiedName keeps the full path, which is what it is FOR. The `name`
+      // field is the identity; this is the path. Before the fix the path was
+      // doing the identity's job and no path was recorded at all.
+      qualifiedName: label,
+      metadata: { luaSpecific: true, isLocal: lexicallyLocal, isMethod, ownerTable: owner, qualifiedName: label }
+    };
+    ctx.symbols.push(symbol);
+    if (owner) {
+      ctx.declaredTables.add(owner);
+      ctx.patterns.add("Object-Oriented Programming");
+      const members = ctx.membersByOwner.get(owner) ?? /* @__PURE__ */ new Map();
+      if (!members.has(name)) members.set(name, node.startPosition.row + 1);
+      ctx.membersByOwner.set(owner, members);
+    }
+    const byLabel = ctx.declarationsByLabel.get(label) ?? [];
+    byLabel.push({ line: node.startPosition.row + 1, owner: owner ?? null, member: owner ? name : null });
+    ctx.declarationsByLabel.set(label, byLabel);
+    if (lexicallyLocal) ctx.globalVariables.delete(name);
+  }
+  // M60 LUA-15: split a declaration's name into its OWN name and its OWNER.
+  //
+  // In this grammar `function Buffer:initialize()` and `function
+  // Buffer.readUInt8()` both put an index expression in the `name` field, with
+  // the RECEIVER first and the FIELD last:
+  //   method_index_expression
+  //     table: (identifier "Buffer")
+  //     :     (identifier "initialize")
+  // so the field is the LAST named child and the receiver the first. Taking the
+  // first yields "Buffer" — the table, not the method.
+  splitMemberName(nameNode, label) {
+    if (nameNode.type !== "dot_index_expression" && nameNode.type !== "method_index_expression") {
+      return { name: label };
+    }
+    const first = nameNode.namedChild(0);
+    const last = nameNode.namedChildCount > 1 ? nameNode.namedChild(nameNode.namedChildCount - 1) : void 0;
+    const owner = first?.type === "identifier" ? first.text : void 0;
+    return { name: last?.text || label, owner };
+  }
+  extractLocalDeclaration(node, frame, ctx) {
+    const first = node.type === "variable_declaration" ? node.namedChild(0) : node;
+    const assignment = first?.type === "assignment_statement" ? first : void 0;
+    const variableList = assignment ? this.childOfType(assignment, "variable_list") : first?.type === "variable_list" ? first : void 0;
+    if (!variableList) return;
+    for (let i = 0; i < variableList.namedChildCount; i++) {
+      const variable = variableList.namedChild(i);
+      const name = this.plainVariableName(variable);
+      if (!variable || !name) continue;
+      frame.localNames.add(name);
+      const value = assignment ? this.assignmentValue(assignment) : void 0;
+      const isTable = this.isTableNode(value);
+      if (isTable) ctx.declaredTables.add(name);
+      ctx.symbols.push({
+        name,
+        kind: ASTEngine.SymbolKind.Variable,
+        range: this.nodeToRange(variable),
+        scope: frame.callable || "global",
+        // M60 LUA-37: a declaration inside a body is contained by the FUNCTION whose
+        // body it is, so the owner is that function's own name (`selfName`), not the
+        // function's own owner. `function fs.appendFile()` has owner "fs" and self
+        // "appendFile", and a local inside it must read `appendFile -> localName`:
+        // "fs" is the owner of the METHOD, and using it filed the local as a sibling
+        // of the method rather than a member of it, which cost 525 unexplained
+        // contains edges on an 83-file kong slice.
+        ownerName: frame.selfName ?? frame.owner ?? frame.callable,
+        frameSelfName: frame.selfName,
+        ownerKind: frame.callable ? ASTEngine.SymbolKind.Function : void 0,
+        visibility: frame.callable ? "private" : "public",
+        metadata: { luaSpecific: true, isLocal: true, isTable, tableFields: isTable ? this.tableFieldNames(value) : [] }
+      });
+    }
+  }
+  /**
+   * M60 LUA-49: a for-clause BINDS a name, and the frame never heard of it.
+   *
+   * `extractAssignment` suppresses a local re-assignment with
+   * `frame.localNames.has(name)` — the one line standing between a re-assignment and
+   * a fabricated declaration. `localNames` was filled from exactly one place,
+   * `variable_declaration` (real-lua-analyzer.ts:649), so every OTHER binding form in
+   * the language fell through it. A generic-for clause is the common one:
+   *
+   *     for _, line in ipairs(lines) do
+   *       line = line:match("(.-)%%") or line     <- a re-assignment
+   *     end
+   *
+   * `line` is bound by the clause, so the statement above re-assigns a local and
+   * declares nothing. The analyzer had no record of the binding, published a
+   * `variable` SYMBOL for it, and `addContainsRelationships` then published
+   * `contains get_packages -> line` — a containment edge for a declaration that never
+   * happened, sitting on the assignment's line rather than the clause's.
+   *
+   * Found by the ORACLE rather than by reading: `lua-truth-oracle.ts` records
+   * for-clause names in `localsIn` (for its own LUA-26 exemption), so it correctly
+   * declined to derive the re-assignment, and the two disagreed. Four unexplained
+   * `contains` edges over ~600 corpus files, every one this shape:
+   * `contains get_packages -> line` (snacks.nvim/lua/snacks/image/doc.lua:131),
+   * `contains json -> item` (snacks.nvim/lua/snacks/picker/source/proc.lua:172),
+   * and one each in kong and luarocks.
+   *
+   * WHAT THIS DOES NOT DO, stated because the omission is the other half of the
+   * defect: the loop BINDING itself is still not published as a declaration. Lua
+   * binds `line` there, and neither a symbol nor a `contains` edge says so — the
+   * edge that used to appear was on the wrong line and for the wrong reason.
+   * Publishing the binding is the larger change and it is not made here: `for k, v in
+   * pairs(t)` is one of the most frequent constructs in Lua, so it is a symbol-count
+   * and payload decision for the whole graph surface, not a lane-local fix. Reported
+   * rather than done (§8 of the workstream, and limitation 14 of the doc).
+   *
+   * Scope: the name is recorded WITH THE LOOP'S END OFFSET, and the re-assignment
+   * test asks whether that loop is still lexically open at the assignment. That is
+   * not a refinement, it is the whole correctness of the rule: Lua scopes a loop
+   * variable to the loop body, so
+   *
+   *     for _, v in ipairs(t) do v = f(v) end   -- a RE-assignment
+   *     v = 5                                    -- a DIFFERENT binding
+   *
+   * are different facts. Recording the name in `localNames` unconditionally, which is
+   * what the first version of this fix did, got the first line right and the second
+   * one wrong: it suppressed 18 real `contains` edges on kong alone. The oracle caught
+   * it as 18 MISSING, which is the oracle working — it derives the post-loop
+   * assignment because the loop really has closed.
+   *
+   * Lua has no block scope for locals — a `do ... end` does not open one — so the
+   * binding goes in the ENCLOSING FUNCTION's frame rather than a block frame, and the
+   * loop's own extent is what bounds it. At file scope `frame.callable` is undefined
+   * and `extractAssignment`'s existing `frame.callable &&` guard still lets a
+   * file-scope assignment declare a global, which is correct: after
+   * `for _, v in ...` ends at file scope, `v = 5` assigns a global.
+   */
+  registerLoopBindings(node, frame) {
+    const clause = node.namedChild(0);
+    if (!clause) return;
+    const end = node.endIndex;
+    const add = (n) => {
+      if (n?.type !== "identifier") return;
+      let list = frame.loopBindings;
+      if (!list) frame.loopBindings = list = [];
+      list.push({ name: n.text, endIndex: end });
+    };
+    if (clause.type === "for_numeric_clause") {
+      add(clause.childForFieldName("name"));
+      return;
+    }
+    if (clause.type !== "for_generic_clause") return;
+    for (let i = 0; i < clause.namedChildCount; i++) {
+      const list = clause.namedChild(i);
+      if (list?.type !== "variable_list") continue;
+      for (let j = 0; j < list.namedChildCount; j++) add(list.namedChild(j));
+    }
+  }
+  /** Is `name` bound by a for-clause whose loop is still open at byte offset `at`? */
+  inOpenLoopBinding(frame, name, at) {
+    const list = frame.loopBindings;
+    if (!list) return false;
+    for (let i = list.length - 1; i >= 0; i--) {
+      if (list[i].name === name && at < list[i].endIndex) return true;
+    }
+    return false;
+  }
+  extractAssignment(node, frame, ctx) {
+    if (node.parent?.type === "variable_declaration" && this.isLocalVariableDeclaration(node.parent)) return;
+    const variableList = this.childOfType(node, "variable_list");
+    if (!variableList) return;
+    const value = this.assignmentValue(node);
+    for (let i = 0; i < variableList.namedChildCount; i++) {
+      const variable = variableList.namedChild(i);
+      const name = this.plainVariableName(variable);
+      if (!variable || !name) continue;
+      if (frame.callable && frame.localNames.has(name) || this.inOpenLoopBinding(frame, name, node.startIndex)) continue;
+      const isTable = this.isTableNode(value);
+      if (isTable) ctx.declaredTables.add(name);
+      ctx.symbols.push({
+        name,
+        kind: ASTEngine.SymbolKind.Variable,
+        range: this.nodeToRange(variable),
+        scope: frame.callable || "global",
+        ownerName: frame.selfName ?? frame.owner ?? frame.callable,
+        frameSelfName: frame.selfName,
+        ownerKind: frame.callable ? ASTEngine.SymbolKind.Function : void 0,
+        visibility: frame.callable ? "private" : "public",
+        metadata: { luaSpecific: true, isGlobal: !frame.callable, isTable, tableFields: isTable ? this.tableFieldNames(value) : [] }
+      });
+      if (!frame.callable) ctx.globalVariables.add(name);
+    }
+  }
+  processCall(node, frame, ctx) {
+    const functionNode = node.childForFieldName("name") || node.namedChild(0);
+    if (!functionNode) return;
+    const callee = this.callee(functionNode);
+    if (!callee) return;
+    const callName = callee.name;
+    const qualified = functionNode.text;
+    this.detectFrameworks(qualified, ctx);
+    const values = this.callArguments(node);
+    const firstString = this.stringValue(values[0]);
+    if (callName === "require" || callName === "module") {
+      if (firstString) this.addImport(firstString, frame, node, ctx);
+      return;
+    }
+    if (callName === "pcall" || callName === "xpcall") {
+      if (values[0]?.text === "require") {
+        const moduleName = this.stringValue(values[1]);
+        if (moduleName) this.addImport(moduleName, frame, node, ctx);
+      }
+    }
+    const source = frame.callable || "global";
+    if (callName !== "pcall" && callName !== "xpcall") {
+      this.addRelationship(ctx, source, callName, ASTEngine.RelationshipType.Calls, { luaSpecific: true, ...callee.shapeMark }, callee.nameNode);
+    }
+    if (qualified === "coroutine.create" || qualified === "coroutine.wrap") {
+      ctx.patterns.add("Coroutines");
+      ctx.coroutineCalls++;
+    }
+    if (callName === "setmetatable") {
+      ctx.patterns.add("Object-Oriented Programming (Metatables)");
+      const target = values[0];
+      const metatable = values[1];
+      const srcName = this.nameBearing(target);
+      const mtName = this.nameBearing(metatable);
+      if (target && metatable && !this.isTableNode(target) && srcName && mtName && srcName !== mtName) {
+        this.addRelationship(ctx, srcName, mtName, ASTEngine.RelationshipType.Extends, { luaSpecific: true, relationshipType: "lua_metatable" }, metatable);
+      }
+      if (metatable?.type === "identifier") {
+        const tableName = metatable.text;
+        ctx.declaredTables.add(tableName);
+      }
+    }
+    const constructor = this.constructorTarget(functionNode, ctx);
+    if (constructor) {
+      this.addRelationship(ctx, source, constructor, ASTEngine.RelationshipType.Instantiates, { luaSpecific: true, relationshipType: "instantiates" }, callee.nameNode);
+    }
+    if (callName === "class" || qualified === "Object:extend" || qualified === "Object.extend") {
+      const className = firstString;
+      if (className) {
+        ctx.symbols.push({
+          name: className,
+          kind: ASTEngine.SymbolKind.Class,
+          range: this.nodeToRange(node),
+          scope: source,
+          ownerName: frame.selfName ?? frame.owner ?? frame.callable,
+          frameSelfName: frame.selfName,
+          metadata: { luaSpecific: true, isLibraryClass: true }
+        });
+      }
+      ctx.patterns.add("Object-Oriented Programming (Libraries)");
+    }
+  }
+  addImport(moduleName, frame, node, ctx) {
+    ctx.imports.push({
+      module: moduleName,
+      items: [],
+      isDefaultImport: true,
+      isNamespaceImport: false,
+      range: this.nodeToRange(node),
+      metadata: { luaSpecific: true }
+    });
+    const fileClaim = this.moduleFileClaim(moduleName, ctx);
+    this.addRelationship(ctx, frame.callable || "global", moduleName, ASTEngine.RelationshipType.Imports, {
+      luaSpecific: true,
+      relationshipType: "lua_require",
+      ...fileClaim !== null ? { importProjectFile: fileClaim } : {}
+    }, node);
+    if (moduleName.startsWith("resty")) ctx.frameworks.add("OpenResty");
+    if (moduleName === "socket" || moduleName === "lfs" || moduleName === "cjson" || moduleName === "ssl") ctx.frameworks.add("LuaRocks Core Modules");
+    if (moduleName === "lapis") ctx.frameworks.add("Lapis");
+    if (moduleName === "middleclass" || moduleName === "classic" || moduleName === "30log") ctx.patterns.add("Object-Oriented Programming (Libraries)");
+    if (moduleName === "hs" || moduleName.startsWith("hs.")) ctx.frameworks.add("Hammerspoon");
+    if (moduleName.startsWith("lovr")) ctx.frameworks.add("L\xD6VR (VR/AR)");
+  }
+  /**
+   * THE FILE CLAIM for one module name, or null when no candidate can be confirmed.
+   *
+   * WHAT IT ASSERTS, in the exact words of the guard's own contract: the project carries an admitted
+   * `.lua` file that this `require` names. It asserts NOTHING about symbols, so it can never raise
+   * `resolved`, and it is written ONLY where the guard confirmed a candidate on disk — a claim the
+   * project would refute is worse than no claim, because the gate checks a claim BEFORE the count.
+   *
+   * WHEN IT IS SILENT, and both silences are deliberate:
+   *   * NO ROOT, NO CLAIM. `analyze` without an absolute `projectRoot` (the fixture runner, a
+   *     one-off parse) states no claim at all rather than guessing a base. A caller that wants the
+   *     claim must hand the analyzer the project it is reading inside;
+   *   * NO CANDIDATE, NO CLAIM. `require("luarocks.fs")`, `require("tap")` and the rest of the
+   *     residue name files this corpus does not carry — those edges keep their target and stay
+   *     unresolved, which is TRUE, rather than being marked external to make a column smaller.
+   *
+   * The candidate arithmetic is `luaModuleFileCandidates`; the ADMITTED-EXTENSION clause, the
+   * inside-the-project clause, the size cap and the `statSync` are the shared guard's, so this lane
+   * cannot relax them by editing its own spelling of them.
+   */
+  moduleFileClaim(moduleName, ctx) {
+    const { projectRoot, filePath } = ctx;
+    if (projectRoot === void 0 || filePath === void 0) return null;
+    const cached = ctx.moduleFileClaims?.get(moduleName);
+    if (cached !== void 0) return cached;
+    const fileRel = path.relative(projectRoot, filePath).split(path.sep).join("/");
+    const claim = fileClaimForTarget({
+      projectRoot,
+      filePath,
+      // THE TARGET AS WRITTEN. The guard folds it itself before the extras below; the claim is a
+      // statement ABOUT this string and never a rewrite of it.
+      written: moduleName,
+      // THE LANE'S OWN ADMITTED LIST out of the router: lua admits `.lua` alone, so a candidate of
+      // any other extension can never verify while a miss still refutes — which is why this clause
+      // is the guard's and not this file's.
+      admittedExtensions: ["lua"],
+      extraCandidates: luaModuleFileCandidates(moduleName, fileRel),
+      // The indexer's own admission cap: a file above it is not in the population a claim is
+      // checked against, so a claim about it would be REFUTED rather than unverified.
+      maxFileSizeBytes: FILE_CLAIM_MAX_BYTES
+    });
+    ctx.moduleFileClaims?.set(moduleName, claim);
+    return claim;
+  }
+  // M60 LUA-06: this was ORDER-DEPENDENT, and therefore wrong. `declaredTables`
+  // was filled during the same single traversal that read it, so whether a
+  // constructor call produced an edge depended on whether the table's
+  // declaration happened to appear EARLIER IN THE FILE. Proven by probe, with
+  // the two files differing only in statement order:
+  //
+  //   local A = {}            A.new()
+  //   function A.new() end    local A = {}
+  //   A.new()                 function A.new() end
+  //
+  //   first  -> instantiates global->A   (edge present)
+  //   second -> NO EDGE                  (same semantics, no edge)
+  //
+  // A relationship that depends on where its declaration sits is not a fact
+  // about the program, it is a fact about the traversal. The fix is a PRE-PASS:
+  // collect every name this file binds to a table, before any call is examined.
+  // One traversal, order-independent.
+  constructorTarget(functionNode, ctx) {
+    if (!["dot_index_expression", "method_index_expression"].includes(functionNode.type)) return void 0;
+    const method = functionNode.childForFieldName("method") || functionNode.childForFieldName("field");
+    const table = functionNode.childForFieldName("table");
+    if ((method?.text === "new" || method?.text === "constructor") && table?.text && ctx.declaredTables.has(table.text)) return table.text;
+    return void 0;
+  }
+  // M60 LUA-06: collect the file's table-valued names BEFORE the walk, so a
+  // constructor call does not depend on the order of the declaration.
+  collectDeclaredTables(root, ctx) {
+    const stack = [root];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (node.type === "variable_declaration" || node.type === "assignment_statement") {
+        const inner = node.type === "variable_declaration" ? node.namedChild(0) : node;
+        const list = inner?.type === "assignment_statement" ? inner.namedChild(0) : void 0;
+        const values = inner?.type === "assignment_statement" ? inner.namedChild(1) : void 0;
+        const first = values?.namedChild(0);
+        if (list?.type === "variable_list" && first?.type === "table_constructor") {
+          for (let i = 0; i < list.namedChildCount; i++) {
+            const id = list.namedChild(i);
+            if (id?.type === "identifier") ctx.declaredTables.add(id.text);
+          }
+        }
+      }
+      if (node.type === "function_declaration") {
+        const nm = node.childForFieldName("name");
+        if (nm && (nm.type === "dot_index_expression" || nm.type === "method_index_expression")) {
+          const recv = nm.namedChild(0);
+          if (recv?.type === "identifier") ctx.declaredTables.add(recv.text);
+        }
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c) stack.push(c);
+      }
+    }
+  }
+  /**
+   * M60 LUA-44: derived table -> the tables its member lookup falls back to.
+   *
+   * Lua has NO inheritance keyword, so a grammar inventory can never find this
+   * relation — it is a CONVENTION over three ordinary constructs, and the
+   * ontology-coverage gate's own json ruling says in as many words that a grammar
+   * cannot see a convention. All three forms are read here because all three mean
+   * the same thing for an override:
+   *
+   *   setmetatable(D, B)            D's members fall back to B's  (direct)
+   *   setmetatable(D, {__index = B})  the same, through an inline metatable
+   *   local Mt = {__index = B}; setmetatable(D, Mt)   the same, through a named
+   *                                    metatable — kong's idiom, and the shape
+   *                                    probe B2 actually found
+   *   D.__index = B                 the same, assigned after the fact
+   *
+   * The named-metatable form needs TWO HOPS and is why this method does not simply
+   * read the second argument: `setmetatable(_lmdb, _lmdb_mt)` names a METATABLE,
+   * and reading it as a supertype would make every metatable in the corpus look
+   * like a base class. Resolving `Mt -> Mt.__index -> Base` is the difference
+   * between the two, and it is a derivation over parse facts rather than a guess:
+   * both hops are written in the file.
+   *
+   * The third form is deliberately absent from the B2 probe in
+   * script/m60/lua-ontology-census.ts, which reads only the inline
+   * `setmetatable` forms and therefore UNDER-counts (1 occurrence). That probe is
+   * the falsifiable instrument for the ruling; this is the analyzer's wider read,
+   * and the gap between them is disclosed rather than reconciled by widening the
+   * probe until the numbers agree.
+   */
+  collectSupertypeLinks(root, ctx) {
+    const link = (derived, base) => {
+      if (!derived || !base || derived === base) return;
+      if (ctx.declaredTables.has(derived) || ctx.declaredTables.has(base)) {
+        const set = ctx.supertypeLinks.get(derived) ?? /* @__PURE__ */ new Set();
+        set.add(base);
+        ctx.supertypeLinks.set(derived, set);
+      }
+    };
+    const indexField = (table) => {
+      if (table?.type !== "table_constructor") return void 0;
+      for (let i = 0; i < table.namedChildCount; i++) {
+        const f = table.namedChild(i);
+        if (f?.type !== "field") continue;
+        const key = f.childForFieldName("name") ?? f.namedChild(0);
+        const value = f.namedChild(1);
+        if (key?.text === "__index" && value?.type === "identifier") return value.text;
+      }
+      return void 0;
+    };
+    const metatableIndex = /* @__PURE__ */ new Map();
+    const pending = [];
+    const stack = [root];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (node.type === "function_call") {
+        const fn = node.childForFieldName("name");
+        const args = node.childForFieldName("arguments");
+        if (fn?.type === "identifier" && (fn.text === "setmetatable" || fn.text === "setmetatable2")) {
+          const a0 = args?.namedChild(0) ?? null;
+          pending.push({ derived: a0?.type === "identifier" ? a0.text : void 0, second: args?.namedChild(1) ?? null });
+        }
+      }
+      if (node.type === "variable_declaration" || node.type === "assignment_statement") {
+        const inner = node.type === "variable_declaration" ? node.namedChild(0) : node;
+        if (inner?.type === "assignment_statement") {
+          const list = inner.namedChild(0);
+          const values = inner.namedChild(1);
+          const table = values?.type === "expression_list" ? values.namedChild(0) : void 0;
+          const base = indexField(table);
+          if (base && list?.type === "variable_list") {
+            for (let i = 0; i < list.namedChildCount; i++) {
+              const id = list.namedChild(i);
+              if (id?.type === "identifier") metatableIndex.set(id.text, base);
+            }
+          }
+        }
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c) stack.push(c);
+      }
+    }
+    for (const site of pending) {
+      const second = site.second;
+      if (second?.type === "identifier") {
+        link(site.derived, metatableIndex.get(second.text) ?? second.text);
+      } else {
+        const base = indexField(second);
+        if (base) link(site.derived, base);
+      }
+    }
+    const stack2 = [root];
+    while (stack2.length > 0) {
+      const node = stack2.pop();
+      if (node.type === "assignment_statement") {
+        const list = node.namedChild(0);
+        const values = node.namedChild(1);
+        const lhs = list?.type === "variable_list" ? list.namedChild(0) ?? null : null;
+        const rhs = values?.type === "expression_list" ? values.namedChild(0) ?? null : null;
+        if ((lhs?.type === "dot_index_expression" || lhs?.type === "method_index_expression") && lhs.namedChild(lhs.namedChildCount - 1)?.text === "__index" && rhs?.type === "identifier") {
+          const receiver = lhs.namedChild(0);
+          link(receiver?.type === "identifier" ? receiver.text : void 0, rhs.text);
+        }
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c) stack2.push(c);
+      }
+    }
+  }
+  /**
+   * M60 LUA-51 — a WRITTEN supertype CLAUSE, expressed as an ordinary call argument.
+   *
+   * MEASURED BEFORE THIS METHOD EXISTED (script/m60/lua-supertype-arg-probe.ts, over
+   * the 3,250 admitted corpus files): 7 written supertype arguments across 5 files,
+   * of which 2 are inheritance and neither was emitted. The two:
+   *
+   *   luarocks/vendor/argparse.lua:277   local Command = class({...}, {...}, Parser)
+   *   luarocks/vendor/argparse.lua:328   local Option  = class({...}, {...}, Argument)
+   *
+   * `extends` read only `setmetatable` (real-lua-analyzer.ts:924) and the `class`
+   * branch read only `firstString`, the class's own NAME — so a parent passed in ANY
+   * argument position was invisible.
+   *
+   * ## Why the position is READ and not GUESSED
+   *
+   * The obvious implementation is "the third argument of a `class` call is the
+   * parent", and it is wrong in a way the corpus demonstrates: middleclass's own form
+   * is `class("Name", Super)` — second position — and luarocks' is
+   * `class(prototype, properties, parent)` — third. A fixed index publishes a wrong
+   * edge for one of them and misses the other.
+   *
+   * So the position comes from the CALLEE'S OWN PARAMETER LIST, which the same file
+   * writes down:
+   *
+   *   local function class(prototype, properties, parent)
+   *                        0           1          2      <- the parent slot
+   *
+   * A parameter whose NAME states the supertype role (`parent`, `super`, `base`,
+   * `supertype`, `superclass`, …) identifies its own slot. If the file does not
+   * declare such a parameter there is nothing to read, and no edge is published — so
+   * the rule cannot invent a relation from a call that never claimed one.
+   *
+   * ## Why this is `extends` and not `implements`
+   *
+   * Because the callee's body composes the parent into the object it returns:
+   *
+   *   if parent then cl.__prototype = deep_update(deep_update({}, parent.__prototype), prototype)
+   *
+   * The new class's prototype is built FROM the parent's. That is inheritance, and it
+   * is the same relation the `setmetatable` forms already publish, so it carries the
+   * same label and feeds the same `supertypeLinks` map that `overrides` reads.
+   *
+   * ## Confidence
+   *
+   * 0.95, `usage_contextual` — NOT 1.0 and NOT `structural`, and deliberately so.
+   * Both endpoint NAMES are written in the file, which is what earns `extends` 1.0
+   * elsewhere; what is a convention rather than a fact is the ROLE: that a parameter
+   * named `parent` means the supertype. `overrides`' `lua_inherited_member` takes the
+   * same 0.95 for the same reason and cites the same family precedent
+   * (real-objective-c-analyzer.ts:1020). The corpus shows the cost of reading it as
+   * certain: `snacks.nvim/lua/snacks/layout.lua` and three other files declare a
+   * `parent` parameter for TREE TRAVERSAL (`_each(widget, parent)`,
+   * `add(result, parent)`), and the probe returns all 5 of those alongside the 2 real
+   * ones.
+   *
+   * So the read is narrowed to the case the corpus proves is inheritance: the factory
+   * must be ASSIGNED to a top-level name, because `local Command = class(...)` is what
+   * makes the edge's SOURCE a name a consumer can follow, and the derived and base
+   * names must differ.
+   */
+  collectFactorySupertypeLinks(root, ctx) {
+    const SUPERTYPE_ROLES = /* @__PURE__ */ new Set([
+      "parent",
+      "super",
+      "base",
+      "supertype",
+      "superclass",
+      "super_class",
+      "parentclass",
+      "parent_class"
+    ]);
+    const paramNames = (params) => {
+      const out = [];
+      if (!params) return out;
+      for (let i = 0; i < params.namedChildCount; i++) {
+        const c = params.namedChild(i);
+        if (!c) continue;
+        if (c.type === "identifier") out.push(c.text);
+        else if (c.type === "vararg_expression") continue;
+        else out.push("");
+      }
+      return out;
+    };
+    const foldsIntoMetamethod = (fn, param) => {
+      let found = false;
+      const isRole = (n) => n?.type === "identifier" && n.text === param;
+      const visit = (n) => {
+        if (found) return;
+        if (n.type === "dot_index_expression" || n.type === "method_index_expression") {
+          if (isRole(n.namedChild(0))) {
+            const last = n.namedChild(n.namedChildCount - 1);
+            if (last?.text?.startsWith("__")) {
+              found = true;
+              return;
+            }
+          }
+        }
+        if (n.type === "assignment_statement") {
+          const lhs = n.namedChild(0);
+          const lhsNode = lhs?.type === "variable_list" ? lhs.namedChild(0) : void 0;
+          if (lhsNode && (lhsNode.type === "dot_index_expression" || lhsNode.type === "method_index_expression")) {
+            const field = lhsNode.namedChild(lhsNode.namedChildCount - 1);
+            const rhs = n.namedChild(1);
+            const rhsNode = rhs?.type === "expression_list" ? rhs.namedChild(0) : void 0;
+            if (field?.text?.startsWith("__") && isRole(rhsNode)) {
+              found = true;
+              return;
+            }
+          }
+        }
+        for (let i = 0; i < n.namedChildCount; i++) {
+          const c = n.namedChild(i);
+          if (c) visit(c);
+        }
+      };
+      const body = fn.childForFieldName("body") ?? fn;
+      for (let i = 0; i < body.namedChildCount; i++) {
+        const c = body.namedChild(i);
+        if (c) visit(c);
+      }
+      return found;
+    };
+    const factoryParams = /* @__PURE__ */ new Map();
+    const stack0 = [root];
+    while (stack0.length > 0) {
+      const node = stack0.pop();
+      if (node.type === "function_declaration" || node.type === "function_definition") {
+        const nameNode = node.childForFieldName("name");
+        if (nameNode?.type === "identifier" && nameNode.text && !factoryParams.has(nameNode.text)) {
+          const ps = paramNames(node.childForFieldName("parameters"));
+          if (ps.some((p) => SUPERTYPE_ROLES.has(p.toLowerCase()) && foldsIntoMetamethod(node, p))) {
+            factoryParams.set(nameNode.text, ps);
+          }
+        }
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c) stack0.push(c);
+      }
+    }
+    if (factoryParams.size === 0) return;
+    const stack1 = [root];
+    while (stack1.length > 0) {
+      const node = stack1.pop();
+      if (node.type === "variable_declaration" || node.type === "assignment_statement") {
+        const inner = node.type === "variable_declaration" ? node.namedChild(0) : node;
+        const call = inner?.type === "assignment_statement" ? inner.namedChild(1) : node;
+        const value = call?.type === "expression_list" ? call.namedChild(0) : void 0;
+        if (value?.type === "function_call" && inner) {
+          const callee = value.childForFieldName("name");
+          const args = value.childForFieldName("arguments");
+          if (callee?.type === "identifier" && args) {
+            const ps = factoryParams.get(callee.text);
+            if (ps) {
+              const list = inner.namedChild(0);
+              const derived = list?.type === "variable_list" ? list.namedChild(0) : void 0;
+              const derivedName = derived?.type === "identifier" ? derived.text : void 0;
+              ps.forEach((p, slot) => {
+                if (!SUPERTYPE_ROLES.has(p.toLowerCase())) return;
+                const argNode = args.namedChild(slot);
+                if (argNode?.type !== "identifier") return;
+                const baseName = argNode.text;
+                if (!derivedName || derivedName === baseName) return;
+                const existing = ctx.supertypeLinks.get(derivedName) ?? /* @__PURE__ */ new Set();
+                existing.add(baseName);
+                ctx.supertypeLinks.set(derivedName, existing);
+                ctx.factorySupertypeLines.set(`${derivedName}|${baseName}`, {
+                  derived: derivedName,
+                  base: baseName,
+                  line: argNode.startPosition.row + 1
+                });
+              });
+            }
+          }
+        }
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c) stack1.push(c);
+      }
+    }
+  }
+  /**
+   * M60 LUA-51 — publish the `extends` edge for a factory supertype clause.
+   *
+   * `extends` was emitted only from the `setmetatable` call site, so a link collected
+   * by `collectFactorySupertypeLinks` reached `overrides` and nothing else. This runs
+   * beside it and emits the same relation, deduplicated against the `extends` edges
+   * already in the result so a link both readers find is published once.
+   *
+   * It iterates `factorySupertypeLines` and NOT `supertypeLinks`, and that is the whole
+   * correction. The first version walked `supertypeLinks`, which is the union of THREE
+   * conventions, and so published the third one — `D.__index = Base` — under this
+   * method's `lua_factory_supertype` label. Measured on the file that exposed it:
+   *
+   *   luarocks/vendor/argparse.lua:99   class_metatable.__index = parent
+   *
+   * produced `class_metatable -[extends 0.95 lua_factory_supertype]-> parent` — a link
+   * the walk had deliberately never published, carrying a label that says "factory" for
+   * a construct with no factory in it. `factorySupertypeLines` is keyed only by links
+   * `collectFactorySupertypeLinks` created, so iterating it cannot reach the other two.
+   */
+  addFactorySupertypeEdges(ctx) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const e of ctx.relationships) {
+      if (e.type !== ASTEngine.RelationshipType.Extends) continue;
+      seen.add(`${e.source}|${e.target}`);
+    }
+    for (const [key, link] of ctx.factorySupertypeLines) {
+      const { derived, base, line } = link;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      this.addRelationship(
+        ctx,
+        derived,
+        base,
+        ASTEngine.RelationshipType.Extends,
+        { luaSpecific: true, relationshipType: "lua_factory_supertype", evidenceClass: "usage_contextual" },
+        null,
+        { confidence: 0.95, symbolRange: { startLine: line } }
+      );
+    }
+  }
+  /**
+   * `decorates` — THE LUA DECORATOR IDIOM, and the measurement that made it a
+   * relation instead of a ruling.
+   *
+   * ## What the construct is
+   *
+   * Lua has no annotation syntax. Its decorator idiom is the PYTHON DESUGARING
+   * WRITTEN OUT: a declared function is wrapped by a declared higher-order
+   * function and rebound to the same name at file scope.
+   *
+   *     function fib(n) ... end
+   *     function cache(f)                -- a WRAPPER FACTORY: returns a function
+   *       local c = {}
+   *       return function(x) ... end
+   *     end
+   *     fib = cache(fib)                 -- redis/deps/lua/test/fib.lua:39
+   *
+   * `@cache def fib` in Python compiles to exactly this sequence — the function
+   * object is created, then `cache` is applied to it, then the name is rebound. So
+   * the relation is a real runtime application to a DECLARATION, and the edge is
+   * `fib -> cache` (the vocabulary's direction: decorated declaration -> decorator).
+   *
+   * ## Why the discriminator is structural, and what each clause excludes
+   *
+   * MEASURED over the whole admitted population (3,255 tracked files, artifact
+   * validation/m14/measurements/lua-extended-census.json): 1,185 `X = f(X)` sites;
+   * 186 whose name is declared somewhere in the file; 3 at file scope; **1** that is
+   * a decoration. The clauses below are what separate that one from the other 1,184:
+   *
+   *   FILE SCOPE ONLY. A decorator is applied while the declaration is created, and
+   *   in Lua that is chunk scope. An in-function `X = f(X)` is a value assignment —
+   *   measured class: `value = sub(value, 2, -2)`, `payload = json_encode(payload)`.
+   *   Publishing those would attach a decoration to a local parameter.
+   *
+   *   X IS A DECLARED FUNCTION. The decorated endpoint must be a declaration this
+   *   file writes (`function X(...)`, including `local function X`). A rebinding of
+   *   a table or a scalar is not a declaration being decorated.
+   *
+   *   f IS A DECLARED WRAPPER FACTORY. `f`'s own body must RETURN a function
+   *   definition — that is the structural evidence it is a decorator and not a
+   *   transform. `cache` returns `function(x) ... end`; `sub`, `concat`,
+   *   `json_encode` return values. This clause is the whole difference between the
+   *   185 value rebindings and the 1 decoration, and a name-based filter would not
+   *   find it (the dart lane's lesson: a filter on the NAME does not separate the
+   *   construct from its impostors).
+   *
+   *   THE ARGUMENT IS THE DECORATED NAME. `f(X)` with the same identifier that is
+   *   rebound; `fib = cache(x)` decorates `x`'s value, not `fib`.
+   *
+   * ## Confidence and tier
+   *
+   * 0.95 and `usage_contextual`, NOT 1.0 and NOT `structural`. The application is a
+   * real call site and both names are written in the file; what is a CONVENTION is
+   * the READING — that a wrapper-factory application to a declaration is a
+   * decoration rather than a memoization rebinding. Same number and tier this
+   * analyzer already assigns its two other convention edges (`lua_factory_supertype`,
+   * `lua_inherited_member`), and the same reason: "a 0.95 edge must not claim
+   * `structural`" (see `addFactorySupertypeEdges`).
+   */
+  extractDecoratorApplication(node, frame, ctx) {
+    if (frame.inFunction) return;
+    const inner = node.type === "variable_declaration" ? node.namedChild(0) : node;
+    if (inner?.type !== "assignment_statement") return;
+    const list = this.childOfType(inner, "variable_list");
+    const values = this.childOfType(inner, "expression_list");
+    const lhs = list?.namedChild(0);
+    const call = values?.namedChild(0);
+    if (lhs?.type !== "identifier" || call?.type !== "function_call") return;
+    const callee = call.childForFieldName("name");
+    if (callee?.type !== "identifier") return;
+    const args = call.childForFieldName("arguments");
+    const arg0 = args?.namedChild(0);
+    if (arg0?.type !== "identifier" || arg0.text !== lhs.text) return;
+    if (callee.text === lhs.text) return;
+    if (!ctx.declaredFunctions.has(lhs.text)) return;
+    if (!ctx.wrapperFactories.has(callee.text)) return;
+    this.addRelationship(
+      ctx,
+      lhs.text,
+      callee.text,
+      ASTEngine.RelationshipType.Decorates,
+      {
+        luaSpecific: true,
+        relationshipType: "lua_decorator_application",
+        decorator: callee.text,
+        evidenceClass: "usage_contextual"
+      },
+      call,
+      { confidence: 0.95 }
+    );
+  }
+  /**
+   * THE PRE-PASS for `decorates`: the file's declared function names and, of those,
+   * the ones whose body RETURNS a function (wrapper factories).
+   *
+   * Order-independent by construction, for the same reason `collectDeclaredTables`
+   * and `collectSupertypeLinks` are: a file may apply a factory declared below the
+   * site, and a relation that depends on traversal order is a fact about the
+   * traversal, not the program.
+   *
+   * `function X()` and `local function X()` both parse as `function_declaration` with
+   * an `identifier` name (verified on the pinned build), so both are declarations for
+   * this purpose. A `function M.x()` binds a FIELD — reachable only through the
+   * table and not a bare name a decoration site could rebind — and is not collected.
+   */
+  collectDecoratorFacts(root, ctx) {
+    const stack = [root];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (node.type === "function_declaration") {
+        const nm = node.childForFieldName("name");
+        if (nm?.type === "identifier") {
+          ctx.declaredFunctions.add(nm.text);
+          if (this.returnsFunctionDefinition(node)) ctx.wrapperFactories.add(nm.text);
+        }
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c) stack.push(c);
+      }
+    }
+  }
+  /**
+   * Does this function's own body RETURN a function definition, at ITS OWN level?
+   *
+   * The walk stops at a nested function body, because a return inside it belongs to
+   * that inner function. `function cache(f) ... return function(x) ... end end`
+   * answers true; `function sub(s, i) return s end` answers false; a factory whose
+   * inner wrapper itself returns a value (`return function(x) return f(x) end end`)
+   * answers true from the OUTER return, which is the one that matters.
+   */
+  returnsFunctionDefinition(fn) {
+    const body = fn.childForFieldName("body");
+    if (!body) return false;
+    const visit = (n) => {
+      if (n.type === "return_statement") {
+        const list = this.childOfType(n, "expression_list");
+        const first = list?.namedChild(0) ?? n.namedChild(0);
+        if (first && (first.type === "function_definition" || first.type === "function_declaration")) return true;
+        return false;
+      }
+      if (n.type === "function_definition" || n.type === "function_declaration") return false;
+      for (let i = 0; i < n.namedChildCount; i++) {
+        const c = n.namedChild(i);
+        if (c && visit(c)) return true;
+      }
+      return false;
+    };
+    for (let i = 0; i < body.namedChildCount; i++) {
+      const c = body.namedChild(i);
+      if (c && visit(c)) return true;
+    }
+    return false;
+  }
+  extractExport(node, frame, ctx) {
+    if (frame.inFunction) return;
+    const values = this.childOfType(node, "expression_list");
+    const target = values?.namedChild(0);
+    if (!target) return;
+    if (target.type === "identifier") {
+      ctx.exports.push({ name: target.text, isDefault: true, range: this.nodeToRange(node), metadata: { luaSpecific: true } });
+      this.addExportEdge(ctx, target.text, target);
+      return;
+    }
+    if (target.type === "function_call") {
+      const nameNode = target.childForFieldName("name") ?? target.namedChild(0);
+      const calleeName = nameNode ? this.callee(nameNode)?.name : void 0;
+      if (calleeName === "setmetatable") {
+        const first = this.callArgument(target, 0);
+        const named = this.nameBearing(first);
+        if (named) {
+          ctx.exports.push({ name: named, isDefault: true, range: this.nodeToRange(first), metadata: { luaSpecific: true, viaMetatable: true } });
+          this.addExportEdge(ctx, named, first ?? null);
+        } else {
+          ctx.unpublishedSurface.push({ shape: "call-result", detail: calleeName ?? null, line: target.startPosition.row + 1, why: "setmetatable's first argument is an expression, so the surface has no name" });
+        }
+      } else if (calleeName === "require") {
+        const arg = this.callArgument(target, 0);
+        const path2 = arg?.type === "string" ? this.stringValue(arg) : null;
+        ctx.unpublishedSurface.push({ shape: "re-export", detail: path2 ?? null, line: target.startPosition.row + 1, why: "the surface is another module's, not this module's" });
+      } else {
+        ctx.unpublishedSurface.push({ shape: "call-result", detail: calleeName ?? null, line: target.startPosition.row + 1, why: "the result of a call is statically unknowable" });
+      }
+      return;
+    }
+    if (target.type === "string") {
+      ctx.unpublishedSurface.push({ shape: "value-literal", detail: this.stringValue(target) ?? null, line: target.startPosition.row + 1, why: "a value is not a name" });
+      return;
+    }
+    if (target.type === "function_definition") {
+      ctx.unpublishedSurface.push({ shape: "anonymous-function", detail: null, line: target.startPosition.row + 1, why: "an anonymous function has no name" });
+      return;
+    }
+    if (target.type === "table_constructor") {
+      for (let i = 0; i < target.namedChildCount; i++) {
+        const f = target.namedChild(i);
+        if (!f || f.type !== "field") continue;
+        const key = f.childForFieldName("name");
+        if (!key) continue;
+        let name;
+        if (key.type === "identifier") name = key.text;
+        else if (key.type === "string") name = this.stringValue(key);
+        if (!name) continue;
+        ctx.exports.push({ name, isDefault: false, range: this.nodeToRange(key), metadata: { luaSpecific: true } });
+        this.addExportEdge(ctx, name, key);
+      }
+    }
+  }
+  /** M60 LUA-42: the `exports` edge for one nameable module-surface name.
+   *
+   * Confidence 1.0 and `evidenceClass: "structural"`, because both halves of the
+   * claim are written in the file: a `return` at chunk scope names this name. That
+   * is the difference from `uses`/`references` (LUA-40/LUA-41), where the name is
+   * written but the BINDING it denotes is not — the reason those two carry 0.9
+   * and those two only.
+   */
+  addExportEdge(ctx, name, nameNode) {
+    this.addRelationship(
+      ctx,
+      "global",
+      name,
+      ASTEngine.RelationshipType.Exports,
+      { luaSpecific: true, relationshipType: "lua_module_return" },
+      nameNode
+    );
+  }
+  /**
+   * M60 LUA-44 — `overrides`, the type this lane was missing.
+   *
+   * MEASURED BEFORE THIS METHOD EXISTED, on 3,250 corpus files through
+   * `parseFile` (script/m60/lua-ontology-census.ts):
+   *
+   *   B1-override-redefinition   65 occurrences / 37 files
+   *   B2-override-inherited       1 occurrence  /  1 file
+   *
+   * Both non-zero, so `overrides` could NOT be ruled and had to be built. That is
+   * the whole reason this method exists: the ontology-coverage gate refuses a
+   * ruling whose probe finds a non-zero count, and the lua grammar's 100 node
+   * types include no `override_specifier` and no `redefinition` node, so no
+   * grammar inventory would ever have found it — instrument A is silent here by
+   * construction, and only instrument B could falsify the ruling.
+   *
+   * TWO SHAPES, two labels, because Lua expresses two different things and fusing
+   * them would state one of them falsely:
+   *
+   *   lua_redefinition    the SAME name declared twice in one chunk. The later
+   *                       declaration replaces the earlier one. 1.0, structural —
+   *                       both endpoints are nodes this parse saw, and the
+   *                       `overridesLine` metadata carries the prior declaration's
+   *                       line so the two are distinguishable, exactly as
+   *                       real-bash-analyzer.ts:343 does for the same construct.
+   *
+   *   lua_inherited_member  a member of D that D also inherits from a base B. 0.95,
+   *                       structural — the family number for this edge is objc's
+   *                       (real-objective-c-analyzer.ts:1020), and perl uses 0.95
+   *                       for the same verified-base case. It is not 1.0 because
+   *                       the corpus's inheritance is a CONVENTION over
+   *                       `setmetatable`/`__index`, and nothing in the tree says
+   *                       the link is meant as inheritance.
+   *
+   * The DIRECTION and the ENDPOINTS deliberately do NOT copy objc's
+   * `Derived.member -> Base.member`. This lane's member-identity contract (LUA-15,
+   * pinned by validation/m14/fixtures/lua/member-identity.expectation.json) holds
+   * that a member's identity is its container plus its own name and that the
+   * qualified path must not BE the name — that fixture FORBIDS `Buffer:initialize`
+   * as a symbol name. So the edge runs `Derived -> Base`, the same pair `extends`
+   * uses, and the overridden member travels in metadata as `member` plus the
+   * qualified `memberPath`. Two tables in one file can therefore produce an
+   * `overrides` and an `extends` edge between the same pair, under different type
+   * labels; the store treats a distinct type on the same pair as a distinct link,
+   * which is the property that keeps them from being read as one fact.
+   */
+  addOverrideRelationships(ctx) {
+    for (const [label, decls] of ctx.declarationsByLabel) {
+      if (decls.length < 2) continue;
+      const byLine = [...decls].sort((a, b) => a.line - b.line);
+      const first = byLine[0];
+      for (let i = 1; i < byLine.length; i++) {
+        const d = byLine[i];
+        this.addRelationship(
+          ctx,
+          d.owner ?? "global",
+          d.owner ? d.member ?? label : label,
+          ASTEngine.RelationshipType.Overrides,
+          {
+            luaSpecific: true,
+            relationshipType: "lua_redefinition",
+            redefinition: true,
+            qualifiedName: label,
+            overridesLine: first.line,
+            overriddenOwner: first.owner
+          },
+          null,
+          { confidence: 1, symbolRange: { startLine: d.line } }
+        );
+      }
+    }
+    for (const [derived, bases] of ctx.supertypeLinks) {
+      const derivedMembers = ctx.membersByOwner.get(derived);
+      if (!derivedMembers || derivedMembers.size === 0) continue;
+      for (const base of bases) {
+        const baseMembers = ctx.membersByOwner.get(base);
+        if (!baseMembers) continue;
+        for (const [member, line] of derivedMembers) {
+          if (!baseMembers.has(member)) continue;
+          this.addRelationship(
+            ctx,
+            derived,
+            base,
+            ASTEngine.RelationshipType.Overrides,
+            {
+              luaSpecific: true,
+              relationshipType: "lua_inherited_member",
+              isOverride: true,
+              member,
+              memberPath: `${derived}.${member} -> ${base}.${member}`,
+              // M60 LUA-52: the tier is `usage_contextual`, NOT the `structural` that
+              // `evidenceClassFor` hands every type which is not imports/references/uses.
+              // The rule this analyzer already wrote for ITSELF is at
+              // `addFactorySupertypeEdges` (:1381): "a 0.95 edge must not claim
+              // `structural`". `structural` asserts both endpoints are nodes this parse
+              // saw, which is true here — and is not the claim. The claim is that a
+              // member SHADOWS another through an `__index` chain, and Lua's inheritance
+              // is a CONVENTION over `setmetatable`/`__index` with nothing in the tree
+              // saying the link is meant as inheritance. Same reason, same 0.95, same
+              // tier as `lua_factory_supertype`.
+              //
+              // MEASURED (validation/m60/lua/ontology-census.json, 3,252 files): 2 of
+              // 67 `overrides` edges carried `structural` at confidence 0.95, and the
+              // census counted 67 edges before and after this change — the tier is the
+              // whole difference. Pinned by
+              // `validation/m14/fixtures/lua/override-shapes.expectation.json`, whose
+              // forbid half fails an implementation that derives the tier from the
+              // type, and by the mutant in script/m60/mutate-lua-evidence-tier.ts.
+              evidenceClass: "usage_contextual"
+            },
+            null,
+            { confidence: 0.95, symbolRange: { startLine: line } }
+          );
+        }
+      }
+    }
+  }
+  addContainsRelationships(ctx) {
+    for (const symbol of ctx.symbols) {
+      const owner = symbol.ownerName || symbol.frameSelfName || (symbol.scope === "global" || !symbol.scope ? "global" : symbol.scope);
+      const selfNamed = owner === symbol.name;
+      const ownerWrittenAsReceiver = symbol.metadata?.isMethod === true;
+      const containerExists = selfNamed && ownerWrittenAsReceiver && ctx.symbols.some(
+        (o) => o.name === owner && o !== symbol && (o.range?.startLine !== symbol.range?.startLine || o.kind !== symbol.kind)
+      );
+      if (owner && (owner !== symbol.name || containerExists)) {
+        this.addRelationship(ctx, owner, symbol.name, ASTEngine.RelationshipType.Contains, {}, void 0, { symbolRange: symbol.range });
+      }
+    }
+  }
+  addRelationship(ctx, source, target, type, metadata, nameNode, opts) {
+    if (!source || !target) return;
+    const key = `${type}${source}${target}`;
+    if (ctx.seenRelationships.has(key)) return;
+    ctx.seenRelationships.add(key);
+    const relationship = {
+      source,
+      target,
+      type,
+      confidence: opts?.confidence ?? 1,
+      metadata
+    };
+    if (nameNode) relationship.line_number = nameNode.startPosition.row + 1;
+    else if (opts?.symbolRange) relationship.line_number = opts.symbolRange.startLine;
+    relationship.metadata = { evidenceClass: this.evidenceClassFor(type), ...relationship.metadata };
+    const receiver = nameNode ? this.stdlibReceiverOf(nameNode) : null;
+    if (receiver) ctx.stdlibCandidates.push({ rel: relationship, receiver });
+    const globalName = (type === ASTEngine.RelationshipType.Calls || type === ASTEngine.RelationshipType.Uses) && nameNode !== null && nameNode !== void 0 && target === nameNode.text ? this.stdlibGlobalNameOf(nameNode) : null;
+    if (globalName !== null && LUA54_GLOBALS.has(globalName)) {
+      ctx.stdlibGlobalCandidates.push({ rel: relationship, name: globalName });
+    }
+    ctx.relationships.push(relationship);
+  }
+  /**
+   * M60 LUA-54 — the standard-library receiver of a member read, or `null`.
+   *
+   * The name node is the edge's own target, so the test is structural rather than
+   * a name comparison: walk up to the `dot_index_expression` /
+   * `method_index_expression` that OWNS this node, require its receiver to be an
+   * `identifier`, and return that identifier's text. `bracket_index_expression` is
+   * excluded deliberately — `t["insert"]` is a member read whose key is a STRING
+   * literal and never an identifier, so it cannot carry a receiver name, and
+   * `stdlibReceiverOf` returning `null` for it is the correct answer rather than a
+   * miss. `t[table.insert]` is a real `table.insert` read and is NOT marked: the
+   * subscript is a computed value, so the name it denotes is not in the tree.
+   *
+   * Returns the RECEIVER's text and nothing else. Whether that name is a standard
+   * library table is decided by the caller against a transcribed list, so this
+   * method holds no list and cannot drift from one.
+   */
+  stdlibReceiverOf(nameNode) {
+    const owner = nameNode.parent;
+    if (!owner) return null;
+    if (owner.type !== "dot_index_expression" && owner.type !== "method_index_expression") return null;
+    const field = owner.childForFieldName("field") ?? owner.childForFieldName("method");
+    if (!field || !this.isSameNode(field, nameNode)) return null;
+    const receiver = owner.childForFieldName("table");
+    if (!receiver || receiver.type !== "identifier") return null;
+    return receiver.text;
+  }
+  /**
+   * M60 LUA-57 — the node's text when the node is a BARE identifier, or `null` when
+   * it is a member's name.
+   *
+   * The inverse question to `stdlibReceiverOf`, and it is answered structurally for
+   * the same reason: `("abc"):type()` and `obj.type()` both publish target `type`
+   * with a node whose TEXT is `type`, and neither is the standard library global —
+   * the first because its receiver is a literal, the second because its receiver is
+   * an identifier that is not a documented table. Text alone cannot tell either from
+   * a bare `type(x)`, so the shape decides: a name that is the FIELD or METHOD of an
+   * index expression is a member's name and never a global read. The RECEIVER half
+   * of an index expression is deliberately NOT excluded — it is a genuine bare read
+   * of that identifier — but no `calls`/`uses` edge is ever published under it, so
+   * the case is unreachable from the only two call sites that consult this.
+   */
+  stdlibGlobalNameOf(nameNode) {
+    if (nameNode.type !== "identifier") return null;
+    const owner = nameNode.parent;
+    if (owner && (owner.type === "dot_index_expression" || owner.type === "method_index_expression")) {
+      const field = owner.childForFieldName("field") ?? owner.childForFieldName("method");
+      if (field && this.isSameNode(field, nameNode)) return null;
+    }
+    return nameNode.text;
+  }
+  /**
+   * M60 LUA-54 — mark the standard-library member edges, from ONE post-pass, after
+   * every symbol this file declares is known.
+   *
+   * ## WHAT IT CLAIMS, AND THE MEASUREMENT BEHIND THE CLAIM
+   *
+   * An edge is marked `external` when its target is the field of a member read
+   * whose receiver is an identifier naming one of the eight documented Lua 5.4
+   * standard tables (`string`, `table`, `math`, `io`, `os`, `coroutine`, `debug`,
+   * `utf8` — reference manual §6, transcribed into `LUA54_TABLES`), AND this file
+   * publishes no symbol under that receiver.
+   *
+   * Measured on the whole-corpus draw of 3,252 .lua files from 199 repos
+   * (drawDigest 502ef2f4..., 3,250 parsed, 219,981 relationships, production
+   * `parseFile`): 3,525 edges are marked — 2,738 `calls` and 787 `references` —
+   * out of 219,981, by `script/m60/verify-lua-stdlib-external.mts`. It changes NO
+   * edge count and creates NO edge: the edge digest is `bc0c38b6...` with and
+   * without this method, because the key is additive metadata and every consumer
+   * that ignores it sees the identical graph.
+   *
+   * `script/m60/lua-external-marking.ts` puts the same rule at 3,956 from outside
+   * the analyzer. The 431 difference is the outer instrument keying on LINE,
+   * which credits a hit to every edge on that line — including the 398 `contains`
+   * edges that share a line with a `references` edge and carry no node at all. The
+   * two agree exactly on `calls` at 2,725, so the gap sits entirely in the types
+   * with no node to test, which is what the analyzer can prove.
+   *
+   * ## THE RULE THAT WAS REJECTED, because it is the interesting half
+   *
+   * The first version of this marked any target whose bare name is in a
+   * transcribed stdlib surface — 16,195 edges, 4.1x the above — and it is a
+   * NAME-MATCH GUESS. This analyzer publishes the FINAL SEGMENT of a member read
+   * (LUA-13), so `table.insert(x)` arrives as target `insert`, and a bare
+   * `insert(x)` with no receiver arrives as target `insert` too. Lua 5.4
+   * publishes no global named `insert`, so the name alone cannot tell the standard
+   * library from a user's own global, and marking the second case `external`
+   * would move it out of `unresolved` without moving anything toward truth — the
+   * arbiter's PASS would then mean less than it did. Measured: **0** edge targets
+   * a dotted `table.field` spelling anywhere in the corpus, which is why the name
+   * list cannot recover the receiver from the target.
+   *
+   * ## WHAT IS DELIBERATELY LEFT UNMARKED
+   *
+   * `imports` targets (6,601 on the same draw) are Lua MODULE paths, not
+   * declarations. One file cannot tell a sibling module from a luarocks rock, and
+   * `classb-origin` measured both populations — 2,425 dotted targets whose module
+   * file is in the corpus against 3,060 whose file is absent. Marking all 6,601
+   * would assert the second count for the first.
+   *
+   * UPDATED 2026-10-11 (LUA-55), because the sentence that used to close this
+   * paragraph — "the gate has no bucket for 'this type's target is a module', so they
+   * are reported rather than swept" — stopped being true, and a comment that outlives
+   * its code is this lane's most expensive defect class (LUA-21, 41811754). The gate
+   * HAS a bucket now: `metadata.importProjectFile`, the shared file claim, and
+   * `addImport` writes it. The split above is unchanged and is still why an `isExternal`
+   * MARK is wrong here (1,560 of 5,485 REFUTED) — but the file claim is a different
+   * statement about the same edge, and it is checkable rather than asserted. See
+   * LUA-55 in docs/analyzers/lua.md.
+   */
+  markStdlibExternal(ctx) {
+    if (ctx.stdlibCandidates.length === 0 && ctx.stdlibGlobalCandidates.length === 0) return;
+    const declaredAt = /* @__PURE__ */ new Map();
+    for (const s of ctx.symbols) {
+      const line = Number(s.range?.startLine ?? s.startLine ?? 0);
+      if (!s.name) continue;
+      const arr = declaredAt.get(s.name) ?? [];
+      arr.push(line);
+      declaredAt.set(s.name, arr);
+    }
+    for (const { rel, receiver } of ctx.stdlibCandidates) {
+      if (!LUA54_TABLES.has(receiver)) continue;
+      const line = Number(rel.line_number ?? 0);
+      const lines = declaredAt.get(receiver);
+      if (lines && lines.some((l) => l <= 0 || line > 0 && l <= line)) continue;
+      rel.metadata.external = true;
+      rel.metadata.externalKind = "lua54-stdlib";
+      rel.metadata.externalReceiver = receiver;
+    }
+    for (const { rel, name } of ctx.stdlibGlobalCandidates) {
+      if (!LUA54_GLOBALS.has(name)) continue;
+      const line = Number(rel.line_number ?? 0);
+      const lines = declaredAt.get(name);
+      if (lines && lines.some((l) => l <= 0 || line > 0 && l <= line)) continue;
+      rel.metadata.external = true;
+      rel.metadata.externalKind = "lua54-global";
+    }
+  }
+  /** M60 LUA-43: the evidence tier for a relationship type. See the call site for
+   * why these three words and not a fourth. */
+  evidenceClassFor(type) {
+    if (type === ASTEngine.RelationshipType.Imports || type === ASTEngine.RelationshipType.References) return "import_based";
+    if (type === ASTEngine.RelationshipType.Uses) return "usage_contextual";
+    return "structural";
+  }
+  functionName(node) {
+    return node.childForFieldName("name")?.text || node.namedChild(0)?.text;
+  }
+  hasChildType(node, type) {
+    for (let i = 0; i < node.childCount; i++) if (node.child(i)?.type === type) return true;
+    return false;
+  }
+  isLocalFunction(node) {
+    return this.hasChildType(node, "local");
+  }
+  isLocalVariableDeclaration(node) {
+    return this.hasChildType(node, "local");
+  }
+  /**
+   * The resolvable CONTAINER of a member: the HEAD of the receiver path.
+   *
+   * M60 LUA-37. `function Buffer:initialize()` has receiver `Buffer`; `function
+   * Buffer.meta.index()` has receiver `Buffer.meta`. Returning the receiver's
+   * text verbatim makes the second an owner of `"Buffer.meta"`, which no symbol is
+   * filed under, so the owner still does not resolve. The head is the only part
+   * of the path that is a declared name, and the analyzer already files
+   * `Buffer` as a symbol. Returns undefined for a bare name — a plain function
+   * has no container, and its own name is its scope.
+   */
+  functionOwner(nameNode) {
+    if (!["dot_index_expression", "method_index_expression"].includes(nameNode.type)) return void 0;
+    const recv = nameNode.childForFieldName("table")?.text;
+    if (!recv) return void 0;
+    const head = recv.split(".")[0];
+    return head.length > 0 ? head : void 0;
+  }
+  extractParameters(node) {
+    const list = node.childForFieldName("parameters");
+    if (!list) return [];
+    const parameters = [];
+    for (let i = 0; i < list.namedChildCount; i++) {
+      const child = list.namedChild(i);
+      if (!child) continue;
+      if (child.type === "identifier") parameters.push({ name: child.text, type: "Any" });
+      else if (child.type === "vararg_expression") parameters.push({ name: "...", type: "Any", isVariadic: true });
+    }
+    return parameters;
+  }
+  plainVariableName(node) {
+    return node?.type === "identifier" ? node.text : void 0;
+  }
+  isTableNode(node) {
+    return node?.type === "table_constructor";
+  }
+  assignmentValue(node) {
+    const expressionList = node.childForFieldName("value") || node.namedChild(1);
+    return expressionList?.namedChild(0) || expressionList || void 0;
+  }
+  callArguments(node) {
+    const argumentList = node.childForFieldName("arguments");
+    if (!argumentList) return [];
+    const source = argumentList;
+    const values = [];
+    for (let i = 0; i < source.namedChildCount; i++) {
+      const child = source.namedChild(i);
+      if (child) values.push(child);
+    }
+    return values;
+  }
+  callArgument(node, index) {
+    return this.callArguments(node)[index];
+  }
+  stringValue(node) {
+    if (!node || node.type !== "string") return void 0;
+    return this.cleanLuaString(node.text);
+  }
+  tableFieldNames(node) {
+    const result = [];
+    const fieldList = node;
+    for (let i = 0; i < (fieldList?.namedChildCount || 0); i++) {
+      const field = fieldList?.namedChild(i);
+      if (!field || field.type !== "field") continue;
+      const key = field.childForFieldName("name") || field.namedChild(0);
+      if (key?.text) result.push(key.text);
+    }
+    return result;
+  }
+  // M60 LUA-13 + LUA-01: the callee's NAME and the node that CARRIES ITS LINE
+  // must be the same node, returned together so they cannot drift apart.
+  //
+  // Getting this wrong took three measurements, and each wrong answer was
+  // plausible enough to nearly ship:
+  //   1. `node.text` on the callee — on a call split across lines that is a
+  //      SOURCE SNIPPET ("obj\n  .method"), which the pool-worker's
+  //      garbage-target filter deletes (pool-worker.ts:391 rejects any target
+  //      containing a newline). Consequence: `obj\n.method()` produced NO EDGE
+  //      while the identical one-line call produced one. A line break silently
+  //      removed a call from the graph.
+  //   2. the first identifier in the index expression — that is the RECEIVER
+  //      (`obj`), not the thing called.
+  //   3. the index expression itself — its start is the receiver's line, so
+  //      `obj\n  .method()` reported the `obj` line and the gate caught it.
+  //
+  // The callee of `table . field` / `table : field` is `field`, and `field` is
+  // the LAST named child, so its own start position is the line the method name
+  // is written on — which is exactly M59 (#825)'s rule and exactly what java
+  // gets from `childForFieldName("name")` on its invocation node.
+  // M60 LUA-32: the ONE rule for "is this node a name", shared by the callee
+  // whitelist (LUA-29/LUA-30) and the setmetatable path, so the two cannot drift
+  // apart the way `table_index_expression` did (LUA-27). Three node forms carry a
+  // name; everything else is an expression, and an expression used as a target is
+  // a payload — unmatchable, unreferenceable, and unbounded in shape.
+  //
+  // `dot_index_expression` and `method_index_expression` yield their FULL TEXT
+  // (`Account.Meta`), which is a path rather than a bare name. That is kept
+  // deliberately: these are relationship ENDPOINTS, not symbols, and the
+  // member-identity rule that forbids '.' in a SYMBOL name (verify-lua-member-identity)
+  // is a different contract from what a reference to `Account.Meta` may look like.
+  nameBearing(node) {
+    if (!node) return void 0;
+    if (node.type === "identifier") return node.text;
+    if (node.type === "dot_index_expression" || node.type === "method_index_expression") return node.text;
+    return void 0;
+  }
+  // M60 LUA-56 — WHY THE SHAPE IS RETURNED WITH THE NAME. `calls` is this lane's largest
+  // remaining cause (42,889 not-resolved edges, 30,370 ambiguous + 12,519 unresolved, measured
+  // on the whole admitted population), and the class is TWO mechanisms wearing one label:
+  //
+  //   `foo()`      an IDENTIFIER callee — the name the language looks up through the file's
+  //                lexical scope and then `_ENV`. This is the only shape about which an
+  //                externality question can even be asked, because the target IS the name.
+  //   `M.foo()`    an INDEX callee — `callee()` publishes the FIELD (LUA-13), so the target is a
+  //   `M:foo()`    member name whose CONTAINER the edge does not carry. "declared nowhere in the
+  //   `M["foo"]()` project" is then a statement about a field, not about a global.
+  //
+  // The distinction is DECIDED BY THE BRANCH THAT PRODUCES THE NAME — the same node test that
+  // returns the name decides which form it is — so it is returned from here rather than
+  // re-derived at the call site, where a second copy of the node test could silently drift from
+  // this one. That is the "one spelling, two places" hazard this lane has paid for repeatedly.
+  //
+  // THE TWO KEYS ARE A PARTITION of the `calls` population (every edge carries exactly one), and
+  // they are marker KEYS rather than one value-carrying key on purpose: the gate's marker table
+  // and this lane's own cause reader both group by KEY ONLY ("a value would split one marker into
+  // a signature per symbol it names"), so a fact that must be separable there has to be a key.
+  //
+  // THE THIRD STATE IS DELIBERATE. The fallthrough below publishes a name taken from arbitrary
+  // node text — the payload-as-a-name defect LUA-22/LUA-29/LUA-30 closed for every form the
+  // pinned grammar can produce — and it carries NO shape key. An edge in that state is therefore
+  // visible as a hole (the lane's `calls-file-scope-pricing.mts` reports it as UNPUBLISHED, and a
+  // non-zero reading there means the grammar grew a callee form this whitelist has not seen)
+  // rather than being silently filed under one of the two shapes.
+  callee(functionNode) {
+    if (functionNode.type === "identifier") return { name: functionNode.text, nameNode: functionNode, shapeMark: { calleeIdentifier: true } };
+    if (functionNode.type === "dot_index_expression" || functionNode.type === "method_index_expression") {
+      const last = functionNode.namedChildCount > 0 ? functionNode.namedChild(functionNode.namedChildCount - 1) : void 0;
+      if (last?.text) return { name: last.text, nameNode: last, shapeMark: { calleeIndexed: true } };
+    }
+    if (functionNode.type === "bracket_index_expression") {
+      const field = functionNode.childForFieldName("field");
+      if (field?.type !== "string") return void 0;
+      const literal = this.stringValue(field);
+      return literal ? { name: literal, nameNode: field, shapeMark: { calleeIndexed: true } } : void 0;
+    }
+    if (functionNode.type === "function_call" || functionNode.type === "table_constructor" || functionNode.type === "binary_expression" || functionNode.type === "parenthesized_expression" || functionNode.type === "string" || functionNode.type === "number") return void 0;
+    if (functionNode.text) return { name: functionNode.text, nameNode: functionNode, shapeMark: {} };
+    return void 0;
+  }
+  // M60 LUA-01: reach a child by node TYPE. The five field literals this
+  // analyzer used to ask for (`name_list`, `function`, `expression_list`, `key`)
+  // do not exist in the pinned grammar, and every one of them sat behind a
+  // `|| namedChild(0)` fallback that turned "this field does not exist" into
+  // "quietly use whatever happens to be first" — a wrong answer that could not
+  // raise, log, or fail. Type-directed lookup has no fallback to hide behind:
+  // either the child is there or the path does not run.
+  childOfType(node, type) {
+    if (!node) return void 0;
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type === type) return child;
+    }
+    return void 0;
+  }
+  cleanLuaString(text) {
+    const cleaned = text.trim();
+    if (cleaned.length >= 2) {
+      const first = cleaned[0];
+      const last = cleaned[cleaned.length - 1];
+      if ((first === '"' || first === "'") && first === last) return cleaned.substring(1, cleaned.length - 1);
+    }
+    if (cleaned.startsWith("[[") && cleaned.endsWith("]]")) return cleaned.substring(2, cleaned.length - 2);
+    return cleaned;
+  }
+  // M60 LUA-04: framework detection fired on EVERY identifier node and matched
+  // BARE NAMES — `use`, `setup`, `GetTime`, `C_Timer`, `Proto`, `UIParent`. So a
+  // file containing `local setup = 1` was labelled "Neovim Configuration", and
+  // the committed gate for this defect class caught a probe labelled BOTH
+  // "Neovim Configuration" AND "World of Warcraft Addon" purely from three
+  // ordinary variable names.
+  //
+  // The analyzer's own header claims "No regex fallback or source-wide scanning
+  // is used". A bare-name equality test applied to every identifier is
+  // source-wide scanning wearing an AST costume, so this is a contract failure
+  // and not only a precision one.
+  //
+  // The rule now: a framework is claimed only from a QUALIFIED member access
+  // (`vim.api`, `love.graphics`, `ngx.timer`) or from a `require`d module name
+  // that names it. A bare identifier never names a framework. That is narrower
+  // than the old rule on purpose — and the gate asserts the CONVERSE too, so it
+  // cannot be satisfied by deleting detection: a file that really does use
+  // `vim.api` must still be labelled Neovim.
+  detectFrameworks(text, ctx) {
+    if (!text.includes(".")) return;
+    const head = text.split(".")[0];
+    if (!head) return;
+    if (head === "vim") ctx.frameworks.add("Neovim Configuration");
+    if (head === "love") ctx.frameworks.add("Love2D");
+    if (head === "ngx" || head === "resty") ctx.frameworks.add("OpenResty");
+    if (head === "display" || head === "system" || head === "transition" || head === "Runtime") ctx.frameworks.add("Corona SDK / Solar2D");
+    if (head === "lovr") ctx.frameworks.add("L\xD6VR (VR/AR)");
+    if (head === "redis") ctx.frameworks.add("Redis Scripting");
+  }
+  collectErrors(rootNode, ctx) {
+    if (!rootNode.hasError) return;
+    const stack = [rootNode];
+    while (stack.length) {
+      const node = stack.pop();
+      if (node.type === "ERROR" || node.isMissing) {
+        ctx.errors.push({ message: `Syntax ${node.type} detected.`, range: this.nodeToRange(node), severity: "warning" });
+      }
+      for (let i = node.namedChildCount - 1; i >= 0; i--) {
+        const child = node.namedChild(i);
+        if (child) stack.push(child);
+      }
+    }
+  }
+  calculateCyclomaticComplexity(rootNode) {
+    let complexity = 1;
+    const stack = [rootNode];
+    while (stack.length) {
+      const node = stack.pop();
+      if (node.type === "if_statement" || node.type === "for_statement" || node.type === "while_statement" || node.type === "repeat_statement") complexity++;
+      if (node.type === "binary_expression") {
+        const operator = node.childForFieldName("operator");
+        if (operator?.text === "and" || operator?.text === "or") complexity++;
+      }
+      for (let i = node.namedChildCount - 1; i >= 0; i--) {
+        const child = node.namedChild(i);
+        if (child) stack.push(child);
+      }
+    }
+    return complexity;
+  }
+  // M60 LUA-02: this counted `symbol.metadata?.isCoroutine`, which NO code path
+  // in the analyzer ever set — processCall adds the string "Coroutines" to
+  // ctx.patterns and stops. So the count could only ever read 0, and it was
+  // published as a count. It is now counted from the calls the walk actually
+  // saw: `coroutine.create` and `coroutine.wrap` are ordinary function_call
+  // nodes, so a file that uses them reports a positive number and a file that
+  // does not reports 0 that means something.
+  // M60 LUA-02. Counted during the walk, not afterwards and not from the stored
+  // edges: the edge carries the callee FIELD, so after the LUA-13 fix there is
+  // no relationship whose target is "coroutine.create" — the field is "create".
+  // Two earlier versions of this fix were wrong in ways the gate caught: the
+  // first counted ctx.symbols (a call is not a declaration, so it read 0), the
+  // second counted relationship targets (which no longer exist under that name,
+  // so it also read 0). Counting at the point where the qualified name is still
+  // in hand is the only place the fact exists.
+  countCoroutineSymbols(ctx) {
+    return ctx.coroutineCalls;
+  }
+  // M60 LUA-11: a derived figure, or absent. Returns undefined when there is
+  // nothing to measure rather than a number that means nothing.
+  relationshipDensity(ctx) {
+    if (ctx.symbols.length === 0 && ctx.relationships.length === 0) return void 0;
+    const perSymbol = ctx.symbols.length === 0 ? 0 : ctx.relationships.length / ctx.symbols.length;
+    return Math.max(0, Math.min(100, Math.round(100 - perSymbol * 10)));
+  }
+  retainedRowKb(ctx) {
+    if (ctx.symbols.length === 0 && ctx.relationships.length === 0) return void 0;
+    const SYMBOL_ROW_KB = 0.5;
+    const RELATIONSHIP_ROW_KB = 0.25;
+    const kb = ctx.symbols.length * SYMBOL_ROW_KB + ctx.relationships.length * RELATIONSHIP_ROW_KB;
+    return Math.round(kb * 100) / 100;
+  }
+  // M60 LUA-10: the +5 branch for "Module/Table Pattern" rewarded a string
+  // nothing ever added, so a published score was computed from a dead branch —
+  // and codeQuality thresholds on that score, so the error propagated into a
+  // second published field. The branch is gone rather than wired up: a module
+  // table IS this language's module idiom, so awarding points for it would
+  // award points to most Lua files, which measures nothing.
+  calculateArchitecturalScore(ctx) {
+    let score = 70;
+    if (ctx.relationships.length > 0) score += 10;
+    if (ctx.exports.length > 0) score += 5;
+    if (ctx.patterns.has("Object-Oriented Programming (Metatables)")) score += 10;
+    if (ctx.patterns.has("Object-Oriented Programming (Libraries)")) score += 5;
+    return Math.min(100, score);
+  }
+  assessCodeQuality(ctx) {
+    const score = this.calculateArchitecturalScore(ctx);
+    if (score >= 90) return "excellent";
+    if (score >= 80) return "good";
+    if (score >= 60) return "fair";
+    return "poor";
+  }
+  generateArchitecturalInsights(ctx) {
+    const insights = [];
+    if (ctx.patterns.has("Object-Oriented Programming (Metatables)")) {
+      insights.push({ type: "architecture", category: "lua_oop", message: "Lua object-oriented patterns detected through metatables.", severity: "info" });
+    }
+    return insights;
+  }
+  lineCount(content) {
+    let count = 1;
+    for (let i = 0; i < content.length; i++) if (content[i] === "\n") count++;
+    return count;
+  }
+  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 {
+  RealLuaAnalyzer
+};