npm package: @protocol-embedded-compliance/policy-cards
Description: Policy Cards implementation for Protocol-Embedded Compliance - machine-readable runtime governance for AI agents
Author: Lloyd Jones
Latest version: 0.1.0

# @protocol-embedded-compliance/policy-cards

Machine-readable runtime governance for AI agents, complementing [Protocol-Embedded Compliance (PEC)](https://usepec.eu).

Based on the [Policy Cards](https://arxiv.org/html/2510.24383v1) 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

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

## Usage

### Loading a Policy Card

```typescript
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

```typescript
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

```typescript
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

```typescript
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](./schemas/policy-card-schema-v0.1.json) for the full JSON Schema.

### Example Policy Card (YAML)

```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](https://arxiv.org/html/2510.24383v1) - Mavračić (2025)
- [Protocol-Embedded Compliance](https://usepec.eu) - Jones (2026)
- [NIST AI RMF](https://www.nist.gov/itl/ai-risk-management-framework)
- [ISO/IEC 42001](https://www.iso.org/standard/42001)
- [EU AI Act](https://eur-lex.europa.eu/eli/reg/2024/1689)

## License

MIT