SLeeLa

SLeeLa Decompiler

# SLeeLa Decompiler Max Rupplin - MEARVK LLC - 2026 The /lib/decompiler package is the SLeeLa-sourced and SLeeLa-driven decompiler design and implementation layer. It converts executable artifacts, object files, byte streams, and other supported binary inputs into evidence-preserving SLeeLa-oriented intermediate representations and VM-ready reconstruction artifacts. ## Authority The authoritative model is: input artifact -> acquisition -> format/OS evidence -> decoding -> CFG -> SLIR -> semantic analysis -> reconstruction -> SLeeLa/target output -> VM validation The decompiler does not pretend that every binary can be perfectly reconstructed. Evidence, inference, reconstruction, and unresolved/fractional input are represented separately. ## Selection model A decompilation request can declare source language family (C, C++, SLeeLa, or a loaded language module), source language version, expected input format and architecture, desired output, treatment of fractional/partial input, operating-system/ABI discernment policy, analysis depth, and additional language/format modules. ## Fractional input Fractional input is never silently discarded. The request chooses PRESERVE, PARTIAL, REPORT_ONLY, or STRICT. ## OS discernment OS identification is evidence-weighted, not assumed from a single signature. Format headers, ABI markers, imports/exports, relocation data, calling conventions, section names, runtime metadata, and executable evidence may contribute. Conflicting evidence remains visible in the report. ## VM readiness The resulting SLeeLa model is validated by the same VM completeness/capability boundaries used by the compiler. Native C/C++ code provides implementation services; .sleela files define the source-level decompiler contract. ## Build make -C lib/decompiler or make decompiler **SLeeLa — MEARVK LLC — 2026** ## Usage This package has two cooperating halves, and it helps to keep them distinct: - **The SLeeLa contract (`lib/decompiler/*.sleela`)** defines *what* a decompilation request is — its input, selection options, fractional-input policy, OS/ABI policy, pipeline stages, and output target. The `.sleela` classes are the source-of-truth contract; their method bodies are intentionally declarative. - **The native subsystem (`decompiler/`, built as `sleela-decompiler`)** is the executing implementation — it actually reads a binary, decodes it, builds a CFG, lifts SLIR, and writes reconstructed source. When you want to *run* a decompilation and *save output*, you use this. The sections below cover accepted inputs, the request/selection surface, worked examples, and how to direct output to a file or directory. ### Input types and mediums Inputs are treated as untrusted evidence and are never executed. The catalogs in `LANGUAGE.FORMAT.REFERENCE.md` and `EXECUTABLE.LIBRARY.SOURCE.REFERENCE.md` are authoritative; the commonly supported mediums are: | Medium | Examples | Evidence yielded | |---|---|---| | Native executable | ELF `ET_EXEC`/PIE, PE `.exe`, Mach-O | format, architecture, OS/ABI, entry point, sections, symbols | | Shared/dynamic library | ELF `.so`/`.so.*`, PE `.dll`, Mach-O `.dylib` | SONAME/exports, imports/needed libraries, relocations | | Static library / object | AR `.a`, ELF `.o` | member enumeration, per-member format, symbols | | Kernel module | ELF `.ko` (incl. compressed, when safely identifiable) | module name, vermagic, license/author, dependencies | | Managed / bytecode | JVM class/JAR, .NET assembly, BEAM, Lua bytecode | runtime metadata, managed symbol/debug attributes | | Portable / IR | WebAssembly module, LLVM bitcode | producer metadata, name/debug/custom sections | | Raw / firmware | raw images, blobs, dumps | byte-level evidence with SHA-256 provenance | Native disassembly today covers x86, x86-64, AArch64 (ARM64), and 32-bit ARM (A32 + Thumb); other mediums are parsed for format/symbol/metadata evidence. A medium is *detected*, *parsed*, and/or *disassembled* — see `decompiler/README.md` for the per-format coverage matrix. ### Composing a request (the contract surface) A request declares how the input should be interpreted and how output should be produced. The relevant contract classes and their key fields: - **`SleelaDecompilerSourceLanguage`** — `name`, `family`, `version`, `abi`, `compiler`, `exactVersionRequired`. Selects the expected source-language family and version hypothesis. - **`SleelaDecompilerModule` / `SleelaDecompilerModules`** — `name`, `languageFamily`, `format`, `architecture`, `operatingSystem`, `trusted`. Loads additional language/format modules; selection stays evidence-driven and trust-gated. - **`SleelaDecompilerFractionalInput`** — `policy`, `allowGaps`, `preserveEvidence`, `emitPlaceholders`. Never silently discards partial input; choose one policy (below). - **`SleelaDecompilerOSDetector`** — weighted evidence over headers, ABI, imports, relocations, runtime metadata, calling conventions, sections; `conflictingEvidence` stays visible. - **`SleelaDecompilerOutput`** (the output target) — `format`, `language`, `version`, `path`, `profile`, `vmReady`, `preserveEvidence`, `includeReport`. Covered under "Directing output" below. **Fractional-input policies** (`SleelaDecompilerFractionalInput`): | Policy | Meaning | |---|---| | `PRESERVE` | keep unreadable/undecoded ranges as evidence | | `PARTIAL` | reconstruct valid regions, insert explicit unresolved regions | | `REPORT_ONLY` | stop before reconstruction, retain analysis evidence | | `STRICT` | reject incomplete or contradictory input | The native request mirror (`lib/decompiler/include/sleela_decompiler.h`) carries the same shape for the C/C++ services: ```c sleela_decompiler_request req = { .source_language = "c++", .source_version = "", /* "" = let evidence decide */ .expected_input = "elf", .desired_output = "c++", .os_policy = "weighted", .fractional_policy = SLEELA_FRACTIONAL_PRESERVE, .analysis_depth = 2, .preserve_evidence = 1, }; if (!sleela_decompiler_validate_request(&req)) { /* reject */ } ``` ### Worked examples Contract-level examples live under `tutorials/examples/`: - `artifact-analysis.sleela` — acquire an artifact and walk it through module/output/OS-discernment selection. - `fractional-reconstruction.sleela` — apply a fractional-input policy to incomplete input. The lesson path in `tutorials/` (`01-artifact-to-slir`, `02-os-abi-and-format-discernment`, `03-fractional-input-and-source-reconstruction`) covers the body of the work end to end. To actually run a decompilation, use the native CLI (built from `decompiler/`): ```sh # Inspect: format, architecture, sections, symbols, imports/exports, metadata sleela-decompiler inspect ./libexample.so # Disassemble a window (ARM: add --thumb or --arm to force state) sleela-decompiler disassemble ./program 256 # Control-flow edges / recovered function candidates sleela-decompiler cfg ./program sleela-decompiler functions ./program # Reconstruct source (lifted SLIR statements + evidence) sleela-decompiler decompile ./program --output c++ ``` ### Directing output (save toward a directory; uploads) Output is chosen on the output target. In the contract (`SleelaDecompilerOutput`): - `format` / `language` / `version` — the reconstruction target (e.g. `c++`, `c`, `java`, `sleela`); - `path` — the destination to write toward (a file, or a file within a directory you control); - `includeReport` — also emit the evidence/analysis report; - `vmReady` — validate the lifted SLIR against the VM before finalizing; - `preserveEvidence` — retain observed-vs-inferred distinctions in the output. With the native CLI, `--output` selects the language and `--file` saves toward a path; `--header` emits the companion header. To save into a directory, point `--file` at a path inside it (create the directory first): ```sh mkdir -p out # Source and companion header into ./out sleela-decompiler decompile ./program --output c++ --file out/recovered.cpp sleela-decompiler decompile ./program --output c++ --header --file out/recovered.hpp # Other targets sleela-decompiler decompile ./program --output c --file out/recovered.c sleela-decompiler decompile ./program --output java --file out/Recovered.java sleela-decompiler decompile ./program --output sleela --file out/recovered.sleela ``` Default extensions when you let the emitter choose: `.c`, `.cpp`, `.java`, `.sleela` for source and `.h` / `.hpp` for C/C++ headers. Without `--file`, the reconstruction is written to standard output, so you can redirect or pipe it. ### Network and remote destinations (`--to`) A governed destination adapter delivers an already-produced reconstruction to a local or network target. It is **output only** — it transmits bytes the pipeline has already generated and never reads or executes an input artifact. On the contract side this is `SleelaDecompilerDestination`, bound to the output via `SleelaDecompilerOutput.destination`; on the native side it is `decompiler/src/destination.cpp`, driven by `--to `. Transports and URI forms: | Transport | URI form | |---|---| | Local file | `file:/abs/path` or a bare `/local/path` | | FTP (RFC 959 `STOR`, passive) | `ftp://[user:pass@]host[:port]/remote/path` | | HTTP POST | `http://host[:port]/path` or `http+post://...` | | HTTP PUT | `http+put://host[:port]/path` | | SFTP (governed `sftp` helper) | `sftp://[user@]host[:port]/remote/path` | Addressing is explicit and uniform across IP families: `host` may be a DNS name, an IPv4 literal, or an IPv6 literal written in brackets (`[2001:db8::1]`). Name resolution uses `getaddrinfo`, so A and AAAA records are handled transparently; set the IP preference (`ANY`/`IPV4`/`IPV6`) when a host offers both. A `port` of `0` selects the transport default (FTP 21, HTTP 80, SFTP/SSH 22). The IP actually connected to is reported back for audit. ```sh # HTTP POST / PUT (DNS host, explicit path and content type) sleela-decompiler decompile ./program --output c++ \ --to http://uploads.example.org/recovered.cpp --content-type text/x-c++src sleela-decompiler decompile ./program --output c \ --to "http+put://198.51.100.20:8080/artifacts/recovered.c" # FTP STOR with credentials and an explicit port sleela-decompiler decompile ./program --output java \ --to "ftp://deploy:secret@ftp.example.net:2121/incoming/Recovered.java" # IPv6 literal (brackets), and SFTP via a governed client on PATH sleela-decompiler decompile ./program --output c++ --to "http://[2001:db8::1]:8443/r.cpp" sleela-decompiler decompile ./program --output c++ --to "sftp://build@host.example/out/r.cpp" ``` `--to` takes precedence over `--file`, which takes precedence over standard output. **Security posture.** Network delivery is a governed capability and nothing is sent unless you supply `--to`. The adapter embeds no SSH stack: SFTP is delegated to a system `sftp` client (key/agent auth; host-key checking is left to your SSH configuration and is not weakened). Plain HTTP and FTP are unencrypted — send only output you are authorized to distribute, and prefer SFTP or an HTTPS-terminating endpoint for sensitive material. Credentials passed in a URI are visible to the local process environment; prefer key-based auth where possible. TLS termination for HTTPS is a follow-on adapter. ### Boundary note Because `.sleela` is the contract and the native subsystem is the implementation, do not expect a contract method such as `emit()` to write a file by itself — it declares the behavior that the native `sleela-decompiler decompile ... --file ...` path performs. Everything here stays static and read-only: no input artifact is loaded or executed merely to identify or reconstruct it. ## Language and format reference The package uses LANGUAGE.FORMAT.REFERENCE.md as the decompiler-side native reference for language names, producer programs, binary/object/executable formats, architecture and OS/ABI evidence, and safety considerations. The mapping is evidence, not proof, and does not authorize execution of an input artifact. ## Reverse executable/library to source references The decompiler also maintains `EXECUTABLE.LIBRARY.SOURCE.REFERENCE.md`, which maps executables, shared/dynamic/static libraries, object files, managed artifacts, WebAssembly, LLVM bitcode, and raw images backward through format, architecture, OS/ABI, producer, language, version, and source references. The mapping is evidence-based rather than a claim of exact original source. Debug information, symbols, provenance, compiler fingerprints, runtime metadata, and object-member analysis are used to strengthen the reference. ## Language edition 3.0 The SLeeLa decompiler contract is aligned with the normative SLeeLa syntax **3.0** edition. Its SLeeLa source reconstruction target names syntax 3.0 as the current edition while preserving source-version evidence and older syntax compatibility. A reconstructed file must not be labelled as syntax 3.0 unless its emitted constructs satisfy that edition; the decompiler preserves uncertainty rather than inventing unsupported source semantics. See the root [`SLEELA.syntax`](../../SLEELA.syntax) and [API guide](../../decompiler/API.md). ### Source-version preservation For SLeeLa input, the decompiler treats the source pragma and artifact metadata as evidence. Syntax **3.0** is the current reconstruction edition, not a license to upgrade historical source automatically. Preserve the original declared source version when reconstructing an identifiable source file; use a 3.0 declaration only when the emitted constructs are valid under Syntax 3.0 and their individual feature gates. If the original version cannot be established, report that uncertainty rather than inventing a version.