Major algorithm behavior changes must never ship silently.
Why this exists
Mana is trust-sensitive. If coefficients, pool behavior, or task costs shift after an update, users need both safety and explainability.
This page defines the contract for algorithm change management.
Versioning contract
Each calibration state is tagged with an integer algorithmVersion.
Required records:
- calibration snapshot (
algorithmVersion, coefficient, EWMA values, confidence)
- migration changelog entry (
fromVersion, toVersion, type, timestamp, impact estimate)
- rollback checkpoint reference
Every non-trivial behavior change requires a recorded version bump.
Migration types
- Parameter-only: constants/policies change, no state transform required
- State transform: deterministic update to stored derived values
- Recompute: replay from event/check-in history when formulas materially change
All migrations must be deterministic, idempotent, and transactional.
Rollback policy
Before migration, persist pre-migration snapshot.
Rollback procedure:
- restore pre-migration snapshot
- set engine version back to prior value
- write rollback event to changelog
Audit history is append-only; rollback does not erase change history.
Trust-impact policy
A change is major-impact if either threshold is crossed:
- pool shift >= 15%
- median canonical task-cost shift >= 20%
Major-impact changes require user-facing explanation copy on first post-upgrade interaction.
Local and sync-ready storage posture
Current runtime is local-only encrypted SQLite. Migration logs should still be modeled as sync-safe event records (deterministic IDs + ordered sequence) so cross-device sync can be added without redesigning migration semantics.
Test requirements
- migration determinism across runs/devices
- idempotency (same migration run twice has no additional effect)
- rollback restores pre-migration behavior within tolerance
- crash/interruption recovery preserves consistency
- threshold gate coverage for explanation policy
Read next
