@foir/sdk 0.5.0 → 0.8.0

package/dist/data/selection.d.ts

@@ -0,0 +1,524 @@
+/**
+ * The type-level selection machinery — deliberately shallow.
+ *
+ * Two operations and nothing else:
+ *
+ *   1. `Omit<Fields, K>` for `omit`.
+ *   2. One conditional per `include`d relation key.
+ *
+ * No template-literal parsing (Supabase's approach, and the source of its
+ * `tsc` perf complaints), no deep recursive mapped types over field values, no
+ * build-time query parser. The complete-by-default selection model is what
+ * makes that enough: scalars are ALWAYS returned, so the model type is
+ * unconditionally true and there is nothing to narrow. If this file ever
+ * misbehaves the failure mode is a missing relation key, not a mis-parsed
+ * string.
+ *
+ * ---------------------------------------------------------------------------
+ * Why unions survive
+ * ---------------------------------------------------------------------------
+ *
+ * Sanity's typegen — a mature, shipped implementation of the same
+ * architecture — is documented to lose discriminated-union information on
+ * rest-operator array projections. That is the fragile part of any generated
+ * type system, so it is worth being explicit about why it cannot happen here:
+ *
+ * every transformation below operates on the OUTER object's keys only. `Omit`,
+ * `Simplify` and the include-shape mapped type all iterate `keyof Fields` and
+ * copy `Fields[K]` through untouched. A polymorphic field's value type — a
+ * union of `__typename`-discriminated members, written out statically by the
+ * generator — is a property VALUE. It is never mapped over, never distributed,
+ * never re-inferred, so it arrives at the call site byte-identical to what the
+ * generator emitted and narrows under `switch` exactly as it would have.
+ *
+ * `__tests__/selection.test-d.ts` pins this, including the rest-operator and
+ * `.map()` shapes that break Sanity.
+ *
+ * Two notes for whoever edits this file next, both found by mutating it and
+ * watching what the tests did:
+ *
+ *   - A homomorphic mapped type over a NAKED type parameter — the classic
+ *     `type Simplify<T> = { [K in keyof T]: T[K] }` applied to an array's
+ *     element type — is SAFE. It distributes over unions, so the discriminated
+ *     union comes out the other side intact. Mutating the pipeline to do this
+ *     left all six union tests green.
+ *   - `Omit<U, …>` or `Pick<U, …>` on that element type is NOT safe. Both
+ *     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 the union collapses to `{ __typename: 'A' | 'B' | 'C' }` and every
+ *     branch's own fields vanish. That is Sanity's failure mode, and mutating
+ *     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 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.
+ *
+ * ---------------------------------------------------------------------------
+ * 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';
+/**
+ * How deep `include` may nest. Finite by necessity, not by taste: relations are
+ * routinely self-referential (`tilly_block.parentBlockId -> tilly_block`), and
+ * an uncapped recursive mapped type over that is an immediate
+ * "Type instantiation is excessively deep and possibly infinite".
+ */
+type IncludeDepth = 3;
+/** `Decrement[3] === 2`. */
+type Decrement = [never, 0, 1, 2, 3];
+/**
+ * The model a relation resolves to. Falls back to a relation-free, opaque model
+ * when the generated schema names a target that is not in `models` — a
+ * malformed generated file should surface as a useless-but-quiet type, not as a
+ * mapped type over `keyof never`.
+ */
+type TargetModel<S extends FoirSchemaDefinition, R extends FoirRelationDefinition> = R['target'] extends keyof S['models'] ? S['models'][R['target']] : OpaqueModel;
+type OpaqueModel = {
+    typeName: string;
+    fields: Record<string, unknown>;
+    relations: Record<never, FoirRelationDefinition>;
+    ops: Record<never, FoirOpDefinition>;
+};
+/**
+ * The keys a caller may `omit`.
+ *
+ * `_id` is excluded because the server refuses it — verified against deployed
+ * dev: `omit "_id": "_id" is required for correctness and cannot be removed`
+ * (HTTP 400). Excluding it here turns a runtime 400 into a compile error.
+ *
+ * Relations are absent by construction: they are not in `fields`, and omitting
+ * something you never asked for is meaningless.
+ */
+export type FoirOmittableKey<M extends FoirModelDefinition> = Exclude<Extract<keyof M['fields'], string>, '_id'>;
+/**
+ * The `omit` entries actually present in a call.
+ *
+ * `never` when `omit` was not passed. That matters: an OPTIONAL `omit?:` on the
+ * inferred query type does not satisfy the required-property check below, so
+ * the no-argument case (where `Q` falls back to its own constraint) correctly
+ * omits nothing rather than omitting every omittable key.
+ */
+type OmittedKeys<Q> = Q extends {
+    omit: readonly (infer K)[];
+} ? Extract<K, string> : never;
+type ApplyOmit<F, Q> = [OmittedKeys<Q>] extends [never] ? F : Omit<F, OmittedKeys<Q>>;
+/**
+ * Every scalar key, including `_id`.
+ *
+ * Unlike `FoirOmittableKey` this does NOT exclude `_id`: naming it is harmless
+ * because it survives either way, and excluding it would make the obvious
+ * `pick: ['_id', 'title']` a type error for no reason.
+ */
+export type FoirPickableKey<M extends FoirModelDefinition> = Extract<keyof M['fields'], string>;
+/** The `pick` entries actually present in a call. `never` when absent — see OmittedKeys. */
+type PickedKeys<Q> = Q extends {
+    pick: readonly (infer K)[];
+} ? Extract<K, string> : never;
+/**
+ * `_id` is added back unconditionally, because the server emits it whatever the
+ * caller asked for (`protectedSelectionFields`). Typing the result without it
+ * would describe a response the server does not send, and a caller would lose
+ * the ability to address the record they just read.
+ *
+ * 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<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.
+ *
+ * They are mutually exclusive on the wire and in `FoirQuery`, so this only has
+ * to decide which is present — `pick` first, and `omit` is then reached exactly
+ * when `pick` is absent.
+ */
+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.
+ *
+ * Load-bearing for the guard below rather than a curiosity: a union distributed
+ * through `(U extends any ? (k: U) => void : never)` intersects to something
+ * that is not assignable back to the original, which a single type always is.
+ */
+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;
+/**
+ * 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.
+ *
+ * `__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.
+ *
+ * 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.
+ */
+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.
+ *
+ * The verb repeats at each level — `pick: { seo: { pick: { jsonLd: true } } }` —
+ * which is Prisma's shape and, more to the point here, the shape `include`
+ * already uses (`include: { author: { include: { tags: true } } }`). One idiom
+ * in the call rather than two.
+ *
+ * Repeating the keyword also leaves a slot: a future `include: { author: { pick:
+ * {…} } }` has somewhere to live. A bare child map — the first cut of this —
+ * had nowhere to put it and, worse, could not express more than one level, so
+ * `image.variants.thumbnail` was reachable on the wire and untypeable here.
+ *
+ * `D` bounds the recursion for the same reason `IncludeDepth` does: composites
+ * can reference each other, and an uncapped recursive mapped type over that is
+ * 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]?: 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 — `Image.variants.thumbnail` is the deepest
+ * shape on any live model at two.
+ */
+type SelectorDepth = 3;
+/** The selector actually present under `verb`, or `never` when absent or an array. */
+type SelectorOf<Q, Verb extends 'pick' | 'omit'> = Q extends Record<Verb, infer S> ? S extends readonly unknown[] ? never : S : never;
+/**
+ * Apply a nested `pick` selector. `_id` survives regardless, for the same
+ * 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 ? NarrowPick<F[K], S[K]> : F[K];
+};
+/**
+ * The same walk one level in. Separate from the root because `_id` is forced at
+ * the ROOT only — a composite has no `_id`, and adding one would describe a
+ * response shape the server never sends.
+ */
+type PickSelectorDeep<F, S> = {
+    [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.
+ *
+ * `true` at a key drops the whole field. An object at a key drops only the
+ * named children, which is what makes `omit: { description: { markdown: true } }`
+ * 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 ? NarrowOmit<F[K], S[K]> : F[K];
+};
+/**
+ * The `include` argument for a model: every relation key, opt-in, optionally
+ * carrying a nested `include` for the relation's own relations.
+ *
+ * `true` only (not `boolean`) — a `false` would go on the wire and the server
+ * validates `include` keys strictly, so a conditional include has to be built
+ * by conditionally spreading the key, not by passing `false`.
+ */
+export type FoirInclude<S extends FoirSchemaDefinition, M extends FoirModelDefinition, D extends number = IncludeDepth> = {
+    [K in keyof M['relations']]?: D extends 0 ? true : true | {
+        include?: FoirInclude<S, TargetModel<S, M['relations'][K]>, Decrement[D]>;
+    };
+};
+/** 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, 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;
+/**
+ * A model as this call will receive it: the complete scalar shape, minus
+ * `omit`, plus the `include`d relations.
+ *
+ * When neither was passed this resolves to `M['fields']` BY IDENTITY — not a
+ * structurally-equal copy — so `foir.tilly_block.findUnique({ id })` hovers as
+ * `TillyBlock` rather than as an anonymous 40-property object literal.
+ *
+ * `include` produces an INTERSECTION rather than a flattened object, on
+ * purpose. A `{ [K in keyof T]: T[K] }` flattening pass would read a little
+ * tidier in a hover, but `TillyBlock & { noteId: TillyNote | null }` already
+ * 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, Depth extends number = DepthOf<Q>> = Q extends {
+    include: infer I;
+} ? 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';
+    type: infer T;
+} ? T : O['returns'] extends {
+    kind: 'connection';
+} ? FoirConnection<FoirRecordResult<S, M, Q>> : O['returns'] extends {
+    kind: 'list';
+    nullable: infer N;
+} ? N extends true ? Array<FoirRecordResult<S, M, Q>> | null : Array<FoirRecordResult<S, M, Q>> : O['returns'] extends {
+    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 }`)
+ * — `include`/`omit` are selection, not arguments — but at the call site a
+ * single flat object is what reads well.
+ *
+ * An `opaque` op returns something that is not the model, so selection does not
+ * apply and is not offered.
+ */
+export type FoirQuery<S extends FoirSchemaDefinition, M extends FoirModelDefinition, O extends FoirOpDefinition> = O['returns'] extends {
+    kind: 'opaque';
+} ? O['args'] : O['args'] & FoirDepthOption & ({
+    include?: FoirInclude<S, M>;
+    omit?: readonly FoirOmittableKey<M>[] | FoirSelector<M['fields'], 'omit'>;
+    /**
+     * Mutually exclusive with `omit`, mirroring the server's 400. Typed as
+     * `never?` on this branch rather than left out, because omitting the key
+     * would let an object carrying BOTH satisfy this branch and reach the
+     * wire — the excess-property check does not fire on a value inferred
+     * into a generic parameter, which is the same hole `NoExtraKeys` exists
+     * to close.
+     */
+    pick?: never;
+} | {
+    include?: FoirInclude<S, M>;
+    pick?: readonly FoirPickableKey<M>[] | FoirSelector<M['fields'], 'pick'>;
+    omit?: never;
+});
+/**
+ * Reject keys the op does not declare.
+ *
+ * TypeScript's excess-property check does NOT fire when an object literal is
+ * inferred into a generic type parameter — `Q` is inferred as the literal's own
+ * shape and then merely has to be *assignable* to its constraint, which an
+ * object with extra keys is. So `findUnique({ id, first: 10 })` compiled
+ * silently and sent `first` to a server that does not take it. Typing every
+ * undeclared key as `never` puts the check back: `first: 10` is not assignable
+ * to `never`, and the error lands on the offending key.
+ *
+ * Pinned by "rejects an arg the op does not declare" in
+ * `__tests__/selection.test-d.ts`.
+ */
+type NoExtraKeys<Q, T> = Record<Exclude<keyof Q, keyof T>, never>;
+/**
+ * One model operation.
+ *
+ * `const Q` is what makes `omit: ['bodyRichtext']` infer as the tuple
+ * `readonly ['bodyRichtext']` instead of `string[]`; without it `Omit` would
+ * have nothing to remove. It also pins `include: { author: true }` to the
+ * literal `true`.
+ */
+export type FoirModelOperation<S extends FoirSchemaDefinition, M extends FoirModelDefinition, O extends FoirOpDefinition> = <const Q extends FoirQuery<S, M, O>>(query?: Q & NoExtraKeys<Q, FoirQuery<S, M, O>>) => Promise<FoirOpResult<S, M, O, Q>>;
+/**
+ * One namespace operation. No model behind it, so no `include`/`omit` and the
+ * generated result type is used verbatim.
+ */
+export type FoirNamespaceOperation<O extends FoirNamespaceOpDefinition> = (args?: O['args']) => Promise<O['result']>;
+export {};