borgmcp-server 0.1.1 → 0.1.5

package/src/https-server.ts

@@ -2,25 +2,21 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { createServer, type Server as HttpsServer } from "node:https";
 import type { AddressInfo, Socket } from "node:net";
 import { createHash, X509Certificate } from "node:crypto";
+import {
+  ATTACH_PATH,
+  CUBES_PATH,
+  ENROLLMENT_EXCHANGE_PATH,
+  ErrorCode,
+  HEALTH_PATH,
+  PROTOCOL_INFO_PATH,
+  PROTOCOL_VERSION,
+  createProtocolTagPreflight,
+} from "borgmcp-shared/protocol";
 
 import { resolveBindOptions, type BindOptionsInput } from "./network-policy.js";
 import type { CoordinationRequest, CoordinationResponse } from "./coordination-api.js";
 import type { Principal } from "./principal.js";
-
-export interface ProtocolInfoDocument {
-  readonly protocol_version: string;
-  readonly package: {
-    readonly name: "borgmcp-shared";
-    readonly version: string;
-  };
-  readonly capabilities: readonly string[];
-  readonly limits: {
-    readonly max_request_bytes: number;
-    readonly max_log_message_bytes: number;
-    readonly max_read_page_size: number;
-    readonly max_replay_page_size: number;
-  };
-}
+import { disabledDebugLogger, type DebugLogger, type DebugRoute } from "./debug-log.js";
 
 export interface ServiceLimits {
   readonly maxConnections: number;
@@ -61,19 +57,15 @@ export const DEFAULT_SERVICE_LIMITS: ServiceLimits = {
 };
 
 export interface RequestHandlerContext {
-  readonly protocolInfo: ProtocolInfoDocument;
-  readonly authorizeProtocol: (
-    authorization: string | undefined,
-    signal: AbortSignal,
-  ) => Promise<boolean | "missing" | "invalid" | "revoked">;
   readonly exchangeEnrollment?: (
     body: unknown,
-  ) => Promise<{ readonly status: 201 | 400 | 401 | 507; readonly body?: unknown }>;
+  ) => Promise<{ readonly status: 201 | 400 | 401 | 426 | 507; readonly body?: unknown }>;
   readonly authorizeCoordination?: (
     authorization: string | undefined,
     signal: AbortSignal,
-  ) => Promise<Principal | "missing" | "invalid" | "revoked">;
+  ) => Promise<Principal | "missing" | "invalid" | "revoked" | "evicted">;
   readonly handleCoordination?: (request: CoordinationRequest) => Promise<CoordinationResponse>;
