@foir/sdk 0.7.0 → 0.8.0

package/dist/data/document.d.ts

@@ -0,0 +1,251 @@
+/**
+ * From a resolved selection tree to a GraphQL document string.
+ *
+ * ---------------------------------------------------------------------------
+ * Why there is no `graphql` dependency here, and never can be
+ * ---------------------------------------------------------------------------
+ *
+ * The tree arrives PRE-RESOLVED. The server walked the built schema once per
+ * schema version — unions expanded per member, response-shape aliases assigned,
+ * cycles broken, the field budget counted — and published the answer on
+ * `GET /v1/manifest`: `models.<key>.selection` for a model's own tree, and
+ * `ops.<op>.payload` for the shape of what each op actually returns. What is
+ * left at runtime is a filter and a printer, which is string building. That is
+ * the whole reason this client shrinks rather than inheriting
+ * `query_compiler.go` in TypeScript.
+ *
+ * The rule that keeps it that way: **nothing below may need to know something
+ * about the schema that the manifest does not publish.** Every decision here is
+ * made from a flag the tree carries (`alias`, `model`, `union`, `relation`,
+ * `truncated`), from a payload's stated `kind`, or from a published argument
+ * type. There is no table of op names, no inferred wrapper shape, and no type
+ * guessed from a JavaScript value.
+ *
+ * ---------------------------------------------------------------------------
+ * Arguments are variables, not literals
+ * ---------------------------------------------------------------------------
+ *
+ * The manifest publishes each argument's declared GraphQL type
+ * (`ops.<op>.argTypes`), so an argument is emitted as a variable definition and
+ * its value travels in `variables`:
+ *
+ *     query PageFindMany($orderBy: [PageOrderByInput]) { pages(orderBy: $orderBy) { … } }
+ *
+ * That is not a nicety. A printer working from argument NAMES alone has to
+ * infer each value's literal form from the JavaScript value it holds, 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'`, indistinguishable from `naturalKey: "DESC"`. Putting the
+ * value in `variables` does not resolve the ambiguity, it removes it — the
+ * executor coerces against the declared input type, which is the same path the
+ * server's own `compileArgs` took so that no caller byte is spliced into query
+ * text.
+ *
+ * The second-order win is that the document text no longer varies with the
+ * argument VALUE, so a persisted-query registry holds one entry per op instead
+ * of one per argument tuple. Argument names are emitted in sorted order for the
+ * same reason: two callers passing the same arguments in a different object
+ * literal order must hash to one entry.
+ *
+ * An argument the manifest publishes no type for is REFUSED. Falling back to
+ * inferring a literal would reinstate the defect above under a condition no
+ * caller can see.
+ */
+import type { FoirManifestOp, FoirManifestRelation, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionUnion } from './manifest';
+/**
+ * One model, as the printer needs it.
+ *
+ * A structural subset of `FoirManifestModel`, deliberately — so the two ways of
+ * getting here are the same shape and there is one code path, not two:
+ *
+ *   - `foir types` bakes it into `foirSelections`, the runtime half of the
+ *     generated module, and the client never fetches anything.
+ *   - the fallback fetches `GET /v1/manifest` at construction and passes
+ *     `manifest.models` straight in, because a `FoirManifestModel` already
+ *     satisfies this interface.
+ */
+export interface FoirSelectionModel {
+    /** GraphQL type name, e.g. `'Page'`. Used when a polymorphic relation needs fragments. */
+    typeName: string;
+    /** Op name → root field, argument types and the resolved shape of the result. */
+    ops?: Readonly<Record<string, FoirManifestOp>>;
+    /** The complete-by-default selection for this model's own record payload. */
+    selection?: FoirManifestSelection;
+    /** Relations a caller may `include`. Needed to resolve an include's target. */
+    relations?: readonly FoirManifestRelation[];
+}
+/**
+ * One namespace, as the printer needs it.
+ *
+ * A namespace op is a `FoirManifestOp` exactly as a model op is, which is what
+ * makes `foir.ns.search.searchRecords()` and `foir.page.findMany()` the same
+ * code path below rather than two printers that agree by inspection.
+ */
+export interface FoirSelectionNamespace {
+    /** Op token → root field, argument types and the resolved shape of the result. */
+    ops?: Readonly<Record<string, FoirManifestOp>>;
+}
+/** Model key → its selection. What `foir types` emits as `foirSelections`. */
+export type FoirSelections = Readonly<Record<string, FoirSelectionModel>>;
+/** Namespace name → its ops. What `foir types` emits as `foirNamespaceSelections`. */
+export type FoirNamespaceSelections = Readonly<Record<string, FoirSelectionNamespace>>;
+/** Union type name → its expansion. What `foir types` emits as `foirSelectionUnions`. */
+export type FoirSelectionUnions = Readonly<Record<string, FoirManifestSelectionUnion>>;
+/** Everything the printer reads. `FoirManifest` satisfies it as-is. */
+export interface FoirSelectionSource {
+    models: FoirSelections;
+    namespaces?: FoirNamespaceSelections;
+    selectionUnions?: FoirSelectionUnions;
+}
+/**
+ * `_id` is emitted whatever the caller asked for — the server's own
+ * `protectedSelectionFields` does the same, and a record you cannot address is
+ * not a useful answer. Named here so `pick` adds it back and `omit` refuses it.
+ *
+ * Exported because the subject registry reads it back off the response: every
+ * record in a response carries this key precisely because no narrowing can
+ * remove it, and that guarantee is this constant's, not the registry's.
+ */
+export declare const PROTECTED_ROOT_FIELD = "_id";
+/**
+ * Print a complete selection body from a resolved tree, with no narrowing.
+ *
+ * The one entry point for a caller that has a `ManifestSelection` and wants the
+ * whole of it — today, the subscription transport, whose payload trees the
+ * manifest publishes exactly as it publishes a model's.
+ *
+ * It exists so there is ONE implementation of "walk a resolved tree and emit
+ * braces". Every rule a reader would otherwise have to re-derive lives in
+ * `printFields`: relations are include-governed and skipped, a `truncated` field
+ * degrades to `__typename` rather than an illegal empty body, a union emits
+ * `__typename` plus one inline fragment per member, a `model` reference expands
+ * to that model's published tree, and an alias prints as `alias: key`. A second
+ * walk elsewhere in this package would be correct on the day it was written and
+ * wrong on the day any of those changed.
+ *
+ * `isRoot` is false: the `_id` protection is a property of a MODEL's root
+ * selection, and an event payload has no records in it to address.
+ */
+export declare function printFoirSelectionBody(fields: readonly FoirManifestSelectionField[], unions: FoirSelectionUnions, models?: FoirSelections): string;
+/**
+ * Where a payload puts a record, and which model it is.
+ *
+ * `record` names one outright, AT THE PAYLOAD ROOT — an empty path. An `object`
+ * payload reaches one through a `model` reference at some depth (`edges.node`,
+ * `record`), and the path is the RESPONSE keys to it, so an aliased field
+ * contributes its alias rather than its key.
+ *
+ * The empty path is therefore not merely a position: it is the manifest saying
+ * this op's result IS one record, which is what the subject registry reads as
+ * "the caller addressed this record by name".
+ */
+export interface FoirRecordPath {
+    /** Response keys from the root field's value down to the record. */
+    path: readonly string[];
+    /** Model key whose published `selection` is printed at that position. */
+    modelKey: string;
+}
+/** One printed operation, and what the transport needs to route it. */
+export interface FoirDocumentPlan {
+    /** The document text. Also the thing that gets hashed for APQ. */
+    document: string;
+    /** The argument values, sent beside the document. Empty when the op takes none. */
+    variables: Record<string, unknown>;
+    /** True when the op lives on the Mutation root. Decides the route and the keyword. */
+    mutation: boolean;
+    /** The single root field the response is keyed by. */
+    rootField: string;
+    /**
+     * Fields this document selects, in the unit the server's complexity ceiling is
+     * denominated in — the same number `CompiledQuery.Fields` carries on the
+     * server side.
+     *
+     * Measured while printing rather than derived afterwards, and exposed rather
+     * than kept private so it is TESTABLE against the document it describes: a
+     * counter nobody can compare to the artefact is a counter that drifts from it.
+     *
+     * OPTIONAL because a plan is not only something this file returns — a
+     * hand-built one is a real pattern for executing a document the printer did
+     * not produce, and requiring the count there would mean requiring a caller to
+     * invent a number about a document this code never measured. Everything
+     * `planFoirModelCall` / `planFoirNamespaceCall` return sets it.
+     */
+    fields?: number;
+    /**
+     * Where the records this document selects sit in the response, and which
+     * model each one is.
+     *
+     * Read by the subject registry (`subjects.ts`) to answer "what did this page
+     * fetch" without inspecting the response's shape — the manifest already said
+     * where the records would be, so hunting for objects carrying an `_id` would
+     * be re-deriving something published.
+     *
+     * OPTIONAL for the same reason `fields` is: a hand-built plan for a document
+     * this printer never produced has no published payload to read positions off,
+     * and inventing them would put subjects against records nobody can vouch for.
+     * Absent means "this call records nothing", never "this call fetched nothing".
+     */
+    records?: readonly FoirRecordPath[];
+}
+/** What a model call carries, already split out of the caller's flat query object. */
+export interface FoirCall {
+    model: string;
+    op: string;
+    args: Record<string, unknown>;
+    include?: Record<string, unknown>;
+    omit?: readonly string[];
+    pick?: readonly string[];
+    /** Union levels to expand. See `FoirNamespaceCall.depth`. */
+    depth?: number;
+}
+/** What a namespace call carries. Same shape, addressed by namespace. */
+export interface FoirNamespaceCall {
+    namespace: string;
+    op: string;
+    args: Record<string, unknown>;
+    include?: Record<string, unknown>;
+    omit?: readonly string[];
+    pick?: readonly string[];
+    /**
+     * How many union levels to expand, default `1`.
+     *
+     * 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
+     * document stops one level in and says so, publishing the union name it
+     * 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
+     * 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.
+     *
+     * What a level costs is one more expansion at each STOPPING POINT inside the
+     * expansion, so it still compounds where a member carries several union-typed
+     * fields — and it no longer grows at all with how many members the union has.
+     * Where a level does cross the ceiling, `planCall` refuses and names the
+     * count, rather than letting the server answer with a number the caller
+     * cannot act on.
+     */
+    depth?: number;
+}
+/**
+ * Turn a model call into a document.
+ *
+ * Every op is printable or REFUSED. There is no third answer: an op the
+ * manifest describes no payload for is one this client would have to invent a
+ * shape for, and inventing one is what this design exists to stop.
+ */
+export declare function planFoirModelCall(source: FoirSelectionSource, call: FoirCall): FoirDocumentPlan;
+/**
+ * Turn a namespace call into a document.
+ *
+ * Identical to `planFoirModelCall` below the addressing, and deliberately the
+ * same function underneath: a namespace op is a `FoirManifestOp` carrying a
+ * payload exactly as a model op is, so `foir.ns.search.searchRecords()` is
+ * printed by the code that prints `foir.page.findMany()` rather than by a
+ * second printer that agrees with it by inspection.
+ */
+export declare function planFoirNamespaceCall(source: FoirSelectionSource, call: FoirNamespaceCall): FoirDocumentPlan;
+/** True when a hand-written document is a mutation, so it never takes the shared lane. */
+export declare function isFoirMutationDocument(documentText: string): boolean;

