@axiom-lattice/local-stores 3.1.1 → 3.1.2

package/src/stores/LocalProjectBotMembershipStore.ts

@@ -0,0 +1,105 @@
+import type { ProjectBotMembership, ProjectBotMembershipStatus, ProjectBotMembershipStore, ProjectBotRole } from "@axiom-lattice/protocols";
+import { DatabaseWrapper } from "../database";
+import { ensureProjectRoomSchema, isUniqueError, timestamp, transaction, validDate, write } from "./project-room-schema";
+
+type Row = { id: unknown; tenant_id: unknown; workspace_id: unknown; project_id: unknown; room_id: unknown; assistant_id: unknown; role: unknown; title: unknown; responsibility: unknown; mention_name: unknown; status: unknown; room_thread_id: unknown; joined_at: unknown; updated_at: unknown };
+type Conflict = "coordinator_conflict" | "mention_conflict";
+const columns = "id, tenant_id, workspace_id, project_id, room_id, assistant_id, role, title, responsibility, mention_name, status, room_thread_id, joined_at, updated_at";
+
+export class ProjectBotMembershipIdConflictError extends Error { constructor(tenantId: string, id: string) { super(`Project bot membership ID '${id}' already exists in tenant '${tenantId}'`); this.name = "ProjectBotMembershipIdConflictError"; } }
+function isRole(value: unknown): value is ProjectBotRole { return value === "coordinator" || value === "specialist"; }
+function isStatus(value: unknown): value is ProjectBotMembershipStatus { return value === "active" || value === "paused" || value === "removed"; }
+function mapRow(row: Row): ProjectBotMembership {
+  const joinedAt = typeof row.joined_at === "string" ? new Date(row.joined_at) : undefined;
+  const updatedAt = typeof row.updated_at === "string" ? new Date(row.updated_at) : undefined;
+  if (typeof row.id !== "string" || typeof row.tenant_id !== "string" || typeof row.workspace_id !== "string"
+    || typeof row.project_id !== "string" || typeof row.room_id !== "string" || typeof row.assistant_id !== "string"
+    || !isRole(row.role) || typeof row.title !== "string" || (row.responsibility !== null && typeof row.responsibility !== "string")
+    || typeof row.mention_name !== "string" || !isStatus(row.status) || typeof row.room_thread_id !== "string"
+    || !validDate(joinedAt) || !validDate(updatedAt)) throw new Error("Invalid project bot membership row");
+  return { id: row.id, tenantId: row.tenant_id, workspaceId: row.workspace_id, projectId: row.project_id,
+    roomId: row.room_id, assistantId: row.assistant_id, role: row.role, title: row.title,
+    ...(row.responsibility === null ? {} : { responsibility: row.responsibility }), mentionName: row.mention_name,
+    status: row.status, roomThreadId: row.room_thread_id, joinedAt, updatedAt };
+}
+
+/** Persists durable project bot roster memberships in local SQLite. */
+export class LocalProjectBotMembershipStore implements ProjectBotMembershipStore {
+  constructor(private readonly db: DatabaseWrapper) { ensureProjectRoomSchema(db); }
+  async list(tenantId: string, projectId: string): Promise<ProjectBotMembership[]> { return (this.db.prepare(`SELECT ${columns} FROM lt_project_bot_memberships WHERE tenant_id = ? AND project_id = ? ORDER BY joined_at ASC, id ASC`).all(tenantId, projectId) as Row[]).map(mapRow); }
+  async findById(tenantId: string, id: string): Promise<ProjectBotMembership | null> { const row = this.byId(tenantId, id); return row ? mapRow(row) : null; }
+  async findByAssistant(tenantId: string, projectId: string, assistantId: string): Promise<ProjectBotMembership | null> { const row = this.db.prepare(`SELECT ${columns} FROM lt_project_bot_memberships WHERE tenant_id = ? AND project_id = ? AND assistant_id = ?`).get(tenantId, projectId, assistantId) as Row | undefined; return row ? mapRow(row) : null; }
+  async save(input: Omit<ProjectBotMembership, "joinedAt" | "updatedAt">): Promise<{ kind: "created" | "updated" | "reactivated"; membership: ProjectBotMembership } | { kind: Conflict }> {
+    try {
+      return transaction(this.db, () => {
+        const existing = this.db.prepare(`SELECT ${columns} FROM lt_project_bot_memberships WHERE tenant_id = ? AND project_id = ? AND assistant_id = ?`).get(input.tenantId, input.projectId, input.assistantId) as Row | undefined;
+        if (existing) return this.reactivate(existing, input);
+        if (this.byId(input.tenantId, input.id)) throw new ProjectBotMembershipIdConflictError(input.tenantId, input.id);
+        const conflict = this.preflight(input.tenantId, input.projectId, input.roomId, input.role, input.mentionName, input.status, input.id);
+        if (conflict) return { kind: conflict };
+        const now = timestamp();
+        try { write(this.db, "INSERT INTO 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) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [input.id, input.tenantId, input.workspaceId, input.projectId, input.roomId, input.assistantId, input.role, input.title, input.responsibility ?? null, input.mentionName, input.status, input.roomThreadId, now, now]); }
+        catch (error) {
+          if (!isUniqueError(error)) throw error;
+          if (this.byId(input.tenantId, input.id)) throw new ProjectBotMembershipIdConflictError(input.tenantId, input.id);
+          const raced = this.byAssistant(input.tenantId, input.projectId, input.assistantId);
+          if (raced) return this.reactivate(raced, input);
+          const racedConflict = this.preflight(input.tenantId, input.projectId, input.roomId, input.role, input.mentionName, input.status, input.id);
+          if (racedConflict) return { kind: racedConflict };
+          throw new Error("Unclassified project bot membership uniqueness conflict");
+        }
+        return { kind: "created", membership: mapRow(this.byId(input.tenantId, input.id) as Row) };
+      });
+    } catch (error) { const conflict = this.conflict(error); if (conflict) return { kind: conflict }; throw error; }
+  }
+  async update(input: { tenantId: string; id: string; patch: Partial<Pick<ProjectBotMembership, "role" | "title" | "responsibility" | "mentionName" | "status">>; expectedUpdatedAt: Date }): Promise<{ kind: "updated"; membership: ProjectBotMembership } | { kind: "not_found" | "conflict" | Conflict }> {
+    try {
+      return transaction(this.db, () => {
+        const row = this.byId(input.tenantId, input.id); if (!row) return { kind: "not_found" as const };
+        const existing = mapRow(row);
+        if (!validDate(input.expectedUpdatedAt) || existing.updatedAt.getTime() !== input.expectedUpdatedAt.getTime()) return { kind: "conflict" as const };
+        const candidate = { ...existing, ...input.patch };
+        const conflict = this.preflight(candidate.tenantId, candidate.projectId, candidate.roomId, candidate.role, candidate.mentionName, candidate.status, candidate.id);
+        if (conflict) return { kind: conflict };
+        let changes: number;
+        try { changes = write(this.db, "UPDATE lt_project_bot_memberships SET role = ?, title = ?, responsibility = ?, mention_name = ?, status = ?, updated_at = ? WHERE tenant_id = ? AND id = ? AND updated_at = ?", [candidate.role, candidate.title, candidate.responsibility ?? null, candidate.mentionName, candidate.status, timestamp(row.updated_at as string), input.tenantId, input.id, row.updated_at as string]); }
+        catch (error) {
+          if (!isUniqueError(error)) throw error;
+          const racedConflict = this.preflight(candidate.tenantId, candidate.projectId, candidate.roomId, candidate.role, candidate.mentionName, candidate.status, candidate.id);
+          if (racedConflict) return { kind: racedConflict };
+          throw new Error("Unclassified project bot membership uniqueness conflict");
+        }
+        if (changes === 0) return { kind: "conflict" as const };
+        return { kind: "updated" as const, membership: mapRow(this.byId(input.tenantId, input.id) as Row) };
+      });
+    } catch (error) { const conflict = this.conflict(error); if (conflict) return { kind: conflict }; throw error; }
+  }
+  private byId(tenantId: string, id: string): Row | undefined { return this.db.prepare(`SELECT ${columns} FROM lt_project_bot_memberships WHERE tenant_id = ? AND id = ?`).get(tenantId, id) as Row | undefined; }
+  private byAssistant(tenantId: string, projectId: string, assistantId: string): Row | undefined { return this.db.prepare(`SELECT ${columns} FROM lt_project_bot_memberships WHERE tenant_id = ? AND project_id = ? AND assistant_id = ?`).get(tenantId, projectId, assistantId) as Row | undefined; }
+  private reactivate(existing: Row, input: Omit<ProjectBotMembership, "joinedAt" | "updatedAt">): { kind: "updated" | "reactivated"; membership: ProjectBotMembership } | { kind: Conflict } {
+    const persisted = mapRow(existing);
+    const wasRemoved = persisted.status === "removed";
+    const conflict = this.preflight(input.tenantId, input.projectId, persisted.roomId, input.role, input.mentionName, "active", persisted.id);
+    if (conflict) return { kind: conflict };
+    try { write(this.db, "UPDATE lt_project_bot_memberships SET role = ?, title = ?, responsibility = ?, mention_name = ?, status = 'active', updated_at = ? WHERE tenant_id = ? AND id = ?", [input.role, input.title, input.responsibility ?? null, input.mentionName, timestamp(existing.updated_at as string), input.tenantId, persisted.id]); }
+    catch (error) {
+      if (!isUniqueError(error)) throw error;
+      const racedConflict = this.preflight(input.tenantId, input.projectId, persisted.roomId, input.role, input.mentionName, "active", persisted.id);
+      if (racedConflict) return { kind: racedConflict };
+      throw new Error("Unclassified project bot membership uniqueness conflict");
+    }
+    return { kind: wasRemoved ? "reactivated" : "updated", membership: mapRow(this.byId(input.tenantId, persisted.id) as Row) };
+  }
+  private preflight(tenantId: string, projectId: string, roomId: string, role: ProjectBotRole, mentionName: string, status: ProjectBotMembershipStatus, excludeId: string): Conflict | undefined {
+    if (status === "removed") return undefined;
+    if (role === "coordinator" && this.db.prepare("SELECT 1 FROM lt_project_bot_memberships WHERE tenant_id = ? AND project_id = ? AND id <> ? AND role = 'coordinator' AND status IN ('active', 'paused')").get(tenantId, projectId, excludeId)) return "coordinator_conflict";
+    if (this.db.prepare("SELECT 1 FROM lt_project_bot_memberships WHERE tenant_id = ? AND room_id = ? AND mention_name = ? AND id <> ? AND status IN ('active', 'paused')").get(tenantId, roomId, mentionName, excludeId)) return "mention_conflict";
+    return undefined;
+  }
+  private conflict(error: unknown): Conflict | undefined {
+    if (!isUniqueError(error) || !(error instanceof Error)) return undefined;
+    if (error.message.includes("tenant_id, lt_project_bot_memberships.project_id")) return "coordinator_conflict";
+    if (error.message.includes("room_id") && error.message.includes("mention_name")) return "mention_conflict";
+    return undefined;
+  }
+}

package/src/stores/LocalProjectMembershipStore.ts

@@ -0,0 +1,72 @@
+import type { ProjectHumanRole, ProjectMembership, ProjectMembershipMutationResult, ProjectMembershipStore } from "@axiom-lattice/protocols";
+import { DatabaseWrapper } from "../database";
+import { ensureProjectRoomSchema, isUniqueError, timestamp, transaction, validDate, write } from "./project-room-schema";
+
+type Row = { id: unknown; tenant_id: unknown; project_id: unknown; user_id: unknown; role: unknown; status: unknown; joined_at: unknown; updated_at: unknown };
+const columns = "id, tenant_id, project_id, user_id, role, status, joined_at, updated_at";
+
+export class DuplicateProjectMembershipError extends Error { constructor() { super("Project membership already exists for tenant, project, and user"); this.name = "DuplicateProjectMembershipError"; } }
+export class ProjectMembershipIdConflictError extends Error { constructor() { super("Project membership ID already exists for tenant"); this.name = "ProjectMembershipIdConflictError"; } }
+function role(value: unknown): value is ProjectHumanRole { return value === "owner" || value === "admin" || value === "member" || value === "viewer"; }
+function mapRow(row: Row): ProjectMembership {
+  const joinedAt = typeof row.joined_at === "string" ? new Date(row.joined_at) : undefined;
+  const updatedAt = typeof row.updated_at === "string" ? new Date(row.updated_at) : undefined;
+  if (typeof row.id !== "string" || typeof row.tenant_id !== "string" || typeof row.project_id !== "string"
+    || typeof row.user_id !== "string" || !role(row.role) || (row.status !== "active" && row.status !== "removed")
+    || !validDate(joinedAt) || !validDate(updatedAt)) throw new Error("Invalid project membership row");
+  return { id: row.id, tenantId: row.tenant_id, projectId: row.project_id, userId: row.user_id,
+    role: row.role, status: row.status, joinedAt, updatedAt };
+}
+
+/** Persists human project memberships in local SQLite. */
+export class LocalProjectMembershipStore implements ProjectMembershipStore {
+  constructor(private readonly db: DatabaseWrapper) { ensureProjectRoomSchema(db); }
+  async list(tenantId: string, projectId: string): Promise<ProjectMembership[]> { return (this.db.prepare(`SELECT ${columns} FROM lt_project_memberships WHERE tenant_id = ? AND project_id = ? ORDER BY joined_at ASC, id ASC`).all(tenantId, projectId) as Row[]).map(mapRow); }
+  async findByUser(tenantId: string, projectId: string, userId: string): Promise<ProjectMembership | null> { const row = this.db.prepare(`SELECT ${columns} FROM lt_project_memberships WHERE tenant_id = ? AND project_id = ? AND user_id = ?`).get(tenantId, projectId, userId) as Row | undefined; return row ? mapRow(row) : null; }
+  async create(input: Omit<ProjectMembership, "joinedAt" | "updatedAt">): Promise<ProjectMembership> {
+    return transaction(this.db, () => {
+      if (this.byId(input.tenantId, input.id)) throw new ProjectMembershipIdConflictError();
+      const now = timestamp();
+      try { write(this.db, "INSERT INTO lt_project_memberships (id, tenant_id, project_id, user_id, role, status, joined_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [input.id, input.tenantId, input.projectId, input.userId, input.role, input.status, now, now]); }
+      catch (error) { if (isUniqueError(error)) throw this.classifyUnique(input.tenantId, input.id, input.projectId, input.userId); throw error; }
+      return mapRow(this.byId(input.tenantId, input.id) as Row);
+    });
+  }
+  async createInitialOwner(input: Omit<ProjectMembership, "role" | "status" | "joinedAt" | "updatedAt">): Promise<{ kind: "created" | "existing"; membership: ProjectMembership } | { kind: "already_initialized" }> {
+    return transaction(this.db, () => {
+      const rows = this.db.prepare(`SELECT ${columns} FROM lt_project_memberships WHERE tenant_id = ? AND project_id = ?`).all(input.tenantId, input.projectId) as Row[];
+      if (rows.length > 0) { const existing = rows.map(mapRow).find((item) => item.userId === input.userId && item.role === "owner" && item.status === "active"); return existing ? { kind: "existing", membership: existing } : { kind: "already_initialized" }; }
+      if (this.byId(input.tenantId, input.id)) throw new ProjectMembershipIdConflictError();
+      const now = timestamp();
+      try { write(this.db, "INSERT INTO lt_project_memberships (id, tenant_id, project_id, user_id, role, status, joined_at, updated_at) VALUES (?, ?, ?, ?, 'owner', 'active', ?, ?)", [input.id, input.tenantId, input.projectId, input.userId, now, now]); }
+      catch (error) { if (isUniqueError(error)) throw this.classifyUnique(input.tenantId, input.id, input.projectId, input.userId); throw error; }
+      return { kind: "created", membership: mapRow(this.byId(input.tenantId, input.id) as Row) };
+    });
+  }
+  async updateRole(input: { tenantId: string; id: string; role: ProjectHumanRole; expectedUpdatedAt: Date }): Promise<ProjectMembershipMutationResult> { return this.mutate(input.tenantId, input.id, input.expectedUpdatedAt, input.role, false); }
+  async remove(input: { tenantId: string; id: string; expectedUpdatedAt: Date }): Promise<ProjectMembershipMutationResult> { return this.mutate(input.tenantId, input.id, input.expectedUpdatedAt, undefined, true); }
+  private mutate(tenantId: string, id: string, expected: Date, nextRole: ProjectHumanRole, remove: false): ProjectMembershipMutationResult;
+  private mutate(tenantId: string, id: string, expected: Date, nextRole: undefined, remove: true): ProjectMembershipMutationResult;
+  private mutate(tenantId: string, id: string, expected: Date, nextRole: ProjectHumanRole | undefined, remove: boolean): ProjectMembershipMutationResult {
+    return transaction(this.db, () => {
+      const row = this.byId(tenantId, id); if (!row) return { kind: "not_found" };
+      const current = mapRow(row); if (!validDate(expected) || current.updatedAt.getTime() !== expected.getTime()) return { kind: "conflict" };
+      if (current.role === "owner" && current.status === "active" && (remove || nextRole !== "owner")) {
+        const other = this.db.prepare("SELECT 1 FROM lt_project_memberships WHERE tenant_id = ? AND project_id = ? AND id <> ? AND role = 'owner' AND status = 'active'").get(tenantId, current.projectId, id);
+        if (!other) return { kind: "last_owner" };
+      }
+      const updatedAt = timestamp(row.updated_at as string);
+      const changes = remove
+        ? write(this.db, "UPDATE lt_project_memberships SET status = 'removed', updated_at = ? WHERE tenant_id = ? AND id = ? AND updated_at = ?", [updatedAt, tenantId, id, row.updated_at as string])
+        : write(this.db, "UPDATE lt_project_memberships SET role = ?, updated_at = ? WHERE tenant_id = ? AND id = ? AND updated_at = ?", [nextRole as ProjectHumanRole, updatedAt, tenantId, id, row.updated_at as string]);
+      if (changes === 0) return { kind: "conflict" };
+      return { kind: remove ? "removed" : "updated", membership: mapRow(this.byId(tenantId, id) as Row) };
+    });
+  }
+  private byId(tenantId: string, id: string): Row | undefined { return this.db.prepare(`SELECT ${columns} FROM lt_project_memberships WHERE tenant_id = ? AND id = ?`).get(tenantId, id) as Row | undefined; }
+  private classifyUnique(tenantId: string, id: string, projectId: string, userId: string): Error {
+    if (this.byId(tenantId, id)) return new ProjectMembershipIdConflictError();
+    if (this.db.prepare("SELECT 1 FROM lt_project_memberships WHERE tenant_id = ? AND project_id = ? AND user_id = ?").get(tenantId, projectId, userId)) return new DuplicateProjectMembershipError();
+    return new Error("Unclassified project membership uniqueness conflict");
+  }
+}

package/src/stores/LocalProjectRoomMessageStore.ts

@@ -0,0 +1,63 @@
+import type { ProjectRoomMention, ProjectRoomMessage, ProjectRoomMessageAuthor, ProjectRoomMessageSource, ProjectRoomMessageStore } from "@axiom-lattice/protocols";
+import { DatabaseWrapper } from "../database";
+import { ensureProjectRoomSchema, isUniqueError, timestamp, transaction, validDate, write } from "./project-room-schema";
+
+type Row = { id: unknown; tenant_id: unknown; workspace_id: unknown; project_id: unknown; room_id: unknown; author: unknown; content: unknown; mentions: unknown; reply_to_message_id: unknown; source: unknown; source_id: unknown; idempotency_key: unknown; created_at: unknown };
+const columns = "id, tenant_id, workspace_id, project_id, room_id, author, content, mentions, reply_to_message_id, source, source_id, idempotency_key, created_at";
+export class ProjectRoomMessageIdConflictError extends Error { constructor(tenantId: string, id: string) { super(`Project room message ID '${id}' already exists in tenant '${tenantId}'`); this.name = "ProjectRoomMessageIdConflictError"; } }
+export class DuplicateProjectRoomMessageIdempotencyKeyError extends Error { constructor(tenantId: string, roomId: string, key: string) { super(`Project room message idempotency key '${key}' already exists in tenant '${tenantId}' room '${roomId}'`); this.name = "DuplicateProjectRoomMessageIdempotencyKeyError"; } }
+function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function only(value: Record<string, unknown>, keys: string[]): boolean { return Object.keys(value).every((key) => keys.includes(key)); }
+function parseJson(value: unknown): unknown { if (typeof value !== "string") return undefined; try { return JSON.parse(value) as unknown; } catch { return undefined; } }
+function author(value: unknown): ProjectRoomMessageAuthor | undefined { if (!record(value)) return undefined; if (value.type === "human" && only(value, ["type", "userId"]) && typeof value.userId === "string") return { type: "human", userId: value.userId }; if (value.type === "bot" && only(value, ["type", "membershipId", "assistantId"]) && typeof value.membershipId === "string" && typeof value.assistantId === "string") return { type: "bot", membershipId: value.membershipId, assistantId: value.assistantId }; if (value.type === "system" && only(value, ["type"])) return { type: "system" }; return undefined; }
+function mention(value: unknown): ProjectRoomMention | undefined { if (!record(value)) return undefined; if (value.type === "bot" && only(value, ["type", "membershipId"]) && typeof value.membershipId === "string") return { type: "bot", membershipId: value.membershipId }; if (value.type === "team" && only(value, ["type"])) return { type: "team" }; return undefined; }
+function source(value: unknown): value is ProjectRoomMessageSource { return value === "user" || value === "agent" || value === "task" || value === "routine" || value === "system"; }
+function mapRow(row: Row): ProjectRoomMessage {
+  const mappedAuthor = author(parseJson(row.author)); const content = parseJson(row.content); const rawMentions = parseJson(row.mentions);
+  const mappedMentions = Array.isArray(rawMentions) ? rawMentions.map(mention) : undefined;
+  const createdAt = typeof row.created_at === "string" ? new Date(row.created_at) : undefined;
+  if (typeof row.id !== "string" || typeof row.tenant_id !== "string" || typeof row.workspace_id !== "string" || typeof row.project_id !== "string" || typeof row.room_id !== "string" || !mappedAuthor
+    || !record(content) || content.type !== "text" || typeof content.text !== "string" || !only(content, ["type", "text"])
+    || !mappedMentions || mappedMentions.some((item) => item === undefined) || (row.reply_to_message_id !== null && typeof row.reply_to_message_id !== "string")
+    || !source(row.source) || (row.source_id !== null && typeof row.source_id !== "string") || (row.idempotency_key !== null && typeof row.idempotency_key !== "string") || !validDate(createdAt)) throw new Error("Invalid project room message row");
+  return { id: row.id, tenantId: row.tenant_id, workspaceId: row.workspace_id, projectId: row.project_id, roomId: row.room_id,
+    author: mappedAuthor, content: { type: "text", text: content.text }, mentions: mappedMentions as ProjectRoomMention[],
+    ...(row.reply_to_message_id === null ? {} : { replyToMessageId: row.reply_to_message_id }), source: row.source,
+    ...(row.source_id === null ? {} : { sourceId: row.source_id }), ...(row.idempotency_key === null ? {} : { idempotencyKey: row.idempotency_key }), createdAt };
+}
+
+/** Persists validated project room messages in local SQLite. */
+export class LocalProjectRoomMessageStore implements ProjectRoomMessageStore {
+  constructor(private readonly db: DatabaseWrapper) { ensureProjectRoomSchema(db); }
+  async create(input: Omit<ProjectRoomMessage, "createdAt">): Promise<ProjectRoomMessage> { return this.insert(input, false); }
+  async createIdempotent(input: Omit<ProjectRoomMessage, "createdAt"> & { idempotencyKey: string }): Promise<ProjectRoomMessage> { return this.insert(input, true); }
+  async list(input: { tenantId: string; roomId: string; before?: { createdAt: Date; id: string }; limit: number }): Promise<ProjectRoomMessage[]> {
+    if (input.before && !validDate(input.before.createdAt)) throw new RangeError("Project room message cursor date is invalid");
+    const limit = Math.min(100, Math.max(1, Math.trunc(Number.isFinite(input.limit) ? input.limit : 1)));
+    const rows = input.before
+      ? this.db.prepare(`SELECT ${columns} FROM lt_project_room_messages WHERE tenant_id = ? AND room_id = ? AND (created_at < ? OR (created_at = ? AND id < ?)) ORDER BY created_at DESC, id DESC LIMIT ?`).all(input.tenantId, input.roomId, input.before.createdAt.toISOString(), input.before.createdAt.toISOString(), input.before.id, limit)
+      : this.db.prepare(`SELECT ${columns} FROM lt_project_room_messages WHERE tenant_id = ? AND room_id = ? ORDER BY created_at DESC, id DESC LIMIT ?`).all(input.tenantId, input.roomId, limit);
+    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; }
+  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); }
+      if (this.byId(input.tenantId, input.id)) throw new ProjectRoomMessageIdConflictError(input.tenantId, input.id);
+      try { write(this.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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [input.id, input.tenantId, input.workspaceId, input.projectId, input.roomId, JSON.stringify(input.author), JSON.stringify(input.content), JSON.stringify(input.mentions), input.replyToMessageId ?? null, input.source, input.sourceId ?? null, input.idempotencyKey ?? null, timestamp()]); }
+      catch (error) {
+        if (!isUniqueError(error)) throw error;
+        if (this.byId(input.tenantId, input.id)) throw new ProjectRoomMessageIdConflictError(input.tenantId, input.id);
+        if (input.idempotencyKey) {
+          const canonical = this.byKey(input.tenantId, input.roomId, input.idempotencyKey);
+          if (canonical && idempotent) return mapRow(canonical);
+          if (canonical) throw new DuplicateProjectRoomMessageIdempotencyKeyError(input.tenantId, input.roomId, input.idempotencyKey);
+        }
+        throw new Error("Unclassified project room message uniqueness conflict");
+      }
+      return mapRow(this.byId(input.tenantId, input.id) as Row);
+    });
+  }
+  private byId(tenantId: string, id: string): Row | undefined { return this.db.prepare(`SELECT ${columns} FROM lt_project_room_messages WHERE tenant_id = ? AND id = ?`).get(tenantId, id) as Row | undefined; }
+  private byKey(tenantId: string, roomId: string, key: string): Row | undefined { return this.db.prepare(`SELECT ${columns} FROM lt_project_room_messages WHERE tenant_id = ? AND room_id = ? AND idempotency_key = ?`).get(tenantId, roomId, key) as Row | undefined; }
+}

