@axiom-lattice/local-stores 3.1.1 → 3.1.2

package/src/stores/LocalThreadMessageQueueStore.ts

@@ -10,6 +10,12 @@ import type {
   ThreadInfo,
   QueueScope,
 } from "@axiom-lattice/core";
+import {
+  parseQueuedExecutionMode,
+  parseTrustedRunContext,
+  type QueuedExecutionMode,
+  type TrustedRunContext,
+} from "@axiom-lattice/protocols";
 import { ensureTable, nowISO, parseISO } from "../database";
 import { randomUUID } from "crypto";
 
@@ -28,6 +34,8 @@ CREATE TABLE IF NOT EXISTS lt_thread_message_queue (
   status TEXT NOT NULL DEFAULT 'pending',
   command TEXT,
   custom_run_config TEXT,
+  trusted_run_context TEXT,
+  execution_mode TEXT CHECK (execution_mode IS NULL OR execution_mode = 'followup'),
   created_at TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS idx_lt_tmq_thread ON lt_thread_message_queue(thread_id, status);
@@ -48,6 +56,8 @@ interface QueueRow {
   status: string;
   command: string | null;
   custom_run_config: string | null;
+  trusted_run_context: string | null;
+  execution_mode: string | null;
   created_at: string;
 }
 
@@ -58,9 +68,18 @@ export class LocalThreadMessageQueueStore implements IMessageQueueStore {
   constructor(db: DatabaseWrapper) {
     this.db = db;
     ensureTable(db, DDL);
+    const columns = db.prepare("PRAGMA table_info(lt_thread_message_queue)").all() as Array<{ name: string }>;
+    const names = new Set(columns.map(({ name }) => name));
+    if (!names.has("trusted_run_context")) {
+      db.run("ALTER TABLE lt_thread_message_queue ADD COLUMN trusted_run_context TEXT");
+    }
+    if (!names.has("execution_mode")) {
+      db.run("ALTER TABLE lt_thread_message_queue ADD COLUMN execution_mode TEXT CHECK (execution_mode IS NULL OR execution_mode = 'followup')");
+    }
   }
 
   async addMessage(params: AddMessageParams): Promise<PendingMessage> {
+    const trusted = validateQueueTrust(params);
     const now = nowISO();
     const id = params.id || randomUUID();
 
@@ -70,8 +89,8 @@ export class LocalThreadMessageQueueStore implements IMessageQueueStore {
     const nextSeq = seqRow.next_seq;
 
     this.db.prepare(
-      `INSERT INTO lt_thread_message_queue (id, thread_id, tenant_id, assistant_id, workspace_id, project_id, message_content, message_type, sequence_order, priority, command, custom_run_config, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      `INSERT INTO lt_thread_message_queue (id, thread_id, tenant_id, assistant_id, workspace_id, project_id, message_content, message_type, sequence_order, priority, command, custom_run_config, trusted_run_context, execution_mode, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     ).run(
       id, params.threadId, params.tenantId, params.assistantId,
        params.workspaceId ?? null, params.projectId ?? null,
@@ -79,6 +98,8 @@ export class LocalThreadMessageQueueStore implements IMessageQueueStore {
        params.priority ?? 0,
       params.command ? JSON.stringify(params.command) : null,
       params.custom_run_config ? JSON.stringify(params.custom_run_config) : null,
+      trusted.trustedRunContext ? JSON.stringify(trusted.trustedRunContext) : null,
+      trusted.executionMode ?? null,
       now,
     );
 
@@ -86,6 +107,7 @@ export class LocalThreadMessageQueueStore implements IMessageQueueStore {
   }
 
   async addMessageIfCapacity(params: AddMessageParams, maxSize: number): Promise<boolean> {
+    const trusted = validateQueueTrust(params);
     let release!: () => void;
     const previous = this.capacityTail;
     this.capacityTail = new Promise<void>((resolve) => { release = resolve; });
@@ -101,10 +123,11 @@ export class LocalThreadMessageQueueStore implements IMessageQueueStore {
       const id = params.id || randomUUID();
       const limit = maxSize === Infinity ? -1 : maxSize;
       const result = this.db.prepare(
-        `INSERT INTO lt_thread_message_queue (id, thread_id, tenant_id, assistant_id, workspace_id, project_id, message_content, message_type, sequence_order, priority, command, custom_run_config, created_at)
+        `INSERT INTO lt_thread_message_queue (id, thread_id, tenant_id, assistant_id, workspace_id, project_id, message_content, message_type, sequence_order, priority, command, custom_run_config, trusted_run_context, execution_mode, created_at)
          SELECT ?, ?, ?, ?, ?, ?, ?, ?,
            (SELECT COALESCE(MAX(sequence_order), 0) + 1 FROM lt_thread_message_queue WHERE thread_id = ?),
-           ?, ?, ?, ?
+           ?, ?, ?, ?, ?,
+           ?
          WHERE ? = -1 OR (SELECT COUNT(*) FROM lt_thread_message_queue WHERE thread_id = ? AND status = 'pending'${filter.sql}) < ?`,
       ).run(
         id, params.threadId, params.tenantId, params.assistantId,
@@ -114,6 +137,8 @@ export class LocalThreadMessageQueueStore implements IMessageQueueStore {
         params.priority ?? 0,
         params.command ? JSON.stringify(params.command) : null,
         params.custom_run_config ? JSON.stringify(params.custom_run_config) : null,
+        trusted.trustedRunContext ? JSON.stringify(trusted.trustedRunContext) : null,
+        trusted.executionMode ?? null,
         nowISO(), limit, params.threadId, ...filter.params, limit,
       );
       return result.changes > 0;
@@ -123,6 +148,7 @@ export class LocalThreadMessageQueueStore implements IMessageQueueStore {
   }
 
   async addMessageAtHead(params: AddMessageParams): Promise<PendingMessage> {
+    const trusted = validateQueueTrust(params);
     const now = nowISO();
     const id = params.id || randomUUID();
 
@@ -131,14 +157,16 @@ export class LocalThreadMessageQueueStore implements IMessageQueueStore {
     ).get(params.threadId) as { next_seq: number };
 
     this.db.prepare(
-      `INSERT INTO lt_thread_message_queue (id, thread_id, tenant_id, assistant_id, workspace_id, project_id, message_content, message_type, sequence_order, priority, command, custom_run_config, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 100, ?, ?, ?)`,
+      `INSERT INTO lt_thread_message_queue (id, thread_id, tenant_id, assistant_id, workspace_id, project_id, message_content, message_type, sequence_order, priority, command, custom_run_config, trusted_run_context, execution_mode, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 100, ?, ?, ?, ?, ?)`,
     ).run(
       id, params.threadId, params.tenantId!, params.assistantId!,
       params.workspaceId ?? null, params.projectId ?? null,
       JSON.stringify(params.content), params.type || "human", seqRow.next_seq,
       params.command ? JSON.stringify(params.command) : null,
       params.custom_run_config ? JSON.stringify(params.custom_run_config) : null,
+      trusted.trustedRunContext ? JSON.stringify(trusted.trustedRunContext) : null,
+      trusted.executionMode ?? null,
       now,
     );
 
@@ -218,6 +246,20 @@ export class LocalThreadMessageQueueStore implements IMessageQueueStore {
   }
 }
 
+function validateQueueTrust(params: AddMessageParams): {
+  trustedRunContext: TrustedRunContext | undefined;
+  executionMode: QueuedExecutionMode | undefined;
+} {
+  return {
+    trustedRunContext: params.trusted_run_context === undefined
+      ? undefined
+      : parseTrustedRunContext(params.trusted_run_context),
+    executionMode: params.execution_mode === undefined
+      ? undefined
+      : parseQueuedExecutionMode(params.execution_mode),
+  };
+}
+
 function scopeClause(scope?: QueueScope): { sql: string; params: unknown[] } {
   if (!scope) return { sql: "", params: [] };
   const entries = (["tenantId", "assistantId", "workspaceId", "projectId"] as const)
@@ -238,5 +280,9 @@ function rowToMessage(row: QueueRow): PendingMessage {
     priority: row.priority || 0,
     command: row.command ? JSON.parse(row.command) : undefined,
     custom_run_config: row.custom_run_config ? JSON.parse(row.custom_run_config) : undefined,
+    trusted_run_context: row.trusted_run_context
+      ? parseTrustedRunContext(JSON.parse(row.trusted_run_context))
+      : undefined,
+    execution_mode: row.execution_mode == null ? undefined : parseQueuedExecutionMode(row.execution_mode),
   };
 }

package/src/stores/project-room-schema.ts

@@ -0,0 +1,243 @@
+import { DatabaseWrapper } from "../database";
+
+const schemaMarker = Symbol("projectRoomSchema");
+type SchemaDatabase = DatabaseWrapper & { [schemaMarker]?: boolean };
+type ColumnRow = { name: unknown; type: unknown; notnull: unknown };
+type IndexRow = { name: unknown; unique: unknown; partial: unknown };
+type IndexColumnRow = { name: unknown };
+const activeTransactions = new WeakSet<DatabaseWrapper>();
+const migrationName = "create_project_room_tables";
+const migrationTableDdl = `CREATE TABLE IF NOT EXISTS lattice_schema_migrations (
+  store_name TEXT NOT NULL, name TEXT NOT NULL, version INTEGER NOT NULL, applied_at TEXT NOT NULL,
+  PRIMARY KEY (store_name, name)
+)`;
+
+const ddl = `
+CREATE TABLE IF NOT EXISTS lt_project_rooms (
+  id TEXT NOT NULL, tenant_id TEXT NOT NULL, workspace_id TEXT NOT NULL, project_id TEXT NOT NULL,
+  type TEXT NOT NULL CHECK (type = 'main'), name TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, id), UNIQUE (tenant_id, project_id, type)
+);
+CREATE TABLE IF NOT EXISTS lt_project_memberships (
+  id TEXT NOT NULL, tenant_id TEXT NOT NULL, project_id TEXT NOT NULL, user_id TEXT NOT NULL,
+  role TEXT NOT NULL CHECK (role IN ('owner','admin','member','viewer')),
+  status TEXT NOT NULL CHECK (status IN ('active','removed')), joined_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, id), UNIQUE (tenant_id, project_id, user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_lt_project_memberships_project ON lt_project_memberships (tenant_id, project_id);
+CREATE TABLE IF NOT EXISTS lt_project_bot_memberships (
+  id TEXT NOT NULL, tenant_id TEXT NOT NULL, workspace_id TEXT NOT NULL, project_id TEXT NOT NULL,
+  room_id TEXT NOT NULL, assistant_id TEXT NOT NULL, role TEXT NOT NULL CHECK (role IN ('coordinator','specialist')),
+  title TEXT NOT NULL, responsibility TEXT, mention_name TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('active','paused','removed')), room_thread_id TEXT NOT NULL,
+  joined_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY (tenant_id, id),
+  UNIQUE (tenant_id, project_id, assistant_id)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_lt_project_bot_memberships_coordinator
+  ON lt_project_bot_memberships (tenant_id, project_id) WHERE role = 'coordinator' AND status IN ('active','paused');
+CREATE UNIQUE INDEX IF NOT EXISTS uq_lt_project_bot_memberships_mention
+  ON lt_project_bot_memberships (tenant_id, room_id, mention_name) WHERE status IN ('active','paused');
+CREATE INDEX IF NOT EXISTS idx_lt_project_bot_memberships_project ON lt_project_bot_memberships (tenant_id, project_id);
+CREATE INDEX IF NOT EXISTS idx_lt_project_bot_memberships_room ON lt_project_bot_memberships (tenant_id, room_id);
+CREATE TABLE IF NOT EXISTS lt_project_room_messages (
+  id TEXT NOT NULL, tenant_id TEXT NOT NULL, workspace_id TEXT NOT NULL, project_id TEXT NOT NULL, room_id TEXT NOT NULL,
+  author TEXT NOT NULL, content TEXT NOT NULL, mentions TEXT NOT NULL DEFAULT '[]', reply_to_message_id TEXT,
+  source TEXT NOT NULL CHECK (source IN ('user','agent','task','routine','system')), source_id TEXT,
+  idempotency_key TEXT, created_at TEXT NOT NULL, PRIMARY KEY (tenant_id, id)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_lt_project_room_messages_idempotency
+  ON lt_project_room_messages (tenant_id, room_id, idempotency_key) WHERE idempotency_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_lt_project_room_messages_room_created
+  ON lt_project_room_messages (tenant_id, room_id, created_at DESC, id DESC);
+`;
+
+const tableColumns: Record<string, string[]> = {
+  lt_project_rooms: ["id", "tenant_id", "workspace_id", "project_id", "type", "name", "created_at", "updated_at"],
+  lt_project_memberships: ["id", "tenant_id", "project_id", "user_id", "role", "status", "joined_at", "updated_at"],
+  lt_project_bot_memberships: ["id", "tenant_id", "workspace_id", "project_id", "room_id", "assistant_id", "role", "title", "responsibility", "mention_name", "status", "room_thread_id", "joined_at", "updated_at"],
+  lt_project_room_messages: ["id", "tenant_id", "workspace_id", "project_id", "room_id", "author", "content", "mentions", "reply_to_message_id", "source", "source_id", "idempotency_key", "created_at"],
+};
+const indexes: Record<string, { table: string; columns: string[]; unique: boolean; partial: boolean; sql?: string[] }> = {
+  idx_lt_project_memberships_project: { table: "lt_project_memberships", columns: ["tenant_id", "project_id"], unique: false, partial: false },
+  uq_lt_project_bot_memberships_coordinator: { table: "lt_project_bot_memberships", columns: ["tenant_id", "project_id"], unique: true, partial: true, sql: ["role = 'coordinator'", "status in ('active','paused')"] },
+  uq_lt_project_bot_memberships_mention: { table: "lt_project_bot_memberships", columns: ["tenant_id", "room_id", "mention_name"], unique: true, partial: true, sql: ["status in ('active','paused')"] },
+  idx_lt_project_bot_memberships_project: { table: "lt_project_bot_memberships", columns: ["tenant_id", "project_id"], unique: false, partial: false },
+  idx_lt_project_bot_memberships_room: { table: "lt_project_bot_memberships", columns: ["tenant_id", "room_id"], unique: false, partial: false },
+  uq_lt_project_room_messages_idempotency: { table: "lt_project_room_messages", columns: ["tenant_id", "room_id", "idempotency_key"], unique: true, partial: true, sql: ["idempotency_key is not null"] },
+  idx_lt_project_room_messages_room_created: { table: "lt_project_room_messages", columns: ["tenant_id", "room_id", "created_at", "id"], unique: false, partial: false, sql: ["created_at desc", "id desc"] },
+};
+const uniqueConstraints: Record<string, string[][]> = {
+  lt_project_rooms: [["tenant_id", "id"], ["tenant_id", "project_id", "type"]],
+  lt_project_memberships: [["tenant_id", "id"], ["tenant_id", "project_id", "user_id"]],
+  lt_project_bot_memberships: [["tenant_id", "id"], ["tenant_id", "project_id", "assistant_id"]],
+  lt_project_room_messages: [["tenant_id", "id"]],
+};
+const checkConstraints: Record<string, Array<{ name: string; fragment: string }>> = {
+  lt_project_rooms: [{ name: "type", fragment: "type='main'" }],
+  lt_project_memberships: [
+    { name: "role", fragment: "role in ('owner','admin','member','viewer')" },
+    { name: "status", fragment: "status in ('active','removed')" },
+  ],
+  lt_project_bot_memberships: [
+    { name: "role", fragment: "role in ('coordinator','specialist')" },
+    { name: "status", fragment: "status in ('active','paused','removed')" },
+  ],
+  lt_project_room_messages: [{ name: "source", fragment: "source in ('user','agent','task','routine','system')" }],
+};
+
+function rows(db: DatabaseWrapper, sql: string): Record<string, unknown>[] {
+  const result = db.getRawDb().exec(sql);
+  if (!result[0]) return [];
+  return result[0].values.map((values) => Object.fromEntries(result[0].columns.map((column, index) => [column, values[index]])));
+}
+
+function normalizeSql(value: string): string {
+  return value.toLowerCase()
+    .replace(/["`]/g, "")
+    .replace(/\[|\]/g, "")
+    .replace(/\s+/g, " ")
+    .replace(/\s*([=,])\s*/g, "$1")
+    .replace(/[()]/g, "")
+    .trim();
+}
+
+function extractCheckExpressions(sql: string): string[] {
+  const checks: string[] = [];
+  let quoted = false;
+  for (let index = 0; index < sql.length; index += 1) {
+    if (sql[index] === "'") {
+      if (quoted && sql[index + 1] === "'") { index += 1; continue; }
+      quoted = !quoted;
+      continue;
+    }
+    if (quoted || sql.slice(index, index + 5).toLowerCase() !== "check") continue;
+    const before = sql[index - 1];
+    const after = sql[index + 5];
+    if ((before && /[a-z0-9_]/i.test(before)) || (after && /[a-z0-9_]/i.test(after))) continue;
+    let opening = index + 5;
+    while (/\s/.test(sql[opening] ?? "")) opening += 1;
+    if (sql[opening] !== "(") continue;
+    let depth = 1;
+    let expressionQuoted = false;
+    for (let cursor = opening + 1; cursor < sql.length; cursor += 1) {
+      if (sql[cursor] === "'") {
+        if (expressionQuoted && sql[cursor + 1] === "'") { cursor += 1; continue; }
+        expressionQuoted = !expressionQuoted;
+      } else if (!expressionQuoted && sql[cursor] === "(") {
+        depth += 1;
+      } else if (!expressionQuoted && sql[cursor] === ")") {
+        depth -= 1;
+        if (depth === 0) {
+          checks.push(sql.slice(opening + 1, cursor));
+          index = cursor;
+          break;
+        }
+      }
+    }
+  }
+  return checks;
+}
+
+/** Validates every table and named index required by project-room version 1. */
+export function validateProjectRoomSchema(db: DatabaseWrapper): void {
+  for (const [table, expected] of Object.entries(tableColumns)) {
+    const actual = rows(db, `PRAGMA table_info(${table})`) as ColumnRow[];
+    if (actual.map((column) => column.name).join(",") !== expected.join(",") || actual.some((column) => column.type !== "TEXT")
+      || actual.some((column) => column.name !== "responsibility" && column.name !== "reply_to_message_id" && column.name !== "source_id" && column.name !== "idempotency_key" && column.notnull !== 1)) {
+      throw new Error(`Invalid project room schema: table '${table}' has incompatible columns`);
+    }
+    const uniqueIndexes = (rows(db, `PRAGMA index_list(${table})`) as IndexRow[]).filter((index) => index.unique === 1);
+    const signatures = uniqueIndexes.map((index) => (rows(db, `PRAGMA index_info(${String(index.name)})`) as IndexColumnRow[]).map((column) => column.name).join(","));
+    if (uniqueConstraints[table].some((constraint) => !signatures.includes(constraint.join(",")))) {
+      throw new Error(`Invalid project room schema: table '${table}' is missing required uniqueness`);
+    }
+    const definition = rows(db, `SELECT sql FROM sqlite_master WHERE type = 'table' AND name = '${table}'`)[0]?.sql;
+    const checks = typeof definition === "string" ? extractCheckExpressions(definition).map(normalizeSql) : [];
+    const missingCheck = checkConstraints[table].find((constraint) => !checks.includes(normalizeSql(constraint.fragment)));
+    if (missingCheck) {
+      throw new Error(`Invalid project room schema: table '${table}' is missing required CHECK constraint '${missingCheck.name}'`);
+    }
+  }
+  for (const [name, expected] of Object.entries(indexes)) {
+    const listed = (rows(db, `PRAGMA index_list(${expected.table})`) as IndexRow[]).find((index) => index.name === name);
+    const columns = (rows(db, `PRAGMA index_info(${name})`) as IndexColumnRow[]).map((column) => column.name);
+    const definition = rows(db, `SELECT sql FROM sqlite_master WHERE type = 'index' AND name = '${name}'`)[0]?.sql;
+    const normalized = typeof definition === "string" ? definition.toLowerCase().replace(/\s+/g, " ") : "";
+    if (!listed || listed.unique !== Number(expected.unique) || listed.partial !== Number(expected.partial)
+      || columns.join(",") !== expected.columns.join(",") || expected.sql?.some((fragment) => !normalized.includes(fragment))) {
+      throw new Error(`Invalid project room schema: index '${name}' is incompatible`);
+    }
+  }
+}
+
+/** Atomically installs and validates project-room migration version 1. */
+export function ensureProjectRoomSchema(db: DatabaseWrapper): void {
+  const marked = db as SchemaDatabase;
+  if (marked[schemaMarker]) return;
+  const raw = db.getRawDb();
+  const hasMigrationTable = rows(db, "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'lattice_schema_migrations'").length > 0;
+  const applied = hasMigrationTable ? rows(db, `SELECT name, version FROM lattice_schema_migrations WHERE store_name = 'project_room' AND name = '${migrationName}'`)[0] : undefined;
+  if (applied) {
+    if (applied.version !== 1) throw new Error(`Invalid project room schema migration version: ${String(applied.version)}`);
+    validateProjectRoomSchema(db);
+    marked[schemaMarker] = true;
+    return;
+  }
+  raw.exec("BEGIN IMMEDIATE");
+  try {
+    raw.exec(migrationTableDdl);
+    raw.exec(ddl);
+    validateProjectRoomSchema(db);
+    raw.run("INSERT INTO lattice_schema_migrations (store_name, name, version, applied_at) VALUES (?, ?, ?, ?)", ["project_room", migrationName, 1, new Date().toISOString()]);
+    raw.exec("COMMIT");
+  } catch (error) {
+    try { raw.exec("ROLLBACK"); } catch { /* preserve the schema failure */ }
+    throw error;
+  }
+  db.save();
+  marked[schemaMarker] = true;
+}
+
+/** Runs synchronous sql.js work atomically. This helper is intentionally non-reentrant. */
+export function transaction<T>(db: DatabaseWrapper, work: () => T): T {
+  if (activeTransactions.has(db)) throw new Error("Nested local store transactions are not supported");
+  activeTransactions.add(db);
+  let began = false;
+  try {
+    db.exec("BEGIN IMMEDIATE");
+    began = true;
+    const result = work();
+    db.exec("COMMIT");
+    db.save();
+    return result;
+  } catch (error) {
+    if (began) {
+      try { db.exec("ROLLBACK"); } catch { /* preserve the original error */ }
+      db.save();
+    }
+    throw error;
+  } finally {
+    activeTransactions.delete(db);
+  }
+}
+
+/** Executes a write without persisting mid-transaction. */
+export function write(db: DatabaseWrapper, sql: string, params: Array<string | number | null>): number {
+  const raw = db.getRawDb();
+  raw.run(sql, params);
+  return raw.getRowsModified();
+}
+
+export function timestamp(previous?: string): string {
+  const previousTime = previous === undefined ? Number.NaN : Date.parse(previous);
+  const now = Date.now();
+  return new Date(Math.max(now, Number.isFinite(previousTime) ? previousTime + 1 : now)).toISOString();
+}
+
+export function validDate(value: unknown): value is Date {
+  return value instanceof Date && !Number.isNaN(value.getTime());
+}
+
+export function isUniqueError(error: unknown): boolean {
+  return error instanceof Error && error.message.includes("UNIQUE constraint failed");
+}

package/src/stores/room-channel-binding-index.ts

@@ -0,0 +1,60 @@
+import {
+  ChannelBindingMigrationConflictError,
+  type ChannelBindingMigrationConflict,
+} from "@axiom-lattice/protocols";
+import type { DatabaseWrapper } from "../database";
+
+const UNIQUE_INDEX_SQL = `CREATE UNIQUE INDEX IF NOT EXISTS idx_lt_cb_subject_unique
+  ON lt_channel_bindings(channel, channel_installation_id, tenant_id, sender_id)`;
+const LOOKUP_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_lt_cb_resolve
+  ON lt_channel_bindings(channel, sender_id, channel_installation_id, tenant_id)`;
+
+/**
+ * Installs global binding-subject uniqueness without silently reconciling legacy rows.
+ *
+ * @param db - Synchronous sql.js database wrapper.
+ * @throws {ChannelBindingMigrationConflictError} When existing subjects require operator repair.
+ */
+export function ensureChannelBindingSubjectIndex(db: DatabaseWrapper): void {
+  db.exec("BEGIN");
+  try {
+    const conflicts = db.prepare(`SELECT tenant_id, channel, channel_installation_id, sender_id, COUNT(*) AS count
+      FROM lt_channel_bindings
+      GROUP BY channel, channel_installation_id, tenant_id, sender_id
+      HAVING COUNT(*) > 1
+      ORDER BY tenant_id, channel, channel_installation_id, sender_id`).all() as ChannelBindingConflictRow[];
+    if (conflicts.length > 0) {
+      throw new ChannelBindingMigrationConflictError(conflicts.map(mapConflict));
+    }
+    db.exec("DROP INDEX IF EXISTS idx_lt_cb_room_subject");
+    db.exec(UNIQUE_INDEX_SQL);
+    db.exec(LOOKUP_INDEX_SQL);
+    db.exec("COMMIT");
+  } catch (error) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // Preserve the migration failure that triggered rollback.
+    }
+    throw error;
+  }
+  db.save();
+}
+
+interface ChannelBindingConflictRow {
+  tenant_id: string;
+  channel: string;
+  channel_installation_id: string;
+  sender_id: string;
+  count: number;
+}
+
+function mapConflict(row: ChannelBindingConflictRow): ChannelBindingMigrationConflict {
+  return {
+    tenantId: row.tenant_id,
+    channel: row.channel,
+    channelInstallationId: row.channel_installation_id,
+    senderId: row.sender_id,
+    count: row.count,
+  };
+}