Read the version history
| Tool | What it does |
|---|---|
shape_workbench_version_graph | View the shape’s version history. |
shape_workbench_version_graph to see the committed versions of a shape and
how they relate. It is the starting point before you change anything: you are
reading where the shape has been so you know what you are evolving from.
Why versions are load-bearing
When you materialize a shape, the graph it governs records which version produced each node and edge. Delta provenance ties every committed node and edge back to the shape version that staged it. That is what makes migration tractable. The runtime can tell which entities were written under v1 and which under v2, so a migration is a concrete operation over a known population rather than a guess.Provenance is recorded at materialize time. A shape you have only compiled (a
draft) has version hashes from
shape_workbench_compile, but it has not
written provenance into any graph until you materialize it.Assert version alignment
Before you plan a migration, confirm what you are aligned to. A session you opened a while ago, or a graph you are about to migrate, may not be on the version you think it is.| Tool | What it does |
|---|---|
shape_workbench_assert_version_alignment | Confirm a session or graph is aligned to a version. |
shape_workbench_assert_version_alignment proves alignment at one of two
strengths:
- Strict — checks node and edge provenance against the version. Use this when relationships changed, or when you need full confidence the whole graph matches.
- Node-only — checks node provenance against the version. A lighter proof for when you only touched types and properties, not relationships.
Plan a migration
Once you have changed a materialized shape and compiled the new draft, plan the migration from the committed version to the new one.| Tool | What it does |
|---|---|
shape_workbench_diff | Diff the draft against the committed shape. |
shape_workbench_plan_migration | Plan a migration between versions. |
shape_workbench_diff shows you exactly what changed between the draft and the
committed shape. shape_workbench_plan_migration turns that delta into a plan
for moving the graph from one version to the next.
The change cascade
Changing a materialized shape follows a fixed sequence. Each step is a Workbench tool you drive conversationally in your client.Open the shape for edit
shape_workbench_open with mode: "edit" against the materialized shape.
Editing the live shape produces its next version. (Use mode: "fork" only if
you want a separate derived shape instead of a new version of this one.)Make your changes
Add, edit, or remove types, properties, and relationships with the
authoring tools.
Plan the migration
shape_workbench_plan_migration to plan the move from the committed version
to the new one.Next
Author shapes
The authoring tools you use to make the change before you migrate.
Materialize
Commit the new version to the project so the runtime picks it up.