@descryy/adapter-csharp 0.1.0 → 0.3.0

package/dist/extract.js

@@ -1,40 +1,25 @@
 /**
  * C# files to Canonical IR.
  *
- * ## Identity is the project plus the declared namespace
+ * Identity is project + declared namespace, not namespace alone: namespaces
+ * don't follow directories and can span projects, so two `.csproj` files may
+ * both declare `Shop.Orders.OrderService` (DEC-077's collision — the project
+ * is C#'s equivalent of Java's source set).
  *
- * Not the namespace alone. C# namespaces do not follow directories and the same
- * namespace legitimately spans projects, so two `.csproj` files in one
- * repository may both declare `Shop.Orders.OrderService`. That is DEC-077's
- * collision — the Java case where one fully-qualified name existed under two
- * source sets and stopped identifying anything — and the project is C#'s
- * equivalent separator.
+ * DEC-083: `partial class` is the first multi-file declaration here. Parts
+ * merge into one node (ids never carry a file path) — `file` is the
+ * lexicographically first declaring path, every part listed in `attrs.declaredIn`.
  *
- * ## Two decisions land here, both taken before this file was written
+ * DEC-084: `class A : B, IC` doesn't say which entry is the base class, but
+ * the language does — at most one, and it's first. So later entries are
+ * `IMPLEMENTS` unconditionally, and only the first entry per class ever needs
+ * resolving. The `IFoo` naming convention is never read (`System.Exception`
+ * disproves it; golden pattern 12 punishes inferring edges from naming habits).
  *
- * **DEC-083, a declaration that spans files.** `partial class` is the first
- * construct in this project whose declaration is legitimately multi-file. The
- * merge is free — a node id never contains a file path — so the parts collapse
- * to one node with no new machinery. `file` is the lexicographically first
- * declaring path and every part is listed in `attrs.declaredIn`, which is what
- * a precision adjudicator has to search instead of `file`.
- *
- * **DEC-084, the base list.** `class A : B, IC` does not say which entry is the
- * class, but the language does: at most one base class, and it must be first.
- * So entries after the first are `IMPLEMENTS` unconditionally, a struct's and an
- * interface's entries are all `IMPLEMENTS`, and exactly one entry per class ever
- * needs resolving. The `IFoo` prefix is never read — it is a convention,
- * `System.Exception` disproves it in the other direction, and inferring an edge
- * from a naming habit is what golden pattern 12 exists to punish.
- *
- * ## Ambiguity is disclosed, never broken
- *
- * A `using` imports a whole namespace, so a bare name can be found under two of
- * them at once. Real C# resolves that with the full type environment; this
- * adapter has names only, so two candidates produce a ledger entry and no edge.
- * Extension methods are the same answer for the same reason: `x.Foo()` where
- * `Foo` is a static method on an unrelated class, selected by the receiver's
- * type, is not decidable from names.
+ * Ambiguity is disclosed, not guessed: a `using` imports a whole namespace, so
+ * a bare name can match two of them — real C# resolves via the full type
+ * environment, this adapter has names only, so two candidates ledger and mint
+ * no edge. Extension methods are the same call for the same reason.
  */
 import { edgeId, endpointQsp, nodeId, normaliseEndpointPath, symbolQsp, testCaseQsp, } from "@descryy/ir";
 import { efModels, isGenerated } from "./efcore.js";
