supporter-loop reusable workflow: catch-up + invitation queue + sweep state (contract v2.0, caty-ai/x-collector#142) — child B of EPIC caty-ai/x-collector#119 #91

目的 (Why)

Implement contract v2.0 (caty-ai/x-collector#142, child A1) in the central reusable workflow so the supporter loop is lossless under a launch burst and honest about GitHub's 50-invitations-per-24 h rate: event runs stay the fast path, the twice-daily sweep becomes the reconciler (catch-up), and invitations are queued at ≤ 45/day. Measured background and the five-seat design review: caty-ai/x-collector design packet _handoffs/x-collector-supporter-loop-scale-design-20260908/design-v1.3.md (mirror the relevant sections into supporter-loop/README.md).

完了条件 (Done when)

• Catch-up (§11 step 4b, live in act): candidates = stargazers (exhaustive list, gate (b)) with any tier-1 action undelivered per §7 and no skip excluded-* line in the current generation. Pass 1: projection repairs (supporters-append missing) — quota-free, identity-free. Pass 2: invitations — order-preserving dedup (unique_by over paged order; unique removed at the stars output and the decide re-emit), never-invited first, oldest first, take Q with refill → GET /user/{id} → §3 rules (roster, self, bot, type==User) → PUT {"permission":"pull"}; invite result: ok-catchup, then supporters-append; event: sweep, tier: 1, dedup_key <repo>:1:<id> (line() parameterised). Bounded re-invite: at most 2 invitations per generation, then one skip excluded-unresponsive (<repo>:sweep:<id>, written by act).
• Quota: B = ledger invite lines with result ∈ {ok, ok-backfill, ok-catchup} in the last 24 h + pending invitations (GET /invitations) created ≤ 24 h with no ledger line; already-1 never counts. Re-evaluated before every PUT; cumulative wait ≤ 3 min per sweep when the window opens imminently (dynamic per candidate, never a static slice); ceiling 45 (sweep only — the event path never computes B). Invitation-limit 422: event path → invite/comment/supporters-append all deferred-quota (nothing sent); sweep path → one ledgered skip/deferred-quota for the refused candidate, catch-up stops, run stays green. Other 422s stay error-422. Launch gate: the invitation-limit 422 message text is probed live and pinned in a fixture before merge.
• Gates: catch-up pass 2 requires (a) no red run since T, (b) exhaustive stargazers, (c) token preflight. Unstar cleanup keeps (a)–(e). Cancelled runs (status=cancelled&created>=T, event vs schedule) counted, never gating.
• Regeneration: regenerate() = GET sha → read ledger → render → PUT(sha), restart from GET on conflict; once per sweep, on every live sweep (incl. red-run sweeps); write pacing ≤ 1 content write/s across the whole sweep.
• State + notifications: ledger/<name>.sweep-state.json (last_sweep_ts, backlog, cancelled_runs, capacity_pct, alarm_state) regenerated by act with the ledger PAT; one Telegram summary per sweep; capacity 70 % warnings and red-run condition edge-triggered. Record-only: reduced sweep in decide runs identity + §3 and writes would-invite/would-supporters-append (tier key) or skip excluded-*; rehearsal B ledger-only; rehearsal never touches the state file.
• stars job timeout-minutes: 10; output guard unchanged (400 k) until measured (tracking epic).
• Fixtures (all in supporter-loop/fixtures/workflow/): deferred-quota (event, whole bundle), ok-catchup, each §3 reason on the catch-up path, ordering across pages with duplicates, 2-invitation bound → excluded-unresponsive, excluded-once filter across both key namespaces, quota window edges incl. already-1 exclusion and the 24 h boundary, stop line does not self-exclude, crash-between-actions / stranded supporters-append repaired in pass 1, two-lane regeneration conflict (restart-from-GET), write-rate pacing + cumulative wait cap, record-only ≡ live parity (same ledger, empty unledgered-pending set), sweep-state derivation (state ≡ f(ledger, inputs)), interface pins (stars sweep-only, contents: write only, single GET, no secret). check-decide-static.sh re-run with its violating fixtures (edit only if parsing changes). §5.3 vocabulary fixtures accept the new result values.
• supporter-loop/README.md updated; tests + lint green; tag + GitHub Release (v0.12.0)
• 5-seat review (size H, permission boundary + supporter-facing sends); merge only after caty-ai/x-collector A1 (contract v2.0) is on main

触るファイル / モジュール予測

• .github/workflows/supporter-loop-reusable.yml
• supporter-loop/README.md
• supporter-loop/fixtures/workflow/test-decide.py
• supporter-loop/fixtures/workflow/test-interface.py
• supporter-loop/fixtures/workflow/ (new ledger/event fixtures listed above)
• supporter-loop/check-decide-static.sh + its fixtures (run; edit only if parsing changes)

想定スコープ

Everything in design §2.0 + §2.1 (timeout only). Out of scope (tracking epic): ledger snapshot, SUPPORTERS.md paging, diff-only stars→decide→act hand-off, guard raise, tier-2/3 late thanks, per-run shards, GraphQL path.

前提条件 (Blocked by)

• contract v2.0 (supporter-loop scale): catch-up + invitation queue, twice-daily sweep lane, §7 key rule, capacity §16 — child A of EPIC #119 x-collector#142 A1 (contract v2.0) merged.
• After this merges: caty-ai/x-collector A3 (caller cron twice daily).

Coordination

Open lane caty-ai/x-collector#141 (v1.11 follow-up: dispatch wording, dispatch watermark, static check covers stars) touches the same files (CONTRACT.md, caller, reusable workflow). Serial: #141 first or fold its three items into A1/B — decided at WIP time, never parallel (L0-2).