@axiom-lattice/local-stores 3.1.5 → 3.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/local-stores",
-  "version": "3.1.5",
+  "version": "3.1.8",
   "description": "Local SQLite-based stores for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,8 +25,8 @@
     "@types/sql.js": "^1.4.11",
     "sql.js": "^1.14.1",
     "uuid": "^14.0.1",
-    "@axiom-lattice/core": "4.2.5",
-    "@axiom-lattice/protocols": "4.1.3"
+    "@axiom-lattice/core": "4.2.8",
+    "@axiom-lattice/protocols": "4.2.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/__tests__/LocalMcpServerConfigStore.test.ts

@@ -0,0 +1,77 @@
+// The @axiom-lattice/core barrel cannot load under jest in this package (ESM-only
+// transitive deps), so mock it with the real encryption module — node:crypto only.
+jest.mock("@axiom-lattice/core", () => ({
+  ...jest.requireActual("../../../core/src/util/encryption"),
+}));
+
+import { afterEach, beforeEach, describe, expect, it } from "@jest/globals";
+import { tmpdir } from "os";
+import path from "path";
+
+import { closeDatabase, initDatabase } from "../database";
+import { LocalMcpServerConfigStore } from "../stores/LocalMcpServerConfigStore";
+
+const nextDbPath = (): string => path.join(
+  tmpdir(), `lt-mcp-config-${Date.now()}-${Math.random().toString(36).slice(2)}.db`,
+);
+
+const httpConfig = {
+  name: "remote",
+  version: "1.0.0",
+  transport: "streamable_http" as const,
+  url: "https://mcp.example.com/mcp",
+  headers: { Authorization: "Bearer sk-secret-token" },
+};
+
+describe("LocalMcpServerConfigStore secret handling", () => {
+  let store: LocalMcpServerConfigStore;
+  let db: Awaited<ReturnType<typeof initDatabase>>;
+
+  beforeEach(async () => {
+    db = await initDatabase({ dbPath: nextDbPath() });
+    store = new LocalMcpServerConfigStore(db);
+  });
+  afterEach(() => closeDatabase());
+
+  it("encrypts env and headers at rest and decrypts on read", async () => {
+    await store.createConfig("tenant-1", "cfg-1", {
+      key: "remote",
+      config: { ...httpConfig, env: { MCP_TOKEN: "env-secret" } },
+    });
+
+    const row = db.prepare(
+      "SELECT config, is_env_encrypted FROM lt_mcp_configs WHERE id = ?",
+    ).get("cfg-1") as unknown as { config: string; is_env_encrypted: number };
+    expect(row.is_env_encrypted).toBe(1);
+    const atRest = JSON.parse(row.config);
+    expect(atRest.env.MCP_TOKEN).not.toBe("env-secret");
+    expect(atRest.headers.Authorization).not.toBe("Bearer sk-secret-token");
+
+    const read = await store.getConfigByKey("tenant-1", "remote");
+    expect(read?.config.env?.MCP_TOKEN).toBe("env-secret");
+    expect(read?.config.headers?.Authorization).toBe("Bearer sk-secret-token");
+  });
+
+  it("round-trips configs without secrets and leaves no headers key", async () => {
+    await store.createConfig("tenant-1", "cfg-2", {
+      key: "plain",
+      config: {
+        name: "plain", version: "1.0.0", transport: "stdio",
+        command: "npx", args: ["-y", "@modelcontextprotocol/server-everything"],
+      },
+    });
+    const read = await store.getConfigByKey("tenant-1", "plain");
+    expect(read?.config.headers).toBeUndefined();
+    expect(read?.config.command).toBe("npx");
+    expect(read?.isEnvEncrypted).toBe(false);
+  });
+
+  it("re-encrypts rotated header secrets on update", async () => {
+    await store.createConfig("tenant-1", "cfg-3", { key: "remote", config: httpConfig });
+    await store.updateConfig("tenant-1", "cfg-3", {
+      config: { ...httpConfig, headers: { Authorization: "Bearer rotated-token" } },
+    });
+    const read = await store.getConfigByKey("tenant-1", "remote");
+    expect(read?.config.headers?.Authorization).toBe("Bearer rotated-token");
+  });
+});

