Skip to content

Commit f1d795b

Browse files
feat(spec): declare the whole-deployment export, every installed package as installable packages in one read (PackageExportBundleSchema) (#29100)
domain:spec#1 · os-steve · session_01ADHkmScwpkMFTAD5HHubn1 <!-- claude-projects-attribution: {"github_login":"os-steve"} --> _Requested by **Steve** · [project thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9MxfAf9Gx3CPUtLb43fGSBY)_ Part of #28914 Clause-②: yes (widening) Metadata-protocol: added Skills-docs: follow-up owed — `content/docs/deployment/cli.mdx` (a row and section for the CLI command that calls the read) and `content/docs/concepts/metadata-lifecycle.mdx` (its export paragraph, which names only the per-package `GET /packages/:id/export`). Both belong with the server slice that mounts the read and adds the command: taught today, they would send a reader to a route no runtime serves. No `skills/**` file teaches package export. Ruling-ref: 6568804196 ## 维护者速读 - 改了什么:在 `@objectstack/spec/api` 声明「整租户本体导出」这个读的回答形状 `PackageExportBundleSchema`:`{ packages }`,一次给出部署里不是由部署自己的代码注册的全部已安装包(注册表行 `source` 不是 `code`:市场安装的和库里创作的包,含 `.custom` 配对包),每一项就是现有单包导出 `GET /packages/:id/export` 的回答,按依赖顺序排好(基础包在前,它的 `.custom` 配对包在后)。导出不带启用状态,装回去每个包都是启用的。这是「先声明、后兑现」(ADR-0049):路由 `GET /packages/export` 和调用它的 CLI 命令是下一张服务端卡的事,本 PR 不碰运行时;在路由真正挂上之前,schema 的 describe 以 `[PLANNED — not yet served]` 开头。 - 为什么改:官网承诺「本体是你的,可以导出到开源运行时跑」,今天只能一个包一个包导;您在 docs.objectos.ai #334 裁定「同意,同时立开发卡」,按车道规矩先定 spec 形状,服务端卡 `Blocked-by` 本 PR。 - 风险与回滚:纯新增,没有任何现有形状或接受集变化;还没有运行时提供这个路由,所以对线上零影响。回滚即撤掉本 PR。 - 先看:`packages/spec/src/api/package-lifecycle.zod.ts` 新增的 `PackageExportBundleSchema` 及其上方说明(选哪些包、什么顺序、凭据不出门、门禁和查询参数);`packages/spec/src/api/package-lifecycle.test.ts` 新增的 7 条测试;`.changeset/28914-package-export-bundle.md`。 - 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run src/api/package-lifecycle.test.ts`,应看到 32 条全过(其中 7 条是本次新增)。 - 需要你做的:批准新公开名(路由路径 `GET /api/v1/packages/export`、schema 名 `PackageExportBundleSchema`、键 `packages`);选包规则已按契约复审改成读注册表行的 `source`(排除 `code`),不再从 `manifest.scope` 推导。批准后由席位落地。 ## What changes - **`PackageExportBundleSchema`** (with `PackageExportBundle` and `PackageExportBundleParsed`) in `packages/spec/src/api/package-lifecycle.zod.ts`, exported from `@objectstack/spec/api`. It is declared ahead of its producer (ADR-0049): it is the `data` that `GET /api/v1/packages/export` must answer once the server slice mounts the route on the runtime dispatcher, enveloped like its lifecycle siblings: `{ packages: PackageExportManifest[] }`, strict at the top level. No runtime serves the route yet, so the schema's describe opens with `[PLANNED — not yet served]` and names ADR-0049, and the docblock states the door as what it MUST do. The change that mounts the route drops the marker, adds the route's ledger row and flips the test that pins the marker. The house has no other planned channel for an API response: the liveness ledgers are per metadata type, the runtime route ledger records only what the dispatcher serves, and the API-level `handlerStatus: 'planned'` was retired under ADR-0049. - **One producer.** `packages` is `z.array(PackageExportManifestSchema)`: each entry is exactly what `GET /packages/:id/export` answers, and a test pins that the element IS that schema (identity, not a copy). A `.custom` pair is its own entry with its override declarations (ADR-0146 D8 item 3); environment customizations stay where the per-package export places them, under the package that owns them. - **Which packages.** Every package whose registry row's `source` (`InstalledPackageSourceSchema`) is not `code`, enabled or not, each once: the marketplace and authored packages, a `.custom` pair among them. A `code` package is registered by the deployment's own code (a `defineStack()` host's packages, a plugin's bundled manifest, a platform package), so it travels with that code and not with the bundle. The registry forbids deriving a package's origin from `manifest.scope` or `writable`, and the per-package export already reads the row that carries `source`. A pair of a `code` base is still exported. A metadata item bound to no package is in no entry; ADR-0146 D11's migration binds it first. - **No enabled state.** The per-package export has no `enabled` or `status` key, so the bundle carries none: every entry installs enabled, and a package the tenant switched off comes back on. Both describes say so. - **Order.** ADR-0141 D5's, the order a boot hydrates installed packages in: an entry comes after every entry its package's `manifest.dependencies` names, so a pair comes after its base. The consumer installs in the order listed and never re-sorts. - **No credential value.** The per-package export already withholds credential positions (it reads the `served` audience, which `decorateMetadataItems` redacts); the bundle adds no second rule, and a `credentialRef` stays a reference. - **The door the server slice must build.** The per-package export's read gate (`studio.access` or `setup.access`, or a system context). A closed, empty query set: the door must refuse a parameter `400 VALIDATION_ERROR`, naming it. Whole or absent: a package whose export cannot be assembled must fail the read, naming it. - **Generated:** `content/docs/references/api/package-lifecycle.mdx` and `content/docs/references/index.mdx` (1594 → 1595 schemas), `packages/spec/api-surface/api.json` (+3 names), `packages/spec/export-origins/api.json`, `packages/spec/declaration-map/api.json`, `packages/spec/json-schema.manifest/api.json` (+`api/PackageExportBundle`), `packages/spec/authorable-surface/api.json` (+`api/PackageExportBundle:packages`), `docs/audits/2026-07-unknown-key-strictness-ledger.counts/api.md` (`api/` 484 → 485). All written by `check:generated --fix`. - **Changeset:** `.changeset/28914-package-export-bundle.md`, `@objectstack/spec: minor`. ### Forced test edits None. No existing test changed. ## Why The maintainer's ruling on docs.objectos.ai #334 (record 6568804196): 「Cloud/Enterprise 租户怎么导出本体?同意,同时立开发卡。」 Today a tenant can export its ontology only one package at a time. This is the spec slice: it declares the read's answer first, and the server slice (the route in `packages/runtime/src/domains/packages.ts`, the CLI command in `packages/cli`, the round-trip and credential tests) is `Blocked-by` this PR. ## Tests `packages/spec/src/api/package-lifecycle.test.ts`, a new describe with 7 tests over a bundle shaped as the card's done criteria name it (a base, its `.custom` pair with an `overrides` block, and a third package extending the base; the base carries a connector whose `auth` keeps `credentialRef`): - the bundle parses and every entry is preserved, in the order listed; - the element of `packages` is `PackageExportManifestSchema` itself, and an entry with no identity is refused at `packages.1.id`, `packages.1.name` and `packages.1.version`; - an empty bundle parses (a deployment whose every package is registered by its own code); - an answer with no `packages` is refused at `packages`; - an unknown top-level member is refused `unrecognized_keys` naming it; - the describe opens with `[PLANNED — not yet served]`, names ADR-0049 and the sentence that no runtime serves the route, and carries no tracker id (the server slice flips this test when it mounts the route); - both describes select by the registry row's `source` (they name `source` and `code`), never mention `scope`, and state the missing enabled state. ## Acceptance notes - **Route, not a member of an existing read (the seat's lean, taken).** A member of `GET /packages` (`ListInstalledPackagesResponseSchema`) would make every list call pay for 27 metadata types per package, and the list keeps its own query set (`status`, `type`, `enabled`). The path cannot collide: `MANIFEST_ID_PATTERN` needs at least two dot-separated segments, so `export` is never a package id and never shadows `GET /packages/:id`. - **Where the route is declared.** Measured on `origin/main` `135054eb`: neither `package-api.zod.ts` nor `package-api-assembled.zod.ts` carries `GET /packages/:id/export`. That route is declared by its response schema's docblock and the runtime route ledger row (`packages/runtime/src/route-ledger.ts`, `responseSchema: 'PackageExportManifestSchema'`). `PackageApiContracts` says a route is declared there "only in the same change that MOUNTS it — never ahead of its door". `PackageApiContracts` binds only the list, get, install and uninstall doors; no lifecycle route has an entry, so this one needs none. This PR adds no ledger row; the server slice adds it (`responseSchema: 'PackageExportBundleSchema'`) with the mount. - **No request schema.** The door reads no path id, no body and no query parameter, so there is nothing to declare beyond the closed empty set, which the docblock states. `GetPackageCustomizationsRequestSchema` exists because that door has a path id. - **No liveness row.** `check:liveness` ledgers are per metadata type (`packages/spec/liveness/TYPE.json`); an API response schema has none. `check:liveness` is green. - **The per-package export does not carry what a reinstall reads (for the server slice).** Read on this head: `assemblePackageManifest` (`packages/runtime/src/domains/packages.ts`) sets only `id`, `name`, `version` and `label` beside the metadata collections. It drops `manifest.namespace` and `manifest.dependencies`. A body with no namespace gets `installPackage`'s id-derived default (`deriveNamespaceFromPackageId`, `packages/metadata-protocol/src/protocol-package-install.ts`), and for a pair that is `custom`, not the base's `NS_custom`: the exact case `protocol-customization-package.ts` sets the namespace explicitly to avoid. So the round trip of a `.custom` pair likely fails until the per-package export carries both keys. This is a reading of source, not a reproduction; the server slice's round-trip test is the measurement. If it holds, `PackageExportManifestSchema` gains two declared fixed keys, which is a spec change (see Open questions). - **The client SDK is untouched.** `client.packages.exportAll` (or similar) and the `unwrap-misfire.pin.test.ts` roster row belong with the server slice. `{ packages }` declares neither `success` nor `data`, so the unwrap heuristic cannot fire on it. ## Open questions (for the maintainer, through the seat) 1. **New public names.** The route path `GET /api/v1/packages/export`; the schema `PackageExportBundleSchema` and its types `PackageExportBundle` / `PackageExportBundleParsed`; the key `packages`. Recommendation: approve as written. They sit beside `PackageExportManifestSchema` and the existing `packages` key of `GET /packages`. 2. **Which packages: settled by the contract review (round 3).** The first draft left out manifest `scope: 'system'`. The review ruled that wrong: `InstalledPackageSourceSchema` forbids deriving a package's origin from `manifest.scope`, and the runtime corrected the same derivation once already. A scope-less `code` package would be exported and then refused `409` on reinstall; a marketplace or authored package carrying `scope: 'system'` would be dropped. The rule now reads the registry row's `source`: every package whose `source` is not `code`. Disabled packages: exported, and both describes say the bundle carries no enabled state (the seat's lean, taken, because the bundle mirrors the per-package export). 3. **The per-package export's missing `namespace` and `dependencies`.** Options: A, the server slice measures the round trip first and, if a pair fails, a spec card adds both as declared fixed keys of `PackageExportManifestSchema`; B, add them in this PR now. Recommendation: A. Declaring keys no producer emits yet would be declared-not-enforced, and the measurement belongs to the slice that runs the install. ## Verification Readings on head `0493264f` (this branch with `origin/main` `ab085a04` merged in) unless a line says otherwise, and on the later heads in the last block; every heavy run went through `os-verify-lock.sh`, whose `VERDICT command-exit` line is quoted. <details><summary>Package suites and type checks (packages/spec and its two named consumers, packages/runtime and packages/cli)</summary> - `pnpm turbo run build --concurrency=2` over the `@objectstack/runtime` and `@objectstack/cli` dependency closures: Tasks 62 successful, 62 total. VERDICT command-exit 0. - `pnpm --filter @objectstack/spec check:generated`: all 14 generated artifacts up to date (exit 0). On the first head it named 5 stale (api-surface, export-origins, declaration-map, references docs, strictness-ledger counts); `--fix` regenerated exactly those, committed in `020adeb0`. - `pnpm --filter @objectstack/spec test`: Test Files 790 passed (790), Tests 23349 passed, 1 todo. VERDICT command-exit 0. - `pnpm --filter @objectstack/spec typecheck`: VERDICT command-exit 0. - `pnpm --filter @objectstack/runtime test`: Test Files 513 passed (513), Tests 8267 passed, 19 skipped. `typecheck`: VERDICT command-exit 0. - `pnpm --filter @objectstack/cli exec vitest run --project unit`: Test Files 368 passed (368), Tests 5196 passed. `typecheck`: VERDICT command-exit 0. The `integration` layer is declared to CI (the diff touches no CLI file). - The same round on `020adeb0`, before `origin/main` `ab085a04` was merged: spec 789/789 files (23330 tests), runtime 513/513, cli unit 368/368, all three typechecks exit 0. - `pnpm exec eslint --no-inline-config --max-warnings=0` over the two changed `.ts` files: exit 0. </details> <details><summary>Ablations and the reverse type probe (on 020adeb; the merge did not touch either file)</summary> - `package-lifecycle.zod.ts`, the bundle's `}).strict().describe(` → `}).describe(` (through `ablation-replace.mjs`, anchor 1 → 0): `package-lifecycle.test.ts` 1 failed | 29 passed ("is strict at the top level"). Restored: blob `ad533652` == HEAD, `git diff HEAD` empty. - `package-lifecycle.zod.ts`, `z.array(PackageExportManifestSchema)` → `z.array(` a hand-copied four-key object with an open catch-all `)`: 1 failed | 29 passed ("judges each entry by THE per-package export schema"). Every other test stayed green, so the copy is indistinguishable by parse alone and only the identity pin catches it. Restored: blob == HEAD. - Reverse type probe in `packages/runtime/src` against the rebuilt `.d.ts`: `const ok: PackageExportBundle = { packages: [ … ] }` compiles; `{ packages: [], cycles: [] }` is TS2353 (`'cycles' does not exist in type …`), the probe's only error. Probe deleted; `git status` clean. </details> <details><summary>Derived gate families (dispatch-gates)</summary> - `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` at `0493264f`: 103 commands, change set 11 paths vs merge base `ab085a048` (+221 / -8). - All 103 exit 0 on `0493264f`. On the first pass `pnpm check:dual-build-cjs-loads` exited 3 (PREREQUISITE NOT MET: no `dist/` for connector-slack, organizations, service-print in this container). After building those three it reported 115 entry points across 70 packages load, exit 0. - `dispatch-gates --ran`: "103 derived famil(ies) accounted for — 103 run, 0 NOT-MEASURED (a DERIVED zero …)". - `check-changeset-no-major.mjs --base origin/main --event` (this body, offline): exit 0, LEVEL AXIS `yes (widening)` + `added`, `@objectstack/spec: minor`. - Local-only families: `check:skill-frame-freshness` exit 0. `check:dev-prereqs` exit 1 is a box precondition (35 `ui/` workspace dists not built in this container), not a reading about this diff. - Full dogfood not run: no `!` in the title and no `(narrowing)` arm. </details> <details><summary>Later heads: the main merge and the three review rounds</summary> - `2882de4a` (`origin/main` `12aad143` merged in through `os-regen-merge.sh`, generated artifacts regenerated by `check:generated --fix`; branch delta unchanged): closure build, `check:generated`, spec test (Test Files 790 passed (790), Tests 23362 passed, 1 todo) and spec typecheck, each VERDICT command-exit 0; all 103 derived gates exit 0, `--ran` 0 NOT-MEASURED. - `cf37246e` (the docblock reads as declared ahead of its producer; the `[PLANNED — not yet served]` marker and its pin test): spec build, `check:generated`, spec test (Test Files 790 passed (790), Tests 23363 passed, 1 todo) and spec typecheck, each VERDICT command-exit 0; `check:doc-authoring` exit 0; all 103 derived gates exit 0, `--ran` 0 NOT-MEASURED; `check-changeset-no-major.mjs --event` exit 0. Ablation: removing the marker from the describe (`ablation-replace.mjs`, anchor 1 → 0) gives 1 failed | 30 passed (the marker test); restored, blob == HEAD. - `a373ba53` (the describe and changeset no longer name a CLI command that does not exist yet): CI's `Lint · docs & code guards` was red on `cf37246e` only at `check:cli-command-ids` (1 of 52 gates; the derived set does not carry it). Now `pnpm check:cli-command-ids` exit 0, `check:doc-authoring` exit 0, `check:generated --fix` rewrote only `content/docs/references/api/package-lifecycle.mdx`, and `package-lifecycle.test.ts` is 31/31. - `1ce77b0a` (contract review round 3: the selection reads the registry row's `source`, not `manifest.scope`; both describes state the missing enabled state; the docblock no longer asks for a `PackageApiContracts` entry): spec build, `check:generated` (`--fix` rewrote only `content/docs/references/api/package-lifecycle.mdx`), spec test (Test Files 790 passed (790), Tests 23364 passed, 1 todo) and spec typecheck, each VERDICT command-exit 0; `pnpm check:cli-command-ids` and `check:doc-authoring` exit 0; all 103 derived gates exit 0, `--ran` 0 NOT-MEASURED; `check-changeset-no-major.mjs --event` exit 0. `package-lifecycle.test.ts` 32/32. Ablation: the `scope` rule put back into the `packages` describe (`ablation-replace.mjs`, anchor 1 → 0) gives 1 failed | 31 passed (the new selection test); restored, blob == HEAD. - `runtime` and `cli` suites were not re-run after `0493264f`: the later commits change describe text and the main merge, and the branch touches neither package. </details> ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` passes. - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: its generated artifacts are regenerated and committed. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English. - [x] The *Before Submitting* list in CONTRIBUTING.md is done. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01ADHkmScwpkMFTAD5HHubn1 --- _Generated by [Claude Code](https://claude.ai/code/session_01ADHkmScwpkMFTAD5HHubn1)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 107be28 commit f1d795b

11 files changed

Lines changed: 280 additions & 8 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
feat(spec): `PackageExportBundleSchema` declares the whole-deployment export, every installed package as installable packages in one read
6+
7+
Clause-②: yes (widening)
8+
Metadata-protocol: added
9+
10+
A tenant on ObjectOS Cloud or Enterprise can take its ontology to the Apache-2.0 runtime only one package at a time today (`GET /packages/:id/export`). This declares the contract of the read that answers all of it at once, `GET /packages/export`. The route, and a CLI command that calls it, follow in `@objectstack/runtime` and `@objectstack/cli`; no runtime serves it yet. Until a runtime mounts the route, the schema's description opens with `[PLANNED — not yet served]` (ADR-0049): the shape is the contract that door must answer, not a read a client can make today.
11+
12+
- **`@objectstack/spec`**: `PackageExportBundleSchema` (with `PackageExportBundle` and `PackageExportBundleParsed`) in `@objectstack/spec/api`. The answer is `{ packages }`: every package whose registry row's `source` is not `code` (the marketplace and authored packages, a `.custom` pair among them; a `code` package is registered by the deployment's own code and travels with that code, not with the bundle), enabled or not, each exactly as `GET /packages/:id/export` answers it. The bundle carries no enabled state, so every entry installs enabled. The entries are `PackageExportManifestSchema` itself, so the per-package export stays the one producer. A base's `.custom` pair is its own entry with its override declarations, and environment customizations stay under the package that owns them. The bundle carries no credential value: the per-package export withholds credential positions, and a `credentialRef` stays a reference.
13+
- **Order**: dependencies first, the order a boot hydrates installed packages in (ADR-0141 D5). An entry comes after every entry its package's `manifest.dependencies` names, so a pair comes after its base. Install the entries in the order listed; a consumer never re-sorts them.
14+
- The answer is strict at the top level; each entry stays open, as the per-package export is.

