ObjectStackObjectStack

Package Lifecycle — API Protocol reference

Response payloads for the dispatcher-served packages.* lifecycle routes — the ADR-0067 commit timeline, the ADR-0033 draft batch doors.

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.

One pair is the exception: ImportUnmanagedPackageRequestSchema / ImportUnmanagedPackageResponseSchema (ADR-0131 D6) declare a protocol verb no route serves yet, and the request half is parsed by its producer rather than transcribed — 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).

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

TypeScript Usage

import { DiscardPackageDraftsResponseSchema, DuplicatePackageResponseSchema, ImportUnmanagedPackageRequestSchema, ImportUnmanagedPackageResponseSchema, ListPackageCommitsResponseSchema, PackageExportManifestSchema, PackagePublishResultSchema, ReassignOrphanedMetadataResponseSchema, RevertPackageCommitResponseSchema, RollbackToPackageCommitResponseSchema } from '@objectstack/spec/api';
import type { DiscardPackageDraftsResponse, DuplicatePackageResponse, ImportUnmanagedPackageRequest, ImportUnmanagedPackageResponse, ListPackageCommitsResponse, PackageExportManifest, PackagePublishResult, ReassignOrphanedMetadataResponse, RevertPackageCommitResponse, RollbackToPackageCommitResponse } from '@objectstack/spec/api';

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

DiscardPackageDraftsResponse

Properties

PropertyTypeRequiredDescription
successboolean✅True exactly when nothing failed.
discardedCountnumber✅How many drafts were discarded.
failedCountnumber✅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]

PropertyTypeRequiredDescription
typestring✅Metadata type of the discarded draft.
namestring✅Name of the discarded draft.

Nested Shape: DiscardPackageDraftsResponse.failed[number]

PropertyTypeRequiredDescription
typestring✅Metadata type of the failing draft.
namestring✅Name of the failing draft.
errorstring✅Why the discard failed.
codestringoptionalMachine-readable failure code, when one was recorded.

DuplicatePackageResponse

Properties

PropertyTypeRequiredDescription
successboolean✅The duplicate's own verdict: true exactly when nothing failed AND at least one item was copied.
copiedCountnumber✅How many items were copied.
failedCountnumber✅How many items could not be copied.
targetPackageIdstring✅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]

PropertyTypeRequiredDescription
typestring✅Metadata type of the copied item.
namestring✅Name of the copied item.

Nested Shape: DuplicatePackageResponse.failed[number]

PropertyTypeRequiredDescription
typestring✅Metadata type of the failing item.
namestring✅Name of the failing item.
errorstring✅Why copying it failed.

ImportUnmanagedPackageRequest

Properties

PropertyTypeRequiredDescription
manifestRecord<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.
targetPackageIdstringoptionalId 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.
targetNamestringoptionalDisplay name of the new base. Defaults to the source package's name.

ImportUnmanagedPackageResponse

Properties

PropertyTypeRequiredDescription
sourcePackageIdstring✅The id of the package the items were copied from.
sourceVersionstringoptionalThe version the imported body declared, when it declared one.
targetPackageIdstring✅The new writable base that owns every copied item. Nothing is registered under the source id.
namespacestring✅The base's namespace — the SOURCE package's, kept so every copied object name stays valid.
copiedCountnumber✅How many items were copied.
copied{ type: string; name: string }[]✅Every item that was copied, in the order it was written.

Nested Shape: ImportUnmanagedPackageResponse.copied[number]

PropertyTypeRequiredDescription
typestring✅Metadata type of the copied item.
namestring✅Name of the copied item.

ListPackageCommitsResponse

Properties

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

Nested Shape: ListPackageCommitsResponse.commits[number]

PropertyTypeRequiredDescription
idstring✅Commit id.
operationEnum<'apply' | 'revert'>✅Whether the commit applied changes or reverted an earlier commit.
messagestringoptionalCommit message, when one was recorded.
actorstringoptionalWho made the commit, when recorded.
aiModelstringoptionalAI model that authored the change, when recorded.
parentCommitIdstringoptionalThe commit this one chains from, when recorded.
itemCountnumber✅How many items the commit touched.
items{ type: string; name: string; existedBefore: boolean; prevVersion: number | null }[]✅The items the commit touched.
createdAtstringoptionalWhen the commit was made (ISO-8601 string), when recorded.

