@query-farm/vgi-rpc 0.6.3 → 0.7.0

package/dist/launcher/hash.d.ts

@@ -0,0 +1,22 @@
+/** Recursively stringify with sorted object keys and `,`/`:` separators —
+ *  the JS equivalent of `json.dumps(..., sort_keys=True, separators=(",",":"))`.
+ *  We can't reuse `JSON.stringify` because the V8 implementation preserves
+ *  insertion order rather than sorting. */
+declare function canonicalJson(value: unknown): string;
+/**
+ * Compute the 16-hex-char tuple hash for a worker.
+ *
+ * @param workerArgv The worker command and its arguments.
+ * @param cwd        Working directory; defaults to `process.cwd()`.
+ * @param env        Process environment; defaults to `process.env`.  Only
+ *                   keys starting with `VGI_RPC_` participate in the hash —
+ *                   workers that differ only in unrelated env (PATH,
+ *                   HOME, …) intentionally share a worker.
+ */
+export declare function computeHash(workerArgv: readonly string[], cwd?: string, env?: Record<string, string | undefined>): Promise<string>;
+/** Exposed for parity-test fixtures that need to inspect the canonical form. */
+export declare const _internal: {
+    canonicalJson: typeof canonicalJson;
+};
+export {};
+//# sourceMappingURL=hash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/launcher/hash.ts"],"names":[],"mappings":"AA6BA;;;2CAG2C;AAC3C,iBAAS,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAoB7C;AAaD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,GAAG,CAAC,EAAE,MAAM,EACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACvC,OAAO,CAAC,MAAM,CAAC,CAoBjB;AAED,gFAAgF;AAChF,eAAO,MAAM,SAAS;;CAAoB,CAAC"}

package/dist/launcher/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AF_UNIX worker launcher — TypeScript port of `vgi_rpc.launcher`.
+ *
+ * Two halves:
+ *
+ * - **Coordination** ({@link launch}, {@link computeHash}, {@link gcStateDir},
+ *   {@link statusRows}): spawn-or-reuse a long-running worker process for a
+ *   given command tuple, returning the AF_UNIX socket path the caller
+ *   should connect to.  Hash and on-disk layout match the Python
+ *   implementation byte-for-byte so workers in any language under the
+ *   same tuple resolve to the same socket.
+ *
+ * - **Worker runner** ({@link serveUnix}): bind a Unix socket and serve a
+ *   {@link Protocol} via per-connection IPC streams.  Implements the
+ *   `--unix PATH` / `--idle-timeout SEC` / `UNIX:<path>` contract so
+ *   launchers (Python or TS) can spawn TS workers transparently.
+ */
+export { computeHash } from "./hash.js";
+export { type LaunchConfig, launch } from "./launch.js";
+export { acquireLock, type FileLockHandle, tryAcquireLock } from "./lock.js";
+export { type ServeUnixHandle, type ServeUnixOptions, serveUnix } from "./serve-unix.js";
+export { defaultStateDir, type GcResult, gcStateDir, probeSocket, type SocketPaths, type StatusRow, socketPaths, statusRows, } from "./state.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACzF,OAAO,EACL,eAAe,EACf,KAAK,QAAQ,EACb,UAAU,EACV,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/launcher/launch.d.ts

@@ -0,0 +1,27 @@
+/** Inputs to {@link launch}. */
+export interface LaunchConfig {
+    /** The worker command and its arguments.  Must be non-empty. */
+    workerArgv: readonly string[];
+    /** Explicit socket path; when omitted, derived from the hash of the tuple. */
+    socketPath?: string;
+    /** Worker self-shutdown after this many seconds idle.  Forwarded as
+     *  `--idle-timeout SEC`.  Default: 300. */
+    idleTimeout?: number;
+    /** Maximum seconds to block waiting for the per-hash file lock.  Default: 30. */
+    connectTimeout?: number;
+    /** Maximum seconds to wait for the worker to print `UNIX:<path>`.  Default: 60. */
+    workerStartupTimeout?: number;
+    /** If set, worker stderr is appended to this file; otherwise discarded. */
+    workerStderr?: string;
+    /** Override the default state directory. */
+    stateDir?: string;
+}
+/**
+ * Ensure a worker is running and return its socket path.
+ *
+ * Either the existing worker for this hash is reused (probe succeeds) or
+ * a fresh one is spawned under flock.  Throws on any failure to bring up
+ * a worker.
+ */
+export declare function launch(config: LaunchConfig): Promise<string>;
+//# sourceMappingURL=launch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/launcher/launch.ts"],"names":[],"mappings":"AAyCA,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;+CAC2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAiElE"}

