@mnemom/mnemom 0.12.1 → 0.13.0

package/dist/lib/api.js

@@ -26,15 +26,95 @@ function validateUrl(url) {
 export function newIdempotencyKey() {
     return randomUUID();
 }
+/**
+ * Extract the human message + code + details from a raw error body,
+ * tolerating all three live envelope shapes (prefer nested).
+ */
+export function normalizeApiError(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    let message;
+    let code;
+    let details;
+    const e = raw.error;
+    if (e && typeof e === "object") {
+        // Nested {error:{code,message,details}} (enforce-hook).
+        message = typeof e.message === "string" ? e.message : undefined;
+        code = typeof e.code === "string" ? e.code : undefined;
+        details = e.details;
+    }
+    else if (typeof e === "string") {
+        // Flat {error:"message"} (+ optional top-level code on auth routes).
+        message = e;
+    }
+    // Fallbacks: top-level message/code/details when the above didn't populate.
+    if (!message && typeof raw.message === "string")
+        message = raw.message;
+    if (!code && typeof raw.code === "string")
+        code = raw.code;
+    if (details === undefined)
+        details = raw.details;
+    const spec_deviation = raw.spec_deviation && typeof raw.spec_deviation === "object" ? raw.spec_deviation : undefined;
+    return { message, code, details, conflict_agent_id: raw.conflict_agent_id, spec_deviation };
+}
+/** Parse a non-OK Response body into normalized error fields (never throws). */
+export async function parseApiErrorBody(response) {
+    const raw = (await response.json().catch(() => null));
+    return normalizeApiError(raw);
+}
+/**
+ * Structured API error. `message` is the human-readable server message (or a
+ * fallback); `.status`/`.code`/`.details`/`.conflictAgentId` give callers a
+ * structured surface to branch on without parsing the message string.
+ * `instanceof MnemomApiError` narrows in command-layer catch blocks.
+ */
+export class MnemomApiError extends Error {
+    /** The wire HTTP status — may be a synthetic 500 from the enforce hook. */
+    status;
+    /**
+     * The TRUE intended status: `spec_deviation.original_status ?? status`. The
+     * enforce hook can rewrite an undocumented status to a synthetic 500; command
+     * layers MUST branch on `effectiveStatus` (not `status`) for 404/empty-state
+     * detection or they'll be fooled by the rewrite.
+     */
+    effectiveStatus;
+    code;
+    details;
+    conflictAgentId;
+    /** Top-level enforce-hook sibling (present only on a spec-rewritten body). */
+    specDeviation;
+    constructor(status, message, opts = {}) {
+        super(message);
+        this.name = "MnemomApiError";
+        this.status = status;
+        this.code = opts.code;
+        this.details = opts.details;
+        this.conflictAgentId = opts.conflictAgentId;
+        this.specDeviation = opts.specDeviation;
+        this.effectiveStatus = opts.specDeviation?.original_status ?? status;
+    }
+}
+/**
+ * Read a non-OK Response into a MnemomApiError, preferring the server message
+ * and falling back to `${fallback}: ${status}` when the body carried none.
+ * Captures the enforce-hook `spec_deviation` sibling so `.effectiveStatus`
+ * reflects the true intended status behind any synthetic-500 rewrite.
+ */
+export async function readApiError(response, fallback) {
+    const parsed = await parseApiErrorBody(response);
+    const message = parsed.message || `${fallback}: ${response.status}`;
+    return new MnemomApiError(response.status, message, {
+        code: parsed.code,
+        details: parsed.details,
+        conflictAgentId: parsed.conflict_agent_id,
+        specDeviation: parsed.spec_deviation,
+    });
+}
 async function fetchApi(endpoint) {
     const url = validateUrl(`${API_BASE}${endpoint}`);
     const response = await fetch(url);
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return response.json();
 }
@@ -58,16 +138,22 @@ export async function postApi(endpoint, body, opts = {}) {
         body: JSON.stringify(body),
     });
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: `HTTP ${response.status}`,
-        })));
-        const msg = "message" in error ? error.message : JSON.stringify(error);
-        // Preserve conflict_agent_id in the error message for 409 handling upstream
-        if (response.status === 409 && "conflict_agent_id" in error) {
-            throw new Error(`409: ${msg} (conflict: ${error.conflict_agent_id})`);
+        const parsed = await parseApiErrorBody(response);
+        const msg = parsed.message || `HTTP ${response.status}`;
+        // Preserve the 409 conflict_agent_id surface: carry it structurally on the
+        // error (.conflictAgentId) AND keep it in the message for back-compat with
+        // any callers still string-matching the old "409: ... (conflict: ...)" form.
+        if (response.status === 409 && parsed.conflict_agent_id) {
+            throw new MnemomApiError(409, `409: ${msg} (conflict: ${parsed.conflict_agent_id})`, {
+                code: parsed.code,
+                details: parsed.details,
+                conflictAgentId: parsed.conflict_agent_id,
+            });
         }
-        throw new Error(`${response.status}: ${msg}`);
+        throw new MnemomApiError(response.status, `${response.status}: ${msg}`, {
+            code: parsed.code,
+            details: parsed.details,
+        });
     }
     return response.json();
 }
