hypertopos 0.2.1__tar.gz → 0.2.2__tar.gz

{hypertopos-0.2.1 → hypertopos-0.2.2}/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to hypertopos will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] — 2026-04-11
+
+### Added
+
+**Temporal as-of reconstruction across edge-table graph primitives**
+- `contagion_score()`, `contagion_score_batch()` — optional keyword-only `timestamp_cutoff: float | None` parameter. When set, only edges with `timestamp <= timestamp_cutoff` are considered. Batch forwards the cutoff to every per-entity call.
+- `entity_flow()` — same `timestamp_cutoff` parameter; both outgoing and incoming edge reads honor the cutoff, so net flow reflects the as-of graph state.
+- `degree_velocity()` — same parameter; buckets derive from the filtered edge set so the last bucket endpoint is naturally `<= timestamp_cutoff`.
+- `propagate_influence()` — same parameter; threaded through the BFS `_expand_neighbors` closure so expansion follows only edges with `timestamp <= cutoff`.
+- `find_counterparties()` — same parameter on the edge-table fast path via `_find_counterparties_via_edges`. The points-scan fallback has no timestamp column and **raises `GDSNavigationError`** when `timestamp_cutoff` is supplied — fail loudly instead of silently returning unfiltered results.
+
+The semantic mirrors the existing `WitnessCohortConfig.timestamp_cutoff` from 0.2.1: edges with `timestamp <= timestamp_cutoff` are included. Enables agents to reconstruct contagion, flow, connection velocity, and influence propagation state at a prior point in time — useful for incident forensics ("what did this neighborhood look like on the day the alert fired?"), retroactive detection validation, and historical-snapshot comparisons.
+
+### Fixed
+
+- `detect_cross_pattern_discrepancy` no longer triggers full edge-table scans through `PassiveScanner.auto_discover`. The scanner gains an `include_graph: bool = True` keyword-only parameter; `detect_cross_pattern_discrepancy` calls it with `include_graph=False` because graph contagion plays no role in the downstream geometry-disagreement check. Eliminates the dominant latency regression on multi-pattern spheres with edge tables — the discrepancy detector previously paid one full edge-table read per event pattern with no signal benefit. Every other `auto_discover` caller (`composite_risk`, explicit scanner use) stays at the graph-enabled default.
+
 ## [0.2.1] — 2026-04-11
 
 ### Added
@@ -15,17 +32,11 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Excludes already-connected entities via BTREE edge lookup; bidirectional check by default; `timestamp_cutoff` for as-of evaluation in temporal hold-out
 - Auto-resolves the event pattern with edge table covering an anchor's entity line; explicit `edge_pattern_id` override is validated
 - Trajectory branch decided once per call (not per candidate) — when ref has trajectory, missing candidates get neutral 0.5 instead of mixed renormalization
-- Batch trajectory load via single Lance scan instead of per-candidate (~11× speedup: 3.7s → ~330ms on AML HI-small)
+- Batch trajectory load via single Lance scan instead of per-candidate (~11× speedup over the per-candidate path)
 - `WitnessCohortConfig` and `WitnessCohortWeights` dataclasses group all tunable parameters; navigator API takes a single `config=` keyword
 - `CohortMember` and `WitnessCohortResult` frozen dataclasses with per-component scores, exclusion counts, and reproducibility metadata
 - `GDSEngine.witness_jaccard()`, `GDSEngine.trajectory_cosine()`, `GDSEngine.composite_link_score()` — pure scoring helpers exposed for reuse
 
-**Empirical validation on AML HI-small** (5M edges, 6357 labeled launderers):
-- Co-laundering precision@10: **25.3%** (vs 1.2% base rate = **20.5× lift**)
-- 2.6× improvement over `find_similar_entities + is_anomaly` baseline (which scored 6.5%)
-- Top-10 overlap with that baseline: 15.5% (function returns substantively different entities, not the same ranking)
-- Temporal hold-out recall@10: **0.0%** — confirms the function does NOT forecast future edges; it surfaces existing geometric peers
-
 ## [0.2.0] — 2026-04-10
 
 ### Added

