Skip to content

Latest commit

 

History

History
859 lines (664 loc) · 81.4 KB

package-api.mdx

File metadata and controls

859 lines (664 loc) · 81.4 KB
title Package Api schema — API Protocol reference
navTitle Package Api
description Package API Protocol — REST API endpoint schemas for package lifecycle management.

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Package API Protocol

REST API endpoint schemas for package lifecycle management.

Base path: /api/v1/packages

Endpoints

POST   /api/v1/packages                      — Install a package
GET    /api/v1/packages                      — List installed packages
GET    /api/v1/packages/:packageId           — Get package details
POST   /api/v1/packages/:packageId/rollback  — Rollback a package
DELETE /api/v1/packages/:packageId           — Uninstall a package

Five declarations of this API live one file over, on purpose

The two READ responses (ListInstalledPackagesResponseSchema, GetInstalledPackageResponseSchema), the installed-row stages they are bound to (AssembledInstalledPackageSchema, InstalledPackageAtEitherStageSchema) and the PackageApiContracts map that names both responses are declared in ./package-api-assembled.zod.ts and published from @objectstack/spec/api-assembled, not from @objectstack/spec/api.

The reason is weight, not meaning. Four of them carry the ASSEMBLED package body (the fifth, the route map, names two of those four), which is the whole metadata vocabulary (../stack.zod) plus the datasource and driver-config validators behind it. While they sat in this file, every @objectstack/spec/api bundle linked that tree, and a browser consumer that imported two string constants from ./sortability.zod paid for all of it: measured at about twice the gzipped bundle of the same import before the stage declarations arrived. The maintainer ruling on #18576 (letter B) split the entry so the browser-facing half does not carry them.

⛔ Nothing in this file may import ../stack.zod or anything that reaches ../data/datasource.zod: that edge is exactly what the split removed from @objectstack/spec/api, and ./api-entry-graph.pin.test.ts refuses it. A declaration that needs the assembled body goes in the sibling file.

**Source:** `packages/spec/src/api/package-api.zod.ts`

TypeScript Usage

