feat(notifications): idempotent per-period recap claim + generation audit trail

[oktofeesh1]

Summary

• feat(notifications): recap queue job type + processor case (idempotent, throttle-claimed) #2249: adds a per-UTC-date claim so a retried cron tick / redelivered (at-least-once) queue message never re-scans repos or re-sends the maintainer recap digest for a period already sent. claimMaintainerRecapPeriod (src/db/repositories.ts) performs an atomic conditional UPDATE on the global_agent_controls singleton, mirroring the exact proven pattern claimRegateFanoutSlot already uses for the re-gate sweep's own fan-out dedup (migration 0063) — D1 serializes writes, so only the first invocation for a given period (YYYY-MM-DD, UTC) matches the "unset or a different period" predicate; a retry for the same period gets 0 changes and short-circuits before any repo scan or Discord send. Fail-open on a driver error, matching claimRegateFanoutSlot's own philosophy (a DB hiccup must never silently stop the digest from ever sending).
  • New migration: migrations/0129_maintainer_recap_claim.sql (ALTER TABLE global_agent_controls ADD COLUMN last_recap_period_key TEXT — nullable, no default, backward-compatible).
  • Note: feat(notifications): recap queue job type + processor case (idempotent, throttle-claimed) #2249's other deliverable — extending the job-type union and adding the processor case gated on isRecapEnabled — was already completed in feat(notifications): schedule the maintainer recap job on a configurable cadence #4418 (the generate-maintainer-recap job type + case already exist). This PR adds only the missing idempotency piece.
• feat(notifications): audit-event trail for recap generation + delivery outcome #2251: records a maintainer_recap_generated audit event once the report is built, mirroring generateWeeklyValueReport's own recordAuditEvent call (weekly-value-report.ts:72). Metadata: cadence (resolved the same way shouldFireMaintainerRecap does — a present config-as-code override wins, else the env knob), windowDays, repoCount, sectionCount, channelsAttempted.
  • Note: feat(notifications): audit-event trail for recap generation + delivery outcome #2251's other deliverable — per-channel delivery outcome (success/failure) as observable metadata — was already completed in feat(notifications): schedule the maintainer recap job on a configurable cadence #4418/feat(notifications): Discord delivery for the maintainer recap digest (reuse discord-notify) #2245 via deliverRecapToDiscord's own existing maintainer_recap_notification.discord audit event. This PR adds only the missing generation-level event.
• Closes feat(notifications): recap queue job type + processor case (idempotent, throttle-claimed) #2249. Closes feat(notifications): audit-event trail for recap generation + delivery outcome #2251.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR bundles two small, closely-related deliverables (both non-conflicting edits inside the same runMaintainerRecapJob orchestrator, both "Part of Maintainer review recap digest (Discord / Slack) #1963") rather than splitting into two PRs that would each touch the exact same lines.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked currently open issues this PR resolves — Closes #2249, Closes #2251.

Validation

• git diff --check
• npm run actionlint
• npm run db:migrations:check — contiguous, next free 0130
• npm run db:schema-drift:check — global_agent_controls stays raw-SQL-only (allowlisted), no Drizzle drift
• npm run typecheck
• npm run test:coverage locally — 100% branch coverage on every changed line, verified directly against lcov.info for every touched file (src/db/repositories.ts, src/review/maintainer-recap-wire.ts, src/queue/processors.ts)
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate — 0 vulnerabilities
• Full npm run test:ci green (652 test files / 12,769 tests)
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries — see below.

Test coverage added:

• test/unit/db-parsers.test.ts: claimMaintainerRecapPeriod — first claim for a period wins, a retry for the same period loses, a different period wins again; fails open (returns true) on a DB error.
• test/unit/maintainer-recap-wire.test.ts: a retried tick within the same UTC date is a no-op (no repo scan, no second Discord post — verified via the stubbed fetch call count); a tick on a different UTC date gets its own fresh claim and sends again; the maintainer_recap_generated audit event's full metadata shape on success; a present manifest cadence override is reflected in the audit metadata over the env value.
• Existing feat(notifications): schedule the recap job on the cron with a configurable cadence knob #2248/feat(notifications): config-as-code recap channel/cadence overrides in .gittensory.yml focus manifest #2250 tests re-verified to still pass (each already uses a fresh env per test, so the new per-period claim doesn't change their behavior).

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (N/A — no auth/CORS/session surface touched.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A — no API/OpenAPI/MCP surface changed; internal job orchestration + a D1 column only.)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A — no UI changes.)
• Visible UI changes include a UI Evidence section. (N/A — no visible UI changes; backend-only.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. (No changelog edit.)

UI Evidence

N/A — backend-only change (D1 migration + queue orchestrator), no UI surface touched.

Notes

• The claim key is the UTC calendar date alone (not cadence-specific): daily fires at most once per date, and weekly fires on only ONE designated date per week, so date-only keying is correct for both cadences without needing to encode which cadence produced the tick.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.01%. Comparing base (861e8b7) to head (671106e).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4459   +/-   ##
=======================================
  Coverage   94.01%   94.01%           
=======================================
  Files         418      418           
  Lines       37417    37427   +10     
  Branches    13677    13678    +1     
=======================================
+ Hits        35178    35188   +10     
  Misses       1583     1583           
  Partials      656      656           

Files with missing lines	Coverage Δ
src/db/repositories.ts	96.72% <100.00%> (+<0.01%)	⬆️
src/queue/processors.ts	95.39% <100.00%> (ø)
src/review/maintainer-recap-wire.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-09 20:04:13 UTC}

6 files · no blockers · readiness 100/100 · CI green · dirty

⏸️ Suggested Action - Manual Review

• AI review already in progress for this PR head: Another Gittensory pass is already running the AI review for this exact PR head. This pass is skipping to avoid a duplicate LLM call.

Review summary
AI review is already running for this PR head in another Gittensory pass. Gittensory is holding this PR for manual review until that pass completes.

Nits — 1 non-blocking

• AI review already in progress for this PR head — The gate is held for a human reviewer rather than passed automatically; it re-evaluates once the in-flight review completes or on the next update.

Signal	Result	Evidence
Code review	✅ No blockers	No AI review summary
Linked issue	✅ Linked	#2249, #2251
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (2 linked issues).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 30 registered-repo PR(s), 24 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	oktofeesh1; Gittensor profile; 30 PR(s), 0 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Linked issue satisfaction

Partially addressed
The diff adds a real per-period idempotency mechanism (claimMaintainerRecapPeriod atomic UPDATE + migration + tests for same-period no-op and different-period re-send), satisfying the digest's dedup goal, but it uses a singleton-column claim mirroring claimRegateFanoutSlot rather than the notification_deliveries ON CONFLICT DO NOTHING throttle-claim idiom the issue explicitly points to, and the di

Review context

• Author: oktofeesh1
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 30 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (conflicts with the base branch — resolve and open a fresh PR). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.