refactor(storage): collapse duplicated session-write authority gate to one function

[Sinity]

Summary

Consolidates a duplicated revision-authority refusal check that lived
independently in two production session-write paths into one function,
revision_authority_refuses_write (storage/sqlite/archive_tiers/ingest_precedence.py).

Problem

ArchiveStore._write_parsed_precedence_result (archive_tiers/revision_governance.py,
the real implementation behind write_parsed_for_retained_raw/write_raw_and_parsed,
used by the one-shot importer and the revision-authority-aware live batch path)
and _write_session (pipeline/services/ingest_batch/_core.py, the daemon's
default batch-ingest write path for most non-drive origins) each hand-carried
their own copy of two checks: "has this session_id already been claimed by an
accepted raw_revision_heads cohort winner" and "is this raw's own
raw_session_memberships decision recorded ambiguous".

polylogue-c737 is the concrete symptom this duplication produced: the live
archive had 28 aistudio-drive cohorts genuinely recorded ambiguous (correctly
refused a winner) whose sessions were nonetheless materialized in index.db
with 641 attachments stuck unfetched. PR #3397 fixed the ambiguous-membership
refusal in _write_parsed_precedence_result; PR #3398 then had to independently
re-derive and hand-apply the identical fix to _write_session because it was a
separate copy that had never been patched — "the signature of duplicated
semantics rather than a missing check" (polylogue-aggz Invariant 2).

I read both write functions in full (revision_governance.py ~2900 lines,
ingest_batch/_core.py ~1970 lines) before touching anything, and traced real
callers rather than assuming duplication from file/line coordinates alone. Note:
the coordinator's initial lead (_write_parsed_precedence_result/write_parsed
duplicated between revision_governance.py and archive.py) turned out to be a
false positive — archive.py's copies are genuine one-line delegating methods
to the sole implementation in revision_governance.py, exactly as that module's
own docstring documents (an already-completed extraction, not a live
duplication). The real duplication was the _core.py / revision_governance.py
pair named in polylogue-c737's own closure notes as a "known sibling hole."

Solution

• Added revision_authority_refuses_write(conn, source_conn, *, session_id, raw_id, provider_session_id) to ingest_precedence.py — the module that
  already owns the sibling precedence primitives shared by these same two
  write paths (should_skip_stale_replace, browser_capture_precedence,
  session_has_parser_ingest_flag, stored_message_count), so this is a
  continuation of an established consolidation pattern (see that module's own
  should_skip_stale_replace docstring, itself a prior 3-copy→1 consolidation
  for polylogue-t83e), not a new one-off shim.
• _write_parsed_precedence_result and _write_session now call this one
  function instead of carrying their own inline SQL + comment block. The two
  duplicated blocks (~59 lines and ~65 lines including their explanatory
  comments) are deleted, not left as bypassable dead alternates, per this
  repo's surgical-renewal rule.
• session_id/raw_id/provider_session_id are required keyword arguments
  with no defaults — a caller cannot invoke the gate without supplying
  identity, and (per the anti-vacuity check below) cannot silently skip
  calling it without a production regression test failing.

Acceptance criteria (Invariant 2 only — this lane's scope per coordinator reshape)

• "Exactly one code path can write a session, and it cannot be called without
  authority": partially satisfied. The specific duplicated-semantics bug
  shape polylogue-c737/fix(storage): refuse a precedence write for a raw recorded ambiguous membership #3397/fix(storage): scope the ambiguous-membership refusal to the membership written #3398 exhibited (independently hand-maintained
  copies of the revision-authority refusal check) is now structurally
  impossible — there is exactly one implementation of that refusal decision.
  This PR does not merge the two write paths themselves into one function;
  _write_parsed_precedence_result and _write_session remain separate
  entry points serving genuinely different callers (one-shot importer /
  revision-authority-aware live batch vs. the daemon's default batch-ingest
  path), each still carrying its own freshness/browser-capture-precedence
  logic downstream of the shared gate. A full single-function merge of the two
  write paths is a larger, riskier change spanning ~4900 lines across two
  files and many call sites; I judged landing this smaller, verified slice
  safer than forcing that merge in one lane, per this lane's explicit
  "acceptable to land a smaller slice" guidance.
• "At least two existing special-case paths are DELETED, not merely
  bypassed": satisfied for this slice — both inline duplicate-check blocks
  (with their explanatory comments) are deleted from revision_governance.py
  and ingest_batch/_core.py.

Anti-vacuity

Production callers exercised: ArchiveStore.write_parsed_for_retained_raw
(→ _write_parsed_precedence_result) is reached from the one-shot importer
(pipeline/services/archive_ingest.py) and the revision-authority-aware live
batch path; _write_session is reached from the daemon's default batch-ingest
path (_write_session_entry → _process_ingest_batch_sync, the daemon's
primary write path for most non-drive origins).

Mutation proof (temporarily replacing each call site's
if revision_authority_refuses_write(...): ... with if False: ..., one at a
time, then reverting):

• revision_governance.py mutation → tests/unit/storage/test_revision_replay.py::test_precedence_write_refuses_a_raw_recorded_ambiguous fails (assert (1,) == (0,), i.e. the ambiguous raw's session gets written).
• ingest_batch/_core.py mutation → tests/unit/pipeline/test_ingest_batch.py::test_write_session_refuses_a_raw_recorded_ambiguous_membership fails (assert True is False).
  Both pass again once reverted (see Verification below for the clean run).

Follow-ups (not in scope here)

• A genuine single-function merge of _write_parsed_precedence_result and
  _write_session into one literal chokepoint (rather than one shared
  authority-gate they both call) remains open, if the full Invariant 2 shape
  is wanted. I have not filed a new bead for this per this lane's bd-write
  restrictions (worktree .beads/issues.jsonl reimport hazard) — reporting it
  here for the coordinator to file.
• ArchiveStore.write_parsed/SessionRepository.save_parsed_session is a
  third code path that writes directly to sessions via
  write_parsed_session_to_archive with no revision-authority
  consultation at all (no raw_id, no governed-head check, no ambiguous-
  membership check). Traced its only production caller
  (repository_writes.py::save_parsed_session) and that method itself has no
  real production caller — only a docstring example and test infrastructure
  reference it. Currently dead in the real ingest pipeline, but it is a public
  method reachable from SessionRepository/ArchiveStore, so it remains a
  structurally-possible fourth way to write a session bypassing authority if
  anything ever calls it for real. Worth a follow-up bead to either delete it
  or route it through the same gate.

Verification

python -m devtools test tests/unit/storage/test_revision_replay.py \
  tests/unit/pipeline/test_ingest_batch.py \
  polylogue/storage/sqlite/archive_tiers/ingest_precedence.py \
  polylogue/storage/sqlite/archive_tiers/revision_governance.py \
  polylogue/pipeline/services/ingest_batch/_core.py \
  tests/unit/storage/test_archive_tiers_archive.py
# 127 passed

python -m devtools verify --quick
# exit_code: 0 (ruff format/check, mypy --strict, render all --check, layering, closure-matrix, schema policies)

Ref polylogue-aggz

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 56 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: 4248232e-3550-4d87-9838-6826419531d3

📥 Commits

Reviewing files that changed from the base of the PR and between 5d449f9 and ff4b807.

📒 Files selected for processing (3)

• polylogue/pipeline/services/ingest_batch/_core.py
• polylogue/storage/sqlite/archive_tiers/ingest_precedence.py
• polylogue/storage/sqlite/archive_tiers/revision_governance.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.}