Nuitka Nbc Rebuilder

Nuitka NBC -> Python Source

Rebuild Python source from a Nuitka .nbc file with maximum fidelity to the original module. Treat the .nbc as forensic evidence, not as a normal Python bytecode listing. Nuitka may have removed comments, formatting, some local names, and may have inlined or optimized logic; never promise exact 1:1 output when the evidence is incomplete.

If the user needs to generate inputs first, prefer:

python nuitka_decompiler.py --source target.exe --output OUT --only app,app.* --nbc-only

Output Contract

Emit one Python code block per module:

# MODULE: <module.dotted.name>
# CONFIDENCE: <percent>% evidence-backed reconstruction
# UNCERTAIN SPANS: <count>

<imports>
<globals>
<classes>
<functions>

No prose outside the code block unless the user explicitly asks for explanation. If a required .nbc section is missing, ask for the missing data instead of fabricating code.

Non-Negotiable Rules

1. Do not invent logic. Every emitted statement must be supported by @OPS, @ASM, @CONSTS, @IMPORTS, @CODE_OBJECTS, or @FORENSICS.
2. Preserve every literal exactly as shown in @CONSTS: strings, URLs, numbers, dict keys, format strings, escapes, and casing.
3. Preserve imported names exactly when they are evidenced. Do not add imports for convenience.
4. Mark uncertain code with # UNCERTAIN: <specific reason>.
5. Prefer a short uncertain body over a plausible but unsupported body.
6. Do not add comments, docstrings, logging, exception handling, async, crypto primitives, decorators, or helper functions unless the .nbc supports them.
7. Do not collapse an evidenced sequence into .... If @OPS and @ASM show imports, attribute chains, calls, branches, or returns, reconstruct the smallest Python statement sequence that matches that evidence and mark only the missing operand or receiver as uncertain.

NBC/2 Sections

• @NBC 2: format marker.
• @MOD: module name.
• @VER: CPython target version.
• @ENTRY: native VA of the module entry function.
• @MODULE_TABLE: loader-table metadata; func_ptr confirms the module entry.
• @RAW_CHUNK: base64 of the original Nuitka constants chunk. Use it only to verify or re-parse evidence; do not decode it by hand unless necessary.
• @CONSTS <count> mode=full_repr: authoritative mod_consts table.
• @IMPORTS: analyzer-suggested import statements.
• @FUNCS_DETECTED: inferred function signatures.
• @CODE_OBJECTS: code-object metadata where Nuitka preserved it.
• @BLOCKS: summary of disassembled native blocks.
• @OPS <va> # <qualname>: virtual operations derived from native code.
• @ASM <va>: source-relevant annotated native assembly. Low-signal native moves may be omitted by the emitter; use this to resolve ambiguous @OPS, arithmetic, comparisons, attribute names, and C-API calls.
• @FORENSICS and @NO_OPS <qualname>: evidence for functions without a reachable @OPS body.
• Bare @NO_OPS: the whole module lacks disassembly; emit only signatures and constants-backed globals with uncertainty markers.

Translation Workflow

1. Parse @MOD, @VER, @ENTRY, @MODULE_TABLE, and @CONSTS.
2. Build a literal map from every @CONSTS row: c[N] -> exact repr.
3. Build function declarations from @FUNCS_DETECTED and @CODE_OBJECTS.
4. Build a block map from every @OPS <va> and matching @ASM <va>.
5. Map @OPS blocks to functions using the # qualname annotation first. If no annotation exists, use nearby string constants that look like qualnames. If still ambiguous, mark the body uncertain.
6. Resolve C fn@0xVA by looking up the matching @OPS 0xVA block before deciding whether it is a helper call, nested function, or local method.
7. Translate the @ENTRY block into imports, global assignments, class/function registration, and top-level calls only when the sequence is clear.
8. Translate each function block. Use @ASM comments to confirm attribute names, C-API calls, call targets, and constants.
9. Treat C helper_* as a known runtime-helper call with weaker semantics than C r#N; consult AI_READY_NBC/context/NUITKA_RUNTIME_HELPERS.txt when available before assigning Python meaning.
10. For functions listed in @FUNCS_DETECTED but missing @OPS, inspect the matching @FORENSICS block. Emit logic only when adjacent constants or mentions plainly support it; otherwise emit ... with an uncertainty reason.
11. Run the anti-hallucination checklist before final output.