diff --git a/‎.changeset/17536-client-packages-read-doors-either-stage.md‎
Lines changed: 23 additions & 3 deletions b/‎.changeset/17536-client-packages-read-doors-either-stage.md‎
Lines changed: 23 additions & 3 deletions
diff --git a/‎packages/client/src/index.ts‎
Lines changed: 49 additions & 13 deletions b/‎packages/client/src/index.ts‎
Lines changed: 49 additions & 13 deletions
diff --git a/‎packages/client/src/return-type-precision.test.ts‎
Lines changed: 59 additions & 20 deletions b/‎packages/client/src/return-type-precision.test.ts‎
Lines changed: 59 additions & 20 deletions
@@ -12,11 +12,31 @@ Clause-②: yes
 
 `packages/spec` is the one contract between producers and consumers, and `packages/client` is a consumer of it, so the consumer's declaration is what moves. All four now declare `InstalledPackageAtEitherStage` from `@objectstack/spec/api`.
 
-**What the union is, and what it is not.** It is a union of two whole, closed stages — `InstalledPackageSchema` and `AssembledInstalledPackageSchema` — that differ in exactly one key, `manifest`. Every other member of the row (`id`, `name`, `version`, `status`, `enabled`, `installedAt`, …) is common to both branches and reads exactly as it did. A row belonging to neither stage is refused by both branches and therefore by the declaration; ⛔ this is not a tolerant shape and must never be relaxed into one.
+**What the union is.** It is a union over the two manifest stages — `InstalledPackageSchema` and `AssembledInstalledPackageSchema` — which differ in exactly one key, `manifest`. Every other member of the row (`id`, `name`, `version`, `status`, `enabled`, `installedAt`, …) is common to both branches and reads exactly as it did, so code that reads only those members needs no change at all.
 
-**What a consumer does.** Code that reads only the common members needs no change at all. Code that reaches INTO `manifest` separates the two stages first, because the authoring stage's `objects` are GLOB STRINGS while the assembled stage's are object DEFINITIONS — the compiler now says so at the call site instead of letting a glob-shaped read compile against a row that carries definitions. In this repository the whole consumer cost is zero sites outside `packages/client` itself: no other workspace package calls either read member.
+**Where the RUNTIME and the TYPE disagree, measured at this head.** The runtime schema is the strict half: `InstalledPackageAtEitherStageSchema.safeParse(row)` answers `success: false` for a row whose `manifest` belongs to neither stage — measured on a `{ bogus: 1, objects: 'not-even-an-array' }` manifest and on an empty `{}` one. The published TYPE is NOT that strict: on the assembled branch `manifest` is declared `Record<string, unknown>`, so both of those same rows COMPILE against the declared return type. ⛔ Do not read this widening as a type-level guarantee about `manifest` — the guarantee is the parse's. The type-level tolerance is a known gap, tracked as **#19324**; its root cause is the deliberate `z.ZodType<Record<string, unknown>, …>` annotation at `packages/spec/src/stack.zod.ts:1283` (#14513 — TS7056 and a declaration-chunk ceiling), and it is ⛔ not this change's to fix. It is recorded as a pin in `packages/client/src/return-type-precision.test.ts`, which reddens the day the gap closes.
 
-**The three WRITE members did not move** and stay declared at the authoring stage. `install` / `enable` / `disable` answer the row their own request contract produced — `PackageInstallRequestSchema` declares `manifest: ManifestSchema` — and PR #17517 moved the read doors alone. That asymmetry is the measurement, not an oversight, and it is pinned.
+**What a consumer does, concretely.** A member read off `manifest` on the union arrives as `unknown` (measured: `pkg.manifest.objects` is `unknown`). ⇒ a caller that reaches INTO `manifest` narrows by PARSING the row with a `packages/spec` schema and reading the parse's output:
+
+```ts
+import { AssembledInstalledPackageSchema } from '@objectstack/spec/api';
+import { InstalledPackageSchema } from '@objectstack/spec/kernel';
+
+const row = await client.packages.get(id);
+const parsed = AssembledInstalledPackageSchema.safeParse(row);
+if (parsed.success) {
+  // parsed.data.manifest — the ASSEMBLED stage, object definitions
+} else {
+  const authoring = InstalledPackageSchema.parse(row);
+  // authoring.manifest.objects — the AUTHORING stage, glob strings
+}
+```
+
+⛔ Do NOT narrow with `Array.isArray(pkg.manifest.objects)`, or with any other structural guess. It separates the stages on NEITHER level: at the type level `pkg.manifest` is the same union inside both branches of that `if`, and at runtime BOTH stages' `objects` are arrays — `z.array(z.string())` at the authoring stage against `z.array(ObjectSchema)` at the assembled one. (Measured: a row carrying no `objects` at all parses as either stage, which is the right answer for it — the key such a guess would read is not there.)
+
+In this repository the whole consumer cost is zero sites outside `packages/client` itself: no other workspace package calls either read member.
+
+**The WRITE members did not move** and stay declared at the authoring stage — all four of them: `install`, `enable`, `disable`, `update` still answer `Promise<InstalledPackage>`. `install` answers the row its own request contract produced (`PackageInstallRequestSchema` declares `manifest: ManifestSchema`), and PR #17517 moved the read doors alone. That asymmetry is the measurement, not an oversight, and it is pinned.
 
 The type is reached the same way `InstalledPackage` always was, from `@objectstack/spec` rather than re-exported here: this SDK has never re-exported the package row, and this change does not start.
 
 