package/src/stores/LocalProjectRoomStore.ts

@@ -0,0 +1,37 @@
+import type { ProjectRoom, ProjectRoomStore } from "@axiom-lattice/protocols";
+import { DatabaseWrapper } from "../database";
+import { ensureProjectRoomSchema, timestamp, transaction, validDate, write } from "./project-room-schema";
+
+type Row = { id: unknown; tenant_id: unknown; workspace_id: unknown; project_id: unknown; type: unknown; name: unknown; created_at: unknown; updated_at: unknown };
+const columns = "id, tenant_id, workspace_id, project_id, type, name, created_at, updated_at";
+
+function mapRow(row: Row): ProjectRoom {
+  const createdAt = typeof row.created_at === "string" ? new Date(row.created_at) : undefined;
+  const updatedAt = typeof row.updated_at === "string" ? new Date(row.updated_at) : undefined;
+  if (typeof row.id !== "string" || typeof row.tenant_id !== "string" || typeof row.workspace_id !== "string"
+    || typeof row.project_id !== "string" || row.type !== "main" || typeof row.name !== "string"
+    || !validDate(createdAt) || !validDate(updatedAt)) throw new Error("Invalid project room row");
+  return { id: row.id, tenantId: row.tenant_id, workspaceId: row.workspace_id, projectId: row.project_id,
+    type: "main", name: row.name, createdAt, updatedAt };
+}
+
+/** Persists canonical project main rooms in local SQLite. */
+export class LocalProjectRoomStore implements ProjectRoomStore {
+  constructor(private readonly db: DatabaseWrapper) { ensureProjectRoomSchema(db); }
+  async ensureMainRoom(input: { id: string; tenantId: string; workspaceId: string; projectId: string; name: string }): Promise<ProjectRoom> {
+    return transaction(this.db, () => {
+      const existing = this.getRow(input.tenantId, input.projectId);
+      if (existing) return mapRow(existing);
+      const now = timestamp();
+      write(this.db, "INSERT INTO lt_project_rooms (id, tenant_id, workspace_id, project_id, type, name, created_at, updated_at) VALUES (?, ?, ?, ?, 'main', ?, ?, ?)", [input.id, input.tenantId, input.workspaceId, input.projectId, input.name, now, now]);
+      return mapRow(this.getRow(input.tenantId, input.projectId) as Row);
+    });
+  }
+  async getMainRoom(tenantId: string, projectId: string): Promise<ProjectRoom | null> {
+    const row = this.getRow(tenantId, projectId);
+    return row ? mapRow(row) : null;
+  }
+  private getRow(tenantId: string, projectId: string): Row | undefined {
+    return this.db.prepare(`SELECT ${columns} FROM lt_project_rooms WHERE tenant_id = ? AND project_id = ? AND type = 'main'`).get(tenantId, projectId) as Row | undefined;
+  }
+}

