fix(registry): enforce that a canister's cycles cost schedule never changes

[mraszyk]

The cycles prepaid for a response execution are recorded in the callback under the cost schedule in effect when the call was performed, and settled when the response is executed against the cycles that execution requires, derived under the cost schedule in effect by then. The two amounts are only comparable if both were derived under the same cost schedule: an amount that is free under the free cost schedule has a zero real part but a non-zero nominal one, so settling across a switch either forfeits the real part of the prepayment or credits the canister with real cycles that were never withdrawn from its balance.

Nothing enforced that today. This PR enforces it for every canister that a subnet hosts, with one gap that it cannot close and documents instead: see Known gap.

The property, not its mutations

A canister is charged under the cost schedule of the subnet that the routing table assigns its canister ID to, so check_canister_cost_schedule_invariants compares, for every canister ID routed both before and after the mutations under check, the cost schedule of the subnet that hosted it with the one of the subnet that hosts it now. That covers both ways of changing it — moving the canister and changing the cost schedule of its subnet — in any combination, and hence every mutation of the routing table or of a subnet record, present and future.

Enforcing this at the individual mutations instead would have kept missing paths: merge_subnets moves every canister ID range of the source subnet to the destination subnet without touching either subnet record, and do_migrate_canisters reassigns individual canisters without validating anything at all, not even that the target subnet exists.

check_subnet_cost_schedule_immutability is kept alongside it as the stronger and simpler statement — no existing subnet ever changes its cost schedule, whichever mutation would change it; a newly created subnet is free to pick either. It also catches a change on a subnet that hosts no canister ID range yet.

Validation at the mutations

An invariant failure traps, so the paths that a proposal or the canister migration orchestrator can reach validate the cost schedules themselves and report which subnets, or which canister, are at fault:

• prepare_canister_migration rejects preparing a migration between subnets on different cost schedules. This one is not covered by the invariant at all: it only writes canister_migrations, and the move happens later in reroute_canister_ranges;
• merge_subnets rejects merging a source subnet into a destination on a different cost schedule;
• do_migrate_canisters rejects migrating a canister to a subnet on a cost schedule other than that of the subnet hosting it.

reroute_canister_ranges compares nothing of its own: it only reroutes ranges covered by a canister migration, which prepare_canister_migration has already validated. do_split_subnet needs no check either, as the new subnet inherits the cost schedule of the source subnet.

All comparisons normalize Unspecified to Normal, as a subnet record that predates the field leaves it unset and the replica reads that as Normal.

What the checks cost

Reading the subnet records and the routing table is not free, and a first version of this PR had every mutation pay for reading the routing table twice over — once from the registry for its pre-mutation state and once from the snapshot, each read decoding every canister ranges shard. The canbench benchmarks caught it: migrate_canisters_* regressed by 71% to 74% and upgrade_with_routing_table_* by 5% to 11%.

Each check is now charged to the mutations that can actually break it:

• a subnet record mutation pays for check_subnet_cost_schedule_immutability;
• a canister ranges shard mutation pays for check_canister_cost_schedule_invariants, which compares only the shards that mutation touches. A canister ID whose covering entry did not change is still assigned to the same subnet, and the cost schedule of that subnet cannot have changed either, which the invariant above enforces. An entry can move between shards, e.g. when two adjacent ranges are merged into one, which mutates the shard it leaves as well as the shard it lands in, so both are compared. The shards are collected into a set, as a single batch can mutate one of them more than once and decoding a shard twice would produce duplicate entries, which RoutingTable rejects;
• every other mutation, post_upgrade with its empty mutation list included, pays for neither.

Thirteen of the fourteen benchmarks are within the noise threshold with that in place. migrate_canisters_10_times_100 remains 4.81% more expensive, which is the cost of the check itself on a routing table small enough for it to show — the 1k and the 10k variants of the same benchmark are within noise — and the recorded results are updated accordingly.

Known gap: canister IDs that pass through an unrouted state

