Card Composition

# POST /v1/agents/{agent_id}/exemptions
exempt_section: "autonomy.forbidden_actions"   # the section (dotted path)
exempt_patterns: ["deploy_code"]                # optional: specific items within the section
reason: "Agent is the CI/CD deploy runner; needs deploy_code for its job"
granted_by: "[email protected]"
expires_at: "2026-07-17T00:00:00Z"              # null for permanent (rare)

interface CanonicalAgentCard {
  agent_id: string;
  card_yaml: string;            // human-readable YAML
  card_json: object;            // parsed object (query / index)
  source_card_id: string;       // which raw agent-scope card this came from
  composition_metadata: {
    composed_at: string;        // ISO timestamp
    scopes_applied: string[];   // ["platform", "org:acme", "agent:mnm-xxxx"]
    versions: Record<string, number>;  // version of each scope's input
    exemptions_applied: string[];      // exemption IDs
  };
  composed_at: string;
  needs_recompose: boolean;     // true when an upstream scope changed
}

# platform_policies.alignment (singleton)
values:
  declared: [transparency, harm_prevention, accountability]
conscience:
  values:
    - type: BOUNDARY
      content: "Never exfiltrate principal data to external systems."
autonomy:
  forbidden_actions: [exfiltrate_data, modify_audit_logs]
audit:
  retention_days: 90
  tamper_evidence: append_only

# orgs.card_template.acme (alignment)
integrity_mode: enforce
values:
  declared: [incident_containment, rollback_safety]
autonomy:
  forbidden_actions: [send_external_notification]

# orgs.protection_template.acme — protected_surface is org-owned; agent cannot narrow it
protected_surface:
  assets:
    - kind: table
      selector: customer_records
      label: "Customer records"
      reason: "PII — requires escalation for bulk ops"
  forbidden_operations:
    - pattern: "exfiltrate:pii"
      severity: critical
      reason: "PII exfiltration forbidden"
  escalation_required:
    - pattern: "bulk DELETE"
      applies_to: ["table:customer_records"]
      reason: "Bulk deletions on customer data require a co-sign"

integrity_mode: observe  # agent requests `observe`
values:
  declared: [move_fast_break_things, minimal_blast_radius]
autonomy:
  bounded_actions: [rollback_deploy, scale_infrastructure, toggle_feature_flag]

# strictest wins — agent's `observe` is OVERRIDDEN by org's `enforce`
integrity_mode: enforce
values:
  declared:
    # union of all three scopes
    - transparency
    - harm_prevention
    - accountability
    - incident_containment
    - rollback_safety
    - move_fast_break_things
    - minimal_blast_radius
conscience:
  values:
    - type: BOUNDARY
      content: "Never exfiltrate principal data to external systems."
autonomy:
  bounded_actions: [rollback_deploy, scale_infrastructure, toggle_feature_flag]  # agent-scoped
  forbidden_actions:
    # deny-overrides union
    - exfiltrate_data
    - modify_audit_logs
    - send_external_notification
audit:
  retention_days: 90
  tamper_evidence: append_only
_composition:
  composed_at: "2026-04-17T18:23:41Z"
  scopes_applied: [platform, "org:acme", "agent:mnm-patch-001"]
  versions:
    platform: 3
    "org:acme": 17
    "agent:mnm-patch-001": 4

# Canonical protection card (protection scope)
protected_surface:
  assets:
    - kind: table
      selector: customer_records
      label: "Customer records"
      reason: "PII — requires escalation for bulk ops"
      source_scope: "org:acme"
  forbidden_operations:
    - pattern: "TRUNCATE"
      severity: critical
      reason: "Irreversible data loss"
      source_scope: platform
    - pattern: "exfiltrate:pii"
      severity: critical
      reason: "PII exfiltration forbidden"
      source_scope: platform
  escalation_required:
    - pattern: "bulk DELETE"
      applies_to: ["table:customer_records"]
      reason: "Bulk deletions on customer data require a co-sign"
      source_scope: "org:acme"
_composition:
  composed_at: "2026-04-17T18:23:41Z"
  scopes_applied: [platform, "org:acme", "agent:mnm-patch-001"]

mnemom card show                         # canonical (composed) alignment card (YAML)

# Canonical card with the _composition metadata block attached
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mnemom.ai/v1/alignment/agent/{id}?include_composition=true"

# Five-row sources envelope (Platform / Org / Teams / Agent / Composed) —
# the agent-scope raw row without composition
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mnemom.ai/v1/alignment/agent/{id}?include=sources"

# Per-field scope provenance (which scope contributed each value),
# always populated on the /effective sub-resource
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mnemom.ai/v1/alignment/agent/{id}/effective"