import { GetInstalledPackageRequestSchema, ListInstalledPackagesRequestSchema, PackageApiErrorCode, PackageInstallBodySchema, PackageInstallManifestSchema, PackageInstallRequestSchema, PackageInstallResponseSchema, PackagePathParamsSchema, PackageRollbackRequestSchema, PackageUpgradeRequestSchema, PackageUpgradeResponseSchema, ResolveDependenciesRequestSchema, ResolveDependenciesResponseSchema, UninstallPackageApiRequestSchema, UninstallPackageApiResponseSchema, UploadArtifactRequestSchema, UploadArtifactResponseSchema } from '@objectstack/spec/api';
import type { GetInstalledPackageRequest, ListInstalledPackagesRequest, PackageApiErrorCode, PackageInstallBody, PackageInstallManifest, PackageInstallRequest, PackageInstallResponse, PackagePathParams, PackageRollbackRequest, PackageUpgradeRequest, PackageUpgradeResponse, ResolveDependenciesRequest, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api';

// Validate data
const result = GetInstalledPackageRequestSchema.parse(data);

GetInstalledPackageRequest

Get installed package request

Properties

Property Type Required Description
packageId string ✅ Package identifier
version string optional Scope the read to this exact installed version; latest or omitted reads the installed row

ListInstalledPackagesRequest

List installed packages request

Properties

Property Type Required Description
status Enum<'installed' | 'disabled' | 'installing' | 'upgrading' | 'uninstalling' | 'error'> optional Filter by package status
enabled boolean optional Filter by enabled state
type string optional Filter by the installed manifest's type — exact match, unmatched values select nothing
limit never optional [REMOVED] limit / cursor were removed from GET /api/v1/packages in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — both were declared here and read by nothing: the serving door filters on status / type / enabled and then returns every remaining row, so no page was ever withheld and no continuation token was ever minted. limit also declared .default(50), so a reader of the published schema was entitled to believe an unparameterised list is capped at 50 rows; it has never been capped at all, and nothing parses a query string through this schema, so that default has never been stamped onto anything. Delete the key. This route is NOT paginated — it answers the whole installed set, which is a bounded table of tens of rows, and hasMore on the response is a constant false that is now true by construction. Filter with status, type and enabled instead of asking for a window. A first-class package cursor, if one is ever designed, will be a response-minted opaque token, not this key.
cursor never optional [REMOVED] limit / cursor were removed from GET /api/v1/packages in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — both were declared here and read by nothing: the serving door filters on status / type / enabled and then returns every remaining row, so no page was ever withheld and no continuation token was ever minted. limit also declared .default(50), so a reader of the published schema was entitled to believe an unparameterised list is capped at 50 rows; it has never been capped at all, and nothing parses a query string through this schema, so that default has never been stamped onto anything. Delete the key. This route is NOT paginated — it answers the whole installed set, which is a bounded table of tens of rows, and hasMore on the response is a constant false that is now true by construction. Filter with status, type and enabled instead of asking for a window. A first-class package cursor, if one is ever designed, will be a response-minted opaque token, not this key.

PackageApiErrorCode

Allowed Values

  • package_not_found
  • package_already_installed
  • version_not_found
  • dependency_conflict
  • namespace_conflict
  • platform_incompatible
  • artifact_invalid
  • checksum_mismatch
  • signature_invalid
  • upgrade_failed
  • rollback_failed
  • snapshot_not_found
  • upload_failed

PackageInstallBody

Install package request body, wrapped or as a bare manifest

Union Options

This schema accepts one of the following structures:

Option 1

Install package request

Properties

Property Type Required Description
manifest { id: string; namespace?: string; defaultDatasource?: string; version: string; … } ✅ Package manifest to install (AUTHORING stage: objects are glob patterns; scope is project)
settings Record<string, any> optional User-provided settings at install time
enableOnInstall boolean optional Whether to enable immediately after install — honoured at POST /api/v1/packages: true enables the installed row, false disables it, and ABSENT keeps the row's current lifecycle state (a fresh install lands enabled)
overwrite boolean optional Overwrite an already-installed package id instead of answering 409 Conflict; an id the deployment ships read-only (code-booted, or scope cloud / system) is refused 422 WRITABLE_PACKAGE_REQUIRED
platformVersion string optional Current platform version for compatibility verification
artifactRef { url: string; sha256: string; size: integer; format?: Enum<'tgz' | 'zip'>; … } optional Artifact reference for marketplace installation

Nested Shape: PackageInstallBody[option 1].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<'project'> optional (default: "project") Deployment scope — an authored install is always project; cloud / system are refused (platform-shipped, read-only scopes)
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'>; columns?: Record<string, object>; … }[] 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
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) and at boot for a plugin os plugin install installed: only node is loaded (in process, not isolated); sandbox and worker are refused until ADR-0025 M3 routes them
packaging Enum<'bundled'> optional Dependency packaging strategy (ADR-0025 v2 §3.3): bundled, the only one and the default — omit the key or write bundled
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: PackageInstallBody[option 1].artifactRef

Property Type Required Description
url string ✅ Artifact download URL
sha256 string ✅ SHA256 checksum
size integer ✅ Artifact size in bytes
format Enum<'tgz' | 'zip'> optional (default: "tgz") Artifact format
uploadedAt string ✅ Upload timestamp

Option 2

Package manifest installed through POST /api/v1/packages (AUTHORING stage; scope is project)

Properties

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' | 'module' | 'gateway' | 'adapter'> ✅ Type of package
scope Enum<'project'> optional (default: "project") Deployment scope — an authored install is always project; cloud / system are refused (platform-shipped, read-only scopes)
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'>; columns?: Record<string, object>; … }[] 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
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) and at boot for a plugin os plugin install installed: only node is loaded (in process, not isolated); sandbox and worker are refused until ADR-0025 M3 routes them
packaging Enum<'bundled'> optional Dependency packaging strategy (ADR-0025 v2 §3.3): bundled, the only one and the default — omit the key or write bundled
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: PackageInstallBody[option 2].permissions

Property Type Required Description
services string[] optional Platform services the plugin may resolve (e.g. "object", "http")
hooks string[] optional Lifecycle hooks the plugin may register (e.g. "record.beforeInsert")
network string[] optional Network hosts the plugin may reach (e.g. "api.acme.com")
fs string[] optional Filesystem paths the plugin may access

Nested Shape: PackageInstallBody[option 2].contributes

