AEGIS Migration Guide¶

Version: 1.0.0 | Updated: 2026-02-09 | Status: Active

This guide covers upgrading AEGIS versions, migrating parameter schemas, recalibrating thresholds, and handling workflow state migrations.

1. Parameter Schema Migration¶

Schema Versioning¶

schema/interface-contract.yaml is the authoritative source for all frozen parameters. The schema version is tracked in the file's version field.

Migration Procedure¶

1. Compare schemas: Diff old and new interface-contract.yaml

git diff guardrail-v1.1-freeze..HEAD -- schema/interface-contract.yaml

1. Identify changes: New parameters get defaults automatically. Modified parameters require review.

2. Validate config: Test your custom config against the new schema

aegis validate-config <your-config.yaml>

1. Rollback plan: Keep a tagged backup of the previous frozen state

git tag guardrail-v{X.Y}-freeze -m "Freeze guardrail params at v{X.Y}"

Parameter Change Categories¶

2. Parameter Recalibration¶

When to Recalibrate¶

• KL divergence drift detection triggers sustained warnings (tau_warning exceeded)
• Business requirements change (risk tolerance shift)
• Model performance degrades over time
• Calibrator actor proposes threshold adjustments

Recalibration via Calibrator Actor¶

The Calibrator actor (src/actors/calibrator.py) provides a structured workflow for threshold tuning:

from actors.calibrator import Calibrator
from engine.drift import DriftMonitor
from engine.bayesian import BayesianPosterior

calibrator = Calibrator(
    actor_id="calibrator-1",
    drift_monitor=drift_monitor,
    bayesian_posterior=posterior,
)

# 1. Propose new thresholds based on observed data
proposal = calibrator.propose_calibration(
    parameter="tau_warning",
    new_value=0.35,
    justification="Sustained drift above current threshold",
)

# 2. Approval gate (requires human approval)
calibrator.approve(proposal.proposal_id, approver_id="risk-lead")

# 3. Apply calibrated thresholds
calibrator.apply_calibration(proposal.proposal_id)

Recognized Parameters¶

The Calibrator accepts changes to these 16 parameters (whitelist in _RECOGNIZED_PARAMETERS):

Safety Constraints¶

• Calibration proposals require APPROVED status before application
• The _RECOGNIZED_PARAMETERS whitelist prevents modification of unrecognized parameters
• Thread-safe via threading.Lock
• All calibration events emit telemetry for audit trail

3. Workflow State Migration¶

Persistence Schema¶

AEGIS workflow state is stored via SQLAlchemy ORM models (src/workflows/persistence/models.py):

Schema version: 1.0.0

Upgrade Procedure¶

Current approach (pre-Alembic):

1. Export existing workflow data:

from workflows.persistence.repository import WorkflowPersistence
workflows = await repo.list_workflows(status="pending")

1. Apply schema changes via SQL migration scripts

2. Re-import workflows with updated schema

Future approach (planned): - Alembic migration framework for automatic schema versioning - alembic upgrade head for seamless upgrades

Serialization¶

All workflows support to_dict() / from_dict() serialization:

# Export
data = workflow.to_dict()

# Import (handles timezone normalization via ensure_utc)
workflow = ProposalWorkflow.from_dict(data)

The shared ensure_utc() helper (src/workflows/serialization.py) normalizes timestamps across all three workflow types (proposal, consensus, override).

Data Safety¶

• PII fields: 12 telemetry fields encrypted at rest via PIIEncryptionEnricher
• Audit trail: Hash-chained transitions (SHA-256) for tamper detection
• Encrypted fields: EncryptedField.value_type discriminator ("str", "bytes", "json") for lossless round-trips

4. Configuration Upgrade Path¶

AegisConfig Properties¶

AegisConfig is a frozen dataclass — instances are immutable after creation. This prevents parameter drift during a session.

from aegis_governance import AegisConfig

# Immutable: raises AttributeError
config = AegisConfig.default()
config.epsilon_R = 0.5  # AttributeError: cannot assign to field

Backward Compatibility¶

Configuration Loading¶

AegisConfig.from_yaml() reads the parameters key with nested sections:

# Top-level parameters
parameters:
  epsilon_R: 0.01
  # Nested section
  novelty_gate:
    N0: 0.7
    k: 10.0
    output_threshold: 0.8
  # Nested section
  kl_drift:
    tau_warning: 0.3
    tau_critical: 0.5
    window_days: 30

Nested sections are mapped to flat AegisConfig fields via _NESTED_SECTIONS in src/config.py.

5. Version Compatibility Matrix¶

AEGIS Version Matrix¶

Dependency Compatibility¶

6. Pre-Migration Checklist¶

• [ ] Backup current config: cp schema/interface-contract.yaml schema/interface-contract.yaml.bak
• [ ] Tag current state: git tag guardrail-v{X.Y}-freeze
• [ ] Run test suite against new version: pytest tests/ -v --tb=short
• [ ] Validate config against new schema: aegis validate-config <config.yaml>
• [ ] Test in staging: Deploy new version to staging environment first
• [ ] Verify audit trail continuity: Ensure hash chain remains valid after migration

from workflows.persistence.durable import DurableWorkflowEngine
# Verify hash chain integrity
is_valid, message = engine.verify_audit_chain(workflow_id)
assert is_valid, f"Audit chain broken: {message}"

• [ ] Review ROADMAP.md: Check for breaking changes in the target version
• [ ] Update monitoring: Ensure Prometheus rules match new metric names (if changed)

References¶

• Interface Contract — Frozen parameters (authoritative)
• Calibrator Actor — Threshold recalibration
• Persistence Models — ORM schema
• Config Module — AegisConfig, from_yaml(), nested sections
• Serialization — ensure_utc() shared helper
• Production Guide — Deployment instructions
• Performance SLAs — Latency and throughput targets