package/dist/launcher/lock.d.ts

@@ -0,0 +1,19 @@
+/** Result of a successful lock acquisition. */
+export interface FileLockHandle {
+    /** Path to the lockfile (informational). */
+    readonly path: string;
+    /** Release the lock — truncates the file to zero bytes; the file
+     *  itself persists as a slot marker.  Idempotent. */
+    release(): void;
+}
+/**
+ * Try to acquire the lock once, non-blocking.
+ *
+ * Returns a release callback on success, or `null` when the lock is
+ * held by another live process.  Stale stamps (PID not alive) are
+ * cleared and the call retries.
+ */
+export declare function tryAcquireLock(lockPath: string): FileLockHandle | null;
+/** Async version that polls until the lock is acquired or the timeout fires. */
+export declare function acquireLock(lockPath: string, timeoutMs: number): Promise<FileLockHandle>;
+//# sourceMappingURL=lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/launcher/lock.ts"],"names":[],"mappings":"AAuCA,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;yDACqD;IACrD,OAAO,IAAI,IAAI,CAAC;CACjB;AA8ED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CA0BtE;AAED,gFAAgF;AAChF,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAU9F"}

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

@@ -0,0 +1,54 @@
+import type { ExternalLocationConfig } from "../external.js";
+import type { Protocol } from "../protocol.js";
+import { type DispatchHook, type ServeStartHook } from "../types.js";
+/** Configuration for {@link serveUnix}. */
+export interface ServeUnixOptions {
+    /** Absolute path to the Unix socket file the worker should bind. */
+    unixPath: string;
+    /** Self-terminate after this many seconds with zero connected clients.
+     *  Default: 300.  `0` disables the timer (server runs until killed). */
+    idleTimeout?: number;
+    /** Grace period after `listen()` succeeds before the idle timer starts
+     *  ticking.  Default: 5 — gives the first launcher caller a chance to
+     *  connect after the `UNIX:<path>` announcement. */
+    startupGraceSeconds?: number;
+    /** Optional logical-service / protocol-contract version label. */
+    protocolVersion?: string;
+    /** Custom server identifier. */
+    serverId?: string;
+    /** Enable __describe__ method. Default: true. */
+    enableDescribe?: boolean;
+    /** Optional dispatch hook for observability. */
+    dispatchHook?: DispatchHook;
+    /** Optional external-storage config for large-batch externalisation. */
+    externalLocation?: ExternalLocationConfig;
+    /** Lifecycle hook fired once before the first dispatched request. */
+    onServeStart?: ServeStartHook;
+    /** Maximum sequential listen backlog. Mirrors Python's `serve_unix`
+     *  (`backlog=16`).  Default: 16. */
+    backlog?: number;
+    /** Called *after* `listen()` returns successfully but *before*
+     *  `UNIX:<path>` is printed.  The launcher uses this hook to write the
+     *  announcement only after we're sure the bind took. */
+    onBound?: (sockPath: string) => void;
+    /** Override the stream used for the `UNIX:<path>` line.  Defaults to
+     *  `process.stdout`. */
+    announcementSink?: NodeJS.WritableStream;
+}
+/** Handle returned by {@link serveUnix} for callers that want to stop the server. */
+export interface ServeUnixHandle {
+    readonly socketPath: string;
+    /** Shut down the listener and unlink the socket file. */
+    stop(): Promise<void>;
+    /** Promise that resolves when the server has stopped (idle timeout, stop(),
+     *  or a fatal error).  Mirrors Python's blocking `serve()` return. */
+    readonly done: Promise<void>;
+}
+/**
+ * Bind an AF_UNIX socket and serve `protocol` over per-connection IPC streams.
+ *
+ * Sequential listen — one client at a time, just like Python's `serve_unix`.
+ * Each connection gets its own dispatch loop and shares the protocol.
+ */
+export declare function serveUnix(protocol: Protocol, options: ServeUnixOptions): Promise<ServeUnixHandle>;
+//# sourceMappingURL=serve-unix.d.ts.map

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

