How do I migrate semantic contracts without rewriting operational history?

Classify what changed before assigning a version

A spelling correction differs from splitting “available stock” into physical stock and reservable stock. The second change can alter queries, eligibility rules, user expectations, and actions even when a database migration runs cleanly. Describe the changed interpretation in ordinary language and give a before-and-after decision that makes its consequence visible.

Find consumers beyond direct queries

Inventory mappings, constraints, dashboards, agent tools, policy inputs, exports, and historical decision records. Some dependencies arrive through cached projections or copied reports rather than a live schema reference. Name an owner for each affected consumer and determine whether it can read both meanings during migration. A dependency that is unknown is a migration risk to resolve, not an implicit compatible consumer.

Keep historical evidence interpretable

An earlier reservation may have been justified under a now-retired definition. Preserve the relevant contract and mapping revision with its evidence. A current view may recompute data under a new definition, but label that interpretation separately from what the operator knew at the original time. Changing the current model should not silently rewrite the explanation of past work.

Write a semantic migration record

Record element	Concrete question
Meaning change	Which previously valid conclusion changes?
Affected consumers	Who reads or acts on the old interpretation?
Historical policy	What is preserved, recomputed, or annotated?
Parallel period	Which version combinations are supported?
Reversal	Can current use return safely to the old contract?
Retirement	What evidence proves old active use has ended?

A numerical version label cannot answer these questions by itself. Keep the record beside the actual migration and compatibility tests.

Exercise mixed versions and late records

In a fictional migration, one regional adapter continues emitting the old availability flag after the central service supports the split fields. Verify whether the system translates, rejects, or quarantines those records. Test an old event arriving late and an agent resuming with an earlier projection. Do not let a successful deployment of the central schema stand in for migration of every consumer.

Retire active use without erasing the old contract

Observe adoption and resolve the remaining callers before removing the old path. Retain the minimum historical definitions and lineage needed to interpret recorded decisions under the applicable retention policy. If returning to the old contract would misinterpret newly created state, define a forward repair rather than promising a simple rollback. The release is complete when present operations and historical explanations are both coherent.

Evidence and scope

• W3C DCAT 3: DCAT describes cataloged datasets, distributions, and data services, including version relationships.
• W3C PROV-O: PROV-O represents entities, activities, agents, and derivation relationships.

The proposed checks are teaching tools; validate their behavior in the actual environment.