@axiom-lattice/pg-stores 3.1.1 → 3.1.2

package/src/__tests__/PostgreSQLProjectRoomStore.migrations.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import type { PoolClient } from "pg";
+
+const registeredMigrationNames: string[] = [];
+
+jest.mock("@axiom-lattice/core", () => ({}));
+
+jest.mock("pg", () => ({
+  Pool: class Pool {},
+}));
+
+jest.mock("../migrations/migration", () => ({
+  MigrationManager: class MigrationManager {
+    register(migration: { name: string }): void {
+      registeredMigrationNames.push(migration.name);
+    }
+
+    async migrate(): Promise<void> {
+      throw new Error("stop after migrations");
+    }
+  },
+}));
+
+import { createPgStoreConfig } from "../createPgStoreConfig";
+import { createProjectRoomTables } from "../migrations/project_room_migration";
+
+function normalizeSql(sql: string): string {
+  return sql.replace(/\s+/g, " ").trim();
+}
+
+describe("project room migration", () => {
+  it("has a globally unique identity and is centrally registered before migration", async () => {
+    expect(createProjectRoomTables.version).toBe(172);
+    expect(createProjectRoomTables.name).toBe("create_project_room_tables");
+
+    registeredMigrationNames.length = 0;
+    await expect(createPgStoreConfig("postgres://unused")).rejects.toThrow("stop after migrations");
+
+    expect(registeredMigrationNames).toContain("create_project_room_tables");
+    expect(registeredMigrationNames.filter((name) => name === "create_project_room_tables")).toHaveLength(1);
+  });
+
+  it("creates the four tables with their checks, uniqueness rules, and query indexes", async () => {
+    const statements: string[] = [];
+    const client = {
+      query: async (sql: string) => {
+        statements.push(normalizeSql(sql));
+        return { rows: [] };
+      },
+    } as unknown as PoolClient;
+
+    await createProjectRoomTables.up(client);
+    const sql = statements.join("\n");
+
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS lattice_project_rooms");
+    expect(sql).toContain("PRIMARY KEY (tenant_id, id)");
+    expect(sql).toContain("UNIQUE (tenant_id, project_id, type)");
+    expect(sql).toContain("CHECK (type IN ('main'))");
+
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS lattice_project_memberships");
+    expect(sql).toContain("CHECK (role IN ('owner', 'admin', 'member', 'viewer'))");
+    expect(sql).toContain("CHECK (status IN ('active', 'removed'))");
+    expect(sql).toContain("UNIQUE (tenant_id, project_id, user_id)");
+    expect(sql).toContain("idx_lattice_project_memberships_project");
+
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS lattice_project_bot_memberships");
+    expect(sql).toContain("CHECK (role IN ('coordinator', 'specialist'))");
+    expect(sql).toContain("CHECK (status IN ('active', 'paused', 'removed'))");
+    expect(sql).toContain("UNIQUE (tenant_id, project_id, assistant_id)");
+    expect(sql).toContain("idx_lattice_project_bot_memberships_project");
+    expect(sql).toContain("idx_lattice_project_bot_memberships_room");
+    expect(sql).toContain("UNIQUE INDEX IF NOT EXISTS uq_lattice_project_bot_memberships_coordinator");
+    expect(sql).toContain("ON lattice_project_bot_memberships (tenant_id, project_id) WHERE role = 'coordinator' AND status IN ('active', 'paused')");
+    expect(sql).toContain("UNIQUE INDEX IF NOT EXISTS uq_lattice_project_bot_memberships_mention");
+    expect(sql).toContain("ON lattice_project_bot_memberships (tenant_id, room_id, mention_name) WHERE status IN ('active', 'paused')");
+
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS lattice_project_room_messages");
+    expect(sql).toContain("author JSONB NOT NULL");
+    expect(sql).toContain("content JSONB NOT NULL");
+    expect(sql).toContain("mentions JSONB NOT NULL DEFAULT '[]'::jsonb");
+    expect(sql).toContain("CHECK (source IN ('user', 'agent', 'task', 'routine', 'system'))");
+    expect(sql).toContain("UNIQUE INDEX IF NOT EXISTS uq_lattice_project_room_messages_idempotency");
+    expect(sql).toContain("ON lattice_project_room_messages (tenant_id, room_id, idempotency_key) WHERE idempotency_key IS NOT NULL");
+    expect(sql).toContain("idx_lattice_project_room_messages_room_created");
+    expect(sql).toContain("ON lattice_project_room_messages (tenant_id, room_id, created_at DESC, id DESC)");
+    expect(sql).not.toMatch(/REFERENCES\s/i);
+  });
+
+  it("drops indexes and tables in reverse dependency order", async () => {
+    const statements: string[] = [];
+    const client = {
+      query: async (sql: string) => {
+        statements.push(normalizeSql(sql));
+        return { rows: [] };
+      },
+    } as unknown as PoolClient;
+
+    await createProjectRoomTables.down?.(client);
+
+    expect(statements).toEqual([
+      "DROP INDEX IF EXISTS idx_lattice_project_room_messages_room_created",
+      "DROP INDEX IF EXISTS uq_lattice_project_room_messages_idempotency",
+      "DROP TABLE IF EXISTS lattice_project_room_messages",
+      "DROP INDEX IF EXISTS idx_lattice_project_bot_memberships_room",
+      "DROP INDEX IF EXISTS idx_lattice_project_bot_memberships_project",
+      "DROP INDEX IF EXISTS uq_lattice_project_bot_memberships_mention",
+      "DROP INDEX IF EXISTS uq_lattice_project_bot_memberships_coordinator",
+      "DROP TABLE IF EXISTS lattice_project_bot_memberships",
+      "DROP INDEX IF EXISTS idx_lattice_project_memberships_project",
+      "DROP TABLE IF EXISTS lattice_project_memberships",
+      "DROP TABLE IF EXISTS lattice_project_rooms",
+    ]);
+  });
+});

