@axiom-lattice/pg-stores 1.0.74 → 1.0.76

package/jest.config.js

@@ -0,0 +1,19 @@
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  roots: ["<rootDir>/src"],
+  testMatch: ["**/__tests__/**/*.test.ts"],
+  transform: {
+    "^.+\\.ts$": [
+      "ts-jest",
+      {
+        isolatedModules: true,
+      },
+    ],
+  },
+  moduleNameMapper: {
+    "^@axiom-lattice/protocols$": "<rootDir>/../protocols/src/index.ts",
+  },
+  transformIgnorePatterns: [],
+  testTimeout: 10000,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "1.0.74",
+  "version": "1.0.76",
   "description": "PG stores implementation for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -23,7 +23,7 @@
     "@langchain/langgraph-checkpoint-postgres": "1.0.0",
     "pg": "^8.16.3",
     "uuid": "^9.0.1",
-    "@axiom-lattice/core": "2.1.83",
+    "@axiom-lattice/core": "2.1.85",
     "@axiom-lattice/protocols": "2.1.43"
   },
   "devDependencies": {
@@ -38,6 +38,7 @@
     "build": "tsup src/index.ts --format cjs,esm --dts --sourcemap",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "lint": "tsc --noEmit && node scripts/check-migration-versions.mjs",
+    "test": "jest",
     "clean": "rimraf dist"
   }
 }

