Load and save projects.

Loading a project, changing the working graph, saving its bundle, and reloading a copy are different actions. Keep project IDs and versions from actual receipts rather than treating a project name as identity.

#Read both parts of a save receipt

A save can persist a project while the attached Studio tab still needs reconciliation. Inspect the returned persistence and adoption fields, including any adoption guard. Keep the saved project identity and verify which project the tab now owns. Replacing or closing the tab without inspecting these outcomes can lose unsaved local work. The controls only compare example outcomes.

Updating A keeps the project identity. Saving a separate copy produces B while the editor can still show A; confirming adoption changes the editor binding to B without changing B’s saved content. Persistence and adoption remain independently inspected receipts.

#Work in the headless graph

Use list_projects, then load_project(project_id) to replace the server's headless working graph with the intended project. Inspect and edit that graph, then save_project(name, project_id, expected_version) to update it using the observed saved-project version. For a new named project, use the new-save contract instead of passing an unrelated existing ID.

Scratch single-node execution is not this working graph and cannot be saved through this workflow. Add and connect persistent nodes when you need work that can be extended and reopened.

#Save an attached Studio graph

Attach explicitly and read the current session's saveContext, including project ID and bundleVersion, plus the live graphRevision. An update uses the same project ID, its bundle version as expected_version, and current expected_revision. Changing the name on that update renames the same project.

For a separate copy, omit project_id and use expected_version:0 with the current editor revision. This can save live unsaved work into a new bundle. Inspect bundleSaved, versionConfirmed, returned bundle version, and any reloadCopyState separately. A saved bundle and editor adoption/reloading are not the same fact.

#Treat attached loading as conditional

Attached load_project is not enabled in every deployment. When available, it requires current revision and a supported different personal project; reserved/temporary or unsupported team contexts can be refused. Respect STUDIO_ACTION_NOT_ALLOWED or other availability responses. Do not silently retry the refused action against a headless graph.

#Check identity and receipt before retrying

Headless: load the intended saved project into the headless working graph and update it with its saved version. Attached update: use the same project ID, bundle version and current live revision. Copy: omit project ID, use new-save version zero, and inspect save versus reload/adoption receipts. Attached loading is deployment-dependent and must not silently fall back.

#Recover without overwriting another context

Retain a pending actionId and inspect the original action after uncertainty. If a bundle save succeeded but editor adoption was incomplete, do not assume the entire operation failed and create another copy. Read the receipt and current tab before deciding the next action.

For stale saved versions, reread and reconcile the project. For stale editor revisions or lost attachment, refresh the live context. These failures need different repairs. See Live Studio sessions and Permissions and troubleshooting.