NAMESPACE XL-4: reference-derived dependency graph instrument

dag/gunbc/instruments/reference_derived_graph.dag

@@ -0,0 +1,200 @@
+module tools.reference_derived_graph
+
+import std.process { ExitSuccess, ProcessExit, exit_failure }
+import std.types { Bool, List, String }
+import extdeps.filesystem.filesystem_io
+import v2.std.algebra { any, fold_list }
+import v2.std.diagnostic { Accepted, Outcome, Rejected }
+import v2.lens.module_graph {
+  ImportResolutionFact,
+  ModuleDependencyEdge,
+  dependency_edges_from_import_facts,
+  import_resolution_facts_live,
+  reference_derived_resolution_facts,
+}
+
+// XL-4 instrument: the reference-derived graph (swap body of v2.lens.module_graph) and its
+// typed difference against the import-derived graph, over a named source root.
+//
+//   gunbc run --source-root dag --source-root src/v2 \
+//     --entry dag/gunbc/instruments/reference_derived_graph.dag --function main
+//
+// Discriminating run is the fixture root below. Qualified mentions are a declared frontier
+// triggered on the dotted-reference capability, not lowering. Call contents are
+// eager-raven-113. Bare field types have a tree-side census with UNVERIFIED cause. Collector-only.
+// Unused-import-must-not-mint-a-reference-edge still is. It does not swap
+// dependency_resolution_facts_live (NAMESPACE-XL STAGE XL-6).
+
+data instrument_source_roots: List<String> = ["dag/test/fixture/reference_derived_graph"]
+
+data instrument_exclude: List<String> = []
+
+data provider_module: String = "test.fixture.reference_derived_graph.provider"
+
+data consumer_reference_only_path: String = "dag/test/fixture/reference_derived_graph/consumer_reference_only.dag"
+
+data consumer_import_only_path: String = "dag/test/fixture/reference_derived_graph/consumer_import_only.dag"
+
+type ReferenceImportEdgeDiff
+  = SharedEdge { path: String, target_module: String }
+  | ReferenceOnlyEdge { path: String, target_module: String }
+  | ImportOnlyEdge { path: String, target_module: String }
+
+type ReferenceDerivedGraphReport {
+  source_roots: List<String>
+  reference_edges: List<ModuleDependencyEdge>
+  import_edges: List<ModuleDependencyEdge>
+  diffs: List<ReferenceImportEdgeDiff>
+}
+
+fn has_identity(edges: List<ModuleDependencyEdge>, path: String, target_module: String) -> Bool {
+  any(xs: edges, predicate: fn(e) { e.path == path && e.target_module == target_module })
+}
+
+fn diff_against_import(
+  reference_edges: List<ModuleDependencyEdge>,
+  import_edges: List<ModuleDependencyEdge>
+) -> List<ReferenceImportEdgeDiff> {
+  let from_reference = fold_list(
+    xs: reference_edges,
+    empty: [],
+    cons: fn(acc, edge) {
+      concat(acc, [
+        if has_identity(edges: import_edges, path: edge.path, target_module: edge.target_module) {
+          SharedEdge { path: edge.path, target_module: edge.target_module }
+        } else {
+          ReferenceOnlyEdge { path: edge.path, target_module: edge.target_module }
+        }
+      ])
+    }
+  )
+  fold_list(
+    xs: import_edges,
+    empty: from_reference,
+    cons: fn(acc, edge) {
+      if has_identity(edges: reference_edges, path: edge.path, target_module: edge.target_module) {
+        acc
+      } else {
+        concat(acc, [ImportOnlyEdge { path: edge.path, target_module: edge.target_module }])
+      }
+    }
+  )
+}
+
+fn report(source_roots: List<String>) -> Outcome<ReferenceDerivedGraphReport> {
+  match reference_derived_resolution_facts(
+    pool_roots: source_roots,
+    importer_roots: source_roots,
+    exclude_substrings: instrument_exclude
+  ) {
+    Rejected { diagnostics: d } => Rejected { diagnostics: d }
+    Accepted { value: reference_edges, diagnostics: pending } => {
+      let import_edges = dependency_edges_from_import_facts(
+        edges: import_resolution_facts_live(
+          pool_roots: source_roots,
+          importer_roots: source_roots,
+          exclude_substrings: instrument_exclude
+        )
+      )
+      Accepted {
+        value: ReferenceDerivedGraphReport {
+          source_roots: source_roots,
+          reference_edges: reference_edges,
+          import_edges: import_edges,
+          diffs: diff_against_import(
+            reference_edges: reference_edges,
+            import_edges: import_edges
+          )
+        },
+        diagnostics: pending
+      }
+    }
+  }
+}
+
+fn fixture_report() -> Outcome<ReferenceDerivedGraphReport> {
+  report(source_roots: instrument_source_roots)
+}
+
+fn diffs_include_reference_only(diffs: List<ReferenceImportEdgeDiff>, path: String, target: String) -> Bool {
+  any(xs: diffs, predicate: fn(d) {
+    match d {
+      ReferenceOnlyEdge { path: p, target_module: t } => p == path && t == target
+      SharedEdge { path: _, target_module: _ } => false
+      ImportOnlyEdge { path: _, target_module: _ } => false
+    }
+  })
+}
+
+fn diffs_include_import_only(diffs: List<ReferenceImportEdgeDiff>, path: String, target: String) -> Bool {
+  any(xs: diffs, predicate: fn(d) {
+    match d {
+      ImportOnlyEdge { path: p, target_module: t } => p == path && t == target
+      SharedEdge { path: _, target_module: _ } => false
+      ReferenceOnlyEdge { path: _, target_module: _ } => false
+    }
+  })
+}
+
+fn diffs_include_shared(diffs: List<ReferenceImportEdgeDiff>, path: String, target: String) -> Bool {
+  any(xs: diffs, predicate: fn(d) {
+    match d {
+      SharedEdge { path: p, target_module: t } => p == path && t == target
+      ReferenceOnlyEdge { path: _, target_module: _ } => false
+      ImportOnlyEdge { path: _, target_module: _ } => false
+    }
+  })
+}
+
+fn main() -> ProcessExit {
+  match fixture_report() {
+    Rejected { diagnostics: _ } =>
+      exit_failure(
+        reason: "tools.reference_derived_graph.report refused over the fixture source root"
+      )
+    Accepted { value: r, diagnostics: _ } =>
+      if !(diffs_include_reference_only(
+        diffs: r.diffs,
+        path: consumer_reference_only_path,
+        target: provider_module
+      ) || diffs_include_shared(
+        diffs: r.diffs,
+        path: consumer_reference_only_path,
+        target: provider_module
+      )) {
+        exit_failure(
+          reason: "positive control absent: the reference-only fixture produced no reference-derived edge, so every negative check below would pass on an empty edge set"
+        )
+      } else if diffs_include_import_only(
+        diffs: r.diffs,
+        path: consumer_reference_only_path,
+        target: provider_module
+      ) {
+        exit_failure(
+          reason: "the reference-only fixture was classified as import-only, so the instrument is reading import syntax"
+        )
+      } else if !diffs_include_import_only(
+        diffs: r.diffs,
+        path: consumer_import_only_path,
+        target: provider_module
+      ) {
+        exit_failure(
+          reason: "an import with no reference produced a reference-derived edge or dropped the import-only difference"
+        )
+      } else if diffs_include_reference_only(
+        diffs: r.diffs,
+        path: consumer_import_only_path,
+        target: provider_module
+      ) || diffs_include_shared(
+        diffs: r.diffs,
+        path: consumer_import_only_path,
+        target: provider_module
+      ) {
+        exit_failure(
+          reason: "an unused import minted a reference-derived edge"
+        )
+      } else {
+        ExitSuccess
+      }
+  }
+}

