@cortexkit/subc-client 0.8.0 → 0.11.0

package/dist/client.d.ts

@@ -30,15 +30,61 @@ export interface RouteOpenOptions {
     /** Optional consumer-declared reverse-request capabilities for this route.open. This is a declaration, not a verified privilege; providers must treat an omitted field as no reverse-request capability. Known MCP method-family values today are "elicitation", "sampling", and "roots". */
     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;
 }
@@ -106,6 +152,13 @@ export declare class SubcCallError extends Error {
     readonly code?: string | undefined;
     readonly cause?: unknown | undefined;
     constructor(kind: SubcCallErrorKind, message: string, code?: string | undefined, cause?: unknown | undefined);
+    /**
+     * 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;
 }
 /**
  * A live subscription to a provider's event stream, riding a single held-open
@@ -122,7 +175,21 @@ export interface Subscription {
 }
 export declare class SubcError extends Error {
     readonly code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
+    /**
+     * 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 | undefined;
+    constructor(message: string, code?: string | undefined, 
+    /**
+     * 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.
+     */
+    detail?: unknown | undefined);
 }
 export interface ConnectOptions {
     connectionFile: string;
@@ -135,6 +202,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.
@@ -171,6 +246,23 @@ export interface ControlPush {
     /** The full parsed body, `op` included, for op-specific fields. */
     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 declare function parseRouteCloseReason(reason: unknown): RouteCloseReason;
+/** Unknown close reasons take the strictest action and must not trigger a reopen. */
+export declare function classifyRouteCloseReason(reason: unknown): RouteCloseDisposition;
+/** Decode a close reason from a route lifecycle control push, if present. */
+export declare function routeCloseReason(push: ControlPush): RouteCloseReason | undefined;
 export declare class SubcClient {
     private sock;
     private currentConn;
@@ -193,6 +285,15 @@ export declare class SubcClient {
     static connect(opts: ConnectOptions): Promise<SubcClient>;
     /** List modules subc knows about (channel-0 catalog.list). */
     catalogList(moduleId?: string): Promise<CatalogEntry[]>;
+    /**
+     * 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.
+     */
+    resolveProvider(capability: string): Promise<string>;
+    /** Resolve every catalog claimant in deterministic module-id order. */
+    resolveProviders(capability: string): Promise<string[]>;
     /** Open a route and return its connection-bound immutable handle. */
     routeOpen(target: RouteTarget, identity: BindIdentity, opts?: RouteOpenOptions): Promise<RouteHandle>;
     /** Send a data-plane request on exactly the supplied route generation. */
@@ -202,6 +303,14 @@ export declare class SubcClient {
      * reconnecting and re-opening cached routes after connection drops.
      */
     call<Response = unknown>(moduleId: string, method: string, params?: unknown, opts?: ManagedCallOptions): Promise<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.
+     */
+    callBinary(moduleId: string, body: Uint8Array, opts?: ManagedCallOptions): Promise<Uint8Array | unknown>;
+    private managedCall;
     /** Open a held request on exactly one route generation. */
     subscribe(handle: RouteHandle, body: unknown, onEvent: (event: Uint8Array) => void, opts?: SubscribeOptions): Subscription;
     /** Send a pure-header cancellation for an in-flight request. */
@@ -257,11 +366,26 @@ export declare 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;
     private probeLivenessAfterDeadline;
     private ensureConnectedForManaged;
     private scheduleReconnectAfterDrop;
@@ -301,6 +425,8 @@ export declare class SubcClient {
     private allocateCorr;
     private closeConnectionAfterCleanupFailure;
     private encode;
+    /** Decode a terminal response according to the representation on the wire. */
+    private decodeReply;
     private parseJson;
 }
 export declare function isConsumerReconnectTransient(err: unknown): boolean;
@@ -310,12 +436,15 @@ export declare 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 declare function isRetryableRouteOpenCode(code: string | undefined): boolean;
 export declare function connectionFileExists(path: string): Promise<boolean>;
+/** Validate the exact capability-grammar identifier before catalog I/O. */
+export declare function isValidCapabilityIdentifier(identifier: string): boolean;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAeA,OAAO,EAA2C,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACpG,OAAO,EACL,cAAc,EAKd,QAAQ,EAET,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,WAAW,EAGZ,MAAM,mBAAmB,CAAC;AAsD3B,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,sNAAsN;IACtN,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC3C,6RAA6R;IAC7R,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,sNAAsN;IACtN,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,iBAAiB,GAAG,UAAU,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAEpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB;IAEhC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAHf,IAAI,EAAE,iBAAiB,EAChC,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,WAAW,IAAI,IAAI,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,qBAAa,SAAU,SAAQ,KAAK;IAGhC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;gBADtB,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,MAAM,YAAA;CAIzB;AAmBD,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,wFAAwF;IACxF,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,uDAAuD;IACvD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;OAMG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CAC7C;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAsCD,qBAAa,UAAU;IAmBnB,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IApBvB,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6C;IAC3E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,UAAU,CAAK;IAKvB,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO;IAQP,IAAI,IAAI,IAAI,cAAc,CAEzB;IAED,gFAAgF;WACnE,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAM/D,8DAA8D;IACxD,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAS3D,qEAAqE;IACjE,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;IAwC7G,0EAA0E;IACtE,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAS9F;;;OAGG;IACG,IAAI,CAAC,QAAQ,GAAG,OAAO,EAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,QAAQ,CAAC;IAyDlB,2DAA2D;IAC7D,SAAS,CACP,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACpC,IAAI,GAAE,gBAAqB,GAC1B,YAAY;IAiDf,gEAAgE;IAChE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,QAA+B,GAAG,IAAI;IAa1F,yEAAyE;IACnE,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC;IAgBjF,uDAAuD;IACnD,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAelF,qEAAqE;IAC/D,iBAAiB,CACrB,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAA;KAAE,CAAC,EACxD,QAAQ,EAAE,YAAY,EACtB,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC,IAAI,CAAC;IAWd,+GAA+G;IAC3G,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzF,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,gBAAgB;mBAqBH,cAAc;YAcrB,UAAU;IAQxB,OAAO,CAAC,IAAI;IAkDZ;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;YA2BV,cAAc;IAa5B,OAAO,CAAC,WAAW;YAsEL,iBAAiB;YAqCjB,eAAe;IAoD7B,OAAO,CAAC,eAAe,CAAK;IAE5B,OAAO,CAAC,aAAa,CAA8B;IAEnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,0BAA0B;YAuCpB,yBAAyB;IAMvC,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,kBAAkB;YAWZ,kBAAkB;IAsChC,OAAO,CAAC,iBAAiB;YAaX,kBAAkB;IAoBhC,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,qBAAqB;YAIf,QAAQ;IAwBtB,OAAO,CAAC,QAAQ;IA0HhB;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,oBAAoB;IAM5B,qFAAqF;IACrF,IAAI,oBAAoB,IAAI,MAAM,CAEjC;IAED,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,kCAAkC;IAO1C,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,SAAS;CAIlB;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAkBlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQ1E;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzE"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -12,7 +12,7 @@ import { promises as fs } from "node:fs";
 import { debuglog } from "node:util";
 import { AuthError, authenticateClient } from "./auth.js";
 import { ConnectionFileError, readConnectionFile } from "./connection-file.js";
-import { AdmissionClass, buildFrame, buildFlags, encodeFrame, FrameType, Priority, } from "./envelope.js";
+import { AdmissionClass, buildFrame, buildFlags, encodeFrame, FrameType, hasBinary, Priority, } from "./envelope.js";
 import { belongsToConnection, createRouteHandle, newConnectionToken, sameRouteHandle, StaleRouteHandleError, } from "./route-handle.js";
 import { SocketClosedError, SocketTimeoutError, SocketWriteNotQueuedError, SocketWriteQueuedError, SubcSocket, writeBorrowed, writeTrackedBorrowed, } from "./socket.js";
 const debug = debuglog("subc-client");
@@ -89,14 +89,75 @@ export class SubcCallError extends Error {
         this.cause = cause;
         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() {
+        return this.cause instanceof SubcError ? this.cause.detail : undefined;
+    }
 }
 export class SubcError extends Error {
     code;
-    constructor(message, code) {
+    detail;
+    constructor(message, code, 
+    /**
+     * 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.
+     */
+    detail) {
         super(message);
         this.code = code;
+        this.detail = detail;
+    }
+}
+function requireBinaryBody(body) {
+    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");
+}
+/**
+ * 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) {
+    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) {
+    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) {
+    if (push.op !== "route.closing" && push.op !== "route.closed")
+        return undefined;
+    return parseRouteCloseReason(push.body.reason);
+}
 export class SubcClient {
     sock;
     currentConn;
@@ -139,6 +200,33 @@ export class SubcClient {
         const parsed = this.parseJson(reply);
         return parsed.modules ?? [];
     }
+    /**
+     * 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) {
+        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) {
+        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, identity, opts = {}) {
         const consumerIdentity = routeOpenConsumerIdentity(opts);
@@ -185,23 +273,40 @@ export class SubcClient {
     /** Send a data-plane request on exactly the supplied route generation. */
     async request(handle, body, opts = {}) {
         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);
     }
     /**
      * Managed route + request convenience. Opens and caches a route for the module,
      * reconnecting and re-opening cached routes after connection drops.
      */
     async call(moduleId, method, params, opts = {}) {
+        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));
+    }
+    /**
+     * 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, body, opts = {}) {
+        const bytes = requireBinaryBody(body);
+        return this.managedCall(moduleId, bytes, { ...opts, binary: true });
+    }
+    async managedCall(moduleId, body, opts) {
         let retriedUnknownChannel = false;
         for (;;) {
             const routeHandle = await this.cachedRouteHandle(moduleId, opts);
             try {
-                return (await this.managedRequest(routeHandle, body, opts));
+                return await this.managedRequest(routeHandle, body, opts);
             }
             catch (err) {
                 if (!(err instanceof SubcCallError))
@@ -408,7 +513,7 @@ export class SubcClient {
     async controlRpc(body, acceptFrame, onLateResponse) {
         return this.send(null, body, Priority.Interactive, AdmissionClass.Normal, undefined, undefined, acceptFrame, onLateResponse);
     }
-    send(handle, body, priority, admission, timeoutMs, onProgress, acceptFrame, onLateResponse) {
+    send(handle, body, priority, admission, timeoutMs, onProgress, acceptFrame, onLateResponse, binary = false) {
         if (handle)
             this.assertLiveHandle(handle);
         if (this.closedErr)
@@ -423,7 +528,7 @@ export class SubcClient {
         const key = pendingKey(handle, corr);
         const channel = handle?.channel ?? 0;
         const epoch = handle?.epoch ?? 0;
-        const frame = buildFrame(FrameType.Request, buildFlags(false, priority, false, admission), channel, epoch, corr, body);
+        const frame = buildFrame(FrameType.Request, buildFlags(binary, priority, false, admission), channel, epoch, corr, body);
         return new Promise((resolve, reject) => {
             const ms = timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
             const pending = {
@@ -479,12 +584,13 @@ export class SubcClient {
         setImmediate(arbitrate);
     }
     async managedRequest(handle, body, opts) {
-        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)
@@ -492,7 +598,7 @@ export class SubcClient {
             throw this.terminalCallError("managed call failed", error);
         }
     }
-    sendManaged(handle, body, priority, admission, timeoutMs, onProgress) {
+    sendManaged(handle, body, priority, admission, timeoutMs, onProgress, binary = false) {
         try {
             this.assertLiveHandle(handle);
         }
@@ -510,7 +616,7 @@ export class SubcClient {
             return Promise.reject(this.notSentCallError("request correlation allocator was exhausted", error));
         }
         const key = pendingKey(handle, corr);
-        const frame = buildFrame(FrameType.Request, buildFlags(false, priority, false, admission), handle.channel, handle.epoch, corr, body);
+        const frame = buildFrame(FrameType.Request, buildFlags(binary, priority, false, admission), handle.channel, handle.epoch, corr, body);
         let handedToSocket = false;
         const classifyFailure = (error) => {
             if (!handedToSocket)
@@ -572,7 +678,7 @@ export class SubcClient {
         return cached.opening;
     }
     async openCachedRoute(cached) {
-        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 (;;) {
@@ -611,13 +717,20 @@ 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)`, error);
+                    throw this.notSentCallError(`route.open failed for module ${cached.moduleId}: ${error.code} (retry deadline exhausted after ${routeRetryAttempt} attempts)`, error);
                 }
                 throw this.terminalCallError(`route.open failed for module ${cached.moduleId}`, error);
             }
@@ -645,14 +758,37 @@ 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). */
+    hasControlPending() {
+        for (const pending of this.pending.values()) {
+            if (pending.handle === null)
+                return true;
+        }
+        return false;
+    }
     probeLivenessAfterDeadline() {
         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;
@@ -674,6 +810,10 @@ export class SubcClient {
                 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`));
             sock.close();
         })().finally(() => {
@@ -814,6 +954,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
@@ -949,7 +1096,7 @@ export class SubcClient {
     errorFromFrame(frame) {
         try {
             const parsed = JSON.parse(Buffer.from(frame.body).toString("utf8"));
-            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");
@@ -1034,6 +1181,10 @@ export class SubcClient {
     encode(value) {
         return Buffer.from(JSON.stringify(value), "utf8");
     }
+    /** Decode a terminal response according to the representation on the wire. */
+    decodeReply(frame) {
+        return hasBinary(frame.header.flags) ? frame.body : this.parseJson(frame);
+    }
     parseJson(frame) {
         const b = frame.body;
         return JSON.parse(Buffer.from(b.buffer, b.byteOffset, b.byteLength).toString("utf8"));
@@ -1068,13 +1219,17 @@ export function isConsumerReconnectTransient(err) {
  * 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) {
+    // A capability deny is policy, never a transient target-availability failure.
+    if (code === "capability_forbidden")
+        return false;
     return (code === "unknown_module" ||
         code === "module_reloading" ||
         code === "module_warming" ||
@@ -1098,11 +1253,32 @@ function normalizeConnectOptions(opts) {
         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) {
+    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, identity, consumerIdentity) {
     const consumerPart = consumerIdentity
         ? `${consumerIdentity.module_id}\0${consumerIdentity.launch_nonce}`