Package Layering

PEAC Protocol enforces a strict layering model across its packages. Dependencies flow downward only -- a package may only import from packages in layers below it. This rule is enforced by dep-cruiser in CI.

Layer diagram

Layer Architecture

Layer 6  @peac/sdk-js                                         Consumer SDK
         ---------------------------------------------------------------
Layer 5  @peac/server  |  @peac/cli  |  @peac/mcp-server     Applications
         ---------------------------------------------------------------
Layer 4  @peac/rails-*  |  @peac/mappings-*  |  @peac/adapter-*
         @peac/capture-core  |  @peac/capture-node            Adapters
         ---------------------------------------------------------------
Layer 3.5  @peac/middleware-core  |  @peac/middleware-express  Middleware
         ---------------------------------------------------------------
Layer 3  @peac/protocol  |  @peac/control                    High-level APIs
         ---------------------------------------------------------------
Layer 2  @peac/crypto                                         Signing
         ---------------------------------------------------------------
Layer 1  @peac/schema                                         Validation
         ---------------------------------------------------------------
Layer 0  @peac/kernel                                         Foundation

Layer descriptions

Layer 0 -- Kernel

Package: @peac/kernel Dependencies: None (zero external dependencies)

• TypeScript type definitions for the entire protocol
• Constants -- error codes, status values, wire format identifiers
• Registry data -- attestation types, extension keys
• Generated from normative JSON specifications in specs/kernel/

Layer 1 -- Schema

Package: @peac/schema Dependencies: @peac/kernel, zod

• Zod schemas for receipts, policies, and extensions
• Runtime validation functions
• Schema-derived TypeScript types

Layer 2 -- Crypto

Package: @peac/crypto Dependencies: @peac/schema, @noble/ed25519 v3

• Ed25519 signing (signAsync) and verification (verifyAsync)
• Key generation (generateSigningKey, getPublicKeyAsync)
• JWKS management and key resolution
• Pure JavaScript -- no native modules required

Layer 3 -- Protocol and Control

Package: @peac/protocol Dependencies: @peac/crypto, @peac/schema

• issueReceipt() -- high-level receipt issuance
• verifyReceipt() -- high-level receipt verification with 12 checks
• createEvidenceBundle() -- .peac.tar.gz bundle creation
• Receipt decoding, inspection, and claim extraction

Package: @peac/control Dependencies: @peac/schema

• Policy parsing and evaluation
• Purpose-based access control
• Access control rule engine

Layer 3.5 -- Middleware

Package: @peac/middleware-core Framework-agnostic middleware logic for receipt issuance and verification.

Package: @peac/middleware-express Express.js adapter that wraps middleware-core.

Layer 4 -- Adapters

Rail adapters, protocol mappings, and platform adapters. All vendor-specific code lives here.

Package	Description
@peac/rails-x402	Coinbase x402 payment evidence
@peac/rails-stripe	Stripe PaymentIntent and CryptoPaymentIntent
@peac/rails-razorpay	Razorpay UPI, cards, netbanking
@peac/rails-card	Visa, Mastercard, Amex card networks
@peac/mappings-mcp	MCP tool call metadata
@peac/mappings-acp	ACP agent-to-agent interactions
@peac/adapter-openclaw	OpenClaw activate + keygen
@peac/capture-core	Core capture logic (spool, dedupe)
@peac/capture-node	Node.js durable stores (FileSpoolStore, FileDedupeIndex)

Layer 5 -- Applications

Full applications built on the protocol stack:

Package	Description
@peac/server	HTTP server for receipt issuance and verification
@peac/cli	Command-line tools (peac-keygen, peac verify)
@peac/mcp-server	MCP server with 5 tools (verify, inspect, decode, issue, bundle)

Layer 6 -- Consumer SDK

Package: @peac/sdk-js

High-level consumer SDK that re-exports the most common functions from the protocol stack. Use this when you want a single import for common operations.

Import rules

Downward-only rule

A package may only import from packages in lower layers. Importing from a higher layer is a build error caught by dep-cruiser in CI.

For example, @peac/crypto (Layer 2) can import from @peac/schema (Layer 1) and @peac/kernel (Layer 0), but it cannot import from @peac/protocol (Layer 3).

• No circular dependencies -- enforced by dep-cruiser in CI
• Vendor neutrality -- core packages (Layers 0--3) contain no vendor-specific code
• Vendor code in Layer 4 -- all vendor-specific logic lives in adapters, mappings, and rails packages

---

Kernel-First Design

How normative JSON specs drive the implementation.

Wire Format

The peac-receipt/0.1 wire format -- frozen until v1.0.