package/dist/data/index.d.ts

@@ -1,17 +1,17 @@
 /**
  * `@foir/sdk/data` — the typed data client.
  *
- * A second app-runtime transport alongside `@foir/sdk/client`'s GraphQL one,
- * shaped by the credential you hand it. `POST /v1/query` takes a JSON op and
- * the server compiles it to a GraphQL document, so both surfaces run through
- * the same executor, the same scope checks, the same response cache — the SDK
- * surface is a projection of `SchemaForCaller(scopes)`, never a parallel
- * construction.
- *
- * What you get over the GraphQL path: no `.graphql` documents, no
- * `graphql-codegen` step, and **no `graphql` dependency at all**. This subpath
- * imports neither `graphql` nor `@graphql-typed-document-node/core`; the import
- * graph is asserted graphql-free by `__tests__/data.test.ts`
+ * A typed client over the same GraphQL endpoint `@foir/sdk/client` posts to,
+ * shaped by the credential you hand it. It sends a GraphQL document like every
+ * other consumer — one execution surface, the same executor, the same scope
+ * checks, the same response cache — but you never write one: the document is
+ * printed from the selection tree the manifest publishes for that op.
+ *
+ * What you get over the hand-written GraphQL path: no `.graphql` documents, no
+ * `graphql-codegen` step, and **no `graphql` dependency at all**. Printing a
+ * pre-resolved tree is string building. This subpath imports neither `graphql`
+ * nor `@graphql-typed-document-node/core`; the import graph is asserted
+ * graphql-free by `__tests__/data.test.ts`
  * ("`@foir/sdk/data` has zero graphql dependency").
  *
  * `./data` and not `./client` because `./client` is the editor-iframe/GraphQL
@@ -19,12 +19,12 @@
  *
  * ```ts
  * import { createFoirClient } from '@foir/sdk/data';
- * import { type FoirSchema, foirSchemaVersion } from './foir.generated';
+ * import * as generated from './foir.generated';
  *
- * const foir = createFoirClient<FoirSchema>({
+ * const foir = createFoirClient({
  *   apiUrl: 'https://api.foir.dev',
  *   apiKey: process.env.PLATFORM_API_KEY!,
- *   schemaVersion: foirSchemaVersion,
+ *   generated,
  * });
  *
  * const page = await foir.page.findUnique({
@@ -34,7 +34,7 @@
  * });
  *
  * const results = await foir.ns.search.searchRecords({ query: 'shoes' });
- * const anything = await foir.raw({ model: 'page', op: 'findMany', args: { first: 5 } });
+ * const anything = await foir.raw('{ designTokens { name value } }');
  * ```
  *
  * `FoirSchema` comes from `foir types` (TTS-875). The contract it generates
@@ -44,10 +44,29 @@
 export { createFoirClient, createFoirClientFromEnv } from './client';
 export type { FoirClient, FoirClientCore, FoirModelClient, FoirNamespaceClient } from './client';
 export { fetchFoirManifest } from './manifest';
-export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManifestNamespace, FoirManifestOp, FoirManifestRelation, FoirManifestScalar, FoirManifestUnclassifiedField, } from './manifest';
-export type { CollabInfo, FileBlock, FileValue, FlexibleBlock, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirBlockMeta, FoirDegraded, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPointValue, ImageBlock, ImageFormat, ImageValue, ImageVariant, ImageVariantSet, MediaBlock, MediaValue, ReferenceBlock, ReferenceValue, RichtextBlock, RichtextValue, TextBlock, VideoBlock, VideoValue, } from './builtins';
-export { foirDataEndpoint } from './transport';
-export type { FoirClientConfig, FoirRawOp, FoirSchemaDrift } from './transport';
+export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManifestNamespace, FoirManifestOp, FoirManifestOpPayload, FoirManifestRelation, FoirManifestScalar, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionMember, FoirManifestSelectionUnion, 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, Reference, Richtext, Video, } from './builtins';
+/**
+ * Pre-TTS-1391 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.
+ *
+ * `MediaBlock`, `TextBlock`, `FlexibleBlock` and `FoirBlockMeta` are NOT here:
+ * they described a wrapper, a member and an envelope the platform no longer
+ * 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 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 { FoirConnection, FoirFieldsShape, FoirModelDefinition, FoirNamespaceDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirRelationDefinition, FoirReturnDefinition, FoirSchemaDefinition, } from './schema';
 export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmittableKey, FoirOpResult, FoirQuery, FoirRecordResult, } from './selection';
 export { FoirRequestError } from '../transport/foir-http';

package/dist/data/manifest.d.ts

@@ -20,9 +20,9 @@ export interface FoirManifestScalar {
     /**
      * GraphQL named type: a scalar (`String`, `Float`, `Boolean`, `ID`,
      * `DateTime`, `JSON`), a generated enum (then `enumValues` is set), or one of
-     * the closed set of platform-owned value objects (`ImageValue`, `VideoValue`,
-     * `FileValue`, `MediaValue`, `RichtextValue`, `GeoPointValue`,
-     * `ReferenceValue`, `CollabInfo`) — see `builtins.ts`.
+     * the closed set of platform-owned value objects (`Image`, `Video`,
+     * `FileValue`, `MediaValue`, `Richtext`, `GeoPoint`,
+     * `Reference`, `CollabInfo`) — see `builtins.ts`.
      */
     type: string;
     /**
@@ -72,8 +72,72 @@ export interface FoirManifestOp {
     /** GraphQL root field this op compiles to, e.g. `tillyBlocks`. */
     field: string;
     args?: string[];