‎content/docs/references/api/package-lifecycle.mdx‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,8 @@ authored after that retirement per the ruling's sequencing (3A).
5050
## TypeScript Usage
5151

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

5656
// Validate data
5757
const result = DiscardPackageDraftsResponseSchema.parse(data);
@@ -306,6 +306,28 @@ A field or flow another package contributes to one of the base's objects.
306306
| **createdAt** | `string` | optional | When the commit was made (ISO-8601 string), when recorded. |
307307

308308

309+
---
310+
311+
## PackageExportBundle
312+
313+
[PLANNED — not yet served] Whole-deployment 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. Declared ahead of its producer (ADR-0049): no runtime serves `GET /packages/export` yet. The server half of the whole-deployment package export mounts it, together with a future CLI command that calls it; until then this is the contract that door must answer, not a read a client can make.
314+
315+
### Properties
316+
317+
| Property | Type | Required | Description |
318+
| :--- | :--- | :--- | :--- |
319+
| **packages** | `({ id: string; name: string; version: string; label?: 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. |
320+
321+
### Nested Shape: `PackageExportBundle.packages[number]`
322+
323+
| Property | Type | Required | Description |
324+
| :--- | :--- | :--- | :--- |
325+
| **id** | `string` | ✅ | The exported package's id. |
326+
| **name** | `string` | ✅ | The exported package's machine name. |
327+
| **version** | `string` | ✅ | The exported package's version. |
328+
| **label** | `string` | optional | Display label, when the package declares one. |
329+
330+
309331
---
310332

311333
## PackageExportManifest

‎content/docs/references/index.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Protocol reference — every schema by module
33
navTitle: Protocol Reference
4-
description: Every schema published by @objectstack/spec — 1603 schemas across 14 protocol modules
4+
description: Every schema published by @objectstack/spec — 1604 schemas across 14 protocol modules
55
---
66

77
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -21,7 +21,7 @@ counts are sums of the rows they head. Regenerate with
2121
| Module | Pages | Schemas | Description |
2222
| :--- | ---: | ---: | :--- |
2323
| [AI Protocol](/docs/references/ai) | 12 | 68 | Agents, tools, skills, RAG and knowledge sources, model registry, conversations. |
24-
| [API Protocol](/docs/references/api) | 35 | 473 | REST contracts, endpoints, routing, realtime, batch, discovery. |
24+
| [API Protocol](/docs/references/api) | 35 | 474 | REST contracts, endpoints, routing, realtime, batch, discovery. |
2525
| [Automation Protocol](/docs/references/automation) | 15 | 78 | Flows and their nodes, approvals, ETL pipelines, webhooks, state machines, execution records. |
2626
| [Data Protocol](/docs/references/data) | 31 | 174 | Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer. |
2727
| [Identity Protocol](/docs/references/identity) | 5 | 27 | Users and accounts, organizations, positions, SCIM provisioning. |
@@ -34,7 +34,7 @@ counts are sums of the rows they head. Regenerate with
3434
| [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
3535
| [System Protocol](/docs/references/system) | 39 | 292 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
3636
| [UI Protocol](/docs/references/ui) | 16 | 175 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
37-
| **Total** | **208** | **1603** | 14 protocol modules |
37+
| **Total** | **208** | **1604** | 14 protocol modules |
3838

3939
---
4040

@@ -63,7 +63,7 @@ Agents, tools, skills, RAG and knowledge sources, model registry, conversations.
6363

6464
## API Protocol
6565

66-
**Source:** `packages/spec/src/api/` · **Import:** `@objectstack/spec/api` · **35 pages, 473 schemas**
66+
**Source:** `packages/spec/src/api/` · **Import:** `@objectstack/spec/api` · **35 pages, 474 schemas**
6767

6868
REST contracts, endpoints, routing, realtime, batch, discovery.
6969

@@ -90,7 +90,7 @@ REST contracts, endpoints, routing, realtime, batch, discovery.
9090
| [`odata.zod.ts`](/docs/references/api/odata) | `ODataConfig`, `ODataError`, `ODataFilterFunction`, `ODataMetadata`, `ODataQuery`, `ODataResponse` |
9191
| [`package-api.zod.ts`](/docs/references/api/package-api) | `GetInstalledPackageRequest`, `ListInstalledPackagesRequest`, `PackageApiErrorCode`, `PackageInstallBody`, `PackageInstallManifest`, `PackageInstallRequest`, `PackageInstallResponse`, `PackagePathParams`, `PackageRollbackRequest`, `PackageUpgradeRequest`, `PackageUpgradeResponse`, `ResolveDependenciesRequest`, `ResolveDependenciesResponse`, `UninstallPackageApiRequest`, `UninstallPackageApiResponse`, `UploadArtifactRequest`, `UploadArtifactResponse` |
9292
| [`package-api-assembled.zod.ts`](/docs/references/api/package-api-assembled) | `AssembledInstalledPackage`, `GetInstalledPackageResponse`, `InstalledPackageAtEitherStage`, `ListInstalledPackagesResponse` |
93-
| [`package-lifecycle.zod.ts`](/docs/references/api/package-lifecycle) | `DiscardPackageDraftsResponse`, `DuplicatePackageResponse`, `EnsureCustomizationPackageRequest`, `EnsureCustomizationPackageResponse`, `GetPackageCustomizationsRequest`, `GetPackageCustomizationsResponse`, `ImportUnmanagedPackageRequest`, `ImportUnmanagedPackageResponse`, `ListPackageCommitsResponse`, `PackageExportManifest`, `PackagePublishResult`, `ReassignOrphanedMetadataResponse`, `RevertPackageCommitResponse`, `RollbackToPackageCommitResponse` |
93+
| [`package-lifecycle.zod.ts`](/docs/references/api/package-lifecycle) | `DiscardPackageDraftsResponse`, `DuplicatePackageResponse`, `EnsureCustomizationPackageRequest`, `EnsureCustomizationPackageResponse`, `GetPackageCustomizationsRequest`, `GetPackageCustomizationsResponse`, `ImportUnmanagedPackageRequest`, `ImportUnmanagedPackageResponse`, `ListPackageCommitsResponse`, `PackageExportBundle`, `PackageExportManifest`, `PackagePublishResult`, `ReassignOrphanedMetadataResponse`, `RevertPackageCommitResponse`, `RollbackToPackageCommitResponse` |
9494
| [`plugin-rest-api.zod.ts`](/docs/references/api/plugin-rest-api) | `ErrorHandlingConfig`, `OpenApiGenerationConfig`, `RequestValidationConfig`, `ResponseEnvelopeConfig`, `RestApiEndpoint`, `RestApiPluginConfig`, `RestApiRouteCategory`, `RestApiRouteRegistration`, `ValidationMode` |
9595
| [`protocol.zod.ts`](/docs/references/api/protocol) | `AiAgentCapabilities`, `AiAgentChatRequest`, `AiAgentSummary`, `AiAgentsResponse`, `AiChatRequest`, `AiChatResponse`, `AiCompleteRequest`, `AiConversation`, `AiMessage`, `AiModelsResponse`, `AiPendingAction`, `AiPendingActionStatus`, `AiStreamChunk`, `ApproveAiPendingActionResponse`, `AuditMetaItemRequest`, `AuditMetaItemResponse`, `AutomationActionsResponse`, `AutomationTriggerRequest`, `AutomationTriggerResponse`, `BatchDataRequest`, `BatchDataResponse`, `CheckPermissionRequest`, `CheckPermissionResponse`, `CloneDataResponse`, `CreateAiConversationRequest`, `CreateDataRequest`, `CreateDataResponse`, `CreateManyDataRequest`, `CreateManyDataResponse`, `DeleteDataRequest`, `DeleteDataResponse`, `DeleteManyDataRequest`, `DeleteManyDataResponse`, `DeleteMetaItemRequest`, `DeleteMetaItemResponse`, `DiffMetaItemResponse`, `DisablePackageRequest`, `DisablePackageResponse`, `EnablePackageRequest`, `EnablePackageResponse`, `FindDataRequest`, `FindDataResponse`, `FindReferencesToMetaResponse`, `FlowRegistration`, `FlowRegistrationRefusal`, `GetDataRequest`, `GetDataResponse`, `GetDiscoveryRequest`, `GetDiscoveryResponse`, `GetEffectivePermissionsRequest`, `GetEffectivePermissionsResponse`, `GetFieldLabelsRequest`, `GetFieldLabelsResponse`, `GetLocalesRequest`, `GetLocalesResponse`, `GetMetaDiagnosticsResponse`, `GetMetaItemCachedRequest`, `GetMetaItemCachedResponse`, `GetMetaItemLayeredRequest`, `GetMetaItemLayeredResponse`, `GetMetaItemRequest`, `GetMetaItemResponse`, `GetMetaItemsRequest`, `GetMetaItemsResponse`, `GetMetaTypesRequest`, `GetMetaTypesResponse`, `GetNotificationPreferencesRequest`, `GetNotificationPreferencesResponse`, `GetObjectPermissionsRequest`, `GetObjectPermissionsResponse`, `GetPackageRequest`, `GetPackageResponse`, `GetPresenceRequest`, `GetPresenceResponse`, `GetPublishedMetaItemResponse`, `GetRecordFieldAccessResponse`, `GetTranslationsRequest`, `GetTranslationsResponse`, `GetUiViewRequest`, `GetUiViewResponse`, `HistoryMetaItemRequest`, `HistoryMetaItemResponse`, `HttpFindQueryParams`, `InstallPackageRequest`, `InstallPackageResponse`, `ListAiConversationsRequest`, `ListAiConversationsResponse`, `ListAiPendingActionsRequest`, `ListAiPendingActionsResponse`, `ListDraftsResponse`, `ListNotificationsRequest`, `ListNotificationsResponse`, `ListPackagesRequest`, `ListPackagesResponse`, `MarkAllNotificationsReadRequest`, `MarkAllNotificationsReadResponse`, `MarkNotificationsReadRequest`, `MarkNotificationsReadResponse`, `MetadataAuthoringClient`, `MetadataAuthoringSurface`, `MetadataConflictError`, `Notification`, `NotificationPreferences`, `PublicFormSubmitResponse`, `PublishMetaItemRequest`, `PublishMetaItemResponse`, `PublishPackageDraftsRequest`, `PublishPackageDraftsResponse`, `RealtimeConnectRequest`, `RealtimeConnectResponse`, `RealtimeDisconnectRequest`, `RealtimeDisconnectResponse`, `RealtimeSubscribeRequest`, `RealtimeSubscribeResponse`, `RealtimeUnsubscribeRequest`, `RealtimeUnsubscribeResponse`, `RegisterDeviceRequest`, `RegisterDeviceResponse`, `RejectAiPendingActionResponse`, `RollbackMetaItemResponse`, `RuntimeAuthoringIssue`, `SaveMetaItemRequest`, `SaveMetaItemResponse`, `SearchAllHit`, `SearchAllPageHit`, `SearchAllResponse`, `SetPresenceRequest`, `SetPresenceResponse`, `UninstallPackageRequest`, `UninstallPackageResponse`, `UnregisterDeviceRequest`, `UnregisterDeviceResponse`, `UpdateAiConversationRequest`, `UpdateDataRequest`, `UpdateDataResponse`, `UpdateManyDataRequest`, `UpdateManyDataResponse`, `UpdateNotificationPreferencesRequest`, `UpdateNotificationPreferencesResponse`, `ValidateDataIssue`, `ValidateDataRequest`, `ValidateDataResponse` |
9696
| [`push-delivery.zod.ts`](/docs/references/api/push-delivery) | `PushDeliveryData`, `PushRoute` |

‎docs/audits/2026-07-unknown-key-strictness-ledger.counts/api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,4 @@ hand-patch a number here** — fix the code or the verdict and regenerate.
1919

2020
| Dir | Sites |
2121
|---|---|
22-
| `api/` | 488 |
22+
| `api/` | 489 |

‎packages/spec/api-surface/api.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -778,6 +778,9 @@
778778
"PROVENANCE_WAIVERS (const)",
779779
"PackageApiErrorCode (const)",
780780
"PackageApiErrorCode (type)",
781+
"PackageExportBundle (type)",
782+
"PackageExportBundleParsed (type)",
783+
"PackageExportBundleSchema (const)",
781784
"PackageExportManifest (type)",
782785
"PackageExportManifestParsed (type)",
783786
"PackageExportManifestSchema (const)",

‎packages/spec/authorable-surface/api.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1301,6 +1301,7 @@
13011301
"api/OperatorMapping:odata",
13021302
"api/OperatorMapping:operator",
13031303
"api/OperatorMapping:rest",
1304+
"api/PackageExportBundle:packages",
13041305
"api/PackageExportManifest:id",
13051306
"api/PackageExportManifest:label",
13061307
"api/PackageExportManifest:name",

‎packages/spec/declaration-map/api.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -570,6 +570,8 @@
570570
"OperatorMapping": "api/OperatorMapping",
571571
"OperatorMappingSchema": "api/OperatorMapping",
572572
"PackageApiErrorCode": "api/PackageApiErrorCode",
573+
"PackageExportBundle": "api/PackageExportBundle",
574+
"PackageExportBundleSchema": "api/PackageExportBundle",
573575
"PackageExportManifest": "api/PackageExportManifest",
574576
"PackageExportManifestSchema": "api/PackageExportManifest",
575577
"PackageInstallBody": "api/PackageInstallBody",

‎packages/spec/export-origins/api.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -750,6 +750,9 @@
750750
"OperatorMappingSchema": "src/api/query-adapter.zod.ts#OperatorMappingSchema (const)",
751751
"PROVENANCE_WAIVERS": "src/api/error-code-ledger.zod.ts#PROVENANCE_WAIVERS (const)",
752752
"PackageApiErrorCode": "src/api/package-api.zod.ts#PackageApiErrorCode (type)",
753+
"PackageExportBundle": "src/api/package-lifecycle.zod.ts#PackageExportBundle (type)",
754+
"PackageExportBundleParsed": "src/api/package-lifecycle.zod.ts#PackageExportBundleParsed (type)",
755+
"PackageExportBundleSchema": "src/api/package-lifecycle.zod.ts#PackageExportBundleSchema (const)",
753756
"PackageExportManifest": "src/api/package-lifecycle.zod.ts#PackageExportManifest (type)",
754757
"PackageExportManifestParsed": "src/api/package-lifecycle.zod.ts#PackageExportManifestParsed (type)",
755758
"PackageExportManifestSchema": "src/api/package-lifecycle.zod.ts#PackageExportManifestSchema (const)",

‎packages/spec/json-schema.manifest/api.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -311,6 +311,7 @@
311311
"api/OpenApiSpec",
312312
"api/OperatorMapping",
313313
"api/PackageApiErrorCode",
314+
"api/PackageExportBundle",
314315
"api/PackageExportManifest",
315316
"api/PackageInstallBody",
316317
"api/PackageInstallManifest",

0 commit comments

Comments
 (0)