package/src/__tests__/PostgreSQLProjectRoomStore.test.ts

@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import type { Pool } from "pg";
+
+import { PostgreSQLProjectRoomStore } from "../stores/PostgreSQLProjectRoomStore";
+
+const query = jest.fn();
+const pool = { query } as unknown as Pool;
+const now = new Date("2026-08-30T12:00:00.000Z");
+const row = {
+  id: "room-1", tenant_id: "tenant-1", workspace_id: "workspace-1", project_id: "project-1",
+  type: "main", name: "Main", created_at: now, updated_at: now,
+};
+
+describe("PostgreSQLProjectRoomStore", () => {
+  beforeEach(() => query.mockReset());
+
+  it("atomically ensures the persisted winner without changing its semantic fields", async () => {
+    query.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLProjectRoomStore({ pool });
+
+    await expect(store.ensureMainRoom({
+      id: "candidate", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", name: "Candidate",
+    })).resolves.toEqual({
+      id: "room-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1",
+      type: "main", name: "Main", createdAt: now, updatedAt: now,
+    });
+
+    const [sql, params] = query.mock.calls[0] as [string, unknown[]];
+    expect(sql).toContain("ON CONFLICT (tenant_id, project_id, type)");
+    expect(sql).toContain("SET updated_at = lattice_project_rooms.updated_at");
+    expect(sql).toContain("RETURNING");
+    expect(params).toEqual(["candidate", "tenant-1", "workspace-1", "project-1", "main", "Candidate"]);
+  });
+
+  it("uses exact tenant filters when finding the main room", async () => {
+    query.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLProjectRoomStore({ pool });
+    await expect(store.getMainRoom("tenant-1", "project-1")).resolves.toMatchObject({ id: "room-1" });
+    expect(query.mock.calls[0][0]).toContain("WHERE tenant_id = $1 AND project_id = $2 AND type = 'main'");
+    expect(query.mock.calls[0][1]).toEqual(["tenant-1", "project-1"]);
+  });
+
+  it("rejects malformed rows", async () => {
+    query.mockResolvedValueOnce({ rows: [{ ...row, type: "side" }] });
+    const store = new PostgreSQLProjectRoomStore({ pool });
+    await expect(store.getMainRoom("tenant-1", "project-1")).rejects.toThrow("Invalid project room row");
+  });
+});