+    /**
+     * Each name in `args` mapped to the GraphQL type the root field declares for
+     * it — `'String!'`, `'[PageOrderByInput]'`, `'SortDirection'` — spelled
+     * exactly as a variable definition needs it.
+     *
+     * This is what lets the printer emit `query FoirQuery($orderBy: [PageOrderByInput])`
+     * and put the value in `variables`, where the executor coerces it. Without
+     * the type a printer has to infer a LITERAL from the JavaScript value, which
+     * is exact for strings, numbers, booleans and objects and ambiguous for
+     * enums — the client holds the string `'DESC'` and `orderBy: { createdAt: DESC }`
+     * needs it unquoted.
+     *
+     * An argument named in `args` with no entry here has no type this projection
+     * could read. The printer REFUSES such a call: inferring the literal form
+     * from the value is the defect this field exists to remove, so falling back
+     * to it would reintroduce it under a condition nobody can see.
+     */
+    argTypes?: Record<string, string>;
     /** True when the field lives on the Mutation root. */
     mutation?: boolean;
+    /**
+     * The resolved shape of this op's RESULT.
+     *
+     * The model's own `selection` answers for `findUnique` and for nothing else:
+     * `findMany` returns a connection OVER the model, `search` returns a wrapper
+     * CARRYING it, `delete` returns `Boolean!`, and `myAccess` returns a payload
+     * that is not the model in any sense. A consumer that bridged that gap by
+     * knowing from the OP NAME which shape to print was carrying a schema under
+     * another name.
+     *
+     * Absent is not "no selection". A consumer must refuse the op rather than
+     * synthesise a shape for it.
+     */
+    payload?: FoirManifestOpPayload;
+}
+/**
+ * The resolved shape of one op's result — four kinds, and the printer handles
+ * all four rather than defaulting.
+ */
+export interface FoirManifestOpPayload {
+    /**
+     * - `record` — the payload IS the model named by `model`; print that model's
+     *   published `selection` as the root field's selection set.
+     * - `object` — `fields` is the resolved selection set. A field carrying
+     *   `model` expands to that model's `selection`, which is how the connection
+     *   and search-result wrappers keep the record's tree in one place instead of
+     *   copying it per op.
+     * - `union` — print one inline fragment per member of `selectionUnions[union]`.
+     * - `leaf` — `Boolean!`, `Int`, an enum. NO selection set: emitting `{}` is a
+     *   parse error, which is why this is a stated kind rather than empty `fields`.
+     */
+    kind: 'record' | 'object' | 'union' | 'leaf';
+    /** Model key, for kind `record`. */
+    model?: string;
+    /** `selectionUnions` key, for kind `union`. */
+    union?: string;
+    /** The resolved selection, for kind `object`. */
+    fields?: FoirManifestSelectionField[];
+    /** What this payload emits when printed whole, in `FoirManifestSelection.cost`'s unit. */
+    cost?: number;
+    /**
+     * Why this payload could not be resolved. Set INSTEAD of the shape fields,
+     * never beside them — an op carrying an error has no printable shape and a
+     * consumer must refuse it.
+     */
+    error?: string;
 }
 /** A built field the projection has no bucket for. Reported rather than dropped. */
 export interface FoirManifestUnclassifiedField {
@@ -95,6 +159,16 @@ export interface FoirManifestModel {
      * survived pruning — hence optional, not `{}`.
      */
     ops?: Record<string, FoirManifestOp>;
+    /**
+     * The resolved complete-by-default selection for this model. Present on a
+     * server that publishes selection trees; absent otherwise.
+     *
+     * It hangs off the MODEL rather than each op because every op whose payload
+     * is this model shares one selection root.
+     */
+    selection?: FoirManifestSelection;
+    /** Why `selection` is absent, when the server could not resolve one. */
+    selectionError?: string;
     scalars: FoirManifestScalar[];
     relations: FoirManifestRelation[];
     composites: FoirManifestComposite[];
@@ -108,6 +182,37 @@ export interface FoirManifestModel {
     unions?: Record<string, string[]>;
     /** Op names of this model's typed lookups. Each also appears in `ops`. */
     lookups?: string[];
+    /**
+     * The model's `<Type>OrderByInput`, projected — the vocabulary of the
+     * `orderBy` argument.
+     *
+     * `fields` are the entry keys a sort element may carry; `directions` are the
+     * value names of the enum those entries are typed as (`ASC` / `DESC`). Both
+     * are read off the built input object server-side, so neither can disagree
+     * with what the executor coerces a caller's `orderBy` against.
+     *
+     * IT IS PUBLISHED BECAUSE NOTHING ELSE HERE ANSWERS FOR IT, and `scalars` —
+     * the field that looks like it should — is wrong in both directions at once:
+     *
+     *  - wrong SET: `hero` (`Image`), `body` (`Richtext`), `_segments`
+     *    (`JSON`) and every soft-deleted field are scalars and none is sortable;
+     *  - wrong NAMES: the platform-managed columns are `_id` / `_createdAt` /
+     *    `_updatedAt` / `_naturalKey` on the record type and `id` / `createdAt` /
+     *    `updatedAt` / `naturalKey` in `OrderByInput`. A consumer deriving sort
+     *    keys from the scalar list emits `_createdAt`, which the server refuses.
+     *
+     * `ops[op].argTypes.orderBy` names the input type (`[PageOrderByInput]`) and
+     * stops there: enough to print a variable definition, not enough to type a
+     * call site.
+     *
+     * ABSENT means "this projection has nothing to say" — an embedded model, or a
+     * server that predates the field. A consumer must WIDEN on absent, never read
+     * it as "nothing is sortable".
+     */
+    orderBy?: {
+        fields: string[];
+        directions: string[];
+    };
     unclassifiedFields?: FoirManifestUnclassifiedField[];
     cacheControl?: {
         scope: string;
@@ -133,6 +238,20 @@ export interface FoirManifestNamespace {
     execute?: string[];
     /** `operations` only: operation keys reachable as `query.<key>`. */
     query?: string[];
+    /**
+     * Each of those root fields described the way a model op is described:
+     * arguments with their types, and the resolved shape of the result.
+     *
+     * Keyed by the token the op is ADDRESSED by — the root field name for every
+     * namespace but `operations`, where it is `execute.<key>` / `query.<key>` for
+     * the per-operation surfaces and the plain field name for the bookkeeping
+     * ones. The lists above stay authoritative for REACHABILITY; this is the
+     * description of what those names do.
+     *
+     * Because an entry is a `FoirManifestOp`, whatever prints a model op prints a
+     * namespace op — one code path, not two.
+     */
+    ops?: Record<string, FoirManifestOp>;
 }
 export interface FoirManifest {
     schemaVersion: number;
@@ -149,7 +268,151 @@ export interface FoirManifest {
     unclassified?: {
         queries?: string[];
         mutations?: string[];
+        /**
+         * Subscription root fields the server declined to state the reachability
+         * of — today only `events`, whose scope is charged against the resolved
+         * data-plane authority rather than the api key's own scope set. Reported so
+         * the gap is visible; nothing is generated from it.
+         */
+        subscriptions?: string[];
     };
+    /**
+     * Each union's expansion, once, keyed by union type name. A selection field
+     * references one by name rather than inlining it — seven models reaching one
+     * 56-member block union inlined it seven times and made the manifest 6.9x
+     * larger, 85% of it duplication.
+     *
+     * Absent on a server that predates selection trees, which is why every
+     * consumer must treat it as optional rather than assume the shape.
+     */
+    selectionUnions?: Record<string, FoirManifestSelectionUnion>;
+    /**
+     * Subscription root fields this credential may open over `/graphql/ws`.
+     *
+     * Unlike `models[].ops`, this list is NOT derived from the caller's schema
+     * variant: the server copies the whole Subscription root into every variant
+     * (the transport is out of band), so the variant admits all of them to
+     * everybody. The list is projected from the same table the socket charges at
+     * subscribe time, which is what makes it safe to generate against — a field
+     * that is here will be accepted, and one that is absent will be refused.
+     */
+    subscriptions?: FoirManifestSubscription[];
+}
+/**
+ * One subscription root field, with the tree a document is printed from.
+ */
+export interface FoirManifestSubscription {
+    /** The Subscription root field name. */
+    field: string;
+    /** Argument names, sorted. */
+    args?: string[];
+    /**
+     * Each name in `args` mapped to the GraphQL type the field declares for it —
+     * `'String!'` — spelled exactly as a variable definition needs it, and for
+     * the same reason `FoirManifestOp.argTypes` exists: a subscribe frame carries
+     * a `variables` object like any other operation, so without the type a
+     * consumer would have to infer a literal form from the value it holds.
+     *
+     * It also decides the variable NAME. The socket resolves an argument-gated
+     * subscription's scope by reading `variables[<arg>]` BY NAME, so
+     * `subscription S($m: String!) { recordChanged(modelKey: $m) … }` opens and is
+     * then refused for a scope it cannot complete. Declaring `$<arg>` — which is
+     * what a printer driven by this map does — is what keeps the two in step.
+     */
+    argTypes?: Record<string, string>;
+    /** GraphQL named type of the event payload. */
+    type: string;
+    /**
+     * The scope the socket charges. Empty exactly when `argScope` is set. Carried
+     * so a client can say WHICH capability a refusal was about instead of
+     * reporting a bare failure.
+     */
+    scope?: string;
+    /** Set when the required scope is completed by a subscribe argument. */
+    argScope?: FoirManifestSubscriptionArgScope;
+    /** Resolved complete-by-default selection for the payload type. */
+    selection?: FoirManifestSelection;
+    /** Why `selection` is absent. Absent is not "no fields". */
+    selectionError?: string;
+}
+/**
+ * A subscription whose authorization depends on a value supplied at subscribe
+ * time.
+ *
+ * `recordChanged` is the one instance: the socket charges
+ * `records:read:<modelKey>` against the `modelKey` variable, so the field has
+ * no static yes/no. What is statically true is which values this credential's
+ * scopes admit, and that is what `values` carries.
+ */
+export interface FoirManifestSubscriptionArgScope {
+    /** The subscribe argument whose value completes the scope. */
+    arg: string;
+    /** What the argument's value is appended to. */
+    prefix: string;
+    /**
+     * The argument values this credential admits, sorted. The ADDRESSABLE set,
+     * not a proof of exhaustiveness — a key holding the two-part `records:read`
+     * satisfies the socket for any string at all.
+     */
+    values: string[];
+}
+/**
+ * A resolved complete-by-default selection: what to ask for, already expanded.
+ *
+ * The server resolves this once per schema version — unions expanded per
+ * member, response-shape aliases assigned, cycles broken, field budget
+ * counted — so printing a document is string building rather than a schema
+ * walk. Nothing here requires the consumer to know a field's GraphQL type.
+ */
+export interface FoirManifestSelection {
+    fields: FoirManifestSelectionField[];
+    /**
+     * Fields this tree emits when printed whole, relations excluded. Same unit
+     * the executor's complexity budget is denominated in.
+     */
+    cost: number;
+}
+export interface FoirManifestSelectionField {
+    key: string;
+    /**
+     * The response key to emit instead of `key`, set only where a union member's
+     * field name collides with an incompatible shape on another member. A
+     * consumer prints `alias: key` and types the result under `alias`.
+     */
+    alias?: string;
+    /** Nested selection for a composite or a builtin value object. */
+    fields?: FoirManifestSelectionField[];
+    /**
+     * Names a model whose published `selection` IS this field's selection.
+     *
+     * It appears where a record turns up inside a payload the caller did not
+     * address the record through: a connection's `node`, a search result's
+     * `record`. A REFERENCE rather than an inlined copy, so seven ops over one
+     * model do not carry seven copies of its tree — and so a caller's `omit`
+     * reaches the same tree whichever op it came through.
+     */
+    model?: string;
+    /** Names an entry in `FoirManifest.selectionUnions`. */
+    union?: string;
+    /**
+     * `include` governs this field, so it is NOT part of the default document.
+     * Emit it only when the caller asks for it.
+     */
+    relation?: boolean;
+    /**
+     * The cycle or depth rule stopped expansion here. Still selectable, but only
+     * as `__typename` — print that rather than an empty body, which is a parse
+     * error.
+     */
+    truncated?: boolean;
+}
+export interface FoirManifestSelectionUnion {
+    /** Sorted by type name, so the expansion is stable across runs. */
+    members: FoirManifestSelectionMember[];
+}
+export interface FoirManifestSelectionMember {
+    typeName: string;
+    fields: FoirManifestSelectionField[];
 }
 /**
  * Fetch the manifest for the credential in `config`.