brahman/crates/modules/fana/SDD.md

modules/fana/ — Writer DAG editor (absorbe pluma)

Propósito. Editor de escritura multidimensional: el documento es un DAG de átomos narrativos con ramas (timelines), tracking de coherencia, e indexación semántica. Absorbe el linaje markdown de pluma. Prioridad alta entre las apps.

Estado

• Implementado: fana-core (átomo + coherencia), fana-graph (DAG + propagate_mutation + orden topológico), fana-render-plan (layout agnóstico: bloques en columnas por rama, conectores, osciloscopio), fana-editor-gpui (backend GPUI), fana-semantic (cliente verbo), fana-store (persistencia sled), fana-md + fana-md-reader-web (linaje markdown de pluma). App apps/fana funcional (relato de ejemplo + onda de choque lógica).
• Pendiente: fana-llm (cliente HTTP a LLMs remotos — requiere cliente HTTP en el workspace), fana-editor-web (cdylib WASM).

Crates (objetivo)

crate	tipo	rol
fana-core	lib	NarrativeAtom + NarrativeGraph + CoherenceState
fana-md	lib	Parser markdown (ex pluma-md)
fana-graph	lib	DAG ops + propagate_mutation topológico
fana-semantic	lib	Cliente verbo + scoring de intensidad adjetiva
fana-store	lib	Persistencia sled/RocksDB + bincode/rkyv zero-copy
fana-llm	lib	Cliente HTTP a LLMs remotos (evaluación + merge)
fana-render-plan	lib	DrawCommands agnósticos (editor + sidepane + ghost)
fana-editor-gpui	lib	WorkspaceEditor View + OscilloscopeSidepane + Ghost
fana-md-reader-web	lib	Lector markdown DOM (ex pluma-reader-web)
fana-editor-web	lib	(futuro) editor WASM

Modelo de datos

enum CoherenceState { Valid, InConflict { origin, reason }, PendingEvaluation }

struct NarrativeAtom {
    id: Uuid,
    content_hash: [u8; 32],            // SHA-256 estricto
    content: Arc<String>,              // texto compartido (zero-alloc al ramificar)
    semantic_vectors: HashMap<String, f32>,  // concepto → intensidad
    dependencies: Vec<Uuid>,           // nodos prerrequisito
    branch_id: String,
    coherence: CoherenceState,
}

struct NarrativeGraph {
    nodes: HashMap<Uuid, NarrativeAtom>,
    adjacency_list: HashMap<Uuid, Vec<Uuid>>,  // padre → hijos dependientes
}

Dependencias

• fana-semantic ← verbo (embeddings, instancia modelo ligero ~384d).
• fana-md puro (sin deps de host).
• fana-md-reader-web + fana-editor-web ← wasm-bindgen, web-sys.
• fana-editor-gpui ← gpui, nahual.
• gioser-web sigue consumiendo fana-md-reader-web.

Invariantes

• Toda mutación de texto valida contra el hash binario del contenido.
• Branches comparten texto vía Arc<String> — clonar una rama es O(1).
• propagate_mutation marca PendingEvaluation en cascada topológica cuando un átomo origen cambia (shock-wave lógica).
• Separabilidad UI estricta: fana-core/md/graph/semantic/store/llm/ render-plan agnósticos; fana-editor-{gpui,web} intercambiables.

Apps

• apps/fana — binario GPUI (prioridad alta).
• apps/fana-web — (futuro) cdylib WASM.