@foir/sdk 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -104,6 +104,699 @@ on `dev` would publish unreviewed work to npm.
 
 Changes on `dev` that have not been published to npm.
 
+## [0.11.0] — 2026-09-26
+
+Breaking changes under the pre-1.0 note, so this release is a MINOR:
+`OperationPayload` now describes the body the platform actually sends,
+`FoirClientConfig` is a union of two credentials, a record write resolves to
+`FoirWriteResult`, an option field's union is its declared values, and the
+generated module, the drift check and `FoirSchemaDrift` are keyed on the
+surface version instead of the schema counter.
+
+### Added
+
+- The data client takes an operation's dispatch token as its credential, so an
+  operation endpoint calls Foir AS the operation and holds no key.
+
+  ```ts
+  import { createFoirClient } from '@foir/sdk/data';
+  import { readDispatch, requireScopedToken } from '@foir/sdk/server';
+  // foir types --operation checkout --out src/checkout.generated.ts
+  import * as generated from './checkout.generated';
+
+  export async function POST(request: Request) {
+    const { dispatch } = await requireScopedToken(request, {
+      expectedProjectId: process.env.FOIR_PROJECT_ID,
+    });
+    const { input } = await readDispatch<{ email: string }>(request);
+    const foir = createFoirClient({ apiUrl: process.env.PLATFORM_API_URL!, dispatch, generated });
+    // ...
+  }
+  ```
+
+  A dispatch client requires `generated`, and only a module generated for an
+  operation: `foir types --operation <key>` types the surface that operation's
+  token is served (`GET /v1/manifest?operation=<key>`) and exports
+  `foirCredential` naming it. A key client refuses such a module, a dispatch
+  client refuses a key's module, and a dispatch whose `X-Foir-Context` names
+  another operation than the module is refused, each at the type and at
+  construction. New on `@foir/sdk/data`: `FoirOperationCredential`,
+  `FoirKeyGeneratedModule` and `FoirOperationGeneratedModule`.
+
+  A client built with `dispatch` sends the token as `X-Foir-Token`, with the
+  dispatch's `X-Foir-Context`, and never sends `x-api-key`. api-public accepts
+  the token as a caller in its own right and builds the schema from the
+  capabilities the operation declared, so the generated client works unchanged
+  over it: queries, mutations and `execute<Op>`. `dispatch.token` is a provider
+  read before every request, not a string captured once. There is no key
+  fallback: a provider that yields nothing fails the request.
+
+  New on `@foir/sdk/data`: `FoirDispatchCredential`, `FoirKeyClientConfig` and
+  `FoirDispatchClientConfig`. New on `@foir/sdk/server`: `dispatch` on the
+  result of `requireScopedToken`, which is the token it verified as a ready
+  credential.
+
+  Two things a dispatch client does not do. It does not subscribe: the
+  subscription socket authenticates a key, an admin token or a customer bearer
+  and has no path for a dispatch token, so `onChange` and friends throw, naming
+  why. And it takes no key-side option (`apiKey`, `bearerToken`, `orgId`,
+  `channel`, the socket options), because the token carries its own customer,
+  organization and channel; each is a compile error and a runtime refusal.
+
+- `readDispatch(request)` and `OperationPayloadError` on `@foir/sdk/server`.
+
+  An operation endpoint had no typed reader for its own dispatch, and the body
+  is the run, not the input: reading it as the input finds nothing and refuses
+  every call on a missing field. `readDispatch` parses the body into
+  `OperationPayload`, checks the fields that identify a dispatch, and refuses
+  anything else with `OperationPayloadError` (`status` 400), naming what is
+  wrong. It keeps every key the platform sent, typed or not. `input` is always
+  an object: a run started with no input, which the platform sends as `null`,
+  reads as `{}`.
+
+- `FoirWriteResult<R>` on `@foir/sdk/data`: `{ record, replayed }`, what a
+  record write answers with.
+
+- `fetchFoirManifest(config, { operation })` asks for the surface an
+  operation's dispatch token is served instead of the credential's own, which
+  is described to a key that can author the operation (`operations:write`).
+  `fetchFoirManifest` takes `FoirRequestConfig`, the credential and transport
+  half of a client config, so a manifest is fetched without a generated module;
+  `FoirManifestRequestOptions` and `FoirRequestConfig` are new on
+  `@foir/sdk/data`.
+
+- `FoirRecordOwner` on `@foir/sdk/data`: `{ id, ownerId, ownerKind }`, what
+  `setOwner` answers with. An operation that declares `records:attribute:<model>`
+  hands a record to another customer with `foir.<model>.setOwner({ id, ownerId })`,
+  and names the owner of a record it creates with `create({ input, ownerId })`.
+  The answer carries the owner and not the record, because an operation acting
+  for the previous holder may no longer read it.
+
+- `orgUrl` names the organization a client acts in by the address of the page
+  it is for, sent as `X-Org-Url`, beside `orgId`. An app serving many
+  organizations from its own addresses (a path each, a subdomain each, or a
+  domain an organization brought) passes the page URL with the publishable key
+  it already ships, and the server finds the organization whose registered
+  address is the longest prefix of that URL. Also on `FoirRequestOptions` and
+  the auth ops' options. A URL no organization's address covers answers
+  `NOT_FOUND` as an unknown `orgId` does, and a request naming one takes the
+  origin lane.
+
+  ```ts
+  const foir = createFoirClient({ apiUrl, apiKey, generated, orgUrl: window.location.href });
+  ```
+
+  The same answer is available up front as the `resolveOrganizationAddress(url)`
+  query.
+
+### Changed
+
+- `requestOperation` (the editor SDK) no longer gives up after 60 seconds. A
+  blocking operation is now a direct call the platform ends at the operation's
+  own timeout, and the host answers every request with that outcome, so the
+  editor's own clock could only report as failed an operation that went on to
+  complete. The promise settles when the host answers.
+
+- **Breaking (types).** `OperationPayload` matches the platform's
+  `buildOperationPayload` field for field. Code that read a field the platform
+  never sent now fails to compile, which is the point:
+
+  - `credentials` and `config` are removed. The platform stopped sending them
+    when scoped-token dispatch replaced credentials in the body; an app reads
+    its secrets through the dispatch token.
+  - `executionId` is required. It is always sent.
+  - `content`, `record`, `triggerContext` and `callback` are optional and are
+    absent, never `null`, when not sent. `content` is an object.
+  - `OperationRecordContext` is `Record<string, unknown>`. The platform forwards
+    the block as the caller wrote it and shapes none of it; the previous `data`
+    and `metadata` members were never guaranteed.
+  - `OperationTrigger` is `{ type: 'ui' | 'api' | 'lifecycle' | 'schedule' }`,
+    the platform's own four values. `fieldKey`, `fieldType` and the `field`
+    trigger were never sent; caller context arrives in `triggerContext`.
+  - `OperationContext.userId` is a string that is always present (empty for a
+    hook's run), and `locale` is removed.
+  - `OperationPayload` takes a type parameter for `input`.
+  - `callback` is documented as ASYNC only. A blocking (SYNC) dispatch carries
+    no callback: the endpoint's response body is the result. `callback` gains
+    `causationChain`.
+
+- **Breaking (types).** `FoirClientConfig` is `FoirKeyClientConfig |
+  FoirDispatchClientConfig`. A config literal with an `apiKey` is unchanged.
+  Code that `extends FoirClientConfig` in an interface should extend
+  `FoirKeyClientConfig`, and code that reads `config.apiKey` off a
+  `FoirClientConfig` sees `string | undefined`.
+
+- A client with `dispatch` refuses a credential header in `headers`
+  (`x-api-key`, `Authorization`, `X-Foir-Token`, `X-Foir-Context`), whatever its
+  case. A key client's `headers` are unchanged.
+
+- `fetchFoirManifest` resolves the credential before the request rather than
+  inside it, so a `bearerToken` provider that throws surfaces its own error
+  instead of `[foir] network error`, as it already did on `/graphql`.
+
+- **`create`, `update` and `rename` resolve to `FoirWriteResult`, not the
+  record.** The data API's `create<Model>`, `update<Model>` and
+  `rename<Model>` now return `<Model>WritePayload`, the record beside
+  `replayed`, and a typed call returns that payload as it came. `replayed` is
+  true when the call's `idempotencyKey` was already used by an earlier attempt
+  of the same write: nothing was written this time, and `record` is as the
+  first attempt left it. Read the record from `.record`:
+
+  ```ts
+  const { record, replayed } = await foir.order.update({ where, data, idempotencyKey });
+  if (replayed) {
+    // The first attempt's answer. Nothing was applied by this call.
+  }
+  ```
+
+  A generated schema types these ops as `{ kind: 'write' }`; re-run
+  `foir types`.
+
+- `FoirUpdateManyPayload` carries `replayed`, with the same meaning.
+
+- **An option field's generated union is the declared values.** The data API
+  serves an option value exactly as the config declares it (`orderSlip`, not
+  `ORDERSLIP`), so the union `foir types` prints from the manifest is the
+  config's own strings. Re-run `foir types`; a comparison against the
+  upper-cased names no longer type-checks, and never matched a stored value.
+
+- **Schema drift compares the surface version, not the schema counter.**
+
+  `GET /v1/manifest` now serves `surfaceVersion`: a hash over exactly the
+  sections `foir types` reads, so it moves if and only if regenerating the types
+  would write a different file. Beside it, `surfaceHashes` carries the
+  components that version is folded from, one per model, namespace, union
+  expansion and the subscriptions. `schemaVersion` stays on the manifest and
+  keeps meaning what it always did server-side: the invalidation counter that
+  keys the ETag and the response cache.
+
+  The client used to pin generated types to that counter. Every write that
+  could change a response bumps it, so pushing an operation, a role or a key
+  reported drift, and under the strict default the next typed call threw,
+  though nothing the client prints had moved. A false alarm and a real one had
+  the same remedy, so nobody learned which they had. Now a drift is reported
+  only when the surface moved, and it names what moved: "Changed since: model
+  `page`." Every drift is real, so the message says `foir types` and no longer
+  suggests `strictSchemaDrift: false`, which is never the remedy.
+
+  What changes for a caller:
+
+  - The generated module exports `foirSurfaceVersion` and `foirSurfaceHashes`
+    in place of `foirSchemaVersion`, and `FoirGeneratedModule` requires them. A
+    module generated before this is refused at construction by name. **Re-run
+    `foir types`** with a current `@foir/cli` as part of the upgrade.
+  - `createFoirClient`'s `schemaVersion` option is now `surfaceVersion`, with
+    `surfaceHashes` beside it. Only a client wired field by field sets them;
+    one passing `generated` gets both from the module.
+  - `FoirSchemaDefinition.schemaVersion` is now `surfaceVersion: string`.
+  - `FoirSchemaDrift.generated` and `.server` are the two surface versions, as
+    strings, and `.changed` lists the components that moved (`models.page`).
+    An `onSchemaDrift` handler logging the numbers logs the hashes instead.
+  - `foirDriftIsActionable` (`@foir/sdk/live`) treats any difference as
+    actionable: a hash has no ahead or behind, and a rollback is another
+    surface like any other.
+  - `FoirManifest` gains `surfaceVersion` and `surfaceHashes`.
+
+---
+
+### Fixed
+
+- A response in which no root field answered now throws `FoirRequestError`
+  with the server's errors. It used to count as partial data. Every
+  `execute<Op>` payload is nullable, so a failed operation run came back as
+  `{ r: null }` beside its error, and the typed call resolved to `null` with the
+  refusal only logged. The partial-errors default is unchanged wherever at least
+  one root field answered, and a null root with no error is still an answer.
+
+## [0.10.0] — 2026-09-22
+
+Two breaking changes under the pre-1.0 note, so a MINOR: `fetchHostedSession`
+returns a result object rather than `HostedSession | null`, and
+`operations.onExecution` delivers `status` as the enum name.
+
+### Added
+
+
+- `composedFor` on `FoirManifest`: the organisation whose composition the
+  manifest describes, absent for the project's own surface.
+
+  A key confined to an organisation is served that organisation's surface by
+  `GET /v1/manifest` without naming it, so nothing in the payload, or in a
+  module generated from it, said whose definitions it carried. `foir types`
+  records it in the generated header and `foir explain` prints it. Optional and
+  additive: a project manifest is unchanged, and no export was added.
+
+- A subscribing client no longer fetches `GET /v1/manifest`.
+
+  `foir types` now emits `foirSubscriptions` alongside the model trees, and
+  `createFoirClient` prints subscribe documents from it. Previously `generated`
+  carried model trees only, so passing the module was strictly *worse* for a
+  subscribe-only client: the bundle cost, and the round trip anyway.
+
+  `foirSubscriptions` is optional on the generated module and is deliberately
+  not part of the strict export check — a module generated before it existed
+  keeps working and keeps fetching, which is what it did before. Re-run
+  `foir types` to pick it up.
+
+- `FoirSchemaDriftError` on `@foir/sdk/data`, and `strictSchemaDrift` on
+  `createFoirClient` to turn it off.
+
+  **Behaviour change.** Typed calls now THROW once schema drift is detected,
+  where they previously warned and served the stale shape. An app that upgrades
+  while holding a stale `foir.generated.ts` will start throwing on the second
+  and subsequent calls — re-run `foir types` as part of the upgrade. Pass
+  `strictSchemaDrift: false` to keep the old warn-and-serve behaviour.
+
+  The client already detects that its generated selection trees are older than
+  the schema the server is serving, and warns. The warning is easy to scroll
+  past, and what it is warning about is not a typing problem: the trees are what
+  the client PRINTS ITS QUERIES FROM, so a field added since generation is not
+  merely untyped, it is not requested. It arrives as absent data and reads as a
+  bug in the app.
+
+  That is the lax half of an asymmetry. An unknown ARGUMENT is refused
+  client-side before the server sees it; a missing field is silent. Set
+  `strictSchemaDrift: true` and typed calls throw `FoirSchemaDriftError` once
+  drift is detected, naming `foir types` as the fix.
+
+  Two deliberate exemptions. It never fails the FIRST call — drift is only known
+  once the manifest comes back, which happens off the response path after a call
+  has been served, and blocking every first call on a second round trip is the
+  cost the warning exists to avoid. And it never touches `raw()`, because a
+  hand-written document asks for exactly the fields it names and cannot silently
+  omit one.
+
+  On by default, because the failure it prevents is silent: a stale selection
+  omits a field rather than complaining, so an opt-in guard would only protect
+  the people who already suspected it. Opting out is written at the call site
+  where a reader can see it, rather than inferred from an environment variable.
+
+- `graphql()` and `TypedFoirDocument` on `@foir/sdk/data`: a GraphQL document
+  that carries its own result and variable types.
+
+  ```ts
+  const RECENT = graphql<{ pages: { totalCount: number } }, { n: number }>(
+    'query Recent($n: Int) { pages(first: $n) { totalCount } }',
+  );
+  const { pages } = await foir.raw(RECENT, { n: 5 }); // pages is typed
+  ```
+
+  `raw` returns `unknown`, so every call site hand-writes a result type that
+  nothing checks, and the sites that most need type safety are exactly the ones
+  the typed client could not express. Two real bugs came from a result type that
+  had drifted from the selection it claimed to describe. A branded document does
+  not make a bespoke selection type-checked against the schema, which is the
+  larger half and wants generated documents rather than a helper. What it removes
+  is the retyping: the assertion moves from every call site to one place beside
+  the document, and a wrong one is wrong where a reader is looking at the query.
+
+  Nothing changes for a caller passing a plain string. `raw('...')` still returns
+  `unknown` and `raw<T>('...')` still returns `T`. `graphql()` is a cast and
+  returns the string it was given, so a branded document can be logged, hashed or
+  sent anywhere a string goes.
+
+- `FoirRawOptions` on `@foir/sdk/data`, and a third argument to `foir.raw()`:
+  `raw(document, variables, { strict: true })`.
+
+  A GraphQL response can carry `errors` and `data` together, and the SDK warns
+  and returns the data. That stays the default, and it is the right one for a
+  served page: a field the server could not resolve should not blank the whole
+  render. On a hand-written document it is also how a wrong selection stays
+  invisible — there is no generated selection to have caught a bad field name
+  first, so selecting something that does not exist returns everything else and
+  logs, and the hand-written result type asserts the shape was fine.
+
+  `strict: true` makes that a thrown `FoirRequestError` instead. The error
+  carries the data it refused on `partialData`, so opting in does not trade a
+  silent wrong answer for a thrown one that discards the answer. Nothing changes
+  for a caller that does not pass it.
+
+- `registerOrganization(env, { key, name }, { bearerToken })` on `@foir/sdk/auth`: a customer founds an organization of their own and becomes its first member, holding the role the project's `operatorSignupRole` setting names. Returns the same `MyOrganization` entry `myOrganizations` lists. Present on the wire only while the project's `operatorSignupEnabled` setting is on.
+- **The operator's organization context, on `@foir/sdk/auth`** — `myOrganizations`
+  and `selectOrganization`, plus the types `MyOrganization` and
+  `SelectedOrganization`, and two entries on `AUTH_OPS`.
+
+  A Fóir project can be partitioned into organizations, one per tenant of a SaaS
+  built on Fóir. An *operator* is a customer who runs one or more of them.
+  `myOrganizations()` answers which ones this customer may stand in — from their
+  own membership rows, so it is not the project's inventory and cannot be used as
+  one — and `selectOrganization({ orgId })` says which. An empty `orgId` clears
+  the selection.
+
+  **Set once, not per call.** No read or write in this SDK takes an `orgId`
+  argument: the claim the row layer filters on is resolved server-side from the
+  caller's membership on every request. An application therefore cannot forget
+  to send it, cannot send another organization's, and cannot be made to cross
+  the boundary by a query it built wrong. These two functions are the entire
+  per-customer surface; everything downstream names no organization at all.
+  (The project credential's side of the same boundary is the client-level
+  `orgId` option below — a property of the client, still never of a call.)
+
+  Requires a server serving `myOrganizations` and `selectMyOrganization` in its
+  `auth` namespace. Against an older api-public both refuse, naming the op.
+
+- **Acting inside an organization with the project credential** — `orgId` on
+  `FoirClientConfig` (`createFoirClient` / `createFoirClientFromEnv`), on
+  `FoirRequestOptions` (`foirRequest`) and on `AuthOpOptions` (the
+  `@foir/sdk/auth` ops), plus `'org'` on `FoirLaneReason`.
+
+  A multi-tenant app holding the PROJECT key has to choose which of its
+  organizations a request is for — after resolving `<sub>.theapp.com` to one,
+  or from the back-office. `orgId` sends `X-Org-Id` on every request the client
+  makes (HTTP, the manifest fetch and the subscription handshake alike). The
+  server resolves it against the credential's OWN project — an unknown,
+  suspended or foreign organization all read `NOT_FOUND` — and binds the
+  request to it; a credential already confined to an organization may only name
+  its own (`PERMISSION_DENIED`), so this cannot steer a storefront key. A read
+  naming an organization always takes the origin lane: the shared lane keys by
+  URL, where the header does not appear.
+
+  Pairs with the `organization` owner plane on a model: a record created on
+  such a model while acting in an organization belongs to it, and the project
+  key with no `orgId` still reads every organization's rows — which is how the
+  host→organization lookup is answered in the first place.
+
+- **Reconcile on reconnect, on `@foir/sdk/live`** — `createFoirReconciler`,
+  `foirHeldRecordIds`, `foirTagsForGoneRecords`, and the types
+  `FoirReconciler`, `FoirReconcilerOptions` and `FoirReconcileResolveFn`. Plus a
+  `reconcile` prop on `<FoirLive>`.
+
+  Required, not optional, on any model whose records are partitioned per caller.
+  The server filters that stream with an inner join against the records the
+  caller can currently read, and records delete hard rather than being flagged —
+  so by the time the join runs for a deletion there is no row to match, and **no
+  event is emitted**. The same silence covers a record whose ownership moved
+  away. Resuming the cursor recovers neither: there was never an event to replay.
+
+  So the client names the ids it holds and asks which are still visible;
+  anything absent is gone. That cannot leak, because the caller supplies the ids
+  — an id it names is one it already had. The manager calls it on every
+  reconnect, after the stream is back rather than before, so nothing deleted
+  mid-reconcile falls between the two halves.
+
+  A resolve that throws ABANDONS the reconcile rather than reporting everything
+  as gone, so a network blink cannot evict a working cache.
+- **Write-token primitives on `@foir/sdk/live`** — `readFoirWriteToken`,
+  `foirWriteTokenHeaders` and `FOIR_WRITE_TOKEN_HEADER`. Plus a `floor` reason
+  and a `writeToken` input on `foirRoute`.
+
+  Reading your own write without throwing the cache away. A mutation returns an
+  opaque token naming where it committed; a later read carries it; the server
+  serves a cached entry only if that entry resolved at or above the write.
+  `Cache-Control: no-cache` gets the same guarantee by discarding every warm
+  entry on the path, whether or not it was already fresh enough.
+
+  A token-bearing read is routed to the ORIGIN, with `floor` as the stated
+  reason. The shared edge has no view of the project clock, so it cannot tell
+  whether what it holds is new enough — and served from there the floor reads as
+  satisfied, which is worse than never asking for one.
+
+  Primitives rather than automatic behaviour: how long a token stands for, and
+  across which of a user's tabs, are application questions this package cannot
+  answer. Guessing gives either a floor that expires before it helps or one that
+  pins reads to the origin long after the write stopped mattering.
+
+- **Cache-tag bridge on `@foir/sdk/next`** — `createFoirTaggingFetch`,
+  `foirCacheTags`, `readFoirCacheTags`, `foirTagsForRecordEvent`,
+  `revalidateFoirRecordEvent`, the constants `FOIR_SURROGATE_KEY_HEADER`,
+  `FOIR_NEXT_TAG_MAX_ITEMS`, `FOIR_NEXT_TAG_MAX_LENGTH` and `FOIR_UNTAGGED_TAG`,
+  and the types `FoirHeaderSource`, `FoirCacheTags`, `FoirCacheTagsOptions`,
+  `FoirTaggingReport`, `FoirTaggingFetchOptions` and `FoirRecordChange`.
+
+  The API already computes which records and collections every cacheable
+  response depends on — it has to, to invalidate its own cache — and ships that
+  set on `Surrogate-Key`. It already streams the events that make them stale.
+  Nothing joined the two. This is the join: tags in on the read, `revalidateTag`
+  out on the event, with a dependency graph computed by the process that
+  actually resolved the query rather than guessed at by a query-key convention.
+
+  `cacheTag` and `revalidateTag` are **injected**, never imported. `cacheTag` is
+  `unstable_cacheTag` on Next 15, needs `experimental.useCache`, and may be
+  renamed or gated differently in 16 — injecting it means the SDK inherits none
+  of that, and nothing under `packages/sdk/src` imports `next`.
+
+  Two behaviours worth knowing before you wire it up. **Over Next's 128-tag
+  limit the per-record tags are dropped entirely**, not truncated: Next's own
+  answer to overflow is a `console.warn` and a silent drop, which leaves the
+  dropped records stale until the entry's TTL with nothing to say which ones
+  they were. Over-invalidating on the coarse tags costs a refetch; truncating
+  loses invalidation permanently. And a response with **no** `Surrogate-Key` at
+  all — a draft read, a preview, a `NO_CACHE` model, a client `no-store`, a
+  traced read — reports `kind: 'untagged'` and is filed under `foir:untagged`,
+  because an entry cached with zero tags can never be invalidated at all.
+
+  Reads the injected `fetch` rather than the transport, which is unchanged.
+- **Coalescing, backpressure and schema-drift invalidation on `@foir/sdk/live`**
+  — `createFoirCoalescer`, `createFoirDriftHandler`, `foirDriftIsActionable`,
+  plus `coalesceWindowMs` / `maxConcurrentRefetches` on `<FoirLive>` and an
+  `invalidate` seam on `applyFoirRecordChange`.
+
+  The invalidation graph is exact, and exact still means N invalidations for N
+  writes. A bulk import or a scheduled publish sweep fires a burst on one model,
+  and a client that refetched each one would spend the burst doing nothing else
+  — on the exact screen a burst is most likely to be watched from. Fifty
+  invalidations of one key inside the window are now one refetch, a burst
+  spanning many keys runs at most four at a time, and a key invalidated again
+  while its refetch is in flight is owed exactly one more, never one per event.
+
+  Schema drift is a different problem with the same remedy. A deploy that
+  renames a field leaves every cached entry perfectly current and quietly wrong:
+  no record changed, nothing is out of order, and the bytes describe a schema
+  that no longer exists — until the tab is reloaded, which on a long admin
+  session can be days. `createFoirDriftHandler` wires the `FoirSchemaDrift` the
+  data client already reports to a full clear.
+
+- **`@foir/sdk/live/react`** — `<FoirLive>`, `useFoirLive`, `useFoirLiveStatus`.
+  One socket, refcounted per model: the first component to say
+  `useFoirLive('product')` opens the stream, the last to unmount closes it, and
+  N watchers of a model cost one subscription.
+
+  An **adapter**, not a store. You keep the query library you have and it owns
+  your data; what this owns is which entries a change invalidates. The query
+  client is structurally typed, so `@tanstack/react-query` is neither imported
+  nor pinned — the same reason the Next bridge takes `cacheTag` as a function.
+
+  Live is **opt-in per model**. Nothing subscribes because the provider is
+  mounted: the shared CDN lane is a major asset, and blanket liveness pushes
+  read traffic off it onto the origin.
+
+  Pagination is handled asymmetrically, because that is what the data supports.
+  `deleted` removes the row by id with **no fetch**; `created` exposes a
+  **count** rather than refetching, since a create cannot be spliced and
+  refetching the head page prepends under a reader mid-scroll; `updated`
+  refetches only the queries holding that record, matched on `rec:` rather than
+  the model. `totalCount` is flagged approximate rather than adjusted.
+
+  **Mutable sort keys are a documented limitation.** A query ordered by
+  `updatedAt` or a draggable `position` can have a record move between pages on
+  update. See the README.
+
+  Also on `@foir/sdk/live`: `createFoirLiveManager`, `applyFoirRecordChange`,
+  `foirQueryKeys`, `foirModelQueryKey`, `foirTagsForQueryInvalidation`,
+  `FOIR_QUERY_KEY_ROOT` and their types — the framework-free half of the same
+  adapter.
+
+- **`after` on `foir.<model>.onChange`** (`@foir/sdk/data`), plus the
+  `FoirChangeSubscribeOptions` type. Pass the highest `seq` you have applied and
+  the stream replays what came after it from the durable log before continuing
+  live, so a message lost anywhere upstream is repaired by the next connect
+  rather than left as a permanently stale cache entry. Omitting it is the stream
+  as it has always been. `onChange` already took an object, so this is additive.
+
+- **`@foir/sdk/live`** — a new subpath: the client half of Foir's invalidation
+  graph. `createFoirLiveStore`, `createFoirTagIndex`, `foirQueryKey`,
+  `foirStableKey`, `foirDecimalKey`, `readFoirLiveHeaders`,
+  `foirTagsForRecordChange`, `foirRecordTag`, `foirModelTag`,
+  `foirRequiresResync`, `foirResumeCursor`, the header and code constants, and
+  the accompanying types.
+
+  The API already computes which records and collections every cacheable
+  response depends on — it has to, to invalidate its own cache — and ships that
+  set on a response header, alongside the project's monotonic `seq`. It already
+  streams the change events that make those dependencies stale. This is the
+  join, on the client: a bidirectional tag index, a store that honours ordering
+  and completeness, and the mapping from one record change to the entries it
+  invalidates. Apollo, urql and TanStack Query all guess at that graph; here it
+  is computed by the process that actually resolved the query.
+
+  Framework-free and graphql-free, asserted as a property of the import graph
+  rather than promised in a comment.
+
+  **It is not a state-management library, and will not become one.** No local
+  mutation log, no offline mode, no conflict resolution, no optimistic
+  rollback. The server is authoritative: mutations go over the wire and the
+  invalidation comes back. That is a product boundary, not a phasing decision.
+
+  Three behaviours to know before building on it. The store holds the **raw
+  wire payload** and hydration happens at the read boundary — `FoirDecimal` is
+  a class with `#`-private fields, so `structuredClone` returns `{}` without
+  throwing and a structural deep-equal reports every decimal equal to every
+  other; raw JSON has neither problem, because a decimal there is a string.
+  Writes are **last-write-wins by `seq`**, so a slow refetch landing second
+  cannot walk the cache backwards. And a **hard resync fences requests already
+  in flight**: one issued before the resync arrives afterwards looking exactly
+  like a fresh answer, so `dedupe` hands the running function a fence to write
+  through.
+
+  Keys normalise, payloads never do. A decimal in query *variables* is
+  canonicalised to its minimal scale so `1.0` and `1.00` are one entry — but
+  never on the way into the store, where a trailing zero is significant for
+  money.
+
+- **`FoirDecimal` and `decimal()` on `@foir/sdk/data`** — the exact numeric type
+  a `decimal` field arrives as. Also `FoirDecimalInput`, `FoirDecimalRounding`
+  and `FoirDecimalDivOptions`.
+
+  A `decimal` field travels as a string, because JSON has one number type and
+  every JavaScript consumer parses it into a double whatever the server meant.
+  Supabase is the worked example of getting this half right: Postgres stores
+  `numeric` exactly, PostgREST serialises it as a JSON number, and the precision
+  is gone inside `JSON.parse` before any application code runs. Exact storage
+  behind a lossy wire format buys nothing.
+
+  The string is therefore the transport and deliberately not what you are
+  handed, because `"19.99" + "2.00"` is `"19.992.00"` — silently. `FoirDecimal`
+  holds a scaled `bigint`, so arithmetic is exact by construction, and answers
+  only the `string` primitive hint: template literals work, while `+`, `<` and
+  `Number()` throw and name the method to use instead. TypeScript rejects those
+  at compile time already; the throw is for JavaScript callers and for values
+  arriving through `any`.
+
+  Scale is preserved for display (`19.90` stays `19.90`) while `equals` compares
+  values (`1.0` equals `1.00`). `JSON.stringify` emits the canonical string, not
+  an object — pinned by test, because leaving it implicit is Prisma's most common
+  support thread.
+
+  No dependency: `bigint` is ES2020 and this package targets ES2022. Prisma
+  hands out `Decimal.js` instances and prisma/prisma#16397 has run for years
+  because callers cannot supply a matching version — a type that crosses a
+  package boundary should not carry a third party's identity with it.
+
+  A `number` is refused by the constructor; `FoirDecimal.fromNumber()` accepts
+  one and names the precision loss at the call site.
+
+
+- **`HostedSession.expiresIn`** — seconds until the bearer lapses, from the
+  endpoint's `expires_in`, which the exchange already received and discarded.
+
+  The hosted flow has no refresh token by design: the cookie is the durable
+  credential and the bearer is re-exchanged when it dies. A consumer that cannot
+  see the lifetime has to hardcode the platform's (coupling itself to a server
+  constant it cannot observe) or decode `exp` off the JWT — or, as happened,
+  treat a 15-minute bearer as good forever and have customers appear signed out
+  mid-session. `createFoirSessionClient` on the SPA path has read `expires_in`
+  and scheduled a proactive refresh all along; this closes the asymmetry.
+
+  `0` when the endpoint reported none. Treat that as "expires imminently", never
+  as "never expires".
+
+- **`HostedSessionResult`** exported from `./auth`.
+
+- **`FoirAuthDowngrade`** on `./data` and `./server`, plus `extensions` on the
+  response envelope — Foir now reports when it DISCARDED a customer token you
+  sent, and the SDK stops dropping that report on the floor.
+
+  A customer JWT is optional: one that fails to verify is not refused, the read
+  is served anonymously and returns `200`. So a lapsed token and a genuinely
+  anonymous request were indistinguishable — nothing threw, no refresh armed,
+  and auth-targeted content quietly resolved to its anonymous variant. The
+  failure surfaced as *wrong content*, never as an error.
+
+  ```json
+  { "data": { "…": "…" },
+    "extensions": { "auth": {
+      "customerToken": "rejected", "reason": "expired", "servedAs": "anonymous"
+    } } }
+  ```
+
+  The SDK warns once per episode (not once per request — a lapsed bearer affects
+  every one of them), naming the remedy, and re-arms after a clean response so a
+  second episode is reported as its own. The data is still returned: a downgrade
+  is a report, not an error.
+
+- **`events.subscribe(params)` on `./server`** — the push form of the event
+  cursor `list()` and `stream()` already page through. The server backfills from
+  `after` and continues live on one stream, so there is no gap between catching
+  up and keeping up. The cursor advances as events arrive, so a dropped socket
+  resumes from the last event delivered rather than replaying the backfill; a
+  cursor older than the retention window ends the subscription with
+  `FoirEventCursorExpiredError` carrying `resumeFrom`, matching the 410 the HTTP
+  lane answers.
+
+  The GraphQL `events` subscription has been live on the public schema since the
+  events spine shipped, with no client able to reach it. It is an `sk_`-only
+  operator surface, so it lives on `./server` beside the rest of the events
+  client and inherits its `pk_` and `Authorization` refusals unchanged.
+
+  New exports: `FoirEventsSubscribeParams`, plus `FoirSubscription` and
+  `FoirSubscriptionHandlers` re-exported from `./server` so a consumer need not
+  import them from the browser-facing `./data`.
+
+  `wsUrl`, `webSocketImpl` and `reconnect` are accepted on
+  `FoirEventsClientConfig` for the socket, mirroring `./data`. Node 18/20 have no
+  global `WebSocket`, so a server process on those versions passes the `ws`
+  package's constructor.
+
+### Changed
+
+
+- **`fetchHostedSession` returns a `HostedSessionResult` instead of
+  `HostedSession | null`.** BREAKING — every call site has to branch on
+  `outcome`.
+
+  It collapsed every failure to `null`: no cookie, a `401`, a `502`, a rate
+  limit, a DNS failure. Consumers have to act on that `null`, and the only
+  safe-looking action is to clear the session and redirect to the front door —
+  so one blip on `/session/token` signed out a customer whose 30-day cookie was
+  perfectly valid, and nothing recorded that it had happened. The route's own
+  rate limiter is deliberately fail-open for the opposite reason.
+
+  ```ts
+  // before
+  const session = await fetchHostedSession(request, config);
+  if (!session) return redirect(hostedLoginUrl(config));
+
+  // after
+  const result = await fetchHostedSession(request, config);
+  if (result.outcome === 'signed-out') return redirect(hostedLoginUrl(config));
+  if (result.outcome === 'unavailable') return keepExistingSession();
+  use(result.session);
+  ```
+
+  `outcome` says what to DO; `reason` says what happened. Only `401` and a
+  missing cookie are `signed-out`. A `403` reports as `unavailable` with reason
+  `forbidden` — it means the CSRF header did not arrive, which is a
+  misconfiguration rather than a blip, but signing the customer out over it
+  would still be wrong.
+
+- **`foir.ns.operations.onExecution` delivers `status` as the
+  `OperationExecutionStatus` enum name.** BREAKING. `FoirOperationExecutionEvent.status`
+  is now `'PENDING' | 'DISPATCHED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMED_OUT'`
+  where it was a lowercase `string`.
+
+  `operationExecution` and `operationExecutions` return the enum name for a
+  run, and the socket carries the platform's lowercase value, so one consumer
+  held two spellings of the same run's status. The typed stream now matches the
+  query. The socket itself is unchanged: a subscriber on `FoirSocketTransport`
+  directly still receives the lowercase value the server sends.
+
+  ```ts
+  // before
+  onData: (event) => { if (event.status === 'completed') done(); }
+
+  // after
+  onData: (event) => { if (event.status === 'COMPLETED') done(); }
+  ```
+
+### Fixed
+
+
+- **Subscription errors keep their `extensions`.** The socket transport reduced
+  every terminal `error` frame to its message and dropped the structured fields,
+  so `graphQLErrors` was always absent and a caller had no `code` to branch on —
+  while the HTTP lane carried them. This affected every subscription, not only
+  `events`. Both lanes now report the same shape.
+
 ---
 
 ## [0.9.0] — 2026-08-20
