Bind published response contracts for the 17 unbound client-SDK methods; retire the false PackageRollbackResponseSchema (#12038, ruling 1C·2C·3A·4A·5A) (#12848)

* spec: retire PackageRollbackResponseSchema and the rollbackPackage contract binding (#12038 3A)

The schema declared a VERSION rollback ({ success, restoredVersion?,
message? }) while PackageApiContracts.rollbackPackage bound it to the live
POST /api/v1/packages/:packageId/rollback path, which the dispatcher serves
with rollbackToPackageCommit — the ADR-0067 COMMIT rollback, a different
operation with a different result. Retired through the ADR-0087 discipline:
RETIRED_DEFS_BY_MAJOR entry api/PackageRollbackResponse, D3 semantic entry
package-rollback-response-retired, manifest key and authorable-surface
baseline lines released with their registered proof (#4725 / #4650), runtime
namespace-probe pins in package-api.test.ts. PackageRollbackRequestSchema
stays published as ruled; the true commit-rollback contract follows in the
next commit, after this retirement per the ruling's sequencing.

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

* spec: bind the meta history/diagnostics and package lifecycle response contracts (#12038)

The twelve describe-only transcriptions from the recorded ruling
(1C/2C/3A/4A/5A), each transcribed from the return type its producer already
declares inline: six meta.* payloads in api/protocol.zod.ts (listDrafts,
getMetaDiagnostics, findReferencesToMeta, rollbackMetaItem, diffMetaItem,
plus the ruling-1C opaque GetPublishedMetaItemResponseSchema), the package
lifecycle family in the new api/package-lifecycle.zod.ts (discardDrafts,
listCommits with the handler-minted commits wrapper, revertCommit, the true
commit-rollback RollbackToPackageCommitResponseSchema, the ruling-4A
fixed-keys-plus-catchall PackageExportManifestSchema, adoptOrphans,
duplicate), and the resolved book tree as Zod beside its interfaces in
system/book.zod.ts. Ruling 5A re-exports (PackagePublishResultSchema,
ResolvedBookSchema family) land in the /api namespace the ledger resolver
searches — never a second copy. meta.migrateStored stays unbound, documented
(ruling 2C). Generated artifacts regenerated by the spec build.

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

* runtime/rest/client: name the #12038 response contracts in the ledgers and bind the SDK

Fill responseSchema on the 18 boundable ledger rows across both ledgers,
each row stating which surface's envelope it describes (the dispatcher wraps
{ success, data }; the REST server answers the payload bare — the three
dual-mounted meta routes carry one note per surface). meta.migrateStored's
two rows document the ruling-2C deliberate unbinding instead. Conformance
suites land with the rows (spec api/protocol.test.ts, the new
api/package-lifecycle.test.ts, system/book.test.ts — the #3877
no-row-without-conformance rule, house capture pattern).

The client SDK binds 16 of the 17 methods to the published payload types
(migrateStored stays any, documented per 2C; getPublished binds to unknown
per 1C), replaces the four invented test mocks (getDiagnostics, getBookTree,
rollbackItem, diffItem) with producer-true shapes, flips the #11925 rollback
negative guard to guard the new commit-rollback truth, adds the
returnTypePrecisionPins12038 type-level pins, and pins the unwrapResponse
mis-unwrap hazard (survey §8.2) so no bound payload can ever declare both a
boolean success and a data key.

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

* spec/docs: regenerate artifacts for the new contracts; add the #12038 changeset

api-surface, export-origins, reference docs and the strictness ledger
regenerated by check:generated --fix (only the artifacts it proved stale);
the ResolvedBook type family re-exported on /api so the generated page's
import line resolves. The changeset carries the breaking FROM-to-TO mapping
and the ADR-0087 disposition (registered package-rollback-response-retired).

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

* spec: keep the package-lifecycle header inside the description corpus pins

The file docblock opened at heading level 1 (the #12249 demotion pin counts
exactly the 38 files that predate it) and split a code span across lines,
leaving a same-directory source path as plain text for the #6484 rule. Open
at level 2 and keep the span on one line; reference docs regenerated.

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

* spec/docs: satisfy the ADR-0122 alias convention and the quick-reference total for the new contracts

The 13 new response types gain their Parsed aliases (check:spec-parsed-alias;
all are isomorphic — no defaults or transforms — but the paired-alias route
keeps the family uniform with its package-api siblings), the API Protocol
quick-reference heading's M rises to the 31 pages the reference tree now
publishes, and the spec artifacts are regenerated for the new type exports.

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

* spec: count the package-lifecycle module in llms.txt's schema inventory

check:llms-txt (the last step of the source-gates job) went red on the new
api/package-lifecycle.zod.ts: the hand-kept inventory declared 207 schemas
total and 29 under api. Re-read per the gate's own rule — number AND prose:
208 / 30, with Package Lifecycle added to the api row's key-schema sampler.
Gate re-derived green locally: 97 claims, 14 domains, 208 schemas.

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

* client: shrink the exported-any-returns ledger by the 15 gaps this PR closed

check:exported-any-returns (Type Check - consumer gates) is exact in both
directions: the #11925 entries for the newly bound meta.* and packages.*
methods no longer resolve to any, so their ledger rows must be deleted.
meta.migrateStored's entry stays - it remains any by the 2C ruling. Verified
against the rebuilt dist: 'no NEW exported callable resolves to any: 317
callables reached, 47 ledgered site(s) still open'.

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

* spec: spell the discard-drafts capture's failure code as the ledger declares it

check:error-code-casing (Lint & Repo Gates) flagged the handwritten
conformance capture's code: 'item_locked' — an invented lowercase spelling.
The producer propagates deleteMetaItem's refusal code verbatim, and the
protection path sets 'ITEM_LOCKED' (ledger-declared, error-code-ledger.zod.ts
ADR-0010 §3.3), so the capture now carries the code the route really answers.
Gate and the conformance suite re-run green.

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

* merge origin/main (os-regen artifacts taken from main; regeneration follows)

* spec: regenerate the merged tree's artifacts (regen-merge sync after #12849)

os-regen-merge.sh step 4: gen:migration-registry rebuilds registry.ts with
BOTH step-18 populations (#12849's ui-form-view-predicate-features-root-refused
semantic entry beside this PR's retirement + semantic entries), the retirement's
manifest and authorable-surface deletions are re-applied over main's side (the
merge takes main's copy of os-regen artifacts by design; the #4725/#4650 proofs
re-verify against the new base), and the full chain regenerates green:
check:generated 14/14, check:llms-txt 208 schemas, the five touched spec
suites, client typecheck and the resolver + unwrap pin suites all pass on the
merged tree.

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

---------

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

Author: os-sales

.changeset/sdk-response-contracts-bound.md

@@ -0,0 +1,72 @@
+---
+"@objectstack/spec": minor
+"@objectstack/client": minor
+"@objectstack/runtime": patch
+"@objectstack/rest": patch
+---
+
+feat(spec,client): bind published response contracts for the 17 unbound client-SDK methods; retire the false `PackageRollbackResponseSchema` (#12038, ruling 1C · 2C · 3A · 4A · 5A)
+
+<!-- adr-0087: registered package-rollback-response-retired -->
+
+**BREAKING** export removal, landing after the v17.0.0 cut (the lockstep
+launch-window convention ships it as `minor`; the prescription is registered
+under protocol major 18 — `RETIRED_DEFS_BY_MAJOR[18]` `api/PackageRollbackResponse`
+plus the D3 semantic entry `package-rollback-response-retired` — where
+`os migrate meta` users will look).
+
+FROM → TO:
+
+- `PackageRollbackResponseSchema` / `PackageRollbackResponse` /
+  `PackageRollbackResponseParsed` → `RollbackToPackageCommitResponseSchema` /
+  `RollbackToPackageCommitResponse` (`@objectstack/spec/api`). The retired
+  schema declared a VERSION rollback (`{ success, restoredVersion?,
+  message? }`) while the live `POST /packages/:id/rollback` route posts
+  `{ commitId }` and answers the ADR-0067 COMMIT rollback —
+  `{ success, revertedCommits: string[], failed: [{ commitId, error }] }`.
+  Read `revertedCommits` / `failed`; there is no `restoredVersion`.
+- `PackageApiContracts.rollbackPackage` → *(removed)* — it bound the
+  wrong-operation schema to the exact live path. No route registration or
+  SDK generation ever consumed it (zero consumers measured across
+  objectstack, objectui and cloud; only its own unit test and the #11925
+  compile-time guard, both updated in this PR).
+
+One-line fix: replace any import of `PackageRollbackResponse(Schema)` with
+`RollbackToPackageCommitResponse(Schema)` and read `revertedCommits` /
+`failed` instead of `restoredVersion`. `PackageRollbackRequestSchema` stays
+published (ruled out of the retirement), bound to no route.
+
+The rest of the change is additive — the recorded five-part maintainer
+ruling (2026-08-27) for the 17 client-SDK methods that had no published
+response contract:
+
+- **12 describe-only transcriptions** into `@objectstack/spec/api`, each
+  from the return type its producer already declares inline (no wire byte
+  changes): `ListDraftsResponseSchema`, `GetMetaDiagnosticsResponseSchema`,
+  `FindReferencesToMetaResponseSchema`, `RollbackMetaItemResponseSchema`,
+  `DiffMetaItemResponseSchema`, `ResolvedBookSchema` (authored beside its
+  interfaces in `system/book.zod.ts`), `DiscardPackageDraftsResponseSchema`,
+  `ListPackageCommitsResponseSchema` (the `{ commits }` wrapper declared as
+  the handler's own), `RevertPackageCommitResponseSchema`,
+  `RollbackToPackageCommitResponseSchema`,
+  `ReassignOrphanedMetadataResponseSchema`, `DuplicatePackageResponseSchema`.
+- **Ruling 1C**: `GetPublishedMetaItemResponseSchema` is deliberately opaque
+  (`z.unknown()`) — the route answers an arbitrary metadata item body, never
+  a union frozen against the type registry.
+- **Ruling 2C**: `meta.migrateStored` stays UNBOUND, documented at its two
+  ledger rows and in the SDK — `StoredMigrationReport` lives in
+  `@objectstack/metadata-protocol`, and a second declaration would drift.
+- **Ruling 4A**: `PackageExportManifestSchema` pins the four fixed keys
+  (`id`, `name`, `version`, `label?`) and stays honestly open for the
+  registry-derived plural keys.
+- **Ruling 5A**: `PackagePublishResultSchema` and the `ResolvedBook` family
+  are re-exported into `@objectstack/spec/api` (the namespace the
+  route-ledger resolver searches) — never a second copy.
+- The 18 boundable route-ledger rows in `@objectstack/runtime` and
+  `@objectstack/rest` now name their `responseSchema`, each stating which
+  surface's envelope it describes; every named schema carries conformance
+  coverage (the #3877 rule).
+- The client SDK binds 16 of the 17 methods to the published payload types,
+  replaces four invented test mocks with producer-true shapes, and pins the
+  `unwrapResponse` mis-unwrap hazard so no bound payload can declare both a
+  boolean `success` and a `data` key.

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

@@ -127,7 +127,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 29 schemas)
+## API Protocol (17 of 31 schemas)
 
 REST endpoints, real-time subscriptions, and discovery.
 

content/docs/references/api/index.mdx

@@ -22,8 +22,10 @@ This section contains all protocol schemas for the api layer of ObjectStack.
   <Card href="/docs/references/api/export" title="Export" description="Source: packages/spec/src/api/export.zod.ts" />
   <Card href="/docs/references/api/http-cache" title="Http Cache" description="Source: packages/spec/src/api/http-cache.zod.ts" />
   <Card href="/docs/references/api/metadata" title="Metadata" description="Source: packages/spec/src/api/metadata.zod.ts" />
+  <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-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" />
   <Card href="/docs/references/api/query-adapter" title="Query Adapter" description="Source: packages/spec/src/api/query-adapter.zod.ts" />

content/docs/references/api/meta.json

@@ -33,6 +33,8 @@
     "storage",
     "---More---",
     "error-code-ledger",
+    "misc",
+    "package-lifecycle",
     "sortability"
   ]
 }

content/docs/references/api/misc.mdx

@@ -0,0 +1,82 @@
+---
+title: Misc
+description: Misc protocol schemas
+---
+
+{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
+
+## TypeScript Usage
+
+```typescript
+import { ResolvedBookSchema, ResolvedEntrySchema, ResolvedGroupSchema } from '@objectstack/spec/api';
+import type { ResolvedBook, ResolvedEntry, ResolvedGroup } from '@objectstack/spec/api';
+
+// Validate data
+const result = ResolvedBookSchema.parse(data);
+```
+
+---
+
+## ResolvedBook
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **name** | `string` | ✅ | The book's machine name. |
+| **label** | `string` | optional | The book's display label, when it declares one. |
+| **groups** | `{ key: string; label: string; entries: object[] }[]` | ✅ | The resolved groups, in render order. |
+
+### Nested Shape: `ResolvedBook.groups[number]`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **key** | `string` | ✅ | The group's key (from the spine, or `uncategorized`). |
+| **label** | `string` | ✅ | The group's display label. |
+| **entries** | `{ doc?: string; href?: string; label?: string; description?: string; … }[]` | ✅ | The group's resolved entries, in render order. |
+
+
+---
+
+## ResolvedEntry
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **doc** | `string` | optional | Doc name, or undefined for an external link / separator. |
+| **href** | `string` | optional | External link target, when the entry is a link. |
+| **label** | `string` | optional | Display label, when one resolved. |
+| **description** | `string` | optional | Doc description, when one resolved. |
+| **badge** | `string` | optional | Badge text (e.g. "beta"), when declared. |
+| **icon** | `string` | optional | Icon name, when declared. |
+| **separator** | `boolean` | optional | True for a `---` separator node. |
+
+
+---
+
+## ResolvedGroup
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **key** | `string` | ✅ | The group's key (from the spine, or `uncategorized`). |
+| **label** | `string` | ✅ | The group's display label. |
+| **entries** | `{ doc?: string; href?: string; label?: string; description?: string; … }[]` | ✅ | The group's resolved entries, in render order. |
+
+### Nested Shape: `ResolvedGroup.entries[number]`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **doc** | `string` | optional | Doc name, or undefined for an external link / separator. |
+| **href** | `string` | optional | External link target, when the entry is a link. |
+| **label** | `string` | optional | Display label, when one resolved. |
+| **description** | `string` | optional | Doc description, when one resolved. |
+| **badge** | `string` | optional | Badge text (e.g. "beta"), when declared. |
+| **icon** | `string` | optional | Icon name, when declared. |
+| **separator** | `boolean` | optional | True for a `---` separator node. |
+
+
+---
+

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

@@ -28,8 +28,8 @@ DELETE /api/v1/packages/:packageId           — Uninstall a package
 ## TypeScript Usage
 
 ```typescript
-import { GetInstalledPackageRequestSchema, GetInstalledPackageResponseSchema, ListInstalledPackagesRequestSchema, ListInstalledPackagesResponseSchema, PackageApiErrorCode, PackageInstallRequestSchema, PackageInstallResponseSchema, PackagePathParamsSchema, PackageRollbackRequestSchema, PackageRollbackResponseSchema, PackageUpgradeRequestSchema, PackageUpgradeResponseSchema, ResolveDependenciesRequestSchema, ResolveDependenciesResponseSchema, UninstallPackageApiRequestSchema, UninstallPackageApiResponseSchema, UploadArtifactRequestSchema, UploadArtifactResponseSchema } from '@objectstack/spec/api';
-import type { GetInstalledPackageRequest, GetInstalledPackageResponse, ListInstalledPackagesRequest, ListInstalledPackagesResponse, PackageApiErrorCode, PackageInstallRequest, PackageInstallResponse, PackagePathParams, PackageRollbackRequest, PackageRollbackResponse, PackageUpgradeRequest, PackageUpgradeResponse, ResolveDependenciesRequest, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api';
+import { GetInstalledPackageRequestSchema, GetInstalledPackageResponseSchema, ListInstalledPackagesRequestSchema, ListInstalledPackagesResponseSchema, PackageApiErrorCode, PackageInstallRequestSchema, PackageInstallResponseSchema, PackagePathParamsSchema, PackageRollbackRequestSchema, PackageUpgradeRequestSchema, PackageUpgradeResponseSchema, ResolveDependenciesRequestSchema, ResolveDependenciesResponseSchema, UninstallPackageApiRequestSchema, UninstallPackageApiResponseSchema, UploadArtifactRequestSchema, UploadArtifactResponseSchema } from '@objectstack/spec/api';
+import type { GetInstalledPackageRequest, GetInstalledPackageResponse, ListInstalledPackagesRequest, ListInstalledPackagesResponse, PackageApiErrorCode, PackageInstallRequest, PackageInstallResponse, PackagePathParams, PackageRollbackRequest, PackageUpgradeRequest, PackageUpgradeResponse, ResolveDependenciesRequest, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api';
 
 // Validate data
 const result = GetInstalledPackageRequestSchema.parse(data);
@@ -287,43 +287,6 @@ Rollback package request
 | **rollbackCustomizations** | `boolean` | optional (default: `true`) | Whether to restore pre-upgrade customizations |
 
 
----
-
-## PackageRollbackResponse
-
-Rollback package response
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **success** | `boolean` | ✅ | Operation success status |
-| **error** | `{ code: Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| …>; declaredCode?: string; message: string; userMessage?: string; … }` | optional | Error details if success is false |
-| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
-| **data** | `{ success: boolean; restoredVersion?: string; message?: string }` | ✅ |  |
-
-### Nested Shape: `PackageRollbackResponse.error`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| …>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
-| **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112, #9106) |
-| **message** | `string` | ✅ | Readable error message |
-| **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim (#9934). Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution (#3821) for anything unmarked. Status-agnostic; never replaces `message`. |
-| **category** | `string` | optional | Error category (e.g. validation, authorization) |
-| **httpStatus** | `integer` | optional | HTTP status of the response carrying this error |
-| **details** | `any` | optional | Additional error context (e.g. field validation errors) |
-| **requestId** | `string` | optional | Request ID for tracking |
-
-### Nested Shape: `PackageRollbackResponse.data`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **success** | `boolean` | ✅ | Whether the rollback succeeded |
-| **restoredVersion** | `string` | optional | Restored version |
-| **message** | `string` | optional | Rollback status message |
-
-
 ---
 
 ## PackageUpgradeRequest