unidecompiler-simulator 0.1.1__tar.gz

unidecompiler_simulator-0.1.1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: unidecompiler-simulator
+Version: 0.1.1
+Summary: A decoupled generic IR simulator for unidecompiler
+Author-email: Wker <1670133844@qq.com>
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/Wker666/unidecompiler
+Project-URL: Repository, https://github.com/Wker666/unidecompiler
+Project-URL: Issues, https://github.com/Wker666/unidecompiler/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: unidecompiler<0.2.0,>=0.1.1
+
+# unidecompiler-simulator
+
+`unidecompiler-simulator` is a library for bounded execution of
+`unidecompiler` generic IR. It depends on the decompiler core but the core does
+not depend on, import, or know about this package.
+
+The simulator owns frames, control flow, calls, limits, exceptions, and the
+execution trace. A frontend may expose an optional `simulation_adapter`
+attribute for frontend-specific function lookup and runtime facts. The adapter
+may answer individual operations, but it must not execute functions, interpret
+instructions, recover control flow, or return executable callbacks.
+
+Generic IR execution is available without a frontend:
+
+```python
+from unidecompiler_simulator import SimulationEngine
+
+result = SimulationEngine().simulate_function(module, function, args=(1, 2))
+```
+
+Artifact execution gives an adapter the decoded frontend-owned payload only for
+function lookup and runtime hooks:
+
+```python
+result = SimulationEngine().simulate_artifact(
+    data,
+    "sample.bytecode",
+    query={"class": "Example", "method": "run"},
+)
+```
+
+The `unidecompiler-cli` package hosts the command-line interface and accepts a
+frontend-owned function query and JSON arguments:
+
+```sh
+unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
+```
+
+For the Lua bubble-sort fixture, compile the source before invoking the
+simulator. The Lua frontend adapter supplies only Lua function lookup and
+runtime value facts; the simulator still executes the lifted generic IR.
+
+```sh
+luac -o bubble_sort.luac simulator_projects/source/arithmetic.lua
+unidecompiler simulate bubble_sort.luac --frontend lua --function bubble_sort --args '[[5, 1, 4, 2, 8]]'
+```
+
+The completed result contains `"values": [[1, 2, 4, 5, 8]]`.
+
+Built-in frontend adapters accept the following frontend-owned function queries:
+
+| Frontend | Query |
+| --- | --- |
+| Python `.pyc` | Unique function name, for example `arithmetic` |
+| JVM `.class` | Unique method name or `Class.method`, for example `Sample.add` |
+| .NET assembly | Unique method name or `Type.Method`, for example `Probe.Add` |
+| WebAssembly | Function name or `$funcN`, for example `add` or `$func0` |
+| Lua chunk | Unique function name, for example `bubble_sort` |
+
+Ambiguous queries are rejected by the relevant frontend adapter. The simulator
+does not choose among overloads or perform frontend-specific name recovery.
+
+Execution is bounded and in-memory. Unknown operations, unsupported IR, and
+unsafe runtime behavior stop with a structured result instead of guessing.
+
+Applications may inject an `ExternalEnvironment` for unresolved named calls.
+The environment receives only `ExternalCallRequest` data and returns an
+`ExternalCallResult`; it never receives IR, frames, adapters, or execution
+control. Python-file loading is intentionally owned by `unidecompiler-cli`,
+not this library.
+
+The simulator does not resolve `Global` expressions as function names. Any
+frontend-specific function lookup or dynamic call target must be provided by
+the optional adapter and must resolve back to a `FunctionIR` owned by the
+current lifted module.
+
+The simulator intentionally does not execute frontend bytecode, frontend
+opcode tables, or core `Effect` objects directly. Core is responsible for
+lifting VM-neutral effects into generic IR; this package executes that generic
+IR. Keeping that boundary strict prevents a language-specific opcode switch
+from leaking into the simulator and keeps every frontend replaceable.

unidecompiler_simulator-0.1.1/README.md

