@foir/sdk 0.7.0 → 0.8.0

package/dist/data/schema.d.ts

@@ -11,9 +11,20 @@
  * What the generator emits
  * ---------------------------------------------------------------------------
  *
- * A single module, `foir.generated.ts`. A `.ts` and not a `.d.ts` for exactly
- * one reason: `foirSchemaVersion` has to survive to runtime for drift
- * detection. Everything else in the file is types and erases to nothing.
+ * A single module, `foir.generated.ts`, PASSED WHOLE:
+ *
+ * ```ts
+ * import * as generated from './foir.generated';
+ * const foir = createFoirClient({ apiUrl, apiKey, generated });
+ * ```
+ *
+ * A `.ts` and not a `.d.ts` because the file has a runtime half — the selection
+ * trees, `foirSchemaVersion`, and `foirSchemaType`, which is what carries
+ * `FoirSchema` across the type/value boundary so the client can infer it (a
+ * namespace import carries values; an interface erases). `FoirGeneratedModule`
+ * in `transport.ts` is the shape those exports have to satisfy, and it requires
+ * all of them: there is no case where a subset is wanted, and accepting one
+ * quietly meant a client that fetched the manifest on every cold start instead.
  *
  * ```ts
  * // foir.generated.ts — DO NOT EDIT. Generated by `foir types`.
@@ -23,14 +34,26 @@
  * export const foirSchemaVersion = 317;
  * export const foirSchemaChannel = 'published';
  *
- * export interface TillyBlock {
+ * // `<D>` ONLY on the types between the record and a union stopping point —
+ * // see rule 10. Everything else is emitted without it.
+ * export interface TillyBlock<D extends FoirDepthLevel = 1> {
  *   _id: string;
  *   _createdAt: string;
  *   text: string | null;
  *   // Composite/polymorphic fields are emitted as a STATIC discriminated
  *   // union on `__typename`. The client never infers these; it only has to
  *   // avoid destroying them. See `selection.ts`.
- *   body: Array<HeroBlock | TextBlock> | null;
+ *   body: Array<HeroBlock<D> | TextBlock> | null;
+ * }
+ *
+ * export interface HeroBlock<D extends FoirDepthLevel = 1> {
+ *   __typename: 'HeroBlock';
+ *   headline: string;
+ *   // The stopping point: a union reached from inside a union member is
+ *   // already on the op compiler's path, so it degrades — unless the caller
+ *   // bought a level. Mirrors the printer's `depth - 1` at this position.
+ *   body: Array<(D extends 1 ? TillyBlockBodyDegraded
+ *                            : TillyBlockBody<FoirDepthBelow[D]>) | null> | null;
  * }
  *
  * export interface TillyBlockFindUniqueArgs {
@@ -54,6 +77,8 @@
  *     tilly_block: {
  *       typeName: 'TillyBlock';
  *       fields: TillyBlock;
+ *       // Rule 10. Absent on a model with no stopping point, which is most.
+ *       atDepth: { 2: TillyBlock<2>; 3: TillyBlock<3>; 4: TillyBlock<4> };
  *       relations: {
  *         parentBlockId: { target: 'tilly_block'; list: false; nullable: true };
  *       };
@@ -80,6 +105,10 @@
  *     };
  *   };
  * }
+ *
+ * // The type carrier. `FoirSchema` is an interface and erases, so this is the
+ * // only thing a namespace import can infer it from. Runtime value: undefined.
+ * export const foirSchemaType = undefined as unknown as FoirSchema;
  * ```
  *
  * ---------------------------------------------------------------------------
@@ -87,9 +116,9 @@
  * ---------------------------------------------------------------------------
  *
  * 1. **Model keys are the manifest's model keys verbatim** (`tilly_block`, not
- *    `tillyBlock`). They are what `POST /v1/query` takes in `model`, and the
- *    client forwards the property name straight onto the wire. Renaming them
- *    for aesthetics breaks the request.
+ *    `tillyBlock`). They are the key the client looks the model's selection
+ *    tree up by, and the key a refusal names when there is no tree to look up.
+ *    Renaming them for aesthetics breaks the lookup.
  *
  * 2. **Op names are the manifest's op names verbatim** (`findUnique`,
  *    `findMany`, `search`, …) — the canonical names, NOT the GraphQL root