@@ -126,10 +212,9 @@ export async function listAgents() {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Failed to list agents: ${response.status}`);
+        throw await readApiError(response, "Failed to list agents");
     }
     const data = (await response.json());
     return data.agents ?? [];
@@ -146,10 +231,9 @@ export async function listMyOrgs() {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     const data = (await response.json());
     return data.orgs ?? [];
@@ -166,10 +250,9 @@ export async function getMyPersonalOrg() {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -211,13 +294,12 @@ export async function getTeam(teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found or not accessible.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found or not accessible.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -234,16 +316,15 @@ export async function getTeamTemplate(teamId, kind) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: not a member of team '${teamId}'s org.`);
+            throw new MnemomApiError(403, `Forbidden: not a member of team '${teamId}'s org.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -271,19 +352,18 @@ export async function putTeamTemplate(teamId, kind, yamlBody) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: org admin or owner role required to write a team template.`);
+            throw new MnemomApiError(403, `Forbidden: org admin or owner role required to write a team template.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
         if (response.status === 413) {
-            throw new Error(`Template too large (server limit: 128 KiB alignment / 64 KiB protection).`);
+            throw new MnemomApiError(413, `Template too large (server limit: 128 KiB alignment / 64 KiB protection).`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -305,16 +385,15 @@ export async function deleteTeamTemplate(teamId, kind) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: org admin or owner role required to clear a team template.`);
+            throw new MnemomApiError(403, `Forbidden: org admin or owner role required to clear a team template.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -337,8 +416,7 @@ export async function previewComposeTeamTemplate(teamId, kind, yamlBody) {
         body: yamlBody,
     }));
     if (!response.ok) {
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Preview failed: ${response.status}`);
+        throw await readApiError(response, "Preview failed");
     }
     const body = (await response.json());
     return { composed: body.composed, conflicts: body.conflicts };
