---
title: Package Registry
description: Package Registry protocol schemas
---

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

# Package Registry Protocol

Defines the runtime state and lifecycle operations for installed packages.

## Key Distinction: App vs Package (ADR-0019)

- **App (AppSchema)**: the one consumer-facing unit — what a tenant downloads,

opens, and uninstalls. Only `type: app` packages are consumer-installable

(see `isConsumerInstallable`), and a consumer package defines **at most one

app** — there is no "suite contains apps" aggregator.

- **Package (Manifest)**: the internal / control-plane artifact term (the

"row" in the installed-packages table). Never surfaced to consumers as a

separate noun.

- **Internal contributions** (plugin/driver/server/…): the "frameworks inside

the .app bundle" — bundled within an App or operator-provisioned; a consumer

never installs them directly.

## Architecture Alignment

- **Salesforce**: Managed Packages with install/uninstall lifecycle

- **VS Code**: Extension marketplace with enable/disable per-workspace

- **Kubernetes**: Helm charts with release state tracking

- **npm**: Package registry with install/uninstall/version management

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

## TypeScript Usage

```typescript
import { DisablePackageRequest, EnablePackageRequest, GetPackageRequest, ListPackagesRequest, NamespaceConflictError, NamespaceRegistryEntry, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel';
import type { DisablePackageRequest, EnablePackageRequest, GetPackageRequest, ListPackagesRequest, NamespaceConflictError, NamespaceRegistryEntry, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel';

// Validate data
const result = DisablePackageRequest.parse(data);
```

---

## DisablePackageRequest

Disable package request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Package ID to disable |


---

## EnablePackageRequest

Enable package request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Package ID to enable |


---

## GetPackageRequest

Get package request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Package identifier |


---

## ListPackagesRequest

List packages request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **status** | `Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>` | optional | Filter by package status |
| **type** | `Enum<'plugin' \| 'ui' \| 'driver' \| 'server' \| 'app' \| 'theme' \| 'agent' \| 'objectql' \| 'module' \| 'gateway' \| 'adapter'>` | optional | Filter by package type |
| **enabled** | `boolean` | optional | Filter by enabled state |


---

## NamespaceConflictError

Namespace collision error during installation

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | Error type |
| **requestedNamespace** | `string` | ✅ | Requested namespace |
| **conflictingPackageId** | `string` | ✅ | Conflicting package ID |
| **conflictingPackageName** | `string` | ✅ | Conflicting package display name |
| **suggestion** | `string` | optional | Suggested alternative namespace |


---

## NamespaceRegistryEntry

Namespace ownership entry in the registry

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **namespace** | `string` | ✅ | Namespace prefix |
| **packageId** | `string` | ✅ | Owning package ID |
| **registeredAt** | `string` | ✅ | Registration timestamp |
| **status** | `Enum<'active' \| 'disabled' \| 'reserved'>` | ✅ | Namespace status |


---

## PackageStatusEnum

Package installation status

### Allowed Values

* `installed`
* `disabled`
* `installing`
* `upgrading`
* `uninstalling`
* `error`


---

## UninstallPackageRequest

Uninstall package request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Package ID to uninstall |


---

## UninstallPackageResponse

Uninstall package response

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Uninstalled package ID |
| **success** | `boolean` | ✅ | Whether uninstall succeeded |
| **message** | `string` | optional | Uninstall status message |


---

