@lifi/composer-sdk 0.6.0 → 0.6.2

package/dist/reachability.js

@@ -0,0 +1,99 @@
+const DEFAULT_MAX_HOPS = 2;
+const tokenKey = (token) => `${token.chainId}:${token.address.toLowerCase()}`;
+const isSync = (edge) => edge.availability === void 0;
+const isProxyHeld = (edge) => isSync(edge) && edge.recipient !== "required";
+const visitEdge = ({
+  edge,
+  from,
+  depth,
+  sourceKey,
+  isTerminal,
+  found,
+  expanded
+}) => {
+  const key = tokenKey(edge.out);
+  if (key === sourceKey) return void 0;
+  if (isTerminal(edge) && !found.has(key)) {
+    found.set(key, { in: from, out: edge.out, hops: depth });
+  }
+  if (!isProxyHeld(edge) || expanded.has(key)) return void 0;
+  expanded.add(key);
+  return edge.out;
+};
+const closureFrom = ({
+  byIn,
+  from,
+  maxHops,
+  isTerminal
+}) => {
+  const sourceKey = tokenKey(from);
+  const found = /* @__PURE__ */ new Map();
+  const expanded = /* @__PURE__ */ new Set([sourceKey]);
+  let frontier = [from];
+  for (let depth = 1; depth <= maxHops && frontier.length > 0; depth++) {
+    const next = [];
+    for (const node of frontier) {
+      for (const edge of byIn.get(tokenKey(node)) ?? []) {
+        const out = visitEdge({
+          edge,
+          from,
+          depth,
+          sourceKey,
+          isTerminal,
+          found,
+          expanded
+        });
+        if (out) next.push(out);
+      }
+    }
+    frontier = next;
+  }
+  return found;
+};
+const indexByIn = (packs) => {
+  const byIn = /* @__PURE__ */ new Map();
+  for (const pack of packs) {
+    for (const edge of pack.edges) {
+      const key = tokenKey(edge.in);
+      const list = byIn.get(key);
+      if (list) list.push(edge);
+      else byIn.set(key, [edge]);
+    }
+  }
+  return byIn;
+};
+const buildReachability = (packs, options = {}) => {
+  const maxHops = options.maxHops ?? DEFAULT_MAX_HOPS;
+  const allowAsync = options.allowAsyncRoutes ?? false;
+  const isTerminal = (edge) => isSync(edge) || allowAsync && edge.availability === "future";
+  const byIn = indexByIn(packs);
+  const memo = /* @__PURE__ */ new Map();
+  const closure = (from) => {
+    const key = tokenKey(from);
+    const cached = memo.get(key);
+    if (cached) return cached;
+    const computed = closureFrom({ byIn, from, maxHops, isTerminal });
+    memo.set(key, computed);
+    return computed;
+  };
+  return {
+    maxHops,
+    canRoute: (from, to) => closure(from).has(tokenKey(to)),
+    routableFrom: (from) => [...closure(from).values()],
+    pairs: () => {
+      const sources = /* @__PURE__ */ new Map();
+      for (const pack of packs) {
+        for (const edge of pack.edges) sources.set(tokenKey(edge.in), edge.in);
+      }
+      const all = [];
+      for (const source of sources.values()) {
+        all.push(...closure(source).values());
+      }
+      return all;
+    }
+  };
+};
+export {
+  buildReachability
+};
+//# sourceMappingURL=reachability.js.map