{hypertopos-0.2.1 → hypertopos-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypertopos
-Version: 0.2.1
+Version: 0.2.2
 Summary: Navigate your data like space.
 Project-URL: Homepage, https://github.com/hypertopos/hypertopos-py
 Project-URL: Documentation, https://github.com/hypertopos/hypertopos-py/tree/main/docs

{hypertopos-0.2.1 → hypertopos-0.2.2}/README.md

@@ -8,7 +8,7 @@
 [![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/lancedb/lancedb)
 [![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
-[![Version](https://img.shields.io/badge/version-0.2.1-blue.svg)](pyproject.toml)
+[![Version](https://img.shields.io/badge/version-0.2.2-blue.svg)](pyproject.toml)
 
 **hypertopos** transforms relational data into navigable geometric space.
 
@@ -38,7 +38,7 @@ Navigation primitives turn this space into a stateful, step-by-step workspace, w
 
 - **Geometry, not queries** — entities live in a population-calibrated coordinate space (μ, σ, θ). Position tells you what's typical. Distance reveals what's unusual, what's similar, and where clusters form.
 - **Navigate, don't search** — twelve primitives (π1–π12) let agents walk lines, jump across relationships, cluster populations, compare groups, find hubs, and track drift. Stateful, composable, geometric.
-- **Graph meets geometry** — edge tables give runtime graph traversal with geometric path scoring. Find paths scored by witness overlap and anomaly propagation — not just hop count. Lazy chain discovery without build-time extraction. Surface witness cohorts (`find_witness_cohort`) — entities sharing the target's anomaly signature, ranked by delta similarity, witness overlap, trajectory alignment, and graded anomaly bonus, with already-connected entities filtered out. Investigative peer ranking validated on AML HI-small at **20.5× lift** over random base rate for co-laundering precision@10.
+- **Graph meets geometry** — edge tables give runtime graph traversal with geometric path scoring. Find paths scored by witness overlap and anomaly propagation — not just hop count. Lazy chain discovery without build-time extraction. Surface witness cohorts (`find_witness_cohort`) — entities sharing the target's anomaly signature, ranked by delta similarity, witness overlap, trajectory alignment, and graded anomaly bonus, with already-connected entities filtered out. Investigative peer ranking, not edge forecasting.
 - **Time is built in** — polygons accumulate into solids. Trajectory similarity, regime change detection, and drift analysis are first-class — not bolted on.
 - **Agents first** — designed for MCP tool-calling. Smart detection recipes, investigation workflows. The sphere is the agent's workspace.
 - **Zero training** — no ML models, no labels, no training pipeline. Population statistics and empirical thresholds. Deploy in minutes.
@@ -56,7 +56,7 @@ Navigation primitives turn this space into a stateful, step-by-step workspace, w
 | **Navigation** | 12 stateful primitives | Query-based | KNN search | N/A |
 | **Multi-hop** | Edge table (runtime graph + lazy chains) + pre-computed chain geometry | Native (Cypher, ad-hoc) | No | No |
 | **Anomaly propagation** | Contagion scoring + influence BFS in delta-space | No | No | Local neighborhood only |
-| **Witness cohort discovery** | Witness overlap + delta + trajectory + edge absence (validated 20.5× lift on AML) | Topological only (Adamic-Adar, common neighbors) | KNN, no graph awareness | Learned embeddings (training required) |
+| **Witness cohort discovery** | Witness overlap + delta + trajectory + edge absence | Topological only (Adamic-Adar, common neighbors) | KNN, no graph awareness | Learned embeddings (training required) |
 | **Agent-native (MCP)** | Yes | No | No | No |
 | **Explains why** | Witness sets, dimension ranking | Centrality scores | Nearest neighbors | Anomaly scores |
 

{hypertopos-0.2.1 → hypertopos-0.2.2}/ROADMAP.md

@@ -2,15 +2,27 @@
 
 > Planned direction. Priorities may change based on feedback. 
 
-## Current: 0.2.0
+## Current: 0.2.2
 
-**Graph meets geometry.** Lance-based **edge table** per event pattern with BTREE indexes, auto-emitted at build time, gives runtime graph traversal at O(log n) scale. 11 new navigator functions (paths, chains, flow, contagion, influence, bridges, anomalous edges, …) and matching MCP tools available in Phase 2. PassiveScanner gains a `"graph"` contagion source. 7 fraud-investigation recipes added to `gds-fraud-investigator`, all 8 skills refreshed for the new tools. Major perf wins (`passive_scan` 84 s → <10 s, `detect_pattern` 86 s → <15 s, `cluster_bridges` 31 s → <5 s). 66 MCP tools total (55 → 66).
+As-of graph reconstruction across edge-table graph primitives + latency fix on `detect_cross_pattern_discrepancy`. See CHANGELOG.
+
+---
+
+## 0.2.1
+
+Witness cohort discovery — investigative peer ranking. See CHANGELOG.
+
+---
+
+## 0.2.0
+
+Graph meets geometry — edge table, runtime traversal, contagion/influence, +11 navigator functions. See CHANGELOG.
 
 ---
 
 ## 0.1.0
 
-**First public release.** Complete GDS stack: declarative YAML sphere builder with CLI, navigation primitives π1–π12 (walk/jump/dive/attract/drift/trajectory/regime), aliases with cutting planes, temporal solids, investigation tools (`explain_anomaly`, witness/anti-witness, reputation), forecasting, FTS + hybrid search, online calibration tracker, MVCC sessions, multi-source PassiveScanner, incremental builder updates, MCP server (55 tools, smart detection, 3-phase visibility), Lance/Arrow storage, validation suite (Berka, NYC Taxi, IBM AML), full docs.
+First public release — full GDS stack, π1–π12, builder, MCP server, validation suite. See CHANGELOG.
 
 ---
 

{hypertopos-0.2.1 → hypertopos-0.2.2}/SECURITY.md

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

{hypertopos-0.2.1 → hypertopos-0.2.2}/docs/api-reference.md

@@ -124,15 +124,15 @@ with sphere.session("agent-1") as session:
 |--------|-------------|
 | `find_geometric_path(from_key, to_key, pattern_id, max_depth=5, beam_width=10, scoring="geometric")` | Beam search for paths between two entities via the edge table, scored by geometric coherence. Scoring modes: `"geometric"` (witness overlap + delta alignment + anomaly preservation), `"amount"` (geometric score modulated by log(transaction amount)), `"anomaly"` (prefer paths through anomalous entities), `"shortest"` (plain BFS, no geometric scoring). Returns best paths with per-hop scores |
 | `discover_chains(primary_key, pattern_id, time_window_hours=168, max_hops=10, min_hops=2, max_chains=100, direction="forward")` | Runtime temporal BFS on the edge table to discover entity chains from a starting point. Unlike `find_chains_for_entity()` which queries pre-computed chains, this performs live traversal -- works without build-time chain extraction |
-| `entity_flow(primary_key, pattern_id, top_n=20)` | Net flow analysis per counterparty via edge table. Two edge lookups (outgoing + incoming), sum amounts, compute per-counterparty net flow. Returns outgoing/incoming totals, net_flow, flow_direction, counterparties sorted by abs(net_flow) |
-| `contagion_score(primary_key, pattern_id)` | Score how many of an entity's counterparties are anomalous via edge table + geometry check. Returns score (0.0–1.0), total/anomalous counterparty counts |
-| `contagion_score_batch(primary_keys, pattern_id, max_keys=200)` | Batch contagion scoring for multiple entities. Returns per-entity scores plus summary (mean, max, high_contagion_count) |
-| `degree_velocity(primary_key, pattern_id, n_buckets=4)` | Temporal connection velocity — buckets edges by timestamp, counts unique counterparties per bucket. Velocity = last_bucket_degree / first_bucket_degree. Returns buckets with out/in degree, velocity metrics |
+| `entity_flow(primary_key, pattern_id, top_n=20, *, timestamp_cutoff=None)` | Net flow analysis per counterparty via edge table. Two edge lookups (outgoing + incoming), sum amounts, compute per-counterparty net flow. `timestamp_cutoff` (Unix seconds) restricts to edges with `timestamp <= cutoff`. Returns outgoing/incoming totals, net_flow, flow_direction, counterparties sorted by abs(net_flow) |
+| `contagion_score(primary_key, pattern_id, *, timestamp_cutoff=None)` | Score how many of an entity's counterparties are anomalous via edge table + geometry check. `timestamp_cutoff` enables as-of contagion reconstruction. Returns score (0.0–1.0), total/anomalous counterparty counts |
+| `contagion_score_batch(primary_keys, pattern_id, max_keys=200, *, timestamp_cutoff=None)` | Batch contagion scoring for multiple entities — forwards `timestamp_cutoff` to each per-entity call. Returns per-entity scores plus summary (mean, max, high_contagion_count) |
+| `degree_velocity(primary_key, pattern_id, n_buckets=4, *, timestamp_cutoff=None)` | Temporal connection velocity — buckets edges by timestamp, counts unique counterparties per bucket. Velocity = last_bucket_degree / first_bucket_degree. `timestamp_cutoff` clamps the last bucket endpoint by filtering edges at the read level. Returns buckets with out/in degree, velocity metrics |
 | `investigation_coverage(primary_key, pattern_id, explored_keys)` | Agent guidance: how much of an entity's edge neighborhood has been explored. Splits counterparties into explored/unexplored, batch anomaly check on unexplored |
-| `propagate_influence(seed_keys, pattern_id, max_depth=3, decay=0.7, min_threshold=0.001, max_affected=10_000)` | BFS influence propagation from seed entities with geometric decay and tx_count weighting. At each hop: influence = parent_score * decay * geometric_coherence * tx_weight. Returns affected_entities with tx_count per neighbor |
+| `propagate_influence(seed_keys, pattern_id, max_depth=3, decay=0.7, min_threshold=0.001, max_affected=10_000, *, timestamp_cutoff=None)` | BFS influence propagation from seed entities with geometric decay and tx_count weighting. At each hop: influence = parent_score * decay * geometric_coherence * tx_weight. `timestamp_cutoff` restricts BFS expansion to edges with `timestamp <= cutoff`. Returns affected_entities with tx_count per neighbor |
 | `cluster_bridges(pattern_id, n_clusters=5, top_n_bridges=10)` | Find entities bridging geometric clusters via edge table. Runs π8 clustering then identifies cross-cluster edges and bridge entities |
 | `anomalous_edges(from_key, to_key, pattern_id, top_n=10)` | Find edges between two entities enriched with event-level geometry (delta_norm, is_anomaly). Unlike path tools which score entities (anchor), this scores individual transactions (event geometry) |
-| `find_witness_cohort(primary_key, pattern_id, top_n=10, *, config=None, edge_pattern_id=None)` | Rank entities that share the target's witness signature. Investigative peer ranking — NOT edge forecasting. Combines four signals: `exp(-distance/theta)` delta similarity, witness Jaccard overlap, trajectory cosine alignment (optional), and graded anomaly bonus from `delta_rank_pct`. Excludes entities already connected via BTREE edge lookup — this is the function's main contribution over plain ANN. Configure via `WitnessCohortConfig(weights=WitnessCohortWeights(...), candidate_pool, min_witness_overlap, min_score, use_trajectory, bidirectional_check, timestamp_cutoff)`. Returns `WitnessCohortResult` with ranked `CohortMember` items, per-component scores, exclusion counts, and reproducibility metadata. Validated on AML HI-small: 20.5× lift over random for co-laundering precision@10 (25.3% vs 1.2%), 2.6× over `find_similar_entities + is_anomaly` baseline (6.5%), 15.5% top-10 overlap with that baseline |
+| `find_witness_cohort(primary_key, pattern_id, top_n=10, *, config=None, edge_pattern_id=None)` | Rank entities that share the target's witness signature. Investigative peer ranking — NOT edge forecasting. Combines four signals: `exp(-distance/theta)` delta similarity, witness Jaccard overlap, trajectory cosine alignment (optional), and graded anomaly bonus from `delta_rank_pct`. Excludes entities already connected via BTREE edge lookup — this is the function's main contribution over plain ANN. Configure via `WitnessCohortConfig(weights=WitnessCohortWeights(...), candidate_pool, min_witness_overlap, min_score, use_trajectory, bidirectional_check, timestamp_cutoff)`. Returns `WitnessCohortResult` with ranked `CohortMember` items, per-component scores, exclusion counts, and reproducibility metadata |
 
 ### Analysis and Detection
 
@@ -149,7 +149,7 @@ with sphere.session("agent-1") as session:
 | `cross_pattern_profile(primary_key, line_id)` | Anomaly status from all patterns the entity participates in |
 | `find_chains_for_entity(primary_key, pattern_id, top_n)` | Find chains involving a specific entity |
 | `find_neighborhood(primary_key, pattern_id, max_hops)` | BFS through polygon edges to find reachable entities |
-| `find_counterparties(primary_key, line_id, from_col, to_col, pattern_id, top_n, use_edge_table=True)` | Discover counterparty entities from event data. When pattern_id is given and edge table exists, uses BTREE fast path with amount_sum/amount_max per counterparty |
+| `find_counterparties(primary_key, line_id, from_col, to_col, pattern_id, top_n, use_edge_table=True, *, timestamp_cutoff=None)` | Discover counterparty entities from event data. When pattern_id is given and edge table exists, uses BTREE fast path with amount_sum/amount_max per counterparty. `timestamp_cutoff` applies to the edge-table fast path only; raises `GDSNavigationError` when supplied without an edge-table-eligible configuration |
 | `assess_false_positive(primary_key, pattern_id)` | Evaluate likelihood of false positive anomaly classification |
 
 **Detection recipes (population-level patterns):**
@@ -422,7 +422,7 @@ Or use the navigator shortcut: `nav.passive_scan(home_line_id)`.
 | `add_points_source(name, line_id, rules, combine)` | Register a points-rule source filtering by column thresholds |
 | `add_compound_source(name, geometry_pattern_id, line_id, rules)` | Geometry expansion intersected with points rules |
 | `add_graph_source(name, pattern_id, contagion_threshold=0.3, weight)` | Register a graph contagion source — flags entities whose anomalous counterparty ratio exceeds threshold. Requires event pattern with edge table |
-| `auto_discover(home_line_id, include_borderline)` | Auto-register all patterns related to a line. Also auto-detects graph sources for event patterns with edge tables |
+| `auto_discover(home_line_id, include_borderline, *, include_graph=True)` | Auto-register all patterns related to a line. Also auto-detects graph sources for event patterns with edge tables. Pass `include_graph=False` to skip graph source registration when the downstream scan does not need contagion signal — `detect_cross_pattern_discrepancy` uses this to avoid ~37s-per-event-pattern edge-table reads |
 | `scan(home_line_id, scoring, threshold, top_n)` | Execute batch scan across all registered sources. Returns `ScanResult` |
 
 ### ScanResult

{hypertopos-0.2.1 → hypertopos-0.2.2}/docs/architecture.md

@@ -224,6 +224,10 @@ The scanner collects, deduplicates, and ranks results into a unified candidate l
 is the primary entry point for broad screening workflows where the agent does not yet know
 which specific primitive to focus on. `auto_discover()` registers the appropriate sources
 automatically — graph sources are added for every event pattern that has an edge table.
+Callers that do not need graph contagion signal (e.g. `detect_cross_pattern_discrepancy`,
+which measures geometry disagreement between patterns, not neighbor contamination) pass
+`include_graph=False` to skip graph source registration and avoid the per-pattern edge
+table read that would otherwise dominate scan latency on large spheres.
 
 ## Build Flow
 
@@ -278,7 +282,7 @@ The MCP package is a transport and tool layer.
 It does not define the core GDS model. Instead, it:
 
 - opens and closes spheres
-- exposes 66 navigation and analysis tools
+- exposes 67 navigation and analysis tools
 - formats results as JSON
 - manages session state for an agentic client
 

{hypertopos-0.2.1 → hypertopos-0.2.2}/docs/concepts.md

@@ -132,7 +132,7 @@ An edge table is a flat Lance dataset that links anchor entities through an even
 - **Runtime graph traversal** -- `find_geometric_path` uses beam search over the edge table, scoring paths by geometric coherence of intermediate entities
 - **Lazy chain discovery** -- `discover_chains` performs temporal BFS on edges without requiring build-time chain extraction
 - **Edge statistics** -- row counts, unique entity counts, timestamp and amount ranges
-- **Witness cohort discovery** -- `find_witness_cohort` ranks entities that share the target's witness signature by combining delta similarity, witness overlap, trajectory alignment, and a graded anomaly bonus, while excluding entities already connected via the edge table. **Investigative peer ranking, not edge forecasting.** Validated on AML HI-small: 25.3% co-laundering precision@10 vs 1.2% random base rate (20.5× lift), 2.6× improvement over `find_similar_entities + is_anomaly` baseline (6.5%), 15.5% top-10 overlap with that baseline (substantively different results, not ANN with extra steps); temporal hold-out recall@10 is 0%, confirming the function surfaces existing peers rather than predicting future edges. Uniquely possible because population-relative geometry, witness sets, temporal solids, and the edge table all live in one storage layer
+- **Witness cohort discovery** -- `find_witness_cohort` ranks entities that share the target's witness signature by combining delta similarity, witness overlap, trajectory alignment, and a graded anomaly bonus, while excluding entities already connected via the edge table. **Investigative peer ranking, not edge forecasting** — surfaces existing peers rather than predicting future edges. Uniquely possible because population-relative geometry, witness sets, temporal solids, and the edge table all live in one storage layer
 
 **Edge table fields:** `from_key` and `to_key` are anchor entity keys derived from event pattern FK columns. `event_key` links back to the event line for traceability. `timestamp` is epoch seconds from the column specified by `edge_table.timestamp_col` (or auto-detected). `amount` is the numeric value from `edge_table.amount_col` (or auto-detected from columns named `amount`, `value`, `total`, `amt`). The semantic meaning of `amount` depends on the domain (e.g. payment value, fare, order total, shipment weight). When no amount column is found, defaults to 0.0.
 

{hypertopos-0.2.1 → hypertopos-0.2.2}/hypertopos/__init__.py

@@ -16,4 +16,4 @@ __all__ = [
     "GDSBuilder",
     "RelationSpec",
 ]
-__version__ = "0.1.0"
+__version__ = "0.2.2"

{hypertopos-0.2.1 → hypertopos-0.2.2}/hypertopos/navigation/navigator.py

@@ -2268,17 +2268,26 @@ class GDSNavigator:
         line_id: str,
         pattern_id: str,
         top_n: int = 20,
+        *,
+        timestamp_cutoff: float | None = None,
     ) -> dict[str, Any]:
         """Fast counterparty lookup via edge table BTREE indexes.
 
         Returns same structure as find_counterparties but with ``amount_sum``
         and ``amount_max`` per counterparty entry.  Anomaly enrichment uses
         the resolved anchor pattern's geometry.
+
+        ``timestamp_cutoff`` restricts the lookup to edges with
+        ``timestamp <= timestamp_cutoff``.
         """
         # Outgoing: from_key == primary_key → counterparties in to_key
-        fwd = self._storage.read_edges(pattern_id, from_keys=[primary_key])
+        fwd = self._storage.read_edges(
+            pattern_id, from_keys=[primary_key], timestamp_to=timestamp_cutoff,
+        )
         # Incoming: to_key == primary_key → counterparties in from_key
-        rev = self._storage.read_edges(pattern_id, to_keys=[primary_key])
+        rev = self._storage.read_edges(
+            pattern_id, to_keys=[primary_key], timestamp_to=timestamp_cutoff,
+        )
 
         def _group(edges: pa.Table, group_col: str) -> list[dict[str, Any]]:
             if edges.num_rows == 0:
@@ -2403,6 +2412,8 @@ class GDSNavigator:
         pattern_id: str | None = None,
         top_n: int = 20,
         use_edge_table: bool = True,
+        *,
+        timestamp_cutoff: float | None = None,
     ) -> dict[str, Any]:
         """Find transaction counterparties of an entity with anomaly enrichment.
 
@@ -2413,6 +2424,13 @@ class GDSNavigator:
         If *pattern_id* is provided, each counterparty is enriched with ``is_anomaly``
         and ``delta_rank_pct`` from that pattern's geometry.
 
+        ``timestamp_cutoff`` restricts the lookup to edges with
+        ``timestamp <= timestamp_cutoff``. **Edge-table fast path only.** The
+        points-scan fallback has no timestamp column available and cannot
+        honor the cutoff, so passing it without an edge-table-eligible
+        configuration raises ``GDSNavigationError`` to fail loudly instead of
+        silently returning unfiltered results.
+
         Returns ``{primary_key, outgoing, incoming, summary}``.
         """
         # Fast path: edge table BTREE lookup
@@ -2423,6 +2441,16 @@ class GDSNavigator:
         ):
             return self._find_counterparties_via_edges(
                 primary_key, line_id, pattern_id, top_n,
+                timestamp_cutoff=timestamp_cutoff,
+            )
+
+        # Cutoff is meaningless on the points-scan fallback — fail loudly.
+        if timestamp_cutoff is not None:
+            raise GDSNavigationError(
+                "find_counterparties: timestamp_cutoff is only supported on "
+                "the edge-table fast path. Provide a pattern_id whose edge "
+                "table exists and leave use_edge_table=True, or omit "
+                "timestamp_cutoff."
             )
 
         sphere = self._storage.read_sphere()
@@ -2552,12 +2580,18 @@ class GDSNavigator:
         primary_key: str,
         pattern_id: str,
         top_n: int = 20,
+        *,
+        timestamp_cutoff: float | None = None,
     ) -> dict[str, Any]:
         """Net flow analysis per counterparty via edge table.
 
         Two edge lookups (outgoing + incoming), sum amounts, compute
         per-counterparty net flow.
 
+        When ``timestamp_cutoff`` is set (Unix seconds as float), only edges
+        with ``timestamp <= timestamp_cutoff`` are considered — used for
+        as-of evaluation of flow history up to a given point in time.
+
         Returns ``{outgoing_total, incoming_total, net_flow, flow_direction,
         counterparties: [{key, net_flow, direction}]}``.
         """
@@ -2566,8 +2600,12 @@ class GDSNavigator:
                 f"Pattern '{pattern_id}' has no edge table. "
                 "entity_flow requires an edge table."
             )
-        fwd = self._storage.read_edges(pattern_id, from_keys=[primary_key])
-        rev = self._storage.read_edges(pattern_id, to_keys=[primary_key])
+        fwd = self._storage.read_edges(
+            pattern_id, from_keys=[primary_key], timestamp_to=timestamp_cutoff,
+        )
+        rev = self._storage.read_edges(
+            pattern_id, to_keys=[primary_key], timestamp_to=timestamp_cutoff,
+        )
 
         # Sum outgoing amounts per counterparty
         out_by_cp: dict[str, float] = {}
@@ -2624,12 +2662,19 @@ class GDSNavigator:
         self,
         primary_key: str,
         pattern_id: str,
+        *,
+        timestamp_cutoff: float | None = None,
     ) -> dict[str, Any]:
         """Score how many of an entity's counterparties are anomalous.
 
         Edge lookup for counterparties, batch geometry check on the anchor
         pattern.  Score = anomalous_counterparties / total_counterparties.
 
+        When ``timestamp_cutoff`` is set (Unix seconds as float), only edges
+        with ``timestamp <= timestamp_cutoff`` are considered — used for
+        as-of evaluation, reproducing the state of the graph at a given
+        point in time.
+
         Returns ``{score: 0.0-1.0, total_counterparties,
         anomalous_counterparties, interpretation}``.
         """
@@ -2638,8 +2683,12 @@ class GDSNavigator:
                 f"Pattern '{pattern_id}' has no edge table. "
                 "contagion_score requires an edge table."
             )
-        fwd = self._storage.read_edges(pattern_id, from_keys=[primary_key])
-        rev = self._storage.read_edges(pattern_id, to_keys=[primary_key])
+        fwd = self._storage.read_edges(
+            pattern_id, from_keys=[primary_key], timestamp_to=timestamp_cutoff,
+        )
+        rev = self._storage.read_edges(
+            pattern_id, to_keys=[primary_key], timestamp_to=timestamp_cutoff,
+        )
 
         cp_keys: set[str] = set()
         if fwd.num_rows > 0:
@@ -2688,15 +2737,25 @@ class GDSNavigator:
         primary_keys: list[str],
         pattern_id: str,
         max_keys: int = 200,
+        *,
+        timestamp_cutoff: float | None = None,
     ) -> dict[str, Any]:
         """Contagion score for multiple entities.
 
+        When ``timestamp_cutoff`` is set, forwards it to each per-entity
+        contagion_score call so that only edges with
+        ``timestamp < timestamp_cutoff`` are considered.
+
         Returns per-entity scores plus a summary with mean/max.
         """
         keys = primary_keys[:max_keys]
         results: list[dict[str, Any]] = []
         for pk in keys:
