@fonoster/common 0.27.0 → 0.30.0

package/dist/session/schema.js

@@ -0,0 +1,397 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APP_COMMAND_SCHEMAS = exports.GATEWAY_MESSAGE_SCHEMAS = exports.recordNoteSchema = exports.handoffSchema = exports.resumeSchema = exports.holdSchema = exports.transferCompleteSchema = exports.transferSchema = exports.TRANSFER_MODES = exports.dtmfSendSchema = exports.hangupSchema = exports.clearSchema = exports.markCommandSchema = exports.subscribeSchema = exports.SUBSCRIBABLE_EVENTS = exports.listenUpdateSchema = exports.playSchema = exports.speakSchema = exports.amdResultSchema = exports.dtmfEventSchema = exports.markEventSchema = exports.outputInterruptedSchema = exports.outputDoneSchema = exports.outputStartedSchema = exports.transcriptPartialSchema = exports.turnEstimateSchema = exports.turnBackchannelSchema = exports.turnResumedSchema = exports.turnEndedSchema = exports.turnLikelyEndedSchema = exports.turnUserStartedSchema = exports.errorSchema = exports.ERROR_CODES = exports.sessionEndSchema = exports.SESSION_END_REASONS = exports.sessionStartSchema = exports.SESSION_PROTOCOL = void 0;
+exports.sessionProtocolDocument = sessionProtocolDocument;
+// The fonoster.session.v1 messages (fonoster protocol), as JSON Schema. These schemas are the source
+// of truth: TypeScript types are derived from them below, and schema/session.v1.json is exported
+// from them for other languages (see scripts/export-session-schema.ts).
+//
+// Every schema allows extra fields: both sides ignore unknown fields (voice-session, "Message
+// envelope and versioning"), so the protocol only grows.
+exports.SESSION_PROTOCOL = "fonoster.session.v1";
+const id = { type: "string", minLength: 1, maxLength: 128 };
+const catalogId = { type: "string", minLength: 1 };
+// ---- gateway → app ---------------------------------------------------------------------
+exports.sessionStartSchema = {
+    type: "object",
+    required: [
+        "type",
+        "protocol",
+        "sessionRef",
+        "callRef",
+        "appRef",
+        "direction",
+        "from",
+        "to",
+        "metadata",
+        "handoff",
+        "audio",
+        "tracks",
+        "speech"
+    ],
+    properties: {
+        type: { const: "session.start" },
+        protocol: { const: exports.SESSION_PROTOCOL },
+        sessionRef: { type: "string" },
+        callRef: { type: "string" },
+        appRef: { type: "string" },
+        direction: { enum: ["inbound", "outbound"] },
+        from: { type: "string" },
+        to: { type: "string" },
+        metadata: { type: "object" },
+        handoff: { oneOf: [{ type: "null" }, { type: "object" }] },
+        audio: {
+            type: "object",
+            required: ["codec", "rate"],
+            properties: {
+                // The native format menu (voice-session OQ8, AO-B4); Opus is not offered over WebSocket.
+                codec: { enum: ["pcm16", "pcmu"] },
+                rate: { enum: [8000, 16000, 24000] }
+            }
+        },
+        tracks: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["id", "side", "kind", "codec"],
+                properties: {
+                    id: { type: "integer", minimum: 0, maximum: 255 },
+                    side: { enum: ["inbound", "outbound"] },
+                    kind: { enum: ["audio"] },
+                    codec: { type: "string" }
+                }
+            }
+        },
+        speech: {
+            type: "object",
+            required: ["voice", "language"],
+            properties: { voice: { type: "string" }, language: { type: "string" } }
+        }
+    }
+};
+exports.SESSION_END_REASONS = [
+    "caller_hangup",
+    "app_hangup",
+    "transfer",
+    "handoff",
+    "error",
+    "timeout"
+];
+exports.sessionEndSchema = {
+    type: "object",
+    required: ["type", "reason"],
+    properties: {
+        type: { const: "session.end" },
+        reason: { enum: exports.SESSION_END_REASONS }
+    }
+};
+exports.ERROR_CODES = [
+    "bad_message",
+    "unknown_command",
+    "read_only",
+    "not_supported_by_protocol",
+    "provider_unavailable",
+    "provider_timeout",
+    "invalid_catalog_id",
+    "feature_not_supported",
+    "transfer_failed",
+    "on_hold",
+    "queue_full",
+    "play_fetch_failed",
+    "internal"
+];
+exports.errorSchema = {
+    type: "object",
+    required: ["type", "code", "message", "fatal"],
+    properties: {
+        type: { const: "error" },
+        code: { type: "string" },
+        message: { type: "string" },
+        fatal: { type: "boolean" },
+        relatesTo: id
+    }
+};
+exports.turnUserStartedSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "turn.user_started" } }
+};
+exports.turnLikelyEndedSchema = {
+    type: "object",
+    required: ["type", "text"],
+    properties: { type: { const: "turn.likely_ended" }, text: { type: "string" } }
+};
+exports.turnEndedSchema = {
+    type: "object",
+    required: ["type", "text", "language", "confidence", "durationMs"],
+    properties: {
+        type: { const: "turn.ended" },
+        text: { type: "string" },
+        language: { type: "string" },
+        confidence: { type: "number", minimum: 0, maximum: 1 },
+        durationMs: { type: "number", minimum: 0 },
+        /** No speech followed turn.user_started for 10 s (noise, a dropped line). */
+        abandoned: { type: "boolean" }
+    }
+};
+exports.turnResumedSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "turn.resumed" } }
+};
+exports.turnBackchannelSchema = {
+    type: "object",
+    required: ["type", "text"],
+    properties: { type: { const: "turn.backchannel" }, text: { type: "string" } }
+};
+exports.turnEstimateSchema = {
+    type: "object",
+    required: ["type", "eot", "speaking", "kind"],
+    properties: {
+        type: { const: "turn.estimate" },
+        eot: { type: "number", minimum: 0, maximum: 1 },
+        speaking: { type: "boolean" },
+        kind: { enum: ["speech", "backchannel", "interruption", "none"] }
+    }
+};
+exports.transcriptPartialSchema = {
+    type: "object",
+    required: ["type", "text"],
+    properties: {
+        type: { const: "transcript.partial" },
+        text: { type: "string" },
+        language: { type: "string" }
+    }
+};
+exports.outputStartedSchema = {
+    type: "object",
+    required: ["type", "id"],
+    properties: { type: { const: "output.started" }, id }
+};
+exports.outputDoneSchema = {
+    type: "object",
+    required: ["type", "id"],
+    properties: {
+        type: { const: "output.done" },
+        id,
+        heardMs: { type: "number", minimum: 0 }
+    }
+};
+exports.outputInterruptedSchema = {
+    type: "object",
+    required: ["type", "id", "heardText", "heardMs"],
+    properties: {
+        type: { const: "output.interrupted" },
+        id,
+        heardText: { type: "string" },
+        heardMs: { type: "number", minimum: 0 }
+    }
+};
+exports.markEventSchema = {
+    type: "object",
+    required: ["type", "name", "cleared"],
+    properties: {
+        type: { const: "mark" },
+        name: { type: "string" },
+        cleared: { type: "boolean" }
+    }
+};
+exports.dtmfEventSchema = {
+    type: "object",
+    required: ["type", "digit"],
+    properties: {
+        type: { const: "dtmf" },
+        digit: { type: "string", pattern: "^[0-9A-D*#]$" }
+    }
+};
+/** Answering-machine detection, once per call, for apps with `amd` (add-media-node 4.3). */
+exports.amdResultSchema = {
+    type: "object",
+    required: ["type", "status", "confidence", "detector", "audioMs"],
+    properties: {
+        type: { const: "amd.result" },
+        status: { enum: ["human", "voicemail", "ivr", "machine", "unknown"] },
+        confidence: { type: "number", minimum: 0, maximum: 1 },
+        detector: { type: "string" },
+        /** How much caller audio the verdict is based on, from when the caller started speaking. */
+        audioMs: { type: "number", minimum: 0 },
+        /** Caller audio received before speech began (unset when the caller never spoke). */
+        speechOnsetMs: { type: "number", minimum: 0 },
+        /** Why detection could not run (status unknown): no_audio, no_speech, no_classifier, call_ended, … */
+        reason: { type: "string" }
+    }
+};
+// ---- app → gateway ---------------------------------------------------------------------
+exports.speakSchema = {
+    type: "object",
+    required: ["type", "text"],
+    properties: {
+        type: { const: "speak" },
+        id,
+        text: { type: "string" },
+        last: { type: "boolean" },
+        voice: catalogId,
+        language: catalogId,
+        interruptible: { type: "boolean" },
+        preempt: { type: "boolean" }
+    }
+};
+exports.playSchema = {
+    type: "object",
+    required: ["type", "url"],
+    properties: {
+        type: { const: "play" },
+        id,
+        url: { type: "string", pattern: "^https?://" },
+        loop: { type: "boolean" },
+        interruptible: { type: "boolean" },
+        preempt: { type: "boolean" }
+    }
+};
+exports.listenUpdateSchema = {
+    type: "object",
+    required: ["type"],
+    properties: {
+        type: { const: "listen.update" },
+        id,
+        language: catalogId,
+        hints: { type: "array", items: { type: "string" } },
+        /** How long the Turn Detector waits before turn.ended. */
+        patience: { enum: ["low", "normal", "high"] }
+    }
+};
+exports.SUBSCRIBABLE_EVENTS = [
+    "turn.estimate",
+    "transcript.partial"
+];
+exports.subscribeSchema = {
+    type: "object",
+    required: ["type", "events"],
+    properties: {
+        type: { const: "subscribe" },
+        id,
+        events: { type: "array", items: { type: "string" } }
+    }
+};
+exports.markCommandSchema = {
+    type: "object",
+    required: ["type", "name"],
+    properties: {
+        type: { const: "mark" },
+        name: { type: "string", minLength: 1 }
+    }
+};
+exports.clearSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "clear" }, id }
+};
+exports.hangupSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "hangup" }, id }
+};
+exports.dtmfSendSchema = {
+    type: "object",
+    required: ["type", "digits"],
+    properties: {
+        type: { const: "dtmf.send" },
+        id,
+        digits: { type: "string", pattern: "^[0-9A-D*#w]+$" }
+    }
+};
+exports.TRANSFER_MODES = ["cold", "warm", "refer"];
+exports.transferSchema = {
+    type: "object",
+    required: ["type", "to"],
+    properties: {
+        type: { const: "transfer" },
+        id,
+        to: { type: "string", minLength: 1 },
+        headers: { type: "object", additionalProperties: { type: "string" } },
+        mode: { enum: exports.TRANSFER_MODES },
+        /** Warm transfers: what the caller hears while waiting. */
+        music: { type: "string" }
+    }
+};
+exports.transferCompleteSchema = {
+    type: "object",
+    required: ["type", "id"],
+    properties: { type: { const: "transfer.complete" }, id }
+};
+exports.holdSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "hold" }, id, music: { type: "string" } }
+};
+exports.resumeSchema = {
+    type: "object",
+    required: ["type"],
+    properties: { type: { const: "resume" }, id }
+};
+exports.handoffSchema = {
+    type: "object",
+    required: ["type", "app"],
+    properties: {
+        type: { const: "handoff" },
+        id,
+        app: { type: "string", minLength: 1 },
+        payload: { type: "object" }
+    }
+};
+exports.recordNoteSchema = {
+    type: "object",
+    required: ["type", "data"],
+    properties: {
+        type: { const: "record.note" },
+        id,
+        data: { type: "object" }
+    }
+};
+/** Schemas by message type, per direction. "mark" exists in both directions. */
+exports.GATEWAY_MESSAGE_SCHEMAS = {
+    "session.start": exports.sessionStartSchema,
+    "session.end": exports.sessionEndSchema,
+    error: exports.errorSchema,
+    "turn.user_started": exports.turnUserStartedSchema,
+    "turn.likely_ended": exports.turnLikelyEndedSchema,
+    "turn.ended": exports.turnEndedSchema,
+    "turn.resumed": exports.turnResumedSchema,
+    "turn.backchannel": exports.turnBackchannelSchema,
+    "turn.estimate": exports.turnEstimateSchema,
+    "transcript.partial": exports.transcriptPartialSchema,
+    "output.started": exports.outputStartedSchema,
+    "output.done": exports.outputDoneSchema,
+    "output.interrupted": exports.outputInterruptedSchema,
+    mark: exports.markEventSchema,
+    dtmf: exports.dtmfEventSchema,
+    "amd.result": exports.amdResultSchema
+};
+exports.APP_COMMAND_SCHEMAS = {
+    speak: exports.speakSchema,
+    play: exports.playSchema,
+    "listen.update": exports.listenUpdateSchema,
+    subscribe: exports.subscribeSchema,
+    mark: exports.markCommandSchema,
+    clear: exports.clearSchema,
+    hangup: exports.hangupSchema,
+    "dtmf.send": exports.dtmfSendSchema,
+    transfer: exports.transferSchema,
+    "transfer.complete": exports.transferCompleteSchema,
+    hold: exports.holdSchema,
+    resume: exports.resumeSchema,
+    handoff: exports.handoffSchema,
+    "record.note": exports.recordNoteSchema
+};
+/** The whole protocol as one JSON Schema document, as exported to schema/session.v1.json. */
+function sessionProtocolDocument() {
+    return {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        $id: "https://fonoster.com/schemas/session/v1.json",
+        title: exports.SESSION_PROTOCOL,
+        description: "Messages of the Fonoster session protocol (a stream with protocol fonoster). Unknown types and fields must be ignored.",
+        protocol: exports.SESSION_PROTOCOL,
+        gatewayToApp: exports.GATEWAY_MESSAGE_SCHEMAS,
+        appToGateway: exports.APP_COMMAND_SCHEMAS
+    };
+}