package/src/__tests__/PostgreSQLWorkflowTrackingStore.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Unit tests for row mapping and safeParse utilities.
+ *
+ * These are pure-function tests — no database required.
+ * They verify that corrupted JSON in stored columns won't crash the API.
+ */
+import { safeParse, mapRowToWorkflowRun, mapRowToRunStep } from "../stores/PostgreSQLWorkflowTrackingStore";
+
+// ─── safeParse ──────────────────────────────────────────────────────────────
+
+describe("safeParse", () => {
+  test("parses valid JSON string", () => {
+    expect(safeParse('{"a":1}', {})).toEqual({ a: 1 });
+  });
+
+  test("parses JSON array", () => {
+    expect(safeParse("[1,2,3]", [])).toEqual([1, 2, 3]);
+  });
+
+  test("returns fallback for invalid JSON", () => {
+    expect(safeParse("not json", {})).toEqual({});
+  });
+
+  test("returns fallback for empty string", () => {
+    expect(safeParse("", [])).toEqual([]);
+  });
+
+  test("returns fallback for malformed JSON (unclosed brace)", () => {
+    expect(safeParse('{"a":1', {})).toEqual({});
+  });
+
+  test("returns fallback for plain text", () => {
+    expect(safeParse("hello world", "fallback")).toBe("fallback");
+  });
+
+  test("passes through non-string value (object)", () => {
+    const obj = { x: 1 };
+    expect(safeParse(obj, {})).toBe(obj);
+  });
+
+  test("returns fallback for null", () => {
+    expect(safeParse(null, "fb")).toBe("fb");
+  });
+
+  test("returns fallback for undefined", () => {
+    expect(safeParse(undefined, "fb")).toBe("fb");
+  });
+
+  test("passes through number", () => {
+    expect(safeParse(42, 0)).toBe(42);
+  });
+
+  test("parses nested JSON safely", () => {
+    const json = '{"a":{"b":{"c":[1,2,3]}},"d":"text"}';
+    expect(safeParse(json, {})).toEqual({ a: { b: { c: [1, 2, 3] } }, d: "text" });
+  });
+
+  test("handles JSON with unicode", () => {
+    expect(safeParse('{"msg":"你好世界"}', {})).toEqual({ msg: "你好世界" });
+  });
+});
+
+// ─── mapRowToWorkflowRun ────────────────────────────────────────────────────
+
+describe("mapRowToWorkflowRun", () => {
+  const baseRow = {
+    id: "run-1",
+    tenant_id: "t1",
+    assistant_id: "a1",
+    thread_id: "th1",
+    status: "running",
+    topology_edges: null, // JSONB returns parsed object, not string
+    total_edges: 3,
+    completed_edges: 1,
+    error_message: null,
+    metadata: null,
+    started_at: new Date("2026-01-01"),
+    completed_at: null,
+    created_at: new Date("2026-01-01"),
+    updated_at: new Date("2026-01-01"),
+  };
+
+  test("maps a clean row", () => {
+    const result = mapRowToWorkflowRun({
+      ...baseRow,
+      topology_edges: [{ from: "A", to: "B", purpose: "test" }],
+      metadata: { key: "value" },
+    });
+    expect(result.id).toBe("run-1");
+    expect(result.topologyEdges).toEqual([{ from: "A", to: "B", purpose: "test" }]);
+    expect(result.metadata).toEqual({ key: "value" });
+    expect(result.status).toBe("running");
+    expect(result.totalEdges).toBe(3);
+  });
+
+  test("falls back to empty array for null topology_edges", () => {
+    const result = mapRowToWorkflowRun({ ...baseRow, topology_edges: null });
+    expect(result.topologyEdges).toEqual([]);
+  });
+
+  test("falls back to empty object for null metadata", () => {
+    const result = mapRowToWorkflowRun({ ...baseRow, metadata: null });
+    expect(result.metadata).toEqual({});
+  });
+
+  test("handles topology_edges as JSON string (legacy TEXT column)", () => {
+    const result = mapRowToWorkflowRun({
+      ...baseRow,
+      topology_edges: JSON.stringify([{ from: "X", to: "Y", purpose: "legacy" }]),
+    });
+    expect(result.topologyEdges).toEqual([{ from: "X", to: "Y", purpose: "legacy" }]);
+  });
+
+  test("handles metadata as JSON string (legacy TEXT column)", () => {
+    const result = mapRowToWorkflowRun({
+      ...baseRow,
+      metadata: JSON.stringify({ legacy: true }),
+    });
+    expect(result.metadata).toEqual({ legacy: true });
+  });
+
+  test("safe-falls back on corrupted topology_edges string — does NOT throw", () => {
+    expect(() =>
+      mapRowToWorkflowRun({ ...baseRow, topology_edges: "{{{bad}}" })
+    ).not.toThrow();
+  });
+
+  test("safe-falls back on corrupted metadata string — does NOT throw", () => {
+    expect(() =>
+      mapRowToWorkflowRun({ ...baseRow, metadata: "not-json-at-all" })
+    ).not.toThrow();
+  });
+
+  test("returns fallback values for corrupted strings", () => {
+    const result = mapRowToWorkflowRun({
+      ...baseRow,
+      topology_edges: "bad",
+      metadata: "also bad",
+    });
+    expect(result.topologyEdges).toEqual([]);
+    expect(result.metadata).toEqual({});
+  });
+});
+
+// ─── mapRowToRunStep ────────────────────────────────────────────────────────
+
+describe("mapRowToRunStep", () => {
+  const baseRow = {
+    id: "step-1",
+    run_id: "run-1",
+    tenant_id: "t1",
+    step_type: "agent",
+    step_name: "MyStep",
+    thread_id: null,
+    edge_from: null,
+    edge_to: null,
+    edge_purpose: null,
+    input: null,
+    output: null,
+    status: "running",
+    error_message: null,
+    started_at: new Date("2026-01-01"),
+    completed_at: null,
+    duration_ms: null,
+    created_at: new Date("2026-01-01"),
+    updated_at: new Date("2026-01-01"),
+  };
+
+  test("maps a clean row", () => {
+    const result = mapRowToRunStep({
+      ...baseRow,
+      input: { template: "hello", rendered: "world" },
+      output: { result: "done" },
+      thread_id: "sub-thread-1",
+    });
+    expect(result.id).toBe("step-1");
+    expect(result.input).toEqual({ template: "hello", rendered: "world" });
+    expect(result.output).toEqual({ result: "done" });
+    expect(result.threadId).toBe("sub-thread-1");
+  });
+
+  test("handles null input and output (maps to undefined)", () => {
+    const result = mapRowToRunStep(baseRow);
+    expect(result.input).toBeUndefined();
+    expect(result.output).toBeUndefined();
+  });
+
+  test("handles input as JSON string (legacy TEXT column)", () => {
+    const result = mapRowToRunStep({
+      ...baseRow,
+      input: JSON.stringify({ template: "t", rendered: "r" }),
+    });
+    expect(result.input).toEqual({ template: "t", rendered: "r" });
+  });
+
+  test("handles output as JSON string (legacy TEXT column)", () => {
+    const result = mapRowToRunStep({
+      ...baseRow,
+      output: JSON.stringify({ result: "ok" }),
+    });
+    expect(result.output).toEqual({ result: "ok" });
+  });
+
+  test("safe-falls back on corrupted input string — does NOT throw", () => {
+    expect(() =>
+      mapRowToRunStep({ ...baseRow, input: "{{{corrupt" })
+    ).not.toThrow();
+  });
+
+  test("safe-falls back on corrupted output string — does NOT throw", () => {
+    expect(() =>
+      mapRowToRunStep({ ...baseRow, output: "bad-json-here" })
+    ).not.toThrow();
+  });
+
+  test("returns undefined for corrupted input/output strings", () => {
+    const result = mapRowToRunStep({
+      ...baseRow,
+      input: "invalid",
+      output: "also invalid",
+    });
+    expect(result.input).toBeUndefined();
+    expect(result.output).toBeUndefined();
+  });
+
+  test("handles deeply nested objects", () => {
+    const result = mapRowToRunStep({
+      ...baseRow,
+      output: { deep: { nested: { arr: [1, { x: "y" }] } } },
+    });
+    expect(result.output).toEqual({ deep: { nested: { arr: [1, { x: "y" }] } } });
+  });
+});