package/src/__tests__/PostgreSQLTaskStore.integration.test.ts

@@ -87,4 +87,31 @@ describeIfDatabase("PostgreSQLTaskStore timestamp contract", () => {
       task.updatedAt,
     )).resolves.toBeNull();
   });
+
+  it("lists exact JSONB dependents and nonproject tasks in deterministic order", async () => {
+    const common = {
+      tenantId, ownerType: "agent", ownerId: "agent-1", workspaceId: "workspace-1", projectId: "project-1",
+    } as const;
+    for (const [id, status, dependencies] of [
+      ["dependent-a", "pending", ["dependency-1"]],
+      ["dependent-b", "interrupted", ["dependency-1", "dependency-1"]],
+      ["dependent-c", "pending", ["dependency-1"]],
+    ] as const) {
+      await store.create({ ...common, id, title: id, status, dependencies });
+    }
+    await pool.query("UPDATE lattice_tasks SET created_at = $1 WHERE tenant_id = $2", ["2026-01-01T00:00:00.000Z", tenantId]);
+
+    const dependents = await store.listDependents({
+      tenantId, workspaceId: "workspace-1", projectId: "project-1", dependencyTaskId: "dependency-1",
+      statuses: ["pending", "interrupted"], limit: 2, offset: 0,
+    });
+    expect(dependents.map(({ id }) => id)).toEqual(["dependent-c", "dependent-b"]);
+
+    for (const [id, projectId] of [["nonproject-d", undefined], ["nonproject-c", ""], ["nonproject-b", "default"]] as const) {
+      await store.create({ id, tenantId, ownerType: "user", ownerId: "user-1", title: id, projectId });
+    }
+    await pool.query("UPDATE lattice_tasks SET created_at = $1 WHERE tenant_id = $2 AND id LIKE 'nonproject-%'", ["2026-01-02T00:00:00.000Z", tenantId]);
+    const nonproject = await store.list({ tenantId, projectId: null, limit: 2, offset: 1 });
+    expect(nonproject.map(({ id }) => id)).toEqual(["nonproject-c", "nonproject-b"]);
+  });
 });

package/src/__tests__/PostgreSQLTaskStore.test.ts

@@ -210,6 +210,44 @@ describe("PostgreSQLTaskStore.create", () => {
     )).resolves.toBeNull();
   });
 
+  it("uses exact owner and project snapshot predicates for update and delete", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery
+      .mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 })
+      .mockResolvedValueOnce({ rows: [], rowCount: 1 });
+    const snapshot = {
+      status: "pending" as const, updatedAt: "2026-01-01T00:00:00.000Z",
+      ownerType: "agent" as const, ownerId: "owner-1", workspaceId: "workspace-1", projectId: "project-1",
+    };
+
+    await store.updateIfSnapshot("t1", "task-1", { title: "Updated" }, snapshot);
+    await store.deleteIfSnapshot("t1", "task-1", snapshot);
+
+    for (const [sql, params] of mockQuery.mock.calls as unknown as Array<[string, unknown[]]>) {
+      expect(sql).toContain("status =");
+      expect(sql).toContain("updated_at");
+      expect(sql).toContain("owner_type =");
+      expect(sql).toContain("owner_id =");
+      expect(sql).toContain("workspace_id IS NOT DISTINCT FROM");
+      expect(sql).toContain("project_id IS NOT DISTINCT FROM");
+      expect(params).toEqual(expect.arrayContaining([
+        "pending", snapshot.updatedAt, "agent", "owner-1", "workspace-1", "project-1",
+      ]));
+    }
+  });
+
+  it("uses null-safe predicates for a nonproject snapshot", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [], rowCount: 0 });
+    await store.updateIfSnapshot("t1", "task-1", { title: "Updated" }, {
+      status: "pending", updatedAt: "2026-01-01T00:00:00.000Z", ownerType: "user", ownerId: "user-1",
+      workspaceId: null, projectId: null,
+    });
+    const [sql, params] = mockQuery.mock.calls[0] as unknown as [string, unknown[]];
+    expect(sql).toContain("workspace_id IS NOT DISTINCT FROM");
+    expect(params).toEqual(expect.arrayContaining([null]));
+  });
+
   it("lets only one caller update the same snapshot", async () => {
     const store = new PostgreSQLTaskStore({ pool });
     mockQuery
@@ -284,4 +322,23 @@ describe("PostgreSQLTaskStore.create", () => {
     )).resolves.toBeNull();
   });
 
