# Unified Runtime Data Migration

> Canonical path: `specs/deployment/unified-runtime-data-migration.md`
> Status: living deployment runbook
> Scope: preserving AgentTeam, MeshX, and AGS data when moving from standalone MeshX to the unified runtime.

## Risk

SQL rows and repository content have different persistence boundaries. AgentTeam,
MeshX, and AGS schemas remain in their configured databases, while AGS Git
objects and other MeshX files live under the MeshX data root. A deployment can
therefore preserve every SQL row but expose an empty repository directory if
the unified runtime receives a new volume.

The container path `/data/meshx/ags-repos` is not proof that old and new
processes use the same persistent volume.

## Preconditions

Before migration:

1. identify the exact old MeshX volume or host data root and the new unified
   runtime data root for the target environment;
2. record the AgentTeam, MeshX, and AGS DSNs and verify that deployment will keep
   pointing to the existing databases;
3. produce a preflight inventory with the expected number of AGS bare
   repositories and retained references;
4. stop API, Desktop sync, mirror, Automation, and every other repository
   writer;
5. from the same quiesced recovery point, back up all three databases and the
   complete old MeshX data root.

Do not start schema migration or the unified runtime until these facts are
recorded and the backups are restorable.

## Copy and verify

Mount old and new data roots at different explicit paths in an admin container
or host. Run:

```bash
scripts/migrate-unified-runtime-volume.sh \
  --expected-repositories "$EXPECTED_AGS_REPOSITORIES" \
  copy /mnt/old-meshx-data /mnt/new-agentteam-data

scripts/migrate-unified-runtime-volume.sh \
  --expected-repositories "$EXPECTED_AGS_REPOSITORIES" \
  verify /mnt/old-meshx-data /mnt/new-agentteam-data
```

`EXPECTED_AGS_REPOSITORIES` comes from the preflight database/backup
inventory. Zero repositories fail by default. `--allow-empty` is permitted
only for an independently verified environment that has never stored an AGS
repository.

The script fails closed when the required source marker is absent, source and
target are the same root, inventory differs, Git integrity fails, or a
non-empty target differs from the source. Source inventory and `git fsck` run
before any target mutation. Copy uses one hidden staging tree; a failed copy
removes staging and can be retried safely. All present subtrees are staged and
globally verified before the script publishes the complete `meshx` tree with
one rename. A later run verifies an already-published identical tree as an
idempotent success and never merges into or overwrites a divergent target.

Verification compares filesystem entry types, sizes, and SHA-256 digests, then
checks every bare repository's integrity, HEAD, full ref inventory, and object
inventory.

## Cutover

After copy and verify succeed:

1. run schema initialization against the existing three databases;
2. start one unified runtime with the verified new data root;
3. check readiness and confirm the configured AGS repository path resolves
   inside that data root;
4. repeat repository count, HEAD/ref/object checks and sample representative
   repository trees through the application read path;
5. smoke-test Knowledge Base, Skill, Memory, and Automation reads before
   reopening writers;
6. reopen traffic gradually and retain the old data root and backups as
   read-only rollback inputs.

Any mismatch keeps writers stopped and blocks cutover.

## Rollback

Rollback restores the complete previous release topology, the three databases,
and the old MeshX data root from one compatible recovery point. Do not combine
a database from one point with repository files from another. If writers were
reopened after cutover, first quiesce them and follow the environment's approved
forward-data reconciliation procedure; never overwrite either volume in place.

The old MeshX volume and AGS database must not be deleted during the cutover
change. Retention ends only after the agreed rollback window and an independent
verification that all required native ContentVersions and product references are
readable.