@salesforce/platform-sdk 11.69.2 → 11.70.0

package/dist/core/data.d.ts

@@ -105,6 +105,8 @@ export type QuerySubscriber<T> = (snapshot: QuerySnapshot<T>) => void;
  * @remarks
  * On uncached surfaces (Mosaic, OpenAI), `subscribe` only emits in response
  * to `refresh()` — there is no cache to push background updates.
+ *
+ * @see docs/data/03-reactive-handle-lifecycle.md
  */
 export interface QueryResult<T> extends QuerySnapshot<T> {
     subscribe(cb: QuerySubscriber<T>): Unsubscribe;
@@ -127,6 +129,8 @@ export interface QueryResult<T> extends QuerySnapshot<T> {
  * `subscribe` / `refresh` (mutating a side effect on subscription is incoherent;
  * re-running it on refresh is dangerous). Stale-after-mutation is handled by
  * the caller holding query result references and calling `result.refresh()`.
+ *
+ * @see docs/data/03-reactive-handle-lifecycle.md
  */
 export interface MutationResult<T> {
     data: T | undefined;
@@ -140,6 +144,8 @@ export interface MutationResult<T> {
  *   Follows HTTP RFC 7234 `no-cache` semantics.
  * - `"only-if-cached"` — return the cached entry without a network call.
  *   Returns an error if no entry exists for this query + variables.
+ *
+ * @see docs/data/02-caching-and-freshness.md
  */
 export type CacheControlShorthand = "no-cache" | "only-if-cached";
 /**
@@ -149,6 +155,8 @@ export type CacheControlShorthand = "no-cache" | "only-if-cached";
  * - `maxAge: 0` — entry is written but immediately considered stale
  *   (always re-fetches, similar to `"no-cache"` but writes a 0s TTL).
  * - Invalid values (NaN, Infinity, negative) fall back to the 300s default.
+ *
+ * @see docs/data/02-caching-and-freshness.md
  */
 export interface CacheControlMaxAge {
     type: "max-age";
@@ -169,10 +177,14 @@ export interface CacheControlMaxAge {
  *
  * When omitted, the default `max-age` strategy with a 300-second TTL applies.
  * After the TTL expires, the next call fetches fresh data from the network.
+ *
+ * @see docs/data/02-caching-and-freshness.md
  */
 export type CacheControl = CacheControlShorthand | CacheControlMaxAge;
 /**
  * Options bag for {@link DataSDKGraphQL.query}.
+ *
+ * @see docs/data/02-caching-and-freshness.md
  */
 export interface QueryOptions<V = Record<string, unknown>> {
     query: GraphQLRawDocument;
@@ -197,6 +209,8 @@ export interface QueryOptions<V = Record<string, unknown>> {
 }
 /**
  * Options bag for {@link DataSDKGraphQL.mutate}.
+ *
+ * @see docs/data/02-caching-and-freshness.md
  */
 export interface MutateOptions<V = Record<string, unknown>> {
     mutation: GraphQLRawDocument;
@@ -214,6 +228,8 @@ export interface MutateOptions<V = Record<string, unknown>> {
  * Queries are reactive (cached on surfaces that cache, subscribable on every
  * surface); mutations are request/response. Each method's return shape
  * matches its semantics — no fakes, no noops.
+ *
+ * @see docs/data/04-surfaces-and-guards.md
  */
 export interface DataSDKGraphQL {
     /**
@@ -302,6 +318,8 @@ export interface DataSDKGraphQL {
  *
  * May be a bare `{}` on unsupported surfaces — feature-detect `graphql` or
  * `fetch` before use to avoid runtime errors.
+ *
+ * @see docs/data/04-surfaces-and-guards.md
  */
 export interface DataSDK {
     /** GraphQL namespace. Present when the surface supports data operations. */

package/dist/core/data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../src/core/data.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../src/core/data.ts"],"names":[],"mappings":"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"}

package/dist/data/gql.d.ts

@@ -18,6 +18,8 @@
  *
  * const query = gql`query { account { name } }`;
  * ```
+ *
+ * @see docs/data/01-grounding-and-precedence.md
  */
 export declare function gql(strings: TemplateStringsArray, ...values: unknown[]): string;
 //# sourceMappingURL=gql.d.ts.map

package/dist/data/gql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gql.d.ts","sourceRoot":"","sources":["../../src/data/gql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAM/E"}
+{"version":3,"file":"gql.d.ts","sourceRoot":"","sources":["../../src/data/gql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAM/E"}

package/dist/data/index.d.ts

@@ -3,10 +3,15 @@ import { MosaicDataSDKOptions } from './mosaic';
 /**
  * A callback the host invokes for a given HTTP status (see {@link WebAppDataSDKOptions.onStatus}).
  * May be sync or async.
+ *
+ * @see docs/data/04-surfaces-and-guards.md
  */
 export type StatusCallback = () => Promise<unknown> | void;
 /**
- * Options for creating a WebAppDataSDK
+ * Options for the WebApp surface — the browser-hosted, cached surface. Passed
+ * as `DataSDKOptions.webapp`.
+ *
+ * @see docs/data/04-surfaces-and-guards.md
  */
 export interface WebAppDataSDKOptions {
     /**
@@ -52,7 +57,10 @@ export declare const defineDataExtension: <const Name extends string, Api>(exten
  */
 export type DataSDKWithExtensions<Extensions extends ExtensionsFor<DataSDK>> = ExtendedSDK<DataSDK, Extensions>;
 /**
- * Options for creating a DataSDK instance.
+ * Options for creating a DataSDK instance — surface selection plus the
+ * per-surface option bags (`webapp`, `mosaic`) and any `plugins`.
+ *
+ * @see docs/data/04-surfaces-and-guards.md
  */
 export interface DataSDKOptions extends SDKOptions {
     /**
@@ -116,6 +124,8 @@ export interface DataSDKOptions extends SDKOptions {
  *   console.log(result.data);
  * }
  * ```
+ *
+ * @see docs/data/01-grounding-and-precedence.md
  */
 export declare function createDataSDK<const Extensions extends ExtensionsFor<DataSDK> = []>(options?: Omit<DataSDKOptions, "extensions"> & {
     extensions?: Extensions;
@@ -127,6 +137,8 @@ export type { CacheControl, DataSDK, DataSDKGraphQL, GraphQLError, GraphQLRawDoc
  * `{ edges: [{ node }] }` connection. Resolves to `never` when `T` is not such a connection.
  *
  * @typeParam T - The connection type to unwrap.
+ *
+ * @see docs/data/04-surfaces-and-guards.md
  */
 export type NodeOfConnection<T> = T extends {
     edges?: (infer E)[] | null;

package/dist/data/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACX,OAAO,EACP,WAAW,EACX,SAAS,EACT,aAAa,EACb,UAAU,EACV,oBAAoB,EACpB,eAAe,EACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAKpE;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IACnD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,GAAG,GAAG,OAAO,IAAI,SAAS,CACpF,OAAO,EACP,IAAI,EACJ,GAAG,CACH,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,+IAAoC,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,CAAC,UAAU,SAAS,aAAa,CAAC,OAAO,CAAC,IAAI,WAAW,CACzF,OAAO,EACP,UAAU,CACV,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IACjD;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACpC;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAiBH,wBAAgB,aAAa,CAAC,KAAK,CAAC,UAAU,SAAS,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,EACjF,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,GAAG;IAC9C,UAAU,CAAC,EAAE,UAAU,CAAC;CACxB,GAAG,oBAAoB,CAAC,UAAU,CAAC,GACnC,eAAe,CAAC,UAAU,CAAC,GAC1B,OAAO,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC;AAe9C,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,YAAY,EACX,YAAY,EACZ,OAAO,EACP,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,WAAW,GACX,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS;IAC3C,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC;CAC3B,GAAG,IAAI,GACL,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,GAClC,CAAC,GACD,KAAK,GACN,KAAK,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACX,OAAO,EACP,WAAW,EACX,SAAS,EACT,aAAa,EACb,UAAU,EACV,oBAAoB,EACpB,eAAe,EACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAKpE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IACnD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,GAAG,GAAG,OAAO,IAAI,SAAS,CACpF,OAAO,EACP,IAAI,EACJ,GAAG,CACH,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,+IAAoC,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,CAAC,UAAU,SAAS,aAAa,CAAC,OAAO,CAAC,IAAI,WAAW,CACzF,OAAO,EACP,UAAU,CACV,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IACjD;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACpC;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAiBH,wBAAgB,aAAa,CAAC,KAAK,CAAC,UAAU,SAAS,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,EACjF,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,GAAG;IAC9C,UAAU,CAAC,EAAE,UAAU,CAAC;CACxB,GAAG,oBAAoB,CAAC,UAAU,CAAC,GACnC,eAAe,CAAC,UAAU,CAAC,GAC1B,OAAO,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC;AAe9C,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,YAAY,EACX,YAAY,EACZ,OAAO,EACP,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,WAAW,GACX,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS;IAC3C,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC;CAC3B,GAAG,IAAI,GACL,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,GAClC,CAAC,GACD,KAAK,GACN,KAAK,CAAC"}

package/dist/data/index.js

@@ -279,7 +279,7 @@ const v = "Accept-Language", we = (t) => {
     return l(t);
   const [r, n] = t;
   return (r instanceof Request && !n?.headers ? r.headers.has(v) : new Headers(n?.headers).has(v)) ? l(t) : l(b(v, e, t));
-}, Se = "X-SFDC-Client-Name", ge = "X-SFDC-Client-Version", ve = "@salesforce/platform-sdk", Ee = "11.69.2", Ce = (t) => {
+}, Se = "X-SFDC-Client-Name", ge = "X-SFDC-Client-Version", ve = "@salesforce/platform-sdk", Ee = "11.70.0", Ce = (t) => {
   let e = b(Se, ve, t);
   return e = b(ge, Ee, e), l(e);
 }, De = "X-CSRF-Token";

package/dist/data/mosaic/index.d.ts

@@ -1,6 +1,9 @@
 import { DataSDK, DataSDKGraphQL } from '../../core';
 /**
- * Options for creating a MosaicDataSDK
+ * Options for the Mosaic surface — the server-side (Node.js) surface. Auth is
+ * via access token and there is no cache. Passed as `DataSDKOptions.mosaic`.
+ *
+ * @see docs/data/04-surfaces-and-guards.md
  */
 export interface MosaicDataSDKOptions {
     /**

package/dist/data/mosaic/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/data/mosaic/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAmC,MAAM,YAAY,CAAC;AAe3F;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;gBAErB,OAAO,CAAC,EAAE,oBAAoB;YAa5B,iBAAiB;CAe/B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/data/mosaic/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAmC,MAAM,YAAY,CAAC;AAe3F;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;gBAErB,OAAO,CAAC,EAAE,oBAAoB;YAa5B,iBAAiB;CAe/B"}

package/docs/data/01-grounding-and-precedence.md

@@ -0,0 +1,84 @@
+<!-- sdk-symbols
+createDataSDK: dist/data/index.d.ts
+gql: dist/data/gql.d.ts
+DataSDK: dist/core/data.d.ts
+-->
+
+# Data access — grounding & precedence
+
+This folder is the **authored** half of the `@salesforce/platform-sdk` data-access contract. It
+ships **inside the installed package**, so it version-travels with the `.d.ts` you have on disk:
+the guidance you read here always matches the SDK version you installed, never a newer or older
+copy kept somewhere else.
+
+It is deliberately **thin**. The installed declarations own the call contract; these pages carry
+only the residue the types cannot express — strategy, negatives, lifecycle, and the migration
+story.
+
+## Two ways in — `.graphql` and `.fetch`
+
+`createDataSDK()` returns two data-access members, both surface-optional (feature-detect before use
+— see [04-surfaces-and-guards.md](./04-surfaces-and-guards.md)):
+
+- **`.graphql` — the primary route.** UIAPI-backed reads and mutations, cached and reactive on the
+  WebApp surface. Steer here first: anything the GraphQL schema can express should go through
+  `.graphql`. Pages [02](./02-caching-and-freshness.md)–[03](./03-reactive-handle-lifecycle.md)
+  are entirely about this route.
+- **`.fetch` — the escape hatch.** SDK-enriched authenticated HTTP (`typeof fetch`) for the
+  endpoints the GraphQL schema does not expose — REST (`/services/data/…`), Apex REST
+  (`/services/apexrest/…`), Connect, blob/file downloads. It carries the surface's auth, CSRF, and
+  header handling, and is **not** cached. On WebApp, `.graphql` is itself built on top of `.fetch`
+  — it is the primitive, not an afterthought.
+
+**Which door:** default to `.graphql`; reach for `.fetch` only when there is no GraphQL
+representation for what you need. These pages document the _mechanics_ of each — the `.fetch`
+contract, per-surface behaviour, and examples live in
+[04-surfaces-and-guards.md](./04-surfaces-and-guards.md). The authoritative
+`.graphql`-vs-`.fetch` **routing** decision (which endpoints belong on which door) stays with the
+`experience-ui-bundle-salesforce-data-access` skill, not here.
+
+## Precedence — read in this order, and let the earlier rung win
+
+1. **Tier-1 — the live GraphQL schema.** What fields/types actually exist for a `.graphql` query.
+   Not in this package. This rung grounds the `.graphql` door only — the `.fetch` door is grounded
+   by the contract of whatever REST/Apex endpoint you call, which this SDK does not own.
+2. **Tier-2a — the installed `.d.ts`.** The authoritative call contract: exports, `query`/`mutate`
+   signatures, options bags, result shapes, `CacheControl`, `NodeOfConnection`. Start here:
+   - `dist/core/data.d.ts` — the contract types (`DataSDK`, `DataSDKGraphQL`, `QueryResult`,
+     `CacheControl`, …).
+   - `dist/data/index.d.ts` — the entry points (`createDataSDK`, `gql`) and the surface options.
+3. **Tier-2b — these pages.** Only what the types can't carry. **If a page and the `.d.ts`
+   disagree, the `.d.ts` wins** — assume the prose has drifted and trust the declaration.
+4. **Skill spine — fallback.** The `experience-ui-bundle-salesforce-data-access` skill covers
+   routing, guardrails, and the tier-1 gate. It points _here_ for the SDK-usage detail rather
+   than restating it.
+
+## What lives where
+
+| The installed `.d.ts` owns                                     | These pages own                                                 |
+| -------------------------------------------------------------- | --------------------------------------------------------------- |
+| Signatures, options bags, result shapes, enums, default values | Strategy/decision tables, "do NOT reinvent it" negatives        |
+| `CacheControl` values & the default TTL                        | _When_ to reach for each cache policy, offline-first stance     |
+| The `QueryResult` shape                                        | Living with the reactive handle in a framework lifecycle        |
+| `DataSDK.fetch` (`typeof fetch`) — the raw call shape          | _When_ to reach for `.fetch` vs `.graphql`, and what it carries |
+| The current call contract                                      | The dead `@salesforce/sdk-data` → new-API migration story       |
+
+## Reading order
+
+- [02-caching-and-freshness.md](./02-caching-and-freshness.md) — the WebApp cache, the two refresh
+  tools, offline-first.
+- [03-reactive-handle-lifecycle.md](./03-reactive-handle-lifecycle.md) — living with
+  `QueryResult.subscribe`/`refresh`.
+- [04-surfaces-and-guards.md](./04-surfaces-and-guards.md) — the two data-access members,
+  `sdk.graphql!` vs guard, reading `errors`, the `.fetch` escape hatch, per-surface options.
+- [05-migration-from-sdk-data.md](./05-migration-from-sdk-data.md) — old callable API → new
+  namespace API.
+
+## Deep-path `.d.ts` are for reading, not importing
+
+A few pages cite declarations that live deep in the tree — e.g.
+`dist/data/shared/graphql/cache/command.d.ts`. Those are **raw file paths you may open to read**,
+**not import subpaths**. The only importable entries are the ones declared in the package's
+`exports` (`@salesforce/platform-sdk`, `@salesforce/platform-sdk/core`,
+`@salesforce/platform-sdk/data`, …). Never write
+`import … from "@salesforce/platform-sdk/data/shared/graphql/cache/command"` — it will not resolve.

package/docs/data/02-caching-and-freshness.md

@@ -0,0 +1,183 @@
+<!-- sdk-symbols
+CacheControl: dist/core/data.d.ts
+CacheControlMaxAge: dist/core/data.d.ts
+CacheControlShorthand: dist/core/data.d.ts
+QueryOptions: dist/core/data.d.ts
+MutateOptions: dist/core/data.d.ts
+DataSDKGraphQL: dist/core/data.d.ts
+HttpGraphQLResourceCacheControlCommand: dist/data/shared/graphql/cache/command.d.ts
+cacheBundleRegistry: dist/data/shared/graphql/cache/services.d.ts
+buildCacheServices: dist/data/shared/graphql/cache/services.d.ts
+-->
+
+# Caching & freshness
+
+> **Surface caveat up front:** everything about _caching_ here is the **WebApp surface**. On the
+> uncached surfaces (Mosaic, OpenAI) there is no cache — see
+> [Uncached surfaces](#uncached-surfaces-mosaic-openai) below and
+> [04-surfaces-and-guards.md](./04-surfaces-and-guards.md). The `query`/`mutate` shape is identical
+> on every surface, so call sites stay portable.
+
+The `CacheControl`, `CacheControlMaxAge`, and `DataSDKGraphQL` declarations in `dist/core/data.d.ts`
+own the supported values, the default TTL, and the hit/miss behaviour. Read them first; this page is
+strategy and negatives only.
+
+## Caching is ON by default (WebApp) — do NOT reinvent it
+
+Every `sdk.graphql!.query()` on WebApp is cached automatically. There is **no opt-in flag, no
+`createCachedClient` factory, and no `/cache` import subpath** — those do not exist in
+`@salesforce/platform-sdk`. There is also **no need for React Query, SWR, `localStorage`, or any
+hand-rolled memoization**. If you find yourself writing a cache, **stop** — it already exists.
+
+The default TTL and the max-age override are defined on `CacheControl` / `CacheControlMaxAge` in the
+`.d.ts`. Read the value there rather than hard-coding a number here — the declaration is the source
+of truth for the default.
+
+## What gets cached
+
+Only **successful responses with a non-empty `data` object** are written:
+
+- `data` is `null`, missing, or `{}` → **NOT cached**. An empty `data` usually means a transient
+  server condition; caching it would poison the entry for the full TTL.
+- Response carries a non-empty `errors` array → surfaced as an error and **NOT cached**.
+
+## Cache key
+
+The key is `stableJSONStringify({ query, variables, operationName })`, plus a `headers` field when
+the call passes per-request headers (see the `headers` bullet below). The derivation lives in
+`HttpGraphQLResourceCacheControlCommand` (`dist/data/shared/graphql/cache/command.d.ts` — a raw path
+to read, not an import). What matters at a call site:
+
+- **`cacheControl` does NOT affect the key.** The same query + variables share **one** entry no
+  matter what policy each call passes. A `"no-cache"` call and a default call read/write the _same_
+  slot.
+- The query is keyed by its **normalized, printed GraphQL document** — the WebApp path parses the
+  authored query into an AST and re-serializes it with `print()` before it reaches the cache key, so
+  whitespace-only differences between two calls do **not** produce separate entries. Two calls only
+  land in different entries if their parsed documents actually differ (selections, arguments,
+  fragments). Reuse the same `gql`-tagged constant anyway — it stays the single source of truth for
+  the operation, independent of cache-key mechanics.
+- Variables are deep-cloned at call time, so mutating your variables object afterward does not
+  desync the key from the request body. Variables must be JSON-serializable (circular refs / BigInt
+  throw a typed error).
+- **`headers` are part of the key** (see `QueryOptions.headers` in the `.d.ts`): two calls that
+  differ only in `headers` resolve to different entries, so a response scoped by an `Authorization`
+  header is never served to a caller that passed a different value.
+
+## Shared across SDK instances by host + API version
+
+Cache bundles are deduped in a module-level registry keyed by the resolved `baseUrl` **plus the
+API-version path** (`cacheBundleRegistry` / `buildCacheServices` in
+`dist/data/shared/graphql/cache/services.d.ts` — raw paths). **A query run through one
+`createDataSDK()` instance is a cache hit on another instance only if both the host and the
+`apiVersion` match.** Two instances targeting the same host but different `apiVersion` get fully
+isolated cache bundles — version isolation matters because the per-entry cache key does not carry
+the request URL, so sharing across versions would let one version read another's cached response.
+The per-instance fetch pipeline (CSRF, `onStatus`) stays **isolated** — a cache _miss_ routes through
+the calling SDK's own fetch. The registry is a plain module-level `Map`, so sharing only happens
+**within the current JavaScript realm** — it does not persist across page reloads and is not shared
+across browser tabs.
+
+**Practical implication:** you do **not** need to hoist `createDataSDK()` into a singleton purely to
+share cache. Calling it per-feature is fine as long as every instance resolves the same `baseUrl` +
+`apiVersion`; the cache is shared underneath. (A singleton is still reasonable for other reasons.)
+
+## The two refresh tools (keep them distinct)
+
+There are **two unrelated mechanisms** for getting fresh data. Do not conflate `result.refresh()` (a
+method on a live handle) with `cacheControl: "no-cache"` (a per-call option).
+
+|                     | **Reactive refresh**                                 | **Call-site cache control**                           |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| **API**             | `result.subscribe(cb)` + `result.refresh()`          | `cacheControl` on the query options bag               |
+| **Lifetime**        | Long-lived handle; persists until you unsubscribe    | One-shot, per call                                    |
+| **Pushes updates?** | Yes — `subscribe` fires on every subsequent snapshot | No — you read the returned value once                 |
+| **PR**              | #502                                                 | #537 (W-22514759)                                     |
+| **Use when**        | A mounted consumer should react / re-fetch on demand | "This specific read must bypass / only-use the cache" |
+
+The reactive handle's lifecycle (subscribe/unsubscribe, framework teardown) is
+[03-reactive-handle-lifecycle.md](./03-reactive-handle-lifecycle.md). This page covers `cacheControl`.
+
+### `cacheControl` — the per-call policy
+
+Values and mechanics are defined on `CacheControl` / `CacheControlShorthand` / `CacheControlMaxAge`
+in the `.d.ts`. Two behaviours worth stating that the declaration does not:
+
+- An **`only-if-cached` miss is not an exception.** The Promise resolves and the miss surfaces on
+  `result.errors`. This is offline-first: a miss is **expected, not an error** — when it genuinely is
+  a miss, render an empty state and **do not fall back to a network read** (a fallback defeats the
+  point of `only-if-cached`).
+
+  **A cache miss is discriminable; other failures are message-only.** `result.errors` is a flat
+  `GraphQLError[]` (`message`/`locations`/`path`/`extensions` — see `dist/core/data.d.ts`). A cache
+  miss on `only-if-cached` carries a typed discriminator — `extensions.code === "CACHE_MISS"` — so
+  you can identify it positively; every other SDK-synthesized failure sets no `code` and is told
+  apart by `message` text alone. Verified by executing every path (not just reading it — see
+  `error-shape-discriminators.spec.ts`):
+
+  | Failure                                   | `result.errors?.[0]`                                                             |
+  | ----------------------------------------- | -------------------------------------------------------------------------------- |
+  | Cache miss (`only-if-cached`, cold cache) | `{ message: "No cached entry found …", extensions: { code: "CACHE_MISS" } }`     |
+  | Wrong operation kind                      | `{ message: "…requires a GraphQL query, received <kind>." }`                     |
+  | Malformed GraphQL syntax                  | `{ message: "Syntax Error: …" }` (parser-generated)                              |
+  | Non-serializable variables                | `{ message: "…must be JSON-serializable. …" }`                                   |
+  | Network failure                           | `{ message: <the rejected fetch's Error.message, verbatim> }`                    |
+  | Server-returned GraphQL error             | Whatever the server sent (`message`, optionally `path`/`locations`/`extensions`) |
+
+  `only-if-cached` never touches the network, so an errored result with no data is by construction a
+  cache miss — platform-sdk synthesizes the typed `CACHE_MISS` error (see `invokeResourceGraphQL`)
+  rather than leaking the underlying transport's opaque empty-message 504. Because the miss is
+  discriminable, you can branch on it positively even at a call site that can also fail for other
+  reasons: check `extensions.code === "CACHE_MISS"` first, then route anything else through your
+  normal application error path. It's pinned by `error-shape-discriminators.spec.ts` — if that test
+  ever fails, this table is stale.
+
+  ```typescript
+  const result = await sdk.graphql!.query({
+    query: GET_ACCOUNTS,
+    variables,
+    cacheControl: "only-if-cached",
+  });
+  if (result.errors?.[0]?.extensions?.code === "CACHE_MISS") {
+    // Cold cache. Do NOT fall back to the network; that defeats offline-first.
+    return renderEmptyState();
+  }
+  if (result.errors?.length) {
+    // Any other failure (syntax, variables, network, server) — not a cache miss.
+    return handleQueryError(result.errors);
+  }
+  ```
+
+- `cacheControl` does **not** affect the cache key (see above) — it only chooses the read/write
+  policy for that one call.
+
+Mutations never touch the cache — `MutateOptions` has no `cacheControl`. To reflect a write, refresh
+a held query (see [Refresh after a mutation](./03-reactive-handle-lifecycle.md#refresh-after-a-mutation)).
+
+## Choosing a strategy
+
+| Goal                                                                       | Reach for                                                                                |
+| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Default reads, freshness within the default TTL is fine                    | Nothing — the default cache                                                              |
+| Mounted consumer should reflect cache updates / re-fetch on demand         | `subscribe` + `refresh` ([reactive handle lifecycle](./03-reactive-handle-lifecycle.md)) |
+| Re-fetch a held query after a mutation                                     | `result.refresh()` ([reactive handle lifecycle](./03-reactive-handle-lifecycle.md))      |
+| One-off "this read must be fresh" (button, post-mutation one-shot)         | `cacheControl: "no-cache"`                                                               |
+| Offline-first — render only cached data, tolerate a miss as an empty state | `cacheControl: "only-if-cached"`                                                         |
+| Data changes faster than the default TTL                                   | `cacheControl: { type: "max-age", maxAge: N }`                                           |
+
+`no-cache` and `refresh()` both bypass the cache and write back; the difference is **`refresh()`
+pushes to existing subscribers** and is a method on a live handle, while `no-cache` is a fresh
+one-shot call with no subscribers.
+
+## Uncached surfaces (Mosaic, OpenAI)
+
+- **No cache exists.** Every `query()` is a network request.
+- **`cacheControl` is silently ignored** — `"no-cache"`, `"only-if-cached"`, and `max-age` have no
+  effect. Notably `only-if-cached` will **not** raise `DataNotFoundError`, because there is no cache
+  layer to miss.
+- **`subscribe` is real but only emits in response to `refresh()`** — there is no background cache to
+  push updates, so `refresh()` is the sole source of new snapshots and each one costs a network
+  request. See [03-reactive-handle-lifecycle.md](./03-reactive-handle-lifecycle.md).
+- PR #502 flags the uncached `subscribe`/`refresh` edge semantics (re-emit-to-all, error fan-out,
+  ordering vs concurrent refresh) as a **known soft spot / follow-up**. Document conservatively; do
+  not over-promise behaviour there.

package/docs/data/03-reactive-handle-lifecycle.md

@@ -0,0 +1,84 @@
+<!-- sdk-symbols
+QueryResult: dist/core/data.d.ts
+QuerySnapshot: dist/core/data.d.ts
+QuerySubscriber: dist/core/data.d.ts
+Unsubscribe: dist/core/data.d.ts
+MutationResult: dist/core/data.d.ts
+-->
+
+# Living with the reactive query handle
+
+`sdk.graphql!.query()` resolves to a `QueryResult<T>` — a reactive handle, not a plain response.
+Its shape and core behaviour are owned by `QueryResult` / `QuerySnapshot` / `QuerySubscriber` in
+`dist/core/data.d.ts`. This page is the residue: the subscription behaviours the declaration doesn't
+spell out, and how to live with the handle inside a UI framework's lifecycle.
+
+## Two subscription behaviours to know
+
+- Each `subscribe` is **independent** — unsubscribing one leaves the others live.
+- `subscribe` does **not** fire on registration; it only pushes **later** snapshots. Set initial
+  state from the **awaited** snapshot (`result.data` / `result.errors`), not from the subscriber
+  callback.
+- `result.refresh()` broadcasts the new snapshot to **all** current subscribers, not just the caller.
+
+## The lifecycle
+
+Read the initial snapshot, register a subscriber for later snapshots, and **always unsubscribe when
+the consumer goes away** (component unmount, effect re-run, view teardown) so the subscription
+doesn't leak:
+
+```typescript
+const result = await sdk.graphql!.query<GetAccountsQuery>({ query: GET_ACCOUNTS, variables });
+render(result.data, result.errors); // initial snapshot (subscribe won't re-deliver this)
+
+const unsub = result.subscribe(({ data, errors }) => render(data, errors)); // live updates
+await result.refresh(); // force re-fetch → pushes to subscribers
+// later, when the consumer tears down:
+unsub();
+```
+
+## Managing the subscription in a framework
+
+Whatever reactive/lifecycle primitive your UI layer uses — a React effect, a Vue/Svelte lifecycle
+hook, a web-component `connected`/`disconnectedCallback`, a store teardown — the same three
+obligations hold:
+
+- Kick off `query()` on mount/setup and store the resolved `result`, so you can call `refresh()` on
+  it later (e.g. behind a "Refresh" button).
+- Push each `subscribe` snapshot into your reactive state so the view re-renders.
+- Run `unsub()` in the teardown path, and guard against a late-resolving `query()` writing state
+  **after** teardown — track a `cancelled` flag. (Because `subscribe` does not fire on registration,
+  the awaited snapshot is the only place your initial state comes from.)
+
+## Refresh after a mutation
+
+Mutations resolve to a `MutationResult` — a one-shot `{ data, errors }` with **no**
+`subscribe`/`refresh` (see `MutationResult` in the `.d.ts`; re-running a mutation on refresh would be
+dangerous). A mutation **does not throw on a GraphQL-level failure** — exactly like a query, the
+outcome surfaces on the resolved result (`result.errors`, with `result.data` left `undefined`). A
+failed operation — or even a degenerate `{ data: undefined, errors: [] }` response from the server —
+will **not** raise. So **guard on the result before treating the write as done**, and only refresh a
+held query after a clean mutation:
+
+```typescript
+const result = await sdk.graphql!.mutate({ mutation: CREATE_ACCOUNT, variables: { input } });
+if (result.errors?.length || !result.data) {
+  // Mutation didn't succeed. Surface it through your normal error path — do NOT refresh a
+  // write that didn't happen. (`!result.data` also catches the empty-errors degenerate case.)
+  return handleMutationFailure(result.errors);
+}
+await accountsResult.refresh(); // re-fetches, bypasses cache, pushes to subscribers
+```
+
+## When to reach for this vs the default cache
+
+_Whether_ to use `subscribe`/`refresh` at all — versus just relying on the default cache or a
+one-shot `cacheControl` — is a strategy call. See the two-refresh-tools table and decision matrix in
+[02-caching-and-freshness.md](./02-caching-and-freshness.md); this page is not duplicated there.
+
+## Uncached surfaces
+
+On Mosaic / OpenAI the handle exists but `subscribe` only emits in response to `refresh()` — there
+is no background cache to push updates, and each `refresh()` costs a network request. See
+[Uncached surfaces](./02-caching-and-freshness.md#uncached-surfaces-mosaic-openai) and
+[04-surfaces-and-guards.md](./04-surfaces-and-guards.md).

package/docs/data/04-surfaces-and-guards.md

@@ -0,0 +1,146 @@
+<!-- sdk-symbols
+DataSDK: dist/core/data.d.ts
+DataSDKGraphQL: dist/core/data.d.ts
+DataSDKOptions: dist/data/index.d.ts
+WebAppDataSDKOptions: dist/data/index.d.ts
+StatusCallback: dist/data/index.d.ts
+MosaicDataSDKOptions: dist/data/mosaic/index.d.ts
+NodeOfConnection: dist/data/index.d.ts
+-->
+
+# Surfaces & guards
+
+`createDataSDK()` returns a `DataSDK` with two data-access members — `graphql` (the primary route)
+and `fetch` (the escape hatch; see [01-grounding-and-precedence.md](./01-grounding-and-precedence.md)
+for which door to pick). Both are **optional**: a surface that doesn't support data operations
+resolves to a bare `{}` rather than throwing (see `DataSDK` in `dist/core/data.d.ts`). This page is
+the residue: how to guard that optionality, what `.fetch` is and how it differs from `.graphql`, how
+to read `errors`, and the per-surface options.
+
+## `sdk.graphql!` vs guard — a surface decision
+
+Whether to assert `sdk.graphql` after `createDataSDK()` is a **surface** call, not a style call:
+
+```typescript
+// `!` form — WebApp-exclusive bundles only.
+const result = await sdk.graphql!.query<...>({ query, variables });
+
+// Portable guard form — safe on every surface. Use when the bundle is not WebApp-exclusive.
+if (!sdk.graphql) {
+  // No data SDK on this surface — degrade gracefully (render empty, throw, or feature-flag off).
+  return;
+}
+const result = await sdk.graphql.query<...>({ query, variables });
+```
+
+Use `!` **only** if the bundle ships to WebApp exclusively. A bare `sdk.graphql!` that later ships to
+another surface throws `Cannot read properties of undefined` at runtime, and TypeScript **cannot**
+catch it because `!` silences exactly that check. The same `!`-vs-guard decision applies to
+`sdk.fetch!`.
+
+## `.fetch` — the escape hatch
+
+`sdk.fetch` is the SDK's authenticated HTTP primitive: the same call shape as the global `fetch`
+(`typeof fetch` — a URL/`Request` plus optional `RequestInit`, resolving to a `Response`), enriched
+per surface so you don't reassemble auth and transport concerns by hand. Reach for it when the
+GraphQL schema doesn't expose what you need — REST (`/services/data/…`), Apex REST
+(`/services/apexrest/…`), Connect, or blob/file downloads. Default to `.graphql`; `.fetch` is the
+route for everything that has no GraphQL representation.
+
+What it carries, per surface:
+
+- **WebApp** — CSRF token handling with automatic retry on token rejection, the `Accept-Language`
+  and client-context headers the platform expects, and relative URLs resolved against the app's API
+  base path. Your `onStatus` callbacks fire on `.fetch` responses too, so a `401` handler
+  re-authenticates for `.fetch` and `.graphql` alike. On this surface `.graphql` is itself built on
+  top of `.fetch`.
+- **Mosaic** — no `.fetch`. `MosaicDataSDK` only implements `graphql`; guard for `.fetch`'s absence
+  rather than assuming it.
+- **OpenAI** — no `.fetch`. That surface exposes only `.graphql` via an MCP tool, so guard for
+  `.fetch`'s absence rather than assuming it.
+
+Two things `.fetch` does **not** do, both by contrast with `.graphql`:
+
+- **No cache.** `.fetch` responses are never cached by the SDK — caching is a `.graphql`-only
+  concern (see [02-caching-and-freshness.md](./02-caching-and-freshness.md)). Layer your own if you
+  need it.
+- **No `errors` envelope.** `.fetch` resolves to a raw `Response`, so the HTTP status _is_ the
+  signal — check `response.ok` / `response.status` and parse the body yourself, exactly as with the
+  platform `fetch`. This is the inverse of the `.graphql` "HTTP 200 ≠ success" model below.
+
+```typescript
+if (!sdk.fetch) {
+  // No fetch on this surface (e.g. OpenAI) — degrade gracefully.
+  return;
+}
+
+// REST read — the standard Response model: status is the signal.
+const res = await sdk.fetch("/services/data/v64.0/sobjects/Account/001xx000003DGb0AAG");
+if (!res.ok) {
+  throw new Error(`Account read failed: ${res.status}`);
+}
+const account = await res.json();
+
+// Apex REST — POST to a custom endpoint.
+const apexRes = await sdk.fetch("/services/apexrest/MyService", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ recordId: "001xx000003DGb0AAG" }),
+});
+```
+
+Guard `sdk.fetch` exactly as you guard `sdk.graphql` — the `!`-vs-guard decision above applies
+identically.
+
+## HTTP 200 ≠ success — always read `.graphql` `errors`
+
+`DataSDKGraphQL.query` / `.mutate` **always resolve**; they do not reject. Every failure (GraphQL
+errors, parse errors, wrong operation kind, non-serializable variables, network errors) is funnelled
+into the resolved `result.errors` array (see `DataSDKGraphQL` in the `.d.ts`). So a settled Promise
+is **not** a successful result — you must inspect `result.errors`. (This is `.graphql`-specific:
+`.fetch` reports failure through the `Response` status instead, per the section above.)
+
+Choose the product-appropriate stance; all three inspect `result.errors`:
+
+```typescript
+// Strict — any errors = failure
+if (result.errors?.length) throw new Error(result.errors.map((e) => e.message).join("; "));
+
+// Tolerant — log, use whatever data came back (partial success)
+if (result.errors?.length) console.warn("GraphQL partial errors:", result.errors);
+
+// Discriminated — fail only when NO data returned
+if (!result.data && result.errors?.length) {
+  throw new Error(result.errors.map((e) => e.message).join("; "));
+}
+```
+
+## Per-surface options
+
+`createDataSDK(options)` takes a `DataSDKOptions` bag; the fields you set depend on the surface. The
+declarations own the field lists — this is just the routing:
+
+- **WebApp** — `WebAppDataSDKOptions` (`options.webapp`): `basePath`, and `onStatus` per-HTTP-status
+  callbacks (each a `StatusCallback`) for cases like re-authenticating on a `401`. This is the
+  cached surface — see [02-caching-and-freshness.md](./02-caching-and-freshness.md).
+- **Mosaic** — `MosaicDataSDKOptions` (`options.mosaic`): server-side (Node) auth via `instanceUrl` /
+  `accessToken` / `apiVersion`. Uncached.
+- **OpenAI** — no surface options bag; delegates to an MCP tool. Uncached, and it exposes no header
+  channel, so per-request `headers` are ignored there.
+
+## Uncached surfaces (Mosaic, OpenAI)
+
+- No cache exists — every `query()` is a network request, and `cacheControl` is silently ignored.
+- `subscribe` is real but only emits in response to `refresh()`.
+
+The full uncached-surface behaviour and the caching model it contrasts with are in
+[02-caching-and-freshness.md](./02-caching-and-freshness.md#uncached-surfaces-mosaic-openai) and
+[03-reactive-handle-lifecycle.md](./03-reactive-handle-lifecycle.md). The `query`/`mutate` shape is
+identical across surfaces, so the same call site runs everywhere — only caching differs.
+
+## `NodeOfConnection` — unwrapping a connection
+
+Read queries that return a Relay-style `{ edges: [{ node }] }` connection can have the element type
+unwrapped with `NodeOfConnection<T>` (see the declaration in `dist/data/index.d.ts`). It resolves to
+`never` when `T` isn't such a connection, and it is **read-side only** — only `query` returns
+connections, so it never applies to `mutate` results.

package/docs/data/05-migration-from-sdk-data.md

@@ -0,0 +1,126 @@
+<!-- sdk-symbols
+createDataSDK: dist/data/index.d.ts
+gql: dist/data/gql.d.ts
+NodeOfConnection: dist/data/index.d.ts
+CacheControl: dist/core/data.d.ts
+-->
+
+# Migration — old Data SDK → `@salesforce/platform-sdk`
+
+The Data SDK changed in two breaking ways (PR #502, shipped in `@salesforce/platform-sdk` v10.10.1):
+
+1. **Package renamed** — `@salesforce/sdk-data` → **`@salesforce/platform-sdk`**.
+2. **`sdk.graphql` reshaped** from a **callable method** into a **namespace** with `.query()` and
+   `.mutate()`, both taking an **options object**.
+
+> Any remaining `@salesforce/sdk-data` **import in consumer source** is a leftover from before this
+> migration — not canonical. Always import from `@salesforce/platform-sdk`. (This does not cover
+> intentional historical/comparative references elsewhere in the repo — e.g. this package's own
+> `PACKAGING-STRATEGY.md` or the migration-facing skill docs — which are expected to keep the old
+> name.)
+
+This is the **only** page where the dead callable API appears, for comparison. The **new-side**
+snippets below are illustrative of the transition, **not** the source of truth for the current call
+contract — for the authoritative new signatures read `dist/core/data.d.ts` and `dist/data/index.d.ts`
+(tier-2a). If a new-side snippet here has drifted from the installed declaration, the declaration
+wins.
+
+## 1. Import
+
+```diff
+- import { createDataSDK, gql, type NodeOfConnection } from "@salesforce/sdk-data";
++ import { createDataSDK, gql, type NodeOfConnection, type CacheControl } from "@salesforce/platform-sdk";
+```
+
+`createDataSDK`, `gql`, `NodeOfConnection`, and `CacheControl` all export from
+`@salesforce/platform-sdk`.
+
+## 2. Query call
+
+```diff
+- // OLD — callable, positional args, returns a response object with .data / .errors
+- const response = await sdk.graphql?.<GetAccountsQuery, GetAccountsQueryVariables>(GET_ACCOUNTS, variables);
+- const accounts = response?.data?.uiapi?.query?.Account?.edges ?? [];
+- if (response?.errors?.length) { /* ... */ }
+
++ // NEW — namespace method, options bag, returns a reactive QueryResult
++ const result = await sdk.graphql!.query<GetAccountsQuery, GetAccountsQueryVariables>({
++   query: GET_ACCOUNTS,
++   variables,
++ });
++ const accounts = result.data?.uiapi?.query?.Account?.edges ?? [];
++ if (result.errors?.length) { /* ... */ }
+```
+
+Passing the generated `<GetAccountsQuery>` type parameter makes `result.data` fully typed — no
+`as any` cast needed.
+
+| Old                                   | New                                                      |
+| ------------------------------------- | -------------------------------------------------------- |
+| `sdk.graphql?.(QUERY, vars)`          | `sdk.graphql!.query({ query: QUERY, variables: vars })`  |
+| positional `<T, V>(query, variables)` | type params on `query<T, V>(options)`                    |
+| `response.data` / `response.errors`   | `result.data` / `result.errors` (same fields)            |
+| (none)                                | `result.subscribe(cb)` / `result.refresh()` — new handle |
+| (none)                                | `cacheControl` option — new per-call cache policy        |
+
+## 3. Mutation call
+
+The old callable form was used for mutations too. Mutations now have their own method, and the
+operation key is **`mutation`**, not `query`:
+
+```diff
+- const response = await sdk.graphql?.<CreateAccountMutation>(CREATE_ACCOUNT, { input });
++ const { data, errors } = await sdk.graphql!.mutate<CreateAccountMutation, CreateAccountMutationVariables>({
++   mutation: CREATE_ACCOUNT,   // key is `mutation`, not `query`
++   variables: { input },
++ });
+```
+
+`mutate()` returns `{ data, errors }` only — **no** `subscribe`/`refresh`, and it is **never cached**.
+To refresh a list after a mutation, hold the query `result` and call `result.refresh()` (see
+[03-reactive-handle-lifecycle.md](./03-reactive-handle-lifecycle.md)).
+
+## 4. Optional chaining → non-null assertion
+
+The old guidance was "always use optional chaining" (`sdk.graphql?.()`). Real consumer code now uses
+the **non-null assertion** after `createDataSDK()` — but whether `!` or a guard is correct is a
+surface decision, covered in [04-surfaces-and-guards.md](./04-surfaces-and-guards.md):
+
+```diff
+- const response = await sdk.graphql?.(QUERY, vars);
++ const result = await sdk.graphql!.query({ query: QUERY, variables: vars });
+```
+
+## 5. Generated types — unchanged generation, new call placement
+
+The generated operation type **names** (`<Op>Query` / `<Op>QueryVariables` / `<Op>Mutation` /
+`<Op>MutationVariables`) are **unchanged**. Only **where** the type params attach moves — from the
+callable to the namespace method:
+
+```diff
+- await sdk.graphql?.<GetAccountsQuery, GetAccountsQueryVariables>(GET_ACCOUNTS, variables);
++ await sdk.graphql!.query<GetAccountsQuery, GetAccountsQueryVariables>({ query: GET_ACCOUNTS, variables });
+```
+
+`NodeOfConnection` (read-side) still unwraps a connection the same way. **Regenerating** the types is
+a repo/skill command, not something this package owns — this page only covers where the generated
+names now attach.
+
+## 6. New capabilities unlocked while migrating
+
+The reshape also unlocked the freshness features (none required to get back to working). The one
+migration-specific gotcha: **caching is now on by default** (WebApp) — if any code relied on every
+call hitting the network, add `cacheControl: "no-cache"` to it. The reactive `subscribe`/`refresh`
+handle and the rest of `CacheControl` are in
+[02-caching-and-freshness.md](./02-caching-and-freshness.md) and
+[03-reactive-handle-lifecycle.md](./03-reactive-handle-lifecycle.md).
+
+## 7. Migration checklist
+
+- [ ] Replace every `@salesforce/sdk-data` import with `@salesforce/platform-sdk`.
+- [ ] Convert every `sdk.graphql?.(q, v)` query to `sdk.graphql!.query({ query: q, variables: v })`.
+- [ ] Convert every mutation call to `sdk.graphql!.mutate({ mutation: m, variables: v })` (key is `mutation`).
+- [ ] Move generated type params onto `query<T,V>` / `mutate<T,V>`.
+- [ ] Rename `response` → `result`; `response.data`/`.errors` → `result.data`/`.errors`.
+- [ ] Add `cacheControl: "no-cache"` to any call that genuinely must always hit the network.
+- [ ] Re-check the `!`-vs-guard decision per surface ([surfaces & guards](./04-surfaces-and-guards.md)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/platform-sdk",
-  "version": "11.69.2",
+  "version": "11.70.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",
@@ -112,15 +112,20 @@
     },
     "./package.json": "./package.json"
   },
+  "directories": {
+    "doc": "docs"
+  },
   "files": [
-    "dist"
+    "dist",
+    "docs/data"
   ],
   "scripts": {
     "build": "vite build",
     "clean": "rm -rf dist",
     "dev": "vite build --watch",
-    "test": "vitest run --typecheck && npm run test:examples",
+    "test": "vitest run --typecheck && npm run test:examples && npm run test:docs",
     "test:examples": "tsx scripts/check-examples.mts",
+    "test:docs": "tsx scripts/check-docs-symbols.mts",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage --typecheck"
   },
@@ -134,7 +139,7 @@
     "@conduit-client/service-pubsub": "3.19.6",
     "@conduit-client/service-retry": "3.19.6",
     "@conduit-client/utils": "3.19.6",
-    "@salesforce/jsonrpc": "^11.69.2",
+    "@salesforce/jsonrpc": "^11.70.0",
     "@salesforce/sf-embedding-bridge": "2.2.5-rc.2"
   },
   "peerDependencies": {