@foir/sdk 0.5.0 → 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,1126 @@
+# Changelog
+
+All notable changes to `@foir/sdk`.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows the policy below.
+
+---
+
+## Semver policy
+
+`@foir/sdk` is published to npm and installed by people outside this repo. Its
+**public API is the set of named exports reachable through the subpaths in
+`package.json#exports`** — nothing else. Anything reachable only by deep-importing
+`@foir/sdk/dist/...` is private and may change in any release without notice.
+
+That surface is pinned in [`public-exports.snapshot.json`](./public-exports.snapshot.json)
+and enforced on every build by `scripts/assert-public-exports.mjs`. If a change
+reds that guard, it belongs in this file.
+
+### Pre-1.0 note — breaking changes bump the MINOR
+
+While the version is `0.x`, a breaking change bumps the **minor** (`0.5.0` →
+`0.6.0`), not the major. This is not laziness about semver, it is what actually
+protects consumers: npm resolves `^0.5.0` to `>=0.5.0 <0.6.0`, so for a `0.x`
+package the minor — not the major — is the boundary an existing `pnpm install`
+will not cross on its own. Once `1.0.0` ships, breaking changes move to the
+major and this note goes away.
+
+Read "MAJOR" below as "minor, while we are pre-1.0".
+
+### MAJOR — breaking
+
+A change is breaking if code that compiled and ran against the previous version
+can stop compiling, stop resolving, or start behaving differently:
+
+- **Removing a named export** from any published subpath.
+- **Renaming a named export.** A rename is a removal plus an addition; shipping
+  the old name as a deprecated alias for at least one minor is preferred.
+- **Removing a subpath** from `package.json#exports`, or repointing one at a
+  module with a different surface.
+- **Demoting a value export to type-only** (`export { X }` → `export type { X }`).
+  The type-checker stays happy at the re-export site and the runtime import
+  starts throwing, which is the worst possible failure shape.
+- **Narrowing a type**: making an optional parameter or property required,
+  removing a member from a union or an enum, tightening a parameter's accepted
+  type, widening a return type, or adding a required field to an options object.
+  Rule of thumb — narrowing what we *accept* or widening what we *return* is
+  breaking; the reverse is not.
+- **Changing the runtime behaviour of an existing call**: different network
+  endpoint, different request or response shape on the wire, different default
+  value, throwing where it used to return, returning where it used to throw, or
+  a change in what gets persisted (cookie name, storage key, header name).
+- **Raising the floor**: a higher minimum Node version, a higher required
+  version of a peer dependency, or making an optional peer dependency required.
+
+Every breaking change needs a `### Removed` or `### Changed` entry below that
+**names each affected symbol** and states the migration.
+
+### MINOR — additive
+
+- A new subpath, a new named export, or a new optional parameter/property.
+- Widening what an existing call accepts, or narrowing what it returns.
+- Promoting a type-only export to a value export.
+- A new optional peer dependency.
+- Deprecating something (the deprecation itself is additive; the eventual
+  removal is the breaking part).
+
+Additive changes still red the export-surface guard — deliberately, so the
+snapshot cannot rot into a rubber stamp. Refresh it with
+`pnpm --filter @foir/sdk run snapshot:exports` and commit the result.
+
+### PATCH — fixes
+
+- A bug fix that moves behaviour **toward** what the types and docs already
+  promised. If a caller could reasonably have been depending on the buggy
+  behaviour, it is a MAJOR, not a PATCH.
+- Internal refactors, build/bundling changes, dependency bumps and performance
+  work with no observable change to the public surface.
+- Documentation, comments and JSDoc.
+
+### Releasing
+
+Bump `packages/sdk/package.json#version`, move `Unreleased` into a dated
+section here, then push a `sdk-v<version>` tag — the tag, not the commit,
+triggers `.github/workflows/sdk-publish.yml`.
+
+`pnpm --filter @foir/sdk release:minor` does the bump and the tag together, but
+only because `packages/sdk/.npmrc` sets `tag-version-prefix=sdk-v`. Without it
+`pnpm version` tags `v<version>`, which does **not** match the workflow's
+`sdk-v*` trigger — the bump would land and no publish would ever run. If you
+move or drop that `.npmrc`, tag by hand:
+
+```sh
+git tag sdk-v<version> && git push origin sdk-v<version>
+```
+
+The tag must point at a commit on `main`: `main` is what is released, and a tag
+on `dev` would publish unreviewed work to npm.
+
+---
+
+## [Unreleased]
+
+Changes on `dev` that have not been published to npm.
+
+**The next release is BREAKING** — see `foir.raw()` under "Changed". A MINOR,
+per the pre-1.0 note above.
+
+### Removed
+
+- **BREAKING — `FoirBlockMeta`, `MediaBlock`, `TextBlock` and `FlexibleBlock`
+  are gone from `./data`.** They have no replacement because the things they
+  described are not in the schema:
+
+  - `FoirBlockMeta` declared `_id`/`_key`/`_label`/`_type` on every member. That
+    was the wrapper's envelope, removed at TTS-1391 — an item IS its value. No
+    member carries any of the four, so every one was a field the types promised
+    and the API never returned.
+  - `MediaBlock` — `media` stopped being a primitive at TTS-1391. It was never
+    in the proto FieldType enum, and it is the one primitive name a project had
+    also used as a model key.
+  - `TextBlock` — removed at TTS-1406. GraphQL requires a union member to be an
+    object type and a text item's value is a bare scalar, which is the whole
+    reason a wrapper existed. An inline model with a text field is how a text
+    slot is authored.
+  - `FlexibleBlock` — there is no fallback member. An item whose `_type` names
+    nothing is nulled out of its list and reported, which is already what a
+    stored null reads as.
+
+  **Migration:** delete the import. Code narrowing on `__typename ===
+  'MediaBlock' | 'TextBlock' | 'FlexibleBlock'` was matching nothing, so the
+  branch was already dead. Code reading `_id`/`_key`/`_label`/`_type` off a
+  member was reading `undefined` through a type that said `string | null`.
+
+  Nothing generates them either: `foir types` emitted `FoirBlockMeta` and the
+  three tokens, and no longer does — see the CLI entry below.
+
+### Changed
+
+- **BREAKING (`foir types`) — a flexible union member is the model's own type,
+  and the per-model wrapper is gone.** `foir types` used to emit a second
+  interface for every inline model — `ActHero` AND `ActHeroBlock` — where the
+  wrapper was `FoirBlockMeta` plus the model's non-`_`-prefixed fields. On the
+  Marketing fixture that was 20 of 47 interfaces describing a shape the platform
+  stopped serving at TTS-1391.
+
+  A union branch is now `(<Model> & { __typename: '<Model>' })`: the model
+  itself, intersected with the discriminant the union position guarantees. The
+  intersection is not a wrapper — it adds no field the server does not send. It
+  is there because the op compiler selects `__typename` on a union's own
+  selection set and nowhere else, so the model interface cannot declare it
+  outright, and because `@foir/sdk/data`'s narrowing surface is written as
+  `U extends { __typename: infer T }` — an optional key does not satisfy that,
+  and `pick: { on: … }` would silently stop working.
+
+  Where a model is reached BOTH as a member and as a model, the two answers now
+  live on one declaration keyed on `C`: `PageContent<D, C>` degrades `sections`
+  at `C extends true` and expands it otherwise, which is exactly what
+  `PageContentBlock` and `PageContent` said separately before.
+
+  **Migration:** re-run `foir types`. Narrow on `ActHero` rather than
+  `ActHeroBlock`; `_type`, `_key` and `_label` are gone with the envelope, and
+  `__typename` is the discriminant. Aliased response keys are unchanged — they
+  are a wire contract published in the manifest, so `imageBlockHeight` stays
+  `imageBlockHeight` until the platform republishes it.
+
+- **BREAKING (`foir types`) — a manifest carrying a retired primitive is now
+  refused by name.** `text`, `media` and a `flexible` fallback member stopped
+  being union members at TTS-1391/1406. A manifest listing one predates that, so
+  the generator says so and names re-publishing as the fix rather than emitting
+  a branch for a type the server never sends.
+
+- **BREAKING — the primitive members are the value types, under the schema's own
+  names.** `ImageValue` and `ImageBlock` are one type called `Image`, and the
+  same for the rest:
+
+  | was | now |
+  | --- | --- |
+  | `ImageValue` · `ImageBlock` | `Image` |
+  | `VideoValue` · `VideoBlock` | `Video` |
+  | `RichtextValue` · `RichtextBlock` | `Richtext` |
+  | `GeoPointValue` | `GeoPoint` |
+  | `ReferenceValue` · `ReferenceBlock` | `Reference` |
+  | `FileValue` · `FileBlock` | `FileValue` |
+
+  Every old name is kept as a deprecated alias of the new one, so imports keep
+  resolving. What changes underneath them:
+
+  - **`__typename` is now on each type**, optional, carrying the schema's name —
+    `'Image'`, not `'ImageBlock'`. The old literals matched nothing in a current
+    project, so an exhaustive `switch` over a flexible field fell through every
+    case.
+  - **`Image.url` and `Video.url` are nullable.** They were `string`. The
+    platform relaxed them to `String` at TTS-1391 — non-null on the value object
+    and nullable on the wrapper is a §5.3.2 response-shape conflict once the two
+    are one type — so `img.url.startsWith(…)` could throw on a value the types
+    said was present.
+  - **`Reference` loses `_id` and `_type`, and gains `_targetModelKey`,
+    `_targetId`, `_targetNaturalKey` and `record`.** `_id` was the ITEM's id and
+    `_type` read `"reference"` on every reference ever stored; neither is in the
+    schema. The target coordinates are what actually make a reference
+    followable (TTS-1349/1371), and both identifier shapes are live — on the dev
+    database 101 of 193 stored references carry an id and 92 carry a natural key
+    and no id.
+
+  **Migration:** narrow on the new `__typename` literals; treat `url` as
+  nullable; replace `ref._id` with `ref._targetId ?? ref._targetNaturalKey` and
+  `ref._type` with `ref.__typename`.
+
+  **Why this was wrong for so long:** `builtins.ts` is the one part of the typed
+  data surface that is not generated per project, and nothing compared it to a
+  real schema. `src/data/__tests__/builtins.test-d.ts` now pins every member
+  against graphql-codegen output taken from a live project.
+
+- **BREAKING (behaviour) — the codegen plugins now default to the `Flexible`
+  union, not `Block`.** `DEFAULT_UNIONS` in `@foir/sdk/codegen` was `['Block']`;
+  it is `['Flexible']`.
+
+  The platform stopped emitting a union named `Block` at TTS-1391 — a flexible
+  field's members are the value types and inline models under their own names,
+  and the project-wide union an unconstrained field resolves to is `Flexible`.
+  So `foirCodegen()` on defaults could not have worked against any current
+  project: `collectItemMembers` refuses rather than emitting an empty registry,
+  so it threw `[foir codegen] no union members found. Looked for union(s):
+  Block`. This is listed as breaking because it changes a default, but the
+  default it replaces had no working configuration.
+
+  It stayed invisible because the plugin tests built their own fixture schema
+  declaring `union Block = RichtextBlock | ImageBlock | TextBlock` — the
+  pre-TTS-1391 shape. The fixture is now the post-1391 shape, and
+  `DEFAULT_UNIONS` is asserted against it directly.
+
+  **Migration:** none if you pass `blockUnions`/`itemUnions` explicitly. If you
+  relied on the default and codegen was failing, it now resolves. If your
+  project genuinely has a union named `Block`, pass `itemUnions: ['Block']`.
+
+- **`createContentRenderer` passes `item` to every component, and accepts
+  `items` as well as `blocks`.** `props.block` is still passed on every render
+  and `blocks=` is still accepted, so scaffolded components and existing call
+  sites are unaffected. Passing both `items` and `blocks` is a type error rather
+  than a silent precedence rule.
+
+### Added
+
+- **`@foir/sdk/codegen/item-registry` and `@foir/sdk/codegen/item-scaffold`** —
+  the two graphql-codegen plugins under names that do not claim `block` is a
+  platform concept. `@foir/sdk/codegen/block-registry` and `/block-scaffold`
+  re-export them unchanged and keep working.
+
+- **`ItemLike`, `ItemComponent`, `ItemComponentProps`, `ItemRegistry`** on
+  `./content`, and **`ItemPluginConfig`**, **`ItemRegistryConfig`**,
+  **`ItemScaffoldConfig`** on the codegen subpaths. Each is the canonical name
+  for the `Block*` type of the same shape.
+
+- **`foirCodegen({ itemUnions })` / `foirScaffold({ itemUnions })`** — the
+  canonical spelling of `blockUnions`, which is still honoured when `itemUnions`
+  is unset.
+
+### Deprecated
+
+- **Every `Block*` spelling in the SDK.** `BlockLike`, `BlockComponent`,
+  `BlockComponentProps`, `BlockRegistry`, `BlockPluginConfig`,
+  `BlockRegistryConfig`, `BlockScaffoldConfig`, `collectBlockMembers`, the
+  `blockUnions` option, the `blocks` prop on `createContentRenderer`, the
+  `props.block` field, and the `./codegen/block-registry` and
+  `./codegen/block-scaffold` subpaths.
+
+  `block` was never a platform concept — it was one project's NAME for a
+  flexible field, and a modeller may equally call one `items`, `sections` or
+  `modules`. The platform never infers anything from a field's name and the SDK
+  should not teach otherwise (TTS-1391).
+
+  Nothing is removed in this release; every old name still resolves and still
+  behaves identically. Removal is a later, separately announced break.
+
+- **BREAKING (generated types) — a union the compiler stopped in front of one
+  level BELOW a block union member is now typed as the degraded union, where it
+  used to be typed as the whole one.** Same direction as the composite entry
+  below: the type promised more than arrives, so code reading through it
+  compiled and got `undefined`.
+
+  The entry below fixed the composites cut at a union member's OWN fields, which
+  are emitted per position and could simply be degraded there. A cut can also
+  land one level deeper. `ProductDetailsAccordionBlock.items` is a composite the
+  server did NOT cut, so it expands and is typed with `Detail`'s own interface —
+  and `Detail.body` IS cut inside that subtree, because reaching it means
+  `Block` is already on the compiler's path.
+
+  `Detail` is one interface referenced from a cut position and an uncut one
+  (`product_details_accordion.items` at the model position), so it could not
+  simply be degraded: that would have been wrong at the other reference. The
+  answer now travels with the REFERENCE, as a second parameter threaded the way
+  `<D>` already is:
+
+  ```ts
+  export interface Detail<D extends FoirDepthLevel = 1, C extends boolean = false> {
+    label: string | null;
+    body: Array<(C extends true ? … : DetailBody<D>) | null> | null;
+  }
+
+  // inside the union member — cut
+  export interface ProductDetailsAccordionBlock<D extends FoirDepthLevel = 1> … {
+    items: Array<Detail<D, true> | null> | null;
+  }
+  // at the model position — whole
+  export interface ProductDetailsAccordion<D extends FoirDepthLevel = 1, C extends boolean = false> {
+    items: Array<Detail<D, C> | null> | null;
+  }
+  ```
+
+  **Nothing a caller writes ever passes `C`.** It defaults to `false`, so every
+  existing reference resolves exactly as it did; the position it came from is
+  what sets it.
+
+  On the live dev project **one position narrows**, and the full recursive
+  census is what says so: ten `truncated` positions anywhere in `models[*]
+  .selection` or `selectionUnions`, of which six were already correct, three
+  were fixed by the entry below, and this is the tenth. Re-run after the change,
+  the count of over-promising positions is **zero of ten**.
+
+  | position | was | is |
+  | --- | --- | --- |
+  | `ProductDetailsAccordionBlock.items[].body` | `Array<DetailBody \| null> \| null` | `Array<DetailBodyDegraded \| null> \| null` |
+
+  **`depth` DOES help here**, which is the difference from the composite case.
+  The position carries a union name, so `printFields` expands it when the budget
+  allows and the type follows: at `depth: 2` the same read resolves to the whole
+  `DetailBody` union and narrows on `__typename` with no cast. Verified against
+  deployed dev — at the level where the member arrives expanded, all ten live
+  `body` values are `{ "__typename": "RichtextBlock" }` and nothing else; one
+  level further, every one of them is a whole `RichtextBlock` carrying its
+  `html` and `json`.
+
+  **The wire is untouched.** Types only: 192 documents compared across five
+  manifests (the four committed fixtures and a live capture) at every level
+  1–4, all byte-identical, and every emitted `foirSelections` /
+  `foirNamespaceSelections` / `foirSelectionUnions` const unchanged byte for
+  byte. **Regenerate with `foir types` to get the narrowing.**
+
+  A manifest with no selection trees is unaffected, as before: no `truncated`
+  means no cut, no interface gains the parameter, and the generated file is what
+  it was.
+
+- **BREAKING (generated types) — a composite the compiler stopped in front of
+  inside a block union member is now typed `FoirDegraded`, where it used to be
+  typed whole.** The DEFAULT result type narrows at those positions, and code
+  reading through one stops compiling. That is the point: it compiles today
+  against a value that never arrives.
+
+  The op compiler never expands a type already on the current path, and the path
+  includes the union the composite was reached through. `foir types` was deciding
+  truncation from the composite GRAPH alone, which cannot see that edge — so a
+  composite reached from inside a union member got the target's full interface
+  for a position the server sends `{ "__typename": "PageContent" }` at. A caller
+  wrote `block.pageContent.sections[0].anchor`, it type-checked, and it was
+  `undefined` at runtime with no null check to have skipped.
+
+  On the live dev project (50 models, one 56-member `Block` union) **four
+  positions narrow**, and they are the whole population — the manifest's own
+  `truncated` flag is now what decides, so this is not an estimate:
+
+  | position | was | is |
+  | --- | --- | --- |
+  | `ProductBlock.pageContent` | `PageContent` | `FoirDegraded<'PageContent'>` |
+  | `PageBlock.pageContent` | `PageContent` | `FoirDegraded<'PageContent'>` |
+  | `CollectionBlock.pageContent` | `PageContent` | `FoirDegraded<'PageContent'>` |
+  | `PageContentBlock.sections` | `Array<Section \| null> \| null` | `Array<FoirDegraded<'Section'> \| null> \| null` |
+
+  **What a caller does about it.** The values were never arriving, so there is no
+  code to preserve — only a read to move:
+
+  ```ts
+  // was: compiled, `sections` undefined at runtime
+  const anchor = block.pageContent.sections[0].anchor;
+
+  // now: `__typename` is all that arrives, and the type says so
+  if (block.pageContent?.__typename === 'PageContent') { /* … */ }
+  ```
+
+  To actually get the content, address the record it belongs to in a second call
+  (`foir.page.findUnique({ … })`), or reach it through the position where it is
+  NOT cut — the same composite read from the model rather than from inside a
+  block still arrives whole.
+
+  **`depth` does not help here, deliberately.** A UNION stopping point is buyable
+  a level at a time (see `depth` under "Added"); a COMPOSITE one has no union to
+  expand, so `printFields` prints `{ __typename }` for it at every level. Typing
+  it behind `<D>` would promise a level that never arrives, which is the defect
+  being fixed rather than a fix for it. Measured on the live project: the number
+  of expanded union positions rises 1 → 2 → 3 → 4 with `depth`, and the four
+  composite cuts are merely replicated by that expansion, never opened.
+
+  **The wire is untouched.** This is a types-only change: the document printed
+  for a call passing no `depth` is byte-identical — verified across 119 default
+  documents (73 ops of the live manifest, 39 of the `orderby` fixture, 7 of the
+  `jacket` one), and the emitted `foirSelections` runtime const is unchanged
+  byte for byte. **Regenerate with `foir types` to get the narrowing**; an
+  existing generated file keeps its old, over-promising types.
+
+  A manifest with no selection trees — a server predating `selectionUnions` —
+  keeps widening at these positions, unchanged. Absence of the flag must not read
+  as "cut", or an old server would silently degrade every composite in every
+  block, which is a worse lie than the one being fixed. `compositeCycleMembers`
+  is still what cuts a composite CYCLE there, from the graph alone.
+
+- **`@foir/sdk/data` prints a GraphQL document and executes it over `/graphql`**,
+  the same endpoint every other consumer of the API uses — one execution surface,
+  one executor, one set of scope checks, one response cache. The public API is
+  unchanged: `foir.page.findMany({ where, include, omit })` is the same call it
+  always was. What changed is what goes on the wire. The client loads that op's
+  selection tree (published by `GET /v1/manifest` as `models.<key>.selection`),
+  applies `omit`/`pick`/`include`, prints a document, hashes it and sends the
+  hash.
+
+  Still **no `graphql` dependency** — the tree arrives pre-resolved, so printing
+  it is string building. The import-graph assertion that pins this is unchanged
+  and still passes.
+
+  What this buys, immediately: a block-bearing model reads complete-by-default.
+  `page`, `product` and `collection` need no caller-supplied `omit` to be read at
+  all. A document is the only form that can alias two union members which
+  disagree on a field's response shape, and the manifest publishes those aliases,
+  so those models return 200 on a bare `findMany()`.
+
+  Two new config fields carry the runtime half of `foir types`:
+
+  ```ts
+  createFoirClient<FoirSchema>({
+    apiUrl, apiKey,
+    selections: foirSelections,
+    selectionUnions: foirSelectionUnions,
+  });
+  ```
+
+  Both are optional. Without them the client fetches `GET /v1/manifest` once at
+  first use and reads the same trees off it — a FALLBACK, so a zero-codegen start
+  still works, at the cost of a round trip in front of the first query on every
+  cold edge invocation.
+
+  Reads take the shared, cacheable lane where they can:
+  `GET /cdn/graphql?key=pk_…` with the persisted-query hash in the URL when the
+  call is a query, on a `pk_` key, with no customer bearer, on the published
+  channel — and `POST /graphql` otherwise. The server's gate refuses on five
+  conditions and the client decides all five before the request: the fifth,
+  "the credential is in the URL", it satisfies by construction. The server is
+  still the authority — it refuses an ineligible read by name, and the refusal
+  is retried on `/graphql`.
+
+- **BREAKING — `foir.raw()` takes a GraphQL document.** A document string and an
+  optional variables object, where it used to take a JSON op
+  (`{ model, op, args }`):
+
+  ```ts
+  // before
+  await foir.raw({ model: 'page', op: 'findMany', args: { first: 5 } });
+  // after
+  await foir.raw('query ($n: Int) { pages(first: $n) { totalCount } }', { n: 5 });
+  ```
+
+  It returns the whole `data` object rather than a single root field, because a
+  hand-written document may legitimately have several. As a document it reaches
+  everything the credential can reach — including the two dozen root fields no
+  model and no namespace claims (`designTokens`, `record`, `locales`, the
+  customer-auth mutations), which is the point of an escape hatch and is more
+  than the old shape could address.
+
+- **Every op prints, and there is one wire format rather than two.** The
+  descriptor now publishes a `payload` per op — the model it IS, the model it
+  CARRIES, its own resolved fields, or an explicit `leaf` — so every shape the
+  client can name is a shape it can print. That covers the 18 the client could
+  previously only name: every `foir.ns.*` op, plus `myAccess` and the other model
+  ops whose result is not the model. They execute over `/graphql` like everything
+  else, and nothing is kept beside it that a call could quietly land on.
+
+  This also removes the last place the client knew something the descriptor did
+  not tell it. A connection was wrapped in `edges { cursor node { … } }` from a
+  table of op names compiled into the client; it is now printed from the wrapper
+  the manifest published, so a server that changes that shape does not need a
+  client release to match.
+
+  **An op the manifest describes no payload for is refused, by name.** It is not
+  synthesised and there is no second protocol to fall back to.
+
+- **Arguments are sent as GraphQL variables, not printed as literals.** An op's
+  published `argTypes` becomes a real variable definition —
+  `query PageFindMany($orderBy: [PageOrderByInput])` — and the value travels in
+  `variables`, where the executor coerces it against the declared input type.
+
+  This is the fix for enum arguments. A printer working from argument names
+  alone has to infer each value's literal form from the JavaScript value, which
+  is exact for strings, numbers, booleans and objects and ambiguous for enums:
+  `orderBy: { createdAt: DESC }` needs `DESC` unquoted and the client holds the
+  string `'DESC'`. On one real project that was `orderBy` on every `findMany`
+  plus `where` on any enum field. Those calls used to be refused by the server,
+  by name; they work now.
+
+  Second-order, and worth having on its own: the document text no longer varies
+  with the argument VALUE, so the persisted-query registry holds one entry per
+  op instead of one per argument tuple. Argument names are emitted sorted for
+  the same reason.
+
+  **An argument the manifest publishes no type for is refused.** Falling back to
+  inferring a literal would reinstate the ambiguity under a condition no caller
+  can see.
+
+- **`@foir/sdk/auth` prints its documents too.** The flows used the same JSON
+  lane the data client did; they now print from `namespaces.auth.ops.<op>` on
+  the caller's own descriptor and execute over `/graphql`. Same functions, same
+  arguments, same return values. The descriptor is fetched once per credential
+  and memoised, so a `currentUser()` on every render does not refetch it.
+
+- **Schema drift now means "regenerate", not "be aware".** The trees the client
+  prints from are the ones the generated version published, so a field added
+  since is not merely untyped — it is not requested. The warning says so.
+
+### Removed
+
+- **`FoirRawOp` from `@foir/sdk/data`** — the JSON op shape (`{ model, op, args }`)
+  `foir.raw()` used to take. There is no replacement type because a call is a
+  GraphQL document now: `foir.raw()` takes a document string and variables. See
+  `foir.raw()` under "Changed" above for the migration.
+- **`foirOpResultKind` and `FoirResultKind` from `@foir/sdk/data`** — a table
+  mapping op NAMES to how their result wrapped the model, which is exactly the
+  schema knowledge the client is not allowed to hold. The manifest publishes
+  each op's result shape, so the table has nothing left to answer. Neither
+  symbol has appeared in a published release.
+- **`customerResendVerificationEmail` from `@foir/sdk/auth`** — and the
+  `AUTH_OPS.customerResendVerificationEmail` entry with it. **It never sent an
+  email.** The resolver behind it checked that the request carried a customer id,
+  returned `true`, and called no RPC; there is no customer verification-code
+  column and no customer verification email in the action catalogue for it to
+  have used. A caller got a success response every time and nothing was
+  delivered, which is worse than an error, because there is no signal to act on.
+
+  **Use the OTP flow for mailbox proof:** `customerRequestOTP(env, email)` emails
+  a code, and `customerLoginOTP(env, { email, otp })` redeems it — activating a
+  pending account on redemption and returning a session, so possession of the
+  mailbox is proven by the same call that signs the customer in. That is a live,
+  delivered path today; `customerVerifyEmail` remains for redeeming a token that
+  arrived by some other route.
+
+  Like the two entries above, this symbol has not appeared in a published
+  release — the whole `@foir/sdk/auth` surface it belongs to is unreleased — so
+  no installed version loses a function and there is nothing to migrate off.
+
+### Added
+
+- **`<FoirFeedback>` — a feedback widget anchored to the record, not the page.**
+  On `./react`, beside `<SignIn>` and `<UserButton>`.
+
+  ```tsx
+  const subjects = createFoirSubjectRegistry({ label: (r) => r.title as string });
+  const foir = createFoirClient({ apiUrl, apiKey, generated, subjects });
+
+  <FoirFeedback client={foir} subjects={subjects} />
+  ```
+
+  That is the whole wiring. There is no route table and no per-page
+  configuration: the subject is the last record the client addressed by name, so
+  a comment attaches to the record and survives a redesign, a URL change and a
+  locale variant. Nothing in the component reads `window.location`.
+
+  A page whose data all came out of lists has no subject, and the widget says so
+  rather than picking one of the twelve or falling back to the address bar. Pass
+  `subject` to name one yourself, or `subject={null}` to state there is nothing
+  here — which beats whatever the registry still holds from the previous page.
+
+  The visitor sees a human label or nothing at all: the model key and the record
+  id are what the note is filed against and never appear on screen.
+
+  Opening the panel reads `noteConfig`, which the API charges `notes:write` and
+  refuses to a caller with no customer session, so one probe settles whether the
+  visitor is signed in, whether their role may write notes, and whether
+  screenshot capture may be offered. A missing scope reads like a bad API key and
+  is not one, so it is reported as what it is: the signed-in customer's ROLE is
+  short `notes:write`, which a new project's default customer role does not
+  carry.
+
+  Screenshot capture is offered only when the project allows it and the browser
+  can do it, and is opt-in per submission — the browser's own picker is the
+  consent gate. A still is uploaded through the ordinary
+  `createFileUpload` → PUT → `confirmFileUpload` flow, so the mime gate, the
+  plan's per-file limit and the storage allowance all apply; an upload that fails
+  fails the whole submission rather than quietly sending a note without the
+  picture.
+
+  Props: `client`, `subjects`, `subject`, `label`, `triggerLabel`, `title`,
+  `placeholder`, `defaultOpen`, `onSignIn`, `onSubmitted`, `onError`,
+  `className`. Passing `className` turns the built-in inline styles off entirely;
+  the `data-foir-feedback-*` attributes are the styling hooks.
+
+  New exports on `./react`: `FoirFeedback`, `FoirFeedbackProps`,
+  `FoirFeedbackClient`.
+
+- **Screen capture on `./media`.** `isFoirScreenCaptureSupported()` says whether
+  the browser can do it at all; `captureFoirScreen()` captures one still of a
+  surface the reader picks, downscaled to 1600px and encoded as JPEG at 0.7. It
+  answers `null` when the picker is dismissed, because that is a decision rather
+  than a failure, and it stops every track before returning on every path. The
+  blob and the data URL are one encode read two ways, so the size the upload
+  declares is the size the bytes are.
+
+  New exports on `./media`: `captureFoirScreen`, `isFoirScreenCaptureSupported`,
+  `FoirScreenCapture`, `FoirScreenCaptureOptions`.
+
+- **Note attachments and note config on `./data`.** `FoirCustomerNote` gains
+  `attachments`, `FoirCreateMyNoteArgs` gains an optional `attachmentFileIds`,
+  and `FoirNoteConfig` is the shape `foir.ns.notes.noteConfig()` answers with.
+
+  New exports on `./data`: `FoirCustomerNoteAttachment`, `FoirNoteConfig`.
+
+- **A subject registry — the records a client fetched, so an annotation can
+  anchor to the record instead of to a URL.** `createFoirSubjectRegistry()`
+  builds one; passing it as `subjects` on the client config records what each
+  call fetched.
+
+  ```ts
+  const subjects = createFoirSubjectRegistry({ label: (r) => r.title as string });
+  const foir = createFoirClient({ apiUrl, apiKey, generated, subjects });
+
+  await foir.article.findUnique({ naturalKey: 'about-us' });
+  subjects.subject(); // { modelKey: 'article', recordId: 'kx7p…', label: 'About Us' }
+  ```
+
+  `subject()` answers with the last record the caller addressed **by name**; a
+  record that only appeared inside a list is recorded but never promoted, so a
+  page whose data all came out of lists answers `undefined` rather than picking
+  one. That distinction is read off the op's published payload — a `record`
+  payload IS one record — not inferred from result counts or field names. The
+  rest of the surface is `fetched()`, `setSubject()`, `clear()`, `subscribe()`
+  and `add()`, the last for seeding a record read on the server or through
+  `foir.raw()`, neither of which the data path can see.
+
+  **Off unless you build one, and there is no flag that turns it on.** A list of
+  the records a page fetched names content the reader may never have seen
+  rendered, so it exists only when the host constructs it and the host holds the
+  only reference. Build one per client, never at module scope — a shared registry
+  on a multi-tenant edge isolate is shared across tenants.
+
+  A failing `label` function or `subscribe` listener raises rather than being
+  swallowed, in a message that says the request itself succeeded: a subject that
+  silently fails to record leaves the PREVIOUS one standing, and a widget then
+  files feedback against the wrong page.
+
+  `FoirDocumentPlan` also now carries an optional `records` — where the records a
+  document selects sit in the response, and which model each is — derived from
+  the same payload walk that decides where `pick`/`omit` land. Optional so a
+  hand-built plan need not invent positions.
+
+  New exports on `./data`: `createFoirSubjectRegistry`, `recordFoirSubjects`,
+  `FoirSubject`, `FoirSubjectEntry`, `FoirSubjectOptions`, `FoirSubjectOrigin`,
+  `FoirSubjectRegistry`, `FoirRecordPath`.
+
+- **Types for the customer notes surface.** `foir.ns.notes.myNotes()` and
+  `foir.ns.notes.createMyNote()` already worked — `notes` is a namespace the
+  manifest publishes like any other — but their shapes had to be written out by
+  hand at each call site. They are platform-owned and identical in every project,
+  so they now ship: `FoirCustomerNote`, `FoirMyNotesArgs`, `FoirMyNotesResult`,
+  `FoirCreateMyNoteArgs`, `FoirNoteSubjectType`.
+
+  ```ts
+  const mine = (await foir.ns.notes.myNotes({ first: 20 })) as FoirMyNotesResult;
+  ```
+
+  `FoirNoteSubjectType` is the closed set the platform's write path enforces
+  (`record`, `file`, `model`, `operation`, `schedule`, `customer`) and is never a
+  model key — a note on a record is `'record'` plus the key on
+  `subjectModelKey`. Like every mirrored platform table in `builtins.ts`, a kind
+  added upstream widens this union in a minor release.
+
+- **`depth` on a model or namespace call — a per-request budget for nested block
+  content.** A block union's members can themselves carry block unions, and the
+  server refuses to expand a union already on the current path, so the
+  complete-by-default document stops one level in. Those stopping points now
+  publish the union they stopped in front of, and `depth` spends a level on one:
+
+  ```ts
+  // Default: a stopping point arrives as `{ __typename }`, exactly as before.
+  await foir.product.findMany({ first: 5 });
+
+  // One further union expansion — the nested blocks' own fields arrive.
+  await foir.product.findMany({ first: 5, depth: 2 });
+  ```
+
+  It is a **budget**, not a setting: the field count is exponential per level.
+  On one real project the same op measures 1,203 fields at the default, 4,308 at
+  `depth: 2` and 13,623 at `depth: 3`, against a server ceiling of 10,000 — so
+  the third level is reachable there only alongside `pick`/`omit`. A call whose
+  document would cross the ceiling is refused **client-side**, with the
+  arithmetic in the message and the ceiling named, rather than being sent for the
+  server to answer with a complexity number the caller cannot act on.
+
+  Additive in the strict sense: **the document printed for a call that does not
+  pass `depth` is byte-identical to the one printed before this change** — 
+  verified across all 73 ops of a live manifest, and asserted in
+  `document.test.ts`. `FoirDocumentPlan` also now carries an optional `fields`,
+  the count the server's complexity ceiling is denominated in — optional so a
+  hand-built plan need not invent a number, and always set on one this SDK
+  printed.
+
+  **The result type follows the level.** A stopping point the budget reaches is
+  typed as the expanded union rather than `FoirDegraded`, so the value is read
+  with a `__typename` narrowing and no cast:
+
+  ```ts
+  const page = await foir.product.findMany({ first: 5, depth: 2 });
+  const block = page.edges[0].node.pageContent?.sections?.[0]?.blocks?.[0];
+  if (block?.__typename === 'SectionBlock') {
+    const nested = block.blocks?.[0];          // the expanded union, not `{ __typename }`
+    if (nested?.__typename === 'ProductMainBlock') nested.enableShopPay; // reads
+  }
+  ```
+
+  `foir types` gives the composites between the record and a stopping point a
+  `<D extends FoirDepthLevel = 1>` parameter and names the model's shape at each
+  level under a new optional `FoirModelDefinition.atDepth`; the client picks one
+  with a single lookup. **Regenerate to get it** — an existing generated file
+  keeps working and keeps typing stopping points as `FoirDegraded` at every
+  level, which is what it did before.
+
+  The default is untouched, in the same strict sense the document is: `D`
+  defaults to `1`, so **the result type of a call that does not pass `depth` is
+  the type it was before this change**. A `depth` that is not a literal at the
+  call site (a variable typed `number`), or a level past the four `atDepth`
+  names, falls back to that same default shape — the values still arrive, the
+  type just declines to describe them, which is the direction that cannot
+  mislead.
+
+- **`FoirDepthLevel` and `FoirDepthBelow` on `@foir/sdk/data`** — the two type
+  exports the generated file needs to declare its `<D>` parameter (see `depth`
+  above). Platform-owned rather than emitted per project because `FoirDepthBelow`
+  mirrors the printer's `depth - 1` at an expanded stopping point, and one
+  definition beside it is how the two stay agreeing. Named exports, so the
+  export-surface snapshot moves 372 → 374.
+
+- **`generated` on `createFoirClient` and `createFoirClientFromEnv`, with the
+  `FoirGeneratedModule` type** — the generated module passed whole, which is now
+  the documented way to build a client:
+
+  ```ts
+  import { createFoirClient } from '@foir/sdk/data';
+  import * as generated from './foir.generated';
+
+  const foir = createFoirClient({ apiUrl, apiKey, generated });
+  ```
+
+  One import, no per-export knowledge at the call site, and `FoirSchema` inferred
+  from the module rather than restated as `createFoirClient<FoirSchema>`. An
+  artifact added to `foir types` later then costs a call site nothing.
+
+  **Additive.** `schemaVersion`, `selections`, `namespaceSelections` and
+  `selectionUnions` are unchanged, still accepted, and still win where both are
+  given — a client written against them compiles and behaves exactly as before.
+
+  What the module form removes is a failure that had no symptom. Passing four of
+  the five exports produced a client that silently fetched `GET /v1/manifest` on
+  every cold start and answered identically, so a `foirSelections` emitted in a
+  shape the printer could not read went unnoticed. A `generated` module is now
+  checked where it is passed: a missing export is a compile error naming it and a
+  refusal at construction, and so is a `foirSelections` entry that is a bare
+  selection tree rather than a selection model.
+
+  Needs a file from a current `foir types`: the inference reads `foirSchemaType`,
+  a type carrier the generator now emits, because a namespace import carries
+  values and `FoirSchema` is an interface. An older generated file, or one from a
+  server that publishes no selection trees, does not type-check as a
+  `FoirGeneratedModule` — re-run `foir types`, or keep using the individual
+  fields, which is what that file's own header now tells you to do.
+- **`announceManifestFallback` on `createFoirClient`** — set `false` to silence
+  the one-line `console.info` a client prints when it is built with neither
+  `generated` nor `selections` and will therefore read its selection trees from
+  `GET /v1/manifest`.
+
+  The fallback itself is unchanged and stays supported: it is what makes a
+  zero-codegen start work. What is new is that it announces itself, because a
+  fallback nobody can see is indistinguishable from the wiring mistake above.
+- **`planFoirNamespaceCall` on `@foir/sdk/data`**, with `FoirNamespaceCall`,
+  `FoirNamespaceSelections` and `FoirSelectionNamespace`. A namespace op is a
+  `FoirManifestOp` carrying a payload exactly as a model op is, so the function
+  that prints `foir.page.findMany()` prints `foir.ns.search.searchRecords()` —
+  one printer rather than two that agree by inspection.
+- **`namespaceSelections` on `createFoirClient`** — the namespace half of what
+  `foir types` emits, beside `selections`. Optional, like `selections`: without
+  it the client reads the same descriptor from `GET /v1/manifest` at first use.
+- **`FoirManifestOpPayload` on `@foir/sdk/data`** — an op's published result
+  shape, in four kinds (`record`, `object`, `union`, `leaf`). `leaf` is a stated
+  kind rather than an absent field list because a leaf takes NO selection set
+  and printing `{}` after one is a parse error.
+- **Selection-tree types on `@foir/sdk/data`** — `FoirManifestSelection`,
+  `FoirManifestSelectionField`, `FoirManifestSelectionMember` and
+  `FoirManifestSelectionUnion`, the resolved complete-by-default selections
+  `GET /v1/manifest` now publishes alongside the field buckets.
+
+  They are what `foir types` emits as a runtime value, so a client can print a
+  GraphQL document without a schema and without recomputing a selection in a
+  second language. Every field on them is optional on `FoirManifest` and
+  `FoirManifestModel`, because a server that predates trees omits them and a
+  consumer must not assume the shape.
+- **`foirSelections` / `foirNamespaceSelections` / `foirSelectionUnions` on
+  `@foir/sdk/data`** — the runtime contract `foir types` emits against, and the
+  printer that reads it: `planFoirModelCall`, `planFoirNamespaceCall`,
+  `foirRoute`, and the types `FoirSelections`, `FoirNamespaceSelections`,
+  `FoirSelectionUnions`, `FoirSelectionModel`, `FoirSelectionNamespace`,
+  `FoirSelectionSource`, `FoirCall`, `FoirNamespaceCall`, `FoirDocumentPlan`,
+  `FoirRouteDecision`, `FoirRouteInput`, `FoirLane`, `FoirLaneReason`. Plus the
+  manifest's own per-op and selection types — `FoirManifestOpPayload`,
+  `FoirManifestSelection`, `FoirManifestSelectionField`,
+  `FoirManifestSelectionUnion`, `FoirManifestSelectionMember`.
+
+- **The event-log client on `@foir/sdk/server`** (TTS-983) — `createEventsClient`,
+  cursor-resumable consumption of a project's durable event history over
+  `GET /v1/events`. `list()` returns one page; `stream()` pages forward to the
+  current end of the log and yields events, each carrying the `seq` that is the
+  durable cursor.
+
+  Also `FoirEventCursorExpiredError` and `isFoirEventCursorExpired` for the
+  retention refusal, the constants `FOIR_EVENTS_PATH`, `FOIR_EVENTS_SCOPE` and
+  `FOIR_EVENTS_RETENTION_DAYS`, and the types `FoirEvent`, `FoirEventActor`,
+  `FoirEventPage`, `FoirEventRetention`, `FoirEventsClient`,
+  `FoirEventsClientConfig`, `FoirEventsListParams`, `FoirEventsStreamParams`.
+
+  **On `@foir/sdk/server` and no other subpath, deliberately.** The event log is
+  an OPERATOR surface (DECIDED 2026-08-04, TTS-981): reachable by an `sk_` key or
+  an admin session, never by a customer token, and `events:list.project` is not
+  mintable on a `pk_` key at all. `events.view` is plain tenant+project
+  containment while `record.view` carries owner/grantee/borrow terms on top, so a
+  containment-only read over the log describes rows whose records the same caller
+  could not read — and each row's `actor` names which *other* customer acted.
+  `createEventsClient` therefore throws on a `pk_` key and on an `Authorization`
+  header rather than letting either reach the wire, and an import-graph test
+  fails if the module becomes reachable from a subpath that ships to a browser.
+
+  Requires foir-io/platform#757 to be deployed. Against an api-public without it,
+  `GET /v1/events` 404s.
+
+- **The package error taxonomy on `@foir/sdk/server`** — `FoirRequestError`,
+  `isFoirRateLimited`, `isFoirUnauthenticated`, `isFoirForbidden`,
+  `isFoirNotFound`, and the `FoirErrorCode` / `FoirErrorExtensions` /
+  `FoirGraphQLErrorItem` types, re-exported from `@foir/sdk/client` so an
+  events-client consumer classifies failures without importing a second subpath.
+  Same classes, not copies.
+
+- **The whole auth surface on `@foir/sdk/auth`.** Password management, email
+  verification and account lifecycle were reachable NOWHERE in the package — a
+  storefront doing "forgot password" had to drop to hand-written GraphQL, which
+  is the entire cost of GraphQL paid for one screen. Ten root fields closed:
+
+  `getAuthConfig`, `getDefaultAuthProvider`, `currentUser`, `myProviderToken`,
+  `customerLogout`, `customerRequestPasswordReset`, `customerResetPassword`,
+  `customerUpdatePassword`, `customerVerifyEmail`, `deleteMyAccount`.
+
+  Plus the session-layer pairings for the flows that need one:
+  `resetPasswordAndSignIn` (redeem the emailed token and persist the session it
+  mints — the peer of `loginWithPassword` for the branch where the customer
+  cannot log in), `signOut` (revoke server-side, then clear locally, and clear
+  locally even if the revoke fails), and `authedOp` (`authedRequest`'s twin for
+  auth ops: refresh once, retry once, on a 401-shaped failure).
+
+  And the vocabulary: `AUTH_OPS`, `AuthOpName`, `AuthOpOptions`, with the result
+  types `AuthConfig`, `AuthConfigProvider`, `DefaultAuthProvider`, `CurrentUser`,
+  `ProviderToken`, `DeleteAccountResult`.
+
+  Requires an api-public that publishes the full `auth` namespace in
+  `GET /v1/manifest`. Against an older one every auth call is refused with
+  `operation "…" is not available in namespace "auth" for this credential`, so
+  **the platform change deploys first**.
+
+### Removed
+
+- **The nine auth operation documents on `@foir/sdk/auth`** —
+  `CustomerLoginDocument`, `CustomerRegisterDocument`,
+  `CustomerRefreshTokenDocument`, `CustomerRequestOTPDocument`,
+  `CustomerLoginOTPDocument`, `CustomerLoginWithProviderDocument`,
+  `CustomerProviderCallbackDocument`, `CustomerProviderVerifyOTPDocument`,
+  `AuthProvidersDocument`.
+
+  **Breaking, so the next release is a MINOR** per the pre-1.0 note above.
+
+  *Why.* They were a second wire protocol for one substrate inside one package:
+  hand-written GraphQL posted to `/graphql` while every other typed call in the
+  SDK went through the op transport. That split is what produced the gap above —
+  the hand-written set covered nine root fields and nobody noticed the other
+  eleven were unreachable. The flows now address the server's generated `auth`
+  namespace, so `@foir/sdk/auth` carries no transport of its own.
+
+  *Migration.* Nothing that called a FUNCTION changes: `customerLogin(env, …)`,
+  `getAuthProviders(env)`, `loginWithPassword(adapter, env, …)`, `refreshSession`,
+  `requireAuth`, `authedRequest` and every React hook in `@foir/sdk/react` keep
+  their exact signatures. Only code importing a `*Document` const is affected,
+  and only if it was executing the document itself through its own GraphQL
+  client. Two options:
+
+  - call the SDK function instead (`customerLogin(env, vars)` rather than running
+    `CustomerLoginDocument` through Apollo/urql), which is what the exports were
+    for; or
+  - keep your own client and write the document in your own codebase — these are
+    fixed-shape platform operations, so the text does not vary by project.
+
+  `authedRequest` is unchanged and still takes a `TypedDocumentNode`: it exists
+  for the project's OWN operations, whose shape the SDK cannot know.
+
+- **`graphql` from `@foir/sdk/auth`'s path.** The removed documents were
+  `parse()`d at module load, which no bundler could tree-shake, and that is the
+  reason `@foir/sdk/auth/session` had to exist as a separate graphql-free door.
+  The subpath stays — it is a published surface and consumers import it — but it
+  is no longer the only graphql-free way into this package.
+
+---
+
+## [0.7.0] — 2026-08-08
+
+Everything additive, so a MINOR per the pre-1.0 note.
+
+Ships 0.6.0 with it. That version was cut in the changelog and in
+`package.json` on 2026-07-27 but no `sdk-v0.6.0` tag was ever pushed, and the
+tag is what publishes, so npm went straight from 0.5.0 to here. The 0.6.0
+section below is left as written rather than folded in, so the history says what
+actually happened.
+
+### Added
+
+- **Failure classification on `@foir/sdk/client`** — `isFoirRateLimited`,
+  `isFoirUnauthenticated`, `isFoirForbidden`, `isFoirNotFound`, plus `code`,
+  `requestId`, `retryable` and `retryAfterMs` on `FoirRequestError`, and the
+  `FoirErrorCode` / `FoirErrorExtensions` types behind them.
+
+  `FoirGraphQLErrorItem` now carries `extensions`, which is what makes any of
+  this possible: the platform has been sending `extensions.code` on every
+  rejection and the SDK's error type had nowhere to put it, so the only way to
+  tell one failure from another was to match the message.
+
+- **Retry, on by default, in `createFoirContentClient`** — `withFoirRetry` and
+  `foirRetryDelayMs` are exported for callers running their own loop.
+
+  It covers no-response, `5xx`, and **`429`**. The last one is the reason this
+  is in the SDK rather than in a docs snippet. A 429 sits among the 4xx statuses
+  that are permanent, so the rule everyone writes — retry 5xx, never retry 4xx —
+  excludes the one failure in that family that clears on its own. A storefront
+  wrote exactly that rule; when its key saturated, every read failed on the
+  first attempt for an hour and the site served empty pages while the API was
+  healthy.
+
+  A server-stated `Retry-After` wins over backoff, capped by `maxDelayMs`
+  (default 20s) so an hour-long window does not block a render. Opt out with
+  `retry: { attempts: 1 }`.
+
+- **`onRateLimit`** on `createFoirContentClient` and on `FoirRequestOptions`,
+  with `readFoirRateLimit` and the `FoirRateLimitSnapshot` type. Called with the
+  `X-RateLimit-*` headers of every response, so an app can log that a key is
+  approaching its ceiling instead of finding out when it hits one.
+
+- **New subpath `@foir/sdk/auth/session`** — `createFoirSessionClient` and its
+  types (`FoirSessionClient`, `FoirSessionConfig`, `FoirSessionUser`) on their
+  own, without the rest of `./auth`.
+
+  Purely additive: `./auth` keeps exporting all four, unchanged, and nothing is
+  moved or renamed. What changes is the cost of reaching them. `./auth` also
+  exports the customer-auth GraphQL documents, which build their
+  TypedDocumentNodes with a top-level `parse()` that no bundler can treat as
+  pure — so a browser app importing only `createFoirSessionClient` was shipping
+  the whole `graphql` package to get it. `src/auth/session-client.ts` imports
+  nothing at all, and this subpath bundles it alone.
+
+  Like `./data`, it adds **no dependency and no peer dependency**:
+  `dist/auth-session.js` has no imports. An app on this subpath needs `graphql`
+  neither installed nor bundled. Use `./auth` when you want the login /
+  register / OTP / provider flows too; use this one for a backend-less SPA whose
+  only credential is the Fóir-hosted session cookie.
+
+- **New subpath `@foir/sdk/data`** — the typed data client (TTS-874).
+  `createFoirClient<FoirSchema>({ apiUrl, apiKey })` gives `foir.<model>.<op>(…)`,
+  `foir.ns.<namespace>.<op>(…)` and an untyped `foir.raw(op)`. The client's surface is shaped by the credential: an op that
+  is not in that key's manifest is not on the type, so `foir.page.create(…)`
+  under a `pk_` key is a compile error rather than a 400.
+
+  Selection is complete-by-default — every scalar always arrives, so the model
+  type is unconditionally true — with `include` to opt into relations and
+  `omit` to drop a heavy field. `_id` is not omittable, matching the server.
+
+  **This subpath has no `graphql` dependency**: it imports neither `graphql`,
+  `@graphql-typed-document-node/core` nor `@graphql-codegen/*`, and adds no new
+  peer dependency, required or optional. `dist/data.js` has no imports at all.
+
+  New exports on `./data`: `createFoirClient`, `createFoirClientFromEnv`,
+  `fetchFoirManifest`, `foirDataEndpoint`, `FoirRequestError`, and the type
+  surface (`FoirSchemaDefinition`, `FoirModelDefinition`,
+  `FoirRelationDefinition`, `FoirOpDefinition`, `FoirReturnDefinition`,
+  `FoirNamespaceDefinition`, `FoirNamespaceOpDefinition`, `FoirFieldsShape`,
+  `FoirConnection`, `FoirClient`, `FoirClientCore`, `FoirClientConfig`,
+  `FoirModelClient`, `FoirNamespaceClient`, `FoirModelOperation`,
+  `FoirNamespaceOperation`, `FoirQuery`, `FoirInclude`, `FoirOmittableKey`,
+  `FoirRecordResult`, `FoirOpResult`, `FoirRawOp`, `FoirSchemaDrift`,
+  `FoirManifest` + its members, and `FoirEnv` / `FoirGraphQLErrorItem` /
+  `FoirTokenProvider` re-exported for `./data`-only consumers).
+
+  Additive, so a MINOR bump at release time. No existing subpath's surface
+  changed — the export snapshot diff for this change is one new subpath and
+  nothing else.
+
+### Changed
+
+- Internal only, no public surface change: the `graphql`-free half of
+  `src/graphql/foir-request.ts` moved to `src/transport/foir-http.ts` so
+  `./data` and `./client` share one header builder and one `FoirRequestError`
+  rather than forking the transport. `@foir/sdk/client` re-exports every symbol
+  it exported before, unchanged, and `FoirTokenProvider` is now declared in the
+  shared module and re-exported from its old home.
+
+---
+
+## [0.6.0] — 2026-07-27
+
+First release since the public surface was pinned. Everything in it is
+additive, so per the pre-1.0 note this is a MINOR: `^0.5.0` will not pick it up
+on its own, which is the intended behaviour for a release that adds exports.
+
+### Added
+
+- `@foir/sdk/auth`: `customerSignupContext` and `customerJoinWaitlist`, plus the
+  `SignupContext`, `SignupMode` and `WaitlistJoinResult` types — waitlist and
+  restricted-signup flows for projects that are not open-registration.
+- A pinned public-export surface: `public-exports.snapshot.json` plus
+  `scripts/assert-public-exports.mjs`, wired into `pnpm build`. Deleting a named
+  export previously passed the full SDK CI lane — 125 tests and the export-map
+  guard all green — because nothing checked the contents of the declared files,
+  only that they existed.
+- This changelog, and the semver policy above.
+
+### Changed
+
+- Type declarations are emitted by a dedicated `tsc --emitDeclarationOnly` pass
+  instead of `tsup`'s built-in `dts`, whose parallel rollup workers
+  intermittently failed to flush a subpath's `.d.ts`; consumers saw
+  "Could not find a declaration file for module '@foir/sdk/realtime'".
+  `scripts/assert-export-types.mjs` now fails the build if any file the export
+  map promises is missing. No change to the public surface.
+- The test suite pins `NODE_ENV=test` so an inherited `NODE_ENV=production`
+  cannot load React's production build and break every render test. Internal.
+
+---
+
+## [0.5.0] — 2026-07-15
+
+### Added
+
+- `@foir/sdk/client`: `createFoirContentClient` — forwards the customer bearer
+  token on content reads, so authenticated and segment-targeted content works
+  without hand-rolling the header.
+
+## [0.4.0] — 2026-07-12
+
+### Added
+
+- `@foir/sdk/auth`: `createFoirSessionClient`, plus the `FoirSessionClient`,
+  `FoirSessionConfig` and `FoirSessionUser` types — Foir-hosted first-party
+  sessions for backend-less SPAs, over the `fetchHostedSession` /
+  `hostedLoginUrl` hosted-login bridge that already shipped in 0.1.0 (EID-516).
+
+## [0.3.0] — 2026-07-12
+
+### Added
+
+- **New subpath `@foir/sdk/react`** — drop-in React customer auth: `FoirProvider`,
+  `SignIn`, `OAuthButtons`, `UserButton`, `useFoirAuth`, `useFoirSession`,
+  `useFoirUser` (EID-515).
+- **New subpath `@foir/sdk/next`** — Next.js App Router BFF auth adapter: cookie
+  session store, `createFoirMiddleware`, server-side sign-in/out actions and the
+  provider callback handler (EID-515).
+
+## [0.2.0] — 2026-07-10
+
+### Added
+
+- **New subpath `@foir/sdk/push`** — native Web Push (VAPID) enrolment:
+  `enableWebPush`, `disableWebPush`, `isWebPushSupported`.
+- `@foir/sdk/server`: `requireScopedToken` — a one-line ingress guard for
+  operation BFF routes, over the existing `verifyScopedToken` (EID-498).
+
+## [0.1.0] — 2026-06-23
+
+First public release. Ten subpaths:
+
+- `@foir/sdk` — editor iframe client: `EditorProvider`, `useEditor`, the
+  host↔editor message protocol, and `createPlatformClient` (EID-88, EID-91).
+- `@foir/sdk/server` — server-side platform helpers for config API backends:
+  `createServerClient`, scoped-token verification, `verifyWebhookSignature`.
+- `@foir/sdk/client` — React-free GraphQL transport for SSR/edge (`foirRequest`).
+- `@foir/sdk/media` — progressive media components and adapters (EID-94).
+- `@foir/sdk/content` — `createContentRenderer` and `RichTextRenderer` with
+  injected typography tokens (EID-93).
+- `@foir/sdk/auth` — customer auth flows, token lifecycle, hosted-login bridge
+  (EID-95).
+- `@foir/sdk/realtime` — `createCollabSession`, a thin y-websocket helper
+  (EID-103, EID-104).
+- `@foir/sdk/codegen`, `@foir/sdk/codegen/block-registry`,
+  `@foir/sdk/codegen/block-scaffold` — the `foirCodegen` preset and the
+  graphql-codegen plugins (EID-92).
+
+---
+
+### A note on the backfilled entries
+
+`@foir/sdk` shipped 0.1.0 through 0.5.0 with no changelog. The five sections
+above were reconstructed after the fact from sources that can be re-checked:
+the `sdk-v*` git tags, the `packages/sdk/package.json#exports` map read at each
+of those tags, the commits between consecutive tags that touch `packages/sdk/`,
+and the npm registry's publish timestamps (`npm view @foir/sdk time`), which is
+where the dates come from.
+
+They are **headline-level, not exhaustive**. They record subpath additions and
+the named feature of each release; they do not claim to list every symbol added,
+because no per-symbol record was kept at the time and reconstructing one would
+mean guessing. Nothing above is asserted that could not be read out of the tags
+and the commit history.
+
+`Unreleased` and every section after it are authored at the time of the change
+and are exhaustive for the public surface, which is what the export-surface
+guard exists to keep true.
+
+[Unreleased]: https://github.com/foir-io/clients/compare/sdk-v0.5.0...dev
+[0.5.0]: https://github.com/foir-io/clients/compare/sdk-v0.4.0...sdk-v0.5.0
+[0.4.0]: https://github.com/foir-io/clients/compare/sdk-v0.3.0...sdk-v0.4.0
+[0.3.0]: https://github.com/foir-io/clients/compare/sdk-v0.2.0...sdk-v0.3.0
+[0.2.0]: https://github.com/foir-io/clients/compare/sdk-v0.1.0...sdk-v0.2.0
+[0.1.0]: https://github.com/foir-io/clients/releases/tag/sdk-v0.1.0