@axiom-lattice/pg-stores 3.1.0 → 3.1.2

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

@@ -0,0 +1,107 @@
+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;
+
+describeIfDatabase("PostgreSQLTaskWorkItemStore pending key grammar", () => {
+  let pool: Pool;
+
+  beforeAll(() => {
+    pool = new Pool({ connectionString: databaseUrl });
+  });
+
+  afterAll(async () => {
+    await pool.end();
+  });
+
+  it("uses C collation to accept canonical ASCII and reject non-ASCII keys", async () => {
+    const result = await pool.query<{ event_key: string }>(
+      `SELECT event_key
+       FROM (VALUES
+         ('execution-result:ascii-._:09'),
+         ('execution-result:cafeé'),
+         ('execution-result:任务')
+       ) AS candidates(event_key)
+       WHERE event_key COLLATE "C" ~ '^execution-result:[A-Za-z0-9._:-]+$'
+       ORDER BY event_key COLLATE "C"`,
+    );
+
+    expect(result.rows.map((row) => row.event_key)).toEqual([
+      "execution-result:ascii-._:09",
+    ]);
+  });
+});
+
+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,10 @@
 import type { Pool } from "pg";
 import { PostgreSQLTaskWorkItemStore } from "../stores/PostgreSQLTaskWorkItemStore";
-import { addTaskWorkItemEventKeyMigration } from "../migrations/task_work_items_migration";
+import {
+  addProjectLifecycleEventIndex,
+  addTaskWorkItemEventKeyMigration,
+  addTaskWorkItemPendingIndexesMigration,
+} from "../migrations/task_work_items_migration";
 
 describe("PostgreSQLTaskWorkItemStore", () => {
   const row = {
@@ -10,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"],
@@ -74,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);
@@ -89,6 +116,96 @@ 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 () => {
+    const pendingRows = [
+      { ...row, id: "item-3", event_key: "execution-result:c", action: "execution_result" },
+      { ...row, id: "item-1", event_key: "execution-result:a", action: "execution_result" },
+    ];
+    const query = jest.fn().mockResolvedValue({ rows: pendingRows });
+    const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+
+    const result = await store.listPendingExecutionResults({
+      tenantId: "tenant-1", taskId: "task-1", limit: 2,
+    });
+
+    expect(query).toHaveBeenCalledTimes(1);
+    expect(query).toHaveBeenCalledWith(
+      expect.stringMatching(
+        /action = 'execution_result'[\s\S]+event_key COLLATE "C" ~ '\^execution-result:\[A-Za-z0-9\._:-\]\+\$'[\s\S]+NOT EXISTS[\s\S]+reconciled\.detail ->> 'executionResultId' = result\.event_key[\s\S]+ORDER BY result\.created_at DESC, result\.id DESC[\s\S]+LIMIT \$3/,
+      ),
+      ["tenant-1", "task-1", 2],
+    );
+    expect(result.map((item) => item.eventKey)).toEqual([
+      "execution-result:c", "execution-result:a",
+    ]);
+  });
+
+  it.each([-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, Number.MAX_SAFE_INTEGER + 1, 1_001])(
+    "rejects invalid pending execution result limit %s",
+    async (limit) => {
+      const query = jest.fn();
+      const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+
+      await expect(store.listPendingExecutionResults({
+        tenantId: "tenant-1", taskId: "task-1", limit,
+      })).rejects.toMatchObject({ name: "RangeError", code: "INVALID_LIMIT" });
+      expect(query).not.toHaveBeenCalled();
+    },
+  );
+
+  it("returns no pending execution results for limit zero without querying", async () => {
+    const query = jest.fn();
+    const store = new PostgreSQLTaskWorkItemStore({ query } as unknown as Pool);
+
+    await expect(store.listPendingExecutionResults({
+      tenantId: "tenant-1", taskId: "task-1", limit: 0,
+    })).resolves.toEqual([]);
+    expect(query).not.toHaveBeenCalled();
   });
 
   it("migrates a task-scoped unique event key", async () => {
@@ -101,4 +218,48 @@ describe("PostgreSQLTaskWorkItemStore", () => {
       "(tenant_id, task_id, event_key) WHERE event_key IS NOT NULL",
     ));
   });
+
+  it("adds ordered pending and partial reconciliation indexes in a new migration", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [] });
+
+    await addTaskWorkItemPendingIndexesMigration.up({ query } as never);
+
+    expect(addTaskWorkItemPendingIndexesMigration.version)
+      .toBeGreaterThan(addTaskWorkItemEventKeyMigration.version);
+    expect(query).toHaveBeenCalledWith(expect.stringContaining(
+      "(tenant_id, task_id, action, created_at DESC, id DESC)",
+    ));
+    expect(query).toHaveBeenCalledWith(expect.stringMatching(
+      /\(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");
+  });
+});