package/src/stores/PostgreSQLWorkflowTrackingStore.ts

@@ -98,7 +98,7 @@ export class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
       `SELECT * FROM lattice_workflow_runs WHERE id = $1`, [runId]
     );
     if (result.rows.length === 0) return null;
-    return this.mapRowToWorkflowRun(result.rows[0]);
+    return mapRowToWorkflowRun(result.rows[0]);
   }
 
   async updateWorkflowRun(runId: string, updates: UpdateWorkflowRunRequest): Promise<WorkflowRun | null> {
@@ -145,7 +145,7 @@ export class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
       `SELECT * FROM lattice_workflow_runs WHERE tenant_id = $1 AND thread_id = $2 ORDER BY created_at DESC`,
       [tenantId, threadId]
     );
-    return result.rows.map(this.mapRowToWorkflowRun);
+    return result.rows.map(mapRowToWorkflowRun);
   }
 
   async getWorkflowRunsByAssistantId(tenantId: string, assistantId: string): Promise<WorkflowRun[]> {
@@ -154,7 +154,7 @@ export class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
       `SELECT * FROM lattice_workflow_runs WHERE tenant_id = $1 AND assistant_id = $2 ORDER BY created_at DESC`,
       [tenantId, assistantId]
     );
-    return result.rows.map(this.mapRowToWorkflowRun);
+    return result.rows.map(mapRowToWorkflowRun);
   }
 
   async getWorkflowRunsByTenantId(tenantId: string): Promise<WorkflowRun[]> {
@@ -163,7 +163,7 @@ export class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
       `SELECT * FROM lattice_workflow_runs WHERE tenant_id = $1 ORDER BY created_at DESC`,
       [tenantId]
     );
-    return result.rows.map(this.mapRowToWorkflowRun);
+    return result.rows.map(mapRowToWorkflowRun);
   }
 
   async createRunStep(request: CreateRunStepRequest): Promise<RunStep> {
@@ -199,7 +199,7 @@ export class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
       [request.runId, request.stepType, request.stepName]
     );
     if (result.rows.length > 0) {
-      const existing = this.mapRowToRunStep(result.rows[0]);
+      const existing = mapRowToRunStep(result.rows[0]);
       // Update threadId if not already set and request has one
       if (!existing.threadId && request.threadId) {
         await this.pool.query(
@@ -250,7 +250,7 @@ export class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
       `SELECT * FROM lattice_workflow_steps WHERE run_id = $1 AND id = $2`,
       [runId, stepId]
     );
-    return row.rows.length > 0 ? this.mapRowToRunStep(row.rows[0]) : null;
+    return row.rows.length > 0 ? mapRowToRunStep(row.rows[0]) : null;
   }
 
   async getRunSteps(runId: string): Promise<RunStep[]> {
@@ -259,7 +259,7 @@ export class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
       `SELECT * FROM lattice_workflow_steps WHERE run_id = $1 ORDER BY created_at ASC`,
       [runId]
     );
-    return result.rows.map(this.mapRowToRunStep);
+    return result.rows.map(mapRowToRunStep);
   }
 
   async getRunStepsByType(runId: string, stepType: StepType): Promise<RunStep[]> {
@@ -268,7 +268,7 @@ export class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
       `SELECT * FROM lattice_workflow_steps WHERE run_id = $1 AND step_type = $2 ORDER BY created_at ASC`,
       [runId, stepType]
     );