@@ -46,13 +31,11 @@ export const LANGUAGE = "csharp";
 const CONFIDENCE = { 0: 0.5, 1: 0.7, 2: 0.9, 3: 0.95 };
 const REASONS = {
     outside: 
-    // Same correction as the Java adapter's, for the same reason, on weaker
-    // evidence. There the final sentence "A scope boundary, not an analysis
-    // gap." was measured false for 238 of 458 entries on `okhttp`, which is
-    // Kotlin-and-Java. No C# corpus here holds another CLR language — `.fs` and
-    // `.vb` counts are 0 across all six — so the claim is not *known* wrong on
-    // C#. It is unverifiable either way from inside one adapter, and a
-    // disclosure must not assert what its author cannot check.
+    // Same correction as Java's, weaker evidence: Java's "scope boundary, not
+    // an analysis gap" was measured false for 238/458 entries on `okhttp`
+    // (Kotlin+Java). No C# corpus here holds another CLR language (.fs/.vb
+    // counts are 0 across all six), so unverifiable either way — don't assert
+    // what can't be checked.
     "names a type or member this run did not analyse. Either a scope boundary — a NuGet " +
         "package, the .NET base class library, a project outside the analysed set — or a " +
         "declaration this run could not read, in another language in this same repository. " +
@@ -72,12 +55,9 @@ const REASONS = {
 const INHERITANCE_HOPS = 12;
 const PENDING_PASSES = 3;
 /**
- * Test attributes, by framework. All three are declared in source.
- *
- * xUnit `[Fact]`/`[Theory]`, NUnit `[Test]`/`[TestCase]`, MSTest `[TestMethod]`.
- * This is the same shape Java's `@Test` already handles and it is reading an
- * annotation, not guessing from a method name — C# has no naming convention for
- * tests the way XCTest does.
+ * Test attributes, by framework: xUnit `[Fact]`/`[Theory]`, NUnit
+ * `[Test]`/`[TestCase]`, MSTest `[TestMethod]`. All declared in source, read
+ * as an annotation — C# has no naming convention for tests the way XCTest does.
  */
 const TEST_ATTRIBUTES = new Set(["Fact", "Theory", "Test", "TestCase", "TestMethod", "DataTestMethod"]);
 function qualify(namespace, path) {
@@ -90,41 +70,30 @@ export function extract(input) {
     const unresolved = [];
     const seenEdge = new Set();
     const scope = input.scope;
-    // The caller's half of the HTTP boundary — collected per-method below,
-    // where the enclosing FUNCTION node and receiver scopes are both in hand,
-    // and emitted with the routes below so both halves mint one `API_ENDPOINT`.
+    // Caller's half of the HTTP boundary — collected per-method, emitted with
+    // the routes below so both halves mint one `API_ENDPOINT`.
     const clientCallSites = [];
     /**
-     * `FUNCTION`/`TEST_CASE` node id -> its index in `nodes`, so D-FIX-3's
-     * client-base extractor (DEC-164) can patch `attrs.clientBase` onto the
-     * caller node once `clientCallSites` is fully known — golden patterns
-     * 08a/08b/08c bind their `caller_*` role to the `FUNCTION`, not the edge,
-     * per `capabilities.ts`'s own "on every caller" phrasing.
+     * `FUNCTION`/`TEST_CASE` node id -> its index in `nodes`, so the client-base
+     * extractor (DEC-164) can patch `attrs.clientBase` onto the caller node once
+     * `clientCallSites` is known — golden patterns 08a/08b/08c bind `caller_*`
+     * to the `FUNCTION`, not the edge.
      */
     const functionNodeIndex = new Map();
     /** `FUNCTION`/`TEST_CASE` node id -> the `clientBase` this row attaches to it. First writer wins. */
     const functionClientBase = new Map();
-    // -------------------------------------------------------------------------
-    // Framework extractors, resolved for the whole batch before any id is minted
-    // -------------------------------------------------------------------------
-    //
-    // A MODEL is a MODEL rather than a CLASS, and the node id hashes the kind
-    // (DEC-004), so the kind has to be settled BEFORE the id exists. Both
-    // extractors also read across files — a `DbSet<Order>` names a type declared
-    // elsewhere, and the evidence making a class a controller is usually on a base
-    // in another file — so neither can run per-unit.
+    // Framework extractors, resolved for the whole batch before any id is minted:
+    // the node id hashes MODEL vs CLASS (DEC-004), so kind must be settled first,
+    // and both extractors read cross-file (a `DbSet<Order>` names a type declared
+    // elsewhere), so neither can run per-unit.
     const sources = input.sources ?? new Map();
     const frameworkFiles = input.files
         .map((parsed) => ({ parsed, source: sources.get(parsed.file) ?? "" }))
         .filter((each) => each.source !== "" && !isGenerated(each.parsed.file, each.source));
     /**
-     * The NRT context governing a file, resolved from its directives alone here.
-     *
-     * The project and the imported props are the adapter's to supply and are not
-     * reachable from a `CsFile`, so a file with no directive resolves to `absent`
-     * and its reference-typed columns come out `unresolved` and counted. That is
-     * the honest degradation: unknown is not false, and DEC-180 §2 is the whole
-     * reason this is not allowed to guess.
+     * NRT context from directives alone (project/props aren't reachable from a
+     * `CsFile`), so an undirected file resolves `absent` and its reference-typed
+     * columns come out `unresolved`. Honest degradation — DEC-180 §2 forbids guessing.
      */
     const contextOf = (file) => {
         if (input.nullableContextOf !== undefined)
@@ -135,14 +104,13 @@ export function extract(input) {
         return resolveNullable({ directives: nullableDirectives(source), project: "absent", directoryProps: "absent" }, source.split("\n").length).context;
     };
     const orm = efModels({ files: frameworkFiles, contextOf });
-    /** D-FIX-3's client-base extractor (DEC-164), the `AddHttpClient<T>(...)` half — `client-base.ts`'s own header has the account. */
+    /** Client-base extractor (DEC-164), the `AddHttpClient<T>(...)` half — see `client-base.ts`. */
     const typedClientBaseMap = typedClientBases(frameworkFiles);
     /**
-     * **Qualified** type name -> its mapping, for the CLASS/MODEL decision below.
-     *
-     * Keyed on the simple name until a resolved collision showed what that costs:
-     * two types named `Basket` in one repository both became `MODEL`, and the
-     * Razor `ViewComponent` carried the entity's columns.
+     * Qualified type name -> its mapping, for the CLASS/MODEL decision below.
+     * Keyed on the qualified name after a simple-name collision cost real data:
+     * two `Basket` types in one repo both became `MODEL`, and a Razor
+     * `ViewComponent` carried the entity's columns.
      */
     const modelsByName = new Map(orm.models.map((model) => [model.fqn, model]));
     const push = (edge, level) => {
@@ -169,32 +137,26 @@ export function extract(input) {
             ...(attrs === undefined ? {} : { attrs }),
         });
     };
-    // -------------------------------------------------------------------------
-    // Nodes — types first, so partial parts merge before any member is placed
-    // -------------------------------------------------------------------------
+    // Nodes — types first, so partial parts merge before any member is placed.
     /** Keyed by `assembly::FullyQualifiedName`, which is what makes it identity. */
     const types = new Map();
     /**
-     * The same names, keyed by fully-qualified name alone.
-     *
-     * Identity and resolution want different indexes and conflating them is a
-     * defect in both directions. The assembly separates two declarations of one
-     * name, so it belongs in the id. But a `using` reaches *across* projects — a
-     * test project referencing the app project is the ordinary case — so keying
-     * resolution by assembly too would silently drop every cross-project edge.
+     * The same names, keyed by fully-qualified name alone. Identity and
+     * resolution want different indexes: assembly separates two declarations of
+     * one name (belongs in the id), but a `using` reaches across projects (a
+     * test project referencing the app is ordinary), so keying resolution by
+     * assembly too would drop cross-project edges.
      *
-     * `<ProjectReference>` is not read, so which projects may see each other is
-     * unknown here. The rule that follows is the precision rule: prefer a match in
-     * the referencing file's own assembly, and otherwise accept a match only when
-     * exactly one assembly declares the name. Two claimants is an ambiguity to
-     * disclose, not a tie to break.
+     * `<ProjectReference>` isn't read, so cross-project visibility is unknown.
+     * Precision rule: prefer a match in the referencing file's own assembly,
+     * else accept only if exactly one assembly declares the name — two
+     * claimants is an ambiguity to disclose, not a tie to break.
      */
     const byFqn = new Map();
     const moduleIdOf = new Map();
     const moduleKeys = new Map();
-    // Sorted, so the primary declaration of a partial type is a property of the
-    // repository and not of filesystem enumeration order. DEC-083 requires this:
-    // "lexicographically first" is only reproducible if the input is ordered.
+    // Sorted: DEC-083's "lexicographically first" is only reproducible if the
+    // input is ordered, not left to filesystem enumeration order.
     const units = [...input.files].sort((a, b) => a.file.localeCompare(b.file));
     const keyOf = (unit, fqn) => `${unit.assembly}::${fqn}`;
     for (const unit of units) {
@@ -287,10 +249,9 @@ export function extract(input) {
                     : {
                         orm: "efcore",
                         ...(model.table === null ? {} : { table: model.table }),
-                        // **Not gated on `input.reached`.** A mapped column is a
-                        // declaration the framework itself enforces, not an inference, so
-                        // its resolution is the evidence's rather than the run's (DEC-058)
-                        // — the same exception `adapter-java` records for JPA.
+                        // Not gated on `input.reached`: a mapped column is a framework
+                        // declaration, not an inference — resolution is the evidence's,
+                        // not the run's (DEC-058), same exception as adapter-java's JPA.
                         ...(model.columns.length > 0
                             ? {
                                 fields: model.columns.map((column) => ({
@@ -333,10 +294,9 @@ export function extract(input) {
             const id = isCase
                 ? nodeId(scope, "TEST_CASE", testCaseQsp(holder, [unit.namespace, ...fn.ownerPath].filter((s) => s !== ""), fn.name), LANGUAGE)
                 : nodeId(scope, "FUNCTION", symbolQsp(holder, [ownerFqn, fn.name]), LANGUAGE);
-            // An overload set is one node. C# picks between overloads by argument
-            // types, which is R3 evidence this adapter does not have — so an edge to
-            // "the method called Format" is the honest claim, and pretending to have
-            // chosen an overload would be a claim it cannot support.
+            // An overload set is one node: choosing between overloads needs argument
+            // types (R3), which this adapter doesn't have — "the method called
+            // Format" is the honest claim.
             if (owner.methods.has(fn.name))
                 continue;
             owner.methods.set(fn.name, { id, fn, unit, ownerFqn, isTest: isCase });
@@ -358,24 +318,18 @@ export function extract(input) {
             });
         }
     }
-    // -------------------------------------------------------------------------
-    // Resolution
-    // -------------------------------------------------------------------------
+    // Resolution.
     /**
-     * Every fully-qualified name a written name could denote, in this file.
-     *
-     * C# searches the enclosing namespaces outward and then the imports, and a
-     * name found under two imports is genuinely ambiguous without the full type
-     * environment. Candidates are collected rather than short-circuited so that
-     * ambiguity can be *seen* instead of silently resolved to whichever rule ran
-     * first.
+     * Every fully-qualified name a written name could denote, in this file. C#
+     * searches enclosing namespaces outward then imports; a name found under
+     * two imports is genuinely ambiguous without the full type environment, so
+     * candidates are collected rather than short-circuited — ambiguity is seen,
+     * not silently resolved to whichever rule ran first.
      */
     /**
-     * `global using` declarations, by assembly.
-     *
-     * They are in force for every file in their project, so they are gathered once
-     * and consulted for every unit — the alternative is that a name introduced by
-     * one resolves nowhere else, which is the whole point of the construct.
+     * `global using` declarations, by assembly — in force for every file in
+     * their project, gathered once. Otherwise a name introduced by one file
+     * would resolve nowhere else, defeating the construct's point.
      */
     const globalUsings = new Map();
     for (const unit of units) {
@@ -395,13 +349,10 @@ export function extract(input) {
             return [];
         const found = new Set();
         const visible = usingsFor(unit);
-        // **Enclosing TYPES are searched before enclosing namespaces.** A nested
-        // type written by its simple name from inside the type that declares it —
-        // `DbLock.EnterWrite(...)` inside `PessimisticLockBehavior`, which declares
-        // `private sealed class DbLock` — resolved nowhere, because only the
-        // namespace chain was walked. Innermost wins outright, as in C#: returning
-        // here rather than adding to `found` keeps a nested `Foo` from colliding
-        // with a namespace-level `Foo` and being reported ambiguous.
+        // Enclosing TYPES are searched before namespaces: a nested type used by
+        // its simple name from inside its declaring type resolved nowhere when
+        // only the namespace chain was walked. Innermost wins outright — return
+        // here (not `found`) so a nested `Foo` never collides with a namespace `Foo`.
         if (host !== undefined) {
             let scope_ = host.fqn;
             while (scope_ !== "") {
@@ -504,22 +455,16 @@ export function extract(input) {
         }
         return undefined;
     }
-    // ---------------------------------------------------------------------------
-    // D-FIX-3's client-base extractor (DEC-164) — see `client-base.ts`'s own
-    // header for the shape and why it is scoped exactly here.
-    // ---------------------------------------------------------------------------
+    // Client-base extractor (DEC-164) — see `client-base.ts` for shape and scope.
     /**
-     * Does `rawName`'s own declaration — resolved in `unit`/`host`'s context,
-     * the same resolution every other type reference in this file goes
-     * through — carry `WebApplicationFactory<` in its written base list,
-     * directly or through one further in-repo indirection?
+     * Does `rawName`'s declaration (resolved in `unit`/`host`'s context, same
+     * as any other type reference) carry `WebApplicationFactory<` in its
+     * written base list, directly or via one further in-repo indirection?
      *
-     * `WebApplicationFactory<TEntryPoint>` is itself external (`Microsoft.
-     * AspNetCore.Mvc.Testing`), so `resolveType` never resolves it as a
-     * `DeclaredType` and `ancestry` never yields it — this reads the *written*
-     * text of each yielded type's own base list instead of trying to resolve
-     * that final hop, the same reason `baseListWritten` exists rather than
-     * `baseList` alone (see `CsType.baseListWritten`'s own doc).
+     * `WebApplicationFactory<TEntryPoint>` is external (`Microsoft.AspNetCore.Mvc.Testing`),
+     * so `resolveType`/`ancestry` never yield it — this reads the written text
+     * of each yielded type's base list instead, same reason `baseListWritten`
+     * exists rather than `baseList` alone.
      */
     function derivesFromWebApplicationFactory(rawName, unit, host) {
         const resolved = resolveType(rawName, unit, host);
@@ -534,10 +479,10 @@ export function extract(input) {
         return false;
     }
     /**
-     * The one traceable base-setting mechanism this row builds. `receiverType`
-     * is the *written* type name of whatever received a `.CreateClient()` call
-     * — see `client-base.ts`'s own header for why `IHttpClientFactory`'s named-
-     * client form and every other DI shape are deliberately left untouched.
+     * The one traceable base-setting mechanism built here. `receiverType` is
+     * the written type name of whatever received `.CreateClient()` — see
+     * `client-base.ts` for why `IHttpClientFactory`'s named-client form and
+     * other DI shapes are deliberately left untouched.
      */
     function creatorBaseOf(receiverType, unit, host) {
         if (receiverType === undefined)
@@ -545,21 +490,17 @@ export function extract(input) {
         if (!derivesFromWebApplicationFactory(receiverType, unit, host))
             return undefined;
         // `WebApplicationFactory<T>.CreateClient()`'s documented default
-        // `BaseAddress` is `http://localhost/` — origin only, no path. No
-        // corpus witness in this row overrides it (`WebApplicationFactoryClientOptions`
-        // is never constructed with its own `BaseAddress` in any of the six), so
-        // that override is not read here — disclosed, not silently assumed.
+        // `BaseAddress` is `http://localhost/`, origin only. No corpus witness
+        // overrides it, so the override path isn't read — disclosed, not assumed.
         return { state: "resolved", path: "" };
     }
     /**
-     * `var client = _factory.CreateClient();` — resolved from `scope_.pending`
-     * *before* `settle()` runs, because `settle()`'s own fallback (`locals.set(name,
-     * null)`) is exactly the silence this row exists to fix: `CreateClient` is
-     * never declared in-repo (it is inherited from an external base), so
-     * `findMethod` never finds it and every such local stayed permanently
-     * unresolved before this function existed — invisible to `clientCalls`,
-     * not even ledgered. Mutates `scope_` in place (same contract `settle`
-     * already has) and returns the per-local bases this pass resolved.
+     * `var client = _factory.CreateClient();` — read from `scope_.pending`
+     * before `settle()` runs, because `settle()`'s fallback nulls exactly this:
+     * `CreateClient` is never declared in-repo (inherited from an external
+     * base), so every such local was permanently unresolved, invisible to
+     * `clientCalls`, before this existed. Mutates `scope_` in place and returns
+     * the per-local bases resolved.
      */
     function resolveClientBaseLocals(scope_, unit, host) {
         const bases = new Map();
@@ -588,11 +529,9 @@ export function extract(input) {
     }
     /**
      * A property or field's own base, traced once per `DeclaredType` and
-     * cached — a field's inline initialiser (`memberProvenance`, read at the
-     * declaration) or a `.ctor`'s own assignment (`propertyAssignments`, read
-     * from the constructor's body) are the two shapes measured; the first
-     * writer for a given name wins, matching `findMember`'s own "nearest
-     * declaration" precedence.
+     * cached. Two shapes: a field's inline initialiser (`memberProvenance`) or
+     * a `.ctor`'s assignment (`propertyAssignments`) — first writer wins,
+     * matching `findMember`'s "nearest declaration" precedence.
      */
     const memberClientBaseCache = new Map();
     function memberClientBase(declared) {
@@ -657,18 +596,15 @@ export function extract(input) {
         return resolveType(written, unit, host);
     }
     /**
-     * The receiver's type **as written**, without resolving it to a declaration —
-     * `HttpClient` has none in this repository, and `ownerOfReceiver` above would
-     * refuse it for exactly that reason. D-FIX-3 needs the name, not the node, so
-     * this stops one step earlier: same lookup order (`locals`, then the host
-     * type's own members), same `null`-is-poisoned handling, no `resolveType` call.
+     * The receiver's type as written, without resolving to a declaration —
+     * `HttpClient` has none in this repo, so `ownerOfReceiver` would refuse it.
+     * This needs the name, not the node: same lookup order (`locals`, then host
+     * members), same `null`-is-poisoned handling, no `resolveType` call.
      *
-     * `ref.receiverProperty` is resolved only through `this` — `this._client.Get()`
-     * — not through an arbitrary chain (`_service.Client.Get()`), which is a
-     * disclosed limit rather than an attempt to walk a chain this reader does not
-     * track elsewhere. `ref.receiverCall` (`Factory.CreateClient().Get()`) is left
-     * unresolved for the same reason Java's chained builder is: no receiver here
-     * has a written type, so nothing is silently guessed.
+     * Disclosed limit: `ref.receiverProperty` resolves only through `this`
+     * (`this._client.Get()`), not an arbitrary chain (`_service.Client.Get()`).
+     * `ref.receiverCall` (`Factory.CreateClient().Get()`) stays unresolved for
+     * the same reason as Java's chained builder — nothing is silently guessed.
      */
     function writtenReceiverType(ref, scope_, host) {
         if (ref.receiverType !== undefined)
@@ -720,16 +656,14 @@ export function extract(input) {
             scope_.locals.set(name, null);
         scope_.pending.clear();
     }
-    // -------------------------------------------------------------------------
-    // Edges
-    // -------------------------------------------------------------------------
+    // Edges.
     for (const unit of units) {
         const moduleId = moduleIdOf.get(unit.file);
         if (moduleId === undefined)
             continue;
-        // IMPORTS. A C# `using` names a *namespace*, so like Go's package import it
-        // fans out — to every file declaring a type in that namespace. That is not
-        // an approximation: importing a namespace makes every type in it visible.
+        // IMPORTS. A `using` names a namespace, so like Go's package import it
+        // fans out to every file declaring a type in it — not an approximation,
+        // importing a namespace makes every type in it visible.
         for (const using of unit.usings) {
             const targets = new Set();
             for (const declared of types.values()) {
@@ -769,30 +703,23 @@ export function extract(input) {
             const declared = host?.methods.get(fn.name);
             if (declared === undefined || declared.unit.file !== unit.file || declared.fn !== fn)
                 continue;
-            // D-FIX-3's client-base extractor (DEC-164): `var client =
-            // _factory.CreateClient();` must be read out of `fn.scope.pending`
-            // *before* `settle()` runs — `settle()`'s own fallback nulls out
-            // anything it cannot resolve, and `CreateClient` is never declared
-            // in-repo (inherited from an external base), so every such local
-            // stayed permanently, silently unresolved before this pass existed.
+            // Client-base extractor (DEC-164): must run before `settle()`, whose
+            // fallback nulls out anything unresolved (see `resolveClientBaseLocals`).
             const localClientBase = resolveClientBaseLocals(fn.scope, unit, host);
             settle(fn.scope, unit, host);
-            // The caller's half of the HTTP boundary (DEC-241 §4). Read alongside
-            // the general ref loop below rather than inside it — `clientCalls` owns
-            // its own candidate predicate (`candidateClientRefs`), the same
-            // separation Java's `client.ts` keeps from `extract.ts`'s general
-            // `CALLS` handling.
+            // Caller's half of the HTTP boundary (DEC-241 §4). Read alongside the
+            // general ref loop, not inside it — `clientCalls` owns its own
+            // candidate predicate, same separation Java's `client.ts` keeps.
             {
                 const clientBaseOf = (ref) => {
                     // A local traced through `resolveClientBaseLocals` above.
                     const local = localClientBase.get(ref.receiver);
                     if (local !== undefined)
                         return local;
-                    // `this.Client` / a bare `Client` reaching a member on the host type.
-                    // A bare receiver only ever names a member here when it is not
-                    // *also* a local or parameter — same precedence `writtenReceiverType`
-                    // already applies, so a local that happens to shadow a same-named
-                    // member is never misattributed to the member's own base.
+                    // `this.Client` / a bare `Client` reaching a host member. Only
+                    // counts when the receiver isn't also a local or parameter — same
+                    // precedence `writtenReceiverType` applies, so a shadowing local is
+                    // never misattributed to the member's own base.
                     const propertyName = ref.receiverProperty !== undefined
                         ? ref.receiverProperty.of === "this"
                             ? ref.receiverProperty.name
@@ -805,12 +732,10 @@ export function extract(input) {
                         if (member !== undefined)
                             return member;
                     }
-                    // `AddHttpClient<TClient>(...)` — DI hands the configured client
-                    // straight to `TClient`'s own constructor, so a call inside
-                    // `TClient` whose receiver reached here untraced is exactly that
-                    // typed client. Matched against the host's own simple name — see
-                    // `typedClientBases`'s own doc for why this is textual rather than
-                    // a full type resolution.
+                    // `AddHttpClient<TClient>(...)`: DI hands the configured client
+                    // straight to `TClient`'s constructor, so an untraced receiver
+                    // inside `TClient` is exactly that typed client — matched against
+                    // the host's simple name (see `typedClientBases` for why textual).
                     if (host !== undefined) {
                         const simple = host.fqn.slice(host.fqn.lastIndexOf(".") + 1);
                         const typed = typedClientBaseMap.get(simple);
@@ -826,11 +751,9 @@ export function extract(input) {
                         functionClientBase.set(call.fromId, call.clientBase);
                 }
                 for (const refusal of read.refusals) {
-                    // A refusal still carries `clientBase` when DEC-164's own
-                    // `unresolved` state is *why* it refused — golden pattern 08b binds
-                    // its `caller_unresolved_base` role to the `FUNCTION` even though
-                    // no `USES_API` edge exists to look at, so the node is the only
-                    // place that fact can live.
+                    // A refusal still carries `clientBase` when DEC-164's `unresolved`
+                    // state is why it refused — golden 08b binds `caller_unresolved_base`
+                    // to the `FUNCTION` node, the only place the fact can live.
                     if (refusal.clientBase !== undefined && !functionClientBase.has(refusal.fromId)) {
                         functionClientBase.set(refusal.fromId, refusal.clientBase);
                     }
@@ -869,11 +792,9 @@ export function extract(input) {
         }
     }
     /**
-     * DEC-084 in one function.
-     *
-     * Position is a specification guarantee, not a convention: a class has at most
-     * one base class and it must come first. So only the first entry of a class
-     * base list is ever ambiguous, and everything else is decided by the language.
+     * DEC-084 in one function: base-list position is a language guarantee, not
+     * a convention, so only the first entry of a class base list is ever
+     * ambiguous — everything else is decided by the language.
      */
     function emitBaseList(declared, part, unit) {
         part.baseList.forEach((raw, index) => {
@@ -994,31 +915,24 @@ export function extract(input) {
         }
         return ownerOfReceiver(ref.receiver, scope_, unit, host);
     }
-    // -------------------------------------------------------------------------
-    // Routes
-    // -------------------------------------------------------------------------
-    //
-    // R2 and no lower, for the reason `adapter-go` records and `adapter-java`
-    // repeats: telling a controller from an ordinary class is provenance, and a
-    // route emitted from the R0 or R1 rung is a claim stronger than the run that
-    // produced it — which the Normaliser rejects as RESOLUTION_EXCEEDS_BATCH.
+    // Routes. R2 and no lower (adapter-go/adapter-java's reason too): telling a
+    // controller from an ordinary class is provenance, and an R0/R1 route is a
+    // stronger claim than the run supports — Normaliser rejects it as
+    // RESOLUTION_EXCEEDS_BATCH.
     //
-    // Gated on `reached >= 2` alone, not on `frameworkFiles.length > 0` — a
-    // repository can make outbound `HttpClient` calls without being an ASP.NET
-    // server itself (a pure API-consuming client, an integration test project),
-    // so the caller's half below must not depend on route files existing. Only
-    // the route loop itself stays gated on ASP.NET files being present.
+    // Gated on `reached >= 2` alone, not `frameworkFiles.length > 0`: a repo can
+    // make outbound `HttpClient` calls without being an ASP.NET server itself,
+    // so the caller's half must not depend on route files existing. Only the
+    // route loop itself is gated on ASP.NET files being present.
     if (input.reached >= 2) {
         const routeNodes = new Map();
         const endpointNodes = new Map();
         if (frameworkFiles.length > 0) {
             const census = aspNetRoutes({ files: frameworkFiles });
-            // D-FIX-3's own finding: `census.unresolvedBaseSites` was computed
-            // correctly and never reached this ledger before this row — a real,
-            // disclosed-by-the-adapter-internally refusal that was nonetheless a
-            // true silence from `emit()`'s own caller's point of view. `SERVES_API`
-            // is the edge type this class's controller status would have produced
-            // evidence for, had the base resolved.
+            // `census.unresolvedBaseSites` was computed correctly but never reached
+            // this ledger before — a real refusal that was still a silence from
+            // `emit()`'s caller's point of view. `SERVES_API` is the edge type this
+            // class's controller status would have produced, had the base resolved.
             const unitByFile = new Map(units.map((each) => [each.file, each]));
             for (const site of census.unresolvedBaseSites) {
                 const unit = unitByFile.get(site.file);
@@ -1055,10 +969,9 @@ export function extract(input) {
                         },
                     });
                 }
-                // Workspace-scoped, fileless, language-less, and minted with the SAME
-                // `endpointQsp` every other producer uses — DEC-115's one hard
-                // constraint. Two producers that mint different ids do not conflict,
-                // they silently fail to join.
+                // Workspace-scoped, fileless, language-less, minted with the SAME
+                // `endpointQsp` every producer uses (DEC-115): mismatched ids don't
+                // conflict, they silently fail to join.
                 const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(route.method, route.written), null);
                 if (!endpointNodes.has(endpointId)) {
                     endpointNodes.set(endpointId, {
@@ -1076,12 +989,10 @@ export function extract(input) {
                 push({ from: routeId, to: endpointId, type: "SERVES_API" }, 2);
             }
         }
-        // --- The caller's half ---------------------------------------------------
-        //
-        // Mints into the SAME `endpointNodes` map, so a call to a route this run
-        // also read produces one node with two edges rather than two nodes with
-        // one each. A call to a route this run did *not* read still mints its
-        // endpoint — either side can exist without the other (golden 08's note).
+        // Caller's half. Mints into the SAME `endpointNodes` map, so a call to a
+        // route this run also read produces one node with two edges, not two. A
+        // call to an unread route still mints its endpoint — either side can
+        // exist without the other (golden 08).
         for (const call of clientCallSites) {
             const endpoint = endpointFor(scope, call, input.producedBy, normaliseEndpointPath);
             if (!endpointNodes.has(endpoint.id))
@@ -1090,24 +1001,19 @@ export function extract(input) {
                 from: call.fromId,
                 to: endpoint.id,
                 type: "USES_API",
-                // DEC-164's contract: every `USES_API` edge this adapter mints now
-                // carries `clientBase` — `resolved` (a traced base composed per
-                // DEC-097) or `none` (no traced mechanism; the call's own literal
-                // path stood alone, unchanged from before this row). See
-                // `client-base.ts`'s own header for why `unresolved` is never
-                // produced by this build.
+                // DEC-164: every `USES_API` edge carries `clientBase` — `resolved`
+                // (traced base, DEC-097) or `none` (no traced mechanism, literal
+                // path stands alone). See `client-base.ts` for why `unresolved` is
+                // never produced by this build.
                 attrs: { callerKind: call.callerKind, via: call.method, clientBase: call.clientBase },
             }, 2);
         }
         nodes.push(...routeNodes.values(), ...endpointNodes.values());
     }
-    // D-FIX-3's client-base extractor (DEC-164): patch `attrs.clientBase` onto
-    // the caller `FUNCTION`/`TEST_CASE` node itself, not just the `USES_API`
-    // edge — golden patterns 08a/08b/08c bind their `caller_*` role to the
-    // node, and 08b's refused call has no edge for the fact to live on at all.
-    // Done here, after every unit's calls and refusals are known, because
-    // `functionNodeIndex` and `functionClientBase` are both built incrementally
-    // across the whole loop above.
+    // Client-base extractor (DEC-164): patch `attrs.clientBase` onto the caller
+    // node itself, not just the edge — golden 08a/08b/08c bind `caller_*` to
+    // the node, and 08b's refused call has no edge to carry the fact. Done here
+    // since `functionNodeIndex`/`functionClientBase` build incrementally above.
     for (const [fnId, base] of functionClientBase) {
         const index = functionNodeIndex.get(fnId);
         const node = index === undefined ? undefined : nodes[index];