Home /Modules/decompiler/README.md

README.md

lib/decompiler/README.md · 225 line(s) · markdown

<img align="right" src="https://github.com/mearvk/SLeeLa/blob/master/images/debian/debian-logo.png" width="75" height="75" alt="SLeeLa">

<p align="center"><img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela/sleela-decompiler-logo-001.jpeg" alt="SLeeLa Decompiler" width="100%"></p>

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 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:

MediumExamplesEvidence yielded
Native executableELF ET_EXEC/PIE, PE .exe, Mach-Oformat, architecture, OS/ABI, entry point, sections, symbols
Shared/dynamic libraryELF .so/.so.*, PE .dll, Mach-O .dylibSONAME/exports, imports/needed libraries, relocations
Static library / objectAR .a, ELF .omember enumeration, per-member format, symbols
Kernel moduleELF .ko (incl. compressed, when safely identifiable)module name, vermagic, license/author, dependencies
Managed / bytecodeJVM class/JAR, .NET assembly, BEAM, Lua bytecoderuntime metadata, managed symbol/debug attributes
Portable / IRWebAssembly module, LLVM bitcodeproducer metadata, name/debug/custom sections
Raw / firmwareraw images, blobs, dumpsbyte-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:

Fractional-input policies (SleelaDecompilerFractionalInput):

PolicyMeaning
PRESERVEkeep unreadable/undecoded ranges as evidence
PARTIALreconstruct valid regions, insert explicit unresolved regions
REPORT_ONLYstop before reconstruction, retain analysis evidence
STRICTreject incomplete or contradictory input

The native request mirror (lib/decompiler/include/sleela_decompiler.h) carries the same shape for the C/C++ services:

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/:

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/):

# 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):

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):

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 <uri>.

Transports and URI forms:

TransportURI form
Local filefile:/abs/path or a bare /local/path
FTP (RFC 959 STOR, passive)ftp://[user:pass@]host[:port]/remote/path
HTTP POSThttp://host[:port]/path or http+post://...
HTTP PUThttp+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.

# 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 and API guide.

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.