rpkbin 0.1.0__tar.gz

rpkbin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 redpigkiller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rpkbin-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: rpkbin
+Version: 0.1.0
+Summary: Personal collection of small scripts and helpers for work.
+Author-email: redpigkiller <hongrunlu511@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/redpigkiller/rpkbin
+Project-URL: Repository, https://github.com/redpigkiller/rpkbin
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.3.1
+Provides-Extra: cfg
+Requires-Dist: networkx>=3.6.1; extra == "cfg"
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1.5; extra == "excel"
+Requires-Dist: xlrd>=2.0.2; extra == "excel"
+Requires-Dist: rapidfuzz>=3.14.3; extra == "excel"
+Provides-Extra: wave
+Requires-Dist: textual>=8.0.2; extra == "wave"
+Requires-Dist: prompt_toolkit>=3.0.52; extra == "wave"
+Requires-Dist: rich>=14.2.0; extra == "wave"
+Provides-Extra: all
+Requires-Dist: networkx>=3.6.1; extra == "all"
+Requires-Dist: openpyxl>=3.1.5; extra == "all"
+Requires-Dist: xlrd>=2.0.2; extra == "all"
+Requires-Dist: rapidfuzz>=3.14.3; extra == "all"
+Requires-Dist: textual>=8.0.2; extra == "all"
+Requires-Dist: prompt_toolkit>=3.0.52; extra == "all"
+Requires-Dist: rich>=14.2.0; extra == "all"
+Dynamic: license-file
+
+# rpkbin — Core IC Design & Verification Utilities
+
+[![English](https://img.shields.io/badge/Language-English-blue.svg)](README.md)
+[![繁體中文](https://img.shields.io/badge/語言-繁體中文-blue.svg)](README_zh.md)
+
+`rpkbin` is a comprehensive toolkit providing essential data types and utilities for hardware design and verification flows.
+
+## Core Features
+
+### 1. MapBV — BitVector with Bidirectional Mapping
+MapBV allows you to define a hierarchy of bit-fields that stay synchronized automatically.
+- **Hierarchical Slicing**: Define a 32-bit register and slice it into named fields.
+- **Bidirectional Linking**: Use `concat` to build a new view from existing variables; updating the view updates the sources.
+- **Symbolic Evaluation**: Use `.eval()` to test "what-if" scenarios without changing actual values.
+
+[Learn more in MapBV Documentation](docs/mapbv/mapbv.md)
+
+### 2. NumBV — Bit-True Fixed-Point Arithmetic
+Bit-exact fixed-point simulation for DSP pipeline verification. Pure NumPy, no external dependency.
+- **Two-layer API**: Operator layer (`+`, `*`) for convenience; function layer (`nbv.add()`, `nbv.mul()`) for explicit pipeline staging.
+- **Five Rounding Modes**: `trunc`, `round`, `round_half_even` (convergent, Xilinx DSP48), `ceil`, `round_to_zero`.
+- **Unified Operations**: One `NumBV` class handles both scalar and array computations. Backed by NumPy by default, with an optional drop-in JAX backend for transparent XLA hardware acceleration.
+
+[Learn more in NumBV Documentation](docs/numbv/numbv.md)
+
+### 3. Excel Extractor — Template-Based Extraction
+Intelligently extract data from complex spreadsheets.
+- **Layout Description**: Define the "shape" of data instead of hardcoded coordinates.
+- **Fuzzy Matching**: Matches headers even with slight spelling variations.
+- **Merged Cell Support**: Correctly resolves values spanning across merged rows/cols.
+
+[Learn more in Excel Extractor Documentation](docs/excel_extractor/excel_extractor.md)
+
+### 4. Job Manager
+A practical, cross-platform job manager for running shell commands and Python callables safely in parallel.
+
+- **One API for Common Workloads**: Run local functions (`FuncJob`) and CLI tasks (`CmdJob`) with the same manager.
+- **Resource-Aware Scheduling**: Limit concurrency by global resources such as GPU count or license tokens.
+- **Operationally Friendly**: Built-in cancellation, retries, live logs, and callbacks for automation pipelines.
+
+[Job Manager Documentation](docs/job_manager/job_manager.md)
+
+### 5. Wave — Batch Workflow Orchestration with Live TUI
+A workflow layer built on top of Job Manager for declaring and observing long-running batch flows.
+
+- **Wave File Pattern**: Declare jobs, parsers, and hooks in a plain Python file. Run it with `rpk-wave run`.
+- **Live TUI**: A full-screen Textual interface with a job dashboard, per-job log/data/event panels, and a built-in command bar.
+- **Headless REPL**: For CI or terminal sessions where a TUI isn't wanted — full inspection and control commands via stdin.
+- **Hooks & Parsers**: React to log output, structured parsed data, elapsed time, or lifecycle events automatically.
+- **Job Events with Source Tracking**: `job.emit()` records named events; `source="system"` marks internal errors (parser/hook failures) for easy filtering in the TUI.
+- **Operational Control**: Pause/resume dispatch, gracefully stop jobs, force-cancel jobs, or target active jobs by tag from either the TUI command bar or headless REPL.
+- **Fast Job Inspection**: Open `show`, `logs`, `data`, or `events <job>` directly in JOB DETAIL, then switch between jobs with `[` / `]` or between running jobs with `{` / `}`.
+- **Intentional Cancellation Semantics**: User-cancelled jobs are reported as `cancelled` without turning the whole Wave run into a failed exit; real job failures and session timeouts still return a non-zero exit code.
+
+[Wave Documentation](docs/wave/wave.md)
+
+## Installation
+
+```bash
+# Core only (zero dependencies)
+pip install -e .
+
+# Install specific features
+pip install -e .[wave]   # Installs textual, prompt_toolkit, rich
+pip install -e .[excel]  # Installs openpyxl, xlrd, rapidfuzz
+pip install -e .[cfg]    # Installs networkx
+
+# Install everything
+pip install -e .[all]
+```
+
+## Testing
+
+Run tests using `pytest` from the root directory:
+```bash
+pytest tests/ -v
+```
+*(All tests require only `numpy` — no optional dependencies needed.)*

rpkbin-0.1.0/README.md

@@ -0,0 +1,78 @@
+# rpkbin — Core IC Design & Verification Utilities
+
+[![English](https://img.shields.io/badge/Language-English-blue.svg)](README.md)
+[![繁體中文](https://img.shields.io/badge/語言-繁體中文-blue.svg)](README_zh.md)
+
+`rpkbin` is a comprehensive toolkit providing essential data types and utilities for hardware design and verification flows.
+
+## Core Features
+
+### 1. MapBV — BitVector with Bidirectional Mapping
+MapBV allows you to define a hierarchy of bit-fields that stay synchronized automatically.
+- **Hierarchical Slicing**: Define a 32-bit register and slice it into named fields.
+- **Bidirectional Linking**: Use `concat` to build a new view from existing variables; updating the view updates the sources.
+- **Symbolic Evaluation**: Use `.eval()` to test "what-if" scenarios without changing actual values.
+
+[Learn more in MapBV Documentation](docs/mapbv/mapbv.md)
+
+### 2. NumBV — Bit-True Fixed-Point Arithmetic
+Bit-exact fixed-point simulation for DSP pipeline verification. Pure NumPy, no external dependency.
+- **Two-layer API**: Operator layer (`+`, `*`) for convenience; function layer (`nbv.add()`, `nbv.mul()`) for explicit pipeline staging.
+- **Five Rounding Modes**: `trunc`, `round`, `round_half_even` (convergent, Xilinx DSP48), `ceil`, `round_to_zero`.
+- **Unified Operations**: One `NumBV` class handles both scalar and array computations. Backed by NumPy by default, with an optional drop-in JAX backend for transparent XLA hardware acceleration.
+
+[Learn more in NumBV Documentation](docs/numbv/numbv.md)
+
+### 3. Excel Extractor — Template-Based Extraction
+Intelligently extract data from complex spreadsheets.
+- **Layout Description**: Define the "shape" of data instead of hardcoded coordinates.
+- **Fuzzy Matching**: Matches headers even with slight spelling variations.
+- **Merged Cell Support**: Correctly resolves values spanning across merged rows/cols.
+
+[Learn more in Excel Extractor Documentation](docs/excel_extractor/excel_extractor.md)
+
+### 4. Job Manager
+A practical, cross-platform job manager for running shell commands and Python callables safely in parallel.
+
+- **One API for Common Workloads**: Run local functions (`FuncJob`) and CLI tasks (`CmdJob`) with the same manager.
+- **Resource-Aware Scheduling**: Limit concurrency by global resources such as GPU count or license tokens.
+- **Operationally Friendly**: Built-in cancellation, retries, live logs, and callbacks for automation pipelines.
+
+[Job Manager Documentation](docs/job_manager/job_manager.md)
+
+### 5. Wave — Batch Workflow Orchestration with Live TUI
+A workflow layer built on top of Job Manager for declaring and observing long-running batch flows.
+
+- **Wave File Pattern**: Declare jobs, parsers, and hooks in a plain Python file. Run it with `rpk-wave run`.
+- **Live TUI**: A full-screen Textual interface with a job dashboard, per-job log/data/event panels, and a built-in command bar.
+- **Headless REPL**: For CI or terminal sessions where a TUI isn't wanted — full inspection and control commands via stdin.
+- **Hooks & Parsers**: React to log output, structured parsed data, elapsed time, or lifecycle events automatically.
+- **Job Events with Source Tracking**: `job.emit()` records named events; `source="system"` marks internal errors (parser/hook failures) for easy filtering in the TUI.
+- **Operational Control**: Pause/resume dispatch, gracefully stop jobs, force-cancel jobs, or target active jobs by tag from either the TUI command bar or headless REPL.
+- **Fast Job Inspection**: Open `show`, `logs`, `data`, or `events <job>` directly in JOB DETAIL, then switch between jobs with `[` / `]` or between running jobs with `{` / `}`.
+- **Intentional Cancellation Semantics**: User-cancelled jobs are reported as `cancelled` without turning the whole Wave run into a failed exit; real job failures and session timeouts still return a non-zero exit code.
+
+[Wave Documentation](docs/wave/wave.md)
+
+## Installation
+
+```bash
+# Core only (zero dependencies)
+pip install -e .
+
+# Install specific features
+pip install -e .[wave]   # Installs textual, prompt_toolkit, rich
+pip install -e .[excel]  # Installs openpyxl, xlrd, rapidfuzz
+pip install -e .[cfg]    # Installs networkx
+
+# Install everything
+pip install -e .[all]
+```
+
+## Testing
+
+Run tests using `pytest` from the root directory:
+```bash
+pytest tests/ -v
+```
+*(All tests require only `numpy` — no optional dependencies needed.)*

rpkbin-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rpkbin"
+version = "0.1.0"
+description = "Personal collection of small scripts and helpers for work."
+readme = "README.md"
+authors = [
+    { name = "redpigkiller", email = "hongrunlu511@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = [
+    "click>=8.3.1",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+]
+
+[project.optional-dependencies]
+cfg   = ["networkx>=3.6.1"]
+excel = ["openpyxl>=3.1.5", "xlrd>=2.0.2", "rapidfuzz>=3.14.3"]
+wave  = ["textual>=8.0.2", "prompt_toolkit>=3.0.52", "rich>=14.2.0"]
+all   = [
+    "networkx>=3.6.1",
+    "openpyxl>=3.1.5",
+    "xlrd>=2.0.2",
+    "rapidfuzz>=3.14.3",
+    "textual>=8.0.2",
+    "prompt_toolkit>=3.0.52",
+    "rich>=14.2.0"
+]
+
+[project.urls]
+Homepage   = "https://github.com/redpigkiller/rpkbin"
+Repository = "https://github.com/redpigkiller/rpkbin"
+
+[project.scripts]
+rpk-wave = "rpkbin.wave.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["rpkbin*"]
+
+[tool.setuptools]
+include-package-data = true
+

rpkbin-0.1.0/rpkbin/__init__.py

@@ -0,0 +1,5 @@
+"""rpkbin — A collection of utilities for IC design & verification."""
+
+__version__ = "0.1.0"
+
+__all__ = []

rpkbin-0.1.0/rpkbin/cfg/__init__.py

@@ -0,0 +1,85 @@
+"""rpkbin.cfg — Control Flow Graph IR, analysis, and domain-specific tools.
+
+Public API
+----------
+
+Core IR::
+
+    from rpkbin.cfg import CFG, BasicBlock
+    from rpkbin.cfg import Assignment, CallRef, OtherInsn, Insn
+    from rpkbin.cfg import NaturalLoop, Program
+
+Merging::
+
+    from rpkbin.cfg import merge_cfgs
+    from rpkbin.cfg import (
+        CFGMergeError, DuplicateLabelError, InsnConflictError,
+        EdgeConflictError, MetaConflictError,
+    )
+    merged = merge_cfgs(flow1, flow2, flow3)
+    merged.set_entry("IDLE")
+
+Interprocedural analysis::
+
+    from rpkbin.cfg.analysis import (
+        build_call_graph,
+        check_call_depth,
+        interprocedural_liveness,
+        FunctionSummary,
+        LivenessResult,
+    )
+
+FSM tools::
+
+    from rpkbin.cfg import fsm
+    fsm.find_dead_states(program)
+    fsm.find_sink_sccs(program)
+    fsm.check_conditions_complete(program)
+    layout = fsm.linearize(program)          # → FSMLayout
+
+MCU tools::
+
+    from rpkbin.cfg import mcu
+    mcu.find_dead_loops(program, exit_block="HALT")
+    mcu.dead_code_elimination(cfg)
+    layout = mcu.linearize(program)          # → MCULayout
+"""
+
+from .block import Assignment, CallRef, Insn, OtherInsn, BasicBlock
+from .cfg import (
+    CFG,
+    NaturalLoop,
+    CFGMergeError,
+    DuplicateLabelError,
+    InsnConflictError,
+    EdgeConflictError,
+    MetaConflictError,
+    merge_cfgs,
+)
+from .program import Program
+from . import fsm
+from . import mcu
+
+__all__ = [
+    # IR types
+    "BasicBlock",
+    "Assignment",
+    "CallRef",
+    "OtherInsn",
+    "Insn",
+    # CFG
+    "CFG",
+    "NaturalLoop",
+    # Merge
+    "merge_cfgs",
+    "CFGMergeError",
+    "DuplicateLabelError",
+    "InsnConflictError",
+    "EdgeConflictError",
+    "MetaConflictError",
+    # Program container
+    "Program",
+    # Domain-specific sub-modules
+    "fsm",
+    "mcu",
+]

rpkbin-0.1.0/rpkbin/cfg/analysis.py

@@ -0,0 +1,281 @@
+"""Interprocedural analysis utilities for CFG Programs.
+
+This module provides analysis functions that operate across multiple CFGs
+(i.e. across function boundaries) using the :class:`~rpkbin.cfg.program.Program`
+container.
+
+Key features
+------------
+* :func:`build_call_graph` — scans all ``CallRef`` instructions to construct
+  the program's call graph automatically; no manual registration needed.
+* :func:`check_call_depth` — verifies the call graph is a DAG and its depth
+  does not exceed a hardware limit.
+* :func:`interprocedural_liveness` — computes live-in / live-out sets for
+  every block in every function using a bottom-up summary-based approach.
+
+def/use derivation
+------------------
+``Assignment(lhs, rhs)``
+    def = {lhs},  use = set(rhs)
+
+``CallRef(callee)``
+    def = callee's FunctionSummary.defs
+    use = callee's FunctionSummary.uses
+
+``OtherInsn(defs, uses)``
+    def = defs,   use = uses
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import FrozenSet
+
+import networkx as nx
+
+from .block import Assignment, CallRef, Insn, OtherInsn
+from .cfg import CFG
+from .program import Program
+
+
+# ---------------------------------------------------------------------------
+# def/use helper
+# ---------------------------------------------------------------------------
+
+def _block_def_use(
+    insn: Insn,
+    summaries: dict[str, "FunctionSummary"],
+) -> tuple[set[str], set[str]]:
+    """Return ``(defs, uses)`` for a single instruction.
+
+    For :class:`CallRef`, the summary of the callee is used if available;
+    otherwise both sets are empty (safe but imprecise — run bottom-up to avoid
+    this case).
+    """
+    if isinstance(insn, Assignment):
+        return {insn.lhs}, set(insn.rhs)
+    if isinstance(insn, CallRef):
+        s = summaries.get(insn.callee)
+        if s is not None:
+            return set(s.defs), set(s.uses)
+        return set(), set()   # callee not analysed yet (cycle guard)
+    if isinstance(insn, OtherInsn):
+        return set(insn.defs), set(insn.uses)
+    return set(), set()      # unreachable with the current Insn union
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class FunctionSummary:
+    """Liveness summary exported from a single function.
+
+    Attributes:
+        defs: Variables the function *may* write on any execution path.
+        uses: Variables the function reads before (possibly) writing them —
+              i.e. the live-in set at the function's entry block.
+    """
+
+    defs: set[str] = field(default_factory=set)
+    uses: set[str] = field(default_factory=set)
+
+    def __repr__(self) -> str:
+        return f"FunctionSummary(defs={sorted(self.defs)}, uses={sorted(self.uses)})"
+
+
+@dataclass
+class LivenessResult:
+    """Per-block liveness sets for a single function.
+
+    Attributes:
+        live_in:  Mapping from block id to the set of variables live at the
+                  *entry* of that block.
+        live_out: Mapping from block id to the set of variables live at the
+                  *exit* of that block.
+    """
+
+    live_in:  dict[str, FrozenSet[str]] = field(default_factory=dict)
+    live_out: dict[str, FrozenSet[str]] = field(default_factory=dict)
+
+    def is_live_at_entry(self, block_id: str, var: str) -> bool:
+        """Return ``True`` if *var* is live at the entry of *block_id*."""
+        return var in self.live_in.get(block_id, frozenset())
+
+    def is_live_at_exit(self, block_id: str, var: str) -> bool:
+        """Return ``True`` if *var* is live at the exit of *block_id*."""
+        return var in self.live_out.get(block_id, frozenset())
+
+
+# ---------------------------------------------------------------------------
+# Call graph
+# ---------------------------------------------------------------------------
+
+def build_call_graph(program: Program) -> nx.DiGraph:
+    """Build a directed call graph by scanning ``CallRef`` instructions.
+
+    Each node in the returned graph is a function name (a key in
+    ``program.cfgs``).  An edge ``(caller, callee)`` is added for every
+    :class:`~rpkbin.cfg.block.CallRef` found in *caller*'s blocks.
+
+    Returns:
+        A :class:`networkx.DiGraph` with one node per function.
+
+    Raises:
+        KeyError: If a ``CallRef.callee`` does not exist in ``program.cfgs``.
+    """
+    cg: nx.DiGraph = nx.DiGraph()
+    cg.add_nodes_from(program.cfgs.keys())
+
+    for fn_name, cfg in program.cfgs.items():
+        for bb in cfg.blocks:
+            for insn in bb.insns:
+                if isinstance(insn, CallRef):
+                    if insn.callee not in program.cfgs:
+                        raise KeyError(
+                            f"CallRef to unknown function {insn.callee!r} "
+                            f"in block {bb.id!r} of function {fn_name!r}."
+                        )
+                    cg.add_edge(fn_name, insn.callee)
+
+    return cg
+
+
+def check_call_depth(program: Program, max_depth: int | None = None) -> int:
+    """Verify the call graph is acyclic and within the depth limit.
+
+    Args:
+        program:   The program to analyse.
+        max_depth: Maximum allowed call-stack depth.  If ``None``, only the
+                   actual depth is returned without raising.
+
+    Returns:
+        The actual maximum call depth (longest path length in the call graph).
+
+    Raises:
+        ValueError: If the call graph contains a cycle (recursive call).
+        ValueError: If the actual depth exceeds *max_depth*.
+    """
+    cg = build_call_graph(program)
+    try:
+        depth: int = nx.dag_longest_path_length(cg)
+    except nx.NetworkXUnfeasible:
+        raise ValueError(
+            "Call graph contains a cycle — recursive calls are not allowed."
+        )
+    if max_depth is not None and depth > max_depth:
+        raise ValueError(
+            f"Call depth {depth} exceeds the allowed maximum of {max_depth}."
+        )
+    return depth
+
+
+# ---------------------------------------------------------------------------
+# Intraprocedural liveness (single CFG)
+# ---------------------------------------------------------------------------
+
+def _intraprocedural_liveness(
+    cfg: CFG,
+    summaries: dict[str, FunctionSummary],
+) -> tuple[LivenessResult, FunctionSummary]:
+    """Run liveness analysis on a single CFG using pre-computed summaries.
+
+    Returns the per-block :class:`LivenessResult` and the derived
+    :class:`FunctionSummary` for this function.
+    """
+    g = cfg._graph
+
+    # Compute per-block def/use sets (in sequential instruction order)
+    block_def: dict[str, set[str]] = {}
+    block_use: dict[str, set[str]] = {}
+    for bb in cfg.blocks:
+        blk_def: set[str] = set()
+        blk_use: set[str] = set()
+        for insn in bb.insns:
+            d, u = _block_def_use(insn, summaries)
+            # A variable used before it is defined in this block is live-in
+            blk_use |= u - blk_def
+            blk_def |= d
+        block_def[bb.id] = blk_def
+        block_use[bb.id] = blk_use
+
+    # Initialize live sets
+    live_in:  dict[str, FrozenSet[str]] = {bb.id: frozenset() for bb in cfg.blocks}
+    live_out: dict[str, FrozenSet[str]] = {bb.id: frozenset() for bb in cfg.blocks}
+
+    # Iterative worklist (backward)
+    worklist: set[str] = {bb.id for bb in cfg.blocks}
+    while worklist:
+        bid = worklist.pop()
+
+        new_out: set[str] = set()
+        for succ in g.successors(bid):
+            new_out |= live_in[succ]
+        new_out_f = frozenset(new_out)
+
+        new_in = frozenset(block_use[bid] | (new_out - block_def[bid]))
+
+        if new_out_f != live_out[bid] or new_in != live_in[bid]:
+            live_out[bid] = new_out_f
+            live_in[bid]  = new_in
+            for pred in g.predecessors(bid):
+                worklist.add(pred)
+
+    result = LivenessResult(live_in=live_in, live_out=live_out)
+
+    # Build summary: defs = union of all block defs; uses = live_in at entry
+    all_defs: set[str] = set()
+    for d in block_def.values():
+        all_defs |= d
+    entry_uses: set[str] = set(live_in[cfg._entry]) if cfg._entry else set()
+    summary = FunctionSummary(defs=all_defs, uses=entry_uses)
+
+    return result, summary
+
+
+# ---------------------------------------------------------------------------
+# Interprocedural liveness
+# ---------------------------------------------------------------------------
+
+def interprocedural_liveness(
+    program: Program,
+) -> dict[str, LivenessResult]:
+    """Bottom-up interprocedural liveness analysis.
+
+    Analyses each function in reverse topological order of the call graph
+    (leaf functions first) so that every callee's :class:`FunctionSummary`
+    is available before its callers are analysed.
+
+    The call graph must be a DAG (no recursion).  Use :func:`check_call_depth`
+    to verify this beforehand if needed.
+
+    Args:
+        program: The program to analyse.
+
+    Returns:
+        A mapping from function name to its :class:`LivenessResult`.
+
+    Raises:
+        ValueError: If the call graph contains a cycle.
+    """
+    cg = build_call_graph(program)
+
+    # Topological order: process leaves (callees) before callers
+    try:
+        topo_order: list[str] = list(nx.topological_sort(cg))
+    except nx.NetworkXUnfeasible:
+        raise ValueError(
+            "Call graph contains a cycle — recursive calls are not allowed."
+        )
+
+    summaries: dict[str, FunctionSummary] = {}
+    results:   dict[str, LivenessResult]  = {}
+
+    for fn_name in reversed(topo_order):   # reversed → leaves first
+        cfg = program.cfgs[fn_name]
+        result, summary = _intraprocedural_liveness(cfg, summaries)
+        results[fn_name]   = result
+        summaries[fn_name] = summary
+
+    return results