feat(marmot-app): record an epoch_stall_backfill_armed forensic audit row at the epoch-stall arm decision

[jgmontoya]

---

Summary by CodeRabbit

• New Features

  • Added forensic audit logging when epoch-stall backfill is armed.
  • Audit records include the stalled epoch and configured threshold.
  • Added schema support for the new epoch_stall_backfill_armed event type.

• Bug Fixes

  • Prevented duplicate audit records for repeated backfill triggers at the same stalled epoch.

• Tests

  • Added coverage for threshold behavior, event serialization, schema validation, and duplicate-event prevention.

[stage-review]

Ready to review this PR? Stage has broken it down into 4 individual chapters for you:

	Title
1	Define epoch stall audit event schema
2	Expose epoch stall threshold and recording
3	Trigger audit recording on backfill arming
4	Verify audit row emission in integration tests

_{Chapters generated by Stage for commit c2e4e90 on Jul 18, 2026 5:51pm UTC.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fd1ccb1d-cfba-439b-a1c0-ab429980e517

📥 Commits

Reviewing files that changed from the base of the PR and between e673cf8 and c2e4e90.

📒 Files selected for processing (7)

• crates/marmot-app/src/client/audit.rs
• crates/marmot-app/src/client/epoch_stall.rs
• crates/marmot-app/src/client/sync.rs
• crates/marmot-app/tests/epoch_stall_backfill_audit.rs
• crates/marmot-forensics/schema/audit-log-event.v2.schema.json
• crates/marmot-forensics/src/audit.rs
• crates/marmot-forensics/src/audit/tests.rs

---

Walkthrough

Changes

Adds the epoch_stall_backfill_armed audit event to the forensic schema and serialization layer, records it when epoch-stall detection arms backfill, and adds integration coverage for threshold, non-threshold, and debounce behavior.

Epoch-stall backfill auditing

Layer / File(s)	Summary
Audit event contract crates/marmot-forensics/src/audit.rs, crates/marmot-forensics/schema/audit-log-event.v2.schema.json, crates/marmot-forensics/src/audit/tests.rs	Defines the new event with stalled_epoch and threshold, maps its JSON type, updates the schema, and verifies serialization round trips.
Backfill arm recording crates/marmot-app/src/client/epoch_stall.rs, crates/marmot-app/src/client/audit.rs, crates/marmot-app/src/client/sync.rs	Exposes the detector threshold, records a group-scoped arm event, and invokes recording when undecryptable traffic crosses the backfill threshold.
End-to-end audit verification crates/marmot-app/tests/epoch_stall_backfill_audit.rs	Tests threshold crossing, below-threshold traffic, audit row contents, and once-per-epoch debounce behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• marmot-protocol/mdk#892: Introduced the epoch-stall backfill detector and arming control flow extended by this change.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: recording an epoch_stall_backfill_armed forensic audit row at the arm decision.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/epoch-stall-backfill-audit

---

_{Comment @coderabbitai help to get the list of available commands.}