{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mnemom-ai/json-schema/mnemom-ai-unified-alignment-card-schema.json",
  "title": "UnifiedAlignmentCard",
  "description": "Unified alignment card (ADR-008/ADR-039). Authored in YAML or JSON; composed server-side with platform defaults, org template, and active exemptions before storage. This schema matches the runtime validator at src/composition/validate.ts EXACTLY — a card authored strictly to it passes `PUT /v1/agents/{id}/alignment-card` and the preview-compose endpoint. Output-only fields (card_id, issued_at, expires_at, _composition, content_hash, version) are server-assigned and must NOT be sent on a PUT.",
  "x-generated": "2026-11-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mnemom-ai-openapi.json#/components/schemas/UnifiedAlignmentCard",
  "type": "object",
  "required": [
    "card_version",
    "agent_id",
    "autonomy_mode",
    "integrity_mode",
    "principal",
    "values",
    "autonomy",
    "audit"
  ],
  "properties": {
    "card_version": {
      "type": "string",
      "minLength": 1,
      "description": "Card schema version (required, non-empty). Current canonical value: `unified/2026-04-26`."
    },
    "content_version": {
      "type": "string",
      "description": "Optional. Which default content the card carries, e.g. `mnemom-agent-default/2.1.0` (semver within a lineage). Distinct from `card_version`, the schema version. New agents are born with it; composition carries the agent card's value onto the canonical card."
    },
    "autonomy_mode": {
      "type": "string",
      "enum": [
        "off",
        "observe",
        "nudge",
        "enforce"
      ],
      "description": "ADR-039 master switch for the action-policing pipeline (autonomy constraints). Required at the top level post-cutover; the legacy `enforcement.mode` location is rejected."
    },
    "integrity_mode": {
      "type": "string",
      "enum": [
        "off",
        "observe",
        "nudge",
        "enforce"
      ],
      "description": "ADR-039 master switch for the values/conscience pipeline (integrity constraints). Required at the top level post-cutover; the legacy `integrity.enforcement_mode` location is rejected."
    },
    "card_id": {
      "type": "string",
      "description": "Card row id. Server-assigned on PUT (`ac-{uuid}`)."
    },
    "agent_id": {
      "type": "string",
      "description": "Target agent id. On PUT, server overwrites to match the URL path."
    },
    "issued_at": {
      "type": "string",
      "format": "date-time"
    },
    "expires_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "principal": {
      "type": "object",
      "description": "Required object describing whose authority the agent acts under (ADR-039 Decision 10).",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "human",
            "organization",
            "agent",
            "unspecified"
          ]
        },
        "identifier": {
          "type": "string",
          "minLength": 1,
          "description": "Required (non-empty) when principal.type is not `unspecified`; identifies the human / organization / agent."
        },
        "relationship": {
          "type": "string",
          "enum": [
            "delegated_authority",
            "advisory",
            "autonomous"
          ]
        },
        "escalation_contact": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "relationship"
      ],
      "allOf": [
        {
          "if": {
            "properties": {
              "type": {
                "not": {
                  "const": "unspecified"
                }
              }
            }
          },
          "then": {
            "required": [
              "identifier"
            ]
          }
        }
      ]
    },
    "values": {
      "type": "object",
      "required": [
        "declared"
      ],
      "properties": {
        "declared": {
          "type": "array",
          "minItems": 1,
          "items": {
            "oneOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "additionalProperties": {
                  "type": "string"
                }
              }
            ]
          },
          "description": "Ordered list of declared values. Phase 1 cards-as-primitive: each entry is either a catalog-v1 ID string (e.g. `'accuracy'`) or a parameterized map carrying optional `intensity` / `domain` / `severity_on_violation` / `scope` (e.g. `{id: 'accuracy', domain: 'financial', severity_on_violation: 'critical'}`)."
        },
        "definitions": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "description": {
                "type": "string"
              },
              "priority": {
                "type": "number"
              }
            }
          }
        },
        "conflicts_with": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "hierarchy": {
          "type": "string",
          "enum": [
            "lexicographic",
            "weighted",
            "contextual"
          ]
        }
      }
    },
    "conscience": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "augment",
            "replace"
          ]
        },
        "values": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "type",
              "content"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "BOUNDARY",
                  "FEAR",
                  "COMMITMENT",
                  "BELIEF",
                  "HOPE"
                ]
              },
              "content": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "severity": {
                "type": "string",
                "enum": [
                  "advisory",
                  "mandatory"
                ]
              }
            }
          }
        }
      },
      "required": [
        "mode",
        "values"
      ]
    },
    "autonomy": {
      "type": "object",
      "required": [
        "bounded_actions"
      ],
      "properties": {
        "bounded_actions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        },
        "forbidden_actions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "escalation_triggers": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "condition",
              "action",
              "reason"
            ],
            "properties": {
              "condition": {
                "type": "string"
              },
              "action": {
                "type": "string",
                "enum": [
                  "escalate",
                  "deny",
                  "log"
                ]
              },
              "reason": {
                "type": "string"
              }
            }
          }
        },
        "max_autonomous_value": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            }
          }
        }
      }
    },
    "capabilities": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "required_actions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "enforcement": {
      "type": "object",
      "description": "Optional ADR-039 Decision-3 user-facing knobs for unmapped-tool handling. The legacy `mode`, `unmapped_tool_action` and `fail_open` keys are REJECTED by the validator (mode → top-level autonomy_mode; fail_open → gateway env config).",
      "properties": {
        "allow_unmapped_tools": {
          "type": "boolean",
          "description": "When true, tools not mapped to a capability are allowed by default."
        },
        "default_unmapped_severity": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high",
            "critical"
          ],
          "description": "Severity assigned to an unmapped tool when allow_unmapped_tools is false."
        },
        "forbidden_tools": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "pattern",
              "reason",
              "severity"
            ],
            "properties": {
              "pattern": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              },
              "severity": {
                "type": "string",
                "enum": [
                  "critical",
                  "high",
                  "medium",
                  "low"
                ]
              }
            }
          }
        },
        "grace_period_hours": {
          "type": "integer"
        }
      }
    },
    "audit": {
      "type": "object",
      "required": [
        "retention_days",
        "queryable"
      ],
      "allOf": [
        {
          "if": {
            "properties": {
              "queryable": {
                "const": true
              }
            },
            "required": [
              "queryable"
            ]
          },
          "then": {
            "required": [
              "query_endpoint"
            ]
          }
        }
      ],
      "properties": {
        "trace_format": {
          "type": "string"
        },
        "retention_days": {
          "type": "integer",
          "minimum": 0
        },
        "queryable": {
          "type": "boolean"
        },
        "query_endpoint": {
          "type": "string",
          "description": "Required when audit.queryable is true."
        },
        "tamper_evidence": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "append_only",
            "signed",
            "merkle",
            null
          ]
        },
        "storage": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "local",
                "remote",
                "distributed"
              ]
            },
            "location": {
              "type": "string"
            }
          }
        }
      }
    },
    "tier_modes": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "read": {
          "type": "string",
          "enum": [
            "off",
            "observe",
            "nudge",
            "enforce"
          ]
        },
        "in_scope_write": {
          "type": "string",
          "enum": [
            "off",
            "observe",
            "nudge",
            "enforce"
          ]
        },
        "out_of_scope": {
          "type": "string",
          "enum": [
            "off",
            "observe",
            "nudge",
            "enforce"
          ]
        },
        "protected": {
          "type": "string",
          "enum": [
            "off",
            "observe",
            "nudge",
            "enforce"
          ]
        }
      },
      "description": "Per-action risk tier modes for CLPI and AIP. Capped by `autonomy_mode` / `integrity_mode`: a tier can only lower them, and read-tier calls are never withheld. Composition is strictest-wins per tier (enforce > nudge > observe > off). Omitted from the composed card when no scope defines it."
    },
    "context_fold": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "enabled"
      ],
      "properties": {
        "enabled": {
          "type": "boolean"
        }
      },
      "description": "Owner opt-out of the header-less context fold. Absent means enabled; `enabled: false` turns the fold off for the agent. Composition is off-wins across scopes: an agent can turn it off for itself and an org template can force it off for every agent under it. Omitted from the composed card when no scope defines it."
    },
    "extensions": {
      "type": "object",
      "additionalProperties": true
    },
    "_composition": {
      "$ref": "#/$defs/CompositionMetadata"
    },
    "content_hash": {
      "type": "string",
      "description": "Response-only: content hash of the composed card (`sha256:<hex>`), injected by the GET/PUT response. Server-assigned — do not send on a PUT."
    },
    "version": {
      "type": "integer",
      "description": "Response-only: monotonic card version, injected by the GET/PUT response. Server-assigned — do not send on a PUT."
    }
  },
  "$defs": {
    "CompositionMetadata": {
      "type": "object",
      "description": "System-managed block describing which scope sources merged into the canonical card. Only returned when `?include_composition=true`.",
      "properties": {
        "canonical_id": {
          "type": "string"
        },
        "composed_at": {
          "type": "string",
          "format": "date-time"
        },
        "scopes_applied": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "scope": {
                "type": "string",
                "description": "`platform`, `org:<id>`, or `agent:<id>`."
              },
              "version": {
                "type": "integer"
              },
              "template_version": {
                "type": "integer"
              },
              "card_id": {
                "type": "string"
              }
            }
          }
        },
        "exemptions_applied": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "source_card_id": {
          "type": "string"
        },
        "source_policy_id": {
          "type": "string"
        }
      }
    }
  }
}