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

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

TypeScript Usage

import { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, InstalledPackage, ListPackagesRequest, ListPackagesResponse, NamespaceConflictError, NamespaceRegistryEntry, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel';
import type { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, InstalledPackage, ListPackagesRequest, ListPackagesResponse, 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

DisablePackageResponse

Disable package response

Properties

Property	Type	Required	Description
package	`Object`	✅	Disabled package details
message	`string`	optional	Disable status message

EnablePackageRequest

Enable package request

Properties

Property	Type	Required	Description
id	`string`	✅	Package ID to enable

EnablePackageResponse

Enable package response

Properties

Property	Type	Required	Description
package	`Object`	✅	Enabled package details
message	`string`	optional	Enable status message

GetPackageRequest

Get package request

Properties

Property	Type	Required	Description
id	`string`	✅	Package identifier

GetPackageResponse

Get package response

Properties

Property	Type	Required	Description
package	`Object`	✅	Package details

InstallPackageRequest

Install package request

Properties

Property	Type	Required	Description
manifest	`Object`	✅	Package manifest to install
settings	`Record<string, any>`	optional	User-provided settings at install time
enableOnInstall	`boolean`	optional	Whether to enable immediately after install
platformVersion	`string`	optional	Current platform version for compatibility verification

InstallPackageResponse

Install package response

Properties

Property	Type	Required	Description
package	`Object`	✅	Installed package details
message	`string`	optional	Installation status message
dependencyResolution	`Object`	optional	Dependency resolution result from install analysis

InstalledPackage

Installed package with runtime lifecycle state

Properties

Property	Type	Required	Description
manifest	`Object`	✅	Full package manifest
status	`Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>`	optional	Package state: installed, disabled, installing, upgrading, uninstalling, or error
enabled	`boolean`	optional	Whether the package is currently enabled
installedAt	`string`	optional	Installation timestamp
updatedAt	`string`	optional	Last update timestamp
installedVersion	`string`	optional	Currently installed version for quick access
previousVersion	`string`	optional	Version before the last upgrade
statusChangedAt	`string`	optional	Status change timestamp
errorMessage	`string`	optional	Error message when status is error
settings	`Record<string, any>`	optional	User-provided configuration settings
upgradeHistory	`Object[]`	optional	Version upgrade history
registeredNamespaces	`string[]`	optional	Namespace prefixes registered by this package

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

ListPackagesResponse

List packages response

Properties

Property	Type	Required	Description
packages	`Object[]`	✅	List of installed packages
total	`number`	✅	Total package count

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

Package Registry

On this page