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.
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.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.
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.
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.
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.
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.