+  readonly debugLogger: DebugLogger;
 }
 
 export interface HttpsServerOptions {
@@ -83,12 +75,11 @@ export interface HttpsServerOptions {
     readonly cert: string | Buffer;
     readonly ca?: string | Buffer;
   };
-  readonly protocolInfo: ProtocolInfoDocument;
-  readonly authorizeProtocol: RequestHandlerContext["authorizeProtocol"];
   readonly exchangeEnrollment?: RequestHandlerContext["exchangeEnrollment"];
   readonly authorizeCoordination?: RequestHandlerContext["authorizeCoordination"];
   readonly handleCoordination?: RequestHandlerContext["handleCoordination"];
   readonly limits?: ServiceLimits;
+  readonly debugLogger?: DebugLogger;
   readonly testHooks?: {
     readonly identifyRemoteAddress?: (socket: Socket) => string;
   };
@@ -126,8 +117,14 @@ export async function startHttpsServer(options: HttpsServerOptions): Promise<Run
 
   const acceptedSockets = applyServerLimits(server, limits);
   server.on("secureConnection", (socket) => socket.disableRenegotiation());
-  server.on("tlsClientError", (_error, socket) => socket.destroy());
-  server.on("clientError", (_error, socket) => socket.end("HTTP/1.1 400 Bad Request\r\n\r\n"));
+  server.on("tlsClientError", (_error, socket) => {
+    handlerContext.debugLogger.emit({ event: "transport_rejection", reason: "tls_client_error" });
+    socket.destroy();
+  });
+  server.on("clientError", (_error, socket) => {
+    handlerContext.debugLogger.emit({ event: "transport_rejection", reason: "http_parser_error" });
+    socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+  });
   server.on("checkContinue", (_request, response) => sendEmpty(response, 417, true));
 
   try {
@@ -159,8 +156,6 @@ export function createRequestHandlerContext(
   options: HttpsServerOptions,
 ): RequestHandlerContext {
   return Object.freeze({
-    protocolInfo: options.protocolInfo,
-    authorizeProtocol: options.authorizeProtocol,
     ...(options.exchangeEnrollment === undefined
       ? {}
       : { exchangeEnrollment: options.exchangeEnrollment }),
@@ -170,6 +165,7 @@ export function createRequestHandlerContext(
     ...(options.handleCoordination === undefined
       ? {}
       : { handleCoordination: options.handleCoordination }),
+    debugLogger: options.debugLogger ?? disabledDebugLogger,
   });
 }
 
@@ -182,6 +178,32 @@ function createRequestListener(
   const credentialRateLimiter = new RequestRateLimiter(limits, limits.maxRequestsPerWindow);
   const streamQuota = new ConcurrentQuota(limits.maxStreamsPerCredential);
   return (request, response) => {
+    const startedAt = Date.now();
+    const trace: RequestTrace = {
+      route: debugRoute(request.url),
+      method: debugMethod(request.method),
+      authentication: "not_required",
+    };
+    let debugEmitted = false;
+    const emitDebug = (): void => {
+      if (debugEmitted) return;
+      debugEmitted = true;
+      const status = response.headersSent ? response.statusCode : 0;
+      context.debugLogger.emit({
+        event: "request",
+        route: trace.route,
+        method: trace.method,
+        authentication: trace.authentication,
+        authorization: trace.authentication === "accepted"
+          ? status === 403 || status === 404 ? "denied_or_not_found" : "accepted"
+          : "not_checked",
+        ...(trace.principal === undefined ? {} : { principal: trace.principal }),
+        status,
+        durationMs: Math.max(0, Date.now() - startedAt),
+      });
+    };
+    response.once("finish", emitDebug);
+    response.once("close", emitDebug);
     const controller = new AbortController();
     response.once("close", () => controller.abort());
     let timer: NodeJS.Timeout | undefined;
@@ -202,6 +224,7 @@ function createRequestListener(
       streamQuota,
       identifyRemoteAddress,
       controller.signal,
+      trace,
     )
       .then(() => "handled" as const);
 
@@ -226,6 +249,7 @@ async function handleRequest(
   streamQuota: ConcurrentQuota,
   identifyRemoteAddress: (socket: Socket) => string,
   signal: AbortSignal,
+  trace: RequestTrace,
 ): Promise<void> {
   const addressIdentity = `address:${identifyRemoteAddress(request.socket)}`;
   const preAuthRetry = admissionLimiter.consume(addressIdentity);
@@ -252,43 +276,23 @@ async function handleRequest(
     return;
   }
 
-  if (path === "/healthz") {
+  if (path === HEALTH_PATH) {
     if (requestBody.length !== 0) return sendEmpty(response, 400, true);
     sendEmpty(response, request.method === "GET" ? 204 : 405);
     return;
   }
 
-  if (path === "/api/protocol") {
+  if (path === PROTOCOL_INFO_PATH) {
     if (requestBody.length !== 0) return sendEmpty(response, 400, true);
-    const authorized = await context.authorizeProtocol(request.headers.authorization, signal);
-    if (signal.aborted) return;
-    if (authorized !== true) {
-      const code = authorized === "revoked"
-        ? "SESSION_REVOKED"
-        : authorized === "missing" || request.headers.authorization === undefined
-          ? "AUTH_MISSING"
-          : "AUTH_INVALID";
-      sendJson(response, 401, protocolError(code, "Authentication failed."));
-      return;
-    }
-    const credentialRetry = consumeAuthenticatedRateLimit(
-      request.headers.authorization,
-      credentialRateLimiter,
-    );
-    if (credentialRetry !== null) return sendRateLimited(response, credentialRetry);
     if (request.method !== "GET") {
       sendEmpty(response, 405);
       return;
     }
-    sendJson(response, 200, {
-      protocol_version: "1",
-      request_id: "protocol-info",
-      payload: context.protocolInfo,
-    });
+    sendJson(response, 200, createProtocolTagPreflight());
     return;
   }
 
-  if (path === "/api/enrollment/exchange") {
+  if (path === ENROLLMENT_EXCHANGE_PATH) {
     if (request.method !== "POST" || context.exchangeEnrollment === undefined) {
       sendEmpty(response, 405);
       return;
@@ -307,7 +311,9 @@ async function handleRequest(
     if (signal.aborted) return;
     if (result.body === undefined) sendEmpty(response, result.status, result.status === 400);
     else if (result.status === 400) sendJson(response, 400, result.body, true);
-    else if (result.status === 401 || result.status === 507) sendJson(response, result.status, result.body);
+    else if (result.status === 401 || result.status === 426 || result.status === 507) {
+      sendJson(response, result.status, result.body);
+    }
     else sendJson(response, 201, result.body);
     return;
   }
@@ -330,21 +336,27 @@ async function handleRequest(
       return;
     }
     const authentication = await authorizeCoordination(authorization, signal);
+    trace.authentication = typeof authentication === "string" ? authentication : "accepted";
     if (signal.aborted) return;
     if (typeof authentication === "string") {
+      if (authentication === "evicted") {
+        sendJson(response, 410, protocolError(ErrorCode.DRONE_EVICTED, "Authentication failed."));
+        return;
+      }
       const code = authentication === "revoked"
         ? "SESSION_REVOKED"
         : authentication === "missing" || authorization === undefined ? "AUTH_MISSING" : "AUTH_INVALID";
       sendJson(response, 401, protocolError(code, "Authentication failed."));
       return;
     }
+    trace.principal = authentication;
     const clientIdentity = `client:${authentication.kind === "drone-session"
       ? authentication.clientId
       : authentication.id}`;
     const credentialRetry = credentialRateLimiter.consume(clientIdentity);
     if (credentialRetry !== null) return sendRateLimited(response, credentialRetry);
-    const cursor = parseCursorParameter(request.url, path);
-    if (cursor === INVALID_COORDINATION_QUERY) {
+    const query = parseCoordinationQuery(request.url, path);
+    if (query === INVALID_COORDINATION_QUERY) {
       sendJson(response, 400, protocolError("INVALID_INPUT", "Invalid query parameters."), true);
       return;
     }
@@ -353,7 +365,7 @@ async function handleRequest(
       path,
       principal: authentication,
       ...(decoded === undefined ? {} : { body: decoded }),
-      ...(cursor === undefined ? {} : { cursor }),
+      ...query,
       signal,
     });
     if (signal.aborted) {
@@ -378,6 +390,39 @@ async function handleRequest(
   sendEmpty(response, 404);
 }
 
+interface RequestTrace {
+  readonly route: DebugRoute;
+  readonly method: string;
+  authentication: "not_required" | "missing" | "invalid" | "revoked" | "evicted" | "accepted";
+  principal?: Principal;
+}
+
+function debugMethod(method: string | undefined): string {
+  return method === "GET" || method === "POST" || method === "PUT" ||
+    method === "PATCH" || method === "DELETE" ? method : "OTHER";
+}
+
+function debugRoute(rawUrl: string | undefined): DebugRoute {
+  const path = parseRequestPath(rawUrl);
+  if (path === null) return "unknown";
+  if (path === HEALTH_PATH) return "health";
+  if (path === PROTOCOL_INFO_PATH) return "protocol";
+  if (path === ENROLLMENT_EXCHANGE_PATH) return "enrollment_exchange";
+  if (path === ATTACH_PATH) return "client_attach";
+  if (path === "/api/cubes") return "cubes";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}$/iu.test(path)) return "cube";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/roles$/iu.test(path)) return "cube_roles";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/roles\/[0-9a-f-]{36}$/iu.test(path)) return "cube_role";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/roles\/[0-9a-f-]{36}\/section-patch$/iu.test(path)) return "cube_role_section_patch";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/taxonomy-patch$/iu.test(path)) return "cube_taxonomy_patch";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/drones$/iu.test(path)) return "cube_drones";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/logs$/iu.test(path)) return "cube_logs";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/acks$/iu.test(path)) return "cube_acks";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/decisions$/iu.test(path)) return "cube_decisions";
+  if (/^\/api\/cubes\/[0-9a-f-]{36}\/stream$/iu.test(path)) return "cube_stream";
+  return "unknown";
+}
+
 async function closeRejectedStream(stream: AsyncIterable<string>): Promise<void> {
   const iterator = stream[Symbol.asyncIterator]();
   try {
@@ -517,35 +562,33 @@ function waitForDrain(response: ServerResponse): Promise<void> {
 }
 
 function protocolError(code: string, message: string): object {
-  return { protocol_version: "1", error: { code, message } };
+  return { protocol_version: PROTOCOL_VERSION, error: { code, message } };
 }
 
 const INVALID_COORDINATION_QUERY = Symbol("invalid-coordination-query");
 
-function parseCursorParameter(
+function parseCoordinationQuery(
   value: string | undefined,
   path: string,
-): string | undefined | typeof INVALID_COORDINATION_QUERY {
-  if (value === undefined) return undefined;
+): { readonly cursor?: string; readonly since?: string } | typeof INVALID_COORDINATION_QUERY {
+  if (value === undefined) return {};
   try {
     const parsed = new URL(value, "https://local.invalid");
     const keys = [...parsed.searchParams.keys()];
-    if (!path.endsWith("/stream")) {
-      return keys.length === 0 ? undefined : INVALID_COORDINATION_QUERY;
-    }
-    if (keys.some((key) => key !== "cursor")) return INVALID_COORDINATION_QUERY;
-    const values = parsed.searchParams.getAll("cursor");
-    if (values.length === 0) return undefined;
-    return values.length === 1 && values[0]!.length > 0
-      ? values[0]
-      : INVALID_COORDINATION_QUERY;
+    const allowed = path.endsWith("/stream") ? "cursor" : path.endsWith("/drones") ? "since" : null;
+    if (allowed === null) return keys.length === 0 ? {} : INVALID_COORDINATION_QUERY;
+    if (keys.some((key) => key !== allowed)) return INVALID_COORDINATION_QUERY;
+    const values = parsed.searchParams.getAll(allowed);
+    if (values.length === 0) return {};
+    if (values.length !== 1 || values[0]!.length === 0) return INVALID_COORDINATION_QUERY;
+    return allowed === "cursor" ? { cursor: values[0]! } : { since: values[0]! };
   } catch {
     return INVALID_COORDINATION_QUERY;
   }
 }
 
 function isCoordinationPath(path: string | null): path is string {
-  return path === "/api/client/attach" || path === "/api/cubes" ||
+  return path === ATTACH_PATH || path === CUBES_PATH ||
     path?.startsWith("/api/cubes/") === true;
 }
 
@@ -921,14 +964,6 @@ function credentialIdentity(authorization: string | undefined): string | null {
   return `credential:${createHash("sha256").update(authorization).digest("base64url")}`;
 }
 
-function consumeAuthenticatedRateLimit(
-  authorization: string | undefined,
-  rateLimiter: RequestRateLimiter,
-): number | null {
-  const identity = credentialIdentity(authorization);
-  return identity === null ? null : rateLimiter.consume(identity);
-}
-
 function listen(server: HttpsServer, port: number, host: string): Promise<void> {
   return new Promise((resolve, reject) => {
     const onError = (error: Error): void => {

package/src/index.ts

@@ -1,3 +1,3 @@
 export { runCli } from "./cli.js";
 export type { CliIo } from "./cli.js";
-export type { ServerService } from "./service.js";
+export type { ServerService, SetupOptions } from "./service.js";

package/src/message-taxonomy.ts

@@ -0,0 +1,284 @@
+import type { MessageTaxonomy, MessageTaxonomyClass } from "borgmcp-shared/domain";
+
+export interface RoutingRole {
+  readonly id: string;
+  readonly name: string;
+  readonly is_human_seat: boolean;
+}
+
+export interface RoutingDrone {
+  readonly id: string;
+  readonly label: string;
+  readonly role_id: string;
+  readonly posture: "observer" | "participant";
+}
+
+export interface MessageRouting {
+  readonly visibility: "broadcast" | "direct";
+  readonly recipientDroneIds: string[];
+  readonly routing: {
+    readonly class: string | null;
+    readonly recipients: string[];
+    readonly fellOpen: boolean;
+    readonly message: string | null;
+  };
+}
+
+export type TaxonomyPatch =
+  | { readonly action: "add" | "replace"; readonly classDef: MessageTaxonomyClass }
+  | { readonly action: "remove"; readonly className: string };
+
+const MAX_TAXONOMY_CLASSES = 50;
+const MAX_LIST_ITEMS = 100;
+const MAX_NAME_LENGTH = 120;
+
+export function validateMessageTaxonomy(value: unknown): MessageTaxonomy | null {
+  if (value === null) return null;
+  if (!Array.isArray(value) || value.length > MAX_TAXONOMY_CLASSES) {
+    throw new TypeError("Message taxonomy must be null or an array of at most 50 classes.");
+  }
+  const classes = new Set<string>();
+  const prefixes = new Set<string>();
+  return value.map((candidate) => {
+    const record = taxonomyObject(candidate);
+    exactTaxonomyKeys(record);
+    const className = boundedTaxonomyString(record["class"], "Taxonomy class", 64);
+    const classKey = normalize(className);
+    if (classes.has(classKey)) throw new TypeError("Message taxonomy class names must be unique.");
+    classes.add(classKey);
+    const routing = record["routing"];
+    if (routing !== "broadcast" && routing !== "directed") {
+      throw new TypeError("Message taxonomy routing must be broadcast or directed.");
+    }
+    const classPrefixes = taxonomyStringArray(record["prefixes"], "Taxonomy prefixes", 64);
+    for (const prefix of classPrefixes) {
+      const key = normalize(prefix);
+      if (prefixes.has(key)) throw new TypeError("Message taxonomy prefixes must be unique.");
+      prefixes.add(key);
+    }
+    const defaultTo = taxonomyStringArray(record["default_to"], "Taxonomy default recipients");
+    if (routing === "directed" && defaultTo.length === 0) {
+      throw new TypeError("Directed taxonomy classes require default recipients.");
+    }
+    const lifecycle = record["lifecycle"];
+    if (lifecycle !== undefined && lifecycle !== "dispatch" && lifecycle !== "completion") {
+      throw new TypeError("Message taxonomy lifecycle must be dispatch or completion.");
+    }
+    return {
+      class: className,
+      prefixes: classPrefixes,
+      routing,
+      ...(defaultTo.length === 0 ? {} : { default_to: defaultTo }),
+      ...(lifecycle === undefined ? {} : { lifecycle }),
+    };
+  });
+}
+
+export function patchMessageTaxonomy(
+  taxonomy: MessageTaxonomy | null,
+  patch: TaxonomyPatch,
+): MessageTaxonomy | null {
+  const current = taxonomy ?? [];
+  if (patch.action === "remove") {
+    const index = classIndex(current, patch.className);
+    if (index < 0) throw new TypeError("Message taxonomy class does not exist.");
+    const next = [...current.slice(0, index), ...current.slice(index + 1)];
+    return next.length === 0 ? null : validateMessageTaxonomy(next);
+  }
+  const validated = validateMessageTaxonomy([patch.classDef])![0]!;
+  const index = classIndex(current, validated.class);
+  if (patch.action === "add") {
+    if (index >= 0) throw new TypeError("Message taxonomy class already exists.");
+    return validateMessageTaxonomy([...current, validated]);
+  }
+  if (index < 0) throw new TypeError("Message taxonomy class does not exist.");
+  return validateMessageTaxonomy([
+    ...current.slice(0, index),
+    validated,
+    ...current.slice(index + 1),
+  ]);
+}
+
+export function resolveMessageRouting(
+  input: {
+    readonly message: string;
+    readonly visibility?: "broadcast" | "direct";
+    readonly recipientDroneIds?: readonly string[];
+    readonly className?: string;
+    readonly to?: readonly string[];
+  },
+  taxonomy: MessageTaxonomy | null,
+  roles: readonly RoutingRole[],
+  drones: readonly RoutingDrone[],
+): MessageRouting {
+  if (input.visibility === "broadcast" &&
+      ((input.recipientDroneIds?.length ?? 0) > 0 || input.to !== undefined)) {
+    throw new TypeError("Broadcast activity cannot name direct recipients.");
+  }
+  if (input.visibility !== undefined || input.recipientDroneIds !== undefined) {
+    const visibility = input.visibility ?? "direct";
+    const recipients = visibility === "direct"
+      ? input.recipientDroneIds?.length
+        ? [...new Set(input.recipientDroneIds)]
+        : resolveSelectors(input.to ?? [], roles, drones, true)
+      : [];
+    if (visibility === "direct" && recipients.length === 0) {
+      throw new TypeError("Direct activity requires a recipient.");
+    }
+    return routingResult(visibility, recipients, null, false, null);
+  }
+
+  const explicitClass = input.className === undefined
+    ? null
+    : taxonomyClass(taxonomy, input.className);
+  if (input.className !== undefined && explicitClass === null) {
+    throw new TypeError("Message taxonomy class is not declared by this cube.");
+  }
+  if (input.to !== undefined) {
+    const recipients = resolveSelectors(input.to, roles, drones, true);
+    return routingResult("direct", recipients, explicitClass?.class ?? null, false, null);
+  }
+  if (taxonomy === null) return routingResult("broadcast", [], null, false, null);
+
+  const matched = explicitClass ?? classifyMessage(taxonomy, input.message);
+  if (matched === null || matched.routing === "broadcast") {
+    return routingResult("broadcast", [], matched?.class ?? null, false, null);
+  }
+  const recipients = resolveSelectors(matched.default_to ?? [], roles, drones, false);
+  if (recipients.length === 0) {
+    return routingResult(
+      "broadcast",
+      [],
+      matched.class,
+      true,
+      "No active default recipient resolved; delivered as broadcast.",
+    );
+  }
+  return routingResult("direct", recipients, matched.class, false, null);
+}
+
+function resolveSelectors(
+  selectors: readonly string[],
+  roles: readonly RoutingRole[],
+  drones: readonly RoutingDrone[],
+  strict: boolean,
+): string[] {
+  if (strict && selectors.length === 0) throw new TypeError("Direct recipients cannot be empty.");
+  const recipients = new Set<string>();
+  for (const selector of selectors) {
+    try {
+      for (const drone of resolveSelector(selector, roles, drones)) recipients.add(drone.id);
+    } catch (error) {
+      if (strict) throw error;
+    }
+  }
+  return [...recipients];
+}
+
+function resolveSelector(
+  selector: string,
+  roles: readonly RoutingRole[],
+  allDrones: readonly RoutingDrone[],
+): RoutingDrone[] {
+  const drones = allDrones.filter((drone) => drone.posture === "participant");
+  if (selector === "@human-seat") {
+    const roleIds = new Set(roles.filter((role) => role.is_human_seat).map((role) => role.id));
+    const matches = drones.filter((drone) => roleIds.has(drone.role_id));
+    if (matches.length === 0) throw new TypeError("Recipient has no active drone.");
+    return matches;
+  }
+  const exact = drones.filter((drone) => drone.id === selector || drone.label === selector);
+  if (exact.length === 1) return exact;
+  if (exact.length > 1) throw new TypeError("Recipient is ambiguous.");
+
+  const shortId = selector.replace(/^`|`$/gu, "").replace(/^id:/iu, "");
+  if (/^[0-9a-f]{8,}$/iu.test(shortId)) {
+    const matches = drones.filter((drone) => drone.id.toLowerCase().startsWith(shortId.toLowerCase()));
+    if (matches.length === 1) return matches;
+    if (matches.length > 1) throw new TypeError("Recipient is ambiguous.");
+  }
+
+  const matchingRoles = roles.filter((role) => roleSlug(role.name) === roleSlug(selector));
+  if (matchingRoles.length > 1) throw new TypeError("Recipient role is ambiguous.");
+  if (matchingRoles.length === 1) {
+    const matches = drones.filter((drone) => drone.role_id === matchingRoles[0]!.id);
+    if (matches.length === 0) throw new TypeError("Recipient role has no active drone.");
+    return matches;
+  }
+  throw new TypeError("Recipient does not exist.");
+}
+
+function classifyMessage(taxonomy: MessageTaxonomy, message: string): MessageTaxonomyClass | null {
+  const token = message.split(/[:\s]/u, 1)[0] ?? "";
+  const key = normalize(token);
+  return taxonomy.find((entry) => (entry.prefixes ?? []).some((prefix) => normalize(prefix) === key)) ?? null;
+}
+
+function taxonomyClass(
+  taxonomy: MessageTaxonomy | null,
+  className: string,
+): MessageTaxonomyClass | null {
+  if (taxonomy === null) return null;
+  const key = normalize(className);
+  return taxonomy.find((entry) => normalize(entry.class) === key) ?? null;
+}
+
+function routingResult(
+  visibility: "broadcast" | "direct",
+  recipientDroneIds: string[],
+  className: string | null,
+  fellOpen: boolean,
+  message: string | null,
+): MessageRouting {
+  return {
+    visibility,
+    recipientDroneIds,
+    routing: { class: className, recipients: recipientDroneIds, fellOpen, message },
+  };
+}
+
+function taxonomyObject(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError("Message taxonomy classes must be objects.");
+  }
+  return value as Record<string, unknown>;
+}
+
+function exactTaxonomyKeys(record: Record<string, unknown>): void {
+  const allowed = new Set(["class", "prefixes", "routing", "default_to", "lifecycle"]);
+  if (Object.keys(record).some((key) => !allowed.has(key))) {
+    throw new TypeError("Message taxonomy class contains an unknown field.");
+  }
+}
+
+function boundedTaxonomyString(value: unknown, label: string, maxLength = MAX_NAME_LENGTH): string {
+  if (typeof value !== "string" || value.trim().length === 0 || value.length > maxLength) {
+    throw new TypeError(`${label} must be non-empty bounded text.`);
+  }
+  return value.trim();
+}
+
+function taxonomyStringArray(value: unknown, label: string, maxLength = MAX_NAME_LENGTH): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_LIST_ITEMS) {
+    throw new TypeError(`${label} must be a bounded array.`);
+  }
+  const entries = value.map((entry) => boundedTaxonomyString(entry, label, maxLength));
+  if (new Set(entries.map(normalize)).size !== entries.length) {
+    throw new TypeError(`${label} must contain unique values.`);
+  }
+  return entries;
+}
+
+function classIndex(taxonomy: MessageTaxonomy, className: string): number {
+  const key = normalize(className);
+  return taxonomy.findIndex((entry) => normalize(entry.class) === key);
+}
+
+function normalize(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function roleSlug(value: string): string {
+  return value.toLowerCase().replace(/[\s_]+/gu, "-").replace(/[^a-z0-9-]/gu, "");
+}