-            results.append(self.contagion_score(pk, pattern_id))
+            results.append(
+                self.contagion_score(
+                    pk, pattern_id, timestamp_cutoff=timestamp_cutoff,
+                )
+            )
 
         scores = [r["score"] for r in results]
         mean_score = round(sum(scores) / len(scores), 4) if scores else 0.0
@@ -2718,12 +2777,19 @@ class GDSNavigator:
         primary_key: str,
         pattern_id: str,
         n_buckets: int = 4,
+        *,
+        timestamp_cutoff: float | None = None,
     ) -> dict[str, Any]:
         """Temporal connection velocity via edge table.
 
         Buckets edges by timestamp, counts unique counterparties per bucket.
         Velocity = degree in last bucket / degree in first bucket.
 
+        When ``timestamp_cutoff`` is set (Unix seconds as float), only edges
+        with ``timestamp <= timestamp_cutoff`` are considered. Buckets are
+        computed from the filtered edge set, so the last bucket endpoint is
+        naturally <= cutoff.
+
         Returns ``{buckets: [{period, out_degree, in_degree}],
         velocity_out, velocity_in, interpretation}``.
         """
@@ -2732,8 +2798,12 @@ class GDSNavigator:
                 f"Pattern '{pattern_id}' has no edge table. "
                 "degree_velocity requires an edge table."
             )