package/src/stores/LocalTaskStore.ts

@@ -10,11 +10,16 @@ import type {
   CreateTaskRequest,
   UpdateTaskRequest,
   TaskListFilter,
+  TaskDependentListQuery,
+  TaskMutationSnapshot,
 } from "@axiom-lattice/protocols";
 import { ensureTable, nowISO, parseISO } from "../database";
 import { randomUUID } from "crypto";
 
 const MAX_CANONICAL_TASK_TIME = "9999-12-31T23:59:59.999Z";
+const TASK_STATUSES: ReadonlySet<string> = new Set([
+  "pending", "in_progress", "review", "failed", "interrupted", "completed", "cancelled",
+]);
 const NEXT_UPDATED_AT_SQL = `updated_at = CASE
   WHEN strftime('%Y-%m-%dT%H:%M:%fZ', updated_at) = updated_at AND updated_at >= ?
     THEN strftime('%Y-%m-%dT%H:%M:%fZ', updated_at, '+0.001 seconds')
@@ -117,6 +122,11 @@ function nextISO(previous: Date | string): string {
   return new Date(Math.max(Date.now(), previousMs + 1)).toISOString();
 }
 
+function assertPage(limit: number, offset = 0): void {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100
+    || !Number.isSafeInteger(offset) || offset < 0) throw new RangeError("Invalid task page");
+}
+
 export class LocalTaskStore implements TaskStore {
   private db: DatabaseWrapper;
 
@@ -190,7 +200,8 @@ export class LocalTaskStore implements TaskStore {
     }
     if (filter.priority) { conditions.push('priority = ?'); params.push(filter.priority); }
     if (filter.workspaceId) { conditions.push('workspace_id = ?'); params.push(filter.workspaceId); }
-    if (filter.projectId) { conditions.push('project_id = ?'); params.push(filter.projectId); }
+    if (filter.projectId === null) conditions.push("(project_id IS NULL OR project_id = '' OR project_id = 'default')");
+    else if (filter.projectId !== undefined) { conditions.push('project_id = ?'); params.push(filter.projectId); }
     if (filter.parentId) { conditions.push('parent_id = ?'); params.push(filter.parentId); }
     if (filter.sourceId) { conditions.push('source_id = ?'); params.push(filter.sourceId); }
     if (filter.metadata) {
@@ -217,11 +228,39 @@ export class LocalTaskStore implements TaskStore {
     const offset = filter.offset || 0;
 
     const rows = this.db.prepare(
-      `SELECT * FROM lt_tasks WHERE ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+      `SELECT * FROM lt_tasks WHERE ${where} ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?`,
     ).all(...params, limit, offset) as unknown as TaskRow[];
     return rows.map(mapRowToTask);
   }
 
