Immutable means immutable
Re-applying identical content to the same version is a no-op — no regeneration, no token rotation. Change the services, operations, auth, injections, or language under an existing version and apply returnsapp_version_immutable.
The fix is always the same: bump the version and publish that. The guided path updates the existing YAML rather than creating a second file:
extend reads the existing YAML to infer SDK mode, then opens the same operation selector as init. Existing services and operations remain in that file, and the app keeps its stable SDK ID.
When the requested merge changes a stable SemVer version, Fused infers the next minor version: 1.0.0 becomes 1.1.0. A terminal shows that successor in the combined confirmation before writing. The same deterministic inference works with --no-input. An idempotent extension keeps its current version.
Pass --version when you want a different successor. A prerelease or non-SemVer version such as 2026-09-01 cannot be advanced safely and always requires an explicit successor.
For the explicit lifecycle, edit the version in the existing file yourself:
sdk validate separately only when you need an offline-only check.
When the Registry moves under you
app_version_immutable is about something you changed. Its sibling is about something Fused changed: when the Registry advances the selection schema your published versions were built against, applying an older plan returns app_selection_schema_version_mismatch (HTTP 409), and fused-cli sdk sync refuses a version whose schema is newer than the CLI understands.
Neither is a data loss. Re-plan so the selections are rebuilt against the current schema, then apply. If sync is the one complaining, upgrade fused-cli first — it is telling you the Engine is ahead of it.
Do not edit a generated package to impersonate another version. The Engine authorizes the opaque
app_id embedded in the package, not a version number the client reports.What carries across versions
Because tokens belong to the SDK rather than a version, a new version that expands capability expands what existing tokens can reach. The plan reports which tokens are affected. If two teams must not share capability, give them different SDK names rather than different versions of one.
There is no implicit “latest.” Every command that resolves a version wants
name@version or a Version ID.
Inspect what shipped
sdk list shows SDK_ID, stable across versions, and VERSION_ID, identifying one exact immutable version.
Flags
sdk download
sdk list
sdk openapi
sdk openapi always writes a file and never prints the document to stdout. It needs your ordinary control credential and app.read — an execution token cannot authorize the export.
Pull the Engine’s state back down
version yourself, then plan and apply it deliberately.
One quirk worth expecting: sync freezes the current selection into an explicit sorted operation list, so a service configured with select_all: true does not come back as select_all: true.
Retiring a version
Permanently deactivate one exact immutable version by name and version or by Version ID:Issue execution tokens
A new version does not need a new token. It may need you to review the old ones.