package/dist/sessions/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { KV, NatsConnection } from "nats";
+/**
+ * The session registry (add-platform 2.3, add-media-node 3.2, decision D3): one NATS JetStream KV
+ * bucket shared by every service. Keys are `<kind>.<id>`:
+ *
+ *   nodes.<nodeId>        media node: { nodeId, rooms, draining, at }      (written by the node)
+ *   rooms.<roomRef>       media node: { roomRef, nodeId, at }              (written by the node)
+ *   calls.<callRef>       gateway:    { callRef, gatewayRef, nodeId, roomRef, direction, at }
+ *                                     + once answered: { appRef, from, to, startedAt }
+ *   gateways.<gatewayRef> gateway:    { gatewayRef, calls, at }
+ *
+ * The control plane reads `calls` and `gateways`: a call whose entry and whose gateway's entry
+ * both stop being rewritten lost its gateway mid-call, and gets `call.ended` (`appbridge-lost`).
+ *
+ * Entries are leases: the bucket keeps a value for SESSIONS_TTL_MS after its last write, owners
+ * rewrite theirs every SESSIONS_REFRESH_MS, and a crashed owner's entries expire on their own. The
+ * Go node uses the same bucket, TTL and key rules (go/medianode/internal/registry).
+ */
+export declare const SESSIONS_BUCKET = "fonoster_sessions";
+export declare const SESSIONS_TTL_MS = 15000;
+export declare const SESSIONS_REFRESH_MS = 5000;
+export type SessionKind = "nodes" | "rooms" | "calls" | "gateways";
+/** `<kind>.<id>` with characters KV keys do not allow replaced by `_`. */
+export declare const sessionKey: (kind: SessionKind, id: string) => string;
+/** Opens the bucket, creating it when it does not exist yet. */
+export declare function openSessions(nc: NatsConnection, options?: {
+    bucket?: string;
+    ttlMs?: number;
+}): Promise<KV>;
+type Logger = {
+    warn(message: string): void;
+};
+/**
+ * An owner's entries, kept alive until deleted (the gateway's calls and its own gateway entry).
+ * Writes never throw: the registry is best effort and entries are rewritten on the next refresh.
+ */
+export declare class SessionLeases {
+    private readonly kv;
+    private readonly options;
+    private readonly entries;
+    private readonly timer;
+    private chain;
+    private closed;
+    constructor(kv: KV, options?: {
+        refreshMs?: number;
+        logger?: Logger;
+    });
+    private write;
+    /** Writes the entry now and keeps it alive. */
+    set(kind: SessionKind, id: string, value: Record<string, unknown>): Promise<unknown>;
+    /** Removes the entry. */
+    delete(kind: SessionKind, id: string): Promise<unknown>;
+    /** Reads any owner's entry from the bucket (undefined when absent or expired). */
+    get(kind: SessionKind, id: string): Promise<Record<string, unknown>>;
+    /** Rewrites every live entry (called on a timer). */
+    refresh(): Promise<unknown>;
+    /** Stops refreshing; with `remove`, deletes every entry first (clean shutdown). */
+    close(remove?: boolean): Promise<void>;
+}
+export type SessionEntry = {
+    kind: SessionKind;
+    id: string;
+    /** Undefined when the entry was deleted or purged. */
+    value?: Record<string, unknown>;
+    /** When the entry was last written (the server's timestamp). */
+    writtenAt: Date;
+};
+/**
+ * Follows one kind of entries: the current ones first (so a restarted replica knows the registry
+ * at once), then every change. Returns a stop function.
+ */
+export declare function watchSessions(kv: KV, kind: SessionKind, onEntry: (entry: SessionEntry) => void): Promise<() => void>;
+/** Reads one entry (undefined when absent or expired). */
+export declare function getSession(kv: KV, kind: SessionKind, id: string): Promise<Record<string, unknown> | undefined>;
+export {};