+  /** Lists exact project tasks containing a string dependency. */
+  async listDependents(query: TaskDependentListQuery): Promise<TaskItem[]> {
+    assertPage(query.limit, query.offset);
+    if (query.statuses.length === 0 || query.statuses.some((status) => !TASK_STATUSES.has(status))) {
+      throw new RangeError("Invalid task statuses");
+    }
+    const rows = this.db.prepare(
+      `SELECT task.* FROM lt_tasks AS task
+       WHERE task.tenant_id = ? AND task.workspace_id = ? AND task.project_id = ?
+         AND task.status IN (${query.statuses.map(() => "?").join(", ")})
+         AND task.dependencies IS NOT NULL
+         AND json_valid(task.dependencies) = 1
+         AND json_type(CASE WHEN json_valid(task.dependencies)=1
+                            THEN task.dependencies ELSE '[]' END) = 'array'
+         AND EXISTS (
+           SELECT 1 FROM json_each(
+             CASE WHEN json_valid(task.dependencies)=1 THEN
+               CASE WHEN json_type(task.dependencies)='array' THEN task.dependencies ELSE '[]' END
+             ELSE '[]' END
+           ) AS dependency
+           WHERE dependency.type = 'text' AND dependency.value = ?
+         )
+       ORDER BY task.created_at DESC, task.id DESC LIMIT ? OFFSET ?`,
+    ).all(query.tenantId, query.workspaceId, query.projectId, ...query.statuses,
+      query.dependencyTaskId, query.limit, query.offset) as unknown as TaskRow[];
+    return rows.map(mapRowToTask);
+  }
+
   async update(
     tenantId: string,
     id: string,
@@ -400,6 +439,37 @@ export class LocalTaskStore implements TaskStore {
     return this.getById(tenantId, id);
   }
 
+  /** Atomically update only while status, timestamp, owner, and Project scope match. */
+  async updateIfSnapshot(
+    tenantId: string, id: string, updates: UpdateTaskRequest, snapshot: TaskMutationSnapshot,
+  ): Promise<TaskItem | null> {
+    const expectedIso = new Date(snapshot.updatedAt).toISOString();
+    if (expectedIso === MAX_CANONICAL_TASK_TIME) return null;
+    const setClauses = ["updated_at = ?"];
+    const values: unknown[] = [nextISO(expectedIso)];
+    const fields: Array<[keyof UpdateTaskRequest, string, boolean?]> = [
+      ["title", "title"], ["description", "description"], ["status", "status"], ["priority", "priority"],
+      ["dueDate", "due_date"], ["metadata", "metadata", true], ["parentId", "parent_id"],
+      ["sourceId", "source_id"], ["context", "context", true], ["ownerType", "owner_type"],
+      ["ownerId", "owner_id"], ["requireReview", "require_review"], ["dependencies", "dependencies", true],
+      ["result", "result"], ["failureReason", "failure_reason"], ["workspaceId", "workspace_id"],
+      ["projectId", "project_id"], ["files", "files", true],
+    ];
+    for (const [field, column, json] of fields) {
+      const value = updates[field];
+      if (value === undefined) continue;
+      setClauses.push(`${column} = ?`);
+      values.push(json && value !== null ? JSON.stringify(value) : field === "requireReview" ? (value ? 1 : 0) : value);
+    }
+    values.push(tenantId, id, snapshot.status, expectedIso, snapshot.ownerType, snapshot.ownerId,
+      snapshot.workspaceId, snapshot.projectId);
+    const result = this.db.prepare(
+      `UPDATE lt_tasks SET ${setClauses.join(", ")} WHERE tenant_id = ? AND id = ? AND status = ?
+        AND updated_at = ? AND owner_type = ? AND owner_id = ? AND workspace_id IS ? AND project_id IS ?`,
+    ).run(...values);
+    return result.changes === 0 ? null : this.getById(tenantId, id);
+  }
+
   /** Atomically update a child only when both child and parent snapshots match. */
   async updateIfStatusUpdatedAtAndParentUpdatedAt(
     tenantId: string,
@@ -458,4 +528,14 @@ export class LocalTaskStore implements TaskStore {
     ).run(tenantId, id);
     return result.changes > 0;
   }
+
+  /** Atomically delete only while status, timestamp, owner, and Project scope match. */
+  async deleteIfSnapshot(tenantId: string, id: string, snapshot: TaskMutationSnapshot): Promise<boolean> {
+    const result = this.db.prepare(
+      `DELETE FROM lt_tasks WHERE tenant_id = ? AND id = ? AND status = ? AND updated_at = ?
+        AND owner_type = ? AND owner_id = ? AND workspace_id IS ? AND project_id IS ?`,
+    ).run(tenantId, id, snapshot.status, new Date(snapshot.updatedAt).toISOString(), snapshot.ownerType,
+      snapshot.ownerId, snapshot.workspaceId, snapshot.projectId);
+    return result.changes > 0;
+  }
 }

