@foir/sdk 0.7.0 → 0.8.0

package/dist/data.js

@@ -73,6 +73,13 @@ function buildFoirHeaders(input) {
   }
   return headers;
 }
+function foirApiEndpoint(apiUrl, path) {
+  const base = apiUrl.trim().replace(/\/+$/, "").replace(/\/graphql$/i, "");
+  if (!base) {
+    throw new FoirRequestError("[foir] apiUrl is empty \u2014 pass the Foir API origin");
+  }
+  return base + path;
+}
 function readFoirEnvelope(json) {
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
@@ -90,44 +97,105 @@ function readFoirEnvelope(json) {
   return json.data;
 }
 
+// src/transport/persisted-query.ts
+var FOIR_CDN_GRAPHQL_PATH = "/cdn/graphql";
+function persistedQueryExtension(hash) {
+  return { persistedQuery: { version: 1, sha256Hash: hash } };
+}
+function buildCdnUrl(endpoint, apiKey, hash, variables) {
+  const url = new URL(endpoint);
+  url.pathname = url.pathname.replace(/\/graphql\/?$/, "") + FOIR_CDN_GRAPHQL_PATH;
+  url.searchParams.set("key", apiKey);
+  url.searchParams.set("extensions", JSON.stringify(persistedQueryExtension(hash)));
+  if (variables && Object.keys(variables).length > 0) {
+    url.searchParams.set("variables", JSON.stringify(variables));
+  }
+  return url.toString();
+}
+async function documentHash(documentText) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(documentText));
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var PERSISTED_QUERY_NOT_FOUND = "PERSISTED_QUERY_NOT_FOUND";
+var NOT_SHAREABLE = "NOT_SHAREABLE";
+async function hasFoirErrorCode(res, ...codes) {
+  try {
+    const body = await res.clone().json();
+    return body.errors?.some((e) => e.extensions?.code !== void 0 && codes.includes(e.extensions.code)) ?? false;
+  } catch {
+    return false;
+  }
+}
+
 // src/data/transport.ts
 function foirDataEndpoint(apiUrl, path) {
-  const base = apiUrl.trim().replace(/\/+$/, "").replace(/\/graphql$/i, "");
-  if (!base) {
-    throw new FoirRequestError("[foir] apiUrl is empty \u2014 pass the Foir API origin");
-  }
-  return base + path;
+  return foirApiEndpoint(apiUrl, path);
 }
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
   if (typeof source === "function") return await source() ?? void 0;
   return source ?? void 0;
 }
-async function readErrorBody(res) {
-  try {
-    const json = await res.json();
-    return json?.errors?.length ? json.errors : void 0;
-  } catch {
-    return void 0;
+function foirRoute(input) {
+  if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
+  if (input.bearerToken) return { lane: "origin", reason: "bearer" };
+  if (input.mutation) return { lane: "origin", reason: "operation" };
+  if (input.channel === "draft") return { lane: "origin", reason: "channel" };
+  return { lane: "shared" };
+}
+async function executeFoirDocument(config, plan) {
+  const data = await runFoirDocument(config, plan.document, plan.mutation, plan.variables);
+  if (!(plan.rootField in data)) {
+    throw new FoirRequestError(
+      `[foir] the response has no "${plan.rootField}" field` + (Object.keys(data).length ? ` (got ${Object.keys(data).join(", ")})` : "")
+    );
   }
+  return data[plan.rootField];
+}
+async function executeFoirRawDocument(config, document, mutation, variables) {
+  return await runFoirDocument(config, document, mutation, variables);
 }
-async function postFoirOp(config, body) {
-  const url = foirDataEndpoint(config.apiUrl, "/v1/query");
+async function runFoirDocument(config, document, mutation, variables) {
   const doFetch = config.fetch ?? globalThis.fetch;
+  const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
+  const bearerToken = await resolveBearerToken(config);
   const headers = buildFoirHeaders({
     apiKey: config.apiKey,
     draftChannel: config.channel === "draft",
-    bearerToken: await resolveBearerToken(config),
+    bearerToken,
     extra: config.headers
   });
+  const hash = await documentHash(document);
+  const route = foirRoute({
+    apiKey: config.apiKey,
+    bearerToken,
+    mutation,
+    channel: config.channel
+  });
+  const post = (body) => doFetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    ...config.requestInit
+  });
+  const extensions = persistedQueryExtension(hash);
   let res;
   try {
-    res = await doFetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(body),
-      ...config.requestInit
-    });
+    if (route.lane === "shared") {
+      res = await doFetch(buildCdnUrl(endpoint, config.apiKey, hash, variables), {
+        method: "GET",
+        headers,
+        ...config.requestInit
+      });
+      if (await hasFoirErrorCode(res, PERSISTED_QUERY_NOT_FOUND, NOT_SHAREABLE)) {
+        res = await post({ query: document, variables, extensions });
+      }
+    } else {
+      res = await post({ variables, extensions });
+      if (await hasFoirErrorCode(res, PERSISTED_QUERY_NOT_FOUND)) {
+        res = await post({ query: document, variables, extensions });
+      }
+    }
   } catch (err) {
     throw new FoirRequestError("[foir] network error", { cause: err });
   }
@@ -140,14 +208,15 @@ async function postFoirOp(config, body) {
     });
   }
   const json = await res.json();
-  const data = readFoirEnvelope(json);
-  const roots = Object.keys(data);
-  if (roots.length !== 1) {
-    throw new FoirRequestError(
-      `[foir] expected exactly one root field in the /v1/query response, got ${roots.length}` + (roots.length ? ` (${roots.join(", ")})` : "")
-    );
+  return readFoirEnvelope(json);
+}
+async function readErrorBody(res) {
+  try {
+    const json = await res.json();
+    return json?.errors?.length ? json.errors : void 0;
+  } catch {
+    return void 0;
   }
-  return data[roots[0]];
 }
 
 // src/data/manifest.ts
@@ -178,6 +247,1127 @@ async function fetchFoirManifest(config) {
   return await res.json();
 }
 
