fix: exclude speculative phantoms from retention promotion (#1132)

[robotrocketscience]

What

Excludes speculative-origin phantoms from the corroboration-driven retention
promotion (find_promotable_snapshots → doctor.promote_retention).

Refs #1132 (Q1). The issue stays open; the promotion-opportunity detector (Q2)
lands in a follow-up PR and closes it.

Why

find_promotable_snapshots promotes any retention_class='snapshot' belief with
≥3 corroborations across ≥2 distinct sessions (no inbound CONTRADICTS) to
retention_class='fact'. Phantoms ingest with retention_class='snapshot'
(wonder_ingest, wonder/lifecycle.py), and the query filtered on
retention_class but not on origin. So a phantom corroborated ≥3×/≥2 sessions
was eligible for a count-driven flip to durable fact retention — the exact
trigger shape the ratified #229 rule (v2_phantom_promotion_trigger.md) rejects
on the origin axis ("promote on N feedback / retrieval-count … These are
non-triggers").

retention_class (durability policy) and origin (trust label) are orthogonal
axes, so this was not a logical contradiction with #229 — but it let a
speculative belief advance on a corroboration count alone via a different axis,
which is against the spirit of the ratified rule and was undocumented at the
intersection. In practice it is manual-opt-in (aelf doctor --promote-retention,
nothing auto-invokes it) so it has almost certainly never fired, but the guard
is correct and cheap.

Change

• store.find_promotable_snapshots: add AND b.origin != ?
  (bound to ORIGIN_SPECULATIVE), matching the existing parameterized-origin
  idiom in store.py. Docstring updated to state the guard and its R&D: phantom promotion — origin path is 0-by-design (#229); retention path reaches speculative rows on a count trigger #1132/[v2.0] Phantom promotion-trigger rule — three rejected naive triggers, need a benchmarked rule #229
  rationale.
• Regression tests (test_doctor_promote_retention.py):
  • test_promotable_excludes_speculative_origin_phantoms — a phantom with a
    qualifying corroboration profile (N=3 / 3 sessions / no CONTRADICTS) is
    excluded; contrast-documented against the existing
    test_promotable_returns_qualifying_belief (identical profile, non-speculative
    origin, IS promotable).
  • test_promote_retention_leaves_phantom_untouched — end-to-end:
    promote_retention finds 0 candidates and leaves the phantom's
    retention_class='snapshot' with no retention_promotion feedback row.

Both new tests were confirmed to fail without the one-line guard and pass with
it. Retention/origin orthogonality is preserved for every non-speculative origin.

Summary by Sourcery

Exclude speculative-origin phantoms from corroboration-based retention promotion and ensure they cannot be auto-upgraded from snapshot to fact.

Bug Fixes:

• Prevent speculative-origin phantoms from being selected by find_promotable_snapshots for retention promotion.
• Ensure promote_retention does not change retention_class or record retention_promotion feedback events for speculative-origin phantoms.

Tests:

• Add regression tests verifying speculative-origin phantoms are excluded from promotable snapshots despite qualifying corroborations.
• Extend test belief factory helpers to support configuring origin and belief type for targeted retention-promotion scenarios.

Summary by CodeRabbit

• Bug Fixes

  • Prevented speculative-origin beliefs from being incorrectly promoted during retention promotion.
  • Ensured excluded beliefs remain unchanged and do not generate synthetic promotion feedback.

• Tests

  • Expanded retention-promotion coverage for speculative and phantom beliefs.
  • Added validation for promotion eligibility and resulting feedback records.

[sourcery-ai]

Reviewer's Guide

This PR tightens the retention promotion logic so that corroboration-driven promotion from snapshot to fact explicitly excludes speculative-origin phantoms, and adds regression tests to cover both the store query and the end-to-end doctor flow.

Sequence diagram for doctor.promote_retention excluding speculative-origin phantoms

sequenceDiagram
    actor User
    participant Doctor
    participant Store

    User ->> Doctor: promote_retention(min_corroborations, min_sessions)
    Doctor ->> Store: find_promotable_snapshots(min_corroborations, min_sessions)
    Store -->> Doctor: promotable_beliefs_non_speculative
    Doctor ->> Doctor: [for each promotable belief, set retention_class to fact]

Loading

File-Level Changes

Change	Details	Files
Exclude speculative-origin beliefs from corroboration-driven snapshot-to-fact retention promotion.	Extend promotion rule documentation in the store query docstring to include an origin != 'speculative' guard and explain the R&D: phantom promotion — origin path is 0-by-design (#229); retention path reaches speculative rows on a count trigger #1132/[v2.0] Phantom promotion-trigger rule — three rejected naive triggers, need a benchmarked rule #229 rationale. Amend the SQL used by the snapshot promotion finder to add an origin != ? predicate alongside the existing retention/corroboration constraints. Update SQL parameter binding so the origin constant is passed before corroboration/session thresholds.	src/aelfrice/store.py
Add regression coverage ensuring speculative phantoms are not selected nor mutated by retention promotion, and adjust test helpers to model origin and belief type.	Extend the test belief factory helper with origin and belief_type parameters and import the required constants. Add a unit test that constructs a speculative-origin phantom with qualifying corroborations and asserts it is not returned as promotable. Add an end-to-end doctor test that runs retention promotion on such a phantom and asserts no promotion, no retention-class flip, and no promotion feedback events are recorded.	tests/test_doctor_promote_retention.py

Possibly linked issues

• R&D: phantom promotion — origin path is 0-by-design (#229); retention path reaches speculative rows on a count trigger #1132: The PR directly implements the issue’s Q1 decision: add an origin!='speculative' guard to retention promotion.

---

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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a13b9556-5859-45ed-b1e8-61e8b7170cbc

📥 Commits

Reviewing files that changed from the base of the PR and between 2a608b1 and 1e06c11.

📒 Files selected for processing (2)

• src/aelfrice/store.py
• tests/test_doctor_promote_retention.py

---

📝 Walkthrough

Walkthrough

Snapshot retention promotion now excludes speculative-origin beliefs through an additional SQL predicate. Tests add configurable belief construction and verify speculative phantom beliefs are neither selected nor promoted or given promotion feedback.

Changes

Retention promotion filtering

Layer / File(s)	Summary
Promotion eligibility filter src/aelfrice/store.py	find_promotable_snapshots documents and enforces exclusion of origin='speculative' beliefs.
Promotion regression coverage tests/test_doctor_promote_retention.py	Belief fixtures accept configurable origins and types; tests verify speculative phantoms remain unchanged and produce no promotion feedback.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• Issue 1132 — The change implements the recommended exclusion of speculative-origin beliefs and adds regression tests.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: blocking speculative phantoms from retention promotion.
Description check	✅ Passed	It covers the summary, issue reference, rationale, code changes, and regression tests, even though the template headings aren't followed exactly.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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 fix/issue-1132-exclude-speculative-retention

---

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.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

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.}

[github-actions]

merge-train: merged 1e06c11 → main via FF push.