feat: what you pay for, against what FC actually follows (387 C4)

Reconciliation in Subscriptions, asymmetric on purpose. Subscriptions FC does not follow get a per-row add; sources the roster cannot account for are REPORT ONLY (operator decision) and link to the list on the same page. No one-click disable, so no disabled-reason column and no migration.

The membership<->source join lands as a SHARED resolver in membership_roster, not inline here: E4 now uses it as its negative check, so the two features cannot give different answers to 'is this membership already tracked?'. Keys on the exact cached campaign id FIRST and the URL handle only as fallback, because the id is written only after a source has been walked once. Read via any <platform>_campaign_id override rather than naming Patreon's, per rule 169.

The report-only bucket is gated on roster freshness and carries a per-row basis, so 'your membership says former patron', 'we know this id and it is absent', and 'we only have a handle' stay three different sentences. has_paid_access None never reads as lapsed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LNXXULQDjVZmbuNa2G9mD9

backend/app/api/sources.py

@@ -7,7 +7,9 @@ from ..extensions import get_session
 from ..models import DownloadEvent, MembershipSync, PlatformMembership, Source
 from ..services.artist_membership_service import ArtistMembershipService
 from ..services.artist_membership_service import rescan as membership_rescan
-from ..services.membership_roster import roster_is_fresh
+from ..services.artist_service import ArtistService
+from ..services.membership_reconcile import reconcile_all
+from ..services.membership_roster import roster_is_fresh, source_for_membership
 from ..services.scheduler_service import active_platform_cooldowns, scheduler_status
 from ..services.source_service import (
     KNOWN_PLATFORMS,
@@ -386,3 +388,68 @@ async def rescan_membership_suggestions():
         result = await membership_rescan(session)
         await session.commit()
     return jsonify(result)
+
+
+# --- #387 C4: reconciling the roster against what FC actually tracks -------
+#
+# Asymmetric on purpose. The "you subscribe but FC doesn't follow it" direction
+# carries a per-row action, because adding a source is the reversible half. The
+# "FC follows it but your roster doesn't show it" direction is REPORT ONLY by
+# the operator's decision (2026-09-11): it says what it sees and links to the
+# Subscriptions row, and offers no one-click disable.
+
+
+@sources_bp.route("/reconciliation", methods=["GET"])
+async def reconciliation():
+    async with get_session() as session:
+        return jsonify(await reconcile_all(session))
+
+
+@sources_bp.route("/reconciliation/adopt", methods=["POST"])
+async def adopt_membership():
+    """Start tracking a creator the roster says the account already pays for.
+
+    One row, one click, never a sweep side effect: adding a source commits disk,
+    worker time and rate budget, and unwinding it means deleting files.
+    """
+    body = await request.get_json()
+    if not isinstance(body, dict):
+        return _bad("invalid_body", status=400)
+    membership_id = body.get("membership_id")
+    if not isinstance(membership_id, int):
+        return _bad("membership_id_required", status=400)
+
+    async with get_session() as session:
+        membership = await session.get(PlatformMembership, membership_id)
+        if membership is None:
+            return _bad("membership_not_found", status=404)
+        if not membership.url:
+            return _bad("membership_has_no_url", status=400)
+
+        existing = await source_for_membership(session, membership)
+        if existing is not None:
+            # The operator got there by another route between the page load and
+            # the click. That is them being ahead of us, not an error.
+            return jsonify({"already_tracked": existing.id})
+
+        # The sweep already captured the creator's real display name, so the
+        # artist gets its true name with NO lookup on the request path. Task
+        # #1293 asked for `resolve_display_name` here; the roster satisfies that
+        # concern earlier in the pipeline than #1293 expected, which also keeps
+        # this route off the network entirely (rule 164). The vanity is the
+        # fallback, never the preferred value.
+        name = membership.display_name or membership.vanity_or_none()
+        if not name:
+            return _bad("membership_has_no_name", status=400)
+
+        artist, _created = await ArtistService(session).find_or_create(name)
+        try:
+            record = await SourceService(session).create(
+                artist_id=artist.id,
+                platform=membership.platform,
+                url=membership.url,
+            )
+        except DuplicateSourceError as exc:
+            return jsonify({"already_tracked": exc.existing_id})
+        artist_id = artist.id
+    return jsonify({"source_id": record.id, "artist_id": artist_id}), 201

backend/app/services/artist_membership_service.py

@@ -75,6 +75,7 @@ from ..models import (
 )
 from ..utils.slug import slugify
 from ..utils.text import html_to_plain
+from .membership_roster import source_for_membership
 
 log = logging.getLogger(__name__)
 
@@ -204,6 +205,14 @@ class ArtistMembershipService:
         membership = await self.session.get(PlatformMembership, membership_id)
         if membership is None:
             return 0
+        # The shared identity join (C4), used here as the NEGATIVE check. A
+        # membership FC already has a source for is tracked — whoever it happens
+        # to be filed under — and proposing it to some OTHER artist would be
+        # exactly the wrong link this service exists to avoid making.
+        # `_candidate_artists` only knows whether a GIVEN artist has a source on
+        # the platform, which cannot see a source sitting under someone else.
+        if await source_for_membership(self.session, membership) is not None:
+            return 0
         already = await self._decided(membership_id)
 
         made = 0

backend/app/services/membership_reconcile.py

@@ -0,0 +1,243 @@
+"""Reconciling the learned roster against the sources FC actually tracks.
+
+Milestone 387, step C4. The step the operator asked for; C0-C3 are what make it
+trustworthy enough to act on.
+
+## The buckets
+
+1. `subscribed_not_tracked` — you pay for this and FC does not follow it. The
+   adoption win, and the only bucket carrying an action.
+2. `tracked_not_subscribed` — FC follows this and the roster does not show you
+   paying for it. REPORT ONLY, by the operator's decision (2026-09-11): it says
+   what it sees and links to the existing Subscriptions row, and offers no
+   one-click disable.
+3. `matched` — the healthy set. Counted, not listed loudly.
+4. `unidentified` — sources this join cannot speak to at all. Reported as
+   exactly that, because the alternative is filing them under a verdict.
+
+## Why absence is the dangerous direction
+
+Bucket 1 is safe to be wrong about: the cost of offering a source the operator
+does not want is one ignored row. Bucket 2 is not. It is computed from an
+ABSENCE — no membership matched — and three different things produce that
+absence: the subscription genuinely lapsed, the sweep failed, or the creator
+renamed and this source has never been walked so no exact id was ever cached.
+
+Two guards follow from that, and they are the substance of this module:
+
+* the whole bucket is gated on `roster_is_fresh`, so a failed or never-run sweep
+  yields an empty list rather than a confident accusation (C3 built the state
+  this reads);
+* every row carries the BASIS for its claim, so "your membership says former
+  patron" and "we know this creator's id and it is not in your roster" and "we
+  only have a URL handle to go on" are three different sentences rather than one
+  overconfident one.
+
+`has_paid_access` returning None is honoured throughout: unknown is never
+rendered as lapsed. That is the whole reason it returns a tri-state.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..models import Artist, MembershipSync, PlatformMembership, Source
+from .membership_roster import (
+    get_sync_state,
+    has_paid_access,
+    identity_keys_for_source,
+    match_kind,
+    roster_is_fresh,
+    url_tail,
+)
+
+# Why a source appears in `tracked_not_subscribed`. Ordered strongest first —
+# the UI renders a different sentence per basis, because collapsing them into
+# one would make the weakest claim sound like the strongest.
+BASIS_LAPSED = "lapsed"           # a matched membership says access ended
+BASIS_ABSENT_EXACT = "absent_exact"    # exact id known, not in a fresh roster
+BASIS_ABSENT_HANDLE = "absent_handle"  # only a URL handle to go on
+
+
+def _membership_row(m: PlatformMembership) -> dict:
+    return {
+        "id": m.id,
+        "platform": m.platform,
+        "external_campaign_id": m.external_campaign_id,
+        "display_name": m.display_name or m.vanity_or_none(),
+        "url": m.url,
+        "vanity": m.vanity_or_none(),
+        "status": m.status,
+        "tier_names": m.tier_names,
+        "amount_cents": m.amount_cents,
+        "currency": m.currency,
+        "paid_access": has_paid_access(
+            m.platform, m.status,
+            is_free_member=bool((m.details or {}).get("is_free_member")),
+        ),
+    }
+
+
+def _source_row(source: Source, artist: Artist) -> dict:
+    return {
+        "id": source.id,
+        "platform": source.platform,
+        "url": source.url,
+        "enabled": source.enabled,
+        "artist": {"id": artist.id, "name": artist.name, "slug": artist.slug},
+    }
+
+
+async def reconcile(
+    session: AsyncSession, *, platform: str, now: datetime | None = None,
+) -> dict:
+    """Sort one platform's memberships and sources into the four buckets.
+
+    Always returns the COMPLETE shape, including when the roster is not fresh —
+    a caller reading `len(result["tracked_not_subscribed"])` must not have to
+    check which keys exist first. `fresh` is what says whether the emptiness
+    means anything.
+    """
+    state = await get_sync_state(session, platform)
+    fresh = roster_is_fresh(state, now=now)
+
+    memberships = (await session.execute(
+        select(PlatformMembership).where(PlatformMembership.platform == platform)
+    )).scalars().all()
+    rows = (await session.execute(
+        select(Source, Artist)
+        .join(Artist, Artist.id == Source.artist_id)
+        .where(Source.platform == platform)
+    )).all()
+
+    # Nested loop rather than a SQL join: the match is a predicate over a JSON
+    # blob and a derived URL handle, neither of which is indexable, and both
+    # sides are tens of rows on any real library. Keeping it in Python means ONE
+    # definition of identity (`match_kind`) instead of a second one in SQL that
+    # could drift from it.
+    pairs: dict[int, tuple[PlatformMembership, str]] = {}
+    matched_membership_ids: set[int] = set()
+    for source, _artist in rows:
+        for m in memberships:
+            kind = match_kind(source, m)
+            if kind:
+                pairs[source.id] = (m, kind)
+                matched_membership_ids.add(m.id)
+                break
+
+    subscribed_not_tracked = []
+    for m in memberships:
+        if m.id in matched_membership_ids:
+            continue
+        paid = has_paid_access(
+            m.platform, m.status,
+            is_free_member=bool((m.details or {}).get("is_free_member")),
+        )
+        # A membership FC knows has ENDED is not an adoption opportunity —
+        # adding it would start a walk that can only fetch what is already
+        # public. Unknown (None) is still offered: the operator can judge it,
+        # and refusing to show it would hide a real subscription behind a word
+        # this code has not been taught.
+        if paid is False:
+            continue
+        subscribed_not_tracked.append(_membership_row(m))
+
+    tracked_not_subscribed = []
+    matched = []
+    unidentified = []
+    for source, artist in rows:
+        pair = pairs.get(source.id)
+        if pair is not None:
+            m, kind = pair
+            paid = has_paid_access(
+                m.platform, m.status,
+                is_free_member=bool((m.details or {}).get("is_free_member")),
+            )
+            if paid is False:
+                if not source.enabled:
+                    # Already off. Reporting a source the operator has already
+                    # stopped following is noise, not a finding.
+                    continue
+                row = _source_row(source, artist)
+                row["basis"] = BASIS_LAPSED
+                row["matched_by"] = kind
+                row["membership"] = _membership_row(m)
+                tracked_not_subscribed.append(row)
+            else:
+                row = _source_row(source, artist)
+                row["matched_by"] = kind
+                row["membership"] = _membership_row(m)
+                matched.append(row)
+            continue
+
+        # No membership matched. Whether that MEANS anything depends entirely on
+        # how well this source can be identified at all.
+        has_exact = bool(identity_keys_for_source(source))
+        if not has_exact and url_tail(source.url) is None:
+            # Nothing to match on — a sidecar anchor or a URL with no handle.
+            # Reported as unidentified rather than silently dropped, so the
+            # counts add up to the source list the operator can see.
+            unidentified.append(_source_row(source, artist))
+            continue
+        if not source.enabled:
+            # Already off. Telling the operator to stop following something they
+            # have stopped following is noise, not a finding.
+            continue
+        row = _source_row(source, artist)
+        row["basis"] = BASIS_ABSENT_EXACT if has_exact else BASIS_ABSENT_HANDLE
+        row["matched_by"] = None
+        row["membership"] = None
+        tracked_not_subscribed.append(row)
+
+    # THE GATE. Everything above computed the bucket; this decides whether it may
+    # be shown. A stale or never-run roster makes every absence meaningless, and
+    # an absence rendered as a verdict is how this feature would tell the
+    # operator to cancel something they are still paying for.
+    if not fresh:
+        tracked_not_subscribed = []
+
+    return {
+        "platform": platform,
+        "fresh": fresh,
+        # How many sources exist on this platform at all. The UI needs it to
+        # decide whether an untrustworthy roster is worth mentioning: with no
+        # sources here there is nothing to reconcile, and a stale-roster warning
+        # would be noise on an install that simply has not started yet (that
+        # empty-install case is C6's, not this card's).
+        "tracked_total": len(rows),
+        "last_success_at": (
+            state.last_success_at.isoformat()
+            if state is not None and state.last_success_at else None
+        ),
+        "subscribed_not_tracked": subscribed_not_tracked,
+        "tracked_not_subscribed": tracked_not_subscribed,
+        "matched": matched,
+        "unidentified": unidentified,
+    }
+
+
+async def reconcile_all(session: AsyncSession, now: datetime | None = None) -> dict:
+    """Every platform the roster knows about, in one payload for the UI.
+
+    The platform list is the UNION of platforms with memberships and platforms
+    with sync state, not just the former. A sweep that has never succeeded has
+    recorded zero memberships, and deriving the list from memberships alone
+    would drop exactly that platform from the payload — making a broken
+    credential indistinguishable from a platform FC was never asked about. That
+    distinction is the whole reason C3 records sync state.
+    """
+    with_memberships = (await session.execute(
+        select(PlatformMembership.platform).distinct()
+    )).scalars().all()
+    with_state = (await session.execute(
+        select(MembershipSync.platform)
+    )).scalars().all()
+    platforms = set(with_memberships) | set(with_state)
+    return {
+        "platforms": [
+            await reconcile(session, platform=p, now=now) for p in sorted(platforms)
+        ]
+    }

backend/app/services/membership_roster.py

@@ -34,7 +34,7 @@ from sqlalchemy import func, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from ..models import MembershipSync, PlatformMembership
+from ..models import MembershipSync, PlatformMembership, Source
 
 log = logging.getLogger(__name__)
 
@@ -275,3 +275,96 @@ async def sync_platform(
     await session.commit()
     log.info("membership sync ok for %s: %d membership(s)", platform, len(memberships))
     return {"platform": platform, "ok": True, "count": len(memberships)}
+
+
+# ---------------------------------------------------------------------------
+# Membership <-> Source identity (#387 C4)
+# ---------------------------------------------------------------------------
+#
+# "Is this membership already tracked?" is asked by TWO features — C4's
+# reconciliation buckets and E4's creator suggestions — and it lives here, once,
+# on purpose. Built inline in C4 it would have looked finished while leaving E4
+# matching on name similarity alone, so the two would answer the same question
+# differently and only one of them would be right.
+#
+# E4 and C4 use it from opposite sides: E4 as the NEGATIVE check (propose only
+# where nothing matches) and C4 as the join itself.
+
+# Any platform that caches its creator id does so under this suffix; see
+# `download_service._phase3_persist`, which writes `patreon_campaign_id`.
+_CAMPAIGN_KEY_SUFFIX = "_campaign_id"
+
+
+def identity_keys_for_source(source: Source) -> set[str]:
+    """Every platform-side creator id cached on this source.
+
+    Reads ANY `<platform>_campaign_id` override rather than naming Patreon's,
+    so a second platform participates by caching its id under the same suffix —
+    no registry, no `if platform ==` branch (rule 169). A source that has never
+    been walked has cached nothing and simply contributes no exact key, which is
+    what makes the handle fallback below necessary rather than merely tolerated.
+    """
+    keys = set()
+    for name, value in (source.config_overrides or {}).items():
+        if name.endswith(_CAMPAIGN_KEY_SUFFIX) and isinstance(value, str) and value:
+            keys.add(value)
+    return keys
+
+
+def url_tail(url: str | None) -> str | None:
+    """The creator handle at the end of a source URL, lowercased.
+
+    Deliberately the same derivation as `PlatformMembership.vanity_or_none`'s
+    own fallback, so both sides of the comparison reduce a URL to a handle the
+    same way. Query strings and fragments are stripped first; Patreon's `/c/`
+    and `/cw/` forms both end in the vanity, so they need no special case (the
+    missing-`/c/` regex is what broke creator detection in #1485).
+
+    Returns None for the pre-0030 `sidecar:` synthetic anchors, which are not
+    feeds and must never match anything.
+    """
+    if not url or url.startswith("sidecar:"):
+        return None
+    cleaned = url.split("?", 1)[0].split("#", 1)[0]
+    tail = cleaned.rstrip("/").rsplit("/", 1)[-1]
+    return tail.lower() or None
+
+
+def match_kind(source: Source, membership: PlatformMembership) -> str | None:
+    """How this source and this membership are known to be the same creator.
+
+    Returns "campaign" for an exact platform-id match, "vanity" for agreeing URL
+    handles, or None for no evidence.
+
+    THE ORDER MUST NOT BE INVERTED. The campaign id is exact and the handle is
+    not, but the id is only written AFTER a source has been walked at least once
+    — so checking the handle first would let a stale or renamed URL outvote the
+    authoritative id on every source FC has actually polled.
+    """
+    if source.platform != membership.platform:
+        return None
+    if membership.external_campaign_id in identity_keys_for_source(source):
+        return "campaign"
+    vanity = membership.vanity_or_none()
+    tail = url_tail(source.url)
+    if vanity and tail and vanity.strip().lower() == tail:
+        return "vanity"
+    return None
+
+
+async def source_for_membership(
+    session: AsyncSession, membership: PlatformMembership,
+) -> Source | None:
+    """The source FC already tracks for this membership, if there is one.
+
+    Scoped to the membership's own platform, so a creator tracked on Discord and
+    subscribed to on Patreon does not read as already-tracked — that pairing is
+    E4's suggestion to make, not an identity.
+    """
+    rows = (await session.execute(
+        select(Source).where(Source.platform == membership.platform)
+    )).scalars().all()
+    for source in rows:
+        if match_kind(source, membership):
+            return source
+    return None