@descryy/adapter-java 0.4.1 → 0.5.1

package/dist/extract.js

@@ -18,12 +18,27 @@
  * ambiguous wildcard import. Each goes to the ledger with its reason — a
  * missing edge is a disclosed gap, a guessed one corrupts every layer above.
  */
-import { edgeId, endpointQsp, nodeId, normaliseEndpointPath, symbolQsp, testCaseQsp, } from "@descryy/ir";
+import { edgeId, endpointQsp, externalQsp, nodeId, normaliseEndpointPath, symbolQsp, testCaseQsp, } from "@descryy/ir";
+import { fileNode } from "@descryy/adapter-common";
 import { jpaModels } from "./jpa.js";
+import { readTransportShapes, SCHEMA as DTO_SCHEMA } from "./dto.js";
+import { hasJacksonShapeEvidence } from "./jackson.js";
 import { SHAPE_LEVEL } from "./shape-reach.js";
 import { jaxrsRoutes, springRoutes } from "./spring.js";
 import { clientCalls, endpointFor } from "./client.js";
+import { resolveBaseSite } from "./client-base.js";
+import { attributeExternalCall, attributeExternalStaticCall, attributeExternalType, } from "./external.js";
 export const LANGUAGE = "java";
+/** Which packaging world an external package name belongs to. The name is the
+ *  ecosystem's, not a resolved classpath's: `org.slf4j:slf4j-api` ships the
+ *  package `org.slf4j`, and `org.slf4j` is what the source writes and what the
+ *  node is identified by. */
+const EXTERNAL_ECOSYSTEM = "maven";
+/** An external node is attributed from the file's own `import` block — module
+ *  resolution and nothing more. R1 exactly: never R0 (the import IS the
+ *  resolution), never R4 (nothing observed it run).
+ *  `DEC-NEXT-external-symbol-nodes-at-the-dependency-boundary`. */
+const EXTERNAL_RESOLUTION = 1;
 /** Confidence by the level an edge's evidence earned, never the level reached. */
 const CONFIDENCE = { 0: 0.5, 1: 0.7, 2: 0.9, 3: 0.95 };
 /** A compilation unit with no `package` declaration. Not a legal package name,
@@ -58,6 +73,39 @@ const REASONS = {
         "run's analysed set — most often inherited from a supertype or interface this run did not " +
         "read, rather than declared directly on the controller.",
 };
+/** The two spellings `isX()` is allowed to stand for. */
+const BOOLEANS = new Set(["boolean", "Boolean"]);
+/**
+ * `java.beans.Introspector.decapitalize`, to the letter — `TotalAmount`
+ * becomes `totalAmount`, and `URL` stays `URL`. Written out rather than
+ * lower-casing the first character, because the two-leading-capitals rule is
+ * the half that decides whether `getURL()` names a field called `uRL` (it
+ * does not) and a mapping lookup on the wrong spelling silently finds nothing.
+ */
+function decapitalize(name) {
+    const second = name[1];
+    if (second !== undefined && second !== second.toLowerCase() && /[A-Z]/.test(second))
+        return name;
+    return name[0].toLowerCase() + name.slice(1);
+}
+/** The property a JavaBeans accessor name denotes, or `undefined` for a name
+ *  that is not one. `isForm` distinguishes the boolean spelling, which is only
+ *  legal over a `boolean`/`Boolean`. */
+function beansProperty(name) {
+    if (name.startsWith("get") && name.length > 3)
+        return { name: decapitalize(name.slice(3)), isForm: false };
+    if (name.startsWith("is") && name.length > 2)
+        return { name: decapitalize(name.slice(2)), isForm: true };
+    return undefined;
+}
+/** A declared type reduced to the name the two sides can be compared on:
+ *  generics dropped, package qualification dropped. `java.lang.String` and
+ *  `String` are one type written two ways, and refusing the edge over the
+ *  spelling would lose a real read. */
+function simpleTypeName(written) {
+    const bare = written.replace(/<.*$/s, "").replace(/\[\]/g, "").trim();
+    return bare.slice(bare.lastIndexOf(".") + 1);
+}
 /**
  * Every declared type, indexed before any node id exists, then every JPA
  * entity resolved against that index.
@@ -105,6 +153,51 @@ export function readEntities(units) {
     }
     return entitiesByType;
 }
+/**
+ * The fallback graph when `extract()` throws mid-run, per
+ * `DEC-NEXT-degraded-graph-shape-for-adapters-without-one.md`.
+ *
+ * `FILE`, not `MODULE`: a Java module's identity here is `identityPackage`,
+ * and `identityPackage` is derived from `unit.packageName` — the `package
+ * a.b.c;` statement *inside* the file (`roots.ts`'s `identityPackage`,
+ * layered over a source-set anchor only when one resolves; the package name
+ * itself is never filesystem-derivable, since Java allows — and this corpus
+ * contains — a file whose directory does not match its declared package).
+ * A mid-extraction throw means exactly this machinery cannot be trusted to
+ * have run to completion. Unlike Go's import path or Rust's crate/module
+ * path — both resolved from the file's own location plus a manifest, never
+ * from parsed content — nothing about a Java file's identity is recoverable
+ * without a successful parse. `FILE` (via the shared
+ * `@descryy/adapter-common#fileNode` helper) is the fact that survives: the
+ * file exists, on disk, at this path, and that is all this function claims.
+ *
+ * One disclosure row, not one per file — the fact is about the run. Anchored
+ * to the first file's `FILE` node because the ledger requires a `fromNodeId`
+ * and `FILE` is the only node type this path emits.
+ */
+export function degradedGraph(input) {
+    const scope = { repo: input.repo, workspace: input.workspace };
+    const nodes = input.files.map((file) => fileNode(scope, file, input.producedBy));
+    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 ${String(input.files.length)} Java file(s). ${input.cause}. ` +
+                    "Files are listed because their existence and path are facts 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.",
+                attrs: { refusalClass: "capability-gap" },
+            },
+        ];
+    return { nodes, edges: [], unresolved };
+}
 /**
  * The qualified symbol path for a Java symbol.
  *
@@ -226,6 +319,40 @@ export function extract(input) {
     const scope = input.scope;
     /** Outbound HTTP calls, collected in the method loop and emitted with the routes. */
     const clientCallSites = [];
+    /**
+     * DEC-164: caller node id -> the base this reader traced for it. First
+     * writer wins, so a method making two calls is described by the first one
+     * read. Patched onto the node after the walk, the way `adapter-csharp`
+     * does it — the node exists before its calls are read.
+     */
+    const functionClientBase = new Map();
+    /**
+     * ONE PROGRAM, READ TWICE — DEC-164's origin rule needs every base in the
+     * program before any single call site can be judged.
+     *
+     * `client-base.ts` admits an absolute call path only at an origin some base
+     * in this same program resolves to, and Java is the language that forces
+     * this to be program-wide rather than per file: one public class per file is
+     * not a style here but a rule, so the constant and the absolute call site
+     * CANNOT be in the same file. This pre-pass reads only the declaration
+     * tables the parse already built — no call sites, no scope resolution — so
+     * it is cheap, and with no absolute base anywhere it yields an empty set and
+     * changes nothing.
+     */
+    const knownOrigins = new Set();
+    for (const unit of input.units) {
+        const sites = [];
+        for (const type of unit.types) {
+            sites.push(...type.fieldBases.values());
+            for (const method of type.methods)
+                sites.push(...method.localBases.values());
+        }
+        for (const site of sites) {
+            const { origin } = resolveBaseSite(site, unit.stringConstants);
+            if (origin !== undefined)
+                knownOrigins.add(origin);
+        }
+    }
     /**
      * Returns `false` when the edge's evidence outranks the level this run
      * reached, so the caller can disclose it instead of dropping it silently.
@@ -254,6 +381,72 @@ export function extract(input) {
         file: unit.file,
         line: ref.line,
     });
+    /**
+     * Node ids already minted for a dependency symbol — one node per symbol and
+     * per node type, not per reference site.
+     *
+     * The three settled rules are asserted here rather than argued: the qsp
+     * carries an `ext:` marker (`externalQsp`), the node claims R1 and may never
+     * claim R0 or R4, and it owns no outgoing edge because nothing read its body.
+     * `thirdParty` and `binding` ride in `attrs`, outside the hash — a package
+     * that moved between the JDK and a jar would otherwise change identity with
+     * no line of source changing.
+     */
+    const externalIds = new Map();
+    const mintExternal = (attribution, type) => {
+        if (input.reached < EXTERNAL_RESOLUTION)
+            return null;
+        const qsp = externalQsp(attribution.moduleOrNamespace, attribution.symbolPath);
+        const key = `${type}\u0000${qsp}`;
+        const existing = externalIds.get(key);
+        if (existing !== undefined)
+            return existing;
+        const id = nodeId(scope, type, qsp, LANGUAGE);
+        externalIds.set(key, id);
+        nodes.push({
+            id,
+            type,
+            name: attribution.symbolPath[attribution.symbolPath.length - 1] ?? "",
+            // No file and no range: the symbol lives in a dependency, and a node that
+            // named a file here would be invalidated by a source file it has nothing
+            // to do with.
+            file: null,
+            range: null,
+            language: LANGUAGE,
+            producedBy: input.producedBy,
+            resolution: EXTERNAL_RESOLUTION,
+            attrs: { thirdParty: attribution.thirdParty, binding: attribution.binding },
+            external: {
+                ecosystem: EXTERNAL_ECOSYSTEM,
+                // Identity, and it is the package the source wrote — never a resolved
+                // classpath entry, never a Maven coordinate, never a version.
+                moduleOrNamespace: attribution.moduleOrNamespace,
+            },
+        });
+        return id;
+    };
+    /**
+     * The context `external.ts` attributes against, for one compilation unit.
+     * `ownPackages` and `analysed` are the repository's own; the import tables are
+     * the file's. Built lazily per unit and cached, since the two repository-wide
+     * sets are the same object every time.
+     */
+    const externalContexts = new Map();
+    const externalContextFor = (unit) => {
+        const cached = externalContexts.get(unit.file);
+        if (cached !== undefined)
+            return cached;
+        const context = {
+            imports: {
+                singleTypeImports: unit.singleTypeImports,
+                staticMemberImports: unit.staticMemberImports,
+            },
+            ownPackages,
+            analysed: analysedFqns,
+        };
+        externalContexts.set(unit.file, context);
+        return context;
+    };
     const ledger = (from, edgeType, rawTarget, at, reason, attrs) => {
         unresolved.push({
             fromNodeId: from,
@@ -284,6 +477,9 @@ export function extract(input) {
     // step earlier — it decides the run's resolution level from it — so it is
     // read there and handed on here rather than computed twice (`shape-reach.ts`).
     const entitiesByType = input.entities ?? readEntities(input.units);
+    // Transport shapes a Spring ROUTE declares — never a class this reader
+    // guessed at from its name (DEC-043). Own file, `dto.ts`.
+    const shapesByType = readTransportShapes(input.units);
     for (const unit of input.units) {
         const pkg = unit.identityPackage;
         // Named by its *primary* type, which Java requires to match the file name
@@ -324,7 +520,12 @@ export function extract(input) {
         // whole batch above, since inherited mappings cross compilation units.
         for (const type of unit.types) {
             const model = entitiesByType.get(`${unit.identityPackage}::${type.fqn}`);
-            const kind = model === undefined ? "CLASS" : "MODEL";
+            // A mapped entity outranks a declared transport shape where both somehow
+            // apply: a wrong `MODEL` is a claim about a database and a wrong `DTO` a
+            // claim about a wire format, so the narrower evidence wins — the same
+            // tie-break, for the same reason, as `adapter-python`'s.
+            const shape = model === undefined ? shapesByType.get(`${unit.identityPackage}::${type.fqn}`) : undefined;
+            const kind = model !== undefined ? "MODEL" : shape !== undefined ? "DTO" : "CLASS";
             const id = nodeId(scope, kind, qspFor(type.fqn, unit), LANGUAGE);
             const declaredAs = byFqn.get(type.fqn);
             if (declaredAs === undefined)
@@ -345,11 +546,35 @@ export function extract(input) {
              * (one annotation, read at R0/R1) and *this is its mapped shape* (the
              * column-by-column read below) — and only the second is R3-grade. So
              * the shape's level is also stated separately in `attrs.shapeResolution`,
-             * DEC-058's carrier, which `descry-core`'s contract engine already
-             * reads: a consumer comparing shapes gets the shape's evidence, not the
-             * node's weakest.
+             * DEC-058's carrier.
+             *
+             * **Node-scoped, and deliberately unrelated to the `USES_API`-edge
+             * `shapeResolution` this file also now writes** (see
+             * `responseShapeEvidence` below, `DEC-NEXT-dto-shape-evidence-for-api-
+             * contracts`). This one is the JPA-mapped, PERSISTED database shape —
+             * `descry-core`'s contract engine (`engine.ts:286`) reads only the
+             * edge-level attribute for API wire-shape comparison and never reads a
+             * node-level `shapeResolution` at all, on a `MODEL` or otherwise. A
+             * class can be both — an entity Jackson also serializes straight to the
+             * wire — but the two facts rest on different annotations (JPA's vs.
+             * Jackson's) and are asserted independently; this one is not the
+             * mechanism the API-shape ruling built.
              */
             let level = 0;
+            if (shape !== undefined) {
+                // The declaration this node rests on, named the way a `MODEL` names
+                // its ORM — a node type minted from evidence that does not state the
+                // evidence is indistinguishable from a guess outside the adapter.
+                attrs["schema"] = DTO_SCHEMA;
+                attrs["declaredDirections"] = shape.roles;
+                // NAMES only, and no `shapeResolution`/`fieldDetail` and no level
+                // raise: whether a plain class body's field list is R3-grade evidence
+                // is a filed, unanswered question, and `shape-reach.ts` is untouched
+                // by design. Golden 05 asks for exactly this — the DTO nodes without
+                // field detail rather than guessed fields.
+                if (shape.fields.length > 0)
+                    attrs["fields"] = shape.fields;
+            }
             if (model !== undefined) {
                 attrs["orm"] = "jpa";
                 if (model.table !== null)
@@ -465,6 +690,41 @@ export function extract(input) {
         }
         return { reason: bySimpleName.has(written) ? REASONS.unknownName : REASONS.outside };
     };
+    /**
+     * `DEC-NEXT-dto-shape-evidence-for-api-contracts`'s ruling, applied at the
+     * one place a Java `USES_API` edge states a response type: a class literal
+     * on the call (`getForObject(url, OrderResponse.class)`, read by
+     * `classLiteralArgumentOf` in `parse.ts`). Mirrors `adapter-python`'s
+     * `extract.ts:3512-3519` gate — resolve the written name through the SAME
+     * scope rules every other name in this adapter goes through, then require
+     * real Jackson evidence before claiming R3, never the class literal alone.
+     *
+     * Gated on `input.reached >= 3` INSIDE the returned attrs rather than by an
+     * early return one level up — same reasoning as `adapter-python`'s own
+     * comment at that site: a guard placed above this function would be green
+     * at R3 and silently wrong at R2, the monotonic sweep's own failure mode.
+     *
+     * A `MODEL` is excluded even when Jackson-annotated: that is a
+     * database-persistence claim (see the comment beside `attrs.shapeResolution`
+     * at the `MODEL` node above), and DEC-NEXT scopes this ruling to *wire*
+     * shape evidence, a different fact resting on different annotations.
+     */
+    const responseShapeEvidence = (unit, written) => {
+        if (input.reached < 3 || written === undefined)
+            return {};
+        const resolved = resolveType(unit, written);
+        if (!("declared" in resolved))
+            return {};
+        const { declared } = resolved;
+        const key = `${declared.unit.identityPackage}::${declared.type.fqn}`;
+        if (entitiesByType.has(key))
+            return {}; // a MODEL: persisted shape, not wire shape
+        if (shapesByType.get(key) === undefined)
+            return {}; // not an established DTO
+        if (!hasJacksonShapeEvidence(declared.type, declared.unit))
+            return {};
+        return { responseType: declared.id, shapeResolution: 3 };
+    };
     /**
      * The declared type of a field, following the scopes Java says are in scope.
      *
@@ -530,6 +790,21 @@ export function extract(input) {
         }
         return undefined;
     };
+    /**
+     * Packages this repository declares for itself, and every fully-qualified
+     * name this run read. Both are what `external.ts` refuses against: a type
+     * under one of our own packages that went unanalysed is unanalysed code of
+     * OURS, and calling it a dependency is the error that never surfaces.
+     *
+     * This is also the only guard against `REASONS.outside`'s disclosed
+     * cross-language case — 238 of `okhttp`'s 458 `outside` rows name a type
+     * declared in a `.kt` file in this same repository. A Kotlin class in a
+     * package this repository's Java sources also declare is ours by this check.
+     * One in a package no Java source declares is not caught, and stays a
+     * disclosed limit of a Java-only reader.
+     */
+    const ownPackages = new Set(input.units.map((unit) => unit.packageName).filter((name) => name !== "" && name !== DEFAULT_PACKAGE));
+    const analysedFqns = new Set(byFqn.keys());
     for (const unit of input.units) {
         const moduleId = moduleIdOf.get(unit.file);
         if (moduleId === undefined)
@@ -583,8 +858,32 @@ export function extract(input) {
                     const read = clientCalls(method, member.id, (name) => writtenReceiverType(method, declared, name), 
                     // Source set read from the identity-package anchor, not pattern-
                     // matched off the file path.
-                    isTestSourceSet(unit.identityPackage));
-                    clientCallSites.push(...read.calls);
+                    isTestSourceSet(unit.identityPackage), (name) => {
+                        // DEC-164, resolved with the same scope rules `writtenReceiverType`
+                        // uses: a local shadows a field, and `this.x` names the field.
+                        const viaThis = name.startsWith("this.");
+                        const bare = viaThis ? name.slice("this.".length) : name;
+                        if (bare.includes("."))
+                            return undefined;
+                        const site = (viaThis ? undefined : method.localBases.get(bare)) ?? type.fieldBases.get(bare);
+                        return site === undefined ? undefined : resolveBaseSite(site, unit.stringConstants).base;
+                    }, knownOrigins);
+                    for (const call of read.calls) {
+                        clientCallSites.push({
+                            ...call,
+                            ...responseShapeEvidence(unit, call.responseTypeWritten),
+                        });
+                        if (call.clientBase !== undefined && !functionClientBase.has(call.fromId)) {
+                            functionClientBase.set(call.fromId, call.clientBase);
+                        }
+                    }
+                    for (const refusal of read.refusals) {
+                        // A refusal still states a base when DEC-164 reached one — 08b's
+                        // whole point is that `unresolved` is a reading, not a silence.
+                        if (refusal.clientBase !== undefined && !functionClientBase.has(refusal.fromId)) {
+                            functionClientBase.set(refusal.fromId, refusal.clientBase);
+                        }
+                    }
                     for (const refusal of read.refusals) {
                         ledger(refusal.fromId, "USES_API", refusal.raw, { file: unit.file, line: refusal.line }, refusal.reason, 
                         // Unset `refusalClass` means unclassified (DEC-242) — `attrs`
@@ -595,9 +894,20 @@ export function extract(input) {
                                 blockedBy: refusal.blockedBy,
                                 refusalClass: refusal.refusalClass,
                                 ...(refusal.argumentKind === undefined ? {} : { argumentKind: refusal.argumentKind }),
+                                ...(refusal.clientBase === undefined ? {} : { clientBase: refusal.clientBase }),
+                                ...(refusal.callPath === undefined ? {} : { callPath: refusal.callPath }),
                             });
                     }
                 }
+                /**
+                 * Mapped-field reads, grouped by the entity they land on. Edge
+                 * identity is `(from, to, type)`, so a method reading three columns
+                 * of one entity is **one** edge naming three fields, not three edges
+                 * — a singular `field` attribute would make the second read
+                 * unrepresentable (DEC-046). Sorted on the way out so the attribute
+                 * is a property of the source rather than of statement order.
+                 */
+                const fieldReads = new Map();
                 for (const ref of method.refs) {
                     if (ref.kind === "type") {
                         emitTypeRef(member.id, unit, ref);
@@ -612,6 +922,14 @@ export function extract(input) {
                         emitTypeRef(member.id, unit, ref);
                         continue;
                     }
+                    const read = mappedFieldRead(method, declared, unit, ref);
+                    if (read !== undefined) {
+                        const fields = fieldReads.get(read.to);
+                        if (fields === undefined)
+                            fieldReads.set(read.to, new Set([read.field]));
+                        else
+                            fields.add(read.field);
+                    }
                     // `method`, not `member.method` — an overload set's node carries
                     // only the *first* overload, so resolving against
                     // `member.method.locals` would type overload A's variables with
@@ -619,6 +937,11 @@ export function extract(input) {
                     // could see.
                     emitCall(member, method, declared, unit, ref);
                 }
+                for (const [to, fields] of fieldReads) {
+                    if (push({ from: member.id, to, type: "READS", attrs: { fields: [...fields].sort() } }, 2))
+                        continue;
+                    ledger(member.id, "READS", [...fields].sort().join(", "), { file: unit.file, line: method.startLine }, REASONS.belowLevel);
+                }
             }
         }
     }
@@ -630,6 +953,27 @@ export function extract(input) {
             }
             return;
         }
+        // A type reference that left the repository. When a binding the developer
+        // wrote settles which package and which type, it mints a `CLASS` standing
+        // for that type in the dependency and is reached by `USES_TYPE` — the node
+        // type follows the EDGE, because that is what the edge means. An attributed
+        // site files no ledger row: a site that resolves to a node is not an
+        // `UnresolvedRef`, and filing both would count it twice.
+        //
+        // `member` refs are excluded. `parse.ts` calls them a *candidate* only —
+        // `Status.PENDING` is an enum constant and `Map.Entry` is a nested type, and
+        // nothing written tells them apart. Minting a `CLASS` for the first is a
+        // wrong fact, so both are declined.
+        if (ref.kind === "type" && resolved.reason === REASONS.outside) {
+            const attribution = attributeExternalType(ref.name, externalContextFor(unit));
+            if (attribution !== null) {
+                const to = mintExternal(attribution, "CLASS");
+                if (to !== null) {
+                    push({ from, to, type: "USES_TYPE" }, EXTERNAL_RESOLUTION);
+                    return;
+                }
+            }
+        }
         ledger(from, "USES_TYPE", ref.name, file(unit, ref), resolved.reason);
     }
     function emitCall(member, method, owner, unit, ref) {
@@ -640,6 +984,18 @@ export function extract(input) {
         const resolvedType = method.isTest ? "TESTS" : "CALLS";
         const target = receiverTarget(method, owner, unit, ref);
         if ("reason" in target) {
+            // A call whose receiver's **written** type left the repository. Java
+            // writes its types down where Go and PHP do not, so this is the half that
+            // makes the boundary worth attributing here at all: `Logger log` under
+            // `import org.slf4j.Logger` says which package `log.info(...)` reaches.
+            //
+            // Only `outside` — `untypedReceiver` means no type was written at this
+            // reference (a `var`, a chained call, a generic variable) and there is
+            // nothing to read; `unknownName` means the simple name IS declared in this
+            // repository and calling it a dependency would be wrong.
+            if (target.reason === REASONS.outside && externalCall(member, method, owner, unit, ref)) {
+                return;
+            }
             ledger(member.id, "CALLS", ref.raw, file(unit, ref), target.reason);
             return;
         }
@@ -656,6 +1012,21 @@ export function extract(input) {
             }
         }
         if (found === undefined) {
+            // An unqualified name bound by a `static` import whose declaring type is
+            // not ours. This is how every JUnit assertion is written, and it arrives
+            // here rather than at `outside` because the *enclosing* type resolved
+            // fine — it simply declares no such member. Python's `from x import y`
+            // shape, and the larger half there too.
+            if (ref.receiver === undefined) {
+                const attribution = attributeExternalStaticCall(ref.name, externalContextFor(unit));
+                if (attribution !== null) {
+                    const to = mintExternal(attribution, "FUNCTION");
+                    if (to !== null) {
+                        push({ from: member.id, to, type: "CALLS" }, EXTERNAL_RESOLUTION);
+                        return;
+                    }
+                }
+            }
             ledger(member.id, "CALLS", ref.raw, file(unit, ref), REASONS.unmodelled);
             return;
         }
@@ -666,6 +1037,113 @@ export function extract(input) {
             ledger(member.id, "CALLS", ref.raw, file(unit, ref), REASONS.belowLevel);
         }
     }
+    /**
+     * `FUNCTION --READS--> MODEL` for `order.getTotalAmount()` — golden 07.
+     *
+     * **Why the accessor and not the field.** A JPA entity's mapped fields are
+     * `private` in essentially all real code, because field-access mapping is
+     * the default, so a route handler in another class cannot name the field at
+     * all. An adapter admitting only `order.totalAmount` would declare `READS`
+     * and then emit it almost nowhere — a declaration that is true of the code
+     * and useless about it. The read Java actually writes is the accessor.
+     *
+     * **Why that is not the name heuristic rule 2 forbids.** Four *written*
+     * things have to agree before an edge exists, and no name decides any of
+     * them on its own:
+     *
+     *   1. the receiver's declared type resolves — same `receiverTarget` every
+     *      `CALLS` edge here goes through, so the receiver is typed by the
+     *      source or refused;
+     *   2. that type was admitted as a `MODEL` by `jpa.ts`, on an
+     *      `@Entity`/`@Document` annotation;
+     *   3. the property the accessor denotes under the JavaBeans contract is a
+     *      **mapped field** of that entity — present in the mapping that was
+     *      read, not merely a declared member; and
+     *   4. the entity declares a **zero-parameter** method of exactly that name
+     *      whose **declared return type is the field's declared type**.
+     *
+     * (4) is the corroboration that makes (3) more than a spelling: a computed
+     * `getDisplayName()` names no column, and a `getTotal()` returning `Money`
+     * over a `long total` column does not agree with the mapping and is
+     * refused. JPA's own property-access mode maps *through* this contract, so
+     * following it reads a declaration rather than inferring from a name.
+     *
+     * **Level 2, not 3.** `shape-reach.ts` records that exactly one fact kind
+     * in this package reaches R3 — the mapped field *shape* on a `MODEL` — and
+     * this is not that fact. This edge says a member is read **by name**; it
+     * compares no shapes and proves none, and the resolution cap makes a
+     * name-level fact R2. The shape itself is already on the `MODEL` node at
+     * R3, carrying its own `shapeResolution`; this edge points at it and claims
+     * no more than the pointing.
+     *
+     * **Reads only.** `order.setTotal(x)` is a write and is deliberately not
+     * admitted here: a write filed as a read is not a thinner claim, it is the
+     * opposite one, and data propagation is built on the direction.
+     */
+    function mappedFieldRead(method, owner, unit, ref) {
+        if (ref.receiver === undefined || ref.receiver === "this")
+            return undefined;
+        const property = beansProperty(ref.name);
+        if (property === undefined)
+            return undefined;
+        const target = receiverTarget(method, owner, unit, ref);
+        if ("reason" in target)
+            return undefined;
+        const entity = entitiesByType.get(`${target.declared.unit.identityPackage}::${target.declared.type.fqn}`);
+        if (entity === undefined)
+            return undefined;
+        if (!entity.fields.some((each) => each.name === property.name))
+            return undefined;
+        const accessor = target.declared.type.methods.find((each) => each.name === ref.name && each.parameterNames.size === 0);
+        if (accessor === undefined)
+            return undefined;
+        const field = target.declared.type.fieldDeclarations.find((each) => each.name === property.name);
+        if (field?.writtenType === undefined)
+            return undefined;
+        const returns = accessor.returnType;
+        if (returns.kind !== "named" && returns.kind !== "primitive")
+            return undefined;
+        const column = simpleTypeName(field.writtenType);
+        if (simpleTypeName(returns.name) !== column)
+            return undefined;
+        // `isX()` is the boolean accessor and nothing else — JavaBeans says so,
+        // and without the check an `isbn` column would be read out of `isBn()`.
+        if (property.isForm && !BOOLEANS.has(column))
+            return undefined;
+        return { to: target.declared.id, field: property.name };
+    }
+    /**
+     * Mint the dependency symbol a call's receiver reaches, and the `CALLS` edge
+     * into it. `true` when it did; `false` leaves the site to the ledger.
+     *
+     * The receiver's type is read **as written** and never inferred, by the same
+     * two scopes `receiverTarget` reads — a local or parameter's declared type,
+     * then a field's — plus the static case where the receiver is itself a type
+     * name. `writtenReceiverType` returns `undefined` for a `var`, a name declared
+     * twice, a chained call and a dotted receiver, and each of those is a site
+     * where the source wrote no type down.
+     */
+    function externalCall(member, method, owner, unit, ref) {
+        const receiver = ref.receiver;
+        if (receiver === undefined || receiver === "this")
+            return false;
+        const bare = receiver.startsWith("this.") ? receiver.slice("this.".length) : receiver;
+        if (bare === "" || bare.includes("."))
+            return false;
+        // A local or field shadows a type of the same spelling, as the language
+        // says — so the written type is asked for first and the receiver is read as
+        // a type name only when nothing local bound it.
+        const written = writtenReceiverType(method, owner, receiver) ??
+            (/^[A-Z]/.test(bare) ? bare : undefined);
+        const attribution = attributeExternalCall(written, ref.name, externalContextFor(unit));
+        if (attribution === null)
+            return false;
+        const to = mintExternal(attribution, "FUNCTION");
+        if (to === null)
+            return false;
+        push({ from: member.id, to, type: "CALLS" }, EXTERNAL_RESOLUTION);
+        return true;
+    }
     /** Which type a call's receiver names, from what the source wrote down. */
     function receiverTarget(method, owner, unit, ref) {
         const receiver = ref.receiver;
@@ -830,11 +1308,33 @@ export function extract(input) {
                 // 12 of Java's 16 relative-path call sites are test files, none
                 // production — `test` feeds Verification status (integration
                 // coverage), not the confidence label. DEC-189.
-                attrs: { callerKind: call.callerKind, via: call.method },
+                attrs: {
+                    callerKind: call.callerKind,
+                    via: call.method,
+                    ...(call.responseType === undefined
+                        ? {}
+                        : { responseType: call.responseType, shapeResolution: call.shapeResolution }),
+                },
             }, 2);
         }
         nodes.push(...routeNodes.values(), ...endpointNodes.values());
     }
+    // DEC-164's client base, patched onto the caller. NOT behind the R2 gate
+    // the `USES_API` edge sits behind: the golden asserts `attrs.clientBase` at
+    // R2 and the field is a reading of the source, not of a rung.
+    // `adapter-python` shipped this patch after an `input.reached` guard and it
+    // was green at R3 and absent at R2 — only the monotonic sweep saw it.
+    //
+    // The field's ABSENCE is DEC-164's fourth state: a method whose receiver's
+    // declaration this reader never saw says nothing about a base, rather than
+    // saying `none`.
+    for (let i = 0; i < nodes.length; i += 1) {
+        const node = nodes[i];
+        const base = functionClientBase.get(node.id);
+        if (base === undefined)
+            continue;
+        nodes[i] = { ...node, attrs: { ...node.attrs, clientBase: base } };
+    }
     return { nodes, edges, unresolved };
 }
 //# sourceMappingURL=extract.js.map