@axiom-lattice/pg-stores 2.0.9 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "2.0.9",
+  "version": "3.0.0",
   "description": "PG stores implementation for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,8 +25,8 @@
     "@langchain/core": "1.1.30",
     "pg": "^8.16.3",
     "uuid": "^9.0.1",
-    "@axiom-lattice/core": "3.1.1",
-    "@axiom-lattice/protocols": "3.0.4"
+    "@axiom-lattice/core": "4.0.0",
+    "@axiom-lattice/protocols": "4.0.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

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

@@ -0,0 +1,76 @@
+/**
+ * Standalone-migration tests for PostgreSQLA2AApiKeyStore.
+ *
+ * When the store is constructed with its own `poolConfig` (no shared pool from
+ * `createPgStoreConfig`), its private MigrationManager must register every
+ * migration the store's queries depend on — including the `assistant_ids`
+ * column added after the original table creation.
+ */
+
+import { describe, expect, it, beforeEach } from "@jest/globals";
+
+const mockRecordedMigrationNames: string[] = [];
+const mockClientSql: string[] = [];
+
+jest.mock("@axiom-lattice/core", () => ({
+  encrypt: (value: string) => `enc:${value}`,
+  decrypt: (value: string) => value.replace(/^enc:/, ""),
+}));
+
+jest.mock("pg", () => {
+  const client = {
+    query: async (sql: string, params?: unknown[]) => {
+      mockClientSql.push(sql);
+      if (sql.includes("information_schema.tables")) {
+        return { rows: [{ exists: true }] };
+      }
+      if (sql.includes("pg_index")) {
+        // PK already on `name` — no legacy schema migration needed.
+        return { rows: [] };
+      }
+      if (sql.includes("INSERT INTO lattice_schema_migrations")) {
+        mockRecordedMigrationNames.push(params?.[0] as string);
+        return { rows: [] };
+      }
+      if (sql.includes("FROM lattice_schema_migrations")) {
+        return { rows: [] };
+      }
+      return { rows: [] };
+    },
+    release: () => undefined,
+  };
+  const pool = {
+    connect: async () => client,
+    query: async () => ({ rows: [] }),
+    end: async () => undefined,
+  };
+  return { Pool: function Pool() { return pool; } };
+});
+
+import { PostgreSQLA2AApiKeyStore } from "../stores/PostgreSQLA2AApiKeyStore";
+
+describe("PostgreSQLA2AApiKeyStore standalone migrations", () => {
+  beforeEach(() => {
+    mockRecordedMigrationNames.length = 0;
+    mockClientSql.length = 0;
+  });
+
+  it("registers and applies both the table and assistant_ids migrations", async () => {
+    const store = new PostgreSQLA2AApiKeyStore({
+      poolConfig: "postgres://unused",
+      autoMigrate: false,
+    });
+
+    await store.initialize();
+
+    expect(mockRecordedMigrationNames).toEqual([
+      "create_a2a_api_keys_table",
+      "add_a2a_key_assistant_ids",
+    ]);
+    expect(
+      mockClientSql.some((sql) => sql.includes("ADD COLUMN IF NOT EXISTS assistant_ids")),
+    ).toBe(true);
+
+    await store.dispose();
+  });
+});

package/src/__tests__/PostgreSQLA2AApiKeyStore.test.ts