package/src/stores/LocalTaskWorkItemStore.ts

@@ -9,11 +9,18 @@ import type {
   CreateWorkItemRequest,
   CreateWorkItemIfAbsentRequest,
   TaskWorkItemListFilter,
+  ProjectLifecycleEventQuery,
+  TaskMutationSnapshot,
 } from "@axiom-lattice/protocols";
 import { MAX_PENDING_EXECUTION_RESULTS_LIMIT } from "@axiom-lattice/protocols";
 import { ensureTable, nowISO, parseISO } from "../database";
 import { v4 as uuid } from "uuid";
 
+const PROJECT_LIFECYCLE_ACTIONS: ReadonlySet<string> = new Set([
+  "in_progress", "interrupted", "failed", "completed", "cancelled", "reassigned",
+]);
+
+
 const DDL = `
 CREATE TABLE IF NOT EXISTS lt_task_work_items (
   id TEXT NOT NULL,
@@ -48,6 +55,18 @@ interface WorkItemRow {
   created_at: string;
 }
 
+function parseDetail(raw: string | null): Record<string, unknown> | undefined {
+  if (!raw) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function mapRowToWorkItem(row: WorkItemRow): TaskWorkItem {
   return {
     id: row.id,
@@ -57,7 +76,7 @@ function mapRowToWorkItem(row: WorkItemRow): TaskWorkItem {
     actor: row.actor,
     threadId: row.thread_id ?? undefined,
     summary: row.summary ?? undefined,
-    detail: row.detail ? JSON.parse(row.detail) : undefined,
+    detail: parseDetail(row.detail),
     attempt: row.attempt ?? undefined,
     workspaceId: row.workspace_id ?? undefined,
     projectId: row.project_id ?? undefined,
@@ -66,6 +85,33 @@ function mapRowToWorkItem(row: WorkItemRow): TaskWorkItem {
   };
 }
 
+function assertAndCloneProjectLifecycleEvent(item: TaskWorkItem): TaskWorkItem {
+  let milliseconds: number;
+  try { milliseconds = Date.prototype.getTime.call(item.createdAt) as number; }
+  catch { throw new Error("Invalid project lifecycle event row"); }
+  if (!Number.isFinite(milliseconds) || typeof item.id !== "string" || item.id.length === 0
+    || typeof item.eventKey !== "string" || item.eventKey.length === 0) {
+    throw new Error("Invalid project lifecycle event row");
+  }
+  return { ...item, createdAt: new Date(milliseconds) };
+}
+
+function assertLifecyclePage(query: ProjectLifecycleEventQuery): number | null {
+  if (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > 100
+    || query.actions.length === 0
+    || query.actions.some((action) => !PROJECT_LIFECYCLE_ACTIONS.has(action))) {
+    throw new RangeError("Invalid project lifecycle event page");
+  }
+  if (!query.before) return null;
+  let milliseconds: number;
+  try { milliseconds = Date.prototype.getTime.call(query.before.createdAt) as number; }
+  catch { throw new RangeError("Invalid project lifecycle event cursor"); }
+  if (!Number.isFinite(milliseconds) || typeof query.before.id !== "string" || query.before.id.length === 0) {
+    throw new RangeError("Invalid project lifecycle event cursor");
+  }
+  return milliseconds;
+}
+
 export class LocalTaskWorkItemStore implements TaskWorkItemStore {
   private db: DatabaseWrapper;
 
@@ -82,6 +128,9 @@ export class LocalTaskWorkItemStore implements TaskWorkItemStore {
     this.db.exec(`CREATE INDEX IF NOT EXISTS idx_task_work_items_reconciled_result
       ON lt_task_work_items (tenant_id, task_id, json_extract(detail, '$.executionResultId'))
       WHERE action = 'execution_reconciled';`);
+    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_task_work_items_project_lifecycle
+      ON lt_task_work_items (tenant_id, workspace_id, project_id, created_at DESC, id DESC)
+      WHERE event_key IS NOT NULL;`);
   }
 
   /** Add a column if it does not exist (SQLite version compatible). */