Property Type Required Description
kinds { id: string; description?: string }[] optional Metadata kind identifiers this package registers
events never optional [REMOVED] manifest.contributes.events was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read the list: its only in-repo author already subscribed imperatively in plugin code, so the declaration was decorative. Delete the key. Subscribe to system events in the plugin itself — ctx.hook('kernel:ready', …) (or the events service) from init/start is the enforced channel; record lifecycle hooks register on the data engine.
menus never optional [REMOVED] manifest.contributes.menus was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — no renderer ever read it; two alias maps already redirected this spelling to navigation. Delete the key. Declare navigation in the app's navigation tree, or inject items into another package's app via manifest.navigationContributions (ADR-0029 D7), which the engine registers.
themes never optional [REMOVED] manifest.contributes.themes was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — it never had an effect: theme registration reaches the registry only through the stack-level themes collection (a ThemeSchema surface, unrelated to this { id, label, path } shape), never through contributes.themes. Delete the key; declare themes in the stack themes collection instead.
translations never optional [REMOVED] manifest.contributes.translations was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — no loader ever read these { locale, path } entries; authoring them registered no translations. Delete the key. Declare translations as translation metadata: defineTranslationBundle({ … }) in the stack's translations collection (defineStack({ translations: […] })), which the engine registers and the i18n pipeline serves.
actions never optional [REMOVED] manifest.contributes.actions was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read it; actions declared here were never invocable. Delete the key. Declare actions in the stack actions collection (registered by the engine) or register imperatively via engine.registerAction.
drivers never optional [REMOVED] manifest.contributes.drivers was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — it never had an effect: a storage driver is wired by registering a kernel SERVICE named driver.* (the objectql plugin picks it up and calls registerDriver), and its only in-repo author was registered that way, not by this declaration. Delete the key.
fieldTypes never optional [REMOVED] manifest.contributes.fieldTypes was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — there is no registerFieldType seam anywhere: the declaration advertised an extension point the platform does not have, so authoring it configured nothing. Delete the key. The field-type vocabulary is the spec FieldType enum; extending it is a spec change, not a manifest declaration.
functions never optional [REMOVED] manifest.contributes.functions was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read it; ObjectQL functions declared here were never registered. Delete the key. Declare functions on the stack (defineStack({ functions: […] })), which the hook binder registers via engine.registerFunction.
routes never optional [REMOVED] manifest.contributes.routes was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read it: the HttpDispatcher never registered a prefix from the declaration, so an entry here parsed cleanly and served nothing while published material kept recommending it. Delete the key. An app does not mount routes on http.server — that service is the platform's own door-building primitive, and a code-mounted route gets no caller identity, auth gate, rate limit, namespace carve-out or OpenAPI entry. Declare the endpoint under defineStack({ apis }) (type: 'object_operation' or 'flow', ADR-0121), compute in a flow, and register code as a stack function (defineStack({ functions })) or a connector.
commands never optional [REMOVED] manifest.contributes.commands was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — the CLI never resolved commands from this declaration: commands are auto-discovered through oclif's native plugin system (the plugin package declares an oclif section in its own package.json; see cli-extension.zod.ts), and the objectstack.config.ts plugins array no longer determines CLI commands. Delete the key.

Nested Shape: PackageInstallBody[option 2].data[number]

Property Type Required Description
object string ✅ Target Object Name
externalId string | string[] optional (default: "name") Field (or composite list of fields) matched for the uniqueness check
mode Enum<'insert' | 'update' | 'upsert' | 'replace' | 'ignore'> optional (default: "upsert") Conflict resolution strategy
columns Record<string, { applyOn?: Enum<'create' | 'always'> }> optional Per-column write policy, keyed by field name: { status: { applyOn: 'create' } } writes status only when the seed creates the row. Omitted, every column is written on create and update.
env Enum<'prod' | 'dev' | 'test'>[] optional (default: ["prod","dev","test"]) Applicable environments
locale string[] optional Applicable locales (BCP-47 tags); omitted applies to every locale. The publish and install paths do not filter by locale — they load every dataset and warn
records Record<string, any>[] ✅ Data records
files Record<string, { contentType: string; size: integer; sha256: string; data: string }> optional Bytes of the package files the records name with seedFile(path), keyed by path. Written by os build, which reads each path relative to the package root; the loader stores each one as a file the written record owns.
_lock Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> optional Item-level lock — controls overlay & delete (ADR-0010).
_lockReason string optional Human-readable reason shown when a write is refused by _lock.
_lockSource Enum<'artifact' | 'package' | 'env-forced'> optional Layer that set _lock (artifact | package | env-forced).
_provenance Enum<'package' | 'org' | 'env-forced'> optional Origin of the item (package | org | env-forced).
_packageId string optional Owning package machine id.
_packageVersion string optional Owning package version.
_lockDocsUrl string optional Optional documentation link surfaced next to _lockReason.