@@ -144,6 +173,27 @@
  *    (as the sketch above does) is the safe shape; if the generator ever
  *    factors these out for readability, they have to be `type X = {…}`.
  *    `__tests__/fixture-schema.ts` is the compiling reference.
+ *
+ * 10. **The `<D>` level parameter goes on the path to a stopping point, and
+ *     nowhere else.** A union reached from inside a union member is already on
+ *     the op compiler's path, so it degrades to `__typename` — and `depth: 2`
+ *     buys one such level back, on the wire AND in the type. The parameter is
+ *     what carries the caller's level from the record down to that position,
+ *     so it belongs on exactly the interfaces, union aliases and member
+ *     projections between the two, and the model names its shape at each level
+ *     under `atDepth`.
+ *
+ *     Both halves of "and nowhere else" matter. A parameter on a type that
+ *     reaches no stopping point is a generic instantiation at every reference
+ *     that can only ever resolve to the default — measured at 7 interfaces of
+ *     50 on the live dev project, which is why the change costs +1.6% types
+ *     rather than a multiple. And `= 1` on every one of them is what makes a
+ *     call passing no `depth` resolve to the type it always did; a parameter
+ *     without a default would be a breaking change to every generated name.
+ *
+ *     The generator computes the set (`depthReach`); it is not a judgement
+ *     call. See `builtins.ts` for `FoirDepthLevel` / `FoirDepthBelow`, and
+ *     `selection.ts` for the single lookup that reads `atDepth`.
  */
 /**
  * A model's complete scalar shape. Deliberately loose — the generator writes a
@@ -191,6 +241,26 @@ export interface FoirModelDefinition {
     readonly typeName: string;
     /** Complete scalar shape. See contract rule 4. */
     readonly fields: FoirFieldsShape;
+    /**
+     * The same shape at a depth ABOVE the default, keyed by the level a caller
+     * would pass as `depth`.
+     *
+     * Present only on models whose tree reaches a union stopping point — a
+     * position the op compiler refuses to expand because the union is already on
+     * its path. `depth: 2` expands one such level on the wire, and the entry
+     * under `2` is the model type describing what then arrives.
+     *
+     * OPTIONAL, and absent is the common case. A model with no stopping point
+     * reads identically at every depth, so generating an entry for it would emit
+     * a second name for one type. A LEVEL with no entry — a depth past what the
+     * generator emitted, or a `depth` that is not a literal at the call site —
+     * falls back to `fields`, which under-promises: the caller gets the values
+     * and narrows by hand, exactly as they did before this key existed. That is
+     * the safe direction, and the reason absence never has to be an error.
+     *
+     * Contract rule 9 applies: emit it as an object type LITERAL.
+     */
+    readonly atDepth?: Readonly<Record<number, FoirFieldsShape>>;
     readonly relations: Readonly<Record<string, FoirRelationDefinition>>;
     readonly ops: Readonly<Record<string, FoirOpDefinition>>;
 }

package/dist/data/selection.d.ts

@@ -50,14 +50,39 @@
  *     the pipeline to do it reds all six union tests plus the rest-operator
  *     one by name.
  *
- * So: never reach inside a field's value type when that type may be a UNION.
+ * So: never reach inside a field's value type WITH A MAPPED TYPE OVER THE UNION.
  *
  * Nested selection (`pick: { seo: { jsonLd: true } }`) does reach one level in,
  * and is safe only because `Descendable` refuses unions before it gets there —
