Core replaces a live description-registered Schema and migrates instances by field name (#77) #89

Merged

crowmaki merged 2 commits from schema-migration-77 into main

2026-09-06 02:11:54 +00:00

crowmaki commented

2026-09-06 02:11:42 +00:00

Owner

Closes #77.

What

engine_register_component_schema with a name that a description-registered Schema already holds replaces that Schema and returns the same Component_Type. Live instances migrate by field name (ADR-0020): a kept field with the same Kind carries its value over, a kept field with a different Kind reads as zero, a removed field is dropped, an added field is zero. Component Handles, Object Ids, owners, and dense indices are untouched, so references into a migrated Component still resolve. Replacing an Odin-registered Schema fails with a logged error and Duplicate_Component_Name.

How

core/schema_migration.odin builds a by-name Migration_Plan, rewrites every live instance through value_encode / value_decode into fresh storage, then re-keys the Reference Side Table across every loaded Scene. Every key leaves a table before any is put back, so two reference fields that swap indices keep their own targets.
Everything is built before anything is swapped: a failure at any point frees only the new storage and leaves the previous Schema and every instance in force.
Schema_Storage records a Schema_Origin, which is what decides whether a name may be replaced.
Description validation moves into schema_desc_is_well_formed so the new and replace paths share it.

"Compatible Kind" is implemented as identical Kind; the three Kinds today admit no other compatibility. Migrated instances take the new description's Hooks.

Tests

tests/core/schema_migration_test.odin covers every acceptance criterion: same-type replacement, by-name matching, drop / add / retype, Handle and Object Id survival, Odin refusal, a failed replacement, migration with two Scenes loaded including External Reference re-resolution after the target Scene reloads, a retyped reference dropping its External Reference, and two External References swapping indices.

Post-build failure paths (allocation failure mid-migration) are verified by inspection; the suite cannot inject allocator failure.

just check and just test pass (core: 334 tests).

Closes #77. ## What `engine_register_component_schema` with a name that a description-registered Schema already holds replaces that Schema and returns the same `Component_Type`. Live instances migrate by field name (ADR-0020): a kept field with the same Kind carries its value over, a kept field with a different Kind reads as zero, a removed field is dropped, an added field is zero. Component Handles, Object Ids, owners, and dense indices are untouched, so references into a migrated Component still resolve. Replacing an Odin-registered Schema fails with a logged error and `Duplicate_Component_Name`. ## How - `core/schema_migration.odin` builds a by-name `Migration_Plan`, rewrites every live instance through `value_encode` / `value_decode` into fresh storage, then re-keys the Reference Side Table across every loaded Scene. Every key leaves a table before any is put back, so two reference fields that swap indices keep their own targets. - Everything is built before anything is swapped: a failure at any point frees only the new storage and leaves the previous Schema and every instance in force. - `Schema_Storage` records a `Schema_Origin`, which is what decides whether a name may be replaced. - Description validation moves into `schema_desc_is_well_formed` so the new and replace paths share it. "Compatible Kind" is implemented as identical Kind; the three Kinds today admit no other compatibility. Migrated instances take the new description's Hooks. ## Tests `tests/core/schema_migration_test.odin` covers every acceptance criterion: same-type replacement, by-name matching, drop / add / retype, Handle and Object Id survival, Odin refusal, a failed replacement, migration with two Scenes loaded including External Reference re-resolution after the target Scene reloads, a retyped reference dropping its External Reference, and two External References swapping indices. Post-build failure paths (allocation failure mid-migration) are verified by inspection; the suite cannot inject allocator failure. `just check` and `just test` pass (core: 334 tests).

crowmaki added 2 commits

2026-09-06 02:11:42 +00:00