hypertopos 0.7.0__tar.gz → 0.7.2__tar.gz

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

@@ -7,6 +7,50 @@ 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
+
+- `GDSBuilder` now invokes `engine.calibration_label_aware.calibrate_label_aware` per pattern listed in `sphere.yaml`'s `label_audit:` block when the `--label-aware-calibration` build flag is set. The result is persisted onto `Pattern.label_aware_calibration` (new field, type `dict[str, dict[str, float]] | None`) and `signed_direction_vector` populates the `delta_norm_signed` Lance column. Closes the wiring gap that left `audit_pattern_dims` MCP tool in fallback mode on every sphere prior to this build path.
+- `Pattern.heteroscedasticity_diagnostic` — optional per-pattern dict, keyed by the `group_by_property` column name, persisted at build time when a pattern carries `group_by_property`. Each entry is a Brown-Forsythe (median-centred Levene) test result on `delta_norm` partitioned by the grouping column: `{W_statistic, p_value, k_groups, per_group_variance, per_group_n, skipped_groups_low_n}`. Groups with N < 30 are dropped from the test (low Levene power) and counted in `skipped_groups_low_n`. When all qualifying groups have zero residual variance Levene returns NaN; the diagnostic encodes that as `null` for `W_statistic` / `p_value` so the JSON is well-formed and consumers can treat "computed-but-degenerate" the same way as "fewer than two qualifying groups".
+- `sphere_overview.dim_quality_warnings[]` gains a new pattern-level type `"heteroscedasticity"` — fires when the persisted Levene `p_value < 0.01` on a pattern's grouping variable. The `dim_label` carries the grouping column name (a categorical line property), not a δ-dim — the warning's role is to flag that the global θ / Cohen's d pooled-σ / APS global-percentile assumptions are violated for this pattern. Carries `evidence_value` (p-value) and `threshold` (0.01) so the agent can rank patterns by severity. Advice: keep the per-group θ calibration the pattern already carries, or apply a variance-stabilizing transform (`log1p`) on `delta_norm` before thresholding if per-group θ is undesirable downstream.
+- `engine.diagnostics.levene_test_per_group(values, group_ids)` — pure-math primitive (NumPy + scipy.stats) returning `{W_statistic, p_value, k_groups, per_group_variance, per_group_n, skipped_groups_low_n}`. Uses Brown-Forsythe (median-centred) variant of Levene for robustness on skewed distributions. Independent of any builder state — callable on any `(values, group_ids)` pair.
+- `engine.dim_audit.normality_test_per_dim(values)` — per-dim normality test primitive. Selects Shapiro-Wilk for samples up to 5000 observations and Kolmogorov-Smirnov against a fitted normal for larger samples; returns `{test_name, statistic, p_value, n}`. Strips NaN before testing and returns a `nan` p-value for samples with fewer than three finite values or zero variance, letting callers treat those cases as "insufficient data" without pre-filtering.
+- `Pattern.dim_normality_pvalues` and `CalibrationFit.dim_normality_pvalues` — optional `{dim_name: p_value}` mapping populated at build time by walking the same float columns the `dim_percentiles` cache covers (entity-line columns plus aggregated edge dims). Persisted to `sphere.json` and the calibration history; legacy spheres lacking the field continue to load unchanged.
+- New `non_normal_dim` warning class on `sphere_overview.dim_quality_warnings`. Fires when a dim declared with `kind='gaussian'` has a build-time normality p-value below 0.01 — surfaces dims where the z-score `(x - mu) / sigma` is a poor anomaly scorer because the empirical distribution is heavy-tailed. The warning carries `reason`, `advice` (suggesting `log1p` / `sqrt` / `rank` transform or kind re-declaration), `evidence_value` (the p-value), and `threshold` (0.01). Suppressed for dims already flagged by `negative_space` to avoid double-flagging when the kind itself is the bug. Bernoulli and poisson dims are silently skipped — normality testing does not apply to binary or discrete-count kinds.
+- `Pattern.dim_percentiles` now covers aggregated edge dimensions on anchor patterns. Each `{source_dim}_{aggregate}` label declared via `edge_dim_aggregations` receives the same six-key entry (`min / p25 / p50 / p75 / p99 / max`) that the cache already provided for `event_dimensions` and `prop_columns`. Consumers of the percentile cache — `dim_quality_warnings` in `sphere_overview`, `dominant_dim_mass` / `negative_space` auditors, the percentile-driven scoring path in `find_anomalies` — now see aggregated edge dims uniformly alongside the other dim families.
+- `engine.calibration_label_aware.calibrate_label_aware(deltas, labels, dim_labels=None, regularization=1e-6)` — per-dim label-aware calibration producing `{mu_pos, sigma_pos, mu_neg, sigma_neg, direction}` per dim plus the unit-norm Fisher LDA direction vector across all dims; opt-in calibration path layered on top of standard mu/sigma stats.
+- `hypertopos build --label-aware-calibration` CLI flag — opt-in switch that activates label-aware calibration during build. No-op until the sphere config declares a `label_audit` block selecting patterns; behavior unchanged on unlabeled spheres.
+- `delta_norm_signed` Lance column in the geometry dataset — per-polygon projection of the delta vector onto the label-aware Fisher LDA direction, signed so positive values mean the polygon is pushed toward the positive-labelled centroid and negative values toward the negative. Nullable float32; populated only for patterns whose builder calibration produced a `signed_direction_vector`. Patterns without label-aware calibration emit the column as all-null, preserving the existing unsigned `delta_norm` magnitude untouched.
+- `sphere.yaml` now accepts a top-level `label_audit:` block — `{label_column, label_positive_value, patterns: [...]}` — naming the binary-label column on the entity line, the value treated as the positive class, and the patterns to calibrate. The parser rejects malformed blocks (missing `label_column`, missing `label_positive_value`, missing or empty `patterns`, unknown pattern names). The block is persisted into `sphere.json` and surfaced to consumers via `Sphere.label_audit`.
+- Sphere format minor `3.1` — stamped on `sphere.json` only when the build registers a `label_audit` block; otherwise spheres continue to stamp `3.0`. Readers compare on the major component only, so older 3.x readers transparently load newer 3.x spheres and ignore the new optional field.
+- `Pattern.edge_dim_names: list[str]` — edge-derived dim names persisted on event patterns that declared an `edge_dimensions:` block in `sphere.yaml`. The block is written into `pattern.json` and surfaced via `Pattern.dim_labels` and `Pattern.dim_index(name)` in storage order (after event dims, before prop columns), so every stored delta dim now has a labelled name. `Pattern.delta_dim()` matches the stored mu / sigma / theta width for these patterns; empty list for patterns without `edge_dimensions:`. Rebuild required to surface labels on existing spheres.
+
+### Changed
+- `storage.reader.GDSReader.read_sphere` accepts any sphere with format major 3; pre-3.x and malformed `format_version` strings continue to raise `GDSVersionError` with a rebuild hint.
+- `builder.conformance_mapping.parse_conformance_rules(raw_block, *, pattern_id, available_columns=None)` — YAML loader for the per-pattern `conformance_rules:` block. Accepts the declarative predicate AST (`and`, `or`, `not`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`) and the `severity` literals `low`, `medium`, `high`, `critical`. Validates structural shape (logical compounds require non-empty `terms`, `not` requires exactly one term, `in` requires an iterable `value`), assigns `rule_id` of the form `r0`, `r1`, … when absent, rejects duplicate `rule_id`s, and — when `available_columns` is supplied — fails fast on any leaf `prop` that is not a column on the entity points table. Returns a list of `ConformanceRule` ready to attach to `Pattern.conformance_rules`.
+- `sphere.yaml` patterns now accept a `conformance_rules:` block. The block is a list of entries shaped `{rule_id?, severity, description?, violates_when}` where `violates_when` is the predicate AST mirroring the on-disk JSON shape. The build pipeline parses, validates against the entity-line points table, attaches the rule set to the pattern, and writes the violations sidecar alongside the geometry — every entity matching `violates_when` lands in the sidecar tagged with the rule's `rule_id` and `severity`.
+- `builder.add_pattern(..., conformance_rules=...)` keyword — programmatic equivalent of the YAML block, accepting a list of `ConformanceRule` directly for callers using the builder API without YAML.
+
+### Fixed
+- `anomaly_summary` no longer falls back to synthesized `dim_{i}` labels for the `top_driving_dimensions` block on event patterns that declared `edge_dimensions:`. Every reported dim now resolves to the labelled name persisted on the pattern; the per-cluster `dim_sq_totals` accumulator is sized by `len(pattern.dim_labels)` and the round-trip is consistent with `Pattern.delta_dim()`.
+
 ## [0.7.0] — 2026-05-18
 
 ### Added

{hypertopos-0.7.0 → 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-18
+**Change Date:** 2029-05-21
 
 **Change License:** Apache License, Version 2.0
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypertopos
-Version: 0.7.0
+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
@@ -11,13 +11,17 @@ License: BSL-1.1
 License-File: LICENSE.md
 Requires-Python: >=3.12
 Requires-Dist: numpy>=1.26
+Requires-Dist: packaging>=23.0
+Requires-Dist: pandas>=2.0
 Requires-Dist: pyarrow>=14.0
 Requires-Dist: pylance<7.0,>=6.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.11
 Provides-Extra: dev
 Requires-Dist: igraph>=0.11; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Provides-Extra: graph
@@ -28,3 +32,4 @@ Requires-Dist: tzdata>=2024.1; extra == 'mcp'
 Provides-Extra: topology
 Requires-Dist: persim>=0.3.5; extra == 'topology'
 Requires-Dist: ripser>=0.6.14; extra == 'topology'
+Requires-Dist: scikit-learn>=1.3; extra == 'topology'

{hypertopos-0.7.0 → 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.0-%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.0 → hypertopos-0.7.2}/SECURITY.md

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

{hypertopos-0.7.0 → hypertopos-0.7.2}/docs/api-reference.md

@@ -688,6 +688,7 @@ Key methods: `slice_at(timestamp)` -- binary search for the slice active at a gi
 | `population_size` | `int` | Total entity count at calibration time |
 | `version` | `int` | Pattern version |
 | `prop_columns` | `list[str]` | Boolean property columns tracked as dimensions |
+| `edge_dim_names` | `list[str]` | Edge-derived dim names for event patterns that declared an `edge_dimensions:` block in `sphere.yaml`. Order matches the storage layout (after `event_dimensions`, before `prop_columns`). Empty for patterns without `edge_dimensions:`. |
 | `dimension_weights` | `np.ndarray \| None` | Per-dimension importance weights |
 | `dimension_kinds` | `list[str] \| None` | Per-dimension distribution family: `"gaussian"`, `"poisson"`, or `"bernoulli"`. Populated at build time; `None` on pre-2.3 spheres. |
 

{hypertopos-0.7.0 → hypertopos-0.7.2}/docs/concepts.md

@@ -108,12 +108,13 @@ Override via `kind:` on individual dimension entries in `sphere.yaml`. The resul
 
 ### Dim-quality warnings
 
-`sphere_overview` surfaces a `dim_quality_warnings[]` block per pattern that catches silent build-time failures of z-score / `delta_norm` semantics. Every warning carries `type`, `dim_label`, `reason`, `advice`. `dominant_dim_mass` additionally carries numeric `evidence_value` (the actual share) and `threshold` (the firing cutoff) so the agent can rank patterns by severity. Computed from cached pattern state (`sigma_diag`, `mu`, `dim_percentiles`, `dimension_kinds`) — sub-millisecond, no storage scan. Four auditor types:
+`sphere_overview` surfaces a `dim_quality_warnings[]` block per pattern that catches silent build-time failures of z-score / `delta_norm` semantics. Every warning carries `type`, `dim_label`, `reason`, `advice`. `dominant_dim_mass` and `heteroscedasticity` additionally carry numeric `evidence_value` (the firing metric) and `threshold` (the firing cutoff) so the agent can rank patterns by severity. Computed from cached pattern state (`sigma_diag`, `mu`, `dim_percentiles`, `dimension_kinds`, `heteroscedasticity_diagnostic`) — sub-millisecond, no storage scan. Five auditor types:
 
 - `dead_dim` — per-dim signal. Fires on dims with `sigma_diag[i] < 1e-10`. The z-score `(x − mu) / sigma` is undefined; the dim contributes nothing meaningful and silently dilutes other dims' signal. Advice: drop the dim from the pattern, or investigate the data source for a constant column.
 - `sparse_dim` — per-dim signal. Fires on dims with `dim_percentiles[label].p50 == 0` and `p99 > 0` (mostly-zero with rare nonzero tail). The gaussian z-score assumption is wrong because the empirical distribution is point-mass-at-zero plus a tail. Advice: switch to Bregman with `kind='poisson'` or `kind='bernoulli'`, or split into `is_active` + `value_when_active` dims.
 - `dominant_dim_mass` — pattern-level signal. Computed as the max share of `((p99 − μ_d) / σ_d)²` across all dims with `dim_percentiles` coverage; fires when one dim's share ≥ 0.70 (matches the per-polygon `single_dim_driven` threshold). Means the pattern's `delta_norm` ranking is effectively single-dim; investigator should cross-check the per-polygon `reliability_flags.single_dim_driven` incidence on top-N anomalies. Aggregated edge dims without `dim_percentiles` entries are silently skipped.
 - `negative_space` — per-dim signal. Fires on dims with `dim_percentiles[label].p50 == 0` AND `dimension_kinds[i] == "gaussian"`. The gaussian z-score is wrong for these dims because the empirical distribution is point-mass-at-zero, not centered. Advice: re-declare with `kind='bernoulli'` (presence/absence) or `kind='poisson'` (count), or split into a binary `is_active` dim plus a continuous `value_when_active` dim.
+- `heteroscedasticity` — pattern-level signal, keyed by the pattern's `group_by_property`. Computed at build time from a Brown-Forsythe (median-centred Levene) test on `delta_norm` partitioned by the grouping column; fires when `p < 0.01`. The `dim_label` carries the grouping variable name (the categorical line property), not a δ-dim. Means the global θ assumption is statistically violated for this pattern — per-group θ calibration is statistically warranted. Advice: keep the per-group calibration the pattern already carries, or consider a variance-stabilizing transform (`log1p`) on `delta_norm` before thresholding. Groups with N < 30 are silently dropped from the test (low Levene power) and surfaced in the persisted entry as `skipped_groups_low_n`.
 
 ## Anomaly Confidence
 

{hypertopos-0.7.0 → hypertopos-0.7.2}/docs/configuration.md

@@ -376,6 +376,7 @@ patterns:
 | `edge_table` | dict | `null` | Explicit edge table config (see below). Auto-emitted for event patterns with 2+ FK relations to same anchor line. |
 | `edge_dimensions` | list | `null` | Build-time per-edge dims for event patterns. Each item is either a bare dim name or a single-key dict with overrides. Five dims available: `pair_edge_count`, `position_in_chain` (`min_position` ≥ 3, default 5), `time_since_pair_last_edge`, `pair_amount_zscore` (LOW_VAR pairs only), `find_motif_structuring`. |
 | `edge_dim_aggregations` | dict | `null` | **Anchor patterns only.** Aggregate per-edge sidecar dims of an event pattern up to per-anchor `_mean` / `_max` columns baked into the anchor polygon. `from: <event_pid>` is required and must reference an event pattern that declares `edge_dimensions:`. `dims: [...]` is required — must be a non-empty list of source dim names from the referenced sidecar (the previous "omit `dims` to aggregate everything" shorthand was removed; explicit declaration prevents build-vs-runtime label drift). Anchor regimes: `single` (account-style, anchor PK matches edge `from_key` OR `to_key`) and `pair` (composite-key, anchor PK = `<from>__<to>`); `chain` raises `NotImplementedError`. Builder switches to a two-phase build (events first, anchors second) when this block is present. |
+| `conformance_rules` | list | `null` | Declarative compliance predicates evaluated at build time against the entity-line points table. Each entry has shape `{rule_id?, severity, description?, violates_when}` where `severity` is one of `low` / `medium` / `high` / `critical` and `violates_when` is a predicate AST. `rule_id` is auto-assigned as `r0`, `r1`, ... when omitted; duplicate `rule_id`s are rejected. Predicate ops: `and`, `or`, `not` (logical compounds carry `terms`), `==`, `!=`, `<`, `<=`, `>`, `>=` (carry `prop` + scalar `value`), and `in` (carries `prop` + list `value`). The `prop` field references a raw column on the entity-line points table — unknown columns fail the build immediately. Violators land in a sidecar Lance dataset read by `find_conformance_violations`. |
 | `bootstrap_iterations` | int | `200` | Number of bootstrap resamples used to compute `anomaly_confidence` per entity. Skipped automatically for N > 50K, `group_by_property`, or `use_mahalanobis`. |
 
 ### Edge Table
@@ -444,6 +445,61 @@ patterns:
 
 Dimension prefixes (`g:`, `t:`, `s:`) appear in `explain_anomaly` output, making it clear which block a dimension belongs to.
 
+### Conformance Rules
+
+Patterns optionally accept a `conformance_rules:` block that declares compliance predicates evaluated at build time against the entity-line points table. Violators land in a sidecar Lance dataset surfaced by the `find_conformance_violations` navigator primitive and MCP tool.
+
+```yaml
+patterns:
+  account_pattern:
+    type: anchor
+    entity_line: accounts
+    relations: []
+    conformance_rules:
+      - rule_id: high_amount
+        severity: high
+        description: account average above compliance ceiling
+        violates_when:
+          op: ">"
+          prop: avg_amount             # Column on the entity-line points table.
+          value: 10000
+
+      - rule_id: sanctioned_region
+        severity: critical
+        violates_when:
+          op: in
+          prop: country
+          value: [XX, ZZ]
+
+      - rule_id: high_value_and_sanctioned
+        severity: critical
+        violates_when:
+          op: and
+          terms:
+            - op: ">"
+              prop: avg_amount
+              value: 10000
+            - op: in
+              prop: country
+              value: [XX, ZZ]
+```
+
+Predicate language:
+
+| Op | Shape | Description |
+|----|-------|-------------|
+| `and`, `or` | `{op, terms: [...]}` | Logical compound — non-empty list of child predicates. |
+| `not` | `{op, terms: [child]}` | Logical negation — exactly one child predicate. |
+| `==`, `!=`, `<`, `<=`, `>`, `>=` | `{op, prop, value}` | Comparison on a single column against a scalar literal. |
+| `in` | `{op, prop, value: [...]}` | Membership in a list literal. |
+
+Rules:
+
+- `severity` is one of `low`, `medium`, `high`, `critical`.
+- `rule_id` is optional; when omitted, rules are auto-assigned `r0`, `r1`, ... in YAML order. Duplicate `rule_id`s within a pattern are rejected at parse time.
+- `description` is optional and surfaced in violation responses for audit context.
+- `prop` references a raw column on the entity-line points table — not a dim label. An unknown column fails the build immediately.
+
 ### Multiple patterns on the same entity line
 
 You can define multiple patterns for the same anchor line with different calibration:

{hypertopos-0.7.0 → hypertopos-0.7.2}/docs/data-format.md

@@ -51,11 +51,12 @@ The central config file. Loaded once on `open_sphere` (typically a few KB). Cont
 | Field | Type | Description |
 |-------|------|-------------|
 | `sphere_id` | string | Unique sphere identifier |
-| `format_version` | string | On-disk layout version. Current: `"3.0"` (flat single-dataset geometry with native Lance epoch tags). Reader rejects earlier values and points to a clean rebuild from source. |
+| `format_version` | string | On-disk layout version, written as `"<major>.<minor>"`. Major `3` is required; minor bumps (e.g. `"3.1"`) ride a backward-compatible field addition and load on any major-3 reader. Pre-3.x and malformed values are rejected with a rebuild hint. |
 | `lines` | dict | Line definitions: versions, columns, partition config, descriptions |
 | `patterns` | dict | Pattern stats: `mu`, `sigma_diag`, `theta`, `edge_max`, `dimension_weights`, `group_stats` |
 | `aliases` | dict | Alias definitions: `base_pattern`, cutting plane (`normal` vector, `bias`) |
 | `storage` | dict | Storage config per layer (format, partition mode) |
+| `label_audit` | dict, optional | Top-level label-aware calibration metadata — `{label_column, label_positive_value, patterns: [...]}`. Present only when the build registered a YAML `label_audit:` block; absent on spheres built without one. When present, `format_version` is stamped `"3.1"`. |
 
 Example (abridged pattern entry):
 

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.0 → hypertopos-0.7.2}/hypertopos/__init__.py

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