---
title: Stage 1 — Full Library Dependency Map
type: reference
tags: :passepartout:architecture:social-protocol:dependencies:
created: 2026-05-28
---

← Stage 1 — Social Protocol | Repo Organization

# Stage 1 — Full Library Dependency Map

Stage 1 (social protocol) depends on three tiers of libraries: existing CL, spec-based CL, and bridged sidecars.

## Existing CL Libraries (ready now)

These are mature, production-tested Common Lisp libraries that require no development work:

| Library | Role in Stage 1 |
|---------|----------------|
| Ironclad | All crypto primitives — Ed25519, SHA-256, AES, ChaCha20-Poly1305, HMAC, DH |
| hunchentoot | HTTP server — PDS API endpoints |
| drakma | HTTP client — inter-PDS communication, sidecar calls |
| cl+ssl | TLS everywhere — server and client |
| websocket-driver | Real-time Relay connections |
| jonathan | JSON parsing/serialization — DID docs, JWE headers, API payloads |
| cl-sqlite | Message storage, user data, DAG index |
| local-time | Timestamps for Notes, DAG entries |
| bordeaux-threads | Concurrency — connection handling, parallel verification |
| alexandria | General utilities |
| log4cl | Structured logging |
| fiveam | Testing framework |
| cffi | Foreign function interface to C/Rust sidecars |
| usocket | Socket abstraction |

## New CL Libraries (need development)

| Library | What it implements | Key correctness challenge |
|---------|-------------------|-------------------------|
| cl-dag / cl-cid | IPLD Merkle DAG — CID encoding, multihash, DAG tree operations | Spec compliance (IPLD test vectors) |
| cl-did | W3C DID — Ed25519 key wrapping, DID document construction, did:key resolution | Spec compliance (W3C test suite) |
| cl-jose | JWE/JWS — envelope serialization, key wrapping modes, algorithm selection | Surface area (combinatorial spec, not deep math) |
| cl-double-ratchet | Signal Double Ratchet — DH ratchet, symmetric ratchet, associated data, header encryption | **Highest risk** — one byte wrong in associated data breaks every message |
| cl-bip | BIP-32/39/44 — mnemonic encoding, HD key derivation, hardened vs non-hardened paths | Silent failure (wrong derivation produces wrong keys, no error) |
| cl-didcomm | DIDComm v2 — message packing, forwarding, routing, attachment handling | Composes the above libraries; protocol logic correctness |

## Bridged Sidecars (initial release)

Replace native CL development risk with battle-tested implementations via CFFI or sidecar processes:

| Component | Bridge method | Source | Replaced by |
|-----------|--------------|--------|-------------|
| Double Ratchet | CFFI → libsignal | Signal's C library, MIT license | cl-double-ratchet |
| DID operations | CFFI → didkit | Spruce, Rust + C bindings, Apache 2.0 | cl-did |
| DIDComm | CFFI → didcomm-rust | DIDComm WG, C bindings, Apache 2.0 | cl-didcomm |
| DAG/CID storage | HTTP API → ipfs daemon | IPFS Go daemon, MIT license | cl-dag |
| BIP derivation | CFFI or sidecar | libbitcoin or bip-utils | cl-bip |
| JOSE envelopes | CFFI → libjose or OpenSSL CMS | libjose/OpenSSL | cl-jose |

## Infrastructure Code (Passepartout-specific)

These are not libraries but Passepartout systems that must be built:

| Component | Role |
|-----------|------|
| PDS server | HTTP/WS API, message routing, storage orchestration, gate integration |
| Relay server | Pub/sub message routing between PDSs, connection management |
| Client API layer | Protocol endpoints the mobile apps call |

## Risk Distribution

- **Low risk:** cl-dag, cl-did, cl-bip — published standards with test vectors, or bridged via sidecar
- **Medium risk:** cl-jose — large spec surface area but well-documented
- **High risk:** cl-double-ratchet — protocol logic depth, must get state transitions exactly right

The sidecar strategy collapses the high-risk items to near-zero implementation risk for the initial release.

→ Repo Organization
→ Stage 2 — Verification Subsystem

:PROPERTIES:
:CREATED:  [2026-05-11 Mon]
:ID:       3ec5bd52-f115-455e-83be-63db9a4ad3a7
:END: