@foir/sdk 0.7.0 → 0.9.0

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'>;
     /**

package/dist/data/subjects.d.ts

@@ -0,0 +1,221 @@
+/**
+ * The subject registry — which records this client fetched.
+ *
+ * ---------------------------------------------------------------------------
+ * What it is for
+ * ---------------------------------------------------------------------------
+ *
+ * An annotation surface — a comment widget, a feedback button, a review prompt
+ * — has to say what it is about. Every tool that does this anchors to a URL or
+ * to a CSS selector, and both break the moment the page is redesigned, the
+ * route changes, or the reader is served a different locale or variant.
+ *
+ * A page rendered through this client does not have that problem, because the
+ * client already knows: it printed the document, it named the model, and every
+ * record in the response carries `_id` (the selection model protects it — see
+ * `PROTECTED_ROOT_FIELD`). So the anchor can be the RECORD, which survives all
+ * three, and it can be derived rather than configured.
+ *
+ * ```ts
+ * const subjects = createFoirSubjectRegistry();
+ * const foir = createFoirClient({ apiUrl, apiKey, generated, subjects });
+ *
+ * await foir.article.findUnique({ naturalKey: 'about-us' });
+ * subjects.subject(); // { modelKey: 'article', recordId: 'kx7p…' }
+ * ```
+ *
+ * Nothing here maps a URL, and nothing here may start to. A registry that fell
+ * back to the address bar would reintroduce exactly the fragility the record
+ * anchor exists to remove, and it would do so silently — the anchor would look
+ * identical and would point somewhere else after the next redesign.
+ *
+ * ---------------------------------------------------------------------------
+ * Why it is opt-in, and off unless you build one
+ * ---------------------------------------------------------------------------
+ *
+ * A list of the records a page fetched is a DISCLOSURE SURFACE. It names
+ * content by model key and id, including records a visitor never saw rendered —
+ * a draft pulled for an editor, a related record fetched and then filtered out
+ * in the template, the twelve nav pages behind a menu. Handing that to whatever
+ * else runs on the page (an analytics tag, an embedded widget, a browser
+ * extension) is a decision with consequences, and it is not this package's
+ * decision to make.
+ *
+ * So it is not a flag that defaults to false — it is an OBJECT the host
+ * constructs and owns. There is no configuration that turns it on by accident,
+ * the host holds the only reference, and its lifetime is the host's: a registry
+ * built per request on an edge runtime cannot outlive that request, which is the
+ * same reason nothing in this client keeps module-level state.
+ *
+ * The corollary is the one warning worth repeating: a registry built at MODULE
+ * scope on a multi-tenant edge worker is shared across tenants, exactly like a
+ * module-level response cache would be. Build one per client.
+ *
+ * ---------------------------------------------------------------------------
+ * Where the subjects come from
+ * ---------------------------------------------------------------------------
+ *
+ * From the plan, not from the response's shape. `planCall` derives the record
+ * positions from the payload the manifest published (`FoirDocumentPlan.records`)
+ * — the same walk that decides where `pick`/`omit` land — so the registry reads
+ * the response at the positions the server said records would be, rather than
+ * hunting for objects that happen to carry an `_id`.
+ */
+import { type FoirDocumentPlan } from './document';
+/**
+ * One thing an annotation can be about.
+ *
+ * `recordId` / `modelKey` and not `id` / `model`, matching
+ * `FoirRecordChangedEvent` in `subscriptions.ts`: a subscription event and a
+ * fetched subject name the same pair, and two spellings of one pair is how a
+ * consumer ends up writing an adapter between two halves of one SDK.
+ */
+export interface FoirSubject {
+    /** The record's model key, e.g. `article`. */
+    modelKey: string;
+    /** The record's `_id`. */
+    recordId: string;
+    /**
+     * A human label for the record, when one is available. See
+     * `FoirSubjectOptions.label` for where it comes from and why the client does
+     * not pick a field on its own.
+     */
+    label?: string;
+}
+/**
+ * How a record reached the registry.
+ *
+ * NOT a heuristic: it is read off the op's published payload. A payload whose
+ * kind is `record` IS one record, which means the caller addressed one record by
+ * name (`findUnique`, `create`, a lookup); a record reached through a field of
+ * an `object` payload arrived inside something — a connection's `edges.node`, a
+ * search wrapper's `record`.
+ *
+ * That distinction is what lets `subject()` answer at all. A page renders FROM
+ * the record it addressed and merely LISTS the rest, and the manifest already
+ * says which is which, so the client does not have to guess from result counts
+ * or field names.
+ */
+export type FoirSubjectOrigin = 'record' | 'collection';
+/** What `FoirSubjectRegistry.add` takes. */
+export interface FoirSubjectEntry {
+    modelKey: string;
+    recordId: string;
+    /**
+     * Defaults to `record`, which is what a hand-seeded entry means: you named
+     * this record deliberately. The data path passes the origin it read off the
+     * plan.
+     */
+    origin?: FoirSubjectOrigin;
+    /**
+     * The record as it arrived, for the labeller to read. Optional, because a
+     * host seeding a subject from an id has no record object to hand.
+     */
+    record?: Readonly<Record<string, unknown>>;
+    /** An explicit label. Wins over the labeller and over `_naturalKey`. */
+    label?: string;
+}
+export interface FoirSubjectOptions {
+    /**
+     * Turn a record into the label a widget shows: `"About Us"` rather than
+     * `article/kx7p…`.
+     *
+     * There is no default that reads one of your fields, and that is deliberate.
+     * The manifest publishes a model's scalars and their types; it does not
+     * publish which one is the title, because there is no such concept — one
+     * project calls it `title`, the next `name`, the next `headline`. A client
+     * that picked `title` when it saw one would label most projects correctly and
+     * mislabel the rest, silently, in the one string a reader actually reads.
+     *
+     * So the field is yours to name, in one line:
+     *
+     * ```ts
+     * createFoirSubjectRegistry({
+     *   label: (record) => (record.title as string) ?? null,
+     * });
+     * ```
+     *
+     * Return `null` or `undefined` for "no label" — the subject is still
+     * recorded, just without one. It must not throw: see `recordFoirSubjects`.
+     */
+    label?: (record: Readonly<Record<string, unknown>>, subject: FoirSubject) => string | null | undefined;
+}
+export interface FoirSubjectRegistry {
+    /**
+     * Record one subject.
+     *
+     * The data path calls this for you. Call it yourself to seed a subject this
+     * client did not fetch — a server-rendered page whose record was read on the
+     * server, or a record that arrived through `foir.raw()`, which prints no
+     * published payload and therefore has no record positions to read.
+     */
+    add(entry: FoirSubjectEntry): void;
+    /**
+     * Every record recorded so far, de-duplicated on `modelKey` + `recordId` and
+     * ordered least-recently-fetched first — so the last entry is the last record
+     * this client saw, whether or not it was addressed by name.
+     *
+     * This is what a widget offers when it wants to let the reader choose, and it
+     * is the honest answer for a page whose data all came out of lists.
+     */
+    fetched(): readonly FoirSubject[];
+    /**
+     * The subject to annotate: your override if you set one, otherwise the last
+     * record this client addressed BY NAME.
+     *
+     * One rule, and no case analysis behind it. A record that only ever appeared
+     * inside a list is never promoted — a page that fetched twelve nav entries and
+     * nothing else has no subject, and saying so is better than picking one of the
+     * twelve. Use `fetched()` or `setSubject()` there.
+     */
+    subject(): FoirSubject | undefined;
+    /**
+     * Pin the subject, overriding whatever was fetched. `null` drops the override
+     * and goes back to the fetched answer.
+     */
+    setSubject(subject: FoirSubject | null): void;
+    /**
+     * Forget everything: the recorded records AND the override.
+     *
+     * A single-page app must call this when it navigates. Without it the registry
+     * accumulates every record the session ever touched and `subject()` keeps
+     * answering with a record from a page the reader has left.
+     */
+    clear(): void;
+    /**
+     * Run `listener` after every change, and return the function that stops it.
+     *
+     * For a widget mounted before the data resolves. Listeners run synchronously
+     * in registration order; one that throws does not stop the others, and the
+     * failure is reported rather than dropped (see `recordFoirSubjects`).
+     */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Build a registry.
+ *
+ * Per client, never at module scope — see the file header. It is handed to
+ * `createFoirClient` as `subjects`, and the host keeps the same reference to
+ * read from.
+ */
+export declare function createFoirSubjectRegistry(options?: FoirSubjectOptions): FoirSubjectRegistry;
+/**
+ * Record what one call fetched.
+ *
+ * A no-op without a registry, which is what "off by default" means at runtime:
+ * a client built without `subjects` walks nothing and allocates nothing.
+ *
+ * # Errors are not swallowed here
+ *
+ * The only things that can fail are the host's own: a `label` function, or a
+ * `subscribe` listener. Both are re-thrown, wrapped in a message that says the
+ * REQUEST succeeded so the failure cannot be read as a transport fault.
+ *
+ * Catching them would be worse than it looks. A subject that silently failed to
+ * record does not degrade to "no annotation offered" — it degrades to the
+ * PREVIOUS subject still being the answer, so the widget offers to comment on
+ * the record the reader was looking at a moment ago. A loud failure in a
+ * function the host wrote is strictly better than an annotation filed against
+ * the wrong record.
+ */
+export declare function recordFoirSubjects(registry: FoirSubjectRegistry | undefined, plan: Pick<FoirDocumentPlan, 'records'>, result: unknown): void;