@foir/sdk 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -106,6 +106,860 @@ Changes on `dev` that have not been published to npm.
 
 ---
 
+## [0.9.0] — 2026-08-20
+
+Everything additive, so a MINOR either way under the pre-1.0 note.
+
+### Added
+
+- **`hostedLogoutUrl(config, clientId, returnTo?)` on `./auth`** — the mirror of
+  `hostedLoginUrl`, and the only thing that actually signs a customer out on the
+  hosted-cookie flow.
+
+  Login on that flow is symmetric across browser and server; logout was not.
+  The apex `foir_customer_session` cookie is the durable credential, and
+  disposing of a bearer, clearing a local session, or calling the
+  `customerLogout` mutation all leave it in place — the next request
+  re-establishes the customer from it. The only surface that ended a session was
+  `POST /session/logout`, cookie-authenticated and CSRF-header-gated, which only
+  a browser sending `credentials: 'include'` can reach.
+
+  This is a URL builder: no transport, no CORS surface, no CSRF header, no
+  JavaScript required. Server-side logout becomes
+  `return redirect(hostedLogoutUrl(config, clientId, returnTo))`. `returnTo`
+  must be absolute and on an origin registered for `clientId`.
+
+  Requires the platform's `end-session` endpoint (TTS-1534). `HostedLoginConfig`
+  gains an optional `endSessionPath`, defaulting to `/session/end-session`.
+
+- **`Prose`, `Passage`, `ProseSpan` and `RecordAncestor` on `./data`.** The
+  shapes a prose field and the record hierarchy resolve to, shipped here
+  rather than generated per project because they are identical everywhere —
+  the same reason `Image` and `Reference` live here.
+
+  `Prose<E>` is parameterised on its entries element: `Prose<Passage>` for a
+  text-only field, `Prose<Cta | Passage>` for one that admits embeds. `foir
+  types` fills the parameter in from the field's own member set.
+
+- **`FoirManifestStructural`, and `structurals` on `FoirManifestModel`.** The
+  manifest's bucket for a platform-owned object with no model behind it — a
+  prose wrapper, an `ancestors` list. Absent on a server that predates it,
+  where those fields landed in `unclassifiedFields` and dropped out of the
+  selection entirely; widen on absent.
+
+---
+
+## [0.8.0] — 2026-08-20
+
+**BREAKING** — see `foir.raw()` under "Changed". A MINOR, per the pre-1.0
+note above.
+
+> Filed after the fact. 0.8.0 was published with a version bump and no
+> changelog entry, so everything below sat under "Unreleased" while it was
+> already on npm. Recorded here rather than left there, because a consumer
+> upgrading from 0.7.0 has no other account of what changed.
+
+### 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.
@@ -166,10 +1020,9 @@ actually happened.
   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 over
-  `POST /v1/query` (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
+- **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.