dag/gunbc/namespace/namespace_cut_stage.dag

@@ -163,8 +163,11 @@ data required_stage_delivery_evidence_kinds: List<StageDeliveryEvidenceKind> = [
   ReferenceGraphInstrumentDelivered,
 ]
 
-// Empty by construction today: neither instrument exists. A row lands here when the stage that
-// owes it delivers it.
+// Empty: neither instrument is delivered. XL-4's reference-graph instrument exists, but on the
+// production ingest route it emits no reference-derived edge for any fixture, so it has no accepted
+// positive control there (review 64925 on gunbc#11202). A receipt discriminated only over hand-built
+// roots would inflate the rung (DESIGN 4b(1)). The row lands when tools.reference_derived_graph main
+// exits success on the production route, which requires its positive control.
 data held_stage_delivery_receipts: List<StageDeliveryReceipt> = []
 
 fn stage_delivery_outstanding(held: List<StageDeliveryReceipt>) -> List<String> {

dag/gunbc/recurring_failure_mode/shared_precondition_re_derived_once_per_claim_frame.dag

@@ -22,6 +22,8 @@ data shared_precondition_re_derived_once_per_claim_frame: RecurringFailureMode =
 
     "SECOND SPECIMEN, gunbc#11032, arriving by the same recognition rule a day later and diagnosed by a lane that had not read this row. A newly landed family -- the where-refinement parse witnesses from gunbc#10946 -- refused the 500ms line on main with interrupted_before_verdict and nothing failing. Partitioned, the shared precondition dominated: v2.compiler.parse parse_grammar_digest and the production index were re-derived on EVERY PARSE CALL although prepare_grammar had fixed both before the first token, and the shared fixture sources were re-parsed per claim. The producer that named it is the floor's cross-claim demand census (main run 34556223550, required_floor_cross_claim_demand.tsv, row parse_grammar_digest). The repair was the one this row prescribes: carry both facts on the prepared grammar, the seam where the grammar is already resolved, and share the fixture trees warm (v2.workflow.floor_pure_producer_share floor_cross_claim_pure_producers_warm). Its frame is narrower than a claim -- per parse call -- which widens this row's reach rather than founding a neighbour: the question that finds it is still the one above. It also shows the census already locating the class and nothing refusing on it, which is this row's next-rung trigger unmet.",
 
+    "XL-4 SPECIMEN, gunbc#11202. Two claim files -- v2.test.claim.reference_derived_graph_call_arg_tree and v2.test.claim.reference_derived_graph_production_ingest -- re-derived the same parse-and-normalize ingest once per claim frame. Floor run 34730467598: verdict=FloorRefused, interrupted_before_verdict=23, ENROLMENT-MARGIN-REFUSED at the 500ms ceiling. Hoisting into module-scope data rows does not help (the claim frame is narrower than the file). The repair is one warm producer, v2.test.claim.reference_derived_graph_fixture.xl4_fixture_trees, consumed by both files. The seam is the ingest, not the collector: the claims name the collector and the edge fold.",
+
     "WHAT THE DIAGNOSTIC OFFERED AND WHY BOTH ARMS WERE WRONG, recorded because two readers took them in turn and neither questioned the frame. The refusal named exactly two remedies -- reduce the cost, or move the row to a lane declaring its own ceiling -- and a cost ladder showed the first unreachable, since the cheapest possible precondition was already 1.45x the line. That made the second arm look forced, and it is worse than it looks: the only off-floor home in the tree is a namespace the floor's own authority describes as NOT COVERED by anything, so routing there would have executed the rows nowhere and greened the gate over four unobserved claims. A diagnostic that enumerates its remedies teaches its reader that the enumeration is exhaustive; here the repair was in neither arm, and the reason is that both arms are about what the cost is ALLOWED to be while the defect was how many times it was paid.",
 
     "RUNG FOUND AT: mitigatable. The gate refuses, typed and located, and contains the harm -- it did not ship a wrong verdict. What it does not do is name the duplication, so the refusal is discovered per family and diagnosed by hand, and on this specimen two readers in sequence reasoned about cost allowance before anyone asked about cost multiplicity.",

dag/test/fixture/reference_derived_graph/consumer_body_value.dag

@@ -0,0 +1,7 @@
+module test.fixture.reference_derived_graph.consumer_body_value
+
+import std.types { Int }
+
+fn uses() -> Int {
+  test.fixture.reference_derived_graph.provider.provided_value
+}

dag/test/fixture/reference_derived_graph/consumer_both.dag

@@ -0,0 +1,8 @@
+module test.fixture.reference_derived_graph.consumer_both
+
+import std.types { Int }
+import test.fixture.reference_derived_graph.provider { provided_value }
+
+fn uses_imported_provider() -> Int {
+  test.fixture.reference_derived_graph.provider.provided_value
+}

dag/test/fixture/reference_derived_graph/consumer_call_only.dag

@@ -0,0 +1,9 @@
+module test.fixture.reference_derived_graph.consumer_call_only
+
+import std.types { Int }
+
+fn sink(x: Int) -> Int { x }
+
+fn uses_only_in_call() -> Int {
+  sink(x: test.fixture.reference_derived_graph.provider.provided_value)
+}

dag/test/fixture/reference_derived_graph/consumer_callee_only.dag

@@ -0,0 +1,7 @@
+module test.fixture.reference_derived_graph.consumer_callee_only
+
+import std.types { Int }
+
+fn uses_only_as_callee() -> Int {
+  test.fixture.reference_derived_graph.provider.provided_fn()
+}

dag/test/fixture/reference_derived_graph/consumer_field_bare_local.dag

@@ -0,0 +1,15 @@
+module test.fixture.reference_derived_graph.consumer_field_bare_local
+
+import std.types { Int }
+
+type LocalFieldOnly
+
+type LocalParamMarker
+
+type LocalWrapper {
+  f: LocalFieldOnly
+}
+
+fn uses(x: LocalParamMarker) -> Int {
+  1
+}

dag/test/fixture/reference_derived_graph/consumer_import_only.dag

@@ -0,0 +1,3 @@
+module test.fixture.reference_derived_graph.consumer_import_only
+
+import test.fixture.reference_derived_graph.provider { ProvidedMarker }

dag/test/fixture/reference_derived_graph/consumer_reference_only.dag

@@ -0,0 +1,7 @@
+module test.fixture.reference_derived_graph.consumer_reference_only
+
+import std.types { Int }
+
+fn uses_provider() -> Int {
+  test.fixture.reference_derived_graph.provider.provided_value
+}

dag/test/fixture/reference_derived_graph/consumer_type_bare_local.dag

@@ -0,0 +1,9 @@
+module test.fixture.reference_derived_graph.consumer_type_bare_local
+
+import std.types { Int }
+
+type LocalMarker
+
+fn uses(x: LocalMarker) -> Int {
+  1
+}

dag/test/fixture/reference_derived_graph/consumer_type_imported.dag

@@ -0,0 +1,8 @@
+module test.fixture.reference_derived_graph.consumer_type_imported
+
+import std.types { Int }
+import test.fixture.reference_derived_graph.provider { ProvidedMarker }
+
+fn uses(x: ProvidedMarker) -> Int {
+  1
+}

dag/test/fixture/reference_derived_graph/consumer_type_only.dag

@@ -0,0 +1,9 @@
+module test.fixture.reference_derived_graph.consumer_type_only
+
+import std.types { Int }
+
+fn uses(
+  x: test.fixture.reference_derived_graph.provider.ProvidedMarker
+) -> Int {
+  1
+}

dag/test/fixture/reference_derived_graph/provider.dag

@@ -0,0 +1,9 @@
+module test.fixture.reference_derived_graph.provider
+
+import std.types { Int }
+
+type ProvidedMarker
+
+data provided_value: Int = 1
+
+fn provided_fn() -> Int { 1 }