You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Response payloads for the dispatcher-served packages.* lifecycle routes — the ADR-0067 commit timeline, the ADR-0033 draft batch doors.
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
Package lifecycle response contracts (#12038)
Response payloads for the dispatcher-served packages.* lifecycle routes —
the ADR-0067 commit timeline, the ADR-0033 draft batch doors, the ADR-0070
export / adopt / duplicate family — ruled on 2026-08-27 (#12038,
1C · 2C · 3A · 4A · 5A).
Every schema here is a DESCRIBE-ONLY TRANSCRIPTION of the return type its
producer already declares inline (@objectstack/metadata-protocolprotocol.ts, except where a schema's own docblock says otherwise) —
authoring one changes no wire byte. All of these routes are served by the
runtime dispatcher ONLY (no REST twin — #12038 survey §1b), which answers
through the { success, data } envelope (http-dispatcher.ts), so each
schema declares the data payload, envelope-free — the same convention as
PublishPackageDraftsResponseSchema and its ledger row.
Two pairs are the exception, each with a request half its producer PARSES
rather than a transcription: ImportUnmanagedPackageRequestSchema /
ImportUnmanagedPackageResponseSchema (ADR-0131 D6) declare a protocol verb
no route serves yet, and EnsureCustomizationPackageRequestSchema /
EnsureCustomizationPackageResponseSchema (ADR-0146 D3) declare the ensure
door of a base's paired .custom package — see their own docblocks.
packages.publish's contract is NOT here: its producer
(MetadataManager.publishPackage) already has an exact published schema,
PackagePublishResultSchema in @objectstack/spec/system — re-exported
below into this /api namespace (ruling 5A: re-export, never a second
copy) because the route-ledger resolver looks names up only in the API
protocol's entries — @objectstack/spec/api, and /api-assembled for the
declarations that embed the assembled package body (#18576).
The retired PackageRollbackResponseSchema and its
PackageApiContracts.rollbackPackage binding (see ./package-api-assembled.zod.ts)
declared a VERSION rollback against the live COMMIT-rollback path;
RollbackToPackageCommitResponseSchema below is the true contract,
authored after that retirement per the ruling's sequencing (3A).
Two members are not transcriptions but DECLARED AHEAD OF THEIR PRODUCER
(ADR-0049), each describe opening [PLANNED — not yet served] until the
change that serves it drops the marker: the nav arm of
GetPackageCustomizationsResponseSchema.contributions (#27928) and
PackageExportManifestSchema.withheldMaps (#28640 ruling ③A, served by
#29342). Their own docblocks say what is not served yet.
Id of the installed base whose paired customization package is ensured (com.acme.crm → com.acme.crm.custom). The base must be installed and read-only — a writable base is customized directly — and must not itself be a customization package.
EnsureCustomizationPackageResponse
Properties
Property
Type
Required
Description
basePackageId
string
✅
The base the pair customizes.
packageId
string
✅
The paired customization package: <basePackageId>.custom.
namespace
string
✅
The pair's namespace: the base's namespace followed by _custom (crm → crm_custom), set explicitly and never derived from the pair's id. A new object authored into the pair is named <namespace>_<short>.
dependencyRange
string
✅
The range the pair declares on its base in manifest.dependencies. A created pair declares ^<major> of the base's version at creation; an existing pair answers the range it declares, unchanged.
created
boolean
✅
True when this call created the pair; false when the pair was already installed and was returned unchanged.
writable
boolean
✅
Whether the pair is a writable package — the verdict the package read doors serve as writable. A created pair is writable; an existing pair delivered by code or an installed artifact is not, and its items are authored where it is built.
GetPackageCustomizationsRequest
Per-package customization read request: the base package id, no query parameters.
Properties
Property
Type
Required
Description
packageId
string
✅
The installed BASE package whose customizations are read (e.g. "com.acme.crm"). A paired <base>.custom id is refused 400 VALIDATION_ERROR with a message naming its base; an id no installed package carries answers 404.
GetPackageCustomizationsResponse
Per-package customization read: overrides, extensions and switched-off items of one installed base, and the fields, flows and (not yet served) navigation items other packages contribute to it.
Properties
Property
Type
Required
Description
packageId
string
✅
The base package the customizations are of (the request's id).
Every ACTIVE item of the base's paired <base>.custom package that declares overrides.package = the base and that the effective read serves over the base's item of the same name: the rows the served-override predicate admits (a declaration from any other package, and an undeclared pair item, are not listed), minus the stored rows every read declines (a shipped flow name). Ordered by type, name and member.
Every field, validation rule and index the paired <base>.custom package declares in an object extension (objectExtensions) of an object the base owns, one entry per member, as the extension declares it. Ordered by object, kind and name.
switchedOff
{ type: string; name: string }[]
✅
Every activation-ledger row (sys_metadata_activation) that records the base as its package and active: false: the base's items this deployment switched off. Ordered by type and name.
Every field, flow and navigation item another installed package contributes to the base, one entry per item and contributing package: the fields of every object extension of an object the base owns, from any package but the base and its pair; every flow registered under such a package whose trigger object the base owns (a flow of a disabled package is not served, so not listed); and, declared ahead of its producer and not yet served, every navigation item such a package contributes to an app the base owns. The entry shape is per kind: object for field and flow, app and an optional group for nav. Ordered: the field and flow entries first, by object, kind, name and package; then the nav entries, by app, group (an entry with no group first), name and package.
Metadata type of the overriding item, canonical singular (e.g. view).
name
string
✅
Name of the item: the base's name it is served under.
member
string
optional
The bundle member, for a metadata type whose identity is a pair (email_template, identified by (name, locale)): its discriminator value. Absent for a type whose identity is its name alone.
basedOn
string
optional
The base package version the declaration records (overrides.basedOn), copied as stored and never judged. Absent when the stored body records none.
version
integer
optional
The overriding item's stored history version, when the row carries one.
A field or flow another package contributes to one of the base's objects.
Property
Type
Required
Description
kind
Enum<'field' | 'flow'>
✅
What is contributed: field, a field another package's object extension (objectExtensions) adds to one of the base's objects; flow, a flow another package ships whose trigger object (its start node's config.objectName) is one of the base's objects.
object
string
✅
The base-owned object the item is on: the extended object, or the flow's trigger object.
name
string
✅
The item's name: the field name as the extension declares it, or the flow's name.
packageId
string
✅
The package that contributes the item: the extension's package, or the package the flow is registered under. Never the base and never its <base>.custom pair.
[PLANNED — not yet served] Declared ahead of its producer (ADR-0049): the read lists no nav entry yet. A navigation item another installed package contributes to an app the base owns, one entry per item of the contribution's items (a contributed group's children ride inside it and are not entries of their own), read from the same contribution registry the served app's navigation fold reads (ADR-0029 D7). An item that declares no id (a separator may omit it) has no name to give and is not an entry. A disabled package's contributions are not listed, as the fold drops them.
Property
Type
Required
Description
kind
'nav'
✅
What is contributed: nav, a navigation item another package's navigationContributions entry adds to the navigation of an app the base owns.
app
string
✅
The base-owned app the item is contributed to: the contribution's app.
group
string
optional
The group nav item the contribution targets: its group, as the contribution declares it. Absent when the contribution targets the app's top level. A group the app does not declare is still named here, though the served navigation appends those items at the app's top level.
name
string
✅
The nav item's id, as the contribution's items declare it.
packageId
string
✅
The package that contributes the item: the package whose navigationContributions declares it. Never the base and never its <base>.custom pair.
The package to import: ONE package's assembled body, flattened — its manifest fields beside its metadata collections (objects, views, …), the shape the install door hands the manifest service. An artifact carrying packages is refused: import each package body on its own.
targetPackageId
string
optional
Id of the NEW writable base the items are written into, in reverse-domain form. It must differ from the source id and name no installed package. Defaults to <manifest.id>-copy.
targetName
string
optional
Display name of the new base. Defaults to the source package's name.
ImportUnmanagedPackageResponse
Properties
Property
Type
Required
Description
sourcePackageId
string
✅
The id of the package the items were copied from.
sourceVersion
string
optional
The version the imported body declared, when it declared one.
targetPackageId
string
✅
The new writable base that owns every copied item. Nothing is registered under the source id.
namespace
string
✅
The base's namespace — the SOURCE package's, kept so every copied object name stays valid.
copiedCount
number
✅
How many items were copied.
copied
{ type: string; name: string }[]
✅
Every item that was copied, in the order it was written.
Every protection lock the package shipped on a copied item and the copy does not keep, in the order the items were written. Empty when the package locked nothing.
When the commit was made (ISO-8601 string), when recorded.
PackageExportBundle
Whole-deployment export, the answer of GET /packages/export (os package export): every installed package the deployment's own code does not register (registry source other than code), as installable packages in dependency order. Carries no credential value and no enabled state. A package whose export cannot be assembled fails the whole read, naming it.
Every package whose registry row's source is not code (the marketplace and authored packages, a .custom pair among them), enabled or not, each once and each as GET /packages/:id/export answers it, dependencies first: an entry comes after every entry its package's manifest.dependencies names, so a .custom pair comes after its base. Install the entries in this order; never re-sort them. No entry carries an enabled state, so every entry installs enabled. Empty when every package of the deployment is registered by its own code.
The namespace the package was installed with, as its registry row's manifest declares it; absent when the row declares none. An install of the export keeps it instead of deriving one from the id, so a .custom pair is reinstalled under its own namespace rather than custom.
dependencies
Record<string, string>
optional
The packages this package depends on, each id mapped to its version range, as its registry row's manifest declares them; absent when the row declares none. An install of the export orders it after each of them (ADR-0141 D5), and a .custom pair keeps the edge to its base that admits its overrides (ADR-0146 D2).
[PLANNED — not yet served] Declared ahead of its producer (ADR-0049): no export writes this list yet and no install door reads it yet. Every map the export withheld WHOLE because a served read never carries it: a connector's header and environment-variable maps. The item is written with that map absent, so once served an import reads this list to tell an incomplete map from one the package never had, and names each one for an operator to re-enter. Positions only: no header or variable name is listed. Absence says nothing about what was withheld when the exporter predates this key; from an exporter that writes it, absence means nothing was withheld.
PackageExportManifest
Properties
Property
Type
Required
Description
id
string
✅
The exported package's id.
name
string
✅
The exported package's machine name.
version
string
✅
The exported package's version.
namespace
string
optional
The namespace the package was installed with, as its registry row's manifest declares it; absent when the row declares none. An install of the export keeps it instead of deriving one from the id, so a .custom pair is reinstalled under its own namespace rather than custom.
dependencies
Record<string, string>
optional
The packages this package depends on, each id mapped to its version range, as its registry row's manifest declares them; absent when the row declares none. An install of the export orders it after each of them (ADR-0141 D5), and a .custom pair keeps the edge to its base that admits its overrides (ADR-0146 D2).
[PLANNED — not yet served] Declared ahead of its producer (ADR-0049): no export writes this list yet and no install door reads it yet. Every map the export withheld WHOLE because a served read never carries it: a connector's header and environment-variable maps. The item is written with that map absent, so once served an import reads this list to tell an incomplete map from one the package never had, and names each one for an operator to re-enter. Positions only: no header or variable name is listed. Absence says nothing about what was withheld when the exporter predates this key; from an exporter that writes it, absence means nothing was withheld.