@@ -129,7 +822,7 @@ Everything additive, so a MINOR either way under the pre-1.0 note.
   `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`
+  Requires the platform's `end-session` endpoint. `HostedLoginConfig`
   gains an optional `endSessionPath`, defaulting to `/session/end-session`.
 
 - **`Prose`, `Passage`, `ProseSpan` and `RecordAncestor` on `./data`.** The
@@ -166,13 +859,13 @@ note above.
   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
+    was the wrapper's envelope, removed — 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
+  - `MediaBlock` — `media` stopped being a primitive. 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
+  - `TextBlock` — removed. 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.
@@ -195,7 +888,7 @@ note above.
   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.
+  stopped serving.
 
   A union branch is now `(<Model> & { __typename: '<Model>' })`: the model
   itself, intersected with the discriminant the union position guarantees. The
@@ -219,7 +912,7 @@ note above.
 
 - **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
+  being union members. 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.
 
@@ -244,7 +937,7 @@ note above.
     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
+    platform relaxed them to `String` — 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.
@@ -252,7 +945,7 @@ note above.
     `_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
+    followable, 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.
 
@@ -269,7 +962,7 @@ note above.
   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
+  The platform stopped emitting a union named `Block` — 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
@@ -280,7 +973,7 @@ note above.
 
   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
+  pre-rename shape. The fixture is now the post-rename shape, and
   `DEFAULT_UNIONS` is asserted against it directly.
 
   **Migration:** none if you pass `blockUnions`/`itemUnions` explicitly. If you
@@ -321,7 +1014,7 @@ note above.
   `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).
