torch-abi-audit 0.0.1__tar.gz

torch_abi_audit-0.0.1/.gitignore

@@ -0,0 +1,34 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+src/torch_abi_audit/_version.py
+
+# Caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.pyrefly/
+.ruff_cache/
+.mypy_cache/
+
+# Environments
+.venv/
+.python-version.local
+.pixi/
+
+# Editor
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Docs build
+docs/site/
+docs/.cache/
+
+# Scratch
+*.so
+*.dylib
+*.pyd

torch_abi_audit-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 torch-abi-audit contributors
+
+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.

torch_abi_audit-0.0.1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: torch-abi-audit
+Version: 0.0.1
+Summary: Audit Python extensions for PyTorch (and CPython) Stable ABI compliance.
+Project-URL: Homepage, https://github.com/Quansight/torch-abi-audit
+Project-URL: Documentation, https://quansight.github.io/torch-abi-audit/
+Project-URL: Issues, https://github.com/Quansight/torch-abi-audit/issues
+Author-email: Ralf Gommers <ralf.gommers@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: abi,cpython,extension-modules,limited-api,pytorch,stable-abi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Software Distribution
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: abi3info
+Requires-Dist: pycxxfilt
+Description-Content-Type: text/markdown
+
+# torch-abi-audit
+
+Audit Python extension modules for compliance with the
+[PyTorch Stable ABI](https://docs.pytorch.org/docs/main/notes/libtorch_stable_abi.html)
+(`aoti_torch_*` C shim and `torch::stable::*` / `torch::headeronly::*` C++
+wrappers, introduced in PyTorch 2.9). Walks every `.so` shipped in a
+package — both Python extension modules and bundled internal libraries —
+and reports which stick to the stable surface and which reach into
+`at::` / `c10::` / `torch::jit::` internals.
+
+As a side benefit the same symbol-table walk also reports
+[CPython Stable ABI](https://docs.python.org/3/c-api/stable.html) (PEP 384)
+compliance, since the data is right there.
+
+📖 **Documentation:** <https://quansight.github.io/torch-abi-audit/>
+
+## Install
+
+```bash
+pip install torch-abi-audit
+```
+
+Linux and macOS only for now (Windows requires `dumpbin` support — not yet implemented).
+
+## CLI usage
+
+```bash
+# Inspect an installed PyTorch ecosystem package by import name
+torch-abi-audit torchaudio
+
+# Inspect a path to an installed package or a single .so
+torch-abi-audit /path/to/site-packages/somepkg
+
+# Inspect every package in the current environment's site-packages
+torch-abi-audit --env
+
+# Inspect a specific site-packages directory
+torch-abi-audit --site-packages /opt/venv/lib/python3.12/site-packages
+
+# JSON output for tooling
+torch-abi-audit --env --json | jq '.packages[] | select(.torch.uses_torch)'
+```
+
+## Example output
+
+Run against the three packages tracked by `scripts/check_real_world.py`
+(captured against torch 2.11.0 / torchaudio 2.11.0 / torchcodec 0.11.1):
+
+```text
+Package: torchaudio
+  Root: <venv>/lib/python3.11/site-packages/torchaudio
+  Torch ABI:   STABLE
+  CPython ABI: n/a
+  Extensions:  0
+  Bundled libs: 3
+  -- bundled libs --
+    [STABLE  ] [abi3-tagged-no-capi   ] lib/_torchaudio.abi3.so  (stable_shim=6, unstable=0)
+    [STABLE  ] [abi3-tagged-no-capi   ] lib/libtorchaudio.abi3.so  (stable_shim=80, unstable=0)
+    [STABLE  ] [abi3-tagged-no-capi   ] lib/torchaudio_prefixctc.abi3.so  (stable_shim=62, unstable=0)
+
+Package: torch
+  Root: <venv>/lib/python3.11/site-packages/torch
+  Torch ABI:   UNSTABLE
+  CPython ABI: no
+  Extensions:  1
+  Bundled libs: 13
+  -- extensions --
+    [NO-TORCH] [not-abi3              ] _C.cpython-311-aarch64-linux-gnu.so
+  -- bundled libs --
+    [UNSTABLE] [not-abi3              ] lib/libc10_cuda.so  (stable_shim=0, unstable=44)
+    [UNSTABLE] [not-abi3              ] lib/libtorch_cpu.so  (stable_shim=0, unstable=327)
+    [UNSTABLE] [not-abi3              ] lib/libtorch_cuda.so  (stable_shim=0, unstable=2515)
+    [UNSTABLE] [uses-private-api      ] lib/libtorch_python.so  (stable_shim=0, unstable=5085)
+    ... (9 more, mostly NO-TORCH or UNSTABLE)
+
+Package: torchcodec
+  Root: <venv>/lib/python3.11/site-packages/torchcodec
+  Torch ABI:   UNSTABLE
+  CPython ABI: no
+  Extensions:  5
+  Bundled libs: 10
+  -- extensions --
+    [NO-TORCH] [uses-private-api      ] libtorchcodec_pybind_ops4.so
+    ... (4 similar)
+  -- bundled libs --
+    [UNSTABLE] [not-abi3              ] libtorchcodec_core4.so  (stable_shim=64, unstable=4)
+    ... (4 similar)
+    [STABLE  ] [uses-private-api      ] libtorchcodec_custom_ops4.so  (stable_shim=68, unstable=0)
+    ... (4 similar)
+```
+
+`torchaudio` is reported as stable because every compiled library it ships
+links against `aoti_torch_*` and `torch::stable::*` only. `torch` lands on
+`UNSTABLE` because its bundled `libtorch_python.so`, `libtorch_cpu.so`, etc.
+naturally reference internal `at::` / `c10::` namespaces (torch *implements*
+those internals, after all). `torchcodec` is mid-migration: the
+`custom_ops*` libs already use the stable surface, but `core*` libs still
+link a handful of `c10::` symbols.
+
+## Python API
+
+```python
+from torch_abi_audit import (
+    inspect_extension,
+    inspect_package,
+    inspect_site_packages,
+)
+
+report = inspect_package("torchaudio")
+print(report.torch_verdict)             # "torch-stable" | "torch-unstable" | "no-torch"
+
+# `extensions` holds Python extension modules; `bundled_libs` holds the
+# rest of the compiled .so files (libtorch_python.so, STABLE_TORCH_LIBRARY
+# plugins, etc.). Both contribute to the verdict.
+for lib in (*report.extensions, *report.bundled_libs):
+    print(lib.path, lib.torch.stable, lib.cpython.compliant)
+```
+
+## Development
+
+```bash
+uv sync                          # install + dev dependencies in .venv
+uv run pytest                    # run tests
+uv run pyrefly check             # type-check
+uv run zensical serve docs/      # local docs server
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

torch_abi_audit-0.0.1/README.md

@@ -0,0 +1,130 @@
+# torch-abi-audit
+
+Audit Python extension modules for compliance with the
+[PyTorch Stable ABI](https://docs.pytorch.org/docs/main/notes/libtorch_stable_abi.html)
+(`aoti_torch_*` C shim and `torch::stable::*` / `torch::headeronly::*` C++
+wrappers, introduced in PyTorch 2.9). Walks every `.so` shipped in a
+package — both Python extension modules and bundled internal libraries —
+and reports which stick to the stable surface and which reach into
+`at::` / `c10::` / `torch::jit::` internals.
+
+As a side benefit the same symbol-table walk also reports
+[CPython Stable ABI](https://docs.python.org/3/c-api/stable.html) (PEP 384)
+compliance, since the data is right there.
+
+📖 **Documentation:** <https://quansight.github.io/torch-abi-audit/>
+
+## Install
+
+```bash
+pip install torch-abi-audit
+```
+
+Linux and macOS only for now (Windows requires `dumpbin` support — not yet implemented).
+
+## CLI usage
+
+```bash
+# Inspect an installed PyTorch ecosystem package by import name
+torch-abi-audit torchaudio
+
+# Inspect a path to an installed package or a single .so
+torch-abi-audit /path/to/site-packages/somepkg
+
+# Inspect every package in the current environment's site-packages
+torch-abi-audit --env
+
+# Inspect a specific site-packages directory
+torch-abi-audit --site-packages /opt/venv/lib/python3.12/site-packages
+
+# JSON output for tooling
+torch-abi-audit --env --json | jq '.packages[] | select(.torch.uses_torch)'
+```
+
+## Example output
+
+Run against the three packages tracked by `scripts/check_real_world.py`
+(captured against torch 2.11.0 / torchaudio 2.11.0 / torchcodec 0.11.1):
+
+```text
+Package: torchaudio
+  Root: <venv>/lib/python3.11/site-packages/torchaudio
+  Torch ABI:   STABLE
+  CPython ABI: n/a
+  Extensions:  0
+  Bundled libs: 3
+  -- bundled libs --
+    [STABLE  ] [abi3-tagged-no-capi   ] lib/_torchaudio.abi3.so  (stable_shim=6, unstable=0)
+    [STABLE  ] [abi3-tagged-no-capi   ] lib/libtorchaudio.abi3.so  (stable_shim=80, unstable=0)
+    [STABLE  ] [abi3-tagged-no-capi   ] lib/torchaudio_prefixctc.abi3.so  (stable_shim=62, unstable=0)
+
+Package: torch
+  Root: <venv>/lib/python3.11/site-packages/torch
+  Torch ABI:   UNSTABLE
+  CPython ABI: no
+  Extensions:  1
+  Bundled libs: 13
+  -- extensions --
+    [NO-TORCH] [not-abi3              ] _C.cpython-311-aarch64-linux-gnu.so
+  -- bundled libs --
+    [UNSTABLE] [not-abi3              ] lib/libc10_cuda.so  (stable_shim=0, unstable=44)
+    [UNSTABLE] [not-abi3              ] lib/libtorch_cpu.so  (stable_shim=0, unstable=327)
+    [UNSTABLE] [not-abi3              ] lib/libtorch_cuda.so  (stable_shim=0, unstable=2515)
+    [UNSTABLE] [uses-private-api      ] lib/libtorch_python.so  (stable_shim=0, unstable=5085)
+    ... (9 more, mostly NO-TORCH or UNSTABLE)
+
+Package: torchcodec
+  Root: <venv>/lib/python3.11/site-packages/torchcodec
+  Torch ABI:   UNSTABLE
+  CPython ABI: no
+  Extensions:  5
+  Bundled libs: 10
+  -- extensions --
+    [NO-TORCH] [uses-private-api      ] libtorchcodec_pybind_ops4.so
+    ... (4 similar)
+  -- bundled libs --
+    [UNSTABLE] [not-abi3              ] libtorchcodec_core4.so  (stable_shim=64, unstable=4)
+    ... (4 similar)
+    [STABLE  ] [uses-private-api      ] libtorchcodec_custom_ops4.so  (stable_shim=68, unstable=0)
+    ... (4 similar)
+```
+
+`torchaudio` is reported as stable because every compiled library it ships
+links against `aoti_torch_*` and `torch::stable::*` only. `torch` lands on
+`UNSTABLE` because its bundled `libtorch_python.so`, `libtorch_cpu.so`, etc.
+naturally reference internal `at::` / `c10::` namespaces (torch *implements*
+those internals, after all). `torchcodec` is mid-migration: the
+`custom_ops*` libs already use the stable surface, but `core*` libs still
+link a handful of `c10::` symbols.
+
+## Python API
+
+```python
+from torch_abi_audit import (
+    inspect_extension,
+    inspect_package,
+    inspect_site_packages,
+)
+
+report = inspect_package("torchaudio")
+print(report.torch_verdict)             # "torch-stable" | "torch-unstable" | "no-torch"
+
+# `extensions` holds Python extension modules; `bundled_libs` holds the
+# rest of the compiled .so files (libtorch_python.so, STABLE_TORCH_LIBRARY
+# plugins, etc.). Both contribute to the verdict.
+for lib in (*report.extensions, *report.bundled_libs):
+    print(lib.path, lib.torch.stable, lib.cpython.compliant)
+```
+
+## Development
+
+```bash
+uv sync                          # install + dev dependencies in .venv
+uv run pytest                    # run tests
+uv run pyrefly check             # type-check
+uv run zensical serve docs/      # local docs server
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

torch_abi_audit-0.0.1/docs/docs/api.md

@@ -0,0 +1,107 @@
+---
+icon: lucide/code-2
+---
+
+# Python API
+
+The package exposes a small typed API for programmatic use.
+
+## Inspection entry points
+
+```python
+from torch_abi_audit import (
+    inspect_extension,
+    inspect_package,
+    inspect_site_packages,
+)
+```
+
+### `inspect_extension(path) -> ExtensionReport`
+
+Inspect a single extension module file. Returns an `ExtensionReport` even for
+unreadable files (the `error` field carries the message).
+
+### `inspect_package(name_or_path) -> PackageReport`
+
+Inspect an installed package. `name_or_path` is either:
+
+- An import name string (e.g. `"torchaudio"`) — resolved via the import system.
+- A `Path` (or path-string with a separator) — treated as a file or directory.
+
+The returned `PackageReport` separates Python extension modules
+(`.extensions`) from bundled internal libraries (`.bundled_libs`); both
+contribute to the torch ABI verdict.
+
+### `inspect_site_packages(directory=None) -> EnvironmentReport`
+
+Walk a site-packages directory, returning one `PackageReport` per package that
+contains compiled libraries — extension modules, bundled libraries, or both.
+`directory=None` defaults to the active interpreter's `purelib`.
+
+## Result types
+
+All result dataclasses are frozen, slotted, and fully typed.
+
+```python
+@dataclass(frozen=True, slots=True)
+class CPythonABIVerdict:
+    intent: bool         # filename carries an `abi3` tag
+    compliant: bool      # all Py*/_Py* symbols are in the stable set
+    violations: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TorchABIVerdict:
+    uses_torch: bool
+    stable: bool
+    unstable_symbols: tuple[str, ...]
+    stable_shim_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionReport:
+    path: Path
+    cpython: CPythonABIVerdict
+    torch: TorchABIVerdict
+    error: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class PackageReport:
+    name: str
+    root: Path
+    extensions: tuple[ExtensionReport, ...]      # PyInit_*-bearing .so files
+    bundled_libs: tuple[ExtensionReport, ...]    # other compiled .so files in the package
+    error: str | None
+    # @property torch_verdict   -> "torch-stable" | "torch-unstable" | "no-torch" | "error"
+    # @property cpython_verdict -> "abi3-compliant" | "not-abi3" | "mixed" | "no-extensions"
+
+
+@dataclass(frozen=True, slots=True)
+class EnvironmentReport:
+    site_packages: Path
+    packages: tuple[PackageReport, ...]
+```
+
+## Formatters
+
+```python
+from torch_abi_audit.report import (
+    format_json,
+    format_package_table,
+    format_environment_table,
+)
+```
+
+`format_json` accepts any of the three top-level report types and emits
+indented JSON. The table formatters are package- and environment-specific.
+
+## Example
+
+```python
+from torch_abi_audit import inspect_site_packages
+
+env = inspect_site_packages()
+unstable = [p.name for p in env.packages if p.torch_verdict == "torch-unstable"]
+print("Packages using unstable libtorch ABI:", unstable)
+```

torch_abi_audit-0.0.1/docs/docs/cli.md

@@ -0,0 +1,200 @@
+---
+icon: lucide/terminal
+---
+
+# CLI reference
+
+```text
+usage: torch-abi-audit [-h] [--version] [--env | --site-packages PATH]
+                       [--json] [--all] [-v]
+                       [TARGET ...]
+```
+
+## Modes
+
+The CLI selects exactly one inspection mode:
+
+| Mode | Flag(s) | What it inspects |
+|------|---------|------------------|
+| Targets | `TARGET ...` (positional) | One or more import names or filesystem paths. |
+| Active env | `--env` | Every package in the running interpreter's site-packages. |
+| Specific env | `--site-packages PATH` | Every package under the given site-packages directory. |
+
+A `TARGET` can be:
+
+- An importable name like `torchvision` — resolved via `importlib.util.find_spec`.
+- A path to an installed package directory (recursive scan).
+- A path to a single `.so` / `.pyd` / `.dylib` file.
+
+## Output
+
+By default the CLI prints a human-readable table.
+
+- `--json` switches to JSON. With multiple targets the output is wrapped
+  in an `EnvironmentReport`-shaped envelope so the JSON shape is consistent.
+- `--verbose` (`-v`) shows the offending symbol list for unstable / non-compliant
+  extensions.
+- `--all` makes env-scan output include packages with no torch use (hidden
+  by default to keep the table focused on potentially-problematic packages).
+
+## Output examples
+
+All three samples below were captured against `torch 2.11.0`,
+`torchaudio 2.11.0`, and `torchcodec 0.11.1` on Linux aarch64.
+
+### Default table — multi-package
+
+`torch-abi-audit torchaudio torch torchcodec`:
+
+```text
+Package: torchaudio
+  Root: <venv>/lib/python3.11/site-packages/torchaudio
+  Torch ABI:   STABLE
+  CPython ABI: n/a
+  Extensions:  0
+  Bundled libs: 3
+  -- bundled libs --
+    [STABLE  ] [abi3-tagged-no-capi   ] lib/_torchaudio.abi3.so  (stable_shim=6, unstable=0)
+    [STABLE  ] [abi3-tagged-no-capi   ] lib/libtorchaudio.abi3.so  (stable_shim=80, unstable=0)
+    [STABLE  ] [abi3-tagged-no-capi   ] lib/torchaudio_prefixctc.abi3.so  (stable_shim=62, unstable=0)
+
+Package: torch
+  Root: <venv>/lib/python3.11/site-packages/torch
+  Torch ABI:   UNSTABLE
+  CPython ABI: no
+  Extensions:  1
+  Bundled libs: 13
+  -- extensions --
+    [NO-TORCH] [not-abi3              ] _C.cpython-311-aarch64-linux-gnu.so
+  -- bundled libs --
+    [NO-TORCH] [not-abi3              ] lib/libarm_compute.so
+    [NO-TORCH] [not-abi3              ] lib/libarm_compute_graph.so
+    [NO-TORCH] [not-abi3              ] lib/libc10.so
+    [UNSTABLE] [not-abi3              ] lib/libc10_cuda.so  (stable_shim=0, unstable=44)
+    [NO-TORCH] [not-abi3              ] lib/libcaffe2_nvrtc.so
+    [UNSTABLE] [not-abi3              ] lib/libshm.so  (stable_shim=0, unstable=9)
+    [NO-TORCH] [not-abi3              ] lib/libtorch.so
+    [UNSTABLE] [not-abi3              ] lib/libtorch_cpu.so  (stable_shim=0, unstable=327)
+    [UNSTABLE] [not-abi3              ] lib/libtorch_cuda.so  (stable_shim=0, unstable=2515)
+    [UNSTABLE] [not-abi3              ] lib/libtorch_cuda_linalg.so  (stable_shim=0, unstable=143)
+    [NO-TORCH] [not-abi3              ] lib/libtorch_global_deps.so
+    [UNSTABLE] [not-abi3              ] lib/libtorch_nvshmem.so  (stable_shim=0, unstable=66)
+    [UNSTABLE] [uses-private-api      ] lib/libtorch_python.so  (stable_shim=0, unstable=5085)
+
+Package: torchcodec
+  Root: <venv>/lib/python3.11/site-packages/torchcodec
+  Torch ABI:   UNSTABLE
+  CPython ABI: no
+  Extensions:  5
+  Bundled libs: 10
+  -- extensions --
+    [NO-TORCH] [uses-private-api      ] libtorchcodec_pybind_ops4.so
+    [NO-TORCH] [uses-private-api      ] libtorchcodec_pybind_ops5.so
+    [NO-TORCH] [uses-private-api      ] libtorchcodec_pybind_ops6.so
+    [NO-TORCH] [uses-private-api      ] libtorchcodec_pybind_ops7.so
+    [NO-TORCH] [uses-private-api      ] libtorchcodec_pybind_ops8.so
+  -- bundled libs --
+    [UNSTABLE] [not-abi3              ] libtorchcodec_core4.so  (stable_shim=64, unstable=4)
+    [UNSTABLE] [not-abi3              ] libtorchcodec_core5.so  (stable_shim=64, unstable=4)
+    [UNSTABLE] [not-abi3              ] libtorchcodec_core6.so  (stable_shim=64, unstable=4)
+    [UNSTABLE] [not-abi3              ] libtorchcodec_core7.so  (stable_shim=64, unstable=4)
+    [UNSTABLE] [not-abi3              ] libtorchcodec_core8.so  (stable_shim=64, unstable=4)
+    [STABLE  ] [uses-private-api      ] libtorchcodec_custom_ops4.so  (stable_shim=68, unstable=0)
+    [STABLE  ] [uses-private-api      ] libtorchcodec_custom_ops5.so  (stable_shim=68, unstable=0)
+    [STABLE  ] [uses-private-api      ] libtorchcodec_custom_ops6.so  (stable_shim=68, unstable=0)
+    [STABLE  ] [uses-private-api      ] libtorchcodec_custom_ops7.so  (stable_shim=68, unstable=0)
+    [STABLE  ] [uses-private-api      ] libtorchcodec_custom_ops8.so  (stable_shim=68, unstable=0)
+```
+
+The per-row labels:
+
+| Torch | CPython | Meaning |
+|---|---|---|
+| `STABLE` / `UNSTABLE` / `NO-TORCH` | — | Per-library torch verdict. |
+| — | `abi3-ok` | Filename tagged abi3 *and* every Py\* symbol is in the limited API. |
+| — | `abi3-tagged-violations` | Filename tagged abi3 but the file references private CPython symbols. |
+| — | `abi3-tagged-no-capi` | Filename tagged abi3, file has no CPython API references at all (e.g. a STABLE_TORCH_LIBRARY plugin). |
+| — | `uses-private-api` | Not abi3-tagged, references private CPython symbols. |
+| — | `not-abi3` | Not abi3-tagged, no Py\* references. |
+
+### Verbose excerpt — `--verbose` surfaces offending symbols
+
+`torch-abi-audit torch -v` (first 28 lines):
+
+```text
+Package: torch
+  Root: <venv>/lib/python3.11/site-packages/torch
+  Torch ABI:   UNSTABLE
+  CPython ABI: no
+  Extensions:  1
+  Bundled libs: 13
+  -- extensions --
+    [NO-TORCH] [not-abi3              ] _C.cpython-311-aarch64-linux-gnu.so
+  -- bundled libs --
+    [NO-TORCH] [not-abi3              ] lib/libarm_compute.so
+    [NO-TORCH] [not-abi3              ] lib/libarm_compute_graph.so
+    [NO-TORCH] [not-abi3              ] lib/libc10.so
+    [UNSTABLE] [not-abi3              ] lib/libc10_cuda.so  (stable_shim=0, unstable=44)
+        torch unstable: c10::SetAllocator(c10::DeviceType, c10::Allocator*, unsigned char)
+        torch unstable: c10::WarningUtils::get_warnAlways()
+        torch unstable: c10::MessageLogger::stream[abi:cxx11]()
+        torch unstable: c10::MessageLogger::MessageLogger(c10::SourceLocation, int, bool)
+        torch unstable: c10::MessageLogger::~MessageLogger()
+        torch unstable: c10::DeviceAllocator::DeviceAllocator()
+        torch unstable: c10::DeviceAllocator::~DeviceAllocator()
+        torch unstable: c10::SmallVectorBase<unsigned int>::grow_pod(void const*, unsigned long, unsigned long)
+        torch unstable: c10::CachingAllocator::AcceleratorAllocatorConfig::roundup_power2_divisions(unsigned long)
+        torch unstable: c10::CachingAllocator::AcceleratorAllocatorConfig::instance()
+        torch unstable: c10::reportMemoryUsageToProfiler(void*, long, unsigned long, unsigned long, c10::Device)
+        torch unstable: c10::reportOutOfMemoryToProfiler(long, unsigned long, unsigned long, c10::Device)
+        torch unstable: c10::ApproximateClockToUnixTimeConverter::makeConverter()
+        torch unstable: c10::ApproximateClockToUnixTimeConverter::ApproximateClockToUnixTimeConverter()
+        torch unstable: c10::impl::DeviceGuardImplRegistrar::DeviceGuardImplRegistrar(...)
+        ... 29 more
+```
+
+The first 15 unstable symbols per library are listed inline; anything past
+that becomes a `... N more` summary so the table doesn't blow up.
+
+### JSON shape — `--json`
+
+`torch-abi-audit torchaudio --json`:
+
+```json
+{
+  "name": "torchaudio",
+  "root": "<venv>/lib/python3.11/site-packages/torchaudio",
+  "extensions": [],
+  "bundled_libs": [
+    {
+      "path": "<venv>/.../torchaudio/lib/_torchaudio.abi3.so",
+      "cpython": { "intent": true, "compliant": false, "violations": [] },
+      "torch": {
+        "uses_torch": true,
+        "stable": true,
+        "unstable_symbols": [],
+        "stable_shim_count": 6
+      },
+      "error": null
+    },
+    { "path": "<venv>/.../torchaudio/lib/libtorchaudio.abi3.so", "...": "..." },
+    { "path": "<venv>/.../torchaudio/lib/torchaudio_prefixctc.abi3.so", "...": "..." }
+  ],
+  "error": null
+}
+```
+
+The verdict roll-ups (`torch_verdict`, `cpython_verdict`) are `@property`
+on `PackageReport`, so they're computed on access and don't appear in the
+JSON dump. Compute them yourself by looking at the `extensions` and
+`bundled_libs` lists, or use the Python API.
+
+## Exit codes
+
+The CLI reports verdicts via stdout / JSON; it returns:
+
+- `0` on inspection success regardless of verdict.
+- `2` on operational errors (missing `nm`, unknown import name, unreadable path).
+
+This makes the tool safe to run interactively without `set -e` surprises.
+For CI gating, parse the JSON output.