tablambda 0.6.0.post30.dev0__py3-none-any.whl

tablambda/_defun_runtime.py

@@ -0,0 +1,207 @@
+"""The defunctionalized runtime: the minimal execution substrate for compiled code.
+
+Generated code references three free names from this module: ``Closure``, ``Thunk``, and ``interned``.
+A compiled ``Closure`` and a ``Thunk`` are both ``Node``s, so they share the interpreter's
+``weak_head_normal_form`` and interning and can run mixed with interpreted terms. The runtime holds NO
+domain logic; all compilation decisions live in the pure-lambda compiler ``_defun_codegen``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import struct
+import sys
+import threading
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, fields as dataclass_fields
+from typing import Any, TypeGuard, TypeVar, overload
+
+from typing_extensions import dataclass_transform
+
+from tablambda._ast import Node, WeakHeadBottom
+
+_T = TypeVar("_T")
+
+# The compiled runtime shares the interpreter's single bottom (``WeakHeadBottom``); ``_BOTTOM`` is the
+# terse internal alias used at the forcing call sites.
+_BOTTOM = WeakHeadBottom.BOTTOM
+
+
+class Closure(Node, ABC):
+    """A compiled closure: an opaque, closed, 1-ary callable ``Node`` (the defunctionalized value, and
+    the FFI). Every closure class the compiler emits subclasses ``Closure`` (injected by ``interned``),
+    so a compiled value is a ``Node`` and shares the interpreter's ``weak_head_normal_form`` and
+    interning. A closure is a weak-head value (its weak head normal form is itself), and it is closed,
+    so its ``loose_bound`` is ``0`` and ``shift``/``substitute`` leave it untouched.
+    """
+
+    __slots__ = ()
+
+    # Closures are closed: no exposed de Bruijn index, so shift/substitute are identity.
+    loose_bound = 0
+
+    @abstractmethod
+    def __call__(self, argument: Node) -> Node: ...
+
+
+def _intern(cls: type[_T], field_names: tuple[str, ...]) -> type[_T]:
+    """Hash-cons ``cls``'s instances by ``(cls, field-values-by-identity)``.
+
+    Two instances of the same class with identical field values (by ``is``) become the same object.
+    Fields are themselves interned closures or ``Thunk`` instances, so identity comparison is O(1)
+    structural equality, matching ``_ast._intern_node``. The hash-cons table is exposed as
+    ``__intern_pool__`` for introspection (e.g. counting tabled objects in a benchmark); it is the SAME
+    table the interner already keeps, so surfacing it adds no behaviour.
+
+    The key is computed directly from the positional constructor arguments (which correspond 1:1 to
+    ``field_names`` for both ``@dataclass`` classes and ``Thunk``), so a cache hit avoids allocating
+    a throwaway instance entirely.
+    """
+    pool: dict[tuple, object] = {}
+    original_init = cls.__init__
+
+    def __new__(klass, *args):
+        key = (klass,) + tuple(id(a) for a in args)
+        existing = pool.get(key)
+        if existing is not None:
+            return existing
+        instance = object.__new__(klass)
+        original_init(instance, *args)
+        pool[key] = instance
+        return instance
+
+    cls_any: Any = cls
+    cls_any.__new__ = __new__
+    cls_any.__init__ = lambda self, *args, **kwargs: None
+    cls_any.__intern_pool__ = pool
+    return cls
+
+
+@overload
+def interned(cls: type[_T], *, slots: bool = ...) -> type[_T]: ...
+
+
+@overload
+def interned(
+    cls: None = ..., *, slots: bool = ...
+) -> Callable[[type[_T]], type[_T]]: ...
+
+
+@dataclass_transform(eq_default=False)
+def interned(cls=None, *, slots=True):
+    """Class decorator: make a generated ``Closure`` subclass a frozen-by-identity dataclass and
+    hash-cons its instances.
+
+    Applies ``dataclass(eq=False, slots=slots)`` internally (so generated code needs only
+    ``@interned``, not a separate ``@dataclass``), then interns. ``slots=True`` (the default) makes the
+    closures the compiler emits slotted, which is faster and lighter; ``eq=False`` keeps identity-based
+    equality. The compiler emits each closure as ``@interned class vg_...(Closure)``, so the class is
+    already a ``Node`` before this decorator runs. Usable bare (``@interned``) or parameterised
+    (``@interned(slots=False)``).
+    """
+    if cls is None:
+        return lambda klass: interned(klass, slots=slots)
+    assert issubclass(cls, Closure), f"@interned expects a Closure subclass, got {cls!r}"
+    cls = dataclass(eq=False, slots=slots)(cls)
+    field_names = tuple(f.name for f in dataclass_fields(cls))
+    return _intern(cls, field_names)
+
+
+def _deterministic_hash(*parts: int) -> int:
+    """A deterministic hash from a sequence of integers, independent of ``PYTHONHASHSEED``."""
+    data = struct.pack(f">{len(parts)}q", *parts)
+    return int.from_bytes(hashlib.sha256(data).digest()[:8], "big")
+
+
+class Thunk(Node):
+    """A suspended application (redex) as a ``Node``: an ``App`` whose callee is a compiled value.
+    Interned so structurally equal redexes share identity, enabling tabling: its
+    ``weak_head_normal_form`` (inherited from ``Node``) is computed once per distinct ``Thunk``.
+
+    It does NOT redeclare ``weak_head_normal_form`` (that would duplicate ``Node``'s fixpoint cache
+    slot); instead ``_shape.compute_weak_head_normal_form`` dispatches a ``Thunk`` to ``force``.
+    A thunk is closed, so its ``loose_bound`` is ``0``.
+    """
+
+    __slots__ = ("callee", "argument")
+
+    # A redex over closed compiled values is itself closed.
+    loose_bound = 0
+
+    def __init__(self, callee: Node, argument: Node) -> None:
+        self.callee = callee
+        self.argument = argument
+
+    def __call__(self, a: Node) -> "Thunk":
+        return Thunk(self, a)
+
+    def force(self) -> Node | WeakHeadBottom:
+        """The weak head normal form of this redex: force the callee to a value, apply it to the
+        argument, and force the result. Mixed-safe: the callee may force to an interpreter ``Lam`` or a
+        ``Closure``, and ``apply_value`` handles both."""
+        from tablambda._shape import apply_value, weak_head_normalize
+
+        callee = weak_head_normalize(self.callee)
+        if callee is _BOTTOM:
+            return _BOTTOM
+        result = apply_value(callee, self.argument)
+        if result is _BOTTOM:
+            return _BOTTOM
+        return weak_head_normalize(result)
+
+
+Thunk = _intern(Thunk, ("callee", "argument"))
+
+
+def _is_thunk(x: object) -> TypeGuard[Thunk]:
+    return isinstance(x, Thunk)
+
+
+# --- stack helpers ---------------------------------------------------------------------------------
+
+_COMPILE_RECURSION_LIMIT = 16_000
+_RECURSION_LIMIT = 200_000
+_STACK_SIZE = 1024 * 1024 * 1024  # 1 GiB
+
+
+@contextmanager
+def recursion_headroom() -> Iterator[None]:
+    previous = sys.getrecursionlimit()
+    sys.setrecursionlimit(max(previous, _COMPILE_RECURSION_LIMIT))
+    try:
+        yield
+    finally:
+        sys.setrecursionlimit(previous)
+
+
+def _python_tag() -> str:
+    """A Python-version tag for generated-module filenames, e.g. ``py313``. Defunctionalized modules
+    are rendered with ``ast.unparse``, whose formatting can differ between Python versions, so a module
+    generated under one interpreter must not be reused under another; the tag keeps artifacts distinct.
+    """
+    return f"py{sys.version_info.major}{sys.version_info.minor}"
+
+
+def run_in_large_stack(thunk):
+    """Run ``thunk`` in a thread with a 1 GiB C stack and a high recursion limit."""
+    result: list = []
+
+    def run() -> None:
+        previous_limit = sys.getrecursionlimit()
+        sys.setrecursionlimit(max(previous_limit, _RECURSION_LIMIT))
+        try:
+            result.append(thunk())
+        finally:
+            sys.setrecursionlimit(previous_limit)
+
+    previous_stack_size = threading.stack_size(_STACK_SIZE)
+    try:
+        worker = threading.Thread(target=run)
+        worker.start()
+        worker.join()
+    finally:
+        threading.stack_size(previous_stack_size)
+    (single_result,) = result
+    return single_result

tablambda/_defunctionalize.py

@@ -0,0 +1,455 @@
+"""The defunctionalization boundary: quote, compile, decode, canonicalize, load.
+
+Thin Python layer analogous to ``_specialize`` but for the defunctionalization target. The lambda
+compiler ``DEFUN`` produces the Scott-encoded ``ast.Module``; this module quotes the input, runs
+the compiler in the interpreter, decodes the Scott AST to a real ``ast.Module``, deduplicates
+class definitions by node identity (``memoized_decode``), renames every class by the Merkle hash of
+its COMPILED body (``_canonicalize_classes``), and unparses to source. ``load`` execs the source
+with the runtime globals (``Thunk``, ``interned``, ``dataclass``) and returns the ``compiled``
+value.
+
+Content addressing happens on the compiled dataclass, not the source lambda term. Two source
+closures of the same shape that capture variables at different de Bruijn depths compile to the same
+dataclass (same arity, byte-identical ``__call__`` body over positional capture fields), so the
+boundary collapses them to one class. This is coarser than the source's term equality and makes the
+generated code smaller and more reusable.
+"""
+
+from __future__ import annotations
+
+import ast
+import contextlib
+import copy
+import hashlib
+from typing import TypeVar
+
+from tablambda._ast import Node
+from tablambda._codec import quote_binnat
+from tablambda._defun_codegen import DEFUN
+from tablambda._defun_runtime import (
+    Closure,
+    Thunk,
+    _BOTTOM,
+    _is_thunk,
+    interned,
+    run_in_large_stack,
+)
+
+_AstNode = TypeVar("_AstNode", bound=ast.AST)
+from tablambda._dsl import app, build
+from tablambda._pyast import SUPPORTED, _ARITY, _reset_gensym, decode, memoized_decode
+
+
+class _RenameClasses(ast.NodeTransformer):
+    """Rewrite ``ast.Name`` references to class names according to ``mapping``."""
+
+    def __init__(self, mapping: "dict[str, str]") -> None:
+        self._mapping = mapping
+
+    def visit_Name(self, node: ast.Name) -> ast.Name:
+        renamed = self._mapping.get(node.id)
+        if renamed is not None:
+            return ast.copy_location(ast.Name(id=renamed, ctx=node.ctx), node)
+        return node
+
+
+def _rename_copy(node: _AstNode, mapping: "dict[str, str]") -> _AstNode:
+    """A deep copy of ``node`` with class-name references rewritten per ``mapping``."""
+    renamed = _RenameClasses(mapping).visit(copy.deepcopy(node))
+    assert isinstance(renamed, type(node)), (
+        f"_RenameClasses must preserve node type {type(node).__name__}, got {type(renamed).__name__}"
+    )
+    return renamed
+
+
+class _RenameFields(ast.NodeTransformer):
+    """Rewrite a class's capture-field names (AnnAssign targets and ``self.<field>`` accesses)."""
+
+    def __init__(self, mapping: "dict[str, str]") -> None:
+        self._mapping = mapping
+
+    def visit_Name(self, node: ast.Name) -> ast.Name:
+        renamed = self._mapping.get(node.id)
+        if renamed is not None:
+            return ast.copy_location(ast.Name(id=renamed, ctx=node.ctx), node)
+        return node
+
+    def visit_Attribute(self, node: ast.Attribute) -> ast.Attribute:
+        self.generic_visit(node)
+        renamed = self._mapping.get(node.attr)
+        if renamed is not None:
+            node.attr = renamed
+        return node
+
+
+def _canonicalize_fields(classdef: ast.ClassDef) -> ast.ClassDef:
+    """Rename a class's capture fields to positional ``cap_<i>`` names (in definition order)."""
+    field_names = [
+        statement.target.id
+        for statement in classdef.body
+        if isinstance(statement, ast.AnnAssign) and isinstance(statement.target, ast.Name)
+    ]
+    mapping = {name: f"cap_{position}" for position, name in enumerate(field_names)}
+    renamed = _RenameFields(mapping).visit(copy.deepcopy(classdef))
+    assert isinstance(renamed, ast.ClassDef)
+    return renamed
+
+
+def _canonicalize_classes(module: ast.Module) -> ast.Module:
+    """Rename every closure class by a content hash of its COMPILED dataclass and drop duplicates.
+
+    Capture fields are first renamed positionally (``cap_0``, ``cap_1``, ...). The content hash of a
+    class is then the Merkle hash of its (field-canonicalized) body with references to other classes
+    replaced by THEIR content hashes (computed bottom-up over the acyclic class-reference DAG) and the
+    class's own name replaced by a fixed placeholder. Two classes with identical compiled bodies hash
+    equal and collapse to one. Definitions are emitted sorted by name, so the output is stable under
+    local source edits and identical between the in-process and self-hosted compilers.
+    """
+    classdefs: "dict[str, ast.ClassDef]" = {}
+    others: "list[ast.stmt]" = []
+    for statement in module.body:
+        if isinstance(statement, ast.ClassDef):
+            field_canonical = _canonicalize_fields(statement)
+            kept = classdefs.get(field_canonical.name)
+            if kept is not None:
+                assert ast.dump(kept) == ast.dump(field_canonical), (
+                    f"provisional class {field_canonical.name!r} has two non-identical definitions"
+                )
+                continue
+            classdefs[field_canonical.name] = field_canonical
+        else:
+            others.append(statement)
+    provisional = set(classdefs)
+
+    def referenced(classdef: ast.ClassDef) -> "set[str]":
+        return {n.id for n in ast.walk(classdef) if isinstance(n, ast.Name) and n.id in provisional}
+
+    canonical: "dict[str, str]" = {}
+    in_progress: "set[str]" = set()
+
+    def canonical_name(name: str) -> str:
+        cached = canonical.get(name)
+        if cached is not None:
+            return cached
+        assert name not in in_progress, f"class reference cycle through {name!r}"
+        in_progress.add(name)
+        classdef = classdefs[name]
+        mapping = {reference: canonical_name(reference) for reference in referenced(classdef)}
+        mapping[name] = "_SELF_"
+        key_node = _rename_copy(classdef, mapping)
+        assert isinstance(key_node, ast.ClassDef)
+        key_node.name = "_SELF_"
+        digest = hashlib.sha256(ast.dump(key_node).encode()).digest()[:8]
+        result = "vg_" + digest.hex()
+        in_progress.discard(name)
+        canonical[name] = result
+        return result
+
+    for name in classdefs:
+        canonical_name(name)
+
+    global_mapping = {name: canonical[name] for name in provisional}
+    deduped: "dict[str, ast.ClassDef]" = {}
+    for name, classdef in classdefs.items():
+        renamed = _rename_copy(classdef, global_mapping)
+        assert isinstance(renamed, ast.ClassDef)
+        renamed.name = canonical[name]
+        deduped[renamed.name] = renamed
+
+    sorted_defs: "list[ast.stmt]" = [deduped[key] for key in sorted(deduped)]
+    new_others = [_rename_copy(statement, global_mapping) for statement in others]
+    module.body = sorted_defs + new_others
+    return module
+
+
+# --- Direct defun decoder: decode Scott-encoded AST from defunctionalized values -----------------
+# Mirrors ``_pyast.decode`` but operates directly on compiled values (``Thunk`` + ``Closure``),
+# reflecting Scott structure out of them with marker handlers in the self-hosted compilation path.
+
+
+# The decoder reflects Scott structure out of compiled values by feeding them marker handlers and
+# reading which handler fires. Compiled code embeds these markers as ``Thunk`` callees/arguments and
+# forces them, so each marker must be a ``Node`` (a ``Closure``): a marker's weak head normal form is
+# itself, and applying a callable marker runs its Python ``__call__``.
+
+
+class _TagMarker(Closure):
+    """Callable marker for Scott constructor extraction. When the Scott value selects this handler,
+    it calls ``__call__`` once per field, accumulating the field values."""
+
+    __slots__ = ("tag", "fields")
+
+    def __init__(self, tag: int) -> None:
+        self.tag = tag
+        self.fields: list[object] = []
+
+    def __call__(self, argument: Node) -> Node:
+        self.fields.append(argument)
+        return self
+
+
+class _ChurchApp(Closure):
+    """Marker node in a Church numeral spine: successor applied to predecessor. Never applied (it is a
+    spine value the decoder walks via ``argument``)."""
+
+    __slots__ = ("argument",)
+
+    def __init__(self, argument: object) -> None:
+        self.argument = argument
+
+    def __call__(self, argument: Node) -> Node:
+        raise TypeError("_ChurchApp is a spine value, not applicable")
+
+
+class _ChurchSucc(Closure):
+    """Callable marker for Church numeral successor."""
+
+    __slots__ = ()
+
+    def __call__(self, argument: Node) -> Node:
+        return _ChurchApp(argument)
+
+
+class _ChurchZero(Closure):
+    """The Church-numeral zero marker: the base value at the end of the spine, never applied."""
+
+    __slots__ = ()
+
+    def __call__(self, argument: Node) -> Node:
+        raise TypeError("_ChurchZero is a base value, not applicable")
+
+
+_CHURCH_SUCC_DEFUN = _ChurchSucc()
+_CHURCH_ZERO_DEFUN = _ChurchZero()
+
+_church_int_cache: "dict[int, int]" = {}
+_defun_gensym_ids: "dict[int, str]" = {}
+_defun_gensym_counter: int = 0
+_defun_decode_memo: "dict[int, ast.AST] | None" = None
+
+
+def _reset_defun_gensym() -> None:
+    _church_int_cache.clear()
+    _defun_gensym_ids.clear()
+    global _defun_gensym_counter
+    _defun_gensym_counter = 0
+
+
+@contextlib.contextmanager
+def _memoized_decode_defun():
+    global _defun_decode_memo
+    assert _defun_decode_memo is None, "memoized decode_defun does not nest"
+    _defun_decode_memo = {}
+    try:
+        yield
+    finally:
+        _defun_decode_memo = None
+
+
+def _force_defun(value: object) -> object:
+    if _is_thunk(value):
+        whnf = value.weak_head_normal_form
+        assert whnf is not _BOTTOM, "hit bottom while forcing defun value"
+        return whnf
+    return value
+
+
+def _extract_defun(value: object, arities: "tuple[int, ...]") -> "tuple[int, list[object]]":
+    current = _force_defun(value)
+    for tag in range(len(arities)):
+        assert callable(current), f"expected callable during extraction, got {type(current).__name__}"
+        result = current(_TagMarker(tag))
+        current = _force_defun(result)
+    assert isinstance(current, _TagMarker), (
+        f"expected _TagMarker after extraction, got {type(current).__name__}"
+    )
+    return current.tag, current.fields
+
+
+def _church_to_int_defun(value: object) -> int:
+    key = id(value)
+    cached = _church_int_cache.get(key)
+    if cached is not None:
+        return cached
+    current = _force_defun(value)
+    assert callable(current), f"church spine head must be callable, got {type(current).__name__}"
+    current = current(_CHURCH_SUCC_DEFUN)
+    current = _force_defun(current)
+    assert callable(current), f"church spine successor result must be callable, got {type(current).__name__}"
+    current = current(_CHURCH_ZERO_DEFUN)
+    current = _force_defun(current)
+    count = 0
+    while isinstance(current, _ChurchApp):
+        count += 1
+        current = _force_defun(current.argument)
+    assert current is _CHURCH_ZERO_DEFUN, "church spine did not end at zero marker"
+    _church_int_cache[key] = count
+    return count
+
+
+def _decode_scott_list_defun(value: object) -> "list[object]":
+    items: "list[object]" = []
+    current = value
+    while True:
+        tag, fields = _extract_defun(current, (2, 0))
+        if tag == 1:
+            return items
+        assert tag == 0, f"expected cons (0) or nil (1), got {tag}"
+        items.append(fields[0])
+        current = fields[1]
+
+
+def _gensym_name_defun(payload: object) -> str:
+    global _defun_gensym_counter
+    key = id(payload)
+    existing = _defun_gensym_ids.get(key)
+    if existing is not None:
+        return existing
+    name = f"vg_{_defun_gensym_counter:016x}"
+    _defun_gensym_counter += 1
+    _defun_gensym_ids[key] = name
+    return name
+
+
+def _decode_field_defun(value: object) -> object:
+    _, fields = _extract_defun(value, (2,))
+    kind_value, payload = fields
+    kind = _church_to_int_defun(kind_value)
+    match kind:
+        case 0:
+            return decode_defun(payload)
+        case 1:
+            return [_decode_field_defun(item) for item in _decode_scott_list_defun(payload)]
+        case 2:
+            return _church_to_int_defun(payload)
+        case 3:
+            return "".join(chr(_church_to_int_defun(code)) for code in _decode_scott_list_defun(payload))
+        case 5:
+            return None
+        case 7:
+            return _gensym_name_defun(payload)
+        case _:
+            raise ValueError(f"defun decode: unsupported field kind {kind}")
+
+
+def decode_defun(value: object) -> ast.AST:
+    """Decode a Scott-encoded AST directly from defunctionalized values (Thunks + closures).
+
+    Reflects Scott structure out of the compiled values with marker handlers, with no intermediate
+    interpreter-tree readback. Under ``_memoized_decode_defun``, each distinct interned value is
+    decoded once (keyed by identity).
+    """
+    if _defun_decode_memo is not None:
+        cached = _defun_decode_memo.get(id(value))
+        if cached is not None:
+            return cached
+    tag, fields = _extract_defun(value, _ARITY)
+    cls = SUPPORTED[tag]
+    decoded = cls(*[_decode_field_defun(field) for field in fields])
+    if _defun_decode_memo is not None:
+        _defun_decode_memo[id(value)] = decoded
+    return decoded
+
+
+def defunctionalize(node: Node) -> str:
+    """Compile a lambda term to defunctionalized Python source (a module of closure classes).
+
+    Runs in a large-stack thread: the interpreter's substitution recursion can be as deep as the term,
+    which overflows the C stack on Python 3.12+ (which caps C recursion regardless of
+    ``setrecursionlimit``); ``run_in_large_stack`` gives it a 1 GiB stack and a high recursion limit.
+    """
+    def work() -> str:
+        module = build(app(DEFUN, quote_binnat(node)))
+        _reset_gensym()
+        with memoized_decode():
+            decoded = decode(module)
+        assert isinstance(decoded, ast.Module)
+        canonical_module = _canonicalize_classes(decoded)
+        return ast.unparse(ast.fix_missing_locations(canonical_module))
+
+    return run_in_large_stack(work)
+
+
+def _defun_globals() -> dict:
+    return {
+        "Thunk": Thunk,
+        "interned": interned,
+        "Closure": Closure,
+    }
+
+
+def load_namespace(source: str) -> dict:
+    """Execute defunctionalized source and return the whole module namespace.
+
+    The namespace holds every generated closure class (each carrying its ``__intern_pool__``) and the
+    ``compiled`` value, so a caller can both run the program and inspect its tabled objects.
+    """
+    namespace = _defun_globals()
+    exec(compile(source, "<defun>", "exec"), namespace)  # noqa: S102
+    return namespace
+
+
+def load(source: str) -> object:
+    """Execute defunctionalized source and return the ``compiled`` value."""
+    return load_namespace(source)["compiled"]
+
+
+def defunctionalize_and_load(node: Node) -> object:
+    """Compile a lambda term to defunctionalized code and load the resulting value."""
+    return load(defunctionalize(node))
+
+
+# A self-contained import header so a generated defunctionalized module runs on its own: it binds the
+# runtime free names the generated code references (``Closure``, ``Thunk``, ``interned``). Every
+# generated closure explicitly subclasses ``Closure`` and annotates its captures ``cap_i: Closure``;
+# ``interned`` applies ``dataclass(eq=False)`` and hash-conses, so generated classes carry only
+# ``@interned``.
+_DEFUN_MODULE_HEADER = (
+    "# Generated, self-contained module: the import header is added at serialization time (see\n"
+    "# tablambda._defunctionalize.runnable_defun_module); the body is emitted by the DEFUN lambda\n"
+    "# term and content-addressed by compiled dataclass shape.\n"
+    "from tablambda._defun_runtime import Closure, Thunk, interned\n"
+)
+
+
+def runnable_defun_module(source: str) -> str:
+    """Prepend the runtime import header so a defunctionalized module is importable on its own."""
+    return _DEFUN_MODULE_HEADER + "\n" + source
+
+
+def defun_compiler_source() -> str:
+    """The defunctionalization compiler ``DEFUN`` self-compiled to a runnable dataclass module.
+
+    This is the dataclass-form ``compiled compiler``: ``DEFUN`` defunctionalized by itself. Importing
+    the result binds ``compiled`` to the defunctionalized ``DEFUN`` value; applying it (through a
+    ``Thunk``) to a quoted program yields that program's compiled Scott ``ast.Module`` as a
+    defunctionalized value.
+    """
+    from tablambda._defun_codegen import DEFUN
+
+    return runnable_defun_module(defunctionalize(build(DEFUN)))
+
+
+def compile_with_defun(engine: object, node: Node) -> str:
+    """Compile ``node`` by RUNNING a defunctionalized ``DEFUN`` engine (the dataclass compiled compiler).
+
+    ``engine`` is the ``compiled`` value of a ``defun_compiler_source`` module. The node is quoted and
+    itself defunctionalized to feed the engine a defunctionalized Scott source value; the engine's
+    output (a defunctionalized Scott ``ast.Module``) is reified, decoded, canonicalized, and unparsed,
+    yielding exactly what the in-process ``defunctionalize`` produces, by self-hosting.
+    """
+    quoted_argument = defunctionalize_and_load(build(quote_binnat(node)))
+
+    def work() -> str:
+        result = Thunk(engine, quoted_argument).weak_head_normal_form
+        if result is _BOTTOM:
+            raise ValueError("the defunctionalized compiler did not produce a module")
+        _reset_defun_gensym()
+        with _memoized_decode_defun():
+            decoded = decode_defun(result)
+        assert isinstance(decoded, ast.Module)
+        canonical_module = _canonicalize_classes(decoded)
+        return ast.unparse(ast.fix_missing_locations(canonical_module))
+
+    return run_in_large_stack(work)
+