package/src/__tests__/LocalProjectRoomReadStateStore.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, it } from "@jest/globals";
+import { existsSync, unlinkSync } from "fs";
+import { tmpdir } from "os";
+import path from "path";
+import { closeDatabase, initDatabase } from "../database";
+import { LocalProjectRoomReadStateStore } from "../stores/LocalProjectRoomReadStateStore";
+
+const nextDbPath = (): string => path.join(tmpdir(), `lt-read-state-${Date.now()}-${Math.random().toString(36).slice(2)}.db`);
+
+describe("LocalProjectRoomReadStateStore", () => {
+  let dbPath: string;
+
+  beforeEach(() => { dbPath = nextDbPath(); });
+  afterEach(() => {
+    closeDatabase();
+    if (existsSync(dbPath)) unlinkSync(dbPath);
+  });
+
+  it("upserts monotonically and isolates scope", async () => {
+    const store = new LocalProjectRoomReadStateStore(await initDatabase({ dbPath }));
+    await expect(store.get("t1", "room-1", "u1")).resolves.toBeNull();
+    await store.markRead({ tenantId: "t1", roomId: "room-1", userId: "u1", lastReadAt: new Date(1000) });
+    await store.markRead({ tenantId: "t1", roomId: "room-1", userId: "u1", lastReadAt: new Date(2000) });
+    await store.markRead({ tenantId: "t1", roomId: "room-1", userId: "u1", lastReadAt: new Date(500) });
+    expect((await store.get("t1", "room-1", "u1"))?.lastReadAt.getTime()).toBe(2000);
+    await expect(store.get("t1", "room-2", "u1")).resolves.toBeNull();
+    await expect(store.get("t2", "room-1", "u1")).resolves.toBeNull();
+    await expect(store.get("t1", "room-1", "u2")).resolves.toBeNull();
+  });
+
+  it("rejects an invalid lastReadAt without writing", async () => {
+    const store = new LocalProjectRoomReadStateStore(await initDatabase({ dbPath }));
+    await expect(store.markRead({ tenantId: "t1", roomId: "room-1", userId: "u1", lastReadAt: new Date(Number.NaN) })).rejects.toBeInstanceOf(RangeError);
+    await expect(store.get("t1", "room-1", "u1")).resolves.toBeNull();
+  });
+
+  it("persists markers across reopen with hydrated dates", async () => {
+    const initial = new LocalProjectRoomReadStateStore(await initDatabase({ dbPath }));
+    const saved = await initial.markRead({ tenantId: "t1", roomId: "room-1", userId: "u1", lastReadAt: new Date(1500) });
+    expect(saved.lastReadAt.getTime()).toBe(1500);
+    expect(saved.updatedAt).toBeInstanceOf(Date);
+    closeDatabase();
+
+    const reopened = new LocalProjectRoomReadStateStore(await initDatabase({ dbPath }));
+    const persisted = await reopened.get("t1", "room-1", "u1");
+    expect(persisted).toEqual(saved);
+    expect(persisted?.lastReadAt).toBeInstanceOf(Date);
+    expect(persisted?.updatedAt).toBeInstanceOf(Date);
+  });
+
+  it("upgrades a version-1 project room database by adding the read-state table", async () => {
+    const db = await initDatabase({ dbPath });
+    db.exec(`CREATE TABLE 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 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 idx_lt_project_memberships_project ON lt_project_memberships (tenant_id, project_id);
+    CREATE TABLE 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 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 uq_lt_project_bot_memberships_mention
+      ON lt_project_bot_memberships (tenant_id, room_id, mention_name) WHERE status IN ('active','paused');
+    CREATE INDEX idx_lt_project_bot_memberships_project ON lt_project_bot_memberships (tenant_id, project_id);
+    CREATE INDEX idx_lt_project_bot_memberships_room ON lt_project_bot_memberships (tenant_id, room_id);
+    CREATE TABLE 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 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 idx_lt_project_room_messages_room_created
+      ON lt_project_room_messages (tenant_id, room_id, created_at DESC, id DESC);
+    CREATE TABLE 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)
+    );`);
+    db.getRawDb().run("INSERT INTO lattice_schema_migrations (store_name, name, version, applied_at) VALUES (?, ?, ?, ?)", ["project_room", "create_project_room_tables", 1, new Date().toISOString()]);
+
+    const store = new LocalProjectRoomReadStateStore(db);
+    await expect(store.get("t1", "room-1", "u1")).resolves.toBeNull();
+    await store.markRead({ tenantId: "t1", roomId: "room-1", userId: "u1", lastReadAt: new Date(1000) });
+    expect((await store.get("t1", "room-1", "u1"))?.lastReadAt.getTime()).toBe(1000);
+    expect(db.prepare("SELECT name, version FROM lattice_schema_migrations WHERE store_name = ? AND name = ?").get("project_room", "create_project_room_read_states")).toMatchObject({ name: "create_project_room_read_states", version: 2 });
+  });
+});

