@descryy/adapter-kotlin 0.4.1 → 0.5.1

package/dist/extract.js

@@ -22,8 +22,25 @@
  * runs Java→Kotlin; ktor is 2,324 `.kt` against 1 `.java`. A rule with zero witnesses is declared
  * absent rather than written blind.
  */
-import { endpointQsp, nodeId, normaliseEndpointPath, symbolQsp, } from "@descryy/ir";
+import { endpointQsp, externalQsp, nodeId, normaliseEndpointPath, symbolQsp, } from "@descryy/ir";
+import { fileNode } from "@descryy/adapter-common";
+import { SHAPE_LEVEL } from "./shape-reach.js";
+import { fieldReadsIn as jpaFieldReadsIn } from "./jpa-reads.js";
+import { hasSerializationEvidence } from "./serialization.js";
+import { attributeExternal, externalImportTable, } from "./external.js";
 const LANGUAGE = "kotlin";
+/** Which packaging world an external package name belongs to. Kotlin publishes
+ *  to Maven repositories like Java does, and the identity is the package the
+ *  source writes — never a coordinate, never a resolved classpath entry. */
+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;
+/** The confidence an R1 edge carries in this adapter, matching every other R1
+ *  edge it emits. */
+const EXTERNAL_CONFIDENCE = 0.7;
 const typeKey = (identityPackage, path) => `${identityPackage}::${path.join(".")}`;
 // identityPackage is `module[/sourceSet]/package`; the package is the segment
 // after the last slash and is what an import path states.