+  should not teach otherwise.
 
   Nothing is removed in this release; every old name still resolves and still
   behaves identically. Removal is a later, separately announced break.
@@ -860,7 +1553,7 @@ note above.
   `FoirManifestSelection`, `FoirManifestSelectionField`,
   `FoirManifestSelectionUnion`, `FoirManifestSelectionMember`.
 
-- **The event-log client on `@foir/sdk/server`** (TTS-983) — `createEventsClient`,
+- **The event-log client on `@foir/sdk/server`** — `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
@@ -873,7 +1566,7 @@ note above.
   `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 OPERATOR surface (DECIDED 2026-08-04): 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
@@ -1020,7 +1713,7 @@ 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 (TTS-874).
+- **New subpath `@foir/sdk/data`** — the typed data client.
   `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(…)`
@@ -1107,7 +1800,7 @@ on its own, which is the intended behaviour for a release that adds exports.
 - `@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).
+  `hostedLoginUrl` hosted-login bridge that already shipped in 0.1.0.
 
 ## [0.3.0] — 2026-07-12
 
@@ -1115,10 +1808,10 @@ on its own, which is the intended behaviour for a release that adds exports.
 
 - **New subpath `@foir/sdk/react`** — drop-in React customer auth: `FoirProvider`,
   `SignIn`, `OAuthButtons`, `UserButton`, `useFoirAuth`, `useFoirSession`,
-  `useFoirUser` (EID-515).
+  `useFoirUser`.
 - **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).
+  provider callback handler.
 
 ## [0.2.0] — 2026-07-10
 
@@ -1127,27 +1820,25 @@ on its own, which is the intended behaviour for a release that adds exports.
 - **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).
+  operation BFF routes, over the existing `verifyScopedToken`.
 
 ## [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).
+  host↔editor message protocol, and `createPlatformClient`.
 - `@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/media` — progressive media components and adapters.
 - `@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).
+  injected typography tokens.
+- `@foir/sdk/auth` — customer auth flows, token lifecycle, hosted-login bridge.
+- `@foir/sdk/realtime` — `createCollabSession`, a thin y-websocket helper.
 - `@foir/sdk/codegen`, `@foir/sdk/codegen/block-registry`,
   `@foir/sdk/codegen/block-scaffold` — the `foirCodegen` preset and the
-  graphql-codegen plugins (EID-92).
+  graphql-codegen plugins.
 
 ---
 
@@ -1170,7 +1861,8 @@ and the commit history.
 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
+[Unreleased]: https://github.com/foir-io/clients/compare/sdk-v0.10.0...dev
+[0.10.0]: https://github.com/foir-io/clients/compare/sdk-v0.9.0...sdk-v0.10.0
 [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