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

package/src/protocol-http.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
+import * as Redacted from "effect/Redacted";
 import { buildRequest, mapKeys } from "./protocol-http.ts";
+import { SensitiveValue, wrapSensitive } from "./protocol-rest.ts";
 import * as S from "./schema.ts";
 import * as T from "./trait.ts";
 
@@ -17,6 +19,14 @@ const JsonInput = S.Struct({
   flags: S.optional(
     S.Array(S.Boolean).pipe(T.Body("flags"), T.StringEncoded()),
   ),
+  profile: S.optional(
+    S.Struct({
+      nested: S.optional(
+        S.Boolean.pipe(T.Body("nested_flag"), T.StringEncoded()),
+      ),
+      plain: S.optional(S.Boolean.pipe(T.Body("plain_flag"))),
+    }).pipe(T.Body("profile")),
+  ),
 }).pipe(T.Http({ method: "POST", uri: "/things" }));
 
 const jsonBodyOf = (input: unknown): unknown => {
@@ -47,12 +57,165 @@ describe("StringEncoded members", () => {
     });
   });
 
+  test("a member nested in a body struct stringifies too", () => {
+    expect(jsonBodyOf({ profile: { nested: true, plain: true } })).toEqual({
+      profile: { nested_flag: "true", plain_flag: true },
+    });
+  });
+
   test("null stays null and an omitted member stays omitted", () => {
     expect(jsonBodyOf({ nullable: null })).toEqual({ nullable: null });
     expect(jsonBodyOf({})).toEqual({});
   });
 });
 
