deepdebug-local-agent 1.3.0 → 1.4.0

package/src/la-protocol-v2/session.js

@@ -0,0 +1,650 @@
+/**
+ * session.js - the Local Agent side of protocol v2 (F3-05b). Contract: docs/contracts/la-protocol-v2 of
+ * vh-api-gateway, copied to ./contract (CONTRACT_SOURCE.json says which commit). Design: vault
+ * "Fase 3 Desenho Tecnico 2026-10-28" sec. 4.2. Gateway side: LaV2Session (F3-05a).
+ *
+ * One V2Session lives as long as the tunnel and survives dropped sockets (resume, 90 s on the gateway):
+ *
+ *   attach(transport)  -> register (+ resume{sessionId,lastRecvSeq}) then hello; CP answers `ready`
+ *   handleText(text)   -> inbound pipeline, in the SAME order as the gateway's rules:
+ *                         size, parse (duplicate keys refused), allowlist, schema, tenant, agent,
+ *                         direction, handshake state, signature, seq, handler
+ *   enqueue/send       -> outbound: allowlist + direction + schema (Ajv, strict) BEFORE a byte is written,
+ *                         seq per direction, piggy-backed ack, at most `maxInFlight` frames unacked
+ *                         (the rest wait in a bounded queue = backpressure), retransmission after
+ *                         ackTimeoutMs (same seq and msgId, at most maxRetries), dedupe by seq+msgId
+ *
+ * What it never does: put frame content in a log, a metric, an error frame or an exception message;
+ * execute anything itself (handlers are registered by type; with none the frame is acked `rejected`);
+ * read the tenant from a payload (tenantId/agentId are the configured ones).
+ */
+import crypto from "node:crypto";
+import { EventEmitter } from "node:events";
+import { loadContract } from "./contract.js";
+import { ProtocolError, closeCodeOf, isFatal, isRetryable } from "./errors.js";
+import { parseStrict } from "./strict-json.js";
+import { ChunkStreamTracker } from "./chunks.js";
+import { verifyWsEnvelope } from "../utils/request-signing.js";
+
+export const STATE = Object.freeze({ IDLE: "idle", AWAIT_READY: "await_ready", READY: "ready", DETACHED: "detached", CLOSED: "closed" });
+
+const WORKSPACE_ID = /^[A-Za-z0-9_.-]{0,64}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const CAPABILITY = /^[a-z0-9]+([._-][a-z0-9]+)*$/;
+const DEDUPE_ENTRIES = 512;
+const noop = () => {};
+
+const DEFAULTS = Object.freeze({
+    handshakeTimeoutMs: 10_000,
+    maxInFlight: 8,           // LA->CP data frames not yet acked
+    maxQueued: 256,           // frames waiting for a slot; beyond it enqueue() refuses (rate_limited)
+    maxInboundQueue: 128,     // CP->LA frames waiting to be processed (the CP never has more than 32 unacked)
+    resumeWindowMs: 120_000,  // the gateway keeps a detached session 90 s
+    handlerAckMs: 2_000,      // a handler that has not decided by then is acked `accepted` (it goes on)
+    bufferHighWater: 512 * 1024,
+    heartbeatMs: null,        // tests only: overrides ready.limits.heartbeatSeconds
+});
+
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+function deepEqual(a, b) {
+    if (a === b) return true;
+    if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") return false;
+    if (Array.isArray(a) !== Array.isArray(b)) return false;
+    if (Array.isArray(a)) return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]));
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    return ka.length === kb.length && ka.every((k) => Object.hasOwn(b, k) && deepEqual(a[k], b[k]));
+}
+
+export class V2Session extends EventEmitter {
+    /**
+     * @param {object} o
+     * @param {string} o.tenantId             lower-case UUID of the tenant (configured, never read from a payload)
+     * @param {string} o.agentId              lower-case UUID of the agent authorization
+     * @param {string} [o.workspaceId]        workspace of this agent for the envelope ("" when unknown)
+     * @param {{mode:string}} o.signing       the signing config of request-signing.js (mode + trusted keys + nonce cache)
+     * @param {string} o.laVersion            semver
+     * @param {string[]} [o.capabilities]
+     * @param {() => Array<{workspaceId:string,pathSha256?:string}>} [o.getWorkspaces]
+     * @param {() => {diskFreeBytes?:number, graphify?:object}} [o.getHealth]
+     * @param {{info:Function,warn:Function}} [o.log]
+     * @param {() => number} [o.now]
+     * @param {object} [o.options]            overrides of DEFAULTS
+     */
+    constructor(o) {
+        super();
+        this.contract = loadContract();
+        this.tenantId = o.tenantId;
+        this.agentId = o.agentId;
+        this.workspaceId = o.workspaceId || "";
+        this.signing = o.signing;
+        this.laVersion = o.laVersion;
+        this.capabilities = [...new Set(o.capabilities || [])].filter((c) => CAPABILITY.test(c) && c.length <= 48).sort();
+        this.getWorkspaces = o.getWorkspaces || (() => []);
+        this.getHealth = o.getHealth || (() => ({}));
+        this.log = o.log || { info: noop, warn: noop };
+        this.now = o.now || Date.now;
+        this.opts = { ...DEFAULTS, ...(o.options || {}) };
+
+        const L = this.contract.limits;
+        this.limits = {
+            maxFrameBytes: L.maxFrameBytes, chunkRawBytes: L.chunkRawBytes, maxChunks: L.maxChunks,
+            ackTimeoutMs: L.ackTimeoutMs, maxRetries: L.maxRetries, heartbeatSeconds: L.heartbeatSeconds,
+        };
+        this.state = STATE.IDLE;
+        this.sessionId = null;        // set by `ready`
+        this.everReady = false;
+        this.sendSeq = 0;             // last LA->CP data seq assigned
+        this.lastRecvSeq = 0;         // highest contiguous CP->LA data seq received
+        this.recvRing = new Map();    // seq -> msgId of the last DEDUPE_ENTRIES received
+        this.unacked = new Map();     // seq -> outbound record, in seq order
+        this.waiters = [];            // frames waiting for a window slot (FIFO)
+        this.handlers = new Map();    // type -> fn(ctx) -> {accept:true}|{reject:code}
+        this.tracker = new ChunkStreamTracker(this.limits);
+        this.transport = null;
+        this.inbound = Promise.resolve();
+        this.inboundDepth = 0;
+        this.timers = { handshake: null, heartbeat: null, expire: null, drain: null };
+        this.stats = {
+            framesIn: 0, framesOut: 0, dataOut: 0, retransmits: 0, duplicatesIn: 0, rejectedIn: {}, ackedOut: 0,
+            nonText: 0, unverified: 0,
+        };
+    }
+
+    // ---------------------------------------------------------------------------------------- public API
+
+    /** Registers the handler of a CP->LA data type. Without one the frame is acked `rejected` (protocol_unsupported). */
+    setHandler(type, fn) {
+        if (!this.contract.canReceive(type) || this.contract.typeInfo(type).control) throw new ProtocolError("unknown_type");
+        this.handlers.set(type, fn);
+    }
+
+    /** A new socket is open: starts (or resumes) the handshake. */
+    attach(transport) {
+        if (this.state === STATE.CLOSED) throw new ProtocolError("agent_offline", "session closed");
+        this.#cancelTimer("expire");
+        this.#cancelTimer("handshake");
+        this.#stopHeartbeat();
+        this.transport = transport;
+        this.state = STATE.AWAIT_READY;
+        for (const rec of this.unacked.values()) this.#cancelRecTimer(rec);
+        const payload = {
+            protocol: 2,
+            laVersion: this.laVersion,
+            capabilities: this.capabilities,
+            signatureMode: this.signing.mode,
+            workspaces: this.#workspaces(),
+            ...(this.everReady && this.sessionId ? { resume: { sessionId: this.sessionId, lastRecvSeq: this.lastRecvSeq } } : {}),
+        };
+        this.#sendControl("register", payload);
+        const health = this.getHealth() || {};
+        const hello = {
+            laVersion: this.laVersion,
+            capabilities: this.capabilities,
+            signatureMode: this.signing.mode,
+            clockEpochMs: this.now(),
+            diskFreeBytes: Number.isSafeInteger(health.diskFreeBytes) && health.diskFreeBytes >= 0 ? health.diskFreeBytes : 0,
+            queueDepth: Math.min(this.unacked.size + this.waiters.length, 100000),
+            inflight: Math.min(this.unacked.size, 10000),
+            ...(health.graphify ? { graphify: health.graphify } : {}),
+        };
+        this.#sendControl("hello", hello);
+        this.timers.handshake = this.#timer(() => {
+            this.timers.handshake = null;
+            if (this.state === STATE.AWAIT_READY && this.transport === transport) this.emit("handshake-timeout");
+        }, this.opts.handshakeTimeoutMs);
+    }
+
+    /** The socket is gone. A session that was ready stays resumable for resumeWindowMs. */
+    detach(transport) {
+        if (transport !== this.transport || this.state === STATE.CLOSED) return;
+        this.#onTransportGone();
+    }
+
+    /** Gives up v2 on the current connection (fallback to v1): nothing of this session is resumable. */
+    abandon() {
+        this.#cancelTimer("handshake");
+        this.#teardown("agent_offline");
+        this.transport = null;
+        this.state = STATE.IDLE;
+    }
+
+    /** Process shutdown. */
+    close() {
+        this.#teardown("agent_offline");
+        this.transport = null;
+        this.state = STATE.CLOSED;
+        this.removeAllListeners();
+    }
+
+    /** One CP->LA text frame (call from the socket 'message' event). Never throws. */
+    handleText(text, transport = this.transport, isBinary = false) {
+        if (this.state === STATE.CLOSED || transport !== this.transport || !this.transport) return;
+        if (isBinary) { this.stats.nonText++; return; }
+        if (this.inboundDepth >= this.opts.maxInboundQueue) { this.#refuse("rate_limited"); return; }
+        this.inboundDepth++;
+        this.inbound = this.inbound
+            .then(() => this.#process(text, transport))
+            .catch(() => this.#refuse("internal"))
+            .finally(() => { this.inboundDepth--; });
+    }
+
+    /**
+     * Queues one LA->CP data frame. Resolves, once the frame has been written, with {seq, msgId, acked};
+     * `acked` settles when the CP acked it (rejects with ProtocolError: rejected ack, timeout, reset).
+     * The promise itself rejects BEFORE anything is written when the frame is not allowed
+     * (unknown_type, wrong_direction, schema_violation, frame_too_large, chunk_*, not_ready, rate_limited).
+     */
+    enqueue(type, payload, { requestId, workspaceId, chunk } = {}) {
+        let prepared;
+        try {
+            prepared = this.#prepare(type, payload, { requestId, workspaceId, chunk });
+        } catch (e) {
+            return Promise.reject(e);
+        }
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ ...prepared, resolve, reject });
+            this.#pump();
+        });
+    }
+
+    /** enqueue() + wait for the ack. */
+    async send(type, payload, opts) {
+        const h = await this.enqueue(type, payload, opts);
+        await h.acked;
+    }
+
+    /** Drops the frames of a request that are still waiting for a slot (cancellation of a chunk stream). */
+    cancelWaiting(requestId) {
+        const keep = [];
+        for (const w of this.waiters) {
+            if (w.requestId === requestId) {
+                if (w.type === "content.response") this.tracker.forget(requestId);
+                w.reject(new ProtocolError("agent_offline", "cancelled"));
+            } else keep.push(w);
+        }
+        this.waiters = keep;
+    }
+
+    get snapshot() {
+        return { state: this.state, sessionId: this.sessionId, sendSeq: this.sendSeq, lastRecvSeq: this.lastRecvSeq,
+            unacked: this.unacked.size, waiting: this.waiters.length, limits: { ...this.limits }, stats: { ...this.stats } };
+    }
+
+    // ---------------------------------------------------------------------------------------- outbound
+
+    #workspaces() {
+        let list = [];
+        try { list = this.getWorkspaces() || []; } catch { list = []; }
+        const out = [];
+        for (const w of list) {
+            if (!w || typeof w.workspaceId !== "string" || !WORKSPACE_ID.test(w.workspaceId)) continue;
+            out.push({ workspaceId: w.workspaceId, ...(typeof w.pathSha256 === "string" && SHA256.test(w.pathSha256) ? { pathSha256: w.pathSha256 } : {}) });
+            if (out.length >= 64) break;
+        }
+        return out;
+    }
+
+    #envelope(type, seq, { requestId, workspaceId, chunk, ack } = {}) {
+        return {
+            schemaVersion: 2,
+            type,
+            msgId: crypto.randomUUID(),
+            seq,
+            ...(ack ? { ack } : {}),
+            ...(requestId ? { requestId } : {}),
+            tenantId: this.tenantId,
+            agentId: this.agentId,
+            workspaceId: workspaceId ?? this.workspaceId,
+            ts: new Date(this.now()).toISOString(),
+            ...(chunk ? { chunk } : {}),
+        };
+    }
+
+    /** Control frames (seq 0): register hello ack error. Validated like everything else; a bug here is an `internal` error. */
+    #sendControl(type, payload, extra) {
+        const frame = { ...this.#envelope(type, 0, extra), payload };
+        const v = this.contract.validateFrame(frame);
+        if (!v.ok) {
+            this.log.warn(`[la-v2] internal: control frame ${type} failed the contract (${v.code})`);
+            throw new ProtocolError("internal", `control frame ${type}`);
+        }
+        this.#write(JSON.stringify(frame));
+        return frame;
+    }
+
+    #write(text) {
+        if (!this.transport) return false;
+        this.stats.framesOut++;
+        try { this.transport.send(text); return true; } catch { return false; }
+    }
+
+    /** Everything that can be refused before a frame is queued (so the caller gets the error, nothing is written). */
+    #prepare(type, payload, { requestId, workspaceId, chunk }) {
+        if (this.state === STATE.CLOSED) throw new ProtocolError("agent_offline");
+        if (!this.contract.typeInfo(type)) throw new ProtocolError("unknown_type");
+        if (!this.contract.canSend(type)) throw new ProtocolError("wrong_direction");
+        if (this.contract.typeInfo(type).control) throw new ProtocolError("wrong_direction", "control frames belong to the session");
+        if (this.state !== STATE.READY && !(this.everReady && (this.state === STATE.DETACHED || this.state === STATE.AWAIT_READY))) {
+            throw new ProtocolError("not_ready");
+        }
+        if (this.waiters.length >= this.opts.maxQueued) throw new ProtocolError("rate_limited", "send queue full");
+        // dry-run with a placeholder seq: the real one is assigned when the frame leaves the queue
+        const probe = { ...this.#envelope(type, 1, { requestId, workspaceId, chunk, ack: this.lastRecvSeq }), payload };
+        const text = JSON.stringify(probe);
+        if (Buffer.byteLength(text, "utf8") + 24 > this.limits.maxFrameBytes) throw new ProtocolError("frame_too_large");
+        const v = this.contract.validateFrame(probe);
+        if (!v.ok) throw new ProtocolError(v.code);
+        if (type === "content.response") {
+            const decoded = Buffer.from(payload.data, "base64").length;
+            const bad = this.tracker.accept(requestId, chunk, decoded);
+            if (bad) throw new ProtocolError(bad);
+        }
+        return { type, payload, requestId, workspaceId, chunk };
+    }
+
+    #canTransmit() {
+        if (this.state !== STATE.READY || !this.transport) return false;
+        if (this.unacked.size >= this.opts.maxInFlight) return false;
+        const buffered = typeof this.transport.bufferedAmount === "function" ? this.transport.bufferedAmount() : 0;
+        if (buffered > this.opts.bufferHighWater) {
+            if (!this.timers.drain) this.timers.drain = this.#timer(() => { this.timers.drain = null; this.#pump(); }, 20);
+            return false;
+        }
+        return true;
+    }
+
+    #pump() {
+        while (this.waiters.length > 0 && this.#canTransmit()) {
+            const w = this.waiters.shift();
+            const seq = ++this.sendSeq;
+            const frame = { ...this.#envelope(w.type, seq, { requestId: w.requestId, workspaceId: w.workspaceId, chunk: w.chunk, ack: this.lastRecvSeq }), payload: w.payload };
+            const text = JSON.stringify(frame);
+            let settle;
+            const acked = new Promise((resolve, reject) => { settle = { resolve, reject }; });
+            acked.catch(noop); // the caller may ignore it; a rejection must never be "unhandled"
+            const rec = { seq, msgId: frame.msgId, type: w.type, requestId: w.requestId, text, retries: 0, timer: null, settle };
+            this.unacked.set(seq, rec);
+            this.stats.dataOut++;
+            this.#write(text);
+            this.#armRecTimer(rec);
+            w.resolve({ seq, msgId: frame.msgId, acked });
+        }
+    }
+
+    #armRecTimer(rec) {
+        this.#cancelRecTimer(rec);
+        rec.timer = this.#timer(() => this.#onAckTimeout(rec), this.limits.ackTimeoutMs);
+    }
+
+    #cancelRecTimer(rec) {
+        if (rec.timer) { clearTimeout(rec.timer); rec.timer = null; }
+    }
+
+    #onAckTimeout(rec) {
+        rec.timer = null;
+        if (this.state !== STATE.READY || this.unacked.get(rec.seq) !== rec) return;
+        if (rec.retries >= this.limits.maxRetries) {
+            // The CP never confirmed: the caller gets `timeout`, the frame stays for a resume, the connection drops.
+            rec.settle.reject(new ProtocolError("timeout", "no ack"));
+            this.emit("timeout");
+            this.#closeTransport(closeCodeOf("timeout"), "ack_timeout");
+            return;
+        }
+        rec.retries++;
+        this.stats.retransmits++;
+        this.#write(rec.text); // identical bytes: same seq, same msgId
+        this.#armRecTimer(rec);
+    }
+
+    #ackUpTo(n) {
+        if (!Number.isSafeInteger(n) || n <= 0) return;
+        for (const [seq, rec] of this.unacked) {
+            if (seq > n) break;
+            this.#cancelRecTimer(rec);
+            this.unacked.delete(seq);
+            this.stats.ackedOut++;
+            rec.settle.resolve();
+        }
+        this.#pump();
+    }
+
+    #rejectAcked(seq, code) {
+        const rec = this.unacked.get(seq);
+        if (!rec) return;
+        this.#cancelRecTimer(rec);
+        this.unacked.delete(seq);
+        rec.settle.reject(new ProtocolError(code, "rejected by the control plane"));
+        this.#pump();
+    }
+
+    // ---------------------------------------------------------------------------------------- inbound
+
+    async #process(text, transport) {
+        if (this.state === STATE.CLOSED || transport !== this.transport) return;
+        this.stats.framesIn++;
+        // 1. size (before any parsing)
+        if (typeof text !== "string" || Buffer.byteLength(text, "utf8") > this.limits.maxFrameBytes) return this.#refuse("frame_too_large");
+        // 2. parse, duplicate keys refused
+        let f;
+        try { f = parseStrict(text); } catch { return this.#refuse("bad_frame"); }
+        if (!isPlainObject(f)) return this.#refuse("bad_frame");
+        const ref = { refSeq: Number.isSafeInteger(f.seq) && f.seq > 0 ? f.seq : undefined, refMsgId: typeof f.msgId === "string" && f.msgId.length === 36 ? f.msgId : undefined };
+        // 3-4. allowlist + closed schema
+        const v = this.contract.validateFrame(f);
+        if (!v.ok) return this.#refuse(v.code, ref);
+        // 5-6. tenant and agent are the configured ones
+        if (f.tenantId !== this.tenantId) return this.#refuse("tenant_mismatch", ref);
+        if (f.agentId !== undefined && f.agentId !== this.agentId) return this.#refuse("agent_mismatch", ref);
+        // 7. direction
+        if (!this.contract.canReceive(f.type)) return this.#refuse("wrong_direction", ref);
+        // 8. handshake state
+        if (this.state === STATE.AWAIT_READY) {
+            if (f.type !== "ready" && f.type !== "error" && f.type !== "ack") return this.#refuse("not_ready", ref);
+        } else if (this.state === STATE.READY && f.type === "ready") {
+            return this.#refuse("handshake_violation", ref);
+        } else if (this.state !== STATE.READY) {
+            return;
+        }
+        // 9. signature of the signed types (ready included)
+        const info = this.contract.typeInfo(f.type);
+        let params = f.payload;
+        if (info.signed) {
+            const bad = this.#verifySigned(f);
+            if (bad) return this.#refuse(bad, ref);
+            if (this.signing.mode !== "enforce") this.stats.unverified++;
+        }
+        if (f.type === "ready") return this.#onReady(f);
+        if (f.type === "ack") return this.#onAck(f);
+        if (f.type === "error") return this.#onPeerError(f);
+        return this.#onData(f, params, ref);
+    }
+
+    /**
+     * paramsRaw must equal payload (what is executed is the signed text), sig must be bound to this
+     * frame's tenant and workspace, and the Ed25519 signature must verify (same canonical string as v1:
+     * method WS, path = type). Mode off skips the cryptography, warn logs and goes on, enforce refuses.
+     */
+    #verifySigned(f) {
+        let signed;
+        try { signed = parseStrict(f.paramsRaw); } catch { return "params_mismatch"; }
+        if (!deepEqual(signed, f.payload)) return "params_mismatch";
+        if (f.sig.tenantId !== f.tenantId || f.sig.workspaceId !== f.workspaceId) return "tenant_mismatch";
+        const out = verifyWsEnvelope({ command: f.type, paramsRaw: f.paramsRaw, sig: f.sig }, this.signing);
+        return out.ok ? null : "unauthorized";
+    }
+
+    #onReady(f) {
+        const p = f.payload;
+        if (p.resumed) {
+            // only a session we offered to resume, and only a position we can have reached
+            if (!this.everReady || p.sessionId !== this.sessionId || p.peerLastSeq > this.sendSeq) return this.#refuse("handshake_violation");
+        }
+        const lim = p.limits;
+        const L = this.contract.limits;
+        this.limits = {
+            maxFrameBytes: Math.min(lim.maxFrameBytes, L.maxFrameBytes),
+            chunkRawBytes: Math.min(lim.chunkRawBytes, L.chunkRawBytes),
+            maxChunks: Math.min(lim.maxChunks, L.maxChunks),
+            ackTimeoutMs: lim.ackTimeoutMs,
+            maxRetries: Math.min(lim.maxRetries, L.maxRetries),
+            heartbeatSeconds: lim.heartbeatSeconds,
+        };
+        this.tracker.chunkRawBytes = this.limits.chunkRawBytes;
+        this.tracker.maxChunks = this.limits.maxChunks;
+        this.#cancelTimer("handshake");
+        if (!p.resumed) this.#resetSession();
+        this.sessionId = p.sessionId;
+        this.state = STATE.READY;
+        this.everReady = true;
+        if (p.resumed) {
+            this.#ackUpTo(p.peerLastSeq);
+            for (const rec of this.unacked.values()) { // what the CP never saw goes again, same seq and msgId
+                rec.retries = 0;
+                this.stats.retransmits++;
+                this.#write(rec.text);
+                this.#armRecTimer(rec);
+            }
+        }
+        this.#startHeartbeat();
+        this.log.info(`[la-v2] ready resumed=${p.resumed} session=${p.sessionId.slice(0, 8)} peerLastSeq=${p.peerLastSeq}`);
+        this.emit("ready", { resumed: p.resumed, sessionId: p.sessionId, limits: { ...this.limits } });
+        this.#pump();
+    }
+
+    #onAck(f) {
+        if (this.state !== STATE.READY) return;
+        const { ackSeq, status, errorCode } = f.payload;
+        if (ackSeq > this.sendSeq) return; // acks a frame we never sent: ignored
+        if (status === "rejected") {
+            this.#ackUpTo(ackSeq - 1);
+            this.#rejectAcked(ackSeq, errorCode || "internal");
+        } else {
+            this.#ackUpTo(ackSeq);
+        }
+    }
+
+    #onPeerError(f) {
+        const p = f.payload;
+        this.stats.rejectedIn[`peer_${p.code}`] = (this.stats.rejectedIn[`peer_${p.code}`] || 0) + 1;
+        this.log.warn(`[la-v2] control plane refused a frame: ${p.code}`);
+        if (this.state === STATE.AWAIT_READY) {
+            if (p.code === "protocol_unsupported") this.emit("unsupported");
+            else this.emit("rejected", p.code);
+            return;
+        }
+        if (p.refSeq !== undefined) this.#rejectAcked(p.refSeq, p.code);
+        this.emit("peer-error", p.code);
+    }
+
+    async #onData(f, params, ref) {
+        const { seq, msgId } = f;
+        if (seq <= this.lastRecvSeq) {
+            if (this.recvRing.get(seq) === msgId) { // a retransmission (our ack was lost): re-ack, never execute twice
+                this.stats.duplicatesIn++;
+                this.#sendAck(seq, "duplicate");
+                return;
+            }
+            return this.#refuse("seq_replayed", ref);
+        }
+        if (seq !== this.lastRecvSeq + 1) return this.#refuse("seq_gap", ref);
+        this.lastRecvSeq = seq;
+        this.recvRing.set(seq, msgId);
+        while (this.recvRing.size > DEDUPE_ENTRIES) this.recvRing.delete(this.recvRing.keys().next().value);
+        if (f.ack !== undefined) this.#ackUpTo(f.ack);
+
+        const handler = this.handlers.get(f.type);
+        if (!handler) { this.#sendAck(seq, "rejected", "protocol_unsupported"); return; }
+        const ctx = Object.freeze({ type: f.type, seq, msgId, requestId: f.requestId, workspaceId: f.workspaceId, params });
+        let verdict;
+        let slow;
+        try {
+            const run = Promise.resolve().then(() => handler(ctx));
+            run.catch(noop);
+            // a handler that has not decided in handlerAckMs is acked `accepted` (it goes on in the background)
+            verdict = await Promise.race([run, new Promise((r) => { slow = this.#timer(() => r({ accept: true }), this.opts.handlerAckMs); })]);
+        } catch {
+            verdict = { reject: "internal" };
+        } finally {
+            clearTimeout(slow);
+        }
+        if (verdict && verdict.reject) this.#sendAck(seq, "rejected", verdict.reject);
+        else this.#sendAck(seq, "accepted");
+    }
+
+    #sendAck(ackSeq, status, errorCode) {
+        if (this.state !== STATE.READY || !this.transport) return;
+        const code = errorCode && this.contract.errorCodes.includes(errorCode) ? errorCode : undefined;
+        try {
+            this.#sendControl("ack", { ackSeq, status, ...(status === "rejected" ? { errorCode: code || "internal" } : {}) });
+        } catch { /* already logged */ }
+    }
+
+    // ---------------------------------------------------------------------------------------- errors, close
+
+    /** Refuses a frame: error frame with the wire code only (never an echo), close when the code is fatal. */
+    #refuse(code, ref = {}) {
+        this.stats.rejectedIn[code] = (this.stats.rejectedIn[code] || 0) + 1;
+        this.log.warn(`[la-v2] refused an inbound frame: ${code}`);
+        const fatal = isFatal(code);
+        const payload = {
+            code,
+            retryable: isRetryable(code),
+            ...(ref.refSeq !== undefined ? { refSeq: ref.refSeq } : {}),
+            ...(ref.refMsgId ? { refMsgId: ref.refMsgId } : {}),
+            ...(fatal ? { closeCode: closeCodeOf(code) } : {}),
+        };
+        try { this.#sendControl("error", payload); } catch { /* logged */ }
+        this.emit("refused", code);
+        if (fatal) this.#closeTransport(closeCodeOf(code), code);
+    }
+
+    #closeTransport(code, reason) {
+        const t = this.transport;
+        if (t) { try { t.close(code, reason); } catch { /* socket already gone */ } }
+        this.#onTransportGone();
+    }
+
+    #onTransportGone() {
+        this.#cancelTimer("handshake");
+        this.#stopHeartbeat();
+        for (const rec of this.unacked.values()) this.#cancelRecTimer(rec);
+        this.transport = null;
+        if (!this.everReady) { this.state = STATE.IDLE; this.#failAll("agent_offline"); return; }
+        this.state = STATE.DETACHED;
+        this.#cancelTimer("expire");
+        this.timers.expire = this.#timer(() => { this.timers.expire = null; this.#teardown("agent_offline"); this.state = STATE.IDLE; }, this.opts.resumeWindowMs);
+        this.emit("detached");
+    }
+
+    /** Nothing of the session survives: every pending frame fails and the next register will not resume. */
+    #teardown(code) {
+        this.#cancelTimer("expire");
+        this.#cancelTimer("handshake");
+        this.#cancelTimer("drain");
+        this.#stopHeartbeat();
+        this.#failAll(code);
+        this.sessionId = null;
+        this.everReady = false;
+        this.sendSeq = 0;
+        this.lastRecvSeq = 0;
+        this.recvRing.clear();
+        this.tracker.clear();
+    }
+
+    /** The CP did not resume us: restart both numberings and fail what was in flight (README: "resumed:false"). */
+    #resetSession() {
+        this.#failAll("agent_offline", { keepWaiting: true });
+        this.sendSeq = 0;
+        this.lastRecvSeq = 0;
+        this.recvRing.clear();
+        this.tracker.clear();
+    }
+
+    #failAll(code, { keepWaiting = false } = {}) {
+        for (const rec of this.unacked.values()) { this.#cancelRecTimer(rec); rec.settle.reject(new ProtocolError(code)); }
+        this.unacked.clear();
+        const keep = [];
+        for (const w of this.waiters) {
+            // a content stream of the old session cannot continue in a new one (the CP would see chunk n without chunk 0)
+            if (!keepWaiting || w.type === "content.response") w.reject(new ProtocolError(code));
+            else keep.push(w);
+        }
+        this.waiters = keep;
+    }
+
+    // ---------------------------------------------------------------------------------------- heartbeat, timers
+
+    #startHeartbeat() {
+        this.#stopHeartbeat();
+        const ms = this.opts.heartbeatMs || Math.max(1000, this.limits.heartbeatSeconds * 1000);
+        this.timers.heartbeat = setInterval(() => {
+            if (this.state !== STATE.READY || this.unacked.size >= this.opts.maxInFlight) return;
+            const h = this.getHealth() || {};
+            this.enqueue("heartbeat", {
+                signatureMode: this.signing.mode,
+                clockEpochMs: this.now(),
+                diskFreeBytes: Number.isSafeInteger(h.diskFreeBytes) && h.diskFreeBytes >= 0 ? h.diskFreeBytes : 0,
+                queueDepth: Math.min(this.unacked.size + this.waiters.length, 100000),
+                inflight: Math.min(this.unacked.size, 10000),
+                ...(h.graphify ? { graphify: h.graphify } : {}),
+            }).catch(noop);
+        }, ms);
+        this.timers.heartbeat.unref?.();
+    }
+
+    #stopHeartbeat() {
+        if (this.timers.heartbeat) { clearInterval(this.timers.heartbeat); this.timers.heartbeat = null; }
+    }
+
+    // Not unref'd: an unacked frame, a pending handshake and a resume window are work the process is waiting for
+    // (a closed or torn-down session clears every one of them, so none outlives close()).
+    #timer(fn, ms) {
+        return setTimeout(fn, ms);
+    }
+
+    #cancelTimer(name) {
+        if (this.timers[name]) { clearTimeout(this.timers[name]); this.timers[name] = null; }
+    }
+}