fix(storage): quarantine real cycles in the live session_links resolver

[Sinity]

Summary

Ports cycle detection + quarantine into the sole production writer of session_links rows, so a genuine cycle in the parent chain is now detected and recorded with evidence instead of silently relying on recursion-guard short-circuits.

Problem

session_links.status/.method are declared vocabulary (TopologyEdgeStatus), but a live-archive measurement (2026-07-28, index v43, 18,871 sessions) found every one of 9,179 topology edges had empty status/method. method is already populated as of #3390 (2026-07-30, landed before this bead's structural audit); status stayed NULL on every row because nothing in the live write path ever detects or records a cycle.

A 2026-08-03 structural audit (polylogue-structural-audit-2026-08-03.html) found the real gap is worse than an unwritten column: a full cycle-detection + quarantine engine already exists at storage/sqlite/queries/session_links.py (_would_create_cycle, _quarantine_link, status='quarantined' + evidence JSON) but has zero production callers — it is exercised only by tests/unit/insights/test_topology_cycle_rejection.py, a test-only surface certifying behavior production code cannot exhibit. The live writer (write_parsed_session_to_archive -> _resolve_session_graph / _resolve_outbound_session_links, storage/sqlite/archive_tiers/write.py) resolves every matching parent edge unconditionally; a real cycle is only ever avoided by _refresh_session_projection's seen-set short-circuit and _composed_db_signatures' visited-set truncation, which silently pick an arbitrary root/branch point on a real cycle instead of persisting evidence of the rejected edge, making root/branch projections order-dependent and arbitrary.

Given polylogue-5dfu already narrowed TopologyEdgeStatus to just REPAIRED/QUARANTINED (NULL = ordinary resolved/unresolved, not "missing data"), the correct fix is not "every row must carry a non-NULL status" — it's "when a cycle actually occurs, the closing edge must be quarantined with evidence, and this must happen in the live path, not only in dead test-only code."

Solution

• Ported _would_create_cycle (walks sessions.parent_session_id upward from a proposed parent, bounded by a 1024-step budget, matching the dead engine's algorithm) and _quarantine_link (_quarantine_session_link here) as synchronous sqlite3-based helpers in storage/sqlite/archive_tiers/write.py, next to the functions they protect.
• Wired cycle checking into both live resolution entry points:
  • _resolve_outbound_session_links (a session resolving its own parent reference) now evaluates each unresolved candidate individually instead of one blanket UPDATE, cycle-checking before resolving.
  • The inbound-child loop inside _resolve_session_graph (a session resolving pending children that reference it as their parent) does the same per child.
• A candidate whose resolution would close a loop is quarantined (status='quarantined', evidence_json recording {reason, cycle_path, detected_at_ms}) instead of resolved; its parent_session_id projection stays NULL, so composition/ancestry walks degrade visibly (the session surfaces as its own root) rather than silently entering the cycle.
• Both entry points now also filter on status IS NULL (in addition to resolved_dst_session_id IS NULL), so a quarantined edge is never reconsidered on a later write — idempotent by construction.

Alternatives rejected

• Retargeting tests/unit/insights/test_topology_cycle_rejection.py (621 lines) and the session_links-dependent slice of tests/unit/storage/test_delegations_view.py off the dead async engine, and deleting storage/sqlite/queries/session_links.py, is explicitly not done in this PR. That's a large, separable retarget-and-delete step (both files currently pass, unchanged, because this PR only adds behavior to the live path and does not touch the dead module) and is called out as follow-up scope below rather than rushed into this PR.

Verification

• New tests: tests/unit/storage/test_topology_cycle_quarantine_live.py — reproduces a genuine cross-ingest two-node cycle (A lands root, B lands as A's child and resolves immediately, A is then re-ingested claiming B as its parent), a self-referential edge, and a non-cyclic diamond-DAG control case (B and C both point at D — a legitimate shared parent, must resolve cleanly, not be mistaken for a cycle), all through the real write_parsed_session_to_archive path.
• Confirmed red without the write.py change: 2 of 3 new tests failed with assert None == 'quarantined' (stashed the fix out, reran, restored it).
• devtools test tests/unit/storage/test_topology_cycle_quarantine_live.py tests/unit/storage/test_lineage_normalization.py tests/unit/storage/test_session_topology.py tests/unit/storage/test_topology_edges.py tests/unit/storage/test_archive_tiers_write.py tests/unit/storage/test_bulk_fts_prefix_reextract.py — 142 passed.
• ruff check / ruff format --check / mypy --strict clean on both touched files.
• devtools verify --quick — exit 0.

Acceptance criteria (polylogue-4ts.10)

1. "Every session_links row written by resolve_session_links_for_session carries a TopologyEdgeStatus value and a method token" — misframed by polylogue-5dfu's prior narrowing: method is satisfied (populated since feat(archive): index v46 wire-evidence batch, free-threaded-only runtime, parse-failure recovery #3390); status legitimately stays NULL for ordinary resolved/unresolved edges (that's the narrowed vocabulary's intent) and is now populated (quarantined) exactly when a cycle is detected, which is the actual gap this bead's own structural-audit note identified.
2. "Existing rows acquire status through ordinary derived-tier rebuild, not a bespoke backfill script" — satisfied: this is a derived-tier (index.db) behavior change with no migration; a polylogue ops reset --index && polylogued run naturally re-derives status/method for every row through the now-fixed live path.
3. "A reader can filter edges by status, and composition refuses (or degrades visibly) on a non-resolved parent rather than silently composing" — satisfied for composition (a quarantined child's parent_session_id stays NULL, so it surfaces as its own root); a dedicated reader/insight surface for quarantined-edge counts is deferred (the dead engine's count_quarantined_session_links is one candidate to port, left for the follow-up retarget work below).
4. "Live re-measure shows zero empty status/method rows and a status distribution consistent with the 222 unresolved-destination rows" — not independently re-measured against the live archive in this PR (no access to /realm/db/polylogue from this worktree); the mechanism this AC depends on is now live, so a follow-up index rebuild + re-measure is the natural next step, not additional code here.

Remaining polylogue-4ts.10 scope (follow-up)

• Retarget tests/unit/insights/test_topology_cycle_rejection.py and the session_links-dependent parts of tests/unit/storage/test_delegations_view.py at the live path (this PR's new test file demonstrates the pattern), then delete storage/sqlite/queries/session_links.py (dead code, zero production callers) once nothing references it.
• A read surface to filter/count quarantined edges (AC The gmd CLI monolith is blocking richer render surfaces #3's "reader can filter" half).
• Live-archive re-measure after an index rebuild (AC refactor: split CLI into command modules and add HTML preview output #4).

Ref polylogue-4ts.10

[coderabbitai]

Warning

Review limit reached

@Sinity, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 25 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 88453b4a-8dfd-4588-8c23-b0b4d1a26c29

📥 Commits

Reviewing files that changed from the base of the PR and between 5cea156 and 9289798.

📒 Files selected for processing (2)

• polylogue/storage/sqlite/archive_tiers/write.py
• tests/unit/storage/test_topology_cycle_quarantine_live.py

---

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