# Context
## Fuente de verdad
La fuente de verdad es [plan_libreria_xml_generica_rust.md](../plan_libreria_xml_generica_rust.md).
El documento [plan_libreria_xml_facturacion_rust.md](../plan_libreria_xml_facturacion_rust.md) queda solo como referencia historica y no define el alcance actual.
## Decision de alcance
El proyecto construye un motor XML generico. El corte actual llega hasta el motor XML y no avanza a dominios.
Decision local de empaquetado:
[] Una sola crate Rust importable llamada `xdoc`.
[] Package publico de crates.io llamado `xdoc-rs`.
[] Separacion por carpetas internas.
[] Sin workspace multi-crate para el motor XML.
[] Excepcion tecnica: `xdoc-macros` queda permitido si `xml!` requiere una proc-macro.
[] Excepcion de herramienta: `xdoc-cli` queda permitido como crate/binario separado para publicar o instalar el comando `xdoc`.
[] Los nombres `xdoc-core`, `xdoc-writer`, etc. del plan se interpretan como responsabilidades internas, no como packages separados.
Regla central:
```text
El dominio depende del motor XML.
El motor XML nunca depende del dominio.
```
## Direccion de API
La experiencia objetivo debe parecerse a Leptos, pero para XML.
Esto significa:
[] Componentes Rust que retornan XML, fragmentos o valores convertibles a XML.
[] Props tipadas para construir elementos y componentes.
[] Children como entrada explicita de componentes.
[] Composicion declarativa con funciones normales de Rust.
[] Macro `xml!` o equivalente con sintaxis cercana a tags.
[] Soporte ergonomico para `{expr}`, condicionales y colecciones.
[] Salida XML deterministica, no actualizacion de DOM.
[] Sin runtime reactivo obligatorio en el MVP.
[] El modelo de componentes sigue siendo parte del motor generico, no un dominio.
## Componentes dentro del alcance
[] `src/core/`: modelo XML base.
[] `src/writer/`: serializacion compacta, pretty y deterministica.
[] `src/builder/`: construccion ergonomica sobre el core.
[] `src/component/`: modelo de componentes estilo Leptos para XML.
[] `src/parser/`: lectura segura hacia el modelo del core.
[] `src/macros/`: macro `xml!` como azucar sobre el builder.
[] `src/query/`: subset tipo XPath.
[] `src/transform/`: templates y transformaciones XML a XML.
[] `src/schema/`: contratos XML propios y validacion estructurada.
[] `src/signature/`: canonicalizacion, digest y XMLDSig basico.
[] `src/security/`: limites y politicas seguras.
[] `src/testing/`: fixtures, golden tests y helpers internos de prueba.
[] `crates/xdoc-cli/`: herramienta de inspeccion y desarrollo.
## Mapeo desde el plan
[] `xdoc-core` -> `src/core/`.
[] `xdoc-writer` -> `src/writer/`.
[] `xdoc-builder` -> `src/builder/`.
[] Modelo de componentes estilo Leptos -> `src/component/`.
[] `xdoc-parser` -> `src/parser/`.
[] `xdoc-macro` -> `src/macros/` para macro declarativa o `xdoc-macros` si se implementa como proc-macro.
[] `xdoc-query` -> `src/query/`.
[] `xdoc-transform` -> `src/transform/`.
[] `xdoc-schema` -> `src/schema/`.
[] `xdoc-signature` -> `src/signature/`.
[] `xdoc-security` -> `src/security/`.
[] `xdoc-testing` -> `src/testing/` y `tests/support/`.
[] `xdoc-cli` -> `crates/xdoc-cli/`.
## Componentes fuera del alcance
[] `src/domains/ubl`.
[] `src/domains/dian`.
[] `src/domains/soap`.
[] `src/domains/hl7`.
[] `src/domains/cda`.
[] `src/domains/saml`.
## Principios tecnicos
[] Namespace-first: los nombres se modelan con `QName`, no con `String` plano.
[] Separar estructura, serializacion, parsing, canonicalizacion y firma.
[] Seguridad por defecto en parser, query y transform.
[] Tree API primero; streaming queda como extension posterior.
[] Builder solido antes que macro.
[] Serializacion deterministica para tests, validacion y firma.
[] Errores estructurados con contexto y path cuando aplique.
[] No introducir dependencias hacia dominios desde modulos del motor.
[] Mantener dependencias internas en direccion descendente: `core` abajo, features superiores arriba.
## Resultado esperado del motor
El motor debe permitir, sin dominios, este flujo:
[] Construir XML con builder o macro.
[] Serializar XML de forma compacta o pretty.
[] Parsear XML existente con configuracion segura.
[] Consultar nodos, textos y atributos.
[] Transformar un XML en otro XML.
[] Validar estructura con contratos propios.
[] Canonicalizar y firmar XML simple.