-        fwd = self._storage.read_edges(pattern_id, from_keys=[primary_key])
-        rev = self._storage.read_edges(pattern_id, to_keys=[primary_key])
+        fwd = self._storage.read_edges(
+            pattern_id, from_keys=[primary_key], timestamp_to=timestamp_cutoff,
+        )
+        rev = self._storage.read_edges(
+            pattern_id, to_keys=[primary_key], timestamp_to=timestamp_cutoff,
+        )
 
         # Collect all timestamps
         fwd_ts = fwd["timestamp"].to_pylist() if fwd.num_rows > 0 else []
@@ -2883,6 +2953,8 @@ class GDSNavigator:
         decay: float = 0.7,
         min_threshold: float = 0.001,
         max_affected: int = 10_000,
+        *,
+        timestamp_cutoff: float | None = None,
     ) -> dict[str, Any]:
         """BFS influence propagation from seed entities with geometric decay.
 
@@ -2890,6 +2962,12 @@ class GDSNavigator:
         Stops expanding when score falls below *min_threshold* or when
         *max_affected* entities have been reached.
 
+        When ``timestamp_cutoff`` is set (Unix seconds as float), the BFS only
+        follows edges with ``timestamp <= timestamp_cutoff``. Use this to
+        reconstruct what influence propagation would have surfaced at a prior
+        point in time — e.g. "what was reachable from this seed on the day
+        of the incident?".
+
         Returns ``{seeds, affected_entities, summary}``.
         """
         if not self._storage.has_edge_table(pattern_id):
