@cortexkit/subc-client 0.8.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/subc-client",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "TypeScript client for the subc daemon. Wire-compatible (byte-for-byte) with the Rust subc-transport handshake and subc-protocol envelope.",
   "type": "module",
   "exports": {
@@ -30,4 +30,4 @@
     "bun-types": "^1.3.14",
     "typescript": "^5.6.0"
   }
-}
+}

package/src/client.ts

@@ -20,6 +20,7 @@ import {
   buildFlags,
   encodeFrame,
   FrameType,
+  hasBinary,
   Priority,
   type Frame,
 } from "./envelope.js";
@@ -112,16 +113,59 @@ export interface RouteOpenOptions {
   consumerCapabilities?: string[];
 }
 
+export interface CatalogCapabilityRequirement {
+  capability: string;
+  need: "required" | "optional";
+}
+
+export interface CatalogCapabilities {
+  provides: string[];
+  requires: CatalogCapabilityRequirement[];
+  must_never_reach: string[];
+}
+
+/** A self-signal's anchor relative to the external surface it shapes. */
+export type CatalogSignalAnchor =
+  | "fixed_interval"
+  | { event: { event: string } };
+
+/** The source of a self-signal's effective cadence. */
+export type CatalogSignalCadence =
+  | { literal: { interval_ms: number } }
+  | { derived: { source: string } };
+
+/** A self-signal declaration mirrored from a registered module manifest. */
+export interface CatalogSelfSignalDeclaration {
+  name: string;
+  /** Open string for forward-compatible self-signal kinds. */
+  kind: string;
+  effect: "observe" | "mutate";
+  anchored_to: CatalogSignalAnchor;
+  cadence?: CatalogSignalCadence | null;
+  domain?: string | null;
+  note?: string | null;
+}
+
 export interface CatalogEntry {
   module_id: string;
   roles: unknown[];
   control_ops: string[];
+  /** Static capability claims mirrored from the registered module manifest. */
+  capabilities?: CatalogCapabilities | null;
+  /** Self-signal declarations mirrored verbatim from the registered manifest. */
+  self_signals?: CatalogSelfSignalDeclaration[] | null;
 }
 
 export interface RequestOptions {
   priority?: Priority;
   admissionClass?: AdmissionClass;
   timeoutMs?: number;
+  /**
+   * Set when the request body is opaque bytes rather than JSON. This flag is the
+   * receiver's only signal about the body representation; reply decoding follows
+   * the response frame's flag instead of this request option.
+   */
+  binary?: boolean;
   /** Called for each interim PUSH / StreamData frame before the terminal reply. */
   onProgress?: (body: Uint8Array) => void;
 }
@@ -208,6 +252,16 @@ export class SubcCallError extends Error {
     super(message);
     this.name = "SubcCallError";
   }
+
+  /**
+   * Machine-parsable payload from the wire `ErrorBody.detail`, surfaced from
+   * the underlying Error frame when one caused this failure. Typed refusal
+   * reasons (for example certification refusals) ride this field; consumers
+   * classify on it and must not have to reach into `cause`.
+   */
+  get detail(): unknown {
+    return this.cause instanceof SubcError ? this.cause.detail : undefined;
+  }
 }
 
 /**
@@ -228,11 +282,24 @@ export class SubcError extends Error {
   constructor(
     message: string,
     readonly code?: string,
+    /**
+     * Machine-parsable payload from the wire `ErrorBody.detail` field, carried
+     * verbatim. Providers use it for typed refusal reasons (for example
+     * synapse's certification-refusal reasons); dropping it here would strand
+     * those reasons at the transport boundary.
+     */
+    readonly detail?: unknown,
   ) {
     super(message);
   }
 }
 
