borgmcp-server 0.1.4 → 0.1.7

package/src/coordination-api.ts

@@ -1,19 +1,39 @@
 import { randomUUID } from "node:crypto";
+import {
+  ATTACH_PATH,
+  ErrorCode,
+  PROTOCOL_VERSION,
+  ProtocolContractError,
+  createProtocolEnvelope,
+  decodeAttachRequestEnvelope,
+  decodeEvictDroneRequestEnvelope,
+  decodeProtocolEnvelope,
+  decodeReassignDroneRequestEnvelope,
+} from "borgmcp-shared/protocol";
 import type { Principal } from "./principal.js";
 import { assertServerDerivedPrincipal } from "./principal.js";
 import { disabledDebugLogger, type DebugLogger } from "./debug-log.js";
+import {
+  patchMessageTaxonomy,
+  resolveMessageRouting,
+  validateMessageTaxonomy,
+} from "./message-taxonomy.js";
 import type { CredentialAuthority } from "./credentials.js";
 import {
   CursorExpiredError,
-  AttachConflictError,
+  AttachSessionRejectedError,
   AccessDeniedError,
   CreateCubeConflictError,
   DefaultRoleRequiredError,
   RoleConflictError,
+  RoleInUseError,
   RoleSectionConflictError,
   ScopedStoreError,
   StorageCapacityError,
-  type EnrichedActivityRecord,
+  type DroneRecord,
+  type ActivityPage,
+  type ActivityStreamRecord,
+  type CubeRecord,
   type LogCursor,
   type StoreRuntime,
 } from "./store.js";
@@ -24,6 +44,7 @@ export interface CoordinationRequest {
   readonly principal: Principal;
   readonly body?: unknown;
   readonly cursor?: string;
+  readonly since?: string;
   readonly signal: AbortSignal;
 }
 
@@ -48,16 +69,19 @@ export class CoordinationApi {
   readonly #runtime: StoreRuntime;
   readonly #authority: CredentialAuthority;
   readonly #debugLogger: DebugLogger;
+  readonly #streamHeartbeatMs: number;
   #replayBarrier: ReplayBarrier | undefined;
 
   constructor(
     runtime: StoreRuntime,
     authority: CredentialAuthority,
     debugLogger: DebugLogger = disabledDebugLogger,
+    streamHeartbeatMs = 5_000,
   ) {
     this.#runtime = runtime;
     this.#authority = authority;
     this.#debugLogger = debugLogger;
+    this.#streamHeartbeatMs = streamHeartbeatMs;
   }
 
   armReplayTransition(): { readonly reached: Promise<void>; readonly release: () => void } {
@@ -78,38 +102,38 @@ export class CoordinationApi {
     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,
-            posture: attachment.posture,
           },
-          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);
@@ -130,6 +154,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,
       }));
@@ -164,6 +189,11 @@ 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);
         }
@@ -173,17 +203,21 @@ export class CoordinationApi {
 
     const roleMatch = /^\/api\/cubes\/([0-9a-f-]{36})\/roles\/([0-9a-f-]{36})(\/section-patch)?$/u
       .exec(request.path);
-    const match = /^\/api\/cubes\/([0-9a-f-]{36})(?:\/(roles|drones|logs|acks|decisions|stream))?$/u
+    const droneMatch = /^\/api\/cubes\/([0-9a-f-]{36})\/drones\/([0-9a-f-]{36})$/u
+      .exec(request.path);
+    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) {
+    if (match === null && roleMatch === null && droneMatch === null) {
       return failure(404, "NOT_FOUND", "The requested resource was not found.");
     }
-    const cubeId = (roleMatch?.[1] ?? match?.[1])!;
+    const cubeId = (roleMatch?.[1] ?? droneMatch?.[1] ?? match?.[1])!;
     const roleId = roleMatch?.[2];
-    if (!uuidPattern.test(cubeId) || (roleId !== undefined && !uuidPattern.test(roleId))) {
+    const droneId = droneMatch?.[2];
+    if (!uuidPattern.test(cubeId) || (roleId !== undefined && !uuidPattern.test(roleId)) ||
+        (droneId !== undefined && !uuidPattern.test(droneId))) {
       return failure(404, "NOT_FOUND", "The requested resource was not found.");
     }
-    const resource = roleMatch === null ? match?.[2] : "role";
+    const resource = roleMatch !== null ? "role" : droneMatch !== null ? "drone" : match?.[2];
     const sectionPatch = roleMatch?.[3] !== undefined;
     const store = this.#runtime.forPrincipal(authentication);
 
@@ -197,11 +231,47 @@ 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) });
       }
@@ -215,6 +285,7 @@ export class CoordinationApi {
           "is_human_seat",
           "can_broadcast",
           "receives_all_direct",
+          "role_class",
         ]);
         const role = store.createRole(cubeId, {
           name: requiredRoleName(envelope.payload, "name"),
@@ -225,6 +296,9 @@ export class CoordinationApi {
           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 });
       }
