borgmcp-server 0.1.1 → 0.1.4

package/src/store.ts

@@ -4,13 +4,14 @@ import { chmod, lstat, mkdir, open } from "node:fs/promises";
 import { dirname, join, parse, relative, resolve, sep } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 
-import { applyMigrations } from "./migrations.js";
+import { applyMigrations, assertMigrationsCurrent } from "./migrations.js";
 import { operatorErrors } from "./operator-error.js";
 import {
   assertCanonicalUuid,
   assertServerDerivedPrincipal,
   type Principal,
 } from "./principal.js";
+import { patchRoleSectionText, type RoleSectionPatchOp } from "./role-section.js";
 
 export type CubeAccess = "read" | "write" | "manage";
 
@@ -84,8 +85,12 @@ export interface RoleRecord {
   readonly cube_id: string;
   readonly name: string;
   readonly short_description: string;
+  readonly detailed_description: string;
   readonly is_default: boolean;
+  readonly is_mandatory: boolean;
   readonly is_human_seat: boolean;
+  readonly can_broadcast: boolean;
+  readonly receives_all_direct: boolean;
   readonly role_class: "queen" | "worker";
   readonly created_at: string;
 }
@@ -97,6 +102,7 @@ export interface DroneRecord {
   readonly label: string;
   readonly last_seen: string;
   readonly hostname: string | null;
+  readonly posture: "observer" | "participant";
   readonly created_at: string;
 }
 