@@ -0,0 +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"}

package/dist/launcher/state.d.ts

@@ -0,0 +1,59 @@
+import { computeHash } from "./hash.js";
+/** Filesystem layout for one worker tuple: `<state_dir>/<hash>.{lock,sock,meta}`. */
+export interface SocketPaths {
+    lockPath: string;
+    sockPath: string;
+    metaPath: string;
+}
+export declare function socketPaths(stateDir: string, hashId: string): SocketPaths;
+/**
+ * Resolve the per-user state directory used for lockfiles + sockets.
+ *
+ * - Linux: `$XDG_RUNTIME_DIR/vgi-rpc/` when set (systemd-managed,
+ *   auto-cleaned on logout); otherwise `$TMPDIR/vgi-rpc-$UID/`.
+ * - macOS / BSD: `$TMPDIR/vgi-rpc-$UID/`.
+ * - Windows: `$TMP/vgi-rpc/`.
+ *
+ * The directory is created mode 0700 if missing.  On POSIX, we refuse to
+ * operate on a directory not owned by the current user — defends against
+ * a hijacked `/tmp/vgi-rpc-$UID` left by an attacker.
+ */
+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;
+export interface StatusRow {
+    hashId: string;
+    cmd: string[];
+    cwd: string;
+    socket: string;
+    startedAt: number | null;
+    alive: boolean;
+}
+export interface GcResult {
+    /** Hash IDs of stale entries that were removed. */
+    cleaned: string[];
+    /** Hash IDs whose lockfile is currently held (a launch is in flight or the
+     *  worker is alive). */
+    skippedInUse: string[];
+}
+/** Probe whether anyone is currently accepting on `sockPath`. */
+export declare function probeSocket(sockPath: string, timeoutMs?: number): Promise<boolean>;
+/** List one row per `<hash>.lock` in `stateDir`.  Read-only; takes no locks. */
+export declare function statusRows(stateDir: string): Promise<StatusRow[]>;
+/**
+ * Remove `<hash>.lock`/`.sock`/`.meta` triples whose worker is no longer
+ * accepting connections.
+ *
+ * @param tryAcquire Function provided by the lock module so we don't pull
+ *  the lock implementation into a circular import.  Returns a release
+ *  callback when the lock can be acquired non-blocking, or `null` when
+ *  it's already held (the worker is alive or another launch is in flight).
+ */
+export declare function gcStateDir(stateDir: string, tryAcquire: (lockPath: string) => Promise<(() => void) | null>, options?: {
+    limit?: number;
+    excludeHash?: string;
+}): Promise<GcResult>;
+/** Re-export for callers that want canonical hashing without going through the
+ *  launch entry point. */
+export { computeHash };
+//# sourceMappingURL=state.d.ts.map

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

@@ -0,0 +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"}

package/dist/otel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAIL,KAAK,KAAK,EAKV,KAAK,MAAM,EAEZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAkB,YAAY,EAA2B,MAAM,YAAY,CAAC;AAIxF,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,cAAc,CAAC,EAAE;QAAE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACrD,mEAAmE;IACnE,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAC;IAClD,2CAA2C;IAC3C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CA+FhE"}
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAIL,KAAK,KAAK,EAKV,KAAK,MAAM,EAEZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAkB,YAAY,EAA2B,MAAM,YAAY,CAAC;AAIxF,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,cAAc,CAAC,EAAE;QAAE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACrD,mEAAmE;IACnE,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAC;IAClD,2CAA2C;IAC3C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CAqGhE"}

package/dist/protocol.d.ts

@@ -1,13 +1,25 @@
 import { type SchemaLike } from "./schema.js";
