@descryy/adapter-python 0.1.0

package/dist/extract.js

@@ -0,0 +1,2267 @@
+/**
+ * Parsed Python to Canonical IR.
+ *
+ * The Python side reports what one file says; everything that needs two files
+ * happens here, where the resolution level is tracked and can be claimed
+ * honestly.
+ *
+ * ## Name binding, which is the whole of R2 for this adapter
+ *
+ * There is no type checker (DEC-062). A name is resolved by building, per file,
+ * the set of module-level bindings that Python itself would build:
+ *
+ *   1. imports — `from .money import format_money` binds `format_money`;
+ *   2. module-level declarations — a `def` or `class` in this file;
+ *   3. module-level instantiations — `service = OrderService()`, the one
+ *      inference made anywhere in this adapter.
+ *
+ * Anything else resolves to nothing and is disclosed. `self.repo.save()`,
+ * `getattr(obj, name)()`, a name rebound in a loop — all absent, all recorded.
+ * That is the recall cost of having no checker, and it is stated rather than
+ * covered with a guess.
+ *
+ * ## The re-export hop
+ *
+ * `from . import validate_order` reaches `src/__init__.py`, which is not where
+ * `validate_order` is defined. Golden pattern 03 requires the edge to terminate
+ * at the definition and explicitly forbids it terminating at the package — the
+ * single most common symbol-resolution bug, and the one the TypeScript adapter
+ * hit three separate times. `followReexport` walks the hop, with a visited set
+ * because `a/__init__.py` importing from `b/__init__.py` importing back is legal
+ * Python and must not hang the run.
+ */
+import { databaseTableNodesFromModel, edgeId, endpointQsp, isTypeLikeNodeType, nodeId, normaliseEndpointPath, symbolQsp, testCaseQsp, } from "@descryy/ir";
+import { importRoots, modulePathOf, moduleNameOf, resolveImport, } from "./module.js";
+import { DECLARATIVE_BASE_FACTORIES, ORM_BASE_MODULES, isFrameworkBaseName, ormShapeOf, } from "./orm.js";
+import { globToRegExp, PYTEST_DEFAULTS } from "./pytest-config.js";
+import { drfShapeOf, dtoShapeOf, isDrfSerializerRoot, isPydanticRoot, isValidatorDecorator, } from "./pydantic.js";
+import { DRF_ACTIONS, drfRegisterCallsIn, drfRouterLocalsIn, djangoUrlEntriesIn, HTTP_METHODS, isApplicationRouter, joinPath, mountsIn, odooRouteFromDecorator, routeFromDecorator, routersIn, } from "./routes.js";
+import { GRAPHQL_METHOD, fieldFromMethod, fieldsFromAttributes, operationPath, schemaDeclsIn, } from "./graphql.js";
+import { clientCallsIn, clientLocalsIn } from "./client.js";
+export const LANGUAGE = "python";
+/**
+ * Confidence by the level an edge's evidence earned — never by the level the
+ * run reached. DEC-058: those were two different notions in the first adapter,
+ * and 83% of its edges claimed a level they had not earned.
+ */
+const CONFIDENCE = { 0: 0.5, 1: 0.7, 2: 0.9, 3: 0.95 };
+const REASONS = {
+    outside: "resolves to a name this run did not analyse — the standard library, an installed package, " +
+        "or a module outside the analysed set. A scope boundary, not an analysis gap.",
+    unknown: "no resolvable binding — the receiver's type is not inferable without a checker, or the " +
+        "target is chosen at runtime. This adapter has no type checker (DEC-062).",
+    unrecognisedTest: "this is in a file a test runner would collect and it looks like a test case, but no test " +
+        "style this adapter understands matched it. NOT the same as 'this code has no tests' — it " +
+        "means this adapter could not read the tests that are there.",
+    testDiscoveryFailed: "TEST DISCOVERY PRODUCED NOTHING. This repository contains files a test runner would " +
+        "collect, and this run emitted no test cases at all. Any statement that code here is " +
+        "untested is UNSUPPORTED — the correct statement is that this adapter could not read the " +
+        "tests. Check the collection rules named in this row against the project's own config.",
+    testDiscoveryPartial: "test discovery is incomplete: files a test runner would collect produced no test case. " +
+        "Coverage claims over this repository are capped by the ratio in this row.",
+    routeReceiverUnknown: "this decorator is spelled like an HTTP route, but its receiver does not resolve to a " +
+        "router or application constructed from a web framework's own module. Reading it as a " +
+        "route on the strength of the verb alone would invent 1,150 routes on saleor, where every " +
+        "one is `unittest.mock.patch`.",
+    routePathNotLiteral: "the route's path is written as an expression rather than a literal, so the path it serves " +
+        "is not knowable from source. Emitting a route here would attach a caller to an endpoint " +
+        "that does not exist, and nothing above the graph could tell that from a correct edge.",
+    routePrefixNotLiteral: "the route's path is a literal, but a prefix somewhere in its mount chain is not, so the " +
+        "served path cannot be assembled. The route exists; where it is served is unreadable.",
+    callPathNotLiteral: "an HTTP call whose request path is not a literal or an f-string. The call is real and its " +
+        "target is assembled somewhere this reader cannot follow, so no endpoint is claimed for it.",
+    callPathNotRelative: "an HTTP call to an absolute URL, which names a host this repository does not serve. Read " +
+        "correctly and out of scope for the join rather than unreadable — there is no route on this " +
+        "side for it to meet.",
+    callMethodNotLiteral: "a requests.request()/httpx.request() call whose verb is not a literal, so no single method " +
+        "describes it. Refused rather than filed under a guess.",
+    callBaseUnresolved: "an HTTP call written as f\"{BASE}/path\" whose base this file does not bind to a string " +
+        "literal. The path half is readable and the base half is not, so the served template cannot " +
+        "be assembled — the named base is the piece of work that would close it.",
+    callBaseIsExternalHost: "an HTTP call written as f\"{BASE}/path\" whose base resolves to an absolute URL on another " +
+        "host. Read correctly and out of scope for the join: an endpoint is identified by method and " +
+        "path with no host (DEC-014), so claiming one here would let this caller join a local route " +
+        "of the same path that it never reaches.",
+    callPathFromLocal: "an HTTP call whose path is a local assembled earlier in the function. Distinguished from an " +
+        "opaque path because it is reachable by further work, and filing the two together would " +
+        "report one number for two populations.",
+    routeNeverMounted: "this route is declared on a router that no source file mounts, so the path it serves is " +
+        "unknowable. Commonly a plugin router mounted by the framework at runtime.",
+    routeIdCollision: "this route's method and path are identical to one already emitted, so it collapsed onto " +
+        "the same API_ROUTE node and this declaration's own SERVES_API edge and location were " +
+        "dropped. The endpoint is real; this specific declaration is not the one the graph kept.",
+    djangoPathNotLiteral: "a Django path()/re_path()/url() call whose route is written as anything but a literal — " +
+        "or, for re_path()/url(), a regex this reader will not translate because it is not just a " +
+        "literal segment with named groups. Emitting a route here would attach a caller to a path " +
+        "that does not exist.",
+    djangoIncludeUnresolved: "a Django include(...) whose target module string does not resolve to a file this run " +
+        "analysed — an installed app, a module outside the analysed set, or a name this reader does " +
+        "not evaluate (a computed string, a (module, namespace) tuple). The routes behind it are real " +
+        "and unreadable from here.",
+    odooPathNotLiteral: "an @http.route(...) whose path is written as anything but a literal, so the path it serves " +
+        "is not knowable from source.",
+    odooMethodsNotLiteral: "an @http.route(...) whose methods= is written but not readable as a list of literals — " +
+        "defaulting to GET here would report the opposite of the source as fact.",
+    graphqlFieldNameNotReadable: "a declared strawberry root-operation field whose SCHEMA-FACING name cannot be read out of " +
+        "the source. strawberry's default is auto_camel_case=True, so `circuit_list` in Python is " +
+        "`circuitList` on the wire — and this run could not resolve the schema's StrawberryConfig to " +
+        "a written boolean, so which of the two the server actually serves is not stated anywhere " +
+        "this reader can see. The field is real; its name is unreadable. Computing it from the " +
+        "library's default would write down a string that appears nowhere in the repository, and a " +
+        "consumer reading the real wire name would mint a different id and join nothing — DEC-055's " +
+        "failure mode exactly. Fixed at the source by writing an explicit name= on the field, or by " +
+        "passing config=StrawberryConfig(auto_camel_case=...) as a literal at the schema call.",
+    graphqlRootBaseUnreadable: "a strawberry root operation class inherits from a base this reader cannot resolve to an " +
+        "analysed class — a starred unpacking of a plugin registry, or a name outside the analysed " +
+        "set. Every field that base contributes is a real operation and none of them are in this " +
+        "graph. A recall gap on this root, not a reason to drop the bases that did resolve.",
+    graphqlRootSlotUnreadable: "a strawberry.Schema(...) whose query=/mutation=/subscription= slot is written as something " +
+        "other than a bare class name, so the root type it puts in that slot cannot be followed. " +
+        "The operations under it are real and unreadable from here.",
+};
+// --- pytest -----------------------------------------------------------------
+/**
+ * pytest's own default collection rule, not a guess about intent.
+ *
+ * `test_*.py` files, `test_*` functions, `Test*` classes — a documented,
+ * machine-checkable convention, which is the same standing `describe`/`it` have
+ * in the TypeScript adapter. It is a world away from deciding that a class is a
+ * `MODEL` because of its name (DEC-043): the runner will genuinely collect these
+ * and will genuinely not collect anything else.
+ */
+function isPytestFile(file, config) {
+    const base = file.split("/").pop() ?? "";
+    return config.filePatterns.some((pattern) => globToRegExp(pattern).test(base));
+}
+/**
+ * Could this file hold tests, **independently of what the project's config says**?
+ *
+ * This is the file gate for the *safety net*, and it must not be the gate that
+ * emits nodes. The two were the same predicate, and that is precisely why Sentry
+ * went dark: one malformed `python_files` value made `isPytestFile` false for
+ * every file in the repository, so the net that exists to catch a failed
+ * understanding was switched off by the same failure it was built to report.
+ * **A safety net wired to the thing it is protecting against is not a safety net.**
+ *
+ * Three independent signals, unioned:
+ *
+ * 1. the project's own configured patterns — the normal case;
+ * 2. pytest's documented defaults, which hold whatever a project misconfigures;
+ * 3. a `test`/`tests` path segment, which catches a project that renames its
+ *    files entirely but still keeps them where every runner looks.
+ *
+ * Signals 2 and 3 are what make this survive a configuration this adapter reads
+ * wrongly, reads partially, or cannot read at all.
+ */
+function couldHoldTests(file, config) {
+    if (isPytestFile(file, config))
+        return true;
+    const base = file.split("/").pop() ?? "";
+    if (PYTEST_DEFAULTS.filePatterns.some((pattern) => globToRegExp(pattern).test(base)))
+        return true;
+    return file.split("/").slice(0, -1).some((segment) => segment === "test" || segment === "tests");
+}
+/**
+ * Modules whose classes are test bases, so a subclass is a suite whatever it is
+ * called. **Provenance beats naming**: `unittest.IsolatedAsyncioTestCase` does
+ * not end in `TestCase`, and a rule that matched on the name missed six of
+ * sherpa-backend's tests even after it was taught about `unittest`.
+ *
+ * The list is short on purpose. It is not the mechanism that has to be complete
+ * — rule 2 covers unlisted libraries by name and rule 3 covers in-repo bases —
+ * and anything all three miss is disclosed to the ledger rather than dropped.
+ */
+const TEST_LIBRARY_MODULES = new Set([
+    "unittest",
+    "unittest.case",
+    "unittest.async_case",
+    "unittest2",
+    "asynctest",
+    "django.test",
+    "rest_framework.test",
+    "tornado.testing",
+    "twisted.trial.unittest",
+    "absl.testing.absltest",
+    "absl.testing.parameterized",
+]);
+/**
+ * Does this declaration *look* like a test case, whether or not we can model it?
+ *
+ * **This is deliberately broader than every rule that emits a node**, and that
+ * gap is the whole point. Measured over seven Python codebases, test detection
+ * fails all-or-nothing per repository rather than evenly: `pandas` is at 99.6%
+ * and `sherpa-backend` and PySpark are at 0% and 0.1%. A repository whose style
+ * we do not handle goes completely dark, and with no disclosure the report says
+ * *"no tests cover this code"* when the truth is *"this adapter did not read
+ * your tests"* — §20.2's two different statements, collapsed into the wrong one.
+ *
+ * Anything matching here and *not* becoming a `TEST_CASE` is written to the
+ * ledger. That converts a silent wrong answer into a counted gap, and unlike
+ * every other fix on this list it holds for test styles nobody has thought of
+ * yet — which is the only kind of protection worth having against the next
+ * repository.
+ *
+ * The file gate is the runner's own rule, so a production function that happens
+ * to be called `test_odoo_connection` is not swept in. That was a real false
+ * positive in the survey that produced these numbers.
+ */
+function looksLikeTestCase(declaration, file, config) {
+    // **The project's own rule, deliberately — not the wider `couldHoldTests`.**
+    // This net answers "a test style we cannot model", and a project that declares
+    // `python_files = ["check_*.py"]` has genuinely excluded `test_ignored.py`;
+    // flagging it would be a gap that is not a gap. The wholesale case — a
+    // configuration this adapter reads wrongly, so *nothing* matches — is caught
+    // by the repository-level audit at the end of `extract`, which is
+    // config-independent precisely because this predicate is not.
+    if (declaration.kind !== "function" || !isPytestFile(file, config))
+        return false;
+    const own = declaration.path[declaration.path.length - 1] ?? "";
+    if (!config.functionPrefixes.some((prefix) => own.startsWith(prefix)))
+        return false;
+    // **A runner collects a module-level function or one method of a class, and
+    // nothing deeper.** Without this the net reported PySpark's
+    // `test_scalar_iter_udf_close.test_close` — a helper defined *inside* a test
+    // method — as a test it could not read. Over-reporting is the safer direction
+    // for a safety net, but a gap that is not a gap still costs the reader trust.
+    if (declaration.path.length > 2)
+        return false;
+    // Nor does a runner collect a property. `HasThrowableProperty.test_property`
+    // is a `@property` on an ordinary helper class, and it is not a test.
+    return !(declaration.decorators ?? []).some((decorator) => {
+        const leaf = (decorator ?? "").split(".").pop() ?? "";
+        return leaf === "property" || leaf === "cached_property";
+    });
+}
+/**
+ * Which of two declarations of one name should own the node.
+ *
+ * A `@typing.overload` stub is never the answer — it has no body worth pointing
+ * at. A `@property` getter is preferred to its setter, because the getter is
+ * what the name evaluates to. Otherwise the widest span, which is deterministic
+ * and picks the more complete of two conditional definitions.
+ */
+function preferredDeclaration(a, b) {
+    const decorated = (entry, leaf) => (entry.declaration.decorators ?? []).some((d) => (d ?? "").split(".").pop() === leaf);
+    const stub = (entry) => decorated(entry, "overload");
+    if (stub(a) !== stub(b))
+        return stub(a) ? b : a;
+    const getter = (entry) => decorated(entry, "property");
+    if (getter(a) !== getter(b))
+        return getter(a) ? a : b;
+    const width = (entry) => entry.range.endLine - entry.range.startLine;
+    return width(b) > width(a) ? b : a;
+}
+/** Names an annotation mentions, as written. `Optional[Order]` -> ["Optional", "Order"]. */
+function typeNamesIn(annotation) {
+    if (annotation === null || annotation === undefined)
+        return [];
+    return [...new Set(annotation.match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? [])];
+}
+/** `Optional[str]`, `str | None` and `None` are the three ways Python writes nullable. */
+function isNullable(annotation, hasDefault) {
+    if (annotation === null || annotation === undefined)
+        return hasDefault;
+    return /\bOptional\s*\[/.test(annotation) || /\bNone\b/.test(annotation) || hasDefault;
+}
+/**
+ * The graph to return when the parse produced nothing but the files are there.
+ *
+ * **A failed analysis must not look like an empty repository.** The two were
+ * indistinguishable, and home-assistant-core and posthog each came back with 0
+ * nodes over ~18,000 files and a successful R0 status.
+ *
+ * A `MODULE` per file is honest at R0 and needs no parse: the file exists and
+ * its module path is a fact about the filesystem. It also gives the disclosure
+ * a real node to hang from — the ledger requires a valid `fromNodeId`, and the
+ * first attempt at this invented one and was rightly rejected by the Normaliser
+ * as `MALFORMED_UNRESOLVED_REF`, which would have thrown away the very warning
+ * it was carrying.
+ *
+ * The result reads as what it is: every module present, every module empty, and
+ * one row saying loudly why.
+ */
+export function degradedGraph(input) {
+    const scope = { repo: input.repo, workspace: input.workspace };
+    const nodes = input.files.map((file) => {
+        const modulePath = modulePathOf(file);
+        return {
+            id: nodeId(scope, "MODULE", symbolQsp(input.packageName, modulePath), LANGUAGE),
+            type: "MODULE",
+            name: moduleNameOf(file),
+            file,
+            range: { startLine: 1, endLine: 1 },
+            language: LANGUAGE,
+            producedBy: input.producedBy,
+            resolution: 0,
+            attrs: { parsed: false },
+        };
+    });
+    const anchor = nodes[0];
+    const unresolved = anchor === undefined
+        ? []
+        : [
+            {
+                fromNodeId: anchor.id,
+                edgeType: "IMPORTS",
+                rawTarget: "(entire repository)",
+                file: anchor.file,
+                line: 1,
+                producedBy: input.producedBy,
+                reason: `NO GRAPH WAS PRODUCED for ${input.files.length} Python file(s). ${input.cause}. ` +
+                    "Modules are listed because their paths are a fact about the filesystem; their " +
+                    "contents are absent. Every finding, coverage figure and 'not affected' statement " +
+                    "over this repository is UNSUPPORTED — this is a failed analysis, not an empty " +
+                    "repository.",
+            },
+        ];
+    return { nodes, edges: [], unresolved };
+}
+export function extract(input) {
+    const scope = { repo: input.repo, workspace: input.workspace };
+    const pytest = input.pytest ?? PYTEST_DEFAULTS;
+    const files = Object.keys(input.parsed.files).sort();
+    const known = new Set(files);
+    const roots = importRoots(files);
+    const pkg = input.packageName;
+    const nodes = [];
+    const edges = [];
+    const unresolved = [];
+    const seenEdge = new Set();
+    /** file -> declaration name (first segment) -> Declared */
+    const declaredIn = new Map();
+    /** node id -> the entry owning it, where it sits in `nodes`, and how many
+     *  source declarations merged into it. */
+    const emittedById = new Map();
+    /** Node ids that are type aliases rather than real classes — see the RETURNS pass. */
+    const aliasIds = new Set();
+    const bindingsOf = new Map();
+    const importsResolved = new Map();
+    /**
+     * Import resolution, memoised.
+     *
+     * An absolute specifier is tried against **every import root**, and posthog
+     * has 2,288 of them against home-assistant-core's 24 — a repository's layout,
+     * not its size, decides how expensive one import is. The same specifier also
+     * repeats across thousands of files: `from django.db import models` resolves
+     * identically wherever it appears.
+     *
+     * The key holds everything the result depends on. For an absolute import that
+     * is the specifier alone. For a relative one it is also the importing file's
+     * *package path*, because `from . import x` means different things in
+     * different packages — keying relative imports on the specifier alone would
+     * be a correctness bug, not an optimisation.
+     */
+    const resolutionCache = new Map();
+    const resolveImportCached = (record, fromFile) => {
+        const anchor = record.level > 0
+            ? `${fromFile.endsWith("__init__.py") ? "p" : "m"}:${modulePathOf(fromFile).join(".")}`
+            : "";
+        const key = `${record.level}|${record.module ?? ""}|${record.name ?? ""}|${anchor}`;
+        let target = resolutionCache.get(key);
+        if (target === undefined) {
+            target = resolveImport(record, fromFile, { known, roots });
+            resolutionCache.set(key, target);
+        }
+        return target;
+    };
+    for (const file of files) {
+        const parsed = input.parsed.files[file];
+        const bindings = new Map();
+        bindingsOf.set(file, bindings);
+        const resolutions = [];
+        importsResolved.set(file, resolutions);
+        for (const record of parsed.imports) {
+            const target = resolveImportCached(record, file);
+            resolutions.push({ record, target });
+            if (target.file === undefined)
+                continue;
+            bindings.set(record.local, {
+                file: target.file,
+                symbol: target.symbol,
+                viaPackageInit: target.viaPackageInit,
+                record,
+            });
+        }
+    }
+    // --- which classes are test suites, decided from evidence not from names ---
+    /** file -> top-level class name -> the bases it was written with. */
+    const basesOf = new Map();
+    for (const file of files) {
+        const byName = new Map();
+        basesOf.set(file, byName);
+        for (const declaration of input.parsed.files[file].declarations) {
+            if (declaration.kind !== "class" || declaration.path.length !== 1)
+                continue;
+            byName.set(declaration.path[0], (declaration.bases ?? []).map((base) => base ?? ""));
+        }
+    }
+    /** The file a bare class name resolves to, following package re-exports. */
+    function classFileOf(startFile, name, depth = 0) {
+        if (depth > 8)
+            return undefined;
+        if (basesOf.get(startFile)?.has(name) === true)
+            return startFile;
+        const binding = bindingsOf.get(startFile)?.get(name);
+        if (binding === undefined)
+            return undefined;
+        return classFileOf(binding.file, binding.symbol ?? name, depth + 1);
+    }
+    /**
+     * Is this class a test suite?
+     *
+     * Three rules, in strength order, and the third is the one that matters at
+     * scale. Measured over seven Python codebases: **2,158 of PySpark's 2,282 test
+     * cases inherit from a shared in-repo base rather than from the test library
+     * directly**, so rules 1 and 2 alone would leave that repository at 5%. Teams
+     * write one base class and hang hundreds of tests off it; following the chain
+     * is not a refinement of this fix, for such a repository it *is* the fix.
+     *
+     * 1. **The base came from a test library.** Where a name came from is written
+     *    in the imports and is not a guess. This catches `IsolatedAsyncioTestCase`
+     *    and anything the library adds next, which name matching never will.
+     * 2. **The base's own name ends in `TestCase`.** The one name rule kept, and
+     *    kept deliberately: it covers Django's `SimpleTestCase`, DRF's
+     *    `APITestCase` and every library nobody has listed, at the cost of a
+     *    class that ends in `TestCase` and is not one — which would be a strange
+     *    thing to write.
+     * 3. **The base is a class in the analysed set that is itself a suite.**
+     *    Recursive and cross-file. `seen` guards the cycles that legal Python
+     *    permits through circular package imports.
+     */
+    function isTestSuiteClass(file, name, seen = new Set()) {
+        const key = `${file}:${name}`;
+        if (seen.has(key) || seen.size > 32)
+            return false;
+        seen.add(key);
+        const bases = basesOf.get(file)?.get(name);
+        if (bases === undefined)
+            return false;
+        const parsed = input.parsed.files[file];
+        for (const base of bases) {
+            if (base === "")
+                continue;
+            const root = base.split(".")[0];
+            const leaf = base.split(".").pop();
+            // 1 — provenance.
+            const fromTestLibrary = parsed.imports.some((record) => {
+                const module = record.module ?? "";
+                if (!TEST_LIBRARY_MODULES.has(module))
+                    return false;
+                // `import unittest` binds the module; `from unittest import TestCase`
+                // binds the symbol. Either way the local name is what the base uses.
+                return record.local === root || record.local === leaf;
+            });
+            if (fromTestLibrary)
+                return true;
+            // 2 — the one name rule kept.
+            if (leaf.endsWith("TestCase"))
+                return true;
+            // 3 — the chain, across files.
+            const owner = classFileOf(file, leaf);
+            if (owner !== undefined && isTestSuiteClass(owner, leaf, seen))
+                return true;
+        }
+        return false;
+    }
+    // --- which classes are ORM models, decided from evidence not from names ----
+    //
+    // The same three-rule shape as `isTestSuiteClass`, with rule 2 deliberately
+    // removed. That rule is a name rule — a base whose name ends in `TestCase` —
+    // and it is affordable there because being wrong misfiles a test. Being wrong
+    // here mints a `MODEL` that no table backs, and every data-propagation
+    // traversal above the graph then reasons about a database column that does not
+    // exist. Provenance, or a chain that reaches provenance, is the only entry.
+    /** Names bound at module level to the result of a declarative-base factory. */
+    const declarativeBases = new Map();
+    for (const file of files) {
+        const parsed = input.parsed.files[file];
+        const bound = new Set();
+        for (const instantiation of parsed.instantiations) {
+            if (instantiation.scope.length !== 0)
+                continue;
+            const leaf = instantiation.typeName.split(".").pop() ?? "";
+            if (!DECLARATIVE_BASE_FACTORIES.has(leaf))
+                continue;
+            // Provenance again: `declarative_base` has to have come from SQLAlchemy.
+            // A project is entitled to a function of its own by that name.
+            const fromSqlAlchemy = parsed.imports.some((record) => ORM_BASE_MODULES.sqlalchemy.has(record.module ?? "") &&
+                (record.local === leaf || record.local === instantiation.typeName.split(".")[0]));
+            if (fromSqlAlchemy)
+                bound.add(instantiation.local);
+        }
+        declarativeBases.set(file, bound);
+    }
+    /**
+     * Which ORM, if any, declared this class — following bases across files.
+     *
+     * `seen` guards the cycles circular package imports make legal, exactly as it
+     * does for test suites.
+     */
+    function ormFrameworkOf(file, name, seen = new Set()) {
+        const key = `${file}:${name}`;
+        if (seen.has(key) || seen.size > 32)
+            return null;
+        seen.add(key);
+        const bases = basesOf.get(file)?.get(name);
+        if (bases === undefined)
+            return null;
+        const parsed = input.parsed.files[file];
+        for (const base of bases) {
+            if (base === "")
+                continue;
+            const root = base.split(".")[0];
+            const leaf = base.split(".").pop();
+            // 1 — provenance. Written in the import statement, so a model is
+            // recognisable at R0; only rule 3 needs imports resolved.
+            for (const framework of ["sqlalchemy", "django"]) {
+                if (!isFrameworkBaseName(leaf, framework))
+                    continue;
+                const fromFramework = parsed.imports.some((record) => {
+                    if (!ORM_BASE_MODULES[framework].has(record.module ?? ""))
+                        return false;
+                    return record.local === root || record.local === leaf;
+                });
+                if (fromFramework)
+                    return framework;
+            }
+            // 2 — a module-level declarative base, which is what SQLAlchemy 1.x makes
+            // the base of every model in the project.
+            if (declarativeBases.get(file)?.has(root) === true)
+                return "sqlalchemy";
+            // 3 — the chain, across files. A project's own `class BaseModel(Base)`.
+            const owner = classFileOf(file, leaf);
+            if (owner !== undefined) {
+                const inherited = ormFrameworkOf(owner, leaf, seen);
+                if (inherited !== null)
+                    return inherited;
+                if (declarativeBases.get(owner)?.has(leaf) === true)
+                    return "sqlalchemy";
+            }
+        }
+        return null;
+    }
+    /**
+     * Does this class's base chain reach a Pydantic root?
+     *
+     * Recursive and **across files**, for the reason DEC-073 recorded about test
+     * suites: real code declares one `DispatchBase(BaseModel)` and inherits from
+     * it everywhere else. Rules that only read a direct base would find 1 model
+     * on dispatch instead of 449.
+     */
+    const pydanticVerdict = new Map();
+    function isPydanticClass(file, name, seen = new Set()) {
+        const key = `${file}:${name}`;
+        const cached = pydanticVerdict.get(key);
+        if (cached !== undefined)
+            return cached;
+        if (seen.has(key) || seen.size > 32)
+            return false; // a cycle is legal to write
+        seen.add(key);
+        // `basesOf` and `classFileOf` are DEC-073's pass 0, built before any node
+        // type is decided precisely so a base can be followed across files while
+        // this question is being asked. Reaching for `declaredIn` here instead
+        // would read a table that pass 1 is still filling in, and the answer would
+        // depend on the order files happen to be walked.
+        const bases = basesOf.get(file)?.get(name);
+        if (bases === undefined) {
+            pydanticVerdict.set(key, false);
+            return false;
+        }
+        const parsed = input.parsed.files[file];
+        let answer = false;
+        for (const base of bases) {
+            if (base === "")
+                continue;
+            const root = base.split(".")[0].split("[")[0];
+            const leaf = base.split(".").pop().split("[")[0];
+            // 1 — provenance. `from pydantic import BaseModel` binds the symbol;
+            // `import pydantic` binds the module and the base reads `pydantic.BaseModel`.
+            const record = parsed.imports.find((r) => r.local === root || r.local === leaf);
+            const origin = record === undefined ? undefined : (record.module ?? record.name ?? undefined);
+            if (isPydanticRoot(base, origin)) {
+                answer = true;
+                break;
+            }
+            // 2 — no name rule. `orm.ts` removed the one `isTestSuiteClass` keeps,
+            // and for the same reason: a wrong `MODEL` claims a table that does not
+            // exist, and a wrong `DTO` claims a wire format that does not exist.
+            // A class called `BaseModel` proves nothing.
+            // 3 — the chain, across files. This is where 448 of dispatch's 449 come
+            // from: real code declares one `DispatchBase(BaseModel)` and inherits it.
+            const owner = classFileOf(file, leaf);
+            if (owner !== undefined && isPydanticClass(owner, leaf, seen)) {
+                answer = true;
+                break;
+            }
+        }
+        pydanticVerdict.set(key, answer);
+        return answer;
+    }
+    /**
+     * Does this class's base chain reach a DRF serializer root? Same
+     * across-file chain walk as `isPydanticClass`, against a different root
+     * set — a project's own `OrderSerializerBase(serializers.ModelSerializer)`
+     * needs the same following.
+     */
+    const drfVerdict = new Map();
+    function isDrfSerializerClass(file, name, seen = new Set()) {
+        const key = `${file}:${name}`;
+        const cached = drfVerdict.get(key);
+        if (cached !== undefined)
+            return cached;
+        if (seen.has(key) || seen.size > 32)
+            return false;
+        seen.add(key);
+        const bases = basesOf.get(file)?.get(name);
+        if (bases === undefined) {
+            drfVerdict.set(key, false);
+            return false;
+        }
+        const parsed = input.parsed.files[file];
+        let answer = false;
+        for (const base of bases) {
+            if (base === "")
+                continue;
+            const root = base.split(".")[0].split("[")[0];
+            const leaf = base.split(".").pop().split("[")[0];
+            const record = parsed.imports.find((r) => r.local === root || r.local === leaf);
+            const origin = record === undefined ? undefined : (record.module ?? record.name ?? undefined);
+            if (isDrfSerializerRoot(base, origin)) {
+                answer = true;
+                break;
+            }
+            const owner = classFileOf(file, leaf);
+            if (owner !== undefined && isDrfSerializerClass(owner, leaf, seen)) {
+                answer = true;
+                break;
+            }
+        }
+        drfVerdict.set(key, answer);
+        return answer;
+    }
+    /** The validated shape of a class, or `null` where nothing declares one. */
+    function dtoShapeOfDeclaration(file, declaration) {
+        if (declaration.kind !== "class" || declaration.path.length !== 1)
+            return null;
+        if (isPydanticClass(file, declaration.path[0])) {
+            const validators = input.parsed.files[file].declarations.filter((other) => other.kind === "function" &&
+                other.path.length === 2 &&
+                other.path[0] === declaration.name &&
+                (other.decorators ?? []).some((d) => isValidatorDecorator(d))).length;
+            return dtoShapeOf({
+                attributes: declaration.attributes ?? [],
+                annotatedFields: declaration.fields ?? [],
+                validatorCount: validators,
+            });
+        }
+        if (isDrfSerializerClass(file, declaration.path[0])) {
+            return drfShapeOf({ attributes: declaration.attributes ?? [] });
+        }
+        return null;
+    }
+    /** The mapped shape of a class, or `null` where nothing declares one. */
+    function ormModelOf(file, declaration) {
+        if (declaration.kind !== "class" || declaration.path.length !== 1)
+            return null;
+        const framework = ormFrameworkOf(file, declaration.path[0]);
+        if (framework === null)
+            return null;
+        const meta = input.parsed.files[file].declarations.find((other) => other.kind === "class" && other.name === `${declaration.name}.Meta`)?.attributes ?? [];
+        return ormShapeOf({ framework, attributes: declaration.attributes ?? [], meta });
+    }
+    /** Is this declaration a test case any supported runner would collect? */
+    function isTestCase(declaration, file) {
+        if (declaration.kind !== "function" || !isPytestFile(file, pytest))
+            return false;
+        const own = declaration.path[declaration.path.length - 1];
+        // The prefixes are the repository's, not this adapter's. `python_files`,
+        // `python_classes` and `python_functions` are pytest's to define and a
+        // project's to change, and a hard-coded `test` is the same class of mistake
+        // as deciding a suite by its name.
+        if (!pytest.functionPrefixes.some((prefix) => own.startsWith(prefix)))
+            return false;
+        if (declaration.path.length === 1)
+            return true;
+        if (declaration.path.length !== 2)
+            return false;
+        // pytest's plain-class convention, then the unittest family. pytest itself
+        // collects a `unittest` subclass whatever it is called, so the name rule
+        // alone was never the framework's own rule.
+        const suite = declaration.path[0];
+        return (pytest.classPrefixes.some((prefix) => suite.startsWith(prefix)) ||
+            isTestSuiteClass(file, suite));
+    }
+    /** node id -> the mapped shape that promoted it, for the passes that come later. */
+    const ormShapes = new Map();
+    /** node id -> the validated shape that promoted it to a `DTO`. */
+    const dtoShapes = new Map();
+    /** Route and endpoint ids already emitted — two routers may serve one path. */
+    const routeSeen = new Set();
+    /** file -> full dotted name -> Declared, so `OrderService.calculate_total` is reachable. */
+    const byFullName = new Map();
+    const moduleNodeId = new Map();
+    const push = (edge, level) => {
+        const key = edgeId(edge.from, edge.to, edge.type);
+        if (seenEdge.has(key))
+            return;
+        seenEdge.add(key);
+        edges.push({
+            ...edge,
+            resolution: level,
+            confidence: CONFIDENCE[level] ?? 0.5,
+            producedBy: input.producedBy,
+        });
+    };
+    const disclose = (from, edgeType, rawTarget, file, line, reason, attrs) => {
+        unresolved.push({
+            fromNodeId: from.id,
+            edgeType,
+            rawTarget,
+            file,
+            line,
+            producedBy: input.producedBy,
+            reason: REASONS[reason],
+            ...(attrs === undefined ? {} : { attrs }),
+        });
+    };
+    // --- pass 1: nodes --------------------------------------------------------
+    for (const file of files) {
+        const parsed = input.parsed.files[file];
+        const modulePath = modulePathOf(file);
+        const moduleId = nodeId(scope, "MODULE", symbolQsp(pkg, modulePath), LANGUAGE);
+        moduleNodeId.set(file, moduleId);
+        // DEC-124: envReads/envDynamicReads/migrationOps carry on MODULE, not
+        // FILE — no shipped adapter emits a FILE node, so that carrier was
+        // silently dead everywhere.
+        const fileScopedAttrs = {
+            ...(parsed.envReads !== undefined && parsed.envReads.length > 0 ? { envReads: parsed.envReads } : {}),
+            ...(parsed.envDynamicReads !== undefined && parsed.envDynamicReads > 0
+                ? { envDynamicReads: parsed.envDynamicReads }
+                : {}),
+            ...(parsed.migrationOps !== undefined && parsed.migrationOps.length > 0
+                ? { migrationOps: parsed.migrationOps }
+                : {}),
+        };
+        nodes.push({
+            id: moduleId,
+            type: "MODULE",
+            name: moduleNameOf(file),
+            file,
+            range: { startLine: 1, endLine: 1 },
+            language: LANGUAGE,
+            producedBy: input.producedBy,
+            resolution: 0,
+            attrs: { ...(file.endsWith("__init__.py") ? { declarationForm: "package" } : {}), ...fileScopedAttrs },
+        });
+        const byName = new Map();
+        const byFull = new Map();
+        declaredIn.set(file, byName);
+        byFullName.set(file, byFull);
+        for (const declaration of parsed.declarations) {
+            // A pytest case is a plain `def`, unlike `it("…", fn)` which is a call and
+            // declares nothing. Emitting both a FUNCTION and a TEST_CASE for it would
+            // put two nodes of the same name in one file, which the conformance
+            // binder correctly refuses to choose between (DEC-039) — a self-inflicted
+            // ambiguity rather than a real one.
+            const isCase = isTestCase(declaration, file);
+            // **A `MODEL` is a promotion, not a second node.** Emitting both a `CLASS`
+            // and a `MODEL` for one declaration would put two ids in the graph for one
+            // thing, and because the two ids differ the duplicate audit cannot see it —
+            // the same silence that let two RSpec examples share one node's edges.
+            const orm = ormModelOf(file, declaration);
+            // A `DTO` is the same kind of promotion as a `MODEL` and is decided the
+            // same way — by provenance. `orm` wins where both somehow apply: a class
+            // that maps a table *and* validates a request is primarily the table,
+            // because a wrong `MODEL` is a claim about a database and a wrong `DTO`
+            // is a claim about a wire format. Measured on both repositories: the
+            // overlap is zero, so this is a tie-break that has never fired.
+            const dto = orm === null ? dtoShapeOfDeclaration(file, declaration) : null;
+            const type = isCase
+                ? "TEST_CASE"
+                : declaration.kind === "class"
+                    ? orm !== null
+                        ? "MODEL"
+                        : dto !== null
+                            ? "DTO"
+                            : "CLASS"
+                    : "FUNCTION";
+            const suite = declaration.path.length === 2 ? [declaration.path[0]] : [];
+            // The package root belongs in a test's identity for the same reason it
+            // belongs in a symbol's (DEC-047): a module path is relative to its own
+            // package anchor, so two packages with the same internal layout collide.
+            // Python cannot produce the same-title duplicate TypeScript can — a test
+            // is a `def`, and two `def`s of one name in one scope are one function —
+            // so the occurrence ordinal is always 1 here.
+            const qsp = isCase
+                ? testCaseQsp(pkg, [...modulePath, ...suite], declaration.path[declaration.path.length - 1])
+                : symbolQsp(pkg, [...modulePath, ...declaration.path]);
+            const entry = {
+                id: nodeId(scope, type, qsp, LANGUAGE),
+                type,
+                name: declaration.name,
+                file,
+                range: { startLine: declaration.range.startLine, endLine: declaration.range.endLine },
+                declaration,
+            };
+            // **One name in one scope is one symbol, however many `def`s write it.**
+            //
+            // Three real shapes, all measured: a `@property` beside its
+            // `@x.setter` (django, `RelatedFieldWidgetWrapper.choices`), a
+            // `@typing.overload` set, and a class defined once per branch of an
+            // `if`/`elif` (dispatch, `Secret` under two secret providers). Python
+            // binds exactly one object to the name in every case.
+            //
+            // Emitting a node each produced duplicate ids — 133 lost declarations on
+            // django, 15 on dispatch, 0 on either repository this adapter was built
+            // against. The Normaliser rejected the extras, keeping the *first*, which
+            // for a property is the getter but for an overload set is a stub.
+            const previous = emittedById.get(entry.id);
+            if (previous !== undefined) {
+                const winner = preferredDeclaration(previous.entry, entry);
+                const merged = { ...winner };
+                nodes[previous.index] = {
+                    ...nodes[previous.index],
+                    range: merged.range,
+                    attrs: { ...nodes[previous.index].attrs, declarations: previous.count + 1 },
+                };
+                emittedById.set(entry.id, { entry: merged, index: previous.index, count: previous.count + 1 });
+                byFull.set(declaration.name, merged);
+                // **`path.length === 1` guards this for the same reason it guards the
+                // non-merge path below, and a second unguarded write here was a wrong
+                // edge rather than a missing one.**
+                //
+                // It wrote `path[0]` whatever the depth, so a *nested* declaration
+                // claimed its enclosing function's importable name. `django`'s
+                // `convert_exception_to_response` contains two `inner` closures, one per
+                // branch; the second merged, and the merge then pointed every importer
+                // of `convert_exception_to_response` at `….inner`. Found by chasing
+                // four "missing" calls that turned out to be four wrong ones.
+                if (declaration.path.length === 1)
+                    byName.set(declaration.path[0], merged);
+                continue;
+            }
+            byFull.set(declaration.name, entry);
+            // Only a top-level name is importable, so only a top-level name enters
+            // the binding table. `OrderService.calculate_total` is reachable by its
+            // full name, never by `calculate_total` alone.
+            if (declaration.path.length === 1)
+                byName.set(declaration.path[0], entry);
+            const attrs = {};
+            if (declaration.kind === "class")
+                attrs["declarationForm"] = "class";
+            if (isCase)
+                attrs["runner"] = "pytest";
+            if (orm !== null) {
+                ormShapes.set(entry.id, orm);
+                attrs["orm"] = orm.framework;
+                if (orm.table !== null)
+                    attrs["table"] = orm.table;
+                // **Not gated on `input.reached`, and the exception is the point.** An
+                // annotation needs a checker before it can be trusted, which is why the
+                // branch below waits for R3. A mapped column does not: `nullable=True`
+                // is a declaration the framework itself enforces, so the shape is
+                // written down rather than inferred and is available as soon as it is
+                // read. Its resolution is the evidence's, not the run's (DEC-058).
+                if (orm.fields.length > 0)
+                    attrs["fields"] = orm.fields;
+                if (orm.undecided.length > 0)
+                    attrs["fieldsUndecided"] = orm.undecided;
+                // DEC-240: DATABASE_TABLE/DATABASE_COLUMN, minted through the one
+                // shared function every producer of these two types now goes
+                // through — never re-derived here, and never guessed when
+                // `orm.table` is `null` (an implicit Django/SQLAlchemy table name,
+                // `tableOf()`'s own disclosed refusal, carried through unchanged).
+                nodes.push(...databaseTableNodesFromModel(scope, { table: orm.table, fields: orm.fields.map((f) => ({ name: f.name, nullable: f.nullable })) }, {
+                    file,
+                    line: declaration.range.startLine,
+                    producedBy: input.producedBy,
+                    resolution: 0,
+                    language: LANGUAGE,
+                }));
+            }
+            else if (dto !== null) {
+                dtoShapes.set(entry.id, dto);
+                attrs["schema"] = "pydantic";
+                // **Gated at R3, exactly as the annotation branch below is.** A field's
+                // shape here is read from a written annotation, and DEC-058's rule for
+                // an annotation is that it is a hint until a checker confirms it —
+                // which is precisely why golden 05 carries `requiredAtResolution: 3`.
+                // The ORM branch above is the deliberate exception: a mapped column's
+                // `nullable=True` is enforced by the framework rather than annotated.
+                // **`fields` is names and `fieldDetail` is shapes — `adapter-openapi`'s
+                // convention, matched rather than re-invented.** Golden 05 compares a
+                // list of names, and two producers of one node type describing it two
+                // ways is the same defect as two producers minting different endpoint
+                // ids: every consumer above the IR then has to know which one ran.
+                // (`MODEL.fields` carries objects instead, which is a corpus-level
+                // inconsistency between DTO and MODEL, not one to fix from this side.)
+                if (input.reached >= 3 && dto.fields.length > 0) {
+                    attrs["fields"] = dto.fields.map((field) => field.name);
+                    attrs["fieldDetail"] = dto.fields.map((field) => ({
+                        name: field.name,
+                        nullable: field.nullable,
+                        required: field.required,
+                        ...(field.type === null ? {} : { type: field.type }),
+                        ...(field.constraints === undefined ? {} : { constraints: field.constraints }),
+                    }));
+                }
+                if (dto.undecided.length > 0)
+                    attrs["fieldsUndecided"] = dto.undecided;
+                // Real rules, none of them statically readable. Counted so the report
+                // can say "this shape is incompletely known" rather than implying the
+                // model constrains nothing beyond what is listed.
+                if (dto.unreadableValidators > 0)
+                    attrs["unreadableValidators"] = dto.unreadableValidators;
+            }
+            else if (
+            // Shapes are the R3 claim: annotations are read from the source at every
+            // level, but only reported once the run claims to have understood types.
+            input.reached >= 3 &&
+                declaration.fields !== undefined &&
+                declaration.fields.length > 0) {
+                attrs["fields"] = [...declaration.fields]
+                    .map((f) => ({ name: f.name, nullable: isNullable(f.annotation, f.hasDefault) }))
+                    .sort((a, b) => a.name.localeCompare(b.name));
+            }
+            emittedById.set(entry.id, { entry, index: nodes.length, count: 1 });
+            nodes.push({
+                id: entry.id,
+                type,
+                name: declaration.name,
+                file,
+                range: entry.range,
+                language: LANGUAGE,
+                producedBy: input.producedBy,
+                resolution: 0,
+                attrs,
+            });
+        }
+        // --- tests we can see but cannot model, disclosed rather than dropped ----
+        //
+        // The ledger is the right home for this and needs no new field: the thing
+        // that failed to exist *is* a `TESTS` edge, and `unresolved_refs` is exactly
+        // "relationships we could not justify emitting". The module is the source
+        // because it is the only node guaranteed to exist for a file whose test
+        // declarations produced nothing.
+        for (const declaration of parsed.declarations) {
+            if (!looksLikeTestCase(declaration, file, pytest))
+                continue;
+            if (isTestCase(declaration, file))
+                continue;
+            disclose({ id: moduleId }, "TESTS", declaration.name, file, declaration.range.startLine, "unrecognisedTest");
+        }
+        // --- type aliases as CLASS nodes (DEC-069) ------------------------------
+        //
+        // DEC-061 settled the representation and the TypeScript adapter has emitted
+        // alias nodes since; this is the Python half of the same rule, not a new
+        // one. Registering the alias in `byName` is what makes the *consumer* edges
+        // appear: `followName` already resolves annotations, and every one of the
+        // 102 measured misses failed only because the name it resolved to had no
+        // node to point at.
+        for (const alias of parsed.aliases ?? []) {
+            if (byName.has(alias.name))
+                continue; // a declaration of the same name wins
+            const qsp = symbolQsp(pkg, [...modulePath, alias.name]);
+            const entry = {
+                id: nodeId(scope, "CLASS", qsp, LANGUAGE),
+                type: "CLASS",
+                name: alias.name,
+                file,
+                range: { startLine: alias.range.startLine, endLine: alias.range.endLine },
+                declaration: {
+                    kind: "class",
+                    path: [alias.name],
+                    name: alias.name,
+                    range: alias.range,
+                    bases: [],
+                    fields: [],
+                    decorators: [],
+                },
+            };
+            byName.set(alias.name, entry);
+            byFull.set(alias.name, entry);
+            aliasIds.add(entry.id);
+            nodes.push({
+                id: entry.id,
+                type: "CLASS",
+                name: alias.name,
+                file,
+                range: entry.range,
+                language: LANGUAGE,
+                producedBy: input.producedBy,
+                resolution: 0,
+                // `declarationForm` is DEC-061's exact vocabulary, shared with the
+                // TypeScript adapter. `aliasRule` is Python-specific provenance and
+                // lives in attrs, which nothing above the IR reads.
+                attrs: { declarationForm: "alias", aliasRule: alias.rule },
+            });
+        }
+    }
+    // --- HTTP routes declared in source (DEC-099) ------------------------------
+    //
+    // **Before the R1 gate, because a route is not automatically an R1 fact.**
+    // Each route carries the level its own evidence earned, which DEC-058 requires
+    // and which the first draft of this pass got wrong by claiming a flat R2 for
+    // everything. A router declared, mounted and decorated in one file is a fact
+    // about one file's text — R0. A chain that crosses a file boundary needs the
+    // import graph and is R1. Nothing here resolves a reference through an index
+    // or compares a shape, so R2 was over-claiming and R3 would be the inflation
+    // DEC-058 removed once already.
+    emitRoutes();
+    if (input.reached < 1)
+        return { nodes, edges, unresolved };
+    // --- pass 2: import edges, off the resolution pass 0 already did ----------
+    for (const file of files) {
+        const fromId = moduleNodeId.get(file);
+        for (const { record, target } of importsResolved.get(file)) {
+            if (target.file === undefined) {
+                disclose({ id: fromId }, "IMPORTS", record.module ?? record.name ?? record.local, file, record.line, "outside");
+                continue;
+            }
+            const toId = moduleNodeId.get(target.file);
+            if (toId !== undefined && toId !== fromId) {
+                push({ from: fromId, to: toId, type: "IMPORTS" }, 1);
+            }
+        }
+    }
+    if (input.reached < 2)
+        return { nodes, edges, unresolved };
+    /**
+     * Follow a name to the declaration that defines it, through however many
+     * package re-exports stand in the way.
+     *
+     * Golden pattern 03 in one function, and its `mustNotResolveTo` clause is why
+     * the loop exists rather than a single lookup: stopping at the first hop would
+     * terminate the edge at the barrel, which the corpus fails an adapter for.
+     */
+    function followName(startFile, name, depth = 0) {
+        if (depth > 8)
+            return undefined; // circular package imports are legal Python
+        const local = declaredIn.get(startFile)?.get(name);
+        if (local !== undefined)
+            return local;
+        const binding = bindingsOf.get(startFile)?.get(name);
+        if (binding === undefined)
+            return undefined;
+        const wanted = binding.symbol ?? name;
+        const direct = declaredIn.get(binding.file)?.get(wanted);
+        if (direct !== undefined)
+            return direct;
+        // Defined elsewhere and merely re-exported here — keep walking.
+        return followName(binding.file, wanted, depth + 1);
+    }
+    /** The class a local name holds, where a bare constructor call said so. */
+    /**
+     * `local name -> its instantiations`, built once per file.
+     *
+     * This was a `.filter()` over the file's whole instantiation list, run once
+     * for **every reference in that file** and twice per reference at R3. It is
+     * quadratic in one file's size, which is invisible on a codebase of small
+     * modules and brutal on one large generated module: `posthog/schema.py` has
+     * 949 instantiations and 14,535 references — **13.8 million scans in a single
+     * file**, each allocating an array.
+     *
+     * Measured: posthog took 1,655 s against 112 s for home-assistant-core at the
+     * same file count. Neither the parser nor the repository size was the cause;
+     * one file was.
+     */
+    const instantiationIndex = new Map();
+    const instantiationsOf = (file, local) => {
+        let index = instantiationIndex.get(file);
+        if (index === undefined) {
+            index = new Map();
+            for (const entry of input.parsed.files[file]?.instantiations ?? []) {
+                const bucket = index.get(entry.local);
+                if (bucket === undefined)
+                    index.set(entry.local, [entry]);
+                else
+                    bucket.push(entry);
+            }
+            instantiationIndex.set(file, index);
+        }
+        return index.get(local) ?? [];
+    };
+    function instantiatedType(file, scopePath, local) {
+        const scopeKey = scopePath.join(".");
+        const inScope = instantiationsOf(file, local).filter((i) => i.scope.length === 0 || i.scope.join(".") === scopeKey);
+        // Innermost scope wins, matching Python: a local shadows a module global.
+        const chosen = inScope.find((i) => i.scope.length > 0 && i.scope.join(".") === scopeKey) ??
+            inScope.find((i) => i.scope.length === 0);
+        if (chosen === undefined)
+            return undefined;
+        const target = followName(file, chosen.typeName);
+        return target !== undefined && isTypeLikeNodeType(target.type) ? target : undefined;
+    }
+    for (const file of files) {
+        const parsed = input.parsed.files[file];
+        const byFull = byFullName.get(file);
+        const containerOf = (scopePath) => {
+            for (let depth = scopePath.length; depth > 0; depth -= 1) {
+                const found = byFull.get(scopePath.slice(0, depth).join("."));
+                if (found !== undefined)
+                    return found;
+            }
+            return undefined;
+        };
+        // --- heritage ----------------------------------------------------------
+        for (const declaration of parsed.declarations) {
+            if (declaration.kind !== "class")
+                continue;
+            const self = byFull.get(declaration.name);
+            if (self === undefined)
+                continue;
+            for (const base of declaration.bases ?? []) {
+                if (base === null)
+                    continue;
+                const root = base.split("[")[0].split(".").pop();
+                const target = followName(file, root);
+                if (target === undefined) {
+                    disclose(self, "INHERITS", root, file, declaration.range.startLine, "outside");
+                    continue;
+                }
+                if (target.id !== self.id)
+                    push({ from: self.id, to: target.id, type: "INHERITS" }, 2);
+            }
+        }
+        // --- calls, method calls, and the tests that make them ------------------
+        for (const reference of parsed.references) {
+            if (reference.name === null)
+                continue;
+            const container = containerOf(reference.scope);
+            if (container === undefined)
+                continue;
+            // A pytest case and the function that carries it are the same source, so
+            // a call inside it is attributed to the TEST_CASE rather than counted
+            // twice — TESTS is the edge the corpus asks for.
+            // A call out of a test case is `TESTS`, which is the edge the corpus asks
+            // for; out of anything else it is `CALLS`.
+            const source = container;
+            const edgeType = container.type === "TEST_CASE" ? "TESTS" : "CALLS";
+            if (reference.kind === "call") {
+                const target = followName(file, reference.name);
+                if (target === undefined) {
+                    disclose(source, edgeType, reference.name, file, reference.line, "outside");
+                    continue;
+                }
+                if ((target.type === "FUNCTION" || target.type === "TEST_CASE") && target.id !== source.id) {
+                    push({ from: source.id, to: target.id, type: edgeType }, 2);
+                }
+                else if (isTypeLikeNodeType(target.type) && target.id !== source.id) {
+                    // `service = OrderService()` — a constructor call. The name resolves
+                    // to a class, so `CALLS` cannot carry it (DEC-068 keeps CALLS to
+                    // FUNCTION and TEST_CASE targets), and the dependency was previously
+                    // dropped entirely. 1,237 of the 1,890 measured missing edges are
+                    // this one form.
+                    push({ from: source.id, to: target.id, type: "USES_TYPE" }, 2);
+                }
+                continue;
+            }
+            if (reference.kind === "method" && reference.receiver !== null) {
+                // `OrderService.create(...)`, `DocumentType.VENDOR_BILL` — the receiver
+                // is the class's own name rather than an instance, so no type inference
+                // is needed: the name resolves to a declaration directly. DEC-068.
+                //
+                // A receiver that is a local, a parameter or `self` resolves to nothing
+                // here and falls through to the paths below — that is the precision
+                // guard, and it is why `resp.total` cannot reach this branch.
+                if (reference.receiver !== "self") {
+                    const owner = followName(file, reference.receiver);
+                    if (owner !== undefined && isTypeLikeNodeType(owner.type) && owner.id !== source.id) {
+                        push({ from: source.id, to: owner.id, type: "USES_TYPE" }, 2);
+                        continue;
+                    }
+                }
+                // `self.x()` needs the enclosing class's own members; anything else
+                // needs the receiver's type, which only a bare constructor call gives.
+                if (reference.receiver === "self") {
+                    const owner = reference.scope[0];
+                    const method = owner === undefined ? undefined : byFull.get(`${owner}.${reference.name}`);
+                    if (method === undefined) {
+                        disclose(source, edgeType, `self.${reference.name}`, file, reference.line, "unknown");
+                        continue;
+                    }
+                    if (method.id !== source.id)
+                        push({ from: source.id, to: method.id, type: edgeType }, 2);
+                    continue;
+                }
+                // `event_service.log_case_event(…)` — the receiver is a **module**,
+                // bound by `from dispatch.event import service as event_service`.
+                //
+                // `symbol === undefined` is the import resolver's own statement that the
+                // specifier named a module rather than a name inside one, so this is not
+                // a guess between two readings of the same text. Without it every call
+                // through an aliased module fell to `instantiatedType`, found nothing,
+                // and was disclosed as unknown: **18 of the 19 measured recall misses on
+                // `dispatch` were this one form**, and it is the commonest way a Python
+                // codebase of any size refers across packages.
+                const asModule = bindingsOf.get(file)?.get(reference.receiver);
+                if (asModule !== undefined && asModule.symbol === undefined) {
+                    const inModule = declaredIn.get(asModule.file)?.get(reference.name);
+                    if (inModule !== undefined && inModule.id !== source.id) {
+                        if (inModule.type === "FUNCTION" || inModule.type === "TEST_CASE") {
+                            push({ from: source.id, to: inModule.id, type: edgeType }, 2);
+                        }
+                        else if (isTypeLikeNodeType(inModule.type)) {
+                            // A class reached through its module is a value dependency, and
+                            // CALLS keeps to FUNCTION and TEST_CASE targets (DEC-068).
+                            push({ from: source.id, to: inModule.id, type: "USES_TYPE" }, 2);
+                        }
+                        continue;
+                    }
+                    disclose(source, edgeType, `${reference.receiver}.${reference.name}`, file, reference.line, "unknown");
+                    continue;
+                }
+                const receiverType = instantiatedType(file, reference.scope, reference.receiver);
+                if (receiverType === undefined) {
+                    disclose(source, edgeType, `${reference.receiver}.${reference.name}`, file, reference.line, "unknown");
+                    continue;
+                }
+                const method = byFullName
+                    .get(receiverType.file)
+                    ?.get(`${receiverType.name}.${reference.name}`);
+                if (method === undefined) {
+                    disclose(source, edgeType, `${receiverType.name}.${reference.name}`, file, reference.line, "unknown");
+                    continue;
+                }
+                if (method.id !== source.id)
+                    push({ from: source.id, to: method.id, type: edgeType }, 2);
+            }
+        }
+        // --- a class or enum reached through its own name (DEC-068) -------------
+        //
+        // `DocumentType.VENDOR_BILL` arrives as an attribute access whose receiver
+        // is the enum's own name. Resolving the *receiver* is the whole of it: the
+        // dependency is on the class, and naming the member would need a node type
+        // the vocabulary does not have. A receiver that is a local or a parameter
+        // resolves to nothing and is left to the ledger, unchanged.
+        for (const reference of parsed.references) {
+            if (reference.kind !== "attribute" && reference.kind !== "attribute_write")
+                continue;
+            if (reference.receiver === null || reference.receiver === "self")
+                continue;
+            const container = containerOf(reference.scope);
+            if (container === undefined)
+                continue;
+            const owner = followName(file, reference.receiver);
+            if (owner === undefined || !isTypeLikeNodeType(owner.type) || owner.id === container.id)
+                continue;
+            push({ from: container.id, to: owner.id, type: "USES_TYPE" }, 2);
+        }
+        // --- a class referenced as a value (DEC-072) ----------------------------
+        //
+        // DEC-068 covered `X()` and `X.MEMBER`. This is the rest: passed as an
+        // argument, caught, matched, returned, defaulted, iterated, put in a list.
+        // Measured at 126 sites and 123 distinct edges before a line was written.
+        //
+        // The gate is that the target has a node at all, which is what keeps this
+        // disjoint from DEC-071's constants by construction — every target here
+        // already has a node, and every target there has none.
+        for (const reference of parsed.valueRefs ?? []) {
+            const container = containerOf(reference.scope);
+            if (container === undefined)
+                continue;
+            const target = followName(file, reference.name);
+            // **Nothing is disclosed here, and that is deliberate.** The ledger is for
+            // references that *would have been edges* — DEC-016's "a name-matched
+            // guess is a false claim, but dropping it silently leaves no denominator".
+            // A bare name in a value position is usually a local or a parameter and is
+            // not a reference to any declaration at all: filing every one of them
+            // grew the ledger from 5,782 to 11,155 on one repository, and the reason
+            // string would have claimed they resolve to the standard library, which is
+            // simply untrue. A scan for one pattern is not a reference list, and
+            // disclosing what it did not find would degrade the one signal the ledger
+            // carries.
+            if (target === undefined)
+                continue;
+            // **A function handed on as a value, DEC-074.** An earlier comment here
+            // said `USES_TYPE` would be the wrong claim about a callback and left the
+            // case out. Sizing it settled the question the other way: `READS` is
+            // defined by the architecture as *code → data* and feeds the propagation
+            // layer, so a function reference there would corrupt data analysis; and
+            // `CALLS` would put a non-call into root-cause traversal, which is the
+            // damage the precision rule names by example. `USES_TYPE` is what
+            // DEC-067 already chose for a value reference when it rejected a separate
+            // `USES_VALUE`, and its operative meaning is *A's declaration names B*.
+            // Measured before the change: 98 edges on directus, 82 on dispatch.
+            if (!isTypeLikeNodeType(target.type) && target.type !== "FUNCTION")
+                continue;
+            if (target.id === container.id)
+                continue;
+            push({ from: container.id, to: target.id, type: "USES_TYPE" }, 2);
+        }
+        // --- USES_TYPE, from an alias to its own constituents (DEC-069) ---------
+        //
+        // The second direction, and the one the annotation sizing could not see.
+        // DEC-061's definition — *A's shape or signature names B* — reads on an
+        // alias exactly as it reads on a parameter, and the TypeScript adapter has
+        // emitted `Pair -> Alpha` since that entry. Omitting it here would make the
+        // two adapters disagree about one construct, which is the failure the
+        // conformance corpus exists to prevent.
+        for (const alias of parsed.aliases ?? []) {
+            const self = byFull.get(alias.name);
+            if (self === undefined)
+                continue;
+            for (const name of alias.constituents) {
+                const target = followName(file, name);
+                if (target === undefined) {
+                    disclose(self, "USES_TYPE", name, file, alias.range.startLine, "outside");
+                    continue;
+                }
+                if (target.id === self.id)
+                    continue; // a recursive alias is not a dependency
+                push({ from: self.id, to: target.id, type: "USES_TYPE" }, 2);
+            }
+        }
+        // --- USES_TYPE, from an annotated local ---------------------------------
+        //
+        // **The "54": parsed, serialised, and never read.** `visit_AnnAssign`
+        // recorded every `client: HttpClient = make()` as an annotation reference
+        // from the day it was written, and no consumer on this side ever looked at
+        // `kind === "annotation"`. Sized at 54 edges repo-wide and left on the
+        // roadmap as "not started", which read as unbuilt work rather than as a
+        // dropped field.
+        //
+        // A local's declared type is a dependency of the declaration that holds it,
+        // by exactly DEC-061's definition, and it is the same `USES_TYPE` claim at
+        // the same R2 as a parameter's. The module-level case is deliberately not
+        // here: a top-level annotated assignment is an alias candidate and is
+        // handled above, and claiming it twice would double-count it.
+        for (const reference of parsed.references) {
+            if (reference.kind !== "annotation")
+                continue;
+            const container = containerOf(reference.scope);
+            if (container === undefined)
+                continue;
+            for (const name of typeNamesIn(reference.name)) {
+                const target = followName(file, name);
+                if (target === undefined)
+                    continue; // builtins and typing live here
+                if (target.id === container.id)
+                    continue;
+                push({ from: container.id, to: target.id, type: "USES_TYPE" }, 2);
+            }
+        }
+        // --- USES_TYPE, from every written annotation (DEC-061) -----------------
+        for (const declaration of parsed.declarations) {
+            const self = byFull.get(declaration.name);
+            if (self === undefined)
+                continue;
+            const written = [
+                declaration.returns,
+                ...(declaration.params ?? []).map((p) => p.annotation),
+                ...(declaration.fields ?? []).map((f) => f.annotation),
+            ];
+            for (const annotation of written) {
+                for (const name of typeNamesIn(annotation)) {
+                    const target = followName(file, name);
+                    if (target === undefined)
+                        continue; // builtins and typing live here
+                    if (target.id === self.id)
+                        continue;
+                    push({ from: self.id, to: target.id, type: "USES_TYPE" }, 2);
+                }
+            }
+        }
+    }
+    function emitRoutes() {
+        /** local name -> the module that supplied it, for the constructor check. */
+        const moduleOfImportIn = (file) => (name) => {
+            const record = input.parsed.files[file]?.imports.find((i) => i.local === name);
+            if (record === undefined)
+                return undefined;
+            if (record.level > 0) {
+                const binding = bindingsOf.get(file)?.get(name);
+                return binding === undefined ? undefined : modulePathOf(binding.file).join(".");
+            }
+            // `from fastapi import APIRouter` names the module outright; `import
+            // fastapi` binds the module itself.
+            return record.module ?? record.name ?? undefined;
+        };
+        /**
+         * A router variable, canonicalised across files.
+         *
+         * **The alias trap, one layer up.** `from .auth.views import router as
+         * auth_router` binds a different local name to the same object, and a table
+         * keyed on the local name misses every mount written against the alias. This
+         * is golden pattern 03's lesson, and it has now cost a bug in this project
+         * four separate times — DEC-052 hit it on the caller side of this very join.
+         */
+        /**
+         * A router's key, qualified by the scope it was declared in.
+         *
+         * **Not optional.** flask's test suite declares `app = Flask(__name__)`
+         * inside individual test functions, and a key of `file::app` makes one such
+         * local visible to every other test in the file — including the ~50 whose
+         * `app` is a pytest fixture parameter, a name this adapter cannot resolve at
+         * all. Keyed flat it emitted 142 routes against 42 real ones. The same bug
+         * existed in the independent truth walker and was found there first.
+         */
+        const scopedKey = (file, scope, local) => `${file}::${scope.join(".")}::${local}`;
+        /** Innermost scope outwards, then the import table. */
+        const lookupRouter = (file, scope, local) => {
+            for (let depth = scope.length; depth >= 0; depth -= 1) {
+                const key = scopedKey(file, scope.slice(0, depth), local);
+                if (routers.has(key))
+                    return key;
+            }
+            const imported = scopedKey(...canonicalParts(file, local));
+            return routers.has(imported) ? imported : undefined;
+        };
+        /** An imported router resolves to module scope in the file that declares it. */
+        const canonicalParts = (file, local) => {
+            const dot = local.lastIndexOf(".");
+            if (dot !== -1) {
+                const moduleBinding = bindingsOf.get(file)?.get(local.slice(0, dot));
+                if (moduleBinding !== undefined)
+                    return [moduleBinding.file, [], local.slice(dot + 1)];
+                return [file, [], local];
+            }
+            const binding = bindingsOf.get(file)?.get(local);
+            if (binding === undefined)
+                return [file, [], local];
+            return [binding.file, [], binding.symbol ?? local];
+        };
+        /**
+         * Did resolving this name need the import graph?
+         *
+         * This is the whole of the resolution question. A name bound in the file
+         * that uses it costs nothing to resolve; a name that came from an import
+         * costs module resolution, which is what R1 *is*.
+         */
+        const crossesFile = (file, local) => bindingsOf.get(file)?.get(local) !== undefined;
+        const routers = new Map();
+        const mounts = [];
+        const routeDecls = [];
+        const clientCalls = [];
+        const djangoRouteEntries = [];
+        const djangoIncludeEntries = [];
+        const drfRegisterEntries = [];
+        const odooRouteEntries = [];
+        const graphqlSchemas = [];
+        for (const file of files) {
+            const parsed = input.parsed.files[file];
+            const calls = parsed.calls ?? [];
+            // `router = APIRouter(...)`: the instantiation table already pairs a
+            // module-level assignment with its constructor, so the local name comes
+            // from there rather than from a second walk.
+            // **`constructions`, not `instantiations`.** The latter records only a
+            // bare `Name` constructor, so `app = flask.Flask(__name__)` — the form
+            // flask's own documentation uses — was invisible and the routes hanging
+            // off it were disclosed as unreadable. Not restricted to module scope
+            // either: an application factory assigns its app inside a function, and
+            // the mounts are written there too.
+            const localOfCall = (call) => (parsed.constructions ?? []).find((c) => c.line === call.line && c.callee === call.callee)
+                ?.local;
+            for (const declared of routersIn(file, calls, localOfCall, moduleOfImportIn(file))) {
+                const scope = (parsed.constructions ?? []).find((c) => c.line === declared.line && c.local === declared.local)?.scope;
+                routers.set(scopedKey(file, scope ?? [], declared.local), declared);
+            }
+            mounts.push(...mountsIn(file, calls));
+            // --- the caller half: HTTP calls this file makes ---------------------
+            //
+            // Written here rather than in the reference walk because import
+            // provenance is already resolved in this loop, and provenance is the
+            // whole precision control: `client.get("/orders/1")` is a Django test
+            // client in 2,280 places across the reference set and an HTTP call in
+            // none of them.
+            const fileClients = byFullName.get(file);
+            const clientLocals = clientLocalsIn(calls, localOfCall, moduleOfImportIn(file));
+            const constants = new Map();
+            for (const constant of parsed.constants ?? [])
+                constants.set(constant.name, constant.value);
+            // Keyed on scope as well as name, because two functions in one file may
+            // each bind `url` to a different path and merging them would attach a
+            // caller to an endpoint it never reaches.
+            const localStrings = new Map();
+            for (const local of parsed.localStrings ?? []) {
+                localStrings.set(`${local.scope.join(".")}::${local.name}`, local.value);
+            }
+            // DEC-242's `varies-per-call`: a function's own parameter names, keyed
+            // by its scope path exactly as `PyCall.scope` writes it — a call inside
+            // that function shares the same scope path, so `call.scope.join(".")`
+            // looks this up directly.
+            const functionParams = new Map();
+            for (const declaration of parsed.declarations) {
+                if (declaration.kind !== "function")
+                    continue;
+                functionParams.set(declaration.path.join("."), new Set((declaration.params ?? []).map((p) => p.name)));
+            }
+            const read = clientCallsIn(file, calls, moduleOfImportIn(file), clientLocals, constants, localStrings, functionParams);
+            const containerFor = (scopePath) => {
+                if (fileClients === undefined)
+                    return undefined;
+                for (let depth = scopePath.length; depth > 0; depth -= 1) {
+                    const found = fileClients.get(scopePath.slice(0, depth).join("."));
+                    if (found !== undefined)
+                        return found;
+                }
+                // A call at module level belongs to the module, exactly as it does in
+                // TypeScript (DEC-098). Without this fallback a client module with no
+                // enclosing def produces no edge *and* no ledger row.
+                const moduleId = moduleNodeId.get(file);
+                return moduleId === undefined ? undefined : { id: moduleId };
+            };
+            for (const refusal of read.refusals) {
+                const container = containerFor([]);
+                if (container === undefined)
+                    continue;
+                disclose(container, "USES_API", refusal.rawTarget, refusal.file, refusal.line, refusal.reason, 
+                // Unset `refusalClass` stays legal and means unclassified — DEC-242 — so
+                // `attrs` is omitted entirely rather than sent with an `undefined` field.
+                refusal.refusalClass === undefined
+                    ? undefined
+                    : {
+                        blockedBy: refusal.blockedBy,
+                        refusalClass: refusal.refusalClass,
+                        ...(refusal.argumentKind === undefined ? {} : { argumentKind: refusal.argumentKind }),
+                    });
+            }
+            for (const call of read.calls) {
+                const container = containerFor(call.scope);
+                if (container === undefined)
+                    continue;
+                clientCalls.push({ call, containerId: container.id });
+            }
+            for (const declaration of parsed.declarations) {
+                for (const call of declaration.decoratorCalls ?? []) {
+                    const route = routeFromDecorator(file, call, declaration.path);
+                    if (route !== null)
+                        routeDecls.push(route);
+                    const odooRoute = odooRouteFromDecorator(file, call, declaration.path, moduleOfImportIn(file));
+                    if (odooRoute !== null)
+                        odooRouteEntries.push(odooRoute);
+                }
+            }
+            // --- Django's own routing: urlpatterns/path()/re_path()/url() --------
+            // --- GraphQL: the schema call is the provenance, nothing else is ------
+            graphqlSchemas.push(...schemaDeclsIn(file, calls, moduleOfImportIn(file)));
+            const djangoUrls = djangoUrlEntriesIn(file, calls, moduleOfImportIn(file));
+            djangoRouteEntries.push(...djangoUrls.routes);
+            djangoIncludeEntries.push(...djangoUrls.includes);
+            // --- DRF: router.register(prefix, ViewSetClass) ----------------------
+            const drfLocals = drfRouterLocalsIn(calls, localOfCall, moduleOfImportIn(file));
+            for (const reg of drfRegisterCallsIn(file, calls)) {
+                if (drfLocals.has(reg.routerLocal))
+                    drfRegisterEntries.push(reg);
+            }
+        }
+        /** child -> its parent and the prefix mounting it there. */
+        const parentOf = new Map();
+        for (const mount of mounts) {
+            const child = lookupRouter(mount.file, mount.scope, mount.childLocal);
+            const parent = lookupRouter(mount.file, mount.scope, mount.parentLocal);
+            if (child === undefined || parent === undefined || child === parent)
+                continue;
+            parentOf.set(child, {
+                parent,
+                prefix: mount.prefix,
+                crossesFile: crossesFile(mount.file, mount.childLocal) || crossesFile(mount.file, mount.parentLocal),
+            });
+        }
+        /**
+         * The full mount prefix of a router, and the resolution its chain earned.
+         *
+         * `prefix: null` means a hop is written and unreadable — disclosed, never
+         * guessed. `level` is 1 as soon as any hop needed the import graph.
+         */
+        const prefixCache = new Map();
+        const fullPrefix = (start) => {
+            const cached = prefixCache.get(start);
+            if (cached !== undefined)
+                return cached;
+            const parts = [];
+            const seen = new Set();
+            let current = start;
+            let answer = "";
+            let level = 0;
+            while (current !== undefined && !seen.has(current)) {
+                seen.add(current);
+                const declared = routers.get(current);
+                if (declared !== undefined) {
+                    if (declared.prefix === null) {
+                        answer = null;
+                        break;
+                    }
+                    if (declared.prefix !== "")
+                        parts.push(declared.prefix);
+                }
+                const step = parentOf.get(current);
+                if (step === undefined)
+                    break;
+                if (step.prefix === null) {
+                    answer = null;
+                    break;
+                }
+                if (step.prefix !== "")
+                    parts.push(step.prefix);
+                if (step.crossesFile)
+                    level = 1;
+                current = step.parent;
+            }
+            if (answer !== null)
+                answer = parts.reverse().join("");
+            const result = { prefix: answer, level };
+            prefixCache.set(start, result);
+            return result;
+        };
+        /**
+         * Every type name a route's contract mentions — its handler's parameter
+         * annotations, its `response_model=`, and its return annotation.
+         *
+         * Names, not resolutions: the caller decides which of them is a `DTO`. A
+         * route naming a type that is not a validated shape produces no edge and
+         * needs no disclosure, because there is no relationship being refused.
+         */
+        const routeContractNames = (route) => {
+            const parsed = input.parsed.files[route.file];
+            const handler = route.handler === null
+                ? undefined
+                : parsed?.declarations.find((d) => d.name === route.handler.join("."));
+            const written = [
+                route.responseModel,
+                handler?.returns ?? null,
+                ...(handler?.params ?? []).map((p) => p.annotation),
+            ];
+            const out = new Set();
+            for (const annotation of written) {
+                for (const name of typeNamesIn(annotation))
+                    out.add(name);
+            }
+            return [...out];
+        };
+        for (const route of routeDecls) {
+            const key = lookupRouter(route.file, route.scope, route.routerLocal);
+            const router = key === undefined ? undefined : routers.get(key);
+            const from = (route.handler === null ? undefined : byFullName.get(route.file)?.get(route.handler.join("."))) ??
+                { id: moduleNodeId.get(route.file) };
+            // **The receiver must be a router this run resolved.** Not "an attribute
+            // spelled like a verb" — `@mock.patch` is 1,150 sites on saleor and 171 on
+            // django, and a Slack Bolt `app.options(...)` registers an action id
+            // rather than a path. Every one would be a false claim about a URL.
+            if (router === undefined) {
+                disclose(from, "SERVES_API", `${route.methods.join("/")} ${route.rawPath}`, route.file, route.line, "routeReceiverUnknown");
+                continue;
+            }
+            if (route.path === null) {
+                disclose(from, "SERVES_API", `${route.methods.join("/")} ${route.rawPath}`, route.file, route.line, "routePathNotLiteral");
+                continue;
+            }
+            const chain = fullPrefix(key);
+            if (chain.prefix === null) {
+                disclose(from, "SERVES_API", `${route.methods.join("/")} ${route.path}`, route.file, route.line, "routePrefixNotLiteral");
+                continue;
+            }
+            const prefix = chain.prefix;
+            // The level this route's own evidence earned, capped by what the run
+            // reached. A route whose chain needs the import graph is not available at
+            // R0, and emitting it there would claim a resolution the run did not have.
+            const level = (chain.level === 1 || crossesFile(route.file, route.routerLocal) ? 1 : 0);
+            if (level > input.reached)
+                continue;
+            // A router nothing mounts serves nothing, and the mount is where the
+            // served path is decided. dispatch declares four such routes in a Slack
+            // plugin whose router is mounted by plugin machinery at runtime.
+            //
+            // **The guard used to fire only when the router had no prefix of its own**
+            // — `!parentOf.has(key) && routers.get(key)?.prefix === ""` — which meant
+            // a `Blueprint(url_prefix="/auth")` that nothing registers was emitted
+            // anyway. It happened to produce correct paths on flask because those
+            // blueprints *are* registered, so the reasoning was unsound while the
+            // answer was right, which is the combination that survives a draw.
+            if (!parentOf.has(key) && !isApplicationRouter(router)) {
+                disclose(from, "SERVES_API", `${route.methods.join("/")} ${route.path}`, route.file, route.line, "routeNeverMounted");
+                continue;
+            }
+            const served = joinPath(prefix, route.path);
+            for (const method of route.methods) {
+                // The route keeps the template AS WRITTEN in its identity and the
+                // normalised form in `attrs.pathTemplate` — `adapter-openapi` does
+                // exactly this, and two producers of one route must mint the same
+                // endpoint id or the join this whole lane exists for does not happen.
+                const routeId = nodeId(scope, "API_ROUTE", `${method} ${served}`, LANGUAGE);
+                if (!routeSeen.has(routeId)) {
+                    routeSeen.add(routeId);
+                    nodes.push({
+                        id: routeId,
+                        type: "API_ROUTE",
+                        name: `${method} ${served}`,
+                        file: route.file,
+                        range: { startLine: route.line, endLine: route.line },
+                        language: LANGUAGE,
+                        producedBy: input.producedBy,
+                        resolution: level,
+                        attrs: {
+                            method,
+                            pathTemplate: normaliseEndpointPath(served),
+                            rawTemplate: served,
+                            framework: router.framework,
+                        },
+                    });
+                }
+                else {
+                    // This declaration's own SERVES_API edge and source location did not
+                    // enter the graph — a second router already claimed this exact
+                    // method+path. Real (two apps mounted at overlapping prefixes, a
+                    // duplicate registration) rather than a bug in this reader, but
+                    // silent until now: nothing distinguished it from "checked, only
+                    // one declaration exists".
+                    disclose(from, "SERVES_API", `${method} ${served}`, route.file, route.line, "routeIdCollision");
+                }
+                // Fileless AND language-less (DEC-014). `nodeId` throws if a fileless
+                // type is hashed with a language, which is the guard against an id that
+                // disagrees with the node it labels — a failure whose only symptom
+                // would be a join that silently does not happen.
+                const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(method, served), null);
+                if (!routeSeen.has(endpointId)) {
+                    routeSeen.add(endpointId);
+                    nodes.push({
+                        id: endpointId,
+                        type: "API_ENDPOINT",
+                        name: `${method} ${normaliseEndpointPath(served)}`,
+                        file: null,
+                        range: null,
+                        language: null,
+                        producedBy: input.producedBy,
+                        resolution: level,
+                        attrs: { method, pathTemplate: normaliseEndpointPath(served) },
+                    });
+                }
+                // `SERVES_API` and nothing else *to the endpoint*. Golden pattern 04
+                // asserts this edge alone, and a route-to-handler edge would be a
+                // second claim with no golden behind it and no draw measuring it.
+                push({ from: routeId, to: endpointId, type: "SERVES_API" }, level);
+                // The route's contract: which validated shapes it names. `USES_TYPE`
+                // is the edge `adapter-openapi` already emits from a route to a schema
+                // it names, and matching it is not cosmetic — two producers describing
+                // one construct with two edge types makes every threshold above the IR
+                // depend on which producer ran.
+                //
+                // **R2, and gated.** Deciding which `OrderRead` a name means is
+                // reference resolution through re-exports, which is what R2 buys and
+                // what `CALLS` and `USES_TYPE` already claim in this adapter.
+                if (input.reached >= 2) {
+                    for (const name of routeContractNames(route)) {
+                        const target = followName(route.file, name);
+                        if (target === undefined || !dtoShapes.has(target.id))
+                            continue;
+                        push({ from: routeId, to: target.id, type: "USES_TYPE" }, 2);
+                    }
+                }
+            }
+        }
+        // --- Django's own routing: chain-resolve include() by module string ----
+        //
+        // Keyed by FILE, not by a local variable — `include("app.urls")` mounts
+        // by dotted module string, and Django's mount graph has no notion of a
+        // local scope a name could be shadowed in. A file's `urlpatterns` is
+        // root (prefix `""`) exactly when nothing in this run's include graph
+        // names it: `include()` only ever points from a project's root urlconf
+        // down into an app's, never the other way, so "nothing includes it" is
+        // the structural definition of root, not a guess about which file is
+        // special.
+        const djangoParentOf = new Map();
+        for (const inc of djangoIncludeEntries) {
+            const includeFrom = { id: moduleNodeId.get(inc.file) };
+            if (inc.targetModule === null) {
+                // `include(router.urls)` hands a DRF router's own generated routes
+                // back into this same file's urlpatterns — not a cross-file mount,
+                // and already covered by the DRF loop below. Anything else
+                // unreadable (a computed string, a `(module, namespace)` tuple) is
+                // disclosed rather than silently dropped.
+                if (!/^[A-Za-z_][A-Za-z0-9_]*\.urls$/.test(inc.rawTarget.trim())) {
+                    disclose(includeFrom, "SERVES_API", inc.rawTarget, inc.file, inc.line, "djangoIncludeUnresolved");
+                }
+                continue;
+            }
+            const target = resolveImportCached({ kind: "absolute", level: 0, module: inc.targetModule, name: null, local: "", line: inc.line }, inc.file);
+            if (target.file === undefined) {
+                disclose(includeFrom, "SERVES_API", inc.targetModule, inc.file, inc.line, "djangoIncludeUnresolved");
+                continue;
+            }
+            // First include wins when a module is mounted from more than one
+            // place — rare, and in the overwhelming majority of real projects
+            // exactly one parent is the meaningful one; overwriting a resolved
+            // chain on a second sighting would be the less safe default.
+            if (!djangoParentOf.has(target.file)) {
+                djangoParentOf.set(target.file, { parent: inc.file, prefix: inc.prefix });
+            }
+        }
+        const djangoPrefixCache = new Map();
+        const djangoFullPrefix = (startFile) => {
+            const cached = djangoPrefixCache.get(startFile);
+            if (cached !== undefined)
+                return cached;
+            const parts = [];
+            const seen = new Set();
+            let current = startFile;
+            let answer = "";
+            let level = 0;
+            while (current !== undefined && !seen.has(current)) {
+                seen.add(current);
+                const step = djangoParentOf.get(current);
+                if (step === undefined)
+                    break;
+                if (step.prefix === null) {
+                    answer = null;
+                    break;
+                }
+                if (step.prefix !== "")
+                    parts.push(step.prefix);
+                level = 1;
+                current = step.parent;
+            }
+            if (answer !== null)
+                answer = parts.reverse().join("");
+            const result = { prefix: answer, level };
+            djangoPrefixCache.set(startFile, result);
+            return result;
+        };
+        /**
+         * A urlconf entry names no verb — Django dispatches by looking at the
+         * request, not the registration. Defaulting to GET matches this file's
+         * own precedent for Flask's undecorated `.route()` (`GENERIC_ROUTE_ATTRS`,
+         * above). Upgraded when the view is a same-file class-based view whose
+         * body itself declares HTTP-verb-named methods — Django's actual
+         * dispatch mechanism (`View.dispatch` calls `getattr(self,
+         * request.method.lower())`), read from source rather than guessed.
+         * Cross-file CBVs and function-based views stay at the GET default —
+         * resolving an imported class's own methods is a second import hop this
+         * pass does not add.
+         */
+        const djangoRouteMethods = (route) => {
+            if (route.viewClassLocal === null)
+                return ["GET"];
+            const declarations = input.parsed.files[route.file]?.declarations ?? [];
+            const found = declarations
+                .filter((d) => d.kind === "function" &&
+                d.path.length === 2 &&
+                d.path[0] === route.viewClassLocal &&
+                HTTP_METHODS.has(d.path[1]))
+                .map((d) => d.path[1].toUpperCase());
+            return found.length > 0 ? found : ["GET"];
+        };
+        const emitDjangoRoute = (file, line, served, method, level, framework) => {
+            const from = { id: moduleNodeId.get(file) };
+            const routeId = nodeId(scope, "API_ROUTE", `${method} ${served}`, LANGUAGE);
+            if (!routeSeen.has(routeId)) {
+                routeSeen.add(routeId);
+                nodes.push({
+                    id: routeId,
+                    type: "API_ROUTE",
+                    name: `${method} ${served}`,
+                    file,
+                    range: { startLine: line, endLine: line },
+                    language: LANGUAGE,
+                    producedBy: input.producedBy,
+                    resolution: level,
+                    attrs: { method, pathTemplate: normaliseEndpointPath(served), rawTemplate: served, framework },
+                });
+            }
+            else {
+                disclose(from, "SERVES_API", `${method} ${served}`, file, line, "routeIdCollision");
+            }
+            const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(method, served), null);
+            if (!routeSeen.has(endpointId)) {
+                routeSeen.add(endpointId);
+                nodes.push({
+                    id: endpointId,
+                    type: "API_ENDPOINT",
+                    name: `${method} ${normaliseEndpointPath(served)}`,
+                    file: null,
+                    range: null,
+                    language: null,
+                    producedBy: input.producedBy,
+                    resolution: level,
+                    attrs: { method, pathTemplate: normaliseEndpointPath(served) },
+                });
+            }
+            push({ from: routeId, to: endpointId, type: "SERVES_API" }, level);
+        };
+        for (const route of djangoRouteEntries) {
+            const from = { id: moduleNodeId.get(route.file) };
+            if (route.path === null) {
+                disclose(from, "SERVES_API", route.rawPath, route.file, route.line, "djangoPathNotLiteral");
+                continue;
+            }
+            const chain = djangoFullPrefix(route.file);
+            if (chain.prefix === null) {
+                disclose(from, "SERVES_API", `${route.path}`, route.file, route.line, "djangoIncludeUnresolved");
+                continue;
+            }
+            const level = chain.level;
+            if (level > input.reached)
+                continue;
+            const served = joinPath(chain.prefix, route.path);
+            for (const method of djangoRouteMethods(route)) {
+                emitDjangoRoute(route.file, route.line, served, method, level, "django");
+            }
+        }
+        // --- DRF: router.register(prefix, ViewSetClass) — the fixed action table
+        // `DefaultRouter`/`SimpleRouter` always generate, regardless of which of
+        // those actions the viewset actually implements (an unimplemented one
+        // still gets the URL and 405s at request time). Reading the router's own
+        // contract rather than inspecting the viewset's mixins, which mostly live
+        // outside the analysed set entirely (`ModelViewSet` composes them from
+        // DRF's own installed package).
+        for (const reg of drfRegisterEntries) {
+            const from = { id: moduleNodeId.get(reg.file) };
+            if (reg.prefix === null) {
+                disclose(from, "SERVES_API", reg.rawPrefix, reg.file, reg.line, "djangoPathNotLiteral");
+                continue;
+            }
+            const chain = djangoFullPrefix(reg.file);
+            if (chain.prefix === null) {
+                disclose(from, "SERVES_API", reg.prefix, reg.file, reg.line, "djangoIncludeUnresolved");
+                continue;
+            }
+            const level = chain.level;
+            if (level > input.reached)
+                continue;
+            const basePath = joinPath(chain.prefix, reg.prefix);
+            for (const action of DRF_ACTIONS) {
+                const served = joinPath(basePath, action.suffix);
+                emitDjangoRoute(reg.file, reg.line, served, action.method, level, "django");
+            }
+        }
+        // --- Odoo: @http.route(...) — path already absolute, nothing to resolve -
+        for (const route of odooRouteEntries) {
+            const from = (route.handler === null ? undefined : byFullName.get(route.file)?.get(route.handler.join("."))) ??
+                { id: moduleNodeId.get(route.file) };
+            if (route.path === null) {
+                disclose(from, "SERVES_API", route.rawPath, route.file, route.line, "odooPathNotLiteral");
+                continue;
+            }
+            if (route.methods === null) {
+                disclose(from, "SERVES_API", route.path, route.file, route.line, "odooMethodsNotLiteral");
+                continue;
+            }
+            const served = normaliseEndpointPath(route.path).startsWith("/") ? route.path : `/${route.path}`;
+            for (const method of route.methods) {
+                const routeId = nodeId(scope, "API_ROUTE", `${method} ${served}`, LANGUAGE);
+                if (!routeSeen.has(routeId)) {
+                    routeSeen.add(routeId);
+                    nodes.push({
+                        id: routeId,
+                        type: "API_ROUTE",
+                        name: `${method} ${served}`,
+                        file: route.file,
+                        range: { startLine: route.line, endLine: route.line },
+                        language: LANGUAGE,
+                        producedBy: input.producedBy,
+                        resolution: 0,
+                        attrs: { method, pathTemplate: normaliseEndpointPath(served), rawTemplate: served, framework: "odoo" },
+                    });
+                }
+                else {
+                    disclose(from, "SERVES_API", `${method} ${served}`, route.file, route.line, "routeIdCollision");
+                }
+                const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(method, served), null);
+                if (!routeSeen.has(endpointId)) {
+                    routeSeen.add(endpointId);
+                    nodes.push({
+                        id: endpointId,
+                        type: "API_ENDPOINT",
+                        name: `${method} ${normaliseEndpointPath(served)}`,
+                        file: null,
+                        range: null,
+                        language: null,
+                        producedBy: input.producedBy,
+                        resolution: 0,
+                        attrs: { method, pathTemplate: normaliseEndpointPath(served) },
+                    });
+                }
+                push({ from: routeId, to: endpointId, type: "SERVES_API" }, 0);
+            }
+        }
+        // --- GraphQL: strawberry root operations -------------------------------
+        //
+        // `method: "GRAPHQL"`, path `/<OperationType>/<field>` — the gRPC identity
+        // convention transposed (`DEC-NEXT-graphql-operation-identity`). See
+        // `graphql.ts`'s header for why the field NAME is read rather than computed
+        // and what is refused when it cannot be.
+        //
+        // The operation type comes from the slot the schema call puts the class in,
+        // never from the class's own name or its `@strawberry.type(name=...)`:
+        // netbox decorates all ten of its root mixins `name="Query"` and strawberry
+        // discards every one of them, because a base class is never registered as a
+        // type. Reading the decorator would have been right there by accident.
+        for (const schema of graphqlSchemas) {
+            const from = { id: moduleNodeId.get(schema.file) };
+            for (const { slot, written } of schema.opaqueSlots) {
+                disclose(from, "SERVES_API", `${slot}=${written}`, schema.file, schema.line, "graphqlRootSlotUnreadable");
+            }
+            for (const [slot, local] of schema.roots) {
+                /**
+                 * Every class contributing fields to this root, the root itself first.
+                 *
+                 * Python's MRO is the reason the bases are walked at all: netbox's root
+                 * `Query` declares no field of its own and inherits all 246 from ten
+                 * mixins in ten other files. Stopping at the root would report a
+                 * GraphQL API with zero operations, which is a false sentence about the
+                 * repository rather than a disclosed gap.
+                 */
+                const collected = [];
+                const seenClass = new Set();
+                const walk = (name, fromFile, depth) => {
+                    if (depth > 8)
+                        return; // a diamond is legal; a cycle is not worth chasing
+                    const declared = followName(fromFile, name);
+                    if (declared === undefined) {
+                        disclose(from, "SERVES_API", name, schema.file, schema.line, "graphqlRootBaseUnreadable");
+                        return;
+                    }
+                    if (seenClass.has(declared.id))
+                        return;
+                    seenClass.add(declared.id);
+                    collected.push({ declared });
+                    for (const base of declared.declaration.bases ?? []) {
+                        // `*registry['plugins']['graphql_schemas']` — a starred unpacking of
+                        // a registry filled at runtime. netbox's real root has one, and the
+                        // fields behind it are real operations this run cannot see. A
+                        // ledger row, and the resolvable siblings still land.
+                        if (base === null || !/^[A-Za-z_]\w*$/.test(base)) {
+                            disclose(from, "SERVES_API", base ?? "<unreadable base>", declared.file, declared.range.startLine, "graphqlRootBaseUnreadable");
+                            continue;
+                        }
+                        walk(base, declared.file, depth + 1);
+                    }
+                };
+                walk(local, schema.file, 0);
+                for (const { declared } of collected) {
+                    const moduleOf = moduleOfImportIn(declared.file);
+                    const fields = [
+                        ...fieldsFromAttributes(declared.declaration.attributes ?? [], declared.file, schema.naming, moduleOf),
+                    ];
+                    // The other documented spelling: `@strawberry.field def circuit(...)`.
+                    // A method is a separate declaration whose `path` is the class's plus
+                    // its own name, so it is found by prefix rather than nested.
+                    const owner = declared.declaration.path;
+                    for (const candidate of input.parsed.files[declared.file]?.declarations ?? []) {
+                        if (candidate.kind !== "function")
+                            continue;
+                        if (candidate.path.length !== owner.length + 1)
+                            continue;
+                        if (owner.some((part, i) => candidate.path[i] !== part))
+                            continue;
+                        const field = fieldFromMethod(
+                        // `name` is the dotted path — `Query.circuit_by_id`. The field is
+                        // the last segment, and using the whole of it would mint
+                        // `/Query/Query.circuit_by_id`.
+                        candidate.path[candidate.path.length - 1], candidate.decorators ?? [], candidate.decoratorCalls ?? [], declared.file, candidate.range.startLine, schema.naming, moduleOf);
+                        if (field !== null)
+                            fields.push(field);
+                    }
+                    for (const field of fields) {
+                        if (field.name === null) {
+                            // The one refusal this reader exists to make. Computing the
+                            // camel-cased name would write down a string that is nowhere in
+                            // the repository, and a consumer reading the real wire name would
+                            // mint a different id and join nothing.
+                            disclose(from, "SERVES_API", `${operationPath(slot, field.attributeName)} (python name; schema name unreadable)`, field.file, field.line, "graphqlFieldNameNotReadable");
+                            continue;
+                        }
+                        // R1 as soon as the field was reached through the import graph —
+                        // netbox's mixins always are. A root declaring its own fields in
+                        // the schema's own file needed no import and says so.
+                        const level = (field.file === schema.file ? 0 : 1);
+                        if (level > input.reached)
+                            continue;
+                        emitDjangoRoute(field.file, field.line, operationPath(slot, field.name), GRAPHQL_METHOD, level, "strawberry");
+                    }
+                }
+            }
+        }
+        // --- the caller half emitted ------------------------------------------
+        //
+        // After the routes, and deliberately sharing their endpoint identity: a
+        // caller and a route in the same repository must mint the SAME
+        // `API_ENDPOINT` id or the join this pattern exists for does not happen.
+        // That is why `endpointQsp` is called here rather than the path being
+        // formatted a second way.
+        //
+        // Guarded, because `USES_API` is an R2 claim: it rests on import
+        // provenance, and provenance is what separates `requests.get` from a test
+        // client's `client.get`. Emitting it from a run that only reached R0 was
+        // rejected at the boundary as RESOLUTION_EXCEEDS_BATCH — the batch
+        // contract catching a claim stronger than the run that produced it, which
+        // is exactly what it is for.
+        for (const { call, containerId } of input.reached >= 2 ? clientCalls : []) {
+            const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(call.method, call.path), null);
+            if (!routeSeen.has(endpointId)) {
+                routeSeen.add(endpointId);
+                nodes.push({
+                    id: endpointId,
+                    type: "API_ENDPOINT",
+                    name: `${call.method} ${normaliseEndpointPath(call.path)}`,
+                    file: null,
+                    range: null,
+                    language: null,
+                    producedBy: input.producedBy,
+                    resolution: 2,
+                    attrs: { method: call.method, pathTemplate: normaliseEndpointPath(call.path) },
+                });
+            }
+            push({
+                from: containerId,
+                to: endpointId,
+                type: "USES_API",
+                attrs: {
+                    client: call.client,
+                    file: call.file,
+                    line: call.line,
+                    written: call.rawPath,
+                },
+            }, 2);
+        }
+    }
+    if (input.reached < 3)
+        return { nodes, edges, unresolved };
+    // --- pass 3: R3 — shapes ---------------------------------------------------
+    for (const file of files) {
+        const parsed = input.parsed.files[file];
+        const byFull = byFullName.get(file);
+        const containerOf = (scopePath) => {
+            for (let depth = scopePath.length; depth > 0; depth -= 1) {
+                const found = byFull.get(scopePath.slice(0, depth).join("."));
+                if (found !== undefined)
+                    return found;
+            }
+            return undefined;
+        };
+        // RETURNS — a written return annotation, which is a stated shape.
+        for (const declaration of parsed.declarations) {
+            if (declaration.kind !== "function")
+                continue;
+            const self = byFull.get(declaration.name);
+            if (self === undefined)
+                continue;
+            for (const name of typeNamesIn(declaration.returns)) {
+                const target = followName(file, name);
+                if (target !== undefined && isTypeLikeNodeType(target.type) && target.id !== self.id) {
+                    // **An alias is not a shape this adapter has resolved.** `RETURNS` is
+                    // the R3 claim — a *stated shape* — and the shape of `Batch =
+                    // list[Alpha]` is its right-hand side, which cannot be resolved
+                    // without a checker this adapter deliberately does not have
+                    // (DEC-062). Naming the alias is a name-level fact, and `USES_TYPE`
+                    // at R2 already carries it.
+                    //
+                    // This also keeps the two adapters honest against each other: given
+                    // the same `-> Batch`, TypeScript resolves *through* the alias with
+                    // its checker and emits nothing when the underlying type is outside
+                    // the analysed set. Python emitting an R3 edge where TypeScript
+                    // deliberately emits none would be an adapter-specific semantic
+                    // reaching the IR, which is exactly what the parity check exists to
+                    // catch — and it would breach the resolution cap by claiming
+                    // reliability A for a name.
+                    if (aliasIds.has(target.id))
+                        continue;
+                    push({ from: self.id, to: target.id, type: "RETURNS" }, 3);
+                }
+            }
+        }
+        // READS and WRITES — a member access on a local whose class is known.
+        // Direction is taken from the AST's own Load/Store context, never assumed:
+        // `resp.total = x` is a write, and filing it as a read would state the
+        // opposite of what the code does in the field data propagation is built on.
+        const fieldsByEdge = new Map();
+        for (const reference of parsed.references) {
+            const isRead = reference.kind === "attribute";
+            const isWrite = reference.kind === "attribute_write";
+            if ((!isRead && !isWrite) || reference.receiver === null || reference.name === null) {
+                continue;
+            }
+            if (reference.receiver === "self")
+                continue;
+            const container = containerOf(reference.scope);
+            if (container === undefined || container.type !== "FUNCTION")
+                continue;
+            const receiverType = instantiatedType(file, reference.scope, reference.receiver);
+            if (receiverType === undefined)
+                continue;
+            // **A mapped column is a declared member, and `fields` cannot see one.**
+            // `fields` collects annotated assignments only, which is right for a
+            // dataclass and blind to `id = Column(String)` — SQLAlchemy 1.x and Django
+            // both write a column as a plain assignment. Reading only `fields` would
+            // have left every model in either style with no READS edge at all, and the
+            // absence would have looked like a language limit rather than an oversight.
+            const declaresField = (receiverType.declaration.fields ?? []).some((f) => f.name === reference.name) ||
+                (ormShapes.get(receiverType.id)?.fields ?? []).some((f) => f.name === reference.name);
+            if (!declaresField)
+                continue;
+            const edgeType = isWrite ? "WRITES" : "READS";
+            const key = `${container.id}|${receiverType.id}|${edgeType}`;
+            const entry = fieldsByEdge.get(key) ?? {
+                from: container,
+                to: receiverType,
+                type: edgeType,
+                fields: new Set(),
+            };
+            entry.fields.add(reference.name);
+            fieldsByEdge.set(key, entry);
+        }
+        for (const { from, to, type, fields } of fieldsByEdge.values()) {
+            push({ from: from.id, to: to.id, type, attrs: { fields: [...fields].sort() } }, 3);
+        }
+    }
+    // --- the repository-level test-discovery audit -----------------------------
+    //
+    // **"We found no tests" must never be sayable without a warning attached.**
+    // Every other guard here is per declaration, and per-declaration guards all
+    // share one weakness: they can only fire for a file something already
+    // recognised. Sentry proved that is not enough — 7,955 files, 2,593 of them
+    // named `test_*.py`, and zero test cases, with nothing in the ledger to say
+    // so. The audit closes that by asking a question no per-declaration rule can:
+    // *did this repository look like it has tests, and did we produce any?*
+    //
+    // The candidate count comes from `couldHoldTests`, which does not depend on
+    // the project's configuration being read correctly. That independence is the
+    // point — an audit that trusts the same input as the thing it audits agrees
+    // with it and calls that agreement a result.
+    // Two candidate sets, because the two questions are different.
+    //
+    // **Total failure** is judged against `couldHoldTests`, which does not trust
+    // the project's configuration — that independence is the only thing that
+    // would have caught Sentry, where one malformed value made every
+    // config-derived predicate false at once.
+    //
+    // **Partial coverage** is judged against the project's *own* declared rule. A
+    // project that says `python_files = ["check_*.py"]` has excluded
+    // `test_ignored.py` on purpose, and counting it as an uncovered test file
+    // would manufacture a gap out of a correct exclusion.
+    const independentCandidates = files.filter((file) => couldHoldTests(file, pytest));
+    const declaredCandidates = files.filter((file) => isPytestFile(file, pytest));
+    const candidateFiles = independentCandidates;
+    if (candidateFiles.length > 0) {
+        const filesWithCases = new Set(nodes.filter((node) => node.type === "TEST_CASE" && node.file !== null).map((n) => n.file));
+        const cases = nodes.filter((node) => node.type === "TEST_CASE").length;
+        const covered = declaredCandidates.filter((file) => filesWithCases.has(file)).length;
+        // One row, at the repository level, carrying the numbers a reader needs to
+        // judge the claim rather than a bare flag.
+        const detail = `${independentCandidates.length} file(s) could hold tests, ` +
+            `${declaredCandidates.length} match the project's declared patterns, ` +
+            `${covered} produced test cases, ${cases} test case(s) total. ` +
+            `Collection rules: ${pytest.source}; patterns [${pytest.filePatterns.join(", ")}].`;
+        // The source is the module of the first candidate file — the one node
+        // guaranteed to exist for a file whose test declarations produced nothing,
+        // which is the same choice the per-declaration disclosure already makes.
+        const anchor = candidateFiles[0];
+        const reason = cases === 0
+            ? `${REASONS.testDiscoveryFailed} ${detail}`
+            : covered < declaredCandidates.length
+                ? `${REASONS.testDiscoveryPartial} ${detail}`
+                : undefined;
+        if (reason !== undefined) {
+            unresolved.push({
+                fromNodeId: nodeId(scope, "MODULE", symbolQsp(pkg, modulePathOf(anchor)), LANGUAGE),
+                edgeType: "TESTS",
+                rawTarget: "(test discovery audit)",
+                file: anchor,
+                line: 1,
+                producedBy: input.producedBy,
+                reason,
+            });
+        }
+    }
+    return { nodes, edges, unresolved };
+}
+//# sourceMappingURL=extract.js.map