@minicor/mcp-server 4.8.0 → 4.9.0

package/dist/__tests__/blueprints-tools.test.js

@@ -0,0 +1,1190 @@
+/**
+ * Tool-level tests for the blueprint suite: resolve_blueprint_state's
+ * decision table (unfolded states -> next calls), the baseVersion CAS 409
+ * surfacing, the synthesize tri-state 409 classification, the apply-proposal
+ * swap guard, answer-question convergence, and blueprint_build's needs_input
+ * precondition.
+ *
+ * Uses an in-memory transport with a mocked fetch that routes by URL,
+ * mirroring jobs-tools.test.ts.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createMinicorServer } from "../lib.js";
+const MW_BASE = "https://mw.test";
+const BP = "/api/workspaces/11/blueprints";
+function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+async function startServer() {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const embedded = await createMinicorServer(serverTransport, {
+        localTools: false,
+        credentials: {
+            access_token: "test-token",
+            refresh_token: "test-refresh-token",
+            expires_at: Date.now() + 3_600_000,
+        },
+        baseUrl: "https://api.test.com",
+        codeMode: false,
+    });
+    const client = new Client({ name: "test-client", version: "1.0.0" });
+    await client.connect(clientTransport);
+    return { client, embedded };
+}
+function parseToolJson(result) {
+    return JSON.parse(result.content[0].text);
+}
+/** Route a mocked fetch by URL suffix (query stripped). */
+function routedFetch(routes) {
+    return vi.fn(async (input) => {
+        const path = new URL(String(input)).pathname;
+        for (const [suffix, body] of Object.entries(routes)) {
+            if (path.endsWith(suffix))
+                return jsonResponse(body);
+        }
+        throw new Error(`Unexpected fetch: ${String(input)}`);
+    });
+}
+/** A GET /blueprints/:id response (Blueprint & BlueprintStateInfo). */
+function bpFixture(overrides = {}) {
+    return {
+        id: "bp-1",
+        workspaceId: 11,
+        name: "COI intake",
+        document: { goal: "", steps: [], openQuestions: [] },
+        librarySeq: 0,
+        specBasedOnSeq: 0,
+        lastSyncedVersion: null,
+        pendingProposal: null,
+        middlewareId: null,
+        routeId: null,
+        buildId: null,
+        state: "never_synced",
+        specStale: false,
+        jobStale: false,
+        jobEditedDirectly: false,
+        hasPendingProposal: false,
+        buildStatus: null,
+        headVersion: 0,
+        drift: { newEntries: [], unsyncedVersions: [] },
+        ...overrides,
+    };
+}
+describe("blueprint tools", () => {
+    const savedMwUrl = process.env.MIDDLEWARE_SERVICE_URL;
+    beforeEach(() => {
+        process.env.MIDDLEWARE_SERVICE_URL = MW_BASE;
+    });
+    afterEach(() => {
+        if (savedMwUrl === undefined)
+            delete process.env.MIDDLEWARE_SERVICE_URL;
+        else
+            process.env.MIDDLEWARE_SERVICE_URL = savedMwUrl;
+        vi.unstubAllGlobals();
+    });
+    // ── baseVersion CAS ────────────────────────────────────────
+    it("blueprint_update surfaces the baseVersion CAS 409 as a structured version_conflict", async () => {
+        const fetchMock = vi.fn(async (_input, _init) => jsonResponse({ message: "Blueprint has moved to version 7 (edit was based on 4)" }, 409));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_update",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    patch: { goal: "New goal" },
+                    baseVersion: 4,
+                },
+            });
+            const [url, init] = fetchMock.mock.calls[0];
+            expect(String(url)).toBe(`${MW_BASE}${BP}/bp-1`);
+            expect(init.method).toBe("PATCH");
+            expect(JSON.parse(String(init.body)).baseVersion).toBe(4);
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("blocked");
+            expect(payload.blocked.reason).toBe("version_conflict");
+            expect(payload.blocked.retryable).toBe(true);
+            expect(payload.nextActions.join("\n")).toContain("blueprint_get");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_update refuses document edits without baseVersion (CAS protocol)", async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_update",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    patch: { goal: "New goal" },
+                },
+            });
+            // Guarded at the tool layer — no request reaches the service.
+            expect(fetchMock).not.toHaveBeenCalled();
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("blocked");
+            expect(payload.blocked.reason).toBe("base_version_required");
+            expect(payload.nextActions.join("\n")).toContain("blueprint_get");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_update allows a conflict-free rename without baseVersion", async () => {
+        const fetchMock = vi.fn(async (_input, init) => init?.method === "PATCH"
+            ? jsonResponse(bpFixture({ name: "Renamed", headVersion: 2, state: "never_synced" }))
+            : jsonResponse(bpFixture({ name: "Renamed", headVersion: 2 })));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_update",
+                arguments: { workspaceId: 11, blueprintId: "bp-1", name: "Renamed" },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("updated");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    // ── synthesize 409 classification ──────────────────────────
+    // These bodies carry NO `code` — they are the legacy string-matching
+    // fallback for deployments that predate structured error codes.
+    it.each([
+        [
+            "A proposal is already pending review — apply or reject it first (or pass replace=true)",
+            "proposal_pending",
+            true,
+        ],
+        [
+            "2 entries are still being enriched — retry when they are ready",
+            "entries_enriching",
+            true,
+        ],
+        [
+            "Synthesis is not configured (MINICOR_LLMS_API_KEY missing)",
+            "llm_unconfigured",
+            false,
+        ],
+    ])("blueprint_synthesize classifies the 409 '%s' as %s", async (message, reason, retryable) => {
+        const fetchMock = vi.fn(async (_input, _init) => jsonResponse({ message }, 409));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_synthesize",
+                arguments: { workspaceId: 11, blueprintId: "bp-1" },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("blocked");
+            expect(payload.blocked.reason).toBe(reason);
+            expect(payload.blocked.retryable).toBe(retryable);
+            expect(payload.nextActions.length).toBeGreaterThan(0);
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it.each([
+        // The code drives classification even when the message is reworded —
+        // the strings below would NOT match the legacy fallback patterns.
+        ["proposal_pending", 409, "a draft awaits your verdict", "proposal_pending", true],
+        ["entries_enriching", 409, "the library is still cooking", "entries_enriching", true],
+        ["synthesis_not_configured", 409, "no LLM key on this deployment", "llm_unconfigured", false],
+        ["llm_gateway_failed", 502, "upstream fell over", "llm_gateway_failed", true],
+        ["synthesis_unparseable", 502, "model returned prose", "synthesis_unparseable", true],
+        ["patch_shape_invalid", 502, "patch broke the document shape", "patch_shape_invalid", true],
+    ])("blueprint_synthesize classifies code %s (HTTP %i) structurally, ignoring the message", async (code, status, message, reason, retryable) => {
+        const fetchMock = vi.fn(async (_input, _init) => jsonResponse({ code, message }, status));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_synthesize",
+                arguments: { workspaceId: 11, blueprintId: "bp-1" },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("blocked");
+            expect(payload.blocked.reason).toBe(reason);
+            expect(payload.blocked.retryable).toBe(retryable);
+            expect(payload.nextActions.length).toBeGreaterThan(0);
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_synthesize returns the pending proposal with prefilled apply coordinates", async () => {
+        const fetchMock = vi.fn(async (_input, _init) => jsonResponse(bpFixture({
+            hasPendingProposal: true,
+            pendingProposal: {
+                patch: {},
+                basedOnSeq: 6,
+                baseVersion: 3,
+                summary: "Added refund flow",
+                citations: [],
+                createdAt: "2026-08-12T00:00:00Z",
+            },
+        })));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_synthesize",
+                arguments: { workspaceId: 11, blueprintId: "bp-1", replace: true },
+            });
+            const [url, init] = fetchMock.mock.calls[0];
+            expect(String(url)).toBe(`${MW_BASE}${BP}/bp-1/synthesize`);
+            expect(JSON.parse(String(init.body))).toEqual({ replace: true });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("proposal_ready");
+            expect(payload.nextActions.join("\n")).toContain("baseVersion=3 proposalBasedOnSeq=6");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    // ── apply-proposal swap guard ──────────────────────────────
+    it("blueprint_apply_proposal refuses (without POSTing) when the pending proposal was swapped", async () => {
+        const fetchMock = routedFetch({
+            "/blueprints/bp-1": bpFixture({
+                hasPendingProposal: true,
+                pendingProposal: {
+                    patch: {},
+                    basedOnSeq: 9,
+                    baseVersion: 5,
+                    summary: "Proposal B",
+                    citations: [],
+                    createdAt: "2026-08-12T00:00:00Z",
+                },
+            }),
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_apply_proposal",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    baseVersion: 2,
+                    proposalBasedOnSeq: 3,
+                },
+            });
+            // Only the re-read GET — the apply POST must not have happened.
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("blocked");
+            expect(payload.blocked.reason).toBe("proposal_swapped");
+            expect(payload.nextActions.join("\n")).toContain("blueprint_get_proposal");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_apply_proposal applies when the reviewed coordinates match", async () => {
+        const pendingProposal = {
+            patch: {},
+            basedOnSeq: 3,
+            baseVersion: 2,
+            summary: "Proposal A",
+            citations: [],
+            createdAt: "2026-08-12T00:00:00Z",
+        };
+        const fetchMock = routedFetch({
+            "/blueprints/bp-1/proposal/apply": bpFixture({
+                headVersion: 3,
+                state: "job_stale",
+                document: {
+                    goal: "Do the thing",
+                    steps: [{ id: "s1" }],
+                    openQuestions: [],
+                },
+            }),
+            "/blueprints/bp-1": bpFixture({
+                hasPendingProposal: true,
+                pendingProposal,
+            }),
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_apply_proposal",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    baseVersion: 2,
+                    proposalBasedOnSeq: 3,
+                },
+            });
+            const applyCall = fetchMock.mock.calls.find(([u]) => String(u).endsWith("/proposal/apply"));
+            expect(applyCall).toBeTruthy();
+            // The reviewed proposal's identity must ride along so the service can
+            // atomically refuse a swapped proposal (409 proposal_mismatch).
+            const [, applyInit] = applyCall;
+            expect(JSON.parse(String(applyInit.body))).toEqual({ basedOnSeq: 3 });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("applied");
+            expect(payload.headVersion).toBe(3);
+            expect(payload.nextActions.join("\n")).toContain("blueprint_build");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_apply_proposal surfaces the service-side 409 proposal_mismatch as proposal_swapped", async () => {
+        // The pre-flight GET passes (coordinates match), but a resynthesize
+        // lands in the check-to-apply window — the service's atomic basedOnSeq
+        // check refuses with code proposal_mismatch.
+        const pendingProposal = {
+            patch: {},
+            basedOnSeq: 3,
+            baseVersion: 2,
+            summary: "Proposal A",
+            citations: [],
+            createdAt: "2026-08-12T00:00:00Z",
+        };
+        const fetchMock = vi.fn(async (input) => {
+            const path = new URL(String(input)).pathname;
+            if (path.endsWith("/proposal/apply")) {
+                return jsonResponse({
+                    code: "proposal_mismatch",
+                    message: "The pending proposal is not the one you reviewed (basedOnSeq 7 vs expected 3) — it was replaced since. Review the current proposal and retry",
+                }, 409);
+            }
+            return jsonResponse(bpFixture({ hasPendingProposal: true, pendingProposal }));
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_apply_proposal",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    baseVersion: 2,
+                    proposalBasedOnSeq: 3,
+                },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("blocked");
+            expect(payload.blocked.reason).toBe("proposal_swapped");
+            expect(payload.blocked.retryable).toBe(true);
+            expect(payload.nextActions.join("\n")).toContain("blueprint_get_proposal");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_apply_proposal keeps treating a code-less spec-moved 409 as spec_moved (legacy fallback)", async () => {
+        const pendingProposal = {
+            patch: {},
+            basedOnSeq: 3,
+            baseVersion: 2,
+            summary: "Proposal A",
+            citations: [],
+            createdAt: "2026-08-12T00:00:00Z",
+        };
+        const fetchMock = vi.fn(async (input) => {
+            const path = new URL(String(input)).pathname;
+            if (path.endsWith("/proposal/apply")) {
+                return jsonResponse({
+                    message: "The spec has changed since this proposal was synthesized (version 5 vs 2). Reject it and resynthesize",
+                }, 409);
+            }
+            return jsonResponse(bpFixture({ hasPendingProposal: true, pendingProposal }));
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_apply_proposal",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    baseVersion: 2,
+                    proposalBasedOnSeq: 3,
+                },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("blocked");
+            expect(payload.blocked.reason).toBe("spec_moved");
+            expect(payload.nextActions.join("\n")).toContain("blueprint_reject_proposal");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    // ── raw-entity write responses get the computed state re-read ──
+    // The live service's PATCH /:id and POST /:id/proposal/apply return the raw
+    // blueprint row WITHOUT headVersion/state (unlike GET) — the tools must
+    // re-read instead of reporting headVersion: undefined (the next CAS base).
+    it("blueprint_update re-reads for headVersion when PATCH returns the raw row", async () => {
+        const rawRow = {
+            id: "bp-1",
+            workspaceId: 11,
+            name: "COI intake",
+            document: { goal: "New goal", steps: [], openQuestions: [] },
+            librarySeq: 0,
+            specBasedOnSeq: 0,
+        };
+        const fetchMock = vi.fn(async (_input, init) => init?.method === "PATCH"
+            ? jsonResponse(rawRow)
+            : jsonResponse(bpFixture({ headVersion: 5, state: "job_stale" })));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_update",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    patch: { goal: "New goal" },
+                    baseVersion: 4,
+                },
+            });
+            // PATCH, then the re-read GET.
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("updated");
+            expect(payload.headVersion).toBe(5);
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_apply_proposal re-reads for headVersion when apply returns the raw row", async () => {
+        const pendingProposal = {
+            patch: {},
+            basedOnSeq: 3,
+            baseVersion: 2,
+            summary: "Proposal A",
+            citations: [],
+            createdAt: "2026-08-12T00:00:00Z",
+        };
+        let applied = false;
+        const fetchMock = vi.fn(async (input) => {
+            const path = new URL(String(input)).pathname;
+            if (path.endsWith("/proposal/apply")) {
+                applied = true;
+                // Raw row: no headVersion, no state.
+                return jsonResponse({
+                    id: "bp-1",
+                    workspaceId: 11,
+                    document: { goal: "Do the thing", steps: [{ id: "s1" }], openQuestions: [] },
+                });
+            }
+            // Guard re-read before apply, computed-state re-read after.
+            return jsonResponse(applied
+                ? bpFixture({ headVersion: 3, state: "job_stale" })
+                : bpFixture({ hasPendingProposal: true, pendingProposal }));
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_apply_proposal",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    baseVersion: 2,
+                    proposalBasedOnSeq: 3,
+                },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("applied");
+            expect(payload.headVersion).toBe(3);
+            expect(payload.state).toBe("job_stale");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_update marks the response partial when the post-write re-read ALSO fails", async () => {
+        const rawRow = {
+            id: "bp-1",
+            workspaceId: 11,
+            name: "COI intake",
+            document: { goal: "New goal", steps: [], openQuestions: [] },
+            librarySeq: 0,
+            specBasedOnSeq: 0,
+        };
+        const fetchMock = vi.fn(async (_input, init) => init?.method === "PATCH"
+            ? jsonResponse(rawRow)
+            : jsonResponse({ message: "boom" }, 500));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_update",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    patch: { goal: "New goal" },
+                    baseVersion: 4,
+                },
+            });
+            const payload = parseToolJson(result);
+            // The write succeeded — but the response must NOT claim a usable CAS
+            // coordinate it doesn't have.
+            expect(payload.status).toBe("updated");
+            expect(payload.headVersion).toBeNull();
+            expect(payload.warning).toContain("state re-read failed");
+            expect(payload.warning).toContain("blueprint_get");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    // ── reject 404 = success-shaped ────────────────────────────
+    it("blueprint_reject_proposal treats a 404 as already_gone (success-shaped)", async () => {
+        const fetchMock = vi.fn(async (_input, _init) => jsonResponse({ message: "No pending proposal" }, 404));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_reject_proposal",
+                arguments: { workspaceId: 11, blueprintId: "bp-1" },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("already_gone");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    // ── answer-question convergence + driftNote ────────────────
+    it("blueprint_answer_question treats the not-open 404 as convergence", async () => {
+        const fetchMock = vi.fn(async (_input, _init) => jsonResponse({ message: "The question is not open" }, 404));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_answer_question",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    question: "Which account?",
+                    answer: "The ops account",
+                },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("already_answered");
+            expect(payload.note).toContain("CONVERGENCE");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_answer_question propagates a blueprint-missing 404 instead of shaping it as convergence", async () => {
+        const fetchMock = vi.fn(async (_input, _init) => jsonResponse({ message: "Blueprint bp-1 not found" }, 404));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_answer_question",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    question: "Which account?",
+                    answer: "The ops account",
+                },
+            });
+            const textOut = result.content[0].text;
+            expect(textOut).toContain("Blueprint not found");
+            expect(textOut).not.toContain("already_answered");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_apply_proposal propagates a blueprint-missing 404 instead of shaping it as convergence", async () => {
+        const fetchMock = vi.fn(async (_input, _init) => jsonResponse({ message: "Blueprint bp-1 not found" }, 404));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_apply_proposal",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    baseVersion: 1,
+                    proposalBasedOnSeq: 1,
+                },
+            });
+            const textOut = result.content[0].text;
+            expect(textOut).toContain("Blueprint not found");
+            expect(textOut).not.toContain("no_pending_proposal");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_answer_question carries the driftNote and remaining questions on success", async () => {
+        const fetchMock = vi.fn(async (_input, _init) => jsonResponse(bpFixture({
+            document: {
+                goal: "g",
+                steps: [],
+                openQuestions: ["Second question?"],
+            },
+        })));
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_answer_question",
+                arguments: {
+                    workspaceId: 11,
+                    blueprintId: "bp-1",
+                    question: "First question?",
+                    answer: "Answered",
+                },
+            });
+            const [url, init] = fetchMock.mock.calls[0];
+            expect(String(url)).toBe(`${MW_BASE}${BP}/bp-1/questions/answer`);
+            expect(JSON.parse(String(init.body))).toEqual({
+                question: "First question?",
+                answer: "Answered",
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("answered");
+            expect(payload.driftNote).toContain("spec_stale");
+            expect(payload.nextActions.join("\n")).toContain("Second question?");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    // ── build precondition + handoff artifact ──────────────────
+    it("blueprint_build blocks (without syncing) when the linked build run is needs_input", async () => {
+        const fetchMock = routedFetch({
+            "/blueprints/bp-1": bpFixture({
+                state: "building",
+                buildStatus: "needs_input",
+                middlewareId: "mw-1",
+                routeId: "route-1",
+                buildId: "b-1",
+            }),
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_build",
+                arguments: { workspaceId: 11, blueprintId: "bp-1" },
+            });
+            // Only the precondition GET — no POST /sync.
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("blocked");
+            expect(payload.blocked.reason).toBe("build_needs_input");
+            expect(payload.nextActions.join("\n")).toContain("answer_build_question");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_build returns the handoff triple and points at the jobs loop", async () => {
+        const fetchMock = routedFetch({
+            "/blueprints/bp-1/sync": {
+                middlewareId: "mw-1",
+                routeId: "route-1",
+                buildId: "b-2",
+                testCaseIds: ["tc-1", "tc-2"],
+            },
+            "/blueprints/bp-1": bpFixture({
+                state: "job_stale",
+                document: { goal: "Do the thing", steps: [{ id: "s1" }] },
+                headVersion: 2,
+            }),
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_build",
+                arguments: { workspaceId: 11, blueprintId: "bp-1" },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.status).toBe("build_queued");
+            expect(payload.middlewareId).toBe("mw-1");
+            expect(payload.routeId).toBe("route-1");
+            expect(payload.buildId).toBe("b-2");
+            expect(payload.testCaseIds).toEqual(["tc-1", "tc-2"]);
+            expect(payload.nextActions.join("\n")).toContain("run_tests");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    it("blueprint_build_status surfaces a build fetch failure instead of pretending there is no build", async () => {
+        const fetchMock = vi.fn(async (input) => {
+            const path = new URL(String(input)).pathname;
+            if (path.includes("/builds/")) {
+                return jsonResponse({ message: "upstream timeout" }, 502);
+            }
+            return jsonResponse(bpFixture({
+                state: "building",
+                middlewareId: "mw-1",
+                routeId: "route-1",
+                buildId: "b-1",
+            }));
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "blueprint_build_status",
+                arguments: { workspaceId: 11, blueprintId: "bp-1" },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.build).toBeNull();
+            expect(payload.buildFetchError).toContain("upstream timeout");
+            expect(payload.nextActions.join("\n")).toContain("READ failure");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+    // ── resolve_blueprint_state decision table ─────────────────
+    describe("resolve_blueprint_state", () => {
+        async function resolve(routes) {
+            const fetchMock = routedFetch(routes);
+            vi.stubGlobal("fetch", fetchMock);
+            const { client, embedded } = await startServer();
+            try {
+                const result = await client.callTool({
+                    name: "resolve_blueprint_state",
+                    arguments: { workspaceId: 11, blueprintId: "bp-1" },
+                });
+                return parseToolJson(result);
+            }
+            finally {
+                await client.close();
+                await embedded.close();
+            }
+        }
+        it("a failed entries read degrades explicitly instead of reporting no_context", async () => {
+            const fetchMock = vi.fn(async (input) => {
+                const path = new URL(String(input)).pathname;
+                if (path.endsWith("/entries")) {
+                    return jsonResponse({ message: "db unavailable" }, 503);
+                }
+                return jsonResponse(bpFixture());
+            });
+            vi.stubGlobal("fetch", fetchMock);
+            const { client, embedded } = await startServer();
+            try {
+                const result = await client.callTool({
+                    name: "resolve_blueprint_state",
+                    arguments: { workspaceId: 11, blueprintId: "bp-1" },
+                });
+                const payload = parseToolJson(result);
+                // The empty spec + unreadable library must NOT unfold to no_context
+                // (which would direct the agent to feed a library it never saw).
+                expect(payload.status).toBe("degraded");
+                expect(payload.state).toBeUndefined();
+                expect(payload.error).toContain("db unavailable");
+                expect(payload.nextActions.join("\n")).toContain("resolve_blueprint_state");
+            }
+            finally {
+                await client.close();
+                await embedded.close();
+            }
+        });
+        it("a failed linked-build read degrades explicitly instead of hiding the build", async () => {
+            const fetchMock = vi.fn(async (input) => {
+                const path = new URL(String(input)).pathname;
+                if (path.includes("/builds/")) {
+                    return jsonResponse({ message: "db unavailable" }, 503);
+                }
+                if (path.endsWith("/entries"))
+                    return jsonResponse([]);
+                return jsonResponse(bpFixture({
+                    document: { goal: "g", steps: [{ id: "s1" }], openQuestions: [] },
+                    middlewareId: "mw-1",
+                    routeId: "route-1",
+                    buildId: "b-1",
+                    state: "job_stale",
+                    lastSyncedVersion: 1,
+                }));
+            });
+            vi.stubGlobal("fetch", fetchMock);
+            const { client, embedded } = await startServer();
+            try {
+                const result = await client.callTool({
+                    name: "resolve_blueprint_state",
+                    arguments: { workspaceId: 11, blueprintId: "bp-1" },
+                });
+                const payload = parseToolJson(result);
+                // An unreadable linked build must NOT unfold to a normal lifecycle
+                // state — needs_input questions and stall facts would silently
+                // vanish.
+                expect(payload.status).toBe("degraded");
+                expect(payload.state).toBeUndefined();
+                expect(payload.error).toContain("b-1");
+                expect(payload.nextActions.join("\n")).toContain("resolve_blueprint_state");
+            }
+            finally {
+                await client.close();
+                await embedded.close();
+            }
+        });
+        it("empty blueprint -> no_context -> feed the library", async () => {
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [],
+                "/blueprints/bp-1": bpFixture(),
+            });
+            expect(payload.state).toBe("no_context");
+            expect(payload.nextActions.join("\n")).toContain("blueprint_add_entry");
+        });
+        it("pending entries -> enriching -> poll the library", async () => {
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "video", title: "Loom", status: "pending", seq: 1 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    librarySeq: 1,
+                    specStale: true,
+                    state: "spec_stale",
+                }),
+            });
+            expect(payload.state).toBe("enriching");
+            expect(payload.nextActions.join("\n")).toContain("blueprint_list_entries");
+            expect(payload.resources.pending).toHaveLength(1);
+        });
+        it("ready library + empty spec -> no_spec -> synthesize", async () => {
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    librarySeq: 1,
+                    specStale: true,
+                    state: "spec_stale",
+                }),
+            });
+            expect(payload.state).toBe("no_spec");
+            expect(payload.nextActions.join("\n")).toContain("blueprint_synthesize");
+        });
+        it("pending proposal -> proposal_pending with prefilled apply coordinates", async () => {
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    hasPendingProposal: true,
+                    pendingProposal: {
+                        patch: {},
+                        basedOnSeq: 4,
+                        baseVersion: 1,
+                        summary: "First draft",
+                        citations: [
+                            { entryId: "e1", reason: "goal", provenance: "extracted" },
+                        ],
+                        createdAt: "2026-08-12T00:00:00Z",
+                    },
+                }),
+            });
+            expect(payload.state).toBe("proposal_pending");
+            expect(payload.nextActions.join("\n")).toContain("baseVersion=1 proposalBasedOnSeq=4");
+            expect(payload.proposal.citations).toBe(1);
+        });
+        it("open questions -> needs_answers with one answer call per question, then ONE synthesize", async () => {
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    document: {
+                        goal: "Do the thing",
+                        steps: [{ id: "s1" }],
+                        openQuestions: ["Which account?", "What about refunds?"],
+                    },
+                }),
+            });
+            expect(payload.state).toBe("needs_answers");
+            const actions = payload.nextActions.join("\n");
+            expect(actions).toContain('question="Which account?"');
+            expect(actions).toContain('question="What about refunds?"');
+            expect(actions).toContain("blueprint_synthesize once");
+        });
+        it("needs_input build -> answer_build_question prefilled + question_needs_human blocker", async () => {
+            const payload = await resolve({
+                "/routes/route-1/builds/b-1": {
+                    id: "b-1",
+                    status: "needs_input",
+                    questions: [{ id: "q1", text: "Which credentials?" }],
+                },
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    state: "building",
+                    buildStatus: "needs_input",
+                    middlewareId: "mw-1",
+                    routeId: "route-1",
+                    buildId: "b-1",
+                    document: { goal: "g", steps: [{ id: "s1" }] },
+                }),
+            });
+            expect(payload.state).toBe("needs_input");
+            const actions = payload.nextActions.join("\n");
+            expect(actions).toContain("answer_build_question workspaceId=11 middlewareId=mw-1 routeId=route-1 buildId=b-1 questionId=q1");
+            expect(payload.blockers.map((b) => b.kind)).toContain("question_needs_human");
+        });
+        it("UNLINKED blueprint whose library moved past a non-empty spec -> spec_stale, not job_stale", async () => {
+            // The service folds !routeId to never_synced regardless of drift; the
+            // specStale boolean is what must drive the synthesize-first branch.
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                    { id: "e2", kind: "note", title: "Late addition", status: "ready", seq: 2 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    state: "never_synced",
+                    specStale: true,
+                    headVersion: 1,
+                    librarySeq: 2,
+                    document: { goal: "g", steps: [{ id: "s1" }], openQuestions: [] },
+                    drift: {
+                        newEntries: [
+                            { id: "e2", kind: "note", title: "Late addition", seq: 2 },
+                        ],
+                        unsyncedVersions: [],
+                    },
+                }),
+            });
+            expect(payload.state).toBe("spec_stale");
+            expect(payload.nextActions.join("\n")).toContain("blueprint_synthesize");
+        });
+        it("never_synced with a ready spec -> job_stale -> blueprint_build", async () => {
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    document: {
+                        goal: "Do the thing",
+                        steps: [{ id: "s1" }],
+                        openQuestions: [],
+                    },
+                    headVersion: 2,
+                }),
+            });
+            expect(payload.state).toBe("job_stale");
+            expect(payload.nextActions.join("\n")).toContain("blueprint_build");
+        });
+        it("spec_stale from answer notes only -> flags answerNotesOnly and one synthesize", async () => {
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [
+                    {
+                        id: "e2",
+                        kind: "note",
+                        title: "Answer: Which account?",
+                        status: "ready",
+                        seq: 5,
+                        content: { answersQuestion: "Which account?" },
+                    },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    state: "spec_stale",
+                    specStale: true,
+                    routeId: "route-1",
+                    middlewareId: "mw-1",
+                    document: { goal: "g", steps: [{ id: "s1" }], openQuestions: [] },
+                    drift: {
+                        newEntries: [
+                            {
+                                id: "e2",
+                                kind: "note",
+                                title: "Answer: Which account?",
+                                seq: 5,
+                            },
+                        ],
+                        unsyncedVersions: [],
+                    },
+                }),
+            });
+            expect(payload.state).toBe("spec_stale");
+            expect(payload.drift.answerNotesOnly).toBe(true);
+            expect(payload.nextActions.join("\n")).toContain("answer notes ONLY");
+        });
+        it("job_ahead -> import-cases fold-back or rebuild", async () => {
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    state: "job_ahead",
+                    jobEditedDirectly: true,
+                    routeId: "route-1",
+                    middlewareId: "mw-1",
+                    document: { goal: "g", steps: [{ id: "s1" }] },
+                }),
+            });
+            expect(payload.state).toBe("job_ahead");
+            const actions = payload.nextActions.join("\n");
+            expect(actions).toContain("blueprint_import_cases");
+            expect(actions).toContain("blueprint_build");
+        });
+        it("failed enrichment surfaces an enrichment_failed blocker", async () => {
+            const payload = await resolve({
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                    {
+                        id: "e2",
+                        kind: "video",
+                        title: "Broken Loom",
+                        status: "failed",
+                        error: "fetch failed",
+                        seq: 2,
+                    },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    document: { goal: "g", steps: [{ id: "s1" }] },
+                }),
+            });
+            const blocker = payload.blockers.find((b) => b.kind === "enrichment_failed");
+            expect(blocker).toBeTruthy();
+            expect(blocker.entries[0].error).toBe("fetch failed");
+        });
+        it("a build queued past the stall threshold surfaces builder_stalled with queuedForMs", async () => {
+            const payload = await resolve({
+                "/routes/route-1/builds/b-1": {
+                    id: "b-1",
+                    status: "queued",
+                    createdAt: new Date(Date.now() - 10 * 60 * 1000).toISOString(),
+                },
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    state: "building",
+                    buildStatus: "queued",
+                    middlewareId: "mw-1",
+                    routeId: "route-1",
+                    buildId: "b-1",
+                    document: { goal: "g", steps: [{ id: "s1" }] },
+                }),
+            });
+            expect(payload.state).toBe("building");
+            const blocker = payload.blockers.find((b) => b.kind === "builder_stalled");
+            expect(blocker).toBeTruthy();
+            expect(blocker.queuedForMs).toBeGreaterThan(2 * 60 * 1000);
+        });
+        it("in_sync -> nothing to do, with the job-side handoff", async () => {
+            const payload = await resolve({
+                "/routes/route-1/builds/b-1": { id: "b-1", status: "green" },
+                "/blueprints/bp-1/entries": [
+                    { id: "e1", kind: "doc", title: "SOP", status: "ready", seq: 1 },
+                ],
+                "/blueprints/bp-1": bpFixture({
+                    state: "in_sync",
+                    routeId: "route-1",
+                    middlewareId: "mw-1",
+                    buildId: "b-1",
+                    buildStatus: "green",
+                    document: { goal: "g", steps: [{ id: "s1" }] },
+                }),
+            });
+            expect(payload.state).toBe("in_sync");
+            expect(payload.nextActions.join("\n")).toContain("resolve_job_state workspaceId=11 middlewareId=mw-1 routeId=route-1");
+        });
+    });
+    // ── resolve_job_state ownership block ──────────────────────
+    it("resolve_job_state flags a blueprint-owned route and points at the spec", async () => {
+        const fetchMock = routedFetch({
+            "/route-1/test-cases": [],
+            "/route-1/test-runs": {
+                content: [],
+                totalElements: 0,
+                totalPages: 0,
+                number: 0,
+                size: 3,
+            },
+            "/route-1/executions": {
+                content: [],
+                totalElements: 0,
+                totalPages: 0,
+                number: 0,
+                size: 10,
+            },
+            "/route-1/builds": [],
+            "/routes": [{ id: "route-1", method: "POST", path: "/coi" }],
+            "/api/workspaces/11/blueprints": [
+                {
+                    id: "bp-9",
+                    name: "COI intake",
+                    state: "in_sync",
+                    middlewareId: "mw-1",
+                    routeId: "route-1",
+                },
+            ],
+        });
+        vi.stubGlobal("fetch", fetchMock);
+        const { client, embedded } = await startServer();
+        try {
+            const result = await client.callTool({
+                name: "resolve_job_state",
+                arguments: {
+                    workspaceId: 11,
+                    middlewareId: "mw-1",
+                    routeId: "route-1",
+                },
+            });
+            const payload = parseToolJson(result);
+            expect(payload.blueprint).toEqual({
+                blueprintId: "bp-9",
+                state: "in_sync",
+                hint: expect.stringContaining("resolve_blueprint_state blueprintId=bp-9"),
+            });
+            const actions = payload.nextActions.join("\n");
+            expect(actions).toContain("OWNED by blueprint bp-9");
+            // The route has no test cases and no definition — on an owned route the
+            // resolver must route BOTH gaps through the spec, never recommend the
+            // direct job edits its own ownership warning forbids.
+            expect(actions).not.toContain("add_test_case (input + assertions)");
+            expect(actions).not.toContain("teach_job (example input + intent)");
+            expect(actions).not.toContain("update_job variant=draft with a step graph");
+            expect(actions).toContain("blueprint_build blueprintId=bp-9");
+        }
+        finally {
+            await client.close();
+            await embedded.close();
+        }
+    });
+});
+//# sourceMappingURL=blueprints-tools.test.js.map