fix(client): packages.install/enable/disable declare the bare row the only serving surface sends (#13060)

`client.packages.install`, `.enable` and `.disable` declared
`{ package: any; message?: string }` — a body no surface has ever emitted.
Each is served by exactly one implementation (`runtime`'s `/packages`
dispatcher domain; the REST registrar mounts no twin for any of the three)
and it answers `success(pkg)`, which `unwrapResponse` strips to the bare
`InstalledPackage` row. Because the member was `any`,
`(await client.packages.enable(id)).package` compiled and was `undefined` at
runtime; the `any` is what kept the falsehood invisible.

All three now declare `InstalledPackage`. `message` goes with the wrapper —
no surface sends one.

`client.packages.get` is deliberately untouched: it is a real fork (the
dispatcher answers the bare row, the REST registrar answers
`{ package: { ...row, source } }`), so no declaration is true on both
surfaces. Converging the two producers is a wire-behaviour ruling above this
change; the measured cost is recorded on the issue.

Two pins, because neither half can observe the other: the WIRE fact is driven
end-to-end against a real `SchemaRegistry` + real `HttpDispatcher` + real
client in `packages-write-envelope.test.ts`, and the DECLARATION is pinned
type-level in `return-type-precision.test.ts`.


Claude-Session: https://claude.ai/code/session_01UjujZN219uFzBhSYfMykCd

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

Author: os-litant

.changeset/client-packages-write-verbs-bare-row.md

@@ -0,0 +1,61 @@
+---
+"@objectstack/client": minor
+---
+
+fix(client): `packages.install` / `enable` / `disable` declare the bare `InstalledPackage` row the only serving surface actually sends (#12034)
+
+**Accept-set narrowing on a published SDK (clause-②), and a false declaration
+deleted.** No runtime change: the value each method resolves to is
+byte-identical before and after. What moved is the DECLARED type — and unlike
+its #11925 siblings this one was not merely erased, it was **wrong**.
+
+FROM → TO, all three methods:
+
+| method | declared before | declares now |
+|---|---|---|
+| `client.packages.install(manifest, opts?)` | `{ package: any; message?: string }` | `InstalledPackage` |
+| `client.packages.enable(id)` | `{ package: any; message?: string }` | `InstalledPackage` |
+| `client.packages.disable(id)` | `{ package: any; message?: string }` | `InstalledPackage` |
+
+No surface has ever emitted `{ package, message }` for these three. Each is
+served by exactly one implementation — `runtime`'s `/packages` dispatcher domain
+— and it answers `success(pkg)`, i.e. `{ success: true, data: <row> }`, which
+`unwrapResponse` strips to the bare row. `@objectstack/rest`'s registrar mounts
+no twin for any of them (it mounts only `POST /packages/publish`,
+`GET /packages`, `GET /packages/:id`, `DELETE /packages/:id`), so there was
+never a question of which surface to match.
+
+**Migration — read the row, not `.package`.** Because the member was `any`,
+the false read compiled and silently produced `undefined` at runtime:
+
+```ts
+// BEFORE — compiled, and `pkg` was `undefined` at runtime
+const pkg = (await client.packages.enable(id)).package;
+const note = (await client.packages.install(manifest)).message;
+
+// AFTER — the response IS the row
+const pkg = await client.packages.enable(id);
+pkg.enabled;          // the state the verb just changed
+pkg.manifest.version;
+```
+
+A consumer stops compiling where it reads `.package` or `.message` off these
+three results, or assigns the result somewhere `InstalledPackage` does not fit.
+That break is the point: those call sites are already broken at runtime today
+and the `any` is what hid it. The compiler is the channel that reaches every
+affected consumer, and it is strictly more precise than a release note.
+
+**What deliberately did NOT change: `client.packages.get`.** It keeps
+`{ package: any }`. That route is a real fork — the dispatcher answers the bare
+row while the REST registrar answers `{ package: { ...row, source } }`, both
+measured by driving each registrar — so no declaration is true on both surfaces.
+Binding either member would harden a falsehood, which is the defect this change
+removes for its neighbours. Making `get` bindable requires converging the two
+PRODUCERS, a wire-behaviour change to two mounted surfaces; the measured
+convergence cost is recorded on #12034 for that ruling.
+
+No ADR-0087 ledger entry: nothing here is a metadata surface. No Zod schema, no
+`packages/spec` declaration and no stored representation changed — the phantom
+members existed only in a TypeScript return annotation — so `objectstack migrate
+meta` has nothing to rewrite. This is the disposition #11925 and #8140 recorded
+for the same class of SDK return-type narrowing.

packages/client/src/client.test.ts

@@ -2509,9 +2509,15 @@ describe('HTTP error shaping — envelope normalisation', () => {
 
 describe('packages.install', () => {
     const MANIFEST = { id: 'com.acme.crm', name: 'Acme CRM', version: '1.0.0', type: 'app' };
+    // [#12034] The body the ONLY serving surface actually sends: `success(pkg)`,
+    // i.e. the bare `InstalledPackage` row under `data`. These two cases assert
+    // the REQUEST and never read the response, so the fixture is inert either
+    // way — but it used to spell `data: { package: … }`, a body nothing emits,
+    // and a decoy fixture is how the next sweep concludes the envelope is real.
+    const INSTALLED_ROW = { manifest: MANIFEST, status: 'installed', enabled: true };
 
     it('POSTs the manifest and omits `overwrite` unless requested', async () => {
-        const { client, fetchMock } = createMockClient({ success: true, data: { package: { manifest: MANIFEST } } });
+        const { client, fetchMock } = createMockClient({ success: true, data: INSTALLED_ROW });
         await client.packages.install(MANIFEST, { enableOnInstall: true });
 
         expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/packages', expect.any(Object));
@@ -2524,7 +2530,7 @@ describe('packages.install', () => {
     });
 
     it('passes `overwrite: true` through for intentional upgrade / re-install', async () => {
-        const { client, fetchMock } = createMockClient({ success: true, data: { package: { manifest: MANIFEST } } });
+        const { client, fetchMock } = createMockClient({ success: true, data: INSTALLED_ROW });
         await client.packages.install(MANIFEST, { overwrite: true });
 
         const body = JSON.parse(fetchMock.mock.calls[0][1].body);

packages/client/src/index.ts

@@ -1673,14 +1673,25 @@ export class ObjectStackClient {
     /**
      * Get a specific installed package by its ID (reverse domain identifier).
      *
-     * ⛔ [#11925] NOT bound, and the `{ package }` envelope is left exactly as
-     * it was — the two mounted surfaces answer this route with DIFFERENT
-     * envelopes, so no single declaration is true (#12034). `runtime`'s
-     * `/packages` domain sends `success(pkg)` — the bare row — while `rest`'s
-     * `GET {base}/packages/:id` sends `sendOk(res, { package: { ...pkg,
-     * source } })`, and the REST routes "shadow live dispatcher twins" only
-     * where a `package` service is registered. Binding the member here would
-     * harden a claim that is already false on one of the two.
+     * ⛔ [#11925 / #12034] STILL NOT bound, and the `{ package }` envelope is
+     * left exactly as it was. #12034 shipped its `install` / `enable` /
+     * `disable` neighbours (one producer each) and deliberately did NOT ship
+     * this one, because this route is a REAL fork with no single true type.
+     * Both bodies below were MEASURED by driving each registrar, not read off
+     * the source:
+     *
+     *     dispatcher  handlePackages('/<id>', 'GET')
+     *       -> { success: true, data: { id, manifest, enabled, status } }
+     *     rest        GET /api/v1/packages/:id
+     *       -> { success: true, data: { package: { …row, source } } }
+     *
+     * `unwrapResponse` strips one envelope, so the post-unwrap value is the
+     * BARE row on the dispatcher and `{ package }` on REST. Binding either
+     * member here hardens a claim that is false on the other surface. Making
+     * it bindable means converging the two PRODUCERS — a wire-behaviour change
+     * to two mounted surfaces, above this card's authority, with a clause-②
+     * narrowing analysis of its own. The measured convergence cost is recorded
+     * on #12034 for that ruling.
      *
      * Its SCOPED twin `ScopedEnvironmentClient.packages.get` IS bound, because
      * only the REST registrar serves the scoped mount — one surface, one
@@ -1695,14 +1706,25 @@ export class ObjectStackClient {
     /**
      * Install a new package from its manifest.
      *
-     * ⛔ [#11925] NOT bound. This method and its `enable` / `disable`
-     * neighbours declare `{ package; message? }`, and the ONLY surface that
-     * serves them — `runtime`'s `/packages` domain; `rest` mounts no twin for
-     * any of the three — answers `success(pkg)`, the bare row (#12034). The
-     * declared envelope is not merely erased, it is false, and the `any`
-     * member is what keeps that invisible. Correcting it is a response-shape
-     * decision with its own clause-② analysis, not the `any`-binding this card
-     * carries, so the shape is left untouched here.
+     * [#12034] Bound to `InstalledPackage` — the BARE row, no envelope.
+     *
+     * What this REPLACED was not an erasure but a FALSEHOOD: the declaration
+     * read `{ package: any; message?: string }`, a shape no surface has ever
+     * sent, and the `any` member is what kept that invisible —
+     * `(await client.packages.install(m)).package` compiled and was
+     * `undefined` at runtime. There is exactly ONE serving surface, so there
+     * was never a "which surface do we match" question: `rest`'s registrar
+     * mounts only `POST /packages/publish`, `GET /packages`,
+     * `GET /packages/:id` and `DELETE /packages/:id` (measured by driving
+     * `registerPackageRoutes` and enumerating what it mounted — this route is
+     * `NO_HANDLER` there), leaving `runtime`'s `/packages` domain alone to
+     * answer, and it answers `success(pkg)`: `{ success: true, data: <row> }`,
+     * status 201. `message` is gone with the wrapper — no surface sends one.
+     *
+     * The wire fact is pinned end-to-end in
+     * `packages-write-envelope.test.ts` (the real dispatcher answering a real
+     * client call), and the DECLARATION in `return-type-precision.test.ts` —
+     * a runtime test cannot observe a return-type narrowing at all.
      *
      * By default the server rejects a manifest whose `id` is already
      * installed with **409 Conflict** (duplicate-id guard) instead of
@@ -1712,7 +1734,7 @@ export class ObjectStackClient {
     install: async (
         manifest: any,
         options?: { settings?: Record<string, any>; enableOnInstall?: boolean; overwrite?: boolean },
-    ) => {
+    ): Promise<InstalledPackage> => {
         const route = this.getRoute('packages');
         const res = await this.fetch(`${this.baseUrl}${route}`, {
             method: 'POST',
@@ -1723,7 +1745,7 @@ export class ObjectStackClient {
                 ...(options?.overwrite !== undefined ? { overwrite: options.overwrite } : {}),
             }),
         });
-        return this.unwrapResponse<{ package: any; message?: string }>(res);
+        return this.unwrapResponse<InstalledPackage>(res);
     },
 
     /**
@@ -1739,24 +1761,38 @@ export class ObjectStackClient {
 
     /**
      * Enable a disabled package.
-     */
-    enable: async (id: string) => {
+     *
+     * [#12034] Bound to `InstalledPackage` — the BARE row, no envelope, for
+     * the reason spelled out on `install` above: one serving surface
+     * (`PATCH /packages/:id/enable` is `NO_HANDLER` on the REST registrar),
+     * and it answers `success(registry.enablePackage(id))`. The
+     * `{ package: any; message?: string }` this replaces was never emitted by
+     * anything.
+     */
+    enable: async (id: string): Promise<InstalledPackage> => {
         const route = this.getRoute('packages');
         const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}/enable`, {
             method: 'PATCH',
         });
-        return this.unwrapResponse<{ package: any; message?: string }>(res);
+        return this.unwrapResponse<InstalledPackage>(res);
     },
 
     /**
      * Disable an installed package.
-     */
-    disable: async (id: string) => {
+     *
+     * [#12034] Bound to `InstalledPackage` — the BARE row, no envelope, same
+     * single-producer argument as `install` / `enable` above
+     * (`PATCH /packages/:id/disable` is `NO_HANDLER` on the REST registrar).
+     * The dispatcher answers `success(registry.disablePackage(id))`, so the
+     * row comes back with `enabled: false` — the caller reads the row itself,
+     * never a `.package` member.
+     */
+    disable: async (id: string): Promise<InstalledPackage> => {
         const route = this.getRoute('packages');
         const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}/disable`, {
             method: 'PATCH',
         });
-        return this.unwrapResponse<{ package: any; message?: string }>(res);
+        return this.unwrapResponse<InstalledPackage>(res);
     },
 
     /* [#3563 PR-4] Lifecycle beyond install/enable — these eleven routes