RFC-038: Domain of Concern Registry — AIGP Dialects as First-Class Artifacts — 14. Compatibility and Migration

AIGP Specification › RFC-038: Domain of Concern Registry — AIGP Dialects as First-Class Artifacts › 14. Compatibility and Migration

← 13. Dialect Lifecycle · Section index · 15. Second-Order Dialect Evolution →

14. Compatibility and Migration

14.1 Compatibility Matrix

Two dialect versions are compatible when a Mediation Vector populated for one version is structurally valid for the other:

Condition	Compatibility
Same variables, same types, same scales	Fully compatible
Subset of variables (target has more)	Forward compatible (old vector valid for new dialect, missing variables are gaps)
Superset of variables (target has fewer)	NOT compatible (old vector has orphan variables)
Same variables, different thresholds	Structurally compatible (different verdicts possible)
Same variables, different types/scales	NOT compatible (measurement semantics diverge)

14.2 Migration Path

When a MAJOR version is published, the dialect MUST include a migration guide:

{
  "migration": {
    "from": "1.x",
    "to": "2.0.0",
    "variable_mapping": {
      "old_variable_a": "new_variable_a",
      "old_variable_b": null,
      "new_variable_c": { "source": "new", "rationale": "..." }
    },
    "threshold_changes": [ ... ],
    "breaking_rationale": "Ordinal aggregation in 1.x violated Stevens constraint. 2.x introduces rank_distance gap operator and prohibits direct ordinal summation.",
    "recommended_migration_steps": [ ... ]
  }
}

14.3 Parallel Subscription During Migration

During migration, an application MAY subscribe to both old and new versions simultaneously:

{
  "dialect_subscriptions": [
    { "dialect_id": "autonomous_systems", "version": "1.3.0", "role": "active" },
    { "dialect_id": "autonomous_systems", "version": "2.0.0", "role": "shadow" }
  ]
}

The shadow subscription evaluates artifacts against the new dialect without affecting governance decisions. This enables organizations to validate the new dialect’s behavior before cutting over.

---

---

← 13. Dialect Lifecycle · Section index · 15. Second-Order Dialect Evolution →