---
title: Environment Package
description: Environment Package protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# 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).

<Callout type="info">
**Source:** `packages/spec/src/cloud/environment-package.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { EnvironmentPackageInstallation, EnvironmentPackageStatus, InstallPackageToEnvironmentRequest, ListEnvironmentPackagesResponse, RollbackEnvironmentPackageRequest, UpgradeEnvironmentPackageRequest } from '@objectstack/spec/cloud';
import type { EnvironmentPackageInstallation, EnvironmentPackageStatus, InstallPackageToEnvironmentRequest, ListEnvironmentPackagesResponse, RollbackEnvironmentPackageRequest, UpgradeEnvironmentPackageRequest } from '@objectstack/spec/cloud';

// Validate data
const result = EnvironmentPackageInstallation.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** | `Object[]` | ✅ | 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 |


---

