@iicp/client 0.5.7 → 0.7.0

package/dist/relay_session.js

@@ -0,0 +1,276 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Relay-as-last-resort — ADR-041 tier-3, Part 3 R1 (#341).
+ *
+ * TypeScript port of iicp-client-python/relay_session.py.
+ * Workers behind CGNAT hold an outbound IICP-TCP connection here.
+ * The relay pushes CALL frames down when /v1/relay is invoked and routes
+ * RESPONSE frames back to the waiting HTTP handler.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayAcceptServer = exports.RelaySessionRegistry = exports.RelayWorkerSession = void 0;
+const net = require("node:net");
+const IICP_MAGIC = Buffer.from("IICP");
+const FRAMING_VERSION = 0x01;
+const FRAME_HEADER_LEN = 12;
+// Frame type constants (mirrors MsgType enum in iicp_tcp.ts)
+const MT_INIT = 0x01;
+const MT_ACK = 0x02;
+const MT_CALL = 0x05;
+const MT_RESPONSE = 0x06;
+const MT_CLOSE = 0x07;
+const MT_PING = 0x09;
+const MT_PONG = 0x0a;
+const MT_RELAY_BIND = 0x0b;
+const MT_RELAY_ACK = 0x0c;
+function _enc(obj) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const cbor = require("cbor-x");
+    return cbor.encode(obj);
+}
+function _dec(buf) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const cbor = require("cbor-x");
+    return cbor.decode(buf);
+}
+function makeFrame(msgType, payload) {
+    const header = Buffer.alloc(FRAME_HEADER_LEN);
+    IICP_MAGIC.copy(header, 0);
+    header.writeUInt8(FRAMING_VERSION, 4);
+    header.writeUInt8(msgType, 5);
+    header.writeUInt8(0, 6); // flags
+    header.writeUInt8(0, 7); // reserved
+    header.writeUInt32BE(payload.length, 8);
+    return Buffer.concat([header, payload]);
+}
+// ── RelayWorkerSession ────────────────────────────────────────────────────────
+class RelayWorkerSession {
+    workerId;
+    _socket;
+    _pending = new Map();
+    _writeLocked = false;
+    constructor(workerId, socket) {
+        this.workerId = workerId;
+        this._socket = socket;
+    }
+    /** Push a task CALL to the worker and await the RESPONSE (via Promise). */
+    async forwardTask(task, timeoutMs = 120_000) {
+        const callId = crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this._pending.delete(callId);
+                reject(new Error(`relay forward timeout for call ${callId}`));
+            }, timeoutMs);
+            this._pending.set(callId, (result) => {
+                clearTimeout(timer);
+                resolve(result);
+            });
+            try {
+                const payload = _enc({ 15: callId, 5: Buffer.from(JSON.stringify(task)) });
+                const frame = makeFrame(MT_CALL, payload);
+                this._socket.write(frame);
+            }
+            catch (err) {
+                this._pending.delete(callId);
+                clearTimeout(timer);
+                reject(err);
+            }
+        });
+    }
+    /** Called by relay accept server when a RESPONSE arrives from the worker. */
+    onResponse(callId, result) {
+        const cb = this._pending.get(callId);
+        if (cb) {
+            this._pending.delete(callId);
+            cb(result);
+        }
+    }
+}
+exports.RelayWorkerSession = RelayWorkerSession;
+// ── RelaySessionRegistry ─────────────────────────────────────────────────────
+class RelaySessionRegistry {
+    _sessions = new Map();
+    bind(workerId, session) {
+        this._sessions.set(workerId, session);
+    }
+    unbind(workerId) {
+        this._sessions.delete(workerId);
+    }
+    get(workerId) {
+        return this._sessions.get(workerId);
+    }
+    isBound(workerId) {
+        return this._sessions.has(workerId);
+    }
+    boundWorkerIds() {
+        return [...this._sessions.keys()];
+    }
+}
+exports.RelaySessionRegistry = RelaySessionRegistry;
+// ── RelayAcceptServer ─────────────────────────────────────────────────────────
+class RelayAcceptServer {
+    _registry;
+    _host;
+    _port;
+    _server;
+    constructor(registry, opts = {}) {
+        this._registry = registry;
+        this._host = opts.host ?? "0.0.0.0";
+        this._port = opts.port ?? 9485;
+    }
+    start() {
+        return new Promise((resolve, reject) => {
+            this._server = net.createServer((socket) => {
+                this._handleConnection(socket).catch((err) => {
+                    console.error(`[relay-accept] session error: ${err instanceof Error ? err.message : err}`);
+                    socket.destroy();
+                });
+            });
+            this._server.listen(this._port, this._host, () => {
+                console.log(`[relay-accept] listening on ${this._host}:${this._port}`);
+                resolve();
+            });
+            this._server.on("error", reject);
+        });
+    }
+    stop() {
+        return new Promise((resolve) => {
+            if (this._server) {
+                this._server.close(() => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    async _handleConnection(socket) {
+        // Accumulate data into a buffer for synchronous frame parsing
+        const chunks = [];
+        let resolveData = null;
+        socket.on("data", (d) => {
+            chunks.push(d);
+            if (resolveData) {
+                resolveData();
+                resolveData = null;
+            }
+        });
+        socket.on("end", () => { if (resolveData) {
+            resolveData();
+            resolveData = null;
+        } });
+        socket.on("error", () => { if (resolveData) {
+            resolveData();
+            resolveData = null;
+        } });
+        const waitForData = () => new Promise((r) => { resolveData = r; });
+        const readExactly = async (n) => {
+            while (true) {
+                let total = chunks.reduce((s, c) => s + c.length, 0);
+                if (total >= n) {
+                    const merged = Buffer.concat(chunks);
+                    chunks.length = 0;
+                    chunks.push(merged.subarray(n));
+                    return merged.subarray(0, n);
+                }
+                if (socket.destroyed)
+                    return null;
+                await waitForData();
+            }
+        };
+        // Step 1: INIT
+        const magic = await readExactly(4);
+        if (!magic || !magic.equals(IICP_MAGIC))
+            return;
+        const rest = await readExactly(FRAME_HEADER_LEN - 4);
+        if (!rest)
+            return;
+        const header = Buffer.concat([magic, rest]);
+        const msgType = header.readUInt8(5);
+        const payloadLen = header.readUInt32BE(8);
+        if (msgType !== MT_INIT)
+            return;
+        if (payloadLen > 0) {
+            const _ = await readExactly(payloadLen);
+            if (!_)
+                return;
+        }
+        socket.write(makeFrame(MT_ACK, _enc({ 1: FRAMING_VERSION })));
+        // Step 2: RELAY_BIND
+        const rh = await readExactly(FRAME_HEADER_LEN);
+        if (!rh)
+            return;
+        const rmt = rh.readUInt8(5);
+        const rlen = rh.readUInt32BE(8);
+        if (rmt !== MT_RELAY_BIND)
+            return;
+        const rbuf = rlen > 0 ? await readExactly(rlen) : Buffer.alloc(0);
+        if (!rbuf)
+            return;
+        let workerId, intent, models;
+        try {
+            const body = _dec(rbuf);
+            workerId = String(body[1] ?? "");
+            intent = String(body[2] ?? "");
+            models = Array.isArray(body[3]) ? body[3].map(String) : [];
+        }
+        catch {
+            return;
+        }
+        if (!workerId)
+            return;
+        const session = new RelayWorkerSession(workerId, socket);
+        this._registry.bind(workerId, session);
+        console.log(`[relay-accept] worker=${workerId} bound (intent=${intent} models=${models.slice(0, 3).join(",")})`);
+        socket.write(makeFrame(MT_RELAY_ACK, _enc({ 1: "ok", 2: workerId })));
+        // Step 3: relay-worker frame loop
+        try {
+            while (!socket.destroyed) {
+                const fh = await readExactly(FRAME_HEADER_LEN);
+                if (!fh)
+                    break;
+                const ft = fh.readUInt8(5);
+                const fl = fh.readUInt32BE(8);
+                const fp = fl > 0 ? await readExactly(fl) : Buffer.alloc(0);
+                if (!fp)
+                    break;
+                if (ft === MT_PING) {
+                    let echo = Buffer.alloc(0);
+                    try {
+                        const pb = _dec(fp);
+                        const e = pb[1];
+                        echo = Buffer.isBuffer(e) ? Buffer.from(e) : Buffer.alloc(0);
+                    }
+                    catch { /* ok */ }
+                    socket.write(makeFrame(MT_PONG, _enc({ 1: echo })));
+                }
+                else if (ft === MT_RESPONSE) {
+                    try {
+                        const rb = _dec(fp);
+                        const callId = String(rb[15] ?? "");
+                        const raw5 = rb[5];
+                        let result = {};
+                        if (Buffer.isBuffer(raw5))
+                            result = JSON.parse(raw5.toString());
+                        else if (typeof raw5 === "string")
+                            result = JSON.parse(raw5);
+                        session.onResponse(callId, result);
+                    }
+                    catch (err) {
+                        console.warn(`[relay-accept] RESPONSE decode error: ${err}`);
+                    }
+                }
+                else if (ft === MT_CLOSE) {
+                    break;
+                }
+            }
+        }
+        finally {
+            this._registry.unbind(workerId);
+            console.log(`[relay-accept] session ended for worker=${workerId}`);
+            socket.destroy();
+        }
+    }
+}
+exports.RelayAcceptServer = RelayAcceptServer;
+//# sourceMappingURL=relay_session.js.map

package/dist/relay_session.js.map

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

package/dist/relay_worker_client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Relay worker client — ADR-041 tier-3, Part 3 R2 (#341).
+ *
+ * TypeScript port of relay_worker_client.py.
+ * A CGNAT-unreachable node connects outbound to a relay node here.
+ * The relay pushes CALL frames down the persistent session; the worker
+ * handles them and sends RESPONSE back. PING/PONG keepalive with auto-
+ * reconnect (exponential backoff, cap 60 s).
+ */
+export type RelayTaskHandler = (task: Record<string, unknown>) => Promise<Record<string, unknown>>;
+export declare class RelayWorkerClient {
+    private readonly _workerId;
+    private readonly _intent;
+    private readonly _relayHost;
+    private readonly _relayPort;
+    private readonly _handler;
+    private readonly _models;
+    private readonly _onBind?;
+    private _stopped;
+    constructor(opts: {
+        workerId: string;
+        intent: string;
+        relayHost: string;
+        relayPort: number;
+        handler: RelayTaskHandler;
+        models?: string[];
+        /** Called after a successful RELAY_ACK — use to re-register with the directory (#358). */
+        onBind?: (relayHost: string, relayPort: number, workerId: string) => Promise<void>;
+    });
+    /** Start the reconnect loop. Returns a stop() function. */
+    start(): () => void;
+    private _run;
+    private _session;
+    private _handshake;
+    private _handleCall;
+}
+//# sourceMappingURL=relay_worker_client.d.ts.map

package/dist/relay_worker_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay_worker_client.d.ts","sourceRoot":"","sources":["../src/relay_worker_client.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAwCH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEnG,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA4E;IACrG,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,gBAAgB,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,0FAA0F;QAC1F,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACpF;IAUD,2DAA2D;IAC3D,KAAK,IAAI,MAAM,IAAI;YAML,IAAI;IAelB,OAAO,CAAC,QAAQ;YAaF,UAAU;YAoFV,WAAW;CAoB1B"}

package/dist/relay_worker_client.js

@@ -0,0 +1,216 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Relay worker client — ADR-041 tier-3, Part 3 R2 (#341).
+ *
+ * TypeScript port of relay_worker_client.py.
+ * A CGNAT-unreachable node connects outbound to a relay node here.
+ * The relay pushes CALL frames down the persistent session; the worker
+ * handles them and sends RESPONSE back. PING/PONG keepalive with auto-
+ * reconnect (exponential backoff, cap 60 s).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayWorkerClient = void 0;
+const net = require("node:net");
+const IICP_MAGIC = Buffer.from("IICP");
+const FRAMING_VERSION = 0x01;
+const FRAME_HEADER_LEN = 12;
+const PING_INTERVAL_MS = 30_000;
+const MAX_RECONNECT_DELAY_MS = 60_000;
+const MT_INIT = 0x01;
+const MT_ACK = 0x02;
+const MT_CALL = 0x05;
+const MT_RESPONSE = 0x06;
+const MT_PING = 0x09;
+const MT_PONG = 0x0a;
+const MT_RELAY_BIND = 0x0b;
+const MT_RELAY_ACK = 0x0c;
+function _enc(obj) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require("cbor-x").encode(obj);
+}
+function _dec(buf) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require("cbor-x").decode(buf);
+}
+function makeFrame(msgType, payload) {
+    const header = Buffer.alloc(FRAME_HEADER_LEN);
+    IICP_MAGIC.copy(header, 0);
+    header.writeUInt8(FRAMING_VERSION, 4);
+    header.writeUInt8(msgType, 5);
+    header.writeUInt8(0, 6);
+    header.writeUInt8(0, 7);
+    header.writeUInt32BE(payload.length, 8);
+    return Buffer.concat([header, payload]);
+}
+class RelayWorkerClient {
+    _workerId;
+    _intent;
+    _relayHost;
+    _relayPort;
+    _handler;
+    _models;
+    _onBind;
+    _stopped = false;
+    constructor(opts) {
+        this._workerId = opts.workerId;
+        this._intent = opts.intent;
+        this._relayHost = opts.relayHost;
+        this._relayPort = opts.relayPort;
+        this._handler = opts.handler;
+        this._models = opts.models ?? [];
+        this._onBind = opts.onBind;
+    }
+    /** Start the reconnect loop. Returns a stop() function. */
+    start() {
+        this._stopped = false;
+        void this._run();
+        return () => { this._stopped = true; };
+    }
+    async _run() {
+        let delay = 2_000;
+        while (!this._stopped) {
+            try {
+                await this._session();
+                delay = 2_000;
+            }
+            catch {
+                // reconnect
+            }
+            if (this._stopped)
+                break;
+            await new Promise((r) => setTimeout(r, delay));
+            delay = Math.min(delay * 2, MAX_RECONNECT_DELAY_MS);
+        }
+    }
+    _session() {
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection(this._relayPort, this._relayHost);
+            socket.on("error", reject);
+            socket.on("connect", () => {
+                this._handshake(socket)
+                    .then(resolve)
+                    .catch(reject)
+                    .finally(() => socket.destroy());
+            });
+        });
+    }
+    async _handshake(socket) {
+        const chunks = [];
+        let resolveData = null;
+        socket.on("data", (d) => {
+            chunks.push(d);
+            if (resolveData) {
+                resolveData();
+                resolveData = null;
+            }
+        });
+        socket.on("end", () => { if (resolveData) {
+            resolveData();
+            resolveData = null;
+        } });
+        const waitData = () => new Promise((r) => { resolveData = r; });
+        const readExact = async (n) => {
+            while (true) {
+                const total = chunks.reduce((s, c) => s + c.length, 0);
+                if (total >= n) {
+                    const merged = Buffer.concat(chunks);
+                    chunks.length = 0;
+                    chunks.push(merged.subarray(n));
+                    return merged.subarray(0, n);
+                }
+                if (socket.destroyed)
+                    return null;
+                await waitData();
+            }
+        };
+        const readFrame = async () => {
+            const h = await readExact(FRAME_HEADER_LEN);
+            if (!h)
+                return null;
+            if (!h.subarray(0, 4).equals(IICP_MAGIC))
+                return null;
+            const mt = h.readUInt8(5);
+            const plen = h.readUInt32BE(8);
+            const payload = plen > 0 ? await readExact(plen) : Buffer.alloc(0);
+            if (!payload)
+                return null;
+            return [mt, payload];
+        };
+        // Step 1: INIT → ACK
+        socket.write(makeFrame(MT_INIT, _enc({ 1: FRAMING_VERSION })));
+        const ack = await readFrame();
+        if (!ack || ack[0] !== MT_ACK)
+            throw new Error(`Expected ACK, got ${ack?.[0]}`);
+        // Step 2: RELAY_BIND → RELAY_ACK
+        socket.write(makeFrame(MT_RELAY_BIND, _enc({
+            1: this._workerId,
+            2: this._intent,
+            3: this._models,
+        })));
+        const rack = await readFrame();
+        if (!rack || rack[0] !== MT_RELAY_ACK)
+            throw new Error(`Expected RELAY_ACK, got ${rack?.[0]}`);
+        const ackBody = _dec(rack[1]);
+        if (ackBody[1] !== "ok")
+            throw new Error(`RELAY_ACK not ok: ${JSON.stringify(ackBody)}`);
+        console.log(`[relay-worker] ${this._workerId}: bound to relay ${this._relayHost}:${this._relayPort}`);
+        if (this._onBind) {
+            try {
+                await this._onBind(this._relayHost, this._relayPort, this._workerId);
+            }
+            catch (exc) {
+                console.warn(`[relay-worker] onBind callback failed: ${exc instanceof Error ? exc.message : exc}`);
+            }
+        }
+        // Step 3: session loop
+        const pingTimer = setInterval(() => {
+            if (!socket.destroyed)
+                socket.write(makeFrame(MT_PING, _enc({ 1: Buffer.alloc(0) })));
+        }, PING_INTERVAL_MS);
+        try {
+            while (!this._stopped && !socket.destroyed) {
+                const frame = await readFrame();
+                if (!frame)
+                    break;
+                const [mt, payload] = frame;
+                if (mt === MT_CALL) {
+                    void this._handleCall(payload, socket);
+                }
+                else if (mt === MT_PONG || mt === MT_PING) {
+                    // keepalive acknowledged / or relay's keepalive
+                }
+                else if (mt === 0x07) {
+                    break; // CLOSE
+                }
+            }
+        }
+        finally {
+            clearInterval(pingTimer);
+        }
+    }
+    async _handleCall(payload, socket) {
+        let callId = "";
+        let result;
+        try {
+            const body = _dec(payload);
+            callId = String(body[15] ?? "");
+            const raw5 = body[5];
+            const taskStr = Buffer.isBuffer(raw5) ? raw5.toString() : String(raw5 ?? "{}");
+            const task = JSON.parse(taskStr);
+            result = await this._handler(task);
+        }
+        catch (exc) {
+            result = { error: exc instanceof Error ? exc.message : String(exc) };
+        }
+        try {
+            const respPayload = _enc({ 15: callId, 5: Buffer.from(JSON.stringify(result)) });
+            socket.write(makeFrame(MT_RESPONSE, respPayload));
+        }
+        catch (exc) {
+            console.warn(`[relay-worker] failed to send RESPONSE: ${exc}`);
+        }
+    }
+}
+exports.RelayWorkerClient = RelayWorkerClient;
+//# sourceMappingURL=relay_worker_client.js.map

package/dist/relay_worker_client.js.map

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

package/dist/scheduler.d.ts

@@ -0,0 +1,23 @@
+/**
+ * QoS-aware admission policy for the provider serve path (parity Block C, #340).
+ *
+ * Port of the QoS *contract* from iicp-adapter `scheduling/queue.py`. The adapter runs a
+ * full PriorityQueue dispatcher; the SDK serve gate is deliberately fail-fast (queuing
+ * would hide overload from the proxy). To close the cat-8 parity gap without contradicting
+ * that design, the SDK applies QoS-aware admission:
+ *
+ *   - realtime / interactive → queue-eligible: wait briefly (QUEUE_WAIT_MS) for a slot.
+ *   - batch / best-effort / unspecified → fail fast with IICP-E021.
+ *
+ * Priority ordering (lower = higher priority) is exposed for telemetry parity.
+ */
+export declare const QOS_PRIORITY: Record<string, number>;
+/** Tiers that wait briefly for a slot rather than failing fast at capacity. */
+export declare const QUEUE_ELIGIBLE: ReadonlySet<string>;
+/** Bounded wait for queue-eligible tiers (ms). */
+export declare const QUEUE_WAIT_MS = 2000;
+/** Priority rank for a QoS class (lower = higher priority; unknown → 3). */
+export declare function qosPriority(qos: string | null | undefined): number;
+/** True if a task of this QoS class should wait briefly for a slot at capacity. */
+export declare function isQueueEligible(qos: string | null | undefined): boolean;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAGH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAM/C,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAAwC,CAAC;AAExF,kDAAkD;AAClD,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGlE;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEvE"}

package/dist/scheduler.js

@@ -0,0 +1,42 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * QoS-aware admission policy for the provider serve path (parity Block C, #340).
+ *
+ * Port of the QoS *contract* from iicp-adapter `scheduling/queue.py`. The adapter runs a
+ * full PriorityQueue dispatcher; the SDK serve gate is deliberately fail-fast (queuing
+ * would hide overload from the proxy). To close the cat-8 parity gap without contradicting
+ * that design, the SDK applies QoS-aware admission:
+ *
+ *   - realtime / interactive → queue-eligible: wait briefly (QUEUE_WAIT_MS) for a slot.
+ *   - batch / best-effort / unspecified → fail fast with IICP-E021.
+ *
+ * Priority ordering (lower = higher priority) is exposed for telemetry parity.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUEUE_WAIT_MS = exports.QUEUE_ELIGIBLE = exports.QOS_PRIORITY = void 0;
+exports.qosPriority = qosPriority;
+exports.isQueueEligible = isQueueEligible;
+// Lower value = higher priority. Both spellings accepted (adapter uses "best-effort").
+exports.QOS_PRIORITY = {
+    realtime: 0,
+    interactive: 1,
+    batch: 2,
+    best_effort: 3,
+    "best-effort": 3,
+};
+/** Tiers that wait briefly for a slot rather than failing fast at capacity. */
+exports.QUEUE_ELIGIBLE = new Set(["realtime", "interactive"]);
+/** Bounded wait for queue-eligible tiers (ms). */
+exports.QUEUE_WAIT_MS = 2000;
+/** Priority rank for a QoS class (lower = higher priority; unknown → 3). */
+function qosPriority(qos) {
+    if (qos == null)
+        return 3;
+    return exports.QOS_PRIORITY[qos] ?? 3;
+}
+/** True if a task of this QoS class should wait briefly for a slot at capacity. */
+function isQueueEligible(qos) {
+    return qos != null && exports.QUEUE_ELIGIBLE.has(qos);
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":";AAAA,sCAAsC;AACtC;;;;;;;;;;;;GAYG;;;AAkBH,kCAGC;AAGD,0CAEC;AAxBD,uFAAuF;AAC1E,QAAA,YAAY,GAA2B;IAClD,QAAQ,EAAE,CAAC;IACX,WAAW,EAAE,CAAC;IACd,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,CAAC;IACd,aAAa,EAAE,CAAC;CACjB,CAAC;AAEF,+EAA+E;AAClE,QAAA,cAAc,GAAwB,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC;AAExF,kDAAkD;AACrC,QAAA,aAAa,GAAG,IAAI,CAAC;AAElC,4EAA4E;AAC5E,SAAgB,WAAW,CAAC,GAA8B;IACxD,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC;IAC1B,OAAO,oBAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,mFAAmF;AACnF,SAAgB,eAAe,CAAC,GAA8B;IAC5D,OAAO,GAAG,IAAI,IAAI,IAAI,sBAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAChD,CAAC"}

package/dist/token_validator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Constant-time bearer-token validation (parity Block E, #340).
+ *
+ * Port of iicp-adapter `services/token_validator.py`. Compares a presented token against
+ * the expected one with `crypto.timingSafeEqual` so a timing side-channel can't recover
+ * the token byte-by-byte. The expected token is updated after registration.
+ */
+export declare class TokenValidator {
+    private expected;
+    constructor(expectedToken?: string);
+    isValid(presented: string | null | undefined): boolean;
+    /** Set the expected token after registration (directory-issued). */
+    updateToken(newToken: string): void;
+}
+//# sourceMappingURL=token_validator.d.ts.map

package/dist/token_validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token_validator.d.ts","sourceRoot":"","sources":["../src/token_validator.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAIH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAS;gBAEb,aAAa,SAAK;IAI9B,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;IAStD,oEAAoE;IACpE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CAGpC"}