Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.canthus.org/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Current runtime baseline (implemented March 7, 2026)

  • Snapshot update paths take algorithmVersion as an explicit input (default 1).
  • Daily calibration snapshots are upserted deterministically for (day, algorithmVersion).
  • Re-running the same day/version path is idempotent (updates one deterministic row, no duplicates).
  • Migration and rollback history is append-only through calibration migration records with:
    • fromVersion, toVersion, type, recordedAt
    • optional impactEstimate
    • optional rollbackCheckpointDay
  • Runtime version resolution can rehydrate active version from append-only migration history.
  • Runtime migrate/rollback calls are idempotent for already-applied target versions.

​
Migration types

  1. Parameter-only: constants/policies change, no state transform required
  2. State transform: deterministic update to stored derived values
  3. 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:
  1. restore pre-migration snapshot
  2. set engine version back to prior value
  3. 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