- * see the guard below and the two tests that pin it. The list form of a union
- * is caught earlier still by the array check, which is why the guard needs a
- * NON-list union to be tested at all; a mutation disabling it left every test
- * green until one was added.
+ * see the guard below and the two tests that pin it.
+ *
+ * ---------------------------------------------------------------------------
+ * Per-variant selection, and why it is not a hole in the above
+ * ---------------------------------------------------------------------------
+ *
+ * `pick: { blocks: { on: { ImageBlock: ['height'] } } }` DOES narrow inside a
+ * polymorphic union, and it is safe for a reason the rule above does not cover:
+ * it distributes FIRST. `U extends { __typename: infer T } ? … : never` on a
+ * naked type parameter splits the union into its members, and every `Pick` or
+ * `Omit` below that line applies to ONE member. The union is reassembled from
+ * the branches, never mapped over whole, so `keyof (A | B | C)` is never taken
+ * and there is nothing to collapse.
+ *
+ * The distinction is the whole design, and it is worth stating as a rule
+ * because the wrong version of this change is a one-line widening of
+ * `Descendable`:
+ *
+ *   - reaching into a union with the VERB is Sanity's failure mode and stays
+ *     refused — `Descendable` still returns false for every union, and it
+ *     checks `IsUnion` rather than `IsPolymorphic` so that widening the
+ *     polymorphic branch cannot widen this one by accident;
+ *   - reaching into it through `on`, per member, keyed on `__typename`, is the
+ *     supported form.
+ *
+ * What DID change is that a LIST of composites is now descendable. Refusing
+ * lists was never about union safety — a union in a list is caught by the union
+ * check either way — and it made `pageContent.sections.blocks` untypeable end to
+ * end, since a list is the only thing between a page and its blocks.
  */
 import type { FoirConnection, FoirModelDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirRelationDefinition, FoirSchemaDefinition } from './schema';
 /**
@@ -104,7 +129,7 @@ export type FoirOmittableKey<M extends FoirModelDefinition> = Exclude<Extract<ke
 type OmittedKeys<Q> = Q extends {
     omit: readonly (infer K)[];
 } ? Extract<K, string> : never;
-type ApplyOmit<M extends FoirModelDefinition, Q> = [OmittedKeys<Q>] extends [never] ? M['fields'] : Omit<M['fields'], OmittedKeys<Q>>;
+type ApplyOmit<F, Q> = [OmittedKeys<Q>] extends [never] ? F : Omit<F, OmittedKeys<Q>>;
 /**
  * Every scalar key, including `_id`.
  *
@@ -126,7 +151,32 @@ type PickedKeys<Q> = Q extends {
  * This is the one place `pick` is not literally what was asked for, which is
  * why it is stated in the docs rather than left to be discovered.
  */
-type ApplyPick<M extends FoirModelDefinition, Q> = Pick<M['fields'], Extract<PickedKeys<Q> | '_id', keyof M['fields']>>;
+type ApplyPick<F, Q> = Pick<F, Extract<PickedKeys<Q> | '_id', keyof F>>;
+/**
+ * The level a call asked for. `1` — the complete-by-default document — when
+ * `depth` is absent, which is what makes the default result type reach
+ * `M['fields']` unchanged.
+ *
+ * A non-literal `depth` (a variable typed `number`) infers `D` as `number`,
+ * which matches no key below and falls back to the default shape. That
+ * under-promises rather than guessing, and is why `depth` can stay `number` at
+ * the call site instead of a literal union that would have to be regenerated.
+ */
+type DepthOf<Q> = Q extends {
+    depth: infer D extends number;
+} ? D : 1;
+/**
+ * The model's field shape at this call's depth.
+ *
+ * `M['fields']` BY IDENTITY whenever the model publishes no shape for the
+ * level — the default, every model without a stopping point, and any depth
+ * past what the generator emitted. `FoirRecordResult`'s identity property
+ * (a no-argument call hovers as `Product`, not as an anonymous object) is that
+ * fallback, so it holds for exactly the calls it held for before.
+ */
+type FieldsAtDepth<M extends FoirModelDefinition, Depth extends number> = M extends {
+    atDepth: infer A;
+} ? Depth extends keyof A ? A[Depth & keyof A] : M['fields'] : M['fields'];
 /**
  * One narrowing step for both verbs.
  *
@@ -134,7 +184,16 @@ type ApplyPick<M extends FoirModelDefinition, Q> = Pick<M['fields'], Extract<Pic
  * to decide which is present — `pick` first, and `omit` is then reached exactly
  * when `pick` is absent.
  */