@@ -127,12 +127,15 @@ import {
   // `ListInstalledPackagesResponseSchema.packages` is
   // `z.array(InstalledPackageAtEitherStageSchema)` and
   // `GetInstalledPackageResponseSchema.data` is that same schema
-  // (`spec/src/api/package-api.zod.ts`) — a union of the two CLOSED manifest
-  // stages, authoring (`InstalledPackageSchema`) and assembled
-  // (`AssembledInstalledPackageSchema`), never a tolerant shape. The client is a
-  // CONSUMER of that contract, so the widest value those doors are declared to
-  // answer is what they are declared to return here. The WRITE methods on the
-  // same object keep `InstalledPackage`: PR #17517 moved the read doors alone.
+  // (`spec/src/api/package-api.zod.ts`) — a union over the two manifest stages,
+  // authoring (`InstalledPackageSchema`) and assembled
+  // (`AssembledInstalledPackageSchema`), each a closed RUNTIME declaration. The
+  // client is a CONSUMER of that contract, so the widest value those doors are
+  // declared to answer is what they are declared to return here. ⚠️ What the
+  // published TYPE admits is wider than what the runtime parse accepts — the
+  // measurement, and what a caller does about it, are on `packages.list` below
+  // (#19324). The WRITE methods on the same object keep `InstalledPackage`:
+  // PR #17517 moved the read doors alone.
   InstalledPackageAtEitherStage,
 } from '@objectstack/spec/api';
 import type {
@@ -2477,13 +2480,46 @@ export class ObjectStackClient {
      * (Prime Directive #12), so the consumer's declaration is what moves.
      *
      * ⚠️ Clause-② widening, and what it costs a caller: the element is a union
-     * of two whole stages that differ in ONE key, `manifest`. Every other member
-     * of the row — `id`, `name`, `version`, `status`, `enabled`, … — is common
-     * to both branches and reads exactly as before. A caller that reaches INTO
-     * `manifest` separates the stages first (`Array.isArray(pkg.manifest.objects)
-     * ? … : …`, or a `packages/spec` parse), because the authoring stage's
-     * `objects` are GLOB STRINGS and the assembled stage's are object
-     * DEFINITIONS. No runtime behaviour changes; the values were always these.
+     * of two stages that differ in ONE key, `manifest`. Every other member of
+     * the row — `id`, `name`, `version`, `status`, `enabled`, … — is common to
+     * both branches and reads exactly as before, so a caller that reads only
+     * those members needs no change at all. No runtime behaviour changes; the
+     * values were always these.
+     *
+     * ⚠️ Reaching INTO `manifest` is where the cost is, and the TYPE will not
+     * do the narrowing for you. On the assembled branch `manifest` is declared
+     * `Record<string, unknown>`, so a member read off the union —
+     * `pkg.manifest.objects` — is `unknown` (measured with `tsc` against the
+     * published declarations, not inferred from the schemas). Narrow by PARSING
+     * the row with a `packages/spec` schema and reading the parse's output:
+     *
+     * ```ts
+     * const parsed = AssembledInstalledPackageSchema.safeParse(pkg); // spec/api
+     * if (parsed.success) {
+     *   // parsed.data.manifest — the ASSEMBLED stage, object definitions
+     * } else {
+     *   const authoring = InstalledPackageSchema.parse(pkg);         // spec/kernel
+     *   // authoring.manifest.objects — the AUTHORING stage, glob strings
+     * }
+     * ```
+     *
+     * ⛔ Do NOT narrow with `Array.isArray(pkg.manifest.objects)`, or with any
+     * other structural guess. It separates the stages on NEITHER level: at the
+     * type level `pkg.manifest` is the same union inside both branches of that
+     * `if`, and at runtime BOTH stages' `objects` are arrays —
+     * `z.array(z.string())` at the authoring stage against `z.array(ObjectSchema)`
+     * at the assembled one. (Measured: a row carrying no `objects` at all parses
+     * as either stage, which is the right answer for it — the key such a guess
+     * would read is not there.)
+     *
+     * ⚠️ The RUNTIME half is the strict one, and the asymmetry is a KNOWN GAP
+     * rather than a design: `InstalledPackageAtEitherStageSchema.safeParse()`
+     * refuses a `manifest` belonging to neither stage, while that same row
+     * COMPILES against this declaration. Tracked as #19324, whose root cause is
+     * the deliberate `z.ZodType<Record<string, unknown>, …>` annotation at
+     * `packages/spec/src/stack.zod.ts:1283` (#14513 — TS7056 and a
+     * declaration-chunk ceiling); ⛔ not something this declaration can fix, and
+     * ⛔ not a licence to relax either runtime branch to match the type.
      */
     list: async (filters?: { status?: string; type?: string; enabled?: boolean }): Promise<{ packages: InstalledPackageAtEitherStage[]; total: number }> => {
         const route = this.getRoute('packages');
 
@@ -591,13 +591,15 @@ export async function returnTypePrecisionPins12034(): Promise<void> {
     // `withWritableVerdict(qlService, toPackageResponse(pkg))`, so this pin and
     // the element type on `list` are two readings of one producer.
     //
-    // ⚠️ [#17536] Which is why these two READ members moved and the three WRITE
-    // members above did not. One producer expression serves `list` and `get`, and
-    // PR #17517 declared what it serves — `InstalledPackageAtEitherStageSchema`
-    // — on both read doors. The install / enable / disable members answer the row
-    // their own request contract produced (`PackageInstallRequestSchema` declares
-    // `manifest: ManifestSchema`, the AUTHORING stage), so their declaration is
-    // unchanged and this asymmetry is the measurement, not an oversight.
+    // ⚠️ [#17536] Which is why these two READ members moved and the WRITE
+    // members above did not — all four of them (`install`, `enable`, `disable`,
+    // `update`) still answer `Promise<InstalledPackage>`. One producer expression
+    // serves `list` and `get`, and PR #17517 declared what it serves —
+    // `InstalledPackageAtEitherStageSchema` — on both read doors. The install
+    // member answers the row its own request contract produced
+    // (`PackageInstallRequestSchema` declares `manifest: ManifestSchema`, the
+    // AUTHORING stage), so its declaration is unchanged and this asymmetry is the
+    // measurement, not an oversight.
     expectTypeOf(await client.packages.get('com.acme.crm'))
         .toEqualTypeOf<InstalledPackageAtEitherStage>();
     expectTypeOf(await scoped.packages.get('com.acme.crm'))
@@ -676,17 +678,28 @@ declare const assembledRow: AssembledInstalledPackage;
  *
  * Direction 1 asserts the declared return now ADMITS an assembled-stage row.
  * That assertion is only evidence if an assembled row was REFUSED before, so the
- * refusal is pinned in the same breath: the three WRITE members did not move,
+ * refusal is pinned in the same breath: the four WRITE members did not move,
  * and the `@ts-expect-error` on `install` below is exactly the assignment
  * direction 1 makes. If `AssembledInstalledPackage` were assignable to
  * `InstalledPackage` after all, that suppression would go UNUSED and tsc would
  * report TS2578 — so the pair fails loudly instead of passing vacuously.
  *
- * Direction 2 asserts what the widening did NOT buy. The door's element is a
- * union of two CLOSED stages, never a tolerant shape, and a `manifest` belonging
- * to neither is refused by both branches. That suppression is what reddens if
- * anyone ever "widens" these members to `any` / `unknown` / an open shape to
- * make a payload fit.
+ * Direction 2 asserts what the widening did NOT buy, and it is narrower than it
+ * looks: the suppressed assignment gives `manifest` a STRING PRIMITIVE, which
+ * both branches of the union refuse, so the suppression is USED. That is the
+ * line that reddens (TS2578, unused directive) if these members are ever
+ * "widened" to `any` / `unknown` to make a payload fit.
+ *
+ * ⛔ It does NOT measure object-shaped tolerance, and at this head there is
+ * some: on the assembled branch `manifest` is declared `Record<string, unknown>`
+ * (the deliberate annotation at `packages/spec/src/stack.zod.ts:1283`, #14513),
+ * so an object `manifest` belonging to NEITHER stage compiles against these
+ * members. The runtime is the half that is correct —
+ * `InstalledPackageAtEitherStageSchema.safeParse()` refuses that same row, and
+ * that refusal is pinned beside its producer in
+ * `packages/runtime/src/domains/packages-read-delete-response-conformance.test.ts`.
+ * The type-level gap is #19324's to close; the third pin below records it as the
+ * behaviour it is, so the day it closes this file says so.
  *
  * ## Ablation, measured rather than asserted
  *
@@ -727,30 +740,56 @@ export function installedPackageEitherStagePins17536(): void {
     // @ts-expect-error the install door answers the AUTHORING stage; an assembled row is not one
     const installRefusesAssembled: Awaited<ReturnType<typeof client.packages.install>> = assembledRow;
 
-    // ── direction 2: two closed stages, not a tolerant shape ─────────────────
-    // GREEN IN BOTH STATES — the second control. A `manifest` belonging to
-    // NEITHER stage is refused by both branches of the union, so it is refused by
-    // the declaration. This is the line that reddens
-    // (TS2578, unused suppression) if these members are ever widened to `any`,
-    // `unknown`, or an open shape.
+    // ── direction 2: a manifest that is not an OBJECT AT ALL is refused ─────
+    // GREEN IN BOTH STATES — the second control, and this is the whole of what
+    // it measures: a STRING PRIMITIVE is refused by both branches of the union,
+    // so the suppression is USED. It reddens (TS2578, unused suppression) if
+    // these members are ever widened to `any` or `unknown`. ⛔ It says nothing
+    // about an object-shaped `manifest` belonging to neither stage — that one
+    // compiles today, and is pinned as such directly below.
     //
     // ⚠️ The suppression sits on the PROPERTY, not on the `const`. Measured: tsc
     // reports this mismatch at the offending member of the object literal, so a
     // directive on the declaration line covers the wrong line and goes unused —
     // TS2578, a red gate that says nothing about the union.
     const neitherStage: Awaited<ReturnType<typeof client.packages.get>> = {
         ...authoringRow,
-        // @ts-expect-error neither manifest stage admits a string; the union is over two closed stages
+        // @ts-expect-error a manifest must at least be an object; neither branch of the union admits a string
         manifest: 'com.acme.crm@1.0.0',
     };
 
+    // ── the KNOWN GAP, pinned as the behaviour it IS (#19324) ─────────────
+    // ⛔ NOT a guarantee — a measurement, written down so it cannot change in
+    // silence. `AssembledInstalledPackage['manifest']` is
+    // `Record<string, unknown>` (from the deliberate
+    // `z.ZodType<Record<string, unknown>, …>` annotation at
+    // `packages/spec/src/stack.zod.ts:1283`, #14513 — TS7056 and a
+    // declaration-chunk ceiling), so the assembled branch admits ANY object and
+    // the assignment below COMPILES at this head. Measured with `tsc` against the
+    // published declarations; the runtime disagrees and is the correct half:
+    // `InstalledPackageAtEitherStageSchema.safeParse()` answers `success: false`
+    // for this very row.
+    //
+    // ⚠️ There is deliberately no `@ts-expect-error` here. The day #19324 types
+    // the assembled body, tsc reds on THIS line — and that red is the
+    // notification this pin exists to deliver: read it as "the gap closed", then
+    // delete this block and tighten the `manifest` guidance on
+    // `ObjectStackClient.packages.list` in `index.ts`, which sends callers
+    // through a `packages/spec` parse precisely because the type cannot carry
+    // the narrowing today.
+    const objectToleranceGap19324: Awaited<ReturnType<typeof client.packages.get>> = {
+        ...authoringRow,
+        manifest: { bogus: 1, objects: 'not-even-an-array' },
+    };
+
     void getAdmitsAssembled;
     void scopedGetAdmitsAssembled;
     void listAdmitsAssembled;
     void scopedListAdmitsAssembled;
     void getStillAdmitsAuthoring;
     void installRefusesAssembled;
     void neitherStage;
+    void objectToleranceGap19324;
 }
 
 /**