@descryy/adapter-kotlin 0.2.0 → 0.3.1

package/dist/extract.d.ts

@@ -3,35 +3,24 @@
  *
  * ## The identity rule, and why it refuses
  *
- * Kotlin shares `@descryy/adapter-jvm`'s anchor with Java: a symbol's identity is
- * `module/sourceSet/package`, derived by subtracting the package path from the
- * file's directory. Measured before this was written — okhttp 570 of 576 files
- * derive, ktor 2,146 of 2,324.
+ * Kotlin shares `@descryy/adapter-jvm`'s anchor with Java: identity is `module/sourceSet/package`,
+ * derived by subtracting the package path from the file's directory (measured: okhttp 570/576
+ * files derive, ktor 2,146/2,324).
  *
- * **When the subtraction fails, the node is refused.** Java falls back to the
- * bare package name; Kotlin must not, because Kotlin Multiplatform declares one
- * qualified name in several source sets **by design** — `expect`/`actual`. A
- * bare-package fallback collapses those onto one id. Measured on ktor: 4 FQNs,
- * `io.ktor.utils.io.charsets.Charsets` among them, declared across seven
- * platform files.
+ * **When the subtraction fails, the node is refused** rather than falling back to the bare
+ * package name as Java does — Kotlin Multiplatform declares one qualified name across several
+ * source sets *by design* (`expect`/`actual`), and a bare-package fallback would collapse those
+ * onto one id (measured on ktor: 4 FQNs, including `io.ktor.utils.io.charsets.Charsets`, across
+ * seven platform files). `attrs` was rejected as the disclosure channel instead: nothing above
+ * the IR reads it, so a refusal beats a merged node with an unseen note (DEC-173).
  *
- * Disclosing the collapse on `attrs` instead was considered and rejected:
- * nothing above the IR reads `attrs`, so scoring, governance and blast radius
- * would act on a merged node while the note sat somewhere they cannot see.
- * A refusal is visible to the layers that act on it; that is the whole
- * difference (DEC-173).
+ * ## No cross-language edges — a measurement, not an omission
  *
- * ## No cross-language edges, and that is a measurement
- *
- * The build plan has this adapter mint Java-shaped target ids for references
- * into `.java` files. **It is not implemented, because the corpus chosen to
- * measure it cannot witness it.** okhttp's 68 `.java` files are 56 samples with
- * `kt/` twins, 11 `module-info.java` declaring no types, and 3 `*JavaTest.java`
- * exercising the Kotlin API. The traffic runs Java→Kotlin. ktor is 2,324 `.kt`
- * against 1 `.java`.
- *
- * A rule with zero witnesses is an untaken branch, not a weak rule — so it is
- * declared absent rather than written blind.
+ * The build plan calls for Java-shaped target ids for references into `.java` files. Not
+ * implemented: the corpus can't witness it. okhttp's 68 `.java` files are 56 samples with `kt/`
+ * twins, 11 `module-info.java` (no types), 3 `*JavaTest.java` exercising the Kotlin API — traffic
+ * runs Java→Kotlin; ktor is 2,324 `.kt` against 1 `.java`. A rule with zero witnesses is declared
+ * absent rather than written blind.
  */
 import { type IRBatch, type ResolutionLevel } from "@descryy/ir";
 import type { KotlinFile } from "./parse.ts";
@@ -43,12 +32,9 @@ export interface ExtractInput {
         readonly workspace?: string | undefined;
     };
     /**
-     * The resolution level `prepare()` actually reached, gating `push()` below.
-     * Without it every edge always carries its full resolution regardless of
-     * `maxResolution`, and a batch claiming R0 would still emit R1 edges — which
-     * the conformance harness's boundary check reports as
-     * `RESOLUTION_EXCEEDS_BATCH`: an edge whose own resolution exceeds what the
-     * batch that carries it claims.
+     * The resolution level `prepare()` actually reached, gating `push()` below —
+     * without it a batch claiming R0 could still emit R1 edges, which the
+     * conformance harness flags as `RESOLUTION_EXCEEDS_BATCH`.
      */
     readonly reached: ResolutionLevel;
 }

package/dist/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAKL,KAAK,OAAO,EAGZ,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AAqB9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IACnF;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AASD,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,CAAC,CAqsB5F"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAKL,KAAK,OAAO,EAGZ,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AAqB9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IACnF;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AASD,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,CAAC,CAipB5F"}

