1# protocol/ — Contratos canónicos + routing
2
3**Propósito.** Núcleo de intercomunicación del fractal: tipos canónicos
4(`Card`, capabilities, soma), handshake módulo↔Init, broker que empareja
5flows por tipo, y wire types de red. No corre lógica de dominio.
6
7## Crates
8
9| crate                  | tipo | rol                                                      |
10| ---------------------- | ---- | -------------------------------------------------------- |
11| `brahman-card`         | lib  | Struct `Card` (19 campos, ver abajo)                     |
12| `brahman-card-wit`     | lib  | Extracción WIT desde componentes WASM                    |
13| `brahman-cards`        | lib  | Templates Nickel + helpers consumer/producer/broker      |
14| `brahman-handshake`    | lib  | Init↔módulo: Hello, Ping, ListSessions, ListMatches      |
15| `brahman-broker`       | lib  | Service locator: flow.input ↔ flow.output por tipo       |
16| `brahman-admin`        | lib  | Socket admin separado: snapshots de sesiones+matches     |
17| `brahman-sidecar`      | lib  | `spawn(card)` para que apps se presenten al Init         |
18| `brahman-net`          | lib  | Malla libp2p opcional (TCP+noise+yamux+kad)              |
19| `arje-card`            | lib  | Alias legacy — re-export de `brahman-card`               |
20
21## Struct `Card` (anatomía completa)
22
23```rust
24pub struct Card {
25    schema_version: u16,         // versión del esquema fractal
26    id: Ulid,                     // identidad opaca única
27    lineage: Option<Ulid>,        // ancestro genealógico
28    label: String,                // nombre humano-legible
29    provides: BTreeSet<Capability>,
30    requires: BTreeSet<Capability>,
31    permissions: Permissions,     // sandbox declarativo
32    soma: SomaSpec,               // runtime Linux (ns + cgroup + rlimits)
33    payload: Payload,             // WASM | ELF | Virtual | Legacy
34    supervision: Supervision,     // restart policy
35    lifecycle: Lifecycle,         // ortogonal a supervision
36    priority: Priority,
37    flow: Flows,                  // contratos de datos in/out
38    service_socket: Option<PathBuf>,  // data plane separado
39    references: Vec<CardReference>,    // grafo de relaciones
40    kind: CardKind,               // Ente | Monada | Index | ...
41    data: Option<DataFacet>,      // None para entes runtime
42    genesis: Vec<Card>,           // hijas a encarnar inmediatamente
43    priority_contexts: BTreeMap<String, ContextBias>,
44}
45```
46
47## Dependencias
48
49- Intra: handshake → card + broker; sidecar → card; net → handshake.
50- Cross: consumido por todos los `modules/*` y `apps/*`.
51- No depende de `init/` ni de `runtime/` (es la base).
52
53## Invariantes
54
55- Serialización: `postcard` length-prefixed sobre Unix SOCK_STREAM, JSON
56  sobre HTTP (gateway). Schemas reproducibles vía Nickel.
57- Identidad: `peer_id` libp2p + firma Ed25519 anclada al peer.
58- Sesiones: el handshake mantiene una sesión por módulo encarnado.
59
60## Estado
61
62Base estable (6,260 LOC con tests). 19 TODOs concentrados en handshake
63(trust remoto fase 3) y broker. Ver `docs/changelog/protocol.md`.