Skip to content

Latest commit

 

History

History
465 lines (331 loc) · 29.1 KB

package-lifecycle.mdx

File metadata and controls

465 lines (331 loc) · 29.1 KB
title Package Lifecycle — API Protocol reference
navTitle Package Lifecycle
description 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-protocol protocol.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.

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

TypeScript Usage

import { DiscardPackageDraftsResponseSchema, DuplicatePackageResponseSchema, EnsureCustomizationPackageRequestSchema, EnsureCustomizationPackageResponseSchema, GetPackageCustomizationsRequestSchema, GetPackageCustomizationsResponseSchema, ImportUnmanagedPackageRequestSchema, ImportUnmanagedPackageResponseSchema, ListPackageCommitsResponseSchema, PackageExportBundleSchema, PackageExportManifestSchema, PackagePublishResultSchema, ReassignOrphanedMetadataResponseSchema, RevertPackageCommitResponseSchema, RollbackToPackageCommitResponseSchema } from '@objectstack/spec/api';
import type { DiscardPackageDraftsResponse, DuplicatePackageResponse, EnsureCustomizationPackageRequest, EnsureCustomizationPackageResponse, GetPackageCustomizationsRequest, GetPackageCustomizationsResponse, ImportUnmanagedPackageRequest, ImportUnmanagedPackageResponse, ListPackageCommitsResponse, PackageExportBundle, PackageExportManifest, PackagePublishResult, ReassignOrphanedMetadataResponse, RevertPackageCommitResponse, RollbackToPackageCommitResponse } from '@objectstack/spec/api';

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

DiscardPackageDraftsResponse

Properties

Property Type Required Description
success boolean ✅ True exactly when nothing failed.
discardedCount number ✅ How many drafts were discarded.
failedCount number ✅ How many drafts could not be discarded.
discarded { type: string; name: string }[] ✅ Every draft that was discarded.
failed { type: string; name: string; error: string; code?: string }[] ✅ Every draft the discard could not remove.

Nested Shape: DiscardPackageDraftsResponse.discarded[number]

Property Type Required Description
type string ✅ Metadata type of the discarded draft.
name string ✅ Name of the discarded draft.

Nested Shape: DiscardPackageDraftsResponse.failed[number]

Property Type Required Description
type string ✅ Metadata type of the failing draft.
name string ✅ Name of the failing draft.
error string ✅ Why the discard failed.
code string optional Machine-readable failure code, when one was recorded.

DuplicatePackageResponse

Properties

Property Type Required Description
success boolean ✅ The duplicate's own verdict: true exactly when nothing failed AND at least one item was copied.
copiedCount number ✅ How many items were copied.
failedCount number ✅ How many items could not be copied.
targetPackageId string ✅ The new package the base was cloned into.
copied { type: string; name: string }[] ✅ Every item that was copied.
failed { type: string; name: string; error: string }[] ✅ Every item the clone could not copy.

Nested Shape: DuplicatePackageResponse.copied[number]

Property Type Required Description
type string ✅ Metadata type of the copied item.
name string ✅ Name of the copied item.

Nested Shape: DuplicatePackageResponse.failed[number]

Property Type Required Description
type string ✅ Metadata type of the failing item.
name string ✅ Name of the failing item.
error string ✅ Why copying it failed.

EnsureCustomizationPackageRequest

Properties

Property Type Required Description
basePackageId string ✅ 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).
overrides { type: string; name: string; member?: string; basedOn?: string; … }[] ✅ 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.
extensions { object: string; kind: Enum<'field' | 'validation' | 'index'>; name?: string; fields?: string[] }[] ✅ 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.
contributions ({ kind: Enum<'field' | 'flow'>; object: string; name: string; packageId: string } | { kind: 'nav'; app: string; group?: string; name: string; … })[] ✅ 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.
counts { overrides: integer; extensions: integer; switchedOff: integer; contributions: integer } ✅ Each list's length, derived from the lists in this same answer.

Nested Shape: GetPackageCustomizationsResponse.overrides[number]

Property Type Required Description
type string ✅ 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.

Nested Shape: GetPackageCustomizationsResponse.extensions[number]

Property Type Required Description
object string ✅ The base-owned object the member is added to.
kind Enum<'field' | 'validation' | 'index'> ✅ Which collection of the object the member joins.
name string optional The member's declared name: the field name, the validation rule name, the index name. Absent only for an index declared without a name.
fields string[] optional For an index: the fields it covers. Absent for a field or a validation.

Nested Shape: GetPackageCustomizationsResponse.switchedOff[number]

Property Type Required Description
type string ✅ The ledger row's metadata type (flow, action, position, …).
name string ✅ The switched-off item's name.

Nested Shape: GetPackageCustomizationsResponse.contributions[number][option 1]

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.

Nested Shape: GetPackageCustomizationsResponse.contributions[number][option 2]