package/dist/extract.js

@@ -3,35 +3,24 @@
  *
  * ## The identity rule, and why it refuses
  *
- * Kotlin shares `@descryy/adapter-jvm`'s anchor with Java: a symbol's identity is
- * `module/sourceSet/package`, derived by subtracting the package path from the
- * file's directory. Measured before this was written — okhttp 570 of 576 files
- * derive, ktor 2,146 of 2,324.
+ * Kotlin shares `@descryy/adapter-jvm`'s anchor with Java: identity is `module/sourceSet/package`,
+ * derived by subtracting the package path from the file's directory (measured: okhttp 570/576
+ * files derive, ktor 2,146/2,324).
  *
- * **When the subtraction fails, the node is refused.** Java falls back to the
- * bare package name; Kotlin must not, because Kotlin Multiplatform declares one
- * qualified name in several source sets **by design** — `expect`/`actual`. A
- * bare-package fallback collapses those onto one id. Measured on ktor: 4 FQNs,
- * `io.ktor.utils.io.charsets.Charsets` among them, declared across seven
- * platform files.
+ * **When the subtraction fails, the node is refused** rather than falling back to the bare
+ * package name as Java does — Kotlin Multiplatform declares one qualified name across several
+ * source sets *by design* (`expect`/`actual`), and a bare-package fallback would collapse those
+ * onto one id (measured on ktor: 4 FQNs, including `io.ktor.utils.io.charsets.Charsets`, across
+ * seven platform files). `attrs` was rejected as the disclosure channel instead: nothing above
+ * the IR reads it, so a refusal beats a merged node with an unseen note (DEC-173).
  *
- * Disclosing the collapse on `attrs` instead was considered and rejected:
- * nothing above the IR reads `attrs`, so scoring, governance and blast radius
- * would act on a merged node while the note sat somewhere they cannot see.
- * A refusal is visible to the layers that act on it; that is the whole
- * difference (DEC-173).
+ * ## No cross-language edges — a measurement, not an omission
  *
- * ## No cross-language edges, and that is a measurement
- *
- * The build plan has this adapter mint Java-shaped target ids for references
- * into `.java` files. **It is not implemented, because the corpus chosen to
- * measure it cannot witness it.** okhttp's 68 `.java` files are 56 samples with
- * `kt/` twins, 11 `module-info.java` declaring no types, and 3 `*JavaTest.java`
- * exercising the Kotlin API. The traffic runs Java→Kotlin. ktor is 2,324 `.kt`
- * against 1 `.java`.
- *
- * A rule with zero witnesses is an untaken branch, not a weak rule — so it is
- * declared absent rather than written blind.
+ * The build plan calls for Java-shaped target ids for references into `.java` files. Not
+ * implemented: the corpus can't witness it. okhttp's 68 `.java` files are 56 samples with `kt/`
+ * twins, 11 `module-info.java` (no types), 3 `*JavaTest.java` exercising the Kotlin API — traffic
+ * 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";
 const LANGUAGE = "kotlin";
@@ -48,9 +37,8 @@ export function extract(input) {
     const funcsByKey = new Map();
     const moduleIdOf = new Map();
     const seenEdges = new Set();
-    // `IREdge` carries no `language` — an edge's language is the language of the
-    // nodes it joins, and duplicating it here would be a second place for it to
-    // be wrong.
+    // `IREdge` carries no `language`: an edge's language is its nodes' language,
+    // and duplicating it here is a second place for it to be wrong.
     const push = (edge, confidence, resolution) => {
         if (resolution > input.reached)
             return false;
@@ -73,27 +61,15 @@ export function extract(input) {
             ...(attrs === undefined ? {} : { attrs }),
         });
     };