PackageExportManifest

Properties

PropertyTypeRequiredDescription
idstring✅The exported package's id.
namestring✅The exported package's machine name.
versionstring✅The exported package's version.
labelstringoptionalDisplay label, when the package declares one.

PackagePublishResult

Properties

PropertyTypeRequiredDescription
successboolean✅Whether the publish succeeded
packageIdstring✅The package ID that was published
versioninteger✅New version number after publish
publishedAtstring✅Publish timestamp
itemsPublishedinteger✅Total metadata items published
validationErrors{ type: string; name: string; message: string }[]optionalValidation errors if publish failed

Nested Shape: PackagePublishResult.validationErrors[number]

PropertyTypeRequiredDescription
typestring✅Metadata type that failed validation
namestring✅Item name that failed validation
messagestring✅Validation error message

ReassignOrphanedMetadataResponse

Properties

PropertyTypeRequiredDescription
successboolean✅Whether the reassignment ran.
reassignedCountnumber✅How many orphaned items were adopted.
reassigned{ type: string; name: string }[]✅Every item that was adopted.
targetPackageIdstring✅The package the items were adopted into.

Nested Shape: ReassignOrphanedMetadataResponse.reassigned[number]

PropertyTypeRequiredDescription
typestring✅Metadata type of the adopted item.
namestring✅Name of the adopted item.

RevertPackageCommitResponse

Properties

PropertyTypeRequiredDescription
successboolean✅True exactly when nothing failed.
revertedCountnumber✅How many items were reverted.
failedCountnumber✅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.
revertCommitIdstringoptionalId of the commit the revert itself created, when one was written.

Nested Shape: RevertPackageCommitResponse.reverted[number]

PropertyTypeRequiredDescription
typestring✅Metadata type of the reverted item.
namestring✅Name of the reverted item.
actionEnum<'removed' | 'restored'>✅What the revert did to the item — removed what the commit created, or restored what it overwrote.

Nested Shape: RevertPackageCommitResponse.failed[number]

PropertyTypeRequiredDescription
typestring✅Metadata type of the failing item.
namestring✅Name of the failing item.
errorstring✅Why the revert failed for this item.
codestringoptionalMachine-readable failure code, when one was recorded.

RollbackToPackageCommitResponse

Properties

PropertyTypeRequiredDescription
successboolean✅True exactly when nothing failed.
revertedCommitsstring[]✅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]

PropertyTypeRequiredDescription
commitIdstring✅The commit that could not be reverted.
errorstring✅Why reverting it failed.

On this page

Package lifecycle response contracts (#12038)TypeScript UsageDiscardPackageDraftsResponsePropertiesNested Shape: DiscardPackageDraftsResponse.discarded[number]Nested Shape: DiscardPackageDraftsResponse.failed[number]DuplicatePackageResponsePropertiesNested Shape: DuplicatePackageResponse.copied[number]Nested Shape: DuplicatePackageResponse.failed[number]ImportUnmanagedPackageRequestPropertiesImportUnmanagedPackageResponsePropertiesNested Shape: ImportUnmanagedPackageResponse.copied[number]ListPackageCommitsResponsePropertiesNested Shape: ListPackageCommitsResponse.commits[number]PackageExportManifestPropertiesPackagePublishResultPropertiesNested Shape: PackagePublishResult.validationErrors[number]ReassignOrphanedMetadataResponsePropertiesNested Shape: ReassignOrphanedMetadataResponse.reassigned[number]RevertPackageCommitResponsePropertiesNested Shape: RevertPackageCommitResponse.reverted[number]Nested Shape: RevertPackageCommitResponse.failed[number]RollbackToPackageCommitResponsePropertiesNested Shape: RollbackToPackageCommitResponse.failed[number]