Nested Shape: PackageInstallBody[option 2].navigationContributions[number]

A navigation contribution: a package injecting nav items into an app it does not own (ADR-0029 D7)

Property Type Required Description
app string ✅ Target app name to contribute navigation into (e.g. "setup")
group string optional Target group nav-item id to append into (e.g. "group_integrations"); omit to append at the app top level. Naming a group the target app does not declare is not refused: the items are appended at the app top level anyway and a nav_contribution_group_missing diagnostic is emitted — by the runtime at warn, and by os build and os validate at compile time.
priority integer optional (default: 200) Merge priority within the target group — lower applied first (matches object extender priority)
items ({ id: string; label?: string | Record<string, string>; icon?: string; order?: number; … } | { type: 'separator'; id?: string; order?: number } | … +8 more)[] ✅ Navigation items contributed into the target app/group

Nested Shape: PackageInstallBody[option 2].engine

Property Type Required Description
objectstack string ✅ ObjectStack platform version requirement (SemVer range, e.g. ">=3.0.0")

Nested Shape: PackageInstallBody[option 2].engines

Property Type Required Description
platform string optional ObjectStack platform release range (SemVer, e.g. ">=4.0 <5")
protocol string optional Runtime/metadata protocol range, checked first (ADR §3.10 #3)


PackageInstallManifest

Package manifest installed through POST /api/v1/packages (AUTHORING stage; scope is project)

Properties

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' | 'module' | 'gateway' | 'adapter'> ✅ Type of package
scope Enum<'project'> optional (default: "project") Deployment scope — an authored install is always project; cloud / system are refused (platform-shipped, read-only scopes)
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'>; columns?: Record<string, object>; … }[] 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
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) and at boot for a plugin os plugin install installed: only node is loaded (in process, not isolated); sandbox and worker are refused until ADR-0025 M3 routes them
packaging Enum<'bundled'> optional Dependency packaging strategy (ADR-0025 v2 §3.3): bundled, the only one and the default — omit the key or write bundled
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: PackageInstallManifest.permissions

Property Type Required Description
services string[] optional Platform services the plugin may resolve (e.g. "object", "http")
hooks string[] optional Lifecycle hooks the plugin may register (e.g. "record.beforeInsert")
network string[] optional Network hosts the plugin may reach (e.g. "api.acme.com")
fs string[] optional Filesystem paths the plugin may access

Nested Shape: PackageInstallManifest.contributes

Property Type Required Description
kinds { id: string; description?: string }[] optional Metadata kind identifiers this package registers
events never optional [REMOVED] manifest.contributes.events was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read the list: its only in-repo author already subscribed imperatively in plugin code, so the declaration was decorative. Delete the key. Subscribe to system events in the plugin itself — ctx.hook('kernel:ready', …) (or the events service) from init/start is the enforced channel; record lifecycle hooks register on the data engine.
menus never optional [REMOVED] manifest.contributes.menus was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — no renderer ever read it; two alias maps already redirected this spelling to navigation. Delete the key. Declare navigation in the app's navigation tree, or inject items into another package's app via manifest.navigationContributions (ADR-0029 D7), which the engine registers.
themes never optional [REMOVED] manifest.contributes.themes was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — it never had an effect: theme registration reaches the registry only through the stack-level themes collection (a ThemeSchema surface, unrelated to this { id, label, path } shape), never through contributes.themes. Delete the key; declare themes in the stack themes collection instead.
translations never optional [REMOVED] manifest.contributes.translations was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — no loader ever read these { locale, path } entries; authoring them registered no translations. Delete the key. Declare translations as translation metadata: defineTranslationBundle({ … }) in the stack's translations collection (defineStack({ translations: […] })), which the engine registers and the i18n pipeline serves.
actions never optional [REMOVED] manifest.contributes.actions was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read it; actions declared here were never invocable. Delete the key. Declare actions in the stack actions collection (registered by the engine) or register imperatively via engine.registerAction.
drivers never optional [REMOVED] manifest.contributes.drivers was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — it never had an effect: a storage driver is wired by registering a kernel SERVICE named driver.* (the objectql plugin picks it up and calls registerDriver), and its only in-repo author was registered that way, not by this declaration. Delete the key.
fieldTypes never optional [REMOVED] manifest.contributes.fieldTypes was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — there is no registerFieldType seam anywhere: the declaration advertised an extension point the platform does not have, so authoring it configured nothing. Delete the key. The field-type vocabulary is the spec FieldType enum; extending it is a spec change, not a manifest declaration.
functions never optional [REMOVED] manifest.contributes.functions was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read it; ObjectQL functions declared here were never registered. Delete the key. Declare functions on the stack (defineStack({ functions: […] })), which the hook binder registers via engine.registerFunction.
routes never optional [REMOVED] manifest.contributes.routes was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read it: the HttpDispatcher never registered a prefix from the declaration, so an entry here parsed cleanly and served nothing while published material kept recommending it. Delete the key. An app does not mount routes on http.server — that service is the platform's own door-building primitive, and a code-mounted route gets no caller identity, auth gate, rate limit, namespace carve-out or OpenAPI entry. Declare the endpoint under defineStack({ apis }) (type: 'object_operation' or 'flow', ADR-0121), compute in a flow, and register code as a stack function (defineStack({ functions })) or a connector.
commands never optional [REMOVED] manifest.contributes.commands was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — the CLI never resolved commands from this declaration: commands are auto-discovered through oclif's native plugin system (the plugin package declares an oclif section in its own package.json; see cli-extension.zod.ts), and the objectstack.config.ts plugins array no longer determines CLI commands. Delete the key.

