Entity versioning

GSB has two independent history systems. Use them for different jobs.

System	Enabled by	Created when	Stored in	Restorable
Explicit snapshots	GsbEntityDef.isVersioned	A caller invokes POST /api/entity/addVersion	GsbEntityVersion	Yes
Automatic change tracking	GsbEntityDef.isTracked	Every create or update	GsbTrackVersion	No; it is an audit log

A definition can enable either flag, both flags, or neither. A normal save does not create a GsbEntityVersion snapshot. For example, the live GsbWfFunction definition is versioned but not tracked, while GsbAddress is tracked but not versioned.

When to create a snapshot

Create an explicit snapshot before a risky or meaningful change: a function rewrite, schema migration, workflow redesign, release, or production correction. Routine edits do not need a snapshot. This is narrower and faster than a full tenant backup, but it protects only one entity. Keep tenant backups for tenant-wide releases, migrations, and disaster recovery.

A safe function workflow is:

gsb version add <function-id> \
  --definition GsbWfFunction \
  --note "Before registration validation rewrite"
gsb push .gsb/<tenantCode>/serverless/functions-wf/myFunction

Create an explicit snapshot

The standard version widget calls:

POST /api/entity/addVersion

{
  "entityId": "live-entity-id",
  "entDefId": "entity-definition-id",
  "minor": false,
  "versionInfo": {
    "note": "Before registration validation rewrite"
  }
}

The entity definition must have isVersioned: true. entityId identifies the current entity; entDefId identifies its definition. Write a note that explains why the snapshot exists, not merely that a save occurred.

The minor flag requests the version level. Always query the created GsbEntityVersion row and use its returned version as authoritative. On dev1 testing on 2026-08-26, minor: true still produced the next major value (2.0.0 after an active 1.0.0), so clients must not invent or assume a semantic version.

List and inspect snapshots

Query GsbEntityVersion with entity_id equal to the live entity ID and sort editDate descending. Useful fields are:

• id: snapshot row ID; this is the restore identifier.
• version, level, note: release metadata.
• fullEntity: serialized complete entity snapshot used for preview and restore.
• editDate, editUser_id: audit metadata.

gsb version list <entity-id>
gsb version list <entity-id> --json

MCP clients use listEntityVersions({ entityId, limit }).

Restore a snapshot

Restoration is destructive because it overwrites the current entity state. Pass the GsbEntityVersion.id, not the live entity ID:

POST /api/entity/restoreVersion

{
  "entityId": "gsb-entity-version-row-id"
}

gsb version restore <version-row-id>

The CLI requires tenant-code confirmation unless --yes is supplied. After restore, fetch the live entity and verify the expected fields and currentVersion. If the current state may also be needed, create a snapshot before restoring.

MCP exposes recoverEntityVersion({ versionId }) as a destructive, approval-required tool. Recovery overwrites the current live entity with the selected snapshot. Mutation tools are disabled by default in the server registry; an operator must enable them under the deployment's authorization policy.

Automatic field-change history

When GsbEntityDef.isTracked is true, each create and update adds a GsbTrackVersion row automatically. No addVersion call is needed. Query rows by the live entity's entity_id.

The values field is Base64-encoded JSON. Decoding it yields entries shaped like:

[
  {
    "propName": "title",
    "prevValue": "Old title",
    "newValue": "New title"
  }
]

Creation rows include initial values and generated metadata; update rows contain changed fields. Track rows are protected system logs and cannot be deleted directly. They are for auditing and comparison, not rollback.

gsb version changes <entity-id>
gsb version changes <entity-id> --json

The CLI decodes values in JSON output. MCP clients use listTrackedChanges({ entityId, limit }); consumers should Base64-decode values before rendering it.

MCP operations

Tool	Risk	Default state	Purpose
listEntityVersions	read	enabled	List bounded snapshot recovery metadata
listTrackedChanges	read	enabled	List automatic field changes
addEntityVersion	write	disabled	Validate the definition and create an explicit snapshot
recoverEntityVersion	destructive	disabled	Overwrite the live entity from a snapshot row

MCP credentials and tenant identity come from the verified server session. They are not accepted from model arguments.

Operational checklist

1. Confirm the definition has isVersioned before creating a snapshot or isTracked before expecting audit rows.
2. Create a snapshot before the risky edit, with a meaningful note.
3. Perform and validate the edit.
4. Re-query history; trust the stored version string rather than calculating one locally.
5. Before restore, preserve the current state if it may be needed.
6. Restore by snapshot row ID, then read the live entity and test its behavior.
7. Use a full tenant backup when a change spans many entities or requires disaster recovery.