-type ApplySelection<M extends FoirModelDefinition, Q> = [PickedKeys<Q>] extends [never] ? [SelectorOf<Q, 'pick'>] extends [never] ? [SelectorOf<Q, 'omit'>] extends [never] ? ApplyOmit<M, Q> : ApplyOmitSelector<M['fields'], SelectorOf<Q, 'omit'>> : ApplyPickSelector<M['fields'], SelectorOf<Q, 'pick'>> : ApplyPick<M, Q>;
+type ApplySelection<M extends FoirModelDefinition, Q, Depth extends number> = ApplySelectionOn<FieldsAtDepth<M, Depth>, Q>;
+/**
+ * The same two verbs, over an already-resolved field shape.
+ *
+ * Split out from `ApplySelection` only so the depth lookup is written ONCE. A
+ * conditional type has no `let`, so the alternative was `FieldsAtDepth<M, Depth>`
+ * spelled out in all four branches — four places for the two to drift apart,
+ * and the verbs stop being about `M` at all once the shape is chosen.
+ */
+type ApplySelectionOn<F, Q> = [PickedKeys<Q>] extends [never] ? [SelectorOf<Q, 'pick'>] extends [never] ? [SelectorOf<Q, 'omit'>] extends [never] ? ApplyOmit<F, Q> : ApplyOmitSelector<F, SelectorOf<Q, 'omit'>> : ApplyPickSelector<F, SelectorOf<Q, 'pick'>> : ApplyPick<F, Q>;
 /**
  * True when `T` is a union.
  *
@@ -145,21 +204,111 @@ type ApplySelection<M extends FoirModelDefinition, Q> = [PickedKeys<Q>] extends
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
 /**
- * Whether a field's value may be descended into.
+ * A field's value with its list wrapper and nullability stripped — the thing a
+ * selection actually addresses.
+ *
+ * A block field is `Array<Block | null> | null`; what a caller narrows is
+ * `Block`. Every classifier below asks about this rather than about `V`, so a
+ * union in a list and a union on its own reach the same answer instead of the
+ * list check shadowing the union check.
+ */
+type ElementOf<V> = NonNullable<V> extends readonly (infer E)[] ? NonNullable<E> : NonNullable<V>;
+/**
+ * Put back the wrapper `ElementOf` took off.
+ *
+ * Narrowing changes the ELEMENT and must not change the shape around it: a
+ * pick inside `Array<Block | null> | null` still arrives as an array, still
+ * nullable, still with nullable elements. Reconstructing it here is what keeps
+ * the result type describing the response rather than describing the part of it
+ * the narrowing was about.
+ */
+type Rewrap<V, T> = NonNullable<V> extends readonly (infer E)[] ? null extends E ? null extends V ? Array<T | null> | null : Array<T | null> : null extends V ? T[] | null : T[] : null extends V ? T | null : T;
+/**
+ * A `__typename`-discriminated union — a polymorphic block field, in practice.
+ *
+ * This is the ONE union shape that can be narrowed safely, because
+ * `__typename` gives a closed set of names to key the narrowing on and
+ * `Extract<U, { __typename: T }>` recovers a member without ever reaching
+ * inside the union itself. Any other union stays undescendable; see
+ * `Descendable`.
+ */
+type IsPolymorphic<V> = ElementOf<V> extends {
+    __typename: string;
+} ? IsUnion<ElementOf<V>> : false;
+/**
+ * Whether a field's value may be descended into with the verb.
+ *
+ * Objects yes — including a LIST of them, which this used to refuse. Refusing
+ * lists made `pageContent.sections.blocks` untypeable end to end even though the
+ * wire had always accepted it: a list is the only thing between a page and its
+ * blocks, so a list that could not be descended meant no block union could be
+ * reached at all.
+ *
+ * **Unions still no**, and the exclusion is unchanged in force even though the
+ * shape moved. `Pick` and `Omit` compile to `{ [P in K]: … }`, which is not
+ * homomorphic and does not distribute, and `keyof (A | B | C)` is the
+ * INTERSECTION of their keys — so narrowing inside a polymorphic block union
+ * with the verb collapses it to `{ __typename: 'A' | 'B' | 'C' }` and every
+ * branch's own fields vanish. That is Sanity's documented failure mode, and the
+ * union tests in `__tests__/selection.test-d.ts` go red the moment anything
+ * reaches inside a field's value type WITH A MAPPED TYPE OVER THE UNION.
+ *
+ * What changed is that a polymorphic union now has somewhere else to go: the
+ * `on` branch in `FoirSelector`, which distributes first and picks per member,
+ * so no mapped type ever sees the union whole. A union that is NOT
+ * `__typename`-discriminated has no such handle and is still `true`-only — the
+ * check here is `IsUnion`, not `IsPolymorphic`, precisely so that widening the
+ * polymorphic branch can never widen this one.
+ */
+type Descendable<V> = IsUnion<ElementOf<V>> extends true ? false : ElementOf<V> extends object ? true : false;
+/** The `__typename` literals of a polymorphic union. Closed, and generated. */
+type MemberNames<U> = U extends {
+    __typename: infer T extends string;
+} ? T : never;
+/** The one member of `U` whose `__typename` is `T`. */
+type MemberOf<U, T> = Extract<U, {
+    __typename: T;
+}>;
+/**
+ * The keys of one member a caller may name.
  *
- * Objects yes, **unions no**, and the exclusion is the whole point. `Pick` and
- * `Omit` compile to `{ [P in K]: … }`, which is not homomorphic and does not
- * distribute, and `keyof (A | B | C)` is the INTERSECTION of their keys — so
- * narrowing inside a polymorphic block union collapses it to
- * `{ __typename: 'A' | 'B' | 'C' }` and every branch's own fields vanish. That
- * is Sanity's documented failure mode, and the union tests in
- * `__tests__/selection.test-d.ts` go red the moment anything reaches inside a
- * field's value type.
+ * `__typename` is excluded because it is not optional: the printer emits it at
+ * the union level whatever the selection says, so offering it would suggest a
+ * choice that does not exist. Block-meta keys (`_id`, `_key`, `_type`,
+ * `_label`) ARE offered — unlike a record's `_id` the server does not force
+ * them inside a fragment, so naming them is the only way to keep them.
+ */
+type MemberKeys<U, T> = Exclude<Extract<keyof MemberOf<U, T>, string>, '__typename'>;
+/**
+ * The per-variant selector: name members, and for each either its keys or
+ * `true` for the whole member.
  *
- * The server will happily narrow inside a union; the types must not offer it.
- * Use GraphQL for that, which is what the transport-choice docs say.
+ * Every member is OPTIONAL, and what an absent one means is the verb's to
+ * decide — `pick` drops it, `omit` leaves it alone — matching what the printer
+ * does with a member the trie does not name.
  */