+  it("queries exact dependents with strict bounds and deterministic ordering", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [fullRow("dependent-c"), fullRow("dependent-b")] });
+    const query = { tenantId: "t1", workspaceId: "workspace-1", projectId: "project-1", dependencyTaskId: "dependency-1", statuses: ["pending", "interrupted"], limit: 2, offset: 0 } as const;
+
+    expect((await store.listDependents(query)).map(({ id }) => id)).toEqual(["dependent-c", "dependent-b"]);
+    expect(mockQuery).toHaveBeenCalledWith(expect.stringMatching(/dependencies @> \$4::jsonb[\s\S]+status = ANY\(\$5::text\[\]\)[\s\S]+ORDER BY created_at DESC, id DESC LIMIT \$6 OFFSET \$7/), ["t1", "workspace-1", "project-1", '["dependency-1"]', ["pending", "interrupted"], 2, 0]);
+    await expect(store.listDependents({ ...query, statuses: [] })).rejects.toThrow(RangeError);
+    await expect(store.listDependents({ ...query, statuses: ["unknown"] as never })).rejects.toThrow(RangeError);
+    await expect(store.listDependents({ ...query, limit: 101 })).rejects.toThrow(RangeError);
+  });
+
+  it("uses null-project semantics before deterministic task pagination", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [] });
+    await store.list({ tenantId: "t1", projectId: null, limit: 2, offset: 1 });
+    expect(mockQuery).toHaveBeenCalledWith(expect.stringMatching(/\(project_id IS NULL OR project_id = '' OR project_id = 'default'\)[\s\S]+ORDER BY created_at DESC, id DESC/), ["t1", 2, 1]);
+  });
+
 });

package/src/__tests__/PostgreSQLTaskWorkItemStore.integration.test.ts

@@ -1,4 +1,6 @@
+import { randomUUID } from "node:crypto";
 import { Pool } from "pg";
+import { PostgreSQLTaskWorkItemStore } from "../stores/PostgreSQLTaskWorkItemStore";
 
 const databaseUrl = process.env.TEST_DATABASE_URL;
 const describeIfDatabase = databaseUrl ? describe : describe.skip;
@@ -31,3 +33,75 @@ describeIfDatabase("PostgreSQLTaskWorkItemStore pending key grammar", () => {
     ]);
   });
 });