@@ -365,16 +443,15 @@ export async function grantTeamAdmin(teamId, userId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: org owner or admin role required, and target user must be in the team's org.`);
+            throw new MnemomApiError(403, `Forbidden: org owner or admin role required, and target user must be in the team's org.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -398,16 +475,15 @@ export async function revokeTeamAdmin(teamId, userId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: revoke requires org owner/admin, or self-revoke with an active grant.`);
+            throw new MnemomApiError(403, `Forbidden: revoke requires org owner/admin, or self-revoke with an active grant.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -422,16 +498,15 @@ export async function listTeamAdmins(teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: requires membership in the team's org.`);
+            throw new MnemomApiError(403, `Forbidden: requires membership in the team's org.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -472,11 +547,7 @@ export async function getIntegrity(id) {
         headers: await authHeaders(),
     }));
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     // Accept both the canonical docs shape (object) and the RPC-wrapped shape
     // (array of one row). The latter is what prod actually returns today on
@@ -518,11 +589,7 @@ export async function getTraces(id, limit = 10) {
         headers: await authHeaders(),
     }));
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     const data = (await response.json());
     // Accept both the envelope shape (current API) and a bare array (defensive
@@ -531,105 +598,6 @@ export async function getTraces(id, limit = 10) {
         return data;
     return data.traces ?? [];
 }
-export async function getCard(agentId) {
-    try {
-        return await fetchApi(`/v1/agents/${agentId}/card`);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("404") || message.includes("not found")) {
-            return null;
-        }
-        throw error;
-    }
-}
-export async function updateCard(agentId, cardJson, opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/card`);
-    const response = await fetch(url, {
-        method: "PATCH",
-        headers: {
-            "Content-Type": "application/json",
-            "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
-            ...(await authHeaders()),
-        },
-        body: sanitizeForHttp(JSON.stringify({ card_json: cardJson })),
-    });
-    if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Card update failed: ${response.status}`);
-    }
-    return response.json();
-}
-export async function reverifyAgent(agentId, opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/reverify`);
-    const response = await fetch(url, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
-            ...(await authHeaders()),
-        },
-    });
-    if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Reverify failed: ${response.status}`);
-    }
-    return response.json();
-}
-export async function getPolicy(agentId) {
-    try {
-        return await fetchApi(`/v1/agents/${agentId}/policy`);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("404") || message.includes("not found")) {
-            return null;
-        }
-        throw error;
-    }
-}
-export async function publishPolicy(agentId, policyJson, opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/policy`);
-    const response = await fetch(url, {
-        method: "PUT",
-        headers: {
-            "Content-Type": "application/json",
-            "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
-            ...(await authHeaders()),
-        },
-        body: sanitizeForHttp(JSON.stringify({ policy_json: policyJson })),
-    });
-    if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Policy publish failed: ${response.status}`);
-    }
-    return response.json();
-}
-export async function testPolicyHistorical(agentId, policyJson, limit = 50) {
-    const url = validateUrl(`${API_BASE}/v1/policies/evaluate/historical`);
-    const response = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...(await authHeaders()) },
-        body: sanitizeForHttp(JSON.stringify({ agent_id: agentId, policy_json: policyJson, limit })),
-    });
-    if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Historical evaluation failed: ${response.status}`);
-    }
-    return response.json();
-}
 // ============================================================================
 // Unified Card API (UC-4+)
 // ============================================================================
@@ -647,11 +615,7 @@ export async function getAlignmentCard(agentId, format = "yaml") {
         if (response.status === 404) {
             return { body: "", contentType: "" };
         }
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Failed to fetch alignment card: ${response.status}`);
+        throw await readApiError(response, "Failed to fetch alignment card");
     }
     const ct = response.headers.get("content-type") ?? "";
     const body = await response.text();
@@ -689,11 +653,7 @@ export async function putAlignmentCard(agentId, body, contentType = "text/yaml",
         body: sanitizedBody,
     }));
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Failed to publish alignment card: ${response.status}`);
+        throw await readApiError(response, "Failed to publish alignment card");
     }
     return response.json();
 }
@@ -710,11 +670,7 @@ export async function getProtectionCard(agentId, format = "yaml") {
         if (response.status === 404) {
             return { body: "", contentType: "" };
         }
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Failed to fetch protection card: ${response.status}`);
+        throw await readApiError(response, "Failed to fetch protection card");
     }
     const ct = response.headers.get("content-type") ?? "";
     const body = await response.text();
@@ -744,14 +700,50 @@ export async function putProtectionCard(agentId, body, contentType = "text/yaml"
         body: sanitizedBody,
     }));
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Failed to publish protection card: ${response.status}`);
+        throw await readApiError(response, "Failed to publish protection card");
     }
     return response.json();
 }
+/**
+ * Dry-run validate + compose a card body against the server's authoritative
+ * pipeline. Returns a structured result — a 422/400 validation failure is an
+ * expected `valid:false` outcome (NOT a thrown error). 401 throws (caller
+ * should fall back to offline validation); 403/5xx throw a MnemomApiError.
+ */
+export async function previewComposeAgentCard(agentId, kind, body, contentType = "text/yaml") {
+    const url = validateUrl(`${API_BASE}/v1/${kind}/agent/${encodeURIComponent(agentId)}/preview-compose`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: { ...(await authHeaders()), "Content-Type": contentType, Accept: "application/json" },
+        body: sanitizeForHttp(body),
+    }));
+    if (response.ok) {
+        const data = (await response.json());
+        return {
+            valid: true,
+            status: response.status,
+            composed: data.composed,
+            conflicts: data.conflicts ?? [],
+            coherence_violations: data.coherence_violations ?? [],
+        };
+    }
+    // 401 → unauthenticated: signal the caller to fall back to offline validation.
+    if (response.status === 401) {
+        throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+    }
+    // 400 / 422 → the card is invalid: an expected validation outcome, not an
+    // exception. Surface the care-framed findings structurally.
+    if (response.status === 400 || response.status === 422) {
+        const parsed = await parseApiErrorBody(response);
+        return {
+            valid: false,
+            status: response.status,
+            error: { code: parsed.code, message: parsed.message, details: parsed.details },
+        };
+    }
+    // 403 / 5xx → a genuine error (e.g. not the owner, server fault).
+    throw await readApiError(response, "Card validation (preview-compose) failed");
+}
 // ============================================================================
 // Agent Resolution (server-side, no local config)
 // ============================================================================