Nested Shape: PackageInstallManifest.data[number]

Property Type Required Description
object string ✅ Target Object Name
externalId string | string[] optional (default: "name") Field (or composite list of fields) matched for the uniqueness check
mode Enum<'insert' | 'update' | 'upsert' | 'replace' | 'ignore'> optional (default: "upsert") Conflict resolution strategy
columns Record<string, { applyOn?: Enum<'create' | 'always'> }> optional Per-column write policy, keyed by field name: { status: { applyOn: 'create' } } writes status only when the seed creates the row. Omitted, every column is written on create and update.
env Enum<'prod' | 'dev' | 'test'>[] optional (default: ["prod","dev","test"]) Applicable environments
locale string[] optional Applicable locales (BCP-47 tags); omitted applies to every locale. The publish and install paths do not filter by locale — they load every dataset and warn
records Record<string, any>[] ✅ Data records
files Record<string, { contentType: string; size: integer; sha256: string; data: string }> optional Bytes of the package files the records name with seedFile(path), keyed by path. Written by os build, which reads each path relative to the package root; the loader stores each one as a file the written record owns.
_lock Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> optional Item-level lock — controls overlay & delete (ADR-0010).
_lockReason string optional Human-readable reason shown when a write is refused by _lock.
_lockSource Enum<'artifact' | 'package' | 'env-forced'> optional Layer that set _lock (artifact | package | env-forced).
_provenance Enum<'package' | 'org' | 'env-forced'> optional Origin of the item (package | org | env-forced).
_packageId string optional Owning package machine id.
_packageVersion string optional Owning package version.
_lockDocsUrl string optional Optional documentation link surfaced next to _lockReason.

Nested Shape: PackageInstallManifest.navigationContributions[number]

A navigation contribution: a package injecting nav items into an app it does not own (ADR-0029 D7)

Property Type Required Description
app string ✅ Target app name to contribute navigation into (e.g. "setup")
group string optional Target group nav-item id to append into (e.g. "group_integrations"); omit to append at the app top level. Naming a group the target app does not declare is not refused: the items are appended at the app top level anyway and a nav_contribution_group_missing diagnostic is emitted — by the runtime at warn, and by os build and os validate at compile time.
priority integer optional (default: 200) Merge priority within the target group — lower applied first (matches object extender priority)
items ({ id: string; label?: string | Record<string, string>; icon?: string; order?: number; … } | { type: 'separator'; id?: string; order?: number } | … +8 more)[] ✅ Navigation items contributed into the target app/group

Nested Shape: PackageInstallManifest.engine

Property Type Required Description
objectstack string ✅ ObjectStack platform version requirement (SemVer range, e.g. ">=3.0.0")

Nested Shape: PackageInstallManifest.engines

