borgmcp-server 0.1.1 → 0.1.5

package/dist/coordination-api.js

@@ -1,12 +1,20 @@
+import { randomUUID } from "node:crypto";
+import { ATTACH_PATH, ErrorCode, PROTOCOL_VERSION, ProtocolContractError, createProtocolEnvelope, decodeAttachRequestEnvelope, decodeProtocolEnvelope, } from "borgmcp-shared/protocol";
 import { assertServerDerivedPrincipal } from "./principal.js";
-import { CursorExpiredError, AttachConflictError, AccessDeniedError, CreateCubeConflictError, ScopedStoreError, StorageCapacityError, } from "./store.js";
+import { disabledDebugLogger } from "./debug-log.js";
+import { patchMessageTaxonomy, resolveMessageRouting, validateMessageTaxonomy, } from "./message-taxonomy.js";
+import { CursorExpiredError, AttachSessionRejectedError, AccessDeniedError, CreateCubeConflictError, DefaultRoleRequiredError, RoleConflictError, RoleSectionConflictError, ScopedStoreError, StorageCapacityError, } from "./store.js";
 export class CoordinationApi {
     #runtime;
     #authority;
+    #debugLogger;
+    #streamHeartbeatMs;
     #replayBarrier;
-    constructor(runtime, authority) {
+    constructor(runtime, authority, debugLogger = disabledDebugLogger, streamHeartbeatMs = 5_000) {
         this.#runtime = runtime;
         this.#authority = authority;
+        this.#debugLogger = debugLogger;
+        this.#streamHeartbeatMs = streamHeartbeatMs;
     }
     armReplayTransition() {
         let markReached;
@@ -24,35 +32,36 @@ export class CoordinationApi {
     async handle(request) {
         assertServerDerivedPrincipal(request.principal);
         const authentication = request.principal;
-        if (request.path === "/api/client/attach" && request.method === "POST") {
+        if (request.path === ATTACH_PATH && request.method === "POST") {
             const requestId = safeRequestId(request.body);
             try {
-                const envelope = decodeEnvelope(request.body);
-                exactKeys(envelope.payload, ["cube_id", "role_id", "retry_key"], ["prior_drone_id"]);
-                const priorDroneId = envelope.payload["prior_drone_id"] === undefined
-                    ? undefined
-                    : requiredUuid(envelope.payload, "prior_drone_id");
+                const envelope = decodeAttachRequestEnvelope(request.body);
+                const priorDroneId = envelope.payload.prior_drone_id;
                 const attachment = this.#authority.attachSeat(this.#runtime.forPrincipal(authentication), {
-                    cubeId: requiredUuid(envelope.payload, "cube_id"),
-                    roleId: requiredUuid(envelope.payload, "role_id"),
-                    retryKey: requiredUuid(envelope.payload, "retry_key"),
+                    cubeId: envelope.payload.cube_id,
+                    roleId: envelope.payload.role_id,
+                    sessionCredential: envelope.payload.session_credential,
                     ...(priorDroneId === undefined ? {} : { priorDroneId }),
                 });
-                return success(201, envelope.requestId, {
+                return success(attachment.result === "created" ? 201 : 200, envelope.request_id, {
+                    result: attachment.result,
                     cube: attachment.cube,
                     role: attachment.role,
                     drone: attachment.drone,
                     session: {
-                        token: attachment.credential,
+                        id: attachment.sessionId,
                         expires_at: attachment.expiresAt,
-                        generation: attachment.generation,
                     },
-                    reattached: attachment.reattached,
                 });
             }
             catch (error) {
-                if (error instanceof AttachConflictError) {
-                    return failure(409, "INVALID_INPUT", "The attach request conflicts.", requestId);
+                if (error instanceof ProtocolContractError) {
+                    return error.code === ErrorCode.UNSUPPORTED_PROTOCOL_VERSION
+                        ? failure(426, error.code, "Unsupported protocol version.", requestId)
+                        : failure(400, "INVALID_INPUT", "Invalid protocol request.", requestId);
+                }
+                if (error instanceof AttachSessionRejectedError) {
+                    return failure(401, ErrorCode.SESSION_REJECTED, error.message, requestId);
                 }
                 if (error instanceof ScopedStoreError) {
                     return failure(404, "NOT_FOUND", error.message, requestId);
@@ -72,6 +81,7 @@ export class CoordinationApi {
                 owner_id: cube.ownerId,
                 name: cube.name,
                 cube_directive: cube.directive,
+                message_taxonomy: cube.messageTaxonomy,
                 created_at: cube.createdAt,
                 updated_at: cube.updatedAt,
             }));
@@ -107,21 +117,31 @@ export class CoordinationApi {
                 if (error instanceof StorageCapacityError) {
                     return failure(507, "CAPACITY_EXCEEDED", error.message, requestId);
                 }
+                if (error instanceof ProtocolContractError) {
+                    return error.code === ErrorCode.UNSUPPORTED_PROTOCOL_VERSION
+                        ? failure(426, error.code, "Unsupported protocol version.", requestId)
+                        : failure(400, "INVALID_INPUT", "Invalid protocol request.", requestId);
+                }
                 if (error instanceof InputError || error instanceof TypeError || error instanceof RangeError) {
                     return failure(400, "INVALID_INPUT", "Invalid protocol request.", requestId);
                 }
                 throw error;
             }
         }
-        const match = /^\/api\/cubes\/([0-9a-f-]{36})(?:\/(roles|drones|logs|acks|decisions|stream))?$/u
+        const roleMatch = /^\/api\/cubes\/([0-9a-f-]{36})\/roles\/([0-9a-f-]{36})(\/section-patch)?$/u
             .exec(request.path);
-        if (match === null)
+        const match = /^\/api\/cubes\/([0-9a-f-]{36})(?:\/(roles|drones|logs|acks|decisions|stream|taxonomy-patch))?$/u
+            .exec(request.path);
+        if (match === null && roleMatch === null) {
             return failure(404, "NOT_FOUND", "The requested resource was not found.");
-        const cubeId = match[1];
-        if (!uuidPattern.test(cubeId)) {
+        }
+        const cubeId = (roleMatch?.[1] ?? match?.[1]);
+        const roleId = roleMatch?.[2];
+        if (!uuidPattern.test(cubeId) || (roleId !== undefined && !uuidPattern.test(roleId))) {
             return failure(404, "NOT_FOUND", "The requested resource was not found.");
         }
-        const resource = match[2];
+        const resource = roleMatch === null ? match?.[2] : "role";
+        const sectionPatch = roleMatch?.[3] !== undefined;
         const store = this.#runtime.forPrincipal(authentication);
         try {
             if (resource === undefined && request.method === "GET") {
@@ -134,31 +154,194 @@ export class CoordinationApi {
                         owner_id: cube.ownerId,
                         name: cube.name,
                         cube_directive: cube.directive,
+                        message_taxonomy: cube.messageTaxonomy,
                         created_at: cube.createdAt,
                         updated_at: cube.updatedAt,
                     },
                 });
             }
+            if (resource === undefined && request.method === "PATCH") {
+                const envelope = decodeEnvelope(request.body);
+                exactKeys(envelope.payload, [], ["cube_directive", "message_taxonomy"]);
+                if (Object.keys(envelope.payload).length === 0)
+                    throw new InputError();
+                const directive = optionalText(envelope.payload, "cube_directive", 100_000);
+                const messageTaxonomy = optionalMessageTaxonomy(envelope.payload["message_taxonomy"]);
+                const cube = store.updateCube(cubeId, {
+                    ...(directive === undefined ? {} : { directive }),
+                    ...(messageTaxonomy === undefined ? {} : { messageTaxonomy }),
+                });
+                return success(200, envelope.requestId, { cube: cubePayload(cube) });
+            }
+            if (resource === "taxonomy-patch" && request.method === "POST") {
+                const envelope = decodeEnvelope(request.body);
+                const action = envelope.payload["action"];
+                const cube = store.getCube(cubeId);
+                if (cube === null)
+                    throw new ScopedStoreError();
+                if (action === "remove") {
+                    exactKeys(envelope.payload, ["action", "class"]);
+                    const messageTaxonomy = patchMessageTaxonomy(cube.messageTaxonomy, {
+                        action,
+                        className: requiredString(envelope.payload, "class", 64),
+                    });
+                    return success(200, envelope.requestId, {
+                        cube: cubePayload(store.updateCube(cubeId, { messageTaxonomy })),
+                    });
+                }
+                if (action !== "add" && action !== "replace")
+                    throw new InputError();
+                exactKeys(envelope.payload, ["action", "class_def"]);
+                const classDef = validateMessageTaxonomy([envelope.payload["class_def"]])[0];
+                const messageTaxonomy = patchMessageTaxonomy(cube.messageTaxonomy, { action, classDef });
+                return success(200, envelope.requestId, {
+                    cube: cubePayload(store.updateCube(cubeId, { messageTaxonomy })),
+                });
+            }
             if (resource === "roles" && request.method === "GET") {
                 return success(200, "roles-read", { roles: store.listRoles(cubeId) });
             }
+            if (resource === "roles" && request.method === "POST") {
+                const envelope = decodeEnvelope(request.body);
+                exactKeys(envelope.payload, ["name"], [
+                    "short_description",
+                    "detailed_description",
+                    "is_default",
+                    "is_mandatory",
+                    "is_human_seat",
+                    "can_broadcast",
+                    "receives_all_direct",
+                    "role_class",
+                ]);
+                const role = store.createRole(cubeId, {
+                    name: requiredRoleName(envelope.payload, "name"),
+                    shortDescription: optionalText(envelope.payload, "short_description", 1_024) ?? "",
+                    detailedDescription: optionalText(envelope.payload, "detailed_description", 51_200) ?? "",
+                    isDefault: optionalBoolean(envelope.payload["is_default"]),
+                    isMandatory: optionalBoolean(envelope.payload["is_mandatory"]),
+                    isHumanSeat: optionalBoolean(envelope.payload["is_human_seat"]),
+                    canBroadcast: optionalBoolean(envelope.payload["can_broadcast"]),
+                    receivesAllDirect: optionalBoolean(envelope.payload["receives_all_direct"]),
+                    ...(envelope.payload["role_class"] === undefined
+                        ? {}
+                        : { roleClass: optionalRoleClass(envelope.payload["role_class"]) }),
+                });
+                return success(201, envelope.requestId, { role });
+            }
+            if (resource === "role" && !sectionPatch && request.method === "PATCH") {
+                const envelope = decodeEnvelope(request.body);
+                exactKeys(envelope.payload, [], [
+                    "name",
+                    "short_description",
+                    "detailed_description",
+                    "is_default",
+                    "is_mandatory",
+                    "is_human_seat",
+                    "can_broadcast",
+                    "receives_all_direct",
+                    "role_class",
+                ]);
+                if (Object.keys(envelope.payload).length === 0)
+                    throw new InputError();
+                const name = envelope.payload["name"] === undefined
+                    ? undefined
+                    : requiredRoleName(envelope.payload, "name");
+                const shortDescription = optionalText(envelope.payload, "short_description", 1_024);
+                const detailedDescription = optionalText(envelope.payload, "detailed_description", 51_200);
+                const isDefault = optionalBooleanValue(envelope.payload["is_default"]);
+                const isMandatory = optionalBooleanValue(envelope.payload["is_mandatory"]);
+                const isHumanSeat = optionalBooleanValue(envelope.payload["is_human_seat"]);
+                const canBroadcast = optionalBooleanValue(envelope.payload["can_broadcast"]);
+                const receivesAllDirect = optionalBooleanValue(envelope.payload["receives_all_direct"]);
+                const roleClass = optionalRoleClass(envelope.payload["role_class"]);
+                const role = store.updateRole(cubeId, roleId, {
+                    ...(name === undefined ? {} : { name }),
+                    ...(shortDescription === undefined ? {} : { shortDescription }),
+                    ...(detailedDescription === undefined ? {} : { detailedDescription }),
+                    ...(isDefault === undefined ? {} : { isDefault }),
+                    ...(isMandatory === undefined ? {} : { isMandatory }),
+                    ...(isHumanSeat === undefined ? {} : { isHumanSeat }),
+                    ...(canBroadcast === undefined ? {} : { canBroadcast }),
+                    ...(receivesAllDirect === undefined ? {} : { receivesAllDirect }),
+                    ...(roleClass === undefined ? {} : { roleClass }),
+                });
+                return success(200, envelope.requestId, { role });
+            }
+            if (resource === "role" && sectionPatch && request.method === "POST") {
+                const envelope = decodeEnvelope(request.body);
+                const action = envelope.payload["action"];
+                if (action === "delete") {
+                    exactKeys(envelope.payload, ["action", "heading"]);
+                    const role = store.patchRoleSection(cubeId, roleId, {
+                        action,
+                        heading: requiredSectionHeading(envelope.payload, "heading"),
+                    });
+                    return success(200, envelope.requestId, { role });
+                }
+                if (action !== "replace" && action !== "insert")
+                    throw new InputError();
+                exactKeys(envelope.payload, ["action", "heading", "body"], action === "insert" ? ["after"] : []);
+                const body = optionalText(envelope.payload, "body", 51_200);
+                if (body === undefined)
+                    throw new InputError();
+                const heading = requiredSectionHeading(envelope.payload, "heading");
+                if (action === "replace") {
+                    return success(200, envelope.requestId, {
+                        role: store.patchRoleSection(cubeId, roleId, { action, heading, body }),
+                    });
+                }
+                const after = optionalNullableSectionHeading(envelope.payload["after"]);
+                return success(200, envelope.requestId, {
+                    role: store.patchRoleSection(cubeId, roleId, {
+                        action,
+                        heading,
+                        body,
+                        ...(after === undefined ? {} : { after }),
+                    }),
+                });
+            }
             if (resource === "drones" && request.method === "GET") {
-                return success(200, "drones-read", { drones: store.listDrones(cubeId) });
+                if (request.since === undefined) {
+                    return success(200, "drones-read", { drones: store.listDrones(cubeId) });
+                }
+                const since = decodeSince(request.since);
+                return success(200, "drones-read", store.listDronesSince(cubeId, since));
             }
             if (resource === "logs" && request.method === "POST") {
                 const envelope = decodeEnvelope(request.body);
-                exactKeys(envelope.payload, ["message"], ["visibility", "recipientDroneIds"]);
+                exactKeys(envelope.payload, ["message"], [
+                    "visibility", "recipientDroneIds", "class", "to",
+                ]);
                 const message = requiredString(envelope.payload, "message", 10_240);
                 const visibility = optionalVisibility(envelope.payload["visibility"]);
                 const recipientDroneIds = optionalUuidArray(envelope.payload["recipientDroneIds"]);
-                if (((visibility ?? "broadcast") === "broadcast" && recipientDroneIds !== undefined) ||
-                    (visibility === "direct" && (recipientDroneIds?.length ?? 0) === 0)) {
-                    throw new InputError();
-                }
-                const entry = store.appendLog(cubeId, {
+                const className = optionalString(envelope.payload, "class", 64);
+                const to = optionalStringArray(envelope.payload["to"]);
+                const cube = store.getCube(cubeId);
+                if (cube === null)
+                    throw new ScopedStoreError();
+                const resolved = resolveMessageRouting({
                     message,
                     ...(visibility === undefined ? {} : { visibility }),
                     ...(recipientDroneIds === undefined ? {} : { recipientDroneIds }),
+                    ...(className === undefined ? {} : { className }),
+                    ...(to === undefined ? {} : { to }),
+                }, cube.messageTaxonomy, store.listRoles(cubeId), store.listDrones(cubeId));
+                const entry = store.appendLog(cubeId, {
+                    message,
+                    visibility: resolved.visibility,
+                    ...(resolved.visibility === "direct"
+                        ? { recipientDroneIds: resolved.recipientDroneIds }
+                        : {}),
+                });
+                this.#debugLogger.emit({
+                    event: "activity_append",
+                    cubeId,
+                    entryId: entry.id,
+                    principal: authentication,
+                    droneId: entry.drone_id,
+                    visibility: entry.visibility,
+                    recipientDroneIds: entry.recipient_drone_ids,
                 });
                 return success(201, envelope.requestId, { entry });
             }
@@ -167,7 +350,17 @@ export class CoordinationApi {
                 exactKeys(envelope.payload, ["cursor"], ["limit"]);
                 const cursor = decodeCursor(envelope.payload["cursor"]);
                 const limit = optionalLimit(envelope.payload["limit"]);
-                return success(200, envelope.requestId, store.readLog(cubeId, cursor, limit));
+                const page = store.readLog(cubeId, cursor, limit);
+                this.#debugLogger.emit({
+                    event: "cursor_replay",
+                    mode: "page",
+                    cubeId,
+                    cursorId: cursor?.id ?? null,
+                    returnedCount: page.entries.length,
+                    behindBy: page.behind_by,
+                    truncated: page.has_more,
+                });
+                return success(200, envelope.requestId, page);
             }
             if (resource === "acks" && request.method === "POST") {
                 const envelope = decodeEnvelope(request.body);
@@ -177,6 +370,7 @@ export class CoordinationApi {
                     throw new InputError();
                 exactKeys(envelope.payload, ["entry_id", "kind"]);
                 store.acknowledge(cubeId, entryId, kind);
+                this.#debugLogger.emit({ event: "ack_write", cubeId, entryId, kind, principal: authentication });
                 return { status: 204 };
             }
             if (resource === "decisions" && request.method === "POST") {
@@ -185,13 +379,18 @@ export class CoordinationApi {
                 const topic = requiredString(envelope.payload, "topic", 120);
                 const decision = requiredString(envelope.payload, "decision", 100_000);
                 const rationale = optionalString(envelope.payload, "rationale", 100_000);
-                return success(201, envelope.requestId, {
-                    decision: store.recordDecision(cubeId, {
-                        topic,
-                        decision,
-                        ...(rationale === undefined ? {} : { rationale }),
-                    }),
+                const decisionRecord = store.recordDecision(cubeId, {
+                    topic,
+                    decision,
+                    ...(rationale === undefined ? {} : { rationale }),
                 });
+                this.#debugLogger.emit({
+                    event: "decision_write",
+                    cubeId,
+                    decisionId: decisionRecord.id,
+                    principal: authentication,
+                });
+                return success(201, envelope.requestId, { decision: decisionRecord });
             }
             if (resource === "decisions" && request.method === "PUT") {
                 const envelope = decodeEnvelope(request.body);
@@ -207,12 +406,29 @@ export class CoordinationApi {
             if (error instanceof CursorExpiredError) {
                 return failure(410, "CURSOR_EXPIRED", error.message);
             }
+            if (error instanceof AccessDeniedError) {
+                return failure(403, ErrorCode.ACCESS_DENIED, error.message);
+            }
             if (error instanceof ScopedStoreError) {
                 return failure(404, "NOT_FOUND", error.message);
             }
+            if (error instanceof RoleConflictError) {
+                return failure(409, error.code, error.message, safeRequestId(request.body));
+            }
+            if (error instanceof DefaultRoleRequiredError) {
+                return failure(409, error.code, error.message, safeRequestId(request.body));
+            }
+            if (error instanceof RoleSectionConflictError) {
+                return failure(409, error.code, error.message, safeRequestId(request.body));
+            }
             if (error instanceof StorageCapacityError) {
                 return failure(507, "CAPACITY_EXCEEDED", error.message, safeRequestId(request.body));
             }
+            if (error instanceof ProtocolContractError) {
+                return error.code === ErrorCode.UNSUPPORTED_PROTOCOL_VERSION
+                    ? failure(426, error.code, "Unsupported protocol version.", safeRequestId(request.body))
+                    : failure(400, "INVALID_INPUT", "Invalid protocol request.", safeRequestId(request.body));
+            }
             if (error instanceof InputError || error instanceof TypeError || error instanceof RangeError) {
                 return failure(400, "INVALID_INPUT", "Invalid protocol request.", safeRequestId(request.body));
             }
@@ -221,14 +437,31 @@ export class CoordinationApi {
     }
     async #openStream(principal, cubeId, cursor, requestSignal) {
         const store = this.#runtime.forPrincipal(principal);
+        const connectionId = randomUUID();
         const session = this.#authority.registerLiveSession(principal);
         const signal = AbortSignal.any([requestSignal, session.signal]);
         let unsubscribe = () => undefined;
+        let subscribed = false;
+        let deliveryCount = 0;
+        let heartbeat;
         const queue = new AsyncStringQueue(() => {
+            if (heartbeat !== undefined)
+                clearInterval(heartbeat);
             unsubscribe();
             session.release();
-        });
-        const pending = [];
+            if (subscribed) {
+                this.#debugLogger.emit({
+                    event: "sse_unsubscribe",
+                    connectionId,
+                    cubeId,
+                    principal,
+                    deliveryCount,
+                });
+            }
+        }, () => { deliveryCount += 1; });
+        let replayDirty = false;
+        const pendingNotifications = [];
+        let notificationIndex = 0;
         let live = false;
         try {
             unsubscribe = store.subscribeActivity(cubeId, (entry) => {
@@ -238,13 +471,15 @@ export class CoordinationApi {
                 }
                 if (live)
                     queue.push(encodeLogEvent(entry));
-                else if (pending.length >= 200)
-                    queue.close();
+                else if ("kind" in entry)
+                    pendingNotifications.push(entry);
                 else
-                    pending.push(entry);
+                    replayDirty = true;
             });
+            subscribed = true;
             signal.addEventListener("abort", () => queue.close(), { once: true });
-            const replay = store.readLog(cubeId, cursor, 200).entries;
+            const firstPage = store.readLog(cubeId, cursor, 200);
+            this.#logReplayPage(cubeId, cursor, firstPage);
             const barrier = this.#replayBarrier;
             this.#replayBarrier = undefined;
             if (barrier !== undefined) {
@@ -252,20 +487,63 @@ export class CoordinationApi {
                 barrier.markReached();
                 await barrier.release;
             }
-            const seen = new Set(replay.map(cursorKey));
-            for (const entry of replay)
-                queue.push(encodeLogEvent(entry));
-            for (const entry of pending) {
-                if (!seen.has(cursorKey(entry)) && afterCursor(entry, cursor)) {
-                    seen.add(cursorKey(entry));
-                    queue.push(encodeLogEvent(entry));
+            void (async () => {
+                let page = firstPage;
+                let replayCursor = cursor;
+                let replayCount = 0;
+                try {
+                    for (;;) {
+                        for (const entry of page.entries) {
+                            if (!await queue.write(encodeLogEvent(entry)))
+                                return;
+                            replayCursor = { id: entry.id, created_at: entry.created_at };
+                            replayCount += 1;
+                        }
+                        if (page.has_more || replayDirty) {
+                            replayDirty = false;
+                            page = store.readLog(cubeId, replayCursor, 200);
+                            this.#logReplayPage(cubeId, replayCursor, page);
+                            continue;
+                        }
+                        while (notificationIndex < pendingNotifications.length) {
+                            if (!await queue.write(encodeLogEvent(pendingNotifications[notificationIndex])))
+                                return;
+                            notificationIndex += 1;
+                        }
+                        // Reserve room for the bookmark before making live callbacks visible.
+                        // Any append while waiting marks replay dirty and is fetched first.
+                        if (!await queue.waitForSpace())
+                            return;
+                        if (replayDirty || notificationIndex < pendingNotifications.length) {
+                            replayDirty = false;
+                            page = store.readLog(cubeId, replayCursor, 200);
+                            this.#logReplayPage(cubeId, replayCursor, page);
+                            continue;
+                        }
+                        queue.push(`event: bookmark\ndata: ${JSON.stringify({
+                            as_of: new Date().toISOString(),
+                            replay_complete: true,
+                        })}\n\n`);
+                        live = true;
+                        heartbeat = setInterval(() => {
+                            queue.tryPush(encodeHeartbeat());
+                        }, this.#streamHeartbeatMs);
+                        heartbeat.unref();
+                        this.#debugLogger.emit({
+                            event: "sse_subscribe",
+                            connectionId,
+                            cubeId,
+                            principal,
+                            replayCount,
+                            truncated: false,
+                        });
+                        return;
+                    }
                 }
-            }
-            queue.push(`event: bookmark\ndata: ${JSON.stringify({
-                as_of: new Date().toISOString(),
-                replay_complete: true,
-            })}\n\n`);
-            live = true;
+                catch {
+                    queue.close();
+                }
+            })();
             return { status: 200, stream: queue };
         }
         catch (error) {
@@ -277,16 +555,30 @@ export class CoordinationApi {
             throw error;
         }
     }
+    #logReplayPage(cubeId, cursor, page) {
+        this.#debugLogger.emit({
+            event: "cursor_replay",
+            mode: "sse",
+            cubeId,
+            cursorId: cursor?.id ?? null,
+            returnedCount: page.entries.length,
+            behindBy: page.behind_by,
+            truncated: page.has_more,
+        });
+    }
 }
 class InputError extends Error {
 }
 class AsyncStringQueue {
     #values = [];
     #waiters = [];
+    #spaceWaiters = [];
     #cleanup;
+    #onDelivered;
     #closed = false;
-    constructor(cleanup) {
+    constructor(cleanup, onDelivered = () => undefined) {
         this.#cleanup = cleanup;
+        this.#onDelivered = onDelivered;
     }
     push(value) {
         if (this.#closed)
@@ -295,11 +587,30 @@ class AsyncStringQueue {
             this.close();
             return;
         }
-        const waiter = this.#waiters.shift();
-        if (waiter === undefined)
-            this.#values.push(value);
-        else
-            waiter({ value, done: false });
+        this.#enqueue(value);
+    }
+    tryPush(value) {
+        if (this.#closed || this.#values.length >= 200)
+            return false;
+        this.#enqueue(value);
+        return true;
+    }
+    async write(value) {
+        while (!this.#closed && this.#values.length >= 200) {
+            if (!await this.waitForSpace())
+                return false;
+        }
+        if (this.#closed)
+            return false;
+        this.#enqueue(value);
+        return true;
+    }
+    waitForSpace() {
+        if (this.#closed)
+            return Promise.resolve(false);
+        if (this.#values.length < 200)
+            return Promise.resolve(true);
+        return new Promise((resolve) => this.#spaceWaiters.push(resolve));
     }
     close() {
         if (this.#closed)
@@ -308,13 +619,18 @@ class AsyncStringQueue {
         this.#cleanup();
         for (const waiter of this.#waiters.splice(0))
             waiter({ value: undefined, done: true });
+        for (const waiter of this.#spaceWaiters.splice(0))
+            waiter(false);
     }
     [Symbol.asyncIterator]() {
         return {
             next: async () => {
                 const value = this.#values.shift();
-                if (value !== undefined)
+                if (value !== undefined) {
+                    this.#spaceWaiters.shift()?.(true);
+                    this.#onDelivered();
                     return { value, done: false };
+                }
                 if (this.#closed)
                     return { value: undefined, done: true };
                 return new Promise((resolve) => this.#waiters.push(resolve));
@@ -325,17 +641,19 @@ class AsyncStringQueue {
             },
         };
     }
+    #enqueue(value) {
+        const waiter = this.#waiters.shift();
+        if (waiter === undefined)
+            this.#values.push(value);
+        else {
+            this.#onDelivered();
+            waiter({ value, done: false });
+        }
+    }
 }
 function decodeEnvelope(value) {
-    const record = object(value);
-    exactKeys(record, ["protocol_version", "request_id", "payload"]);
-    if (record["protocol_version"] !== "1")
-        throw new InputError();
-    const requestId = record["request_id"];
-    if (typeof requestId !== "string" || !/^[A-Za-z0-9._-]{8,128}$/u.test(requestId)) {
-        throw new InputError();
-    }
-    return { requestId, payload: object(record["payload"]) };
+    const envelope = decodeProtocolEnvelope(value, object);
+    return { requestId: envelope.request_id, payload: envelope.payload };
 }
 function object(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
@@ -361,12 +679,75 @@ function requiredPresentationName(record, key) {
         throw new InputError();
     return value;
 }
+function requiredRoleName(record, key) {
+    const value = record[key];
+    if (typeof value !== "string" || value.length < 1 || value.length > 64)
+        throw new InputError();
+    return value;
+}
 function optionalString(record, key, maxBytes) {
     const value = record[key];
     if (value === undefined)
         return undefined;
     return requiredString(record, key, maxBytes);
 }
+function optionalText(record, key, maxCharacters) {
+    const value = record[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length > maxCharacters)
+        throw new InputError();
+    return value;
+}
+function optionalBoolean(value) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== "boolean")
+        throw new InputError();
+    return value;
+}
+function optionalBooleanValue(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new InputError();
+    return value;
+}
+function optionalRoleClass(value) {
+    if (value === undefined)
+        return undefined;
+    if (value !== "queen" && value !== "worker")
+        throw new InputError();
+    return value;
+}
+function optionalMessageTaxonomy(value) {
+    return value === undefined ? undefined : validateMessageTaxonomy(value);
+}
+function optionalStringArray(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length < 1 || value.length > 100 ||
+        value.some((entry) => typeof entry !== "string" || entry.length < 1 || entry.length > 120)) {
+        throw new InputError();
+    }
+    const entries = value;
+    if (new Set(entries).size !== entries.length)
+        throw new InputError();
+    return entries;
+}
+function requiredSectionHeading(record, key) {
+    const value = requiredString(record, key, 60);
+    const heading = value.trim();
+    if (heading.length === 0 || /^\s/u.test(value) || /[:\n\r]/u.test(heading) ||
+        /^[*\-#>`]/u.test(heading))
+        throw new InputError();
+    return heading;
+}
+function optionalNullableSectionHeading(value) {
+    if (value === undefined || value === null)
+        return value;
+    return requiredSectionHeading({ value }, "value");
+}
 function requiredUuid(record, key) {
     const value = record[key];
     if (typeof value !== "string" || !uuidPattern.test(value))
@@ -418,6 +799,13 @@ function decodeOpaqueCursor(value) {
         throw new InputError();
     }
 }
+function decodeSince(value) {
+    if (uuidPattern.test(value))
+        return value.toLowerCase();
+    if (timestampPattern.test(value) && new Date(value).toISOString() === value)
+        return value;
+    throw new InputError();
+}
 function safeRequestId(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
@@ -427,30 +815,40 @@ function safeRequestId(value) {
         : undefined;
 }
 function success(status, requestId, payload) {
-    return { status, body: { protocol_version: "1", request_id: requestId, payload } };
+    return { status, body: createProtocolEnvelope(requestId, payload) };
 }
 function failure(status, code, message, requestId) {
     return {
         status,
         body: {
-            protocol_version: "1",
+            protocol_version: PROTOCOL_VERSION,
             ...(requestId === undefined ? {} : { request_id: requestId }),
             error: { code, message },
         },
     };
 }
 function encodeLogEvent(entry) {
+    if ("kind" in entry) {
+        return `event: log\nid: ${entry.id}\ndata: ${JSON.stringify({ entry })}\n\n`;
+    }
     return `event: log\nid: ${entry.id}\ndata: ${JSON.stringify({
         cursor: { id: entry.id, created_at: entry.created_at },
         entry,
     })}\n\n`;
 }
-function cursorKey(entry) {
-    return `${entry.created_at}\0${entry.id}`;
+function encodeHeartbeat() {
+    return `event: heartbeat\ndata: ${JSON.stringify({ ts: new Date().toISOString() })}\n\n`;
 }
-function afterCursor(entry, cursor) {
-    return cursor === null || entry.created_at > cursor.created_at ||
-        (entry.created_at === cursor.created_at && entry.id > cursor.id);
+function cubePayload(cube) {
+    return {
+        id: cube.id,
+        owner_id: cube.ownerId,
+        name: cube.name,
+        cube_directive: cube.directive,
+        message_taxonomy: cube.messageTaxonomy,
+        created_at: cube.createdAt,
+        updated_at: cube.updatedAt,
+    };
 }
 const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 const timestampPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;