File versions

The version each kind of graph file carries, which versions a graph release reads, and how to upgrade files.

Each kind of file graph reads carries its own version number, separate from graph’s release version and from each other.

File	Current version
config.toml, global and project	4
Plan file	2
Tool file	2
Agent file	1
Data directory	2
pack.toml	1
packs.lock	1

Check which versions your graph reads

graph version prints the version graph writes for each kind of file, and the oldest it still reads when that differs:

graph version

graph version --json reports both numbers for every kind under fileVersions, as current and oldest.

Compatibility

• graph reads every version from the oldest it supports to the current one. It upgrades an older file in memory as it loads and leaves the file on disk unchanged.
• graph refuses a file outside that range before reading its contents. The error names the file, the version it found and the versions graph reads.

Files graph writes, such as a plan saved from the workbench, always carry the current version. A graph release that doesn’t read that version refuses them, even if they use no new keys.

Deprecation

graph currently reads every file version, back to version 1. A future release will drop the oldest versions, and a deprecation process will give you notice and time to migrate before it does.

Upgrade your files

Run the migrate command for each file you want to bring to the current version. A file already at the current version is left untouched. Commit the migrated files so everyone on your team moves together.

graph config check
graph config migrate
graph config migrate --global
graph plan migrate .graph/plans/weekly_changes.yaml
graph tool migrate .graph/tools/summarize.yaml
graph agent migrate .graph/agents/release_notes.yaml

• config.toml. graph config check reports each config file’s version as current, migrate, too new or too old. graph config migrate keeps comments and layout. graph upgrades the global and project files separately, so they can be at different versions. In a terminal, graph prints a reminder to migrate when it loads an older config file.
• Plan, tool and agent files. Migrating keeps the order of keys and the comment block at the top of the file. Comments further down are dropped, and the command reports how many.

Files outside the range

• A plan file graph can’t read is left out of the catalog. graph plan list --json lists it under skipped, and running it by name reports the version problem.
• A tool file graph can’t read fails tool loading with the file’s name.
• An agent file graph can’t read is reported with its path by graph agent list and graph agent validate.
• A pack.toml or packs.lock graph can’t read stops the pack from installing or loading, with the file’s name.

Data directory upgrades

graph upgrades an older data directory in place the first time a newer release opens it. Concurrent graph processes wait for the upgrade to finish rather than run it twice. Afterwards, releases that don’t read the new version refuse the directory, so copy it first if you may need to go back to an older graph.