-    // -------------------------------------------------------------------------
-    // Pass 0 — count declarations sharing an identity key: same identityPackage,
-    // same owner chain, same name. Two shapes produce this, and both share one
-    // cause: this adapter's identity has no parameter-type or file component to
-    // break the tie, by design (DEC-004 — a file component churns on rename).
-    //
-    //  - Two files in one package each declaring a top-level `fun main()`. The
-    //    JVM synthesises a distinct `FileNameKt` class per file; nothing here
-    //    does. okhttp's `samples/` alone has 20+ such files.
-    //  - Overloads: two methods on the same class sharing a name over different
-    //    parameters, which this adapter cannot distinguish without a type
-    //    checker. Measured on ktor: `AuthenticationConfig.provider(name)` and
-    //    `.provider(name, configure, body)` collide; the second's own body is
-    //    the one that calls `requireProviderNotRegistered`, and it was silently
-    //    unreachable through the merged node.
-    //
-    // Pass 1 used to keep the first declaration under a key and silently drop
-    // the rest with no disclosure — a rule-7 violation — which cross-attributes
-    // every edge that belonged to a dropped declaration onto whichever one
-    // happened to parse first, rather than losing them cleanly.
-    // -------------------------------------------------------------------------
+    // Pass 0 — count declarations sharing an identity key (same identityPackage, owner chain, name):
+    // this adapter's identity has no parameter-type or file component to break a tie, by design
+    // (DEC-004 — a file component churns on rename). Two shapes collide: (1) two files in one package
+    // each declaring top-level `fun main()` — the JVM synthesises a distinct `FileNameKt` class per
+    // file, nothing here does (okhttp's `samples/` has 20+); (2) overloads, indistinguishable without
+    // a type checker (ktor's `AuthenticationConfig.provider(name)` vs `.provider(name, configure,
+    // body)` — the second's body calls `requireProviderNotRegistered`, silently unreachable when
+    // merged). Previously the first declaration under a key won silently, cross-attributing dropped
+    // declarations' edges onto it (rule-7 violation) — this pass refuses the collision instead.
     const declNameCount = new Map();
     for (const unit of input.files) {
         if (unit.identityPackage === undefined)
@@ -107,10 +83,8 @@ export function extract(input) {
             declNameCount.set(k, (declNameCount.get(k) ?? 0) + 1);
         }
     }
