fix: make storage-tier changes explicit and auditable

[Meemlahsabi]

Overview

This PR makes storage-tier changes explicit, deterministic, and auditable in predictify-hybrid. It introduces a dedicated storage-tier state machine with bounded transition paths, writes audit events for every tier change, and surfaces diagnostics through events and logs without exposing sensitive data. Existing public interfaces remain compatible, and focused tests cover valid, invalid, duplicate, boundary, and concurrent execution scenarios.

Related Issue

Changes

🗂️ Explicit Storage-Tier State Machine

• [ADD] contracts/predictify-hybrid/src/storage.rs
  • Models storage tiers as a typed enum with explicitly defined allowed transitions.
  • Rejects invalid, duplicate, and out-of-order transitions deterministically.
  • Uses a versioned compare-and-swap style update to prevent lost updates and unsafe concurrent writes.
  • Documents invariants directly in code, including retention and indexing constraints for each tier.

🧾 Audit Events and Persistent Audit Trail

• [ADD] contracts/predictify-hybrid/src/audit.rs and contracts/predictify-hybrid/src/events.rs
  • Emits a StorageTierChanged event for every successful tier transition.
  • Audit payload includes previous tier, new tier, reason, actor, sequence, and version.
  • Adds queryable audit records so tier history is reviewable and diagnosable.
  • Preserves existing public event interfaces while extending the emitted data for new storage-tier changes.

🔒 Invariant Enforcement and Configuration

• [MODIFY] contracts/predictify-hybrid/src/types.rs

  • Tightens storage-tier types and transition validation helpers.
  • Centralizes tier invariants so storage and audit paths cannot diverge.

• [MODIFY] contracts/predictify-hybrid/src/config.rs

  • Adds explicit configuration for allowed tier transitions, retention policies, and audit log retention.
  • Rejects configurations that would permit silent tier downgrades or unsafe retention changes.

• [MODIFY] contracts/predictify-hybrid/src/lib.rs

  • Routes all storage-tier mutations through the audited state machine.
  • Reuses existing authorization checks and applies them before any transition is attempted.

🧪 Focused Test Coverage

• [ADD] contracts/predictify-hybrid/src/storage_layout_tests.rs

  • Verifies storage layout stability and enum/tier representation compatibility.
  • Covers boundary values, duplicate transitions, and invalid transition rejection.

• [ADD] contracts/predictify-hybrid/src/storage_tier_audit.rs

  • Verifies every successful tier change produces an audit record.
  • Verifies failed tier changes do not emit audit events or mutate state.
  • Simulates concurrent transition attempts to confirm only the first valid transition wins.
  • Validates retry safety: repeated submission of the same transition is a no-op once applied.

Verification Results

cargo test -p predictify-hybrid storage_tier_audit storage_layout_tests -- --nocapture

✅ 37/37 tests passed

Coverage includes:
✅ Valid tier transitions accepted
✅ Invalid tier transitions rejected
✅ Duplicate transitions no-op
✅ Boundary tier values handled
✅ Concurrent updates: only one winner, no inconsistent state
✅ Audit record emitted exactly once per successful change
✅ Failed changes emit no audit event and mutate no state

Acceptance Criteria	Status
Intended behavior is deterministic for valid, invalid, duplicate, and boundary-case inputs	✅ Transition matrix tests cover every tier-to-tier pair and all duplicate/boundary scenarios
Authorization, validation, and state-transition invariants remain enforced	✅ Existing auth paths are preserved; validation runs before any state mutation
Retries, partial failure, and concurrent execution cannot produce unsafe or inconsistent results	✅ Versioned compare-and-swap plus test coverage for concurrent transition attempts
Focused tests cover success, rejection, boundary, and regression scenarios	✅ Added storage_tier_audit.rs and storage_layout_tests.rs with 37 passing tests
Existing callers remain compatible, or the PR includes a tested migration path	✅ Public interfaces are preserved; new audit payloads are additive
Relevant logs, metrics, or user-visible errors make failures diagnosable without exposing sensitive data	✅ StorageTierChanged events and audit records expose tier/reason/actor only, never stored contents

Closes #1405

[drips-wave]

@Meemlahsabi 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