---
name: nuitka-nbc-rebuilder
description: Maximum-fidelity Python source reconstruction from Nuitka `.nbc` / `NBC/2` files produced by `nuitka_decompiler.py`. Use when the user pastes or references a `.nbc` file, an `AI_READY_NBC` bundle, sections such as `@MOD`, `@CONSTS`, `@RAW_CHUNK`, `@OPS`, `@ASM`, `@FORENSICS`, `module_code_*`, `mod_consts[N]`, or asks to rebuild Python source from a Nuitka C-compiled module. The goal is evidence-backed reconstruction, not guaranteed perfect 1:1 recovery; uncertain spans must be marked.
---

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

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

## Output Contract

Emit one Python code block per module:

```python
# 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.

## Virtual Ops

- `L c[N]`: load `mod_consts[N]`.
- `C r#N`: call a ranked Nuitka runtime helper.
- `C helper_*`: call a less common runtime helper.
- `C fn@0xVA`: call another native block in this same module; resolve to
  `@OPS 0xVA` when present.
- `C module_code_<name>`: call another module entry. Usually import/init logic.
- `C capi:<name>`: call a Python C-API function.
- `J_EQ c[N] Lx` / `J_NE c[N] Lx`: conditional branch against a constant.
- `J_EQ ? Lx`: conditional branch with unresolved comparator.
- `J Lx`: unconditional branch.
- `:Lx`: label.
- `RET`: return.

## Runtime Helper Hints

Treat ranks as build-local hints, not universal truth. Use
`AI_READY_NBC/context/NUITKA_RUNTIME_HELPERS.txt` when available.

Common rank meanings:

- `r#0`: attribute lookup (`obj.attr`)
- `r#1`: no-arg call (`f()`)
- `r#2`: one-arg call (`f(a)`)
- `r#3`: two-arg call (`f(a, b)`)
- `r#4`: three-arg call (`f(a, b, c)`)
- `r#5`: positional/variadic call
- `r#6` to `r#8`: globals or string-dict lookup/update
- `r#9` to `r#13`: imports or method calls
- `r#14` and above: function creation, class creation, globals update, or
  helper-specific operations depending on the build

## C-API Hints

- `PyImport_ImportModule`: `import X`
- `PyImport_ImportModuleLevel*`: relative/from import logic
- `PyObject_GetAttrString`: `obj.name`
- `PyObject_SetAttrString`: `obj.name = value`
- `PyObject_Call*`: `obj(...)`
- `PyObject_IsTrue`: truthiness check
- `PyDict_GetItem`, `PyDict_SetItem`, `PyDict_DelItem`: dict access/update
- `PyUnicode_GetLength`, `PyUnicode_Find`, `PyUnicode_Substring`: string ops
- `PyErr_*`: exception path evidence
- `PyGen_*`, `PyCoro_*`: generator/coroutine evidence

## Anti-Hallucination Checklist

Before emitting code, verify:

- Every string literal appears verbatim in `@CONSTS`.
- Every numeric literal above 10 appears in `@CONSTS`.
- Every import is supported by `@IMPORTS`, `@OPS`, or `@ASM`.
- Every call target is supported by `@OPS`, `@ASM`, or a known C-API pattern.
- No exception handling appears without `PyErr_*` or branch evidence.
- No crypto logic appears without visible crypto imports, attributes, constants,
  or C-API evidence.
- No async/generator syntax appears without coroutine/generator evidence.

If a line fails, replace that line with `# UNCERTAIN: <failed check>`.

## Reconstruction Bias

Be evidence-maximal, not stub-maximal. A body with five supported operations
and one unknown receiver should become four or five Python lines plus one
`# UNCERTAIN` marker, not a full `...` body. Preserve uncertainty locally.

## Confidence

Compute confidence qualitatively:

- 90-100%: almost every nontrivial line comes from `@OPS`/`@ASM`.
- 70-89%: core control flow is evidenced, with small uncertain spans.
- 40-69%: signatures and literals are strong, bodies partly inferred.
- Below 40%: emit mostly signatures/globals with uncertainty markers.

Use the header value to communicate evidence quality, not optimism.