Module migrate 

W305/R742-F3 — planning a workload’s move between sovereign groups.

yah cloud migrate <workload> --to <sovereign-group> is the verb that keeps environment off the node. Without it, “run dev on the Pis” quietly becomes “dev lives on the Pis forever”, and the pressure to encode the environment as a property of hardware — the mistake W305 exists to undo — comes straight back.

This module plans; it does not move

Operator call, 2026-08-15: migrate computes and refuses, the operator executes. The reason is that the stateful half has no substrate under it. A VolumeSource::Named materialises as a host bind at /var/lib/yah/kamaji/volumes/<name> (kamaji-containerd-core), and there is no volume export/import/snapshot route anywhere in yubaba or kamaji — so “the volume has to follow” means inventing node-to-node data movement on a live fleet. That is its own design (atomicity, checksums, enforcing at-most-one-live across the cut) and its own relay.

What is not deferred is the correctness story. Everything that can be decided from the declarations is decided here and fails loud: which group a workload may go to, which box in it will take the workload, which volumes must follow and which must deliberately not, which ordering the two archetype halves require, and the four ways the move is refused outright. A MigrationPlan is a pure function of the camp’s TOML plus the observed placement — no network, no credentials.

The two halves

The ticket’s framing, and it falls straight out of LifecycleArchetype:

• Stateful (LifecycleArchetype::Appliance) — a volume that must follow, at most one live instance, not drainable. The move is therefore stop → copy → start, and the downtime is inherent rather than incidental: starting the target first would put two live instances on a workload whose whole archetype is “there is only ever one”.
• Fungible (LifecycleArchetype::Server / LifecycleArchetype::Job) — no state to move. The move is start → verify → stop, which has no downtime, and there is no copy step at all.

Rendering one procedure for both would have to pick one ordering, and either choice is wrong for the other half.

@arch:see(.yah/docs/working/W305-sovereign-groups-environments-edges.md)

Structs

MigrationPlan

A checked, ordered move of one workload from one machine to another in a different sovereign group.

MigrationStep

One ordered step of the rendered procedure.

Precondition

A precondition the move depends on that this planner cannot satisfy or verify, stated so it is done before the cut rather than discovered after.

Enums

MigrationRefusal

Why a migration cannot be planned.

VolumeDisposition

What happens to one declared volume mount when the workload moves.

Constants

KAMAJI_VOLUME_ROOT

Host directory kamaji binds a VolumeSource::Named from.

Functions

named_volume_path

Absolute host path backing the named volume name.

plan_migration

Plan the move of workload into sovereign group to_group.