-    // -------------------------------------------------------------------------
-    // Pass 1 — declarations. A file with no derivable identity package mints
-    // nothing at all, and says so once for the file rather than once per symbol.
-    // -------------------------------------------------------------------------
+    // Pass 1 — declarations. A file with no derivable identity mints nothing,
+    // disclosed once per file rather than once per symbol.
     for (const unit of input.files) {
         if (unit.identityPackage === undefined) {
             refuse("", "IMPORTS", unit.file, unit.file, 1, "This file does not sit where its package declaration says it should, so its module and " +
@@ -136,9 +110,8 @@ export function extract(input) {
                 ...(unit.hasError ? { parsedWithErrors: true } : {}),
             },
         });
-        // Counted in parse.ts, disclosed here. Silence is the worst direction under
-        // rule 7, and a declaration this adapter deliberately declined to place is
-        // exactly the thing a reader would otherwise assume absent from the source.
+        // Counted in parse.ts, disclosed here — a declined declaration is exactly
+        // what a reader would otherwise assume simply absent (rule 7).
         if (unit.unparseableDeclarations > 0) {
             refuse(moduleId, "IMPORTS", fileStem(unit.file), unit.file, 1, `${unit.unparseableDeclarations} declaration(s) in this file could not be placed. The pinned ` +
                 "grammar does not parse Kotlin's `fun interface`, so the body arrives as an orphaned lambda " +
@@ -231,34 +204,31 @@ export function extract(input) {
                 ...node,
                 attrs: {
                     ...node.attrs,
-                    // `type` is the element type and `list` a boolean, per the contract
-                    // Lane E stated and every other adapter follows. Kotlin infers, so an
-                    // absent type is "not written", never "no 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."
                     fields: fields.map((f) => ({ name: f.name, type: f.type ?? null, list: false })),
                 },
             };
         }
     }
-    // -------------------------------------------------------------------------
     // Pass 2 — edges.
-    // -------------------------------------------------------------------------
     /** Types a file can name: its own package, plus everything it imports. */
     function resolveType(unit, written) {
         if (unit.identityPackage === undefined)
             return undefined;
-        // A written type may be a dotted path to a NESTED type —
-        // `DiskLruCache.Snapshot`. The whole path is tried first, because resolving
-        // it to its outermost segment is how `snapshot.getSource()` came to be
-        // refused against `DiskLruCache`, where the member genuinely is not.
+        // A written type may be a dotted nested path (`DiskLruCache.Snapshot`);
+        // the whole path is tried first — resolving only the outermost segment is
+        // how `snapshot.getSource()` was wrongly refused against `DiskLruCache`.
         const segments = written.split(".");
         const name = segments[segments.length - 1];
         if (segments.length > 1) {
             const nested = typesByKey.get(typeKey(unit.identityPackage, segments));
             if (nested !== undefined)
                 return nested;
-            // The enclosing type may be imported from another package while the path
-            // is written relative to it, so the tail is matched against declared
-            // paths rather than assumed to be package-local.
+            // The enclosing type may be imported from elsewhere while the path is
+            // written relative to it, so the tail is matched against declared
+            // paths, not assumed package-local.
             const byPath = [...typesByKey.values()].filter((candidate) => candidate.path.join(".").endsWith(segments.join(".")));
             if (byPath.length === 1)
                 return byPath[0];
@@ -275,10 +245,9 @@ export function extract(input) {
             if (candidate.path[candidate.path.length - 1] === name)
                 return candidate;
         }
-        // An explicit import names the symbol; a wildcard names its package. Both
-        // are matched against the DECLARATION table rather than assumed to exist —
-        // an import of something this adapter never read resolves to nothing and is
-        // refused, not invented.
+        // Explicit import names the symbol; wildcard names its package. Both
+        // matched against the DECLARATION table — an import of something never
+        // read resolves to nothing and is refused, not invented.
         const matches = [];
         for (const imported of unit.imports) {
             const wanted = imported.isWildcard ? name : imported.path.split(".").pop();
@@ -295,15 +264,12 @@ export function extract(input) {
             return matches[0];
         if (matches.length > 1)
             return undefined;
-        // Same declared PACKAGE name, but a different source set — `src/test/kotlin`
-        // naming a class in `src/main/kotlin` with no import, which Kotlin compiles
-        // without one because a test source set's classpath includes main. Tried
-        // last, and only when there is exactly one candidate: two declarations
-        // sharing a package name across different SOURCE SETS OR MODULES is the
-        // exact collision `adapter-jvm`'s identity design exists to catch (airbyte's
-        // `RedisDataFactory`, declared under both `src/test/java` and
-        // `src/test-integration/java`) — so ambiguity here still refuses rather than
-        // guesses, the same rule Java's own `pick` applies.
+        // Same declared package, different source set (`src/test/kotlin` naming a class in
+        // `src/main/kotlin` with no import — legal, since a test source set's classpath includes main).
+        // Tried last, only with exactly one candidate: cross-source-set/module name collisions are
+        // exactly what `adapter-jvm`'s identity design exists to catch (airbyte's `RedisDataFactory`
+        // under both `src/test/java` and `src/test-integration/java`), so ambiguity still refuses,
+        // same as Java's own `pick`.
         if (unit.packageName === "")
             return undefined;
         const samePackageName = [...typesByKey.values()].filter((candidate) => packageOf(candidate.identityPackage) === unit.packageName &&
@@ -314,15 +280,12 @@ export function extract(input) {
         return funcsByKey.get(typeKey(owner.identityPackage, [...owner.path, name]));
     }
     /**
-     * A top-level function a bare unqualified call may name: one in the file's
-     * own package, or one reached through an explicit or wildcard import.
-     *
-     * The same gap `resolveType` closes for types, but for functions: an
-     * unqualified call to an imported top-level function (`validateOrder`,
-     * imported from a different package) was refused as "no declaration" because
-     * this lookup only ever checked the caller's OWN package. Kotlin needs no
-     * import for a same-package call, which is what made the gap invisible until
-     * a construct genuinely needing a cross-package import existed to hit it.
+     * A top-level function a bare unqualified call may name — own package, or
+     * reached through an import. Mirrors `resolveType`'s gap for functions: a
+     * call to an imported top-level function was wrongly refused because this
+     * lookup only checked the caller's own package (invisible until a
+     * cross-package call actually needed it, since same-package calls need no
+     * import).
      */
     function resolveFreeFunction(unit, name) {
         if (unit.identityPackage === undefined)
@@ -354,9 +317,8 @@ export function extract(input) {
             return matches[0];
         if (matches.length > 1)
             return undefined;
-        // Same declared package, different source set — see `resolveType`'s
-        // identical fallback for the reasoning; a bare call to a same-package
-        // top-level function needs it exactly as a bare type reference does.
+        // Same declared package, different source set — same reasoning as
+        // `resolveType`'s identical fallback.
         if (unit.packageName === "")
             return undefined;
         const samePackageName = [...funcsByKey.values()].filter((fn) => fn.owners.length === 0 && fn.name === name && packageOf(fn.identityPackage) === unit.packageName);
@@ -369,17 +331,12 @@ export function extract(input) {
         // IMPORTS — file-granular, to the module of the imported symbol.
         if (moduleId !== undefined) {
             for (const imported of unit.imports) {
-                // A STAR IMPORT IS REFUSED. `import io.ktor.util.*` names a package,
-                // and the IR has no PACKAGE node — so the only available edge is
-                // MODULE->MODULE, once per file in that package. Measured on ktor: 144
-                // of 183 sampled such edges point at a file whose declarations the
-                // importing file never names anywhere in its text, and ktor writes
-                // 9,222 star imports against 4,877 explicit ones.
-                //
-                // That made IMPORTS 89,080 of 98,551 edges at roughly 79% wrong — 90%
-                // of the graph, and the single reason both precision gates failed.
-                // Rule 2 decides it: a wrong edge corrupts every layer above, a missing
-                // one is a disclosed gap.
+                // Star imports are refused: `import io.ktor.util.*` names a package, but the IR has no
+                // PACKAGE node, so the only edge available is MODULE->MODULE once per file in that package.
+                // Measured on ktor: 144 of 183 sampled such edges point at a file the importer never
+                // actually names (9,222 star imports vs 4,877 explicit) — this made IMPORTS 89,080/98,551
+                // edges (~79% wrong, ~90% of the graph) and was the reason both precision gates failed.
+                // Rule 2: a wrong edge corrupts every layer above; a missing one is a disclosed gap.
                 if (imported.isWildcard) {
                     refuse(moduleId, "IMPORTS", `${imported.path}.*`, unit.file, imported.line, "A star import names a package, and the IR has no PACKAGE node. The only edge " +
                         "available is one per file in that package, and most of those files declare nothing " +
@@ -387,11 +344,9 @@ export function extract(input) {
                         "rather than emitted; the dependency is real but not expressible at this resolution.");
                     continue;
                 }
-                // An explicit import is matched on its FULL PACKAGE PATH, not on the
-                // last segment. Matching by simple name gave `import okhttp3.Request` an
-                // edge to a nested `data class Request` inside another Gradle module's
-                // ShadowDnsResolver, and made mockwebserver and mockwebserver-deprecated
-                // resolve into each other in both directions.
+                // Matched on the FULL PACKAGE PATH, not the last segment — matching by simple name gave
+                // `import okhttp3.Request` an edge to an unrelated nested `Request` class, and made
+                // mockwebserver/mockwebserver-deprecated resolve into each other both ways.
                 const wanted = imported.path;
                 const targets = new Set();
                 for (const candidate of typesByKey.values()) {
@@ -402,12 +357,10 @@ export function extract(input) {
                     if (target !== undefined && target !== moduleId)
                         targets.add(target);
                 }
-                // A Kotlin import may name a TOP-LEVEL FUNCTION or property, not only a
-                // type — `import io.ktor.server.request.receive` is an extension
-                // function. Matching only against types made 21 of 22 adjudicated wrong
-                // refusals on ktor, and the shape looked like a filename problem from
-                // the outside because the declaring file is named for its subject
-                // (`ApplicationReceiveFunctions.kt`) rather than for the symbol.
+                // An import may name a top-level function, not only a type (`io.ktor.server.request.receive`
+                // is an extension function). Matching only types caused 21 of 22 adjudicated wrong refusals
+                // on ktor — it looked like a filename problem, since the declaring file is named for its
+                // subject (`ApplicationReceiveFunctions.kt`), not the symbol.
                 if (targets.size === 0) {
                     for (const fn of funcsByKey.values()) {
                         if (fn.owners.length > 0)
@@ -466,10 +419,10 @@ export function extract(input) {
                     const free = resolveFreeFunction(unit, ref.name);
                     const target = member ?? free;
                     if (target === undefined) {
-                        // A constructor invocation is syntactically identical to a call —
-                        // Kotlin has no `new` keyword — so a name that resolves to a TYPE
-                        // rather than a function is a class or enum named as a VALUE
-                        // (DEC-068), not a missing declaration.
+                        // Kotlin has no `new` keyword, so a constructor call is
+                        // syntactically identical to an ordinary one — a name resolving
+                        // to a TYPE rather than a function is a class/enum used as a
+                        // VALUE (DEC-068), not a missing declaration.
                         const asType = resolveType(unit, ref.name);
                         if (asType !== undefined) {
                             push({ from: from.id, to: asType.id, type: "USES_TYPE" }, 0.85, 1);
@@ -482,12 +435,10 @@ export function extract(input) {
                     continue;
                 }
                 if (ref.receiverType === undefined) {
-                    // The receiver has no written LOCAL type — but the receiver name
-                    // itself may resolve to a declared type, which is `object`,
-                    // `companion object` and static-style access: `Routes.getOrder(id)`
-                    // has no local variable named `Routes` to look up, because `Routes`
-                    // IS the type. Tried before refusing, not instead of the ordinary
-                    // path — a local variable always wins when one exists.
+                    // No written local type — but the receiver name may itself resolve to a declared type
+                    // (`object`/companion, static-style access): `Routes.getOrder(id)` has no local var
+                    // `Routes`, because `Routes` IS the type. Tried before refusing; a local variable still
+                    // wins when one exists.
                     const asStatic = ref.receiver === undefined ? undefined : resolveType(unit, ref.receiver);
                     const staticMember = asStatic === undefined ? undefined : memberOf(asStatic, ref.name);
                     if (staticMember !== undefined) {
@@ -510,13 +461,10 @@ export function extract(input) {
                             "be inherited, an extension function, or defined in a dependency.");
                     continue;
                 }
-                // R1, NOT R2. The ladder defines R2 as "+ LSP references/definitions"
-                // and there is no LSP here — this edge rests on a WRITTEN type
-                // annotation resolved against the declaration table, which is
-                // module/import resolution plus a piece of source text. Claiming R2 for
-                // it would be claiming a capability the adapter does not have. Raised by
-                // the lane grading this adapter, who could not read this file and asked
-                // what the 2 was backed by; the honest answer was nothing.
+                // R1, not R2: the ladder defines R2 as "+ LSP references/definitions," and there's no LSP
+                // here — this rests on a written type annotation resolved against the declaration table
+                // (module/import resolution + source text). Claiming R2 would claim a capability this
+                // adapter doesn't have.
                 push({ from: from.id, to: target.id, type: "CALLS" }, 0.9, 1);
             }
         }
@@ -530,10 +478,8 @@ export function extract(input) {
             continue;
         push({ from: edge.from, to: edge.to, type: "TESTS" }, edge.confidence, edge.resolution);
     }
-    // ---------------------------------------------------------------------------
     // Routes — Ktor's routing DSL. Last, because every ledger row is attributed
     // to a MODULE the pass above has already minted.
-    // ---------------------------------------------------------------------------
     const routeNodes = new Map();
     const endpointNodes = new Map();
     for (const unit of input.files) {
@@ -591,16 +537,13 @@ export function extract(input) {
             push({ from: routeId, to: endpointId, type: "SERVES_API" }, 0.9, 2);
         }
     }
-    // ---------------------------------------------------------------------------
-    // Client calls — the caller half. Minted through the same `endpointQsp`, so a
-    // call and the route that serves it land on ONE endpoint node rather than two
-    // that never meet.
-    // ---------------------------------------------------------------------------
+    // Client calls — the caller half, minted through the same `endpointQsp` so a
+    // call and the route serving it land on one endpoint node, not two that
+    // never meet.
     /**
-     * DEC-242's `attrs.blockedBy`/`attrs.refusalClass`, plus the diagnostic-only
-     * `argumentKind` — `undefined` when `refusalClass` was never set, so
-     * `refuse` omits `attrs` entirely rather than sending it with an
-     * `undefined` field (unset stays legal and means unclassified).
+     * DEC-242's `attrs.blockedBy`/`attrs.refusalClass`, plus diagnostic-only
+     * `argumentKind`. `undefined` when `refusalClass` was never set, so
+     * `refuse` omits `attrs` entirely rather than an undefined field.
      */
     const clientAttrsOf = (refusal) => refusal.refusalClass === undefined
         ? undefined
@@ -619,17 +562,16 @@ export function extract(input) {
         if (input.reached < 2)
             continue;
         for (const call of unit.clientCalls) {
-            // The caller is the innermost function whose span contains the call, so
-            // the edge starts at the thing a reader would blame. A call outside any
-            // function — a property initialiser at file scope — is attributed to the
-            // MODULE, which is the file-scoped carrier by DEC-124.
+            // Caller = innermost function containing the call (the thing a reader
+            // 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 that does not sit where its package declaration says has no
-            // identity package, so its functions have no ids to point at (DEC-173).
-            // The MODULE still does, and it is the file-scoped carrier by DEC-124 —
-            // so the edge degrades to the file rather than being dropped.
+            // 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;
@@ -651,12 +593,9 @@ export function extract(input) {
             push({ from, to: endpointId, type: "USES_API", attrs: { client: call.client, rawPath: call.rawPath } }, 0.9, 2);
         }
     }
-    // ---------------------------------------------------------------------------
-    // Retrofit — a declarative client interface. Unlike every call above, there is
-    // no call SITE to attribute the edge to: the annotated function's own id IS
-    // the caller, and ordinary CALLS resolution (unchanged) is what connects a
-    // real caller to it, one hop further out. See `retrofit.ts`'s own header.
-    // ---------------------------------------------------------------------------
+    // Retrofit — a declarative client interface. No call site to attribute to:
+    // the annotated function's own id IS the caller; ordinary CALLS resolution
+    // connects a real caller one hop further out. See `retrofit.ts`.
     for (const unit of input.files) {
         const moduleId = moduleIdOf.get(unit.file);
         if (moduleId === undefined)
@@ -671,11 +610,9 @@ export function extract(input) {
                 ? undefined
                 : funcsByKey.get(typeKey(unit.identityPackage, [...endpoint.owners, endpoint.funcName]))?.id;
             if (from === undefined) {
-                // Either the file has no derivable identity, or the declaring
-                // function itself collided with another of the same name and was
-                // refused in Pass 1 — both already disclosed there. Attributing this
-                // edge to the MODULE instead would be a second, misleading claim
-                // about a function this adapter declined to name.
+                // No derivable identity, or the declaring function collided and was
+                // refused in Pass 1 — already disclosed there. Falling back to the
+                // MODULE would be a second, misleading claim about a declined function.
                 continue;
             }
             const template = normaliseEndpointPath(endpoint.path);
@@ -700,22 +637,19 @@ export function extract(input) {
     return { nodes, edges, unresolved };
 }
 /**
- * `INHERITS` or `IMPLEMENTS`, decided against the declaration table.
- *
- * The parenthesised form is Kotlin's own discriminator and it is checked first
- * — but only as a **confirmation** of what the table says. A `class` target that
- * was invoked is unambiguously the superclass; an `interface` target is
- * unambiguously implemented whatever the syntax. Anything else falls to
- * `IMPLEMENTS`, which is the weaker claim of the two.
+ * `INHERITS` or `IMPLEMENTS`, decided against the declaration table — the
+ * parenthesised invocation form is checked only as confirmation. An invoked
+ * `class` target is unambiguously the superclass; an `interface` target is
+ * unambiguously implemented regardless of syntax. Anything else falls to the
+ * weaker `IMPLEMENTS`.
  */
 function classifySupertype(target, written) {
     if (target.kind === "interface")
         return "IMPLEMENTS";
     if (written.invoked)
         return "INHERITS";
-    // A bare class supertype: `interface A : B` where B resolved to a class is
-    // malformed Kotlin, so the likelier reading is that the table is incomplete.
-    // IMPLEMENTS understates rather than inventing an inheritance chain.
+    // `interface A : B` where B resolves to a class is malformed Kotlin —
+    // likelier the table is incomplete. IMPLEMENTS understates rather than invents.
     return target.kind === "class" ? "INHERITS" : "IMPLEMENTS";
 }
 const fileStem = (file) => file.slice(file.lastIndexOf("/") + 1).replace(/\.kt$/, "");