feat(spec)!: split the assembled-stage package API declarations off ./api into @objectstack/spec/api-assembled

.changeset/18576-api-assembled-entry-split.md

@@ -0,0 +1,40 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: split the assembled-stage package API declarations off `@objectstack/spec/api` into the new `@objectstack/spec/api-assembled` entry (#18576)
+
+**BREAKING** — five Package API declarations, with their types, are no longer exported from `@objectstack/spec/api`. They are exported, unchanged, from the new entry `@objectstack/spec/api-assembled`.
+
+A `major`-class change — an existing import path stops resolving for these names — recorded as `minor` under the launch-window convention. Maintainer ruling on #18576, batch #145 item 1, letter B, 「同意,其他也同意」.
+
+**Why.** These five declarations embed the ASSEMBLED package body, which reaches the whole metadata vocabulary and, behind it, the datasource declaration and the driver-config validators. While they were declared inside `@objectstack/spec/api`, that tree was part of every bundle of the entry, and the entry ships as one self-contained bundle that a consumer's tree-shaking can recover little of. A browser module that imports two string constants from `@objectstack/spec/api` paid for all of it. Measured on the splitting PR (esbuild 0.28.2, `platform: browser`, conditions `browser` + `import`, minified, gzip -9), for objectui's `@object-ui/core` `column-sortability.ts`, which imports only those two constants: **311,124 → 166,529 bytes gzipped (−46.5%)**. The `./api` entry bundle itself goes from 612,813 to 469,795 bytes gzipped, and its module graph no longer reaches `stack.zod`, the datasource declaration or any driver-config module. `./api` also no longer needs a `browser` export condition, since nothing in its graph links the server-only pg URL grammar any more; the condition moves to `./api-assembled`.
+
+### FROM → TO
+
+| removed from `@objectstack/spec/api` | import instead from |
+| --- | --- |
+| `AssembledInstalledPackageSchema`, `AssembledInstalledPackage`, `AssembledInstalledPackageParsed` | `@objectstack/spec/api-assembled` |
+| `InstalledPackageAtEitherStageSchema`, `InstalledPackageAtEitherStage`, `InstalledPackageAtEitherStageParsed` | `@objectstack/spec/api-assembled` |
+| `ListInstalledPackagesResponseSchema`, `ListInstalledPackagesResponse`, `ListInstalledPackagesResponseParsed` | `@objectstack/spec/api-assembled` |
+| `GetInstalledPackageResponseSchema`, `GetInstalledPackageResponse`, `GetInstalledPackageResponseParsed` | `@objectstack/spec/api-assembled` |
+| `PackageApiContracts` | `@objectstack/spec/api-assembled` |
+
+**The one-line fix: change the import path.**
+
+```ts
+// before
+import { ListInstalledPackagesResponseSchema } from '@objectstack/spec/api';
+// after
+import { ListInstalledPackagesResponseSchema } from '@objectstack/spec/api-assembled';
+```
+
+The compiler finds every site: `TS2305` ("Module '"@objectstack/spec/api"' has no exported member …"), or `TS2724` with a did-you-mean when a similarly named export exists — measured on the splitting PR, `ListInstalledPackagesResponseSchema` from `/api` answers `TS2724 … Did you mean 'InstallPackageResponseSchema'?`, which is NOT the name you want. Nothing else changes: every schema parses and refuses exactly what it did, `PackageApiContracts` keeps its four entries, and the JSON Schema ids are the same (`json-schema/api/AssembledInstalledPackage.json` and its three siblings are still published under `api/`, and still documented in the API reference). Every other Package API declaration — the two read doors' request schemas, the install / uninstall / upgrade / rollback shapes and `PackageApiErrorCode` — stays on `@objectstack/spec/api`. If you only use those, or any other `/api` contract, you need to do nothing.
+
+⚠️ **Out-of-repo consumers are NOT MEASURED beyond objectui.** Inside this repository the moved names had four importers (the client's type import, one runtime conformance test, the client's return-type pins and the spec's own unit test), all moved in the same PR. objectui at the pinned `.objectui-sha` imports none of the moved names from anywhere; its six browser-shipped files that import `@objectstack/spec/api` keep resolving every name they use, from `/api` itself. `@object-ui/types` re-exports `@objectstack/spec/api` as a type-only `API` namespace, which loses the moved names with this release; objectui itself references none of them through it. The `cloud` repository was not measured.
+
+The ADR-0087 D3 semantic entry `api-assembled-entry-split` carries the judgement: an import path is TypeScript source, not metadata, so there is no source a D2 conversion could rewrite.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered api-assembled-entry-split -->

.changeset/18576-client-api-assembled-type-import.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/client': patch
+---
+
+fix(client): take `InstalledPackageAtEitherStage` from `@objectstack/spec/api-assembled` (#18576)
+
+`@objectstack/spec` moved the declarations that embed the assembled package body — `InstalledPackageAtEitherStage` among them — off `@objectstack/spec/api` into the new `@objectstack/spec/api-assembled` entry. The client's `packages.list` / `packages.get` return types (and their scoped twins) name that type, so the published declarations now import it from the new entry. The return types are the same type as before; nothing a caller writes changes. It is a type-only import, erased from the client's bundle.

content/docs/deployment/troubleshooting.mdx

@@ -344,7 +344,7 @@ import { FieldSchema } from '@objectstack/spec/data';
 import { ErrorResponseSchema } from '@objectstack/spec/api';
 ```
 
-Available subpaths (the `./*` entries of the package's `exports` map, in its order): `data`, `system`, `kernel`, `ai`, `automation`, `api`, `ui`, `contracts`, `integration`, `security`, `studio`, `marketplace`, `qa`, `identity`, `shared`, `meta-spelling`.
+Available subpaths (the `./*` entries of the package's `exports` map, in its order): `data`, `system`, `kernel`, `ai`, `automation`, `api`, `api-assembled`, `ui`, `contracts`, `integration`, `security`, `studio`, `marketplace`, `qa`, `identity`, `shared`, `meta-spelling`.
 
 ---
 

content/docs/getting-started/quick-reference.mdx

@@ -126,7 +126,7 @@ AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking
 | **[Usage](/docs/references/ai/usage)** | `usage.zod.ts` | AIUsageRecord, TokenUsage | AI usage and cost tracking |
 | **[Solution Blueprint](/docs/references/ai/solution-blueprint)** | `solution-blueprint.zod.ts` | BlueprintObject, BlueprintApp | Blueprint format for AI app generation |
 
-## API Protocol (17 of 31 schemas)
+## API Protocol (17 of 32 schemas)
 
 REST endpoints, real-time subscriptions, and discovery.
 

content/docs/references/api/index.mdx

@@ -27,6 +27,7 @@ This section contains all protocol schemas for the api layer of ObjectStack.
   <Card href="/docs/references/api/misc" title="Misc" />
   <Card href="/docs/references/api/odata" title="Odata" description="Source: packages/spec/src/api/odata.zod.ts" />
   <Card href="/docs/references/api/package-api" title="Package Api" description="Source: packages/spec/src/api/package-api.zod.ts" />
+  <Card href="/docs/references/api/package-api-assembled" title="Package Api Assembled" description="Source: packages/spec/src/api/package-api-assembled.zod.ts" />
   <Card href="/docs/references/api/package-lifecycle" title="Package Lifecycle" description="Source: packages/spec/src/api/package-lifecycle.zod.ts" />
   <Card href="/docs/references/api/plugin-rest-api" title="Plugin Rest Api" description="Source: packages/spec/src/api/plugin-rest-api.zod.ts" />
   <Card href="/docs/references/api/protocol" title="Protocol" description="Source: packages/spec/src/api/protocol.zod.ts" />

content/docs/references/api/meta.json

@@ -34,6 +34,7 @@
     "---More---",
     "error-code-ledger",
     "misc",
+    "package-api-assembled",
     "package-lifecycle",
     "sortability"
   ]