Decompile / inspect / disassemble

How to read SPARK_BC with Spark / SparkLang tools — step by step, with screenshots and tool-layout diagrams. Dump tools read real .sparkbc from --compile. This page is inspect / disasm, not lossless source recovery.

Related research: LLM decompile research (site: /docs/llm-decompile.html) — DecompAI (agent) vs seq2seq models, LLM4Decompile, EmergentMind survey, Quarkslab article + RE category (LLM ≠ verified SoT), Plain English demystify overview, OpenBin (online product — not Spark SoT; third-party trust/IP), recompile ≠ semantic fidelity. Compete / scoreboard: DECOMPILE_COMPETE.md (/docs/decompile-compete.html) — parity matrix + measured make decompile-bench JSON (no fake “beats all”). Mermaid factory overview: Diagrams (/docs/diagrams.html).

Never claim an LLM perfectly decompiles SPARK_BC. Do not publish “beats Ghidra/IDA/…” without measured scoreboard JSON.

Tool-function diagrams

Compile path

Caption: .spark → bootstrap / GAS assembler → .sparkbc (SPARK_BC) → --run-bc / TRAIN·STEP / serve. Helpers, published shadow-builds, and the SDK GUI wrap the same SoT — they do not invent bytecode.

Decompile path

Caption: .sparkbc → dump.py (disasm/inspect) → readable hex + mnemonics (or stub JSON / --run-bc). Optional edit is of the .spark source, then recompile — dashed because dump is not a lossless BC→source decompiler.

Helpers · shadow-build · SDK/IDE GUI

Caption: Deterministic SPARK_BC SoT in the center. Helpers (Makefile, sparkc, tests), shadow-build (docs/examples/*.sparkbc), and SDK/IDE GUI (spark-bc-gui) sit around it and call the same compile/dump paths.

Deterministic tools vs LLM assist

Caption: Left = Spark SoT (compile, dump, run). Right = optional LLM assist later (names/comments/drafts) — never the SoT for .sparkbc bytes. See the research note for citations.

Step-by-step — CLI (primary today)

1. Build tools (once)

make spark-bootstrap spark
        

sparkc is a symlink to spark-bootstrap. GAS ./spark --compile thin-forks the same packer.

2. Dump a published .sparkbc

PYTHONPATH=python python3 tools/spark-bc-dump/dump.py \
         docs/examples/spark-train-step.sparkbc \
         --source examples/spark_train_step.spark \
         --command './spark-bootstrap --compile examples/spark_train_step.spark -o docs/examples/spark-train-step.sparkbc' \
         -o /tmp/spark-train-step-bc.txt
        

Caption: Terminal capture of tools/spark-bc-dump/dump.py on docs/examples/spark-train-step.sparkbc — magic SPBC, pools, opcode listing.

Loader / formatters: python/sparklang/model_lab/bc_dump.py (sections, string symbols, const/op xrefs, --json / --html export). Units: tools/spark-bc-dump/test_dump.py via make test-sparkbc; richer dump gate make test-decompile-compete.

Round-trip (SoT): make decompile-roundtrip — compile → dump → recompile → sha256 match on published fixtures.

Analysis project: tools/spark-bc-dump/analyze_project.py writes dump.txt / dump.json / dump.html / report.md under an output folder (local-only).

Bench / scoreboard: make decompile-bench → website/data/decompile-scoreboard.json.

Published dump text (no rebuild): docs/examples/*-bc.txt (site: website/docs/examples/).

3. Stub JSON (builder metadata)

PYTHONPATH=python python3 tools/spark-bc-dump/dump.py \
         docs/examples/spark-builder.sparkbc --stub -o /tmp/stub.json
        

Caption: --stub JSON from spark-builder.sparkbc — status, sha256, magic, version. Still inspect metadata, not source recovery.

4. Inspect behavior with --run-bc

./spark-bootstrap --run-bc docs/examples/spark-train-step.sparkbc
        ./spark --run-bc docs/examples/spark-train-step.sparkbc # GAS → bc_vm
        

Caption: ./spark-bootstrap --run-bc dry bytecode VM lines. TRAIN/STEP contracts: SPARK_BC.md.

5. CLI help (flags)

Caption: Captured dump.py --help — --stub, --weights, --serve (tiny CPU forward; not production LLM).

6. Init weights from bytecode (not trained)

PYTHONPATH=python python3 tools/spark-bc-dump/dump.py \
         docs/examples/spark-self.sparkbc \
         --weights /tmp/spark-self.init.safetensors
        

Emits Spark-created Xavier init (trained: false). See BUILD_MODELS.md.

Graphical path (SDK pack)

The SDK pack ships tools/spark_bc_gui / bin/spark-bc-gui (tkinter) that calls real --compile + bc_dump.format_dump. Prefer the SDK pack from Downloads / make sdk-pack. CLI remains the documented primary path on this page.

When the SDK pack is installed:

./bin/spark-bc-gui
        # or: PYTHONPATH=tools:python python3 -m spark_bc_gui
        

Buttons: Compile → .sparkbc, Decompile .sparkbc, open source / .sparkbc, save dump, load sample. See also sdk-ide-download.

Caption: Annotated layout matching tools/spark_bc_gui chrome. Right pane text is real dump.py output (same capture as the CLI screenshot). Interactive Tk GUI ships with the SDK download pack — headed capture was blocked; this mock is labeled as a mock.

Model lab reverse / inspect

./spark --dry-run examples/model_lab.spark
        make test-model-lab
        

model reverse / inspect read local config.json + safetensors index names only — no tensor body theft. MODEL_LAB.md.

ELF / machine disassembly (not SPARK_BC)

make machine-proof # ELF64 + _start when binary exists
        ./spark-binary-probe --elf ./spark # hdr + sections JSON
        # claim: local_elf_probe_not_ghidra — still not Ghidra-class
        make decompile-bench # records elf_local_probe
        

Language binary artifacts under out/decompile/<basename>/ (ALL_SECTIONS.disasm, …) are ELF section dumps, not SPARK_BC decode. Do not confuse with tools/spark-bc-dump.

sparkasm objects

make -C sparkasm test
        

Host objdump on assembled objects if needed — no Spark-branded SPARK_BC↔ELF round-trip claim beyond test-bc-emit.

What is not “decompile”

Related

• Compile · Build models
• SPARK_BC Builder · SPARK_BC.md
• Factory hub · LLM decompile research
• Decompile compete / scoreboard
• Screenshots + diagrams: website/docs/images/decompile-*, website/docs/images/diagram-*