-type Descendable<V> = IsUnion<NonNullable<V>> extends true ? false : NonNullable<V> extends readonly unknown[] ? false : NonNullable<V> extends object ? true : false;
+export type FoirVariantSelector<U> = {
+    [T in MemberNames<U>]?: true | readonly MemberKeys<U, T>[];
+};
+/**
+ * Apply a per-variant `pick`.
+ *
+ * A member the selector does not name arrives as `{ __typename }` alone rather
+ * than disappearing: the printer drops its FRAGMENT, but `__typename` is
+ * selected once at the union level, so the element is still there and still
+ * discriminates. Typing it as absent would describe a response with fewer
+ * elements than the server sends.
+ */
+type ApplyVariantPick<U, S> = U extends {
+    __typename: infer T;
+} ? T extends keyof S ? S[T] extends true ? U : S[T] extends readonly (infer K)[] ? Pick<U, Extract<K | '__typename', keyof U>> : Pick<U, Extract<'__typename', keyof U>> : Pick<U, Extract<'__typename', keyof U>> : never;
+/**
+ * Apply a per-variant `omit`. The mirror of the above: an unnamed member is
+ * untouched, and `true` drops the whole fragment, leaving `{ __typename }`.
+ */
+type ApplyVariantOmit<U, S> = U extends {
+    __typename: infer T;
+} ? T extends keyof S ? S[T] extends true ? Pick<U, Extract<'__typename', keyof U>> : S[T] extends readonly (infer K)[] ? Omit<U, Extract<K, keyof U>> : U : U : never;
 /**
  * The nested selector: `true` for a leaf, or the verb again to descend.
  *
@@ -178,13 +327,15 @@ type Descendable<V> = IsUnion<NonNullable<V>> extends true ? false : NonNullable
  * an immediate "Type instantiation is excessively deep and possibly infinite".
  */
 export type FoirSelector<T, Verb extends 'pick' | 'omit', D extends number = SelectorDepth> = {
-    [K in keyof T]?: Descendable<T[K]> extends true ? D extends 0 ? true : true | {
-        [P in Verb]: FoirSelector<NonNullable<T[K]>, Verb, Decrement[D]>;
+    [K in keyof T]?: IsPolymorphic<T[K]> extends true ? true | {
+        on: FoirVariantSelector<ElementOf<T[K]>>;
+    } : Descendable<T[K]> extends true ? D extends 0 ? true : true | {
+        [P in Verb]: FoirSelector<ElementOf<T[K]>, Verb, Decrement[D]>;
     } : true;
 };
 /**
  * How deep a selector may nest. Three, matching `IncludeDepth`, and comfortably
- * past what real composites do — `ImageValue.variants.thumbnail` is the deepest
+ * past what real composites do — `Image.variants.thumbnail` is the deepest
  * shape on any live model at two.
  */
 type SelectorDepth = 3;
@@ -195,9 +346,7 @@ type SelectorOf<Q, Verb extends 'pick' | 'omit'> = Q extends Record<Verb, infer
  * reason it does in the flat form — the server always emits it.
  */
 type ApplyPickSelector<F, S> = {
-    [K in Extract<keyof S, keyof F> | Extract<'_id', keyof F>]: K extends keyof S ? S[K] extends {
-        pick: infer Inner;
-    } ? PickSelectorDeep<NonNullable<F[K]>, Inner> : F[K] : F[K];
+    [K in Extract<keyof S, keyof F> | Extract<'_id', keyof F>]: K extends keyof S ? NarrowPick<F[K], S[K]> : F[K];
 };
 /**
  * The same walk one level in. Separate from the root because `_id` is forced at
@@ -205,10 +354,28 @@ type ApplyPickSelector<F, S> = {
  * response shape the server never sends.
  */
 type PickSelectorDeep<F, S> = {
-    [K in Extract<keyof S, keyof F>]: S[K] extends {
-        pick: infer Inner;
-    } ? PickSelectorDeep<NonNullable<F[K]>, Inner> : F[K];
+    [K in Extract<keyof S, keyof F>]: NarrowPick<F[K], S[K]>;
 };
+/**
+ * One field's value under a `pick` selector: split a union, descend an object
+ * or a list of them, or leave a leaf alone.
+ *
+ * `Rewrap` is what makes the list case honest. Descending `sections` narrows
+ * each Section; the caller still receives the array, still nullable, with
+ * still-nullable elements, and reconstructing that is the difference between
+ * typing the response and typing the interesting part of it.
+ */
+type NarrowPick<V, Sel> = Sel extends {
+    on: infer Variants;
+} ? Rewrap<V, ApplyVariantPick<ElementOf<V>, Variants>> : Sel extends {
+    pick: infer Inner;
+} ? Rewrap<V, PickSelectorDeep<ElementOf<V>, Inner>> : V;
+/** The `omit` half of `NarrowPick`. */
+type NarrowOmit<V, Sel> = Sel extends {
+    on: infer Variants;
+} ? Rewrap<V, ApplyVariantOmit<ElementOf<V>, Variants>> : Sel extends {
+    omit: infer Inner;
+} ? Rewrap<V, ApplyOmitSelector<ElementOf<V>, Inner>> : V;
 /**
  * Apply a nested `omit` selector.
  *
@@ -217,9 +384,7 @@ type PickSelectorDeep<F, S> = {
  * able to shed one richtext encoding of three without losing the field.
  */
 type ApplyOmitSelector<F, S> = {
-    [K in keyof F as K extends keyof S ? (S[K] extends true ? never : K) : K]: K extends keyof S ? S[K] extends {
-        omit: infer Inner;
-    } ? ApplyOmitSelector<NonNullable<F[K]>, Inner> : F[K] : F[K];
+    [K in keyof F as K extends keyof S ? (S[K] extends true ? never : K) : K]: K extends keyof S ? NarrowOmit<F[K], S[K]> : F[K];
 };
 /**
  * The `include` argument for a model: every relation key, opt-in, optionally
@@ -235,8 +400,8 @@ export type FoirInclude<S extends FoirSchemaDefinition, M extends FoirModelDefin
     };
 };
 /** The relation keys a call asked for, shaped by list/nullable and nesting. */
-type IncludedRelations<S extends FoirSchemaDefinition, M extends FoirModelDefinition, I, D extends number> = {
-    [K in Extract<keyof I, keyof M['relations']>]: WrapRelation<M['relations'][K], FoirRecordResult<S, TargetModel<S, M['relations'][K]>, I[K], Decrement[D]>>;
+type IncludedRelations<S extends FoirSchemaDefinition, M extends FoirModelDefinition, I, D extends number, Depth extends number> = {
+    [K in Extract<keyof I, keyof M['relations']>]: WrapRelation<M['relations'][K], FoirRecordResult<S, TargetModel<S, M['relations'][K]>, I[K], Decrement[D], Depth>>;
 };
 type WrapRelation<R extends FoirRelationDefinition, T> = R['list'] extends true ? R['nullable'] extends true ? T[] | null : T[] : R['nullable'] extends true ? T | null : T;
 /**
@@ -253,10 +418,16 @@ type WrapRelation<R extends FoirRelationDefinition, T> = R['list'] extends true
  * reads well and names the generated interface — and, more to the point, it
  * means the only mapped type anywhere near a result is `Omit`. One less thing
  * between the generator's union and the call site.
+ *
+ * `Depth` is the call's union-level budget, defaulted FROM `Q` so every
+ * existing reference keeps working unchanged. It is passed to the relations
+ * UNDECREMENTED because the printer does the same: `printIncludes` carries the
+ * caller's depth into a relation's tree without spending any of it, so an
+ * included record's stopping points expand at exactly the level the root's do.
  */
-export type FoirRecordResult<S extends FoirSchemaDefinition, M extends FoirModelDefinition, Q, D extends number = IncludeDepth> = Q extends {
+export type FoirRecordResult<S extends FoirSchemaDefinition, M extends FoirModelDefinition, Q, D extends number = IncludeDepth, Depth extends number = DepthOf<Q>> = Q extends {
     include: infer I;
-} ? ApplySelection<M, Q> & IncludedRelations<S, M, I, D> : ApplySelection<M, Q>;
+} ? ApplySelection<M, Q, Depth> & IncludedRelations<S, M, I, D, Depth> : ApplySelection<M, Q, Depth>;
 /** Apply an op's return wrapper to the shaped record. */
 export type FoirOpResult<S extends FoirSchemaDefinition, M extends FoirModelDefinition, O extends FoirOpDefinition, Q> = O['returns'] extends {
     kind: 'opaque';
@@ -270,6 +441,29 @@ export type FoirOpResult<S extends FoirSchemaDefinition, M extends FoirModelDefi
     kind: 'record';
     nullable: infer N;
 } ? N extends true ? FoirRecordResult<S, M, Q> | null : FoirRecordResult<S, M, Q> : never;
+/**
+ * The depth budget, as a call option.
+ *
+ * A sibling of `include`/`omit`/`pick` rather than an argument: it shapes the
+ * DOCUMENT the client prints, and no root field declares an argument by that
+ * name. `number` rather than a literal union of the levels that fit, because
+ * what fits is a property of the PROJECT — the same level is comfortable on one
+ * model and over the ceiling on another — so the bound is a runtime refusal
+ * carrying the arithmetic, not a type that would have to be regenerated to stay
+ * true and would be wrong between runs.
+ *
+ * The RESULT type follows it. A stopping point the level reaches is typed as
+ * the expanded union rather than `FoirDegraded`, so `depth: 2` reads a nested
+ * member's own field with a `__typename` narrowing and no cast. The generator
+ * threads a level parameter through the composites on the path and names the
+ * instantiations under `FoirModelDefinition.atDepth`; `FieldsAtDepth` picks
+ * one. A LITERAL is what makes that lookup work — a `depth` read from a
+ * variable is `number`, matches no level, and falls back to the default shape,
+ * which under-promises rather than guessing.
+ */
+interface FoirDepthOption {
+    depth?: number;
+}
 /**
  * What a model op accepts: the op's own args with `include`/`omit` as siblings.
  * They are split back apart onto the wire (`{ model, op, args, include, omit }`)
@@ -281,7 +475,7 @@ export type FoirOpResult<S extends FoirSchemaDefinition, M extends FoirModelDefi
  */
 export type FoirQuery<S extends FoirSchemaDefinition, M extends FoirModelDefinition, O extends FoirOpDefinition> = O['returns'] extends {
     kind: 'opaque';
-} ? O['args'] : O['args'] & ({
+} ? O['args'] : O['args'] & FoirDepthOption & ({
     include?: FoirInclude<S, M>;
     omit?: readonly FoirOmittableKey<M>[] | FoirSelector<M['fields'], 'omit'>;
     /**