@axiom-lattice/pg-stores 3.1.1 → 3.1.2

package/src/stores/PostgreSQLProjectRoomMessageStore.ts

@@ -0,0 +1,177 @@
+import type {
+  ProjectRoomMention,
+  ProjectRoomMessage,
+  ProjectRoomMessageAuthor,
+  ProjectRoomMessageSource,
+  ProjectRoomMessageStore,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+type MessageRow = {
+  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;
+};
+type PostgreSQLError = { code?: unknown; constraint?: 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";
+
+/** Indicates that a tenant-scoped room message ID already exists. */
+export class ProjectRoomMessageIdConflictError extends Error {
+  /** Creates an accurate tenant-scoped message ID collision error. */
+  constructor(tenantId: string, id: string) {
+    super(`Project room message ID '${id}' already exists in tenant '${tenantId}'`);
+    this.name = "ProjectRoomMessageIdConflictError";
+  }
+}
+
+/** Indicates that ordinary creation reused a room-scoped idempotency key. */
+export class DuplicateProjectRoomMessageIdempotencyKeyError extends Error {
+  /** Creates an accurate tenant and room-scoped idempotency collision error. */
+  constructor(tenantId: string, roomId: string, idempotencyKey: string) {
+    super(`Project room message idempotency key '${idempotencyKey}' already exists in tenant '${tenantId}' room '${roomId}'`);
+    this.name = "DuplicateProjectRoomMessageIdempotencyKeyError";
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  return Object.keys(value).every((key) => keys.includes(key));
+}
+function mapAuthor(value: unknown): ProjectRoomMessageAuthor | undefined {
+  if (!isRecord(value) || typeof value.type !== "string") return undefined;
+  if (value.type === "human" && hasOnlyKeys(value, ["type", "userId"]) && typeof value.userId === "string") return { type: "human", userId: value.userId };
+  if (value.type === "bot" && hasOnlyKeys(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" && hasOnlyKeys(value, ["type"])) return { type: "system" };
+  return undefined;
+}
+function mapMention(value: unknown): ProjectRoomMention | undefined {
+  if (!isRecord(value) || typeof value.type !== "string") return undefined;
+  if (value.type === "bot" && hasOnlyKeys(value, ["type", "membershipId"]) && typeof value.membershipId === "string") {
+    return { type: "bot", membershipId: value.membershipId };
+  }
+  if (value.type === "team" && hasOnlyKeys(value, ["type"])) return { type: "team" };
+  return undefined;
+}
+function isSource(value: unknown): value is ProjectRoomMessageSource {
+  return value === "user" || value === "agent" || value === "task" || value === "routine" || value === "system";
+}
+function mapRow(row: MessageRow): ProjectRoomMessage {
+  const author = mapAuthor(row.author);
+  const content = isRecord(row.content) && row.content.type === "text" && typeof row.content.text === "string"
+    && hasOnlyKeys(row.content, ["type", "text"]) ? { type: "text" as const, text: row.content.text } : undefined;
+  const mentions = Array.isArray(row.mentions) ? row.mentions.map(mapMention) : 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" || !author || !content || !mentions
+    || mentions.some((mention) => mention === undefined)
+    || (row.reply_to_message_id !== null && typeof row.reply_to_message_id !== "string") || !isSource(row.source)
+    || (row.source_id !== null && typeof row.source_id !== "string")
+    || (row.idempotency_key !== null && typeof row.idempotency_key !== "string")
+    || !(row.created_at instanceof Date) || Number.isNaN(row.created_at.getTime())) {
+    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, content, mentions: mentions 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: row.created_at,
+  };
+}
+function isUniqueViolation(error: unknown): error is PostgreSQLError {
+  return typeof error === "object" && error !== null && "code" in error
+    && (error as PostgreSQLError).code === "23505";
+}
+
+/** Persists tenant-isolated project room messages in PostgreSQL. */
+export class PostgreSQLProjectRoomMessageStore implements ProjectRoomMessageStore {
+  /** Creates a store using an externally managed shared pool. */
+  constructor(options: { pool: Pool }) { this.pool = options.pool; }
+  private readonly pool: Pool;
+
+  /** Creates a room message and maps known uniqueness failures to typed errors. */
+  async create(input: Omit<ProjectRoomMessage, "createdAt">): Promise<ProjectRoomMessage> {
+    try {
+      const result = await this.pool.query<MessageRow>(
+        `INSERT INTO lattice_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 ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, date_trunc('milliseconds', clock_timestamp()))
+         RETURNING ${columns}`,
+        this.parameters(input),
+      );
+      return mapRow(result.rows[0]);
+    } catch (error) {
+      if (isUniqueViolation(error) && error.constraint === "lattice_project_room_messages_pkey") {
+        throw new ProjectRoomMessageIdConflictError(input.tenantId, input.id);
+      }
+      if (isUniqueViolation(error) && error.constraint === "uq_lattice_project_room_messages_idempotency") {
+        throw new DuplicateProjectRoomMessageIdempotencyKeyError(input.tenantId, input.roomId, input.idempotencyKey ?? "");
+      }
+      throw error;
+    }
+  }
+
+  /** Atomically creates or returns the canonical message for a room-scoped idempotency key. */
+  async createIdempotent(
+    input: Omit<ProjectRoomMessage, "createdAt"> & { idempotencyKey: string },
+  ): Promise<ProjectRoomMessage> {
+    try {
+      const result = await this.pool.query<MessageRow>(
+        `INSERT INTO lattice_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 ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, date_trunc('milliseconds', clock_timestamp()))
+         ON CONFLICT (tenant_id, room_id, idempotency_key) WHERE idempotency_key IS NOT NULL
+         DO UPDATE SET idempotency_key = lattice_project_room_messages.idempotency_key
+         RETURNING ${columns}`,
+        this.parameters(input),
+      );
+      return mapRow(result.rows[0]);
+    } catch (error) {
+      if (isUniqueViolation(error) && error.constraint === "lattice_project_room_messages_pkey") {
+        throw new ProjectRoomMessageIdConflictError(input.tenantId, input.id);
+      }
+      throw error;
+    }
+  }
+
+  /** Lists messages newest first using an exclusive stable cursor and a clamped limit. */
+  async list(input: {
+    tenantId: string; roomId: string; before?: { createdAt: Date; id: string }; limit: number;
+  }): Promise<ProjectRoomMessage[]> {
+    if (input.before && (!(input.before.createdAt instanceof Date) || Number.isNaN(input.before.createdAt.getTime()))) {
+      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 result = input.before
+      ? await this.pool.query<MessageRow>(
+        `SELECT ${columns} FROM lattice_project_room_messages
+         WHERE tenant_id = $1 AND room_id = $2 AND (created_at < $3 OR (created_at = $3 AND id < $4))
+         ORDER BY created_at DESC, id DESC LIMIT $5`,
+        [input.tenantId, input.roomId, input.before.createdAt, input.before.id, limit],
+      )
+      : await this.pool.query<MessageRow>(
+        `SELECT ${columns} FROM lattice_project_room_messages
+         WHERE tenant_id = $1 AND room_id = $2 ORDER BY created_at DESC, id DESC LIMIT $3`,
+        [input.tenantId, input.roomId, limit],
+      );
+    return result.rows.map(mapRow);
+  }
+
+  /** Finds a message by tenant-scoped ID. */
+  async findById(tenantId: string, id: string): Promise<ProjectRoomMessage | null> {
+    const result = await this.pool.query<MessageRow>(
+      `SELECT ${columns} FROM lattice_project_room_messages WHERE tenant_id = $1 AND id = $2`, [tenantId, id],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  private parameters(input: Omit<ProjectRoomMessage, "createdAt">): unknown[] {
+    return [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];
+  }
+}

package/src/stores/PostgreSQLProjectRoomStore.ts

@@ -0,0 +1,57 @@
+import type { ProjectRoom, ProjectRoomStore } from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+type ProjectRoomRow = {
+  id: unknown; tenant_id: unknown; workspace_id: unknown; project_id: unknown;
+  type: unknown; name: unknown; created_at: unknown; updated_at: unknown;
+};
+
+function isValidDate(value: unknown): value is Date {
+  return value instanceof Date && !Number.isNaN(value.getTime());
+}
+
+function mapRow(row: ProjectRoomRow): ProjectRoom {
+  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"
+    || !isValidDate(row.created_at) || !isValidDate(row.updated_at)) {
+    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: row.created_at, updatedAt: row.updated_at,
+  };
+}
+
+/** Persists tenant-isolated canonical project main rooms in PostgreSQL. */
+export class PostgreSQLProjectRoomStore implements ProjectRoomStore {
+  /** Creates a store using an externally managed pool; the pool is not migrated or closed. */
+  constructor(options: { pool: Pool }) { this.pool = options.pool; }
+  private readonly pool: Pool;
+
+  /** Creates or returns the single persisted main room for a project. */
+  async ensureMainRoom(input: {
+    id: string; tenantId: string; workspaceId: string; projectId: string; name: string;
+  }): Promise<ProjectRoom> {
+    const result = await this.pool.query<ProjectRoomRow>(
+      `INSERT INTO lattice_project_rooms
+       (id, tenant_id, workspace_id, project_id, type, name)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       ON CONFLICT (tenant_id, project_id, type)
+       DO UPDATE SET updated_at = lattice_project_rooms.updated_at
+       RETURNING id, tenant_id, workspace_id, project_id, type, name, created_at, updated_at`,
+      [input.id, input.tenantId, input.workspaceId, input.projectId, "main", input.name],
+    );
+    return mapRow(result.rows[0]);
+  }
+
+  /** Finds a tenant-scoped project's main room, or returns null. */
+  async getMainRoom(tenantId: string, projectId: string): Promise<ProjectRoom | null> {
+    const result = await this.pool.query<ProjectRoomRow>(
+      "SELECT id, tenant_id, workspace_id, project_id, type, name, created_at, updated_at FROM lattice_project_rooms WHERE tenant_id = $1 AND project_id = $2 AND type = 'main'",
+      [tenantId, projectId],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+}

package/src/stores/PostgreSQLTaskStore.ts

@@ -11,11 +11,18 @@ import type {
   UpdateTaskRequest,
   TaskListFilter,
   TaskFileRef,
+  TaskDependentListQuery,
+  TaskMutationSnapshot,
 } from "@axiom-lattice/protocols";
 import { MigrationManager } from "../migrations/migration";
-import { createTasksTable, addTaskFieldsMigration, addTaskProjectFieldsMigration, addFilesToTasks } from "../migrations/task_migration";
+import { createTasksTable, addTaskFieldsMigration, addTaskProjectFieldsMigration, addFilesToTasks, addTaskDependenciesGinIndex } from "../migrations/task_migration";
 import { v4 as uuidv4 } from "uuid";
 
+const TASK_STATUSES: ReadonlySet<string> = new Set([
+  "pending", "in_progress", "review", "failed", "interrupted", "completed", "cancelled",
+]);
+
+
 interface TaskRow {
   id: string;
   tenant_id: string;
@@ -131,6 +138,11 @@ function mapRowToTask(row: TaskRow): TaskItem {
   };
 }
 
+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 interface PostgreSQLTaskStoreOptions {
   pool?: Pool;
   poolConfig?: string | PoolConfig;
@@ -166,6 +178,7 @@ export class PostgreSQLTaskStore implements TaskStore {
     this.migrationManager.register(addTaskFieldsMigration);
     this.migrationManager.register(addTaskProjectFieldsMigration);
     this.migrationManager.register(addFilesToTasks);
+    this.migrationManager.register(addTaskDependenciesGinIndex);
 
     if (options.autoMigrate !== false) {
       this.initialize().catch((error) => {
@@ -274,7 +287,9 @@ export class PostgreSQLTaskStore implements TaskStore {
       conditions.push(`workspace_id = $${paramIndex++}`);
       params.push(filter.workspaceId);
     }
-    if (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 = $${paramIndex++}`);
       params.push(filter.projectId);
     }
@@ -301,12 +316,30 @@ export class PostgreSQLTaskStore implements TaskStore {
     const offset = filter.offset || 0;
 
     const result = await this.pool.query<TaskRow>(
-      `SELECT * FROM lattice_tasks WHERE ${where} ORDER BY created_at DESC LIMIT $${paramIndex++} OFFSET $${paramIndex++}`,
+      `SELECT * FROM lattice_tasks WHERE ${where} ORDER BY created_at DESC, id DESC LIMIT $${paramIndex++} OFFSET $${paramIndex++}`,
       [...params, limit, offset],
     );
     return result.rows.map((r) => mapRowToTask(r));
   }
 
+  /** Lists exact project tasks containing a JSON 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");
+    }
+    await this.ensureInitialized();
+    const result = await this.pool.query<TaskRow>(
+      `SELECT * FROM lattice_tasks
+       WHERE tenant_id=$1 AND workspace_id=$2 AND project_id=$3
+         AND dependencies @> $4::jsonb AND status = ANY($5::text[])
+       ORDER BY created_at DESC, id DESC LIMIT $6 OFFSET $7`,
+      [query.tenantId, query.workspaceId, query.projectId, JSON.stringify([query.dependencyTaskId]),
+        query.statuses, query.limit, query.offset],
+    );
+    return result.rows.map(mapRowToTask);
+  }
+
   async update(
     tenantId: string,
     id: string,
@@ -558,6 +591,45 @@ export class PostgreSQLTaskStore implements TaskStore {
     return result.rows[0] ? mapRowToTask(result.rows[0]) : null;
   }
 
+  /** Atomically update only while status, timestamp, owner, and Project scope match. */
+  async updateIfSnapshot(
+    tenantId: string, id: string, updates: UpdateTaskRequest, snapshot: TaskMutationSnapshot,
+  ): Promise<TaskItem | null> {
+    await this.ensureInitialized();
+    const setClauses: string[] = [];
+    const params: unknown[] = [];
+    let index = 1;
+    const fields: Array<[keyof UpdateTaskRequest, string, boolean?]> = [
+      ["title", "title"], ["description", "description"], ["status", "status"], ["priority", "priority"],
+      ["dueDate", "due_date"], ["metadata", "metadata", true], ["files", "files", 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"],
+    ];
+    for (const [field, column, json] of fields) {
+      const value = updates[field];
+      if (value === undefined) continue;
+      setClauses.push(`${column} = $${index++}`);
+      params.push(json && value !== null ? JSON.stringify(value) : value);
+    }
+    if (setClauses.length === 0) return this.getById(tenantId, id);
+    setClauses.push(`updated_at = ${nextUpdatedAtSql()}`);
+    const predicates = [tenantId, id, snapshot.status, new Date(snapshot.updatedAt).toISOString(), snapshot.ownerType,
+      snapshot.ownerId, snapshot.workspaceId, snapshot.projectId];
+    const placeholders = predicates.map(() => `$${index++}`);
+    params.push(...predicates);
+    const result = await this.pool.query<TaskRow>(
+      `UPDATE lattice_tasks SET ${setClauses.join(", ")}
+       WHERE tenant_id = ${placeholders[0]} AND id = ${placeholders[1]} AND status = ${placeholders[2]}
+         AND ${canonicalTimestampSnapshotSql("updated_at", placeholders[3])}
+          AND owner_type = ${placeholders[4]} AND owner_id = ${placeholders[5]}
+          AND workspace_id IS NOT DISTINCT FROM ${placeholders[6]}
+          AND project_id IS NOT DISTINCT FROM ${placeholders[7]} RETURNING *`, params,
+    );
+    return result.rows[0] ? mapRowToTask(result.rows[0]) : null;
+  }
+
   /** Atomically update a child only when both child and parent snapshots match. */
   async updateIfStatusUpdatedAtAndParentUpdatedAt(
     tenantId: string,
@@ -631,6 +703,20 @@ export class PostgreSQLTaskStore implements TaskStore {
     return (result.rowCount ?? 0) > 0;
   }
 
+  /** Atomically delete only while status, timestamp, owner, and Project scope match. */
+  async deleteIfSnapshot(tenantId: string, id: string, snapshot: TaskMutationSnapshot): Promise<boolean> {
+    await this.ensureInitialized();
+    const result = await this.pool.query(
+      `DELETE FROM lattice_tasks WHERE tenant_id = $1 AND id = $2 AND status = $3
+       AND ${canonicalTimestampSnapshotSql("updated_at", "$4")}
+        AND owner_type = $5 AND owner_id = $6
+        AND workspace_id IS NOT DISTINCT FROM $7 AND project_id IS NOT DISTINCT FROM $8`,
+      [tenantId, id, snapshot.status, new Date(snapshot.updatedAt).toISOString(), snapshot.ownerType,
+        snapshot.ownerId, snapshot.workspaceId, snapshot.projectId],
+    );
+    return (result.rowCount ?? 0) > 0;
+  }
+
   async dispose(): Promise<void> {
     if (this.ownsPool && this.pool) {
       await this.pool.end();

package/src/stores/PostgreSQLTaskWorkItemStore.ts

@@ -1,17 +1,97 @@
-import type { Pool } from "pg";
-import type { TaskWorkItemStore, TaskWorkItem, CreateWorkItemRequest, CreateWorkItemIfAbsentRequest, TaskWorkItemListFilter } from "@axiom-lattice/protocols";
+import { Pool } from "pg";
+import type { PoolConfig } from "pg";
+import type { TaskWorkItemStore, TaskWorkItem, CreateWorkItemRequest, CreateWorkItemIfAbsentRequest, TaskWorkItemListFilter, ProjectLifecycleEventQuery, TaskMutationSnapshot } from "@axiom-lattice/protocols";
 import { MAX_PENDING_EXECUTION_RESULTS_LIMIT } from "@axiom-lattice/protocols";
 import { v4 } from "uuid";
+import { MigrationManager } from "../migrations/migration";
+import { taskWorkItemMigrations } from "../migrations/task_work_items_migration";
 
+const PROJECT_LIFECYCLE_ACTIONS: ReadonlySet<string> = new Set([
+  "in_progress", "interrupted", "failed", "completed", "cancelled", "reassigned",
+]);
+
+/** PostgreSQL TaskWorkItem store connection and migration options. */
+export interface PostgreSQLTaskWorkItemStoreOptions {
+  /** External caller-owned pool; central migrations must already be applied. */
+  pool?: Pool;
+  /** Connection configuration for a standalone, store-owned pool. */
+  poolConfig?: string | PoolConfig;
+  /** Whether a standalone store eagerly applies migrations. Defaults to true. */
+  autoMigrate?: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isPool(value: Pool | PostgreSQLTaskWorkItemStoreOptions): value is Pool {
+  return typeof (value as { query?: unknown }).query === "function";
+}
+
+/** PostgreSQL TaskWorkItem persistence with optional standalone migrations. */
 export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
-  constructor(private pool: Pool) {}
+  private pool: Pool;
+  private migrationManager!: MigrationManager;
+  private initialized = false;
+  private ownsPool = false;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(pool: Pool);
+  constructor(options: PostgreSQLTaskWorkItemStoreOptions);
+  constructor(poolOrOptions: Pool | PostgreSQLTaskWorkItemStoreOptions) {
+    if (isPool(poolOrOptions)) {
+      this.pool = poolOrOptions;
+      this.initialized = true;
+      return;
+    }
+    const options = poolOrOptions as PostgreSQLTaskWorkItemStoreOptions;
+    if (options.pool) {
+      this.pool = options.pool;
+      this.initialized = true;
+      return;
+    }
+    this.pool = typeof options.poolConfig === "string"
+      ? new Pool({ connectionString: options.poolConfig })
+      : options.poolConfig
+        ? new Pool(options.poolConfig)
+        : (() => { throw new Error("Either pool or poolConfig must be provided"); })();
+    this.ownsPool = true;
+    this.migrationManager = new MigrationManager(this.pool);
+    for (const migration of taskWorkItemMigrations) this.migrationManager.register(migration);
+    if (options.autoMigrate !== false) this.startInitialization();
+  }
+
+  /** Applies the complete standalone TaskWorkItem migration chain once. */
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+    if (this.initPromise) return this.initPromise;
+    return this.startInitialization();
+  }
+
+  /** Closes the pool only when this store created it from connection configuration. */
+  async dispose(): Promise<void> {
+    if (this.ownsPool) await this.pool.end();
+  }
+
+  private startInitialization(): Promise<void> {
+    this.initPromise = this.migrationManager.migrate().then(() => {
+      this.initialized = true;
+    });
+    void this.initPromise.catch(() => undefined);
+    return this.initPromise;
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (!this.initialized) await this.initialize();
+  }
 
   async create(params: CreateWorkItemRequest): Promise<TaskWorkItem> {
+    await this.ensureInitialized();
     const id = v4();
     const result = await this.pool.query(
       `INSERT INTO lattice_task_work_items
-        (id, tenant_id, task_id, action, actor, thread_id, summary, detail, attempt, workspace_id, project_id)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+        (id, tenant_id, task_id, action, actor, thread_id, summary, detail, attempt, workspace_id, project_id, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, date_trunc('milliseconds', clock_timestamp()))
        RETURNING *`,
       [
         id, params.tenantId, params.taskId, params.action, params.actor,
@@ -25,8 +105,36 @@ export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
     return this.rowToItem(result.rows[0]);
   }
 
+  /** Atomically inserts a work item by selecting one exact task snapshot. */
+  async createIfTaskSnapshot(
+    params: CreateWorkItemRequest,
+    snapshot: TaskMutationSnapshot,
+  ): Promise<TaskWorkItem | null> {
+    await this.ensureInitialized();
+    const result = await this.pool.query(
+      `INSERT INTO lattice_task_work_items
+        (id, tenant_id, task_id, action, actor, thread_id, summary, detail, attempt, workspace_id, project_id, created_at)
+       SELECT $1, task.tenant_id, task.id, $2, $3, $4, $5, $6, $7, task.workspace_id, task.project_id,
+         date_trunc('milliseconds', clock_timestamp())
+       FROM lattice_tasks AS task
+       WHERE task.tenant_id = $8 AND task.id = $9 AND task.status = $10
+         AND date_trunc('milliseconds', task.updated_at::timestamptz) = $11::timestamptz
+          AND task.owner_type = $12 AND task.owner_id = $13
+          AND task.workspace_id IS NOT DISTINCT FROM $14 AND task.project_id IS NOT DISTINCT FROM $15
+          AND $14 IS NOT DISTINCT FROM $16 AND $15 IS NOT DISTINCT FROM $17
+       RETURNING *`,
+      [v4(), params.action, params.actor, params.threadId || null, params.summary || null,
+        params.detail ? JSON.stringify(params.detail) : null, params.attempt ?? null,
+        params.tenantId, params.taskId, snapshot.status, new Date(snapshot.updatedAt).toISOString(),
+        snapshot.ownerType, snapshot.ownerId, snapshot.workspaceId, snapshot.projectId,
+        params.workspaceId, params.projectId],
+    );
+    return result.rows[0] ? this.rowToItem(result.rows[0]) : null;
+  }
+
   /** Find an event by its tenant- and task-scoped key without pagination. */
   async findByEventKey(tenantId: string, taskId: string, eventKey: string): Promise<TaskWorkItem | null> {
+    await this.ensureInitialized();
     const result = await this.pool.query(
       `SELECT * FROM lattice_task_work_items
        WHERE tenant_id = $1 AND task_id = $2 AND event_key = $3`,
@@ -37,10 +145,11 @@ export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
 
   /** Atomically return an existing event or create it once. */
   async createIfAbsentByEventKey(params: CreateWorkItemIfAbsentRequest): Promise<TaskWorkItem> {
+    await this.ensureInitialized();
     const result = await this.pool.query(
       `INSERT INTO lattice_task_work_items
-        (id, tenant_id, task_id, action, actor, thread_id, summary, detail, attempt, workspace_id, project_id, event_key)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+        (id, tenant_id, task_id, action, actor, thread_id, summary, detail, attempt, workspace_id, project_id, event_key, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, date_trunc('milliseconds', clock_timestamp()))
        ON CONFLICT (tenant_id, task_id, event_key) WHERE event_key IS NOT NULL
        DO UPDATE SET event_key = EXCLUDED.event_key
        RETURNING *`,
@@ -56,6 +165,7 @@ export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
   }
 
   async list(filter: TaskWorkItemListFilter): Promise<TaskWorkItem[]> {
+    await this.ensureInitialized();
     let query = `SELECT * FROM lattice_task_work_items WHERE tenant_id = $1 AND task_id = $2`;
     const params: unknown[] = [filter.tenantId, filter.taskId];
 
@@ -126,6 +236,47 @@ export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
     return result.rows.map((row: Record<string, unknown>) => this.rowToItem(row));
   }
 
+  /** Lists canonical project lifecycle events with an exclusive cursor. */
+  async listProjectLifecycleEvents(query: ProjectLifecycleEventQuery): Promise<TaskWorkItem[]> {
+    let cursorMilliseconds: number | null = 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) {
+      try { cursorMilliseconds = Date.prototype.getTime.call(query.before.createdAt) as number; }
+      catch { throw new RangeError("Invalid project lifecycle event cursor"); }
+      if (!Number.isFinite(cursorMilliseconds) || typeof query.before.id !== "string" || query.before.id.length === 0) {
+        throw new RangeError("Invalid project lifecycle event cursor");
+      }
+    }
+    const cursor = cursorMilliseconds === null ? null : new Date(cursorMilliseconds);
+    await this.ensureInitialized();
+    const result = await this.pool.query(
+      `SELECT * FROM lattice_task_work_items
+       WHERE tenant_id=$1 AND workspace_id=$2 AND project_id=$3
+         AND action = ANY($4::text[]) AND event_key IS NOT NULL AND event_key <> ''
+         AND ($5::timestamptz IS NULL OR created_at < $5::timestamptz
+           OR (created_at = $5::timestamptz AND id < $6))
+       ORDER BY created_at DESC, id DESC LIMIT $7`,
+      [query.tenantId, query.workspaceId, query.projectId, query.actions,
+        cursor, query.before?.id ?? null, query.limit],
+    );
+    return result.rows.map((row: Record<string, unknown>) => this.assertProjectLifecycleEvent(this.rowToItem(row)));
+  }
+
+  private assertProjectLifecycleEvent(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) };
+  }
+
   private rowToItem(row: Record<string, unknown>): TaskWorkItem {
     return {
       id: row.id as string,
@@ -135,7 +286,7 @@ export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
       actor: row.actor as string,
       threadId: row.thread_id as string | undefined,
       summary: row.summary as string | undefined,
-      detail: row.detail as Record<string, unknown> | undefined,
+      detail: isRecord(row.detail) ? row.detail : undefined,
       attempt: row.attempt as number | undefined,
       workspaceId: row.workspace_id as string | undefined,
       projectId: row.project_id as string | undefined,