# Issue Graph Migration
Issue `number:` values remain useful aliases for people, but graph storage uses
the canonical `id:` field. `tix migrate issue-graph` converts older files that
still store numeric `parent:`, `relationships.from`, or `relationships.to`
values.
## Preview
```sh
tix migrate issue-graph
```
The preview reports issue files that will receive a generated canonical id,
parent and relationship endpoints that will be rewritten, unresolved
references, ambiguous numeric aliases, and duplicate canonical ids. It writes no
issue file.
## Apply
```sh
tix migrate issue-graph --apply
```
Apply is atomic. If any reference is ambiguous, unresolved, or shares a
canonical id with another issue, the migration refuses and leaves every issue
byte-identical. Repair the reported references and rerun.
On success, missing ids are backfilled, numeric graph endpoints become canonical
ids, and unknown frontmatter and Markdown bodies are preserved. Running the same
command again reports no changes.
## Verify from a temporary repository
```sh
tmp="$(mktemp -d)"
cd "$tmp"
tix init
tix create --title Parent
tix create --title Child --parent Parent
printf '\n# Preview: no issue file changes.\n'
tix migrate issue-graph
printf '\n# Apply once.\n'
tix migrate issue-graph --apply
printf '\n# A second apply is a no-op.\n'
tix migrate issue-graph --apply
```
The raw `parent:` and relationship endpoint values now name ids. Commands such
as `tix edit 2 --parent 1` continue to accept numbers as input aliases.
## Rollback
Apply uses the same write journal as other multi-file commands. If any write
fails, every issue touched by the plan is restored to its pre-apply bytes and
the original error is returned. Preview, ambiguity, and unresolved-reference
failures happen before the first write.
## Mixed branches
Run the preview before merging branches whose issue files may both have created
the same human number. A canonical id disambiguates them; a numeric selector does
not. After merge, rerun the preview and repair any reported duplicate id or
ambiguous reference before applying.
Do not merge raw parent or relationship endpoint changes without running the
preview on the merged tree. The preview is read-only and is the conflict check
for shared numbers, duplicate ids, and dangling endpoints.