Package Upgrade Protocol

Defines the complete lifecycle for upgrading installed packages,

including pre-upgrade analysis, snapshot/backup, execution, validation,

and rollback capabilities.

Architecture Alignment

Salesforce: Managed Package upgrade with push upgrades and subscriber control
ServiceNow: Update Sets with preview, commit, and back-out support
Helm: Helm upgrade with rollback to previous release
Kubernetes: Rolling update with readiness probes and automatic rollback

Upgrade Flow


1. PreCheck    → Validate compatibility, check dependencies

2. Plan        → Generate upgrade plan with metadata diff

3. Snapshot    → Backup current state (metadata + customizations)

4. Execute     → Apply new package metadata with 3-way merge

5. Validate    → Run post-upgrade health checks

6. Commit      → Finalize upgrade (or Rollback on failure)

Source: packages/spec/src/kernel/package-upgrade.zod.ts

TypeScript Usage

import { MetadataChangeTypeSchema, MetadataDiffItemSchema, RollbackPackageRequestSchema, RollbackPackageResponseSchema, UpgradeImpactLevelSchema, UpgradePackageRequestSchema, UpgradePackageResponseSchema, UpgradePhaseSchema, UpgradePlanSchema, UpgradeSnapshotSchema } from '@objectstack/spec/kernel';
import type { MetadataChangeType, MetadataDiffItem, RollbackPackageRequest, RollbackPackageResponse, UpgradeImpactLevel, UpgradePackageRequest, UpgradePackageResponse, UpgradePhase, UpgradePlan, UpgradeSnapshot } from '@objectstack/spec/kernel';

// Validate data
const result = MetadataChangeTypeSchema.parse(data);

MetadataChangeType

Type of metadata change between package versions

Allowed Values

added
modified
removed
renamed

MetadataDiffItem

Single metadata change between package versions

Properties

Property	Type	Required	Description
type	`string`	✅	Metadata type
name	`string`	✅	Metadata name
changeType	`Enum<'added' \| 'modified' \| 'removed' \| 'renamed'>`	✅	Category of metadata modification (added, modified, removed, or renamed)
hasConflict	`boolean`	✅	Whether this change may conflict with customizations
summary	`string`	optional	Human-readable change summary
previousName	`string`	optional	Previous name if renamed

RollbackPackageRequest

Rollback package request

Properties

Property	Type	Required	Description
packageId	`string`	✅	Package ID to rollback
snapshotId	`string`	✅	Snapshot ID to restore from
rollbackCustomizations	`boolean`	✅	Whether to restore pre-upgrade customizations

RollbackPackageResponse

Rollback package response

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether the rollback succeeded
restoredVersion	`string`	optional	Version restored to
message	`string`	optional	Rollback status message

UpgradeImpactLevel

Severity of upgrade impact

Allowed Values

none
low
medium
high
critical

UpgradePackageRequest

Upgrade package request

Properties

Property	Type	Required	Description
packageId	`string`	✅	Package ID to upgrade
targetVersion	`string`	optional	Target version (defaults to latest)
manifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	optional	New manifest (if installing from local)
createSnapshot	`boolean`	optional	Whether to create a pre-upgrade backup snapshot
mergeStrategy	`Enum<'keep-custom' \| 'accept-incoming' \| 'three-way-merge'>`	optional	How to handle customer customizations
dryRun	`boolean`	optional	Preview upgrade without making changes
skipValidation	`boolean`	optional	Skip pre-upgrade compatibility checks

UpgradePackageResponse

Upgrade package response

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether the upgrade succeeded
phase	`Enum<'pending' \| 'analyzing' \| 'snapshot' \| 'executing' \| 'migrating' \| 'validating' \| 'completed' \| 'failed' \| 'rolling-back' \| 'rolled-back'>`	✅	Current upgrade phase
plan	`{ packageId: string; fromVersion: string; toVersion: string; impactLevel: Enum<'none' \| 'low' \| 'medium' \| 'high' \| 'critical'>; … }`	optional	Upgrade plan
snapshotId	`string`	optional	Snapshot ID for rollback
conflicts	`{ path: string; baseValue: any; incomingValue: any; customValue: any }[]`	optional	Unresolved merge conflicts
errorMessage	`string`	optional	Error message if upgrade failed
message	`string`	optional	Human-readable status message

UpgradePhase

Current phase of the upgrade process

Allowed Values

pending
analyzing
snapshot
executing
migrating
validating
completed
failed
rolling-back
rolled-back

UpgradePlan

Upgrade analysis plan generated before execution

Properties

Property	Type	Required	Description
packageId	`string`	✅	Package identifier
fromVersion	`string`	✅	Currently installed version
toVersion	`string`	✅	Target upgrade version
impactLevel	`Enum<'none' \| 'low' \| 'medium' \| 'high' \| 'critical'>`	✅	Severity assessment from none (seamless) to critical (breaking changes)
changes	`{ type: string; name: string; changeType: Enum<'added' \| 'modified' \| 'removed' \| 'renamed'>; hasConflict: boolean; … }[]`	✅	All metadata changes
affectedCustomizations	`integer`	✅	Count of customizations that may be affected
requiresMigration	`boolean`	✅	Whether data migration scripts are needed
migrationScripts	`string[]`	optional	Paths to migration scripts
dependencyUpgrades	`{ packageId: string; fromVersion: string; toVersion: string }[]`	optional	Dependent packages that also need upgrading
estimatedDuration	`integer`	optional	Estimated upgrade duration in seconds
summary	`string`	optional	Human-readable upgrade summary

UpgradeSnapshot

Pre-upgrade state snapshot for rollback capability

Properties

Property	Type	Required	Description
id	`string`	✅	Snapshot identifier
packageId	`string`	✅	Package identifier
fromVersion	`string`	✅	Version before upgrade
toVersion	`string`	✅	Target upgrade version
tenantId	`string`	optional	Tenant identifier
previousManifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	✅	Complete manifest of the previous package version
metadataSnapshot	`{ type: string; name: string; metadata: Record<string, any> }[]`	✅	Snapshot of all package metadata
customizationSnapshot	`Record<string, any>[]`	optional	Snapshot of customer customizations
createdAt	`string`	✅	Snapshot creation timestamp
expiresAt	`string`	optional	Snapshot expiry timestamp

Package Upgrade

On this page