@@ -809,13 +801,12 @@ export async function listPostures(opts) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: not a member of org '${opts.orgId}'.`);
+            throw new MnemomApiError(403, `Forbidden: not a member of org '${opts.orgId}'.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     const data = (await response.json());
     return data.postures ?? [];
@@ -828,14 +819,13 @@ export async function getPosture(postureId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 404)
-            throw new Error(`Posture '${postureId}' not found.`);
+            throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
         if (response.status === 403)
-            throw new Error(`Forbidden: not visible to your account.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+            throw new MnemomApiError(403, `Forbidden: not visible to your account.`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -847,11 +837,10 @@ export async function listPostureRevisions(postureId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 404)
-            throw new Error(`Posture '${postureId}' not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+            throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
+        throw await readApiError(response, "API request failed");
     }
     const data = (await response.json());
     return data.revisions ?? [];
@@ -864,13 +853,16 @@ export async function diffPostureRevisions(postureId, fromNo, toNo) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 404) {
-            const errBody = (await response.json().catch(() => ({})));
-            throw new Error(errBody.message || `Posture or revision not found.`);
+            const errBody = await parseApiErrorBody(response);
+            throw new MnemomApiError(404, errBody.message || `Posture or revision not found.`, {
+                code: errBody.code,
+                details: errBody.details,
+                specDeviation: errBody.spec_deviation,
+            });
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Diff failed: ${response.status}`);
+        throw await readApiError(response, "Diff failed");
     }
     return (await response.json());
 }
@@ -889,16 +881,15 @@ export async function createPosture(input) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403) {
-            throw new Error(`Forbidden: org owner/admin role required (or scope=platform reserved for migrations).`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin role required (or scope=platform reserved for migrations).`);
         }
         if (response.status === 409)
-            throw new Error(`A posture with this slug already exists in the org.`);
+            throw new MnemomApiError(409, `A posture with this slug already exists in the org.`);
         if (response.status === 413)
-            throw new Error(`Posture body too large (server limit: 256 KiB).`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Create failed: ${response.status}`);
+            throw new MnemomApiError(413, `Posture body too large (server limit: 256 KiB).`);
+        throw await readApiError(response, "Create failed");
     }
     return (await response.json());
 }
@@ -917,16 +908,15 @@ export async function updatePosture(postureId, input) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403) {
-            throw new Error(`Forbidden: org owner/admin required, or this is a Mnemom-shipped platform default (immutable — clone first).`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin required, or this is a Mnemom-shipped platform default (immutable — clone first).`);
         }
         if (response.status === 404)
-            throw new Error(`Posture '${postureId}' not found.`);
+            throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
         if (response.status === 413)
-            throw new Error(`Posture body too large (server limit: 256 KiB).`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Update failed: ${response.status}`);
+            throw new MnemomApiError(413, `Posture body too large (server limit: 256 KiB).`);
+        throw await readApiError(response, "Update failed");
     }
     return (await response.json());
 }
@@ -945,15 +935,14 @@ export async function clonePosture(postureId, input) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error(`Forbidden: org owner/admin required on target org.`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin required on target org.`);
         if (response.status === 404)
-            throw new Error(`Source posture '${postureId}' not found.`);
+            throw new MnemomApiError(404, `Source posture '${postureId}' not found.`);
         if (response.status === 409)
-            throw new Error(`A posture with this slug already exists in the target org.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Clone failed: ${response.status}`);
+            throw new MnemomApiError(409, `A posture with this slug already exists in the target org.`);
+        throw await readApiError(response, "Clone failed");
     }
     return (await response.json());
 }