@@ -2913,8 +2991,12 @@ class GDSNavigator:
         def _expand_neighbors(keys: set[str]) -> None:
             """Read edges for keys and aggregate tx_count per neighbor."""
             key_list = list(keys)
-            fwd = self._storage.read_edges(pattern_id, from_keys=key_list)
-            rev = self._storage.read_edges(pattern_id, to_keys=key_list)
+            fwd = self._storage.read_edges(
+                pattern_id, from_keys=key_list, timestamp_to=timestamp_cutoff,
+            )
+            rev = self._storage.read_edges(
+                pattern_id, to_keys=key_list, timestamp_to=timestamp_cutoff,
+            )
             for tbl in (fwd, rev):
                 from_arr = tbl["from_key"].to_pylist()
                 to_arr = tbl["to_key"].to_pylist()
@@ -3304,9 +3386,9 @@ class GDSNavigator:
         BTREE-indexed lookup. When ``bidirectional`` is True (default), inspects both
         outgoing and incoming edges.
 
-        ``timestamp_max`` restricts the lookup to edges with timestamp strictly
-        less than the cutoff — used by hold-out evaluation to reproduce the
-        as-of state of the graph at a given point in time.
+        ``timestamp_max`` restricts the lookup to edges with
+        ``timestamp <= timestamp_max`` — used by hold-out evaluation to
+        reproduce the as-of state of the graph at a given point in time.
         """
         existing: set[str] = set()
         fwd = self._storage.read_edges(
@@ -3389,16 +3471,10 @@ class GDSNavigator:
     ) -> WitnessCohortResult:
         """Rank entities that share ``primary_key``'s witness signature.
 
