@minicor/mcp-server 4.8.0 → 4.9.0

package/dist/__live__/blueprints.live.test.js

@@ -0,0 +1,610 @@
+/**
+ * LIVE end-to-end suite for the blueprint_* MCP tool suite, exercising a REAL
+ * middleware-service — the layer above src/__tests__/blueprints-tools.test.ts
+ * (which mocks fetch). Every call here goes through the real MCP server
+ * (in-memory transport) into real HTTP against the service.
+ *
+ * GATING: the whole suite is skipped unless LIVE_MW_URL is set (so plain
+ * `npm test` / CI without a local stack never touches the network). The
+ * expected arrangement is the middleware-service smoke harness: the service's
+ * LAMINAR_API_URL pointed at scripts/smoke-sidecar.mjs, which accepts ANY
+ * bearer as user smoke@test in workspace $WORKSPACE_ID. scripts/live-tests.sh
+ * in this repo brings that up and tears it down (see docs/LIVE-TESTS.md).
+ *
+ * Env:
+ *   LIVE_MW_URL        e.g. http://localhost:4571 (required — gates the suite)
+ *   LIVE_MW_WORKSPACE  workspace id the sidecar grants (default 777)
+ *   LIVE_MW_TOKEN      bearer to present (default "live-mcp-tests"; the
+ *                      sidecar accepts anything)
+ *
+ * COST NOTE: exactly ONE test calls the real synthesis LLM (30–300s, costs
+ * money). Everything else uses cheap endpoints. States that need a real job
+ * build (building / needs_input / job_ahead) are unit-covered only.
+ *
+ * HYGIENE: every blueprint is created with a unique run-stamped name and
+ * deleted in afterEach, so parallel/repeat runs don't collide and the suite
+ * tolerates pre-existing data in the workspace.
+ */
+import { randomUUID } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { createMinicorServer } from "../lib.js";
+import { MiddlewareServiceClient } from "../middleware-service-client.js";
+const LIVE_URL = (process.env.LIVE_MW_URL ?? "").replace(/\/+$/, "");
+const WORKSPACE = Number(process.env.LIVE_MW_WORKSPACE ?? 777);
+const TOKEN = process.env.LIVE_MW_TOKEN ?? "live-mcp-tests";
+const RUN_STAMP = `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+const uniqueName = (suffix) => `live-mcp ${RUN_STAMP} ${suffix}`;
+/**
+ * A minimal document patch that passes the service's shape validation.
+ * NOTE the section envelope: screens/steps/credentials/exampleCases merge via
+ * { upsert, remove } (BlueprintPatch), not bare arrays — bare arrays no-op.
+ */
+const SPEC_PATCH = {
+    goal: "Review cost-center spend and flag anomalies",
+    screens: { upsert: [{ id: "scr-report", name: "Spend report" }] },
+    steps: {
+        upsert: [
+            {
+                id: "s1",
+                screenId: "scr-report",
+                intent: "Open the monthly spend report",
+            },
+        ],
+    },
+};
+const describeLive = LIVE_URL ? describe : describe.skip;
+if (!LIVE_URL) {
+    // eslint-disable-next-line no-console
+    console.log("[blueprints.live] LIVE_MW_URL is not set — skipping the live suite. " +
+        "Run scripts/live-tests.sh (or export LIVE_MW_URL=http://localhost:4571 " +
+        "with the smoke sidecar arrangement up) to execute it.");
+}
+describeLive("blueprint tools (LIVE middleware-service)", () => {
+    let client;
+    let embedded;
+    let raw;
+    const savedMwUrl = process.env.MIDDLEWARE_SERVICE_URL;
+    /** Blueprints created by the current test — deleted in afterEach. */
+    const created = [];
+    beforeAll(async () => {
+        // Route the MCP's middleware client straight at the live service.
+        process.env.MIDDLEWARE_SERVICE_URL = LIVE_URL;
+        // Fail fast with a legible message when the stack isn't actually up.
+        const health = await fetch(`${LIVE_URL}/health`).catch((e) => e);
+        if (health instanceof Error || !health.ok) {
+            throw new Error(`middleware-service is not healthy at ${LIVE_URL} — bring the stack up ` +
+                `first (see docs/LIVE-TESTS.md / scripts/live-tests.sh). ` +
+                `Probe result: ${health instanceof Error ? health.message : health.status}`);
+        }
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        embedded = await createMinicorServer(serverTransport, {
+            localTools: false,
+            credentials: {
+                access_token: TOKEN,
+                refresh_token: "live-refresh-unused",
+                expires_at: Date.now() + 3_600_000,
+            },
+            baseUrl: "https://api.test.invalid",
+            codeMode: false,
+        });
+        client = new Client({ name: "live-test-client", version: "1.0.0" });
+        await client.connect(clientTransport);
+        raw = new MiddlewareServiceClient(LIVE_URL, TOKEN);
+    });
+    afterAll(async () => {
+        await client?.close();
+        await embedded?.close();
+        if (savedMwUrl === undefined)
+            delete process.env.MIDDLEWARE_SERVICE_URL;
+        else
+            process.env.MIDDLEWARE_SERVICE_URL = savedMwUrl;
+    });
+    afterEach(async () => {
+        const ids = created.splice(0);
+        for (const id of ids) {
+            await raw.deleteBlueprint(WORKSPACE, id).catch(() => undefined);
+        }
+    });
+    /**
+     * Call a tool and parse its payload. ok() responses parse as JSON; text()
+     * error responses come back as { __text }.
+     */
+    async function call(name, args) {
+        const result = await client.callTool({
+            name,
+            arguments: { workspaceId: WORKSPACE, ...args },
+        });
+        const body = result.content?.[0]?.text ?? "";
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            return { __text: body, __isError: Boolean(result.isError) };
+        }
+    }
+    /** Create a tracked blueprint and return the created row. */
+    async function createBp(suffix) {
+        const payload = await call("blueprint_create", { name: uniqueName(suffix) });
+        expect(payload.status).toBe("created");
+        expect(typeof payload.blueprint?.id).toBe("string");
+        created.push(payload.blueprint.id);
+        return payload.blueprint;
+    }
+    // ════════════════════════════════════════════════════════════
+    // 1. LIFECYCLE WALK
+    // ════════════════════════════════════════════════════════════
+    it("lifecycle: create → get → add entries → list → update(CAS) → versions → delete", async () => {
+        const bp = await createBp("lifecycle");
+        expect(bp.name).toBe(uniqueName("lifecycle"));
+        // blueprint_get on a fresh blueprint: the advertised empty-state facts.
+        const got = await call("blueprint_get", { blueprintId: bp.id });
+        expect(got.blueprint.id).toBe(bp.id);
+        expect(got.blueprint.state).toBe("never_synced");
+        expect(got.blueprint.headVersion).toBe(0);
+        expect(got.blueprint.librarySeq).toBe(0);
+        expect(got.blueprint.pendingProposal).toBeNull();
+        expect(got.blueprint.drift).toEqual({ newEntries: [], unsyncedVersions: [] });
+        expect(got.inbox).toEqual({ openQuestions: [], pendingProposal: null });
+        // Note entry: not enrichable — ready immediately, bumps librarySeq.
+        const note = await call("blueprint_add_entry", {
+            blueprintId: bp.id,
+            kind: "note",
+            title: "SOP outline",
+            text: "Open the spend report, filter to the cost center, export the rows.",
+        });
+        expect(note.status).toBe("created");
+        expect(note.entry.kind).toBe("note");
+        expect(note.entry.status).toBe("ready");
+        expect(note.entry.seq).toBe(1);
+        // URL entry: enrichable — starts pending (or races straight to ready),
+        // and the tool tells you to poll before synthesizing.
+        const link = await call("blueprint_add_entry", {
+            blueprintId: bp.id,
+            kind: "url",
+            title: "Reference page",
+            url: "https://example.com/",
+        });
+        expect(link.status).toBe("created");
+        expect(["pending", "processing", "ready"]).toContain(link.entry.status);
+        if (link.entry.status !== "ready") {
+            expect(link.note).toContain("blueprint_list_entries");
+        }
+        // blueprint_list_entries: enrichment status is visible per row + counts.
+        const listed = await call("blueprint_list_entries", { blueprintId: bp.id });
+        expect(listed.counts.total).toBe(2);
+        expect(listed.counts.failed).toBe(0);
+        const byId = new Map(listed.entries.map((e) => [e.id, e]));
+        expect(byId.has(note.entry.id)).toBe(true);
+        expect(byId.has(link.entry.id)).toBe(true);
+        for (const e of listed.entries) {
+            expect(["pending", "processing", "ready", "failed"]).toContain(e.status);
+        }
+        if (listed.counts.pending > 0) {
+            expect(listed.note).toContain("enriching");
+        }
+        // blueprint_update with baseVersion: CAS write snapshots version 1.
+        const updated = await call("blueprint_update", {
+            blueprintId: bp.id,
+            patch: SPEC_PATCH,
+            note: "live-test: seed spec",
+            baseVersion: 0,
+        });
+        expect(updated.status).toBe("updated");
+        expect(updated.headVersion).toBe(1);
+        expect(updated.blueprint.document.goal).toBe(SPEC_PATCH.goal);
+        expect(updated.blueprint.document.steps).toHaveLength(1);
+        // blueprint_list_versions: the snapshot is there, and fetchable in full.
+        const versions = await call("blueprint_list_versions", {
+            blueprintId: bp.id,
+        });
+        expect(Array.isArray(versions.versions)).toBe(true);
+        expect(versions.versions.length).toBeGreaterThanOrEqual(1);
+        const v1 = await call("blueprint_list_versions", {
+            blueprintId: bp.id,
+            version: 1,
+        });
+        expect(v1.version).toBeTruthy();
+        // blueprint_list: our row shows up with the summary shape.
+        const all = await call("blueprint_list", {});
+        const row = all.blueprints.find((b) => b.id === bp.id);
+        expect(row).toBeTruthy();
+        expect(row.name).toBe(uniqueName("lifecycle"));
+        expect(typeof row.state).toBe("string");
+        // Delete cleanup, then read-after-delete is a structured 404.
+        await raw.deleteBlueprint(WORKSPACE, bp.id);
+        created.length = 0; // already gone; skip afterEach delete
+        const after = await call("blueprint_get", { blueprintId: bp.id });
+        expect(after.__text).toContain("404");
+        expect(after.__text.toLowerCase()).toContain("not found");
+        expect(after.__text).not.toMatch(/\n\s+at /); // no stack trace
+    });
+    // ════════════════════════════════════════════════════════════
+    // 2. resolve_blueprint_state LIVE DECISION TABLE
+    // ════════════════════════════════════════════════════════════
+    it("decision table: no_context → no_spec → needs_answers → answered (404-convergence) → spec_stale", async () => {
+        const bp = await createBp("decision");
+        // Fresh: no entries, empty spec → no_context, and (no linked route)
+        // resolve degrades sanely: link/build null, no blockers.
+        let r = await call("resolve_blueprint_state", { blueprintId: bp.id });
+        expect(r.state).toBe("no_context");
+        expect(r.backendState).toBe("never_synced");
+        expect(r.link).toBeNull();
+        expect(r.build).toBeNull();
+        expect(r.blockers).toEqual([]);
+        expect(r.resources).toMatchObject({ total: 0, ready: 0 });
+        expect(r.nextActions.join("\n")).toContain("blueprint_add_entry");
+        // Entries added + enriched (notes are ready instantly) → no_spec.
+        await call("blueprint_add_entry", {
+            blueprintId: bp.id,
+            kind: "note",
+            title: "How the review works",
+            text: "Pull the cost-center report every Monday and flag spend over budget.",
+        });
+        r = await call("resolve_blueprint_state", { blueprintId: bp.id });
+        expect(r.state).toBe("no_spec");
+        expect(r.resources).toMatchObject({ total: 1, ready: 1 });
+        expect(r.nextActions.join("\n")).toContain("blueprint_synthesize");
+        // Write openQuestions (plus a real spec) into the doc → needs_answers,
+        // with one prefilled answer call per question and the fold-once rule.
+        const up = await call("blueprint_update", {
+            blueprintId: bp.id,
+            patch: {
+                ...SPEC_PATCH,
+                openQuestions: ["Which cost center?", "Who approves exceptions?"],
+            },
+            note: "live-test: spec + questions",
+            baseVersion: r.blueprint.headVersion,
+        });
+        expect(up.status).toBe("updated");
+        r = await call("resolve_blueprint_state", { blueprintId: bp.id });
+        expect(r.state).toBe("needs_answers");
+        expect(r.openQuestions).toEqual([
+            "Which cost center?",
+            "Who approves exceptions?",
+        ]);
+        const answerActions = r.nextActions.join("\n");
+        expect(answerActions).toContain('question="Which cost center?"');
+        expect(answerActions).toContain('question="Who approves exceptions?"');
+        expect(answerActions).toContain("blueprint_synthesize once");
+        // Answer one question atomically.
+        const a1 = await call("blueprint_answer_question", {
+            blueprintId: bp.id,
+            question: "Which cost center?",
+            answer: "CC-1042 (Field Ops)",
+        });
+        expect(a1.status).toBe("answered");
+        expect(a1.remainingOpenQuestions).toEqual(["Who approves exceptions?"]);
+        expect(a1.driftNote).toContain("spec_stale");
+        // Answer the SAME question again → 404-convergence, not failure.
+        const a2 = await call("blueprint_answer_question", {
+            blueprintId: bp.id,
+            question: "Which cost center?",
+            answer: "CC-9999 (should not land)",
+        });
+        expect(a2.status).toBe("already_answered");
+        expect(a2.note).toContain("CONVERGENCE");
+        // Answer the last question → the tool points at ONE synthesize.
+        const a3 = await call("blueprint_answer_question", {
+            blueprintId: bp.id,
+            question: "Who approves exceptions?",
+            answer: "The finance lead",
+        });
+        expect(a3.status).toBe("answered");
+        expect(a3.remainingOpenQuestions).toEqual([]);
+        expect(a3.nextActions.join("\n")).toContain("blueprint_synthesize");
+        // Library (context note + 2 answer notes) moved past the spec → spec_stale.
+        // answerNotesOnly must be false: the first note is plain context.
+        r = await call("resolve_blueprint_state", { blueprintId: bp.id });
+        expect(r.state).toBe("spec_stale");
+        expect(r.drift.newEntries.length).toBeGreaterThanOrEqual(3);
+        expect(r.drift.answerNotesOnly).toBe(false);
+        expect(r.nextActions.join("\n")).toContain("blueprint_synthesize");
+        // Still no linked route — the build side keeps degrading sanely.
+        expect(r.link).toBeNull();
+        expect(r.build).toBeNull();
+        // The answer notes are real library rows with the provenance link.
+        const entries = await call("blueprint_list_entries", { blueprintId: bp.id });
+        const answers = entries.entries.filter((e) => e.kind === "note" && e.content?.answersQuestion);
+        expect(answers.map((e) => e.content.answersQuestion).sort()).toEqual([
+            "Which cost center?",
+            "Who approves exceptions?",
+        ]);
+    });
+    // ════════════════════════════════════════════════════════════
+    // 3. CAS UNDER FIRE
+    // ════════════════════════════════════════════════════════════
+    it("CAS under fire: two concurrent same-baseVersion updates — exactly one wins, the loser gets version_conflict", async () => {
+        const bp = await createBp("cas");
+        const seed = await call("blueprint_update", {
+            blueprintId: bp.id,
+            patch: { goal: "seed goal" },
+            note: "live-test: seed",
+            baseVersion: 0,
+        });
+        expect(seed.status).toBe("updated");
+        expect(seed.headVersion).toBe(1);
+        // Deterministic CAS: a write authored against version 0 AFTER the head
+        // committed version 1 — the loser must get the structured conflict with
+        // re-read guidance, never a raw error.
+        const stale = await call("blueprint_update", {
+            blueprintId: bp.id,
+            patch: { goal: "stale writer goal" },
+            note: "live-test: stale writer",
+            baseVersion: 0,
+        });
+        expect(stale.status).toBe("blocked");
+        expect(stale.blocked.reason).toBe("version_conflict");
+        expect(stale.blocked.retryable).toBe(true);
+        expect(stale.nextActions.join("\n")).toContain("blueprint_get");
+        expect(stale.nextActions.join("\n")).toContain("baseVersion");
+        // Concurrent same-base writers: EXACTLY one wins. The service runs the
+        // baseVersion check + write + version snapshot inside one row-locked
+        // transaction (middleware-service 5b3a8b3 — the CAS TOCTOU an earlier
+        // version of this test detected), so a double-win here is a regression
+        // and a hard failure.
+        const [x, y] = await Promise.all([
+            call("blueprint_update", {
+                blueprintId: bp.id,
+                patch: { goal: "writer A goal" },
+                note: "live-test: writer A",
+                baseVersion: 1,
+            }),
+            call("blueprint_update", {
+                blueprintId: bp.id,
+                patch: { goal: "writer B goal" },
+                note: "live-test: writer B",
+                baseVersion: 1,
+            }),
+        ]);
+        const winners = [x, y].filter((p) => p.status === "updated");
+        const losers = [x, y].filter((p) => p.status === "blocked");
+        expect(winners, `expected exactly one winner (CAS regression? see middleware 5b3a8b3): ${JSON.stringify([x.status ?? x.__text, y.status ?? y.__text])}`).toHaveLength(1);
+        expect(losers).toHaveLength(1);
+        expect(losers[0].blocked.reason).toBe("version_conflict");
+        expect(losers[0].blocked.retryable).toBe(true);
+        expect(losers[0].nextActions.join("\n")).toContain("blueprint_get");
+        // The surviving document is the winner's, at head 2.
+        const got = await call("blueprint_get", { blueprintId: bp.id });
+        expect(got.blueprint.headVersion).toBe(2);
+        expect(got.blueprint.document.goal).toBe(winners[0].blueprint.document.goal);
+    });
+    it("proposal guards without a proposal: reject → already_gone, apply → no_pending_proposal", async () => {
+        const bp = await createBp("proposal-guards");
+        // Reject with nothing pending: 404 is success-shaped.
+        const rejected = await call("blueprint_reject_proposal", {
+            blueprintId: bp.id,
+        });
+        expect(rejected.status).toBe("already_gone");
+        expect(rejected.note).toContain("Success-shaped");
+        // Apply with nothing pending: convergence, no error surface.
+        const applied = await call("blueprint_apply_proposal", {
+            blueprintId: bp.id,
+            baseVersion: 0,
+            proposalBasedOnSeq: 0,
+        });
+        expect(applied.status).toBe("no_pending_proposal");
+        expect(applied.note).toContain("convergence");
+        // get_proposal agrees and routes you to synthesize.
+        const gp = await call("blueprint_get_proposal", { blueprintId: bp.id });
+        expect(gp.status).toBe("no_pending_proposal");
+        expect(gp.nextActions.join("\n")).toContain("blueprint_synthesize");
+    });
+    // ════════════════════════════════════════════════════════════
+    // 4. THE ONE SYNTHESIS TEST (real LLM call — 30–300s, costs money)
+    // ════════════════════════════════════════════════════════════
+    it("synthesize → citations → get_proposal → swapped-guard → apply lands a spec", async (ctx) => {
+        if (process.env.LIVE_SKIP_SYNTHESIS) {
+            // eslint-disable-next-line no-console
+            console.log("[blueprints.live] SKIP synthesis test: LIVE_SKIP_SYNTHESIS is set " +
+                "(cost-saving knob — unset it for full coverage).");
+            ctx.skip();
+            return;
+        }
+        const bp = await createBp("synthesis");
+        const e1 = await call("blueprint_add_entry", {
+            blueprintId: bp.id,
+            kind: "note",
+            title: "SOP: submit a reimbursement",
+            text: "Open the expenses portal. Click 'New reimbursement'. Enter the amount and cost center CC-1042. Attach the receipt. Submit.",
+        });
+        const e2 = await call("blueprint_add_entry", {
+            blueprintId: bp.id,
+            kind: "note",
+            title: "Approval rules",
+            text: "Amounts under $100 auto-approve. Anything else routes to the finance lead for manual approval.",
+        });
+        expect(e1.entry.status).toBe("ready");
+        expect(e2.entry.status).toBe("ready");
+        const synthesizeOnce = () => call("blueprint_synthesize", {
+            blueprintId: bp.id,
+            instructions: "Keep the spec minimal: one screen, at most four steps, one example case.",
+        });
+        let syn = await synthesizeOnce();
+        // One retry for transient LLM-gateway failures (5xx/429 ride through the
+        // tool as an unstructured error text).
+        if (syn.__text && /failed \((5\d\d|429)\)/.test(syn.__text)) {
+            // eslint-disable-next-line no-console
+            console.warn(`[blueprints.live] transient synthesize failure, retrying once: ${syn.__text.slice(0, 300)}`);
+            await new Promise((r) => setTimeout(r, 10_000));
+            syn = await synthesizeOnce();
+        }
+        if (syn.status === "blocked" && syn.blocked?.reason === "llm_unconfigured") {
+            // eslint-disable-next-line no-console
+            console.log("[blueprints.live] SKIP synthesis test: the service has no synthesis " +
+                "LLM configured (set MINICOR_LLMS_API_KEY on middleware-service).");
+            ctx.skip();
+            return;
+        }
+        expect(syn.status, `unexpected synthesize payload: ${JSON.stringify(syn).slice(0, 1500)}`).toBe("proposal_ready");
+        const proposal = syn.proposal;
+        expect(proposal).toBeTruthy();
+        expect(typeof proposal.summary).toBe("string");
+        expect(proposal.summary.length).toBeGreaterThan(0);
+        // Citations must point at REAL entry ids and carry provenance tags.
+        const entryIds = new Set([e1.entry.id, e2.entry.id]);
+        expect(Array.isArray(proposal.citations)).toBe(true);
+        expect(proposal.citations.length).toBeGreaterThan(0);
+        for (const c of proposal.citations) {
+            expect(entryIds.has(c.entryId)).toBe(true);
+            expect(["extracted", "inferred", "ambiguous"]).toContain(c.provenance);
+        }
+        // get_proposal returns the exact apply coordinates.
+        const gp = await call("blueprint_get_proposal", { blueprintId: bp.id });
+        expect(gp.applyWith).toEqual({
+            baseVersion: proposal.baseVersion,
+            proposalBasedOnSeq: proposal.basedOnSeq,
+        });
+        // Stale coordinates → the swapped guard refuses (simulated stale reviewer).
+        const swapped = await call("blueprint_apply_proposal", {
+            blueprintId: bp.id,
+            baseVersion: gp.applyWith.baseVersion + 1,
+            proposalBasedOnSeq: gp.applyWith.proposalBasedOnSeq + 1,
+        });
+        expect(swapped.status).toBe("blocked");
+        expect(swapped.blocked.reason).toBe("proposal_swapped");
+        expect(swapped.nextActions.join("\n")).toContain("blueprint_get_proposal");
+        // Correct coordinates → applied; the doc now has real substance.
+        const applied = await call("blueprint_apply_proposal", {
+            blueprintId: bp.id,
+            baseVersion: gp.applyWith.baseVersion,
+            proposalBasedOnSeq: gp.applyWith.proposalBasedOnSeq,
+        });
+        expect(applied.status).toBe("applied");
+        expect(applied.headVersion).toBeGreaterThanOrEqual(1);
+        const got = await call("blueprint_get", { blueprintId: bp.id });
+        expect(got.blueprint.pendingProposal).toBeNull();
+        const doc = got.blueprint.document;
+        expect((doc.goal ?? "").length).toBeGreaterThan(0);
+        expect((doc.steps ?? []).length).toBeGreaterThan(0);
+        // Post-apply resolve: the spec is ahead of the (nonexistent) job —
+        // job_stale routes to blueprint_build, or needs_answers if the LLM left
+        // open questions on the spec.
+        const r = await call("resolve_blueprint_state", { blueprintId: bp.id });
+        expect(["job_stale", "needs_answers"]).toContain(r.state);
+        if (r.state === "job_stale") {
+            expect(r.nextActions.join("\n")).toContain("blueprint_build");
+        }
+    }, 360_000);
+    // ════════════════════════════════════════════════════════════
+    // 5. UPLOAD HANDSHAKE
+    // ════════════════════════════════════════════════════════════
+    it("upload handshake: upload_url → PUT blob → add_entry(blobRef) → downloadUrl fetches", async (ctx) => {
+        const bp = await createBp("upload");
+        const up = await call("blueprint_entry_upload_url", {
+            blueprintId: bp.id,
+            fileName: "live-upload.txt",
+        });
+        if (up.status === "blocked" && up.blocked?.reason === "blob_storage_unconfigured") {
+            // eslint-disable-next-line no-console
+            console.log("[blueprints.live] SKIP upload test: blob storage is not configured " +
+                "on the service (set JOB_ARTIFACTS_BUCKET and point " +
+                "GOOGLE_APPLICATION_CREDENTIALS at a service-account key).");
+            ctx.skip();
+            return;
+        }
+        expect(up.uploadUrl).toMatch(/^https?:\/\//);
+        expect(up.blobRef).toMatch(/^gs:\/\//);
+        expect(typeof up.expiresOn).toBe("string");
+        expect(up.nextActions.join("\n")).toContain("PUT the file bytes");
+        const body = `live upload payload ${RUN_STAMP}`;
+        // Plain PUT: GCS signed URLs need no extension headers.
+        const put = await fetch(up.uploadUrl, {
+            method: "PUT",
+            headers: { "Content-Type": "text/plain" },
+            body,
+        });
+        expect(put.status).toBeGreaterThanOrEqual(200);
+        expect(put.status).toBeLessThan(300);
+        const added = await call("blueprint_add_entry", {
+            blueprintId: bp.id,
+            kind: "doc",
+            title: "Uploaded doc",
+            blobRef: up.blobRef,
+            fileName: "live-upload.txt",
+            contentType: "text/plain",
+            sizeBytes: Buffer.byteLength(body, "utf8"),
+        });
+        expect(added.status).toBe("created");
+        expect(added.entry.blobRef).toBe(up.blobRef);
+        const one = await call("blueprint_list_entries", {
+            blueprintId: bp.id,
+            entryId: added.entry.id,
+            downloadUrl: true,
+        });
+        expect(one.entry.id).toBe(added.entry.id);
+        expect(one.downloadUrl).toMatch(/^https?:\/\//);
+        const dl = await fetch(one.downloadUrl);
+        expect(dl.status).toBe(200);
+        expect(await dl.text()).toBe(body);
+    });
+    // ════════════════════════════════════════════════════════════
+    // 6. ERROR SURFACES
+    // ════════════════════════════════════════════════════════════
+    it("nonexistent blueprint id → structured not-found, not a stack trace", async () => {
+        const ghost = randomUUID();
+        const got = await call("blueprint_get", { blueprintId: ghost });
+        expect(got.__text).toBeTruthy();
+        expect(got.__text).toContain("404");
+        expect(got.__text.toLowerCase()).toContain("not found");
+        expect(got.__text).not.toMatch(/\n\s+at /);
+        const resolved = await call("resolve_blueprint_state", {
+            blueprintId: ghost,
+        });
+        expect(resolved.__text).toContain("404");
+    });
+    it("malformed entry kind is rejected at the tool boundary (never hits the wire)", async () => {
+        const bp = await createBp("bad-kind");
+        let message = "";
+        try {
+            const result = await client.callTool({
+                name: "blueprint_add_entry",
+                arguments: {
+                    workspaceId: WORKSPACE,
+                    blueprintId: bp.id,
+                    kind: "sop", // not a valid BlueprintEntryKind
+                    title: "bogus",
+                },
+            });
+            message = result.content?.[0]?.text ?? "";
+            expect(result.isError).toBe(true);
+        }
+        catch (e) {
+            message = e.message; // SDK may throw InvalidParams instead
+        }
+        expect(message.toLowerCase()).toMatch(/kind|invalid|enum/);
+        // Nothing was created.
+        const listed = await call("blueprint_list_entries", { blueprintId: bp.id });
+        expect(listed.counts.total).toBe(0);
+    });
+    it("answering a question that was never open converges instead of failing", async () => {
+        const bp = await createBp("ghost-question");
+        const ans = await call("blueprint_answer_question", {
+            blueprintId: bp.id,
+            question: "Was this question ever asked?",
+            answer: "No.",
+        });
+        expect(ans.status).toBe("already_answered");
+        expect(ans.nextActions.join("\n")).toContain("blueprint_get");
+    });
+    it("blueprint_build on an empty spec surfaces the validator's problem list legibly", async () => {
+        const bp = await createBp("empty-build");
+        const built = await call("blueprint_build", { blueprintId: bp.id });
+        expect(built.status).toBe("blocked");
+        expect(built.blocked.reason).toBe("spec_not_syncable");
+        expect(built.blocked.retryable).toBe(true);
+        // The 400 problem list rides through the blocked message verbatim.
+        expect(built.blocked.message).toContain("goal is empty");
+        expect(built.blocked.message).toContain("no steps");
+        expect(built.nextActions.join("\n")).toContain("blueprint_update");
+    });
+    it("blueprint_synthesize on an empty library blocks with library_empty", async () => {
+        const bp = await createBp("empty-synth");
+        const syn = await call("blueprint_synthesize", { blueprintId: bp.id });
+        expect(syn.status).toBe("blocked");
+        expect(syn.blocked.reason).toBe("library_empty");
+        expect(syn.nextActions.join("\n")).toContain("blueprint_add_entry");
+    });
+});
+//# sourceMappingURL=blueprints.live.test.js.map