@@ -34,6 +51,15 @@ export function extract(input) {
     const unresolved = [];
     const scope = input.scope;
     const typesByKey = new Map();
+    /**
+     * The raw declaration and its own file behind each `typesByKey` entry —
+     * `DeclaredType` itself carries no annotations or import list, and
+     * `responseShapeEvidence` (DEC-NEXT-dto-shape-evidence-for-api-contracts)
+     * needs both to verify kotlinx.serialization evidence. Populated in
+     * lockstep with `typesByKey` below so the two can never disagree on which
+     * key names which declaration.
+     */
+    const declByKey = new Map();
     const funcsByKey = new Map();
     const moduleIdOf = new Map();
     const seenEdges = new Set();
@@ -67,6 +93,93 @@ export function extract(input) {
         else if (!seen.includes(to))
             seen.push(to);
     };
+    /**
+     * 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 standard library 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,
+                moduleOrNamespace: attribution.moduleOrNamespace,
+            },
+        });
+        return id;
+    };
+    /**
+     * Mint the dependency symbol a reference reaches, and the edge into it.
+     * `true` when it did; `false` leaves the site to the caller's refusal.
+     *
+     * The node type follows the EDGE, not the shape of the name: `USES_TYPE`
+     * names a type so it mints a `CLASS`, `CALLS` names a callable so it mints a
+     * `FUNCTION`. A call out of a test function is `CALLS` and never `TESTS` —
+     * `TESTS` asserts coverage, and this run read nothing of the dependency's
+     * body (`DEC-NEXT-external-edge-is-calls-not-tests`).
+     */
+    const externalEdge = (from, unit, written, extra, edgeType) => {
+        const attribution = attributeExternal(written, extra, externalContextFor(unit));
+        if (attribution === null)
+            return false;
+        const to = mintExternal(attribution, edgeType === "USES_TYPE" ? "CLASS" : "FUNCTION");
+        if (to === null)
+            return false;
+        push({ from, to, type: edgeType }, EXTERNAL_CONFIDENCE, EXTERNAL_RESOLUTION);
+        return true;
+    };
+    /** The context `external.ts` attributes against, for one file. The import
+     *  table is the file's; `ownPackages` is the repository's. */
+    const externalContexts = new Map();
+    const externalContextFor = (unit) => {
+        const cached = externalContexts.get(unit.file);
+        if (cached !== undefined)
+            return cached;
+        const context = {
+            imports: externalImportTable(unit.imports),
+            ownPackages,
+        };
+        externalContexts.set(unit.file, context);
+        return context;
+    };
+    /**
+     * Packages this repository declares for itself. A symbol under one of them is
+     * OURS whether or not this run read it.
+     *
+     * This is also the only guard against the cross-language case a Kotlin-only
+     * reader cannot see: `okhttp` declares types in both `.kt` and `.java`, and a
+     * Java class in a package this repository's Kotlin sources also declare is
+     * ours by this check. One in a package no Kotlin source declares is not
+     * caught, and stays a disclosed limit.
+     */
+    const ownPackages = new Set(input.files.map((each) => each.packageName).filter((name) => name !== ""));
     const refuse = (fromNodeId, edgeType, rawTarget, file, line, reason, attrs) => {
         unresolved.push({
             fromNodeId,
@@ -152,20 +265,92 @@ export function extract(input) {
             }
             if (typesByKey.has(key))
                 continue;
-            const id = nodeId(scope, "CLASS", symbolQsp(unit.identityPackage, path), LANGUAGE);
-            typesByKey.set(key, { id, kind: decl.kind, identityPackage: unit.identityPackage, file: unit.file, path });
+            /**
+             * Kind is decided BEFORE the id is minted (DEC-004), never patched on
+             * after: the kind is part of the id, and everything downstream resolves
+             * references out of `typesByKey`. A `MODEL` is a framework claim earned
+             * from one annotation in `jpa.ts` — never from the name, which golden
+             * 07 and 12 exist to punish.
+             */
+            const model = input.reach?.entities.get(key);
+            const kind = model === undefined ? "CLASS" : "MODEL";
+            const id = nodeId(scope, kind, symbolQsp(unit.identityPackage, path), LANGUAGE);
+            // `isModel` is what golden 07's READS resolver asks: an edge to a model
+            // is a different claim from an edge to a plain class.
+            typesByKey.set(key, {
+                id,
+                kind: decl.kind,
+                identityPackage: unit.identityPackage,
+                file: unit.file,
+                path,
+                isModel: model !== undefined,
+            });
+            declByKey.set(key, { decl, unit });
+            const attrs = { declarationForm: decl.kind };
+            /**
+             * The level this node's strongest fact carries. A `MODEL` bundles two
+             * different claims — *this class is persisted* (one annotation, read at
+             * R0) and *this is its mapped shape* (the column-by-column read) — and
+             * only the second is R3-grade, so the shape's level is stated separately
+             * in `attrs.shapeResolution`, DEC-058's carrier.
+             *
+             * **Node-scoped, and deliberately unrelated to the `USES_API`-edge
+             * `shapeResolution` this file also now writes** (see
+             * `responseShapeEvidence` above,
+             * `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
+             * also serialized straight to the wire via kotlinx.serialization — but
+             * the two facts rest on different annotations (JPA's vs.
+             * kotlinx.serialization's) and are asserted independently; this one is
+             * not the mechanism the API-shape ruling built.
+             */
+            let level = 0;
+            if (model !== undefined) {
+                attrs["orm"] = "jpa";
+                if (model.table !== null)
+                    attrs["table"] = model.table;
+                if (model.fields.length > 0) {
+                    attrs["fields"] = model.fields;
+                    /**
+                     * **Never above what the run reached.** A caller that capped this
+                     * adapter at R2 gets the same shape one level down; a node stamped
+                     * R3 unconditionally is rejected as `RESOLUTION_EXCEEDS_BATCH` at
+                     * every lower ceiling and takes the rest of the batch with it. The
+                     * R0-R2 monotonic sweep is what catches that, not the headline run.
+                     */
+                    level = Math.min(SHAPE_LEVEL, input.reached);
+                    attrs["shapeResolution"] = level;
+                }
+                if (model.undecided.length > 0)
+                    attrs["undecidedNullability"] = model.undecided;
+            }
             nodes.push({
                 id,
-                type: "CLASS",
+                type: kind,
                 name: decl.name,
                 file: unit.file,
                 range: { startLine: decl.startLine, endLine: decl.endLine },
                 language: LANGUAGE,
                 producedBy: input.producedBy,
-                resolution: 0,
-                attrs: { declarationForm: decl.kind },
+                resolution: level,
+                attrs,
             });
         }
+        /**
+         * A shape `jpa.ts` withheld because it could not prove the column set
+         * complete. Disclosed rather than silently absent (rule 7): the `MODEL`
+         * node stands and carries no `fields`, and without this a consumer cannot
+         * tell "this entity has no columns" from "this entity's columns were not
+         * enumerable".
+         */
+        for (const refusal of input.reach?.refusals ?? []) {
+            if (refusal.file !== unit.file)
+                continue;
+            refuse(moduleId, "USES_TYPE", refusal.className, unit.file, 1, refusal.reason);
+        }
         for (const fn of unit.funcs) {
             const path = [...fn.owners, fn.name];
             const key = typeKey(unit.identityPackage, path);
@@ -176,15 +361,17 @@ export function extract(input) {
                     "an overload, or two same-named top-level declarations, apart. Refused rather than merged onto one arbitrary winner.");
                 continue;
             }
-            const id = fn.isTest
-                ? nodeId(scope, "TEST_CASE", symbolQsp(unit.identityPackage, path), LANGUAGE)
-                : nodeId(scope, "FUNCTION", symbolQsp(unit.identityPackage, path), LANGUAGE);
+            // `COMPONENT` is earned by Compose's own declaration (`composableOf` in
+            // parse.ts), never by a name. A `@Composable` that returns a value is a
+            // state factory and stays a FUNCTION.
+            const funcType = fn.isTest ? "TEST_CASE" : fn.isComposable ? "COMPONENT" : "FUNCTION";
+            const id = nodeId(scope, funcType, symbolQsp(unit.identityPackage, path), LANGUAGE);
             if (funcsByKey.has(key))
                 continue;
             funcsByKey.set(key, { id, identityPackage: unit.identityPackage, owners: fn.owners, name: fn.name, file: unit.file });
             nodes.push({
                 id,
-                type: fn.isTest ? "TEST_CASE" : "FUNCTION",
+                type: funcType,
                 name: fn.name,
                 file: unit.file,
                 range: { startLine: fn.startLine, endLine: fn.endLine },
@@ -218,16 +405,35 @@ export function extract(input) {
             const node = nodes[index];
             if (node === undefined)
                 continue;
-            nodes[index] = {
-                ...node,
-                attrs: {
-                    ...node.attrs,
-                    // `type` is the element type, `list` a boolean — the contract Lane E
-                    // stated and every adapter follows. Kotlin infers, so an absent
-                    // type means "not written," never "no type."
-                    fields: fields.map((f) => ({ name: f.name, type: f.type ?? null, list: false })),
-                },
-            };
+            /**
+             * **Two producers write `attrs.fields`, and they are not the same fact.**
+             * The language pass below reads every declared property and says what
+             * its type is *written* as — R0/R1 evidence. `jpa.ts` reads the mapped
+             * column set and says whether each column is *nullable* — R3 evidence,
+             * and the assertion golden 06 exists to make. A plain overwrite here
+             * silently destroyed the second: the shape was minted, then replaced by
+             * a list that had lost `nullable` before anything downstream saw it.
+             *
+             * So they are merged, on the ORM list's spine. The column set is the
+             * mapping's — it drops `@Transient`, adds every `@MappedSuperclass`
+             * column, and omits what `jpa.ts` could not decide — and the written
+             * type is carried onto each entry that has one. Neither consumer loses
+             * anything, and the two claims stay distinguishable by their keys.
+             */
+            const written = new Map(fields.map((f) => [f.name, f.type]));
+            // `type` is the element type, `list` a boolean — the contract Lane E
+            // stated and every adapter follows. Kotlin infers, so an absent
+            // type means "not written," never "no type."
+            const asLanguageFields = fields.map((f) => ({ name: f.name, type: f.type ?? null, list: false }));
+            const mapped = node.attrs?.["fields"];
+            const merged = node.type === "MODEL" && Array.isArray(mapped)
+                ? mapped.map((f) => ({
+                    ...f,
+                    type: written.get(f.name) ?? null,
+                    list: false,
+                }))
+                : asLanguageFields;
+            nodes[index] = { ...node, attrs: { ...node.attrs, fields: merged } };
         }
     }
     // Pass 2 — edges.
@@ -294,6 +500,49 @@ export function extract(input) {
             candidate.path[candidate.path.length - 1] === name);
         return samePackageName.length === 1 ? samePackageName[0] : undefined;
     }
+    /**
+     * `DEC-NEXT-dto-shape-evidence-for-api-contracts`'s ruling, applied at the
+     * one place a Kotlin `USES_API` edge states a response type: a Retrofit
+     * endpoint function's own declared return shape (`returnTypeWritten`, read
+     * by `retrofit.ts`'s `returnTypeOf`). Mirrors `adapter-java`'s
+     * `responseShapeEvidence` and `adapter-csharp`'s twin — resolve the written
+     * name through the SAME scope rules every other name in this adapter goes
+     * through, then require real kotlinx.serialization evidence before
+     * claiming R3, never the return type alone.
+     *
+     * Gated on `input.reached >= 3` INSIDE the returned attrs, not by an early
+     * return one level up — 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 `@Serializable`: that is a JPA
+     * 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 a different annotation.
+     *
+     * **Kotlin has no `DTO` node kind at all** (confirmed: this file mints only
+     * `CLASS`/`MODEL`, unlike `adapter-java`/`adapter-csharp`/`adapter-python`).
+     * So this gate rests on the annotation evidence alone — a resolved
+     * declaration, not a `MODEL`, carrying real `@Serializable` — rather than
+     * ALSO requiring the type be independently classified `DTO` by route
+     * evidence the way `adapter-java`/`adapter-csharp` additionally require.
+     * That extra requirement in those two adapters is a narrowing choice on top
+     * of what the ruling itself demands, not a second thing this ruling asks
+     * for; `@Serializable` here is exactly the "genuine serialization-schema
+     * signal" the ruling names, so gating on it alone is not a lowered bar.
+     */
+    function responseShapeEvidence(unit, written) {
+        if (input.reached < 3 || written === undefined)
+            return {};
+        const target = resolveType(unit, written);
+        if (target === undefined || target.isModel)
+            return {};
+        const source = declByKey.get(typeKey(target.identityPackage, target.path));
+        if (source === undefined)
+            return {};
+        if (!hasSerializationEvidence(source.unit, source.decl))
+            return {};
+        return { responseType: target.id, shapeResolution: 3 };
+    }
     function memberOf(owner, name) {
         return funcsByKey.get(typeKey(owner.identityPackage, [...owner.path, name]));
     }
@@ -420,11 +669,33 @@ export function extract(input) {
             const from = funcsByKey.get(typeKey(unit.identityPackage, [...fn.owners, fn.name]));
             if (from === undefined)
                 continue;
+            // `order.totalAmount` where a binding WROTE `order: Order` — golden 07.
+            // The same type resolver that serves CALLS answers this; a receiver whose
+            // type Kotlin inferred states nothing at the binding site and produces
+            // nothing here, which is a disclosed gap rather than a guess.
+            for (const read of jpaFieldReadsIn(fn, (written) => {
+                const target = resolveType(unit, written);
+                return target?.isModel === true ? target.id : undefined;
+            })) {
+                if (read.model === from.id)
+                    continue;
+                push({ from: from.id, to: read.model, type: "READS", attrs: { fields: read.fields } }, 0.95, 
+                // Both halves are written names resolved to a declaration — R2, the
+                // rung every other edge here rests on. The SHAPE lives on the MODEL
+                // node; the edge claims no more than it saw.
+                2);
+            }
             for (const ref of fn.refs) {
                 if (ref.kind === "type") {
                     const target = resolveType(unit, ref.name);
-                    if (target !== undefined)
+                    if (target !== undefined) {
                         push({ from: from.id, to: target.id, type: "USES_TYPE" }, 0.85, 1);
+                        continue;
+                    }
+                    // A type reference that left the repository. When an import the
+                    // developer wrote settles which package and which symbol, it mints a
+                    // `CLASS` standing for that type in the dependency.
+                    externalEdge(from.id, unit, ref.name, [], "USES_TYPE");
                     continue;
                 }
                 if (!ref.hasReceiver) {
@@ -446,6 +717,21 @@ export function extract(input) {
                             push({ from: from.id, to: asType.id, type: "USES_TYPE" }, 0.85, 1);
                             continue;
                         }
+                        // A bare name bound by an import: `import kotlin.test.assertEquals`
+                        // then `assertEquals(a, b)`, or an imported extension function.
+                        // The language guarantees the binding, so following it is
+                        // resolution, not inference — Python's `from x import y`, which was
+                        // the larger half there too.
+                        //
+                        // Kotlin has no `new`, so an imported CLASS called bare is a
+                        // constructor call and is a class used as a VALUE (DEC-068). The
+                        // in-repo branch above already reads it as `USES_TYPE`; the same
+                        // distinction is unavailable here, because nothing read the
+                        // dependency to know whether the name is a type or a function. The
+                        // edge follows what was written — a call — and the node follows the
+                        // edge.
+                        if (externalEdge(from.id, unit, ref.name, [], "CALLS"))
+                            continue;
                         refuse(from.id, "CALLS", ref.name, unit.file, ref.line, "No declaration for this name in the analysed set.");
                         continue;
                     }
@@ -465,6 +751,13 @@ export function extract(input) {
                         push({ from: from.id, to: staticMember.id, type: "CALLS" }, 0.9, 1);
                         continue;
                     }
+                    // `Json.encodeToString(x)` under `import kotlinx.serialization.json.Json`
+                    // — the receiver IS the imported symbol, so the import settles it
+                    // without any type being written. A local of the same spelling would
+                    // have won above, exactly as it does in the in-repo branch.
+                    if (ref.receiver !== undefined && externalEdge(from.id, unit, ref.receiver, [ref.name], "CALLS")) {
+                        continue;
+                    }
                     refuse(from.id, "CALLS", ref.name, unit.file, ref.line, ref.receiver === undefined
                         ? "The receiver is an expression, so it has no written type at this reference. " +
                             "Resolving it needs a type checker (R3)."
@@ -475,6 +768,16 @@ export function extract(input) {
                 const owner = resolveType(unit, ref.receiverType);
                 const target = owner === undefined ? undefined : memberOf(owner, ref.name);
                 if (target === undefined) {
+                    // `val client: HttpClient` under `import io.ktor.client.HttpClient`,
+                    // then `client.get(url)`. The type is written at the reference and
+                    // the import says which package it lives in.
+                    //
+                    // Only when the owner did not resolve. An owner that IS ours and
+                    // declares no such member is an analysis gap — an inherited member or
+                    // an extension function — and calling it a dependency would be wrong.
+                    if (owner === undefined && externalEdge(from.id, unit, ref.receiverType, [ref.name], "CALLS")) {
+                        continue;
+                    }
                     refuse(from.id, "CALLS", ref.name, unit.file, ref.line, owner === undefined
                         ? `No declaration for receiver type "${ref.receiverType}" in the analysed set.`
                         : `"${ref.name}" is not declared on ${owner.path.join(".")} in the analysed set. It may ` +
@@ -491,9 +794,19 @@ export function extract(input) {
         }
     }
     // TESTS — a test case covers what it calls.
+    //
+    // **Never into a dependency.** `TESTS` asserts coverage, and this run read
+    // nothing of an external symbol's body: a test that calls
+    // `kotlin.test.assertEquals` does not cover `assertEquals`. Python and PHP
+    // made the same call at the site that mints the edge; here the edge is
+    // mirrored by a later pass, so the exclusion has to live in the pass.
+    // `DEC-NEXT-external-edge-is-calls-not-tests`.
+    const externalNodeIds = new Set(nodes.filter((n) => n.external !== undefined).map((n) => n.id));
     for (const edge of [...edges]) {
         if (edge.type !== "CALLS")
             continue;
+        if (externalNodeIds.has(edge.to))
+            continue;
         const source = nodes.find((n) => n.id === edge.from);
         if (source?.type !== "TEST_CASE")
             continue;
@@ -558,24 +871,30 @@ export function extract(input) {
             push({ from: routeId, to: endpointId, type: "SERVES_API" }, 0.9, 2);
             // --- Which function actually serves it (golden pattern 19) -----------
             //
-            // `SERVES_API` stops at `API_ROUTE`. Ktor never names its handler —
-            // `get("/orders/{id}") { Routes.getOrder(id) }` puts the body inline —
-            // so the serving function is one hop in, called from the lambda. The
-            // targets those calls ALREADY resolved to are read back by line span, so
-            // the route pass and the call pass cannot disagree about what
-            // `Routes.getOrder` means.
-            //
-            // Exactly one in-repository call is the handler. Zero means the lambda
-            // serves the request itself and no declared function does; more than one
-            // means which is the handler and which a helper is not written down
-            // anywhere, and a wrong handler edge is worse than none — root-cause
-            // traversal would walk it. Both are disclosed, never guessed.
-            //
-            // Emitted at R1, NOT at the route's own R2: the registration's position
-            // is R2 provenance, but the hop rests on this adapter's call resolution,
-            // which is R1 (a written type annotation against the declaration table,
-            // no LSP). An edge's resolution is the weakest evidence under it.
-            if (route.handlerBody !== undefined) {
+            // Spring has no lambda-dispatch ambiguity to resolve: the annotated method IS the
+            // handler unconditionally, already identified by owner chain + name in `spring.ts`.
+            // Resolved through the same `funcsByKey` table Pass 1 built for every FUNCTION node —
+            // a lookup, not a second resolution pass — mirroring `adapter-java/src/spring.ts`'s
+            // `handlerFqn` -> `byMember` join. Emitted at R2, the route's own level: unlike Ktor's
+            // hop (which rests on this adapter's R1 call resolution), nothing here needs more than
+            // the cross-file reference resolution the route registration itself already rests on.
+            if (route.handler !== undefined && unit.identityPackage !== undefined) {
+                const key = typeKey(unit.identityPackage, [...route.handler.owners, route.handler.name]);
+                const handlerFunc = funcsByKey.get(key);
+                if (handlerFunc !== undefined) {
+                    push({ from: routeId, to: handlerFunc.id, type: "CALLS" }, 0.9, 2);
+                }
+                else {
+                    // Shouldn't normally happen — the handler is this same file's already-parsed AST —
+                    // but a name collision Pass 1 refused (two same-named declarations sharing an
+                    // identity key), or another gap, leaves no entry to join to. Disclosed rather than
+                    // silently skipped.
+                    refuse(routeId, "CALLS", [...route.handler.owners, route.handler.name].join("."), unit.file, route.line, "The annotated handler method does not resolve to a declared function in the analysed " +
+                        "set — most likely a name collision this file's own declarations were refused over in " +
+                        "an earlier pass. The route is real; the code serving it is not established.");
+                }
+            }
+            else if (route.handlerBody !== undefined) {
                 const inside = [];
                 for (let ln = route.handlerBody.startLine; ln <= route.handlerBody.endLine; ln += 1) {
                     for (const to of callTargetsAt.get(`${unit.file}:${ln}`) ?? []) {
@@ -598,6 +917,16 @@ export function extract(input) {
                             "as if it had been read from source.");
                 }
             }
+            else if (route.framework === "spring") {
+                // Defensive fallback only — `readSpringRoutes` withholds `handler` when the annotated
+                // method's own name could not be read back, or (unreachably in practice, since a route
+                // only exists once its file's identity resolved) `identityPackage` is absent. Distinct
+                // wording from Ktor's "no handler lambda" case below: a Spring route was never carrying
+                // a lambda to begin with, so that message would misstate why this one is unresolved.
+                refuse(routeId, "CALLS", `${route.method} ${route.template}`, unit.file, route.line, "The annotated handler method's own name could not be read back from this file's parse, " +
+                    "so nothing here identifies the function that serves it. The route is real; the code " +
+                    "serving it is not established.");
+            }
             else {
                 refuse(routeId, "CALLS", `${route.method} ${route.template}`, unit.file, route.line, "The route registration carries no handler lambda, so nothing here names the function " +
                     "that serves it. The route is real; the code serving it is not established.");
@@ -618,13 +947,56 @@ 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 }),
         };
+    /**
+     * DEC-164: caller node id -> the base this reader traced for it. First
+     * writer wins, so a function making two calls is described by the first one
+     * read. Patched onto the node after the walk.
+     */
+    const functionClientBase = new Map();
+    /**
+     * The innermost function containing `line`, resolved to its node id — the
+     * thing a reader would blame, and where DEC-164's `attrs.clientBase`
+     * belongs. Lifted out of the call loop because a REFUSAL needs it too: a
+     * refusal's own ledger row attributes to the MODULE (DEC-124), which is
+     * deliberate and unchanged, but 08b's `attrs.clientBase` has to land on the
+     * caller the golden binds.
+     */
+    const callerAt = (unit, line, moduleId) => {
+        const enclosing = unit.funcs
+            .filter((fn) => fn.startLine <= line && line <= fn.endLine)
+            .sort((a, b) => b.startLine - a.startLine)[0];
+        if (enclosing === undefined || unit.identityPackage === undefined)
+            return moduleId;
+        return funcsByKey.get(typeKey(unit.identityPackage, [...enclosing.owners, enclosing.name]))?.id ?? moduleId;
+    };
     for (const unit of input.files) {
         const moduleId = moduleIdOf.get(unit.file);
         if (moduleId === undefined)
             continue;
         for (const refusal of unit.clientRefusals) {
             refuse(moduleId, "USES_API", refusal.rawTarget, unit.file, refusal.line, refusal.reason, clientAttrsOf(refusal));
+            // 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) {
+                const caller = callerAt(unit, refusal.line, moduleId);
+                if (!functionClientBase.has(caller))
+                    functionClientBase.set(caller, refusal.clientBase);
+            }
+        }
+        // Collected ABOVE the R2 gate on purpose: the golden asserts
+        // `attrs.clientBase` at R2 and the field is a reading of the source, not
+        // of a rung. `adapter-python` shipped exactly this collection below its
+        // own resolution guard and it was green at R3 and absent at R2, caught
+        // only by the monotonic sweep.
+        for (const call of unit.clientCalls) {
+            if (call.clientBase === undefined)
+                continue;
+            const caller = callerAt(unit, call.line, moduleId);
+            if (!functionClientBase.has(caller))
+                functionClientBase.set(caller, call.clientBase);
         }
         if (input.reached < 2)
             continue;
@@ -633,15 +1005,10 @@ export function extract(input) {
             // would blame). Outside any function (a file-scope property
             // initialiser) attributes to the MODULE, the file-scoped carrier
             // (DEC-124).
-            const enclosing = unit.funcs
-                .filter((fn) => fn.startLine <= call.line && call.line <= fn.endLine)
-                .sort((a, b) => b.startLine - a.startLine)[0];
             // A file with no derivable identity package has no function ids to
             // point at (DEC-173); the MODULE still does (DEC-124), so the edge
-            // degrades to the file rather than dropping.
-            const from = enclosing === undefined || unit.identityPackage === undefined
-                ? moduleId
-                : funcsByKey.get(typeKey(unit.identityPackage, [...enclosing.owners, enclosing.name]))?.id ?? moduleId;
+            // degrades to the file rather than dropping — `callerAt`'s own rule.
+            const from = callerAt(unit, call.line, moduleId);
             const template = normaliseEndpointPath(call.path);
             const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(call.method, call.path), null);
             if (!endpointNodes.has(endpointId)) {
@@ -697,12 +1064,74 @@ export function extract(input) {
                     attrs: { method: endpoint.method, pathTemplate: template },
                 });
             }
-            push({ from, to: endpointId, type: "USES_API", attrs: { client: "retrofit", rawPath: endpoint.written } }, 0.9, 2);
+            push({
+                from,
+                to: endpointId,
+                type: "USES_API",
+                attrs: {
+                    client: "retrofit",
+                    rawPath: endpoint.written,
+                    ...responseShapeEvidence(unit, endpoint.returnTypeWritten),
+                },
+            }, 0.9, 2);
         }
     }
     nodes.push(...routeNodes.values(), ...endpointNodes.values());
+    // DEC-164's client base, patched onto the caller. The field's ABSENCE is
+    // the fourth state: a function whose receiver's construction 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 };
 }
+/**
+ * The filesystem-level fallback for a throw mid-extraction — `FILE`-per-file
+ * via the shared `@descryy/adapter-common#fileNode` helper, plus exactly one
+ * disclosure row, mirroring `adapter-typescript`'s `degradedGraph`.
+ *
+ * `identityPackage` is already computed per file by `adapter.ts`'s
+ * `prepare()` by the time `extract()` could throw, so a MODULE-based fallback
+ * built from it was a real option here (unlike TypeScript, where identity
+ * depends on the same resolution machinery that just failed). Declined for
+ * two reasons: (1) it only covers "anchored" files — Kotlin deliberately
+ * refuses identity for the rest (DEC-173), so a MODULE path would still need
+ * a second fallback for the unanchored subset; (2) `identityPackage`'s
+ * derivation includes the KMP source-set fallback (`anchor.sourceSet === ""`,
+ * see `adapter.ts`'s `prepare()`) that itself needed a dedicated fix for
+ * identity collisions on ktor — reusing it inside the degraded path
+ * reintroduces exactly the collision risk that fix exists to prevent, for
+ * uncertain benefit over a plain FILE node, which still merges cleanly with
+ * git-history's FILE nodes for the same path. `FILE`-per-file is simpler,
+ * safer, and uniform with the mechanism's established shape.
+ */
+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)} Kotlin 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 };
+}
 /**
  * `INHERITS` or `IMPLEMENTS`, decided against the declaration table — the
  * parenthesised invocation form is checked only as confirmation. An invoked