Kernel-First Design

PEAC Protocol follows a spec-first architecture. All normative constants, error codes, and registries originate from machine-readable JSON specifications in specs/kernel/. The TypeScript implementation is derived from these specs -- and future Go, Rust, and Python SDKs will be too.

Spec-first flow

Spec-First Flow

specs/kernel/*.json                    Normative JSON (source of truth)
       |
       |  code generation
       v
packages/kernel/src/*.ts               TypeScript constants and types (derived)
       |
       |  imports
       v
packages/{schema,crypto,protocol}      Core packages consume @peac/kernel
       |
       |  imports
       v
packages/{rails-*,mappings-*}          Adapters and mappings

Normative specifications

The specs/kernel/ directory contains the canonical definitions that all implementations must conform to.

File	Contents	Scope
errors.json	139 error codes across 12 categories	Error handling
constants.json	Wire format, algorithms, headers, limits	Protocol constants
registries.json	Payment rails, agent protocols, transport methods	Extension registries
error-categories.json	Auto-generated category index	Error categorization

Code generation

TypeScript constants and types are generated from the kernel specs. CI checks that the generated code matches the specs -- any drift is a build failure.

Generated Constants

// Generated from specs/kernel/errors.json
export const PEAC_ERRORS = {
  E_INVALID_SIGNATURE: {
    code: 'E_INVALID_SIGNATURE',
    http_status: 400,
    title: 'Invalid Signature',
    description: 'Receipt signature verification failed',
    retriable: false,
    category: 'verification',
  },
  E_INVALID_FORMAT: {
    code: 'E_INVALID_FORMAT',
    http_status: 400,
    title: 'Invalid Format',
    description: 'Receipt does not conform to JWS format',
    retriable: false,
    category: 'validation',
  },
  // ... 139 total error codes
} as const;

Language-agnostic by design

Because the source of truth is JSON, any language can generate its implementation from the same specs. The TypeScript SDK is the reference implementation, but the specs are the contract. This means a Go or Rust SDK built from the same specs/kernel/*.json files will have identical error codes, constants, and registry data.

Wire format

The wire format identifier peac-receipt/0.1 is defined in constants.json and appears in every receipt's JWS header. It is frozen until v1.0.

JWS Header

{
  "alg": "EdDSA",
  "typ": "peac-receipt/0.1",
  "kid": "peac-2026-02"
}

Conformance vectors

PEAC maintains over 200 conformance test vectors in specs/conformance/. These vectors serve as the acceptance criteria for any implementation -- if your code passes all vectors at a given level, it conforms to the protocol.

Vector categories cover the full protocol surface:

• Signature vectors -- known-good and known-bad Ed25519 signatures
• Claim vectors -- valid and invalid claim combinations
• Extension vectors -- extension schema validation
• Policy vectors -- policy evaluation scenarios
• Error vectors -- expected error codes for malformed inputs
• RFC 9421 vectors -- HTTP message signature proof capture
• Identity vectors -- agent identity attestation validation
• Bundle vectors -- evidence bundle creation and verification

---

Package Layering

7-layer dependency model with downward-only imports.

Wire Format

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