@@ -0,0 +1,81 @@
+# unidecompiler-simulator
+
+`unidecompiler-simulator` is a library for bounded execution of
+`unidecompiler` generic IR. It depends on the decompiler core but the core does
+not depend on, import, or know about this package.
+
+The simulator owns frames, control flow, calls, limits, exceptions, and the
+execution trace. A frontend may expose an optional `simulation_adapter`
+attribute for frontend-specific function lookup and runtime facts. The adapter
+may answer individual operations, but it must not execute functions, interpret
+instructions, recover control flow, or return executable callbacks.
+
+Generic IR execution is available without a frontend:
+
+```python
+from unidecompiler_simulator import SimulationEngine
+
+result = SimulationEngine().simulate_function(module, function, args=(1, 2))
+```
+
+Artifact execution gives an adapter the decoded frontend-owned payload only for
+function lookup and runtime hooks:
+
+```python
+result = SimulationEngine().simulate_artifact(
+    data,
+    "sample.bytecode",
+    query={"class": "Example", "method": "run"},
+)
+```
+
+The `unidecompiler-cli` package hosts the command-line interface and accepts a
+frontend-owned function query and JSON arguments:
+
+```sh
+unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
+```
+
+For the Lua bubble-sort fixture, compile the source before invoking the
+simulator. The Lua frontend adapter supplies only Lua function lookup and
+runtime value facts; the simulator still executes the lifted generic IR.
+
+```sh
+luac -o bubble_sort.luac simulator_projects/source/arithmetic.lua
+unidecompiler simulate bubble_sort.luac --frontend lua --function bubble_sort --args '[[5, 1, 4, 2, 8]]'
+```
+
+The completed result contains `"values": [[1, 2, 4, 5, 8]]`.
+
+Built-in frontend adapters accept the following frontend-owned function queries:
+
+| Frontend | Query |
+| --- | --- |
+| Python `.pyc` | Unique function name, for example `arithmetic` |
+| JVM `.class` | Unique method name or `Class.method`, for example `Sample.add` |
+| .NET assembly | Unique method name or `Type.Method`, for example `Probe.Add` |
+| WebAssembly | Function name or `$funcN`, for example `add` or `$func0` |
+| Lua chunk | Unique function name, for example `bubble_sort` |
+
+Ambiguous queries are rejected by the relevant frontend adapter. The simulator
+does not choose among overloads or perform frontend-specific name recovery.
+
+Execution is bounded and in-memory. Unknown operations, unsupported IR, and
+unsafe runtime behavior stop with a structured result instead of guessing.
+
+Applications may inject an `ExternalEnvironment` for unresolved named calls.
+The environment receives only `ExternalCallRequest` data and returns an
+`ExternalCallResult`; it never receives IR, frames, adapters, or execution
+control. Python-file loading is intentionally owned by `unidecompiler-cli`,
+not this library.
+
+The simulator does not resolve `Global` expressions as function names. Any
+frontend-specific function lookup or dynamic call target must be provided by
+the optional adapter and must resolve back to a `FunctionIR` owned by the
+current lifted module.
+
+The simulator intentionally does not execute frontend bytecode, frontend
+opcode tables, or core `Effect` objects directly. Core is responsible for
+lifting VM-neutral effects into generic IR; this package executes that generic
+IR. Keeping that boundary strict prevents a language-specific opcode switch
+from leaking into the simulator and keeps every frontend replaceable.

unidecompiler_simulator-0.1.1/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unidecompiler-simulator"
+version = "0.1.1"
+description = "A decoupled generic IR simulator for unidecompiler"
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+authors = [{ name = "Wker", email = "1670133844@qq.com" }]
+requires-python = ">=3.11"
+dependencies = ["unidecompiler>=0.1.1,<0.2.0"]
+
+[project.urls]
+Homepage = "https://github.com/Wker666/unidecompiler"
+Repository = "https://github.com/Wker666/unidecompiler"
+Issues = "https://github.com/Wker666/unidecompiler/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

unidecompiler_simulator-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unidecompiler_simulator-0.1.1/src/unidecompiler_simulator/__init__.py

@@ -0,0 +1,53 @@
+"""Decoupled, bounded execution of unidecompiler generic IR."""
+
+from unidecompiler_simulator.adapters import (
+    CallRequest,
+    IntrinsicCall,
+    NotHandled,
+    ResolvedFunction,
+    SimulationTarget,
+    SimulationTargetCandidate,
+    SimulationAdapter,
+)
+from unidecompiler_simulator.engine import (
+    SimulationEngine,
+    SimulationCancellation,
+    SimulationEvent,
+    SimulationLimits,
+    SimulationResult,
+    SimulationStatus,
+    SimulationTargetListing,
+)
+from unidecompiler_simulator.environment import (
+    ExternalCallRequest,
+    ExternalCallResult,
+    ExternalCallStatus,
+    ExternalEnvironment,
+    ExternalFunction,
+)
+from unidecompiler_simulator.values import ObjectValue, SliceValue, TableValue
+
+__all__ = [
+    "NotHandled",
+    "CallRequest",
+    "IntrinsicCall",
+    "ObjectValue",
+    "SliceValue",
+    "TableValue",
+    "ResolvedFunction",
+    "SimulationAdapter",
+    "SimulationTarget",
+    "SimulationTargetCandidate",
+    "SimulationEngine",
+    "SimulationCancellation",
+    "SimulationEvent",
+    "SimulationLimits",
+    "SimulationResult",
+    "SimulationStatus",
+    "SimulationTargetListing",
+    "ExternalCallRequest",
+    "ExternalCallResult",
+    "ExternalCallStatus",
+    "ExternalEnvironment",
+    "ExternalFunction",
+]