@@ -115,6 +164,31 @@ export class LocalTaskWorkItemStore implements TaskWorkItemStore {
     return mapRowToWorkItem(row!);
   }
 
+  /** Atomically inserts a work item by selecting one exact task snapshot. */
+  async createIfTaskSnapshot(
+    params: CreateWorkItemRequest,
+    snapshot: TaskMutationSnapshot,
+  ): Promise<TaskWorkItem | null> {
+    const id = uuid();
+    const result = this.db.prepare(
+      `INSERT INTO lt_task_work_items
+        (id, tenant_id, task_id, action, actor, thread_id, summary, detail, attempt, workspace_id, project_id, created_at)
+       SELECT ?, task.tenant_id, task.id, ?, ?, ?, ?, ?, ?, task.workspace_id, task.project_id, ?
+       FROM lt_tasks AS task
+       WHERE task.tenant_id = ? AND task.id = ? AND task.status = ? AND task.updated_at = ?
+          AND task.owner_type = ? AND task.owner_id = ? AND task.workspace_id IS ? AND task.project_id IS ?
+          AND ? IS task.workspace_id AND ? IS task.project_id`,
+    ).run(id, params.action, params.actor, params.threadId || null, params.summary || null,
+      params.detail ? JSON.stringify(params.detail) : null, params.attempt ?? null, nowISO(),
+      params.tenantId, params.taskId, snapshot.status, new Date(snapshot.updatedAt).toISOString(),
+      snapshot.ownerType, snapshot.ownerId, snapshot.workspaceId, snapshot.projectId,
+      params.workspaceId, params.projectId);
+    if (result.changes === 0) return null;
+    const row = this.db.prepare(`SELECT * FROM lt_task_work_items WHERE tenant_id = ? AND id = ?`)
+      .get(params.tenantId, id) as unknown as WorkItemRow | undefined;
+    return row ? mapRowToWorkItem(row) : null;
+  }
+
   /** Find an event by its tenant- and task-scoped key without pagination. */
   async findByEventKey(tenantId: string, taskId: string, eventKey: string): Promise<TaskWorkItem | null> {
     const row = this.db.prepare(
@@ -199,4 +273,20 @@ export class LocalTaskWorkItemStore implements TaskWorkItemStore {
     ).all(params.tenantId, params.taskId, params.limit) as unknown as WorkItemRow[];
     return rows.map(mapRowToWorkItem);
   }
+
+  /** Lists canonical project lifecycle events with an exclusive cursor. */
+  async listProjectLifecycleEvents(query: ProjectLifecycleEventQuery): Promise<TaskWorkItem[]> {
+    const cursorMilliseconds = assertLifecyclePage(query);
+    const cursor = cursorMilliseconds === null ? null : new Date(cursorMilliseconds).toISOString();
+    const rows = this.db.prepare(
+      `SELECT * FROM lt_task_work_items
+       WHERE tenant_id = ? AND workspace_id = ? AND project_id = ?
+         AND action IN (${query.actions.map(() => "?").join(", ")})
+         AND event_key IS NOT NULL AND event_key <> ''
+         AND (? IS NULL OR created_at < ? OR (created_at = ? AND id < ?))
+       ORDER BY created_at DESC, id DESC LIMIT ?`,
+    ).all(query.tenantId, query.workspaceId, query.projectId, ...query.actions,
+      cursor, cursor, cursor, query.before?.id ?? null, query.limit) as unknown as WorkItemRow[];
+    return rows.map(mapRowToWorkItem).map(assertAndCloneProjectLifecycleEvent);
+  }
 }