feat: define graph update proposal contract

2026-08-02 08:00:37 +01:00
parent 02a6ecd0da
commit b38a6a9f2e
4 changed files with 477 additions and 0 deletions
@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { buildGraphUpdatePrompt } from "@/lib/graph/prompt-builder.js";
+import { makeEdge, makeGraph, makeNode } from "@/lib/graph/schema.js";
+
+function makeContext() {
+  const unknown = makeNode({
+    id: "n-unknown",
+    label: "Complaint rate denominator",
+    description: "Need the denominator to compare complaint rates",
+    kind: "unknown",
+    status: "unknown",
+    confidence: "high",
+  });
+  const observation = makeNode({
+    id: "n-obs",
+    label: "Complaints up 35%",
+    description: "Complaints increased by 35%",
+    kind: "observation",
+    status: "supported",
+    confidence: "high",
+  });
+
+  return {
+    situationGraph: makeGraph({
+      centralStatement: "Complaints increased while production increased.",
+      nodes: [unknown, observation],
+      edges: [
+        makeEdge({
+          id: "e1",
+          fromNodeId: observation.id,
+          toNodeId: unknown.id,
+          relationship: "supports",
+          confidence: "high",
+          description: "Observation informs the unknown",
+        }),
+      ],
+      activeUnknownNodeId: unknown.id,
+      resolvedNodeIds: [],
+      currentSummary:
+        "Nodes: 1 observation, 1 unknown | Edges: 1 total | Unknowns: 1 unresolved",
+    }),
+    previousQuestion: "What denominator is being used for the complaint rate?",
+    answer:
+      "The complaint rate fell from 2.0 complaints per 100 units to 1.9 complaints per 100 units.",
+  };
+}
+
+describe("buildGraphUpdatePrompt", () => {
+  it("includes the current graph", () => {
+    const prompt = buildGraphUpdatePrompt(makeContext());
+    expect(prompt).toContain(
+      "Complaints increased while production increased.",
+    );
+    expect(prompt).toContain("Complaint rate denominator");
+  });
+
+  it("includes previous question and answer", () => {
+    const prompt = buildGraphUpdatePrompt(makeContext());
+    expect(prompt).toContain(
+      "What denominator is being used for the complaint rate?",
+    );
+    expect(prompt).toContain(
+      "The complaint rate fell from 2.0 complaints per 100 units to 1.9 complaints per 100 units.",
+    );
+  });
+
+  it("contains exact schema keys", () => {
+    const prompt = buildGraphUpdatePrompt(makeContext());
+    expect(prompt).toContain("addedNodes");
+    expect(prompt).toContain("updatedNodes");
+    expect(prompt).toContain("addedEdges");
+    expect(prompt).toContain("removedEdgeIds");
+    expect(prompt).toContain("resolvedUnknownNodeIds");
+    expect(prompt).toContain("affectedNodeIds");
+  });
+
+  it("lists enum values", () => {
+    const prompt = buildGraphUpdatePrompt(makeContext());
+    expect(prompt).toContain(
+      "observation | reported_claim | metric | state | transition | relationship | assumption | unknown | conclusion",
+    );
+    expect(prompt).toContain(
+      "known | unknown | provisional | supported | weakened | contradicted | resolved",
+    );
+    expect(prompt).toContain(
+      "supports | weakens | contradicts | depends_on | causes | may_cause | measures | compares_with | updates | other",
+    );
+  });
+
+  it("forbids full-graph replacement", () => {
+    const prompt = buildGraphUpdatePrompt(makeContext());
+    expect(prompt).toContain("Never return a replacement graph");
+    expect(prompt).toContain("Propose changes only");
+  });
+
+  it("requires JSON only", () => {
+    const prompt = buildGraphUpdatePrompt(makeContext());
+    expect(prompt).toContain("Return JSON only");
+    expect(prompt).toContain("Return one JSON object only");
+  });
+});
@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { parseGraphUpdateProposal } from "@/lib/graph/update-proposal.js";
+
+function makeValidProposal(overrides = {}) {
+  return {
+    addedNodes: [],
+    updatedNodes: [
+      {
+        nodeId: "n-unknown",
+        previousStatus: "unknown",
+        newStatus: "resolved",
+        previousValue: null,
+        newValue: "1.9 complaints per 100 units",
+        reason: "The answer directly provides the normalized complaint rate.",
+      },
+    ],
+    addedEdges: [],
+    removedEdgeIds: [],
+    resolvedUnknownNodeIds: ["n-unknown"],
+    affectedNodeIds: [],
+    ...overrides,
+  };
+}
+
+describe("parseGraphUpdateProposal", () => {
+  it("parses a valid proposal", () => {
+    const result = parseGraphUpdateProposal(makeValidProposal());
+    expect(result.success).toBe(true);
+    expect(result.proposal.updatedNodes).toHaveLength(1);
+  });
+
+  it("fails on malformed JSON", () => {
+    const result = parseGraphUpdateProposal("{not json");
+    expect(result.success).toBe(false);
+  });
+
+  it("fails when required update content is invalid", () => {
+    const result = parseGraphUpdateProposal({
+      updatedNodes: [{ nodeId: "n-unknown" }],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("removes null array entries and logs them", () => {
+    const result = parseGraphUpdateProposal(
+      JSON.stringify({
+        ...makeValidProposal(),
+        addedNodes: [null],
+      }),
+    );
+    expect(result.success).toBe(true);
+    expect(result.proposal.addedNodes).toEqual([]);
+    expect(result.normalisationsApplied).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ change: "Removed null array entry" }),
+      ]),
+    );
+  });
+
+  it("fills missing optional arrays with empty arrays", () => {
+    const result = parseGraphUpdateProposal({
+      updatedNodes: [],
+    });
+    expect(result.success).toBe(true);
+    expect(result.proposal.addedNodes).toEqual([]);
+    expect(result.proposal.addedEdges).toEqual([]);
+    expect(result.normalisationsApplied.length).toBeGreaterThan(0);
+  });
+
+  it("normalises confirmed enum alias and preserves IDs", () => {
+    const result = parseGraphUpdateProposal({
+      ...makeValidProposal(),
+      addedNodes: [
+        {
+          id: "n-new",
+          label: "Reported update",
+          description: "A new reported claim",
+          kind: "reported_statement",
+          status: "supported",
+          confidence: "medium",
+          value: null,
+          unit: null,
+          evidenceIds: [],
+          dependsOn: [],
+          affects: [],
+          parentId: null,
+          childIds: [],
+        },
+      ],
+    });
+    expect(result.success).toBe(true);
+    expect(result.proposal.addedNodes[0].kind).toBe("reported_claim");
+    expect(result.proposal.addedNodes[0].id).toBe("n-new");
+  });
+
+  it("unknown enum values still fail", () => {
+    const result = parseGraphUpdateProposal({
+      ...makeValidProposal(),
+      addedNodes: [
+        {
+          id: "n-new",
+          label: "Bad node",
+          description: "Bad node",
+          kind: "unsupported_kind",
+          status: "supported",
+          confidence: "medium",
+          value: null,
+          unit: null,
+          evidenceIds: [],
+          dependsOn: [],
+          affects: [],
+          parentId: null,
+          childIds: [],
+        },
+      ],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("does not invent a next question", () => {
+    const result = parseGraphUpdateProposal(makeValidProposal());
+    expect(result.proposal.nextQuestion).toBeUndefined();
+  });
+});