@@ -113,6 +119,7 @@ export interface OpenStoreOptions {
   readonly capacityProbe?: () => StorageCapacity;
   readonly cubeLimits?: CubeLimits;
   readonly mutationHook?: (phase: string) => void;
+  readonly migrationMode?: "apply" | "require-current";
 }
 
 export interface CubeLimits {
@@ -166,6 +173,25 @@ export interface StoredSecretDigest extends DigestPair {
 export interface StoredInvitationDigest extends StoredSecretDigest {
   readonly purpose: "owner" | "client";
   readonly ownerEpoch: number | null;
+  readonly cubeId: string | null;
+  readonly access: CubeAccess | null;
+}
+
+export interface InvitationCubeScope {
+  readonly cubeId: string;
+  readonly cubeName: string;
+  readonly access: CubeAccess;
+}
+
+export class InvitationCubeNotFoundError extends Error {}
+
+export class InvitationCubeAmbiguousError extends Error {
+  readonly candidateIds: readonly string[];
+
+  constructor(candidateIds: readonly string[]) {
+    super("Cube name is ambiguous.");
+    this.candidateIds = Object.freeze([...candidateIds]);
+  }
 }
 
 export interface EnrollmentClaimResult {
@@ -190,7 +216,9 @@ export interface CredentialStore {
     readonly digest: DigestPair;
     readonly expiresAt: string;
     readonly purpose: "owner" | "client";
-  }) => void;
+    readonly cubeSelector?: { readonly kind: "id" | "name"; readonly value: string };
+    readonly access?: CubeAccess;
+  }) => InvitationCubeScope | null;
   readonly findInvitation: (lookup: Buffer) => StoredInvitationDigest | null;
   readonly claimInvitation: (input: {
     readonly invitationId: string;
@@ -220,6 +248,9 @@ export interface ScopedStore {
   readonly appendActivity: (cubeId: string, message: string) => ActivityRecord;
   readonly readActivity: (cubeId: string, limit: number) => ActivityRecord[];
   readonly listRoles: (cubeId: string) => RoleRecord[];
+  readonly createRole: (cubeId: string, input: CreateRoleInput) => RoleRecord;
+  readonly updateRole: (cubeId: string, roleId: string, input: UpdateRoleInput) => RoleRecord;
+  readonly patchRoleSection: (cubeId: string, roleId: string, input: RoleSectionPatchOp) => RoleRecord;
   readonly listDrones: (cubeId: string) => DroneRecord[];
   readonly appendLog: (cubeId: string, input: {
     readonly message: string;
@@ -241,6 +272,28 @@ export interface ScopedStore {
   readonly attachSeat: (input: SeatAttachInput) => SeatAttachRecord;
 }
 
+export interface CreateRoleInput {
+  readonly name: string;
+  readonly shortDescription?: string;
+  readonly detailedDescription?: string;
+  readonly isDefault?: boolean;
+  readonly isMandatory?: boolean;
+  readonly isHumanSeat?: boolean;
+  readonly canBroadcast?: boolean;
+  readonly receivesAllDirect?: boolean;
+}
+
+export interface UpdateRoleInput {
+  readonly name?: string;
+  readonly shortDescription?: string;
+  readonly detailedDescription?: string;
+  readonly isDefault?: boolean;
+  readonly isMandatory?: boolean;
+  readonly isHumanSeat?: boolean;
+  readonly canBroadcast?: boolean;
+  readonly receivesAllDirect?: boolean;
+}
+
 export interface CreateCubeInput {
   readonly retryKey: string;
   readonly name: string;
@@ -284,6 +337,7 @@ export interface SeatAttachRecord {
   readonly sessionId: string;
   readonly expiresAt: string;
   readonly generation: number;
+  readonly posture: "observer" | "participant";
   readonly reattached: boolean;
   readonly revokedSessionIds: readonly string[];
 }
@@ -359,6 +413,33 @@ export class ScopedStoreError extends Error {
   }
 }
 
+export class RoleConflictError extends Error {
+  readonly code = "ROLE_ALREADY_EXISTS";
+
+  constructor() {
+    super("A role with that name already exists.");
+    this.name = "RoleConflictError";
+  }
+}
+
+export class DefaultRoleRequiredError extends Error {
+  readonly code = "DEFAULT_ROLE_REQUIRED";
+
+  constructor() {
+    super("A cube must retain one default role.");
+    this.name = "DefaultRoleRequiredError";
+  }
+}
+
+export class RoleSectionConflictError extends Error {
+  readonly code = "ROLE_SECTION_CONFLICT";
+
+  constructor() {
+    super("The role section patch conflicts with the current role text.");
+    this.name = "RoleSectionConflictError";
+  }
+}
+
 export class CursorExpiredError extends Error {
   readonly code = "CURSOR_EXPIRED";
 
@@ -470,8 +551,13 @@ export async function openStore(options: OpenStoreOptions): Promise<StoreRuntime
   });
   const clock = options.clock ?? (() => new Date());
   try {
-    configureDatabase(database);
-    applyMigrations(database);
+    if (options.migrationMode === "require-current") {
+      configureExistingDatabase(database);
+      assertMigrationsCurrent(database);
+    } else {
+      configureDatabase(database);
+      applyMigrations(database);
+    }
   } catch (error) {
     database.close();
     throw error;
@@ -693,19 +779,229 @@ class SqliteScopedStore implements ScopedStore {
   listRoles(cubeId: string): RoleRecord[] {
     this.#requireCube(cubeId, "read");
     const rows = this.#database.prepare(`
-      SELECT id, cube_id, name, short_description, is_default, is_human_seat,
-             role_class, created_at
+      SELECT id, cube_id, name, short_description, detailed_description,
+             is_default, is_mandatory, is_human_seat, can_broadcast,
+             receives_all_direct, role_class, created_at
       FROM roles WHERE cube_id = ? ORDER BY name, id
     `).all(cubeId);
     return rows.map(roleRecord);
   }
 
+  createRole(cubeId: string, input: CreateRoleInput): RoleRecord {
+    assertCanonicalUuid(cubeId, "Cube id");
+    validateRoleName(input.name);
+    const shortDescription = input.shortDescription ?? "";
+    const detailedDescription = input.detailedDescription ?? "";
+    validateRoleShortDescription(shortDescription);
+    assertRoleTextWriteAllowed(detailedDescription);
+    for (const value of [
+      input.isDefault,
+      input.isMandatory,
+      input.isHumanSeat,
+      input.canBroadcast,
+      input.receivesAllDirect,
+    ]) {
+      if (value !== undefined && typeof value !== "boolean") throw new TypeError("Role flags must be boolean.");
+    }
+    const isDefault = input.isDefault ?? false;
+    const isMandatory = input.isMandatory ?? false;
+    const isHumanSeat = input.isHumanSeat ?? false;
+    const canBroadcast = input.canBroadcast ?? false;
+    const receivesAllDirect = input.receivesAllDirect ?? false;
+    this.#requireCube(cubeId, "manage");
+    this.#capacityGuard.assertCanGrow(
+      Buffer.byteLength(input.name) + Buffer.byteLength(shortDescription) +
+      Buffer.byteLength(detailedDescription) + 8_192,
+    );
+
+    this.#database.exec("BEGIN IMMEDIATE");
+    try {
+      this.#requireCube(cubeId, "manage");
+      const duplicate = this.#database.prepare(
+        "SELECT 1 AS present FROM roles WHERE cube_id = ? AND name = ?",
+      ).get(cubeId, input.name);
+      if (duplicate !== undefined) throw new RoleConflictError();
+      if (isDefault) {
+        this.#database.prepare("UPDATE roles SET is_default = 0 WHERE cube_id = ? AND is_default = 1")
+          .run(cubeId);
+        this.#mutationHook?.("role.demote-default");
+      }
+      const id = randomUUID();
+      this.#database.prepare(`
+        INSERT INTO roles (
+          id, cube_id, name, short_description, detailed_description,
+          is_default, is_mandatory, is_human_seat, can_broadcast,
+          receives_all_direct, role_class, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'worker', ?)
+      `).run(
+        id, cubeId, input.name, shortDescription, detailedDescription,
+        booleanInteger(isDefault), booleanInteger(isMandatory), booleanInteger(isHumanSeat),
+        booleanInteger(canBroadcast), booleanInteger(receivesAllDirect), this.#now(),
+      );
+      this.#mutationHook?.("role.insert");
+      const row = this.#database.prepare(`
+        SELECT id, cube_id, name, short_description, detailed_description,
+               is_default, is_mandatory, is_human_seat, can_broadcast,
+               receives_all_direct, role_class, created_at
+        FROM roles WHERE id = ? AND cube_id = ?
+      `).get(id, cubeId);
+      if (row === undefined) throw new ScopedStoreError();
+      this.#database.exec("COMMIT");
+      this.#mutationHook?.("role.after-commit");
+      return roleRecord(row);
+    } catch (error) {
+      try { this.#database.exec("ROLLBACK"); } catch { /* Preserve the original failure. */ }
+      throw error;
+    }
+  }
+
+  updateRole(cubeId: string, roleId: string, input: UpdateRoleInput): RoleRecord {
+    assertCanonicalUuid(cubeId, "Cube id");
+    assertCanonicalUuid(roleId, "Role id");
+    if (Object.values(input).every((value) => value === undefined)) {
+      throw new TypeError("At least one role field is required.");
+    }
+    if (input.name !== undefined) validateRoleName(input.name);
+    if (input.shortDescription !== undefined) validateRoleShortDescription(input.shortDescription);
+    if (input.detailedDescription !== undefined && typeof input.detailedDescription !== "string") {
+      throw new TypeError("Role detailed description must be text.");
+    }
+    for (const value of [
+      input.isDefault,
+      input.isMandatory,
+      input.isHumanSeat,
+      input.canBroadcast,
+      input.receivesAllDirect,
+    ]) {
+      if (value !== undefined && typeof value !== "boolean") throw new TypeError("Role flags must be boolean.");
+    }
+    this.#requireCube(cubeId, "manage");
+    this.#capacityGuard.assertCanGrow(
+      Buffer.byteLength(input.name ?? "") + Buffer.byteLength(input.shortDescription ?? "") +
+      Buffer.byteLength(input.detailedDescription ?? "") + 8_192,
+    );
+
+    this.#database.exec("BEGIN IMMEDIATE");
+    try {
+      this.#requireCube(cubeId, "manage");
+      const existingRow = this.#database.prepare(`
+        SELECT id, cube_id, name, short_description, detailed_description,
+               is_default, is_mandatory, is_human_seat, can_broadcast,
+               receives_all_direct, role_class, created_at
+        FROM roles WHERE id = ? AND cube_id = ?
+      `).get(roleId, cubeId);
+      if (existingRow === undefined) throw new ScopedStoreError();
+      const existing = roleRecord(existingRow);
+      if (input.isDefault === false && existing.is_default) {
+        throw new DefaultRoleRequiredError();
+      }
+      if (input.name !== undefined && input.name !== existing.name) {
+        const duplicate = this.#database.prepare(
+          "SELECT 1 AS present FROM roles WHERE cube_id = ? AND name = ? AND id <> ?",
+        ).get(cubeId, input.name, roleId);
+        if (duplicate !== undefined) throw new RoleConflictError();
+      }
+      if (input.isDefault === true && !existing.is_default) {
+        this.#database.prepare("UPDATE roles SET is_default = 0 WHERE cube_id = ? AND is_default = 1")
+          .run(cubeId);
+        this.#mutationHook?.("role.demote-default");
+      }
+      const nextDetailedDescription = input.detailedDescription ?? existing.detailed_description;
+      assertRoleTextWriteAllowed(nextDetailedDescription, existing.detailed_description);
+      this.#database.prepare(`
+        UPDATE roles SET
+          name = ?, short_description = ?, detailed_description = ?, is_default = ?,
+          is_mandatory = ?, is_human_seat = ?, can_broadcast = ?, receives_all_direct = ?
+        WHERE id = ? AND cube_id = ?
+      `).run(
+        input.name ?? existing.name,
+        input.shortDescription ?? existing.short_description,
+        nextDetailedDescription,
+        booleanInteger(input.isDefault ?? existing.is_default),
+        booleanInteger(input.isMandatory ?? existing.is_mandatory),
+        booleanInteger(input.isHumanSeat ?? existing.is_human_seat),
+        booleanInteger(input.canBroadcast ?? existing.can_broadcast),
+        booleanInteger(input.receivesAllDirect ?? existing.receives_all_direct),
+        roleId,
+        cubeId,
+      );
+      const row = this.#database.prepare(`
+        SELECT id, cube_id, name, short_description, detailed_description,
+               is_default, is_mandatory, is_human_seat, can_broadcast,
+               receives_all_direct, role_class, created_at
+        FROM roles WHERE id = ? AND cube_id = ?
+      `).get(roleId, cubeId);
+      if (row === undefined) throw new ScopedStoreError();
+      this.#database.exec("COMMIT");
+      this.#mutationHook?.("role.after-commit");
+      return roleRecord(row);
+    } catch (error) {
+      try { this.#database.exec("ROLLBACK"); } catch { /* Preserve the original failure. */ }
+      throw error;
+    }
+  }
+
+  patchRoleSection(cubeId: string, roleId: string, input: RoleSectionPatchOp): RoleRecord {
+    assertCanonicalUuid(cubeId, "Cube id");
+    assertCanonicalUuid(roleId, "Role id");
+    this.#requireCube(cubeId, "manage");
+    this.#capacityGuard.assertCanGrow(
+      Buffer.byteLength(input.heading) +
+      ("body" in input ? Buffer.byteLength(input.body) : 0) + 8_192,
+    );
+
+    this.#database.exec("BEGIN IMMEDIATE");
+    try {
+      this.#requireCube(cubeId, "manage");
+      const existingRow = this.#database.prepare(`
+        SELECT id, cube_id, name, short_description, detailed_description,
+               is_default, is_mandatory, is_human_seat, can_broadcast,
+               receives_all_direct, role_class, created_at
+        FROM roles WHERE id = ? AND cube_id = ?
+      `).get(roleId, cubeId);
+      if (existingRow === undefined) throw new ScopedStoreError();
+      const existing = roleRecord(existingRow);
+      let detailedDescription: string;
+      try {
+        detailedDescription = patchRoleSectionText(existing.detailed_description, input);
+      } catch (error) {
+        if (error instanceof TypeError) throw error;
+        throw new RoleSectionConflictError();
+      }
+      assertRoleTextWriteAllowed(detailedDescription, existing.detailed_description);
+      this.#database.prepare(
+        "UPDATE roles SET detailed_description = ? WHERE id = ? AND cube_id = ?",
+      ).run(detailedDescription, roleId, cubeId);
+      const row = this.#database.prepare(`
+        SELECT id, cube_id, name, short_description, detailed_description,
+               is_default, is_mandatory, is_human_seat, can_broadcast,
+               receives_all_direct, role_class, created_at
+        FROM roles WHERE id = ? AND cube_id = ?
+      `).get(roleId, cubeId);
+      if (row === undefined) throw new ScopedStoreError();
+      this.#database.exec("COMMIT");
+      this.#mutationHook?.("role.after-commit");
+      return roleRecord(row);
+    } catch (error) {
+      try { this.#database.exec("ROLLBACK"); } catch { /* Preserve the original failure. */ }
+      throw error;
+    }
+  }
+
   listDrones(cubeId: string): DroneRecord[] {
     this.#requireCube(cubeId, "read");
     const rows = this.#database.prepare(`
-      SELECT id, cube_id, role_id, label, COALESCE(last_seen, created_at) AS last_seen,
-             hostname, created_at
-      FROM drones WHERE cube_id = ? AND evicted_at IS NULL ORDER BY label, id
+      SELECT drone.id, drone.cube_id, drone.role_id, drone.label,
+             COALESCE(drone.last_seen, drone.created_at) AS last_seen,
+             drone.hostname, drone.created_at,
+             CASE WHEN client.revoked_at IS NULL AND grant_row.access IN ('write', 'manage')
+               THEN 'participant' ELSE 'observer' END AS posture
+      FROM drones AS drone
+      LEFT JOIN clients AS client ON client.id = drone.client_id
+      LEFT JOIN client_cube_grants AS grant_row
+        ON grant_row.client_id = drone.client_id AND grant_row.cube_id = drone.cube_id
+      WHERE drone.cube_id = ? AND drone.evicted_at IS NULL
+      ORDER BY drone.label, drone.id
     `).all(cubeId);
     return rows.map(droneRecord);
   }
@@ -758,9 +1054,16 @@ class SqliteScopedStore implements ScopedStore {
       if (inserted.changes !== 1) throw new ScopedStoreError();
       if (recipients.length > 0) {
         const valid = this.#database.prepare(`
-          SELECT COUNT(*) AS count FROM drones
-          WHERE cube_id = ? AND evicted_at IS NULL
-            AND id IN (${recipients.map(() => "?").join(", ")})
+          SELECT COUNT(*) AS count
+          FROM drones AS recipient
+          JOIN clients AS recipient_client ON recipient_client.id = recipient.client_id
+          JOIN client_cube_grants AS recipient_grant
+            ON recipient_grant.client_id = recipient.client_id
+            AND recipient_grant.cube_id = recipient.cube_id
+          WHERE recipient.cube_id = ? AND recipient.evicted_at IS NULL
+            AND recipient_client.revoked_at IS NULL
+            AND recipient_grant.access IN ('write', 'manage')
+            AND recipient.id IN (${recipients.map(() => "?").join(", ")})
         `).get(cubeId, ...recipients);
         if (valid === undefined) throw new Error("Recipient count query returned no row.");
         if (requiredInteger(valid, "count") !== recipients.length) throw new ScopedStoreError();
@@ -786,6 +1089,7 @@ class SqliteScopedStore implements ScopedStore {
       throw new Error("Activity read limit must be an integer from 1 to 500.");
     }
     this.#validateCursor(cubeId, cursor);
+    const broadcastOnly = !this.#allowsDirectedWork(cubeId);
     const cursorSql = cursor === null
       ? { sql: "1 = 1", parameters: [] as string[] }
       : {
@@ -796,6 +1100,7 @@ class SqliteScopedStore implements ScopedStore {
       SELECT l.id
       FROM activity_log AS l
       WHERE l.cube_id = ? AND ${cursorSql.sql}
+        AND (${broadcastOnly ? "l.visibility = 'broadcast'" : "1 = 1"})
       ORDER BY l.created_at, l.id
       LIMIT ?
     `).all(cubeId, ...cursorSql.parameters, limit + 1);
@@ -804,13 +1109,15 @@ class SqliteScopedStore implements ScopedStore {
     const nextCursor = entries.length === 0
       ? cursor
       : { id: entries.at(-1)!.id, created_at: entries.at(-1)!.created_at };
-    const behind = nextCursor === null ? this.#countAfter(cubeId, null) : this.#countAfter(cubeId, nextCursor);
+    const behind = nextCursor === null
+      ? this.#countAfter(cubeId, null, broadcastOnly)
+      : this.#countAfter(cubeId, nextCursor, broadcastOnly);
     return {
       entries,
       cursor: nextCursor,
       behind_by: behind,
       has_more: behind > 0,
-      claims: this.#claims(cubeId),
+      claims: this.#claims(cubeId, broadcastOnly),
     };
   }
 
@@ -912,6 +1219,7 @@ class SqliteScopedStore implements ScopedStore {
         WHERE c.id = ? AND role.id = ? AND ${scope.sql}
       `).get(input.cubeId, input.roleId, ...scope.parameters);
       if (roleRow === undefined) throw new ScopedStoreError();
+      const posture = this.#allowsDirectedWork(input.cubeId) ? "participant" : "observer";
 
       const retryBinding = this.#database.prepare(`
         SELECT binding.cube_id AS binding_cube_id,
@@ -1048,6 +1356,7 @@ class SqliteScopedStore implements ScopedStore {
         sessionId: input.sessionId,
         expiresAt: input.expiresAt,
         generation,
+        posture,
         reattached,
         revokedSessionIds: oldSessions,
       };
@@ -1059,7 +1368,16 @@ class SqliteScopedStore implements ScopedStore {
 
   subscribeActivity(cubeId: string, listener: (entry: EnrichedActivityRecord) => void): () => void {
     this.#requireCube(cubeId, "read");
-    return this.#activityHub.subscribe(cubeId, listener);
+    return this.#activityHub.subscribe(cubeId, (entry) => {
+      if (entry.visibility === "broadcast" || this.#allowsDirectedWork(cubeId)) listener(entry);
+    });
+  }
+
+  #allowsDirectedWork(cubeId: string): boolean {
+    const scope = this.#scope("write");
+    return this.#database.prepare(`
+      SELECT 1 AS allowed FROM cubes AS c WHERE c.id = ? AND ${scope.sql}
+    `).get(cubeId, ...scope.parameters) !== undefined;
   }
 
   #requireCube(cubeId: string, access: CubeAccess): void {
@@ -1123,14 +1441,16 @@ class SqliteScopedStore implements ScopedStore {
     if (valid === undefined) throw new ScopedStoreError();
   }
 
-  #countAfter(cubeId: string, cursor: LogCursor | null): number {
+  #countAfter(cubeId: string, cursor: LogCursor | null, broadcastOnly: boolean): number {
+    const visibility = broadcastOnly ? "AND visibility = 'broadcast'" : "";
     const row = cursor === null
       ? this.#database.prepare(
-          "SELECT COUNT(*) AS count FROM activity_log WHERE cube_id = ?",
+          `SELECT COUNT(*) AS count FROM activity_log WHERE cube_id = ? ${visibility}`,
         ).get(cubeId)
       : this.#database.prepare(`
           SELECT COUNT(*) AS count FROM activity_log
           WHERE cube_id = ? AND (created_at > ? OR (created_at = ? AND id > ?))
+            ${visibility}
         `).get(cubeId, cursor.created_at, cursor.created_at, cursor.id);
     if (row === undefined) throw new Error("Activity count query returned no row.");
     return requiredInteger(row, "count");
@@ -1152,7 +1472,7 @@ class SqliteScopedStore implements ScopedStore {
     return enrichedActivityRecord(row, recipientRows.map((recipient) => requiredText(recipient, "drone_id")));
   }
 
-  #claims(cubeId: string): ClaimRecord[] {
+  #claims(cubeId: string, broadcastOnly: boolean): ClaimRecord[] {
     return this.#database.prepare(`
       SELECT acknowledgement.entry_id AS log_entry_id,
              acknowledgement.claimant_drone_id,
@@ -1166,6 +1486,7 @@ class SqliteScopedStore implements ScopedStore {
       LEFT JOIN roles AS role ON role.id = drone.role_id AND role.cube_id = drone.cube_id
       WHERE entry.cube_id = ? AND acknowledgement.kind = 'claim'
         AND acknowledgement.claimant_drone_id IS NOT NULL
+        AND (${broadcastOnly ? "entry.visibility = 'broadcast'" : "1 = 1"})
       ORDER BY acknowledgement.created_at, acknowledgement.entry_id,
                acknowledgement.claimant_drone_id
     `).all(cubeId).map(claimRecord);
@@ -1557,12 +1878,39 @@ class SqliteCredentialStore implements CredentialStore {
     readonly digest: DigestPair;
     readonly expiresAt: string;
     readonly purpose: "owner" | "client";
-  }): void {
+    readonly cubeSelector?: { readonly kind: "id" | "name"; readonly value: string };
+    readonly access?: CubeAccess;
+  }): InvitationCubeScope | null {
     assertCanonicalUuid(input.id, "Invitation id");
     validateDigest(input.digest);
     validateTimestamp(input.expiresAt);
     this.#database.exec("BEGIN IMMEDIATE");
     try {
+      let scope: InvitationCubeScope | null = null;
+      if (input.cubeSelector !== undefined) {
+        if (input.purpose !== "client" || input.access === undefined) {
+          throw new Error("Only client invitations may carry a complete cube scope.");
+        }
+        if (input.access !== "read" && input.access !== "write" && input.access !== "manage") {
+          throw new Error("Unknown cube access grant.");
+        }
+        const rows = input.cubeSelector.kind === "id"
+          ? this.#database.prepare("SELECT id, name FROM cubes WHERE id = ?").all(input.cubeSelector.value)
+          : this.#database.prepare("SELECT id, name FROM cubes WHERE name = ? ORDER BY id").all(input.cubeSelector.value);
+        if (rows.length === 0) throw new InvitationCubeNotFoundError();
+        if (rows.length > 1) {
+          throw new InvitationCubeAmbiguousError(rows.map((row) => requiredText(row, "id")));
+        }
+        const cubeId = requiredText(rows[0]!, "id");
+        assertCanonicalUuid(cubeId, "Resolved cube id");
+        scope = {
+          cubeId,
+          cubeName: requiredText(rows[0]!, "name"),
+          access: input.access,
+        };
+      } else if (input.access !== undefined) {
+        throw new Error("Invitation access requires a cube selector.");
+      }
       let ownerEpoch: number | null = null;
       if (input.purpose === "owner") {
         const state = this.#database.prepare(
@@ -1587,13 +1935,15 @@ class SqliteCredentialStore implements CredentialStore {
       }
       this.#database.prepare(`
         INSERT INTO enrollment_invitations (
-          id, lookup_digest, verifier_digest, expires_at, created_at, purpose, owner_epoch
-        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+          id, lookup_digest, verifier_digest, expires_at, created_at, purpose, owner_epoch,
+          cube_id, access
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
       `).run(
         input.id, input.digest.lookup, input.digest.verifier, input.expiresAt,
-        this.#now(), input.purpose, ownerEpoch,
+        this.#now(), input.purpose, ownerEpoch, scope?.cubeId ?? null, scope?.access ?? null,
       );
       this.#database.exec("COMMIT");
+      return scope;
     } catch (error) {
       try { this.#database.exec("ROLLBACK"); } catch { /* Preserve the original failure. */ }
       throw error;
@@ -1610,7 +1960,7 @@ class SqliteCredentialStore implements CredentialStore {
              COALESCE(invitation.expires_at, '') AS expires_at,
              invitation.consumed_at, invitation.revoked_at,
              COALESCE(invitation.purpose, 'client') AS purpose,
-             invitation.owner_epoch
+             invitation.owner_epoch, invitation.cube_id, invitation.access
       FROM (SELECT 1) AS seed
       LEFT JOIN enrollment_invitations AS invitation ON invitation.lookup_digest = ?
     `).get(lookup);
@@ -1641,7 +1991,8 @@ class SqliteCredentialStore implements CredentialStore {
                COALESCE(invitation.purpose, 'client') AS purpose,
                invitation.owner_epoch,
                COALESCE(invitation.expires_at, '') AS expires_at,
-               invitation.consumed_at, invitation.revoked_at
+               invitation.consumed_at, invitation.revoked_at,
+               invitation.cube_id, invitation.access
         FROM (SELECT 1) AS seed
         LEFT JOIN enrollment_invitations AS invitation ON invitation.id = ?
       `).get(input.invitationId);
@@ -1689,6 +2040,12 @@ class SqliteCredentialStore implements CredentialStore {
       const ownerEpoch = invitation["owner_epoch"] === null
         ? null
         : requiredInteger(invitation, "owner_epoch");
+      const cubeId = nullableText(invitation, "cube_id");
+      const accessValue = nullableText(invitation, "access");
+      const access = accessValue === null ? null : cubeAccess(accessValue);
+      if ((cubeId === null) !== (access === null) || (cubeId !== null && purpose !== "client")) {
+        throw new Error("Invalid invitation cube scope.");
+      }
       if (purpose === "owner") {
         const state = this.#database.prepare(`
           SELECT epoch, claimed_client_id FROM owner_enrollment_state WHERE singleton = 1
@@ -1699,6 +2056,10 @@ class SqliteCredentialStore implements CredentialStore {
           return null;
         }
       }
+      if (cubeId !== null && this.#database.prepare("SELECT 1 FROM cubes WHERE id = ?").get(cubeId) === undefined) {
+        this.#database.exec("ROLLBACK");
+        return null;
+      }
       this.#capacityGuard.assertCanGrow(Buffer.byteLength(input.requestedClientName ?? "") + 8_192);
       this.#database.prepare(
         "INSERT INTO clients (id, name, created_at) VALUES (?, ?, ?)",
@@ -1723,6 +2084,13 @@ class SqliteCredentialStore implements CredentialStore {
         `).run(input.clientId, now);
         this.#mutationHook?.("enrollment.insert-capability");
       }
+      if (cubeId !== null && access !== null) {
+        this.#database.prepare(`
+          INSERT INTO client_cube_grants (client_id, cube_id, access, created_at)
+          VALUES (?, ?, ?, ?)
+        `).run(input.clientId, cubeId, access, now);
+        this.#mutationHook?.("enrollment.insert-grant");
+      }
       this.#database.prepare(`
         INSERT INTO enrollment_claims (
           invitation_id, retry_key, client_id, requested_client_name,
@@ -1881,9 +2249,7 @@ class SqliteCredentialStore implements CredentialStore {
 async function prepareDatabasePath(path: string): Promise<string> {
   if (path === ":memory:") throw new Error("The server store requires a file-backed database.");
   const databasePath = resolve(path);
-  const directory = dirname(databasePath);
-  await ensureDirectoryTree(directory);
-  await chmod(directory, 0o700);
+  const directory = await preparePrivateDataDirectory(dirname(databasePath));
   try {
     const handle = await open(databasePath, "ax", 0o600);
     await handle.close();
@@ -1898,6 +2264,13 @@ async function prepareDatabasePath(path: string): Promise<string> {
   return databasePath;
 }
 
+export async function preparePrivateDataDirectory(path: string): Promise<string> {
+  const directory = resolve(path);
+  await ensureDirectoryTree(directory);
+  await chmod(directory, 0o700);
+  return directory;
+}
+
 async function ensureDirectoryTree(directory: string): Promise<void> {
   const { root } = parse(directory);
   let current = root;
@@ -1951,6 +2324,19 @@ function configureDatabase(database: DatabaseSync): void {
   }
 }
 
+function configureExistingDatabase(database: DatabaseSync): void {
+  database.exec(`
+    PRAGMA foreign_keys = ON;
+    PRAGMA synchronous = FULL;
+    PRAGMA trusted_schema = OFF;
+    PRAGMA secure_delete = ON;
+    PRAGMA busy_timeout = 5000;
+  `);
+  if (readPragma(database, "journal_mode") !== "wal") {
+    throw new Error("SQLite WAL mode is required.");
+  }
+}
+
 function diagnostics(database: DatabaseSync): StoreDiagnostics {
   const journalMode = readPragma(database, "journal_mode");
   const foreignKeys = readPragma(database, "foreign_keys");
@@ -2083,8 +2469,12 @@ function roleRecord(row: Record<string, unknown>): RoleRecord {
     cube_id: requiredText(row, "cube_id"),
     name: requiredText(row, "name"),
     short_description: requiredText(row, "short_description"),
+    detailed_description: requiredText(row, "detailed_description"),
     is_default: requiredInteger(row, "is_default") === 1,
+    is_mandatory: requiredInteger(row, "is_mandatory") === 1,
     is_human_seat: requiredInteger(row, "is_human_seat") === 1,
+    can_broadcast: requiredInteger(row, "can_broadcast") === 1,
+    receives_all_direct: requiredInteger(row, "receives_all_direct") === 1,
     role_class: roleClass,
     created_at: requiredText(row, "created_at"),
   };
@@ -2100,6 +2490,10 @@ function createCubeRecord(row: Record<string, unknown>): CreateCubeRecord {
 }
 
 function droneRecord(row: Record<string, unknown>): DroneRecord {
+  const posture = requiredText(row, "posture");
+  if (posture !== "observer" && posture !== "participant") {
+    throw new Error("Database contains invalid drone posture.");
+  }
   return {
     id: requiredText(row, "id"),
     cube_id: requiredText(row, "cube_id"),
@@ -2107,6 +2501,7 @@ function droneRecord(row: Record<string, unknown>): DroneRecord {
     label: requiredText(row, "label"),
     last_seen: requiredText(row, "last_seen"),
     hostname: nullableText(row, "hostname"),
+    posture,
     created_at: requiredText(row, "created_at"),
   };
 }
@@ -2155,7 +2550,20 @@ function storedInvitationDigest(row: Record<string, unknown>): StoredInvitationD
   }
   const epochValue = row["owner_epoch"];
   const ownerEpoch = epochValue === null ? null : requiredInteger(row, "owner_epoch");
-  return { ...digest, purpose, ownerEpoch };
+  const cubeId = nullableText(row, "cube_id");
+  const accessValue = nullableText(row, "access");
+  const access = accessValue === null ? null : cubeAccess(accessValue);
+  if ((cubeId === null) !== (access === null) || (cubeId !== null && purpose !== "client")) {
+    throw new Error("Database contains invalid invitation cube scope.");
+  }
+  return { ...digest, purpose, ownerEpoch, cubeId, access };
+}
+
+function cubeAccess(value: string): CubeAccess {
+  if (value !== "read" && value !== "write" && value !== "manage") {
+    throw new Error("Database contains invalid cube access.");
+  }
+  return value;
 }
 
 function enrollmentClaimResult(
@@ -2239,6 +2647,32 @@ function validatePresentationName(value: string): void {
   }
 }
 
+function validateRoleName(value: string): void {
+  if (typeof value !== "string" || value.length < 1 || value.length > 64) {
+    throw new Error("Role name must contain 1 to 64 characters.");
+  }
+}
+
+function validateRoleShortDescription(value: string): void {
+  if (typeof value !== "string" || value.length > 1_024) {
+    throw new Error("Role short description must contain at most 1024 characters.");
+  }
+}
+
+export const MAX_ROLE_DETAILED_DESCRIPTION_CHARS = 51_200;
+
+export function assertRoleTextWriteAllowed(value: string, previous?: string): void {
+  if (typeof value !== "string") throw new TypeError("Role detailed description must be text.");
+  if (value.length <= MAX_ROLE_DETAILED_DESCRIPTION_CHARS) return;
+  if (previous !== undefined && previous.length > MAX_ROLE_DETAILED_DESCRIPTION_CHARS &&
+      value.length < previous.length) return;
+  throw new RangeError("Role detailed description is too large.");
+}
+
+function booleanInteger(value: boolean): 0 | 1 {
+  return value ? 1 : 0;
+}
+
 function validateBoundedText(value: string, name: string, maxBytes: number): void {
   if (value.length === 0 || Buffer.byteLength(value) > maxBytes) {
     throw new Error(`${name} must contain 1 to ${maxBytes} bytes.`);