@protocol-embedded-compliance/policy-cards

Machine-readable runtime governance for AI agents, complementing Protocol-Embedded Compliance (PEC).

Based on the Policy Cards framework by Juraj Mavračić.

Overview

Policy Cards provide a deployment-layer specification for expressing operational, regulatory, and ethical constraints for AI agents. They complement PEC's protocol-layer compliance metadata by defining:

• Rules: Allow/deny conditions referencing PEC metadata fields
• Escalation: Human oversight triggers and fallback actions
• Monitoring: Detectors and thresholds for runtime behavior
• KPIs: Measurable assurance metrics and critical auto-fail conditions
• Assurance Mapping: Crosswalk to NIST AI RMF, ISO/IEC 42001, and EU AI Act

Installation

pnpm add @protocol-embedded-compliance/policy-cards

Usage

Loading a Policy Card

import { loadPolicyCard } from '@protocol-embedded-compliance/policy-cards'

// From YAML file
const result = loadPolicyCard('./policy-cards/retail-banking.yaml')

// From string
const yamlContent = `
policy_card_version: "0.1"
name: "EU General Deployment"
scope:
  geography: ["EU", "EEA"]
rules:
  - id: geo-restriction
    effect: deny
    condition:
      field: pec.processing_locations
      operator: not_any_of
      values: ["EU", "EEA", "ADEQUACY"]
    reason: "Tool processes data outside approved jurisdictions"
`
const result = loadPolicyCard(yamlContent)

if (result.success) {
  console.log('Loaded:', result.policyCard.name)
}

Evaluating PEC Metadata Against a Policy Card

import { evaluatePolicyCard, loadPolicyCard } from '@protocol-embedded-compliance/policy-cards'
import type { PecComplianceMetadata } from '@protocol-embedded-compliance/mastra'

const { policyCard } = loadPolicyCard('./policy-cards/retail-banking.yaml')

const pecMetadata: PecComplianceMetadata = {
  pec_version: '1.0',
  processing_locations: ['DE', 'IE'],
  ai_act_status: {
    classification: 'limited',
    conformity_assessed: true
  },
  // ... other fields
}

const result = evaluatePolicyCard(policyCard!, pecMetadata, 'my-tool')

console.log('Compliant:', result.compliant)
console.log('Violations:', result.violations)
console.log('Assurance coverage:', result.assurance_coverage)

Filtering Tools by Policy Card

import { filterCompliantByPolicyCard, loadPolicyCard } from '@protocol-embedded-compliance/policy-cards'

const { policyCard } = loadPolicyCard('./policy-cards/retail-banking.yaml')

const tools = [
  { name: 'tool-a', compliance: pecMetadataA, tool: toolA },
  { name: 'tool-b', compliance: pecMetadataB, tool: toolB },
]

const { compliant, rejected } = filterCompliantByPolicyCard(policyCard!, tools)

console.log('Compliant tools:', compliant.map(t => t.name))
console.log('Rejected tools:', rejected.map(r => `${r.tool.name}: ${r.evaluation.violations[0]?.reason}`))

Auditing with Declare-Do-Audit Workflow

import { PolicyCardAuditor, loadPolicyCard } from '@protocol-embedded-compliance/policy-cards'

// DECLARE: Load and bind policy card
const { policyCard } = loadPolicyCard('./policy-cards/retail-banking.yaml')
const auditor = new PolicyCardAuditor(policyCard!)

// DO: Evaluate and record tool invocations
for (const tool of tools) {
  const { evaluation, evidence } = auditor.evaluateAndRecord(tool.name, tool.compliance)
  
  if (evaluation.compliant) {
    // Proceed with tool invocation
  } else {
    // Block or escalate
  }
}

// AUDIT: Generate report
const report = auditor.generateReport()
console.log(JSON.stringify(report, null, 2))

Policy Card Schema

See schemas/policy-card-schema-v0.1.json for the full JSON Schema.

Example Policy Card (YAML)

policy_card_version: "0.1"
name: "Retail Banking Payments Agent"
description: "Policy card for payment processing AI agent"

scope:
  ai_act_risk_level: high
  intended_uses:
    - payment_initiation
    - balance_inquiry
  geography:
    - EU
    - EEA

rules:
  - id: geo-restriction
    effect: deny
    condition:
      field: pec.processing_locations
      operator: not_any_of
      values: ["EU", "EEA", "ADEQUACY"]
    reason: "Tool processes data outside approved jurisdictions"
    
  - id: risk-ceiling
    effect: deny
    condition:
      field: pec.ai_act_status.classification
      operator: risk_exceeds
      threshold: limited
    reason: "Tool risk exceeds deployment threshold"

escalation:
  triggers:
    - condition: "transaction_value > 10000"
      action: human_approval_required

monitoring:
  detectors:
    - name: rejection_rate
      threshold: 0.3
      action: alert

kpis_thresholds:
  thresholds:
    - metric: compliance_rate
      target: 1.0
      critical_threshold: 0.95

assurance_mapping:
  nist: ["GOVERN-1", "MAP-1", "MEASURE-1"]
  iso_42001: ["ISO42001-4", "ISO42001-8"]
  eu_ai_act: ["EUAA-AnnexIV-3", "EUAA-Art72"]

Relationship to PEC

| Layer | Framework | Function | |-------|-----------|----------| | Protocol | PEC | MCP servers declare compliance metadata | | Deployment | Policy Cards | Defines what agents CAN/CANNOT do |

PEC provides standardised compliance information; Policy Cards provide constraint logic that consumes that information.

References

• Policy Cards Paper - Mavračić (2025)
• Protocol-Embedded Compliance - Jones (2026)
• NIST AI RMF
• ISO/IEC 42001
• EU AI Act

License

MIT