Property Type Required Description
platform string optional ObjectStack platform release range (SemVer, e.g. ">=4.0 <5")
protocol string optional Runtime/metadata protocol range, checked first (ADR §3.10 #3)

PackageInstallRequest

Install package request

Properties

Property Type Required Description
manifest { id: string; namespace?: string; defaultDatasource?: string; version: string; … } ✅ Package manifest to install (AUTHORING stage: objects are glob patterns; scope is project)
settings Record<string, any> optional User-provided settings at install time
enableOnInstall boolean optional Whether to enable immediately after install — honoured at POST /api/v1/packages: true enables the installed row, false disables it, and ABSENT keeps the row's current lifecycle state (a fresh install lands enabled)
overwrite boolean optional Overwrite an already-installed package id instead of answering 409 Conflict; an id the deployment ships read-only (code-booted, or scope cloud / system) is refused 422 WRITABLE_PACKAGE_REQUIRED
platformVersion string optional Current platform version for compatibility verification
artifactRef { url: string; sha256: string; size: integer; format?: Enum<'tgz' | 'zip'>; … } optional Artifact reference for marketplace installation

Nested Shape: PackageInstallRequest.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<'project'> optional (default: "project") Deployment scope — an authored install is always project; cloud / system are refused (platform-shipped, read-only scopes)
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'>; columns?: Record<string, object>; … }[] 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
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) and at boot for a plugin os plugin install installed: only node is loaded (in process, not isolated); sandbox and worker are refused until ADR-0025 M3 routes them
packaging Enum<'bundled'> optional Dependency packaging strategy (ADR-0025 v2 §3.3): bundled, the only one and the default — omit the key or write bundled
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: PackageInstallRequest.artifactRef

Property Type Required Description
url string ✅ Artifact download URL
sha256 string ✅ SHA256 checksum
size integer ✅ Artifact size in bytes
format Enum<'tgz' | 'zip'> optional (default: "tgz") Artifact format
uploadedAt string ✅ Upload timestamp

PackageInstallResponse

Install package response

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { package: object; dependencyResolution?: object; namespaceConflicts?: object[]; message?: string } ✅

Nested Shape: PackageInstallResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: PackageInstallResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: PackageInstallResponse.data

Property Type Required Description
package { manifest: object; source: Enum<'code' | 'marketplace' | 'authored'>; status?: Enum<'installed' | 'disabled' | 'installing' | 'upgrading' | 'uninstalling' | 'error'>; enabled?: boolean; … } ✅ Installed package details
dependencyResolution { dependencies: object[]; canProceed: boolean; requiredActions: object[]; installOrder: string[]; … } optional Dependency resolution result
namespaceConflicts { type: 'namespace_conflict'; requestedNamespace: string; conflictingPackageId: string; conflictingPackageName: string; … }[] optional Namespace conflicts detected
message string optional Installation status message

PackagePathParams

Properties

Property Type Required Description
packageId string ✅ Package identifier

PackageRollbackRequest

Rollback package request

Properties

Property Type Required Description
packageId string ✅ Package identifier
snapshotId string ✅ Snapshot ID to restore from
rollbackCustomizations boolean optional (default: true) Whether to restore pre-upgrade customizations

PackageUpgradeRequest

Upgrade package request

Properties

Property Type Required Description
packageId string ✅ Package ID to upgrade
targetVersion string optional Target version (defaults to latest)
manifest { id: string; namespace?: string; defaultDatasource?: string; version: string; … } optional New manifest for the target version
createSnapshot boolean optional (default: true) Whether to create a pre-upgrade backup snapshot
mergeStrategy Enum<'keep-custom' | 'accept-incoming' | 'three-way-merge'> optional (default: "three-way-merge") How to handle customer customizations
dryRun boolean optional (default: false) Preview upgrade without making changes
skipValidation boolean optional (default: false) Skip pre-upgrade compatibility checks

Nested Shape: PackageUpgradeRequest.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'>; columns?: Record<string, object>; … }[] 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
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) and at boot for a plugin os plugin install installed: only node is loaded (in process, not isolated); sandbox and worker are refused until ADR-0025 M3 routes them
packaging Enum<'bundled'> optional Dependency packaging strategy (ADR-0025 v2 §3.3): bundled, the only one and the default — omit the key or write bundled
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)

PackageUpgradeResponse

Upgrade package response

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { success: boolean; phase: string; snapshotId?: string; conflicts?: object[]; … } ✅

