hypertopos 0.7.1__tar.gz → 0.7.2__tar.gz

{hypertopos-0.7.1 → hypertopos-0.7.2}/CHANGELOG.md

@@ -7,6 +7,22 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.7.2] — 2026-05-21
+
+### Added
+- `GDSNavigator.π5_attract_anomaly` / `find_anomalies` accept `rank_by="signed_confidence"` — composes `delta_norm_signed`, the Fisher LDA alignment, and the reliability flags into one confidence-weighted score: `score = delta_norm_signed × |lda_alignment| × (1 − reliability_penalty)` where `reliability_penalty = 0.5 × single_dim_driven + 0.5 × low_confidence_bucket`. Survivors carry `signed_confidence_score`, `lda_alignment`, `reliability_penalty` per polygon. Pattern without `label_aware_calibration` raises `GDSNavigationError` — no silent fallback to `delta_norm` ranking.
+- New per-dim `kind_mismatch` warning class on `sphere_overview.dim_quality_warnings`. Fires when a `kind='gaussian'` dim shows `|direction_component| < 0.05` (LDA assigns near-zero weight) AND `cohens_d_pos_neg >= 0.3` (raw class stats separate) — the dim's variance is captured by another dim's Fisher axis, suggesting kind re-declaration or split. Composes with label-aware calibration; suppressed for dims already flagged `negative_space`. Pattern-level prerequisite: `Pattern.label_aware_calibration` must be non-None.
+- `GDSNavigator.audit_label_alignment(pattern_id, *, top_n=10)` — reports Fisher LDA direction's discrimination power as AUROC of `delta_norm_signed` against the binary label column declared in `sphere.yaml`'s `label_audit:` block. Returns `{pattern_id, auroc, n_pos, n_neg, top_dims}` where `top_dims` carries the `top_n` dims sorted by `|direction_component|` desc (most label-discriminating axes first). Returns fallback shape with `auroc: null` and `label_aware_available: False` on patterns built without `label_audit:`.
+- `Chain.to_dict()` carries an additional `edge_potentials: list[float | null]` field — one Euclidean distance `||delta(keys[i]) - delta(keys[i+1])||` per consecutive-pair hop, computed against a caller-supplied anchor pattern delta lookup. `null` on hops with missing polygon, mismatched delta shapes, or non-finite distance (NaN / inf strict-JSON sanitised). Length equals `len(keys) - 1` (empty list for single-entity chains). Surfaces high-distance behavioural jumps inside multi-hop chains for downstream chain investigation primitives.
+- `GDSNavigator.π3_dive_solid` accepts `counterfactual_frozen_population: bool = False` — when `True`, each `SolidSlice` on the returned solid carries an additional `delta_norm_frozen_pop` field reporting the per-slice L2 norm recomputed against the FIRST slice's raw shape as the entity-relative reference epoch (sigma stays at the current pattern's diagonal). Answers "is this entity's apparent normalization a real shift, or just population drift around a stationary entity?" — a stationary entity yields `delta_norm_frozen_pop = 0` across all slices. Default `False` preserves the existing return shape (`delta_norm_frozen_pop = None`).
+- `engine.counterfactual.recompute_delta_norm_against_frozen(shape, mu_frozen, sigma)` — pure-NumPy helper used by the frozen-trajectory path. Sigma-dead dims contribute zero (same convention as the per-edge counterfactual primitives).
+- `SolidSlice.delta_norm_frozen_pop: float | None` — new optional field on the model dataclass populated by the frozen-trajectory path; `None` for the default build path.
+- `docs/refutations.md` — record of tested-and-closed hypotheses: pattern-level σ-estimator swap, per-dim heuristic σ-swap, lazy-chain sampled calibration, Bregman-based `is_anomaly` flag, plus a methodology refutation on cycle-compression. Each entry states the hypothesis, dataset, numeric verdict, root cause, and closure rule.
+- `docs/patent-implementation-map.md` — descriptive map of nine architectural-claim clusters (per-entity geometric position, counterfactual closure, multi-resolution FDR, persistent-homology cycle persistence, declarative compliance, HMP detector composition, chain-coherent investigation, reliability triage, build-time dim quality auditing) to their shipped surfaces. No internal tracker IDs.
+
+### Changed
+- README adds CI test workflow badge linking to the public-mirror Actions run.
+
 ## [0.7.1] — 2026-05-20
 
 ### Added