@@ -239,6 +313,7 @@ export class CoordinationApi {
           "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
@@ -251,6 +326,7 @@ export class CoordinationApi {
         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 }),
@@ -260,6 +336,7 @@ export class CoordinationApi {
           ...(isHumanSeat === undefined ? {} : { isHumanSeat }),
           ...(canBroadcast === undefined ? {} : { canBroadcast }),
           ...(receivesAllDirect === undefined ? {} : { receivesAllDirect }),
+          ...(roleClass === undefined ? {} : { roleClass }),
         });
         return success(200, envelope.requestId, { role });
       }
@@ -295,22 +372,47 @@ export class CoordinationApi {
         });
       }
       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 === "drone" && request.method === "PATCH") {
+        const envelope = decodeReassignDroneRequestEnvelope(request.body);
+        const drone = store.reassignDrone(cubeId, droneId!, envelope.payload.role_id);
+        return success(200, envelope.request_id, { drone: managedDronePayload(drone) });
+      }
+      if (resource === "drone" && request.method === "DELETE") {
+        const envelope = decodeEvictDroneRequestEnvelope(request.body);
+        store.evictDrone(cubeId, droneId!);
+        return success(200, envelope.request_id, { drone_id: droneId!, evicted: true });
       }
       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",
@@ -382,6 +484,9 @@ 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);
       }
@@ -394,9 +499,17 @@ export class CoordinationApi {
       if (error instanceof RoleSectionConflictError) {
         return failure(409, error.code, error.message, safeRequestId(request.body));
       }
+      if (error instanceof RoleInUseError) {
+        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));
       }
@@ -417,7 +530,9 @@ export class CoordinationApi {
     let unsubscribe = (): void => undefined;
     let subscribed = false;
     let deliveryCount = 0;
+    let heartbeat: NodeJS.Timeout | undefined;
     const queue = new AsyncStringQueue(() => {
+      if (heartbeat !== undefined) clearInterval(heartbeat);
       unsubscribe();
       session.release();
       if (subscribed) {
@@ -430,7 +545,9 @@ export class CoordinationApi {
         });
       }
     }, () => { deliveryCount += 1; });
-    const pending: EnrichedActivityRecord[] = [];
+    let replayDirty = false;
+    const pendingNotifications: ActivityStreamRecord[] = [];
+    let notificationIndex = 0;
     let live = false;
     try {
       unsubscribe = store.subscribeActivity(cubeId, (entry) => {
@@ -439,21 +556,13 @@ export class CoordinationApi {
           return;
         }
         if (live) queue.push(encodeLogEvent(entry));
-        else if (pending.length >= 200) queue.close();
-        else pending.push(entry);
+        else if ("kind" in entry) pendingNotifications.push(entry);
+        else replayDirty = true;
       });
+      subscribed = true;
       signal.addEventListener("abort", () => queue.close(), { once: true });
-      const replayPage = store.readLog(cubeId, cursor, 200);
-      const replay = replayPage.entries;
-      this.#debugLogger.emit({
-        event: "cursor_replay",
-        mode: "sse",
-        cubeId,
-        cursorId: cursor?.id ?? null,
-        returnedCount: replay.length,
-        behindBy: replayPage.behind_by,
-        truncated: replayPage.has_more,
-      });
+      const firstPage = store.readLog(cubeId, cursor, 200);
+      this.#logReplayPage(cubeId, cursor, firstPage);
       const barrier = this.#replayBarrier;
       this.#replayBarrier = undefined;
       if (barrier !== undefined) {
@@ -461,28 +570,61 @@ 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;
+          }
+        } catch {
+          queue.close();
         }
-      }
-      queue.push(`event: bookmark\ndata: ${JSON.stringify({
-        as_of: new Date().toISOString(),
-        replay_complete: true,
-      })}\n\n`);
-      live = true;
-      subscribed = true;
-      this.#debugLogger.emit({
-        event: "sse_subscribe",
-        connectionId,
-        cubeId,
-        principal,
-        replayCount: replay.length,
-        truncated: replayPage.has_more,
-      });
+      })();
       return { status: 200, stream: queue };
     } catch (error) {
       queue.close();
@@ -491,6 +633,22 @@ export class CoordinationApi {
       throw error;
     }
   }