-import { type ExchangeFn, type ExchangeInit, type HeaderInit, type MethodDefinition, type ProducerFn, type ProducerInit, type UnaryHandler } from "./types.js";
+import { type ExchangeFn, type ExchangeInit, type HeaderInit, type MethodDefinition, type OnCancelFn, type ProducerFn, type ProducerInit, type UnaryHandler } from "./types.js";
 /**
  * Fluent builder for defining RPC methods.
  * Register unary, producer, and exchange methods, then pass to `VgiRpcServer`.
  */
 export declare class Protocol {
     readonly name: string;
+    /**
+     * Application protocol surface version. When non-empty, the server enforces
+     * exact major+minor match (patch ignored) against every request's
+     * `vgi_rpc.protocol_version` metadata; clients bound to this Protocol emit
+     * the value on every request. Format: canonical semver MAJOR.MINOR.PATCH.
+     * Mirrors Python's `Protocol.protocol_version` ClassVar.
+     */
+    readonly protocolVersion: string;
+    /** Parsed semver tuple; null when `protocolVersion` is unset. */
+    readonly protocolVersionParts: readonly [number, number, number] | null;
     private _methods;
-    constructor(name: string);
+    constructor(name: string, options?: {
+        protocolVersion?: string;
+    });
     /**
      * Register a unary (request-response) method.
      * @param name - Method name exposed to clients
@@ -35,6 +47,7 @@ export declare class Protocol {
         outputSchema: SchemaLike;
         init: ProducerInit<S>;
         produce: ProducerFn<S>;
+        onCancel?: OnCancelFn<S>;
         headerSchema?: SchemaLike;
         headerInit?: HeaderInit;
         doc?: string;
@@ -51,6 +64,7 @@ export declare class Protocol {
         outputSchema: SchemaLike;
         init: ExchangeInit<S>;
         exchange: ExchangeFn<S>;
+        onCancel?: OnCancelFn<S>;
         headerSchema?: SchemaLike;
         headerInit?: HeaderInit;
         doc?: string;

package/dist/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAIA,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,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAIpB;;;GAGG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAA4C;gBAEhD,IAAI,EAAE,MAAM;IAIxB;;;;;;;;;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,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;IAoBP;;;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,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;IAoBP,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,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"}

package/dist/schema.d.ts

@@ -1,34 +1,61 @@
-import { Binary, Bool, DataType, Field, Float32, Float64, Int32, Int64, Schema, Utf8 } from "@query-farm/apache-arrow";
+import { type VgiDataType, type VgiField, type VgiSchema } from "./arrow/index.js";
 /** Apache Arrow Utf8 type. Use as schema shorthand: `{ name: str }` */
-export declare const str: Utf8;
+export declare const str: VgiDataType;
 /** Apache Arrow Binary type. Use as schema shorthand: `{ data: bytes }` */
-export declare const bytes: Binary;
+export declare const bytes: VgiDataType;
 /** Apache Arrow Int64 type. Use as schema shorthand: `{ count: int }` */
-export declare const int: Int64;
+export declare const int: VgiDataType;
 /** Apache Arrow Int32 type. Use as schema shorthand: `{ count: int32 }` */
-export declare const int32: Int32;
+export declare const int32: VgiDataType;
+/** Apache Arrow Int16 type. Use as schema shorthand: `{ count: int16 }` */
+export declare const int16: VgiDataType;
+/** Apache Arrow Int8 type. Use as schema shorthand: `{ count: int8 }` */
+export declare const int8: VgiDataType;
+/** Apache Arrow Uint8 type. Use as schema shorthand: `{ count: uint8 }` */
+export declare const uint8: VgiDataType;
+/** Apache Arrow Uint16 type. Use as schema shorthand: `{ count: uint16 }` */
+export declare const uint16: VgiDataType;
+/** Apache Arrow Uint32 type. Use as schema shorthand: `{ count: uint32 }` */
+export declare const uint32: VgiDataType;
+/** Apache Arrow Uint64 type. Use as schema shorthand: `{ count: uint64 }` */
+export declare const uint64: VgiDataType;
 /** Apache Arrow Float64 type. Use as schema shorthand: `{ value: float }` */
-export declare const float: Float64;
+export declare const float: VgiDataType;
 /** Apache Arrow Float32 type. Use as schema shorthand: `{ value: float32 }` */
-export declare const float32: Float32;
+export declare const float32: VgiDataType;
 /** Apache Arrow Bool type. Use as schema shorthand: `{ flag: bool }` */
-export declare const bool: Bool;
+export declare const bool: VgiDataType;
+/**
+ * Structural minimum that any backend's Schema must satisfy. arrow-js's
+ * `Schema`, vgi-typescript's `VgiSchema`, and flechette's `Schema` all match
+ * this shape. Used so vgi-rpc consumers don't have to know which Arrow
+ * library is on the other side of the wire.
+ *
+ * Kept exported for backwards compatibility — equivalent to `VgiSchema`.
+ */
+export interface SchemaShape {
+    readonly fields: ReadonlyArray<{
+        readonly name: string;
+        readonly type: {
+            readonly typeId: number;
+        };
+        readonly nullable?: boolean;
+        readonly metadata?: Map<string, string>;
+    }>;
+    readonly metadata?: Map<string, string> | null;
+}
 /**
  * A schema specification that accepts:
- * - A real `Schema` (passed through)
- * - A record mapping field names to `DataType` instances or `Field` instances
+ * - A real `VgiSchema` (passed through)
+ * - Anything structurally `SchemaShape`
+ * - A record mapping field names to `VgiDataType` instances or `VgiField` instances
  * - An empty `{}` for an empty schema
  */
-export type SchemaLike = Schema | Record<string, DataType | Field>;
+export type SchemaLike = VgiSchema | SchemaShape | Record<string, VgiDataType | VgiField>;
 /**
- * Convert a SchemaLike spec into a real `Schema`.
- *
- * - `Schema` → returned as-is
- * - `Record<string, DataType>` → each entry becomes `new Field(name, type, false)`
- * - `Record<string, Field>` → each entry is passed through
- * - `{}` → `new Schema([])`
+ * Convert a SchemaLike spec into a real `VgiSchema`.
  */
-export declare function toSchema(spec: SchemaLike): Schema;
+export declare function toSchema(spec: SchemaLike): VgiSchema;
 /**
  * Derive a `paramTypes` record from a SchemaLike spec.
  * Maps common Arrow scalar types to Python-style type strings.

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,OAAO,EACP,OAAO,EAEP,KAAK,EACL,KAAK,EACL,MAAM,EACN,IAAI,EACL,MAAM,0BAA0B,CAAC;AAMlC,uEAAuE;AACvE,eAAO,MAAM,GAAG,MAAa,CAAC;AAC9B,2EAA2E;AAC3E,eAAO,MAAM,KAAK,QAAe,CAAC;AAClC,yEAAyE;AACzE,eAAO,MAAM,GAAG,OAAc,CAAC;AAC/B,2EAA2E;AAC3E,eAAO,MAAM,KAAK,OAAc,CAAC;AACjC,6EAA6E;AAC7E,eAAO,MAAM,KAAK,SAAgB,CAAC;AACnC,+EAA+E;AAC/E,eAAO,MAAM,OAAO,SAAgB,CAAC;AACrC,wEAAwE;AACxE,eAAO,MAAM,IAAI,MAAa,CAAC;AAM/B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;AAEnE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAcjD;AAiBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAiBpF"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAqBL,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAM1B,uEAAuE;AACvE,eAAO,MAAM,GAAG,aAAS,CAAC;AAC1B,2EAA2E;AAC3E,eAAO,MAAM,KAAK,aAAW,CAAC;AAC9B,yEAAyE;AACzE,eAAO,MAAM,GAAG,aAAc,CAAC;AAC/B,2EAA2E;AAC3E,eAAO,MAAM,KAAK,aAAc,CAAC;AACjC,2EAA2E;AAC3E,eAAO,MAAM,KAAK,aAAc,CAAC;AACjC,yEAAyE;AACzE,eAAO,MAAM,IAAI,aAAa,CAAC;AAC/B,2EAA2E;AAC3E,eAAO,MAAM,KAAK,aAAc,CAAC;AACjC,6EAA6E;AAC7E,eAAO,MAAM,MAAM,aAAe,CAAC;AACnC,6EAA6E;AAC7E,eAAO,MAAM,MAAM,aAAe,CAAC;AACnC,6EAA6E;AAC7E,eAAO,MAAM,MAAM,aAAe,CAAC;AACnC,6EAA6E;AAC7E,eAAO,MAAM,KAAK,aAAgB,CAAC;AACnC,+EAA+E;AAC/E,eAAO,MAAM,OAAO,aAAgB,CAAC;AACrC,wEAAwE;AACxE,eAAO,MAAM,IAAI,aAAa,CAAC;AAM/B;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE;YAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACzC,CAAC,CAAC;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAChD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC,CAAC;AAe1F;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CA0BpD;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAgBpF"}

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import type { ExternalLocationConfig } from "./external.js";
 import type { Protocol } from "./protocol.js";
-import { type DispatchHook } from "./types.js";
+import { type DispatchHook, type ServeStartHook } from "./types.js";
 /**
  * RPC server that reads Arrow IPC requests from stdin and writes responses to stdout.
  * Supports unary and streaming (producer/exchange) methods.
@@ -9,15 +9,36 @@ export declare class VgiRpcServer {
     private protocol;
     private enableDescribe;
     private serverId;
-    private describeBatch;
+    private _describePromise;
+    private protocolVersion;
     private dispatchHook;
     private externalConfig;
+    private onServeStart;
+    /** True once the on_serve_start hook has fired successfully. The bind
+     *  state is committed only after the hook returns, so a transient
+     *  failure on first request leaves it `false` and the next request
+     *  re-fires rather than silently skipping. Mirrors Python 7b3999c. */
+    private serveStartFired;
     constructor(protocol: Protocol, options?: {
         enableDescribe?: boolean;
         serverId?: string;
         dispatchHook?: DispatchHook;
         externalLocation?: ExternalLocationConfig;
+        protocolVersion?: string;
+        /** Lifecycle hook fired once before the first dispatched request. */
+        onServeStart?: ServeStartHook;
     });
+    /** Fire the on_serve_start hook once for this transport. Idempotent
+     *  on success — re-throws on failure without committing the bind. */
+    private notifyTransport;
+    /** Build (or retrieve cached) describe batch + protocol hash. */
+    private describeInfo;
+    /** Validate a client's declared protocol_version against the Protocol's
+     *  declared version. Caller invokes only when
+     *  `protocol.protocolVersionParts` is non-null. Mirrors Python's
+     *  `RpcServer._check_protocol_version`: exact major+minor match, patch
+     *  ignored; directional error message names which side is older. */
+    private checkProtocolVersion;
     /** Start the server loop. Reads requests until stdin closes. */
     run(): Promise<void>;
     private serveOne;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAuB,KAAK,YAAY,EAAiC,MAAM,YAAY,CAAC;AAQnG;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAA+D;IACpF,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAAqC;gBAGzD,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,YAAY,CAAC;QAC5B,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;KAC3C;IAcH,gEAAgE;IAC1D,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAwCZ,QAAQ;CA+EvB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAEL,KAAK,YAAY,EAGjB,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AAkBpB;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAS;IAIzB,OAAO,CAAC,gBAAgB,CAGP;IACjB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,YAAY,CAA+B;IACnD;;;0EAGsE;IACtE,OAAO,CAAC,eAAe,CAAS;gBAG9B,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,YAAY,CAAC;QAC5B,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;QAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,qEAAqE;QACrE,YAAY,CAAC,EAAE,cAAc,CAAC;KAC/B;IAWH;yEACqE;YACvD,eAAe;IAQ7B,iEAAiE;YACnD,YAAY;IAkB1B;;;;wEAIoE;IACpE,OAAO,CAAC,oBAAoB;IAyC5B,gEAAgE;IAC1D,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YA6CZ,QAAQ;CA2IvB"}