@foir/sdk 0.9.0 → 0.10.0

package/dist/data/client.d.ts

@@ -95,6 +95,74 @@ export type FoirNamespaceClient<N extends {
 }> = {
     [OK in keyof N['ops']]: N['ops'][OK] extends FoirNamespaceOpDefinition ? FoirNamespaceOperation<N['ops'][OK]> : never;
 };
+declare const foirDocumentResult: unique symbol;
+declare const foirDocumentVariables: unique symbol;
+/**
+ * A GraphQL document string that carries its own result and variable types.
+ *
+ * `raw` returns `unknown` because a hand-written document is opaque to the
+ * client, so every call site hand-writes a result type that nothing checks. That
+ * is the cost the escape hatch was never meant to have: the sites that most need
+ * type safety, the ones the typed client could not express, are the ones with
+ * none.
+ *
+ * A branded document moves that annotation from the call site to the document,
+ * once, next to the selection it describes. It is still an assertion rather than
+ * a proof, because nothing validates it against the live schema, but it is an
+ * assertion made in ONE place that every caller then inherits, and a wrong one
+ * is wrong somewhere a reader is looking at the query.
+ *
+ * The brands are phantom: they exist only in the type system, so a
+ * `TypedFoirDocument` is a plain string at runtime and can be logged, hashed or
+ * sent anywhere a string goes.
+ */
+export type TypedFoirDocument<TResult, TVariables = Record<string, unknown>> = string & {
+    readonly [foirDocumentResult]: TResult;
+    readonly [foirDocumentVariables]: TVariables;
+};
+/**
+ * Brand a GraphQL document with the shape it returns.
+ *
+ * ```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 });
+ * //      ^? { totalCount: number }
+ * ```
+ *
+ * It does nothing at runtime beyond returning the string it was given. The value
+ * is entirely in the type, and in the fact that the type now lives beside the
+ * document rather than being retyped at each call.
+ *
+ * This does NOT make a bespoke selection type-checked against the schema. That
+ * is the larger half and wants generated documents rather than a helper. What it
+ * removes is the retyping, which is where the two real bugs came from: a result
+ * type that drifted from the selection it claimed to describe.
+ */
+export declare function graphql<TResult = unknown, TVariables = Record<string, unknown>>(document: string): TypedFoirDocument<TResult, TVariables>;
+/**
+ * Per-call options for {@link FoirClient.raw}.
+ */
+export interface FoirRawOptions {
+    /**
+     * Treat a partial response as a failure.
+     *
+     * A GraphQL response can carry `errors` AND `data` together, and the default
+     * is to warn and return the data: a field the server could not resolve should
+     * not blank a whole page, and forward compatibility rests on it.
+     *
+     * On a hand-written document that default is the expensive one. There is no
+     * generated selection to have caught a wrong field name first, so selecting
+     * something that does not exist returns everything else and logs — a typo
+     * reads as a missing feature rather than a failure, and the hand-written
+     * result type asserts it was fine. `strict: true` turns that into a thrown
+     * `FoirRequestError`, which still carries the data on `partialData` so a
+     * caller can log what it declined to render.
+     */
+    strict?: boolean;
+}
 export interface FoirClientCore<S extends FoirSchemaDefinition> {
     /**
      * Non-model root namespaces (`search`, `customers`, `notifications`).
@@ -126,7 +194,19 @@ export interface FoirClientCore<S extends FoirSchemaDefinition> {
      * );
      * ```
      */
-    raw<T = unknown>(document: string, variables?: Record<string, unknown>): Promise<T>;
+    raw<TResult, TVariables extends Record<string, unknown>>(document: TypedFoirDocument<TResult, TVariables>, variables?: TVariables, options?: FoirRawOptions): Promise<TResult>;
+    /**
+     * The untyped form, for a document with no brand.
+     *
+     * The document type excludes a branded one deliberately. Without that, a
+     * branded call whose VARIABLES do not match falls through to this overload,
+     * whose `Record<string, unknown>` accepts anything, and the mistake compiles.
+     * The result would still be typed, so the call site reads as checked while the
+     * variables are not, which is the failure mode a brand exists to prevent.
+     */
+    raw<T = unknown>(document: string & {
+        readonly [foirDocumentResult]?: undefined;
+    }, variables?: Record<string, unknown>, options?: FoirRawOptions): Promise<T>;
     /**
      * Close the subscription socket and drop every live subscription.
      *
@@ -164,3 +244,4 @@ export declare function createFoirClient<S extends FoirSchemaDefinition = FoirSc
 export declare function createFoirClientFromEnv<S extends FoirSchemaDefinition = FoirSchemaDefinition>(env: FoirEnv, overrides?: Omit<FoirClientConfig, 'apiUrl' | 'apiKey' | 'channel' | 'generated'> & {
     generated?: FoirGeneratedModule<S>;
 }): FoirClient<S>;
+export {};

package/dist/data/decimal.d.ts

@@ -0,0 +1,212 @@
+/**
+ * `FoirDecimal` — the exact numeric type a `decimal` field arrives as.
+ *
+ * A `decimal` field travels as a STRING on the wire, because JSON has one
+ * number type and every JavaScript consumer parses it into an IEEE-754 double
+ * whatever the server meant. Supabase demonstrates the failure: Postgres stores
+ * `numeric` exactly, PostgREST serialises it as a JSON number, and precision
+ * dies in `JSON.parse` before any application code runs. Exact storage with a
+ * lossy wire format buys nothing.
+ *
+ * So the string is the transport. It is deliberately NOT what you are handed:
+ * `"19.99" + "2.00"` is `"19.992.00"`, silently. This class is the thing that
+ * makes that unrepresentable.
+ *
+ * ---------------------------------------------------------------------------
+ * Representation
+ * ---------------------------------------------------------------------------
+ *
+ * A scaled `bigint`: `value = units / 10 ** scale`. `19.99` is
+ * `{ units: 1999n, scale: 2 }`. All arithmetic is integer arithmetic on
+ * `units`, so it is exact by construction rather than exact by care.
+ *
+ * `bigint` is ES2020 and the package targets ES2022, so this has NO dependency.
+ * That is deliberate: Prisma ships `Decimal.js` instances and prisma/prisma#16397
+ * has run for years because callers cannot get a `Decimal.js` whose version
+ * matches Prisma's. A type that crosses a package boundary should not carry a
+ * third party's identity with it.
+ *
+ * ---------------------------------------------------------------------------
+ * Scale is preserved, equality is numeric
+ * ---------------------------------------------------------------------------
+ *
+ * `decimal('19.90')` renders as `"19.90"`, not `"19.9"`. Trailing zeros are
+ * significant to anyone displaying money, and dropping them would make the
+ * round trip lossy in the one way people actually notice.
+ *
+ * But `equals` compares VALUES: `decimal('1.0').equals(decimal('1.00'))` is
+ * `true`. Textual comparison would be a trap of a different shape.
+ *
+ * ---------------------------------------------------------------------------
+ * Why `+` throws instead of concatenating
+ * ---------------------------------------------------------------------------
+ *
+ * `Symbol.toPrimitive` answers the `'string'` hint and throws on every other
+ * one. So:
+ *
+ * ```ts
+ * `Total: ${price}`     // "Total: 19.99"  — string hint, fine
+ * price + tax           // TypeError, naming .add()
+ * price > limit         // TypeError, naming .cmp()
+ * Number(price)         // TypeError, naming .toNumber()
+ * ```
+ *
+ * TypeScript already rejects `price + tax` at compile time. The throw is for
+ * JavaScript callers and for anything that reaches this through `any`, where a
+ * silent `"19.992.00"` would otherwise reach a customer. Loud beats quiet: the
+ * whole reason this type exists is that the float bug was silent.
+ *
+ * `JSON.stringify` is answered by `toJSON`, so a decimal serialises back to the
+ * canonical string it arrived as — `{"price":"19.99"}`, never `{"price":{}}`.
+ * Prisma's most common support thread is that this behaviour was left implicit;
+ * it is pinned by a test here.
+ *
+ * ---------------------------------------------------------------------------
+ * If you are caching, cloning or comparing these, read this
+ * ---------------------------------------------------------------------------
+ *
+ * **Treat a decimal as an opaque leaf.** The state lives in `#`-private fields,
+ * which are invisible to every structural walk:
+ *
+ * ```ts
+ * Object.keys(price)                   // []
+ * Object.keys(structuredClone(price))  // []   <- no throw. silently {}.
+ * ```
+ *
+ * So a generic deep-clone, structural-share or deep-equal sees an EMPTY OBJECT.
+ * `structuredClone` does not throw, it just returns `{}`, and any equality that
+ * walks own enumerable keys calls two different decimals equal. This is the one
+ * that fails quietly, which on money is the worst place for it.
+ *
+ * Identity is `instanceof`. Equality is `.equals()`. Cloning is unnecessary —
+ * every operation returns a new instance and nothing mutates, so share the
+ * reference.
+ *
+ * **A JSON round trip returns a string, not a decimal.** Lossless in value,
+ * lossy in type:
+ *
+ * ```ts
+ * JSON.parse(JSON.stringify(price))    // "19.99", a string
+ * ```
+ *
+ * Rehydrate at the boundary — `decimal(value)` takes the string, and the
+ * generated types say which fields are decimals, so the revive is keyed on the
+ * schema rather than sniffed.
+ *
+ * **Scale is display, not identity — so normalise KEYS, never PAYLOADS.**
+ * `decimal('1.0').equals(decimal('1.00'))` is true while their `toString()`
+ * differs. Two consequences that pull in opposite directions:
+ *
+ * - Keying a cache on `toString()` splits one value into two entries. If you
+ *   need a canonical key, `rescale()` to a fixed scale first.
+ * - But `rescale()` on a value you will SERVE rewrites what the author entered:
+ *   `19.90` becomes `19.9`, and a price changes how it displays. Never
+ *   normalise a stored payload.
+ *
+ * The cleanest way to hold both is to store the raw wire string and hydrate at
+ * the read boundary. The store then never holds two instances to choose
+ * between, and persistence is correct by construction.
+ */
+/**
+ * How to resolve a value sitting exactly halfway between two representable
+ * results. Only `div`, `toFixed` and `rescale` can produce one — `add`, `sub`
+ * and `mul` are always exact.
+ *
+ * - `half-even` — banker's rounding. Ties go to the even neighbour, so a long
+ *   run of them does not drift upward. The default for `div`, where the result
+ *   is usually an intermediate value that will be summed.
+ * - `half-up` — ties go away from zero. What a person means by "round to 2dp",
+ *   and the default for `toFixed`, which is a display operation.
+ * - `down` — truncate toward zero. Never rounds up, for the cases where over-
+ *   stating is the expensive direction.
+ */
+export type FoirDecimalRounding = 'half-even' | 'half-up' | 'down';
+/** Options for {@link FoirDecimal.div}. */
+export interface FoirDecimalDivOptions {
+    /**
+     * Decimal places in the result. Division is the one operation that cannot be
+     * exact — `1/3` has no finite decimal expansion — so a scale has to be named.
+     * Defaults to 20, which is wider than any currency and narrow enough to stay
+     * cheap.
+     */
+    scale?: number;
+    /** Defaults to `half-even`. */
+    rounding?: FoirDecimalRounding;
+}
+/** Anything that can be widened to a decimal without losing precision. */
+export type FoirDecimalInput = string | bigint | FoirDecimal;
+/**
+ * An exact decimal number.
+ *
+ * Construct from a string (the wire form), a `bigint`, or another decimal.
+ * A `number` is refused — see {@link FoirDecimal.fromNumber}.
+ */
+export declare class FoirDecimal {
+    #private;
+    constructor(value: FoirDecimalInput);
+    /**
+     * Build a decimal from a JavaScript number, accepting the precision that
+     * number may already have lost.
+     *
+     * Deliberately not the constructor. It is for interop — a value read from a
+     * third-party JSON API that emitted a float — and naming it at every call
+     * site is the point. `fromNumber(0.1 + 0.2)` gives `0.30000000000000004`,
+     * because that is genuinely the value it was handed.
+     */
+    static fromNumber(value: number): FoirDecimal;
+    /** `true` if `value` parses as a decimal. Does not throw. */
+    static isDecimalString(value: unknown): value is string;
+    /** Decimal places carried by this value. `19.90` has scale 2. */
+    get scale(): number;
+    /** Re-express at `scale`, rounding away any digits that no longer fit. */
+    rescale(scale: number, rounding?: FoirDecimalRounding): FoirDecimal;
+    add(other: FoirDecimalInput): FoirDecimal;
+    sub(other: FoirDecimalInput): FoirDecimal;
+    /** Exact: scales add, so `1.10 × 1.10` is `1.2100` rather than `1.21`. */
+    mul(other: FoirDecimalInput): FoirDecimal;
+    /** The only inexact operation — see {@link FoirDecimalDivOptions}. */
+    div(other: FoirDecimalInput, options?: FoirDecimalDivOptions): FoirDecimal;
+    abs(): FoirDecimal;
+    neg(): FoirDecimal;
+    isZero(): boolean;
+    isNegative(): boolean;
+    /** `-1`, `0` or `1`. Use this rather than `<`, which throws. */
+    cmp(other: FoirDecimalInput): -1 | 0 | 1;
+    /** Numeric equality: `1.0` equals `1.00`. Scale is display, not identity. */
+    equals(other: FoirDecimalInput): boolean;
+    /**
+     * Fixed-place string, rounding `half-up` by default because this is the
+     * display operation and that is what a person means by "to 2dp".
+     */
+    toFixed(places: number, rounding?: FoirDecimalRounding): string;
+    /**
+     * The canonical wire form, preserving scale. Never exponent notation, so the
+     * output always parses back to an equal value.
+     */
+    toString(): string;
+    /** `JSON.stringify` emits the canonical string, not an object. Pinned by test. */
+    toJSON(): string;
+    /**
+     * Explicitly lossy — this is the boundary back into float, and naming it is
+     * the point. Fine for a chart axis; never for money you will add up.
+     */
+    toNumber(): number;
+    /**
+     * Answers the `'string'` hint so template literals work, and throws on every
+     * other hint so `+`, `<` and `Number()` fail loudly instead of silently
+     * concatenating or truncating.
+     */
+    [Symbol.toPrimitive](hint: string): string;
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * Shorthand for `new FoirDecimal(value)`.
+ *
+ * ```ts
+ * import { decimal } from '@foir/sdk/data';
+ *
+ * const total = decimal(product.price).mul('3').add(shipping);
+ * console.log(total.toFixed(2)); // "62.97"
+ * ```
+ */
+export declare function decimal(value: FoirDecimalInput): FoirDecimal;

package/dist/data/document.d.ts

@@ -215,7 +215,7 @@ export interface FoirNamespaceCall {
      * stopped in front of. Each level above 1 spends one of those stopping points.
      *
      * It is a BUDGET rather than a setting, though a much larger one since
-     * TTS-1448: on a real project the same op measures 318 fields at level 1, 468
+     * On a real project the same op measures 318 fields at level 1, 468
      * at level 2 and 618 at level 3, against a server ceiling of 10,000. Those
      * were 837 / 3,513 / 14,217 while a union position was charged every member it
      * could hold rather than the one a value can be.

package/dist/data/index.d.ts

@@ -37,21 +37,21 @@
  * const anything = await foir.raw('{ designTokens { name value } }');
  * ```
  *
- * `FoirSchema` comes from `foir types` (TTS-875). The contract it generates
+ * `FoirSchema` comes from `foir types`. The contract it generates
  * against is written down in `schema.ts` — read that file before changing
  * anything here, because a generator is written against it.
  */
-export { createFoirClient, createFoirClientFromEnv } from './client';
-export type { FoirClient, FoirClientCore, FoirModelClient, FoirNamespaceClient } from './client';
+export { createFoirClient, createFoirClientFromEnv, graphql } from './client';
+export type { FoirClient, FoirClientCore, FoirModelClient, FoirNamespaceClient, FoirRawOptions, TypedFoirDocument, } from './client';
 export { fetchFoirManifest } from './manifest';
 export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManifestNamespace, FoirManifestOp, FoirManifestOpPayload, FoirManifestRelation, FoirManifestScalar, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionMember, FoirManifestSelectionUnion, FoirManifestStructural, FoirManifestSubscription, FoirManifestSubscriptionArgScope, FoirManifestUnclassifiedField, } from './manifest';
 export { planFoirModelCall, planFoirNamespaceCall } from './document';
 export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
 export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
 export type { FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
-export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirSubmitAnonymousNoteArgs, FoirAnonymousNoteReceipt, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
 /**
- * Pre-TTS-1391 spellings. The `<Name>Block` wrappers and the `<Name>Value`
+ * Pre-rename spellings. The `<Name>Block` wrappers and the `<Name>Value`
  * split are the same thing as the types above — an item IS its value — so each
  * of these is an alias, not a separate shape.
  *
@@ -60,14 +60,16 @@ export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAcces
  * emits, so there is nothing for them to alias. See `builtins.ts`.
  */
 export type { FileBlock, GeoPointValue, ImageBlock, ImageValue, ReferenceBlock, ReferenceValue, RichtextBlock, RichtextValue, VideoBlock, VideoValue, } from './builtins';
-export { foirDataEndpoint, foirRoute } from './transport';
+export { FoirSchemaDriftError, foirDataEndpoint, foirRoute } from './transport';
 export type { FoirClientConfig, FoirGeneratedModule, FoirLane, FoirLaneReason, FoirRouteDecision, FoirRouteInput, FoirSchemaDrift, } from './transport';
 export { foirSocketEndpoint, FoirSocketTransport } from './ws-transport';
 export type { FoirReconnectPolicy, FoirSubscribeRequest, FoirSubscription, FoirSubscriptionHandlers, FoirWebSocketFactory, FoirWebSocketLike, } from './ws-transport';
 export { printSubscriptionDocument } from './subscription-document';
 export type { FoirSubscriptionArgument, PrintSubscriptionDocumentInput, } from './subscription-document';
-export type { FoirExecutionSubscribeOptions, FoirJobProgressEvent, FoirModelSubscriptions, FoirNamespaceSubscriptions, FoirNotificationEvent, FoirOperationExecutionEvent, FoirRecordChangedEvent, } from './subscriptions';
+export type { FoirChangeSubscribeOptions, FoirExecutionSubscribeOptions, FoirJobProgressEvent, FoirModelSubscriptions, FoirNamespaceSubscriptions, FoirNotificationEvent, FoirOperationExecutionEvent, FoirRecordChangedEvent, } from './subscriptions';
 export type { FoirConnection, FoirFieldsShape, FoirModelDefinition, FoirNamespaceDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirRelationDefinition, FoirReturnDefinition, FoirSchemaDefinition, } from './schema';
 export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmittableKey, FoirOpResult, FoirQuery, FoirRecordResult, } from './selection';
+export { FoirDecimal, decimal } from './decimal';
+export type { FoirDecimalDivOptions, FoirDecimalInput, FoirDecimalRounding, } from './decimal';
 export { FoirRequestError } from '../transport/foir-http';
-export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, } from '../transport/foir-http';
+export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, } from '../transport/foir-http';

package/dist/data/manifest.d.ts

@@ -2,7 +2,7 @@
  * `GET /v1/manifest` — the per-caller surface descriptor, as a runtime type.
  *
  * This is the *runtime* mirror of `schema.ts`'s compile-time contract: what the
- * server actually sends, verbatim, so `foir types` (TTS-875) has a typed thing
+ * server actually sends, verbatim, so `foir types` has a typed thing
  * to read and the drift check has a version to compare. The manifest is already
  * the projection of `CachedSchema.SchemaForCaller(scopes)`, so what it lists is
  * exactly what this credential may do — no client-side filtering anywhere.
@@ -275,6 +275,14 @@ export interface FoirManifestNamespace {
 export interface FoirManifest {
     schemaVersion: number;
     channel: 'published' | 'draft';
+    /**
+     * The organisation whose composition this surface is, absent for the
+     * project's own. A credential confined to an organisation is served that
+     * organisation's surface without naming it, so this is how a reader of the
+     * manifest, or of a module generated from it, tells whose definitions it
+     * describes.
+     */
+    composedFor?: string;
     models: Record<string, FoirManifestModel>;
     /**
      * Keyed by namespace name (`auth`, `customers`, `files`, `notifications`,

package/dist/data/schema.d.ts

@@ -2,7 +2,7 @@
  * THE `FoirSchema` CONTRACT.
  *
  * `createFoirClient<FoirSchema>()` is parameterised by a type that `foir types`
- * (TTS-875) emits from `GET /v1/manifest`. This file is that contract: the
+ * emits from `GET /v1/manifest`. This file is that contract: the
  * shape the generator writes and the shape the client reads. It is the only
  * coupling between the two, so it is written down here rather than living in
  * the generator's head.
@@ -161,7 +161,7 @@
  * 8. **`raw` and `ns` are reserved top-level names.** They are the escape hatch
  *    and the namespace accessor on the client object. A model whose key is
  *    `raw` or `ns` would collide; the server should reject those model keys at
- *    create time (noted in TTS-868's "Known limits").
+ *    create time (a known limit).
  *
  * 9. **`models` and `namespaces` must be object type LITERALS, not named
  *    `interface`s.** TypeScript gives an implicit index signature to object

package/dist/data/subscriptions.d.ts

@@ -38,13 +38,17 @@
  * carries a resolved selection tree, which `subscription-document.ts` prints
  * with the same walk the query path prints models with.
  *
- * A subscribing client therefore fetches the descriptor once even when
- * `config.selections` was supplied, because `selections` carries MODEL trees and
- * nothing generates subscription ones yet. That is a real cost and it is stated
- * rather than hidden — but it is ONE fetch, memoised across every subscription
- * and shared with the query path, sitting behind a long-lived socket. `client.ts`
- * rejects a round trip in front of every query for good reason; in front of a
- * socket that will live for minutes it is noise.
+ * A client built with `foirSubscriptions` makes no request at all: `client.ts`
+ * hands this an already-resolved descriptor instead of the fetcher, and the
+ * printer cannot tell the difference — it is the same shape either way, which is
+ * why nothing in this file changed when that landed.
+ *
+ * Without them it fetches once, which is what every client did before `foir
+ * types` emitted subscription trees and what a module generated before that
+ * still does. It is ONE fetch, memoised across every subscription and shared
+ * with the query path, sitting behind a long-lived socket. `client.ts` rejects a
+ * round trip in front of every query for good reason; in front of a socket that
+ * will live for minutes it is noise.
  */
 import type { FoirManifest } from './manifest';
 import type { FoirClientConfig } from './transport';
@@ -88,8 +92,12 @@ export interface FoirJobProgressEvent {
 /** `operationExecution` / `operation{Op}Execution` — one execution's progress. */
 export interface FoirOperationExecutionEvent {
     id: string;
-    /** `pending`, `dispatched`, `running`, `completed`, `failed`, `cancelled` or `timed_out`. */
-    status: string;
+    /**
+     * The same spelling `operationExecution` and `operationExecutions` return for
+     * the run, so one comparison serves a read and an event. The socket carries
+     * the platform's lowercase value; this client hands it over as the enum name.
+     */
+    status: 'PENDING' | 'DISPATCHED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMED_OUT';
     /** 0-100; null on terminal events. */
     progressPct?: number | null;
     progressMessage?: string | null;
@@ -117,6 +125,24 @@ export type FoirExecutionSubscribeOptions = FoirSubscriptionHandlers<FoirOperati
      */
     operation?: string;
 };
+/**
+ * What `onChange` takes: the handlers, plus the optional resume cursor.
+ *
+ * `after` is the highest `seq` this consumer has already applied. Passing it
+ * makes the stream cursor-resumable — the server 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: live from
+ * the moment you connect.
+ *
+ * The two refusals it can produce — a cursor older than the retention window,
+ * or one further behind than the surface will page — arrive on `onError` with a
+ * machine-readable code, and both mean the cache must be thrown away rather
+ * than partially repaired. `@foir/sdk/live` classifies them.
+ */
+export type FoirChangeSubscribeOptions = FoirSubscriptionHandlers<FoirRecordChangedEvent> & {
+    after?: number;
+};
 /** The subscriptions a model accessor carries. */
 export interface FoirModelSubscriptions {
     /**
@@ -125,7 +151,7 @@ export interface FoirModelSubscriptions {
      * The socket refuses a model this credential may not read, but the model is
      * not in `FoirSchema` in that case, so the refusal is a type error first.
      */
-    onChange(handlers: FoirSubscriptionHandlers<FoirRecordChangedEvent>): FoirSubscription;
+    onChange(options: FoirChangeSubscribeOptions): FoirSubscription;
 }
 /**
  * The subscriptions one namespace carries, by name.