-        **Investigative peer ranking, not edge forecasting.** Empirical
-        validation on AML HI-small (5M edges, 6357 labeled launderers):
-        25.3% co-laundering precision@10 vs 1.2% random base rate
-        (20.5× lift), 2.6× improvement over ``find_similar_entities +
-        is_anomaly`` baseline (6.5%), 15.5% top-10 overlap with that
-        baseline so results are substantively different. Temporal hold-out
-        recall@10 is 0% — the function does NOT forecast which entities
-        will form future edges; it surfaces entities that share the
-        target's anomaly signature and are likely to belong to the same
-        investigative cohort.
+        **Investigative peer ranking, not edge forecasting.** Surfaces
+        entities that share the target's anomaly signature and are likely
+        to belong to the same investigative cohort. The function does NOT
+        forecast which entities will form future edges.
 
         Combines four signals into a composite score in [0, 1]:
 
@@ -3421,9 +3497,9 @@ class GDSNavigator:
         so the cohort is denser in unknown peers worth investigating. When
         ``config.bidirectional_check`` is True (default) both outgoing and
         incoming edges count as existing. ``config.timestamp_cutoff`` further
-        restricts the existing-edge filter to edges with ``timestamp < cutoff``
-        — used by hold-out evaluation to reproduce the as-of state of the
-        graph at a given point in time.
+        restricts the existing-edge filter to edges with
+        ``timestamp <= cutoff`` — used by hold-out evaluation to reproduce
+        the as-of state of the graph at a given point in time.
 
         ``edge_pattern_id`` overrides the auto-resolved event pattern; use this
         when multiple event patterns share the same anchor and you want a