+describe("URI label encoding", () => {
+  const input = (preserve?: string) =>
+    S.Struct({
+      scope:
+        preserve === undefined
+          ? S.String.pipe(T.Label())
+          : S.String.pipe(T.Label(), T.LabelEncoding({ preserve })),
+    }).pipe(T.Http({ method: "POST", uri: "/runtime/{scope}" }));
+  const url = (scope: string, preserve?: string) =>
+    buildRequest({
+      input: { scope },
+      inputAst: input(preserve).ast,
+      baseUrl: "https://example.test",
+    }).url;
+
+  test("keeps the existing escaping unless a model opts in", () => {
+    expect(url("__KV:abc")).toBe("https://example.test/runtime/__KV%3Aabc");
+    expect(url("__KV:abc", ":")).toBe("https://example.test/runtime/__KV:abc");
+  });
+
+  test("preserves only modeled pchar delimiters, not separators or escapes", () => {
+    expect(url("__KV:a/b?c#d%3Aé", ":")).toBe(
+      "https://example.test/runtime/__KV:a%2Fb%3Fc%23d%253A%C3%A9",
+    );
+    expect(url("$&:@", "$&:")).toBe("https://example.test/runtime/$&:%40");
+  });
+
+  test("refuses unsafe preservation rules", () => {
+    for (const preserve of ["/", "?", "#", "%", "\\r", "[", "]"]) {
+      expect(() => T.LabelEncoding({ preserve })).toThrow(TypeError);
+    }
+  });
+});
+
+describe("multipart binary parts", () => {
+  const schema = S.Struct({ zip: S.Unknown, environment: S.String }).pipe(
+    T.Http({ method: "POST", uri: "/deployments", contentType: "multipart" }),
+  );
+
+  test("preserves typed-array slices and an already JSON-encoded environment", async () => {
+    const input = new Uint8Array([99, 80, 75, 0, 255, 99]).subarray(1, 5);
+    const environment = JSON.stringify({ SECRET: "value", REMOVED: "" });
+    const request = buildRequest({
+      input: { zip: input, environment },
+      inputAst: schema.ast,
+      baseUrl: "https://example.test",
+    });
+    if (request.body._tag !== "FormData") throw new Error("Expected multipart");
+    const part = request.body.formData.get("zip");
+    expect(part).toBeInstanceOf(File);
+    expect(new Uint8Array(await (part as File).arrayBuffer())).toEqual(input);
+    expect(request.body.formData.getAll("environment")).toEqual([environment]);
+    const wire = new Request(request.url, {
+      method: "POST",
+      body: request.body.formData,
+    });
+    expect(wire.headers.get("content-type")).toContain(
+      "multipart/form-data; boundary=",
+    );
+  });
+
+  test("preserves File names and ArrayBuffer bytes", async () => {
+    for (const zip of [
+      new File([new Uint8Array([80, 75, 255])], "bundle.zip"),
+      new Uint8Array([80, 75, 255]).buffer,
+    ]) {
+      const request = buildRequest({
+        input: { zip, environment: "{}" },
+        inputAst: schema.ast,
+        baseUrl: "https://example.test",
+      });
+      if (request.body._tag !== "FormData")
+        throw new Error("Expected multipart");
+      const part = request.body.formData.get("zip") as File;
+      expect(part.name).toBe(zip instanceof File ? "bundle.zip" : "zip");
+      expect(new Uint8Array(await part.arrayBuffer())).toEqual(
+        new Uint8Array([80, 75, 255]),
+      );
+    }
+  });
+});
+
+describe("sensitive union responses", () => {
+  const schema = S.suspend(() =>
+    S.Union([
+      S.Struct({
+        type: S.Literal("standard"),
+        password: S.String.pipe(SensitiveValue()),
+      }),
+      S.Struct({
+        type: S.Literal("token"),
+        token: S.String.pipe(SensitiveValue()),
+      }),
+      S.Struct({ type: S.Literal("shared") }),
+    ]),
+  );
+
+  test("all arms redact their secrets, even in partial or ambiguous responses", () => {
+    for (const value of [
+      { type: "standard", password: "fixture-password" },
+      { type: "token", token: "fixture-token" },
+      { password: "fixture-password", token: "fixture-token" },
+    ]) {
+      const wrapped = wrapSensitive(schema.ast, value);
+      expect(wrapped).toEqual(
+        Object.fromEntries(
+          Object.entries(value).map(([key, value]) => [
+            key,
+            key === "type" ? value : Redacted.make(value),
+          ]),
+        ),
+      );
+      expect(JSON.stringify(wrapped)).not.toContain("fixture-password");
+      expect(JSON.stringify(wrapped)).not.toContain("fixture-token");
+      expect(wrapSensitive(schema.ast, wrapped)).toEqual(wrapped);
+    }
+  });
+
+  test("nested arrays and optional nullable unions preserve nonsecret values", () => {
+    const nested = S.Struct({
+      provider: S.optional(S.NullOr(schema)),
+      providers: S.Array(schema),
+    });
+    for (const value of [
+      {},
+      { provider: null },
+      { provider: { type: "shared" } },
+    ]) {
+      expect(
+        wrapSensitive(nested.ast, {
+          ...value,
+          providers: [
+            { type: "standard", password: "fixture-password" },
+            { type: "shared" },
+          ],
+        }),
+      ).toEqual({
+        ...value,
+        providers: [
+          { type: "standard", password: Redacted.make("fixture-password") },
+          { type: "shared" },
+        ],
+      });
+    }
+  });
+});
+
 describe("UnionCases decoding", () => {
   const cases = [
     ["id", "type", "zoneName"],

package/src/protocol-http.ts

@@ -9,8 +9,8 @@
  * {@link matchTypedError}).
  */
 import type * as AST from "effect/SchemaAST";
-import * as HttpBody from "effect/unstable/http/HttpBody";
-import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpBody from "effect/http/HttpBody";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
 import {
   bodySymbol,
   deepQuerySymbol,
@@ -21,10 +21,12 @@ import {
   httpSymbol,
   keyDictionarySymbol,
   labelSymbol,
+  labelEncodingSymbol,
   querySymbol,
   stringEncodedSymbol,
   unionCasesSymbol,
   type ErrorMatcher,
+  type ErrorTextMatcher,
   type HttpTrait,
   type KeyDictionaryEntries,
   type UnionDiscriminator,
@@ -149,6 +151,18 @@ export const mapKeysByDictionary = (
  * TS-cased content still reaches the wire in wire case. Content with no
  * dictionary in scope passes through verbatim.
  */
+/**
+ * Value form for a `StringEncoded()` member: the string spelling of the
+ * value, element-wise for lists. `null` stays `null` — an API that models a
+ * flag as `"true" | "false"` still means "unset" by null, not `"null"`.
+ */
+const stringEncode = (value: unknown): unknown =>
+  value === null
+    ? null
+    : Array.isArray(value)
+      ? value.map(stringEncode)
+      : String(value);
+
 export const mapKeys = (
   ast: AST.AST,
   value: unknown,
@@ -294,7 +308,13 @@ export const mapKeys = (
       consumed.add(from);
       const v = (value as Record<string, unknown>)[from];
       if (v === undefined) continue;
-      out[to] = mapKeys(p.type, v, direction, dict);
+      // A `StringEncoded()` member nested in a body struct (e.g. Azure's
+      // `hardwareProfile.dynamicMemoryEnabled`) stringifies here — the
+      // top-level pass in `buildRequest` only sees the outermost member.
+      out[to] =
+        direction === "encode" && hasPropAnn(p, stringEncodedSymbol)
+          ? stringEncode(v)
+          : mapKeys(p.type, v, direction, dict);
     }
     for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
       if (consumed.has(k) || v === undefined) continue;
@@ -334,18 +354,6 @@ const BODYLESS = new Set(["GET", "HEAD"]);
  * filter matching nothing — the call "succeeds" with zero results and the
  * bug is invisible to the caller.
  */
-/**
- * Value form for a `StringEncoded()` member: the string spelling of the
- * value, element-wise for lists. `null` stays `null` — an API that models a
- * flag as `"true" | "false"` still means "unset" by null, not `"null"`.
- */
-const stringEncode = (value: unknown): unknown =>
-  value === null
-    ? null
-    : Array.isArray(value)
-      ? value.map(stringEncode)
-      : String(value);
-
 const appendQuery = (
   query: URLSearchParams,
   name: string,
@@ -479,7 +487,18 @@ export const buildRequest = ({
 
     if (hasPropAnn(prop, labelSymbol)) {
       const token = nameOf(prop, labelSymbol);
-      uri = uri.replace(`{${token}}`, encodeURIComponent(String(value)));
+      const preserve = getPropAnn(prop, labelEncodingSymbol);
+      const encoded = encodeURIComponent(String(value));
+      const label =
+        typeof preserve === "string"
+          ? encoded.replace(/%[0-9A-F]{2}/g, (escape) => {
+              const character = String.fromCharCode(
+                Number.parseInt(escape.slice(1), 16),
+              );
+              return preserve.includes(character) ? character : escape;
+            })
+          : encoded;
+      uri = uri.replace(`{${token}}`, () => label);
     } else if (hasPropAnn(prop, headerSymbol)) {
       const hName = nameOf(prop, headerSymbol).toLowerCase();
       const hVal = String(value);
@@ -536,12 +555,7 @@ export const buildRequest = ({
   const qs = query.toString();
   const url = `${baseUrl}${uri}${qs ? `?${qs}` : ""}`;
   if (process.env.DISTILLED_DEBUG_HTTP) {
-    console.error(
-      `[distilled] ${http.method} ${url}` +
-        (Object.keys(body).length
-          ? ` body=${JSON.stringify(body).slice(0, 400)}`
-          : ""),
-    );
+    console.error(`[distilled] -> ${http.method} ${http.uri}`);
   }
 
   let request = HttpClientRequest.make(http.method)(url).pipe(
@@ -552,8 +566,7 @@ export const buildRequest = ({
     // JSON-encoded under their wire name), each file appends under its own
     // filename. A whole-body member (T.HttpBody) that is a record of files
     // becomes one part per entry (e.g. asset upload: { <hash>: File }).
-    // File/Blob → binary part (filename = File.name), array of files → each
-    // appended, object → JSON string, primitive → string.
+    // Files and byte buffers become binary parts; objects become JSON parts.
     const form = new FormData();
     const parts =
       rawBody !== undefined && typeof rawBody === "object"
@@ -565,6 +578,10 @@ export const buildRequest = ({
       if (value === undefined || value === null) continue;
       if (isFileOrBlob(value)) {
         form.append(key, value, value instanceof File ? value.name : key);
+      } else if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+        const bytes =
+          value instanceof Uint8Array ? new Uint8Array(value).buffer : value;
+        form.append(key, new Blob([bytes]), key);
       } else if (
         Array.isArray(value) &&
         value.length > 0 &&
@@ -666,59 +683,116 @@ export const buildRequest = ({
 
 //#region Typed error matching
 
-/**
- * Whether one matcher matches one wire error: every present field must
- * match; a matcher (or a message object) with no constraints matches
- * nothing.
- */
+/** Parsed response metadata supplied by a protocol after it detects a failure. */
+export interface ErrorResponse {
+  readonly body?: unknown;
+  readonly headers?: Readonly<Record<string, string | undefined>>;
+}
+
+const matchesText = (matcher: ErrorTextMatcher, value: unknown): boolean => {
+  if (typeof value !== "string") return false;
+  if (typeof matcher === "string") return matcher === value;
+  const { includes, matches } = matcher;
+  return (
+    (includes !== undefined || matches !== undefined) &&
+    (includes === undefined || value.includes(includes)) &&
+    (matches === undefined || new RegExp(matches).test(value))
+  );
+};
+
+// Own properties only: inherited properties are not JSON response members.
+const atPointer = (body: unknown, pointer: string): unknown => {
+  if (pointer === "") return body;
+  if (!pointer.startsWith("/") || /~(?![01])/u.test(pointer)) return undefined;
+  let value = body;
+  for (const segment of pointer.slice(1).split("/")) {
+    const key = segment.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (
+      value === null ||
+      typeof value !== "object" ||
+      !Object.hasOwn(value, key) ||
+      (Array.isArray(value) && !/^(0|[1-9][0-9]*)$/.test(key))
+    )
+      return undefined;
+    value = (value as Record<string, unknown>)[key];
+  }
+  return value;
+};
+
+const matcherSpecificity = (m: ErrorMatcher): number =>
+  (m.code !== undefined ? 1 : 0) +
+  (m.status !== undefined ? 1 : 0) +
+  (m.message !== undefined ? 1 : 0) +
+  (m.body === undefined ? 0 : Object.keys(m.body).length) +
+  (m.headers === undefined ? 0 : Object.keys(m.headers).length);
+
+/** Every supplied constraint must match; an unconstrained matcher matches nothing. */
 export const matchesExpression = (
   m: ErrorMatcher,
   code: number | undefined,
   status: number,
   message: string,
+  response: ErrorResponse = {},
 ): boolean => {
-  if (m.code === undefined && m.status === undefined && m.message === undefined)
+  if (
+    m.code === undefined &&
+    m.status === undefined &&
+    m.message === undefined &&
+    matcherSpecificity(m) === 0
+  )
     return false;
   if (m.code !== undefined && m.code !== code) return false;
   if (m.status !== undefined && m.status !== status) return false;
-  if (m.message !== undefined) {
-    if (typeof m.message === "string") {
-      if (m.message !== message) return false;
-    } else {
-      const { includes, matches } = m.message;
-      if (includes === undefined && matches === undefined) return false;
-      if (includes !== undefined && !message.includes(includes)) return false;
-      if (matches !== undefined && !new RegExp(matches).test(message))
-        return false;
+  if (m.message !== undefined && !matchesText(m.message, message)) return false;
+  if (m.body !== undefined) {
+    for (const [pointer, expected] of Object.entries(m.body)) {
+      const actual = atPointer(response.body, pointer);
+      if (
+        typeof expected === "string" ||
+        (expected !== null && typeof expected === "object")
+      ) {
+        if (!matchesText(expected, actual)) return false;
+      } else if (actual !== expected) return false;
+    }
+  }
+  if (m.headers !== undefined) {
+    for (const [name, expected] of Object.entries(m.headers)) {
+      if (response.headers === undefined) return false;
+      const actual = Object.entries(response.headers).find(
+        ([key]) => key.toLowerCase() === name.toLowerCase(),
+      )?.[1];
+      if (!matchesText(expected, actual)) return false;
     }
   }
   return true;
 };
 
-const matcherSpecificity = (m: ErrorMatcher): number =>
-  (m.code !== undefined ? 1 : 0) +
-  (m.status !== undefined ? 1 : 0) +
-  (m.message !== undefined ? 1 : 0);
-
 /**
  * Pick the operation's typed error class for a failed response: among all
  * declared classes whose matchers (see `applyErrorMatchers`) match the wire
  * failure, the most specific matcher wins (ties break by declaration order).
+ * Empty error lists use an HTTP-status message so body/header-only failures can
+ * still match. The constructor receives the raw body and headers as well as
+ * code/message; error schemas can declare these fields to expose them to callers.
  */
 export const matchTypedError = (
   errorClasses: ReadonlyArray<unknown>,
   status: number,
   errors: ReadonlyArray<{ code?: number; message: string }>,
+  response: ErrorResponse = {},
 ): unknown | undefined => {
   let best:
     | { cls: unknown; specificity: number; code?: number; message: string }
     | undefined;
+  const wireErrors =
+    errors.length > 0 ? errors : [{ message: `HTTP ${status}` }];
   for (const cls of errorClasses) {
     const matchers = getErrorMatchers(cls);
     if (!matchers) continue;
     for (const m of matchers) {
-      for (const e of errors) {
-        if (!matchesExpression(m, e.code, status, e.message)) continue;
+      for (const e of wireErrors) {
+        if (!matchesExpression(m, e.code, status, e.message, response))
+          continue;
         const specificity = matcherSpecificity(m);
         if (!best || specificity > best.specificity) {
           best = { cls, specificity, code: e.code, message: e.message };
@@ -730,6 +804,8 @@ export const matchTypedError = (
   return new (best.cls as new (args: any) => unknown)({
     code: best.code ?? 0,
     message: best.message,
+    body: response.body,
+    headers: response.headers,
   });
 };
 //#endregion

package/src/protocol-rest.ts

@@ -12,7 +12,9 @@
  *             values first)
  *
  *   response: 2xx JSON → optional `transformResponse` → recursive wire→TS
- *             key mapping (`mapKeys`) → `Redacted` wrapping of members
+ *             key mapping (`mapKeys`) → in strict mode, a schema check
+ *             failing with the provider's `parseError` (see
+ *             `core/response-validation`) → `Redacted` wrapping of members
  *             marked with {@link SensitiveValue}; non-2xx → typed error:
  *             per-op matcher classes (`matchTypedError`), then the status
  *             map (default `HTTP_STATUS_MAP`), then an `InternalServerError`
@@ -27,8 +29,8 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Redacted from "effect/Redacted";
 import type * as AST from "effect/SchemaAST";
-import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
-import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import type * as HttpClientRequest from "effect/http/HttpClientRequest";
+import type * as HttpClientResponse from "effect/http/HttpClientResponse";
 import * as API from "./api.ts";
 import { httpSymbol, makeAnnotation, type HttpTrait } from "./trait.ts";
 import {
@@ -43,6 +45,7 @@ import {
 } from "./protocol-http.ts";
 import { HTTP_STATUS_MAP, InternalServerError } from "./errors.ts";
 import { parseRetryAfterForStatus } from "./retry-after.ts";
+import { validateResponse } from "./response-validation.ts";
 
 // =============================================================================
 // Traits
@@ -83,6 +86,13 @@ export const rawResponseRootSymbol = Symbol.for(
 export const RawResponseRoot = () =>
   makeAnnotation(rawResponseRootSymbol, true);
 
+export const binaryResponseSymbol = Symbol.for(
+  "@distilled.cloud/core/binary-response",
+);
+
+/** Decode a successful raw binary response as bytes, without text conversion. */
+export const BinaryResponse = () => makeAnnotation(binaryResponseSymbol, true);
+
 // =============================================================================
 // Value helpers
 // =============================================================================
@@ -125,6 +135,13 @@ export const wrapSensitive = (ast: AST.AST, value: unknown): unknown => {
     return value;
   }
   const node = resolveNode(ast);
+  if (node._tag === "Union") {
+    // Redact every possible sensitive member, including in partial responses.
+    return node.types.reduce<unknown>(
+      (redacted, arm) => wrapSensitive(arm, redacted),
+      value,
+    );
+  }
   if (node._tag === "Arrays") {
     if (!Array.isArray(value)) return value;
     const elem = (node as any).rest?.[0] as AST.AST | undefined;
@@ -169,6 +186,12 @@ export interface RestErrorInfo {
   readonly headers: Record<string, string | undefined>;
 }
 
+/** A 2xx body that failed strict validation, for the `parseError` option. */
+export interface RestParseErrorInfo {
+  readonly body: unknown;
+  readonly cause: unknown;
+}
+
 export interface RestErrorEnvelope {
   readonly code?: string | number;
   readonly message?: string;
@@ -215,6 +238,13 @@ export interface RestProtocolOptions<C> {
   readonly statusMap?: Readonly<Record<number, new (args: any) => any>>;
   /** Fallback error for failures nothing else matched. */
   readonly unknownError: (info: RestErrorInfo) => unknown;
+  /**
+   * The SDK's `<Sdk>ParseError`, raised when a 2xx body does not match the
+   * operation's output schema in strict mode (see
+   * `core/response-validation`). `body` is the parsed JSON, or the raw text
+   * when the body wasn't JSON; `cause` is the schema error.
+   */
+  readonly parseError: (info: RestParseErrorInfo) => unknown;
   /** Transform the parsed 2xx JSON before decoding (e.g. stripNulls). */
   readonly transformResponse?: (body: unknown) => unknown;
   /** Passed through to `buildRequest` (member-header transforms). */
@@ -301,12 +331,18 @@ export const makeRestProtocol = <C>(
     readonly errors: ReadonlyArray<unknown>;
   }) =>
     Effect.gen(function* () {
+      if (
+        response.status >= 200 &&
+        response.status < 300 &&
+        getAnn(outputAst, binaryResponseSymbol) !== undefined
+      ) {
+        const bytes = yield* response.arrayBuffer.pipe(Effect.orDie);
+        return new Uint8Array(bytes);
+      }
       // Read as text and parse tolerantly — error pages are often non-JSON.
       const text = (yield* response.text.pipe(Effect.orDie)) ?? "";
       if (process.env.DISTILLED_DEBUG_HTTP) {
-        console.error(
-          `[distilled] <- ${response.status} ${text.slice(0, 400)}`,
-        );
+        console.error(`[distilled] <- ${response.status}`);
       }
       let json: unknown;
       let nonJson = false;
@@ -327,12 +363,17 @@ export const makeRestProtocol = <C>(
           (nonJson && text.trim() ? text.trim() : `HTTP ${status}`);
 
         // 1. Per-operation typed error (matcher metadata on the class).
-        const typed = matchTypedError(errorClasses, status, [
-          {
-            code: typeof env.code === "number" ? env.code : undefined,
-            message,
-          },
-        ]);
+        const typed = matchTypedError(
+          errorClasses,
+          status,
+          [
+            {
+              code: typeof env.code === "number" ? env.code : undefined,
+              message,
+            },
+          ],
+          { body: nonJson ? text : json, headers },
+        );
         if (typed !== undefined) return yield* fail(typed);
 
         // 2. Status-mapped class (retryAfter only stamps on retryable
@@ -373,9 +414,17 @@ export const makeRestProtocol = <C>(
       // 2xx: the response body IS the payload (no envelope). Wire→TS key
       // mapping is schema-driven; `RawResponseRoot` responses are the body
       // verbatim (mapKeys handles arrays/scalars structurally either way).
+      // Strict mode (core/response-validation) checks the mapped body against
+      // the output schema — a non-JSON body reaches it as a string and fails
+      // there unless the operation's output is itself a string.
       let body: unknown = nonJson ? text : (json ?? {});
       if (options.transformResponse) body = options.transformResponse(body);
-      return wrapSensitive(outputAst, mapKeys(outputAst, body, "decode"));
+      const mapped = yield* validateResponse(
+        outputAst,
+        mapKeys(outputAst, body, "decode"),
+        (cause) => options.parseError({ body: nonJson ? text : json, cause }),
+      ).pipe(Effect.catch(fail));
+      return wrapSensitive(outputAst, mapped);
     });
 
   return Layer.succeed(

package/src/query.ts

@@ -0,0 +1,39 @@
+/**
+ * Query combinators for GraphQL SDKs.
+ *
+ * Import this module next to a generated client:
+ *
+ *   import { Query } from "@distilled.cloud/core/query"
+ *   import { Railway } from "@distilled.cloud/railway"
+ *
+ * `Query.fn` takes a **builder** (plain function, not `Effect.gen`) that
+ * returns a plan of `Query<Value>` and `Effect` values. It walks Map /
+ * Filter / FlatMap / Of, posts one GraphQL document, then interprets the
+ * plan. Roots (`Railway.me`) come from the generated SDK; they are not
+ * combinators.
+ *
+ * @see {@link file://./graphql.ts} for the algebra, compiler, and transport.
+ */
+import {
+  filterQuery,
+  flatMapQuery,
+  itemsQuery,
+  mapQuery,
+  ofQuery,
+  pagesQuery,
+  queryFn,
+  type Query as QueryType,
+} from "./graphql.ts";
+
+export type Query<Value, Error = never> = QueryType<Value, Error>;
+export type { PlanError, QueryError, UnwrapPlan } from "./graphql.ts";
+
+export const Query = {
+  fn: queryFn,
+  filter: filterQuery,
+  map: mapQuery,
+  flatMap: flatMapQuery,
+  of: ofQuery,
+  pages: pagesQuery,
+  items: itemsQuery,
+};