package/dist/reachability.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/reachability.ts"],"sourcesContent":["/**\n * Client-side reachability over the zap-pack catalog.\n *\n * `GET /compose/zap-packs` lists single routing edges. `POST /compose/route`\n * chains up to the server's hop budget of them, so the set of routable pairs\n * is the closure of the catalog, not the catalog itself. This module computes\n * that closure locally with the planner's admissibility rule, so an integrator\n * can offer every pair `route` connects without a request per pair.\n *\n * The rule, mirrored from the server's route search:\n *\n * - every edge except the last must leave its output in the proxy for the\n *   next edge to consume: no `availability`, no `recipient: 'required'`\n * - the last edge must be synchronous, or `availability: 'future'` when the\n *   caller opts into `allowAsyncRoutes`\n * - a route never visits the same token twice\n *\n * Amount bounds (`inAmountMin` / `inAmountMax`) on an intermediate edge\n * cannot be checked without an amount, so a pair reported here is routable\n * structurally, exactly as a listed edge is. Routes that open with a\n * `lifi.swap` are not enumerable and are not reported. The server also\n * drops blacklisted tokens as intermediates, which is server-side config\n * this module cannot see, so a reported pair may still answer\n * `no_route_error`.\n */\n\nimport type { ZapPackEdge, ZapPackOverview } from './discovery.js';\n\n/** A token identified by address and chain. */\nexport interface TokenRef {\n  readonly address: string;\n  readonly chainId: number;\n}\n\n/** A from/to pair `POST /compose/route` can connect through the catalog. */\nexport interface RoutablePair {\n  readonly in: TokenRef;\n  readonly out: TokenRef;\n  /** Catalog edges on the shortest admissible route; `1` is a listed edge. */\n  readonly hops: number;\n}\n\nexport interface ReachabilityOptions {\n  /**\n   * Hop budget. The server's `no_route_error` reports its effective value in\n   * `details.maxHops`; the deployment default is 2.\n   */\n  readonly maxHops?: number;\n  /**\n   * Admit a route whose last edge has `availability: 'future'`. Mirrors the\n   * `allowAsyncRoutes` request option; such a pair is a `no_route_error`\n   * without it.\n   */\n  readonly allowAsyncRoutes?: boolean;\n}\n\nexport interface Reachability {\n  readonly maxHops: number;\n  /** Whether `route` can connect `from` to `to` through the catalog. */\n  readonly canRoute: (from: TokenRef, to: TokenRef) => boolean;\n  /** Every pair starting at `from`, shortest routes first. */\n  readonly routableFrom: (from: TokenRef) => readonly RoutablePair[];\n  /** Every routable pair in the catalog. */\n  readonly pairs: () => readonly RoutablePair[];\n}\n\nconst DEFAULT_MAX_HOPS = 2;\n\nconst tokenKey = (token: TokenRef): string =>\n  `${token.chainId}:${token.address.toLowerCase()}`;\n\nconst isSync = (edge: ZapPackEdge): boolean => edge.availability === undefined;\n\n// The output stays in the proxy, so a following edge can consume it.\nconst isProxyHeld = (edge: ZapPackEdge): boolean =>\n  isSync(edge) && edge.recipient !== 'required';\n\n// One edge out of a frontier token. Records the pair it completes, and returns\n// its output when a further hop may consume it (proxy-held) and no shorter\n// path already expanded that token.\nconst visitEdge = ({\n  edge,\n  from,\n  depth,\n  sourceKey,\n  isTerminal,\n  found,\n  expanded,\n}: {\n  readonly edge: ZapPackEdge;\n  readonly from: TokenRef;\n  readonly depth: number;\n  readonly sourceKey: string;\n  readonly isTerminal: (edge: ZapPackEdge) => boolean;\n  readonly found: Map<string, RoutablePair>;\n  readonly expanded: Set<string>;\n}): TokenRef | undefined => {\n  const key = tokenKey(edge.out);\n  if (key === sourceKey) return undefined;\n  if (isTerminal(edge) && !found.has(key)) {\n    found.set(key, { in: from, out: edge.out, hops: depth });\n  }\n  if (!isProxyHeld(edge) || expanded.has(key)) return undefined;\n  expanded.add(key);\n  return edge.out;\n};\n\n// Every pair reachable from one token within `maxHops`, breadth-first so the\n// recorded hop count is the shortest one.\nconst closureFrom = ({\n  byIn,\n  from,\n  maxHops,\n  isTerminal,\n}: {\n  readonly byIn: ReadonlyMap<string, readonly ZapPackEdge[]>;\n  readonly from: TokenRef;\n  readonly maxHops: number;\n  readonly isTerminal: (edge: ZapPackEdge) => boolean;\n}): Map<string, RoutablePair> => {\n  const sourceKey = tokenKey(from);\n  const found = new Map<string, RoutablePair>();\n  const expanded = new Set<string>([sourceKey]);\n  let frontier: readonly TokenRef[] = [from];\n  for (let depth = 1; depth <= maxHops && frontier.length > 0; depth++) {\n    const next: TokenRef[] = [];\n    for (const node of frontier) {\n      for (const edge of byIn.get(tokenKey(node)) ?? []) {\n        const out = visitEdge({\n          edge,\n          from,\n          depth,\n          sourceKey,\n          isTerminal,\n          found,\n          expanded,\n        });\n        if (out) next.push(out);\n      }\n    }\n    frontier = next;\n  }\n  return found;\n};\n\nconst indexByIn = (\n  packs: readonly ZapPackOverview[],\n): Map<string, ZapPackEdge[]> => {\n  const byIn = new Map<string, ZapPackEdge[]>();\n  for (const pack of packs) {\n    for (const edge of pack.edges) {\n      const key = tokenKey(edge.in);\n      const list = byIn.get(key);\n      if (list) list.push(edge);\n      else byIn.set(key, [edge]);\n    }\n  }\n  return byIn;\n};\n\n/**\n * Builds a reachability index over the packs returned by\n * {@link ComposeClient.getZapPacks}. Per-source closures are computed on\n * first use and memoised, so `canRoute` on a handful of pairs stays cheap\n * while `pairs()` enumerates everything.\n */\nexport const buildReachability = (\n  packs: readonly ZapPackOverview[],\n  options: ReachabilityOptions = {},\n): Reachability => {\n  const maxHops = options.maxHops ?? DEFAULT_MAX_HOPS;\n  const allowAsync = options.allowAsyncRoutes ?? false;\n  const isTerminal = (edge: ZapPackEdge): boolean =>\n    isSync(edge) || (allowAsync && edge.availability === 'future');\n\n  const byIn = indexByIn(packs);\n  const memo = new Map<string, Map<string, RoutablePair>>();\n  const closure = (from: TokenRef): Map<string, RoutablePair> => {\n    const key = tokenKey(from);\n    const cached = memo.get(key);\n    if (cached) return cached;\n    const computed = closureFrom({ byIn, from, maxHops, isTerminal });\n    memo.set(key, computed);\n    return computed;\n  };\n\n  return {\n    maxHops,\n    canRoute: (from, to) => closure(from).has(tokenKey(to)),\n    routableFrom: (from) => [...closure(from).values()],\n    pairs: () => {\n      const sources = new Map<string, TokenRef>();\n      for (const pack of packs) {\n        for (const edge of pack.edges) sources.set(tokenKey(edge.in), edge.in);\n      }\n      const all: RoutablePair[] = [];\n      for (const source of sources.values()) {\n        all.push(...closure(source).values());\n      }\n      return all;\n    },\n  };\n};\n"],"mappings":"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","names":[]}

package/dist/responseSchemas.cjs