@@ -7626,7 +7702,12 @@ class GDSNavigator:
 
         sphere = self._storage.read_sphere()
         scanner = PassiveScanner(self._storage, sphere, self._manifest)
-        scanner.auto_discover(entity_line)
+        # Skip graph sources — this detector measures geometry disagreement
+        # between patterns, not graph contagion. Registering graph sources
+        # here triggers full edge-table reads per pattern (~37s on 5M-edge
+        # spheres, compounding for multi-pattern lines) with zero signal
+        # contribution to the downstream single-source hit check.
+        scanner.auto_discover(entity_line, include_graph=False)
 
         if len(scanner._sources) < 2:
             return []

{hypertopos-0.2.1 → hypertopos-0.2.2}/hypertopos/navigation/scanner.py

@@ -256,12 +256,17 @@ class PassiveScanner:
         home_line_id: str,
         include_borderline: bool = False,
         borderline_rank_threshold: float = 80,
+        *,
+        include_graph: bool = True,
     ) -> PassiveScanner:
         """Auto-discover all patterns related to home_line_id.
 
         Registers each discovered pattern as a source with auto-detected key_type.
         When include_borderline is True, also registers borderline sources for
-        each direct pattern.
+        each direct pattern. When include_graph is False, skips registering
+        ``{pattern_id}_graph`` sources even if event patterns with edge tables
+        exist — use this when the downstream scan does not need graph contagion
+        (e.g. cross-pattern geometry discrepancy detection).
         """
         for pat_id in self._sphere.patterns:
             key_type = self._classify_for_line(pat_id, home_line_id)