+
+describeIfDatabase("PostgreSQLTaskWorkItemStore lifecycle pagination", () => {
+  let adminPool: Pool;
+  let pool: Pool;
+  let store: PostgreSQLTaskWorkItemStore;
+  const tenantId = `work-item-pagination-${randomUUID()}`;
+  const schema = `work_item_${randomUUID().replace(/-/g, "")}`;
+
+  beforeAll(async () => {
+    adminPool = new Pool({ connectionString: databaseUrl });
+    await adminPool.query(`CREATE SCHEMA ${schema}`);
+    const poolConfig = { connectionString: databaseUrl, options: `-c search_path=${schema}` };
+    pool = new Pool(poolConfig);
+    store = new PostgreSQLTaskWorkItemStore({ poolConfig, autoMigrate: false });
+    await store.initialize();
+  });
+
+  afterEach(async () => {
+    await pool.query("DELETE FROM lattice_task_work_items WHERE tenant_id = $1 OR tenant_id = $2", [tenantId, `${tenantId}-other`]);
+  });
+
+  afterAll(async () => {
+    await store.dispose();
+    await pool.end();
+    await adminPool.query(`DROP SCHEMA IF EXISTS ${schema} CASCADE`);
+    await adminPool.end();
+  });
+
+  it("pages same-millisecond events with exact scope and action filters", async () => {
+    const common = { tenantId, actor: "agent:a", workspaceId: "workspace-1", projectId: "project-1" } as const;
+    for (const [taskId, action, eventKey] of [
+      ["task-a", "in_progress", "event:a"],
+      ["task-b", "completed", "event:b"],
+      ["task-c", "in_progress", "event:c"],
+    ] as const) await store.createIfAbsentByEventKey({ ...common, taskId, action, eventKey });
+    await store.createIfAbsentByEventKey({ ...common, taskId: "wrong-action", action: "activity", eventKey: "event:action" });
+    await store.createIfAbsentByEventKey({ ...common, taskId: "wrong-project", action: "completed", eventKey: "event:project", projectId: "project-2" });
+    await store.createIfAbsentByEventKey({ ...common, taskId: "wrong-workspace", action: "completed", eventKey: "event:workspace", workspaceId: "workspace-2" });
+    await store.createIfAbsentByEventKey({ ...common, taskId: "wrong-tenant", action: "completed", eventKey: "event:tenant", tenantId: `${tenantId}-other` });
+    await pool.query(
+      `UPDATE lattice_task_work_items
+       SET id = CASE task_id WHEN 'task-a' THEN 'event-a' WHEN 'task-b' THEN 'event-b' ELSE 'event-c' END,
+           created_at = '2026-01-02T00:00:00.123Z'
+       WHERE tenant_id = $1 AND task_id IN ('task-a', 'task-b', 'task-c')`,
+      [tenantId],
+    );
+    const query = { tenantId, workspaceId: "workspace-1", projectId: "project-1", actions: ["in_progress", "completed"], limit: 2 } as const;
+
+    const page1 = await store.listProjectLifecycleEvents(query);
+    const page2 = await store.listProjectLifecycleEvents({ ...query, before: { createdAt: page1[1].createdAt, id: page1[1].id } });
+
+    expect(page1.map(({ id }) => id)).toEqual(["event-c", "event-b"]);
+    expect(page2.map(({ id }) => id)).toEqual(["event-a"]);
+    expect(page1.every(({ createdAt }) => createdAt.toISOString().endsWith(".123Z"))).toBe(true);
+  });
+
+  it("serves immediate pending evidence and Project lifecycle history from one migrated table", async () => {
+    const common = { tenantId, taskId: "combined-task", workspaceId: "workspace-1", projectId: "project-1" } as const;
+    await store.createIfAbsentByEventKey({
+      ...common, eventKey: "execution-result:ordinary-thread", action: "execution_result", actor: "agent:worker",
+    });
+    await store.createIfAbsentByEventKey({
+      ...common, eventKey: "project-completed:combined-task", action: "completed", actor: "agent:project-worker",
+    });
+
+    await expect(store.listPendingExecutionResults({ tenantId, taskId: common.taskId, limit: 10 }))
+      .resolves.toEqual([expect.objectContaining({ eventKey: "execution-result:ordinary-thread" })]);
+    await expect(store.listProjectLifecycleEvents({
+      tenantId, workspaceId: common.workspaceId, projectId: common.projectId, actions: ["completed"], limit: 10,
+    })).resolves.toEqual([expect.objectContaining({ eventKey: "project-completed:combined-task" })]);
+  });
+});