@@ -970,16 +959,15 @@ export async function deletePosture(postureId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error(`Forbidden: platform defaults are immutable.`);
+            throw new MnemomApiError(403, `Forbidden: platform defaults are immutable.`);
         if (response.status === 404)
-            throw new Error(`Posture '${postureId}' not found.`);
+            throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
         if (response.status === 409) {
-            throw new Error(`Cannot delete a posture that is currently assigned to one or more teams. Unassign first.`);
+            throw new MnemomApiError(409, `Cannot delete a posture that is currently assigned to one or more teams. Unassign first.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Delete failed: ${response.status}`);
+        throw await readApiError(response, "Delete failed");
     }
 }
 /** POST /v1/postures/:id/assign — assign to a team. */
@@ -997,15 +985,14 @@ export async function assignPosture(postureId, teamId, pinRevisionNo) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error(`Forbidden: org owner/admin required on team's org.`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin required on team's org.`);
         if (response.status === 404) {
-            const errBody = (await response.json().catch(() => ({})));
-            throw new Error(errBody.message || `Posture, team, or pinned revision not found.`);
+            const errBody = await parseApiErrorBody(response);
+            throw new MnemomApiError(404, errBody.message || `Posture, team, or pinned revision not found.`, { code: errBody.code, details: errBody.details, specDeviation: errBody.spec_deviation });
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Assign failed: ${response.status}`);
+        throw await readApiError(response, "Assign failed");
     }
     return (await response.json());
 }
@@ -1022,14 +1009,13 @@ export async function unassignPosture(postureId, teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error(`Forbidden: org owner/admin required.`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin required.`);
         if (response.status === 404) {
-            throw new Error(`No matching assignment to remove (posture '${postureId}' is not assigned to team '${teamId}').`);
+            throw new MnemomApiError(404, `No matching assignment to remove (posture '${postureId}' is not assigned to team '${teamId}').`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Unassign failed: ${response.status}`);
+        throw await readApiError(response, "Unassign failed");
     }
 }
 /** POST /v1/postures/:id/preview-compose — preview effective for a team. */
@@ -1046,13 +1032,16 @@ export async function previewComposePosture(postureId, teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 404) {
-            const errBody = (await response.json().catch(() => ({})));
-            throw new Error(errBody.message || `Posture or team not found.`);
+            const errBody = await parseApiErrorBody(response);
+            throw new MnemomApiError(404, errBody.message || `Posture or team not found.`, {
+                code: errBody.code,
+                details: errBody.details,
+                specDeviation: errBody.spec_deviation,
+            });
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Preview-compose failed: ${response.status}`);
+        throw await readApiError(response, "Preview-compose failed");
     }
     return (await response.json());
 }
@@ -1076,13 +1065,12 @@ export async function listSidebandAdvisoriesForAgent(agentId, opts = {}) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error("Permission denied (need org membership).");
+            throw new MnemomApiError(403, "Permission denied (need org membership).");
         if (response.status === 404)
-            throw new Error(`Agent '${agentId}' not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `List advisories failed: ${response.status}`);
+            throw new MnemomApiError(404, `Agent '${agentId}' not found.`);
+        throw await readApiError(response, "List advisories failed");
     }
     return (await response.json());
 }
@@ -1106,13 +1094,12 @@ export async function listSidebandAdvisoriesForTeam(teamId, opts = {}) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error("Permission denied (need org membership).");
+            throw new MnemomApiError(403, "Permission denied (need org membership).");
         if (response.status === 404)
-            throw new Error(`Team '${teamId}' not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `List advisories failed: ${response.status}`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
+        throw await readApiError(response, "List advisories failed");
     }
     return (await response.json());
 }
@@ -1131,13 +1118,12 @@ export async function getTeamSidebandCoverage(teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error("Permission denied (need org membership).");
+            throw new MnemomApiError(403, "Permission denied (need org membership).");
         if (response.status === 404)
-            throw new Error(`Team '${teamId}' not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Coverage fetch failed: ${response.status}`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
+        throw await readApiError(response, "Coverage fetch failed");
     }
     return (await response.json());
 }
@@ -1154,11 +1140,10 @@ export async function getSafeHouseHarnessState() {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated. Run `mnemom login`.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login`.");
         if (response.status === 403)
-            throw new Error("Permission denied — `mnemom validate safe-house` is mnemom-staff only.");
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Harness state fetch failed: ${response.status}`);
+            throw new MnemomApiError(403, "Permission denied — `mnemom validate safe-house` is mnemom-staff only.");
+        throw await readApiError(response, "Harness state fetch failed");
     }
     return (await response.json());
 }