[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.

Nested Shape: GetPackageCustomizationsResponse.counts

Property Type Required Description
overrides integer ✅ overrides.length.
extensions integer ✅ extensions.length: members, not objects.
switchedOff integer ✅ switchedOff.length.
contributions integer ✅ contributions.length: items, not packages.

ImportUnmanagedPackageRequest

Properties

Property Type Required Description
manifest Record<string, any> ✅ 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.
strippedLocks { type: string; name: string; lock: Enum<'no-overlay' | 'no-delete' | 'full'>; reason?: string }[] ✅ 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.

Nested Shape: ImportUnmanagedPackageResponse.copied[number]

Property Type Required Description
type string ✅ Metadata type of the copied item.
name string ✅ Name of the copied item.

Nested Shape: ImportUnmanagedPackageResponse.strippedLocks[number]

Property Type Required Description
type string ✅ Metadata type of the copied item.
name string ✅ Name of the copied item.
lock Enum<'no-overlay' | 'no-delete' | 'full'> ✅ The lock the package shipped on the item — its protection block's lock, else its _lock. The copy carries no lock.
reason string optional The reason the package gave for that lock, verbatim. Absent when it gave none.

ListPackageCommitsResponse

Properties

Property Type Required Description
commits { id: string; operation: Enum<'apply' | 'revert'>; message?: string; actor?: string; … }[] ✅ The commit timeline, newest first.

Nested Shape: ListPackageCommitsResponse.commits[number]

Property Type Required Description
id string ✅ Commit id.
operation Enum<'apply' | 'revert'> ✅ Whether the commit applied changes or reverted an earlier commit.
message string optional Commit message, when one was recorded.
actor string optional Who made the commit, when recorded.
aiModel string optional AI model that authored the change, when recorded.
parentCommitId string optional The commit this one chains from, when recorded.
itemCount number ✅ How many items the commit touched.
items { type: string; name: string; member?: string; existedBefore: boolean; … }[] ✅ The items the commit touched.
createdAt string optional 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.

Properties

Property Type Required Description
packages ({ id: string; name: string; version: string; namespace?: string; … } & Record<string, any>)[] ✅ 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.

Nested Shape: PackageExportBundle.packages[number]

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).
label string optional Display label, when the package declares one.
withheldMaps { type: 'connector'; name: string; path: Enum<'providerConfig.headers' | 'providerConfig.defaultHeaders' | …> }[] optional [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).
label string optional Display label, when the package declares one.
withheldMaps { type: 'connector'; name: string; path: Enum<'providerConfig.headers' | 'providerConfig.defaultHeaders' | …> }[] optional [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.

Nested Shape: PackageExportManifest.withheldMaps[number]

Property Type Required Description
type 'connector' ✅ Metadata type of the item whose map was withheld.
name string ✅ Name of the item whose map was withheld.
path Enum<'providerConfig.headers' | 'providerConfig.defaultHeaders' | …> ✅ Dot path of the withheld map inside the item.

PackagePublishResult

Properties

Property Type Required Description
success boolean ✅ Whether the publish succeeded
packageId string ✅ The package ID that was published
version integer ✅ New version number after publish
publishedAt string ✅ Publish timestamp
itemsPublished integer ✅ Total metadata items published
validationErrors { type: string; name: string; message: string }[] optional Validation errors if publish failed

Nested Shape: PackagePublishResult.validationErrors[number]

Property Type Required Description
type string ✅ Metadata type that failed validation
name string ✅ Item name that failed validation
message string ✅ Validation error message

ReassignOrphanedMetadataResponse

Properties

Property Type Required Description
success boolean ✅ Whether the reassignment ran.
reassignedCount number ✅ How many orphaned items were adopted.
reassigned { type: string; name: string }[] ✅ Every item that was adopted.
targetPackageId string ✅ The package the items were adopted into.

Nested Shape: ReassignOrphanedMetadataResponse.reassigned[number]

Property Type Required Description
type string ✅ Metadata type of the adopted item.
name string ✅ Name of the adopted item.

RevertPackageCommitResponse

Properties

Property Type Required Description
success boolean ✅ True exactly when nothing failed.
revertedCount number ✅ How many items were reverted.
failedCount number ✅ How many items could not be reverted.
reverted { type: string; name: string; action: Enum<'removed' | 'restored'> }[] ✅ Every item the revert touched.
failed { type: string; name: string; error: string; code?: string }[] ✅ Every item the revert could not touch.
revertCommitId string optional Id of the commit the revert itself created, when one was written.

Nested Shape: RevertPackageCommitResponse.reverted[number]

Property Type Required Description
type string ✅ Metadata type of the reverted item.
name string ✅ Name of the reverted item.
action Enum<'removed' | 'restored'> ✅ What the revert did to the item — removed what the commit created, or restored what it overwrote.

Nested Shape: RevertPackageCommitResponse.failed[number]

Property Type Required Description
type string ✅ Metadata type of the failing item.
name string ✅ Name of the failing item.
error string ✅ Why the revert failed for this item.
code string optional Machine-readable failure code, when one was recorded.

RollbackToPackageCommitResponse

Properties

Property Type Required Description
success boolean ✅ True exactly when nothing failed.
revertedCommits string[] ✅ Ids of the commits that were rolled back, in the order they were reverted.
failed { commitId: string; error: string }[] ✅ Every commit the rollback could not revert.

Nested Shape: RollbackToPackageCommitResponse.failed[number]

Property Type Required Description
commitId string ✅ The commit that could not be reverted.
error string ✅ Why reverting it failed.