+
+  #logReplayPage(
+    cubeId: string,
+    cursor: LogCursor | null,
+    page: ActivityPage,
+  ): void {
+    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 {}
@@ -498,6 +656,7 @@ class InputError extends Error {}
 class AsyncStringQueue implements AsyncIterable<string> {
   readonly #values: string[] = [];
   readonly #waiters: Array<(result: IteratorResult<string>) => void> = [];
+  readonly #spaceWaiters: Array<(available: boolean) => void> = [];
   readonly #cleanup: () => void;
   readonly #onDelivered: () => void;
   #closed = false;
@@ -513,12 +672,28 @@ class AsyncStringQueue implements AsyncIterable<string> {
       this.close();
       return;
     }
-    const waiter = this.#waiters.shift();
-    if (waiter === undefined) this.#values.push(value);
-    else {
-      this.#onDelivered();
-      waiter({ value, done: false });
+    this.#enqueue(value);
+  }
+
+  tryPush(value: string): boolean {
+    if (this.#closed || this.#values.length >= 200) return false;
+    this.#enqueue(value);
+    return true;
+  }
+
+  async write(value: string): Promise<boolean> {
+    while (!this.#closed && this.#values.length >= 200) {
+      if (!await this.waitForSpace()) return false;
     }
+    if (this.#closed) return false;
+    this.#enqueue(value);
+    return true;
+  }
+
+  waitForSpace(): Promise<boolean> {
+    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(): void {
@@ -526,6 +701,7 @@ class AsyncStringQueue implements AsyncIterable<string> {
     this.#closed = true;
     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](): AsyncIterator<string> {
@@ -533,6 +709,7 @@ class AsyncStringQueue implements AsyncIterable<string> {
       next: async () => {
         const value = this.#values.shift();
         if (value !== undefined) {
+          this.#spaceWaiters.shift()?.(true);
           this.#onDelivered();
           return { value, done: false };
         }
@@ -545,17 +722,20 @@ class AsyncStringQueue implements AsyncIterable<string> {
       },
     };
   }
+
+  #enqueue(value: string): void {
+    const waiter = this.#waiters.shift();
+    if (waiter === undefined) this.#values.push(value);
+    else {
+      this.#onDelivered();
+      waiter({ value, done: false });
+    }
+  }
 }
 
 function decodeEnvelope(value: unknown): RequestEnvelope {
-  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: unknown): Record<string, unknown> {
@@ -622,6 +802,27 @@ function optionalBooleanValue(value: unknown): boolean | undefined {
   return value;
 }
 
+function optionalRoleClass(value: unknown): "queen" | "worker" | undefined {
+  if (value === undefined) return undefined;
+  if (value !== "queen" && value !== "worker") throw new InputError();
+  return value;
+}
+
+function optionalMessageTaxonomy(value: unknown) {
+  return value === undefined ? undefined : validateMessageTaxonomy(value);
+}
+
+function optionalStringArray(value: unknown): string[] | undefined {
+  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 as string[];
+  if (new Set(entries).size !== entries.length) throw new InputError();
+  return entries;
+}
+
 function requiredSectionHeading(record: Record<string, unknown>, key: string): string {
   const value = requiredString(record, key, 60);
   const heading = value.trim();
@@ -682,6 +883,12 @@ function decodeOpaqueCursor(value: string | undefined): LogCursor | null {
   }
 }
 
+function decodeSince(value: string): string {
+  if (uuidPattern.test(value)) return value.toLowerCase();
+  if (timestampPattern.test(value) && new Date(value).toISOString() === value) return value;
+  throw new InputError();
+}
+
 function safeRequestId(value: unknown): string | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
   const requestId = (value as Record<string, unknown>)["request_id"];
@@ -691,7 +898,7 @@ function safeRequestId(value: unknown): string | undefined {
 }
 
 function success(status: number, requestId: string, payload: unknown): CoordinationResponse {
-  return { status, body: { protocol_version: "1", request_id: requestId, payload } };
+  return { status, body: createProtocolEnvelope(requestId, payload) };
 }
 
 function failure(
@@ -703,27 +910,46 @@ function failure(
   return {
     status,
     body: {
-      protocol_version: "1",
+      protocol_version: PROTOCOL_VERSION,
       ...(requestId === undefined ? {} : { request_id: requestId }),
       error: { code, message },
     },
   };
 }
 
-function encodeLogEvent(entry: EnrichedActivityRecord): string {
+function encodeLogEvent(entry: ActivityStreamRecord): string {
+  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: EnrichedActivityRecord): string {
-  return `${entry.created_at}\0${entry.id}`;
+function encodeHeartbeat(): string {
+  return `event: heartbeat\ndata: ${JSON.stringify({ ts: new Date().toISOString() })}\n\n`;
 }
 
-function afterCursor(entry: EnrichedActivityRecord, cursor: LogCursor | null): boolean {
-  return cursor === null || entry.created_at > cursor.created_at ||
-    (entry.created_at === cursor.created_at && entry.id > cursor.id);
+function cubePayload(cube: CubeRecord) {
+  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,
+  };
+}
+
+function managedDronePayload(drone: DroneRecord) {
+  return {
+    id: drone.id,
+    cube_id: drone.cube_id,
+    role_id: drone.role_id,
+    label: drone.label,
+  };
 }
 
 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;