Package Registry — Kernel Protocol reference

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 { DisablePackageRequestSchema, DisablePackageResponseSchema, EnablePackageRequestSchema, EnablePackageResponseSchema, GetPackageRequestSchema, GetPackageResponseSchema, InstallPackageRequestSchema, InstallPackageResponseSchema, InstalledPackageSchema, ListPackagesRequestSchema, ListPackagesResponseSchema, NamespaceConflictErrorSchema, NamespaceRegistryEntrySchema, PackageStatusEnum, UninstallPackageRequestSchema, UninstallPackageResponseSchema } from '@objectstack/spec/kernel';
import type { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, InstalledPackage, ListPackagesRequest, ListPackagesResponse, NamespaceConflictError, NamespaceRegistryEntry, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel';

// Validate data
const result = DisablePackageRequestSchema.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	`{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }`	✅	Disabled package details
message	`string`	optional	Disable status message

Nested Shape: `DisablePackageResponse.package`

Property	Type	Required	Description
manifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	✅	Package manifest at the AUTHORING stage; a row installed by a `defineStack()` host carries the assembled body instead — see `AssembledInstalledPackageSchema` / `InstalledPackageAtEitherStageSchema`
status	`Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>`	optional (default: `"installed"`)	Package state: installed, disabled, installing, upgrading, uninstalling, or error
enabled	`boolean`	optional (default: `true`)	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	`{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]`	optional	Version upgrade history
registeredNamespaces	`string[]`	optional	Namespace prefixes registered by this package

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	`{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }`	✅	Enabled package details
message	`string`	optional	Enable status message

Nested Shape: `EnablePackageResponse.package`

Property	Type	Required	Description
manifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	✅	Package manifest at the AUTHORING stage; a row installed by a `defineStack()` host carries the assembled body instead — see `AssembledInstalledPackageSchema` / `InstalledPackageAtEitherStageSchema`
status	`Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>`	optional (default: `"installed"`)	Package state: installed, disabled, installing, upgrading, uninstalling, or error
enabled	`boolean`	optional (default: `true`)	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	`{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]`	optional	Version upgrade history
registeredNamespaces	`string[]`	optional	Namespace prefixes registered by this package

GetPackageRequest

Get package request

Properties

Property	Type	Required	Description
id	`string`	✅	Package identifier

GetPackageResponse

Get package response

Properties

Property	Type	Required	Description
package	`{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }`	✅	Package details

Nested Shape: `GetPackageResponse.package`

Property	Type	Required	Description
manifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	✅	Package manifest at the AUTHORING stage; a row installed by a `defineStack()` host carries the assembled body instead — see `AssembledInstalledPackageSchema` / `InstalledPackageAtEitherStageSchema`
status	`Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>`	optional (default: `"installed"`)	Package state: installed, disabled, installing, upgrading, uninstalling, or error
enabled	`boolean`	optional (default: `true`)	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	`{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]`	optional	Version upgrade history
registeredNamespaces	`string[]`	optional	Namespace prefixes registered by this package

InstallPackageRequest

Install package request

Properties

Property	Type	Required	Description
manifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	✅	Package manifest to install
settings	`Record<string, any>`	optional	User-provided settings at install time
enableOnInstall	`boolean`	optional	Whether to enable immediately after install — restates the install-door request key, whose one authority is api/PackageInstallRequest; this protocol primitive honours it on the registry row: `true` enables, `false` disables, and ABSENT keeps the row's current lifecycle state (a fresh install lands enabled)
platformVersion	`string`	optional	Current platform version for compatibility verification

Nested Shape: `InstallPackageRequest.manifest`

Property	Type	Required	Description
id	`string`	✅	Unique package identifier — must match reverse-domain notation (e.g. com.acme.crm)
namespace	`string`	optional	Short namespace identifier; also the mandatory prefix of every object name (e.g. "todo" → object names "todo_task", "todo_project")
defaultDatasource	`string`	optional (default: `"default"`)	Default datasource for all objects in this package
version	`string`	✅	Package version (SemVer 2.0.0 — e.g. 1.2.3, 2.0.0-beta.1, 1.0.0+20230101)
type	`Enum<'plugin' \| 'ui' \| 'driver' \| 'server' \| 'app' \| 'theme' \| 'agent' \| 'objectql' \| …>`	✅	Type of package
scope	`Enum<'cloud' \| 'system' \| 'project'>`	optional (default: `"project"`)	Deployment scope: cloud \| system \| project
installModes	`Enum<'managed' \| 'unmanaged'>[]`	optional	Install modes this package permits (ADR-0131 D6): managed \| unmanaged. Absent means ['managed'].
name	`string`	✅	Human-readable package name
description	`string`	optional	Package description
permissions	`{ services?: string[]; hooks?: string[]; network?: string[]; fs?: string[] }`	optional	Required permissions at the AUTHORING stage: the structured plugin block `{ services, hooks, network, fs }` (ADR-0025 §3.2) — the legacy flat string list is retired — and at the assembled stage the same key is the ADR-0090 `PermissionSet[]` collection instead (`AssembledPackageBodySchema`)
objects	`string[]`	optional	Glob patterns for ObjectQL schemas files
datasources	`string[]`	optional	Glob patterns for Datasource definitions
dependencies	`Record<string, string>`	optional	Package dependencies
configuration	`never`	optional	[REMOVED] `manifest.configuration` was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read the block: no settings UI rendered it and no loader resolved a setting from it, so authoring it configured nothing. Worse, `properties.*.secret` promised "value is encrypted/masked (e.g. API Keys)" while nothing encrypted, masked or even parsed the flag — a false assurance about credential handling. Delete the key. A plugin is configured by the host that composes it: pass options to its constructor in `defineStack({ plugins: [new MyPlugin({ … })] })`, which is the enforced channel. A declarative settings surface must be designed with an enforcing reader first, not revived here.
contributes	`{ kinds?: object[] }`	optional	Platform contributions
data	`{ object: string; externalId?: string \| string[]; mode?: Enum<'insert' \| 'update' \| 'upsert' \| 'replace' \| 'ignore'>; env?: Enum<'prod' \| 'dev' \| 'test'>[]; … }[]`	optional	Initial seed data (prefer top-level data field)
capabilities	`never`	optional	[REMOVED] `manifest.capabilities` was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — no discovery path ever consulted the block: nothing read `implements`, `provides`, `requires`, `extensionPoints` or `extensions`, so the declared "interoperability and automatic discovery" never happened. Delete the key. Real dependency resolution runs off top-level `manifest.dependencies`, which stays. Capability-based discovery must be designed with an enforcing reader first, not revived here.
extensions	`never`	optional	[REMOVED] `manifest.extensions` was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — an untyped map with zero readers: whatever was parked here was stored and never consulted. Delete the key. Extend the platform through the enforced channels instead: `contributes.kinds` registers metadata kinds, `navigationContributions` injects navigation into other packages' apps, and code-level extension happens in the plugin itself (`init`/`start`).
navigationContributions	`{ app: string; group?: string; priority?: integer; items: (object \| … +9 more)[] }[]`	optional	Navigation items this package contributes into apps owned by other packages
loading	`never`	optional	[REMOVED] `manifest.loading` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — the entire block (`strategy`, `preload`, `codeSplitting`, `dynamicImport`, `initialization`, `dependencyResolution`, `hotReload`, `caching`, `sandboxing`, `monitoring`) had no runtime reader in any repo, so authoring it configured nothing. Delete the key. Plugins are composed at boot — `defineStack` registers them and the kernel runs `init` then `start` in an order topologically resolved from each composed plugin's own `dependencies` / `optionalDependencies` (`resolvePluginOrder`); the set is fixed until the process restarts. ⚠️ `loading.sandboxing` in particular never isolated anything: it did not run plugins in a process, vm, iframe or web-worker, and `allowedServices` gated no call. If you were relying on it for isolation, you had none — and the plugin trust tier (`manifest.runtime`) does not give it back: that tier is enforced at the cloud marketplace PUBLISH gate only (an unverified publisher requesting the `node` tier is rejected with HTTP 422 and forced to manual review), while load-side enforcement is NOT implemented, so a locally installed plugin is not isolated by the tier it declares. ⛔ Nor do the permission declarations give it back: the install-time granted set is REGISTERED on the PluginPermissionEnforcer at load and queried by nothing, so it refuses no operation. Neither surface confines a plugin today — do not author either one expecting isolation.
engine	`{ objectstack: string }`	optional	Platform compatibility requirements (legacy; superseded by `engines`)
engines	`{ platform?: string; protocol?: string }`	optional	Plugin compatibility ranges (ADR-0025 §3.2; supersedes `engine`)
runtime	`Enum<'node' \| 'sandbox' \| 'worker'>`	optional	Plugin trust tier the plugin declares (ADR-0025 §3.6) — enforced at the cloud marketplace publish gate (unverified publisher requesting `node` → HTTP 422 + manual review); load-side enforcement is NOT implemented, so a locally installed plugin is not isolated by the tier it declares
packaging	`Enum<'bundled' \| 'manifest-deps'>`	optional	Dependency packaging strategy (ADR-0025 §3.3)
main	`string`	optional	Entry module of a code-bearing plugin, relative to the plugin root; `os plugin build` bundles it and writes `dist/index.mjs` here in the compiled manifest (ADR-0025 §3.4)
integrity	`Record<string, string>`	optional	Per-file content digests of the plugin artifact (ADR-0025 §3.2)

InstallPackageResponse

Install package response

Properties

Property	Type	Required	Description
package	`{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }`	✅	Installed package details
message	`string`	optional	Installation status message
dependencyResolution	`{ dependencies: object[]; canProceed: boolean; requiredActions: object[]; installOrder: string[]; … }`	optional	Dependency resolution result from install analysis

Nested Shape: `InstallPackageResponse.package`

Property	Type	Required	Description
manifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	✅	Package manifest at the AUTHORING stage; a row installed by a `defineStack()` host carries the assembled body instead — see `AssembledInstalledPackageSchema` / `InstalledPackageAtEitherStageSchema`
status	`Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>`	optional (default: `"installed"`)	Package state: installed, disabled, installing, upgrading, uninstalling, or error
enabled	`boolean`	optional (default: `true`)	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	`{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]`	optional	Version upgrade history
registeredNamespaces	`string[]`	optional	Namespace prefixes registered by this package

Nested Shape: `InstallPackageResponse.dependencyResolution`

Property	Type	Required	Description
dependencies	`{ packageId: string; requiredRange: string; resolvedVersion?: string; installedVersion?: string; … }[]`	✅	Resolution result for each dependency
canProceed	`boolean`	✅	Whether installation can proceed
requiredActions	`{ type: Enum<'install' \| 'upgrade' \| 'confirm_conflict'>; packageId: string; description: string }[]`	✅	Actions required before proceeding
installOrder	`string[]`	✅	Topologically sorted package IDs for installation
circularDependencies	`string[][]`	optional	Circular dependency chains detected (e.g. [["A", "B", "A"]])

InstalledPackage

Installed package with runtime lifecycle state

Properties

Property	Type	Required	Description
manifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	✅	Package manifest at the AUTHORING stage; a row installed by a `defineStack()` host carries the assembled body instead — see `AssembledInstalledPackageSchema` / `InstalledPackageAtEitherStageSchema`
status	`Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>`	optional (default: `"installed"`)	Package state: installed, disabled, installing, upgrading, uninstalling, or error
enabled	`boolean`	optional (default: `true`)	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	`{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]`	optional	Version upgrade history
registeredNamespaces	`string[]`	optional	Namespace prefixes registered by this package

Nested Shape: `InstalledPackage.manifest`

Property	Type	Required	Description
id	`string`	✅	Unique package identifier — must match reverse-domain notation (e.g. com.acme.crm)
namespace	`string`	optional	Short namespace identifier; also the mandatory prefix of every object name (e.g. "todo" → object names "todo_task", "todo_project")
defaultDatasource	`string`	optional (default: `"default"`)	Default datasource for all objects in this package
version	`string`	✅	Package version (SemVer 2.0.0 — e.g. 1.2.3, 2.0.0-beta.1, 1.0.0+20230101)
type	`Enum<'plugin' \| 'ui' \| 'driver' \| 'server' \| 'app' \| 'theme' \| 'agent' \| 'objectql' \| …>`	✅	Type of package
scope	`Enum<'cloud' \| 'system' \| 'project'>`	optional (default: `"project"`)	Deployment scope: cloud \| system \| project
installModes	`Enum<'managed' \| 'unmanaged'>[]`	optional	Install modes this package permits (ADR-0131 D6): managed \| unmanaged. Absent means ['managed'].
name	`string`	✅	Human-readable package name
description	`string`	optional	Package description
permissions	`{ services?: string[]; hooks?: string[]; network?: string[]; fs?: string[] }`	optional	Required permissions at the AUTHORING stage: the structured plugin block `{ services, hooks, network, fs }` (ADR-0025 §3.2) — the legacy flat string list is retired — and at the assembled stage the same key is the ADR-0090 `PermissionSet[]` collection instead (`AssembledPackageBodySchema`)
objects	`string[]`	optional	Glob patterns for ObjectQL schemas files
datasources	`string[]`	optional	Glob patterns for Datasource definitions
dependencies	`Record<string, string>`	optional	Package dependencies
configuration	`never`	optional	[REMOVED] `manifest.configuration` was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read the block: no settings UI rendered it and no loader resolved a setting from it, so authoring it configured nothing. Worse, `properties.*.secret` promised "value is encrypted/masked (e.g. API Keys)" while nothing encrypted, masked or even parsed the flag — a false assurance about credential handling. Delete the key. A plugin is configured by the host that composes it: pass options to its constructor in `defineStack({ plugins: [new MyPlugin({ … })] })`, which is the enforced channel. A declarative settings surface must be designed with an enforcing reader first, not revived here.
contributes	`{ kinds?: object[] }`	optional	Platform contributions
data	`{ object: string; externalId?: string \| string[]; mode?: Enum<'insert' \| 'update' \| 'upsert' \| 'replace' \| 'ignore'>; env?: Enum<'prod' \| 'dev' \| 'test'>[]; … }[]`	optional	Initial seed data (prefer top-level data field)
capabilities	`never`	optional	[REMOVED] `manifest.capabilities` was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — no discovery path ever consulted the block: nothing read `implements`, `provides`, `requires`, `extensionPoints` or `extensions`, so the declared "interoperability and automatic discovery" never happened. Delete the key. Real dependency resolution runs off top-level `manifest.dependencies`, which stays. Capability-based discovery must be designed with an enforcing reader first, not revived here.
extensions	`never`	optional	[REMOVED] `manifest.extensions` was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — an untyped map with zero readers: whatever was parked here was stored and never consulted. Delete the key. Extend the platform through the enforced channels instead: `contributes.kinds` registers metadata kinds, `navigationContributions` injects navigation into other packages' apps, and code-level extension happens in the plugin itself (`init`/`start`).
navigationContributions	`{ app: string; group?: string; priority?: integer; items: (object \| … +9 more)[] }[]`	optional	Navigation items this package contributes into apps owned by other packages
loading	`never`	optional	[REMOVED] `manifest.loading` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — the entire block (`strategy`, `preload`, `codeSplitting`, `dynamicImport`, `initialization`, `dependencyResolution`, `hotReload`, `caching`, `sandboxing`, `monitoring`) had no runtime reader in any repo, so authoring it configured nothing. Delete the key. Plugins are composed at boot — `defineStack` registers them and the kernel runs `init` then `start` in an order topologically resolved from each composed plugin's own `dependencies` / `optionalDependencies` (`resolvePluginOrder`); the set is fixed until the process restarts. ⚠️ `loading.sandboxing` in particular never isolated anything: it did not run plugins in a process, vm, iframe or web-worker, and `allowedServices` gated no call. If you were relying on it for isolation, you had none — and the plugin trust tier (`manifest.runtime`) does not give it back: that tier is enforced at the cloud marketplace PUBLISH gate only (an unverified publisher requesting the `node` tier is rejected with HTTP 422 and forced to manual review), while load-side enforcement is NOT implemented, so a locally installed plugin is not isolated by the tier it declares. ⛔ Nor do the permission declarations give it back: the install-time granted set is REGISTERED on the PluginPermissionEnforcer at load and queried by nothing, so it refuses no operation. Neither surface confines a plugin today — do not author either one expecting isolation.
engine	`{ objectstack: string }`	optional	Platform compatibility requirements (legacy; superseded by `engines`)
engines	`{ platform?: string; protocol?: string }`	optional	Plugin compatibility ranges (ADR-0025 §3.2; supersedes `engine`)
runtime	`Enum<'node' \| 'sandbox' \| 'worker'>`	optional	Plugin trust tier the plugin declares (ADR-0025 §3.6) — enforced at the cloud marketplace publish gate (unverified publisher requesting `node` → HTTP 422 + manual review); load-side enforcement is NOT implemented, so a locally installed plugin is not isolated by the tier it declares
packaging	`Enum<'bundled' \| 'manifest-deps'>`	optional	Dependency packaging strategy (ADR-0025 §3.3)
main	`string`	optional	Entry module of a code-bearing plugin, relative to the plugin root; `os plugin build` bundles it and writes `dist/index.mjs` here in the compiled manifest (ADR-0025 §3.4)
integrity	`Record<string, string>`	optional	Per-file content digests of the plugin artifact (ADR-0025 §3.2)

Nested Shape: `InstalledPackage.upgradeHistory[number]`

Property	Type	Required	Description
fromVersion	`string`	✅	Version before upgrade
toVersion	`string`	✅	Version after upgrade
upgradedAt	`string`	✅	Upgrade timestamp
status	`Enum<'success' \| 'failed' \| 'rolled_back'>`	✅	Upgrade outcome
migrationLog	`string[]`	optional	Migration step logs

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	`{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }[]`	✅	List of installed packages
total	`number`	✅	Total package count

Nested Shape: `ListPackagesResponse.packages[number]`

Installed package with runtime lifecycle state

Property	Type	Required	Description
manifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	✅	Package manifest at the AUTHORING stage; a row installed by a `defineStack()` host carries the assembled body instead — see `AssembledInstalledPackageSchema` / `InstalledPackageAtEitherStageSchema`
status	`Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>`	optional (default: `"installed"`)	Package state: installed, disabled, installing, upgrading, uninstalling, or error
enabled	`boolean`	optional (default: `true`)	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	`{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]`	optional	Version upgrade history
registeredNamespaces	`string[]`	optional	Namespace prefixes registered by this package

NamespaceConflictError

Namespace collision error during installation

Properties

Property	Type	Required	Description
type	`'namespace_conflict'`	✅	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 — Kernel Protocol reference

On this page