Repository navigation
Commit f1d795b
feat(spec): declare the whole-deployment export, every installed package as installable packages in one read (
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>PackageExportBundleSchema) (#29100)1 parent 107be28 commit f1d795b
11 files changed
Lines changed: 280 additions & 8 deletions
File tree
- .changeset
- content/docs/references
- api
- docs/audits/2026-07-unknown-key-strictness-ledger.counts
- packages/spec
- api-surface
- authorable-surface
- declaration-map
- export-origins
- json-schema.manifest
- src/api
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
50 | 50 | | |
51 | 51 | | |
52 | 52 | | |
53 | | - | |
54 | | - | |
| 53 | + | |
| 54 | + | |
55 | 55 | | |
56 | 56 | | |
57 | 57 | | |
| |||
306 | 306 | | |
307 | 307 | | |
308 | 308 | | |
| 309 | + | |
| 310 | + | |
| 311 | + | |
| 312 | + | |
| 313 | + | |
| 314 | + | |
| 315 | + | |
| 316 | + | |
| 317 | + | |
| 318 | + | |
| 319 | + | |
| 320 | + | |
| 321 | + | |
| 322 | + | |
| 323 | + | |
| 324 | + | |
| 325 | + | |
| 326 | + | |
| 327 | + | |
| 328 | + | |
| 329 | + | |
| 330 | + | |
309 | 331 | | |
310 | 332 | | |
311 | 333 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
| |||
21 | 21 | | |
22 | 22 | | |
23 | 23 | | |
24 | | - | |
| 24 | + | |
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
| |||
34 | 34 | | |
35 | 35 | | |
36 | 36 | | |
37 | | - | |
| 37 | + | |
38 | 38 | | |
39 | 39 | | |
40 | 40 | | |
| |||
63 | 63 | | |
64 | 64 | | |
65 | 65 | | |
66 | | - | |
| 66 | + | |
67 | 67 | | |
68 | 68 | | |
69 | 69 | | |
| |||
90 | 90 | | |
91 | 91 | | |
92 | 92 | | |
93 | | - | |
| 93 | + | |
94 | 94 | | |
95 | 95 | | |
96 | 96 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
22 | | - | |
| 22 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
778 | 778 | | |
779 | 779 | | |
780 | 780 | | |
| 781 | + | |
| 782 | + | |
| 783 | + | |
781 | 784 | | |
782 | 785 | | |
783 | 786 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1301 | 1301 | | |
1302 | 1302 | | |
1303 | 1303 | | |
| 1304 | + | |
1304 | 1305 | | |
1305 | 1306 | | |
1306 | 1307 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
570 | 570 | | |
571 | 571 | | |
572 | 572 | | |
| 573 | + | |
| 574 | + | |
573 | 575 | | |
574 | 576 | | |
575 | 577 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
750 | 750 | | |
751 | 751 | | |
752 | 752 | | |
| 753 | + | |
| 754 | + | |
| 755 | + | |
753 | 756 | | |
754 | 757 | | |
755 | 758 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
311 | 311 | | |
312 | 312 | | |
313 | 313 | | |
| 314 | + | |
314 | 315 | | |
315 | 316 | | |
316 | 317 | | |
| |||
0 commit comments