package/src/__tests__/LocalProjectRoomStores.test.ts

@@ -337,6 +337,45 @@ describe("local project room stores", () => {
     await expect(store.list({ tenantId: "t1", roomId: "r1", before: { createdAt: new Date("invalid"), id: "x" }, limit: 1 })).rejects.toBeInstanceOf(RangeError);
   });
 
+  it("counts messages strictly after the horizon with optional human-author exclusion", async () => {
+    const db = await initDatabase({ dbPath });
+    const store = new LocalProjectRoomMessageStore(db);
+    const insert = (id: string, author: string, createdAt: string) => transaction(db, () => {
+      write(db, "INSERT INTO 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) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        [id, "t1", "w1", "p1", "r1", author, '{"type":"text","text":"text"}', "[]", null, "user", null, null, createdAt]);
+    });
+    insert("m1", '{"type":"human","userId":"u1"}', "2026-01-01T00:00:01.000Z");
+    insert("m2", '{"type":"human","userId":"u1"}', "2026-01-01T00:00:02.000Z");
+    insert("m3", '{"type":"human","userId":"u2"}', "2026-01-01T00:00:03.000Z");
+    insert("m4", '{"type":"bot","membershipId":"b1","assistantId":"a1"}', "2026-01-01T00:00:04.000Z");
+    const horizon = new Date("2026-01-01T00:00:01.000Z");
+
+    expect(await store.countAfter({ tenantId: "t1", roomId: "r1", after: horizon })).toBe(3);
+    expect(await store.countAfter({ tenantId: "t1", roomId: "r1", after: new Date("2026-01-01T00:00:04.000Z") })).toBe(0);
+    expect(await store.countAfter({ tenantId: "t1", roomId: "r1", after: new Date(0) })).toBe(4);
+    expect(await store.countAfter({ tenantId: "t1", roomId: "r1", after: horizon, excludeAuthorUserId: "u1" })).toBe(2);
+    expect(await store.countAfter({ tenantId: "t1", roomId: "r1", after: horizon, excludeAuthorUserId: "u2" })).toBe(2);
+    expect(await store.countAfter({ tenantId: "t1", roomId: "r1", after: new Date("2026-01-01T00:00:03.000Z"), excludeAuthorUserId: "u2" })).toBe(1);
+  });
+
+  it("scopes countAfter by tenant and room and rejects invalid horizons", async () => {
+    const db = await initDatabase({ dbPath });
+    const store = new LocalProjectRoomMessageStore(db);
+    const insert = (id: string, tenantId: string, roomId: string, createdAt: string) => transaction(db, () => {
+      write(db, "INSERT INTO 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) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        [id, tenantId, "w1", "p1", roomId, '{"type":"system"}', '{"type":"text","text":"text"}', "[]", null, "system", null, null, createdAt]);
+    });
+    insert("m1", "t1", "r1", "2026-01-01T00:00:01.000Z");
+    insert("m2", "t1", "r2", "2026-01-01T00:00:02.000Z");
+    insert("m3", "t2", "r1", "2026-01-01T00:00:03.000Z");
+
+    expect(await store.countAfter({ tenantId: "t1", roomId: "r1", after: new Date(0) })).toBe(1);
+    expect(await store.countAfter({ tenantId: "t1", roomId: "r2", after: new Date(0) })).toBe(1);
+    expect(await store.countAfter({ tenantId: "t2", roomId: "r1", after: new Date(0) })).toBe(1);
+    expect(await store.countAfter({ tenantId: "t1", roomId: "r1", after: new Date("2026-01-01T00:00:01.000Z") })).toBe(0);
+    await expect(store.countAfter({ tenantId: "t1", roomId: "r1", after: new Date(Number.NaN) })).rejects.toBeInstanceOf(RangeError);
+  });
+
   it("classifies a room message ID collision that occurs after preflight", async () => {
     const db = await initDatabase({ dbPath });
     const store = new LocalProjectRoomMessageStore(db);

package/src/createLocalStoreConfig.ts

@@ -24,6 +24,7 @@ import { LocalProjectRoomStore } from "./stores/LocalProjectRoomStore";
 import { LocalProjectMembershipStore } from "./stores/LocalProjectMembershipStore";
 import { LocalProjectBotMembershipStore } from "./stores/LocalProjectBotMembershipStore";
 import { LocalProjectRoomMessageStore } from "./stores/LocalProjectRoomMessageStore";
+import { LocalProjectRoomReadStateStore } from "./stores/LocalProjectRoomReadStateStore";
 import { LocalUserStore } from "./stores/LocalUserStore";
 import { LocalTenantStore } from "./stores/LocalTenantStore";
 import { LocalUserTenantLinkStore } from "./stores/LocalUserTenantLinkStore";
@@ -74,6 +75,7 @@ export async function createLocalStoreConfig(options: LocalStoreConfigOptions =
     projectMembership: new LocalProjectMembershipStore(db),
     projectBotMembership: new LocalProjectBotMembershipStore(db),
     projectRoomMessage: new LocalProjectRoomMessageStore(db),
+    projectRoomReadState: new LocalProjectRoomReadStateStore(db),
     user: new LocalUserStore(db),
     tenant: new LocalTenantStore(db),
     userTenantLink: new LocalUserTenantLinkStore(db),

package/src/index.ts

@@ -35,6 +35,7 @@ export { LocalProjectRoomStore } from "./stores/LocalProjectRoomStore";
 export { LocalProjectMembershipStore, DuplicateProjectMembershipError, ProjectMembershipIdConflictError } from "./stores/LocalProjectMembershipStore";
 export { LocalProjectBotMembershipStore, ProjectBotMembershipIdConflictError } from "./stores/LocalProjectBotMembershipStore";
 export { LocalProjectRoomMessageStore, ProjectRoomMessageIdConflictError, DuplicateProjectRoomMessageIdempotencyKeyError } from "./stores/LocalProjectRoomMessageStore";
+export { LocalProjectRoomReadStateStore } from "./stores/LocalProjectRoomReadStateStore";
 export { LocalUserStore } from "./stores/LocalUserStore";
 export { LocalTenantStore } from "./stores/LocalTenantStore";
 export { LocalUserTenantLinkStore } from "./stores/LocalUserTenantLinkStore";

package/src/stores/LocalMcpServerConfigStore.ts

@@ -191,6 +191,19 @@ function mapRowToEntry(row: ConfigRow): McpServerConfigEntry {
     }
   }
 
+  if (config.headers && row.is_env_encrypted) {
+    try {
+      const decryptedHeaders: Record<string, string> = {};
+      for (const [key, value] of Object.entries(config.headers)) {
+        decryptedHeaders[key] = decrypt(value);
+      }
+      config.headers = decryptedHeaders;
+    } catch (error) {
+      console.error("Failed to decrypt MCP server headers:", error);
+      throw new Error("Failed to decrypt MCP server configuration");
+    }
+  }
+
   return {
     id: row.id,
     tenantId: row.tenant_id,
@@ -219,5 +232,14 @@ function encryptEnvInConfig(config: McpServerConfig): { config: McpServerConfig;
     isEnvEncrypted = true;
   }
 
+  if (configCopy.headers && Object.keys(configCopy.headers).length > 0) {
+    const encryptedHeaders: Record<string, string> = {};
+    for (const [key, value] of Object.entries(configCopy.headers)) {
+      encryptedHeaders[key] = encrypt(value);
+    }
+    configCopy.headers = encryptedHeaders;
+    isEnvEncrypted = true;
+  }
+
   return { config: configCopy, isEnvEncrypted };
 }

package/src/stores/LocalProjectRoomMessageStore.ts

@@ -40,6 +40,20 @@ export class LocalProjectRoomMessageStore implements ProjectRoomMessageStore {
     return (rows as Row[]).map(mapRow);
   }
   async findById(tenantId: string, id: string): Promise<ProjectRoomMessage | null> { const row = this.byId(tenantId, id); return row ? mapRow(row) : null; }
+  async countAfter(input: {
+    tenantId: string; roomId: string; after: Date; excludeAuthorUserId?: string;
+  }): Promise<number> {
+    if (!validDate(input.after)) throw new RangeError("Project room message count horizon date is invalid");
+    const rows = this.db.prepare(
+      `SELECT author FROM lt_project_room_messages
+       WHERE tenant_id = ? AND room_id = ? AND created_at > ?`,
+    ).all(input.tenantId, input.roomId, input.after.toISOString()) as Array<{ author: string }>;
+    return rows.filter((row) => {
+      if (input.excludeAuthorUserId === undefined) return true;
+      const parsed = parseJson(row.author);
+      return !(record(parsed) && parsed.type === "human" && parsed.userId === input.excludeAuthorUserId);
+    }).length;
+  }
   private insert(input: Omit<ProjectRoomMessage, "createdAt">, idempotent: boolean): ProjectRoomMessage {
     return transaction(this.db, () => {
       if (idempotent && input.idempotencyKey) { const canonical = this.byKey(input.tenantId, input.roomId, input.idempotencyKey); if (canonical) return mapRow(canonical); }

package/src/stores/LocalProjectRoomReadStateStore.ts

@@ -0,0 +1,50 @@
+import type { ProjectRoomReadState, ProjectRoomReadStateStore } from "@axiom-lattice/protocols";
+import type { DatabaseWrapper } from "../database";
+import { ensureProjectRoomSchema, timestamp, transaction, validDate, write } from "./project-room-schema";
+
+type ReadStateRow = { tenant_id: string; room_id: string; user_id: string; last_read_at: string; updated_at: string };
+const columns = "tenant_id, room_id, user_id, last_read_at, updated_at";
+
+function mapRow(row: ReadStateRow): ProjectRoomReadState {
+  const lastReadAt = new Date(row.last_read_at);
+  const updatedAt = new Date(row.updated_at);
+  if (Number.isNaN(lastReadAt.getTime()) || Number.isNaN(updatedAt.getTime())) throw new Error("Invalid project room read state row");
+  return { tenantId: row.tenant_id, roomId: row.room_id, userId: row.user_id, lastReadAt, updatedAt };
+}
+
+/** Persists per-user project room read markers in the local SQLite store. */
+export class LocalProjectRoomReadStateStore implements ProjectRoomReadStateStore {
+  /** Creates a store over a managed local database wrapper. */
+  constructor(private readonly db: DatabaseWrapper) { ensureProjectRoomSchema(db); }
+
+  /** Returns the user's read marker for a room, or null when never reported. */
+  async get(tenantId: string, roomId: string, userId: string): Promise<ProjectRoomReadState | null> {
+    const row = this.byKey(tenantId, roomId, userId);
+    return row ? mapRow(row) : null;
+  }
+
+  /** Upserts the marker monotonically (an older report never regresses the horizon). */
+  async markRead(input: { tenantId: string; roomId: string; userId: string; lastReadAt: Date }): Promise<ProjectRoomReadState> {
+    if (!validDate(input.lastReadAt)) throw new RangeError("Project room read state lastReadAt is invalid");
+    return transaction(this.db, () => {
+      const existing = this.byKey(input.tenantId, input.roomId, input.userId);
+      const lastReadAt = existing !== undefined && new Date(existing.last_read_at).getTime() > input.lastReadAt.getTime()
+        ? new Date(existing.last_read_at)
+        : input.lastReadAt;
+      write(this.db,
+        `INSERT INTO lt_project_room_read_states (${columns})
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT (tenant_id, room_id, user_id) DO UPDATE
+           SET last_read_at = excluded.last_read_at, updated_at = excluded.updated_at`,
+        [input.tenantId, input.roomId, input.userId, lastReadAt.toISOString(), timestamp()]);
+      const row = this.byKey(input.tenantId, input.roomId, input.userId) as ReadStateRow;
+      return mapRow(row);
+    });
+  }
+
+  private byKey(tenantId: string, roomId: string, userId: string): ReadStateRow | undefined {
+    return this.db.prepare(
+      `SELECT ${columns} FROM lt_project_room_read_states WHERE tenant_id = ? AND room_id = ? AND user_id = ?`,
+    ).get(tenantId, roomId, userId) as ReadStateRow | undefined;
+  }
+}

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

@@ -49,6 +49,13 @@ 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);
+CREATE TABLE IF NOT EXISTS lt_project_room_read_states (
+  tenant_id TEXT NOT NULL, room_id TEXT NOT NULL, user_id TEXT NOT NULL,
+  last_read_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, room_id, user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_lt_project_room_read_states_user
+  ON lt_project_room_read_states (tenant_id, user_id);
 `;
 
 const tableColumns: Record<string, string[]> = {
@@ -56,6 +63,7 @@ const tableColumns: Record<string, string[]> = {
   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"],
+  lt_project_room_read_states: ["tenant_id", "room_id", "user_id", "last_read_at", "updated_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 },
@@ -65,12 +73,14 @@ const indexes: Record<string, { table: string; columns: string[]; unique: boolea
   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"] },
+  idx_lt_project_room_read_states_user: { table: "lt_project_room_read_states", columns: ["tenant_id", "user_id"], unique: false, partial: false },
 };
 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"]],
+  lt_project_room_read_states: [["tenant_id", "room_id", "user_id"]],
 };
 const checkConstraints: Record<string, Array<{ name: string; fragment: string }>> = {
   lt_project_rooms: [{ name: "type", fragment: "type='main'" }],
@@ -83,6 +93,7 @@ const checkConstraints: Record<string, Array<{ name: string; fragment: string }>
     { name: "status", fragment: "status in ('active','paused','removed')" },
   ],
   lt_project_room_messages: [{ name: "source", fragment: "source in ('user','agent','task','routine','system')" }],
+  lt_project_room_read_states: [],
 };
 
 function rows(db: DatabaseWrapper, sql: string): Record<string, unknown>[] {
@@ -179,6 +190,25 @@ export function ensureProjectRoomSchema(db: DatabaseWrapper): void {
   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)}`);
+    const hasReadStates = rows(db, "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'lt_project_room_read_states'").length > 0;
+    if (!hasReadStates) {
+      raw.exec("BEGIN IMMEDIATE");
+      try {
+        raw.exec(`CREATE TABLE IF NOT EXISTS lt_project_room_read_states (
+          tenant_id TEXT NOT NULL, room_id TEXT NOT NULL, user_id TEXT NOT NULL,
+          last_read_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+          PRIMARY KEY (tenant_id, room_id, user_id)
+        ); CREATE INDEX IF NOT EXISTS idx_lt_project_room_read_states_user
+          ON lt_project_room_read_states (tenant_id, user_id);`);
+        raw.run("INSERT INTO lattice_schema_migrations (store_name, name, version, applied_at) VALUES (?, ?, ?, ?)",
+          ["project_room", "create_project_room_read_states", 2, new Date().toISOString()]);
+        raw.exec("COMMIT");
+        db.save();
+      } catch (error) {
+        try { raw.exec("ROLLBACK"); } catch { /* preserve the schema failure */ }
+        throw error;
+      }
+    }
     validateProjectRoomSchema(db);
     marked[schemaMarker] = true;
     return;