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).
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 and flows 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 and flow another installed package contributes to the base's objects, 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, and 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). Ordered by object, kind, 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.
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.
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.