@query-farm/vgi-rpc 0.7.0 → 0.7.1

package/dist/launcher/serve-unix.d.ts

@@ -37,6 +37,7 @@ export interface ServeUnixOptions {
 }
 /** Handle returned by {@link serveUnix} for callers that want to stop the server. */
 export interface ServeUnixHandle {
+    /** Absolute path of the bound AF_UNIX socket the server is listening on. */
     readonly socketPath: string;
     /** Shut down the listener and unlink the socket file. */
     stop(): Promise<void>;

package/dist/launcher/serve-unix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve-unix.d.ts","sourceRoot":"","sources":["../../src/launcher/serve-unix.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAEL,KAAK,YAAY,EAGjB,KAAK,cAAc,EAEpB,MAAM,aAAa,CAAC;AAQrB,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB;4EACwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;wDAEoD;IACpD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gDAAgD;IAChD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,qEAAqE;IACrE,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B;wCACoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;4DAEwD;IACxD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;4BACwB;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;0EACsE;IACtE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiSvG"}
+{"version":3,"file":"serve-unix.d.ts","sourceRoot":"","sources":["../../src/launcher/serve-unix.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAEL,KAAK,YAAY,EAGjB,KAAK,cAAc,EAEpB,MAAM,aAAa,CAAC;AAQrB,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB;4EACwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;wDAEoD;IACpD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gDAAgD;IAChD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,qEAAqE;IACrE,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B;wCACoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;4DAEwD;IACxD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;4BACwB;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;0EACsE;IACtE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiSvG"}

package/dist/launcher/state.d.ts

@@ -1,10 +1,14 @@
 import { computeHash } from "./hash.js";
 /** Filesystem layout for one worker tuple: `<state_dir>/<hash>.{lock,sock,meta}`. */
 export interface SocketPaths {
+    /** Advisory lockfile path (`<hash>.lock`) guarding launch + liveness. */
     lockPath: string;
+    /** AF_UNIX socket path (`<hash>.sock`) the worker binds. */
     sockPath: string;
+    /** Launch-metadata JSON path (`<hash>.meta`) read by `--status`. */
     metaPath: string;
 }
+/** Derive the lock/sock/meta path triple for a worker `hashId` under `stateDir`. */
 export declare function socketPaths(stateDir: string, hashId: string): SocketPaths;
 /**
  * Resolve the per-user state directory used for lockfiles + sockets.
@@ -21,14 +25,22 @@ export declare function socketPaths(stateDir: string, hashId: string): SocketPat
 export declare function defaultStateDir(): string;
 /** Best-effort write of human-readable launch metadata.  Used by `--status`. */
 export declare function writeMeta(metaPath: string, workerArgv: readonly string[], cwd: string, sockPath: string): void;
+/** One row of `--status` output describing a launched worker tuple. */
 export interface StatusRow {
+    /** Canonical hash identifying the worker tuple (the `<hash>` filename stem). */
     hashId: string;
+    /** Worker argv recorded at launch, or `[]` when the meta file is missing. */
     cmd: string[];
+    /** Working directory recorded at launch, or `""` when unknown. */
     cwd: string;
+    /** AF_UNIX socket path the worker binds. */
     socket: string;
+    /** Unix epoch seconds the worker was launched, or `null` when unknown. */
     startedAt: number | null;
+    /** Whether a probe connection to {@link StatusRow.socket} currently succeeds. */
     alive: boolean;
 }
+/** Outcome of a {@link gcStateDir} sweep. */
 export interface GcResult {
     /** Hash IDs of stale entries that were removed. */
     cleaned: string[];

package/dist/launcher/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/launcher/state.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,qFAAqF;AACrF,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAMzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,IAAI,MAAM,CA+BxC;AAMD,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAa9G;AAMD,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;4BACwB;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,iEAAiE;AACjE,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAqBtF;AAgBD,gFAAgF;AAChF,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAwBvE;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,EAC9D,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,OAAO,CAAC,QAAQ,CAAC,CA8CnB;AAED;0BAC0B;AAC1B,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/launcher/state.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,qFAAqF;AACrF,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAMzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,IAAI,MAAM,CA+BxC;AAMD,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAa9G;AAMD,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;4BACwB;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,iEAAiE;AACjE,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAqBtF;AAgBD,gFAAgF;AAChF,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAwBvE;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,EAC9D,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,OAAO,CAAC,QAAQ,CAAC,CA8CnB;AAED;0BAC0B;AAC1B,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/protocol.d.ts

@@ -5,6 +5,7 @@ import { type ExchangeFn, type ExchangeInit, type HeaderInit, type MethodDefinit
  * Register unary, producer, and exchange methods, then pass to `VgiRpcServer`.
  */
 export declare class Protocol {
+    /** Service / protocol name, exposed to clients via introspection. */
     readonly name: string;
     /**
      * Application protocol surface version. When non-empty, the server enforces
@@ -71,6 +72,8 @@ export declare class Protocol {
         defaults?: Record<string, any>;
         paramTypes?: Record<string, string>;
     }): this;
+    /** Snapshot of the registered methods, keyed by method name. Returns a copy,
+     *  so mutating it does not affect the protocol. */
     getMethods(): Map<string, MethodDefinition>;
 }
 //# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmB,KAAK,UAAU,EAAY,MAAM,aAAa,CAAC;AACzE,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,gBAAgB,EAErB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAIpB;;;GAGG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,iEAAiE;IACjE,QAAQ,CAAC,oBAAoB,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACxE,OAAO,CAAC,QAAQ,CAA4C;gBAEhD,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE;IAYhE;;;;;;;;;OASG;IACH,KAAK,CACH,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QACN,MAAM,EAAE,UAAU,CAAC;QACnB,MAAM,EAAE,UAAU,CAAC;QACnB,OAAO,EAAE,YAAY,CAAC;QACtB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,GACA,IAAI;IAeP;;;OAGG;IACH,QAAQ,CAAC,CAAC,EACR,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QACN,MAAM,EAAE,UAAU,CAAC;QACnB,YAAY,EAAE,UAAU,CAAC;QACzB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QACtB,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACvB,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACzB,YAAY,CAAC,EAAE,UAAU,CAAC;QAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,GACA,IAAI;IAqBP;;;OAGG;IACH,QAAQ,CAAC,CAAC,EACR,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QACN,MAAM,EAAE,UAAU,CAAC;QACnB,WAAW,EAAE,UAAU,CAAC;QACxB,YAAY,EAAE,UAAU,CAAC;QACzB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QACtB,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACzB,YAAY,CAAC,EAAE,UAAU,CAAC;QAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,GACA,IAAI;IAqBP,UAAU,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;CAG5C"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmB,KAAK,UAAU,EAAY,MAAM,aAAa,CAAC;AACzE,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,gBAAgB,EAErB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAIpB;;;GAGG;AACH,qBAAa,QAAQ;IACnB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,iEAAiE;IACjE,QAAQ,CAAC,oBAAoB,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACxE,OAAO,CAAC,QAAQ,CAA4C;gBAEhD,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE;IAYhE;;;;;;;;;OASG;IACH,KAAK,CACH,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QACN,MAAM,EAAE,UAAU,CAAC;QACnB,MAAM,EAAE,UAAU,CAAC;QACnB,OAAO,EAAE,YAAY,CAAC;QACtB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,GACA,IAAI;IAeP;;;OAGG;IACH,QAAQ,CAAC,CAAC,EACR,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QACN,MAAM,EAAE,UAAU,CAAC;QACnB,YAAY,EAAE,UAAU,CAAC;QACzB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QACtB,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACvB,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACzB,YAAY,CAAC,EAAE,UAAU,CAAC;QAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,GACA,IAAI;IAqBP;;;OAGG;IACH,QAAQ,CAAC,CAAC,EACR,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QACN,MAAM,EAAE,UAAU,CAAC;QACnB,WAAW,EAAE,UAAU,CAAC;QACxB,YAAY,EAAE,UAAU,CAAC;QACzB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QACtB,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACzB,YAAY,CAAC,EAAE,UAAU,CAAC;QAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,GACA,IAAI;IAqBP;uDACmD;IACnD,UAAU,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;CAG5C"}

package/dist/types.d.ts

@@ -1,7 +1,13 @@
 import { type VgiBatch, type VgiSchema } from "./arrow/index.js";
 import { AuthContext } from "./auth.js";
+/**
+ * Whether an RPC method is request/response or streaming. Mirrors Python's
+ * `MethodType` and is carried in the `__describe__` payload.
+ */
 export declare enum MethodType {
+    /** Single request batch in, single result batch out. */
     UNARY = "unary",
+    /** Streamed batches — either a producer or an exchange stream. */
     STREAM = "stream"
 }
 /**
@@ -19,8 +25,11 @@ export declare enum MethodType {
  * - `UNIX` — AF_UNIX socket handler (the launcher path).
  */
 export declare enum TransportKind {
+    /** Stdio worker — the standalone {@link VgiRpcServer} loop. */
     PIPE = "pipe",
+    /** Fetch-style HTTP handler (`createHttpHandler`). */
     HTTP = "http",
+    /** AF_UNIX socket handler (the launcher path). */
     UNIX = "unix"
 }
 /**
@@ -38,6 +47,9 @@ export declare enum TransportKind {
 export type ServeStartHook = (kind: TransportKind) => void | Promise<void>;
 /** Logging interface available to handlers. */
 export interface LogContext {
+    /** Emit a client-directed log message (sent as a zero-row log batch on the
+     *  wire). `level` is a severity label such as `"info"`, `"warning"`, or
+     *  `"error"`; `extra` carries optional structured string key/value pairs. */
     clientLog(level: string, message: string, extra?: Record<string, string>): void;
 }
 /**
@@ -78,6 +90,8 @@ export interface StickyContext {
 }
 /** Extended context with authentication info, available to handlers. */
 export interface CallContext extends LogContext {
+    /** Authenticated principal for this call; {@link AuthContext.anonymous} when
+     *  the request was not authenticated. */
     readonly auth: AuthContext;
     /** Coarse identifier of the bound transport, or `undefined` until the
      *  server begins serving (the value is committed by the lifecycle hook
@@ -157,23 +171,47 @@ export type HeaderInit = (params: Record<string, any>, state: any, ctx: LogConte
  * objects a chance to release resources. Errors are logged and swallowed.
  */
 export type OnCancelFn<S = any> = (state: S) => Promise<void> | void;
+/**
+ * In-memory definition of one registered RPC method, produced by the
+ * {@link Protocol} builder and consumed by the dispatch layer. Which optional
+ * fields are populated depends on the method {@link type}: `handler` for unary
+ * methods, `producerInit`/`producerFn` for producer streams, and
+ * `exchangeInit`/`exchangeFn` for exchange streams.
+ */
 export interface MethodDefinition {
+    /** Method name as registered on the protocol. */
     name: string;
+    /** Whether the method is unary or streaming. */
     type: MethodType;
+    /** Schema of the request parameters batch. */
     paramsSchema: VgiSchema;
+    /** Schema of the unary result batch (unused for streams). */
     resultSchema: VgiSchema;
+    /** Schema of streamed output batches (producer and exchange streams). */
     outputSchema?: VgiSchema;
+    /** Schema of streamed input batches (exchange streams only). */
     inputSchema?: VgiSchema;
+    /** Implementation for unary methods. */
     handler?: UnaryHandler;
+    /** Builds the initial state object for a producer stream. */
     producerInit?: ProducerInit;
+    /** Produces output batches for a producer stream. */
     producerFn?: ProducerFn;
+    /** Builds the initial state object for an exchange stream. */
     exchangeInit?: ExchangeInit;
+    /** Handles each input batch of an exchange stream. */
     exchangeFn?: ExchangeFn;
+    /** Schema of the optional per-stream header batch. */
     headerSchema?: VgiSchema;
+    /** Builds the optional header batch emitted before the first output batch. */
     headerInit?: HeaderInit;
+    /** Optional hook run when the client cancels a stream. */
     onCancel?: OnCancelFn;
+    /** Human-readable method documentation, surfaced via introspection. */
     doc?: string;
+    /** Default values applied to omitted request parameters. */
     defaults?: Record<string, any>;
+    /** Human-readable parameter type names, surfaced via introspection. */
     paramTypes?: Record<string, string>;
 }
 /** Metadata passed to dispatch hooks before and after RPC method execution. */
@@ -219,11 +257,17 @@ export interface DispatchInfo {
 }
 /** Per-call I/O counters, matching Python's CallStatistics. */
 export interface CallStatistics {
+    /** Number of input batches read from the client. */
     inputBatches: number;
+    /** Number of output batches written to the client. */
     outputBatches: number;
+    /** Total rows across all input batches. */
     inputRows: number;
+    /** Total rows across all output batches. */
     outputRows: number;
+    /** Total serialized bytes of all input batches. */
     inputBytes: number;
+    /** Total serialized bytes of all output batches. */
     outputBytes: number;
 }
 /** Opaque token returned by onDispatchStart, passed back to onDispatchEnd. */
@@ -233,7 +277,11 @@ export type HookToken = unknown;
  * Implementations must be safe for concurrent use (HTTP transport is concurrent).
  */
 export interface DispatchHook {
+    /** Invoked before the method runs. The returned {@link HookToken} is opaque
+     *  to the framework and passed back to {@link onDispatchEnd}. */
     onDispatchStart(info: DispatchInfo): HookToken;
+    /** Invoked after the method completes or throws. `stats` carries the per-call
+     *  I/O counters; `error` is set only when the dispatch failed. */
     onDispatchEnd(token: HookToken, info: DispatchInfo, stats: CallStatistics, error?: Error): void;
 }
 export interface EmittedBatch {
@@ -255,6 +303,8 @@ export declare class OutputCollector implements CallContext {
     private _cookieSinkEnabled;
     private _responseCookies;
     private _stickyContext;
+    /** Authenticated principal for this call; {@link AuthContext.anonymous} when
+     *  the request was not authenticated. */
     readonly auth: AuthContext;
     readonly cookies: ReadonlyMap<string, string>;
     readonly kind?: TransportKind;
@@ -294,8 +344,12 @@ export declare class OutputCollector implements CallContext {
     get sessionId(): string | null;
     openSession(state: unknown, ttl?: number): void;
     closeSession(): void;
+    /** Schema of the data batches this collector emits. */
     get outputSchema(): VgiSchema;
+    /** True once {@link finish} has been called (producer streams only). */
     get finished(): boolean;
+    /** Batches emitted so far this call — the single data batch plus any log
+     *  batches, in emission order. Consumed by the dispatch layer. */
     get batches(): EmittedBatch[];
     /** Emit a pre-built batch as the data batch for this call. */
     emit(batch: VgiBatch, metadata?: Map<string, string>): void;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi-rpc",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "license": "Apache-2.0",
   "homepage": "https://vgi-rpc-typescript.query.farm",
   "repository": {
@@ -49,10 +49,10 @@
   },
   "dependencies": {
     "@noble/ciphers": "^2.2.0",
-    "@query-farm/apache-arrow": "*",
+    "@query-farm/apache-arrow": "^21.1.1",
     "@uwdata/flechette": "github:Query-farm/flechette#fix/timestamp-bigint-encode",
     "fzstd": "^0.1.1",
-    "oauth4webapi": "^3.8.5"
+    "oauth4webapi": "^3.8.6"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.4.0",
@@ -75,15 +75,15 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.5",
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/resources": "^2.6.0",
-    "@opentelemetry/sdk-metrics": "^2.6.0",
-    "@opentelemetry/sdk-trace-base": "^2.6.0",
-    "@opentelemetry/semantic-conventions": "^1.40.0",
-    "@aws-sdk/client-s3": "^3.750.0",
-    "@aws-sdk/s3-request-presigner": "^3.750.0",
-    "@google-cloud/storage": "^7.15.0",
+    "@biomejs/biome": "^2.4.16",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-metrics": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "@aws-sdk/client-s3": "^3.1059.0",
+    "@aws-sdk/s3-request-presigner": "^3.1059.0",
+    "@google-cloud/storage": "^7.19.0",
     "@types/bun": "latest"
   },
   "scripts": {

package/src/access-log.ts

@@ -18,6 +18,7 @@ import type { CallStatistics, DispatchHook, DispatchInfo, HookToken } from "./ty
 
 /** Where the hook writes formatted JSON lines. */
 export interface AccessLogSink {
+  /** Write one access-log line. The trailing newline is included by the caller. */
   write(line: string): void;
 }
 
@@ -39,6 +40,7 @@ function _loadWriteSync(): (fd: number, data: Uint8Array, offset?: number, len?:
 export class FdSink implements AccessLogSink {
   private readonly _writeSync = _loadWriteSync();
   constructor(private readonly fd: number) {}
+  /** Write `line` to the file descriptor, looping until the buffer is fully flushed. */
   write(line: string): void {
     const buf = new TextEncoder().encode(line);
     let offset = 0;
@@ -112,11 +114,14 @@ export class AccessLogHook implements DispatchHook {
     }
   }
 
+  /** Capture a high-resolution start timestamp; returned token feeds {@link onDispatchEnd}. */
   onDispatchStart(_info: DispatchInfo): HookToken {
     const token: StartToken = { startNs: process.hrtime.bigint() };
     return token;
   }
 
+  /** Emit one access-log JSON record for the completed dispatch (best-effort;
+   *  write errors are swallowed so logging never breaks a request). */
   onDispatchEnd(token: HookToken, info: DispatchInfo, stats: CallStatistics, error?: Error): void {
     const t = token as StartToken | undefined;
     const durationMs = t ? roundTo2(Number(process.hrtime.bigint() - t.startNs) / 1_000_000) : 0;

package/src/auth.ts

@@ -5,9 +5,14 @@ import { RpcError } from "./errors.js";
 
 /** Authentication context available to RPC handlers. */
 export class AuthContext {
+  /** Authentication domain/realm that vouched for the principal; empty string
+   *  when anonymous. */
   readonly domain: string;
+  /** True when the request carried valid credentials. */
   readonly authenticated: boolean;
+  /** Authenticated principal identifier, or `null` when anonymous. */
   readonly principal: string | null;
+  /** Arbitrary verified claims about the principal (e.g. decoded JWT claims). */
   readonly claims: Record<string, any>;
 
   constructor(domain: string, authenticated: boolean, principal: string | null, claims: Record<string, any> = {}) {

package/src/client/connect.ts

@@ -26,13 +26,23 @@ import { externalizeRequestBody } from "./uploadUrl.js";
 type CompressFn = (data: Uint8Array, level: number) => Promise<Uint8Array>;
 type DecompressFn = (data: Uint8Array) => Promise<Uint8Array>;
 
+/** A connected RPC client, returned by {@link httpConnect}, {@link pipeConnect}, and {@link subprocessConnect}. */
 export interface RpcClient {
+  /** Invoke a unary method. Returns the single result row, or `null` for void methods. Parameter defaults from `__describe__` are applied automatically. */
   call(method: string, params?: Record<string, any>): Promise<Record<string, any> | null>;
+  /** Open a streaming method, returning a {@link StreamSession} for exchange or producer iteration. */
   stream(method: string, params?: Record<string, any>): Promise<StreamSession>;
+  /** Fetch the server's method/protocol description (cached after the first call). */
   describe(): Promise<ServiceDescription>;
+  /** Release transport resources; for subprocess clients this also terminates the child process. */
   close(): void;
 }
 
+/**
+ * Connect to a vgi-rpc server over HTTP. The returned client lazily introspects
+ * the server (caching `__describe__`) on the first call and transparently handles
+ * zstd compression, authorization, and 413 request externalization.
+ */
 export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcClient {
   const prefix = (options?.prefix ?? "").replace(/\/+$/, "");
   const onLog = options?.onLog;

package/src/client/introspect.ts

@@ -9,25 +9,39 @@ import { ARROW_CONTENT_TYPE } from "../http/common.js";
 import { buildRequestIpc, dispatchLogOrError, readResponseBatches } from "./ipc.js";
 import type { LogMessage } from "./types.js";
 
+/** Describes a single RPC method as reported by the server's `__describe__` response. */
 export interface MethodInfo {
+  /** The method name as invoked by {@link RpcClient.call} / {@link RpcClient.stream}. */
   name: string;
+  /** Whether the method is a single request/response (`unary`) or a streaming method (`stream`). */
   type: "unary" | "stream";
+  /** Arrow schema of the call parameters. */
   paramsSchema: Schema;
+  /** Arrow schema of a unary result; for stream methods this holds the per-batch output schema. */
   resultSchema: Schema;
+  /** Arrow schema of the per-batch input rows for exchange streams, when available. */
   inputSchema?: Schema;
+  /** Arrow schema of the per-batch output rows for stream methods, when available. */
   outputSchema?: Schema;
+  /** Arrow schema of the stream's one-time header row, when the method declares one. */
   headerSchema?: Schema;
+  /** Human-readable documentation for the method, if the server provides it. */
   doc?: string;
+  /** Per-parameter human-readable type names, if the server provides them. */
   paramTypes?: Record<string, string>;
+  /** Default values applied to omitted parameters before a call is sent. */
   defaults?: Record<string, any>;
 }
 
+/** The full set of methods and protocol metadata reported by a server's `__describe__`. */
 export interface ServiceDescription {
+  /** The server's declared protocol/service name. */
   protocolName: string;
   /** Application protocol surface version surfaced by the server's
    *  __describe__ response. Empty string when the server did not declare
    *  a `protocolVersion`. */
   protocolVersion: string;
+  /** Every method the server exposes (excluding the built-in `__describe__`). */
   methods: MethodInfo[];
 }
 

package/src/client/oauth.ts

@@ -3,14 +3,23 @@
 
 /** RFC 9728 OAuth Protected Resource Metadata (client-side response). */
 export interface OAuthResourceMetadataResponse {
+  /** The protected resource's canonical URL (`resource`). */
   resource: string;
+  /** Authorization-server issuer URLs; the first is used for OIDC discovery (`authorization_servers`). */
   authorizationServers: string[];
+  /** Scopes the resource advertises (`scopes_supported`). */
   scopesSupported?: string[];
+  /** Advertised bearer methods, e.g. `["header"]` (`bearer_methods_supported`). */
   bearerMethodsSupported?: string[];
+  /** JWS algorithms the resource accepts (`resource_signing_alg_values_supported`). */
   resourceSigningAlgValuesSupported?: string[];
+  /** Human-readable resource name (`resource_name`). */
   resourceName?: string;
+  /** Documentation URL for the resource (`resource_documentation`). */
   resourceDocumentation?: string;
+  /** Policy URL for the resource (`resource_policy_uri`). */
   resourcePolicyUri?: string;
+  /** Terms-of-service URL for the resource (`resource_tos_uri`). */
   resourceTosUri?: string;
   /** OAuth client_id advertised by the server. */
   clientId?: string;

package/src/client/pipe.ts

@@ -75,6 +75,13 @@ class PipeIncrementalWriter {
 // PipeStreamSession — lockstep streaming over pipes
 // ---------------------------------------------------------------------------
 
+/**
+ * {@link StreamSession} implementation for the pipe/subprocess transport.
+ * Drives lockstep streaming over a single bidirectional pipe: each
+ * {@link PipeStreamSession.exchange} or iteration step writes one input batch
+ * and reads one output batch. Holds the connection's single-threaded busy lock
+ * until closed.
+ */
 export class PipeStreamSession implements StreamSession {
   private _reader: IpcStreamReader;
   private _writeFn: WriteFn;
@@ -109,6 +116,7 @@ export class PipeStreamSession implements StreamSession {
     this._externalConfig = opts.externalConfig;
   }
 
+  /** The stream's one-time header row, or `null` if the method declares no header. */
   get header(): Record<string, any> | null {
     return this._header;
   }
@@ -335,6 +343,11 @@ export class PipeStreamSession implements StreamSession {
     }
   }
 
+  /**
+   * End the stream: close the input side (or send an empty stream if nothing
+   * was sent yet) and drain the server's remaining output in the background,
+   * releasing the connection's busy lock once the drain completes.
+   */
   close(): void {
     if (this._closed) return;
     this._closed = true;
@@ -377,6 +390,12 @@ export class PipeStreamSession implements StreamSession {
 // pipeConnect — create an RpcClient over raw readable/writable streams
 // ---------------------------------------------------------------------------
 
+/**
+ * Connect to a vgi-rpc server over a raw bidirectional pipe (a readable stream
+ * of server output plus a writable for client input). The connection is
+ * single-threaded: only one call or stream may be in flight at a time. The
+ * `__describe__` handshake is sent before the reader is opened to avoid deadlock.
+ */
 export function pipeConnect(
   readable: ReadableStream<Uint8Array>,
   writable: PipeWritable,
@@ -616,6 +635,11 @@ export function pipeConnect(
 // subprocessConnect — spawn a process and wrap with pipeConnect
 // ---------------------------------------------------------------------------
 
+/**
+ * Spawn a server process (via `Bun.spawn`) and connect to it over its
+ * stdin/stdout using {@link pipeConnect}. The returned client's
+ * {@link RpcClient.close} also kills the subprocess.
+ */
 export function subprocessConnect(cmd: string[], options?: SubprocessConnectOptions): RpcClient {
   const proc = Bun.spawn(cmd, {
     stdin: "pipe",

package/src/client/stream.ts

@@ -19,6 +19,12 @@ type DecompressFn = (data: Uint8Array) => Promise<Uint8Array>;
  */
 export type PostFn = (url: string, body: Uint8Array) => Promise<Response>;
 
+/**
+ * {@link StreamSession} implementation for the HTTP transport. Stream state is
+ * carried statelessly across requests via an HMAC state token: each
+ * {@link HttpStreamSession.exchange} or producer-continuation POST sends the
+ * current token and receives the next one in the response metadata.
+ */
 export class HttpStreamSession implements StreamSession {
   private _baseUrl: string;
   private _prefix: string;
@@ -82,6 +88,7 @@ export class HttpStreamSession implements StreamSession {
     });
   }
 
+  /** The stream's one-time header row, or `null` if the method declares no header. */
   get header(): Record<string, any> | null {
     return this._header;
   }
@@ -305,6 +312,7 @@ export class HttpStreamSession implements StreamSession {
     return this._readResponse(resp);
   }
 
+  /** No-op: the HTTP transport is stateless, so there is nothing to tear down. */
   close(): void {
     // No-op for HTTP (stateless)
   }

package/src/client/types.ts

@@ -1,9 +1,13 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+/** Options for {@link httpConnect}, the HTTP-transport RPC client. */
 export interface HttpConnectOptions {
+  /** Route prefix the server mounts its methods under (e.g. `/api`). Trailing slashes are stripped. Defaults to no prefix. */
   prefix?: string;
+  /** Callback invoked for each log/error message the server emits during a request. */
   onLog?: (msg: LogMessage) => void;
+  /** When set, request bodies are zstd-compressed at this level and `Accept-Encoding: zstd` is sent. Omit to disable compression. */
   compressionLevel?: number;
   /** Authorization header value (e.g. "Bearer <token>"). Sent with every request. */
   authorization?: string;
@@ -11,27 +15,46 @@ export interface HttpConnectOptions {
   externalLocation?: import("../external.js").ExternalLocationConfig;
 }
 
+/** A log or error message delivered to an {@link HttpConnectOptions.onLog} callback. */
 export interface LogMessage {
+  /** Severity, mirroring the server's log level (e.g. `INFO`, `WARNING`, `EXCEPTION`). */
   level: string;
+  /** The human-readable log text. */
   message: string;
+  /** Optional structured fields attached to the log record. */
   extra?: Record<string, any>;
 }
 
+/**
+ * A live streaming method call. Exchange methods drive the server with
+ * {@link StreamSession.exchange}; producer methods are consumed by async
+ * iteration. Always {@link StreamSession.close} when done.
+ */
 export interface StreamSession {
+  /** The method's header row (returned once at stream start), or `null` if the method declares no header. */
   readonly header: Record<string, any> | null;
+  /** Send one batch of input rows and receive the server's corresponding output rows (exchange streams). */
   exchange(input: Record<string, any>[]): Promise<Record<string, any>[]>;
+  /** Iterate the server-produced output batches one row-array at a time (producer streams). */
   [Symbol.asyncIterator](): AsyncIterableIterator<Record<string, any>[]>;
+  /** Tear down the stream, flushing/draining the underlying transport. */
   close(): void;
 }
 
+/** Options for {@link pipeConnect}, the client over raw readable/writable streams. */
 export interface PipeConnectOptions {
+  /** Callback invoked for each log/error message the server emits during a request. */
   onLog?: (msg: LogMessage) => void;
   /** External storage config for resolving externalized batches. */
   externalLocation?: import("../external.js").ExternalLocationConfig;
 }
 
+/** Options for {@link subprocessConnect}, which spawns a server process and pipes to it. */
 export interface SubprocessConnectOptions extends PipeConnectOptions {
+  /** Working directory for the spawned process. Defaults to the current directory. */
   cwd?: string;
+  /** Extra environment variables, merged over the current `process.env`. */
   env?: Record<string, string>;
+  /** How to handle the child's stderr. Defaults to `"ignore"`. */
   stderr?: "inherit" | "pipe" | "ignore";
 }