@@ -0,0 +1,133 @@
+/**
+ * PostgreSQLA2AApiKeyStore behavior tests
+ *
+ * Verifies the store aligns with the new A2A key scope model:
+ * - projectId is required (written directly, no null fallback)
+ * - assistantIds is persisted as JSONB and projected back
+ * - workspaceId is no longer read or written
+ */
+
+import { describe, expect, it, jest, beforeEach } from "@jest/globals";
+import type { Pool } from "pg";
+
+const mockQuery = jest.fn();
+
+jest.mock("@axiom-lattice/core", () => ({
+  encrypt: (value: string) => `enc:${value}`,
+  decrypt: (value: string) => value.replace(/^enc:/, ""),
+}));
+
+import { PostgreSQLA2AApiKeyStore } from "../stores/PostgreSQLA2AApiKeyStore";
+
+describe("PostgreSQLA2AApiKeyStore", () => {
+  const pool = { query: mockQuery } as unknown as Pool;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("create writes assistant_ids and project_id, omits workspace_id", async () => {
+    const store = new PostgreSQLA2AApiKeyStore({ pool });
+    mockQuery.mockResolvedValueOnce({
+      rows: [{
+        id: "k1",
+        key_value: "enc:a2a_x",
+        tenant_id: "t1",
+        project_id: "p1",
+        assistant_ids: ["a1", "a2"],
+        label: "lbl",
+        enabled: true,
+        created_at: new Date("2026-01-01T00:00:00.000Z"),
+        updated_at: new Date("2026-01-01T00:00:00.000Z"),
+      }],
+    });
+
+    const record = await store.create({
+      tenantId: "t1",
+      projectId: "p1",
+      assistantIds: ["a1", "a2"],
+      label: "lbl",
+    });
+
+    const [sql, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+    expect(sql).toContain("assistant_ids");
+    expect(sql).not.toContain("workspace_id");
+    expect(params[2]).toBe("p1");
+    expect(params[3]).toBe(JSON.stringify(["a1", "a2"]));
+    expect(record.projectId).toBe("p1");
+    expect(record.assistantIds).toEqual(["a1", "a2"]);
+    expect("workspaceId" in record).toBe(false);
+  });
+
+  it("create stores null assistant_ids when not provided", async () => {
+    const store = new PostgreSQLA2AApiKeyStore({ pool });
+    mockQuery.mockResolvedValueOnce({
+      rows: [{
+        id: "k2",
+        key_value: "enc:a2a_y",
+        tenant_id: "t1",
+        project_id: "p1",
+        assistant_ids: null,
+        label: null,
+        enabled: true,
+        created_at: new Date("2026-01-01T00:00:00.000Z"),
+        updated_at: new Date("2026-01-01T00:00:00.000Z"),
+      }],
+    });
+
+    const record = await store.create({ tenantId: "t1", projectId: "p1" });
+
+    const [, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+    expect(params[3]).toBe(null);
+    expect(record.assistantIds).toBeUndefined();
+  });
+
+  it("findById returns the matching key record", async () => {
+    const store = new PostgreSQLA2AApiKeyStore({ pool });
+    mockQuery.mockResolvedValueOnce({
+      rows: [{
+        id: "k1",
+        key_value: "enc:a2a_x",
+        tenant_id: "t1",
+        project_id: "p1",
+        assistant_ids: null,
+        label: null,
+        enabled: true,
+        created_at: new Date("2026-01-01T00:00:00.000Z"),
+        updated_at: new Date("2026-01-01T00:00:00.000Z"),
+      }],
+    });
+
+    const record = await store.findById("k1");
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringContaining("WHERE id = $1"),
+      ["k1"],
+    );
+    expect(record?.tenantId).toBe("t1");
+  });
+
+  it("loadIntoMap projects assistantIds and omits workspaceId", async () => {
+    const store = new PostgreSQLA2AApiKeyStore({ pool });
+    mockQuery.mockResolvedValueOnce({
+      rows: [{
+        id: "k1",
+        key_value: "enc:a2a_x",
+        tenant_id: "t1",
+        project_id: "p1",
+        assistant_ids: ["a1"],
+        label: null,
+        enabled: true,
+        created_at: new Date("2026-01-01T00:00:00.000Z"),
+        updated_at: new Date("2026-01-01T00:00:00.000Z"),
+      }],
+    });
+
+    const map = await store.loadIntoMap();
+    const entry = map.get("a2a_x");
+    expect(entry).toBeDefined();
+    expect(entry?.projectId).toBe("p1");
+    expect(entry?.assistantIds).toEqual(["a1"]);
+    expect("workspaceId" in (entry ?? {})).toBe(false);
+  });
+});

package/src/__tests__/PostgreSQLChannelInstallationStore.test.ts

@@ -1,4 +1,5 @@
 import { PostgreSQLChannelInstallationStore } from "../stores/PostgreSQLChannelInstallationStore";
+import type { Pool } from "pg";
 
 const mockQuery = jest.fn();
 
@@ -20,8 +21,7 @@ describe("PostgreSQLChannelInstallationStore", () => {
 
   it("retrieves and decrypts an installation by id", async () => {
     const store = new PostgreSQLChannelInstallationStore({
-      poolConfig: "postgres://test:test@localhost:5432/test",
-      autoMigrate: false,
+      pool: { query: mockQuery } as unknown as Pool,
     });
 
     mockQuery.mockResolvedValueOnce({
@@ -51,4 +51,39 @@ describe("PostgreSQLChannelInstallationStore", () => {
     expect(installation?.config.appSecret).toBe("secret");
     expect(installation?.config.verificationToken).toBe("token-1");
   });
+
+  it("rejects a duplicate id without changing the original installation", async () => {
+    const store = new PostgreSQLChannelInstallationStore({
+      pool: { query: mockQuery } as unknown as Pool,
+    });
+    const originalRow = {
+      id: "install-1",
+      tenant_id: "tenant-a",
+      channel: "lark",
+      name: "Original",
+      config: { appId: "app-1", appSecret: "enc:secret-1" },
+      enabled: true,
+      fallback_agent_id: null,
+      reject_when_no_binding: true,
+      created_at: new Date("2026-04-10T00:00:00.000Z"),
+      updated_at: new Date("2026-04-10T00:00:00.000Z"),
+    };
+    const duplicateError = Object.assign(new Error("duplicate key value violates unique constraint"), {
+      code: "23505",
+    });
+    mockQuery.mockRejectedValueOnce(duplicateError).mockResolvedValueOnce({ rows: [originalRow] });
+
+    await expect(
+      store.createInstallation("tenant-a", "install-1", {
+        channel: "lark",
+        name: "Replacement",
+        config: { appId: "app-2", appSecret: "secret-2" },
+      }),
+    ).rejects.toMatchObject({ code: "23505" });
+    await expect(store.getInstallationById("install-1")).resolves.toMatchObject({
+      id: "install-1",
+      name: "Original",
+      config: { appId: "app-1", appSecret: "secret-1" },
+    });
+  });
 });

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

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+import { Pool } from "pg";
+import { PostgreSQLTaskStore } from "../stores/PostgreSQLTaskStore";
+
+const databaseUrl = process.env.TEST_DATABASE_URL;
+const describeIfDatabase = databaseUrl ? describe : describe.skip;
+const CANONICAL_UTC_MILLIS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+describeIfDatabase("PostgreSQLTaskStore timestamp contract", () => {
+  let pool: Pool;
+  let store: PostgreSQLTaskStore;
+  const tenantId = `timestamp-contract-${randomUUID()}`;
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    store = new PostgreSQLTaskStore({ poolConfig: databaseUrl });
+    await store.initialize();
+  });
+
+  afterEach(async () => {
+    await pool.query("DELETE FROM lattice_tasks WHERE tenant_id = $1", [tenantId]);
+  });
+
+  afterAll(async () => {
+    await store.dispose();
+    await pool.end();
+  });
+
+  it("updates canonical VARCHAR timestamps monotonically as UTC ISO text", async () => {
+    const task = await store.create({
+      tenantId,
+      ownerType: "user",
+      ownerId: "user-1",
+      title: "Canonical timestamp",
+    });
+
+    const updated = await store.update(tenantId, task.id, { metadata: { trainingRound: true } });
+    const row = await pool.query<{ updated_at: string }>(
+      "SELECT updated_at FROM lattice_tasks WHERE tenant_id = $1 AND id = $2",
+      [tenantId, task.id],
+    );
+
+    expect(updated!.updatedAt.getTime()).toBeGreaterThan(task.updatedAt.getTime());
+    expect(row.rows[0].updated_at).toMatch(CANONICAL_UTC_MILLIS);
+  });
+
+  it("repairs shape-valid impossible and plainly malformed timestamps without cast errors", async () => {
+    const task = await store.create({
+      tenantId,
+      ownerType: "user",
+      ownerId: "user-1",
+      title: "Repair timestamp",
+    });
+
+    for (const malformed of ["2026-99-99T00:00:00.000Z", "not-a-date"]) {
+      await pool.query(
+        "UPDATE lattice_tasks SET updated_at = $1 WHERE tenant_id = $2 AND id = $3",
+        [malformed, tenantId, task.id],
+      );
+
+      await expect(store.update(tenantId, task.id, { metadata: { repaired: malformed } })).resolves.toBeTruthy();
+      const row = await pool.query<{ updated_at: string }>(
+        "SELECT updated_at FROM lattice_tasks WHERE tenant_id = $1 AND id = $2",
+        [tenantId, task.id],
+      );
+      expect(row.rows[0].updated_at).toMatch(CANONICAL_UTC_MILLIS);
+    }
+  });
+
+  it("makes snapshot CAS safely miss malformed stored timestamps", async () => {
+    const task = await store.create({
+      tenantId,
+      ownerType: "user",
+      ownerId: "user-1",
+      title: "Malformed snapshot",
+    });
+    await pool.query(
+      "UPDATE lattice_tasks SET updated_at = $1 WHERE tenant_id = $2 AND id = $3",
+      ["2026-02-31T00:00:00.000Z", tenantId, task.id],
+    );
+
+    await expect(store.updateIfStatusAndUpdatedAt(
+      tenantId,
+      task.id,
+      { description: "must not write" },
+      ["pending"],
+      task.updatedAt,
+    )).resolves.toBeNull();
+  });
+});

package/src/__tests__/PostgreSQLTaskStore.test.ts

@@ -0,0 +1,287 @@
+/**
+ * PostgreSQLTaskStore.create tests
+ *
+ * Verifies create() honors a caller-provided id (single-ID mapping
+ * with external systems such as A2A) and falls back to a generated
+ * UUID when omitted.
+ */
+
+import { describe, expect, it, jest, beforeEach } from "@jest/globals";
+import type { Pool } from "pg";
+
+const mockQuery = jest.fn();
+
+import { PostgreSQLTaskStore } from "../stores/PostgreSQLTaskStore";
+
+const fullRow = (id: string) => ({
+  id,
+  tenant_id: "t1",
+  owner_type: "agent",
+  owner_id: "owner-1",
+  title: "t",
+  description: null,
+  status: "pending",
+  priority: "medium",
+  due_date: null,
+  metadata: null,
+  parent_id: null,
+  source_id: null,
+  context: null,
+  require_review: null,
+  dependencies: null,
+  result: null,
+  failure_reason: null,
+  workspace_id: null,
+  project_id: null,
+  files: null,
+  created_at: "2026-01-01T00:00:00.000Z",
+  updated_at: "2026-01-01T00:00:00.000Z",
+});
+
+describe("PostgreSQLTaskStore.create", () => {
+  const pool = { query: mockQuery } as unknown as Pool;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("honors a caller-provided id", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery
+      .mockResolvedValueOnce({ rows: [] }) // INSERT
+      .mockResolvedValueOnce({ rows: [fullRow("a2a-task-1")] }); // getById
+
+    const result = await store.create({
+      id: "a2a-task-1",
+      tenantId: "t1",
+      ownerType: "agent",
+      ownerId: "owner-1",
+      title: "t",
+    });
+
+    expect(result.id).toBe("a2a-task-1");
+    const insertParams = mockQuery.mock.calls[0][1] as unknown[];
+    expect(insertParams[0]).toBe("a2a-task-1");
+  });
+
+  it("generates a uuid when id is omitted", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery
+      .mockResolvedValueOnce({ rows: [] }) // INSERT
+      .mockResolvedValueOnce({ rows: [fullRow("some-uuid")] }); // getById
+
+    await store.create({
+      tenantId: "t1",
+      ownerType: "agent",
+      ownerId: "owner-1",
+      title: "t",
+    });
+
+    const insertParams = mockQuery.mock.calls[0][1] as unknown[];
+    expect(insertParams[0]).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
+  });
+
+  it("uses one conditional UPDATE that blocks current statuses", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 });
+
+    const result = await store.updateIfStatusNotIn(
+      "t1",
+      "task-1",
+      { status: "completed", result: "done" },
+      ["cancelled"],
+    );
+
+    expect(result?.id).toBe("task-1");
+    expect(mockQuery).toHaveBeenCalledTimes(1);
+    const [sql, params] = mockQuery.mock.calls[0] as unknown as [string, unknown[]];
+    expect(sql).toContain("status <> ALL");
+    expect(sql).toContain("RETURNING *");
+    expect(params).toContainEqual(["cancelled"]);
+    expect(sql).toContain("updated_at::timestamptz + interval '1 millisecond'");
+  });
+
+  it("casts varchar updated_at before interval arithmetic on ordinary metadata updates", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery
+      .mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 })
+      .mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 });
+
+    await store.update("t1", "task-1", { metadata: { trainingRound: true } });
+
+    const updateSql = mockQuery.mock.calls[1][0] as string;
+    expect(updateSql).toContain("updated_at::timestamptz + interval '1 millisecond'");
+    expect(updateSql).toContain("to_char");
+    expect(updateSql).toMatch(/CASE\s+WHEN updated_at ~/);
+    expect(updateSql).toContain("substring(updated_at FROM 6 FOR 2)::integer BETWEEN 1 AND 12");
+    expect(updateSql).toContain("substring(updated_at FROM 9 FOR 2)::integer BETWEEN 1 AND CASE");
+    expect(updateSql).toContain("updated_at <> '9999-12-31T23:59:59.999Z'");
+    expect(updateSql).not.toContain("updated_at + interval '1 millisecond'");
+    expect(updateSql).toContain("RETURNING *");
+  });
+
+  it("returns null when ordinary update cannot advance the maximum timestamp", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery
+      .mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 })
+      .mockResolvedValueOnce({ rows: [], rowCount: 0 });
+
+    await expect(store.update("t1", "task-1", { title: "Cannot advance" })).resolves.toBeNull();
+  });
+
+  it("treats context undefined as an ordinary update no-op", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 });
+
+    const result = await store.update("t1", "task-1", { context: undefined });
+
+    expect(result?.id).toBe("task-1");
+    expect(mockQuery).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns null when the conditional update is blocked", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [], rowCount: 0 });
+
+    await expect(
+      store.updateIfStatusNotIn("t1", "task-1", { status: "completed" }, ["cancelled"]),
+    ).resolves.toBeNull();
+  });
+
+  it("uses one conditional UPDATE restricted to expected statuses", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 });
+
+    await store.updateIfStatusIn(
+      "t1", "task-1", { status: "completed" }, ["in_progress", "interrupted"],
+    );
+
+    expect(mockQuery).toHaveBeenCalledTimes(1);
+    const [sql, params] = mockQuery.mock.calls[0] as unknown as [string, unknown[]];
+    expect(sql).toContain("status = ANY");
+    expect(sql).toContain("RETURNING *");
+    expect(params).toContainEqual(["in_progress", "interrupted"]);
+    expect(sql).toContain("updated_at::timestamptz + interval '1 millisecond'");
+  });
+
+  it("returns null when no expected status matches or the task is missing", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValue({ rows: [], rowCount: 0 });
+
+    await expect(store.updateIfStatusIn(
+      "t1", "task-1", { status: "completed" }, ["in_progress"],
+    )).resolves.toBeNull();
+    await expect(store.updateIfStatusIn(
+      "t1", "missing", { status: "completed" }, ["in_progress"],
+    )).resolves.toBeNull();
+  });
+
+  it("uses one conditional UPDATE restricted to status and updatedAt snapshot", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 });
+    const snapshot = new Date("2026-01-01T00:00:00.000Z");
+
+    const result = await store.updateIfStatusAndUpdatedAt(
+      "t1", "task-1", { status: "completed" }, ["in_progress"], snapshot,
+    );
+
+    expect(result?.id).toBe("task-1");
+    expect(mockQuery).toHaveBeenCalledTimes(1);
+    const [sql, params] = mockQuery.mock.calls[0] as unknown as [string, unknown[]];
+    expect(sql).toContain("status = ANY");
+    expect(sql).toContain("updated_at =");
+    expect(sql).toContain("date_trunc('milliseconds'");
+    expect(sql).toContain("updated_at::timestamptz + interval '1 millisecond'");
+    expect(sql).toMatch(/CASE WHEN CASE\s+WHEN updated_at ~/);
+    expect(sql).toContain("THEN updated_at::timestamptz =");
+    expect(sql).toContain("ELSE FALSE");
+    expect(sql).toContain("RETURNING *");
+    expect(params).toContain(snapshot.toISOString());
+  });
+
+  it("returns null when the status matches but updatedAt snapshot is stale", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [], rowCount: 0 });
+
+    await expect(store.updateIfStatusAndUpdatedAt(
+      "t1", "task-1", { description: "stale overwrite" }, ["in_progress"], "2026-01-01T00:00:00.000Z",
+    )).resolves.toBeNull();
+  });
+
+  it("lets only one caller update the same snapshot", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery
+      .mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 })
+      .mockResolvedValueOnce({ rows: [], rowCount: 0 });
+    const snapshot = "2026-01-01T00:00:00.000Z";
+
+    const [first, second] = await Promise.all([
+      store.updateIfStatusAndUpdatedAt("t1", "task-1", { description: "first" }, ["in_progress"], snapshot),
+      store.updateIfStatusAndUpdatedAt("t1", "task-1", { description: "second" }, ["in_progress"], snapshot),
+    ]);
+
+    expect(first?.id).toBe("task-1");
+    expect(second).toBeNull();
+  });
+
+  it("passes null lifecycle outputs through a snapshot update as SQL NULL", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [fullRow("task-1")], rowCount: 1 });
+
+    await store.updateIfStatusAndUpdatedAt(
+      "t1",
+      "task-1",
+      { result: null, failureReason: null, context: null },
+      ["failed"],
+      "2026-01-01T00:00:00.000Z",
+    );
+
+    const [sql, params] = mockQuery.mock.calls[0] as unknown as [string, unknown[]];
+    expect(sql).toContain("result =");
+    expect(sql).toContain("failure_reason =");
+    expect(sql).toContain("context =");
+    expect(params.filter((value) => value === null)).toHaveLength(3);
+  });
+
+  it("uses one UPDATE with exact child and parent snapshot predicates", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [fullRow("child-1")], rowCount: 1 });
+    const childSnapshot = "2026-01-01T00:00:00.000Z";
+    const parentSnapshot = "2026-01-01T00:00:01.000Z";
+
+    const result = await store.updateIfStatusUpdatedAtAndParentUpdatedAt(
+      "t1", "child-1", { status: "completed" }, ["in_progress"], childSnapshot,
+      "parent-1", parentSnapshot,
+    );
+
+    expect(result?.id).toBe("child-1");
+    expect(mockQuery).toHaveBeenCalledTimes(1);
+    const [sql, params] = mockQuery.mock.calls[0] as unknown as [string, unknown[]];
+    expect(sql).toContain("UPDATE lattice_tasks AS child");
+    expect(sql).toContain("EXISTS");
+    expect(sql).toContain("parent.tenant_id = child.tenant_id");
+    expect(sql).toContain("parent.id =");
+    expect(sql).toContain("child.updated_at::timestamptz + interval '1 millisecond'");
+    expect(sql).toMatch(/CASE WHEN CASE\s+WHEN child\.updated_at ~/);
+    expect(sql).toContain("THEN child.updated_at::timestamptz =");
+    expect(sql).toMatch(/CASE WHEN CASE\s+WHEN parent\.updated_at ~/);
+    expect(sql).toContain("THEN parent.updated_at::timestamptz =");
+    expect(sql.match(/<> '9999-12-31T23:59:59\.999Z'/g)).toHaveLength(2);
+    expect(params).toEqual(expect.arrayContaining([
+      "t1", "child-1", ["in_progress"], childSnapshot, "parent-1", parentSnapshot,
+    ]));
+  });
+
+  it("returns null when the parent snapshot predicate does not match", async () => {
+    const store = new PostgreSQLTaskStore({ pool });
+    mockQuery.mockResolvedValueOnce({ rows: [], rowCount: 0 });
+
+    await expect(store.updateIfStatusUpdatedAtAndParentUpdatedAt(
+      "t1", "child-1", { status: "completed" }, ["in_progress"], "2026-01-01T00:00:00.000Z",
+      "missing-parent", "2026-01-01T00:00:01.000Z",
+    )).resolves.toBeNull();
+  });
+
+});