Stage demand cache identity once per scan

Author: trissim

NRA_SCAN_PERFORMANCE_HANDOFF.md

@@ -1,5 +1,42 @@
 # NRA scan-performance handoff
 
+## 2026-08-08 cache-policy and staged-demand-signature checkpoint
+
+A corrected one-worker DQDock profile puts 38.0 of 74.6 process-CPU seconds
+inside demanded-family extraction.  Class projection is the largest single
+family at 15.2 seconds, but two follow-up experiments rejected the apparent
+local fixes: disabling eager AutoRegister graph construction saved at most
+2.4 seconds because most attributed time belongs to the shared syntax index,
+and a header-only class core is unsafe for 39 of the 41 live class-family
+consumers.  The slowest individual modules are only 2.0--2.4 seconds, so there
+is no exceptional shard tail to isolate.  More class/index micro-optimization
+cannot plausibly bridge the remaining order-scale target.
+
+The retained change moves cache policy ahead of cache identity construction:
+cache-disabled source stores now return before hashing family and demand
+identities.  Cache-enabled workers receive each demand signature staged once
+by the parent scan and reuse it for load, content-signature, native-store, and
+AST-store operations.  This removes about 15,600 pointless identity builds on
+a DQDock ``--no-cache`` scan without introducing a second cache authority.
+
+Against a same-host detached control at ``87879ba``, two DQDock no-cache runs
+changed from 24.101/24.125 seconds wall (22.967/22.742 internal) to
+20.826/20.533 seconds wall (19.622/19.486 internal), roughly a 15% controlled
+cold improvement.  A fresh empty-cache scan completes in 23.308 seconds wall
+and 21.346 internal; its unchanged follow-up completes in 1.546 seconds wall
+and 0.582 internal.  OpenHCS no-cache completes in 15.938 seconds wall and
+14.907 internal versus the retained 18.170/17.145 gate.  DQDock retains all
+12 expected findings across 252 detectors and OpenHCS retains all 45.  The
+analysis-cache suite passes all 146 tests, including a regression that makes
+worker-side demand-signature reconstruction fail.
+
+This is a material transferable gain, not the requested order-of-magnitude
+collapse.  The next architectural gate is a detector-declared candidate-seed
+contract or a shared demanded-event bundle that can avoid constructing entire
+unused families.  It must demonstrate exact survivor collapse on saved
+DQDock and OpenHCS artifacts before production wiring; further local class
+header or syntax-index polishing is rejected by the measured ceiling above.
+
 ## 2026-08-08 shared demanded-event checkpoint
 
 The report-witness experiment reached a measured ceiling and was stopped.

nominal_refactor_advisor/analysis.py

@@ -995,6 +995,7 @@ class CompactProjectionBuildRequest:
     config: DetectorConfig
     local_detector_types: tuple[type[IssueDetector], ...] = ()
     family_demands: tuple[tuple[type[CollectedFamily], object], ...] = ()
+    family_demand_signatures: tuple[tuple[type[CollectedFamily], str], ...] = ()
     bundle_families: tuple[type[CollectedFamily], ...] = ()
 
 
@@ -1042,6 +1043,7 @@ def add_runtime_projection(
     fallback_local_detector_types = request.local_detector_types
     ast_families = list(request.missing_families)
     demand_by_family = dict(request.family_demands)
+    demand_signature_by_family = dict(request.family_demand_signatures)
     for family in tuple(ast_families):
         demand = demand_by_family.get(family)
         if demand is None:
@@ -1053,6 +1055,7 @@ def add_runtime_projection(
             family_cache_dir=source.family_cache_dir,
             family=family,
             demand=demand,
+            demand_signature=demand_signature_by_family.get(family),
         )
         if projections is None:
             continue
@@ -1066,6 +1069,7 @@ def add_runtime_projection(
                 family_cache_dir=source.family_cache_dir,
                 family=family,
                 demand=demand,
+                demand_signature=demand_signature_by_family.get(family),
             ),
         )
         ast_families.remove(family)
@@ -1174,6 +1178,7 @@ def add_runtime_projection(
                             family=family,
                             demand=demand,
                             items=projections,
+                            demand_signature=demand_signature_by_family.get(family),
                         )
                     add_runtime_projection(family, projections, projection_signature)
                     ast_families.remove(family)
@@ -1230,6 +1235,7 @@ def add_runtime_projection(
                         family=family,
                         demand=demand,
                         items=projections,
+                        demand_signature=demand_signature_by_family.get(family),
                     )
                 )
             else:
@@ -2221,6 +2227,15 @@ def extend_report_findings(
                             if family in report_family_demands
                         )
                     ),
+                    family_demand_signatures=(
+                        ()
+                        if include_local_findings
+                        else tuple(
+                            (family, projection_manifest._demand_signature(family))
+                            for family in missing_families
+                            if family in report_family_demands
+                        )
+                    ),
                     bundle_families=projection_manifest.projection_families,
                 )
             )

nominal_refactor_advisor/ast_tools.py

@@ -2095,6 +2095,8 @@ def store_cached_collected_family_items_for_source_signature(
 ) -> str | None:
     """Publish source-native compact facts under the existing cache identity."""
 
+    if family_cache_dir is None:
+        return None
     return _store_cached_collected_family_items_for_identity(
         cache_dir=family_cache_dir,
         identity=_collected_family_cache_identity_for_source_signature(
@@ -2117,9 +2119,12 @@ def store_cached_demanded_collected_family_items_for_source_signature(
     family: type[CollectedFamily[ShapeItemT]],
     demand: object,
     items: tuple[ShapeItemT, ...],
+    demand_signature: str | None = None,
 ) -> str | None:
     """Persist a focused view without publishing it as the complete family."""
 
+    if family_cache_dir is None:
+        return None
     return _store_cached_collected_family_items_for_identity(
         cache_dir=family_cache_dir,
         identity=_collected_family_demand_cache_identity_for_source_signature(
@@ -2128,6 +2133,7 @@ def store_cached_demanded_collected_family_items_for_source_signature(
             source_signature=source_signature,
             family=family,
             demand=demand,
+            demand_signature=demand_signature,
         ),
         family=family,
         items=items,

tests/test_analysis_cache.py

@@ -2826,6 +2826,25 @@ def test_source_demand_projection_shard_is_filtered_and_not_cached_as_full(
     )
     role_family = role_surface_detectors.CompactRoleSurfaceModuleProjectionFamily
     boundary_family = surface_detectors.CompactDistributedBoundaryModuleProjectionFamily
+    role_demand = role_surface_detectors.CompactRoleSurfaceProjectionDemand(
+        field_names=frozenset({"selected_values"}),
+        generic_axis_tokens=frozenset(),
+        generic_case_tokens=frozenset(),
+        minimum_generic_case_count=2,
+    )
+    boundary_demand = surface_detectors.CompactDistributedBoundaryProjectionDemand(
+        frozenset({"projected_axis_offsets"})
+    )
+    demand_signatures = (
+        (
+            role_family,
+            ast_tools_module.collected_family_demand_cache_signature(role_demand),
+        ),
+        (
+            boundary_family,
+            ast_tools_module.collected_family_demand_cache_signature(boundary_demand),
+        ),
+    )
 
     def unexpected_ast_parse(self, paths):
         del self, paths
@@ -2838,28 +2857,25 @@ def unexpected_ast_parse(self, paths):
         "parsed_source_paths",
         unexpected_ast_parse,
     )
+
+    def unexpected_demand_signature(_demand: object) -> str:
+        raise AssertionError("worker must reuse the staged demand signature")
+
+    monkeypatch.setattr(
+        ast_tools_module,
+        "collected_family_demand_cache_signature",
+        unexpected_demand_signature,
+    )
     result = analysis_module.build_compact_projection_shard(
         analysis_module.CompactProjectionBuildRequest(
             source=projection_source,
             missing_families=(role_family, boundary_family),
             config=DetectorConfig(),
             family_demands=(
-                (
-                    role_family,
-                    role_surface_detectors.CompactRoleSurfaceProjectionDemand(
-                        field_names=frozenset({"selected_values"}),
-                        generic_axis_tokens=frozenset(),
-                        generic_case_tokens=frozenset(),
-                        minimum_generic_case_count=2,
-                    ),
-                ),
-                (
-                    boundary_family,
-                    surface_detectors.CompactDistributedBoundaryProjectionDemand(
-                        frozenset({"projected_axis_offsets"})
-                    ),
-                ),
+                (role_family, role_demand),
+                (boundary_family, boundary_demand),
             ),
+            family_demand_signatures=demand_signatures,
         )
     )