@zieglar/pi-chat-exchange 0.0.0-stage → 0.2.0

package/dist/host/bound-endpoint.js

@@ -0,0 +1,176 @@
+/**
+ * HANDOFF-853274 — one host-owned Endpoint bound for a single-instance
+ * control surface (the local MCP server).
+ *
+ * This is the object injected into the MCP server as its messaging port. It
+ * carries NO endpoint parameter on any call: the Endpoint is fixed at
+ * construction from the trusted launch configuration. All authority still
+ * flows through `CeEndpointHost` (and from there through Storage); this class
+ * only adds admission gating and the opt-in lease lifecycle:
+ *
+ * - start: `beginSession({ requireUnowned: true })` — an existing ownership row
+ *   (live or expired, e.g. after a crash) refuses before any durable write.
+ *   This runtime never adopts or takes over; the separate operator-only recovery
+ *   caller must clear one exact expired owner before a normal restart.
+ * - heartbeat: `host.renew` on a fixed interval. BUSY rolled back and is
+ *   retried only at the next tick; UNCERTAIN or any authority refusal stops
+ *   the heartbeat permanently and blocks new sends (no blind retry).
+ * - shutdown: stop admitting calls, wait for in-flight calls, stop the
+ *   heartbeat, then `host.end` (release, then detach) exactly once. An unknown
+ *   outcome is reported, never retried.
+ */
+import { CeHostRefusal, } from "./endpoint-host.js";
+const defaultTimers = {
+    setInterval: (callback, ms) => {
+        const handle = setInterval(callback, ms);
+        // A heartbeat alone must never keep the process alive.
+        handle.unref();
+        return handle;
+    },
+    clearInterval: (handle) => clearInterval(handle),
+};
+export class CeBoundEndpoint {
+    #admission;
+    #host;
+    #endpointId;
+    #timers;
+    #onEvent;
+    #state = "ACTIVE";
+    #blockedReason;
+    #heartbeat;
+    #inFlight = 0;
+    #shutdown;
+    constructor(host, endpointId, options) {
+        this.#admission = options.admission;
+        this.#host = host;
+        this.#endpointId = endpointId;
+        this.#timers = options.timers ?? defaultTimers;
+        this.#onEvent = options.onEvent;
+    }
+    /** Bind the fixed Endpoint (refusing any existing ownership before writes)
+     * and start the renewal heartbeat. Throws the sanitized host refusal. */
+    static start(host, endpointId, options) {
+        if (!Number.isSafeInteger(options.renewIntervalMs) || options.renewIntervalMs < 1) {
+            throw new CeHostRefusal("CE_HOST_INVALID_REQUEST");
+        }
+        options.admission?.({ kind: "begin" });
+        host.beginSession(endpointId, { requireUnowned: true });
+        const bound = new CeBoundEndpoint(host, endpointId, options);
+        bound.#heartbeat = bound.#timers.setInterval(() => bound.#renew(), options.renewIntervalMs);
+        return bound;
+    }
+    get state() {
+        return this.#state;
+    }
+    #emit(event) {
+        try {
+            this.#onEvent?.(event);
+        }
+        catch {
+            // Observation must never affect authority or lifecycle.
+        }
+    }
+    #stopHeartbeat() {
+        if (this.#heartbeat !== undefined) {
+            this.#timers.clearInterval(this.#heartbeat);
+            this.#heartbeat = undefined;
+        }
+    }
+    #renew() {
+        if (this.#state !== "ACTIVE")
+            return;
+        try {
+            this.#admission?.({ kind: "renew" });
+            this.#host.renew(this.#endpointId);
+            this.#emit({ kind: "renewed" });
+        }
+        catch (error) {
+            const refusal = error instanceof CeHostRefusal ? error : new CeHostRefusal("CE_HOST_UNAVAILABLE");
+            if (refusal.code === "CE_HOST_BUSY") {
+                // Rolled back as a whole: the next tick may try again before expiry.
+                this.#emit({ kind: "renewal_deferred", code: refusal.code });
+                return;
+            }
+            // UNCERTAIN, authority loss, or any other refusal: never retry blindly.
+            this.#stopHeartbeat();
+            this.#state = "WRITE_BLOCKED";
+            this.#blockedReason = refusal.code;
+            this.#emit({ kind: "renewal_stopped", code: refusal.code, reason: refusal.reason });
+        }
+    }
+    #admit(write) {
+        if (this.#state === "CLOSING" || this.#state === "CLOSED") {
+            throw new CeHostRefusal("CE_HOST_UNAVAILABLE", false, "ENDPOINT_CLOSING");
+        }
+        if (write && this.#state === "WRITE_BLOCKED") {
+            throw new CeHostRefusal(this.#blockedReason === "CE_HOST_UNCERTAIN" ? "CE_HOST_UNCERTAIN" : "CE_HOST_AUTHORITY_ABSENT", false, "LEASE_RENEWAL_STOPPED");
+        }
+    }
+    #run(write, request, operation) {
+        this.#admit(write);
+        this.#admission?.(request);
+        this.#inFlight += 1;
+        try {
+            return operation();
+        }
+        finally {
+            this.#inFlight -= 1;
+        }
+    }
+    send(input) {
+        return this.#run(true, { kind: "send", to: input.to }, () => this.#host.send(this.#endpointId, { to: input.to, text: input.text, idempotencyKey: input.idempotencyKey }));
+    }
+    listInbox(input) {
+        const request = {};
+        if (input.afterAuditSequence !== undefined)
+            request.afterAuditSequence = input.afterAuditSequence;
+        if (input.pageSize !== undefined)
+            request.pageSize = input.pageSize;
+        if (input.rawScanLimit !== undefined)
+            request.rawScanLimit = input.rawScanLimit;
+        return this.#run(false, { kind: "inbox" }, () => this.#host.listInbox(this.#endpointId, request));
+    }
+    readPayload(input) {
+        return this.#run(false, { kind: "readPayload" }, () => this.#host.readPayload(this.#endpointId, { messageId: input.messageId }));
+    }
+    /** HANDOFF-CE-E2B-01 delivery ACK. It is a durable WRITE, so it runs through
+     * the same admission gate as `send`: a permanently stopped heartbeat or a
+     * closing endpoint refuses it before the host is reached. The four metadata
+     * fields are copied by the caller from an authorized read; no endpoint,
+     * session, or capability parameter exists on this call. */
+    acknowledge(input) {
+        return this.#run(true, { kind: "ack" }, () => this.#host.acknowledge(this.#endpointId, {
+            messageId: input.messageId,
+            payloadDigest: input.payloadDigest,
+            payloadLength: input.payloadLength,
+            messageCreatedAuditSequence: input.messageCreatedAuditSequence,
+        }));
+    }
+    /** Graceful, idempotent shutdown. Calls after the first return the first
+     * outcome; the release is attempted at most once per process. */
+    shutdown(drainTimeoutMs = 5_000) {
+        if (this.#shutdown !== undefined)
+            return this.#shutdown;
+        this.#state = "CLOSING";
+        this.#shutdown = (async () => {
+            const deadline = Date.now() + drainTimeoutMs;
+            while (this.#inFlight > 0 && Date.now() < deadline) {
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+            this.#stopHeartbeat();
+            try {
+                const ended = this.#host.end(this.#endpointId);
+                return Object.freeze({ released: ended.released, detached: ended.detached, code: undefined, reason: undefined });
+            }
+            catch (error) {
+                const refusal = error instanceof CeHostRefusal ? error : new CeHostRefusal("CE_HOST_UNAVAILABLE");
+                return Object.freeze({ released: false, detached: false, code: refusal.code, reason: refusal.reason });
+            }
+            finally {
+                this.#state = "CLOSED";
+            }
+        })();
+        return this.#shutdown;
+    }
+}
+//# sourceMappingURL=bound-endpoint.js.map