docs

Author: hotlong

content/docs/references/cloud/environment-package.mdx

@@ -0,0 +1,148 @@
+---
+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 |
+
+
+---
+