Module migrate 

schema migrate — rewrite an authoring package’s retired keys into the current schema language, by exactly the translations the loader applies to sealed packages.

The loader keeps every retired key as a serde sentinel on the type structs (the legacy_* fields in types.rs): sealed content is translated so shipped packages keep loading, authoring content refuses with a rename pointer so the author acts. This module is the act: it gives a directory package the same translation the sealed path performs, as a reviewable rewrite of the author’s own files.

One table. LEGACY_KEYS is the only enumeration of retired keys and their rewrites. The suite pins it against the sentinel declarations in types.rs (every legacy_* sentinel names a table row and vice versa), and the verb proves each rewrite faithful at run time: the original loads through the tolerant sealed-style read, the rewrite through the strict authoring read, and what the loader resolved from each must agree. A rewrite that does not reproduce the loader’s translation refuses instead of writing.

Text, not a YAML round-trip: serde_yaml_ng drops comments, and an author package is source — comments, key order, and spacing are the author’s. The rewriter tracks the block-mapping path line by line, edits only the lines the table names, and leaves every other byte alone. Keys it cannot reach (quoted keys, flow-style mappings) are caught by the faithfulness check, never silently skipped.

Polarity. The retired optional: key existed only under the pre-flip language, where an ABSENT key meant required; the sealed read of an unmarked package still gives it that meaning (MetadataPolarityFormat::Legacy). A package that carries optional: anywhere was therefore written under that language, and the migration conserves what it meant: every metadata field declaring neither key gets required: true, so the package says under the current language exactly what the sealed read made of it. The dry run shows each inserted line; deleting one is the author’s call, not the engine’s.

Structs

BareField

A metadata field that declared neither optional: nor required: in a package written under the pre-flip language (it carried the retired optional: key), and therefore received required: true — the meaning the sealed read gives it.

FileMigration

One type file’s migration: the rewrites and the resulting text.

LegacyKey

One retired key: its spelling, where it sits, what replaces it.

MigrateReport

The computed migration of one package. Computing never writes; write_migration applies it.

Rewrite

One rewritten occurrence of a retired key.

Enums

LegacyRewrite

What the loader’s sealed translation does with the key — and therefore what the rewriter writes.

LegacyScope

Where in a type file a retired key sits.

MigrateError

Why a migration could not be computed or written.

RewriteAction

What one rewrite did to one line.

Constants

LEGACY_KEYS

The retired keys the loader still reads on sealed content, with the translation it applies — the single definition the migrate verb rewrites from. Mirrors the legacy_* serde sentinels in types.rs one-to-one; the suite fails when either side gains a key the other lacks.

Functions

migrate_package

Compute the migration of the authoring package at dir. Reads only; the report carries the rewritten texts for write_migration.

next_steps

The author’s follow-up commands after a --write, in order.

write_migration

Write the report’s changed files in place. Files without rewrites are not touched.