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, 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

Package Registry

On this page