+// src/data/document.ts
+function buildPathTrie(paths) {
+  const root = { self: false, children: /* @__PURE__ */ new Map() };
+  for (const path of paths) {
+    let node = root;
+    for (const segment of path.split(".")) {
+      if (!segment) continue;
+      let next = node.children.get(segment);
+      if (!next) {
+        next = { self: false, children: /* @__PURE__ */ new Map() };
+        node.children.set(segment, next);
+      }
+      node = next;
+    }
+    node.self = true;
+  }
+  return root;
+}
+function childFor(node, field) {
+  return node.children.get(field.key) ?? (field.alias ? node.children.get(field.alias) : void 0);
+}
+function segmentFor(node, field) {
+  return node.children.has(field.key) ? field.key : field.alias ?? field.key;
+}
+var PROTECTED_ROOT_FIELD = "_id";
+var MAX_QUERY_COMPLEXITY = 1e4;
+var MAX_EMITTED_FIELDS = 4 * MAX_QUERY_COMPLEXITY;
+var newBudget = () => ({ fields: 0, emitted: 0, stopped: false });
+function charge(ctx, n = 1) {
+  ctx.budget.fields += n;
+  ctx.budget.emitted += n;
+}
+function mayExpand(ctx, depth) {
+  if (depth <= 1) return false;
+  if (ctx.budget.emitted > MAX_EMITTED_FIELDS) {
+    ctx.budget.stopped = true;
+    return false;
+  }
+  return true;
+}
+function printFields(fields, ctx, omit, pick, isRoot, path, depth) {
+  const parts = [];
+  for (const field of fields) {
+    if (field.relation) {
+      const named = pick ? childFor(pick, field) : void 0;
+      if (named) {
+        const segment = segmentFor(pick, field);
+        throw new FoirRequestError(
+          `[foir] pick "${path}${segment}": "${segment}" is a relation, and relations are not part of the default document \u2014 no pick can select one. ` + (path ? (
+            // Nested: there is no `include` form that reaches here at all.
+            // `include` addresses the ROOT model's own relations, and (nested)
+            // a related model's — never one reached through a composite or a
+            // union member. Saying "use include" would send the caller to a
+            // call that refuses them a second time.
+            `A relation at this position cannot be reached by \`include\` either \u2014 that addresses the model's own relations, not one inside a composite or a union member. Read it through the field that owns it, or drop "${path}${segment}" from the pick`
+          ) : `Use include: { ${segment}: true } instead`)
+        );
+      }
+      continue;
+    }
+    const protectedField = isRoot && field.key === PROTECTED_ROOT_FIELD;
+    const omitChild = omit ? childFor(omit, field) : void 0;
+    if (omitChild?.self && !protectedField) continue;
+    let pickChild;
+    if (pick) {
+      pickChild = childFor(pick, field);
+      if (!pickChild && !protectedField) continue;
+      if (pickChild?.self) pickChild = void 0;
+    }
+    const head = field.alias ? `${field.alias}: ${field.key}` : field.key;
+    const childPath = `${path}${pick && childFor(pick, field) ? segmentFor(pick, field) : field.key}.`;
+    if (field.truncated) {
+      if (field.union && mayExpand(ctx, depth)) {
+        const body = printUnion(field.union, ctx, omitChild, pickChild, childPath, depth - 1);
+        if (body) {
+          charge(ctx);
+          parts.push(`${head} ${body}`);
+          continue;
+        }
+      }
+      charge(ctx, 2);
+      parts.push(`${head} { __typename }`);
+      continue;
+    }
+    if (field.model) {
+      const body = printModelTree(field.model, ctx, depth);
+      if (body) {
+        charge(ctx);
+        parts.push(`${head} { ${body} }`);
+      }
+      continue;
+    }
+    if (field.union) {
+      const body = printUnion(field.union, ctx, omitChild, pickChild, childPath, depth);
+      if (body) {
+        charge(ctx);
+        parts.push(`${head} ${body}`);
+      }
+      continue;
+    }
+    if (field.fields?.length) {
+      const body = printFields(field.fields, ctx, omitChild, pickChild, false, childPath, depth);
+      if (body) {
+        charge(ctx);
+        parts.push(`${head} { ${body} }`);
+      }
+      continue;
+    }
+    charge(ctx);
+    parts.push(head);
+  }
+  return parts.join(" ");
+}
+function printModelTree(modelKey, ctx, depth) {
+  const model = ctx.source.models[modelKey];
+  if (!model?.selection) {
+    throw new FoirRequestError(
+      `[foir] the result shape references the model "${modelKey}", which publishes no selection \u2014 re-run \`foir types\``
+    );
+  }
+  const narrowing = ctx.record?.modelKey === modelKey ? ctx.record : void 0;
+  const body = printFields(
+    model.selection.fields,
+    ctx,
+    narrowing?.omit,
+    narrowing?.pick,
+    true,
+    "",
+    depth
+  );
+  const includes = narrowing?.include ? printIncludes(ctx.source, model, modelKey, narrowing.include, ctx, depth) : "";
+  if (!body) {
+    return includes;
+  }
+  return includes ? `${body} ${includes}` : body;
+}
+function printFoirSelectionBody(fields, unions, models = {}) {
+  return printFields(
+    fields,
+    { source: { models }, unions, budget: newBudget() },
+    void 0,
+    void 0,
+    false,
+    "",
+    // A subscription payload takes no caller options, so it prints at the
+    // default level: every stopping point degrades to `__typename` exactly as
+    // it did before depth existed.
+    DEFAULT_DEPTH
+  );
+}
+var NO_FIELDS = { self: false, children: /* @__PURE__ */ new Map() };
+function addressesMembers(node, union) {
+  for (const member of union.members) {
+    if (node.children.has(member.typeName)) return true;
+  }
+  return false;
+}
+function printUnion(unionName, ctx, omit, pick, path, depth) {
+  const union = ctx.unions[unionName];
+  if (!union) {
+    throw new FoirRequestError(
+      `[foir] the selection tree names the union "${unionName}", which is not in selectionUnions \u2014 re-run \`foir types\`, or pass selectionUnions alongside selections`
+    );
+  }
+  const perVariantPick = pick !== void 0 && addressesMembers(pick, union);
+  const perVariantOmit = omit !== void 0 && addressesMembers(omit, union);
+  charge(ctx);
+  const parts = ["__typename"];
+  const chargeBefore = ctx.budget.fields;
+  let widestMember = 0;
+  for (const member of union.members) {
+    let memberPick = pick;
+    if (perVariantPick) {
+      const named = pick.children.get(member.typeName);
+      memberPick = named === void 0 ? NO_FIELDS : named.self ? void 0 : named;
+    }
+    let memberOmit = omit;
+    if (perVariantOmit) {
+      const named = omit.children.get(member.typeName);
+      if (named?.self) continue;
+      memberOmit = named;
+    }
+    const memberPath = perVariantPick ? `${path}${member.typeName}.` : path;
+    const memberStart = ctx.budget.fields;
+    const body = printFields(member.fields, ctx, memberOmit, memberPick, false, memberPath, depth);
+    const memberCost = ctx.budget.fields - memberStart;
+    ctx.budget.fields = memberStart;
+    if (memberCost > widestMember) widestMember = memberCost;
+    if (body) parts.push(`... on ${member.typeName} { ${body} }`);
+  }
+  ctx.budget.fields = chargeBefore + widestMember;
+  return `{ ${parts.join(" ")} }`;
+}
+function printIncludes(source, model, modelKey, include, ctx, depth) {
+  const parts = [];
+  for (const [key, value] of Object.entries(include)) {
+    if (value === void 0 || value === false) continue;
+    const relation = model.relations?.find((r) => r.key === key);
+    if (!relation) {
+      throw new FoirRequestError(
+        `[foir] include "${key}": ${modelKey} has no such relation \u2014 re-run \`foir types\` if the model has changed`
+      );
+    }
+    const nested = value && typeof value === "object" && "include" in value ? value["include"] : void 0;
+    const body = relation.targets?.length ? printPolymorphicRelation(source, relation, ctx, nested, depth) : printRelationTarget(source, relation.target ?? "", ctx, nested, relation.key, depth);
+    charge(ctx, relation.connection ? 1 + CONNECTION_WRAPPER_FIELDS : 1);
+    parts.push(`${key} ${relation.connection ? wrapRelationConnection(body) : `{ ${body} }`}`);
+  }
+  return parts.join(" ");
+}
+var CONNECTION_WRAPPER_FIELDS = 9;
+function wrapRelationConnection(body) {
+  return `{ edges { cursor node { ${body} } } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } totalCount }`;
+}
+function printRelationTarget(source, targetKey, ctx, nested, relationKey, depth) {
+  const target = source.models[targetKey];
+  if (!target?.selection) {
+    throw new FoirRequestError(
+      `[foir] include "${relationKey}": no selection published for its target model "${targetKey}" \u2014 re-run \`foir types\``
+    );
+  }
+  const bare = { source, unions: ctx.unions, budget: ctx.budget };
+  const body = printFields(target.selection.fields, bare, void 0, void 0, true, "", depth);
+  const includes = nested ? printIncludes(source, target, targetKey, nested, bare, depth) : "";
+  return includes ? `${body} ${includes}` : body;
+}
+function printPolymorphicRelation(source, relation, ctx, nested, depth) {
+  charge(ctx);
+  const parts = ["__typename"];
+  const chargeBefore = ctx.budget.fields;
+  let widestTarget = 0;
+  for (const targetKey of relation.targets ?? []) {
+    const target = source.models[targetKey];
+    if (!target?.selection) {
+      throw new FoirRequestError(
+        `[foir] include "${relation.key}": no selection published for its target model "${targetKey}" \u2014 re-run \`foir types\``
+      );
+    }
+    const targetStart = ctx.budget.fields;
+    const body = printRelationTarget(source, targetKey, ctx, nested, relation.key, depth);
+    const targetCost = ctx.budget.fields - targetStart;
+    ctx.budget.fields = targetStart;
+    if (targetCost > widestTarget) widestTarget = targetCost;
+    if (body) parts.push(`... on ${target.typeName} { ${body} }`);
+  }
+  ctx.budget.fields = chargeBefore + widestTarget;
+  return parts.join(" ");
+}
+var GRAPHQL_TYPE_REF = /^\[?\[?[_A-Za-z][_0-9A-Za-z]*!?\]?!?\]?!?$/;
+function buildArguments(args, op, opLabel) {
+  const declared = op.args;
+  const definitions = [];
+  const call = [];
+  const variables = {};
+  for (const name of Object.keys(args).sort()) {
+    const value = args[name];
+    if (value === void 0) continue;
+    if (!declared?.includes(name)) {
+      throw new FoirRequestError(
+        `[foir] ${opLabel} does not take an argument "${name}" \u2014 it takes ${declared?.length ? declared.join(", ") : "no arguments"}`
+      );
+    }
+    const type = op.argTypes?.[name];
+    if (!type) {
+      throw new FoirRequestError(
+        `[foir] ${opLabel}: the manifest publishes no type for the argument "${name}", so it cannot be sent as a variable \u2014 and inferring one from the value would guess wrong on every enum. Re-run \`foir types\` against a server that publishes argTypes, or use foir.raw() with your own variable definitions`
+      );
+    }
+    if (!GRAPHQL_TYPE_REF.test(type)) {
+      throw new FoirRequestError(
+        `[foir] ${opLabel}: the manifest gives the argument "${name}" the type "${type}", which is not a GraphQL type reference`
+      );
+    }
+    definitions.push(`$${name}: ${type}`);
+    call.push(`${name}: $${name}`);
+    variables[name] = toVariableValue(value, `${opLabel} argument "${name}"`);
+  }
+  return {
+    definitions: definitions.length ? `(${definitions.join(", ")})` : "",
+    call: call.length ? `(${call.join(", ")})` : "",
+    variables
+  };
+}
+function toVariableValue(value, label) {
+  if (value === null) return null;
+  const kind = typeof value;
+  if (kind === "string" || kind === "boolean") return value;
+  if (kind === "number") {
+    if (!Number.isFinite(value)) {
+      throw new FoirRequestError(
+        `[foir] ${label} is ${String(value)}, which has no JSON form and cannot be sent`
+      );
+    }
+    return value;
+  }
+  if (kind === "bigint") {
+    const asNumber = Number(value);
+    if (!Number.isSafeInteger(asNumber)) {
+      throw new FoirRequestError(
+        `[foir] ${label} is the bigint ${String(value)}, which is outside the range JSON can carry exactly`
+      );
+    }
+    return asNumber;
+  }
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new FoirRequestError(`[foir] ${label} is an invalid Date`);
+    }
+    return value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    return value.filter((item) => item !== void 0).map((item, index) => toVariableValue(item, `${label}[${index}]`));
+  }
+  if (kind === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (child === void 0) continue;
+      out[key] = toVariableValue(child, `${label}.${key}`);
+    }
+    return out;
+  }
+  throw new FoirRequestError(
+    `[foir] ${label} is a ${kind}, which has no JSON form and cannot be sent`
+  );
+}
+function payloadRecordPaths(payload) {
+  if (payload.kind === "record") {
+    return payload.model ? [{ path: [], modelKey: payload.model }] : [];
+  }
+  const found = [];
+  const visit = (fields, prefix) => {
+    for (const field of fields ?? []) {
+      const at = [...prefix, field.alias ?? field.key];
+      if (field.model) found.push({ path: at, modelKey: field.model });
+      visit(field.fields, at);
+    }
+  };
+  visit(payload.fields, []);
+  return found;
+}
+function printPayload(payload, ctx, root, opLabel, depth) {
+  switch (payload.kind) {
+    case "leaf":
+      return void 0;
+    case "record": {
+      if (!payload.model) {
+        throw new FoirRequestError(
+          `[foir] ${opLabel}: the result shape says it is a record but names no model \u2014 re-run \`foir types\``
+        );
+      }
+      return printModelTree(payload.model, ctx, depth);
+    }
+    case "union": {
+      if (!payload.union) {
+        throw new FoirRequestError(
+          `[foir] ${opLabel}: the result shape says it is a union but names none \u2014 re-run \`foir types\``
+        );
+      }
+      return printUnion(payload.union, ctx, root.omit, root.pick, "", depth).slice(2, -2);
+    }
+    case "object": {
+      if (!payload.fields?.length) {
+        throw new FoirRequestError(
+          `[foir] ${opLabel}: the result shape is an object with no fields \u2014 re-run \`foir types\``
+        );
+      }
+      return printFields(payload.fields, ctx, root.omit, root.pick, false, "", depth);
+    }
+    default:
+      throw new FoirRequestError(
+        `[foir] ${opLabel}: the result shape has the kind "${String(payload.kind)}", which this client does not know how to print \u2014 upgrade @foir/sdk`
+      );
+  }
+}
+var DEFAULT_DEPTH = 1;
+function planFoirModelCall(source, call) {
+  const model = source.models[call.model];
+  if (!model) {
+    throw new FoirRequestError(
+      `[foir] no model "${call.model}" in this credential's surface \u2014 re-run \`foir types\``
+    );
+  }
+  const opDef = model.ops?.[call.op];
+  if (!opDef) {
+    throw new FoirRequestError(
+      `[foir] ${call.model} has no op "${call.op}" for this credential \u2014 re-run \`foir types\``
+    );
+  }
+  return planCall(source, opDef, `${call.model}.${call.op}`, operationName(model.typeName, call.op), call);
+}
+function planFoirNamespaceCall(source, call) {
+  const namespace = source.namespaces?.[call.namespace];
+  if (!namespace) {
+    throw new FoirRequestError(
+      `[foir] no namespace "${call.namespace}" in this credential's surface \u2014 re-run \`foir types\``
+    );
+  }
+  const opDef = namespace.ops?.[call.op];
+  if (!opDef) {
+    throw new FoirRequestError(
+      `[foir] the namespace "${call.namespace}" has no op "${call.op}" for this credential \u2014 re-run \`foir types\``
+    );
+  }
+  return planCall(
+    source,
+    opDef,
+    `${call.namespace}.${call.op}`,
+    operationName(call.namespace, call.op),
+    call
+  );
+}
+function planCall(source, opDef, opLabel, name, call) {
+  const payload = opDef.payload;
+  if (!payload) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: the manifest publishes no result shape for this op, so there is nothing to print \u2014 and synthesising one client-side is exactly the guess this client refuses to make. Re-run \`foir types\` against a server that publishes op payloads`
+    );
+  }
+  if (payload.error) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: the server could not resolve a result shape for this op: ${payload.error}`
+    );
+  }
+  if (call.omit && call.pick) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: "omit" and "pick" are mutually exclusive \u2014 pass one or the other`
+    );
+  }
+  if (call.omit?.includes(PROTECTED_ROOT_FIELD)) {
+    throw new FoirRequestError(
+      `[foir] omit "${PROTECTED_ROOT_FIELD}": "${PROTECTED_ROOT_FIELD}" is required for correctness and cannot be removed`
+    );
+  }
+  const depth = call.depth ?? DEFAULT_DEPTH;
+  if (!Number.isInteger(depth) || depth < DEFAULT_DEPTH) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: depth must be a whole number of union levels, ${DEFAULT_DEPTH} or more \u2014 got ${String(call.depth)}. ${DEFAULT_DEPTH} is the complete-by-default document; each level above it expands one further union`
+    );
+  }
+  const omit = call.omit?.length ? buildPathTrie(call.omit) : void 0;
+  const pick = call.pick?.length ? buildPathTrie(call.pick) : void 0;
+  const include = call.include && Object.keys(call.include).length ? call.include : void 0;
+  const narrowed = Boolean(omit || pick || include);
+  const recordPaths = payloadRecordPaths(payload);
+  const records = new Set(recordPaths.map((entry) => entry.modelKey));
+  if (records.size > 1 && narrowed) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: the result carries records of more than one model (${[...records].sort().join(", ")}), so "include"/"pick"/"omit" do not say which one they mean \u2014 call it without them and narrow with foir.raw()`
+    );
+  }
+  const recordModel = records.size === 1 ? [...records][0] : void 0;
+  if (include && !recordModel) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: "include" names relations of a record, and this op returns none`
+    );
+  }
+  const ctx = {
+    source,
+    unions: source.selectionUnions ?? {},
+    record: recordModel ? { modelKey: recordModel, omit, pick, include } : void 0,
+    budget: newBudget()
+  };
+  const root = recordModel ? {} : { omit, pick };
+  const selection = printPayload(payload, ctx, root, opLabel, depth);
+  if (selection === "") {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: the selection is empty after applying pick/omit \u2014 a GraphQL selection set cannot be empty`
+    );
+  }
+  charge(ctx);
+  if (depth > DEFAULT_DEPTH && (ctx.budget.stopped || ctx.budget.fields > MAX_QUERY_COMPLEXITY)) {
+    const reason = ctx.budget.stopped ? `expands to more than ${MAX_EMITTED_FIELDS} fields to print, which is past what this client will build in one call` : `makes this document select ${ctx.budget.fields} fields, over the server's limit of ${MAX_QUERY_COMPLEXITY}`;
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: depth ${depth} ${reason}. Each level re-expands every stopping point inside the expansion, so spend the level on less: narrow with "pick"/"omit" \u2014 including per-member, pick: { <field>: { on: { <MemberType>: [...] } } } \u2014 or ask for depth ${depth - 1}`
+    );
+  }
+  const args = buildArguments(call.args, opDef, opLabel);
+  const keyword = opDef.mutation ? "mutation" : "query";
+  const body = selection === void 0 ? "" : ` { ${selection} }`;
+  return {
+    document: `${keyword} ${name}${args.definitions} { ${opDef.field}${args.call}${body} }`,
+    variables: args.variables,
+    mutation: opDef.mutation === true,
+    rootField: opDef.field,
+    fields: ctx.budget.fields,
+    records: recordPaths
+  };
+}
+function operationName(scope, op) {
+  const parts = `${scope} ${op}`.split(/[^0-9A-Za-z]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1));
+  const name = parts.join("");
+  return /^[_A-Za-z]/.test(name) ? name : `Foir${name}`;
+}
+function isFoirMutationDocument(documentText) {
+  return /\bmutation\b/.test(documentText);
+}
+
+// src/data/subscription-document.ts
+function printSubscriptionDocument(input) {
+  const args = input.args ?? [];
+  const declaration = args.length ? `(${args.map((a) => `$${a.name}: ${a.type}`).join(", ")})` : "";
+  const call = args.length ? `(${args.map((a) => `${a.name}: $${a.name}`).join(", ")})` : "";
+  const body = printFoirSelectionBody(input.selection.fields, input.unions ?? {});
+  if (!body) {
+    throw new Error(
+      `[foir] subscription \`${input.field}\` has an empty selection, so no valid document can be printed. The manifest's selectionError explains why; re-run \`foir types\` or check GET /v1/manifest.`
+    );
+  }
+  return `subscription ${input.operationName}${declaration} { ${input.field}${call} { ${body} } }`;
+}
+
+// src/data/ws-transport.ts
+var GQL = {
+  connectionInit: "connection_init",
+  connectionAck: "connection_ack",
+  ping: "ping",
+  pong: "pong",
+  subscribe: "subscribe",
+  next: "next",
+  error: "error",
+  complete: "complete"
+};
+var SUBPROTOCOL = "graphql-transport-ws";
+var OPEN_READY_STATE = 1;
+var DEFAULT_RECONNECT = {
+  maxAttempts: Infinity,
+  initialDelayMs: 500,
+  maxDelayMs: 15e3,
+  jitter: 0.25
+};
+function foirSocketEndpoint(apiUrl) {
+  const trimmed = apiUrl.replace(/\/+$/, "").replace(/\/graphql$/, "");
+  return `${trimmed.replace(/^http/, "ws")}/graphql/ws`;
+}
+var FoirSocketTransport = class {
+  config;
+  policy;
+  registrations = /* @__PURE__ */ new Map();
+  socket = null;
+  acknowledged = false;
+  connecting = false;
+  attempt = 0;
+  nextId = 0;
+  disposed = false;
+  keepAlive = null;
+  retryTimer = null;
+  constructor(config) {
+    this.config = config;
+    this.policy = { ...DEFAULT_RECONNECT, ...config.reconnect ?? {} };
+  }
+  /**
+   * Start a subscription.
+   *
+   * Returns synchronously so a caller can hold the handle immediately, while
+   * the connect and the handshake proceed in the background. A subscription
+   * registered before the socket is acknowledged is sent the moment it is —
+   * which is the same path a reconnect takes, so the ordinary case and the
+   * recovery case exercise one piece of code.
+   */
+  subscribe(request, handlers) {
+    if (this.disposed) {
+      throw new FoirRequestError("[foir] this client has been disposed; create a new one");
+    }
+    this.nextId += 1;
+    const id = String(this.nextId);
+    this.registrations.set(id, {
+      id,
+      request,
+      handlers,
+      sent: false,
+      established: false
+    });
+    this.ensureConnected();
+    this.flush();
+    return {
+      unsubscribe: () => this.cancel(id)
+    };
+  }
+  /** Close the socket and drop every subscription. */
+  dispose() {
+    this.disposed = true;
+    this.registrations.clear();
+    this.teardownSocket(true);
+  }
+  /** Live subscription count. Exposed for tests and diagnostics. */
+  get size() {
+    return this.registrations.size;
+  }
+  // -------------------------------------------------------------------------
+  // Connection
+  // -------------------------------------------------------------------------
+  ensureConnected() {
+    if (this.disposed || this.socket || this.connecting) return;
+    this.connecting = true;
+    const factory = this.config.webSocketImpl ?? defaultWebSocketFactory();
+    const url = this.config.wsUrl ?? foirSocketEndpoint(this.config.apiUrl);
+    let socket;
+    try {
+      socket = factory(url, SUBPROTOCOL);
+    } catch (cause) {
+      this.connecting = false;
+      this.scheduleReconnect(
+        new FoirRequestError(`[foir] could not open a WebSocket to ${url}: ${String(cause)}`)
+      );
+      return;
+    }
+    this.socket = socket;
+    socket.onopen = () => {
+      void this.sendConnectionInit(socket);
+    };
+    socket.onmessage = (event) => this.receive(event.data);
+    socket.onerror = () => {
+    };
+    socket.onclose = () => this.handleClose();
+  }
+  async sendConnectionInit(socket) {
+    this.connecting = false;
+    try {
+      const headers = buildFoirHeaders({
+        apiKey: this.config.apiKey,
+        draftChannel: this.config.channel === "draft",
+        bearerToken: await resolveBearerToken(this.config),
+        extra: this.config.headers
+      });
+      const { "Content-Type": _contentType, ...params } = headers;
+      const extra = await this.config.connectionParams?.() ?? {};
+      this.send(socket, {
+        type: GQL.connectionInit,
+        payload: { ...params, ...extra }
+      });
+    } catch (cause) {
+      this.failAll(
+        new FoirRequestError(`[foir] could not resolve the subscription credential: ${String(cause)}`)
+      );
+      this.teardownSocket(true);
+    }
+  }
+  handleClose() {
+    const wasAcknowledged = this.acknowledged;
+    this.teardownSocket(false);
+    if (this.disposed || this.registrations.size === 0) return;
+    for (const registration of this.registrations.values()) {
+      registration.sent = false;
+    }
+    this.scheduleReconnect(
+      new FoirRequestError(
+        wasAcknowledged ? "[foir] the subscription socket closed and could not be re-established" : "[foir] the subscription socket closed before the credential was accepted"
+      )
+    );
+  }
+  scheduleReconnect(error) {
+    if (this.disposed || this.registrations.size === 0) return;
+    if (this.attempt >= this.policy.maxAttempts) {
+      this.failAll(error);
+      return;
+    }
+    const exponent = Math.min(this.attempt, 20);
+    const base = Math.min(
+      this.policy.initialDelayMs * 2 ** exponent,
+      this.policy.maxDelayMs
+    );
+    const delay = base + base * this.policy.jitter * Math.random();
+    this.attempt += 1;
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      this.ensureConnected();
+    }, delay);
+    const timer = this.retryTimer;
+    if (typeof timer?.unref === "function") timer.unref();
+  }
+  teardownSocket(closeIt) {
+    if (this.keepAlive !== null) {
+      clearInterval(this.keepAlive);
+      this.keepAlive = null;
+    }
+    if (this.retryTimer !== null) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+    const socket = this.socket;
+    this.socket = null;
+    this.acknowledged = false;
+    this.connecting = false;
+    if (!socket) return;
+    socket.onopen = null;
+    socket.onmessage = null;
+    socket.onerror = null;
+    socket.onclose = null;
+    if (closeIt) {
+      try {
+        socket.close(1e3, "client disposed");
+      } catch {
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Frames
+  // -------------------------------------------------------------------------
+  receive(data) {
+    if (typeof data !== "string") return;
+    let message;
+    try {
+      message = JSON.parse(data);
+    } catch {
+      return;
+    }
+    switch (message.type) {
+      case GQL.connectionAck:
+        this.acknowledged = true;
+        this.attempt = 0;
+        this.startKeepAlive();
+        this.flush();
+        return;
+      case GQL.ping:
+        if (this.socket) this.send(this.socket, { type: GQL.pong });
+        return;
+      case GQL.pong:
+        return;
+      case GQL.next: {
+        const registration = message.id ? this.registrations.get(message.id) : void 0;
+        if (!registration) return;
+        const payload = message.payload;
+        const root = payload?.data;
+        if (!root) return;
+        const keys = Object.keys(root);
+        if (keys.length !== 1) return;
+        registration.handlers.onData(root[keys[0]]);
+        return;
+      }
+      case GQL.error: {
+        const error = new FoirRequestError(`[foir] subscription refused: ${describe(message.payload)}`);
+        if (!message.id) {
+          this.failAll(error);
+          this.teardownSocket(true);
+          return;
+        }
+        const registration = this.registrations.get(message.id);
+        this.registrations.delete(message.id);
+        registration?.handlers.onError?.(error);
+        this.closeIfIdle();
+        return;
+      }
+      case GQL.complete: {
+        if (!message.id) return;
+        const registration = this.registrations.get(message.id);
+        this.registrations.delete(message.id);
+        registration?.handlers.onComplete?.();
+        this.closeIfIdle();
+        return;
+      }
+      default:
+        return;
+    }
+  }
+  /**
+   * Send every registration the current socket has not yet been told about.
+   *
+   * This IS the resubscribe path. A reconnect clears `sent` on every
+   * registration and lands here, so a subscription re-established after a drop
+   * takes the same code as one opened for the first time — there is no second
+   * implementation that can be correct in one case and wrong in the other.
+   */
+  flush() {
+    const socket = this.socket;
+    if (!socket || !this.acknowledged || socket.readyState !== OPEN_READY_STATE) return;
+    for (const registration of this.registrations.values()) {
+      if (registration.sent) continue;
+      this.send(socket, {
+        id: registration.id,
+        type: GQL.subscribe,
+        payload: registration.request
+      });
+      registration.sent = true;
+      if (registration.established) {
+        registration.handlers.onReconnect?.();
+      } else {
+        registration.established = true;
+      }
+    }
+  }
+  cancel(id) {
+    const registration = this.registrations.get(id);
+    if (!registration) return;
+    this.registrations.delete(id);
+    if (this.socket && registration.sent && this.socket.readyState === OPEN_READY_STATE) {
+      this.send(this.socket, { id, type: GQL.complete });
+    }
+    this.closeIfIdle();
+  }
+  /**
+   * Close the socket once nothing is using it.
+   *
+   * A socket held open with no subscriptions is a connection the server has to
+   * keep, a keepalive timer that keeps a serverless invocation alive, and
+   * nothing in return.
+   */
+  closeIfIdle() {
+    if (this.registrations.size === 0) this.teardownSocket(true);
+  }
+  failAll(error) {
+    const registrations = [...this.registrations.values()];
+    this.registrations.clear();
+    for (const registration of registrations) {
+      registration.handlers.onError?.(error);
+    }
+  }
+  /**
+   * Client-side keepalive.
+   *
+   * The server pings on its own timer and this client answers, which is enough
+   * for the server to know the client is alive. This is the other direction:
+   * an idle subscription can sit for hours with no events, and a proxy that
+   * times out idle sockets will drop it. A periodic `ping` keeps it warm, and
+   * the pong that comes back proves the path is still there.
+   */
+  startKeepAlive() {
+    if (this.keepAlive !== null) clearInterval(this.keepAlive);
+    this.keepAlive = setInterval(() => {
+      const socket = this.socket;
+      if (!socket || socket.readyState !== OPEN_READY_STATE) return;
+      this.send(socket, { type: GQL.ping });
+    }, 2e4);
+    const timer = this.keepAlive;
+    if (typeof timer?.unref === "function") timer.unref();
+  }
+  send(socket, message) {
+    try {
+      socket.send(JSON.stringify(message));
+    } catch {
+    }
+  }
+};
+function defaultWebSocketFactory() {
+  const Impl = globalThis.WebSocket;
+  if (typeof Impl !== "function") {
+    throw new FoirRequestError(
+      "[foir] no WebSocket implementation is available in this runtime. Pass one as `webSocketImpl` \u2014 e.g. `webSocketImpl: (url, protocols) => new WebSocket(url, protocols)` from the `ws` package on Node < 22."
+    );
+  }
+  return (url, protocols) => new Impl(url, protocols);
+}
+function describe(payload) {
+  if (payload == null) return "no reason given";
+  if (typeof payload === "string") return payload;
+  if (Array.isArray(payload)) return payload.map(describe).join("; ");
+  if (typeof payload === "object") {
+    const message = payload.message;
+    if (typeof message === "string") return message;
+  }
+  return JSON.stringify(payload);
+}
+
+// src/data/subscriptions.ts
+var MODEL_SUBSCRIPTION_METHODS = /* @__PURE__ */ new Set(["onChange"]);
+var NAMESPACE_SUBSCRIPTION_METHODS = {
+  notifications: /* @__PURE__ */ new Set(["onNotification"]),
+  operations: /* @__PURE__ */ new Set(["onJobProgress", "onExecution"])
+};
+function isModelSubscriptionMethod(name) {
+  return MODEL_SUBSCRIPTION_METHODS.has(name);
+}
+function isNamespaceSubscriptionMethod(namespace, name) {
+  return NAMESPACE_SUBSCRIPTION_METHODS[namespace]?.has(name) ?? false;
+}
+var FoirSubscriptionRouter = class {
+  transport;
+  loadManifest;
+  /**
+   * `loadManifest` is the client's own memoised descriptor loader, passed in
+   * rather than rebuilt. One client is one credential and one descriptor; a
+   * fetcher of our own would race the query path's for the same bytes and could
+   * end up holding a different schema version than the documents the query path
+   * is printing from.
+   */
+  constructor(config, loadManifest) {
+    this.transport = new FoirSocketTransport(config);
+    this.loadManifest = loadManifest;
+  }
+  dispose() {
+    this.transport.dispose();
+  }
+  /** `foir.<model>.onChange(...)`. */
+  model(modelKey, method, input) {
+    if (method !== "onChange") {
+      throw new FoirRequestError(`[foir] ${modelKey}.${method} is not a subscription`);
+    }
+    return this.open(
+      {
+        field: "recordChanged",
+        operationName: "FoirRecordChanged",
+        args: [{ name: "modelKey", type: "String!" }],
+        variables: { modelKey }
+      },
+      input
+    );
+  }
+  /** `foir.ns.<namespace>.on…(...)`. */
+  namespace(namespace, method, input) {
+    const handlers = input;
+    if (namespace === "notifications" && method === "onNotification") {
+      return this.open(
+        {
+          field: "notification",
+          operationName: "FoirNotification",
+          args: [],
+          variables: {}
+        },
+        handlers
+      );
+    }
+    if (namespace === "operations" && method === "onJobProgress") {
+      return this.open(
+        { field: "jobProgress", operationName: "FoirJobProgress", args: [], variables: {} },
+        handlers
+      );
+    }
+    if (namespace === "operations" && method === "onExecution") {
+      const id = input.id;
+      if (typeof id !== "string" || id === "") {
+        throw new FoirRequestError("[foir] onExecution requires an execution `id`");
+      }
+      const operation = typeof input.operation === "string" ? input.operation : void 0;
+      return this.open(
+        {
+          field: "operationExecution",
+          matchOperation: operation,
+          operationName: "FoirOperationExecution",
+          args: [{ name: "id", type: "String!" }],
+          variables: { id }
+        },
+        handlers
+      );
+    }
+    throw new FoirRequestError(`[foir] ns.${namespace}.${method} is not a subscription`);
+  }
+  /**
+   * Resolve the route's document and subscribe.
+   *
+   * The handle is returned synchronously and the manifest fetch runs behind it,
+   * so a caller can hold and cancel a subscription before the descriptor has
+   * arrived. Cancelling in that window is honoured: `cancelled` is checked
+   * after the await, and the inner handle is never created.
+   */
+  open(route, handlers) {
+    const state = {
+      cancelled: false,
+      inner: null
+    };
+    void this.loadManifest().then((manifest) => {
+      if (state.cancelled) return;
+      const entry = route.matchOperation ? matchTypedExecutionField(manifest, route.matchOperation) : findSubscription(manifest, route.field);
+      const query = printSubscriptionDocument({
+        field: entry.field,
+        operationName: route.operationName,
+        args: route.args,
+        selection: requireSelection(entry),
+        unions: manifest.selectionUnions
+      });
+      if (state.cancelled) return;
+      state.inner = this.transport.subscribe({ query, variables: route.variables }, handlers);
+    }).catch((cause) => {
+      if (state.cancelled) return;
+      handlers.onError?.(
+        cause instanceof FoirRequestError ? cause : new FoirRequestError(`[foir] could not start the subscription: ${String(cause)}`)
+      );
+    });
+    return {
+      unsubscribe: () => {
+        state.cancelled = true;
+        state.inner?.unsubscribe();
+        state.inner = null;
+      }
+    };
+  }
+};
+function findSubscription(manifest, field) {
+  const found = manifest.subscriptions?.find((s) => s.field === field);
+  if (found) return found;
+  const available = (manifest.subscriptions ?? []).map((s) => s.field);
+  if (available.length === 0) {
+    throw new FoirRequestError(
+      `[foir] this credential can open no subscriptions, so \`${field}\` is not available. Subscriptions need the matching read scope on the api key.`
+    );
+  }
+  throw new FoirRequestError(
+    `[foir] \`${field}\` is not available to this credential. Available: ${available.join(", ")}.`
+  );
+}
+function requireSelection(entry) {
+  if (entry.selection) return entry.selection;
+  throw new FoirRequestError(
+    `[foir] the server published no selection for \`${entry.field}\`` + (entry.selectionError ? `: ${entry.selectionError}` : "") + ". Without one there is no document to send."
+  );
+}
+function matchTypedExecutionField(manifest, operationKey) {
+  const wanted = normalise(`operation ${operationKey} execution`);
+  const typed = (manifest.subscriptions ?? []).filter(
+    (s) => s.field !== "operationExecution" && normalise(s.field) === wanted
+  );
+  if (typed.length === 1) return typed[0];
+  const available = (manifest.subscriptions ?? []).filter((s) => s.field.startsWith("operation") && s.field.endsWith("Execution")).map((s) => s.field);
+  throw new FoirRequestError(
+    `[foir] no typed execution subscription for operation \`${operationKey}\`. ` + (available.length ? `Available: ${available.join(", ")}.` : "This credential reaches none \u2014 operations:read is required.") + " Omit `operation` to use the generic `operationExecution` stream."
+  );
+}
+function normalise(value) {
+  return value.replace(/[^0-9a-zA-Z]+/g, "").toLowerCase();
+}
+
+// src/data/subjects.ts
+var keyOf = (modelKey, recordId) => `${modelKey}\0${recordId}`;
+function createFoirSubjectRegistry(options = {}) {
+  const held = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  const pinned = { subject: null };
+  const latest = { key: null };
+  const notify = () => {
+    const failures = [];
+    for (const listener of [...listeners]) {
+      try {
+        listener();
+      } catch (err) {
+        failures.push(err);
+      }
+    }
+    if (failures.length === 0) return;
+    throw new FoirRequestError(
+      `[foir] ${failures.length} subject registry listener(s) threw. Every listener still ran; this is the first failure`,
+      { cause: failures[0] }
+    );
+  };
+  const labelFor = (entry, subject) => {
+    if (entry.label) return entry.label;
+    if (!entry.record) return void 0;
+    if (options.label) {
+      const labelled = options.label(entry.record, subject);
+      return labelled == null || labelled === "" ? void 0 : labelled;
+    }
+    const natural = entry.record["_naturalKey"];
+    return typeof natural === "string" && natural !== "" ? natural : void 0;
+  };
+  const same = (a, b) => a !== void 0 && a.origin === b.origin && a.subject.label === b.subject.label && a.subject.modelKey === b.subject.modelKey && a.subject.recordId === b.subject.recordId;
+  return {
+    add(entry) {
+      if (!entry.modelKey || !entry.recordId) {
+        throw new FoirRequestError(
+          "[foir] a subject needs both a modelKey and a recordId \u2014 an annotation anchored to half of one cannot be resolved back to a record"
+        );
+      }
+      const subject = { modelKey: entry.modelKey, recordId: entry.recordId };
+      const label = labelFor(entry, subject);
+      if (label !== void 0) subject.label = label;
+      const next = { subject, origin: entry.origin ?? "record" };
+      const key = keyOf(entry.modelKey, entry.recordId);
+      if (latest.key === key && same(held.get(key), next)) return;
+      held.delete(key);
+      held.set(key, next);
+      latest.key = key;
+      notify();
+    },
+    fetched() {
+      return [...held.values()].map((entry) => entry.subject);
+    },
+    subject() {
+      if (pinned.subject) return pinned.subject;
+      let answer;
+      for (const entry of held.values()) {
+        if (entry.origin === "record") answer = entry.subject;
+      }
+      return answer;
+    },
+    setSubject(subject) {
+      pinned.subject = subject;
+      notify();
+    },
+    clear() {
+      held.clear();
+      pinned.subject = null;
+      latest.key = null;
+      notify();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+function recordFoirSubjects(registry, plan, result) {
+  if (!registry) return;
+  const positions = plan.records;
+  if (!positions?.length) return;
+  try {
+    for (const position of positions) {
+      const origin = position.path.length === 0 ? "record" : "collection";
+      for (const record of recordsAt(result, position.path)) {
+        const recordId = record[PROTECTED_ROOT_FIELD];
+        if (typeof recordId !== "string" || recordId === "") continue;
+        registry.add({ modelKey: position.modelKey, recordId, origin, record });
+      }
+    }
+  } catch (err) {
+    throw new FoirRequestError(
+      "[foir] the subject registry threw while recording what this call fetched. The request itself succeeded \u2014 the failure is in your `label` function or a `subscribe` listener. It is raised rather than swallowed because a subject that fails to record leaves the PREVIOUS one as the answer, and a widget then offers to annotate the wrong record",
+      { cause: err }
+    );
+  }
+}
+function recordsAt(value, path) {
+  if (value === null || value === void 0 || typeof value !== "object") return [];
+  if (Array.isArray(value)) {
+    const out = [];
+    for (const item of value) out.push(...recordsAt(item, path));
+    return out;
+  }
+  const record = value;
+  if (path.length === 0) return [record];
+  return recordsAt(record[path[0]], path.slice(1));
+}
+
 // src/data/client.ts
 var NON_MODEL_PROPS = /* @__PURE__ */ new Set([
   "then",
@@ -203,8 +1393,30 @@ function selectionPaths(value, verb, prefix = "") {
       out.push(path);
       continue;
     }
-    if (child && typeof child === "object" && verb in child) {
-      out.push(...selectionPaths(child[verb], verb, path));
+    if (child && typeof child === "object") {
+      const node = child;
+      if (verb in node) {
+        out.push(...selectionPaths(node[verb], verb, path));
+        continue;
+      }
+      if ("on" in node) {
+        out.push(...variantPaths(node.on, path));
+      }
+    }
+  }
+  return out;
+}
+function variantPaths(value, prefix) {
+  if (!value || typeof value !== "object") return [];
+  const out = [];
+  for (const [typeName, keys] of Object.entries(value)) {
+    const memberPath = `${prefix}.${typeName}`;
+    if (keys === true) {
+      out.push(memberPath);
+      continue;
+    }
+    if (Array.isArray(keys)) {
+      for (const key of keys) out.push(`${memberPath}.${String(key)}`);
     }
   }
   return out;
@@ -214,6 +1426,7 @@ function splitQuery(query) {
   let include;
   let omit;
   let pick;
+  let depth;
   for (const [key, value] of Object.entries(query ?? {})) {
     if (value === void 0) continue;
     if (key === "include") {
@@ -222,52 +1435,192 @@ function splitQuery(query) {
       omit = selectionPaths(value, "omit");
     } else if (key === "pick") {
       pick = selectionPaths(value, "pick");
+    } else if (key === "depth") {
+      depth = value;
     } else {
       args[key] = value;
     }
   }
-  return { args, include, omit, pick };
+  return { args, include, omit, pick, depth };
 }
-function createFoirClient(config) {
-  if (!config?.apiUrl || !config?.apiKey) {
+var GENERATED_EXPORTS = [
+  "foirSchemaVersion",
+  "foirSelections",
+  "foirNamespaceSelections",
+  "foirSelectionUnions"
+];
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function resolveGeneratedConfig(config) {
+  const generated = config.generated;
+  if (generated === void 0) return config;
+  if (!isRecord(generated)) {
+    throw new FoirRequestError(
+      "[foir] createFoirClient: `generated` must be the module `foir types` emits \u2014 `import * as generated from './foir.generated'`. Omit it to read the selection trees from `GET /v1/manifest` instead."
+    );
+  }
+  const missing = GENERATED_EXPORTS.filter((name) => generated[name] == null);
+  if (missing.length > 0) {
+    throw new FoirRequestError(
+      `[foir] createFoirClient: the module passed as \`generated\` is missing ${missing.join(", ")}. \`foir types\` emits ${GENERATED_EXPORTS.join(", ")} together, so a module missing one is stale or hand-assembled \u2014 re-run \`foir types\`. Reading the rest and fetching \`GET /v1/manifest\` for the remainder would hide that; omit \`generated\` entirely to ask for the manifest deliberately.`
+    );
+  }
+  const version = generated["foirSchemaVersion"];
+  if (typeof version !== "number" || !Number.isFinite(version)) {
+    throw new FoirRequestError(
+      "[foir] createFoirClient: `generated.foirSchemaVersion` is not a number. It is the manifest version the drift check compares against \u2014 re-run `foir types`."
+    );
+  }
+  const selections = generated["foirSelections"];
+  if (!isRecord(selections)) {
+    throw new FoirRequestError(
+      "[foir] createFoirClient: `generated.foirSelections` is not an object of model key -> selection model. Re-run `foir types`."
+    );
+  }
+  for (const [key, model] of Object.entries(selections)) {
+    if (isRecord(model) && typeof model["typeName"] === "string") continue;
+    throw new FoirRequestError(
+      `[foir] createFoirClient: \`generated.foirSelections["${key}"]\` is not a selection model \u2014 it has no \`typeName\`. The printer reads \`typeName\`, \`ops\` and \`selection\` off each entry, so a bare selection tree here prints nothing and every call would fall back to \`GET /v1/manifest\` as if the module were absent. Re-run \`foir types\` with a current @foir/cli.`
+    );
+  }
+  const namespaceSelections = generated["foirNamespaceSelections"];
+  if (!isRecord(namespaceSelections)) {
+    throw new FoirRequestError(
+      "[foir] createFoirClient: `generated.foirNamespaceSelections` is not an object of namespace -> ops. Re-run `foir types`."
+    );
+  }
+  const selectionUnions = generated["foirSelectionUnions"];
+  if (!isRecord(selectionUnions)) {
+    throw new FoirRequestError(
+      "[foir] createFoirClient: `generated.foirSelectionUnions` is not an object of union name -> expansion. Re-run `foir types`."
+    );
+  }
+  for (const [name, union] of Object.entries(selectionUnions)) {
+    if (isRecord(union) && Array.isArray(union["members"])) continue;
+    throw new FoirRequestError(
+      `[foir] createFoirClient: \`generated.foirSelectionUnions["${name}"]\` has no \`members\`. A tree that names this union would print an empty selection set. Re-run \`foir types\`.`
+    );
+  }
+  return {
+    ...config,
+    schemaVersion: config.schemaVersion ?? version,
+    selections: config.selections ?? selections,
+    namespaceSelections: config.namespaceSelections ?? namespaceSelections,
+    selectionUnions: config.selectionUnions ?? selectionUnions
+  };
+}
+function announceFallback(config) {
+  if (config.generated !== void 0 || config.selections !== void 0) return;
+  if (config.announceManifestFallback === false) return;
+  console.info(
+    "[foir] no generated module passed, so this client fetches `GET /v1/manifest` once at first use and prints from the trees it publishes. That works \u2014 it is what makes a zero-codegen start possible \u2014 but it puts a round trip in front of the first query on every cold start. Run `foir types`, then `import * as generated from './foir.generated'` and pass `generated`. Silence this with `announceManifestFallback: false`."
+  );
+}
+function createFoirClient(clientConfig) {
+  if (!clientConfig?.apiUrl || !clientConfig?.apiKey) {
     throw new Error("[foir] createFoirClient needs both apiUrl and apiKey");
   }
+  const config = resolveGeneratedConfig(clientConfig);
+  announceFallback(config);
   let driftChecked = false;
+  let manifestOnce;
+  const manifest = () => {
+    if (!manifestOnce) {
+      manifestOnce = fetchFoirManifest(config).catch((err) => {
+        manifestOnce = void 0;
+        throw err;
+      });
+    }
+    return manifestOnce;
+  };
+  const selectionSource = async () => {
+    if (config.selections) {
+      return {
+        models: config.selections,
+        namespaces: config.namespaceSelections,
+        selectionUnions: config.selectionUnions
+      };
+    }
+    return manifest();
+  };
   const maybeCheckDrift = () => {
     const generated = config.schemaVersion;
     if (driftChecked) return;
     if (generated === void 0) return;
     if (config.checkSchemaDrift === false) return;
     driftChecked = true;
-    void fetchFoirManifest(config).then((manifest) => {
-      if (manifest.schemaVersion === generated) return;
+    void manifest().then((served) => {
+      if (served.schemaVersion === generated) return;
       const drift = {
         generated,
-        server: manifest.schemaVersion,
-        channel: manifest.channel
+        server: served.schemaVersion,
+        channel: served.channel
       };
       if (config.onSchemaDrift) {
         config.onSchemaDrift(drift);
         return;
       }
       console.warn(
-        `[foir] schema drift: types were generated from schemaVersion ${drift.generated}, the server is serving ${drift.server} (${drift.channel}). Re-run \`foir types\` \u2014 new models and fields will be missing, and removed ones will still type-check.`
+        `[foir] schema drift: types were generated from schemaVersion ${drift.generated}, the server is serving ${drift.server} (${drift.channel}). Re-run \`foir types\` \u2014 the selection trees this client prints from are the ones that version published, so a new field is not merely untyped, it is not requested.`
       );
     }).catch(() => {
     });
   };
-  const run = async (body) => {
-    const result = await postFoirOp(config, body);
+  const runModel = async (model, op, query) => {
+    const { args, include, omit, pick, depth } = splitQuery(query);
+    const plan = planFoirModelCall(await selectionSource(), {
+      model,
+      op,
+      args,
+      include,
+      omit,
+      pick,
+      depth
+    });
+    const result = await executeFoirDocument(config, plan);
+    recordFoirSubjects(config.subjects, plan, result);
     maybeCheckDrift();
     return result;
   };
+  const runNamespace = async (namespace, op, query) => {
+    const { args, include, omit, pick, depth } = splitQuery(query);
+    const plan = planFoirNamespaceCall(await selectionSource(), {
+      namespace,
+      op,
+      args,
+      include,
+      omit,
+      pick,
+      depth
+    });
+    const result = await executeFoirDocument(config, plan);
+    recordFoirSubjects(config.subjects, plan, result);
+    maybeCheckDrift();
+    return result;
+  };
+  const subscriptions = /* @__PURE__ */ (() => {
+    const held = { router: null };
+    return {
+      get() {
+        held.router ??= new FoirSubscriptionRouter(config, manifest);
+        return held.router;
+      },
+      dispose() {
+        held.router?.dispose();
+        held.router = null;
+      }
+    };
+  })();
   const opProxy = (address) => new Proxy({}, {
     get(_target, op) {
       if (typeof op !== "string" || NON_MODEL_PROPS.has(op)) return void 0;
-      return (query) => {
-        const { args, include, omit, pick } = splitQuery(query);
-        return run({ ...address, op, args, include, omit, pick });
-      };
+      if ("model" in address) {
+        if (isModelSubscriptionMethod(op)) {
+          return (input) => subscriptions.get().model(address.model, op, input ?? {});
+        }
+      } else if (isNamespaceSubscriptionMethod(address.namespace, op)) {
+        return (input) => subscriptions.get().namespace(address.namespace, op, input ?? {});
+      }
+      return (query) => "model" in address ? runModel(address.model, op, query) : runNamespace(address.namespace, op, query);
     }
   });
   const nsProxy = new Proxy({}, {
@@ -276,11 +1629,24 @@ function createFoirClient(config) {
       return opProxy({ namespace });
     }
   });
-  const raw = (op) => run(op);
+  const raw = async (document, variables) => {
+    if (typeof document !== "string" || !document.trim()) {
+      throw new FoirRequestError("[foir] raw() takes a GraphQL document string");
+    }
+    const result = await executeFoirRawDocument(
+      config,
+      document,
+      isFoirMutationDocument(document),
+      variables
+    );
+    maybeCheckDrift();
+    return result;
+  };
   return new Proxy({}, {
     get(_target, prop) {
       if (prop === "ns") return nsProxy;
       if (prop === "raw") return raw;
+      if (prop === "dispose") return () => subscriptions.dispose();
       if (typeof prop !== "string" || NON_MODEL_PROPS.has(prop)) return void 0;
       return opProxy({ model: prop });
     }
@@ -302,8 +1668,16 @@ function createFoirClientFromEnv(env, overrides) {
 }
 export {
   FoirRequestError,
+  FoirSocketTransport,
   createFoirClient,
   createFoirClientFromEnv,
+  createFoirSubjectRegistry,
   fetchFoirManifest,
-  foirDataEndpoint
+  foirDataEndpoint,
+  foirRoute,
+  foirSocketEndpoint,
+  planFoirModelCall,
+  planFoirNamespaceCall,
+  printSubscriptionDocument,
+  recordFoirSubjects
 };