-    return result.rows.map(this.mapRowToRunStep);
+    return result.rows.map(mapRowToRunStep);
   }
 
   async getInterruptedSteps(runId: string): Promise<RunStep[]> {
@@ -277,48 +277,59 @@ export class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
       `SELECT * FROM lattice_workflow_steps WHERE run_id = $1 AND status = 'interrupted' ORDER BY created_at ASC`,
       [runId]
     );
-    return result.rows.map(this.mapRowToRunStep);
+    return result.rows.map(mapRowToRunStep);
   }
+}
 
-  private mapRowToWorkflowRun(row: any): WorkflowRun {
-    return {
-      id: row.id,
-      tenantId: row.tenant_id,
-      assistantId: row.assistant_id,
-      threadId: row.thread_id,
-      status: row.status as WorkflowRunStatus,
-      topologyEdges: typeof row.topology_edges === 'string' ? JSON.parse(row.topology_edges) : row.topology_edges || [],
-      totalEdges: row.total_edges,
-      completedEdges: row.completed_edges,
-      errorMessage: row.error_message,
-      metadata: typeof row.metadata === 'string' ? JSON.parse(row.metadata) : row.metadata || {},
-      startedAt: row.started_at,
-      completedAt: row.completed_at,
-      createdAt: row.created_at,
-      updatedAt: row.updated_at,
-    };
+export function safeParse<T>(value: unknown, fallback: T): T {
+  if (value === null || value === undefined) return fallback;
+  if (typeof value !== 'string') return value as unknown as T;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
   }
+}
 
-  private mapRowToRunStep(row: any): RunStep {
-    return {
-      id: row.id,
-      runId: row.run_id,
-      tenantId: row.tenant_id,
-      stepType: row.step_type as StepType,
-      stepName: row.step_name,
-      threadId: row.thread_id,
-      edgeFrom: row.edge_from,
-      edgeTo: row.edge_to,
-      edgePurpose: row.edge_purpose,
-      input: typeof row.input === 'string' ? JSON.parse(row.input) : row.input,
-      output: typeof row.output === 'string' ? JSON.parse(row.output) : row.output,
-      status: row.status,
-      errorMessage: row.error_message,
-      startedAt: row.started_at,
-      completedAt: row.completed_at,
-      durationMs: row.duration_ms,
-      createdAt: row.created_at,
-      updatedAt: row.updated_at,
-    };
-  }
+export function mapRowToWorkflowRun(row: any): WorkflowRun {
+  return {
+    id: row.id,
+    tenantId: row.tenant_id,
+    assistantId: row.assistant_id,
+    threadId: row.thread_id,
+    status: row.status as WorkflowRunStatus,
+    topologyEdges: safeParse(row.topology_edges, []),
+    totalEdges: row.total_edges,
+    completedEdges: row.completed_edges,
+    errorMessage: row.error_message,
+    metadata: safeParse(row.metadata, {}),
+    startedAt: row.started_at,
+    completedAt: row.completed_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
 }
+
+export function mapRowToRunStep(row: any): RunStep {
+  return {
+    id: row.id,
+    runId: row.run_id,
+    tenantId: row.tenant_id,
+    stepType: row.step_type as StepType,
+    stepName: row.step_name,
+    threadId: row.thread_id,
+    edgeFrom: row.edge_from,
+    edgeTo: row.edge_to,
+    edgePurpose: row.edge_purpose,
+    input: safeParse(row.input, undefined),
+    output: safeParse(row.output, undefined),
+    status: row.status,
+    errorMessage: row.error_message,
+    startedAt: row.started_at,
+    completedAt: row.completed_at,
+    durationMs: row.duration_ms,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+