package/dist/sessions/index.js

@@ -0,0 +1,194 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionLeases = exports.sessionKey = exports.SESSIONS_REFRESH_MS = exports.SESSIONS_TTL_MS = exports.SESSIONS_BUCKET = void 0;
+exports.openSessions = openSessions;
+exports.watchSessions = watchSessions;
+exports.getSession = getSession;
+/**
+ * The session registry (add-platform 2.3, add-media-node 3.2, decision D3): one NATS JetStream KV
+ * bucket shared by every service. Keys are `<kind>.<id>`:
+ *
+ *   nodes.<nodeId>        media node: { nodeId, rooms, draining, at }      (written by the node)
+ *   rooms.<roomRef>       media node: { roomRef, nodeId, at }              (written by the node)
+ *   calls.<callRef>       gateway:    { callRef, gatewayRef, nodeId, roomRef, direction, at }
+ *                                     + once answered: { appRef, from, to, startedAt }
+ *   gateways.<gatewayRef> gateway:    { gatewayRef, calls, at }
+ *
+ * The control plane reads `calls` and `gateways`: a call whose entry and whose gateway's entry
+ * both stop being rewritten lost its gateway mid-call, and gets `call.ended` (`appbridge-lost`).
+ *
+ * Entries are leases: the bucket keeps a value for SESSIONS_TTL_MS after its last write, owners
+ * rewrite theirs every SESSIONS_REFRESH_MS, and a crashed owner's entries expire on their own. The
+ * Go node uses the same bucket, TTL and key rules (go/medianode/internal/registry).
+ */
+exports.SESSIONS_BUCKET = "fonoster_sessions";
+exports.SESSIONS_TTL_MS = 15000;
+exports.SESSIONS_REFRESH_MS = 5000;
+/** `<kind>.<id>` with characters KV keys do not allow replaced by `_`. */
+const sessionKey = (kind, id) => `${kind}.${id.replace(/[^-_=/.a-zA-Z0-9]/g, "_")}`;
+exports.sessionKey = sessionKey;
+/** Opens the bucket, creating it when it does not exist yet. */
+function openSessions(nc_1) {
+    return __awaiter(this, arguments, void 0, function* (nc, options = {}) {
+        var _a;
+        const bucket = (_a = options.bucket) !== null && _a !== void 0 ? _a : exports.SESSIONS_BUCKET;
+        const open = () => {
+            var _a;
+            return nc.jetstream().views.kv(bucket, {
+                history: 1,
+                ttl: (_a = options.ttlMs) !== null && _a !== void 0 ? _a : exports.SESSIONS_TTL_MS,
+                description: "Fonoster session registry: nodes, rooms, calls, gateways (leases)"
+            });
+        };
+        try {
+            return yield open();
+        }
+        catch (e) {
+            // Another service created it at the same moment with a slightly different config: bind.
+            if (/already in use/i.test(e.message))
+                return nc.jetstream().views.kv(bucket, { bindOnly: true });
+            throw e;
+        }
+    });
+}
+/**
+ * An owner's entries, kept alive until deleted (the gateway's calls and its own gateway entry).
+ * Writes never throw: the registry is best effort and entries are rewritten on the next refresh.
+ */
+class SessionLeases {
+    constructor(kv, options = {}) {
+        var _a, _b, _c;
+        this.kv = kv;
+        this.options = options;
+        this.entries = new Map();
+        this.chain = Promise.resolve();
+        this.closed = false;
+        this.timer = setInterval(() => this.refresh(), (_a = options.refreshMs) !== null && _a !== void 0 ? _a : exports.SESSIONS_REFRESH_MS);
+        (_c = (_b = this.timer).unref) === null || _c === void 0 ? void 0 : _c.call(_b);
+    }
+    write(key, value) {
+        // One write at a time, in order (a delete never overtakes the put before it).
+        this.chain = this.chain.then(() => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                if (value)
+                    yield this.kv.put(key, JSON.stringify(Object.assign(Object.assign({}, value), { at: new Date().toISOString() })));
+                else
+                    yield this.kv.delete(key);
+            }
+            catch (e) {
+                (_a = this.options.logger) === null || _a === void 0 ? void 0 : _a.warn(`session registry write ${key} failed: ${e.message}`);
+            }
+        }));
+        return this.chain;
+    }
+    /** Writes the entry now and keeps it alive. */
+    set(kind, id, value) {
+        if (this.closed)
+            return Promise.resolve();
+        const key = (0, exports.sessionKey)(kind, id);
+        this.entries.set(key, value);
+        return this.write(key, value);
+    }
+    /** Removes the entry. */
+    delete(kind, id) {
+        if (this.closed)
+            return Promise.resolve();
+        const key = (0, exports.sessionKey)(kind, id);
+        this.entries.delete(key);
+        return this.write(key);
+    }
+    /** Reads any owner's entry from the bucket (undefined when absent or expired). */
+    get(kind, id) {
+        return getSession(this.kv, kind, id);
+    }
+    /** Rewrites every live entry (called on a timer). */
+    refresh() {
+        for (const [key, value] of this.entries)
+            void this.write(key, value);
+        return this.chain;
+    }
+    /** Stops refreshing; with `remove`, deletes every entry first (clean shutdown). */
+    close() {
+        return __awaiter(this, arguments, void 0, function* (remove = true) {
+            if (this.closed)
+                return;
+            clearInterval(this.timer);
+            if (remove)
+                for (const key of this.entries.keys())
+                    void this.write(key);
+            this.closed = true;
+            this.entries.clear();
+            yield this.chain;
+        });
+    }
+}
+exports.SessionLeases = SessionLeases;
+/**
+ * Follows one kind of entries: the current ones first (so a restarted replica knows the registry
+ * at once), then every change. Returns a stop function.
+ */
+function watchSessions(kv, kind, onEntry) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const iter = yield kv.watch({ key: `${kind}.>` });
+        void (() => __awaiter(this, void 0, void 0, function* () {
+            var _a, e_1, _b, _c;
+            try {
+                for (var _d = true, _e = __asyncValues(iter), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const e = _c;
+                    const id = e.key.slice(kind.length + 1);
+                    let value;
+                    if (e.operation === "PUT") {
+                        try {
+                            value = JSON.parse(e.string());
+                        }
+                        catch (_g) {
+                            continue;
+                        }
+                    }
+                    onEntry({ kind, id, value, writtenAt: e.created });
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }))();
+        return () => iter.stop();
+    });
+}
+/** Reads one entry (undefined when absent or expired). */
+function getSession(kv, kind, id) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const e = yield kv.get((0, exports.sessionKey)(kind, id));
+        if (!e || e.operation !== "PUT")
+            return undefined;
+        try {
+            return JSON.parse(e.string());
+        }
+        catch (_a) {
+            return undefined;
+        }
+    });
+}