unidecompiler_simulator-0.1.1/src/unidecompiler_simulator/adapters.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from unidecompiler.core.ir import FunctionIR, ModuleIR
+from unidecompiler.plugins import FrontendModule
+
+
+class _NotHandled:
+    def __repr__(self) -> str:
+        return "NotHandled"
+
+
+NotHandled = _NotHandled()
+
+
+@dataclass(frozen=True)
+class CallRequest:
+    """Data-only call request passed to an optional frontend adapter."""
+
+    callee: object
+    args: tuple[object, ...]
+    keywords: tuple[tuple[str, object], ...] = ()
+    context: object | None = None
+
+
+@dataclass(frozen=True)
+class SimulationTargetCandidate:
+    """A frontend-owned lookup query suitable for presenting to a host."""
+
+    label: str
+    query: object
+
+    def __post_init__(self) -> None:
+        if not self.label:
+            raise ValueError("simulation target label must not be empty")
+        if callable(self.query):
+            raise TypeError("simulation target query cannot be executable")
+
+
+@dataclass(frozen=True)
+class SimulationTarget:
+    """A verified generic function target with an opaque frontend query."""
+
+    label: str
+    query: object
+    function_index: int
+    params: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not self.label:
+            raise ValueError("simulation target label must not be empty")
+        if self.function_index < 0:
+            raise ValueError("simulation target function_index must be non-negative")
+        if not all(isinstance(param, str) for param in self.params):
+            raise TypeError("simulation target parameters must be strings")
+        if callable(self.query):
+            raise TypeError("simulation target query cannot be executable")
+
+
+@dataclass(frozen=True)
+class IntrinsicCall:
+    """A data-only request for a simulator-owned pure runtime operation."""
+
+    name: str
+    bit_width: int | None = None
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("intrinsic name must not be empty")
+        if self.bit_width is not None and self.bit_width <= 0:
+            raise ValueError("intrinsic bit_width must be positive")
+
+
+@dataclass(frozen=True)
+class ResolvedFunction:
+    """A frontend-selected generic function plus an opaque identity token.
+
+    The simulator validates that ``function`` belongs to the lifted module and
+    owns all execution. ``context`` is only passed back to adapter hooks; it is
+    never called, interpreted, or used as control flow by the simulator.
+    """
+
+    function: FunctionIR
+    context: object | None = None
+    identifier: str = ""
+
+    def __post_init__(self) -> None:
+        if callable(self.context):
+            raise TypeError("resolved function context cannot be executable")
+
+
+@runtime_checkable
+class SimulationAdapter(Protocol):
+    """Optional frontend runtime facts, never a frontend execution engine.
+
+    Implementations may define any subset of the operation methods. Missing
+    methods are treated as ``NotHandled``. They must not expose execute/run/
+    step/eval methods or return executable callbacks.
+    """
+
+    frontend_id: str
+
+    def resolve_function(
+        self,
+        query: object,
+        decoded_module: FrontendModule,
+        lifted_module: ModuleIR,
+    ) -> ResolvedFunction | _NotHandled: ...
+
+    def list_simulation_targets(
+        self,
+        decoded_module: FrontendModule,
+        lifted_module: ModuleIR,
+    ) -> tuple[SimulationTargetCandidate, ...] | _NotHandled: ...
+
+
+def adapter_for(plugin: object) -> SimulationAdapter | None:
+    adapter = getattr(plugin, "simulation_adapter", None)
+    if adapter is None:
+        return None
+    if isinstance(adapter, type):
+        adapter = adapter()
+    frontend_id = getattr(adapter, "frontend_id", None)
+    if not isinstance(frontend_id, str) or not frontend_id:
+        raise TypeError("simulation_adapter must declare a non-empty frontend_id")
+    if not callable(getattr(adapter, "resolve_function", None)):
+        raise TypeError("simulation_adapter must provide resolve_function")
+    forbidden = {"execute_function", "run", "step", "eval", "interpret", "next_instruction"}
+    exposed = forbidden.intersection(name for name in dir(adapter) if not name.startswith("__"))
+    if exposed:
+        names = ", ".join(sorted(exposed))
+        raise TypeError(f"simulation_adapter exposes forbidden execution methods: {names}")
+    return adapter  # type: ignore[return-value]
+
+
+def call_adapter(adapter: object | None, name: str, *args: Any) -> object:
+    if adapter is None:
+        return NotHandled
+    method = getattr(adapter, name, None)
+    if method is None:
+        return NotHandled
+    result = method(*args)
+    if callable(result) and not isinstance(result, ResolvedFunction):
+        raise TypeError(f"adapter operation {name!r} returned an executable callback")
+    return result