feat(ingest): extend edge substrate with SUPPORTS + SUPERSEDES (#999)

[robotrocketscience]

What

Extends the deterministic ingest edge substrate beyond CONTRADICTS-only
(#988) to also emit SUPPORTS and SUPERSEDES edges, so the
HRR-expand lane (#981/PR #997) traverses a graph with three edge classes
instead of one. Closes #999. Unblocks #1001 (the +HRR-expand ablation).

Spec: docs/design/feature-edge-type-expansion.md.

Key finding — both writers already existed, deferred

No new detector was needed:

• SUPPORTS ← the detector already computes a REFINES verdict
  (same-subject + agreeing modality) but feat(ingest): build the semantic-edge substrate via deterministic relationship-detection at ingest (default-off) — the real LoCoMo lever; reframes #981/#977 #988 wrote CONTRADICTS only.
  write_supports_edges turns the existing REFINES verdict into a
  symmetric SUPPORTS edge. EDGE_SUPPORTS already in models.py.
• SUPERSEDES ← dedup_audit already clusters near-duplicates and
  documented the write-path ("oldest member is the SUPERSEDES target",
  dedup.py:160) deferred behind the Deduplication module (dedup) — v2.0 evaluation #197 bench gate. write_supersedes_edges
  activates it: each newer cluster member → oldest, directional.
  EDGE_SUPERSEDES already in models.py.

Both run behind the existing default-off AELFRICE_AUTO_RELATIONSHIPS
gate, exactly as #988 activated the CONTRADICTS writer. Flag off → ingest
byte-identical to today. Keeps the #605/#897 determinism + narrow-surface
decision intact (stdlib-only, no LLM, no embedding, no default flip).

Properties (both writers)

• Deterministic: audit/cluster pair order; byte-equal edge table across runs.
• Idempotent: existing triple skipped.
• Write-gated: max_edges_per_belief (Exp-48 coverage-dilution guard),
  pre-existing edges count toward the per-belief budget across re-runs.

Commits (atomic)

1. docs(design) — spec memo
2. feat(ingest) — SUPPORTS writer (REFINES→SUPPORTS) + tests
3. feat(ingest) — SUPERSEDES writer (dedup clusters) + tests
4. feat(ingest) — wire both into the auto-detect gate + tests

Tests

16 new tests (SUPPORTS writer, SUPERSEDES writer, ingest on/off wiring),
each covering write / scope / idempotency / write-gate / determinism.
Full suite: 5393 passed, 66 skipped, 75 xfailed.

Out of scope

• CALLS/CITES/TESTS/IMPLEMENTS (no deterministic conversational signal).
• Default-on flip (reverses v3.0 PHILOSOPHY: natural-language-relatedness gate — deterministic vs embedding #605 — routed elsewhere).
• Incremental per-turn detection (perf(ingest): incremental per-turn edge detection (fix 25-40min/conv latency + max_candidate_pairs ~57% undercount) #1000).
• Running the ablation (eval: run the deferred +HRR-expand ablation arm on the #977 canonical sweep (gated on edge-type expansion) #1001, blocked on this).

Closes #999.

Summary by Sourcery

Extend ingest-time automatic relationship detection to emit SUPPORTS and SUPERSEDES edges alongside existing CONTRADICTS edges, based on existing deterministic audits and deduplication, while preserving default-off gating and determinism.

New Features:

• Add a SUPPORTS edge writer that converts REFINES verdicts from the relationship audit into symmetric SUPPORTS edges with per-belief write limits.
• Add a SUPERSEDES edge writer that emits directional member-to-oldest edges within near-duplicate clusters discovered by deduplication, with per-belief write limits.
• Wire the new SUPPORTS and SUPERSEDES writers into the ingest pipeline behind the existing auto-relationships feature flag so they run together with the CONTRADICTS writer when enabled.

Documentation:

• Add a design spec describing the ingest edge-type expansion to SUPPORTS and SUPERSEDES and how they integrate with existing detectors and ingest wiring.

Tests:

• Add unit tests for the SUPPORTS writer covering writes, scope, idempotency, determinism, and write-gating behavior.
• Add unit tests for the SUPERSEDES writer covering cluster-based writes, idempotency, determinism, and per-belief write-gating.
• Add ingest integration tests verifying that auto-relationships gating remains default-off and that SUPPORTS and SUPERSEDES edges are written appropriately when enabled.

Summary by CodeRabbit

• New Features

  • Added two new semantic edge types (SUPPORTS and SUPERSEDES) to enhance belief relationship detection, available via the AELFRICE_AUTO_RELATIONSHIPS feature flag.
  • SUPPORTS edges identify refined belief relationships; SUPERSEDES edges link near-duplicate beliefs.

• Tests

  • Added comprehensive test coverage for new edge type functionality and ingest integration.

[sourcery-ai]

Reviewer's Guide

Extends the ingest-time auto relationship substrate so, when the existing AELFRICE_AUTO_RELATIONSHIPS gate is enabled, it now also emits SUPPORTS edges from existing REFINES verdicts and SUPERSEDES edges from dedup near-duplicate clusters, with deterministic, idempotent writers plus tests and a design doc.

Sequence diagram for ingest-time CONTRADICTS/SUPPORTS/SUPERSEDES edge writing

sequenceDiagram
    participant Ingest as _ingest_turn_ids
    participant RelationshipDetector
    participant Dedup
    participant MemoryStore

    Ingest->>MemoryStore: insert_turn_beliefs()
    Ingest->>Ingest: [inserted > 0]
    alt [auto relationships enabled]
        Ingest->>RelationshipDetector: is_auto_relationship_detection_enabled()
        alt [True]
            Ingest->>RelationshipDetector: write_semantic_edges(store)
            Ingest->>RelationshipDetector: write_supports_edges(store)
            Ingest->>Dedup: write_supersedes_edges(store)
        else [False]
            Ingest->>Ingest: skip edge writers
        end
    else [inserted == 0]
        Ingest->>Ingest: skip audit and edge writers
    end

Loading

File-Level Changes

Change	Details	Files
Add deterministic SUPPORTS edge writer based on existing REFINES verdicts and expose it from the relationship detector module.	Introduce SupportsWriteReport dataclass to summarize SUPPORTS edge write runs. Implement write_supports_edges that filters REFINES verdicts from relationships_audit, canonicalizes symmetric pairs, enforces a per-belief edge cap, and writes EDGE_SUPPORTS edges idempotently. Export SupportsWriteReport and write_supports_edges via all for external use. Add unit tests covering write behavior, idempotency, determinism, and write-gate semantics for SUPPORTS edges.	src/aelfrice/relationship_detector.py tests/test_relationship_detector_supports_writer.py
Add deterministic SUPERSEDES edge writer driven by dedup near-duplicate clusters and expose it from the dedup module.	Define DEFAULT_MAX_EDGES_PER_BELIEF constant in dedup to gate auto-written SUPERSEDES edges without importing relationship_detector. Introduce SupersedesWriteReport dataclass to summarize SUPERSEDES edge write runs. Implement write_supersedes_edges that resolves oldest cluster member as target, writes directional member→oldest EDGE_SUPERSEDES edges with per-belief caps and idempotency, and skips degenerate/small clusters. Add unit tests for write_supersedes_edges covering cluster behavior, idempotency, determinism, and write-gate semantics.	src/aelfrice/dedup.py tests/test_dedup_supersedes_writer.py
Wire new SUPPORTS and SUPERSEDES writers into ingest behind the existing auto relationship detection feature gate and document the design.	Extend ingest _ingest_turn_ids to import and invoke write_supports_edges and write_supersedes_edges alongside write_semantic_edges when is_auto_relationship_detection_enabled is true and new beliefs were inserted. Ensure the new writers respect the existing default-off AELFRICE_AUTO_RELATIONSHIPS environment flag so ingest remains byte-identical when disabled. Add integration tests that exercise ingest_turn with the feature flag on and off, asserting SUPPORTS/SUPERSEDES edge counts for representative content pairs. Add a design document explaining the motivation, design, and constraints for adding SUPPORTS and SUPERSEDES edge types to the ingest substrate.	src/aelfrice/ingest.py tests/test_ingest_edge_type_expansion.py docs/design/feature-edge-type-expansion.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#999	Extend the deterministic ingest relationship substrate to emit SUPPORTS and SUPERSEDES edges (in addition to existing CONTRADICTS), using deterministic detectors and preserving idempotency.	✅
#999	Keep SUPPORTS and SUPERSEDES emission behind the existing default-off auto-relationship detection flag so that ingest behavior is unchanged when the flag is off, and avoid regressions to existing CONTRADICTS behavior.	✅
#999	Add determinism tests for the new SUPPORTS and SUPERSEDES writers, mirroring the existing CONTRADICTS determinism test to ensure byte-equal edge tables across runs and stable tie-breaking.	✅

Possibly linked issues

• feat(ingest): extend deterministic edge substrate beyond CONTRADICTS (SUPPORTS/SUPERSEDES) to feed the HRR-expand lane #999: Yes. The PR adds deterministic SUPPORTS/SUPERSEDES writers, tests, and ingest wiring exactly matching the issue’s requirements.
• feat(ingest): extend deterministic edge substrate beyond CONTRADICTS (SUPPORTS/SUPERSEDES) to feed the HRR-expand lane #999: They match: the issue asks for a denser deterministic edge substrate; the PR adds SUPPORTS and SUPERSEDES edges.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Adds two new semantic edge writers—write_supports_edges (derived from REFINES audit verdicts) and write_supersedes_edges (derived from dedup clusters)—behind the existing default-off AELFRICE_AUTO_RELATIONSHIPS flag. Both writers are wired into _ingest_turn_ids in ingest.py. A design spec, both writer implementations with idempotency and per-belief write gating, and full test suites are included.

Changes

SUPPORTS and SUPERSEDES edge substrate expansion

Layer / File(s)	Summary
Feature design spec docs/design/feature-edge-type-expansion.md	New spec defining the SUPPORTS writer (REFINES-slice, symmetric canonicalized edges) and SUPERSEDES writer (dedup clusters, directional oldest-target edges), ingest wiring order, determinism/test plan, and explicit out-of-scope list.
SUPPORTS edge writer src/aelfrice/relationship_detector.py, tests/test_relationship_detector_supports_writer.py	write_supports_edges audits REFINES pairs and inserts canonical EDGE_SUPPORTS edges (min(id)→max(id)) with idempotency and max_edges_per_belief gating. SupportsWriteReport and write_supports_edges added to __all__. Tests cover basic write, idempotency, contradicts/unrelated no-op, determinism, and write-gate capping.
SUPERSEDES edge writer src/aelfrice/dedup.py, tests/test_dedup_supersedes_writer.py	write_supersedes_edges runs dedup_audit, selects oldest belief per cluster as target, inserts directional EDGE_SUPERSEDES edges with idempotency and per-belief gating. DEFAULT_MAX_EDGES_PER_BELIEF constant and SupersedesWriteReport added. Tests cover direction-to-oldest, idempotency, no-cluster no-op, determinism, and write-gate capping.
Ingest wiring and integration tests src/aelfrice/ingest.py, tests/test_ingest_edge_type_expansion.py	_ingest_turn_ids now imports and calls write_supports_edges and write_supersedes_edges alongside write_semantic_edges inside the existing AELFRICE_AUTO_RELATIONSHIPS guard. Integration tests verify flag-off no-op and flag-on SUPPORTS/SUPERSEDES edge production via direct SQL counts.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• feat(ingest): extend deterministic edge substrate beyond CONTRADICTS (SUPPORTS/SUPERSEDES) to feed the HRR-expand lane #999: This PR directly implements the SUPPORTS and SUPERSEDES edge writers with deterministic, default-off behavior behind AELFRICE_AUTO_RELATIONSHIPS, satisfying all stated acceptance criteria.
• decide: denser/typed semantic-edge substrate beyond CONTRADICTS-only for HRR-expand/BFS lanes #998: The design decision to expand the semantic-edge substrate beyond CONTRADICTS-only is directly realized by this PR's implementation.

Possibly related PRs

• robotrocketscience/aelfrice#990: Introduced the original write_semantic_edges/CONTRADICTS wiring in ingest.py behind AELFRICE_AUTO_RELATIONSHIPS; this PR extends that exact block to additionally call write_supports_edges and write_supersedes_edges.

Suggested labels

attn:review

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 24.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main feature: extending edge substrate with SUPPORTS and SUPERSEDES edges (#999), directly matching the PR's primary objective.
Description check	✅ Passed	The description comprehensively covers summary, linked issues, type of change, verification, test plan, and notes; all major sections from the template are present and substantive.
Linked Issues check	✅ Passed	The PR fully addresses #999's requirements: extends deterministic ingest to emit SUPPORTS and SUPERSEDES edges, maintains default-off gating, provides determinism tests, and ensures no regression when disabled.
Out of Scope Changes check	✅ Passed	All changes are scoped to SUPPORTS and SUPERSEDES writers, their integration into ingest, design documentation, and corresponding tests; the PR explicitly defers CALLS/CITES/TESTS/IMPLEMENTS and default-on flip.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-999-edge-types-supports-supersedes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 734 changed lines (limit: 200)
• 7 changed files (limit: 3)

Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated attn:merge-conflict cycles (see #602). When practical, split into smaller PRs that each touch a focused surface.

This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the size:override label and this comment will be removed on the next push.

[sourcery-ai]

Hey - I've left some high level feedback:

• The per-belief write cap is now defined separately in relationship_detector and dedup (DEFAULT_MAX_EDGES_PER_BELIEF); consider centralizing this value (e.g., in a shared config/module that avoids circular imports) so the cap cannot silently diverge between SUPPORTS and SUPERSEDES writers.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The per-belief write cap is now defined separately in `relationship_detector` and `dedup` (`DEFAULT_MAX_EDGES_PER_BELIEF`); consider centralizing this value (e.g., in a shared config/module that avoids circular imports) so the cap cannot silently diverge between SUPPORTS and SUPERSEDES writers.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[robotrocketscience]

[claim:review:idnn:2026-06-23T18:10:12Z]

[github-actions]

merge-train: merged 6839b3c → main via FF push.

[robotrocketscience]

Review: APPROVE

Verified against github/main:

• Faithful mirror of the accepted feat(ingest): build the semantic-edge substrate via deterministic relationship-detection at ingest (default-off) — the real LoCoMo lever; reframes #981/#977 #988 CONTRADICTS writer. write_supports_edges reuses write_semantic_edges's exact pattern — weight=1.0, canonical src=min/dst=max, per-belief write-gate (existing edges count toward budget), idempotency guard, self-pair counter.
• All symbols resolve on main: LABEL_REFINES (detector emits the verdict at relationship_detector.py:336), EDGE_SUPPORTS/EDGE_SUPERSEDES (models.py:32/35), store.get_edge/insert_edge. No new detector — both writers activate already-deferred verdicts (REFINES → SUPPORTS, dedup clusters → SUPERSEDES).
• Determinism claims are backed upstream: relationships_audit sorts pairs by (belief_a_id, belief_b_id) (:460); dedup_audit sorts member_ids lexicographically (:305) and clusters by representative_id (:312). Write-gate survivors are therefore stable across runs.
• SUPERSEDES is correctly directional (member → oldest, min created_at tie-break min id), distinct from the symmetric SUPPORTS/CONTRADICTS — semantically right.
• Default-off preserved: both writers gated behind is_auto_relationship_detection_enabled; flag off → ingest byte-identical, v3.0 PHILOSOPHY: natural-language-relatedness gate — deterministic vs embedding #605/decide: revisit #605 deterministic-substrate ratification in light of v3.0.1 bench delta #897 scope decision intact.

CI fully green (pytest 3.12/3.13, bench-smoke, all gates). FF-clean on main, 4 atomic signed commits. Discretion grep clean. Tests cover label discrimination, idempotency, determinism, write-gate, and ingest on/off wiring.

Adding ready-to-merge.

[robotrocketscience]

[release:review:idnn:2026-06-23T18:12:52Z]

[github-actions]

merge-train: merged 6839b3c → main via FF push.