feat(client): bind erased SDK return types to their spec contracts (#11929)

* feat(client): bind erased SDK return types to their spec contracts

`packages/client/src/index.ts` dropped the precise contract types at the SDK
boundary on a package that already depends on `@objectstack/spec`, so the types
were reachable and the `any` was forced by nothing.

Four spellings of the same erasure, all measured at head and all bound here:
32 `Promise<any>`, 5 `Promise<any[]>`, 4 `Promise<{ …any[]… }>`, and 14
fixed-shape `<T = any>` methods (8 on `ObjectStackClient`, 6 mirrored on
`ScopedProjectClient`) — 55 sites, of which 51 are bound and 4 are deliberate.

Each binding is the DECLARED return of the service method the route calls,
verified per method against the handler's emit rather than swept: four
federation methods are envelope-wrapped (`{ tables }`, not `RemoteTable[]`),
`security.explain` takes the `z.input` form its contract declares because no
parse runs on that path, and `search` has a same-named wrong type
(`SearchResult`) sitting one import away.

The fixed-shape generics become `<T extends X = X>`, not `<T = X>`: the default
alone closes the erasure only for an unannotated call, because TypeScript infers
`T` from the assignment's contextual type. Measured on the pin file.

`automation.create` / `automation.update` / `search` / `data.clone` keep
`Promise<any>` with a docblock each — they are missing CONTRACTS, not missing
annotations, and authoring one lands in `packages/spec`.

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

* docs(api): repair the two client-sdk fences this narrowing falsifies

`content/docs/api/client-sdk.mdx` carries an UNMARKED ```typescript fence (no
`<!-- os:check -->`), so `check:skill-examples` never compiled it and CI could
not have caught this. Measured by extracting the fence verbatim into the
package's own test tsc program and diffing diagnostics with
`packages/client/src/index.ts` at this branch vs at origin/main: exactly two
diagnostics are INTRODUCED by the narrowing, both TS2345.

  1. `run.runId` -> `resume(flowName: string, runId: string)`.
     `AutomationResult.runId` is optional — a completed run carries none — so
     the argument is `string | undefined`. Narrowed with `&& run.runId`.
  2. `suggestions[0].id` -> `confirm(id: string)`.
     `AudienceBindingSuggestion` is `Record<string, unknown>` by contract, so
     the property reads as `unknown`. Wrapped in `String(...)`.

Both edits carry a one-line explanation, because each is the migration an
external consumer has to make and the page's job is to teach it.

Re-measured after the fix: 0 introduced diagnostics. Five diagnostics remain in
BOTH states (four `err is of type unknown` in the catch block, one unused local)
— pre-existing artifacts of compiling a doc snippet under strict settings it was
never written for, identical before and after, and not touched here.

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

---------

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

Author: claude[bot]

.changeset/client-precise-sdk-return-types.md

@@ -0,0 +1,56 @@
+---
+'@objectstack/client': minor
+---
+
+Bind the SDK's erased return types to the `@objectstack/spec` contracts the package already depends on
+
+**This is a NARROWING of published return types.** 41 methods that resolved to `any` (or to an
+envelope carrying an `any[]`) now resolve to the contract type the route actually answers, and 12
+fixed-shape `automation.*` methods gain a constrained generic in place of `<T = any>`. Nothing
+changes at runtime — no request, response, unwrapping or error path is touched — but code that
+compiles today against these methods can stop compiling. `any` is assignable to everything and
+admits every property read, so the previous declaration accepted assignments, property reads and
+parameter forwarding that a precise type refuses.
+
+What a consumer could stop compiling against, per family:
+
+- **`automation`** — `get`/`getFlow` are `FlowParsed`; `runs.get`/`getRun` are `ExecutionLog`;
+  `runs.list`/`listRuns` are `{ runs: ExecutionLog[]; hasMore: boolean }`; `execute` and `resume`
+  are `AutomationResult`; `getScreen` is `{ runId: string; screen: ScreenSpec }`; `listActions` and
+  `listConnectors` carry `ActionDescriptor[]` / `ConnectorDescriptor[]` instead of `any[]`. ⚠️ The
+  biggest practical break is `AutomationResult.screen`, `.runId`, `.status` and `.summary` being
+  **optional**: a completed run carries no screen, so `result.screen.nodeId` must become
+  `result.screen?.nodeId`. The six flat aliases and their `ScopedProjectClient` mirrors move
+  together. ⚠️ `<T = any>` became `<T extends X = X>` on those twelve: an explicit type argument
+  still works when it narrows the platform shape (`getFlow<FlowParsed & { name: 'onboarding' }>`),
+  but one naming an unrelated type is now refused — including where TypeScript used to infer it
+  from the assignment's own annotation.
+- **`approvals`** — `recall` / `revise` / `resubmit` are `ApprovalRecallResult` /
+  `ApprovalSendBackResult` / `ApprovalResubmitResult`; `remind` is
+  `{ request: ApprovalRequestRow; notified: number }`; `requestInfo` and `comment` are
+  `{ request: ApprovalRequestRow }`. These join `reassign` and `listActions`, which were already
+  typed this way beside them.
+- **`shares` / `shareLinks`** — `shares.list` is `RecordShare[]`, `shares.grant` is `RecordShare`;
+  `shares.rules.list` / `save` / `get` are `SharingRuleRow`(`[]`) and `rules.evaluate` is
+  `SharingRuleEvaluationResult`; `shareLinks.create` / `list` are `ShareLink`(`[]`).
+- **`reports`** — `list` / `save` / `get` are `SavedReport`(`[]`), `run` is `ReportRunResult`,
+  `schedule` / `listSchedules` are `ReportSchedule`(`[]`).
+- **`security`** — `describeDelegableScope` is `DelegableScope`; `explain` is `ExplainDecision` (the
+  `z.input` form `ISecurityService.explain` declares and the route relays verbatim — **not** the
+  post-parse `ExplainDecisionParsed`, since no parse runs on that path); the three
+  `suggestedBindings` methods carry their `{ suggestion, … }` / `{ suggestions, synced }` envelopes.
+  The suggestion ROW stays `Record<string, unknown>` by contract, but `bindingCreated` and
+  `synced.{created,confirmedObserved,pruned}` stop being erased.
+- **`email` / `datasources.external`** — `email.send` is `SendEmailResult` (branch on `status`).
+  ⚠️ The four federation methods are **envelope-wrapped** and the obvious binding is the wrong one:
+  `listTables` answers `{ tables: RemoteTable[] }`, not `RemoteTable[]`; likewise
+  `{ draft: ObjectDraft }`, `{ object: ImportObjectResult }`, `{ catalog: ExternalCatalog }`.
+  `validate` is a bare `SchemaValidationReport`.
+- **`ScopedProjectClient.packages.list`** — `{ packages: InstalledPackage[]; total: number }`.
+
+Four methods deliberately keep `Promise<any>` and say so in their docblocks: `automation.create` /
+`automation.update` echo an unvalidated request body, and `search` / `data.clone` answer shapes
+declared inline in the implementation rather than in `@objectstack/spec`. Those are missing
+*contracts*, not missing annotations, and authoring them belongs to the spec package. The
+caller-supplied generics on `data.*` and `actions.*` are unchanged — there the payload really is
+the caller's.

content/docs/api/client-sdk.mdx

@@ -400,7 +400,9 @@ try {
 // `{ status: 'paused', runId, screen }`; render the screen, then resume the run
 // with the collected values. A wizard pauses again for each further step.
 const run = await client.automation.execute('convert_lead', { params: { recordId } });
-if (run.status === 'paused') {
+// `execute` returns `AutomationResult`, on which `runId` and `screen` are
+// OPTIONAL — a run that COMPLETED carries neither — so narrow before resuming.
+if (run.status === 'paused' && run.runId) {
   await client.automation.resume('convert_lead', run.runId, {
     inputs: { account_name: 'Radium Labs' },
   });
@@ -438,7 +440,10 @@ await client.shareLinks.revoke(link.token);
 
 // Security (admin) — resolve package audience-binding suggestions (ADR-0090)
 const { suggestions } = await client.security.suggestedBindings.list({ status: 'pending' });
-await client.security.suggestedBindings.confirm(suggestions[0].id);
+// A suggestion ROW is deliberately open (`Record<string, unknown>`) — its column
+// set belongs to the backing object, not the contract. Read the fields you know
+// (`id`, `status`, `package_id`) and narrow them at the point of use.
+await client.security.suggestedBindings.confirm(String(suggestions[0].id));
 
 // Storage — File upload and management
 await client.storage.upload(fileData, 'user');

packages/client/src/client.test.ts

@@ -1351,7 +1351,12 @@ describe('ObjectStackClient.automation', () => {
 
         const result = await client.automation.resume('my_flow', 'run_1', { inputs: { account_id: 'a1' } });
         expect(result.status).toBe('paused');
-        expect(result.screen.nodeId).toBe('step2');
+        // [#8140] `resume` now declares `AutomationResult`, on which `screen`
+        // is optional — a run that COMPLETED carries none. Asserting its
+        // presence before reading through it is the consumer-side half of that
+        // narrowing, and is exactly the migration an external caller makes.
+        expect(result.screen).toBeDefined();
+        expect(result.screen?.nodeId).toBe('step2');
     });
 
     // [#8684] BREAKING: a run that resumed and then FAILED used to resolve with