@distilled.cloud/core 1.0.0-rc.11 → 1.0.0-rc.13

package/lib/graphql.js

@@ -1,11 +1,80 @@
-/** GraphQL selections, typed failures and Effect execution for generated SDKs. */
+/**
+ * GraphQL Query algebra — the runtime generated GraphQL SDKs target.
+ *
+ * ── Why this exists ────────────────────────────────────────────────────────
+ * A GraphQL document is a *selection*, not an RPC. Distilled used to bake a
+ * max-depth selection into every operation (`Railway.me({})` downloaded the
+ * world). This module instead treats every field as a lazy `Query<Value>`:
+ * reading `user.email` records that field, and nothing is posted until
+ * `Query.fn` evaluates the plan you returned.
+ *
+ * ── The two phases ─────────────────────────────────────────────────────────
+ * 1. Build (your function). `Railway.me()` / `user.email` / `Query.map` do
+ *    not talk to the network. They construct an expression tree:
+ *      Of | Map | Filter | FlatMap | Prop | Root
+ *    The inner function of `Query.fn` is therefore a *builder*, not an
+ *    Effect generator. No `yield*` inside it.
+ *
+ * 2. Evaluate (`Query.fn`). Walk the returned plan, paint every GraphQL
+ *    field that appears onto one selection forest, POST that document
+ *    once through {@link GqlTransport}, then interpret Map/Filter/FlatMap
+ *    against the JSON. Effects reached via FlatMap (e.g.
+ *    `usernameIsAvailable(name)`) run *after* the POST, with real values.
+ *
+ * ── Combinators ────────────────────────────────────────────────────────────
+ * - `Query.of(x)` — a literal; never selected.
+ * - `Query.map` on a list — callback receives `Query<Item>` so `p.name` is
+ *   still a Query (selected). On a scalar, callback receives the value
+ *   after extract (`stars => stars > 5`). Relay connections (`edges { node }`)
+ *   are lists of the node type, so `projects({ first: 20 }).pipe(Query.map)`
+ *   maps projects, not edges.
+ * - `Query.filter` — predicate is `Query<Item> => Query<boolean>`; the
+ *   boolean Query is walked for fields, then run per row after the POST.
+ * - `Query.flatMap` — after extract, run `(value) => Effect | Query`.
+ * - `Query.pages` / `Query.items` — a Stream over every page / node of a
+ *   Relay connection, one POST per page (see "Pagination").
+ *
+ * ── Types ──────────────────────────────────────────────────────────────────
+ * `Query<Value>` is `QueryNode<Value>` plus the GraphQL fields of `Value`,
+ * so `user.name` type-checks. That copy is a circular type alias
+ * (`Query<User>` contains `Query<Project[]>` which contains `Query<User>`
+ * again). TypeScript leaves the cycle lazy; there is no depth cap.
+ *
+ * ── Transport ──────────────────────────────────────────────────────────────
+ * {@link GqlTransport.execute} posts `{ query, variables, operationName }`.
+ * The Effect it returns may require Credentials / HttpClient; those leak
+ * into `Query.fn`'s requirements. It returns the parsed `data` and raw
+ * `errors`; `Query.fn` classifies the errors (see "Errors" below). Compile
+ * failures are {@link GqlError} defects.
+ *
+ * Generated SDKs export *roots* (`Railway.me`, `Railway.project`).
+ * Combinators live in `@distilled.cloud/core/query`.
+ */
+import * as Context from "effect/Context";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import * as S from "effect/Schema";
 import * as Schedule from "effect/Schedule";
+import * as S from "effect/Schema";
 import * as Stream from "effect/Stream";
