docs(audit): add runbooks for sweep-event reconstruction (#287) and trustline pre-validation (#291)

[judithJn]

Audit runbooks for sweep-event reconstruction and trustline pre-validation

Closes the two operational-runbook gaps currently assigned to @judithJn in the bridgelet-audit/ knowledge base:

• `[Operational runbook] bridgelet-audit/runbooks/audit-sweep-event-logs.md: Auditing on-chain event logs after a sweep #287` — `bridgelet-audit/runbooks/audit-sweep-event-logs.md`
• `[Operational runbook] bridgelet-audit/runbooks/token-trustline-validation-before-sweep.md: Validating recipient trustlines before sweeping non-native assets #291` — `bridgelet-audit/runbooks/token-trustline-validation-before-sweep.md`

Both files are documentation-only additions scoped to the `bridgelet-audit/runbooks/` directory. No changes to `contracts/`, `docs/`, `scripts/`, or `tools/`, matching the stated scope of both issues.

---

What this PR adds

`audit-sweep-event-logs.md` (closes #287)

Operational runbook describing how to reconstruct a single sweep’s full on-chain history from emitted event logs alone. Covers:

• A complete inventory of every event the two contracts emit (`AccountCreated`, `PaymentReceived`/`MultiPaymentReceived`, `SweepExecutedMulti`, `AccountExpired`, `ReserveReclaimed` on `EphemeralAccount`; `SweepCompleted`, `DestinationAuthorized`, `DestinationUpdated` on `SweepController`) with topic symbols and field types.
• A cross-contract correlation methodology: `EphemeralAccount`’s `ReserveReclaimed.sweep_id` field is not shared with `SweepController`, so correlation relies on the composite key `(ephemeral_account, destination, ledger_sequence)` plus a `get_nonce()` before/after snapshot for replay-protection evidence.
• An explicit Known gaps table covering the 1-vs-(M-1) `PaymentReceived`/`MultiPaymentReceived` asymmetry on `record_payment`, the absence of a shared `sweep_id` field, the fact that `claim()` does not iterate `transfers::execute_transfers(...)`, `increment_nonce` running before the transfer tail, and per-transfer success/failure not being emitted.

`token-trustline-validation-before-sweep.md` (closes #291)

Operational runbook for caller-side pre-flight validation that every record-payment asset can be received by the proposed sweep destination, because `SweepController::transfers::execute_transfers(...)` has no in-contract trustline gate today. Covers:

• How to pull the destination’s per-asset trustline state from Horizon (the per-asset matrix: trustline exists / authorized / headroom).
• Per-asset decision logic and aggregated proceed/abort gate, with native XLM excluded.
• Step-by-step interpretation of a failed sweep transaction as a trustline-specific cause (vs. a different transfer error), including race-condition recovery guidance for issuers with `AUTH_REVOCABLE`.
• Explicit scoping statement that the `claim()` path is not covered by this runbook because `SweepController::claim` does not iterate `transfers::execute_transfers(...)`; callers using `claim()` should treat trustline validation as a separate problem class.

---

Why a single PR

The two issues are sibling gaps in the same `bridgelet-audit/runbooks/` knowledge-base initiative, both assigned to the same author, both explicitly scoped to be documentation-only additions to that folder, and both part of the bridgelet-audit knowledge-base initiative (36/100 and 40/100 respectively). Keeping them in one PR makes sense and matches the standard practice of grouping related knowledge-base contributions.

---

CI

The repo README documents that `.github/workflows/test.yml` is fully commented out and `.github/workflows/deploy-testnet.yml` only runs validation for Rust crates. This PR touches no Rust source and no script — only two new markdown files in `bridgelet-audit/runbooks/` — so there is no build, fmt, clippy, or test gate that could regress. CI is a no-op for this change by design.

---

Verification

• Both files were created from scratch and cross-referenced against the actual Rust sources in `contracts/ephemeral_account/src/{events,lib}.rs`, `contracts/sweep_controller/src/{lib,authorization,transfers,errors}.rs`, and `contracts/shared/src/types.rs`.
• All file-path cross-references resolve to files that exist in the repo at the current commit.
• All GitHub issue-tracking links (`[Operational runbook] bridgelet-audit/runbooks/audit-sweep-event-logs.md: Auditing on-chain event logs after a sweep #287`, `[Operational runbook] bridgelet-audit/runbooks/token-trustline-validation-before-sweep.md: Validating recipient trustlines before sweeping non-native assets #291`) point at the correct upstream issue URLs.
• Internal consistency between the two new runbooks was checked: both consistently treat `ReserveReclaimed.sweep_id` as a per-event ledger sequence stamp, both consistently describe `claim()` as not iterating `execute_transfers`.
• Tailwind/markdown syntax is well-formed: code fences closed, table syntax valid, relative links from `bridgelet-audit/runbooks/` use `../../contracts/...` and `../glossary/...` consistently with sister runbooks.

---

Files

• `bridgelet-audit/runbooks/audit-sweep-event-logs.md` — new, 171 lines, closes [Operational runbook] bridgelet-audit/runbooks/audit-sweep-event-logs.md: Auditing on-chain event logs after a sweep #287.
• `bridgelet-audit/runbooks/token-trustline-validation-before-sweep.md` — new, 167 lines, closes [Operational runbook] bridgelet-audit/runbooks/token-trustline-validation-before-sweep.md: Validating recipient trustlines before sweeping non-native assets #291.

```text
docs/audit-runbooks-judithjn-287-291 (commit 0f4dbfc)
2 files changed, 338 insertions(+)
```

[drips-wave]

@judithJn Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits