Skip to content

Context Migration Record

Migration record — instantiates Definition-Time Context Binding

A durable record of how a captured context was translated from one version or environment to another, so a moved unit's origin bindings can be rebuilt and audited.

A Context Migration Record is the written history of a context's move. When a behavior unit's captured environment must cross a boundary where the shapes no longer match — a schema that changed, a config format that was renamed, a permission model that was restructured — the record documents the translation: what the old bindings were, what they became, by which mapping, and under whose authority. It is not the captured context itself and not the new one; it is the durable account of how you got from one to the other. Its defining move against the archetype is temporal: where most mechanisms bind context at a single definition moment, this one binds the relationship between two moments, so that a unit carried forward across versions can still be traced back to the origin assumptions it was actually defined under.

Example

A company upgrades its permissions system. Roles that were once flat strings ("editor", "admin") become structured grants, and every stored automation — rules that fire on events, each defined against the old role names — has to keep working. A Context Migration Record captures the crossing: for each automation, it logs the old role context it was defined with, the mapping that translated those roles into the new grant model, the version stamps of both the source and target schemas, and who ran the migration when. Months later, an automation misbehaves. Instead of guessing, an engineer opens its migration record and sees exactly that this rule was defined under the pre-upgrade "editor" role, mapped to a grant set that — it turns out — dropped one implied permission. The record turns an invisible, silent re-binding into an auditable event with a paper trail.

How it works

  • Record the mapping, not just the result. Store the explicit correspondence from old bindings to new — field-by-field, name-by-name — so the translation can be inspected and, if needed, reversed or replayed.
  • Stamp both endpoints. Attach version and provenance to both the source and target contexts, so any later reader knows precisely which two worlds the unit was carried between.
  • Keep it append-only. Each migration is a new entry, never an overwrite, so the record accumulates a truthful lineage rather than collapsing to a single "current" story.

Tuning parameters

  • Mapping granularity — a coarse "v3 → v4" note, or a field-level correspondence with transforms. Finer mapping enables true reversibility but is heavier to produce and maintain.
  • Provenance depth — who/when only, or full lineage including tool version, inputs, and approvals. Deeper provenance strengthens audits but grows the record.
  • Retention window — how long records are kept. Longer retention preserves traceability across many upgrades but accumulates storage and disclosure surface.
  • Reversibility guarantee — whether the record is rich enough to undo a migration or only to explain it. Full reversibility is powerful but constrains what transforms are allowed.

When it helps, and when it misleads

Its strength is turning a context move — normally an invisible, one-way event — into something inspectable, reversible, and accountable, so a unit that has been carried across three schema upgrades can still be traced to the assumptions it was born with. Anchored well, it functions as an append-only audit log,[1] which is why the "keep it append-only" step matters: an overwritten record silently loses exactly the history it exists to hold. The honest failure mode is a lossy map — a migration that quietly dropped or coerced a binding, faithfully recorded as if nothing were lost, so the record looks complete while the semantics drifted. The classic misuse is writing the record after the fact to rationalize a migration already run, rather than generating it as the migration executes. The discipline is to produce the record from the migration itself, at field granularity, and to reconcile it against a fresh equivalence check rather than trusting that the mapping preserved behavior.

How it implements the components

  • context_migration_map — it holds the explicit old-to-new correspondence that defines how the captured context was translated.
  • context_version_and_provenance — it stamps both source and target with version and origin, fixing which two worlds the unit was carried between and by whom.
  • observability_and_audit_surface — as a durable, inspectable record, it is the audit surface for context moves, making a silent re-binding into a reviewable event.

It records that a migration happened but does not verify the migrated unit still behaves the same — that check is Dual-Run Equivalence Test — and it is not itself the point-in-time snapshot being migrated, which is Versioned Configuration Snapshot.

Notes

The record is descriptive, not enforcing: it explains a migration but does not by itself guarantee the new context is correct. Pairing it with an equivalence check is what upgrades it from "we can see what we did" to "we can see what we did and confirm it still holds."

References

[1] An append-only (write-once) audit log keeps every entry immutable and additive, so history cannot be rewritten. Migration records inherit the same requirement — the value is in the untampered lineage, which an in-place update would destroy. ↩