Phase 15.4 — VersionManager: version lineage, rollback targeting & compatibility assessment

[web3guru888]

Phase 15.4 — VersionManager: Architecture & Design

Welcome to the Show & Tell for VersionManager, the fourth component of Phase 15 (Hot-Reload & Self-Modification). This component is the version ledger of the entire self-modification pipeline.

---

What does VersionManager do?

VersionManager maintains a complete version lineage for every hot-swappable module:

1. Records checkpoints each time a module version is committed by HotSwapper
2. Assesses compatibility (COMPATIBLE / MINOR_CHANGE / BREAKING / UNKNOWN) before a swap is approved
3. Selects rollback targets when a post-swap health check fails
4. Queues breaking changes for operator approval when require_approval=True

---

Version Lifecycle

register(v=1)                    register(v=2)               HEALTH_FAIL
     │                                │                           │
     ▼                                ▼                           ▼
[VersionCheckpoint v=1]   [VersionCheckpoint v=2]    rollback_target() → v=1
 parent=None               parent=v=1                set_status REVERTED

---

Compatibility Assessment

CompatibilityLevel	Meaning	HotSwapper action
COMPATIBLE	Drop-in — no interface changes	Proceed
MINOR_CHANGE	Additive — new optional fields	Proceed
BREAKING	Interface removed or signature changed	Block if reject_breaking=True
UNKNOWN	Insufficient information	Proceed (log warning)

---

Data Model

Three frozen dataclasses:

Dataclass	Key fields
VersionCheckpoint	module_id, version, checksum, timestamp, parent_ver, tags
CompatibilityReport	module_id, from_ver, to_ver, level, rationale, approved_by
VersionManagerConfig	max_checkpoints, require_approval, auto_rollback_on_breaking

---

rollback_target — backwards walk algorithm

# Walk lineage in reverse; return first checkpoint not assessed as BREAKING
for cp in reversed(chain[:-1]):
    key = (module_id, cp.version, current_ver)
    report = self._reports.get(key)
    if report is None or report.level != CompatibilityLevel.BREAKING:
        return cp   # ← safe rollback target
return chain[0]     # last resort: oldest known checkpoint

This guarantees that after a health failure, HotSwapper always has a safe prior version to restore.

---

HotSwapper Integration

HotSwapper.swap() now accepts a version_manager keyword argument:

swap_result = await hot_swapper.swap(
    swap_req,
    resolver        = dep_resolver,
    version_manager = version_manager,   # ← NEW in 15.4
)

After a COMMITTED swap, VersionManager.record_checkpoint() is called automatically. After a ROLLED_BACK result, rollback_target() is queried and ModuleRegistry.set_status(REVERTED) follows.

---

Prometheus Metrics

Metric	Type	Labels
asm_version_checkpoints_total	Counter	module_id
asm_version_rollbacks_total	Counter	module_id, reason
asm_version_breaking_changes_total	Counter	module_id
asm_version_pending_approvals	Gauge	—
asm_version_lineage_depth	Gauge	module_id

PromQL alerts:

- alert: VersionRollbackStorm
  expr: rate(asm_version_rollbacks_total[5m]) > 0.5
  for: 2m
  annotations:
    summary: "High rollback rate — check module stability"

- alert: BreakingChangePending
  expr: asm_version_pending_approvals > 0
  for: 1m
  annotations:
    summary: "Breaking-change swap awaiting operator approval"

---

Open Questions

1. Versioned dependency compatibility — should DependencyResolver consult VersionManager to check cross-module compatibility before resolving topology?
2. Tag-based rollback policies — e.g., only roll back to checkpoints tagged "stable". Worth adding a tag_filter param to rollback_target()?
3. Distributed state — for federated deployments (Phase 9), should VersionManager state be replicated via FederatedBlackboard?

Discussion, feedback, and +1s welcome! 🎉