Versioning and Release
Use immutable versions and release pointers for SOIT agents, workflows, plugins, and other capabilities.
SOIT uses immutable versions so runtime behavior can be reproduced and audited. Releases move pointers to approved versions instead of mutating version records in place, and every publish or rollback writes an append-only release ledger record.
Canonical terms
| Term | Meaning |
|---|---|
| Subject | The versioned business object: an agent, workflow, or plugin |
| Head version | The latest working version, possibly a draft (current_version_id) |
| Live version | The version formal execution uses (published_version_id) |
| Draft | A version that exists but is not live yet |
| Publish | Promote an existing version to live and write a release record |
| Rollback | Point live back to a previous version and write a release record |
| Preview | Explicitly run a draft or a specified version, separate from live execution |
Pointer semantics
Each versioned subject keeps two pointers, and the operations on them follow strict rules:
create_draftcreates a new immutable version and advancescurrent_version_id.publish(version_id)never creates a version — it promotes an existing one to live.rollback(version_id)never creates a version — it moves the live pointer back and records the rollback.published_version_idmay be null when a subject has never been published.
Runtime behavior
- Formal execution uses the live version only. A production request must never silently consume a draft.
- Preview and debug execution uses an explicit
version_id, or falls back to the head version. - Every run records the exact subject version it executed (
subject_version_idin the runtime ledger), which makes observe, audit, rollback, and evaluation meaningful.
Immutability
Version rows are immutable snapshots after creation. The spec payload (spec_json) is never updated in place; only lifecycle metadata such as status and release annotations may change. The normalized version status set is draft, published, superseded, and archived — but which version is live is decided by the subject pointer, not the status field alone.
Release ledger
Publish and rollback actions append to a release ledger that is queryable through stable read endpoints:
GET /api/v1/agents/{agent_id}/releasesGET /api/v1/workflows/{workflow_id}/releasesGET /api/v1/plugins/{plugin_id}/releases— covers plugin-owned skill and MCP artifacts
Release records expose the action (publish / rollback), scope, status, from_version_id, to_version_id, notes, rollback provenance, and author — enough for the UI to render full publish history.
How subjects map to tables
- Agents:
agents+agent_versions+agent_publishes. - Workflows:
workflows+workflow_versions+workflow_publishes. - Skills and MCP servers: not independently versioned — they are plugin artifacts and inherit the plugin lifecycle through
plugin_versionsandplugin_releases. See MCP and Skills.
A shared VersionControlService owns draft/publish/rollback orchestration; each module contributes a subject adapter for domain validation and side effects, so the lifecycle semantics stay identical across subjects.
Compatibility
Schema and API changes must preserve existing version records. Breaking changes are release events that require explicit migration and compatibility planning — see Migration and Upgrade.