fix(spec): declare the assembled manifest stage on the package read API (#17517)

* wip(spec): declare the assembled manifest stage on the installed-package row

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

* wip(spec): keep the read-API record body JSON-Schema representable

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

* feat(spec): declare the assembled manifest stage on the package read API

`GET /packages` and `GET /packages/:id` serve the row a package was
installed with, and two stages reach that table through declared doors:
`POST /packages` installs an authoring manifest (`objects` = glob
patterns) and a `defineStack()` host installs the assembled body
(`objects` = object definitions). Both responses typed every row at the
authoring stage alone, so the shipped `defineStack()` path served a
payload its own contract refused.

Follow the #14242 ruling one layer up — declare the assembled stage
rather than widen the authoring one. `@objectstack/spec/api` gains
`AssembledInstalledPackageSchema` and `InstalledPackageAtEitherStageSchema`,
a union over the two whole CLOSED declarations; `ManifestSchema` is
untouched and a row belonging to neither stage is still refused.

Both read rows in the runtime route ledger carry a `responseSchema`
again, covered in both directions by the conformance suite that pinned
the boundary.

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

* chore(spec): regenerate api-surface, export-origins, declaration-map, docs

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

* fix(spec): give `./api` a browser export condition

The package read API's assembled-stage declaration made
`src/api/index.ts` reach the driver-config validators
(`package-api.zod.ts` -> `stack.zod` -> `data/datasource.zod` ->
`driver/config-registry.zod` -> `postgres.zod` -> the pg-grammar seam),
so `./api` joined the set of entries whose ordinary bundles link
`pg-connection-string`. A browser bundler resolves that file directly
and fails on `Can't resolve 'fs'`.

Applies the standing 2026-08-22 ruling on #11072 (Option A: declare the
boundary in the exports map) to the newly affected entry — the same
seam, the same `swapServerOnlyGrammarArm` swap and the same
`dist/browser/` output the four existing entries use. No second
mechanism, and the four existing entries are untouched.

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

* fix(runtime): strip tracker ids from the /packages route-ledger notes

`check:doc-authoring` refuses internal issue ids in runtime string prose:
a `note:` reaches authors, operators and generated surfaces, none of whom
can resolve `#NNNN`. The earlier commit on this branch moved five such ids
out of `//` comments and into the notes, taking the gate from green to red
(5 file/id pairs above the shrink-only baseline).

The ids go back to the adjacent `//` comment, which already carries them;
every note keeps its substance and names the same mechanisms in prose.

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

* docs(changeset): record the `./api` browser export condition

The exports map is published surface: browser consumers of
`@objectstack/spec/api` now resolve a different build, and the postgres
`url` refinement degrades there to its shape-only checks. Say so where
the release notes will read it.

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

* docs(changeset): state what the stage union does and does not buy statically

The changeset told consumers they "see a union at `manifest` and narrow at the
point of use". Measured against the built `.d.ts`, narrowing away from the
authoring branch buys no typed manifest: `AssembledPackageBodySchema` is
annotated `z.ZodType<Record<string, unknown>, …>` in `stack.zod.ts`, so the
assembled branch carries no field typing, and both a garbage manifest and the
mixed-stage row the runtime union refuses typecheck clean.

Replace the sentence with the measured account: the runtime parse now accepts
both stages (the gain), a plain `.manifest.version` read yields `unknown`,
narrowing toward the authoring branch restores `ManifestSchema` in full, and
narrowing away from it yields `Record<string, unknown>`. The opacity is
inherited from `stack.zod.ts` and untouched here. No code, schema, exports map
or ledger row changes.

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-bill

.changeset/plain-donkeys-repeat.md