@@ -1195,13 +1180,12 @@ async function gFetch(path, init = {}, notFoundLabel) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error("Permission denied (need org admin / membership).");
+            throw new MnemomApiError(403, "Permission denied (need org admin / membership).");
         if (response.status === 404 && notFoundLabel)
-            throw new Error(`${notFoundLabel} not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Request failed: ${response.status}`);
+            throw new MnemomApiError(404, `${notFoundLabel} not found.`);
+        throw await readApiError(response, "Request failed");
     }
     return (await response.json());
 }
@@ -1286,10 +1270,9 @@ export async function listApiKeys() {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Failed to list api keys: ${response.status}`);
+        throw await readApiError(response, "Failed to list api keys");
     }
     const data = (await response.json());
     return data.keys ?? [];
@@ -1310,16 +1293,17 @@ export async function createApiKey(name, scopes) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const body = await response.text().catch(() => "");
+        const parsed = await parseApiErrorBody(response);
+        const detail = parsed.message || `HTTP ${response.status}`;
         if (response.status === 403) {
-            throw new Error(`Mint-time ceiling rejected scope: ${body}`);
+            throw new MnemomApiError(403, `Mint-time ceiling rejected scope: ${detail}`);
         }
         if (response.status === 400) {
-            throw new Error(`Invalid scope(s): ${body}`);
+            throw new MnemomApiError(400, `Invalid scope(s): ${detail}`);
         }
-        throw new Error(`Failed to create api key: ${response.status} ${body}`);
+        throw new MnemomApiError(response.status, `Failed to create api key: ${response.status} ${detail}`);
     }
     return (await response.json());
 }
@@ -1337,12 +1321,12 @@ export async function rotateApiKey(keyId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 404)
-            throw new Error(`Key not found: ${keyId}`);
-        const body = await response.text().catch(() => "");
-        throw new Error(`Failed to rotate api key: ${response.status} ${body}`);
+            throw new MnemomApiError(404, `Key not found: ${keyId}`);
+        const parsed = await parseApiErrorBody(response);
+        throw new MnemomApiError(response.status, `Failed to rotate api key: ${response.status} ${parsed.message ?? ""}`.trim());
     }
     return (await response.json());
 }
@@ -1358,14 +1342,48 @@ export async function revokeApiKey(keyId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 404)
-            throw new Error(`Key not found: ${keyId}`);
-        const body = await response.text().catch(() => "");
-        throw new Error(`Failed to revoke api key: ${response.status} ${body}`);
+            throw new MnemomApiError(404, `Key not found: ${keyId}`);
+        const parsed = await parseApiErrorBody(response);
+        throw new MnemomApiError(response.status, `Failed to revoke api key: ${response.status} ${parsed.message ?? ""}`.trim());
     }
 }
+/**
+ * POST /v1/license/validate — validate a license JWT for an instance.
+ *
+ * UNAUTHENTICATED by design (the license JWT IS the credential; this is a
+ * pre-login path) — sends NO auth header. Source-verified at canonical ref
+ * c18491e6 (handleLicenseValidate): the request body keys are
+ * `{ license, instance_id, instance_metadata }` (NOT `jwt`) — sending `jwt`
+ * would 400 "license is required".
+ *
+ * Returns the parsed validation result on 2xx (including the grace-period
+ * `valid:false` 200 body); throws MnemomApiError on non-2xx so the command
+ * renders `.message`/`.status`. This fixes the live H1 "[object Object]" bug:
+ * the old command-layer `err.error || "unknown"` string-coerced the nested
+ * `{code,message}` object that the enforce hook puts on the wire.
+ *
+ * `license deactivate` may reuse this (best-effort, fire-and-forget) by
+ * catching the throw at the command layer.
+ */
+export async function validateLicense(jwt, instanceId, instanceMetadata = {}) {
+    const url = validateUrl(`${API_BASE}/v1/license/validate`);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            license: sanitizeForHttp(jwt),
+            instance_id: instanceId,
+            instance_metadata: instanceMetadata,
+        }),
+    });
+    if (!response.ok) {
+        throw await readApiError(response, "License validation failed");
+    }
+    return (await response.json());
+}
 export async function reportRecipeFnFp(recipeId, input) {
     return postApi(`/v1/recipes/${encodeURIComponent(recipeId)}/report`, input);
 }