-import { Kind, parseType, print, } from "graphql";
+export const QuerySymbol = Symbol.for("@distilled.cloud/graphql/Query");
+const inspect = Symbol.for("nodejs.util.inspect.custom");
+/** A plan that cannot be compiled (a programming error, raised as a defect). */
+export class GqlError {
+    message;
+    _tag = "GqlError";
+    constructor(message) {
+        this.message = message;
+    }
+}
+// ── Errors ──────────────────────────────────────────────────────────────────
+//
+// Every entry of a GraphQL `errors` array becomes one typed issue. Generated
+// SDKs declare tagged error classes plus the matchers that recognize them,
+// scoped to the root fields that can return them (or global). `Query.fn`
+// classifies each entry against the roots its path points at, so the error
+// channel is the union of the errors declared by the roots the plan reads.
+/** Fields every classified GraphQL error carries. */
 export const errorFields = {
     message: S.String,
     code: S.optional(S.String),
@@ -14,14 +83,17 @@ export const errorFields = {
     extensions: S.optional(S.Unknown),
     traceId: S.optional(S.String),
     status: S.optional(S.Number),
+    /** Server retry hint in seconds. */
     retryAfter: S.optional(S.Number),
 };
+/** A GraphQL error no declared matcher recognizes. */
 export class UnknownGraphQLError extends S.TaggedError()("UnknownGraphQLError", {
     ...errorFields,
+    /** Root field the error path points at, when the path is known. */
     coordinate: S.optional(S.String),
 }) {
 }
-/** All errors from one GraphQL execution, with the original partial response. */
+/** One response carried errors with different tags; none is hidden. */
 export class GraphQLFailure extends Data.TaggedError("GraphQLFailure") {
     get message() {
         return this.errors
@@ -29,479 +101,741 @@ export class GraphQLFailure extends Data.TaggedError("GraphQLFailure") {
             .join("; ");
     }
 }
+/** The request never produced a GraphQL response (network, HTTP, non-JSON). */
 export class GraphQLTransportError extends Data.TaggedError("GraphQLTransportError") {
 }
-export class GraphQLDecodeError extends Data.TaggedError("GraphQLDecodeError") {
+/** A paginated connection reported more pages without a new cursor. */
+export class GraphQLPaginationError extends Data.TaggedError("GraphQLPaginationError") {
 }
-export class GraphQLRequestError extends Data.TaggedError("GraphQLRequestError") {
+export const errorSpec = (make, tag, matchers, options = {}) => ({
+    tag,
+    make: (props) => new make(props),
+    matchers,
+    retryable: options.retryable ?? false,
+    global: options.global ?? false,
+});
+export const scalarField = (name) => ({
+    name,
+    kind: "scalar",
+});
+export const objectField = (name, objectType) => ({
+    name,
+    kind: "object",
+    of: objectType,
+});
+export const listField = (name, itemType, argTypes) => ({
+    name,
+    kind: "list",
+    of: itemType,
+    argTypes,
+});
+/** Relay connection: GraphQL `edges { node }` presented as `Query<Item[]>`. */
+export const connectionField = (name, nodeType, argTypes) => ({
+    name,
+    kind: "connection",
+    of: nodeType,
+    argTypes,
+});
+const objectRef = (meta) => ({ tag: "object", meta });
+const listRef = (itemType) => ({
+    tag: "list",
+    of: itemType,
+});
+const fieldResult = (parent, field) => {
+    const inner = () => {
+        if (field.kind === "scalar")
+            return { tag: "scalar" };
+        if (field.kind === "object")
+            return objectRef(field.of);
+        return listRef(objectRef(field.of)); // list | connection
+    };
+    return parent.tag === "list"
+        ? listRef(fieldResult(parent.of, field))
+        : inner();
+};
+const unwrapList = (typeRef) => {
+    if (typeRef.tag !== "list")
+        throw new GqlError("expected a list Query");
+    return typeRef.of;
+};
+const fieldsOf = (typeRef) => {
+    if (typeRef.tag === "object")
+        return typeRef.meta.fields;
+    if (typeRef.tag === "list")
+        return fieldsOf(typeRef.of);
+    return {};
+};
+export class GqlTransport extends Context.Service()("@distilled.cloud/graphql/Transport") {
 }
-/** True only when every issue has an allowed tag; mixed failures are never hidden. */
-export const isErrorTag = (error, tags) => {
-    const allowed = typeof tags === "string" ? [tags] : tags;
-    return (error instanceof GraphQLFailure &&
-        error.errors.length > 0 &&
-        error.errors.every((issue) => allowed.includes(issue._tag)));
-};
-/** Recover only an aggregate whose every issue matches. The original aggregate is also supplied. */
-export const catchTags = (tags, handler) => (self) => self.pipe(Effect.catch((error) => isErrorTag(error, tags)
-    ? handler(error.errors[0], error)
-    : Effect.fail(error)));
-const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-const named = (ref) => ref.replace(/[\[\]!]/g, "");
-const nameNode = (value) => ({ kind: Kind.NAME, value });
-const requestError = (message) => {
-    throw new GraphQLRequestError({ message });
-};
-const assertName = (name) => {
-    if (!/^[_A-Za-z][_0-9A-Za-z]*$/.test(name))
-        requestError(`Invalid GraphQL name ${name}`);
-};
-/** Validate and encode inputs recursively. Undefined omits; null stays null. */
-const encodeInput = (model, ref, value, at) => {
-    if (value === undefined)
-        return undefined;
-    if (value === null) {
-        if (ref.endsWith("!"))
-            requestError(`${at} must not be null`);
-        return null;
-    }
-    const base = ref.endsWith("!") ? ref.slice(0, -1) : ref;
-    if (base.startsWith("[")) {
-        if (!Array.isArray(value))
-            requestError(`${at} must be an array`);
-        return value.map((v, i) => {
-            if (v === undefined)
-                requestError(`${at}[${i}] must not be undefined`);
-            return encodeInput(model, base.slice(1, -1), v, `${at}[${i}]`);
-        });
+const log = (..._args) => { };
+export class QueryNode {
+    expr;
+    [QuerySymbol] = QuerySymbol;
+    constructor(expr) {
+        this.expr = expr;
+        return proxy(this);
     }
-    const type = model.types[base];
-    if (!type)
-        requestError(`${at}: unknown input type ${base}`);
-    if (type.kind === "INPUT_OBJECT") {
-        if (!object(value))
-            requestError(`${at} must be an input object`);
-        const input = value;
-        const result = {};
-        for (const key of Object.keys(input))
-            if (!type.inputFields?.[key])
-                requestError(`${at}: unknown input field ${key}`);
-        for (const [key, field] of Object.entries(type.inputFields ?? {})) {
-            if (input[key] === undefined) {
-                if (field.type.endsWith("!") && field.defaultValue === undefined)
-                    requestError(`${at}.${key} is required`);
+    pipe(...steps) {
+        return steps.reduce((current, step) => step(current), this);
+    }
+    [inspect]() {
+        return printExpr(this.expr);
+    }
+    toString() {
+        return this[inspect]();
+    }
+}
+export const isQuery = (value) => (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    QuerySymbol in value;
+const make = (expr) => new QueryNode(expr);
+const itemQuery = (list) => new QueryNode({
+    _tag: "Item",
+    list: list.expr,
+    type: unwrapList(list.expr.type),
+});
+function proxy(self) {
+    const callable = Object.assign(function (bag) {
+        return bag == null ? self : applyBag(self, bag);
+    }, self);
+    return new Proxy(callable, {
+        has: (_, prop) => prop === QuerySymbol ||
+            prop === inspect ||
+            prop in self ||
+            (typeof prop === "string" && prop in fieldsOf(self.expr.type)),
+        get: (_target, prop) => {
+            if (prop === QuerySymbol)
+                return QuerySymbol;
+            if (prop === inspect)
+                return self[inspect].bind(self);
+            if (prop === "pipe")
+                return self.pipe.bind(self);
+            if (typeof prop === "string" && prop in self) {
+                const member = self[prop];
+                return typeof member === "function" ? member.bind(self) : member;
             }
-            else
-                result[key] = encodeInput(model, field.type, input[key], `${at}.${key}`);
-        }
-        return result;
-    }
-    if (type.kind === "ENUM") {
-        if (typeof value !== "string" || !type.enumValues?.includes(value))
-            requestError(`${at}: invalid ${base}`);
-    }
-    else if (type.scalar === "string" || base === "String" || base === "ID") {
-        if (typeof value !== "string")
-            requestError(`${at} must be a string`);
-    }
-    else if (type.scalar === "number" || base === "Int" || base === "Float") {
-        if (typeof value !== "number" || !Number.isFinite(value))
-            requestError(`${at} must be a finite number`);
-        if (base === "Int" &&
-            (!Number.isInteger(value) ||
-                value < -2147483648 ||
-                value > 2147483647))
-            requestError(`${at} must be a GraphQL Int`);
-    }
-    else if (type.scalar === "boolean" || base === "Boolean") {
-        if (typeof value !== "boolean")
-            requestError(`${at} must be a boolean`);
-    }
-    if (type.scalar === "string | number" &&
-        typeof value !== "string" &&
-        typeof value !== "number")
-        requestError(`${at} must be a string or number`);
-    if (base === "BigInt" &&
-        ((typeof value === "number" && !Number.isSafeInteger(value)) ||
-            (typeof value === "string" && !/^-?\d+$/.test(value))))
-        requestError(`${at} must be a safe integer or an integer string`);
-    // JSON custom scalars must still be transportable JSON; preserve scalar contents.
-    try {
-        return JSON.parse(JSON.stringify(value));
-    }
-    catch {
-        return requestError(`${at} is not a JSON-encodable scalar`);
-    }
-};
-/** Compile one selection to a GraphQL AST, variables, and an error/decoder path map. */
-export const compile = (model, kind, selection, operationName = "Distilled") => {
-    const rootType = kind === "query" ? model.queryType : model.mutationType;
-    if (!rootType)
-        return requestError(`Schema has no ${kind} root`);
-    assertName(operationName);
-    const variables = {};
-    const definitions = [];
-    const variable = (ref, value) => {
-        const id = `v${definitions.length}`;
-        variables[id] = value;
-        definitions.push({
-            kind: Kind.VARIABLE_DEFINITION,
-            variable: { kind: Kind.VARIABLE, name: nameNode(id) },
-            type: parseType(ref),
+            if (typeof prop !== "string")
+                return undefined;
+            const field = fieldsOf(self.expr.type)[prop];
+            if (!field)
+                return undefined;
+            return make({
+                _tag: "Prop",
+                parent: self.expr,
+                field,
+                type: fieldResult(self.expr.type, field),
+            });
+        },
+        apply: (_target, _thisArg, args) => applyBag(self, args[0] ?? {}),
+    });
+}
+const applyBag = (self, bag) => {
+    const argTypes = self.expr._tag === "Prop"
+        ? self.expr.field.argTypes
+        : self.expr._tag === "Root"
+            ? self.expr.argTypes
+            : undefined;
+    const args = {};
+    for (const [argName, argValue] of Object.entries(bag)) {
+        if (argTypes && argName in argTypes)
+            args[argName] = argValue;
+    }
+    if (self.expr._tag === "Prop") {
+        return make({
+            ...self.expr,
+            args: { ...self.expr.args, ...args },
+        });
+    }
+    if (self.expr._tag === "Root") {
+        return make({
+            ...self.expr,
+            args: { ...self.expr.args, ...args },
         });
-        return { kind: Kind.VARIABLE, name: nameNode(id) };
+    }
+    return self;
+};
+export const root = (op, field, meta, args, argTypes, errors = []) => make({
+    _tag: "Root",
+    op,
+    field,
+    args,
+    argTypes,
+    type: objectRef(meta),
+    errors,
+});
+export const rootList = (op, field, meta, args, argTypes, errors = []) => make({
+    _tag: "Root",
+    op,
+    field,
+    args,
+    argTypes,
+    type: listRef(objectRef(meta)),
+    errors,
+});
+/** Root Relay connection: typed as `Query<Item[]>`, document uses `edges { node }`. */
+export const rootConnection = (op, field, meta, args, argTypes, errors = []) => make({
+    _tag: "Root",
+    op,
+    field,
+    args,
+    argTypes,
+    type: listRef(objectRef(meta)),
+    connection: true,
+    errors,
+});
+/** Root field whose GraphQL type is a scalar, enum, or list of those. */
+export const rootLeaf = (op, field, list, args, argTypes, errors = []) => make({
+    _tag: "Root",
+    op,
+    field,
+    args,
+    argTypes,
+    type: list ? listRef({ tag: "scalar" }) : { tag: "scalar" },
+    errors,
+});
+const printExpr = (expr) => {
+    switch (expr._tag) {
+        case "Root":
+            return expr.args
+                ? `${expr.field}(${JSON.stringify(expr.args)})`
+                : expr.field;
+        case "Prop":
+            return `${printExpr(expr.parent)}.${expr.field.name}`;
+        case "Item":
+            return "$item";
+        case "MapValue":
+            return `map(${printExpr(expr.parent)})`;
+        case "MapItems":
+            return `mapItems(${printExpr(expr.parent)})`;
+        case "Filter":
+            return `filter(${printExpr(expr.parent)})`;
+        case "FlatMap":
+            return `flatMap(${printExpr(expr.parent)})`;
+        case "Literal":
+            return `of(${String(expr.value)})`;
+    }
+};
+const emptySel = (field) => ({
+    field,
+    alias: undefined,
+    args: undefined,
+    children: new Map(),
+    isScalar: false,
+    isList: false,
+});
+const stableStringify = (value) => {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+};
+const bindArgs = (forest, args, argTypes) => {
+    if (args === undefined)
+        return undefined;
+    const bound = {};
+    let hasArgs = false;
+    for (const [name, value] of Object.entries(args)) {
+        if (value === undefined)
+            continue;
+        forest.vars.set(`v${forest.varI}`, {
+            type: argTypes?.[name] ?? "String",
+            value,
+        });
+        bound[name] = `v${forest.varI++}`;
+        hasArgs = true;
+    }
+    return hasArgs ? bound : undefined;
+};
+const ensureChild = (forest, parent, field, options) => {
+    const key = options.args === undefined
+        ? field
+        : `${field}:${stableStringify(options.args)}`;
+    const existing = parent.children.get(key);
+    if (existing)
+        return existing;
+    const taken = new Set([...parent.children.values()].map((c) => c.alias ?? c.field));
+    let alias;
+    if (taken.has(field)) {
+        do {
+            alias = `${field}_${forest.aliasI++}`;
+        } while (taken.has(alias));
+    }
+    const sel = {
+        field,
+        alias,
+        args: bindArgs(forest, options.args, options.argTypes),
+        children: new Map(),
+        isScalar: options.isScalar ?? false,
+        isList: options.isList ?? false,
     };
-    const walk = (parent, input) => {
-        if (!object(input))
-            return requestError(`${parent} requires an object selection`);
-        const type = model.types[parent];
-        if (!type)
-            return requestError(`Unknown GraphQL type ${parent}`);
-        const nodes = [];
-        const positions = [];
-        const addField = (fieldName, selected, alias) => {
-            if (selected === false || selected === undefined)
-                return;
-            assertName(fieldName);
-            if (alias)
-                assertName(alias);
-            const key = alias ?? fieldName;
-            if (positions.some((p) => p.key === key))
-                return requestError(`Duplicate response key ${parent}.${key}; use distinct aliases`);
-            const field = fieldName === "__typename"
-                ? { type: "String!", args: {}, errors: [] }
-                : type.fields?.[fieldName];
-            if (!field)
-                return requestError(`Unknown field ${parent}.${fieldName}`);
-            const wrapper = object(selected) &&
-                ("where" in selected ||
-                    "select" in selected ||
-                    "$include" in selected ||
-                    "$skip" in selected)
-                ? selected
-                : undefined;
-            const args = wrapper?.where ?? {};
-            if (!object(args))
-                return requestError(`${parent}.${fieldName}.where must be an object`);
-            for (const arg of Object.keys(args))
-                if (!field.args[arg])
-                    return requestError(`Unknown argument ${parent}.${fieldName}(${arg})`);
-            const arguments_ = [];
-            for (const [arg, definition] of Object.entries(field.args)) {
-                if (args[arg] === undefined) {
-                    if (definition.type.endsWith("!") &&
-                        definition.defaultValue === undefined)
-                        return requestError(`${parent}.${fieldName}(${arg}) is required`);
-                }
-                else
-                    arguments_.push({
-                        kind: Kind.ARGUMENT,
-                        name: nameNode(arg),
-                        value: variable(definition.type, encodeInput(model, definition.type, args[arg], `${parent}.${fieldName}(${arg})`)),
-                    });
-            }
-            const directives = [];
-            for (const directive of ["include", "skip"]) {
-                const value = wrapper?.[`$${directive}`];
-                if (value !== undefined) {
-                    if (typeof value !== "boolean")
-                        return requestError(`$${directive} must be a boolean`);
-                    directives.push({
-                        kind: Kind.DIRECTIVE,
-                        name: nameNode(directive),
-                        arguments: [
-                            {
-                                kind: Kind.ARGUMENT,
-                                name: nameNode("if"),
-                                value: variable("Boolean!", value),
-                            },
-                        ],
-                    });
-                }
-            }
-            const outputType = model.types[named(field.type)];
-            const leaf = fieldName === "__typename" ||
-                outputType?.kind === "SCALAR" ||
-                outputType?.kind === "ENUM";
-            const sub = wrapper ? wrapper.select : selected;
-            let child = { nodes: [], positions: [] };
-            if (leaf) {
-                if (sub !== true && sub !== undefined)
-                    return requestError(`${parent}.${fieldName} is a leaf and takes no selection`);
+    parent.children.set(key, sel);
+    return sel;
+};
+const paintConnection = (forest, connection) => {
+    const edges = ensureChild(forest, connection, "edges", { isList: true });
+    ensureChild(forest, edges, "node", {});
+    return ["edges", "node"];
+};
+const paintAbs = (forest, expr) => {
+    switch (expr._tag) {
+        case "Root": {
+            if (forest.kind !== undefined && forest.kind !== expr.op) {
+                throw new GqlError(`cannot mix ${forest.kind} and ${expr.op} in one document`);
             }
-            else
-                child = walk(named(field.type), sub);
-            nodes.push({
-                kind: Kind.FIELD,
-                name: nameNode(fieldName),
-                ...(alias ? { alias: nameNode(alias) } : {}),
-                arguments: arguments_,
-                directives,
-                ...(!leaf
-                    ? {
-                        selectionSet: {
-                            kind: Kind.SELECTION_SET,
-                            selections: child.nodes,
-                        },
-                    }
-                    : {}),
+            forest.kind = expr.op;
+            const node = ensureChild(forest, forest.roots, expr.field, {
+                args: expr.args,
+                argTypes: expr.argTypes,
+                // Leaf roots (`projectDelete: Boolean!`) take no sub-selection.
+                isScalar: expr.type.tag === "scalar" ||
+                    (expr.type.tag === "list" && expr.type.of.tag === "scalar"),
+                isList: expr.type.tag === "list" && !expr.connection,
             });
-            const branches = {};
-            // Branch metadata is attached to sentinel positions by walk and removed from regular children.
-            for (const p of child.positions)
-                if (p.field === "__fragment")
-                    branches[p.type] = p.children;
-            positions.push({
-                field: fieldName,
-                key,
-                coordinate: `${parent}.${fieldName}`,
-                type: field.type,
-                errors: field.errors,
-                children: child.positions.filter((p) => p.field !== "__fragment"),
-                branches,
-                typename: fieldName === "__typename",
-                conditional: wrapper?.$include === false || wrapper?.$skip === true,
+            const key = node.alias ?? node.field;
+            forest.rootAlias.set(expr, key);
+            forest.rootErrors.set(key, { field: expr.field, errors: expr.errors });
+            return expr.connection ? [key, ...paintConnection(forest, node)] : [key];
+        }
+        case "Prop": {
+            const parentPath = paintAbs(forest, expr.parent);
+            const parentSel = selAt(forest.roots, parentPath);
+            const node = ensureChild(forest, parentSel, expr.field.name, {
+                args: expr.args,
+                argTypes: expr.field.argTypes,
+                isScalar: expr.field.kind === "scalar",
+                isList: expr.field.kind === "list",
             });
-        };
-        for (const [key, value] of Object.entries(input)) {
-            if (key === "__alias") {
-                if (!object(value))
-                    return requestError(`${parent}.__alias must be an object`);
-                for (const [alias, fields] of Object.entries(value)) {
-                    if (!object(fields) || Object.keys(fields).length !== 1)
-                        return requestError(`Alias ${alias} must select exactly one field`);
-                    const [field, selected] = Object.entries(fields)[0];
-                    addField(field, selected, alias);
-                }
-            }
-            else if (key === "__on") {
-                if (!object(value))
-                    return requestError(`${parent}.__on must be an object`);
-                for (const [branch, fields] of Object.entries(value)) {
-                    if (!type.possibleTypes?.includes(branch))
-                        return requestError(`${branch} is not a possible type of ${parent}`);
-                    const children = walk(branch, fields);
-                    nodes.push({
-                        kind: Kind.INLINE_FRAGMENT,
-                        typeCondition: { kind: Kind.NAMED_TYPE, name: nameNode(branch) },
-                        selectionSet: {
-                            kind: Kind.SELECTION_SET,
-                            selections: children.nodes,
-                        },
-                    });
-                    positions.push({
-                        field: "__fragment",
-                        key: "",
-                        coordinate: parent,
-                        type: branch,
-                        errors: [],
-                        children: children.positions,
-                        branches: {},
-                        conditional: false,
-                    });
-                }
+            const path = [...parentPath, node.alias ?? node.field];
+            return expr.field.kind === "connection"
+                ? [...path, ...paintConnection(forest, node)]
+                : path;
+        }
+        default:
+            throw new GqlError(`paintAbs: ${expr._tag}`);
+    }
+};
+const selAt = (roots, path) => {
+    let current = roots;
+    for (const segment of path) {
+        if (segment === "*")
+            continue;
+        const child = [...current.children.values()].find((candidate) => (candidate.alias ?? candidate.field) === segment);
+        if (!child) {
+            throw new GqlError(`internal: missing ${String(segment)}`);
+        }
+        current = child;
+    }
+    return current;
+};
+const connectionNodeSel = (connection) => {
+    const edges = [...connection.children.values()].find((c) => c.field === "edges");
+    const node = edges
+        ? [...edges.children.values()].find((c) => c.field === "node")
+        : undefined;
+    if (!node)
+        throw new GqlError("internal: connection missing edges.node");
+    return node;
+};
+const relSel = (expr, listSel) => {
+    switch (expr._tag) {
+        case "Item":
+            return listSel;
+        case "Prop": {
+            const parent = relSel(expr.parent, listSel);
+            const child = [...parent.children.values()].find((c) => c.field === expr.field.name);
+            if (!child) {
+                throw new GqlError(`missing ${expr.field.name} in list selection`);
             }
-            else
-                addField(key, value);
+            return expr.field.kind === "connection"
+                ? connectionNodeSel(child)
+                : child;
         }
-        if (type.possibleTypes?.length && !positions.some((p) => p.typename))
-            addField("__typename", true);
-        if (!nodes.length)
-            return requestError(`${parent} has an empty selection`);
-        return { nodes, positions };
-    };
-    const selected = walk(rootType, selection);
-    const query = print({
-        kind: Kind.DOCUMENT,
-        definitions: [
-            {
-                kind: Kind.OPERATION_DEFINITION,
-                operation: kind,
-                name: nameNode(operationName),
-                variableDefinitions: definitions,
-                selectionSet: { kind: Kind.SELECTION_SET, selections: selected.nodes },
-            },
-        ],
-    });
+        default:
+            return listSel;
+    }
+};
+const paintRel = (forest, expr, listSel) => {
+    switch (expr._tag) {
+        case "Item":
+        case "Literal":
+            return;
+        case "Prop": {
+            paintRel(forest, expr.parent, listSel);
+            const child = ensureChild(forest, relSel(expr.parent, listSel), expr.field.name, {
+                args: expr.args,
+                argTypes: expr.field.argTypes,
+                isScalar: expr.field.kind === "scalar",
+                isList: expr.field.kind === "list",
+            });
+            if (expr.field.kind === "connection")
+                paintConnection(forest, child);
+            return;
+        }
+        case "MapValue":
+        case "FlatMap":
+            paintRel(forest, expr.parent, listSel);
+            return;
+        case "MapItems":
+            paintRel(forest, expr.parent, listSel);
+            visitRel(expr.mapped, forest, relSel(expr.parent, listSel));
+            return;
+        case "Filter":
+            paintRel(forest, expr.parent, listSel);
+            paintRel(forest, expr.predicate, relSel(expr.parent, listSel));
+            return;
+        case "Root":
+            throw new GqlError("root inside list item");
+    }
+};
+const visitExpr = (forest, expr) => {
+    switch (expr._tag) {
+        case "Root":
+        case "Prop":
+            paintAbs(forest, expr);
+            return;
+        case "Item":
+            return;
+        case "Literal":
+            return;
+        case "MapValue":
+        case "FlatMap":
+            visitExpr(forest, expr.parent);
+            return;
+        case "MapItems": {
+            visitExpr(forest, expr.parent);
+            const path = paintAbs(forest, graphqlBase(expr.parent));
+            visitRel(expr.mapped, forest, selAt(forest.roots, path));
+            return;
+        }
+        case "Filter": {
+            visitExpr(forest, expr.parent);
+            const path = paintAbs(forest, graphqlBase(expr.parent));
+            paintRel(forest, expr.predicate, selAt(forest.roots, path));
+            return;
+        }
+    }
+};
+const graphqlBase = (expr) => {
+    switch (expr._tag) {
+        case "Root":
+        case "Prop":
+        case "Item":
+            return expr;
+        case "MapValue":
+        case "MapItems":
+        case "Filter":
+        case "FlatMap":
+            return graphqlBase(expr.parent);
+        case "Literal":
+            throw new GqlError("literal has no graphql base");
+    }
+};
+const visitRel = (plan, forest, listSel) => {
+    if (isQuery(plan)) {
+        paintRel(forest, plan.expr, listSel);
+        return;
+    }
+    if (plan !== null && typeof plan === "object" && !Effect.isEffect(plan)) {
+        for (const nested of Object.values(plan)) {
+            visitRel(nested, forest, listSel);
+        }
+    }
+};
+/**
+ * Recurse through a builder return value. Query nodes contribute GraphQL
+ * fields to `forest`; Effects are ignored until interpret (FlatMap).
+ */
+const visitPlan = (plan, forest) => {
+    if (isQuery(plan)) {
+        log("visit", printExpr(plan.expr));
+        visitExpr(forest, plan.expr);
+        return;
+    }
+    if (Effect.isEffect(plan))
+        return;
+    if (plan !== null && typeof plan === "object" && !Array.isArray(plan)) {
+        for (const nested of Object.values(plan)) {
+            visitPlan(nested, forest);
+        }
+    }
+};
+const validate = (node) => {
+    for (const child of node.children.values()) {
+        if (!child.isScalar && child.children.size === 0) {
+            return `field "${child.field}" has no sub-selection`;
+        }
+        const inner = validate(child);
+        if (inner)
+            return inner;
+    }
+    return undefined;
+};
+const printChildren = (node, indent) => {
+    const pad = "  ".repeat(indent);
+    const lines = [];
+    for (const child of node.children.values()) {
+        let head = child.alias ? `${child.alias}: ${child.field}` : child.field;
+        if (child.args && Object.keys(child.args).length > 0) {
+            const printed = Object.entries(child.args)
+                .map(([argName, varName]) => `${argName}: $${varName}`)
+                .join(", ");
+            head += `(${printed})`;
+        }
+        if (child.isScalar)
+            lines.push(`${pad}${head}`);
+        else {
+            lines.push(`${pad}${head} {`);
+            lines.push(printChildren(child, indent + 1));
+            lines.push(`${pad}}`);
+        }
+    }
+    return lines.join("\n");
+};
+const emptyForest = () => ({
+    kind: undefined,
+    roots: emptySel(""),
+    vars: new Map(),
+    varI: 0,
+    aliasI: 0,
+    rootAlias: new WeakMap(),
+    rootErrors: new Map(),
+});
+const emit = (forest) => {
+    const err = validate(forest.roots);
+    if (err)
+        throw new GqlError(err);
+    const kind = forest.kind ?? "query";
+    const varDefs = [...forest.vars.entries()]
+        .map(([name, binding]) => `$${name}: ${binding.type}`)
+        .join(", ");
+    const header = varDefs.length > 0 ? `${kind} Gql(${varDefs})` : `${kind} Gql`;
+    const variables = {};
+    for (const [name, binding] of forest.vars)
+        variables[name] = binding.value;
     return {
-        query,
+        document: `${header} {\n${printChildren(forest.roots, 1)}\n}`,
+        operationName: "Gql",
         variables,
-        operationName,
         kind,
-        rootType,
-        positions: selected.positions,
+        tree: forest.roots,
+        rootAlias: forest.rootAlias,
+        rootErrors: forest.rootErrors,
     };
 };
-const decodeFailure = (message, path) => {
-    throw new GraphQLDecodeError({ message, path });
-};
-/** Validate only selected fields. Preserve the schema's nullability exactly. */
-const decodeData = (model, ref, data, positions, branches, path) => {
-    if (data === null) {
-        if (ref.endsWith("!"))
-            return decodeFailure(`Non-null ${ref} was null`, path);
-        return null;
-    }
-    if (data === undefined)
-        return decodeFailure(`Missing selected ${ref}`, path);
-    const base = ref.endsWith("!") ? ref.slice(0, -1) : ref;
-    if (base.startsWith("[")) {
-        if (!Array.isArray(data))
-            return decodeFailure(`Expected ${ref} array`, path);
-        return data.map((v, i) => decodeData(model, base.slice(1, -1), v, positions, branches, [
-            ...path,
-            i,
-        ]));
-    }
-    const type = model.types[base];
-    if (!type)
-        return decodeFailure(`Unknown response type ${base}`, path);
-    if (type.kind === "SCALAR") {
-        const primitive = type.scalar ??
-            {
-                String: "string",
-                ID: "string",
-                Boolean: "boolean",
-                Int: "number",
-                Float: "number",
-            }[base];
-        if (primitive === "string | number" &&
-            typeof data !== "string" &&
-            typeof data !== "number")
-            return decodeFailure(`Expected ${base}`, path);
-        if (base === "BigInt" &&
-            ((typeof data === "number" && !Number.isSafeInteger(data)) ||
-                (typeof data === "string" && !/^-?\d+$/.test(data))))
-            return decodeFailure(`Invalid ${base}`, path);
-        if (["string", "number", "boolean"].includes(primitive ?? "") &&
-            typeof data !== primitive)
-            return decodeFailure(`Expected ${base}`, path);
-        if (typeof data === "number" &&
-            (!Number.isFinite(data) ||
-                (base === "Int" &&
-                    (!Number.isInteger(data) || data < -2147483648 || data > 2147483647))))
-            return decodeFailure(`Invalid ${base}`, path);
-        return data;
-    }
-    if (type.kind === "ENUM") {
-        if (typeof data !== "string" || !type.enumValues?.includes(data))
-            return decodeFailure(`Invalid ${base} enum`, path);
-        return data;
-    }
-    if (!object(data))
-        return decodeFailure(`Expected ${base} object`, path);
-    if (type.possibleTypes?.length &&
-        (typeof data.__typename !== "string" ||
-            !type.possibleTypes.includes(data.__typename)))
-        return decodeFailure(`Missing or invalid ${base} __typename`, path);
-    const active = [
-        ...positions,
-        ...(typeof data.__typename === "string"
-            ? (branches[data.__typename] ?? [])
-            : []),
-    ];
-    const result = {};
-    const merged = new Map();
-    for (const position of active) {
-        if (position.conditional)
-            continue;
-        const previous = merged.get(position.key);
-        merged.set(position.key, previous
-            ? {
-                ...position,
-                children: [...previous.children, ...position.children],
-                branches: Object.fromEntries([
-                    ...new Set([
-                        ...Object.keys(previous.branches),
-                        ...Object.keys(position.branches),
-                    ]),
-                ].map((key) => [
-                    key,
-                    [
-                        ...(previous.branches[key] ?? []),
-                        ...(position.branches[key] ?? []),
-                    ],
-                ])),
+const nodesFromConnection = (value) => {
+    if (value == null)
+        return value;
+    if (Array.isArray(value))
+        return value.map(nodesFromConnection);
+    const edges = value.edges;
+    if (!Array.isArray(edges))
+        return [];
+    return edges.map((edge) => edge == null ? edge : edge.node);
+};
+const readField = (parent, name) => {
+    if (parent == null)
+        return parent;
+    if (Array.isArray(parent)) {
+        return parent.map((item) => item == null ? item : item[name]);
+    }
+    return parent[name];
+};
+const extractAbs = (expr, data, rootAlias) => {
+    switch (expr._tag) {
+        case "Root": {
+            const raw = data[rootAlias.get(expr) ?? expr.field];
+            return expr.connection ? nodesFromConnection(raw) : raw;
+        }
+        case "Prop": {
+            const value = readField(extractAbs(expr.parent, data, rootAlias), expr.field.name);
+            return expr.field.kind === "connection"
+                ? nodesFromConnection(value)
+                : value;
+        }
+        default:
+            throw new GqlError(`extractAbs: ${expr._tag}`);
+    }
+};
+const extractRel = (expr, item) => {
+    switch (expr._tag) {
+        case "Item":
+            return item;
+        case "Prop": {
+            const value = readField(extractRel(expr.parent, item), expr.field.name);
+            return expr.field.kind === "connection"
+                ? nodesFromConnection(value)
+                : value;
+        }
+        default:
+            throw new GqlError(`extractRel: ${expr._tag}`);
+    }
+};
+const inItem = (expr) => {
+    switch (expr._tag) {
+        case "Item":
+            return true;
+        case "Prop":
+        case "MapValue":
+        case "MapItems":
+        case "Filter":
+        case "FlatMap":
+            return inItem(expr.parent);
+        default:
+            return false;
+    }
+};
+const interpretExpr = (expr, data, rootAlias, item) => {
+    switch (expr._tag) {
+        case "Literal":
+            return expr.value;
+        case "Item":
+            return item;
+        case "Root":
+        case "Prop":
+            return inItem(expr)
+                ? extractRel(expr, item)
+                : extractAbs(expr, data, rootAlias);
+        case "MapValue":
+            return expr.mapFn(interpretExpr(expr.parent, data, rootAlias, item));
+        case "Filter": {
+            const list = interpretExpr(expr.parent, data, rootAlias, item);
+            const arr = Array.isArray(list) ? list : [];
+            return arr.filter((row) => Boolean(interpretExpr(expr.predicate, data, rootAlias, row)));
+        }
+        case "MapItems": {
+            const list = interpretExpr(expr.parent, data, rootAlias, item);
+            if (expr.single) {
+                return list == null
+                    ? null
+                    : interpretValueSync(expr.mapped, data, rootAlias, list);
             }
-            : position);
+            const arr = Array.isArray(list) ? list : [];
+            return arr.map((row) => interpretValueSync(expr.mapped, data, rootAlias, row));
+        }
+        case "FlatMap":
+            throw new GqlError("FlatMap must be interpreted as Effect");
     }
-    for (const position of merged.values()) {
-        if (position.conditional)
-            continue;
-        if (position.typename) {
-            if (typeof data[position.key] !== "string" ||
-                (type.kind === "OBJECT" && data[position.key] !== base))
-                return decodeFailure(`Invalid __typename for ${base}`, [
-                    ...path,
-                    position.key,
-                ]);
-            Object.defineProperty(result, position.key, {
-                value: data[position.key],
-                enumerable: true,
-                configurable: true,
-                writable: true,
-            });
+};
+const interpretValueSync = (plan, data, rootAlias, item) => {
+    if (isQuery(plan)) {
+        return interpretExpr(plan.expr, data, rootAlias, item);
+    }
+    if (plan !== null && typeof plan === "object" && !Effect.isEffect(plan)) {
+        const out = {};
+        for (const [key, nested] of Object.entries(plan)) {
+            out[key] = interpretValueSync(nested, data, rootAlias, item);
         }
-        else
-            Object.defineProperty(result, position.key, {
-                value: decodeData(model, position.type, data[position.key], position.children, position.branches, [...path, position.key]),
-                enumerable: true,
-                configurable: true,
-                writable: true,
-            });
+        return out;
     }
-    return result;
+    return plan;
 };
-const classify = (model, compiled, raw, response, classes) => {
-    const path = Array.isArray(raw.path)
-        ? raw.path
-        : undefined;
-    let candidates = compiled.positions;
-    let position;
-    let currentData = object(response.body)
-        ? response.body.data
-        : undefined;
-    let parents = [];
-    const descendants = (positions, value) => positions.flatMap((p) => [
-        ...p.children,
-        ...(object(value) && typeof value.__typename === "string"
-            ? (p.branches[value.__typename] ?? [])
-            : Object.values(p.branches).flat()),
-    ]);
-    let valid = !!path?.length;
-    for (const segment of path ?? []) {
-        if (typeof segment === "number") {
-            currentData = Array.isArray(currentData)
-                ? currentData[segment]
-                : undefined;
-            candidates = descendants(parents, currentData);
-            continue;
+const interpretPlan = (plan, data, rootAlias) => Effect.gen(function* () {
+    if (isQuery(plan)) {
+        const expr = plan.expr;
+        if (expr._tag === "FlatMap") {
+            const resolved = interpretExpr(expr.parent, data, rootAlias, undefined);
+            const next = expr.flatMapFn(resolved);
+            if (Effect.isEffect(next))
+                return yield* next;
+            if (isQuery(next))
+                return yield* interpretPlan(next, data, rootAlias);
+            return next;
         }
-        const matches = candidates.filter((p) => p.key === segment);
-        if (!matches.length) {
-            valid = false;
-            break;
+        return interpretExpr(expr, data, rootAlias, undefined);
+    }
+    if (Effect.isEffect(plan))
+        return yield* plan;
+    if (plan !== null && typeof plan === "object" && !Array.isArray(plan)) {
+        const out = {};
+        for (const [key, nested] of Object.entries(plan)) {
+            out[key] = yield* interpretPlan(nested, data, rootAlias);
         }
-        position = {
-            ...matches[0],
-            errors: [...new Set(matches.flatMap((p) => p.errors))],
-        };
-        currentData = object(currentData) ? currentData[segment] : undefined;
-        parents = matches;
-        candidates = descendants(matches, currentData);
-    }
-    const extensions = object(raw.extensions) ? raw.extensions : {};
+        return out;
+    }
+    return plan;
+});
+/**
+ * Compile every Query in `plan` into one document, POST it, then replace
+ * Query/Effect leaves with plain data (`UnwrapPlan`).
+ */
+const evaluatePlan = (plan) => Effect.gen(function* () {
+    const forest = emptyForest();
+    visitPlan(plan, forest);
+    let data = {};
+    let rootAlias = new WeakMap();
+    if (forest.roots.children.size > 0) {
+        const compiled = emit(forest);
+        log("document\n" + compiled.document);
+        data = yield* execute(compiled);
+        rootAlias = compiled.rootAlias;
+    }
+    return (yield* interpretPlan(plan, data, rootAlias));
+});
+/**
+ * POST one compiled document and fail with its classified errors. Queries
+ * are retried (bounded) while every failure is retryable; mutations never
+ * are, since an error can follow a side effect that already happened.
+ */
+const execute = (compiled) => {
+    const once = Effect.gen(function* () {
+        const transport = yield* GqlTransport;
+        const response = yield* transport.execute(compiled);
+        const raw = response.errors ?? [];
+        if (raw.length === 0)
+            return response.data;
+        const issues = raw.map((error) => classify(compiled, error, response));
+        const [first, ...rest] = issues;
+        return yield* Effect.fail(rest.every((issue) => issue._tag === first._tag)
+            ? first
+            : new GraphQLFailure({
+                errors: [first, ...rest],
+                data: response.data,
+                status: response.status,
+            }));
+    });
+    return compiled.kind === "query"
+        ? once.pipe(Effect.retry({
+            while: (error) => isRetryable(compiled, error),
+            times: 5,
+            schedule: Schedule.exponential("200 millis"),
+        }))
+        : once;
+};
+const isRetryable = (compiled, error) => {
+    if (error instanceof GraphQLTransportError) {
+        return (error.status === undefined || error.status === 429 || error.status >= 500);
+    }
+    const retryable = new Set([...compiled.rootErrors.values()].flatMap((root) => root.errors.filter((spec) => spec.retryable).map((spec) => spec.tag)));
+    return error instanceof GraphQLFailure
+        ? error.errors.every((issue) => retryable.has(issue._tag))
+        : retryable.has(error._tag);
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Pick the most specific matcher among the errors the root at `path[0]`
+ * declares (or the global errors for a path-less error). A tie between
+ * different tags is ambiguous and stays {@link UnknownGraphQLError}.
+ */
+const classify = (compiled, raw, response) => {
+    const path = Array.isArray(raw.path) ? raw.path : undefined;
+    const root = typeof path?.[0] === "string"
+        ? compiled.rootErrors.get(path[0])
+        : undefined;
+    const candidates = root
+        ? root.errors
+        : uniqueByTag([...compiled.rootErrors.values()].flatMap((entry) => entry.errors.filter((spec) => spec.global)));
+    const extensions = isRecord(raw.extensions) ? raw.extensions : {};
     const code = typeof extensions.code === "string"
         ? extensions.code
         : typeof extensions.errorCode === "string"
             ? extensions.errorCode
             : undefined;
-    const retryHeader = response.headers["retry-after"];
-    const retryAfter = retryHeader && /^\d+(\.\d+)?$/.test(retryHeader)
-        ? Number(retryHeader)
-        : undefined;
+    const message = typeof raw.message === "string" ? raw.message : "";
+    const retryHeader = response.headers?.["retry-after"];
     const props = {
-        message: raw.message,
+        message,
         code,
         path,
         locations: raw.locations,
@@ -512,207 +846,210 @@ const classify = (model, compiled, raw, response, classes) => {
                 ? raw.traceId
                 : undefined,
         status: response.status,
-        retryAfter,
+        retryAfter: retryHeader && /^\d+(\.\d+)?$/.test(retryHeader)
+            ? Number(retryHeader)
+            : undefined,
     };
-    const tags = [
-        ...model.globalErrors,
-        ...(valid ? (position?.errors ?? []) : []),
-    ];
-    const matches = tags.flatMap((tag) => (model.errors[tag]?.matchers ?? [])
+    const matches = candidates.flatMap((spec) => spec.matchers
         .filter((matcher) => (matcher.code === undefined || matcher.code === code) &&
-        (matcher.message === undefined || matcher.message === raw.message) &&
+        (matcher.message === undefined || matcher.message === message) &&
         (matcher.messageIncludes === undefined ||
-            raw.message.includes(matcher.messageIncludes)))
+            message.includes(matcher.messageIncludes)))
         .map((matcher) => ({
-        tag,
+        spec,
         score: (matcher.code ? 1 : 0) +
             (matcher.message ? 4 : 0) +
             (matcher.messageIncludes ? 2 : 0),
     })));
     matches.sort((a, b) => b.score - a.score);
     const best = matches[0];
-    const tag = best && !matches.some((m) => m.score === best.score && m.tag !== best.tag)
-        ? best.tag
-        : undefined;
-    if (tag && classes[tag])
-        return new classes[tag](props);
+    if (best &&
+        !matches.some((match) => match.score === best.score && match.spec.tag !== best.spec.tag)) {
+        return best.spec.make(props);
+    }
     return new UnknownGraphQLError({
         ...props,
-        coordinate: valid ? position?.coordinate : undefined,
+        coordinate: root?.field,
     });
 };
-/** Construct an Effect client; credentials and HTTP are resolved by the transport per call. */
-export const makeClient = (model, transport, classes) => {
-    const executeReport = (kind, selection) => Effect.gen(function* () {
-        const compiled = yield* Effect.try({
-            try: () => compile(model, kind, selection),
-            catch: (cause) => cause instanceof GraphQLRequestError
-                ? cause
-                : new GraphQLRequestError({ message: String(cause) }),
-        });
-        const response = yield* transport(compiled);
-        return yield* Effect.try({
-            try: () => {
-                const body = response.body;
-                if (!object(body))
-                    return decodeFailure("GraphQL response must be an object", []);
-                if (body.errors !== undefined &&
-                    (!Array.isArray(body.errors) || !body.errors.length))
-                    return decodeFailure("GraphQL errors must be a nonempty array", []);
-                const rawErrors = body.errors ?? [];
-                for (const error of rawErrors) {
-                    if (!object(error) || typeof error.message !== "string")
-                        return decodeFailure("Invalid GraphQL error", []);
-                    if (error.path !== undefined &&
-                        (!Array.isArray(error.path) ||
-                            error.path.some((p) => typeof p !== "string" &&
-                                (typeof p !== "number" || !Number.isInteger(p) || p < 0))))
-                        return decodeFailure("Invalid GraphQL error path", []);
-                }
-                if (!("data" in body) && !rawErrors.length) {
-                    if (response.status >= 400)
-                        throw new GraphQLTransportError({
-                            message: `HTTP ${response.status} without a GraphQL response`,
-                            status: response.status,
-                        });
-                    return decodeFailure("GraphQL response has neither data nor errors", []);
-                }
-                if (response.status >= 400 && !rawErrors.length)
-                    throw new GraphQLTransportError({
-                        message: `HTTP ${response.status} without GraphQL errors`,
-                        status: response.status,
-                    });
-                const errors = rawErrors.map((raw) => classify(model, compiled, raw, response, classes));
-                let data = body.data;
-                if (data !== undefined && data !== null)
-                    data = decodeData(model, compiled.rootType + "!", data, compiled.positions, {}, []);
-                if ((data === undefined || data === null) && !errors.length)
-                    return decodeFailure("GraphQL success has no data", []);
-                return {
-                    data,
-                    errors,
-                    status: response.status,
-                    extensions: body.extensions,
-                };
-            },
-            catch: (cause) => cause instanceof GraphQLDecodeError ||
-                cause instanceof GraphQLTransportError
-                ? cause
-                : new GraphQLDecodeError({
-                    message: "Invalid GraphQL response",
-                    cause,
-                }),
-        });
+const uniqueByTag = (specs) => [
+    ...new Map(specs.map((spec) => [spec.tag, spec])).values(),
+];
+/** `Query.of` / pure. */
+export const ofQuery = (value) => make({ _tag: "Literal", value, type: { tag: "scalar" } });
+const filterImpl = (source, predicate) => {
+    const proto = itemQuery(source);
+    const predicateQuery = predicate(proto);
+    log("filter pred", printExpr(predicateQuery.expr));
+    return make({
+        _tag: "Filter",
+        parent: source.expr,
+        predicate: predicateQuery.expr,
+        type: source.expr.type,
     });
-    const retryable = (error) => error instanceof GraphQLFailure
-        ? error.errors.every((issue) => model.errors[issue._tag]?.retryable === true)
-        : error instanceof GraphQLTransportError &&
-            (error.status === undefined ||
-                error.status === 429 ||
-                error.status >= 500);
-    const execute = (kind, selection) => {
-        const effect = executeReport(kind, selection).pipe(Effect.flatMap((report) => report.errors.length
-            ? Effect.fail(new GraphQLFailure({
-                errors: report.errors,
-                data: report.data,
-                status: report.status,
-            }))
-            : Effect.succeed(report.data)));
-        return kind === "query"
-            ? effect.pipe(Effect.retry({
-                while: retryable,
-                times: 5,
-                schedule: Schedule.exponential("200 millis"),
-            }))
-            : effect;
-    };
-    const operation = (kind, name) => {
-        const field = model.types[kind === "query" ? model.queryType : model.mutationType]
-            ?.fields?.[name];
-        const call = (args, selection) => execute(kind, {
-            [name]: { where: args, select: selection ?? true },
-        }).pipe(Effect.map((data) => data[name]));
-        const pages = (args, selection) => Stream.unwrap(Effect.try({
-            try: () => {
-                const connection = field && model.types[named(field.type)];
-                if (kind !== "query" ||
-                    !field?.args.after ||
-                    !connection?.fields?.edges ||
-                    !connection.fields.pageInfo)
-                    return Stream.fromEffect(Effect.fail(new GraphQLRequestError({
-                        message: `${name} is not a paginated query connection`,
-                    })));
-                // Cursor fields are internal additions; the caller's projection remains exact.
-                const projection = compile(model, kind, {
-                    [name]: { where: args, select: selection },
-                }).positions[0];
-                let cursorKey = "pageInfo";
-                let complete;
-                if (selection.__alias &&
-                    Object.hasOwn(selection.__alias, "pageInfo")) {
-                    cursorKey = "_distilledPageInfo";
-                    while (Object.hasOwn(selection, cursorKey) ||
-                        Object.hasOwn(selection.__alias, cursorKey))
-                        cursorKey += "_";
-                    complete = {
-                        ...selection,
-                        __alias: {
-                            ...selection.__alias,
-                            [cursorKey]: {
-                                pageInfo: { endCursor: true, hasNextPage: true },
-                            },
-                        },
-                    };
-                }
-                else {
-                    const { $include: _include, $skip: _skip, ...pageFields } = selection.pageInfo?.select ?? selection.pageInfo ?? {};
-                    complete = {
-                        ...selection,
-                        pageInfo: { ...pageFields, endCursor: true, hasNextPage: true },
-                    };
-                }
-                return Stream.paginate({
-                    after: args.after,
-                    seen: new Set(),
-                }, (state) => call({ ...args, after: state.after }, complete).pipe(Effect.flatMap((page) => {
-                    const cursor = page?.[cursorKey]?.endCursor;
-                    const more = page?.[cursorKey]?.hasNextPage;
-                    if (more &&
-                        (typeof cursor !== "string" ||
-                            cursor === state.after ||
-                            state.seen.has(cursor)))
-                        return Effect.fail(new GraphQLDecodeError({
-                            message: `${name} returned a non-advancing pagination cursor`,
-                        }));
-                    const seen = new Set(state.seen);
-                    if (typeof cursor === "string")
-                        seen.add(cursor);
-                    const projected = decodeData(model, field.type, page, projection.children, projection.branches, []);
-                    return Effect.succeed([
-                        [projected],
-                        more
-                            ? Option.some({ after: cursor, seen })
-                            : Option.none(),
-                    ]);
-                })));
-            },
-            catch: (cause) => cause instanceof GraphQLRequestError
-                ? cause
-                : new GraphQLRequestError({ message: String(cause) }),
+};
+export function filterQuery(sourceOrPredicate, predicate) {
+    if (predicate === undefined) {
+        return (source) => filterImpl(source, sourceOrPredicate);
+    }
+    return filterImpl(sourceOrPredicate, predicate);
+}
+const mapImpl = (source, mapFn) => {
+    if (source.expr.type.tag === "object") {
+        const mapped = mapFn(new QueryNode({
+            _tag: "Item",
+            list: source.expr,
+            type: source.expr.type,
         }));
-        return Object.assign(call, {
-            pages,
-            items: (args, select) => pages(args, { edges: { node: select } }).pipe(Stream.flatMap((page) => Stream.fromIterable((page?.edges ?? []).flatMap((edge) => edge === null ? [] : [edge.node])))),
+        log("map object", printExpr(source.expr));
+        return make({
+            _tag: "MapItems",
+            parent: source.expr,
+            mapped,
+            single: true,
+            type: { tag: "scalar" },
         });
-    };
-    return {
-        query: (selection) => execute("query", selection),
-        mutation: (selection) => execute("mutation", selection),
-        report: {
-            query: (selection) => executeReport("query", selection),
-            mutation: (selection) => executeReport("mutation", selection),
-        },
-        operation,
-    };
+    }
+    if (source.expr.type.tag === "list") {
+        const proto = itemQuery(source);
+        const mapped = mapFn(proto);
+        log("map items", printExpr(source.expr));
+        return make({
+            _tag: "MapItems",
+            parent: source.expr,
+            mapped,
+            type: source.expr.type,
+        });
+    }
+    log("map value", printExpr(source.expr));
+    return make({
+        _tag: "MapValue",
+        parent: source.expr,
+        mapFn,
+        type: { tag: "scalar" },
+    });
+};
+export function mapQuery(sourceOrMapFn, mapFn) {
+    if (mapFn === undefined) {
+        return (source) => mapImpl(source, sourceOrMapFn);
+    }
+    return mapImpl(sourceOrMapFn, mapFn);
+}
+const flatMapImpl = (source, flatMapFn) => {
+    log("flatMap", printExpr(source.expr));
+    return make({
+        _tag: "FlatMap",
+        parent: source.expr,
+        flatMapFn,
+        type: { tag: "scalar" },
+    });
+};
+export function flatMapQuery(sourceOrFlatMapFn, flatMapFn) {
+    if (flatMapFn === undefined) {
+        return (source) => flatMapImpl(source, sourceOrFlatMapFn);
+    }
+    return flatMapImpl(sourceOrFlatMapFn, flatMapFn);
+}
+/**
+ * Builder → Effect. The inner function is *not* a generator; it returns a
+ * plan of Query/Effect values. Query.fn visits the plan, POSTs one document,
+ * then interprets Map/Filter/FlatMap/Of.
+ */
+export const queryFn = (build) => (...args) => {
+    const plan = build(...args);
+    return evaluatePlan(plan);
 };
+// ── Pagination ──────────────────────────────────────────────────────────────
+//
+// A connection lens hides `edges`/`pageInfo`. `Query.pages` re-evaluates the
+// query once per page: it sets the connection's `after` argument, paints
+// `pageInfo { hasNextPage endCursor }` next to `edges`, and stops when
+// `hasNextPage` is false.
+/** The connection a paged query reads, below any list-level Map/Filter. */
+const connectionOf = (expr) => {
+    const base = graphqlBase(expr);
+    const isConnection = (base._tag === "Root" && base.connection === true) ||
+        (base._tag === "Prop" && base.field.kind === "connection");
+    if (!isConnection || inItem(base)) {
+        throw new GqlError(`Query.pages needs a Relay connection, got ${printExpr(base)}`);
+    }
+    const argTypes = base._tag === "Root" ? base.argTypes : base.field.argTypes;
+    if (!argTypes || !("after" in argTypes)) {
+        throw new GqlError(`${printExpr(base)} takes no "after" cursor`);
+    }
+    return base;
+};
+/** Rebuild `expr` with the connection's `after` argument set. */
+const withCursor = (expr, connection, after) => {
+    if (expr === connection) {
+        const current = expr;
+        return { ...current, args: { ...current.args, after } };
+    }
+    switch (expr._tag) {
+        case "MapItems":
+        case "Filter":
+        case "MapValue":
+        case "FlatMap":
+            return { ...expr, parent: withCursor(expr.parent, connection, after) };
+        default:
+            throw new GqlError(`withCursor: ${expr._tag}`);
+    }
+};
+const readPath = (data, path) => {
+    let current = data;
+    for (const segment of path) {
+        if (current == null)
+            return undefined;
+        if (Array.isArray(current)) {
+            throw new GqlError("Query.pages cannot page a connection inside a list");
+        }
+        current = current[segment];
+    }
+    return current;
+};
+const fetchPage = (query, connection, state) => Effect.gen(function* () {
+    const pageExpr = withCursor(query.expr, connection, state.after);
+    const forest = emptyForest();
+    visitExpr(forest, pageExpr);
+    const nodePath = paintAbs(forest, withCursor(connection, connection, state.after));
+    const connectionPath = nodePath.slice(0, -2);
+    const pageInfo = ensureChild(forest, selAt(forest.roots, connectionPath), "pageInfo", {});
+    ensureChild(forest, pageInfo, "hasNextPage", { isScalar: true });
+    ensureChild(forest, pageInfo, "endCursor", { isScalar: true });
+    const compiled = emit(forest);
+    log("page\n" + compiled.document);
+    const data = yield* execute(compiled);
+    const items = (yield* interpretPlan(make(pageExpr), data, compiled.rootAlias));
+    const info = readPath(data, [...connectionPath, "pageInfo"]);
+    const cursor = info?.endCursor ?? null;
+    if (info?.hasNextPage !== true) {
+        return [items ?? [], Option.none()];
+    }
+    if (cursor === null || cursor === state.after || state.seen.has(cursor)) {
+        return yield* new GraphQLPaginationError({
+            message: `${printExpr(connection)} returned a non-advancing cursor`,
+            cursor,
+        });
+    }
+    return [
+        items ?? [],
+        Option.some({ after: cursor, seen: new Set([...state.seen, cursor]) }),
+    ];
+});
+/**
+ * Every page of a Relay connection, one request per page. `query` is a
+ * connection lens (root or nested under objects), optionally mapped or
+ * filtered: `Query.pages(Railway.project({ id }).services({ first: 50 }))`.
+ * Starts from the query's own `after` argument, if any.
+ */
+export const pagesQuery = (query) => Stream.unwrap(Effect.sync(() => {
+    const connection = connectionOf(query.expr);
+    const after = connection.args?.after;
+    return Stream.paginate({
+        after: typeof after === "string" ? after : undefined,
+        seen: new Set(),
+    }, (state) => fetchPage(query, connection, state).pipe(Effect.map(([items, next]) => [[items], next])));
+}));
+/** Every node of a Relay connection, across all pages. */
+export const itemsQuery = (query) => pagesQuery(query).pipe(Stream.flatMap(Stream.fromIterable));
 //# sourceMappingURL=graphql.js.map