@@ -278,13 +283,14 @@ class PassiveScanner:
                         rank_threshold=borderline_rank_threshold,
                     )
         # Auto-discover graph sources — event patterns with edge tables
-        for pat_id, pat in self._sphere.patterns.items():
-            if pat.pattern_type == "event" and self._reader.has_edge_table(pat_id):
-                # Check if any relation targets home_line_id
-                for rel in pat.relations:
-                    if rel.line_id == home_line_id:
-                        self.add_graph_source(f"{pat_id}_graph", pat_id)
-                        break
+        if include_graph:
+            for pat_id, pat in self._sphere.patterns.items():
+                if pat.pattern_type == "event" and self._reader.has_edge_table(pat_id):
+                    # Check if any relation targets home_line_id
+                    for rel in pat.relations:
+                        if rel.line_id == home_line_id:
+                            self.add_graph_source(f"{pat_id}_graph", pat_id)
+                            break
         return self
 
     def scan(

{hypertopos-0.2.1 → hypertopos-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypertopos"
-version = "0.2.1"
+version = "0.2.2"
 description = "Navigate your data like space."
 requires-python = ">=3.12"
 license = {text = "BSL-1.1"}

{hypertopos-0.2.1 → hypertopos-0.2.2}/tests/test_detection.py

@@ -86,6 +86,7 @@ class _FakeHit:
     primary_key: str
     score: int
     source_count: int = 1
+    weighted_score: float = 0.0
 
 
 @dataclass
@@ -156,6 +157,30 @@ class TestDetectCrossPatternDiscrepancy:
         assert result[0]["normal_patterns"] == ["pat_b"]
         assert result[0]["delta_norm_anomalous"] == 3.5
 
+    def test_skips_graph_sources_in_auto_discover(self):
+        """detect_cross_pattern_discrepancy must not register graph sources.
+
+        Graph contagion plays no role in detecting geometry disagreement
+        between patterns, but full edge-table scans are expensive on large
+        spheres (~37s per pattern on 5M-edge spheres). Confirm the detector
+        passes include_graph=False when calling auto_discover.
+        """
+        nav = _make_navigator()
+
+        fake_scanner = MagicMock()
+        fake_scanner._sources = [MagicMock()]  # only 1 source → early return
+        fake_scanner.auto_discover.return_value = fake_scanner
+
+        with patch(
+            "hypertopos.navigation.scanner.PassiveScanner",
+            return_value=fake_scanner,
+        ):
+            nav.detect_cross_pattern_discrepancy("accounts")
+
+        fake_scanner.auto_discover.assert_called_once_with(
+            "accounts", include_graph=False,
+        )
+
 
 class TestDetectNeighborContamination:
     """Tests for detect_neighbor_contamination."""