PREWAVE-BE-103 — Persist Sybil Score Appeals and Their Provenance #804

Problem context

SybilResistanceService persists score snapshots through Prisma, but stores appeal history only in a process-local Map<string, SybilAppealRecord[]>. getAppeals() reads only that map. Appeals disappear after restart, are not shared across API instances, and do not provide a durable audit trail.

Technical scope

Introduce a durable appeal record and migration (or reuse an approved existing appeal model). Persist appeal submission, previous/new score and risk values, target model version, recomputation timestamp, provenance digest, evidence summary reference, and status. Make submission idempotent and owner-scoped. Keep sensitive evidence out of public views and store only a privacy-safe summary or protected reference. Add status transitions and administrative review only if supported by the approved appeal policy.

Required tests

• Appeal survives service restart and reads consistently across instances.
• Owner isolation and authorized reviewer access.
• Duplicate submission/idempotency, concurrent updates, status transition, and migration rollback.
• Provenance digest and model version remain bound to the recorded recomputation.
• Evidence summary and logs do not leak private evidence or unnecessary PII.

Security and architecture constraints

• Fail closed on missing, stale, unauthorized, or ambiguous state.
• Persist audit-critical state; do not rely on process-local maps for user appeals or financial operations.
• Canonical contracts and finalized events remain authoritative for protocol state.
• Do not fabricate scores, provider responses, payout hashes, receipts, or finality.
• Enforce owner/reviewer/service authorization and redact secrets and private evidence.

Acceptance criteria

• The identified in-memory, mock, or simulated behavior is replaced by the production-safe implementation.
• State is durable and consistent across process restarts and API instances where applicable.
• Authorization and privacy boundaries are covered by automated tests.
• Failure, retry, replay, and concurrency behavior is documented and tested.
• Exact-head required CI passes and independent review is recorded.

Dependencies

• Sybil score snapshots and provenance services already present in the API must remain the authoritative calculation source.

Non-goals

Changing the Sybil scoring algorithm, model weights, or appeal policy.

Complexity and points

• Medium — 150 points

Candidate only. Activation remains maintainer-controlled; do not apply Stellar Wave as part of implementation.