@@ -0,0 +1,56 @@
+---
+'@objectstack/spec': minor
+---
+
+Declare the ASSEMBLED manifest stage on the installed-package read API.
+
+`GET /api/v1/packages` and `GET /api/v1/packages/:packageId` serve whatever a
+package was installed with, and two stages reach that table through declared
+doors: `POST /api/v1/packages` installs an authoring manifest (`manifest.objects`
+= glob patterns), while a `defineStack()` host installs the assembled body
+(`manifest.objects` = object definitions). Both response schemas typed every row
+at the authoring stage alone, so the shipped `defineStack()` path served a
+payload its own declared contract refused.
+
+Following the #14242 ruling — declare the assembled stage rather than widen the
+authoring one — `@objectstack/spec/api` gains two exports:
+`AssembledInstalledPackageSchema` (the assembled-stage counterpart of
+`InstalledPackageSchema`) and `InstalledPackageAtEitherStageSchema`, a union
+over the two whole closed stage declarations. `ListInstalledPackagesResponseSchema`
+and `GetInstalledPackageResponseSchema` are bound to the union.
+
+This is additive at runtime, and the runtime parse is where the gain is: every
+payload that parsed before still parses, payloads that were refused for their
+manifest stage now parse, and a row belonging to neither stage — an `objects`
+array mixing globs with definitions — is still refused. `ManifestSchema` is
+unchanged.
+
+The STATIC gain is one-sided, and smaller than a union normally implies.
+`AssembledPackageBodySchema` is annotated `z.ZodType<Record<string, unknown>, …>`
+in `stack.zod.ts` — deliberately, for the declaration-size reasons recorded
+there, and untouched by this change — so the assembled branch carries no field
+typing. Measured against the built `.d.ts`: a plain `.manifest.version` read off
+one of these two response types now yields `unknown` where it used to yield
+`string`; narrowing toward the AUTHORING branch restores the whole of
+`ManifestSchema` (`version: string`, `objects: string[]`), while narrowing away
+from it yields `Record<string, unknown>` — every manifest field `unknown`. In the
+assignment direction the assembled branch admits any object at `manifest`, so a
+garbage manifest and the mixed-stage row named above both typecheck clean even
+though the runtime union refuses both. So: narrow at the point of use for the
+authoring stage, and treat an assembled manifest as a record the runtime — not
+the compiler — has checked.
+
+`@objectstack/spec/api` also gains a `browser` export condition. Declaring the
+assembled stage makes this entry's module graph reach the datasource
+declaration and with it the driver-config validators, whose postgres URL
+refinement links `pg-connection-string` — a package whose `parse` statically
+resolves `require('fs')`, so a browser bundler that reaches it fails on
+`Can't resolve 'fs'`. The entry now resolves, for browser consumers only, to a
+build with the pg-grammar arm swapped for its dependency-free twin: exactly the
+boundary the four entries that already carry the condition use. Node resolution
+and the Node bundles are unchanged, byte for byte. For browser consumers the
+postgres `url` refinement degrades to the shape-only checks it already performs
+before `parse` — the unix-socket short-circuit and the refusal of the
+filesystem-reading `?sslcert=` / `?sslkey=` / `?sslrootcert=` query parameters
+are kept; the "is this a URL `pg` can open" arm answers "no findings". Datasource
+publish is a server-side act, so that arm never legitimately ran in a browser.

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

@@ -1,6 +1,6 @@
 ---
 title: Protocol Reference
-description: Every schema published by @objectstack/spec — 1521 schemas across 14 protocol modules
+description: Every schema published by @objectstack/spec — 1523 schemas across 14 protocol modules
 ---
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -20,7 +20,7 @@ counts are sums of the rows they head. Regenerate with
 | Module | Pages | Schemas | Description |
 | :--- | ---: | ---: | :--- |
 | [AI Protocol](/docs/references/ai) | 11 | 66 | Agents, tools, skills, RAG and knowledge sources, model registry, conversations. |
-| [API Protocol](/docs/references/api) | 31 | 438 | REST contracts, endpoints, routing, realtime, batch, discovery. |
+| [API Protocol](/docs/references/api) | 31 | 440 | REST contracts, endpoints, routing, realtime, batch, discovery. |
 | [Automation Protocol](/docs/references/automation) | 14 | 74 | Flows and their nodes, approvals, ETL pipelines, webhooks, state machines, execution records. |
 | [Data Protocol](/docs/references/data) | 29 | 173 | Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer. |
 | [Identity Protocol](/docs/references/identity) | 5 | 27 | Users and accounts, organizations, positions, SCIM provisioning. |
@@ -33,7 +33,7 @@ counts are sums of the rows they head. Regenerate with
 | [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
 | [System Protocol](/docs/references/system) | 33 | 272 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
 | [UI Protocol](/docs/references/ui) | 16 | 153 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
-| **Total** | **192** | **1521** | 14 protocol modules |
+| **Total** | **192** | **1523** | 14 protocol modules |
 
 ---
 
@@ -61,7 +61,7 @@ Agents, tools, skills, RAG and knowledge sources, model registry, conversations.
 
 ## API Protocol
 
-**Source:** `packages/spec/src/api/` · **Import:** `@objectstack/spec/api` · **31 pages, 438 schemas**
+**Source:** `packages/spec/src/api/` · **Import:** `@objectstack/spec/api` · **31 pages, 440 schemas**
 
 REST contracts, endpoints, routing, realtime, batch, discovery.
 
@@ -85,7 +85,7 @@ REST contracts, endpoints, routing, realtime, batch, discovery.
 | [`metadata.zod.ts`](/docs/references/api/metadata) | `AppDefinitionResponse`, `ConceptListResponse`, `MetadataBulkRegisterRequest`, `MetadataBulkResponse`, `MetadataBulkUnregisterRequest`, `MetadataDeleteResponse`, `MetadataDependenciesResponse`, `MetadataDependentsResponse`, `MetadataExistsResponse`, `MetadataExportRequest`, `MetadataExportResponse`, `MetadataImportRequest`, `MetadataImportResponse`, `MetadataItemResponse`, `MetadataListResponse`, `MetadataNamesResponse`, `MetadataQueryRequest`, `MetadataQueryResponse`, `MetadataRegisterRequest`, `MetadataTypeInfoResponse`, `MetadataTypesResponse`, `MetadataValidateRequest`, `MetadataValidateResponse`, `ObjectDefinitionResponse` |
 | [`misc`](/docs/references/api/misc) *(no single source file)* | `ResolvedBook`, `ResolvedEntry`, `ResolvedGroup` |
 | [`odata.zod.ts`](/docs/references/api/odata) | `ODataConfig`, `ODataError`, `ODataFilterFunction`, `ODataMetadata`, `ODataQuery`, `ODataResponse` |
-| [`package-api.zod.ts`](/docs/references/api/package-api) | `GetInstalledPackageRequest`, `GetInstalledPackageResponse`, `ListInstalledPackagesRequest`, `ListInstalledPackagesResponse`, `PackageApiErrorCode`, `PackageInstallRequest`, `PackageInstallResponse`, `PackagePathParams`, `PackageRollbackRequest`, `PackageUpgradeRequest`, `PackageUpgradeResponse`, `ResolveDependenciesRequest`, `ResolveDependenciesResponse`, `UninstallPackageApiRequest`, `UninstallPackageApiResponse`, `UploadArtifactRequest`, `UploadArtifactResponse` |
+| [`package-api.zod.ts`](/docs/references/api/package-api) | `AssembledInstalledPackage`, `GetInstalledPackageRequest`, `GetInstalledPackageResponse`, `InstalledPackageAtEitherStage`, `ListInstalledPackagesRequest`, `ListInstalledPackagesResponse`, `PackageApiErrorCode`, `PackageInstallRequest`, `PackageInstallResponse`, `PackagePathParams`, `PackageRollbackRequest`, `PackageUpgradeRequest`, `PackageUpgradeResponse`, `ResolveDependenciesRequest`, `ResolveDependenciesResponse`, `UninstallPackageApiRequest`, `UninstallPackageApiResponse`, `UploadArtifactRequest`, `UploadArtifactResponse` |
 | [`package-lifecycle.zod.ts`](/docs/references/api/package-lifecycle) | `DiscardPackageDraftsResponse`, `DuplicatePackageResponse`, `ListPackageCommitsResponse`, `PackageExportManifest`, `PackagePublishResult`, `ReassignOrphanedMetadataResponse`, `RevertPackageCommitResponse`, `RollbackToPackageCommitResponse` |
 | [`plugin-rest-api.zod.ts`](/docs/references/api/plugin-rest-api) | `ErrorHandlingConfig`, `OpenApiGenerationConfig`, `RequestValidationConfig`, `ResponseEnvelopeConfig`, `RestApiEndpoint`, `RestApiPluginConfig`, `RestApiRouteCategory`, `RestApiRouteRegistration`, `ValidationMode` |
 | [`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`, `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`, `GetTranslationsRequest`, `GetTranslationsResponse`, `GetUiViewRequest`, `GetUiViewResponse`, `HistoryMetaItemRequest`, `HistoryMetaItemResponse`, `HttpFindQueryParams`, `InstallPackageRequest`, `InstallPackageResponse`, `ListAiConversationsRequest`, `ListAiConversationsResponse`, `ListAiPendingActionsRequest`, `ListAiPendingActionsResponse`, `ListDraftsResponse`, `ListNotificationsRequest`, `ListNotificationsResponse`, `ListPackagesRequest`, `ListPackagesResponse`, `MarkAllNotificationsReadRequest`, `MarkAllNotificationsReadResponse`, `MarkNotificationsReadRequest`, `MarkNotificationsReadResponse`, `Notification`, `NotificationPreferences`, `PublishMetaItemRequest`, `PublishMetaItemResponse`, `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` |