package/src/__tests__/PostgreSQLTaskWorkItemStore.migrations.test.ts

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it } from "@jest/globals";
+
+const recordedMigrationNames: string[] = [];
+const clientSql: string[] = [];
+
+jest.mock("pg", () => {
+  const client = {
+    query: async (sql: string, params?: unknown[]) => {
+      clientSql.push(sql);
+      if (sql.includes("information_schema.tables")) return { rows: [{ exists: true }] };
+      if (sql.includes("pg_index")) return { rows: [] };
+      if (sql.includes("INSERT INTO lattice_schema_migrations")) {
+        recordedMigrationNames.push(params?.[0] as string);
+      }
+      return { rows: [] };
+    },
+    release: () => undefined,
+  };
+  const pool = {
+    connect: async () => client,
+    query: async () => ({ rows: [] }),
+    end: async () => undefined,
+  };
+  return { Pool: function Pool() { return pool; } };
+});
+
+import { PostgreSQLTaskWorkItemStore } from "../stores/PostgreSQLTaskWorkItemStore";
+
+describe("PostgreSQLTaskWorkItemStore standalone migrations", () => {
+  beforeEach(() => {
+    recordedMigrationNames.length = 0;
+    clientSql.length = 0;
+  });
+
+  it("applies the complete work-item migration chain", async () => {
+    const store = new PostgreSQLTaskWorkItemStore({
+      poolConfig: "postgres://unused",
+      autoMigrate: false,
+    });
+
+    await store.initialize();
+
+    expect(recordedMigrationNames).toEqual([
+      "create_task_work_items_table",
+      "add_task_work_item_project_fields",
+      "add_task_work_item_event_key",
+      "add_task_work_item_pending_indexes",
+      "add_project_lifecycle_event_index",
+    ]);
+    expect(clientSql.find((sql) => sql.includes("information_schema.tables")))
+      .toContain("table_schema = current_schema()");
+    expect(clientSql.some((sql) => sql.includes("CREATE TABLE IF NOT EXISTS lattice_task_work_items"))).toBe(true);
+    expect(clientSql.some((sql) => sql.includes(
+      "created_at TIMESTAMPTZ NOT NULL DEFAULT date_trunc('milliseconds', clock_timestamp())",
+    ))).toBe(true);
+    expect(clientSql.some((sql) => sql.includes(
+      "SET created_at = date_trunc('milliseconds', created_at)",
+    ))).toBe(true);
+    expect(clientSql.some((sql) => sql.includes("idx_task_work_items_project_lifecycle"))).toBe(true);
+    await store.dispose();
+  });
+});

package/src/__tests__/PostgreSQLTaskWorkItemStore.test.ts

@@ -1,6 +1,7 @@
 import type { Pool } from "pg";
 import { PostgreSQLTaskWorkItemStore } from "../stores/PostgreSQLTaskWorkItemStore";
 import {
+  addProjectLifecycleEventIndex,
   addTaskWorkItemEventKeyMigration,
   addTaskWorkItemPendingIndexesMigration,
 } from "../migrations/task_work_items_migration";