Nested Shape: PackageUpgradeResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: PackageUpgradeResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: PackageUpgradeResponse.data

Property Type Required Description
success boolean ✅ Whether the upgrade succeeded
phase string ✅ Current upgrade phase
snapshotId string optional Snapshot ID for rollback
conflicts { path: string; baseValue: any; incomingValue: any; customValue: any }[] optional Unresolved merge conflicts
errorMessage string optional Error message if failed
message string optional Human-readable status message

ResolveDependenciesRequest

Resolve dependencies request

Properties

Property Type Required Description
manifest { id: string; namespace?: string; defaultDatasource?: string; version: string; … } ✅ Package manifest to resolve dependencies for
platformVersion string optional Current platform version for compatibility filtering

Nested Shape: ResolveDependenciesRequest.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'>; columns?: Record<string, object>; … }[] 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
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) and at boot for a plugin os plugin install installed: only node is loaded (in process, not isolated); sandbox and worker are refused until ADR-0025 M3 routes them
packaging Enum<'bundled'> optional Dependency packaging strategy (ADR-0025 v2 §3.3): bundled, the only one and the default — omit the key or write bundled
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)

ResolveDependenciesResponse

Resolve dependencies response

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { dependencies: object[]; canProceed: boolean; requiredActions: object[]; installOrder: string[]; … } ✅ Dependency resolution result with topological sort

Nested Shape: ResolveDependenciesResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: ResolveDependenciesResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: ResolveDependenciesResponse.data

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"]])

UninstallPackageApiRequest

Uninstall package request

Properties

Property Type Required Description
packageId string ✅ Package identifier
keepData boolean optional Preserve object tables and remove metadata only; on the wire, ?keepData=true or ?keepData=1

UninstallPackageApiResponse

Uninstall package response

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { packageId: string; success: boolean; message?: string } ✅

Nested Shape: UninstallPackageApiResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: UninstallPackageApiResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: UninstallPackageApiResponse.data

Property Type Required Description
packageId string ✅ Uninstalled package ID
success boolean ✅ Whether uninstall succeeded
message string optional Uninstall status message

UploadArtifactRequest

Upload artifact request

Properties

Property Type Required Description
artifact { formatVersion?: string; packageId: string; version: string; format?: Enum<'tgz' | 'zip'>; … } ✅ Package artifact metadata
sha256 string optional SHA256 checksum of the uploaded file
token string optional Publisher authentication token
releaseNotes string optional Release notes for this version

Nested Shape: UploadArtifactRequest.artifact

Property Type Required Description
formatVersion string optional (default: "1.0") Artifact format version (e.g. "1.0")
packageId string ✅ Package identifier from manifest
version string ✅ Package version from manifest
format Enum<'tgz' | 'zip'> optional (default: "tgz") Archive format of the artifact
size integer optional Total artifact file size in bytes
builtAt string ✅ ISO 8601 timestamp of when the artifact was built
builtWith string optional Build tool identifier (e.g. "os-cli@3.2.0")
files { path: string; size: integer; category?: Enum<'objects' | 'views' | 'pages' | 'flows' | 'dashboards' | 'permissions' | …> }[] optional List of files contained in the artifact
metadataCategories Enum<'objects' | 'views' | 'pages' | 'flows' | 'dashboards' | 'permissions' | …>[] optional Metadata categories included in this artifact
checksums { algorithm?: Enum<'sha256' | 'sha384' | 'sha512'>; files: Record<string, string> } optional SHA256 checksums for artifact integrity verification
signature { algorithm?: Enum<'RSA-SHA256' | 'RSA-SHA384' | 'RSA-SHA512' | 'ECDSA-SHA256'>; publicKeyRef: string; signature: string; signedAt?: string; … } optional Digital signature for artifact authenticity verification

UploadArtifactResponse

Upload artifact response

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { success: boolean; artifactRef?: object; submissionId?: string; message?: string } ✅

Nested Shape: UploadArtifactResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: UploadArtifactResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: UploadArtifactResponse.data

Property Type Required Description
success boolean ✅ Whether the upload succeeded
artifactRef { url: string; sha256: string; size: integer; format?: Enum<'tgz' | 'zip'>; … } optional Artifact reference in the registry
submissionId string optional Marketplace submission ID for review tracking
message string optional Upload status message