+function requireBinaryBody(body: unknown): Uint8Array {
+  if (body instanceof Uint8Array) return body;
+  const type = body === null ? "null" : Array.isArray(body) ? "array" : typeof body;
+  throw new SubcError(`binary request body must be a Uint8Array; got ${type}`, "binary_body_required");
+}
+
 interface Pending {
   handle: RouteHandle | null;
   resolve: (frame: Frame) => void;
@@ -261,6 +328,14 @@ export interface ConnectOptions {
   reconnectBackoff?: ReconnectBackoff;
   /** Injectable sleep for timer-free reconnect tests. */
   sleep?: (ms: number) => Promise<void>;
+  /**
+   * How long managed calls keep retrying route.open in-place on retryable
+   * refusals (module_reloading, module_warming, target_unavailable, …) before
+   * settling not_sent. This deadline is the ONLY binder on those retries —
+   * module reloads legitimately take tens of seconds (the daemon's drain alone
+   * defaults to 30s), so the default matches the daemon's drain ceiling.
+   */
+  routeOpenRetryDeadlineMs?: number;
   /**
    * Window the post-deadline liveness probe waits for ANY inbound frame after
    * sending its channel-0 Ping before convicting the socket as half-open.
@@ -300,6 +375,59 @@ export interface ControlPush {
   body: Record<string, unknown>;
 }
 
+/** A known route-close reason, excluding forward-compatible unknown values. */
+export type KnownRouteCloseReason =
+  | "reload"
+  | "restart"
+  | "disable"
+  | "crash"
+  | "capability_denied";
+
+/** A route-close reason decoded from a daemon control push. */
+export type RouteCloseReason = KnownRouteCloseReason | "unknown";
+
+/** Whether the close reason alone permits reopening a route automatically. */
+export type RouteCloseDisposition = "may_reopen" | "must_not_reopen";
+
+/**
+ * Decode a daemon close reason without rejecting a future wire value.
+ *
+ * An unknown reason remains observable as `unknown`; callers must use the
+ * strict disposition instead of treating an unrecognized policy change as safe.
+ */
+export function parseRouteCloseReason(reason: unknown): RouteCloseReason {
+  switch (reason) {
+    case "reload":
+    case "restart":
+    case "disable":
+    case "crash":
+    case "capability_denied":
+      return reason;
+    default:
+      return "unknown";
+  }
+}
+
+/** Unknown close reasons take the strictest action and must not trigger a reopen. */
+export function classifyRouteCloseReason(reason: unknown): RouteCloseDisposition {
+  switch (parseRouteCloseReason(reason)) {
+    case "reload":
+    case "restart":
+      return "may_reopen";
+    case "disable":
+    case "crash":
+    case "capability_denied":
+    case "unknown":
+      return "must_not_reopen";
+  }
+}
+
+/** Decode a close reason from a route lifecycle control push, if present. */
+export function routeCloseReason(push: ControlPush): RouteCloseReason | undefined {
+  if (push.op !== "route.closing" && push.op !== "route.closed") return undefined;
+  return parseRouteCloseReason(push.body.reason);
+}
+
 interface NormalizedConnectOptions {
   connectionFile: string;
   handshakeTimeoutMs?: number;
@@ -307,6 +435,7 @@ interface NormalizedConnectOptions {
   targetKind: ManagedRouteKind;
   reconnectBackoff: ReconnectBackoff;
   sleep: (ms: number) => Promise<void>;
+  routeOpenRetryDeadlineMs: number;
   timeoutArbitrationGraceMs: number;
   livenessProbeWindowMs: number;
   onControlPush?: (push: ControlPush) => void;
@@ -383,7 +512,42 @@ export class SubcClient {
     return parsed.modules ?? [];
   }
 
-    /** Open a route and return its connection-bound immutable handle. */
+  /**
+   * Resolve the sole catalog claimant for a capability.
+   *
+   * This expresses singular intent even when the fleet permits plural claims;
+   * ambiguity is returned instead of selecting an arbitrary module.
+   */
+  async resolveProvider(capability: string): Promise<string> {
+    const claimants = await this.resolveProviders(capability);
+    if (claimants.length === 0) {
+      throw new SubcError(`no catalog claimant for capability ${capability}`, "capability_unprovided");
+    }
+    if (claimants.length > 1) {
+      throw new SubcError(
+        `multiple catalog claimants for capability ${capability}: ${claimants.join(", ")}`,
+        "capability_ambiguous",
+      );
+    }
+    return claimants[0]!;
+  }
+
+  /** Resolve every catalog claimant in deterministic module-id order. */
+  async resolveProviders(capability: string): Promise<string[]> {
+    if (!isValidCapabilityIdentifier(capability)) {
+      throw new SubcError(
+        `malformed capability identifier ${JSON.stringify(capability)}`,
+        "invalid_capability_identifier",
+      );
+    }
+    const modules = await this.catalogList();
+    return modules
+      .filter((module) => module.capabilities?.provides.includes(capability) ?? false)
+      .map((module) => module.module_id)
+      .sort();
+  }
+
+  /** Open a route and return its connection-bound immutable handle. */
   async routeOpen(target: RouteTarget, identity: BindIdentity, opts: RouteOpenOptions = {}): Promise<RouteHandle> {
     const consumerIdentity = routeOpenConsumerIdentity(opts);
     const consumerCapabilities = opts.consumerCapabilities;
@@ -424,14 +588,25 @@ export class SubcClient {
     return installed;
   }
 
-    /** Send a data-plane request on exactly the supplied route generation. */
+  /** Send a data-plane request on exactly the supplied route generation. */
   async request(handle: RouteHandle, body: unknown, opts: RequestOptions = {}): Promise<unknown> {
     this.assertLiveHandle(handle);
-    const bytes = body instanceof Uint8Array ? body : this.encode(body);
+    const binary = opts.binary ?? false;
+    const bytes = binary ? requireBinaryBody(body) : body instanceof Uint8Array ? body : this.encode(body);
     const priority = opts.priority ?? Priority.Interactive;
     const admission = opts.admissionClass ?? AdmissionClass.Normal;
-    const reply = await this.send(handle, bytes, priority, admission, opts.timeoutMs, opts.onProgress);
-    return this.parseJson(reply);
+    const reply = await this.send(
+      handle,
+      bytes,
+      priority,
+      admission,
+      opts.timeoutMs,
+      opts.onProgress,
+      undefined,
+      undefined,
+      binary,
+    );
+    return this.decodeReply(reply);
   }
 
   /**
@@ -444,13 +619,37 @@ export class SubcClient {
     params?: unknown,
     opts: ManagedCallOptions = {},
   ): Promise<Response> {
+    if (opts.binary) {
+      throw new SubcError(
+        "call() builds a JSON body and cannot send a binary request; use callBinary(moduleId, body, opts) with a Uint8Array",
+        "binary_call_requires_call_binary",
+      );
+    }
     const body = params === undefined ? { method } : { method, params };
+    return (await this.managedCall(moduleId, body, opts)) as Response;
+  }
+
+  /**
+   * Managed route + raw opaque-body request convenience. Unlike call(), this
+   * sends bytes without a JSON method envelope because the BINARY flag is the
+   * receiver's only signal that the body is not JSON. A BINARY reply resolves
+   * to Uint8Array; a non-binary reply is decoded as JSON.
+   */
+  async callBinary(
+    moduleId: string,
+    body: Uint8Array,
+    opts: ManagedCallOptions = {},
+  ): Promise<Uint8Array | unknown> {
+    const bytes = requireBinaryBody(body);
+    return this.managedCall(moduleId, bytes, { ...opts, binary: true });
+  }
 
+  private async managedCall(moduleId: string, body: unknown, opts: ManagedCallOptions): Promise<unknown> {
     let retriedUnknownChannel = false;
     for (;;) {
       const routeHandle = await this.cachedRouteHandle(moduleId, opts);
       try {
-        return (await this.managedRequest(routeHandle, body, opts)) as Response;
+        return await this.managedRequest(routeHandle, body, opts);
       } catch (err) {
         if (!(err instanceof SubcCallError)) throw this.terminalCallError("managed call failed", err);
         // unknown_channel is the daemon ROUTER refusing an unrouted channel — the
@@ -699,6 +898,7 @@ export class SubcClient {
     onProgress: ((body: Uint8Array) => void) | undefined,
     acceptFrame?: (frame: Frame) => boolean,
     onLateResponse?: (frame: Frame) => void,
+    binary = false,
   ): Promise<Frame> {
     if (handle) this.assertLiveHandle(handle);
     if (this.closedErr) return Promise.reject(this.closedErr);
@@ -713,7 +913,7 @@ export class SubcClient {
     const epoch = handle?.epoch ?? 0;
     const frame = buildFrame(
       FrameType.Request,
-      buildFlags(false, priority, false, admission),
+      buildFlags(binary, priority, false, admission),
       channel,
       epoch,
       corr,
@@ -778,12 +978,21 @@ export class SubcClient {
   }
 
   private async managedRequest(handle: RouteHandle, body: unknown, opts: ManagedCallOptions): Promise<unknown> {
-    const bytes = body instanceof Uint8Array ? body : this.encode(body);
+    const binary = opts.binary ?? false;
+    const bytes = binary ? requireBinaryBody(body) : body instanceof Uint8Array ? body : this.encode(body);
     const priority = opts.priority ?? Priority.Interactive;
     const admission = opts.admissionClass ?? AdmissionClass.Normal;
     try {
-      const reply = await this.sendManaged(handle, bytes, priority, admission, opts.timeoutMs, opts.onProgress);
-      return this.parseJson(reply);
+      const reply = await this.sendManaged(
+        handle,
+        bytes,
+        priority,
+        admission,
+        opts.timeoutMs,
+        opts.onProgress,
+        binary,
+      );
+      return this.decodeReply(reply);
     } catch (error) {
       if (error instanceof SubcCallError) throw error;
       throw this.terminalCallError("managed call failed", error);
@@ -797,6 +1006,7 @@ export class SubcClient {
     admission: AdmissionClass,
     timeoutMs: number | undefined,
     onProgress: ((body: Uint8Array) => void) | undefined,
+    binary = false,
   ): Promise<Frame> {
     try {
       this.assertLiveHandle(handle);
@@ -818,7 +1028,7 @@ export class SubcClient {
     const key = pendingKey(handle, corr);
     const frame = buildFrame(
       FrameType.Request,
-      buildFlags(false, priority, false, admission),
+      buildFlags(binary, priority, false, admission),
       handle.channel,
       handle.epoch,
       corr,
@@ -898,7 +1108,7 @@ export class SubcClient {
   }
 
   private async openCachedRoute(cached: CachedRoute): Promise<RouteHandle> {
-    const routeRetryDeadline = Date.now() + ROUTE_OPEN_RETRY_DEADLINE_MS;
+    const routeRetryDeadline = Date.now() + this.opts.routeOpenRetryDeadlineMs;
     let routeRetryDelay = this.opts.reconnectBackoff.baseMs;
     let routeRetryAttempt = 0;
     for (;;) {
@@ -932,14 +1142,21 @@ export class SubcClient {
           continue;
         }
         if (!this.closeStarted && error instanceof SubcError && isRetryableRouteOpenCode(error.code)) {
+          // The deadline is the ONLY binder here. An attempt cap used to share
+          // this condition, and because the capped backoff sums to ~3.1s it
+          // strictly dominated the 30s deadline — the advertised reload
+          // patience was never delivered, so every module restart whose reload
+          // exceeded ~3s failed managed callers with module_reloading. Module
+          // reloads legitimately take tens of seconds (drain alone defaults to
+          // 30s); the backoff cap below bounds retry pressure instead.
           routeRetryAttempt += 1;
-          if (routeRetryAttempt < this.opts.reconnectBackoff.maxAttempts && Date.now() < routeRetryDeadline) {
+          if (Date.now() < routeRetryDeadline) {
             await this.opts.sleep(routeRetryDelay);
             routeRetryDelay = Math.min(routeRetryDelay * 2, this.opts.reconnectBackoff.capMs);
             continue;
           }
           throw this.notSentCallError(
-            `route.open failed for module ${cached.moduleId}: ${error.code} (retry budget exhausted)`,
+            `route.open failed for module ${cached.moduleId}: ${error.code} (retry deadline exhausted after ${routeRetryAttempt} attempts)`,
             error,
           );
         }
@@ -971,13 +1188,35 @@ export class SubcClient {
    * enough to delay the read loop delays this probe's own timer identically,
    * and when both wake the buffered Pong dispatches before the check runs.
    *
+   * A PENDING CHANNEL-0 REQUEST SUSPENDS THE PROBE (both at launch and at the
+   * conviction check). The daemon's connection loop handles frames one at a
+   * time, and some channel-0 ops legally park it for seconds — route.open
+   * awaits the module's bind ack inline for up to route_bind_relay_timeout
+   * (~12s in production) — during which OUR Ping sits unread in the daemon's
+   * socket buffer. On an otherwise-quiet connection that silence is fully
+   * explained by our own in-flight control op, and convicting on it would
+   * tear down a healthy connection mid-bind (BROCA's Athena panel flagged
+   * this exact premise; the FIFO fact is verified in subc-core server.rs
+   * connection_loop + control.rs handle_route_open). The client always knows
+   * its own channel-0 pendings, so the gate is local and exact: no probe
+   * while one is in flight, no conviction if one appeared during the window.
+   *
    * Scope: hooked from the managed-call path only. Control-plane requests
    * (route.open, catalog.list) are short-lived and their failures already
    * escalate through reconnect classification; the managed path is where a
    * plugin lives for hours and where the pin was observed in production.
    */
+  /** Any in-flight channel-0 request (pendings keyed without a route handle). */
+  private hasControlPending(): boolean {
+    for (const pending of this.pending.values()) {
+      if (pending.handle === null) return true;
+    }
+    return false;
+  }
+
   private probeLivenessAfterDeadline(): void {
     if (this.livenessProbe || this.closeStarted || this.closedErr) return;
+    if (this.hasControlPending()) return; // silence would be self-explained; re-armed by the next settle
     const sock = this.sock;
     const generation = this.generation;
     let corr: bigint;
@@ -1003,6 +1242,9 @@ export class SubcClient {
       await this.opts.sleep(this.opts.livenessProbeWindowMs);
       if (this.sock !== sock || this.generation !== generation || this.closeStarted) return;
       if (this.lastInboundAtMs >= t0) return; // link proven — keep the socket
+      // A control op that started during the window explains the silence: the
+      // daemon's read loop may be parked in its inline handler, not dead.
+      if (this.hasControlPending()) return;
       this.fail(
         new SocketClosedError(
           `liveness probe convicted a half-open socket: no inbound frame for ${this.opts.livenessProbeWindowMs}ms after a channel-0 Ping (deadline-no-drop settles preceded this); closing so the next call reconnects`,
@@ -1151,6 +1393,13 @@ export class SubcClient {
     // post-deadline liveness probe reads this stamp. Stamped after readLoop's
     // generation gate, so a stale socket's late frames never vouch for the
     // live one.
+    //
+    // PLACEMENT IS LOAD-BEARING: every inbound frame passes this one point
+    // before demux, which is the whole reason a single stamp works. A future
+    // fast path or drain-and-dispatch refactor that routes frames around
+    // dispatch() makes the stamp skippable, and the liveness watermark
+    // quietly stops meaning "the link delivered bytes" -- the cheapest
+    // correctness property here is also the easiest to lose in a refactor.
     this.lastInboundAtMs = Date.now();
     if (frame.header.channel === 0 && frame.header.ty === FrameType.Push) {
       // Daemon-originated control push (route.closing / route.closed / future
@@ -1295,8 +1544,9 @@ export class SubcClient {
       const parsed = JSON.parse(Buffer.from(frame.body).toString("utf8")) as {
         code?: string;
         message?: string;
+        detail?: unknown;
       };
-      return new SubcError(parsed.message ?? "subc error", parsed.code);
+      return new SubcError(parsed.message ?? "subc error", parsed.code, parsed.detail);
     } catch {
       return new SubcError(Buffer.from(frame.body).toString("utf8") || "subc error");
     }
@@ -1388,6 +1638,11 @@ export class SubcClient {
     return Buffer.from(JSON.stringify(value), "utf8");
   }
 
+  /** Decode a terminal response according to the representation on the wire. */
+  private decodeReply(frame: Frame): unknown {
+    return hasBinary(frame.header.flags) ? frame.body : this.parseJson(frame);
+  }
+
   private parseJson(frame: Frame): unknown {
     const b = frame.body;
     return JSON.parse(Buffer.from(b.buffer, b.byteOffset, b.byteLength).toString("utf8"));
@@ -1420,13 +1675,16 @@ export function isConsumerReconnectTransient(err: unknown): boolean {
  * is booting, mid-reload, transiently absent, or the bind relay timed out. A
  * daemon-rejected route.open is provably pre-send (no data frame ever left the
  * client), so these classify as not_sent; the managed path retries them in-place
- * within ROUTE_OPEN_RETRY_DEADLINE_MS. Permanent rejections (bad_consumer_identity,
- * config_divergence, unknown_target, ...) are excluded — they are pre-send but
- * would never succeed, so retrying them would only storm the daemon. Kept
- * byte-identical to subc-client-rs is_retryable_route_open_code for cross-client
+ * within ROUTE_OPEN_RETRY_DEADLINE_MS. Permanent rejections (module_removed,
+ * bad_consumer_identity, config_divergence, unknown_target, ...) are excluded — they are pre-send but
+ * would never succeed, so retrying them would only storm the daemon. In
+ * particular, capability_forbidden is an explicit non-retryable policy refusal.
+ * Kept byte-identical to subc-client-rs is_retryable_route_open_code for cross-client
  * classification parity.
  */
 export function isRetryableRouteOpenCode(code: string | undefined): boolean {
+  // A capability deny is policy, never a transient target-availability failure.
+  if (code === "capability_forbidden") return false;
   return (
     code === "unknown_module" ||
     code === "module_reloading" ||
@@ -1453,12 +1711,28 @@ function normalizeConnectOptions(opts: ConnectOptions): NormalizedConnectOptions
     targetKind: opts.targetKind ?? DEFAULT_MANAGED_TARGET_KIND,
     reconnectBackoff: opts.reconnectBackoff ?? DEFAULT_RECONNECT_BACKOFF,
     sleep: opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    routeOpenRetryDeadlineMs: opts.routeOpenRetryDeadlineMs ?? ROUTE_OPEN_RETRY_DEADLINE_MS,
     timeoutArbitrationGraceMs: opts.timeoutArbitrationGraceMs ?? TIMEOUT_ARBITRATION_GRACE_MS,
     livenessProbeWindowMs: opts.livenessProbeWindowMs ?? LIVENESS_PROBE_WINDOW_MS,
     onControlPush: opts.onControlPush,
   };
 }
 
+/** Validate the exact capability-grammar identifier before catalog I/O. */
+export function isValidCapabilityIdentifier(identifier: string): boolean {
+  if (/\s/u.test(identifier)) return false;
+  const separator = identifier.indexOf("/v");
+  if (separator <= 0 || identifier.indexOf("/v", separator + 1) !== -1) return false;
+  const name = identifier.slice(0, separator);
+  const version = identifier.slice(separator + 2);
+  if (new TextEncoder().encode(name).byteLength > 64 || version.length === 0) return false;
+  if (!/^[a-z][a-z0-9-]*[a-z0-9]$/u.test(name) && !/^[a-z]$/u.test(name)) return false;
+  if (name.includes("--")) return false;
+  if (!/^\d+$/u.test(version) || (version.length > 1 && version.startsWith("0"))) return false;
+  const numericVersion = Number(version);
+  return Number.isSafeInteger(numericVersion) && numericVersion >= 1 && numericVersion <= 0xffff_ffff;
+}
+
 function routeCacheKey(
   target: Extract<RouteTarget, { kind: ManagedRouteKind }>,
   identity: BindIdentity,

package/src/envelope.ts

@@ -50,7 +50,8 @@ const FLAG_PRIORITY_SHIFT = 1;
 const FLAG_LAST = 0b0000_1000;
 const FLAG_ADMISSION_MASK = 0b0011_0000;
 const FLAG_ADMISSION_SHIFT = 4;
-const FLAG_RESERVED_MASK = 0b1100_0000;
+export const DAEMON_ORIGIN_FLAG = 0x40;
+const FLAG_RESERVED_MASK = 0b1000_0000;
 
 /** Build flags from typed components. Admission defaults to NORMAL. */
 export function buildFlags(
@@ -71,6 +72,15 @@ export function admissionClass(flags: number): AdmissionClass {
   return ((flags & FLAG_ADMISSION_MASK) >> FLAG_ADMISSION_SHIFT) as AdmissionClass;
 }
 
+/** True when the body is opaque bytes rather than a JSON payload. */
+export function hasBinary(flags: number): boolean {
+  return (flags & FLAG_BINARY) !== 0;
+}
+
+export function hasDaemonOrigin(flags: number): boolean {
+  return (flags & DAEMON_ORIGIN_FLAG) !== 0;
+}
+
 export interface EnvelopeHeader {
   len: number;
   ver: number;

package/src/index.ts

@@ -6,17 +6,26 @@ export {
   SUBC_MODULE_ID_ENV,
   SUBC_LAUNCH_NONCE_ENV,
   isConsumerReconnectTransient,
+  parseRouteCloseReason,
+  classifyRouteCloseReason,
+  routeCloseReason,
+  isValidCapabilityIdentifier,
   connectionFileExists,
   type BindIdentity,
   type RouteTarget,
   type ManagedRouteKind,
   type ConsumerIdentity,
   type RouteOpenOptions,
+  type CatalogCapabilities,
+  type CatalogCapabilityRequirement,
   type CatalogEntry,
   type RequestOptions,
   type ManagedCallOptions,
   type ConnectOptions,
   type ControlPush,
+  type KnownRouteCloseReason,
+  type RouteCloseReason,
+  type RouteCloseDisposition,
   type ReconnectBackoff,
   type SubcCallErrorKind,
   type SubscribeOptions,
@@ -37,6 +46,7 @@ export {
   FrameType,
   Priority,
   AdmissionClass,
+  DAEMON_ORIGIN_FLAG,
   PROTOCOL_VERSION,
   HEADER_LEN,
   buildFrame,
@@ -44,6 +54,8 @@ export {
   buildFlags,
   encodeFrame,
   decodeHeader,
+  hasBinary,
+  hasDaemonOrigin,
   encodeHeader,
   DecodeError,
   type DecodeErrorCode,

package/src/provider.ts

@@ -352,6 +352,8 @@ export class SubcProviderError extends Error {
     message: string,
     readonly code?: string,
     readonly kind: SubcCallErrorKind = "terminal",
+    /** Wire `ErrorBody.detail` carried verbatim (typed refusal payloads). */
+    readonly detail?: unknown,
   ) {
     super(message);
   }
@@ -1222,11 +1224,12 @@ function routeKey(handle: RouteHandle, corr: bigint): string {
 
 function providerErrorFromFrame(frame: Frame): SubcProviderError {
   try {
-    const body = parseJson(frame.body) as { code?: string; message?: string };
+    const body = parseJson(frame.body) as { code?: string; message?: string; detail?: unknown };
     return new SubcProviderError(
       body.message ?? "subc error",
       body.code,
       body.code === "stale_route_epoch" || body.code === "unknown_channel" ? "not_sent" : "terminal",
+      body.detail,
     );
   } catch {
     return new SubcProviderError(Buffer.from(frame.body).toString("utf8") || "subc error");