@@ -13,6 +14,10 @@ describe("PostgreSQLTaskWorkItemStore", () => {
     created_at: "2026-01-01T00:00:00.000Z",
   };
 
+  it("requires a pool or connection configuration", () => {
+    expect(() => new PostgreSQLTaskWorkItemStore({})).toThrow("Either pool or poolConfig must be provided");
+  });
+
   it.each([
     [undefined, "ASC"],
     ["asc", "ASC"],
@@ -77,6 +82,25 @@ describe("PostgreSQLTaskWorkItemStore", () => {
     expect(result[0].eventKey).toBeUndefined();
   });
 
+  it.each([null, [], "legacy", 1] as const)("maps non-object detail %p to undefined", async (detail) => {
+    const query = jest.fn().mockResolvedValue({ rows: [{ ...row, detail }] });
+    const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+
+    const result = await store.list({ tenantId: "tenant-1", taskId: "task-1" });
+
+    expect(result[0].detail).toBeUndefined();
+  });
+
+  it("preserves plain-object detail", async () => {
+    const detail = { markdown: "status" };
+    const query = jest.fn().mockResolvedValue({ rows: [{ ...row, detail }] });
+    const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+
+    const result = await store.list({ tenantId: "tenant-1", taskId: "task-1" });
+
+    expect(result[0].detail).toEqual(detail);
+  });
+
   it("atomically inserts by task-scoped event key or returns the existing row", async () => {
     const query = jest.fn().mockResolvedValue({ rows: [row] });
     const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
@@ -92,6 +116,49 @@ describe("PostgreSQLTaskWorkItemStore", () => {
       expect.arrayContaining(["tenant-1", "task-1", "evidence:key"]),
     );
     expect(result.eventKey).toBe("evidence:key");
+    expect(query).toHaveBeenCalledWith(
+      expect.stringMatching(/created_at[\s\S]+date_trunc\('milliseconds', clock_timestamp\(\)\)/),
+      expect.any(Array),
+    );
+  });
+
+  it("creates ordinary work items with an explicit millisecond timestamp", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [row] });
+    const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+
+    await store.create({ tenantId: "tenant-1", taskId: "task-1", action: "activity", actor: "agent:a" });
+
+    expect(query).toHaveBeenCalledWith(
+      expect.stringMatching(/created_at[\s\S]+date_trunc\('milliseconds', clock_timestamp\(\)\)/),
+      expect.any(Array),
+    );
+  });
+
+  it("atomically inserts activity from an exact task snapshot", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [row] });
+    const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+    const snapshot = {
+      status: "in_progress" as const, updatedAt: "2026-01-01T00:00:00.000Z", ownerType: "agent" as const,
+      ownerId: "agent-1", workspaceId: "workspace-1", projectId: "project-1",
+    };
+    await store.createIfTaskSnapshot({
+      tenantId: "tenant-1", taskId: "task-1", action: "activity", actor: "agent:agent-1",
+      workspaceId: "workspace-1", projectId: "project-1",
+    }, snapshot);
+    expect(query).toHaveBeenCalledWith(
+      expect.stringMatching(/INSERT INTO lattice_task_work_items[\s\S]+SELECT[\s\S]+FROM lattice_tasks[\s\S]+status = [\s\S]+updated_at[\s\S]+owner_type = [\s\S]+owner_id = [\s\S]+workspace_id IS NOT DISTINCT FROM[\s\S]+project_id IS NOT DISTINCT FROM[\s\S]+RETURNING/),
+      expect.arrayContaining(["tenant-1", "task-1", "in_progress", snapshot.updatedAt, "agent", "agent-1", "workspace-1", "project-1"]),
+    );
+  });
+
+  it("uses null-safe scope predicates for nonproject activity", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [] });
+    const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+    await store.createIfTaskSnapshot({ tenantId: "tenant-1", taskId: "task-1", action: "activity", actor: "user:user-1" }, {
+      status: "pending", updatedAt: "2026-01-01T00:00:00.000Z", ownerType: "user", ownerId: "user-1",
+      workspaceId: null, projectId: null,
+    });
+    expect(query).toHaveBeenCalledWith(expect.stringContaining("workspace_id IS NOT DISTINCT FROM"), expect.arrayContaining([null]));
   });
 
   it("uses one bounded deterministic anti-join with C-collated ASCII keys that reject non-ASCII", async () => {
@@ -166,4 +233,33 @@ describe("PostgreSQLTaskWorkItemStore", () => {
       /\(tenant_id, task_id, \(detail ->> 'executionResultId'\)\)[\s\S]+WHERE action = 'execution_reconciled'/,
     ));
   });
