fix(client): bind the five in-repo return res.json() methods erased to Promise< any >, and measure the 38 third-party ones (#13082)

* fix(client): bind the five in-repo `return res.json()` methods erased to `Promise< any >`

The sixth erasure spelling: no return annotation and `return res.json()`, whose
published type comes from `lib.dom`'s `Response.json(): Promise< any >`. The
method text names neither `any` nor `Promise` nor `unwrapResponse`, so it is
invisible to every grep the earlier censuses used.

Binds the five whose producers live in this repo, so the true type is
measurable by DRIVING them rather than reading source or asserting a mock:

  analytics.query       -> BaseResponse & { data: AnalyticsResult }
  analytics.meta        -> AnalyticsMetadataResponse
  analytics.explain     -> AnalyticsSqlResponse
  automation.trigger    -> BaseResponse & { data: AutomationResult }
  analytics.queryDataset-> AnalyticsResult (REST-served, no envelope)

`unwrapResponse` strips the `{ success, data }` envelope; `res.json()` does not,
so four of the five resolve to the envelope and the fifth — mounted only by
@objectstack/rest, which ends `res.json(result)` — to the bare payload.

Two spec response types that LOOK like the right binding are narrower than the
contract their route relays (`AnalyticsResultResponseSchema.data.fields` and
`TriggerFlowResponseSchema.data`); binding either would have shipped a false
narrowing, so both annotations bind the producer's contract instead and the
near-miss is pinned.

Deletes exactly the five matching entries from the shrink-only ledger, in the
same commit as the fix, and adds the two halves the pair needs: a driven wire
test and the type-level pins a runtime test cannot express.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UjujZN219uFzBhSYfMykCd

* gate follow-through: resolve the three driven producers from SOURCE, and answer ADR-0087

`check:test-source-alias` and `check:type-source-resolution` both refuse a new
workspace import that resolves through `dist/`, and the driven wire test added
three. Aliased in `vitest.config.ts` and pathed in `tsconfig.json`, one anchored
bare-name rule each. The reason is stronger here than the general one: that
suite's claim is "the annotation matches what the producer sends", so against a
stale `dist` it would certify a declaration that is already false.

The changeset declares BREAKING, so `check-adr-0087-registration` requires the
ledger question answered in writing: `not-required (no-migration-prescription)`
— nothing metadata-shaped moves, so there is no tombstone and nothing for
`objectstack migrate meta` to rewrite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UjujZN219uFzBhSYfMykCd

* changeset: state the SDK narrowing in the disposition its three siblings use

#8140 / #11925 / #12034 are the same class — a published `@objectstack/client`
return-type narrowing with no metadata surface behind it — and all three record
the no-ADR-0087-entry disposition as prose rather than as a `**BREAKING**`
declaration, which in this repo is the token that routes a change at the
metadata migration ledger. The consumer impact is stated in full (FROM/TO per
method, and the exact reads that stop compiling); what is dropped is a token
that would have claimed a ledger relevance this change does not have.

Recorded on the PR: the ADR-0087 gate has no honest disposition for a published
TYPE-surface narrowing that carries a consumer source-edit prescription and no
metadata migration — filed separately.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UjujZN219uFzBhSYfMykCd

---------

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

Author: os-litant

.changeset/client-json-erasure-in-repo-families.md

@@ -0,0 +1,72 @@
+---
+"@objectstack/client": minor
+---
+
+fix(client): bind the five in-repo `return res.json()` methods, whose published type was `Promise< any >` (part of #12104)
+
+**Return-type narrowing on a published SDK (clause-②).** No runtime change: the
+value each method resolves to is byte-identical before and after. Only the
+DECLARED type moved, off `any` — which is exactly why a runtime test cannot
+observe it and the pins for it are type-level.
+
+> ⓘ Angle brackets are spaced throughout (`Promise< any >`) on purpose —
+> GitHub's body sanitizer strips tag-shaped spans, backticks and fenced code
+> included.
+
+Each of the five carried no return annotation and ended `return res.json()`, so
+its published type was `Promise< any >`, inherited from `lib.dom`'s
+`Response.json(): Promise< any >`. The method text names neither `any` nor
+`Promise` nor `unwrapResponse`, which is why the class was invisible to the
+greps two earlier censuses used.
+
+## What each method declares now
+
+| method | declared before | declares now | why |
+|---|---|---|---|
+| `client.analytics.query` | `any` | `BaseResponse & { data: AnalyticsResult }` | dispatcher-served; `deps.success(v)` wraps and `res.json()` strips nothing |
+| `client.analytics.meta` | `any` | `AnalyticsMetadataResponse` | same envelope; `data` is the bare `CubeMeta[]` projection |
+| `client.analytics.explain` | `any` | `AnalyticsSqlResponse` | same envelope; `data` is `{ sql, params }` |
+| `client.automation.trigger` | `any` | `BaseResponse & { data: AutomationResult }` | same envelope, over the payload its sibling `automation.execute` unwraps |
+| `client.analytics.queryDataset` | `any` | `AnalyticsResult` | served by `@objectstack/rest`, which ends `res.json(result)` — no envelope |
+
+`any` is assignable to everything and admits every property read, so a
+consumer's code can stop compiling where it previously did not. Concretely:
+
+- **Reading a payload key off one of the four ENVELOPED results.**
+  `(await client.analytics.query(q)).rows` compiled and was `undefined` at
+  runtime; the read the wire always required is `.data.rows`. Same for
+  `.data` on `meta` / `explain`, and `.data.runId` / `.data.screen` on
+  `automation.trigger`.
+- **Reading `.data` off `queryDataset`**, which is served bare — likewise
+  `undefined` today, likewise refused now.
+- Assigning any of the five results to an unrelated annotation, or forwarding
+  one to a differently-typed parameter.
+
+That break is the point: those call sites are already wrong at runtime 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.
+
+## How the shapes were established
+
+By DRIVING the real producers — a real `AnalyticsService`, a real
+`AutomationEngine`, the real `HttpDispatcher` and the real `RestServer`, with
+only the socket stood in for — not by reading source and not by asserting
+against a mock. Two spec response types that look like the right binding are
+NARROWER than the contract their route relays
+(`AnalyticsResultResponseSchema.data.fields` and
+`TriggerFlowResponseSchema.data`), so those two annotations bind the producer's
+contract instead; the near-miss is pinned so a later sweep cannot retarget them.
+
+## Scope
+
+The five families whose producers live in this repo. The 38 better-auth-backed
+`auth.*` / `organizations.*` / `oauth.*` methods of the same class are untouched
+and keep their erased `any` — they are exactly as permissive as before, and no
+consumer loses anything by that.
+
+No ADR-0087 ledger entry: nothing here is a metadata surface. No Zod schema, no
+`packages/spec` declaration and no stored representation changed — the erasure
+lived only in a TypeScript return annotation — so `objectstack migrate meta` has
+nothing to rewrite and an entry would have no artifact to project into. This is
+the disposition #8140, #11925 and #12034 recorded for the same class of SDK
+return-type narrowing.

packages/client/exported-any-returns.json

@@ -2,10 +2,6 @@
   "$comment": "Exported callables of @objectstack/client whose AWAITED return type resolves to `any` (#11927). Judged against the BUILT dist by `pnpm --filter @objectstack/client check:exported-any-returns`, because the erasure is invisible in source text when a method carries no return annotation. SHRINK-ONLY and EXACT in both directions: a site here that no longer resolves to `any` is RED until its entry is deleted, and a site NOT here that resolves to `any` is RED — that unlisted case is the everyday one and the reason this file exists. There is deliberately NO --update flag: every entry is debt with a name on it, and a reason a tool wrote is a silencer rather than a worklist. SCOPE, and the one exclusion worth stating out loud: a return type that CONTAINS `any` (`{ packages: any[]; total: number }`, `Promise<Record<string, any>>`) is not listed, because it is not flagged — the gate asks whether the type IS `any`, the same line packages/spec's check:exported-any draws, and admitting the broader question costs the gate its zero-false-positive property. That is why 21 of #11925's 38 unannotated methods are absent here: they are `any`-CONTAINING, and they remain #11925's to close. Nothing is silently absorbed in either direction. A caller-supplied `<T = any>` is likewise never listed: the record type and the action payload really are the caller's, and flagging them is the pressure that turns a correct generic into a wrong concrete type.",
   "entries": {
     "ObjectStackClient.meta.migrateStored": "#11925 — no return annotation; the published type comes from `this.unwrapResponse<any>(res)`. Invisible to a `Promise<` grep because the text never appears in the method. Bind the contract the route actually answers, minding the envelope.",
-    "ObjectStackClient.analytics.query": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
-    "ObjectStackClient.analytics.meta": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
-    "ObjectStackClient.analytics.explain": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
-    "ObjectStackClient.analytics.queryDataset": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
     "ObjectStackClient.organizations.create": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
     "ObjectStackClient.organizations.update": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
     "ObjectStackClient.organizations.setActive": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
@@ -45,7 +41,6 @@
     "ObjectStackClient.auth.twoFactor.disable": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
     "ObjectStackClient.auth.twoFactor.verifyBackupCode": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
     "ObjectStackClient.auth.accounts.unlink": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
-    "ObjectStackClient.automation.trigger": "#12104 — no return annotation; `return res.json()`, and lib.dom declares `Response.json(): Promise<any>`. Invisible to every grep #8140's census and #11925 used: the method names neither `any` nor `Promise` nor `unwrapResponse`. Bind the contract the route actually answers, minding the envelope.",
     "ObjectStackClient.automation.create": "#11924 — DELIBERATE `Promise<any>`: `POST /automation` ends `deps.success(body)`, echoing the caller's own unvalidated bytes, and `IAutomationService.registerFlow` returns nothing, so the service contract has no return shape to relay. This needs a DECISION (keep echoing, or answer the registered `FlowParsed`), not an annotation.",
     "ObjectStackClient.automation.update": "#11924 — DELIBERATE `Promise<any>`: `PUT /automation/:name` ends `deps.success(definition)` where `definition = body.definition ?? body`. Same missing contract as `automation.create`, and the two should be answered together since they are one route class."
   }

packages/client/package.json

@@ -33,7 +33,10 @@
     "@objectstack/metadata-protocol": "workspace:*",
     "@objectstack/objectql": "workspace:*",
     "@objectstack/plugin-hono-server": "workspace:*",
+    "@objectstack/rest": "workspace:*",
     "@objectstack/runtime": "workspace:*",
+    "@objectstack/service-analytics": "workspace:*",
+    "@objectstack/service-automation": "workspace:*",
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"