Environment Package Installation Protocol

Models sys_package_installation — the pairing between an Environment and a specific, immutable sys_package_version snapshot.

Key invariants (per ADR-0003):

One active version per package per environment at any time (UNIQUE (environment_id, package_id)).
Upgrade = atomic UPDATE package_version_id to a newer version UUID.
Rollback = atomic UPDATE package_version_id to an older version UUID.
Only status = 'published' versions may be installed in production environments (draft/pre-release allowed in dev/sandbox with allowDraft).

Stored in the Control Plane DB (not in environment data-plane DBs).

Source: packages/spec/src/cloud/environment-package.zod.ts

TypeScript Usage

import { EnvironmentPackageInstallationSchema, EnvironmentPackageStatusSchema, InstallPackageToEnvironmentRequestSchema, ListEnvironmentPackagesResponseSchema, RollbackEnvironmentPackageRequestSchema, UpgradeEnvironmentPackageRequestSchema } from '@objectstack/spec/cloud';
import type { EnvironmentPackageInstallation, EnvironmentPackageStatus, InstallPackageToEnvironmentRequest, ListEnvironmentPackagesResponse, RollbackEnvironmentPackageRequest, UpgradeEnvironmentPackageRequest } from '@objectstack/spec/cloud';

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

EnvironmentPackageInstallation

Package installation record in an environment (sys_package_installation)

Properties

Property	Type	Required	Description
id	`string`	✅	Unique installation record ID
environmentId	`string`	✅	Environment this installation belongs to
packageVersionId	`string`	✅	UUID of the installed sys_package_version row
packageId	`string`	✅	UUID of the parent sys_package row (denormalized for constraint enforcement)
status	`Enum<'installed' \| 'installing' \| 'upgrading' \| 'disabled' \| 'error'>`	✅	Package installation status within an environment
enabled	`boolean`	✅	Whether the package metadata is loaded
settings	`Record<string, any>`	optional	Per-installation configuration settings
withSampleData	`boolean`	✅	Replay the package seed datasets on next kernel cold-start
installedAt	`string`	✅	Installation timestamp (ISO-8601)
installedBy	`string`	optional	User ID of the installer
updatedAt	`string`	optional	Last update timestamp (ISO-8601)
errorMessage	`string`	optional	Error message when status is error

EnvironmentPackageStatus

Package installation status within an environment

Allowed Values

installed
installing
upgrading
disabled
error

InstallPackageToEnvironmentRequest

Install a package version into a specific environment

Properties

Property	Type	Required	Description
packageVersionId	`string`	optional	Exact package version UUID to install (preferred)
packageManifestId	`string`	optional	Package manifest ID (reverse-domain, e.g. com.acme.crm) — resolved to version UUID
version	`string`	optional	Version string (defaults to latest published)
allowDraft	`boolean`	✅	Allow installing a draft version (dev/sandbox environments only)
settings	`Record<string, any>`	optional	Installation-time configuration settings
withSampleData	`boolean`	✅	Replay the package seed datasets on next kernel cold-start
enableOnInstall	`boolean`	✅	Activate the package immediately after install
installedBy	`string`	optional	User ID of the installer

ListEnvironmentPackagesResponse

List of packages installed in an environment

Properties

Property	Type	Required	Description
packages	`{ id: string; environmentId: string; packageVersionId: string; packageId: string; … }[]`	✅	Packages installed in this environment
total	`number`	✅	Total count

RollbackEnvironmentPackageRequest

Roll back a package installation to a specific older version

Properties

Property	Type	Required	Description
targetPackageVersionId	`string`	✅	Package version UUID to roll back to
rolledBackBy	`string`	optional	User ID performing the rollback

UpgradeEnvironmentPackageRequest

Upgrade a package installation to a newer version

Properties

Property	Type	Required	Description
targetPackageVersionId	`string`	optional	Target package version UUID (preferred)
targetVersion	`string`	optional	Target version string (defaults to latest published)
allowDraft	`boolean`	✅	Allow upgrading to a draft version
upgradedBy	`string`	optional	User ID performing the upgrade

Environment Package

On this page