@@ -94,13 +94,17 @@ const failedPreparedOpSchema = import_zod.default.object({
   op: import_zod.default.string(),
   kind: import_zod.default.string(),
   message: import_zod.default.string(),
-  path: import_zod.default.string().optional()
+  path: import_zod.default.string().optional(),
+  port: import_zod.default.string().optional(),
+  fix: import_zod.default.string().optional()
 });
 const serverErrorBodySchema = import_zod.default.object({
   error: import_zod.default.object({
     kind: import_zod.default.string().optional(),
     message: import_zod.default.string().optional(),
     path: import_zod.default.string().optional(),
+    port: import_zod.default.string().optional(),
+    fix: import_zod.default.string().optional(),
     sdkVersion: import_zod.default.string().optional(),
     serverVersion: import_zod.default.string().optional(),
     minimumSdkVersion: import_zod.default.string().optional(),

package/dist/responseSchemas.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/responseSchemas.ts"],"sourcesContent":["import type { SimulateResult, SimulationRevert } from '@lifi/compose-spec';\nimport z from 'zod';\n\n/**\n * Zod-backed parsers for Compose API response bodies.\n *\n * Server responses are untrusted input crossing into the SDK, so the shapes the\n * client reads back are validated here rather than asserted with `as` casts. The\n * schemas are module-private (the package builds with `--isolatedDeclarations`,\n * which forbids exporting un-annotated complex values); the public surface is\n * the typed `parse*` helpers, whose explicit return types double as the contract.\n *\n * The simulate union is the one response the SDK fully owns and parses itself\n * (it is un-enveloped, unlike `/compose`), so it gets a complete schema kept in\n * lockstep with the canonical `SimulateResult` in `@lifi/compose-spec` by the\n * compile-time assertion below — the same anchoring `@lifi/api-schemas` uses for\n * its server-side simulate schema, so the two cannot silently drift.\n */\n\nconst balanceEntrySchema = z.object({\n  token: z.string(),\n  owner: z.string(),\n  amount: z.string(),\n});\n\nconst simulateOkSchema = z.object({\n  status: z.literal('ok'),\n  block: z.number(),\n  timestamp: z.number(),\n  balancesBefore: z.array(balanceEntrySchema),\n  balancesAfter: z.array(balanceEntrySchema),\n  deltas: z.array(balanceEntrySchema),\n  gasUsed: z.string(),\n});\n\nconst simulateRevertDecodeResultSchema = z.object({\n  errorCandidates: z\n    .array(\n      z.object({\n        decodedErrorSignature: z.string(),\n        decodedParams: z.array(z.string()),\n      }),\n    )\n    .optional(),\n  error: z.string().optional(),\n});\n\nconst simulateRevertSchema = z.object({\n  status: z.literal('revert'),\n  block: z.number(),\n  timestamp: z.number(),\n  revertReason: z.string().optional(),\n  code: z.number().optional(),\n  rawErrorBytes: z.string().optional(),\n  decodeResult: simulateRevertDecodeResultSchema.optional(),\n});\n\nconst simulateSetupErrorSchema = z.object({\n  status: z.literal('error'),\n  message: z.string(),\n});\n\nconst simulateResultSchema = z.discriminatedUnion('status', [\n  simulateOkSchema,\n  simulateRevertSchema,\n  simulateSetupErrorSchema,\n]);\n\n// The type the schema actually parses out. Kept private (referencing it from an\n// exported declaration would break `--isolatedDeclarations`) and pinned to the\n// canonical `SimulateResult` inside `parseSimulateResult` below.\ntype SimulateResultWire = z.infer<typeof simulateResultSchema>;\n\n/**\n * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`\n * when the body does not match the `ok`/`revert`/`error` union, letting the\n * caller raise a transport-level error.\n */\nexport const parseSimulateResult = (body: unknown): SimulateResult | null => {\n  const parsed = simulateResultSchema.safeParse(body);\n  if (!parsed.success) return null;\n  // Pin the schema to the canonical contract in both directions, so it cannot\n  // silently drift (mirroring the conformance assertion `@lifi/api-schemas` runs\n  // on its server-side simulate schema). Assigning the inferred wire value to a\n  // `SimulateResult` checks wire→spec; `satisfies SimulateResultWire` checks\n  // spec→wire. A missing or mistyped field on either side fails to compile.\n  const result: SimulateResult = parsed.data;\n  return result satisfies SimulateResultWire;\n};\n\n/**\n * The validated members of an HTTP 206 partial compile envelope. `data` is\n * verified to be an object at runtime but left `unknown` here — compose-spec\n * owns its full shape (`ComposeCompilePartialData`) as a hand-authored type, so\n * the caller narrows it in one step. `error` is fully validated.\n */\nexport interface CompilePartialEnvelope {\n  readonly data: unknown;\n  readonly error: { readonly kind: string; readonly message: string };\n}\n\nconst compilePartialEnvelopeSchema = z.object({\n  data: z.record(z.string(), z.unknown()),\n  error: z.object({ kind: z.string(), message: z.string() }),\n});\n\n/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */\nexport const parseCompilePartialEnvelope = (\n  body: unknown,\n): CompilePartialEnvelope | null => {\n  const parsed = compilePartialEnvelopeSchema.safeParse(body);\n  return parsed.success ? parsed.data : null;\n};\n\n/**\n * A single prepared-op failure inside a `preparation_error` envelope. `kind` is\n * kept as `string` here — the narrowing to `GenericComposeErrorKind` happens in\n * `errorFromHttpResponse`, where the value is lifted onto `ComposeError`.\n */\nexport interface ServerFailedPreparedOp {\n  readonly callId: string;\n  readonly op: string;\n  readonly kind: string;\n  readonly message: string;\n  readonly path?: string;\n}\n\n/** Error envelope returned on non-2xx responses. */\nexport interface ServerErrorBody {\n  readonly error?: {\n    readonly kind?: string;\n    readonly message?: string;\n    readonly path?: string;\n    readonly sdkVersion?: string;\n    readonly serverVersion?: string;\n    readonly minimumSdkVersion?: string;\n    readonly details?: SimulationRevert;\n    readonly failedOps?: readonly ServerFailedPreparedOp[];\n    readonly succeededOps?: readonly string[];\n  };\n}\n\nconst failedPreparedOpSchema = z.object({\n  callId: z.string(),\n  op: z.string(),\n  kind: z.string(),\n  message: z.string(),\n  path: z.string().optional(),\n});\n\n// `details` is passed through (`z.custom`) rather than parsed: the SDK does not\n// own the `SimulationRevert` schema and forwards the field verbatim onto\n// `ComposeError`.\n//\n// `failedOps`/`succeededOps` are optional here because every error kind shares\n// this envelope; they are only populated for `preparation_error` (422). Zod\n// strips undeclared keys, so omitting them would silently drop them.\nconst serverErrorBodySchema = z.object({\n  error: z\n    .object({\n      kind: z.string().optional(),\n      message: z.string().optional(),\n      path: z.string().optional(),\n      sdkVersion: z.string().optional(),\n      serverVersion: z.string().optional(),\n      minimumSdkVersion: z.string().optional(),\n      details: z.custom<SimulationRevert>().optional(),\n      failedOps: z.array(failedPreparedOpSchema).readonly().optional(),\n      succeededOps: z.array(z.string()).readonly().optional(),\n    })\n    .optional(),\n});\n\n/** Validates an already-parsed error envelope; `null` when it does not match. */\nexport const parseServerErrorBody = (json: unknown): ServerErrorBody | null => {\n  const parsed = serverErrorBodySchema.safeParse(json);\n  return parsed.success ? parsed.data : null;\n};\n"],"mappings":"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","names":["z"]}
+{"version":3,"sources":["../src/responseSchemas.ts"],"sourcesContent":["import type { SimulateResult, SimulationRevert } from '@lifi/compose-spec';\nimport z from 'zod';\n\n/**\n * Zod-backed parsers for Compose API response bodies.\n *\n * Server responses are untrusted input crossing into the SDK, so the shapes the\n * client reads back are validated here rather than asserted with `as` casts. The\n * schemas are module-private (the package builds with `--isolatedDeclarations`,\n * which forbids exporting un-annotated complex values); the public surface is\n * the typed `parse*` helpers, whose explicit return types double as the contract.\n *\n * The simulate union is the one response the SDK fully owns and parses itself\n * (it is un-enveloped, unlike `/compose`), so it gets a complete schema kept in\n * lockstep with the canonical `SimulateResult` in `@lifi/compose-spec` by the\n * compile-time assertion below — the same anchoring `@lifi/api-schemas` uses for\n * its server-side simulate schema, so the two cannot silently drift.\n */\n\nconst balanceEntrySchema = z.object({\n  token: z.string(),\n  owner: z.string(),\n  amount: z.string(),\n});\n\nconst simulateOkSchema = z.object({\n  status: z.literal('ok'),\n  block: z.number(),\n  timestamp: z.number(),\n  balancesBefore: z.array(balanceEntrySchema),\n  balancesAfter: z.array(balanceEntrySchema),\n  deltas: z.array(balanceEntrySchema),\n  gasUsed: z.string(),\n});\n\nconst simulateRevertDecodeResultSchema = z.object({\n  errorCandidates: z\n    .array(\n      z.object({\n        decodedErrorSignature: z.string(),\n        decodedParams: z.array(z.string()),\n      }),\n    )\n    .optional(),\n  error: z.string().optional(),\n});\n\nconst simulateRevertSchema = z.object({\n  status: z.literal('revert'),\n  block: z.number(),\n  timestamp: z.number(),\n  revertReason: z.string().optional(),\n  code: z.number().optional(),\n  rawErrorBytes: z.string().optional(),\n  decodeResult: simulateRevertDecodeResultSchema.optional(),\n});\n\nconst simulateSetupErrorSchema = z.object({\n  status: z.literal('error'),\n  message: z.string(),\n});\n\nconst simulateResultSchema = z.discriminatedUnion('status', [\n  simulateOkSchema,\n  simulateRevertSchema,\n  simulateSetupErrorSchema,\n]);\n\n// The type the schema actually parses out. Kept private (referencing it from an\n// exported declaration would break `--isolatedDeclarations`) and pinned to the\n// canonical `SimulateResult` inside `parseSimulateResult` below.\ntype SimulateResultWire = z.infer<typeof simulateResultSchema>;\n\n/**\n * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`\n * when the body does not match the `ok`/`revert`/`error` union, letting the\n * caller raise a transport-level error.\n */\nexport const parseSimulateResult = (body: unknown): SimulateResult | null => {\n  const parsed = simulateResultSchema.safeParse(body);\n  if (!parsed.success) return null;\n  // Pin the schema to the canonical contract in both directions, so it cannot\n  // silently drift (mirroring the conformance assertion `@lifi/api-schemas` runs\n  // on its server-side simulate schema). Assigning the inferred wire value to a\n  // `SimulateResult` checks wire→spec; `satisfies SimulateResultWire` checks\n  // spec→wire. A missing or mistyped field on either side fails to compile.\n  const result: SimulateResult = parsed.data;\n  return result satisfies SimulateResultWire;\n};\n\n/**\n * The validated members of an HTTP 206 partial compile envelope. `data` is\n * verified to be an object at runtime but left `unknown` here — compose-spec\n * owns its full shape (`ComposeCompilePartialData`) as a hand-authored type, so\n * the caller narrows it in one step. `error` is fully validated.\n */\nexport interface CompilePartialEnvelope {\n  readonly data: unknown;\n  readonly error: { readonly kind: string; readonly message: string };\n}\n\nconst compilePartialEnvelopeSchema = z.object({\n  data: z.record(z.string(), z.unknown()),\n  error: z.object({ kind: z.string(), message: z.string() }),\n});\n\n/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */\nexport const parseCompilePartialEnvelope = (\n  body: unknown,\n): CompilePartialEnvelope | null => {\n  const parsed = compilePartialEnvelopeSchema.safeParse(body);\n  return parsed.success ? parsed.data : null;\n};\n\n/**\n * A single prepared-op failure inside a `preparation_error` envelope. `kind` is\n * kept as `string` here — the narrowing to `GenericComposeErrorKind` happens in\n * `errorFromHttpResponse`, where the value is lifted onto `ComposeError`.\n */\nexport interface ServerFailedPreparedOp {\n  readonly callId: string;\n  readonly op: string;\n  readonly kind: string;\n  readonly message: string;\n  readonly path?: string;\n  readonly port?: string;\n  readonly fix?: string;\n}\n\n/** Error envelope returned on non-2xx responses. */\nexport interface ServerErrorBody {\n  readonly error?: {\n    readonly kind?: string;\n    readonly message?: string;\n    readonly path?: string;\n    readonly port?: string;\n    readonly fix?: string;\n    readonly sdkVersion?: string;\n    readonly serverVersion?: string;\n    readonly minimumSdkVersion?: string;\n    readonly details?: SimulationRevert;\n    readonly failedOps?: readonly ServerFailedPreparedOp[];\n    readonly succeededOps?: readonly string[];\n  };\n}\n\nconst failedPreparedOpSchema = z.object({\n  callId: z.string(),\n  op: z.string(),\n  kind: z.string(),\n  message: z.string(),\n  path: z.string().optional(),\n  port: z.string().optional(),\n  fix: z.string().optional(),\n});\n\n// `details` is passed through (`z.custom`) rather than parsed: the SDK does not\n// own the `SimulationRevert` schema and forwards the field verbatim onto\n// `ComposeError`.\n//\n// `failedOps`/`succeededOps` are optional here because every error kind shares\n// this envelope; they are only populated for `preparation_error` (422). Zod\n// strips undeclared keys, so omitting them would silently drop them — which is\n// also why `port` and `fix`, set on every author-caused `validation_error`,\n// have to be declared here to reach the caller.\nconst serverErrorBodySchema = z.object({\n  error: z\n    .object({\n      kind: z.string().optional(),\n      message: z.string().optional(),\n      path: z.string().optional(),\n      port: z.string().optional(),\n      fix: z.string().optional(),\n      sdkVersion: z.string().optional(),\n      serverVersion: z.string().optional(),\n      minimumSdkVersion: z.string().optional(),\n      details: z.custom<SimulationRevert>().optional(),\n      failedOps: z.array(failedPreparedOpSchema).readonly().optional(),\n      succeededOps: z.array(z.string()).readonly().optional(),\n    })\n    .optional(),\n});\n\n/** Validates an already-parsed error envelope; `null` when it does not match. */\nexport const parseServerErrorBody = (json: unknown): ServerErrorBody | null => {\n  const parsed = serverErrorBodySchema.safeParse(json);\n  return parsed.success ? parsed.data : null;\n};\n"],"mappings":"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","names":["z"]}

package/dist/responseSchemas.d.cts

@@ -32,6 +32,8 @@ interface ServerFailedPreparedOp {
     readonly kind: string;
     readonly message: string;
     readonly path?: string;
+    readonly port?: string;
+    readonly fix?: string;
 }
 /** Error envelope returned on non-2xx responses. */
 interface ServerErrorBody {
@@ -39,6 +41,8 @@ interface ServerErrorBody {
         readonly kind?: string;
         readonly message?: string;
         readonly path?: string;
+        readonly port?: string;
+        readonly fix?: string;
         readonly sdkVersion?: string;
         readonly serverVersion?: string;
         readonly minimumSdkVersion?: string;

package/dist/responseSchemas.d.ts

@@ -32,6 +32,8 @@ interface ServerFailedPreparedOp {
     readonly kind: string;
     readonly message: string;
     readonly path?: string;
+    readonly port?: string;
+    readonly fix?: string;
 }
 /** Error envelope returned on non-2xx responses. */
 interface ServerErrorBody {
@@ -39,6 +41,8 @@ interface ServerErrorBody {
         readonly kind?: string;
         readonly message?: string;
         readonly path?: string;
+        readonly port?: string;
+        readonly fix?: string;
         readonly sdkVersion?: string;
         readonly serverVersion?: string;
         readonly minimumSdkVersion?: string;

package/dist/responseSchemas.js

@@ -59,13 +59,17 @@ const failedPreparedOpSchema = z.object({
   op: z.string(),
   kind: z.string(),
   message: z.string(),
-  path: z.string().optional()
+  path: z.string().optional(),
+  port: z.string().optional(),
+  fix: z.string().optional()
 });
 const serverErrorBodySchema = z.object({
   error: z.object({
     kind: z.string().optional(),
     message: z.string().optional(),
     path: z.string().optional(),
+    port: z.string().optional(),
+    fix: z.string().optional(),
     sdkVersion: z.string().optional(),
     serverVersion: z.string().optional(),
     minimumSdkVersion: z.string().optional(),

package/dist/responseSchemas.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/responseSchemas.ts"],"sourcesContent":["import type { SimulateResult, SimulationRevert } from '@lifi/compose-spec';\nimport z from 'zod';\n\n/**\n * Zod-backed parsers for Compose API response bodies.\n *\n * Server responses are untrusted input crossing into the SDK, so the shapes the\n * client reads back are validated here rather than asserted with `as` casts. The\n * schemas are module-private (the package builds with `--isolatedDeclarations`,\n * which forbids exporting un-annotated complex values); the public surface is\n * the typed `parse*` helpers, whose explicit return types double as the contract.\n *\n * The simulate union is the one response the SDK fully owns and parses itself\n * (it is un-enveloped, unlike `/compose`), so it gets a complete schema kept in\n * lockstep with the canonical `SimulateResult` in `@lifi/compose-spec` by the\n * compile-time assertion below — the same anchoring `@lifi/api-schemas` uses for\n * its server-side simulate schema, so the two cannot silently drift.\n */\n\nconst balanceEntrySchema = z.object({\n  token: z.string(),\n  owner: z.string(),\n  amount: z.string(),\n});\n\nconst simulateOkSchema = z.object({\n  status: z.literal('ok'),\n  block: z.number(),\n  timestamp: z.number(),\n  balancesBefore: z.array(balanceEntrySchema),\n  balancesAfter: z.array(balanceEntrySchema),\n  deltas: z.array(balanceEntrySchema),\n  gasUsed: z.string(),\n});\n\nconst simulateRevertDecodeResultSchema = z.object({\n  errorCandidates: z\n    .array(\n      z.object({\n        decodedErrorSignature: z.string(),\n        decodedParams: z.array(z.string()),\n      }),\n    )\n    .optional(),\n  error: z.string().optional(),\n});\n\nconst simulateRevertSchema = z.object({\n  status: z.literal('revert'),\n  block: z.number(),\n  timestamp: z.number(),\n  revertReason: z.string().optional(),\n  code: z.number().optional(),\n  rawErrorBytes: z.string().optional(),\n  decodeResult: simulateRevertDecodeResultSchema.optional(),\n});\n\nconst simulateSetupErrorSchema = z.object({\n  status: z.literal('error'),\n  message: z.string(),\n});\n\nconst simulateResultSchema = z.discriminatedUnion('status', [\n  simulateOkSchema,\n  simulateRevertSchema,\n  simulateSetupErrorSchema,\n]);\n\n// The type the schema actually parses out. Kept private (referencing it from an\n// exported declaration would break `--isolatedDeclarations`) and pinned to the\n// canonical `SimulateResult` inside `parseSimulateResult` below.\ntype SimulateResultWire = z.infer<typeof simulateResultSchema>;\n\n/**\n * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`\n * when the body does not match the `ok`/`revert`/`error` union, letting the\n * caller raise a transport-level error.\n */\nexport const parseSimulateResult = (body: unknown): SimulateResult | null => {\n  const parsed = simulateResultSchema.safeParse(body);\n  if (!parsed.success) return null;\n  // Pin the schema to the canonical contract in both directions, so it cannot\n  // silently drift (mirroring the conformance assertion `@lifi/api-schemas` runs\n  // on its server-side simulate schema). Assigning the inferred wire value to a\n  // `SimulateResult` checks wire→spec; `satisfies SimulateResultWire` checks\n  // spec→wire. A missing or mistyped field on either side fails to compile.\n  const result: SimulateResult = parsed.data;\n  return result satisfies SimulateResultWire;\n};\n\n/**\n * The validated members of an HTTP 206 partial compile envelope. `data` is\n * verified to be an object at runtime but left `unknown` here — compose-spec\n * owns its full shape (`ComposeCompilePartialData`) as a hand-authored type, so\n * the caller narrows it in one step. `error` is fully validated.\n */\nexport interface CompilePartialEnvelope {\n  readonly data: unknown;\n  readonly error: { readonly kind: string; readonly message: string };\n}\n\nconst compilePartialEnvelopeSchema = z.object({\n  data: z.record(z.string(), z.unknown()),\n  error: z.object({ kind: z.string(), message: z.string() }),\n});\n\n/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */\nexport const parseCompilePartialEnvelope = (\n  body: unknown,\n): CompilePartialEnvelope | null => {\n  const parsed = compilePartialEnvelopeSchema.safeParse(body);\n  return parsed.success ? parsed.data : null;\n};\n\n/**\n * A single prepared-op failure inside a `preparation_error` envelope. `kind` is\n * kept as `string` here — the narrowing to `GenericComposeErrorKind` happens in\n * `errorFromHttpResponse`, where the value is lifted onto `ComposeError`.\n */\nexport interface ServerFailedPreparedOp {\n  readonly callId: string;\n  readonly op: string;\n  readonly kind: string;\n  readonly message: string;\n  readonly path?: string;\n}\n\n/** Error envelope returned on non-2xx responses. */\nexport interface ServerErrorBody {\n  readonly error?: {\n    readonly kind?: string;\n    readonly message?: string;\n    readonly path?: string;\n    readonly sdkVersion?: string;\n    readonly serverVersion?: string;\n    readonly minimumSdkVersion?: string;\n    readonly details?: SimulationRevert;\n    readonly failedOps?: readonly ServerFailedPreparedOp[];\n    readonly succeededOps?: readonly string[];\n  };\n}\n\nconst failedPreparedOpSchema = z.object({\n  callId: z.string(),\n  op: z.string(),\n  kind: z.string(),\n  message: z.string(),\n  path: z.string().optional(),\n});\n\n// `details` is passed through (`z.custom`) rather than parsed: the SDK does not\n// own the `SimulationRevert` schema and forwards the field verbatim onto\n// `ComposeError`.\n//\n// `failedOps`/`succeededOps` are optional here because every error kind shares\n// this envelope; they are only populated for `preparation_error` (422). Zod\n// strips undeclared keys, so omitting them would silently drop them.\nconst serverErrorBodySchema = z.object({\n  error: z\n    .object({\n      kind: z.string().optional(),\n      message: z.string().optional(),\n      path: z.string().optional(),\n      sdkVersion: z.string().optional(),\n      serverVersion: z.string().optional(),\n      minimumSdkVersion: z.string().optional(),\n      details: z.custom<SimulationRevert>().optional(),\n      failedOps: z.array(failedPreparedOpSchema).readonly().optional(),\n      succeededOps: z.array(z.string()).readonly().optional(),\n    })\n    .optional(),\n});\n\n/** Validates an already-parsed error envelope; `null` when it does not match. */\nexport const parseServerErrorBody = (json: unknown): ServerErrorBody | null => {\n  const parsed = serverErrorBodySchema.safeParse(json);\n  return parsed.success ? parsed.data : null;\n};\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/responseSchemas.ts"],"sourcesContent":["import type { SimulateResult, SimulationRevert } from '@lifi/compose-spec';\nimport z from 'zod';\n\n/**\n * Zod-backed parsers for Compose API response bodies.\n *\n * Server responses are untrusted input crossing into the SDK, so the shapes the\n * client reads back are validated here rather than asserted with `as` casts. The\n * schemas are module-private (the package builds with `--isolatedDeclarations`,\n * which forbids exporting un-annotated complex values); the public surface is\n * the typed `parse*` helpers, whose explicit return types double as the contract.\n *\n * The simulate union is the one response the SDK fully owns and parses itself\n * (it is un-enveloped, unlike `/compose`), so it gets a complete schema kept in\n * lockstep with the canonical `SimulateResult` in `@lifi/compose-spec` by the\n * compile-time assertion below — the same anchoring `@lifi/api-schemas` uses for\n * its server-side simulate schema, so the two cannot silently drift.\n */\n\nconst balanceEntrySchema = z.object({\n  token: z.string(),\n  owner: z.string(),\n  amount: z.string(),\n});\n\nconst simulateOkSchema = z.object({\n  status: z.literal('ok'),\n  block: z.number(),\n  timestamp: z.number(),\n  balancesBefore: z.array(balanceEntrySchema),\n  balancesAfter: z.array(balanceEntrySchema),\n  deltas: z.array(balanceEntrySchema),\n  gasUsed: z.string(),\n});\n\nconst simulateRevertDecodeResultSchema = z.object({\n  errorCandidates: z\n    .array(\n      z.object({\n        decodedErrorSignature: z.string(),\n        decodedParams: z.array(z.string()),\n      }),\n    )\n    .optional(),\n  error: z.string().optional(),\n});\n\nconst simulateRevertSchema = z.object({\n  status: z.literal('revert'),\n  block: z.number(),\n  timestamp: z.number(),\n  revertReason: z.string().optional(),\n  code: z.number().optional(),\n  rawErrorBytes: z.string().optional(),\n  decodeResult: simulateRevertDecodeResultSchema.optional(),\n});\n\nconst simulateSetupErrorSchema = z.object({\n  status: z.literal('error'),\n  message: z.string(),\n});\n\nconst simulateResultSchema = z.discriminatedUnion('status', [\n  simulateOkSchema,\n  simulateRevertSchema,\n  simulateSetupErrorSchema,\n]);\n\n// The type the schema actually parses out. Kept private (referencing it from an\n// exported declaration would break `--isolatedDeclarations`) and pinned to the\n// canonical `SimulateResult` inside `parseSimulateResult` below.\ntype SimulateResultWire = z.infer<typeof simulateResultSchema>;\n\n/**\n * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`\n * when the body does not match the `ok`/`revert`/`error` union, letting the\n * caller raise a transport-level error.\n */\nexport const parseSimulateResult = (body: unknown): SimulateResult | null => {\n  const parsed = simulateResultSchema.safeParse(body);\n  if (!parsed.success) return null;\n  // Pin the schema to the canonical contract in both directions, so it cannot\n  // silently drift (mirroring the conformance assertion `@lifi/api-schemas` runs\n  // on its server-side simulate schema). Assigning the inferred wire value to a\n  // `SimulateResult` checks wire→spec; `satisfies SimulateResultWire` checks\n  // spec→wire. A missing or mistyped field on either side fails to compile.\n  const result: SimulateResult = parsed.data;\n  return result satisfies SimulateResultWire;\n};\n\n/**\n * The validated members of an HTTP 206 partial compile envelope. `data` is\n * verified to be an object at runtime but left `unknown` here — compose-spec\n * owns its full shape (`ComposeCompilePartialData`) as a hand-authored type, so\n * the caller narrows it in one step. `error` is fully validated.\n */\nexport interface CompilePartialEnvelope {\n  readonly data: unknown;\n  readonly error: { readonly kind: string; readonly message: string };\n}\n\nconst compilePartialEnvelopeSchema = z.object({\n  data: z.record(z.string(), z.unknown()),\n  error: z.object({ kind: z.string(), message: z.string() }),\n});\n\n/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */\nexport const parseCompilePartialEnvelope = (\n  body: unknown,\n): CompilePartialEnvelope | null => {\n  const parsed = compilePartialEnvelopeSchema.safeParse(body);\n  return parsed.success ? parsed.data : null;\n};\n\n/**\n * A single prepared-op failure inside a `preparation_error` envelope. `kind` is\n * kept as `string` here — the narrowing to `GenericComposeErrorKind` happens in\n * `errorFromHttpResponse`, where the value is lifted onto `ComposeError`.\n */\nexport interface ServerFailedPreparedOp {\n  readonly callId: string;\n  readonly op: string;\n  readonly kind: string;\n  readonly message: string;\n  readonly path?: string;\n  readonly port?: string;\n  readonly fix?: string;\n}\n\n/** Error envelope returned on non-2xx responses. */\nexport interface ServerErrorBody {\n  readonly error?: {\n    readonly kind?: string;\n    readonly message?: string;\n    readonly path?: string;\n    readonly port?: string;\n    readonly fix?: string;\n    readonly sdkVersion?: string;\n    readonly serverVersion?: string;\n    readonly minimumSdkVersion?: string;\n    readonly details?: SimulationRevert;\n    readonly failedOps?: readonly ServerFailedPreparedOp[];\n    readonly succeededOps?: readonly string[];\n  };\n}\n\nconst failedPreparedOpSchema = z.object({\n  callId: z.string(),\n  op: z.string(),\n  kind: z.string(),\n  message: z.string(),\n  path: z.string().optional(),\n  port: z.string().optional(),\n  fix: z.string().optional(),\n});\n\n// `details` is passed through (`z.custom`) rather than parsed: the SDK does not\n// own the `SimulationRevert` schema and forwards the field verbatim onto\n// `ComposeError`.\n//\n// `failedOps`/`succeededOps` are optional here because every error kind shares\n// this envelope; they are only populated for `preparation_error` (422). Zod\n// strips undeclared keys, so omitting them would silently drop them — which is\n// also why `port` and `fix`, set on every author-caused `validation_error`,\n// have to be declared here to reach the caller.\nconst serverErrorBodySchema = z.object({\n  error: z\n    .object({\n      kind: z.string().optional(),\n      message: z.string().optional(),\n      path: z.string().optional(),\n      port: z.string().optional(),\n      fix: z.string().optional(),\n      sdkVersion: z.string().optional(),\n      serverVersion: z.string().optional(),\n      minimumSdkVersion: z.string().optional(),\n      details: z.custom<SimulationRevert>().optional(),\n      failedOps: z.array(failedPreparedOpSchema).readonly().optional(),\n      succeededOps: z.array(z.string()).readonly().optional(),\n    })\n    .optional(),\n});\n\n/** Validates an already-parsed error envelope; `null` when it does not match. */\nexport const parseServerErrorBody = (json: unknown): ServerErrorBody | null => {\n  const parsed = serverErrorBodySchema.safeParse(json);\n  return parsed.success ? parsed.data : null;\n};\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/composer-sdk",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Public Composer SDK for building and submitting flows",
   "license": "Apache-2.0",
   "repository": {
@@ -47,7 +47,7 @@
     "example:staged": "tsx src/examples/run.ts --staged"
   },
   "peerDependencies": {
-    "@lifi/compose-spec": "0.6.0"
+    "@lifi/compose-spec": "0.6.2"
   },
   "dependencies": {
     "abitype": "^1.2.3",

package/src/client.ts

@@ -115,12 +115,12 @@ export interface ComposeClient {
    * `simulationPolicy: 'allow-revert'` yields `status: 'partial'` rather than
    * throwing, exactly as it does for {@link compile}.
    *
-   * As of today that flow is a single zap step: one edge of the backend's
-   * routing catalog (a position entry or exit, a wrap or unwrap, a mint or
-   * burn). Enumerate the pairs it covers with {@link getZapPacks}; a pair with
-   * no edge is rejected with `kind: 'no_route_error'`. The endpoint is meant to
-   * author richer flows later, so the single-step limit is the current state of
-   * the server, not the shape of this contract.
+   * The server plans a short chain of catalog edges for the pair (a position
+   * entry or exit, a wrap or unwrap, a mint or burn), optionally opened by a
+   * `lifi.swap`. {@link getZapPacks} lists the single edges; the pairs the
+   * planner connects are their closure up to the hop budget, which
+   * {@link buildReachability} computes locally. A pair the planner cannot
+   * connect is rejected with `kind: 'no_route_error'`.
    *
    * Only synchronous edges are considered unless the request sets
    * `allowAsyncRoutes: true`, so by default every terminal output comes back
@@ -138,7 +138,7 @@ export interface ComposeClient {
    * @param request - The from/to token pair, amount, signer, and route options.
    * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.
    * @throws {@link ComposeError} on network, validation, or server errors —
-   *   including `NOT_FOUND` (HTTP 404) when no catalog edge covers the pair.
+   *   including `NOT_FOUND` (HTTP 404) when the planner cannot connect the pair.
    */
   readonly route: (
     request: ComposeRouteRequest,

package/src/errors.ts

@@ -79,8 +79,23 @@ export class ComposeError extends Error {
   readonly url?: string;
   /** Server-provided error kind for finer-grained classification. */
   readonly kind?: ComposeErrorKind | ComposeRouteErrorKind;
-  /** JSON-pointer path to the field that caused a validation error. */
+  /**
+   * Where a validation error points: the node id for a rejection of an
+   * authored node, or a JSON-pointer path for a rejection of the request shape.
+   */
   readonly path?: string;
+  /**
+   * The input port of {@link ComposeError.path}'s node whose binding caused the
+   * error. Set when the rejection is about what a port binds rather than about
+   * the node's config.
+   */
+  readonly port?: string;
+  /**
+   * The one edit that clears the error, written for whoever authored the flow.
+   * Set on `continuation.settle` authoring rejections; may be absent on other
+   * `validation_error`s.
+   */
+  readonly fix?: string;
   /**
    * Simulation revert diagnostics attached to `simulation_revert` errors.
    * Contains the raw error bytes and decoded error candidates when the
@@ -112,6 +127,8 @@ export class ComposeError extends Error {
       cause?: unknown;
       kind?: ComposeErrorKind | ComposeRouteErrorKind;
       path?: string;
+      port?: string;
+      fix?: string;
       details?: SimulationRevert;
       failedOps?: readonly FailedPreparedOp[];
       succeededOps?: readonly string[];
@@ -125,6 +142,8 @@ export class ComposeError extends Error {
     this.url = options?.url;
     this.kind = options?.kind;
     this.path = options?.path;
+    this.port = options?.port;
+    this.fix = options?.fix;
     this.details = options?.details;
     this.failedOps = options?.failedOps;
     this.succeededOps = options?.succeededOps;
@@ -312,6 +331,8 @@ export const errorFromHttpResponse = (
       kind: serverError?.kind as
         ComposeErrorKind | ComposeRouteErrorKind | undefined,
       path: serverError?.path,
+      port: serverError?.port,
+      fix: serverError?.fix,
       details: serverError?.details,
       // The wire schema types `kind` as a bare string; the server only ever
       // reports generic kinds for individual ops.

package/src/index.ts

@@ -28,6 +28,13 @@ export type {
   ZapPackEdge,
   ZapPackOverview,
 } from './discovery.js';
+export type {
+  Reachability,
+  ReachabilityOptions,
+  RoutablePair,
+  TokenRef,
+} from './reachability.js';
+export { buildReachability } from './reachability.js';
 export type {
   ComposeError,
   ComposeErrorCode,

package/src/reachability.ts

@@ -0,0 +1,203 @@
+/**
+ * Client-side reachability over the zap-pack catalog.
+ *
+ * `GET /compose/zap-packs` lists single routing edges. `POST /compose/route`
+ * chains up to the server's hop budget of them, so the set of routable pairs
+ * is the closure of the catalog, not the catalog itself. This module computes
+ * that closure locally with the planner's admissibility rule, so an integrator
+ * can offer every pair `route` connects without a request per pair.
+ *
+ * The rule, mirrored from the server's route search:
+ *
+ * - every edge except the last must leave its output in the proxy for the
+ *   next edge to consume: no `availability`, no `recipient: 'required'`
+ * - the last edge must be synchronous, or `availability: 'future'` when the
+ *   caller opts into `allowAsyncRoutes`
+ * - a route never visits the same token twice
+ *
+ * Amount bounds (`inAmountMin` / `inAmountMax`) on an intermediate edge
+ * cannot be checked without an amount, so a pair reported here is routable
+ * structurally, exactly as a listed edge is. Routes that open with a
+ * `lifi.swap` are not enumerable and are not reported. The server also
+ * drops blacklisted tokens as intermediates, which is server-side config
+ * this module cannot see, so a reported pair may still answer
+ * `no_route_error`.
+ */
+
+import type { ZapPackEdge, ZapPackOverview } from './discovery.js';
+
+/** A token identified by address and chain. */
+export interface TokenRef {
+  readonly address: string;
+  readonly chainId: number;
+}
+
+/** A from/to pair `POST /compose/route` can connect through the catalog. */
+export interface RoutablePair {
+  readonly in: TokenRef;
+  readonly out: TokenRef;
+  /** Catalog edges on the shortest admissible route; `1` is a listed edge. */
+  readonly hops: number;
+}
+
+export interface ReachabilityOptions {
+  /**
+   * Hop budget. The server's `no_route_error` reports its effective value in
+   * `details.maxHops`; the deployment default is 2.
+   */
+  readonly maxHops?: number;
+  /**
+   * Admit a route whose last edge has `availability: 'future'`. Mirrors the
+   * `allowAsyncRoutes` request option; such a pair is a `no_route_error`
+   * without it.
+   */
+  readonly allowAsyncRoutes?: boolean;
+}
+
+export interface Reachability {
+  readonly maxHops: number;
+  /** Whether `route` can connect `from` to `to` through the catalog. */
+  readonly canRoute: (from: TokenRef, to: TokenRef) => boolean;
+  /** Every pair starting at `from`, shortest routes first. */
+  readonly routableFrom: (from: TokenRef) => readonly RoutablePair[];
+  /** Every routable pair in the catalog. */
+  readonly pairs: () => readonly RoutablePair[];
+}
+
+const DEFAULT_MAX_HOPS = 2;
+
+const tokenKey = (token: TokenRef): string =>
+  `${token.chainId}:${token.address.toLowerCase()}`;
+
+const isSync = (edge: ZapPackEdge): boolean => edge.availability === undefined;
+
+// The output stays in the proxy, so a following edge can consume it.
+const isProxyHeld = (edge: ZapPackEdge): boolean =>
+  isSync(edge) && edge.recipient !== 'required';
+
+// One edge out of a frontier token. Records the pair it completes, and returns
+// its output when a further hop may consume it (proxy-held) and no shorter
+// path already expanded that token.
+const visitEdge = ({
+  edge,
+  from,
+  depth,
+  sourceKey,
+  isTerminal,
+  found,
+  expanded,
+}: {
+  readonly edge: ZapPackEdge;
+  readonly from: TokenRef;
+  readonly depth: number;
+  readonly sourceKey: string;
+  readonly isTerminal: (edge: ZapPackEdge) => boolean;
+  readonly found: Map<string, RoutablePair>;
+  readonly expanded: Set<string>;
+}): TokenRef | undefined => {
+  const key = tokenKey(edge.out);
+  if (key === sourceKey) return undefined;
+  if (isTerminal(edge) && !found.has(key)) {
+    found.set(key, { in: from, out: edge.out, hops: depth });
+  }
+  if (!isProxyHeld(edge) || expanded.has(key)) return undefined;
+  expanded.add(key);
+  return edge.out;
+};
+
+// Every pair reachable from one token within `maxHops`, breadth-first so the
+// recorded hop count is the shortest one.
+const closureFrom = ({
+  byIn,
+  from,
+  maxHops,
+  isTerminal,
+}: {
+  readonly byIn: ReadonlyMap<string, readonly ZapPackEdge[]>;
+  readonly from: TokenRef;
+  readonly maxHops: number;
+  readonly isTerminal: (edge: ZapPackEdge) => boolean;
+}): Map<string, RoutablePair> => {
+  const sourceKey = tokenKey(from);
+  const found = new Map<string, RoutablePair>();
+  const expanded = new Set<string>([sourceKey]);
+  let frontier: readonly TokenRef[] = [from];
+  for (let depth = 1; depth <= maxHops && frontier.length > 0; depth++) {
+    const next: TokenRef[] = [];
+    for (const node of frontier) {
+      for (const edge of byIn.get(tokenKey(node)) ?? []) {
+        const out = visitEdge({
+          edge,
+          from,
+          depth,
+          sourceKey,
+          isTerminal,
+          found,
+          expanded,
+        });
+        if (out) next.push(out);
+      }
+    }
+    frontier = next;
+  }
+  return found;
+};
+
+const indexByIn = (
+  packs: readonly ZapPackOverview[],
+): Map<string, ZapPackEdge[]> => {
+  const byIn = new Map<string, ZapPackEdge[]>();
+  for (const pack of packs) {
+    for (const edge of pack.edges) {
+      const key = tokenKey(edge.in);
+      const list = byIn.get(key);
+      if (list) list.push(edge);
+      else byIn.set(key, [edge]);
+    }
+  }
+  return byIn;
+};
+
+/**
+ * Builds a reachability index over the packs returned by
+ * {@link ComposeClient.getZapPacks}. Per-source closures are computed on
+ * first use and memoised, so `canRoute` on a handful of pairs stays cheap
+ * while `pairs()` enumerates everything.
+ */
+export const buildReachability = (
+  packs: readonly ZapPackOverview[],
+  options: ReachabilityOptions = {},
+): Reachability => {
+  const maxHops = options.maxHops ?? DEFAULT_MAX_HOPS;
+  const allowAsync = options.allowAsyncRoutes ?? false;
+  const isTerminal = (edge: ZapPackEdge): boolean =>
+    isSync(edge) || (allowAsync && edge.availability === 'future');
+
+  const byIn = indexByIn(packs);
+  const memo = new Map<string, Map<string, RoutablePair>>();
+  const closure = (from: TokenRef): Map<string, RoutablePair> => {
+    const key = tokenKey(from);
+    const cached = memo.get(key);
+    if (cached) return cached;
+    const computed = closureFrom({ byIn, from, maxHops, isTerminal });
+    memo.set(key, computed);
+    return computed;
+  };
+
+  return {
+    maxHops,
+    canRoute: (from, to) => closure(from).has(tokenKey(to)),
+    routableFrom: (from) => [...closure(from).values()],
+    pairs: () => {
+      const sources = new Map<string, TokenRef>();
+      for (const pack of packs) {
+        for (const edge of pack.edges) sources.set(tokenKey(edge.in), edge.in);
+      }
+      const all: RoutablePair[] = [];
+      for (const source of sources.values()) {
+        all.push(...closure(source).values());
+      }
+      return all;
+    },
+  };
+};

package/src/responseSchemas.ts

@@ -123,6 +123,8 @@ export interface ServerFailedPreparedOp {
   readonly kind: string;
   readonly message: string;
   readonly path?: string;
+  readonly port?: string;
+  readonly fix?: string;
 }
 
 /** Error envelope returned on non-2xx responses. */
@@ -131,6 +133,8 @@ export interface ServerErrorBody {
     readonly kind?: string;
     readonly message?: string;
     readonly path?: string;
+    readonly port?: string;
+    readonly fix?: string;
     readonly sdkVersion?: string;
     readonly serverVersion?: string;
     readonly minimumSdkVersion?: string;
@@ -146,6 +150,8 @@ const failedPreparedOpSchema = z.object({
   kind: z.string(),
   message: z.string(),
   path: z.string().optional(),
+  port: z.string().optional(),
+  fix: z.string().optional(),
 });
 
 // `details` is passed through (`z.custom`) rather than parsed: the SDK does not
@@ -154,13 +160,17 @@ const failedPreparedOpSchema = z.object({
 //
 // `failedOps`/`succeededOps` are optional here because every error kind shares
 // this envelope; they are only populated for `preparation_error` (422). Zod
-// strips undeclared keys, so omitting them would silently drop them.
+// strips undeclared keys, so omitting them would silently drop them — which is
+// also why `port` and `fix`, set on every author-caused `validation_error`,
+// have to be declared here to reach the caller.
 const serverErrorBodySchema = z.object({
   error: z
     .object({
       kind: z.string().optional(),
       message: z.string().optional(),
       path: z.string().optional(),
+      port: z.string().optional(),
+      fix: z.string().optional(),
       sdkVersion: z.string().optional(),
       serverVersion: z.string().optional(),
       minimumSdkVersion: z.string().optional(),