An unrouted canister ID has no cost schedule, so a canister ID that passes through an unrouted state is not covered by any of the above. do_migrate_canisters unroutes a canister ID when the target subnet is absent from the routing table, remove_subnet_from_routing_table does when its subnet is deleted, and do_migrate_canisters then supports routing it to a subnet again — that is how a canister whose subnet was deleted is migrated (test_migrate_canisters_succeeds_if_source_subnet_deleted). Two such calls in a row move a canister ID between cost schedules unchecked, and unrouting does not destroy the canister state, callbacks included.

This was raised in review and is documented rather than fixed, as none of the available remedies fits in this PR:

• preserve the cost schedule each unrouted canister ID last had and compare against it. Sound, but it takes a new persistent registry record and a lifecycle for it, i.e. a change to the canister migration protocol that is the governance team's call;
• make unrouting terminal, i.e. refuse to route an unrouted canister ID to any subnet. This breaks the migration of a canister off a deleted subnet, which the test named above covers;
• prove the source cost schedule compatible at the second call. There is nothing to prove it against: the canister ID is unrouted, so the registry state carries no schedule for it, and finding the last version at which it was routed means scanning the changelog backwards without a bound, which a canister cannot do.

Reaching the gap takes a canister migration orchestrator that unroutes a canister and then routes it to a subnet on a different cost schedule, which is not part of any current flow. The gap is documented on check_canister_cost_schedule_invariants and pointed at from the skip in Registry::validate_cost_schedules, so it is not left implicit in the code either.

Shipping with it is a call for a reviewer to make rather than mine: if it should be closed, the persistent record of the cost schedule each unrouted canister ID last had is the way to do it, and it belongs in its own change to the canister migration protocol.

Relation to #11431

Independent of #11431 (no shared files), but that PR relies on this assumption: it settles the prepayment on the nominal parts, which ignores a cost schedule switch entirely, whereas comparing the real parts happened to detect one. Merging this first means the assumption is enforced before anything depends on it.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The critical merge_subnets cost-schedule validation gap remains unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Enforces stable cycles cost schedules for canisters across registry mutations and migrations.

Changes:

• Rejects migrations across differing normalized cost schedules.
• Adds schedule normalization and immutability checks.
• Adds regression tests.

File summaries

File	Review
rs/registry/canister/src/mutations/prepare_canister_migration.rs	Critical: merge_subnets can still move canisters across differing schedules; add validation and regression coverage.
rs/registry/canister/src/mutations/common.rs	Adds cost-schedule normalization.
rs/registry/canister/src/invariants/subnet/tests.rs	Tests schedule immutability.
rs/registry/canister/src/invariants/subnet.rs	Implements the immutability invariant.
rs/registry/canister/src/invariants/checks.rs	Integrates the invariant into registry checks.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

Approval-readiness assessments conflict, and one diagnostic nit remains unresolved.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Critical validation gaps still allow canisters to change cost schedules through unassigned routing intervals.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Reassigning an unrouted canister can still bypass schedule compatibility checks and permit cross-schedule settlement.

Review details

Suppressed comments (1)

rs/registry/canister/src/mutations/do_migrate_canisters.rs:105

• This continue leaves the financial invariant bypassable: an ID unassigned by do_migrate_canisters when its target is absent can later be assigned by the same endpoint to any routed subnet, regardless of its former schedule. Because callbacks survive unrouting, that concrete two-call sequence can still settle a prepayment across Normal/Free schedules—the exact corruption this PR is intended to prevent. Preserve the last schedule for unrouted canisters and compare it here, or reject reassignment unless the source schedule can be proven compatible.

            let Some((_range, source_subnet_id)) = routing_table.lookup_entry(*canister_id) else {
                continue;

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🟢 Approval recommended

The implementation and coverage are consistent, with only a non-blocking documentation correction remaining.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

The registry-wide migration invariant has broad operational impact and retains a documented unrouted-canister gap requiring human acceptance.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 0 new
• Review effort level: Balanced