# libxml-rs
**Phase 1: Compatibility Skeleton** — *C ABI drop-in skeleton verified.*
Custodial native-Rust reimplementation of the **libxml2 + libxslt** ecosystem:
a forensic reconstruction of observable behavior, implemented in native Rust,
with C ABI compatibility for drop-in replacement.
This is **not** an XML crate. This is **not** an XSLT crate. This is **not** a wrapper.
This is a custodial forensic archive and native-Rust reimplementation of
the complete observable behavior of libxml2 and libxslt across their
historical lifetimes.
---
## Current Status: Phase 1 — Compatibility Skeleton (§85)
Phase 1 establishes the C ABI compatibility skeleton: the structural and
linker-level foundations necessary before any parser implementation begins.
Per §85:
> *Deliverable: Existing trivial C consumers compile and load the Rust artifacts.*
### What exists now
- **Single Cargo package**: One crate with deeply organized module tree matching upstream subsystem boundaries
- **C headers (45 libxml + 19 libxslt)**: Compatible C headers in `include/` — compile with both gcc and g++, strict warning flags, zero warnings
- **ABI exports**: 211 `libxml2` + 26 `libxslt` `#[no_mangle]` extern "C" symbols exported from `liblibxml_rs.so`
- **SONAME symlinks**: `libxml2.so.2.12.0`, `libxslt.so.1.1.39` with full symlink chain — `-lxml2` and `-lxslt` link correctly
- **pkg-config**: `libxml-2.0.pc` and `libxslt.pc` generated by `build.rs`
- **Config scripts**: `xml2-config` and `xslt-config` shell scripts
- **Tree implementation**: Complete `xmlNode`, `xmlDoc`, `xmlAttr`, `xmlNs`, `xmlDtd` with create/free/copy/link/unlink/replace — 16 tree tests
- **Dictionary**: FNV-1a hashed dictionary with create/lookup/copy/free — 8 tests
- **Hash table**: Full hash table implementation — 10 tests
- **List**: Doubly-linked list with push/pop/insert/delete/search/sort — 9 tests
- **Memory hooks**: Allocator replacement infrastructure with `parking_lot::RwLock`
- **Error subsystem**: Error stack with domains/codes/levels, structured error handling
- **Globals/Threads**: Library initialization, cleanup, thread-local state
- **Versioning**: `xmlParserVersion`, `xmlLibVersion`, `LIBXML_TEST_VERSION` macros
- **Docker oracle**: Reproducible libxml2 2.12.0 / libxslt 1.1.39 build (Debian bookworm)
- **ABI courts**: 6/6 passing — struct layout, symbol enumeration, enum value verification — against both candidate headers and oracle
- **62 passing tests**: `cargo test --lib` — 0 failures, 0 errors
### What does NOT exist yet
- No XML parser (Phase 2)
- No SAX callback dispatching (Phase 2)
- No XPath engine (Phase 5)
- No XSLT engine (Phase 8)
- No CLI tools (Phase 10)
- No validation (Phase 6)
- 211 exported symbols are stubs returning NULL/0 — function bodies implemented progressively in Phases 2–10
### Build
```sh
cargo build # Build library + CLI stubs
cargo build --lib # Build only the library
cargo test --lib # Run library tests (62 passing)
# Test C consumer compilation against our headers:
gcc -I include courts/suites/sanity/ABI-STRUCT-NODE-0001-abicheck.c -o /tmp/abicheck
clang -I include courts/suites/sanity/ABI-ENUM-0001-enumcheck.c -o /tmp/enumcheck
# Build and run oracle container:
docker build -f docker/Dockerfile.oracle -t libxml-rs/oracle:2.12.0 docker/
```
### Oracle verification
The oracle Docker container builds libxml2 2.12.0 and libxslt 1.1.39 from source.
All ABI courts pass against the oracle. The candidate (`libxml-rs`) does not link
against system libxml2/libxslt — verified by oracle contamination court.
---
## Project Structure
```
libxml-rs/
├── Cargo.toml # Single Cargo package (no workspace)
├── src/
│ ├── lib.rs # Library entry point
│ ├── abi/ # C ABI compatibility layer (§4, §14)
│ ├── xml/ # libxml2 implementation (§1, §3, §31)
│ ├── xslt/ # libxslt implementation (§31–§34)
│ ├── exslt/ # EXSLT modules (§35)
│ ├── compatibility/ # Historical profiles, quirks, platform (§68, §69)
│ └── bin/ # CLI tools: xmllint, xmlcatalog, xsltproc (§36)
├── include/ # Compatible C headers (§15)
├── atlas/ # Forensic archive (§7–§12)
│ ├── releases/ # Release manifests per version
│ ├── api/ # Public API inventories
│ ├── abi/ # ABI snapshots
│ ├── symbols/ # Symbol table comparisons
│ ├── config/ # Build configuration profiles
│ ├── standards/ # Standards mapping
│ ├── HISTORY.md # Complete release history
│ ├── LORE.md # Undocumented behavior archive
│ ├── QUIRKS.md # Confirmed compatibility quirks
│ ├── PARITY_MATRIX.md # Current parity status
│ ├── RESIDUAL_LEDGER.md # Unexplained differences
│ └── SECURITY_HISTORY.md # Vulnerability custody
├── oracle/ # Reproducible upstream build environment (§39)
├── courts/ # Differential testing framework (§40–§50)
│ ├── schema.json # Casefile schema
│ ├── suites/ # Court case suites
│ ├── receipts/ # Execution receipts
│ └── tools/ # Court runner
├── tools/ # Archaeology and analysis tooling
│ ├── archaeology/ # manifest.py, apiatlas.py, symbols.py, delta.py, profileconfig.py
│ └── courts/ # Court runner
├── docker/ # Reproducible Docker oracle images
├── docs/ # Technical documentation
└── archaeology/ # Upstream git clones (immutable, offline)
```
---
## Build
```sh
cargo build # Build the library
cargo build --lib # Build only the library (not CLI stubs)
cargo test # Run tests (Phase 0: limited)
```
---
## License
Licensed under either of:
- MIT license ([LICENSE-MIT](LICENSE-MIT))
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
at your option.
---
## Project Status
| API completeness | 🟡 15% (211 symbols exported, all stubs) |
| ABI compatibility | 🟢 6/6 courts passing (struct, symbol, enum) |
| Tree/ownership | 🟢 16 tree tests passing |
| Dictionary/Hash/List | 🟢 27 tests passing |
| Memory/Error/Globals | 🟢 19 tests passing |
| C headers | 🟢 45+19 headers, gcc & clang, zero warnings |
| Parser parity | 🔴 Not started (Phase 2) |
| XPath parity | 🔴 Not started (Phase 5) |
| XSLT parity | 🔴 Not started (Phase 8) |
| CLI parity | 🔴 Not started (Phase 10) |
| Historical atlas | 🟡 30% |
| Oracle infrastructure | 🟢 Docker oracle built and verified |
| Court coverage | 🟢 6 ABI courts passing |
| Downstream testing | 🔴 Not started |
See [`atlas/PARITY_MATRIX.md`](atlas/PARITY_MATRIX.md) for the detailed,
evidence-bounded parity matrix.