# Migration Guide: v0.9.13 → v0.9.14

## ⚠️ Breaking Changes (Zero Backward Compatibility)

PEAC v0.9.14 is a **zero backward compatibility** release. All legacy adapters and v0.9.12/v0.9.13 compatibility layers have been archived.

## Core Changes

### 1. Wire Format Changes

**JWS Header**

```diff
// v0.9.13
{
  "alg": "EdDSA",
  "typ": "peac.receipt/0.9",
  "kid": "key-1"
}

// v0.9.14
{
  "alg": "EdDSA",
  "typ": "peac.receipt/0.9",  // Standard media type
  "kid": "key-1"
}
```

**HTTP Headers**

```diff
// v0.9.13
PEAC-Receipt: eyJ...
peac-version: 0.9.13

// v0.9.14
PEAC-Receipt: eyJ...
// No peac-version header
```

### 2. Receipt Fields

**Timing Fields**

```diff
// v0.9.13
{
  "iat": 1704067200  // Unix timestamp
}

// v0.9.14
{
  "iat": 1704067200  // Unix timestamp
}
```

**Payment Fields**

```diff
// v0.9.13
{
  "payment": {
    "rail": "stripe",  // Payment provider
    "amount": 1.00,
    "currency": "USD"
  }
}

// v0.9.14
{
  "payment": {
    "scheme": "stripe",  // Renamed from 'rail'
    "amount": 1.00,
    "currency": "USD"
  }
}
```

## Code Migration

### Import Changes

```diff
// v0.9.13
- import { signReceipt } from '@peac/core/dist/sign.js';
+ import { signReceipt } from '@peac/core';

// All legacy adapter packages are archived
- import { LangChainAdapter } from '@peac/adapters-langchain';
```

### Function Signatures

**No breaking changes** to core function signatures:

- `signReceipt(receipt, options)` - unchanged
- `verifyReceipt(jws, keys)` - unchanged
- `enforce(resource, context, options)` - unchanged

### Constants

```typescript
// v0.9.14 exports
import { WIRE, PEAC_CANONICAL_ORIGIN } from '@peac/core';

console.log(WIRE); // '0.9'
console.log(PEAC_CANONICAL_ORIGIN); // 'https://peacprotocol.org'
```

## Domain Migration

All URLs have migrated from `peac.dev` to `peacprotocol.org`:

```diff
// Error types
- https://peacprotocol.org/problems/invalid-signature
+ https://peacprotocol.org/problems/invalid-signature

// Discovery endpoints
- https://example.com/.well-known/ai-policy
+ https://example.com/.well-known/peac.txt
```

## Validation Changes

### Enhanced Validation

- **Subject/hash integrity**: Automatic validation when `subject.uri` provided
- **Payment requirements**: Strict validation for `http-402` enforcement
- **Time bounds**: `iat` must not be future/too old (±5min, 1yr max)

### Error Handling

```typescript
// v0.9.14 enhanced errors
try {
  await verifyReceipt(jws, keys);
} catch (error) {
  // More specific error messages:
  // "Receipt issued in future: iat=1704067500, now=1704067200"
  // "HTTP-402 enforcement requires payment.scheme, amount, and currency"
}
```

## Package Changes

### Archived Packages

- `@peac/adapters-langchain` → `archive/adapters-langchain`
- `@peac/adapters-firecrawl` → `archive/adapters-firecrawl`
- `@peac/adapters-camel` → `archive/adapters-camel`
- `@peac/crawler` → `archive/crawler`

### Active Packages

- `@peac/core` - Core signing/verification (v0.9.14)
- `@peac/api` - HTTP API with v0.9.13.1 verifier (updated)
- `@peac/disc` - Discovery client (updated)
- `@peac/receipts` - Receipt validation (aligned to v0.9.14)
- `@peac/sdk` - High-level SDK (updated)

## Performance

v0.9.14 maintains **P95 < 1ms** for core verification operations with enhanced validation.

## Summary

1. Update receipt fields: `iat` (Unix timestamp), `payment.scheme`
2. Expect JWS `typ: "peac.receipt/0.9"`
3. Remove legacy adapter dependencies
4. Update error handling for enhanced validation
5. Migrate URLs from `peac.dev` to `peacprotocol.org`

**Zero compatibility**: v0.9.13 and earlier receipts will **not validate** in v0.9.14.
