From 0f8e03bdf3195ac076e2a82e892a9f905a6f2f21 Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Tue, 23 Jun 2026 10:51:59 -0700 Subject: [PATCH 1/4] docs(design): spec for SUPPORTS/SUPERSEDES edge-type expansion (#999) Both writers already exist deferred: SUPPORTS = the relationship detector's existing REFINES verdict (unwritten), SUPERSEDES = dedup's cluster write-path (deferred behind #197). #999 activates both behind the existing default-off AELFRICE_AUTO_RELATIONSHIPS gate, mirroring how #988 activated the CONTRADICTS writer. Deterministic, stdlib-only; keeps the #605/#897 narrow-surface decision intact. --- docs/design/feature-edge-type-expansion.md | 122 +++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 docs/design/feature-edge-type-expansion.md diff --git a/docs/design/feature-edge-type-expansion.md b/docs/design/feature-edge-type-expansion.md new file mode 100644 index 000000000..301373d90 --- /dev/null +++ b/docs/design/feature-edge-type-expansion.md @@ -0,0 +1,122 @@ +# Edge-type expansion: SUPPORTS + SUPERSEDES at ingest (#999) + +Status: spec (needs-spec → spec-ready) +Issue: #999 +Depends on: #988 (CONTRADICTS substrate), #201 (detector ratification), #197 (dedup bench gate) +Blocks: #1001 (`+HRR-expand` ablation arm) + +## Problem + +The deterministic HRR vocabulary-bridge expansion lane (`use_hrr_expand`, +#981/PR #997) finds semantic neighbors by traversing typed edges. The ingest +substrate built in #988 emits **CONTRADICTS only** +(`relationship_detector.py:905`), so the lane traverses a graph missing every +other edge class. The #981 ceiling measurement (2,098 edges on LoCoMo10, all +CONTRADICTS) is the binding constraint, not the lane logic. Until the substrate +carries more edge types, the `#1001` ablation measures a starved graph and a +flat F1 delta would be **misread** as "the lane does not help." + +This spec adds the two highest-value semantic edge types for a conversational +corpus — **SUPPORTS** and **SUPERSEDES** — to the ingest substrate. +Code-edge types (CALLS / CITES / TESTS / IMPLEMENTS) are out of scope: they +are source-graph relations with no deterministic lexical signal in +conversational belief text. + +## Key finding: both writers already exist, deferred + +Neither edge type needs a new detector. The detection already exists; only the +write-path is gated off. + +- **SUPPORTS** — `relationship_detector.analyze()` already returns a `REFINES` + verdict for pairs with residual-content overlap above the relatedness floor + **and** agreeing modality (`relationship_detector.py:335-340`). REFINES is + counted in audits (`n_refines`) but never written: `write_semantic_edges` + is `CONTRADICTS only` by design (#988). `EDGE_SUPPORTS` is a defined model + type (`models.py:32`, valence `+1.0`). +- **SUPERSEDES** — `dedup.dedup_audit()` already clusters near-duplicate + beliefs (union-find) and documents the write-path: "will use the *oldest* + member as the SUPERSEDES target" (`dedup.py:160`), "deferred behind the #197 + bench gate" (`dedup.py:329`). `EDGE_SUPERSEDES` is a defined model type + (`models.py:35`, valence `0.0`). + +So #999 = **activate two already-designed, deferred write-paths**, gated +default-off under the existing `AELFRICE_AUTO_RELATIONSHIPS` flag. This mirrors +exactly how #988 activated the #201-ratified CONTRADICTS writer default-off, +and it keeps the #605/#897 determinism-and-narrow-surface decision intact: no +LLM, no embedding, no new default-on behavior. + +## Design + +### SUPPORTS (relationship_detector.py) + +Add `write_supports_edges(store, *, jaccard_min, residual_overlap_min, +max_candidate_pairs, max_edges_per_belief) -> SemanticEdgeWriteReport`, +structurally identical to `write_semantic_edges` but acting on the `REFINES` +slice of the audit instead of the `CONTRADICTS` slice. + +- Candidate set: `report.pairs` where `label == LABEL_REFINES`. +- REFINES carries no confidence gradient (score is fixed `0.0`, + `relationship_detector.py:337`); the residual-overlap floor already cleared + in `analyze()` is the relatedness gate. So **all** REFINES pairs are + eligible — no `confidence_min` partition (unlike CONTRADICTS, which splits + high/sub-confidence between `write_semantic_edges` and + `write_potentially_stale_edges`). +- Edge is **symmetric** (mutual support): canonicalize `src = min(id)`, + `dst = max(id)` — same as the CONTRADICTS writer. +- **Idempotent**: skip if `(src, dst, SUPPORTS)` exists. +- **Write-gated**: reuse `max_edges_per_belief` (Exp-48 coverage-dilution + guard); pre-existing edges count toward the per-belief budget across re-runs. +- **Deterministic**: pairs processed in the audit's `(belief_a_id, + belief_b_id)` order, so which edges survive the cap is deterministic. + +### SUPERSEDES (dedup.py) + +Add `write_supersedes_edges(store, *, jaccard_min, levenshtein_min, +max_candidate_pairs, max_edges_per_belief) -> SupersedesWriteReport`, acting on +`dedup_audit()` clusters. + +- For each cluster, the **oldest** member (min `created_at`, tie-break min + `id`) is the SUPERSEDES *target*. Every other member emits one edge + `src = member` → `dst = oldest` (directional: the newer belief supersedes the + older). +- **Idempotent**: skip if `(member, oldest, SUPERSEDES)` exists. +- **Write-gated**: `max_edges_per_belief`, same semantics. +- **Deterministic**: members are already lexicographically sorted in + `DuplicateCluster.member_ids`; clusters sorted by `representative_id`. +- Direction rationale: SUPERSEDES is the one asymmetric type here. Newer→older + matches the lane's intent (a query hitting the current belief should reach + the ones it replaced, and vice-versa, via the directed edge the lane probes). + +### Ingest wiring (ingest.py) + +The CONTRADICTS writer is already invoked behind +`is_auto_relationship_detection_enabled()` (ingest.py:307-311). Add the two new +writers in the same guarded block, same order every run: +`write_semantic_edges` → `write_supports_edges` → `write_supersedes_edges`. +When the flag is off, ingest stays byte-identical to today. + +## Determinism & test plan + +Mirror the #988 CONTRADICTS tests for each new writer: + +1. Flag-off no-op: ingest writes zero SUPPORTS/SUPERSEDES edges. +2. Byte-equal edge table across two runs on the same store snapshot + (tie-break by `(src, dst)` ASC). +3. Idempotency: second `write_*` run writes 0 new edges, skips N existing. +4. Write-gate: a belief at `max_edges_per_belief` drops further pairs + deterministically. +5. SUPPORTS: a REFINES pair produces exactly one symmetric SUPPORTS edge; a + CONTRADICTS pair produces none. +6. SUPERSEDES: a 3-member duplicate cluster produces 2 edges both pointing at + the oldest member; direction is newer→oldest. +7. No regression: existing CONTRADICTS / POTENTIALLY_STALE writers unchanged. + +## Out of scope + +- CALLS / CITES / TESTS / IMPLEMENTS edge types (no deterministic conversational + signal). +- Flipping `AELFRICE_AUTO_RELATIONSHIPS` to default-on — that reverses #605 and + is explicitly routed elsewhere. +- The incremental per-turn detection rewrite — tracked separately (#1000); this + spec keeps the existing full-audit candidate-pair path. +- Running the `+HRR-expand` ablation — #1001, blocked on this landing. From 7ba5ddb0067708c977f231829185ba7293f8f266 Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Tue, 23 Jun 2026 10:54:01 -0700 Subject: [PATCH 2/4] feat(ingest): write SUPPORTS edges from REFINES verdicts (#999) The detector already computes a REFINES verdict (same-subject + agreeing-modality) but #988 only wrote CONTRADICTS. Add write_supports_edges, the agreement counterpart: emit one symmetric SUPPORTS edge per REFINES pair, idempotent, write-gated by max_edges_per_belief, deterministic in audit pair order. EDGE_SUPPORTS already exists in models.py. Not yet wired into ingest (next commit). --- src/aelfrice/relationship_detector.py | 124 +++++++++++++++ ...t_relationship_detector_supports_writer.py | 148 ++++++++++++++++++ 2 files changed, 272 insertions(+) create mode 100644 tests/test_relationship_detector_supports_writer.py diff --git a/src/aelfrice/relationship_detector.py b/src/aelfrice/relationship_detector.py index cd7e00f3d..e217548e7 100644 --- a/src/aelfrice/relationship_detector.py +++ b/src/aelfrice/relationship_detector.py @@ -986,6 +986,128 @@ def write_semantic_edges( ) +# --- SUPPORTS edge writer (#999 — REFINES verdict → SUPPORTS edge) ------- + + +@dataclass(frozen=True) +class SupportsWriteReport: + """Summary of one ``write_supports_edges`` run. + + ``n_refines`` + REFINES pairs returned by the audit — the candidate set this + writer acts on. REFINES carries no confidence gradient (score is + fixed 0.0); the residual-overlap floor cleared in ``analyze`` is + the relatedness gate, so every REFINES pair is eligible. + + ``n_edges_written`` + Pairs that produced a new SUPPORTS edge this run. + + ``n_edges_skipped_existing`` + Pairs whose edge already existed (idempotency guard fired). + + ``n_edges_skipped_gated`` + Pairs dropped because an endpoint hit ``max_edges_per_belief``. + + ``n_edges_skipped_self_pair`` + Defensive counter — should always be 0; pairs where a == b. + """ + + n_refines: int + n_edges_written: int + n_edges_skipped_existing: int + n_edges_skipped_gated: int + n_edges_skipped_self_pair: int + + +def write_supports_edges( + store: "MemoryStore", + *, + jaccard_min: float = DEFAULT_JACCARD_MIN, + residual_overlap_min: float = DEFAULT_RESIDUAL_OVERLAP_MIN, + confidence_min: float = DEFAULT_CONFIDENCE_MIN, + max_candidate_pairs: int = DEFAULT_MAX_CANDIDATE_PAIRS, + max_edges_per_belief: int = DEFAULT_MAX_EDGES_PER_BELIEF, +) -> SupportsWriteReport: + """Emit SUPPORTS edges for REFINES (mutual-agreement) pairs (#999). + + The deterministic detector already returns a ``refines`` verdict for + pairs with residual-content overlap above the relatedness floor *and* + agreeing modality — same subject, no contradiction. This writer turns + that already-computed verdict into a SUPPORTS edge, the agreement + counterpart to ``write_semantic_edges``'s CONTRADICTS. + + Wired into ingest only behind the default-off ``auto_detect`` flag + (``is_auto_relationship_detection_enabled``); a fresh install writes no + edges and the #605/#897 scope decision stands unchanged. + + Unlike CONTRADICTS, REFINES has no confidence gradient (score is fixed + 0.0), so there is no high/sub-confidence partition — every REFINES pair + the audit returns is eligible. The relation is symmetric, so the edge + direction is canonicalised to ``src = min(id)``, ``dst = max(id)``. + + **Idempotent.** Each ``(src, dst, SUPPORTS)`` triple is checked before + insert and skipped if present. + + **Write-gated.** ``max_edges_per_belief`` caps how many SUPPORTS edges + any one belief accretes; pre-existing edges count toward the budget for + a hard per-belief bound across re-runs. Pairs are processed in the + audit's deterministic ``(belief_a_id, belief_b_id)`` order. + + Stdlib-only: no LLM, no embedding. Delegates detection to + ``relationships_audit``. + """ + from aelfrice.models import Edge, EDGE_SUPPORTS + + report = relationships_audit( + store, + jaccard_min=jaccard_min, + residual_overlap_min=residual_overlap_min, + confidence_min=confidence_min, + max_candidate_pairs=max_candidate_pairs, + ) + + refines_pairs = [p for p in report.pairs if p.label == LABEL_REFINES] + # `report.pairs` is already sorted by (belief_a_id, belief_b_id); + # preserve that order so the write-gate is deterministic. + + edges_per_belief: dict[str, int] = {} + n_written = 0 + n_skipped_existing = 0 + n_gated = 0 + n_self = 0 + for pair in refines_pairs: + a_id, b_id = pair.belief_a_id, pair.belief_b_id + if a_id == b_id: + n_self += 1 + continue + if ( + edges_per_belief.get(a_id, 0) >= max_edges_per_belief + or edges_per_belief.get(b_id, 0) >= max_edges_per_belief + ): + n_gated += 1 + continue + src_id, dst_id = (a_id, b_id) if a_id < b_id else (b_id, a_id) + if store.get_edge(src_id, dst_id, EDGE_SUPPORTS) is not None: + n_skipped_existing += 1 + edges_per_belief[a_id] = edges_per_belief.get(a_id, 0) + 1 + edges_per_belief[b_id] = edges_per_belief.get(b_id, 0) + 1 + continue + store.insert_edge( + Edge(src=src_id, dst=dst_id, type=EDGE_SUPPORTS, weight=1.0) + ) + n_written += 1 + edges_per_belief[a_id] = edges_per_belief.get(a_id, 0) + 1 + edges_per_belief[b_id] = edges_per_belief.get(b_id, 0) + 1 + + return SupportsWriteReport( + n_refines=len(refines_pairs), + n_edges_written=n_written, + n_edges_skipped_existing=n_skipped_existing, + n_edges_skipped_gated=n_gated, + n_edges_skipped_self_pair=n_self, + ) + + __all__ = [ "DEFAULT_CONFIDENCE_MIN", "DEFAULT_JACCARD_MIN", @@ -1001,6 +1123,7 @@ def write_semantic_edges( "RelationshipVerdict", "RelationshipsAuditReport", "SemanticEdgeWriteReport", + "SupportsWriteReport", "Signals", "analyze", "classify", @@ -1012,4 +1135,5 @@ def write_semantic_edges( "relationships_audit", "write_potentially_stale_edges", "write_semantic_edges", + "write_supports_edges", ] diff --git a/tests/test_relationship_detector_supports_writer.py b/tests/test_relationship_detector_supports_writer.py new file mode 100644 index 000000000..881b2cf1e --- /dev/null +++ b/tests/test_relationship_detector_supports_writer.py @@ -0,0 +1,148 @@ +"""Unit tests for the #999 SUPPORTS edge writer. + +Covers ``write_supports_edges`` (SUPPORTS edges for REFINES / mutual- +agreement pairs — the agreement counterpart to the #988 CONTRADICTS +writer), idempotency, the per-belief write-gate, and the determinism +guarantee. + +All tests use a real ``MemoryStore(":memory:")`` — no mocks. +""" +from __future__ import annotations + +import hashlib + +import pytest + +from aelfrice.models import ( + BELIEF_FACTUAL, + EDGE_SUPPORTS, + LOCK_NONE, + Belief, +) +from aelfrice.relationship_detector import write_supports_edges +from aelfrice.store import MemoryStore + +# REFINES pair: identical residual content, agreeing modality (both +# universal "always", no negation) → score 0.0, label refines. +_ALWAYS = "the deployment script always runs the database migration step" +_ALWAYS_LAUNCH = _ALWAYS + " before launch" +_ALWAYS_PROD = _ALWAYS + " in production" +# CONTRADICTS pair counterpart (universal affirm vs negate). +_NEVER = "the deployment script never runs the database migration step" +# Lexically distant filler that relates to nothing else. +_UNRELATED = "the harbor seals bask on the warm rocks at noon each day" + + +def _make_belief( + store: MemoryStore, + *, + belief_id: str, + content: str, + created_at: str = "2026-01-01T00:00:00Z", +) -> Belief: + b = Belief( + id=belief_id, + content=content, + content_hash=hashlib.sha256(content.encode()).hexdigest(), + alpha=1.0, + beta=1.0, + type=BELIEF_FACTUAL, + lock_level=LOCK_NONE, + locked_at=None, + created_at=created_at, + last_retrieved_at=None, + ) + store.insert_belief(b) + return b + + +def _supports_edges(store: MemoryStore) -> list[tuple[str, str]]: + """Return all SUPPORTS edges as sorted (src, dst) tuples.""" + rows = store._conn.execute( # type: ignore[attr-defined] + "SELECT src, dst FROM edges WHERE type = ? ORDER BY src, dst", + (EDGE_SUPPORTS,), + ).fetchall() + return [(r[0], r[1]) for r in rows] + + +@pytest.fixture +def store() -> MemoryStore: + return MemoryStore(":memory:") + + +# --------------------------------------------------------------------------- +# write_supports_edges — write / scope / idempotency +# --------------------------------------------------------------------------- + + +def test_writes_supports_edge_for_refines_pair(store: MemoryStore) -> None: + _make_belief(store, belief_id="b1", content=_ALWAYS) + _make_belief(store, belief_id="b2", content=_ALWAYS_LAUNCH) + report = write_supports_edges(store) + assert report.n_refines == 1 + assert report.n_edges_written == 1 + # Symmetric relation: canonical direction src = min(id), dst = max(id). + assert _supports_edges(store) == [("b1", "b2")] + + +def test_idempotent_second_run_writes_nothing(store: MemoryStore) -> None: + _make_belief(store, belief_id="b1", content=_ALWAYS) + _make_belief(store, belief_id="b2", content=_ALWAYS_LAUNCH) + write_supports_edges(store) + report = write_supports_edges(store) + assert report.n_edges_written == 0 + assert report.n_edges_skipped_existing == 1 + assert _supports_edges(store) == [("b1", "b2")] + + +def test_contradicts_pair_writes_no_supports(store: MemoryStore) -> None: + # Universal affirm vs negate → contradicts, which this SUPPORTS-only + # writer ignores. + _make_belief(store, belief_id="b1", content=_ALWAYS) + _make_belief(store, belief_id="b2", content=_NEVER) + report = write_supports_edges(store) + assert report.n_edges_written == 0 + assert _supports_edges(store) == [] + + +def test_unrelated_pair_writes_no_supports(store: MemoryStore) -> None: + _make_belief(store, belief_id="b1", content=_ALWAYS) + _make_belief(store, belief_id="b2", content=_UNRELATED) + report = write_supports_edges(store) + assert report.n_refines == 0 + assert report.n_edges_written == 0 + assert _supports_edges(store) == [] + + +# --------------------------------------------------------------------------- +# Determinism — byte-equal edge sets across two fresh stores +# --------------------------------------------------------------------------- + + +def test_determinism_byte_equal_edges() -> None: + def build() -> list[tuple[str, str]]: + s = MemoryStore(":memory:") + _make_belief(s, belief_id="b1", content=_ALWAYS) + _make_belief(s, belief_id="b2", content=_ALWAYS_LAUNCH) + _make_belief(s, belief_id="b3", content=_UNRELATED) + write_supports_edges(s) + return _supports_edges(s) + + assert build() == build() + + +# --------------------------------------------------------------------------- +# Write-gate — per-belief edge cap (Exp-48 dilution guard) +# --------------------------------------------------------------------------- + + +def test_write_gate_caps_per_belief_edges(store: MemoryStore) -> None: + # Three mutually-refining beliefs → three REFINES pairs. With a cap of + # 1, only the first pair in deterministic (a_id, b_id) order survives. + _make_belief(store, belief_id="b1", content=_ALWAYS) + _make_belief(store, belief_id="b2", content=_ALWAYS_LAUNCH) + _make_belief(store, belief_id="b3", content=_ALWAYS_PROD) + report = write_supports_edges(store, max_edges_per_belief=1) + assert report.n_edges_written == 1 + assert report.n_edges_skipped_gated == 2 + assert _supports_edges(store) == [("b1", "b2")] From e09c967fe7047d57a0efc9e352282a2cfe6f7e6a Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Tue, 23 Jun 2026 10:56:24 -0700 Subject: [PATCH 3/4] feat(ingest): write SUPERSEDES edges within dedup clusters (#999) Activate the dedup write-path documented at dedup.py:160 and deferred behind the #197 bench gate: within each near-duplicate cluster the oldest member is the SUPERSEDES target and every newer member emits a directional member->oldest edge. Idempotent, write-gated by a dedup-local max_edges_per_belief (no import of relationship_detector, which imports dedup), deterministic in cluster/member order. EDGE_SUPERSEDES already exists in models.py. Not yet wired into ingest. --- src/aelfrice/dedup.py | 120 +++++++++++++++++++++++ tests/test_dedup_supersedes_writer.py | 136 ++++++++++++++++++++++++++ 2 files changed, 256 insertions(+) create mode 100644 tests/test_dedup_supersedes_writer.py diff --git a/src/aelfrice/dedup.py b/src/aelfrice/dedup.py index 85c4aed04..823617570 100644 --- a/src/aelfrice/dedup.py +++ b/src/aelfrice/dedup.py @@ -65,6 +65,11 @@ DEFAULT_JACCARD_MIN: Final[float] = 0.8 DEFAULT_LEVENSHTEIN_MIN: Final[float] = 0.85 DEFAULT_MAX_CANDIDATE_PAIRS: Final[int] = 5000 +# Write-gate for the #999 SUPERSEDES edge writer: per-belief cap on +# auto-written edges (the Exp-48 coverage-dilution guard, mirroring the +# relationship_detector default). Defined locally — dedup must not import +# relationship_detector (that module imports this one at load time). +DEFAULT_MAX_EDGES_PER_BELIEF: Final[int] = 8 # --- Similarity primitives --------------------------------------------- @@ -388,6 +393,121 @@ def dedup_audit( ) +# --- SUPERSEDES edge writer (#999 — the #197-deferred cluster hook) ------ + + +@dataclass(frozen=True) +class SupersedesWriteReport: + """Summary of one ``write_supersedes_edges`` run. + + ``n_clusters`` + Near-duplicate clusters returned by ``dedup_audit`` — the + candidate set this writer acts on. + + ``n_edges_written`` + Member→oldest edges newly written this run. + + ``n_edges_skipped_existing`` + Edges whose triple already existed (idempotency guard fired). + + ``n_edges_skipped_gated`` + Edges dropped because an endpoint hit ``max_edges_per_belief``. + """ + + n_clusters: int + n_edges_written: int + n_edges_skipped_existing: int + n_edges_skipped_gated: int + + +def write_supersedes_edges( + store: MemoryStore, + *, + jaccard_min: float = DEFAULT_JACCARD_MIN, + levenshtein_min: float = DEFAULT_LEVENSHTEIN_MIN, + max_candidate_pairs: int = DEFAULT_MAX_CANDIDATE_PAIRS, + max_edges_per_belief: int = DEFAULT_MAX_EDGES_PER_BELIEF, +) -> SupersedesWriteReport: + """Emit SUPERSEDES edges within near-duplicate clusters (#999). + + Activates the write-path ``dedup_audit`` documented but deferred + behind the #197 bench gate: within each duplicate cluster, the + **oldest** member (min ``created_at``, tie-break min ``id``) is the + SUPERSEDES *target*; every other member emits one directional edge + ``src = member`` → ``dst = oldest`` (the newer belief supersedes the + older one it duplicates). + + Wired into ingest only behind the default-off ``auto_detect`` flag + (``relationship_detector.is_auto_relationship_detection_enabled``); a + fresh install writes no edges and the #605/#897 scope decision stands. + + **Idempotent.** Each ``(member, oldest, SUPERSEDES)`` triple is checked + before insert and skipped if present. + + **Write-gated.** ``max_edges_per_belief`` caps how many SUPERSEDES + edges any one belief accretes; pre-existing edges count toward the + budget for a hard per-belief bound across re-runs. + + **Deterministic.** Clusters are sorted by ``representative_id`` and + members are lexicographically sorted, so the oldest-member resolution + and the write-gate survivors are stable across runs. + + Stdlib-only: no LLM, no embedding. Delegates clustering to + ``dedup_audit``. + """ + from aelfrice.models import Edge, EDGE_SUPERSEDES + + report = dedup_audit( + store, + jaccard_min=jaccard_min, + levenshtein_min=levenshtein_min, + max_candidate_pairs=max_candidate_pairs, + ) + + edges_per_belief: dict[str, int] = {} + n_written = 0 + n_skipped_existing = 0 + n_gated = 0 + for cluster in report.clusters: + members = [ + b + for mid in cluster.member_ids + if (b := store.get_belief(mid)) is not None + ] + if len(members) < 2: + continue + # Oldest member is the SUPERSEDES target (dedup.py cluster note). + oldest = min(members, key=lambda b: (b.created_at, b.id)) + for b in members: + if b.id == oldest.id: + continue + src_id, dst_id = b.id, oldest.id + if ( + edges_per_belief.get(src_id, 0) >= max_edges_per_belief + or edges_per_belief.get(dst_id, 0) >= max_edges_per_belief + ): + n_gated += 1 + continue + if store.get_edge(src_id, dst_id, EDGE_SUPERSEDES) is not None: + n_skipped_existing += 1 + edges_per_belief[src_id] = edges_per_belief.get(src_id, 0) + 1 + edges_per_belief[dst_id] = edges_per_belief.get(dst_id, 0) + 1 + continue + store.insert_edge( + Edge(src=src_id, dst=dst_id, type=EDGE_SUPERSEDES, weight=1.0) + ) + n_written += 1 + edges_per_belief[src_id] = edges_per_belief.get(src_id, 0) + 1 + edges_per_belief[dst_id] = edges_per_belief.get(dst_id, 0) + 1 + + return SupersedesWriteReport( + n_clusters=len(report.clusters), + n_edges_written=n_written, + n_edges_skipped_existing=n_skipped_existing, + n_edges_skipped_gated=n_gated, + ) + + @dataclass(frozen=True) class DedupConfig: """Resolved `[dedup]` section of `.aelfrice.toml`. diff --git a/tests/test_dedup_supersedes_writer.py b/tests/test_dedup_supersedes_writer.py new file mode 100644 index 000000000..b9f486557 --- /dev/null +++ b/tests/test_dedup_supersedes_writer.py @@ -0,0 +1,136 @@ +"""Unit tests for the #999 SUPERSEDES edge writer. + +Covers ``write_supersedes_edges`` (directional member→oldest edges within +near-duplicate clusters — the dedup write-path documented at dedup.py:160 +and deferred behind the #197 bench gate), idempotency, the per-belief +write-gate, and the determinism guarantee. + +All tests use a real ``MemoryStore(":memory:")`` — no mocks. +""" +from __future__ import annotations + +import hashlib + +import pytest + +from aelfrice.dedup import write_supersedes_edges +from aelfrice.models import ( + BELIEF_FACTUAL, + EDGE_SUPERSEDES, + LOCK_NONE, + Belief, +) +from aelfrice.store import MemoryStore + +# Three near-identical paraphrases — clear dedup's jaccard >= 0.8 AND +# levenshtein >= 0.85 thresholds, so they collapse into one cluster. +_BASE = "never push commits directly to the main branch" +_BASE_NOW = _BASE + " now" +_BASE_HERE = _BASE + " here" +_UNRELATED = "the harbor seals bask on the warm rocks at noon each day" + + +def _make_belief( + store: MemoryStore, + *, + belief_id: str, + content: str, + created_at: str, +) -> Belief: + b = Belief( + id=belief_id, + content=content, + content_hash=hashlib.sha256(content.encode()).hexdigest(), + alpha=1.0, + beta=1.0, + type=BELIEF_FACTUAL, + lock_level=LOCK_NONE, + locked_at=None, + created_at=created_at, + last_retrieved_at=None, + ) + store.insert_belief(b) + return b + + +def _supersedes_edges(store: MemoryStore) -> list[tuple[str, str]]: + """Return all SUPERSEDES edges as sorted (src, dst) tuples.""" + rows = store._conn.execute( # type: ignore[attr-defined] + "SELECT src, dst FROM edges WHERE type = ? ORDER BY src, dst", + (EDGE_SUPERSEDES,), + ).fetchall() + return [(r[0], r[1]) for r in rows] + + +@pytest.fixture +def store() -> MemoryStore: + return MemoryStore(":memory:") + + +def _seed_cluster(store: MemoryStore) -> None: + # b1 is the oldest → the SUPERSEDES target. ids sorted b1 < b2 < b3. + _make_belief(store, belief_id="b1", content=_BASE, created_at="2026-01-01T00:00:00Z") + _make_belief(store, belief_id="b2", content=_BASE_NOW, created_at="2026-02-01T00:00:00Z") + _make_belief(store, belief_id="b3", content=_BASE_HERE, created_at="2026-03-01T00:00:00Z") + + +# --------------------------------------------------------------------------- +# write_supersedes_edges — write / scope / idempotency +# --------------------------------------------------------------------------- + + +def test_writes_supersedes_edges_to_oldest(store: MemoryStore) -> None: + _seed_cluster(store) + report = write_supersedes_edges(store) + assert report.n_clusters == 1 + assert report.n_edges_written == 2 + # Both newer members point at the oldest (b1); direction is member→oldest. + assert _supersedes_edges(store) == [("b2", "b1"), ("b3", "b1")] + + +def test_idempotent_second_run_writes_nothing(store: MemoryStore) -> None: + _seed_cluster(store) + write_supersedes_edges(store) + report = write_supersedes_edges(store) + assert report.n_edges_written == 0 + assert report.n_edges_skipped_existing == 2 + assert _supersedes_edges(store) == [("b2", "b1"), ("b3", "b1")] + + +def test_no_cluster_writes_no_edges(store: MemoryStore) -> None: + _make_belief(store, belief_id="b1", content=_BASE, created_at="2026-01-01T00:00:00Z") + _make_belief(store, belief_id="b2", content=_UNRELATED, created_at="2026-02-01T00:00:00Z") + report = write_supersedes_edges(store) + assert report.n_clusters == 0 + assert report.n_edges_written == 0 + assert _supersedes_edges(store) == [] + + +# --------------------------------------------------------------------------- +# Determinism — byte-equal edge sets across two fresh stores +# --------------------------------------------------------------------------- + + +def test_determinism_byte_equal_edges() -> None: + def build() -> list[tuple[str, str]]: + s = MemoryStore(":memory:") + _seed_cluster(s) + write_supersedes_edges(s) + return _supersedes_edges(s) + + assert build() == build() + + +# --------------------------------------------------------------------------- +# Write-gate — per-belief edge cap (Exp-48 dilution guard) +# --------------------------------------------------------------------------- + + +def test_write_gate_caps_per_belief_edges(store: MemoryStore) -> None: + _seed_cluster(store) + # The oldest target (b1) is the dst of both edges; cap=1 lets only the + # first (b2→b1) through, gating b3→b1 once b1 hits its budget. + report = write_supersedes_edges(store, max_edges_per_belief=1) + assert report.n_edges_written == 1 + assert report.n_edges_skipped_gated == 1 + assert _supersedes_edges(store) == [("b2", "b1")] From 6839b3c04ba8d7c2c33aa31415ed6c7c0ffb0857 Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Tue, 23 Jun 2026 10:57:32 -0700 Subject: [PATCH 4/4] feat(ingest): wire SUPPORTS + SUPERSEDES writers into the auto-detect gate (#999) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extend the #988 default-off ingest block to run all three semantic-edge writers in fixed order (CONTRADICTS -> SUPPORTS -> SUPERSEDES) behind the same is_auto_relationship_detection_enabled() flag. Flag off → branch never entered, ingest byte-identical to today. Completes #999: the HRR-expand lane substrate now carries 3 edge classes, not 1. --- src/aelfrice/ingest.py | 17 +++--- tests/test_ingest_edge_type_expansion.py | 67 ++++++++++++++++++++++++ 2 files changed, 78 insertions(+), 6 deletions(-) create mode 100644 tests/test_ingest_edge_type_expansion.py diff --git a/src/aelfrice/ingest.py b/src/aelfrice/ingest.py index b84537b95..2c67ef493 100644 --- a/src/aelfrice/ingest.py +++ b/src/aelfrice/ingest.py @@ -296,20 +296,25 @@ def _ingest_turn_ids( anchor_text=anchor, )) - # #988: optionally build the semantic-edge substrate at ingest. Writes - # CONTRADICTS edges across the store for this turn's new beliefs so the - # graph lanes (HRR-expand #981, BFS) are no longer inert on benchmark - # corpora. Default-OFF (is_auto_relationship_detection_enabled): when - # off, this branch is never entered and ingest is byte-identical to - # today. Gated on `inserted` so corroboration-only turns skip the audit. + # #988/#999: optionally build the semantic-edge substrate at ingest. + # Writes CONTRADICTS (#988), SUPPORTS (REFINES verdicts, #999), and + # SUPERSEDES (dedup clusters, #999) edges across the store so the graph + # lanes (HRR-expand #981, BFS) are no longer starved on a CONTRADICTS-only + # graph. Default-OFF (is_auto_relationship_detection_enabled): when off, + # this branch is never entered and ingest is byte-identical to today. + # Gated on `inserted` so corroboration-only turns skip the audit. if inserted: + from aelfrice.dedup import write_supersedes_edges from aelfrice.relationship_detector import ( is_auto_relationship_detection_enabled, write_semantic_edges, + write_supports_edges, ) if is_auto_relationship_detection_enabled(): write_semantic_edges(store) + write_supports_edges(store) + write_supersedes_edges(store) return inserted diff --git a/tests/test_ingest_edge_type_expansion.py b/tests/test_ingest_edge_type_expansion.py new file mode 100644 index 000000000..a55920698 --- /dev/null +++ b/tests/test_ingest_edge_type_expansion.py @@ -0,0 +1,67 @@ +"""Ingest-wiring tests for the #999 SUPPORTS/SUPERSEDES edge writers. + +Verifies the default-off gate: with AELFRICE_AUTO_RELATIONSHIPS unset, +ingest writes no SUPPORTS/SUPERSEDES edges (byte-identical to today); with +it on, the two new writers run alongside the #988 CONTRADICTS writer. + +All tests use a real ``MemoryStore(":memory:")`` and the real +``ingest_turn`` path — no mocks. +""" +from __future__ import annotations + +import pytest + +from aelfrice.ingest import ingest_turn +from aelfrice.models import EDGE_SUPERSEDES, EDGE_SUPPORTS +from aelfrice.store import MemoryStore + +# REFINES (mutual-agreement) pair — same subject, agreeing modality, but +# too lexically distant for dedup's levenshtein floor (so SUPPORTS, not +# SUPERSEDES). +_ALWAYS = "the deployment script always runs the database migration step" +_ALWAYS_LAUNCH = _ALWAYS + " before the production launch window opens" +# Near-duplicate paraphrases — clear dedup thresholds → SUPERSEDES cluster. +_BASE = "never push commits directly to the main branch" +_BASE_NOW = _BASE + " now" +_BASE_HERE = _BASE + " here" + + +def _edge_count(store: MemoryStore, edge_type: str) -> int: + row = store._conn.execute( # type: ignore[attr-defined] + "SELECT COUNT(*) FROM edges WHERE type = ?", (edge_type,) + ).fetchone() + return int(row[0]) + + +def test_ingest_off_writes_no_new_edges( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.delenv("AELFRICE_AUTO_RELATIONSHIPS", raising=False) + s = MemoryStore(":memory:") + for text in (_ALWAYS, _ALWAYS_LAUNCH, _BASE, _BASE_NOW, _BASE_HERE): + ingest_turn(s, text, source="t", session_id="sess") + assert _edge_count(s, EDGE_SUPPORTS) == 0 + assert _edge_count(s, EDGE_SUPERSEDES) == 0 + + +def test_ingest_on_writes_supports_edge( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setenv("AELFRICE_AUTO_RELATIONSHIPS", "1") + s = MemoryStore(":memory:") + ingest_turn(s, _ALWAYS, source="t", session_id="sess") + ingest_turn(s, _ALWAYS_LAUNCH, source="t", session_id="sess") + assert _edge_count(s, EDGE_SUPPORTS) >= 1 + # Not a near-duplicate cluster → no SUPERSEDES. + assert _edge_count(s, EDGE_SUPERSEDES) == 0 + + +def test_ingest_on_writes_supersedes_edge( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setenv("AELFRICE_AUTO_RELATIONSHIPS", "1") + s = MemoryStore(":memory:") + ingest_turn(s, _BASE, source="t", session_id="sess") + ingest_turn(s, _BASE_NOW, source="t", session_id="sess") + ingest_turn(s, _BASE_HERE, source="t", session_id="sess") + assert _edge_count(s, EDGE_SUPERSEDES) >= 1