Skip to content

Migrate a local projection while keeping old artifacts readable

Version field mappings and compatibility checks instead of silently renaming the only schema.

Guides

Migrate a local projection while keeping old artifacts readable — what should the operator record?

A local table contract may need to evolve as returned evidence structures or operational needs change. A controlled migration keeps older artifacts interpretable and makes current failures explicit. Separate the mapping revision from the input receipt so a schema update is not mistaken for newly retrieved evidence.

Practical operations check
Version field mappings and compatibility checks instead of silently renaming the only schema.
Record from_mapping_revision, to_mapping_revision and the changed paths or types, preserving the actual source receipt identity. A migration record can distinguish path rename from semantic change, since only the former might preserve values without a new interpretation review or additional evidence.
Publish the accepted mapping revision and identify historical artifacts that cannot be migrated faithfully without additional authorized evidence. The release note should identify accepted input shapes and blocked cases narrowly, avoiding claims that one mapping proves compatibility across all source types or client implementations.
01 / Guides

Name old and new contracts

Record from_mapping_revision, to_mapping_revision and the changed paths or types, preserving the actual source receipt identity. A migration record can distinguish path rename from semantic change, since only the former might preserve values without a new interpretation review or additional evidence.

02 / Guides

Define the migration rule

Explain renamed, derived and removed columns separately, including how missing historical fields remain unknown rather than being invented during migration. Removed columns should stay documented as intentionally omitted; a missing historical field cannot be backfilled from a newer unrelated response merely to satisfy the latest schema.

03 / Guides

Test both representations

Use labeled fixtures for old and new input shapes and compare the expected shared output fields and explicit unsupported cases. Test an unsupported historical case too, showing that the adapter fails explicitly instead of fabricating a complete new-format table from insufficient older input.

04 / Guides

Reconcile migrated artifacts

Check membership, qualified identifiers and provenance references after conversion, keeping any changed interpretation in an exception ledger. Compare qualified keys before and after migration, and inspect any changed null handling that could silently alter membership or downstream eligibility even when row counts match.

05 / Guides

Release with compatibility limits

Publish the accepted mapping revision and identify historical artifacts that cannot be migrated faithfully without additional authorized evidence. The release note should identify accepted input shapes and blocked cases narrowly, avoiding claims that one mapping proves compatibility across all source types or client implementations.

Keep the boundaries clear.

  • Version field mappings and compatibility checks instead of silently renaming the only schema.
  • Operational record: Name old and new contracts. Context badges do not certify access.

Start with a read-only check: ask your agent to report actual source coverage before collecting records or exporting an audience.

Primary references

Documentation reviewed 2026-11-15. Product capabilities, client availability and plans can change. Third-party marks identify their products, not an affiliation.

Know what social media shows about you.
Start with a question.

Get started
montage