tawasuyu/brahman

1// Brahman — Protocolo central (handshake & ciclo de vida)
2//
3// Esta interfaz es el contrato de los módulos "conscientes". Los módulos
4// agnósticos sólo presentan un manifest TOML y son supervisados por convención
5// mínima; los módulos con WIT pueden negociar capacidades, reportar estado y
6// recibir señales del Admin.
7//
8// Versionado: este archivo declara `0.1.0`. Cambios major requieren un nuevo
9// archivo (`protocol-v2.wit`); cambios minor son aditivos.
10
11package brahman:protocol@0.1.0;
12
13interface types {
14    /// Identificador opaco emitido por el Admin tras un handshake exitoso.
15    type session-id = string;
16
17    /// Timestamp UNIX en segundos.
18    type unix-ts = u64;
19
20    record module-info {
21        /// Nombre canónico (debe coincidir con el manifest).
22        name: string,
23        /// SemVer del módulo.
24        version: string,
25        /// Versión del protocolo Brahman implementada.
26        protocol-version: string,
27        /// Capacidades que ofrece (ids libres, idealmente URIs).
28        provides: list<string>,
29        /// Capacidades que requiere para arrancar.
30        requires: list<string>,
31    }
32
33    record admin-info {
34        /// Versión del Admin que aceptó el handshake.
35        version: string,
36        /// Versión del protocolo soportada por el Admin.
37        protocol-version: string,
38        /// Identificador de sesión asignado.
39        session: session-id,
40        /// Si el Init está vinculado al Admin actualmente.
41        init-attached: bool,
42    }
43
44    /// Errores comunes durante negociación o ciclo de vida.
45    variant protocol-error {
46        protocol-mismatch(string),
47        unauthorized(string),
48        capability-unmet(string),
49        rejected(string),
50        internal(string),
51    }
52}
53
54interface handshake {
55    use types.{module-info, admin-info, protocol-error, session-id};
56
57    /// Negociación inicial de un módulo con el Admin.
58    /// El Admin valida protocolo, capacidades requeridas y permisos.
59    hello: func(info: module-info) -> result<admin-info, protocol-error>;
60
61    /// Cierre limpio (drena conexiones, libera recursos).
62    farewell: func(session: session-id) -> result<_, protocol-error>;
63
64    /// Latido para mantener viva la sesión. Devuelve el reloj del Admin.
65    ping: func(session: session-id) -> result<u64, protocol-error>;
66}
67
68interface lifecycle {
69    use types.{session-id, unix-ts, protocol-error};
70
71    enum module-state {
72        initializing,
73        ready,
74        running,
75        suspended,
76        degraded,
77        terminating,
78    }
79
80    record state-report {
81        state: module-state,
82        timestamp: unix-ts,
83        detail: option<string>,
84    }
85
86    /// Reporta cambio de estado al Admin (telemetría → Init si está adjunto).
87    report-state: func(session: session-id, report: state-report) -> result<_, protocol-error>;
88
89    /// Señal del Admin solicitando suspensión cooperativa.
90    on-suspend: func(session: session-id) -> result<_, protocol-error>;
91
92    /// Señal del Admin solicitando reanudación.
93    on-resume: func(session: session-id) -> result<_, protocol-error>;
94}
95
96/// Mundo que un módulo Brahman implementa.
97world module {
98    import handshake;
99    import lifecycle;
100
101    /// Punto de entrada que el Admin invoca tras instanciar el componente.
102    export run: func() -> result<_, string>;
103}
104
105/// Mundo que el Admin implementa (host-side) para los módulos.
106world admin-host {
107    export handshake;
108    export lifecycle;
109}