gitgalaxy 2.6.0__tar.gz → 2.7.0__tar.gz

{gitgalaxy-2.6.0/gitgalaxy.egg-info → gitgalaxy-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitgalaxy
-Version: 2.6.0
+Version: 2.7.0
 Summary: An AST-free, LLM-free zero-trust static analysis engine for mapping architectural risk, securing CI/CD pipelines, and modernizing legacy monoliths.
 Author: Joe Esquibel
 Project-URL: Homepage, https://gitgalaxy.io
@@ -119,8 +119,8 @@ and test data aggressively, and §5 of the brief itemizes every exclusion by
 extension and reason.
 
 **cics-genapp** (IBM's CICS COBOL/DB2 sample) — 92.1% scanned: 44 COBOL
-programs, 29 JCL jobs. The cumulative-risk hitlist leads with
-`base/src/lgupdb01.cbl` (state flux ~100%, cognitive load 92%), and the
+programs, 29 JCL jobs. The cumulative structural-surface hitlist leads with
+`base/src/lgupdb01.cbl` (mutation surface ~100%, complexity load 92%), and the
 heaviest paragraph in the repo is `UPDATE-POLICY-DB2-INFO` — the `SELECT FOR
 UPDATE` row-locking logic, which is exactly where a maintainer of that program
 would want to look first. The same brief also shows a limitation plainly: on a
@@ -140,7 +140,7 @@ this repo's own always-current self-scan brief is at
 |---|---|
 | Architecture | What is this repository made of? |
 | Structural analysis | Where are the functions, classes, APIs, dependencies and control structures? |
-| Risk exposure | Where are potentially important risk patterns concentrated? |
+| Structural Surface Profile (formerly Risk exposure) | Where is a given structural/content pattern concentrated? |
 | Refactoring | Which files are complex, high-churn or load-bearing? |
 | Supply chain | What dependencies physically exist on disk? |
 | AI context | What architecture and relationships should an agent know? |
@@ -193,8 +193,10 @@ named rather than hidden — `cog_raw` holds 76% of languages in band,
 are documented, not defects.
 The claim also survives expansion: when the corpus planted its first
 security-lens probe — one identical hardcoded secret in every language —
-`risk_secrets_risk` read a **uniform score across all 44 languages the lens
-covers**, and the two exceptions (the engine deliberately skips its security
+`credential_material` (formerly `risk_secrets_risk`; the `risk_*` name remains
+the DB column — see [`docs/vectors.md`](docs/vectors.md)) read a **uniform
+score across all 44 languages the lens covers**, and the two exceptions (the
+engine deliberately skips its security
 lens on data formats) and the formula's measured length dependence were
 ledgered and filed the same day
 ([#2978](https://github.com/squid-protocol/gitgalaxy/issues/2978),
@@ -232,21 +234,65 @@ unedited artifacts.
 
 ------------------------------------------------------------------------
 
-# Risk exposure: what GitGalaxy claims
-
-GitGalaxy produces **risk-exposure measurements**, not vulnerability verdicts.
-
-A high exposure means:
-
-> **This location deserves attention relative to the rest of the repository.**
+# Structural Surface Profile: what GitGalaxy claims (formerly "Risk exposure")
+
+GitGalaxy's 13 per-file vectors were originally named `risk_*` and described as
+**risk-exposure measurements**. The question this section used to leave open —
+"are these signatures empirically associated with meaningful classes of
+software risk?" — has since been tested, not just asked. The
+temporal-crucible validation program (epic
+[#2982](https://github.com/squid-protocol/gitgalaxy/issues/2982), ~3,550
+scanned snapshots, two repositories, three label families, every test
+pre-registered before the data was looked at) ran that experiment to
+exhaustion, and the honest result drove a rename
+([#2991](https://github.com/squid-protocol/gitgalaxy/issues/2991)): the
+vectors are now called the **Structural Surface Profile**. `risk_*` remains
+the DB column / JSON key name for compatibility (see
+[`docs/vectors.md`](docs/vectors.md) for the full name table and the
+deprecation note).
+
+**What the record found, restated honestly:**
+
+- **Per-file standing risk, falsified.** The founding hypothesis — that a
+  file's `risk_*` level, or its change after a fix, tracks defect
+  probability — did not hold. Median structural delta after a security fix
+  was +0.000 (equivalence-confirmed near-zero on a second, independent
+  repository, not just non-significant); summed structural exposure ranked
+  *last* of six features for predicting fix-touched files; a 26-signal
+  multivariate structural vector scored at chance (AUC 0.479) under a
+  temporal split, below a plain line count (0.531). The full ledger is in
+  temporal-crucible's `docs/HYPOTHESES.md` and is linked from
+  [#2982](https://github.com/squid-protocol/gitgalaxy/issues/2982).
+- **What the vectors actually validated for:** describing **activity and
+  content**, not defect probability. The fix-shaped composite reliably
+  tracks a security-fix → ordinary-fix → control → revert gradient; deltas
+  correspond to real code events (guard code added, threading introduced,
+  debt markers diluted). That's the x-ray this document now names
+  accurately — see [`docs/vectors.md`](docs/vectors.md) vector-by-vector.
+- **System-level / history signal, restated as the actual predictive
+  finding.** Two features *did* survive validation: **recidivism** (the file
+  that had the last fix gets the next one — the single most replicated
+  result of the program, p<1e-4 on both repositories) and **change entropy /
+  Hassan HCM**, validated out-of-selection on fresh bug labels (AUC 0.868 vs
+  a line count's 0.830). Both are **history** metrics, not structural
+  content metrics — and both are currently zeroed in every scan
+  (`GITGALAXY_DISABLE_GIT_HISTORY`, tracked in
+  [temporal-crucible#29](https://github.com/squid-protocol/temporal-crucible/issues/29)).
+  This is the seed of a separate, honestly-named **predictive layer** — the
+  `hist_stability`/`hist_churn` vectors are named to mark that status
+  explicitly — gated on shipping history-enabled mode and then clearing
+  [#2987](https://github.com/squid-protocol/gitgalaxy/issues/2987)'s
+  defect-lift promotion contract.
+
+A high Structural Surface Profile reading means:
+
+> **This location has more of a given structural/content pattern present,
+> relative to the rest of the repository.**
 
 It does not mean:
 
-> "This code is definitely vulnerable."
-
-The current system produces normalized exposure categories across the
-repository and rolls information from structural entities through files,
-folders and repository-level views.
+> "This code is more likely to contain a defect" — the per-file version of
+> that claim was tested and did not hold.
 
 The underlying signatures cover patterns involving areas such as:
 
@@ -263,11 +309,10 @@ The underlying signatures cover patterns involving areas such as:
 -   entropy
 -   other structural/security characteristics
 
-The important research question is whether these signatures are **empirically
-associated with meaningful classes of software risk**, rather than merely
-correlated with a score that GitGalaxy itself mathematically constructed.
-
-That distinction drives the next phase.
+See [`docs/vectors.md`](docs/vectors.md) for the per-vector rename table,
+evidence, and appropriate/inappropriate uses, and
+[temporal-crucible](https://github.com/squid-protocol/temporal-crucible)'s
+`docs/HYPOTHESES.md` for the full validation ledger this section summarizes.
 
 ------------------------------------------------------------------------
 
@@ -413,6 +458,8 @@ guide](github-action-readme.md).
 |---|---|
 | [Documentation](https://squid-protocol.github.io/gitgalaxy/) | Architecture, claims and methodology |
 | [The validation program](docs/validation.md) | The full proof narrative: thesis, benchmarks, validity ladder, next experiments |
+| [Vector reference](docs/vectors.md) | The 13 per-file vectors: names, meaning, evidence, and the `risk_*` deprecation note |
+| [Vector formula facts](docs/vector_formulas.md) | Mechanical per-calculator formula audit (inputs, arithmetic, constants) |
 | [Language Crucible](https://github.com/squid-protocol/language-crucible) | Cross-language benchmark and golden corpus |
 | [Keyword Rosetta](https://github.com/squid-protocol/keyword-rosetta) | 46-language planted control corpus and bias reports |
 | [Raw Output](https://github.com/squid-protocol/gitgalaxy-raw-output) | Unedited scans of real repositories |

{gitgalaxy-2.6.0 → gitgalaxy-2.7.0}/README.md

@@ -92,8 +92,8 @@ and test data aggressively, and §5 of the brief itemizes every exclusion by
 extension and reason.
 
 **cics-genapp** (IBM's CICS COBOL/DB2 sample) — 92.1% scanned: 44 COBOL
-programs, 29 JCL jobs. The cumulative-risk hitlist leads with
-`base/src/lgupdb01.cbl` (state flux ~100%, cognitive load 92%), and the
+programs, 29 JCL jobs. The cumulative structural-surface hitlist leads with
+`base/src/lgupdb01.cbl` (mutation surface ~100%, complexity load 92%), and the
 heaviest paragraph in the repo is `UPDATE-POLICY-DB2-INFO` — the `SELECT FOR
 UPDATE` row-locking logic, which is exactly where a maintainer of that program
 would want to look first. The same brief also shows a limitation plainly: on a
@@ -113,7 +113,7 @@ this repo's own always-current self-scan brief is at
 |---|---|
 | Architecture | What is this repository made of? |
 | Structural analysis | Where are the functions, classes, APIs, dependencies and control structures? |
-| Risk exposure | Where are potentially important risk patterns concentrated? |
+| Structural Surface Profile (formerly Risk exposure) | Where is a given structural/content pattern concentrated? |
 | Refactoring | Which files are complex, high-churn or load-bearing? |
 | Supply chain | What dependencies physically exist on disk? |
 | AI context | What architecture and relationships should an agent know? |
@@ -166,8 +166,10 @@ named rather than hidden — `cog_raw` holds 76% of languages in band,
 are documented, not defects.
 The claim also survives expansion: when the corpus planted its first
 security-lens probe — one identical hardcoded secret in every language —
-`risk_secrets_risk` read a **uniform score across all 44 languages the lens
-covers**, and the two exceptions (the engine deliberately skips its security
+`credential_material` (formerly `risk_secrets_risk`; the `risk_*` name remains
+the DB column — see [`docs/vectors.md`](docs/vectors.md)) read a **uniform
+score across all 44 languages the lens covers**, and the two exceptions (the
+engine deliberately skips its security
 lens on data formats) and the formula's measured length dependence were
 ledgered and filed the same day
 ([#2978](https://github.com/squid-protocol/gitgalaxy/issues/2978),
@@ -205,21 +207,65 @@ unedited artifacts.
 
 ------------------------------------------------------------------------
 
-# Risk exposure: what GitGalaxy claims
-
-GitGalaxy produces **risk-exposure measurements**, not vulnerability verdicts.
-
-A high exposure means:
-
-> **This location deserves attention relative to the rest of the repository.**
+# Structural Surface Profile: what GitGalaxy claims (formerly "Risk exposure")
+
+GitGalaxy's 13 per-file vectors were originally named `risk_*` and described as
+**risk-exposure measurements**. The question this section used to leave open —
+"are these signatures empirically associated with meaningful classes of
+software risk?" — has since been tested, not just asked. The
+temporal-crucible validation program (epic
+[#2982](https://github.com/squid-protocol/gitgalaxy/issues/2982), ~3,550
+scanned snapshots, two repositories, three label families, every test
+pre-registered before the data was looked at) ran that experiment to
+exhaustion, and the honest result drove a rename
+([#2991](https://github.com/squid-protocol/gitgalaxy/issues/2991)): the
+vectors are now called the **Structural Surface Profile**. `risk_*` remains
+the DB column / JSON key name for compatibility (see
+[`docs/vectors.md`](docs/vectors.md) for the full name table and the
+deprecation note).
+
+**What the record found, restated honestly:**
+
+- **Per-file standing risk, falsified.** The founding hypothesis — that a
+  file's `risk_*` level, or its change after a fix, tracks defect
+  probability — did not hold. Median structural delta after a security fix
+  was +0.000 (equivalence-confirmed near-zero on a second, independent
+  repository, not just non-significant); summed structural exposure ranked
+  *last* of six features for predicting fix-touched files; a 26-signal
+  multivariate structural vector scored at chance (AUC 0.479) under a
+  temporal split, below a plain line count (0.531). The full ledger is in
+  temporal-crucible's `docs/HYPOTHESES.md` and is linked from
+  [#2982](https://github.com/squid-protocol/gitgalaxy/issues/2982).
+- **What the vectors actually validated for:** describing **activity and
+  content**, not defect probability. The fix-shaped composite reliably
+  tracks a security-fix → ordinary-fix → control → revert gradient; deltas
+  correspond to real code events (guard code added, threading introduced,
+  debt markers diluted). That's the x-ray this document now names
+  accurately — see [`docs/vectors.md`](docs/vectors.md) vector-by-vector.
+- **System-level / history signal, restated as the actual predictive
+  finding.** Two features *did* survive validation: **recidivism** (the file
+  that had the last fix gets the next one — the single most replicated
+  result of the program, p<1e-4 on both repositories) and **change entropy /
+  Hassan HCM**, validated out-of-selection on fresh bug labels (AUC 0.868 vs
+  a line count's 0.830). Both are **history** metrics, not structural
+  content metrics — and both are currently zeroed in every scan
+  (`GITGALAXY_DISABLE_GIT_HISTORY`, tracked in
+  [temporal-crucible#29](https://github.com/squid-protocol/temporal-crucible/issues/29)).
+  This is the seed of a separate, honestly-named **predictive layer** — the
+  `hist_stability`/`hist_churn` vectors are named to mark that status
+  explicitly — gated on shipping history-enabled mode and then clearing
+  [#2987](https://github.com/squid-protocol/gitgalaxy/issues/2987)'s
+  defect-lift promotion contract.
+
+A high Structural Surface Profile reading means:
+
+> **This location has more of a given structural/content pattern present,
+> relative to the rest of the repository.**
 
 It does not mean:
 
-> "This code is definitely vulnerable."
-
-The current system produces normalized exposure categories across the
-repository and rolls information from structural entities through files,
-folders and repository-level views.
+> "This code is more likely to contain a defect" — the per-file version of
+> that claim was tested and did not hold.
 
 The underlying signatures cover patterns involving areas such as:
 
@@ -236,11 +282,10 @@ The underlying signatures cover patterns involving areas such as:
 -   entropy
 -   other structural/security characteristics
 
-The important research question is whether these signatures are **empirically
-associated with meaningful classes of software risk**, rather than merely
-correlated with a score that GitGalaxy itself mathematically constructed.
-
-That distinction drives the next phase.
+See [`docs/vectors.md`](docs/vectors.md) for the per-vector rename table,
+evidence, and appropriate/inappropriate uses, and
+[temporal-crucible](https://github.com/squid-protocol/temporal-crucible)'s
+`docs/HYPOTHESES.md` for the full validation ledger this section summarizes.
 
 ------------------------------------------------------------------------
 
@@ -386,6 +431,8 @@ guide](github-action-readme.md).
 |---|---|
 | [Documentation](https://squid-protocol.github.io/gitgalaxy/) | Architecture, claims and methodology |
 | [The validation program](docs/validation.md) | The full proof narrative: thesis, benchmarks, validity ladder, next experiments |
+| [Vector reference](docs/vectors.md) | The 13 per-file vectors: names, meaning, evidence, and the `risk_*` deprecation note |
+| [Vector formula facts](docs/vector_formulas.md) | Mechanical per-calculator formula audit (inputs, arithmetic, constants) |
 | [Language Crucible](https://github.com/squid-protocol/language-crucible) | Cross-language benchmark and golden corpus |
 | [Keyword Rosetta](https://github.com/squid-protocol/keyword-rosetta) | 46-language planted control corpus and bias reports |
 | [Raw Output](https://github.com/squid-protocol/gitgalaxy-raw-output) | Unedited scans of real repositories |

{gitgalaxy-2.6.0 → gitgalaxy-2.7.0}/gitgalaxy/metrics/README.md

@@ -2,13 +2,13 @@
 
 Welcome to **GitGalaxy Metrics**. If the `core/` directory is the extraction layer (identifying raw structural signals), this directory is the analytical brain. 
 
-It is responsible for consuming raw lexical data, merging it with temporal Git telemetry, and translating it into actionable, multi-dimensional risk vectors. This is where raw data becomes architectural intelligence.
+It is responsible for consuming raw lexical data, merging it with temporal Git telemetry, and translating it into actionable, multi-dimensional Structural Surface Profile vectors (formerly called "risk vectors" — see [`docs/vectors.md`](../../docs/vectors.md) for the rename record and evidence). This is where raw data becomes architectural intelligence.
 
 ## The Why: False-Positive Eradication & Alert Fatigue
 
 Traditional Static Application Security Testing (SAST) tools suffer from a fatal flaw: they flag raw vulnerabilities in a vacuum. A raw execution command inside a deprecated, unimported sandbox script generates the same critical alert as one sitting in your primary routing controller. This lack of context generates massive false-positive fatigue, eventually causing engineering teams to ignore the scanner entirely.
 
-The GitGalaxy Metrics engine is engineered to solve this through **Contextual Synthesis**. It operates on a fundamental rule: **Risk exposures are calculated metrics derived from structural hits; they are not the hits themselves.** The engine applies mathematical dampeners (like testing umbrellas, network isolation, and documentation shields) to raw signals. For example, a high "state flux" signal in a file with 100% test coverage and zero downstream dependents has its ultimate risk exposure mathematically dampened, reflecting true ecosystem reality rather than isolated syntax panic.
+The GitGalaxy Metrics engine is engineered to solve this through **Contextual Synthesis**. It operates on a fundamental rule: **Structural Surface Profile vectors are calculated metrics derived from structural hits; they are not the hits themselves.** The engine applies mathematical dampeners (like testing umbrellas, network isolation, and documentation shields) to raw signals. For example, a high "mutation surface" (formerly "state flux") signal in a file with 100% test coverage and zero downstream dependents has its ultimate surface reading mathematically dampened, reflecting true ecosystem reality rather than isolated syntax panic. These vectors describe activity and content, not defect probability — see [`docs/vectors.md`](../../docs/vectors.md) for the validation record behind that distinction (gitgalaxy#2991, gitgalaxy#2982).
 
 ---
 
@@ -17,7 +17,7 @@ The GitGalaxy Metrics engine is engineered to solve this through **Contextual Sy
 All modules in this directory are engineered to operate strictly in $O(1)$ or $O(N)$ linear time complexity. Because expensive disk I/O and regex parsing have already concluded in the `core/` phase, these mathematical operations execute across tens of thousands of files in milliseconds.
 
 ### 1. `signal_processor.py` (The Mathematical Core)
-The primary heuristic synthesis engine. It translates raw structural hits into an 18-point risk vector evaluating dimensions like Technical Debt, Cognitive Load, and State Flux.
+The primary heuristic synthesis engine. It translates raw structural hits into an 18-point Structural Surface Profile evaluating dimensions like Debt Markers (formerly Technical Debt), Complexity Load (formerly Cognitive Load), and Mutation Surface (formerly State Flux). The underlying `risk_*` DB columns and JSON keys are unchanged; see [`docs/vectors.md`](../../docs/vectors.md).
 * **Dual-Axis Anomaly Detection:** Evaluates threats using both global repository baselines and local language models. It leverages **Architectural Drift (Z-Score)** to mathematically flag files that blend in globally but violate their local ecosystem's structural norms.
 * **Autonomous Execution Vectors & AI Topology:** Analyzes the density of LLM orchestration tools, vector databases, and execution loops to classify the repository's AI footprint. It explicitly flags vulnerabilities where raw **Prompt Injection Surfaces** flow directly into OS-level execution.
 

{gitgalaxy-2.6.0 → gitgalaxy-2.7.0}/gitgalaxy/metrics/signal_processor.py

@@ -64,6 +64,21 @@ class SignalProcessor:
     # The 18-Point Risk Exposure Schema
     RISK_SCHEMA = config.RECORDING_SCHEMAS.get("RISK_SCHEMA", [])
 
+    # gitgalaxy#2991: canonical new-name -> legacy risk_* mapping (display-layer
+    # only; RISK_SCHEMA and every DB column/JSON key above are unchanged). Not
+    # consumed by this module's own output today -- signal_processor computes
+    # the risk_vector, it doesn't render it -- but bound here alongside
+    # RISK_SCHEMA so it travels with the schema wherever this class is
+    # imported from, rather than each renderer re-deriving it independently.
+    VECTOR_NAMES = config.RECORDING_SCHEMAS.get("VECTOR_NAMES", {})
+
+    # gitgalaxy#2994: Tier-1 declarative family map (analysis_lens.py section
+    # 7b), bound here alongside RISK_SCHEMA/SIGNAL_SCHEMA so it travels with
+    # the schema wherever this class is imported from. Not part of
+    # RECORDING_SCHEMAS -- it's a standalone top-level constant, same pattern
+    # as ENGINE_CONSTANTS/APERTURE_CONFIG below.
+    SURFACE_FAMILIES = getattr(config, "SURFACE_FAMILIES", {})
+
     def __init__(
         self,
         aperture_config: Optional[dict[str, Any]] = None,
@@ -865,6 +880,42 @@ class SignalProcessor:
             if mp_map:
                 telemetry_payload["multipliers"] = mp_map
 
+            # ==================================================================
+            # TIER 1/3 -- SURFACE FAMILIES & RELATIONS (gitgalaxy#2994)
+            # ==================================================================
+            # Summed from raw_signals, NOT the mitigation-suppressed
+            # exposure_vector assembled above (:784-788 in this method) -- these
+            # are "raw truth by construction": a file whose legacy
+            # risk_safety_score got zeroed by an inline `galaxyscope:ignore`
+            # can still show a nonzero `guards` family total. See
+            # analysis_lens.SURFACE_FAMILIES / SURFACE_FAMILY_EXEMPT and the
+            # suppression-interplay test in test_signal_processor.py.
+            #
+            # Additive only: risk_vector/hit_vector/file_impact above are
+            # unchanged, and this key is new -- it does not touch the
+            # golden-mastered audit_recorder output (that reads risk_vector/
+            # hit_vector/file_impact, not telemetry["surface_families"]).
+            surface_families = {
+                family: sum(raw_signals.get(member, 0) for member in members)
+                for family, members in self.SURFACE_FAMILIES.items()
+            }
+            guards_total = surface_families.get("guards", 0)
+            danger_total = surface_families.get("danger", 0)
+            memory_total = surface_families.get("memory", 0)
+            cleanup_total = surface_families.get("cleanup", 0)
+            surface_relations = {
+                # Mechanism story: defensive constructs per unit of danger
+                # surface, +1 in the denominator so a danger-free file (the
+                # common case) doesn't divide by zero or spike to infinity.
+                "guard_balance_ratio": round(guards_total / (danger_total + 1), 4),
+                # Mechanism story: cleanup (free/close/dispose) per unit of
+                # manual allocation surface -- the X-H1 feature from the
+                # temporal-crucible validation record.
+                "alloc_cleanup_pairing": round(cleanup_total / (memory_total + 1), 4),
+            }
+            telemetry_payload["surface_families"] = surface_families
+            telemetry_payload["surface_relations"] = surface_relations
+
             return {
                 "risk_vector": risk_vector_ordered,
                 "hit_vector": hit_vector,
@@ -896,6 +947,16 @@ class SignalProcessor:
         # Execute Pass 2: Temporal Normalization across the Universe
         self._normalize_temporal_metrics(parsed_files)
 
+        # gitgalaxy#2994 Tier 2: snapshot percentiles MUST run AFTER temporal
+        # normalization above -- `_normalize_temporal_metrics` rewrites
+        # `risk_vector[churn_idx]` in place (:1275 in that method), and the
+        # percentile pass ranks the legacy-vector series off `risk_vector`
+        # directly. Reordering this ahead of normalization would rank every
+        # file's churn against its pre-normalization (raw, unnormalized)
+        # value instead -- see the churn-ordering regression test in
+        # test_signal_processor.py.
+        self._compute_snapshot_percentiles(parsed_files)
+
         total_files = len(parsed_files) + len(unparsable_files)
         if total_files == 0:
             return {}
@@ -1266,6 +1327,101 @@ class SignalProcessor:
             if "risk_vector" in file_data and len(file_data["risk_vector"]) > idx:
                 file_data["risk_vector"][idx] = round(final_churn, 2)
 
+    def _compute_snapshot_percentiles(self, parsed_files: list[dict[str, Any]]) -> None:
+        """[TIER 2, gitgalaxy#2994] Snapshot percentiles -- the honest 0-100.
+
+        Ranks each file's 22 Tier-1 surface-family sums (telemetry
+        ["surface_families"], written by calculate_risk_vector) and its 13
+        RISK_SCHEMA legacy-vector values (risk_vector, POST-churn-
+        normalization -- see the call site in summarize_galaxy_metrics, which
+        invokes this method IMMEDIATELY AFTER _normalize_temporal_metrics so
+        churn is already rewritten before ranking) against every other file
+        in THIS scan/snapshot. "Percentile 87" means literally "87th
+        percentile of this surface in this repo" -- true by construction,
+        unlike the legacy sigmoid scores this tier supersedes for display.
+        Legacy risk_vector values themselves are read-only here, never
+        modified.
+
+        Hazen plotting-position formula: pct = (avg_rank - 0.5) / N * 100,
+        rounded to 2dp. Ties share the MEAN of the ranks they would occupy
+        (standard "average rank" tie-breaking), so two files with identical
+        values get identical percentiles.
+
+        An all-zero series (every file measures 0 on that surface) reads as
+        0.0 for EVERY file -- not the 50.0 an average-rank computation would
+        otherwise give a tied field of zeroes. Naively ranking would
+        misrepresent "nobody has this signal in this repo" as "the median
+        file has it," which is exactly backwards for an absent surface.
+
+        A single-file snapshot (N=1) reads 50.0 for a series it actually
+        has (nothing to rank against => true middle), but 0.0 for a series
+        it measures zero on -- the all-zero rule takes precedence at every N.
+
+        Writes `telemetry["surface_percentiles"] = {"fam": {...}, "vec":
+        {...}}` on every parsed file, in place -- mirroring
+        `_normalize_temporal_metrics`'s own in-place style. The return value
+        of `summarize_galaxy_metrics` (the golden-mastered audit JSON) is
+        untouched; this only ever writes per-file telemetry.
+        """
+        n = len(parsed_files)
+        if n == 0:
+            return
+
+        fam_names = list(self.SURFACE_FAMILIES.keys())
+        vec_names = list(self.RISK_SCHEMA)
+
+        def _percentiles_for(values: list[float]) -> list[float]:
+            count = len(values)
+            if count == 0:
+                return []
+            if all(v == 0 for v in values):
+                # Absent signal must not read as median 50 (see docstring).
+                # This check deliberately PRECEDES the N=1 case: a
+                # single-file snapshot with zero of a surface still has
+                # NONE of it -- 0.0, never 50.0.
+                return [0.0] * count
+            if count == 1:
+                # One file, nonzero value: nothing to rank against --
+                # "true middle" is the only honest value.
+                return [50.0]
+
+            # Average-rank (Hazen) ranking: sort ascending, then give every
+            # value in a tied run the MEAN of the 1-based ranks it spans.
+            order = sorted(range(count), key=lambda i: values[i])
+            ranks = [0.0] * count
+            i = 0
+            while i < count:
+                j = i
+                while j + 1 < count and values[order[j + 1]] == values[order[i]]:
+                    j += 1
+                avg_rank = (i + 1 + j + 1) / 2.0  # 1-based rank span [i+1, j+1]
+                for k in range(i, j + 1):
+                    ranks[order[k]] = avg_rank
+                i = j + 1
+
+            return [round((r - 0.5) / count * 100.0, 2) for r in ranks]
+
+        fam_percentiles: dict[str, list[float]] = {}
+        for fam in fam_names:
+            values = [float(f.get("telemetry", {}).get("surface_families", {}).get(fam, 0)) for f in parsed_files]
+            fam_percentiles[fam] = _percentiles_for(values)
+
+        vec_percentiles: dict[str, list[float]] = {}
+        for slug in vec_names:
+            idx = self.RISK_SCHEMA.index(slug)
+            values = [
+                float(f["risk_vector"][idx]) if "risk_vector" in f and len(f["risk_vector"]) > idx else 0.0
+                for f in parsed_files
+            ]
+            vec_percentiles[slug] = _percentiles_for(values)
+
+        for i, file_data in enumerate(parsed_files):
+            telemetry = file_data.setdefault("telemetry", {})
+            telemetry["surface_percentiles"] = {
+                "fam": {fam: fam_percentiles[fam][i] for fam in fam_names},
+                "vec": {slug: vec_percentiles[slug][i] for slug in vec_names},
+            }
+
     # ==========================================================================
     # FORENSIC EQUATIONS (The Structural Models)
     # ==========================================================================

{gitgalaxy-2.6.0 → gitgalaxy-2.7.0}/gitgalaxy/recorders/audit_recorder.py

@@ -53,6 +53,16 @@ class AuditRecorder:
         self.RISK_SCHEMA = schemas.get("RISK_SCHEMA", [])
         # Note: The pipeline calls it SIGNAL_SCHEMA, but the Auditor references it as HIT_SCHEMA
         self.HIT_SCHEMA = schemas.get("SIGNAL_SCHEMA", [])
+        # gitgalaxy#2991: canonical new-name -> legacy risk_* mapping, bound
+        # here for parity with the other 4 definition sites. Deliberately NOT
+        # used to change any EXPOSURE_LABELS/FRIENDLY_MAP-derived string below
+        # -- this recorder's JSON ("Average Risk Exposures", "Vulnerability &
+        # Risk Exposures", ...) is exactly what tests/golden_master_audit.json
+        # and tests/golden_master_zero_dep_audit.json bless byte-for-byte
+        # (see tests/test_golden_crucible.py); changing these label strings
+        # would fail the golden-crucible regression test without a deliberate,
+        # separate golden-master regen this PR does not perform.
+        self.VECTOR_NAMES = schemas.get("VECTOR_NAMES", {})
 
         # PERFORMANCE OPTIMIZATION: Pre-cache all labels to avoid regex overhead on the hot path
         self._label_cache = {}

{gitgalaxy-2.6.0 → gitgalaxy-2.7.0}/gitgalaxy/recorders/gpu_recorder.py

@@ -75,6 +75,14 @@ class GPURecorder:
         self.RISK_SCHEMA = schemas.get("RISK_SCHEMA", [])
         self.HIT_SCHEMA = schemas.get("SIGNAL_SCHEMA", [])
         self.FUNCTION_SCHEMA = schemas.get("SAT_SCHEMA", [])
+        # gitgalaxy#2991: canonical new-name -> legacy risk_* mapping, bound
+        # here for parity with the other 4 definition sites. Deliberately NOT
+        # used to alter "risk_vector_x1000": self.RISK_SCHEMA below -- the
+        # site's WebGPU visualizer (site/js/core/metavisualizer.html) binds
+        # its `slug`/`keys` data lookups positionally against these exact
+        # bare names; only that file's human-readable `label` strings get the
+        # new vocabulary, per #2991's "no functional JS changes" constraint.
+        self.VECTOR_NAMES = schemas.get("VECTOR_NAMES", {})
 
     def record_mission(
         self,