+
+  it("queries project lifecycle events with strict bounds and exclusive cursor", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [{ ...row, id: "event-c", action: "completed", workspace_id: "workspace-1", project_id: "project-1" }] });
+    const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+    const before = { createdAt: new Date("2026-01-02T00:00:00.000Z"), id: "event-b" };
+    const request = { tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", actions: ["in_progress", "completed"], before, limit: 2 } as const;
+
+    await expect(store.listProjectLifecycleEvents(request)).resolves.toHaveLength(1);
+    expect(query).toHaveBeenCalledWith(expect.stringMatching(/action = ANY\(\$4::text\[\]\)[\s\S]+event_key IS NOT NULL AND event_key <> ''[\s\S]+created_at < \$5::timestamptz[\s\S]+id < \$6[\s\S]+ORDER BY created_at DESC, id DESC LIMIT \$7/), ["tenant-1", "workspace-1", "project-1", ["in_progress", "completed"], before.createdAt, "event-b", 2]);
+    await expect(store.listProjectLifecycleEvents({ ...request, actions: [] })).rejects.toThrow(RangeError);
+    await expect(store.listProjectLifecycleEvents({ ...request, actions: ["unknown"] as never })).rejects.toThrow(RangeError);
+    await expect(store.listProjectLifecycleEvents({ ...request, limit: 101 })).rejects.toThrow(RangeError);
+  });
+
+  it("rejects malformed lifecycle event outer rows", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [{ ...row, id: "", workspace_id: "workspace-1", project_id: "project-1" }] });
+    const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+    await expect(store.listProjectLifecycleEvents({ tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", actions: ["completed"], limit: 10 }))
+      .rejects.toThrow("Invalid project lifecycle event row");
+  });
+
+  it("creates the project lifecycle event index", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [] });
+    await addProjectLifecycleEventIndex.up({ query } as never);
+    expect(query.mock.calls[0][0]).toMatch(
+      /UPDATE lattice_task_work_items\s+SET created_at = date_trunc\('milliseconds', created_at\)/,
+    );
+    expect(query).toHaveBeenCalledWith(expect.stringMatching(/created_at DESC,\s*id DESC[\s\S]+WHERE event_key IS NOT NULL/));
+  });
 });

package/src/__tests__/ThreadMessageQueueStore.migrations.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import type { PoolClient } from "pg";
+
+const registeredMigrationNames: string[] = [];
+
+jest.mock("@axiom-lattice/core", () => ({}));
+jest.mock("pg", () => ({ Pool: class Pool {} }));
+jest.mock("../migrations/migration", () => ({
+  MigrationManager: class MigrationManager {
+    register(migration: { name: string }): void {
+      registeredMigrationNames.push(migration.name);
+    }
+    async migrate(): Promise<void> {
+      throw new Error("stop after migrations");
+    }
+  },
+}));
+
+import { createPgStoreConfig } from "../createPgStoreConfig";
+import { addTrustedRunContextColumn } from "../migrations/add_trusted_run_context_column";
+import { ThreadMessageQueueStore } from "../stores/ThreadMessageQueueStore";
+
+function normalizeSql(sql: string): string {
+  return sql.replace(/\s+/g, " ").trim();
+}
+
+describe("thread queue trusted context migration", () => {
+  it("uses the reserved identity and is centrally registered exactly once", async () => {
+    expect(addTrustedRunContextColumn.version).toBe(173);
+    expect(addTrustedRunContextColumn.name).toBe("add_thread_queue_trusted_run_context");
+    registeredMigrationNames.length = 0;
+
+    await expect(createPgStoreConfig("postgres://unused")).rejects.toThrow("stop after migrations");
+
+    expect(registeredMigrationNames.filter((name) => name === addTrustedRunContextColumn.name)).toHaveLength(1);
+  });
+
+  it("registers the migration in the standalone queue store", () => {
+    registeredMigrationNames.length = 0;
+
+    new ThreadMessageQueueStore({ poolConfig: { connectionString: "postgres://unused" }, autoMigrate: false });
+
+    expect(registeredMigrationNames.filter((name) => name === addTrustedRunContextColumn.name)).toHaveLength(1);
+  });
+
+  it("adds and removes both durable columns", async () => {
+    const statements: string[] = [];
+    const client = { query: async (sql: string) => {
+      statements.push(normalizeSql(sql));
+      return { rows: [] };
+    } } as unknown as PoolClient;
+
+    await addTrustedRunContextColumn.up(client);
+    expect(statements.join(" ")).toContain("ADD COLUMN IF NOT EXISTS trusted_run_context JSONB");
+    expect(statements.join(" ")).toContain("ADD COLUMN IF NOT EXISTS execution_mode VARCHAR(20)");
+    expect(statements.join(" ")).toContain("execution_mode IS NULL OR execution_mode = 'followup'");
+
+    statements.length = 0;
+    await addTrustedRunContextColumn.down?.(client);
+    expect(statements.join(" ")).toContain("DROP COLUMN IF EXISTS execution_mode");
+    expect(statements.join(" ")).toContain("DROP COLUMN IF EXISTS trusted_run_context");
+  });
+});