@mnemom/mnemom 0.8.0 → 0.9.1

package/dist/commands/card.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { spawnSync } from "node:child_process";
 import yaml from "js-yaml";
-import { getAlignmentCard, putAlignmentCard, resolveAgentId, } from "../lib/api.js";
+import { ALIGNMENT_CARD_MAX_BYTES, getAlignmentCard, putAlignmentCard, resolveAgentId, } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
@@ -26,133 +26,491 @@ export function parseCardFile(filePath) {
     }
     return { format, parsed: JSON.parse(raw), raw };
 }
-// Standard AAP values that do not require custom definitions
-const STANDARD_VALUES = new Set([
-    "transparency", "honesty", "safety", "privacy", "fairness",
-    "accountability", "beneficence", "non-maleficence", "autonomy",
-    "justice", "reliability", "security", "human_oversight", "explainability",
-]);
+const ALIGNMENT_MODES = ["off", "observe", "nudge", "enforce"];
+const PRINCIPAL_TYPES = ["human", "organization", "agent", "unspecified"];
+const PRINCIPAL_RELATIONSHIPS = ["delegated_authority", "advisory", "autonomous"];
+const VALUE_HIERARCHIES = ["lexicographic", "weighted", "contextual"];
+const ESCALATION_ACTIONS = ["escalate", "deny", "log"];
+const CONSCIENCE_MODES = ["augment", "replace"];
+const CONSCIENCE_VALUE_TYPES = ["BOUNDARY", "FEAR", "COMMITMENT", "BELIEF", "HOPE"];
+const CONSCIENCE_SEVERITIES = ["advisory", "mandatory"];
+const TAMPER_EVIDENCE = ["append_only", "signed", "merkle"];
+const UNMAPPED_SEVERITIES = ["low", "medium", "high", "critical"];
+function isObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 /**
- * Validate a unified alignment card object against ADR-008 schema.
- * Sections: principal, values, conscience, integrity, autonomy,
- *           capabilities, enforcement, audit, extensions
+ * Validate a unified alignment card against ADR-039 canonical form.
+ *
+ * Required: card_version, agent_id, autonomy_mode, integrity_mode,
+ *           principal (with identifier when type != unspecified),
+ *           values.declared (non-empty), autonomy.bounded_actions (non-empty,
+ *           disjoint from forbidden_actions), audit (retention_days, queryable,
+ *           query_endpoint when queryable=true).
+ *
+ * Rejected legacy locations: integrity.enforcement_mode,
+ *   enforcement.{mode, unmapped_tool_action, fail_open}, _composition.
  */
 export function validateUnifiedCard(card) {
     const checks = [];
-    // Required sections
-    const requiredSections = ["principal", "values", "autonomy"];
-    for (const section of requiredSections) {
-        if (card[section] && typeof card[section] === "object") {
-            checks.push({ name: `Section: ${section}`, passed: true, message: "Present" });
+    // ── card_version (required) ──
+    if (typeof card.card_version !== "string" || card.card_version.length === 0) {
+        checks.push({
+            name: "card_version",
+            passed: false,
+            message: 'Required (string, e.g. "unified/2026-04-26").',
+        });
+    }
+    else {
+        checks.push({ name: "card_version", passed: true, message: card.card_version });
+    }
+    // ── agent_id (required) ──
+    if (typeof card.agent_id !== "string" || card.agent_id.length === 0) {
+        checks.push({ name: "agent_id", passed: false, message: "Required (string)." });
+    }
+    else {
+        checks.push({ name: "agent_id", passed: true, message: card.agent_id });
+    }
+    // ── autonomy_mode (top-level master switch, ADR-039 Decision 1) ──
+    if (typeof card.autonomy_mode !== "string") {
+        checks.push({
+            name: "autonomy_mode",
+            passed: false,
+            message: `Required (top-level master switch). Must be one of: ${ALIGNMENT_MODES.join(" | ")}. Per ADR-039 the legacy enforcement.mode location is no longer accepted.`,
+        });
+    }
+    else if (!ALIGNMENT_MODES.includes(card.autonomy_mode)) {
+        checks.push({
+            name: "autonomy_mode",
+            passed: false,
+            message: `Invalid: "${card.autonomy_mode}". Must be one of: ${ALIGNMENT_MODES.join(" | ")}.`,
+        });
+    }
+    else {
+        checks.push({ name: "autonomy_mode", passed: true, message: card.autonomy_mode });
+    }
+    // ── integrity_mode (top-level master switch, ADR-039 Decision 1) ──
+    if (typeof card.integrity_mode !== "string") {
+        checks.push({
+            name: "integrity_mode",
+            passed: false,
+            message: `Required (top-level master switch). Must be one of: ${ALIGNMENT_MODES.join(" | ")}. Per ADR-039 the legacy integrity.enforcement_mode location is no longer accepted.`,
+        });
+    }
+    else if (!ALIGNMENT_MODES.includes(card.integrity_mode)) {
+        checks.push({
+            name: "integrity_mode",
+            passed: false,
+            message: `Invalid: "${card.integrity_mode}". Must be one of: ${ALIGNMENT_MODES.join(" | ")}.`,
+        });
+    }
+    else {
+        checks.push({ name: "integrity_mode", passed: true, message: card.integrity_mode });
+    }
+    // ── ADR-039 cutover: reject legacy locations with a pointer to the new field ──
+    const integ = card.integrity;
+    if (integ && typeof integ === "object" && integ.enforcement_mode !== undefined) {
+        checks.push({
+            name: "integrity.enforcement_mode",
+            passed: false,
+            message: "Legacy field rejected. Use top-level integrity_mode instead (ADR-039).",
+        });
+    }
+    const enf = card.enforcement;
+    if (enf && typeof enf === "object") {
+        if (enf.mode !== undefined) {
+            checks.push({
+                name: "enforcement.mode",
+                passed: false,
+                message: "Legacy field rejected. Use top-level autonomy_mode instead (ADR-039).",
+            });
         }
-        else {
-            checks.push({ name: `Section: ${section}`, passed: false, message: "Missing or invalid" });
+        if (enf.unmapped_tool_action !== undefined) {
+            checks.push({
+                name: "enforcement.unmapped_tool_action",
+                passed: false,
+                message: "Legacy field rejected. Derived from enforcement.allow_unmapped_tools instead (ADR-039).",
+            });
         }
-    }
-    // Optional sections — validate shape if present
-    const optionalSections = ["conscience", "integrity", "capabilities", "enforcement", "audit", "extensions"];
-    for (const section of optionalSections) {
-        if (card[section] !== undefined) {
-            if (typeof card[section] === "object" && card[section] !== null) {
-                checks.push({ name: `Section: ${section}`, passed: true, message: "Present" });
-            }
-            else {
-                checks.push({ name: `Section: ${section}`, passed: false, message: "Must be an object" });
-            }
+        if (enf.fail_open !== undefined) {
+            checks.push({
+                name: "enforcement.fail_open",
+                passed: false,
+                message: "Legacy field rejected. fail_open is a runtime safety knob (gateway env config), not a card field (ADR-039).",
+            });
         }
     }
-    // values.declared is non-empty array
-    const values = card.values;
-    const declared = values?.declared;
-    if (Array.isArray(declared) && declared.length > 0) {
+    // _composition is system-managed
+    if (card._composition !== undefined) {
         checks.push({
-            name: "values.declared",
-            passed: true,
-            message: `${declared.length} value(s) declared`,
+            name: "_composition",
+            passed: false,
+            message: "System-managed field — cannot be set on inbound cards.",
         });
     }
-    else if (values) {
+    // ── principal (required: type + relationship; identifier when type != unspecified) ──
+    if (!isObj(card.principal)) {
+        checks.push({
+            name: "principal",
+            passed: false,
+            message: "Required (object with at least type + relationship).",
+        });
+    }
+    else {
+        const p = card.principal;
+        if (!PRINCIPAL_TYPES.includes(String(p.type))) {
+            checks.push({
+                name: "principal.type",
+                passed: false,
+                message: `Must be one of: ${PRINCIPAL_TYPES.join(", ")}.`,
+            });
+        }
+        if (!PRINCIPAL_RELATIONSHIPS.includes(String(p.relationship))) {
+            checks.push({
+                name: "principal.relationship",
+                passed: false,
+                message: `Must be one of: ${PRINCIPAL_RELATIONSHIPS.join(", ")}.`,
+            });
+        }
+        // ADR-039 Decision 10: identifier required when type != unspecified
+        if (p.type !== "unspecified" &&
+            PRINCIPAL_TYPES.includes(String(p.type)) &&
+            (typeof p.identifier !== "string" || p.identifier.length === 0)) {
+            checks.push({
+                name: "principal.identifier",
+                passed: false,
+                message: 'Required when principal.type is not "unspecified" (ADR-039 Decision 10).',
+            });
+        }
+    }
+    // ── values.declared (required, non-empty array of strings) ──
+    if (!isObj(card.values) || !Array.isArray(card.values.declared)) {
         checks.push({
             name: "values.declared",
             passed: false,
-            message: "Must be a non-empty array",
+            message: "Required (non-empty array of strings).",
         });
     }
-    // Custom values need definitions
-    if (Array.isArray(declared)) {
-        const definitions = (values?.definitions ?? {});
-        const customValues = declared.filter((v) => !STANDARD_VALUES.has(v));
-        const missingDefs = customValues.filter((v) => !definitions[v]);
-        if (missingDefs.length === 0) {
+    else {
+        const v = card.values;
+        const decl = v.declared;
+        if (decl.length === 0) {
             checks.push({
-                name: "Custom value definitions",
-                passed: true,
-                message: customValues.length === 0
-                    ? "No custom values (all standard)"
-                    : `${customValues.length} custom value(s) defined`,
+                name: "values.declared",
+                passed: false,
+                message: "Must contain at least one value.",
+            });
+        }
+        else if (!decl.every(s => typeof s === "string")) {
+            checks.push({
+                name: "values.declared",
+                passed: false,
+                message: "All entries must be strings.",
             });
         }
         else {
             checks.push({
-                name: "Custom value definitions",
+                name: "values.declared",
+                passed: true,
+                message: `${decl.length} value(s) declared`,
+            });
+        }
+        // definitions ⊆ declared (ADR-039 Decision 10)
+        if (v.definitions !== undefined) {
+            if (!isObj(v.definitions)) {
+                checks.push({
+                    name: "values.definitions",
+                    passed: false,
+                    message: "Must be an object keyed by value names.",
+                });
+            }
+            else {
+                const declSet = new Set(decl.filter((s) => typeof s === "string"));
+                for (const key of Object.keys(v.definitions)) {
+                    if (!declSet.has(key)) {
+                        checks.push({
+                            name: `values.definitions.${key}`,
+                            passed: false,
+                            message: "Definition key not present in values.declared (ADR-039 Decision 10).",
+                        });
+                    }
+                }
+            }
+        }
+        // hierarchy enum
+        if (v.hierarchy !== undefined && !VALUE_HIERARCHIES.includes(String(v.hierarchy))) {
+            checks.push({
+                name: "values.hierarchy",
                 passed: false,
-                message: `Missing definitions for: ${missingDefs.join(", ")}`,
+                message: `Must be one of: ${VALUE_HIERARCHIES.join(", ")}.`,
             });
         }
     }
-    // autonomy.bounded_actions is non-empty
-    const autonomy = card.autonomy;
-    const bounded = autonomy?.bounded_actions;
-    if (Array.isArray(bounded) && bounded.length > 0) {
+    // ── autonomy.bounded_actions (required, non-empty; disjoint from forbidden_actions) ──
+    if (!isObj(card.autonomy) || !Array.isArray(card.autonomy.bounded_actions)) {
         checks.push({
             name: "autonomy.bounded_actions",
-            passed: true,
-            message: `${bounded.length} bounded action(s)`,
+            passed: false,
+            message: "Required (non-empty array of strings).",
         });
     }
-    else if (autonomy) {
+    else {
+        const a = card.autonomy;
+        const bounded = a.bounded_actions;
+        if (bounded.length === 0) {
+            checks.push({
+                name: "autonomy.bounded_actions",
+                passed: false,
+                message: "Must contain at least one action.",
+            });
+        }
+        else {
+            checks.push({
+                name: "autonomy.bounded_actions",
+                passed: true,
+                message: `${bounded.length} bounded action(s)`,
+            });
+        }
+        // Disjoint check (ADR-039 Decision 10)
+        if (Array.isArray(a.forbidden_actions)) {
+            const forbidden = new Set(a.forbidden_actions.filter((x) => typeof x === "string"));
+            const overlap = bounded.filter((x) => typeof x === "string" && forbidden.has(x));
+            if (overlap.length > 0) {
+                checks.push({
+                    name: "autonomy.bounded_actions",
+                    passed: false,
+                    message: `bounded_actions and forbidden_actions must be disjoint; both contain: ${overlap.join(", ")} (ADR-039 Decision 10).`,
+                });
+            }
+        }
+        // escalation_triggers shape (ADR-039 Decision 10)
+        if (a.escalation_triggers !== undefined) {
+            if (!Array.isArray(a.escalation_triggers)) {
+                checks.push({
+                    name: "autonomy.escalation_triggers",
+                    passed: false,
+                    message: "Must be an array (may be empty).",
+                });
+            }
+            else {
+                a.escalation_triggers.forEach((t, i) => {
+                    if (!isObj(t)) {
+                        checks.push({
+                            name: `autonomy.escalation_triggers[${i}]`,
+                            passed: false,
+                            message: "Must be an object.",
+                        });
+                        return;
+                    }
+                    const tr = t;
+                    if (typeof tr.condition !== "string" || tr.condition.length === 0) {
+                        checks.push({
+                            name: `autonomy.escalation_triggers[${i}].condition`,
+                            passed: false,
+                            message: "Required (string).",
+                        });
+                    }
+                    if (!ESCALATION_ACTIONS.includes(String(tr.action))) {
+                        checks.push({
+                            name: `autonomy.escalation_triggers[${i}].action`,
+                            passed: false,
+                            message: `Must be one of: ${ESCALATION_ACTIONS.join(", ")}.`,
+                        });
+                    }
+                    if (typeof tr.reason !== "string" || tr.reason.length === 0) {
+                        checks.push({
+                            name: `autonomy.escalation_triggers[${i}].reason`,
+                            passed: false,
+                            message: "Required (string).",
+                        });
+                    }
+                });
+            }
+        }
+    }
+    // ── audit (required: retention_days, queryable; query_endpoint when queryable=true) ──
+    if (!isObj(card.audit)) {
         checks.push({
-            name: "autonomy.bounded_actions",
+            name: "audit",
             passed: false,
-            message: "Must be a non-empty array",
+            message: "Required (object with retention_days, queryable, trace_format).",
         });
     }
-    // capabilities shape validation (if present)
-    const capabilities = card.capabilities;
-    if (capabilities && typeof capabilities === "object") {
-        for (const [name, mapping] of Object.entries(capabilities)) {
-            const m = mapping;
-            if (!Array.isArray(m?.tools)) {
+    else {
+        const a = card.audit;
+        if (typeof a.retention_days !== "number" || a.retention_days < 0) {
+            checks.push({
+                name: "audit.retention_days",
+                passed: false,
+                message: "Required (non-negative number).",
+            });
+        }
+        if (typeof a.queryable !== "boolean") {
+            checks.push({
+                name: "audit.queryable",
+                passed: false,
+                message: "Required (boolean).",
+            });
+        }
+        if (a.queryable === true && typeof a.query_endpoint !== "string") {
+            checks.push({
+                name: "audit.query_endpoint",
+                passed: false,
+                message: "Required when audit.queryable is true.",
+            });
+        }
+        // ADR-039 Decision 7: tamper_evidence enum
+        if (a.tamper_evidence !== undefined && a.tamper_evidence !== null) {
+            if (!TAMPER_EVIDENCE.includes(String(a.tamper_evidence))) {
                 checks.push({
-                    name: `capabilities.${name}.tools`,
+                    name: "audit.tamper_evidence",
                     passed: false,
-                    message: "Must be an array",
+                    message: `Must be one of: ${TAMPER_EVIDENCE.join(", ")}, or null.`,
                 });
             }
-            if (!Array.isArray(m?.required_actions)) {
+        }
+        // ADR-039 cutover: audit.storage no longer accepted
+        if (a.storage !== undefined) {
+            checks.push({
+                name: "audit.storage",
+                passed: false,
+                message: "Legacy field rejected. audit.storage is no longer accepted (ADR-039).",
+            });
+        }
+    }
+    // ── conscience (optional, BOUNDARY+advisory rejected per ADR-039 Decision 10) ──
+    if (card.conscience !== undefined) {
+        if (!isObj(card.conscience)) {
+            checks.push({
+                name: "conscience",
+                passed: false,
+                message: "Must be an object if present.",
+            });
+        }
+        else {
+            const cns = card.conscience;
+            if (!CONSCIENCE_MODES.includes(String(cns.mode))) {
                 checks.push({
-                    name: `capabilities.${name}.required_actions`,
+                    name: "conscience.mode",
                     passed: false,
-                    message: "Must be an array",
+                    message: `Must be one of: ${CONSCIENCE_MODES.join(", ")}.`,
+                });
+            }
+            if (!Array.isArray(cns.values)) {
+                checks.push({
+                    name: "conscience.values",
+                    passed: false,
+                    message: "Must be an array.",
+                });
+            }
+            else {
+                cns.values.forEach((v, i) => {
+                    if (!isObj(v)) {
+                        checks.push({
+                            name: `conscience.values[${i}]`,
+                            passed: false,
+                            message: "Must be an object with type + content.",
+                        });
+                        return;
+                    }
+                    const cv = v;
+                    if (!CONSCIENCE_VALUE_TYPES.includes(String(cv.type))) {
+                        checks.push({
+                            name: `conscience.values[${i}].type`,
+                            passed: false,
+                            message: `Must be one of: ${CONSCIENCE_VALUE_TYPES.join(", ")}.`,
+                        });
+                    }
+                    if (typeof cv.content !== "string" || cv.content.length === 0) {
+                        checks.push({
+                            name: `conscience.values[${i}].content`,
+                            passed: false,
+                            message: "Required (non-empty string).",
+                        });
+                    }
+                    if (cv.severity !== undefined && !CONSCIENCE_SEVERITIES.includes(String(cv.severity))) {
+                        checks.push({
+                            name: `conscience.values[${i}].severity`,
+                            passed: false,
+                            message: `Must be one of: ${CONSCIENCE_SEVERITIES.join(", ")}.`,
+                        });
+                    }
+                    if (cv.type === "BOUNDARY" && cv.severity === "advisory") {
+                        checks.push({
+                            name: `conscience.values[${i}]`,
+                            passed: false,
+                            message: "BOUNDARY entries cannot have severity=advisory; BOUNDARY is inviolable by definition (ADR-039 Decision 10).",
+                        });
+                    }
                 });
             }
         }
     }
-    // enforcement.forbidden_tools shape validation (if present)
-    const enforcement = card.enforcement;
-    const forbidden = enforcement?.forbidden_tools;
-    if (Array.isArray(forbidden)) {
-        for (let i = 0; i < forbidden.length; i++) {
-            const rule = forbidden[i];
-            if (!rule?.pattern || !rule?.reason) {
+    // ── enforcement (optional, ADR-039 Decision 3 user-facing knobs) ──
+    if (card.enforcement !== undefined) {
+        if (!isObj(card.enforcement)) {
+            checks.push({
+                name: "enforcement",
+                passed: false,
+                message: "Must be an object if present.",
+            });
+        }
+        else {
+            const e = card.enforcement;
+            if (e.allow_unmapped_tools !== undefined && typeof e.allow_unmapped_tools !== "boolean") {
+                checks.push({
+                    name: "enforcement.allow_unmapped_tools",
+                    passed: false,
+                    message: "Must be a boolean.",
+                });
+            }
+            if (e.default_unmapped_severity !== undefined &&
+                !UNMAPPED_SEVERITIES.includes(String(e.default_unmapped_severity))) {
                 checks.push({
-                    name: `enforcement.forbidden_tools[${i}]`,
+                    name: "enforcement.default_unmapped_severity",
                     passed: false,
-                    message: "Must have 'pattern' and 'reason' fields",
+                    message: `Must be one of: ${UNMAPPED_SEVERITIES.join(", ")}.`,
                 });
             }
         }
     }
+    // ── capabilities (optional; ADR-039 cutover rejects required_actions) ──
+    if (card.capabilities !== undefined) {
+        if (!isObj(card.capabilities)) {
+            checks.push({
+                name: "capabilities",
+                passed: false,
+                message: "Must be an object if present.",
+            });
+        }
+        else {
+            for (const [name, mapping] of Object.entries(card.capabilities)) {
+                if (!isObj(mapping)) {
+                    checks.push({
+                        name: `capabilities.${name}`,
+                        passed: false,
+                        message: "Must be an object.",
+                    });
+                    continue;
+                }
+                const m = mapping;
+                if (m.tools !== undefined && !Array.isArray(m.tools)) {
+                    checks.push({
+                        name: `capabilities.${name}.tools`,
+                        passed: false,
+                        message: "Must be an array.",
+                    });
+                }
+                if (m.required_actions !== undefined) {
+                    checks.push({
+                        name: `capabilities.${name}.required_actions`,
+                        passed: false,
+                        message: "Legacy field rejected. capabilities.<n>.required_actions is no longer accepted (ADR-039).",
+                    });
+                }
+            }
+        }
+    }
     return checks;
 }
 /** @deprecated Use validateUnifiedCard instead */
@@ -191,7 +549,7 @@ export async function cardShowCommand(agentName) {
         process.exit(1);
     }
 }
-export async function cardPublishCommand(file, agentName) {
+export async function cardPublishCommand(file, agentName, options = {}) {
     const agentId = await resolveAgentId(agentName);
     // Resolve file path
     const filePath = path.resolve(file);
@@ -243,11 +601,19 @@ export async function cardPublishCommand(file, agentName) {
         console.log("\nPublishing alignment card...");
         const contentType = parsed.format === "yaml" ? "text/yaml" : "application/json";
         const body = parsed.format === "yaml" ? parsed.raw : JSON.stringify(parsed.parsed);
-        const result = await putAlignmentCard(agentId, body, contentType);
+        const bodyBytes = Buffer.byteLength(body, "utf-8");
+        if (bodyBytes > ALIGNMENT_CARD_MAX_BYTES) {
+            console.log("\n" +
+                fmt.error(`Alignment card is ${bodyBytes} bytes; limit is ${ALIGNMENT_CARD_MAX_BYTES} bytes (128 KB). The API will return 413.`) +
+                "\n");
+            process.exit(1);
+        }
+        const result = await putAlignmentCard(agentId, body, contentType, {
+            idempotencyKey: options.idempotencyKey,
+        });
         console.log(fmt.success("Alignment card published!"));
-        console.log(fmt.label("  Card ID:", ` ${result.card_id}`));
-        if (result.composed) {
-            console.log(fmt.success("Canonical card recomposed"));
+        if (typeof result.card_id === "string" && result.card_id.length > 0) {
+            console.log(fmt.label("  Card ID:", ` ${result.card_id}`));
         }
         console.log();
     }
@@ -301,7 +667,7 @@ export async function cardValidateCommand(file) {
         process.exit(1);
     }
 }
-export async function cardEditCommand(agentName) {
+export async function cardEditCommand(agentName, options = {}) {
     const agentId = await resolveAgentId(agentName);
     await requireAuth();
     // Fetch current card as YAML
@@ -311,9 +677,18 @@ export async function cardEditCommand(agentName) {
         console.log(fmt.warn("No alignment card found. Creating a template..."));
     }
     const cardYaml = original || yaml.dump({
-        principal: { name: "", type: "ai_agent", organization: "" },
+        card_version: "unified/2026-04-26",
+        agent_id: agentId,
+        autonomy_mode: "observe",
+        integrity_mode: "observe",
+        principal: { type: "agent", identifier: agentId, relationship: "delegated_authority" },
         values: { declared: ["transparency", "safety", "honesty"] },
-        autonomy: { bounded_actions: [], forbidden_actions: [], escalation_triggers: [] },
+        autonomy: {
+            bounded_actions: ["respond_to_prompts"],
+            forbidden_actions: [],
+            escalation_triggers: [],
+        },
+        audit: { retention_days: 30, queryable: false, trace_format: "otel" },
     }, { lineWidth: 120, noRefs: true });
     // Write to temp file
     const tmpDir = os.tmpdir();
@@ -375,9 +750,21 @@ export async function cardEditCommand(agentName) {
     }
     try {
         console.log("\nPublishing alignment card...");
-        const putResult = await putAlignmentCard(agentId, edited, "text/yaml");
+        const editedBytes = Buffer.byteLength(edited, "utf-8");
+        if (editedBytes > ALIGNMENT_CARD_MAX_BYTES) {
+            console.log("\n" +
+                fmt.error(`Alignment card is ${editedBytes} bytes; limit is ${ALIGNMENT_CARD_MAX_BYTES} bytes (128 KB). The API will return 413.`) +
+                "\n");
+            process.exit(1);
+        }
+        const putResult = await putAlignmentCard(agentId, edited, "text/yaml", {
+            idempotencyKey: options.idempotencyKey,
+        });
         console.log(fmt.success("Alignment card published!"));
-        console.log(fmt.label("  Card ID:", ` ${putResult.card_id}`) + "\n");
+        if (typeof putResult.card_id === "string" && putResult.card_id.length > 0) {
+            console.log(fmt.label("  Card ID:", ` ${putResult.card_id}`));
+        }
+        console.log();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);