{hypertopos-0.7.1 → hypertopos-0.7.2}/LICENSE.md

@@ -26,7 +26,7 @@ For purposes of this License:
 - **Internal use** within an organization is not a competitive offering. Your
   organization includes entities under common control.
 
-**Change Date:** 2029-05-20
+**Change Date:** 2029-05-21
 
 **Change License:** Apache License, Version 2.0
 

{hypertopos-0.7.1 → hypertopos-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypertopos
-Version: 0.7.1
+Version: 0.7.2
 Summary: Understand the structure of your data — without training machine learning models
 Project-URL: Homepage, https://github.com/hypertopos/hypertopos-py
 Project-URL: Documentation, https://github.com/hypertopos/hypertopos-py/tree/main/docs

{hypertopos-0.7.1 → hypertopos-0.7.2}/README.md

@@ -2,13 +2,14 @@
 
 > A behavioral feature layer for graph and temporal data — turning behavior into coordinates, trajectories, and explanations.
 
+[![Test](https://github.com/hypertopos/hypertopos-py/actions/workflows/test.yml/badge.svg)](https://github.com/hypertopos/hypertopos-py/actions/workflows/test.yml)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-orange.svg)](LICENSE.md)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19482069.svg)](https://doi.org/10.5281/zenodo.19482069)
 [![PyArrow](https://img.shields.io/badge/format-PyArrow-red.svg)](https://arrow.apache.org/docs/python/)
 [![Lance](https://img.shields.io/badge/storage-Lance-blueviolet.svg)](https://github.com/lance-format/lance)
 [![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
-[![Version](https://img.shields.io/badge/version-0.7.1-%235500FF.svg)](pyproject.toml)
+[![Version](https://img.shields.io/badge/version-0.7.2-%235500FF.svg)](pyproject.toml)
 
 hypertopos is not a database, and not a machine learning model. It is a layer that turns relational data into a coordinate system where every entity gets a position derived from its relationships and the population around it.
 

{hypertopos-0.7.1 → hypertopos-0.7.2}/SECURITY.md

@@ -1,6 +1,6 @@
 # Security
 
-## Current version: 0.7.1
+## Current version: 0.7.2
 
 hypertopos runs locally. No network services, no auth layer, no multi-tenancy.
 

hypertopos-0.7.2/docs/patent-implementation-map.md

@@ -0,0 +1,123 @@
+# Patent implementation map
+
+This document maps the architectural claims behind hypertopos to the shipped implementation surfaces in the current release.
+
+Each cluster names a load-bearing idea, the navigator or MCP surface that ships it, and the method one-line. The point is to make it easy for a reviewer or external auditor to walk from "this is what the project claims to do" to "this is the function that does it and the test that verifies it".
+
+There are no claim numbers (`IC-XX`, `DC-XX.Y`) in this document — those are internal tracker IDs. Each cluster is named by its descriptive function.
+
+---
+
+## Per-entity geometric position derived from a population
+
+**What it is.** Every entity carries a position in a multi-dimensional space whose axes are not raw column values but population-relative statistics — z-scores against the population mean, ratios against population percentiles, signed projections onto label-discriminating axes. The position is computed once at build time and stored as a Lance column.
+
+**Surfaces.** `Pattern.mu_diag`, `Pattern.sigma_diag`, `Pattern.theta_diag` (population-level statistics persisted on every pattern). `Pattern.label_aware_calibration` (per-class moments + Fisher LDA direction, opt-in via `sphere.yaml`'s `label_audit:` block). `delta_norm` and `delta_norm_signed` Lance columns on every geometry table.
+
+**Method.** Welford one-pass for mu / sigma. Quantile sketches for theta. Linear discriminant analysis with diagonal-covariance approximation for label-aware direction. All computations are deterministic and reproducible from the source data plus `sphere.yaml`.
+
+**Tests.** `tests/test_calibration.py`, `tests/test_calibration_label_aware.py`, `tests/test_m1_1_builder_wiring.py`.
+
+---
+
+## Counterfactual closure — what changes if X is removed
+
+**What it is.** For an anomalous entity, ask "would it still be anomalous if this edge, this counterparty, or this dim were removed?" — and answer with a closed-form recomputation of `delta_norm` against the same population statistics, no model retraining.
+
+**Surfaces.** `GDSNavigator.simulate_edge_removal`, `simulate_counterparty_removal`, `select_minimal_joint_edge_removal`, `simulate_dimension_change`. Each surfaces as an MCP tool with the same name.
+
+**Method.** Closed-form exp-family delta recomputation. For each candidate removal, recompute the entity's polygon contribution to `delta_norm` as `mu_diag - new_centroid`, take the ratio against `sigma_diag`, project against `theta_diag` percentile — same calibration, different inputs. Greedy selection for the minimal joint set.
+
+**Tests.** `tests/test_counterfactual_*.py`.
+
+---
+
+## Multi-resolution false-discovery-rate control
+
+**What it is.** Standard Benjamini-Hochberg FDR on a per-entity anomaly score answers one question — "is this entity anomalous?" — but ignores that entities live in nested cells (region × time × kind). Multi-resolution FDR aggregates per-cell p-values up a hierarchy with Tippett min-p and reports `q`-values at every level, surviving the more conservative join.
+
+**Surfaces.** `Pattern.fdr_hierarchy` and `Pattern.fdr_temporal_hierarchy` (declarative schema in `sphere.yaml`). `find_anomalies(fdr_resolution, fdr_temporal_resolution)` MCP tool returns `cell_q_spatial` and `cell_q_temporal` per survivor. `engine.fdr.fdr_multi_resolution` (pure-math primitive).
+
+**Method.** Per-cell Fisher exact 2×2 on an anomaly indicator vs background. BH or Storey correction within each cell. Tippett min-p aggregation up each declared level. Independent per-axis adjustment for spatial vs temporal hierarchies.
+
+**Tests.** `tests/test_fdr_*.py`.
+
+---
+
+## Persistent-homology cycle persistence at the entity level
+
+**What it is.** Treat each entity's k-nearest-neighbour ball in the polygon space as a small point cloud and ask whether that cloud carries persistent topological cycles. An entity with high `h1_max_persistence` sits inside a non-trivial topological structure — a ring, a hub, a cluster boundary — that single-entity z-scores cannot see.
+
+**Surfaces.** `find_topological_anomalies` MCP tool. `engine.topology` module (Vietoris-Rips persistent homology backed by `ripser` when the optional `[topology]` extra is installed). `storage.topology_cache` for memoised per-entity persistence values.
+
+**Method.** Per-entity k-NN ball (k ≈ 50 by default), PCA reduction to 10 dims, Vietoris-Rips H_1 persistence computed with `ripser`. Score = max `h1` death-birth interval. Cached because the computation is expensive; invalidated when calibration epochs bump.
+
+**Tests.** `tests/test_topology_*.py`.
+
+---
+
+## Declarative compliance rules as a first-class build-time predicate language
+
+**What it is.** Compliance officers write rules in YAML using a small declarative AST (`and / or / not` over `==, !=, <, <=, >, >=, in`); the builder evaluates them at build time and materialises a violations sidecar Lance dataset; a runtime MCP tool reads the sidecar with rule-id and severity pushdown. Separate from `delta_norm` anomaly flags — an entity can be one, the other, or both.
+
+**Surfaces.** `Pattern.conformance_rules` (model field). `builder.conformance_mapping.parse_conformance_rules` (YAML loader with column-existence validation). `find_conformance_violations` MCP tool.
+
+**Method.** Vectorised PyArrow expression evaluation. Severity literals `low < medium < high < critical`. Rule-id stamping. Sidecar Lance dataset alongside the geometry table.
+
+**Tests.** `tests/test_conformance_mapping.py`, `tests/test_find_conformance_violations_mcp.py`.
+
+---
+
+## Detector composition via harmonic-mean p-value
+
+**What it is.** Five independent detectors — `delta_norm`, `neighbor_contamination`, `segment_shift`, `trajectory_continuous`, `density_gap` — score each entity. A correct composition treats these as multiple hypothesis tests on the same null and combines them via the Wilson harmonic-mean p-value (HMP), not via score averaging. The combined `hmp` is rank-stable across detector subsets and exact under the null.
+
+**Surfaces.** `combine_anomaly_pvalues`, `classify_detector_consensus`, `composite_risk`, `composite_risk_batch` MCP tools. `engine.composition.harmonic_mean_p` (pure-math primitive). `engine.p_value_calibration` (per-detector score-to-p-value adapters).
+
+**Method.** Per-detector calibrated p-values. Wilson HMP combiner. Null-simulation lookup for the `L`-test threshold at level `alpha`. Per-detector weighting optional.
+
+**Tests.** `tests/test_composition_*.py`, `tests/test_detector_consensus_*.py`.
+
+---
+
+## Chain-coherent investigation primitives
+
+**What it is.** A chain is a multi-hop path through an event graph (`from_account → to_account` over time). Investigating a chain means asking whether the chain itself carries anomaly signal (`investigate_chain`), whether its members move together in regime space (`chain_drift_trajectory`), whether their explanatory witness sets intersect (`chain_witness_intersection`), and whether the chain's typology matches a known pattern (`classify_chain_typology`). The chain becomes a first-class investigation entity, not just a list of vertices.
+
+**Surfaces.** `chain_lines:` YAML block. `extract_chains` build pass. `chain_pattern` derived geometry. `find_chains_with_coherent_anomaly`, `chain_witness_intersection`, `chain_drift_trajectory`, `classify_chain_typology`, `extend_chain`, `investigate_chain`, `generate_sar_rationale` MCP tools.
+
+**Method.** Seeded BFS over the event graph with multi-criteria seed selection (`fan_out`, `cross_bank`, `multi_currency`, `pass_through`). Chain feature extraction at build time (`hop_count`, `is_cyclic`, `time_span_hours`, `amount_decay`, etc.). Same pattern-level calibration applied to chains as to entities, so `delta_norm` carries the same population-relative semantics.
+
+**Tests.** `tests/test_chain_*.py`.
+
+---
+
+## Reliability triage on every flagged polygon
+
+**What it is.** A polygon flagged anomalous can be flagged because one dim dominates the score (an artefact of that dim's calibration, not a real anomaly) or because the bootstrap confidence on `is_anomaly` is fragile (the flag would flip if the population were resampled). Both surfaces are reported as boolean flags alongside the score, so an investigator can corroborate before opening a case.
+
+**Surfaces.** `reliability_flags` field on `find_anomalies`, `explain_anomaly`, `composite_risk`, `combine_anomaly_pvalues`, `investigate_entity`. Shape `{single_dim_driven, dominant_dim, dominant_dim_share, low_confidence_bucket, confidence, flags}`.
+
+**Method.** `single_dim_driven` fires when one dim's attribution share exceeds 70 %. `low_confidence_bucket` fires when bootstrap-resampled `anomaly_confidence` falls below 0.5. Both computed at flag time, no extra MCP roundtrip.
+
+**Tests.** `tests/test_reliability_flags.py`.
+
+---
+
+## Build-time dim quality auditing — silent calibration failure modes surfaced
+
+**What it is.** Five build-time auditors catch the silent failure modes that break z-score / `delta_norm` semantics: dead dims (zero variance), sparse dims (mostly zero), dominant-dim mass (one dim accounts for ≥70 % of tail variance), negative-space dims (gaussian-declared but empirically zero-modal), non-normal dims (gaussian-declared but Shapiro-Wilk / KS `p < 0.01`), and per-pattern heteroscedasticity (Brown-Forsythe Levene `p < 0.01` on the grouping variable).
+
+**Surfaces.** `sphere_overview.dim_quality_warnings[]` block. `engine.diagnostics` and `engine.dim_audit` modules.
+
+**Method.** Build-time statistical tests on the calibrated geometry table. Each auditor returns a structured warning with `dim_label`, `reason`, `advice`, `evidence_value`, `threshold` — enough for a downstream consumer to either raise a calibration ticket or apply the recommended transform.
+
+**Tests.** `tests/test_dim_quality_warnings.py`, `tests/test_diagnostics.py`.
+
+---
+
+## Notes
+
+This document is a living artefact. As new architectural surfaces ship, they are added here. As surfaces are deprecated or refactored, the entries update with the cycle they shipped in.
+
+Internal tracker IDs (`IC-XX`, `DC-XX.Y`, `OPF-XX`, `IDEA-XXX`) are kept out of this document by project rule — they are private bookkeeping and would look like dead hyperlinks to anyone reading from the public mirror. Each cluster is named by what it does, not by which ticket tracks it.

hypertopos-0.7.2/docs/refutations.md

@@ -0,0 +1,71 @@
+# Refutations
+
+This document records hypotheses that were tested, found wrong, and closed. Each entry follows the discipline: state the hypothesis, name the dataset, give the numeric evidence, and link the commit or PR that closed the line of work.
+
+The point is not to celebrate failures. It is to leave a record so the same idea is not re-investigated six months later under a different name, and so a reviewer can see that the project takes negative results seriously.
+
+---
+
+## Pattern-level σ-estimator swap (refuted 0.6.6, PR #435)
+
+**Hypothesis.** Replacing the population standard deviation σ used in `delta_norm` calibration with a robust estimator (MAD, IQR, Qn) would lift downstream anomaly detection by being less sensitive to outlier leak.
+
+**What was tested.** Four σ estimators (`std`, `mad`, `iqr`, `qn`) plugged into `Pattern.sigma_diag` calibration. Evaluation on a money-laundering account-level pattern with binary `is_laundering` labels.
+
+**Verdict.** AUROC and top-K precision differences across the four estimators sat inside the bootstrap noise band (±0.005 on AUROC). MAD and IQR did not deliver any robustness lift on this distribution. The "robust σ" line of work was closed.
+
+**Why it failed.** Account-level features are already log-transformed or rank-normalised upstream of calibration. Outliers no longer drive σ when the input is approximately normal post-transform. The σ-swap intervention had no surface to act on.
+
+**Citation.** PR #435 retrospective + `MEMORY.md` entry `project_population_robust_sigma_refuted`.
+
+---
+
+## Per-dim heuristic σ-estimator swap (refuted 0.6.6, PR #436)
+
+**Hypothesis.** σ-swap might work if applied per-dim rather than population-wide — pick the estimator per column based on a heuristic (skewness, kurtosis, sparsity).
+
+**What was tested.** Per-dim heuristic dispatcher selecting `std` / `mad` / `iqr` based on column statistics. Same evaluation setup as PR #435.
+
+**Verdict.** Same outcome — ΔAUROC < 0.005, inside bootstrap noise. The heuristic dispatcher added complexity without measurable lift.
+
+**Why it failed.** Same root cause as PR #435 — when upstream features are normalised, σ-estimator choice does not materially change the calibration. The dispatcher was solving a problem that did not exist on this data shape.
+
+**Closure rule.** The entire "calibration robustness via σ-estimator swap" theme is closed for the project unless a new dataset surfaces with un-normalised, heavy-tailed inputs where the assumption is testable from scratch. The closure rule is enforced via the session memory `project_population_robust_sigma_refuted` — re-opening requires a different dataset or methodology.
+
+---
+
+## Lazy-chain geometry sampled calibration (refuted 0.5.x, retired 2026-04-19)
+
+**Hypothesis.** Computing chain-pattern calibration on a sampled subset of chains rather than the full population would scale linearly with sphere size and preserve detection quality.
+
+**What was tested.** Sampled-calibration variant against full-calibration baseline on the money-laundering chain pattern. Compared `delta_norm` rankings and downstream chain-level anomaly recall.
+
+**Verdict.** Sampled calibration produced a sub-null `delta_norm` distribution — calibration estimates were biased low because the sampled tail underrepresented the true variance. Bias roughly 24 % on the most affected dims. Chain recall on labelled bad chains dropped materially.
+
+**Why it failed.** Chains are a long-tail distribution by structure. Uniform sampling under-weights long chains, which carry the discriminating signal. A weighted sampler would have helped in theory but the engineering cost outweighed the expected gain.
+
+**Closure.** The lazy-chain-geometry document carries an in-doc retired banner dated 2026-04-19. The work was superseded by treating chains as first-class geometric entities (the `chain_lines:` YAML block and the chain investigation primitives shipped in 0.6.x and 0.7.0).
+
+---
+
+## Bregman-based `is_anomaly` flag (refuted 2026-04-16)
+
+**Hypothesis.** Replacing the Mahalanobis-distance-based anomaly flag with a Bregman-divergence-based flag would lift top-K precision on money-laundering account-level detection by giving exp-family-correct distance semantics for non-gaussian dims (counts, ratios).
+
+**What was tested.** Bregman-flag variant evaluated against Mahalanobis baseline at K ∈ {50, 100, 200, 500}, top-K precision and recall on labelled laundering accounts.
+
+**Verdict.** ΔF1 ≤ +0.005 across all K values — inside bootstrap noise. The Bregman variant did not deliver measurable lift on this data shape.
+
+**Why it failed.** The dimension-kind tags in production are mostly `gaussian` or `mahalanobis` with a few `bernoulli` flags. Bregman's correctness advantage only matters when a substantial fraction of dims are explicitly `poisson` or `bernoulli` and carry top-of-rank load. On the tested pattern, no such dim dominated.
+
+**Closure.** The `is_anomaly` flag stays Mahalanobis-based. Bregman remains a per-dim choice via `dimension_kinds: poisson` / `bernoulli` declarations but is not promoted to the global flag computation. Tracked as a closed direction in session memory.
+
+---
+
+## Process refutation — emergent cycle-compression (0.7.0 retrospective)
+
+This one is not algorithmic. The 0.7.0 cycle landed five PRs in a 24-hour window, four of which had been originally planned as 0.7.1 milestones. The result was a tag that shipped on the planned date but with a release-prep state that drifted across packages.
+
+**Lesson.** Items that emerge during a cycle and feel ready to ship should not skip cycle boundaries unless the truth-in-CHANGELOG cost of leaving them is concrete. The hard cycle-window rule is enforced going forward: feature PRs land outside the seven-day pre-tag window; the release-prep PR is the literal last PR before the tag; emerged-during-execution items defer to the next cycle by default.
+
+**Why this entry exists.** Methodology refutations are as load-bearing as algorithmic ones — they keep the cycle cadence honest. The 0.7.1 cycle deliberately sized smaller to test the rule under real conditions.

{hypertopos-0.7.1 → hypertopos-0.7.2}/hypertopos/__init__.py

@@ -44,4 +44,4 @@ __all__ = [
     "IntrinsicExtrinsicReport",
     "LeadLagReport",
 ]
-__version__ = "0.7.1"
+__version__ = "0.7.2"

{hypertopos-0.7.1 → hypertopos-0.7.2}/hypertopos/engine/chains.py

@@ -10,6 +10,7 @@ Used for: money laundering chain detection, supply chain path analysis.
 from __future__ import annotations
 
 import contextlib
+import math
 from collections import defaultdict
 from dataclasses import dataclass
 from datetime import datetime
@@ -173,7 +174,23 @@ class Chain:
             for i in range(len(self.amounts) - 1)
         )
 
-    def to_dict(self) -> dict:
+    def to_dict(
+        self,
+        *,
+        delta_by_key: dict[str, np.ndarray] | None = None,
+    ) -> dict:
+        """Serialise the chain to a JSON-safe dict.
+
+        ``delta_by_key`` is an optional pre-fetched mapping from entity key
+        to that entity's polygon delta vector against the chain's anchor
+        pattern. When supplied, the output gains an ``edge_potentials``
+        field — one Euclidean distance ``||delta(keys[i]) - delta(keys[i+1])||``
+        per consecutive-pair hop. Element is ``None`` when either endpoint
+        lacks a delta entry, the vectors have mismatched or zero length,
+        or the resulting distance is non-finite (NaN / inf — strict-JSON
+        sanitised). When ``delta_by_key`` is None, ``edge_potentials`` is
+        a list of ``None`` of the appropriate length.
+        """
         amt_std = float(np.std(self.amounts)) if self.amounts else 0.0
         amt_mean = float(np.mean(self.amounts)) if self.amounts else 0.0
         return {
@@ -196,9 +213,51 @@ class Chain:
             "amount_monotone_decreasing": (
                 self.amount_monotone_decreasing()
             ),
+            "edge_potentials": _compute_edge_potentials(
+                self.keys, delta_by_key,
+            ),
         }
 
 
+def _compute_edge_potentials(
+    keys: list[str],
+    delta_by_key: dict[str, np.ndarray] | None,
+) -> list[float | None]:
+    """Euclidean distance ``||delta(keys[i]) - delta(keys[i+1])||`` per hop.
+
+    Length is ``max(0, len(keys) - 1)``. Element is ``None`` when:
+      - ``delta_by_key`` is None (the caller did not pre-fetch deltas);
+      - either endpoint's key is missing from ``delta_by_key``;
+      - the two delta vectors have mismatched or zero length;
+      - the computed distance is not finite (NaN / inf).
+
+    NaN / inf protection keeps the result strict-JSON-safe: any non-finite
+    distance is replaced by ``None`` before serialisation.
+    """
+    n_hops = max(0, len(keys) - 1)
+    if n_hops == 0:
+        return []
+    if delta_by_key is None:
+        return [None] * n_hops
+
+    out: list[float | None] = []
+    for i in range(n_hops):
+        a = delta_by_key.get(keys[i])
+        b = delta_by_key.get(keys[i + 1])
+        if a is None or b is None:
+            out.append(None)
+            continue
+        if a.shape != b.shape or a.size == 0:
+            out.append(None)
+            continue
+        d = float(np.linalg.norm(a - b))
+        if not math.isfinite(d):
+            out.append(None)
+            continue
+        out.append(d)
+    return out
+
+
 def extract_chains(
     from_keys: list[str],
     to_keys: list[str],

{hypertopos-0.7.1 → hypertopos-0.7.2}/hypertopos/engine/counterfactual.py

@@ -26,6 +26,7 @@ __all__ = [
     "compute_per_edge_source_value_pvalues",
     "simulate_joint_edge_removal",
     "select_minimal_joint_removal",
+    "recompute_delta_norm_against_frozen",
 ]
 
 
@@ -823,3 +824,46 @@ def select_minimal_joint_removal(
         "target_reached": target_reached,
         "k_max_reached": k_max_reached,
     }
+
+
+def recompute_delta_norm_against_frozen(
+    *,
+    shape: np.ndarray,
+    mu_frozen: np.ndarray,
+    sigma: np.ndarray,
+) -> float:
+    """L2 norm of ``shape`` normalised against a frozen reference ``mu_frozen``.
+
+    Frozen-population trajectory primitive used by
+    ``GDSEngine.build_solid(counterfactual_frozen_population=True)``: for each
+    solid slice, recompute ``delta_norm`` using the FIRST slice's raw shape
+    (``mu_frozen``) as the population reference and the current pattern's
+    diagonal sigma as the scale. Sigma-dead dims (``sigma < 1e-10``) contribute
+    zero — same convention as the per-edge counterfactual primitives.
+
+    Args:
+        shape: per-slice raw shape vector, shape (D,).
+        mu_frozen: frozen reference mean (e.g. slice-0's raw shape), shape (D,).
+        sigma: current pattern's diagonal sigma, shape (D,).
+
+    Returns:
+        Float L2 norm. Returns ``0.0`` when ``shape == mu_frozen`` (stationary
+        entity in a drifting population) — the canonical signal that the
+        entity's apparent normalisation came from population drift, not
+        entity movement.
+    """
+    if shape.shape != mu_frozen.shape or shape.shape != sigma.shape:
+        raise ValueError(
+            f"shape / mu_frozen / sigma must have matching length; got "
+            f"{shape.shape} / {mu_frozen.shape} / {sigma.shape}",
+        )
+    shape = shape.astype(np.float64, copy=False)
+    mu_frozen = mu_frozen.astype(np.float64, copy=False)
+    sigma = sigma.astype(np.float64, copy=False)
+    sigma_dead_mask = sigma < _SIGMA_ZERO_FLOOR
+    sigma_safe = np.where(sigma_dead_mask, 1.0, sigma)
+    delta = np.where(sigma_dead_mask, 0.0, (shape - mu_frozen) / sigma_safe)
+    val = float(np.linalg.norm(delta))
+    if not np.isfinite(val):
+        return 0.0
+    return val

{hypertopos-0.7.1 → hypertopos-0.7.2}/hypertopos/engine/geometry.py

@@ -201,6 +201,7 @@ class GDSEngine:
         manifest: Manifest,
         filters: dict[str, str | list[str]] | None = None,
         timestamp: datetime | None = None,
+        counterfactual_frozen_population: bool = False,
     ) -> Solid:
         base = self.build_polygon(primary_key, pattern_id, manifest)
         table = self._storage.read_temporal(
@@ -216,6 +217,11 @@ class GDSEngine:
         pattern = sphere.patterns[pattern_id]
         sigma = np.maximum(pattern.sigma_diag, self.SIGMA_EPSILON)
         slices: list[SolidSlice] = []
+        # When counterfactual_frozen_population is requested, capture each
+        # slice's raw shape_snapshot so the frozen-trajectory recompute can
+        # run after the loop using the chronologically-first slice's shape
+        # as the entity-relative reference.
+        raw_shapes: list[np.ndarray] = []
         for i in range(table.num_rows):
             row = {col: table[col][i].as_py() for col in table.schema.names}
             shape = np.array(row["shape_snapshot"], dtype=np.float32)
@@ -241,11 +247,45 @@ class GDSEngine:
                 changed_line_id=row.get("changed_line_id"),
                 added_edge=None,
             ))
-        slices.sort(key=lambda s: s.timestamp)
+            if counterfactual_frozen_population:
+                raw_shapes.append(shape)
+        # Pair raw_shapes with their slice and sort jointly so the
+        # chronologically-first slice's raw shape becomes the frozen
+        # reference even when temporal rows arrive out of order.
+        if counterfactual_frozen_population and slices:
+            paired = sorted(
+                zip(slices, raw_shapes, strict=True),
+                key=lambda p: p[0].timestamp,
+            )
+            slices = [p[0] for p in paired]
+            raw_shapes = [p[1] for p in paired]
+        else:
+            slices.sort(key=lambda s: s.timestamp)
         if timestamp is not None:
             if timestamp.tzinfo is None:
                 timestamp = timestamp.replace(tzinfo=UTC)
-            slices = [s for s in slices if s.timestamp <= timestamp]
+            if counterfactual_frozen_population:
+                surviving = [
+                    (s, r) for s, r in zip(slices, raw_shapes, strict=True)
+                    if s.timestamp <= timestamp
+                ]
+                slices = [p[0] for p in surviving]
+                raw_shapes = [p[1] for p in surviving]
+            else:
+                slices = [s for s in slices if s.timestamp <= timestamp]
+        if counterfactual_frozen_population and slices:
+            from hypertopos.engine.counterfactual import (
+                recompute_delta_norm_against_frozen,
+            )
+            mu_frozen = raw_shapes[0]
+            _w = mu_frozen.shape[-1]
+            sigma_frozen = sigma[:_w]
+            for slc, raw in zip(slices, raw_shapes, strict=True):
+                slc.delta_norm_frozen_pop = recompute_delta_norm_against_frozen(
+                    shape=raw,
+                    mu_frozen=mu_frozen,
+                    sigma=sigma_frozen,
+                )
         return Solid(primary_key=primary_key, pattern_id=pattern_id,
                      base_polygon=base, slices=slices)
 

{hypertopos-0.7.1 → hypertopos-0.7.2}/hypertopos/model/objects.py

@@ -87,6 +87,13 @@ class SolidSlice:
     changed_property: str | None
     changed_line_id: str | None
     added_edge: Edge | None
+    # Counterfactual frozen-population delta_norm. Populated only when the
+    # owning solid was built with ``counterfactual_frozen_population=True`` —
+    # in that case each slice's value is the L2 norm of the per-slice shape
+    # normalised against the FIRST slice's raw shape (treated as the
+    # entity-relative reference epoch) instead of the current pattern mu.
+    # ``None`` for the default path preserves the existing serialised shape.
+    delta_norm_frozen_pop: float | None = None
 
     def prop_column_states(self, pattern: Pattern) -> dict[str, bool]:
         """Inverse z-score: recover boolean property states from delta_snapshot."""