leakscope 0.2.0rc1__tar.gz

leakscope-0.2.0rc1/LICENSE

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

leakscope-0.2.0rc1/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: leakscope
+Version: 0.2.0rc1
+Summary: LeakScope Python collector and CLI; native executables and web assets are installed separately
+License-Expression: MIT
+Project-URL: Repository, https://github.com/polsala/LeakScope
+Project-URL: Documentation, https://github.com/polsala/LeakScope/tree/main/docs
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi==0.143.1
+Requires-Dist: uvicorn==0.34.3
+Requires-Dist: pydantic==2.11.7
+Requires-Dist: sqlalchemy==2.0.41
+Requires-Dist: alembic==1.16.2
+Requires-Dist: zstandard==0.23.0
+Requires-Dist: protobuf==6.33.5
+Requires-Dist: PyYAML==6.0.2
+Requires-Dist: httpx==0.28.1
+Requires-Dist: starlette==1.8.0
+Dynamic: license-file
+
+# LeakScope Python component
+
+This distribution installs the Python collector, FastAPI backend, CLI and Alembic
+migrations. It requires Python 3.11 or newer. It does **not** bundle the Rust sensor,
+Rust analyzer, web assets or CPython 2.7 compatibility extension, and performs no
+executable downloads during installation.
+
+`leakscope --version`, offline capture inspection and database backup work through
+this package. Recording and native allocation analysis require separately installed
+matching `leakscope-sensor` and `leakscope-analyzer` executables on PATH (or the
+explicit LEAKSCOPE_SENSOR_BIN / LEAKSCOPE_ANALYZER_BIN settings). Serving the UI
+requires LEAKSCOPE_WEB_DIST pointing to matching built assets. For the complete
+application, use the verified offline standalone tarball or Debian distribution
+from https://github.com/polsala/LeakScope/releases.
+
+Engineering previews do not claim production readiness. Native tracing is opt-in;
+metrics remain available without BPF. Python 2.7 is used only by the separate
+compatibility agent and optional laboratory interpreter.

leakscope-0.2.0rc1/README.md

@@ -0,0 +1,149 @@
+> Phase 5 engineering preview: offline bundled-runtime packages, reliable startup,
+> genuine six-way Python 2 ABI tests and SQLite recovery are available. Production
+> promotion remains blocked pending the documented kernel, performance, deployment,
+> long-duration and security gates. See [installation](docs/installation/release-candidate.md)
+> and [executed evidence](docs/development/phase5-validation.md).
+
+# LeakScope
+
+Local memory investigations for long-running Linux processes, with a cooperative
+CPython 2.7.18 agent. The interface defaults to Catalan and includes Spanish and English.
+
+**0.1.0 is an engineering preview, not a complete Memray replacement or a production-certified release.**
+Observe metrics work without tracing privileges. Optional native profiling now records
+actual malloc/calloc/realloc/free events through Aya, streams LSCAP captures,
+reconstructs allocations, and displays native flamegraphs, call trees and reports.
+The real Python 2.7/kernel/browser path has been exercised. Cooperative operation/function boundaries now correlate native allocations with Python
+context, while a separately instrumented Lab interpreter can record verified executing
+Python allocation lines. Standard Deep evidence remains temporal. Lab remains experimental. See the [evidence matrix](docs/implementation-status.md).
+
+## Start locally
+
+Requires Linux x86_64, Python 3.11+ (commands default to 3.12), Rust 1.94.1,
+Node 24.13.0 with Corepack, Clang with its BPF target, a C compiler and network access for the initial setup.
+Python 2 is needed only for the compatibility agent and target fixtures.
+
+```bash
+make setup
+make build
+.venv/bin/leakscope serve --listen 127.0.0.1:7831
+# In a separate terminal, read the generated local credential:
+cat .data/admin.token
+```
+
+Open **http://127.0.0.1:7831** and paste the credential. Run as the same UID as
+the monitored application. Select **Diagnostica un procés**, choose a process,
+configure a bounded capture, add markers, stop, compare its two halves, then
+create an offline HTML or JSON report. Captures contain real measurements.
+
+For development, `make dev` starts the sensor, API on 7831 and Vite on 5173.
+For an offline distribution, run `make package` on a connected build host and
+follow [offline installation](docs/installation/offline.md).
+
+## Implemented architecture
+
+```text
+React 19 / TypeScript / TanStack Query
+          │ authenticated HTTP + fetch/SSE
+FastAPI / Pydantic / SQLAlchemy / SQLite WAL
+          │ private Unix socket / framed Protobuf envelope
+Rust sensor ── procfs + optional Aya uprobes ── same-UID target processes
+          │
+          └── bounded leases, acknowledged sample queues, explicit loss
+
+Application-initialized Python 2 agent ── credential-checked Unix datagrams
+         nested operations / C function boundaries / bounded generation-zero GC counts
+         optional Lab object blocks + verified allocation-time frames
+
+Metrics + actual native events ── streaming Zstandard .lscap + SHA256
+          └── Rust lifecycle + native stacks ── flamegraphs / offline reports
+```
+
+`crates/` contains identity, procfs, protocol, capture, analysis, symbol inspection
+and sensor packages. `apps/api` contains the collector and CLI; `apps/web` contains
+the browser UI. `legacy/` contains the genuine Python 2 extension and audited Lab
+patch. `bpf/` contains the C allocation probes embedded in the Aya sensor loader.
+`schemas/`, `tests/`, `packaging/`, `.github/` and `docs/` carry the shared
+contracts, executable validation, installers, CI and operator guidance.
+
+## Native investigations
+
+Phase 4 adds [continuous metrics observation and bounded investigations](docs/usage/production-investigation.md),
+[automatic growth detection](docs/usage/automatic-detection.md), physical native
+capture windows, adaptive safety, deterministic findings and repeated-operation
+experiments. Monitoring keeps no allocator probes attached. Separate windows
+never become one exact lifetime trace. Readiness stays fail-closed until independent
+release gates qualify; releases remain engineering previews.
+
+Actual local results, scoped readiness and remaining blockers are recorded in
+the [Phase 4 validation report](docs/development/phase4-validation.md).
+
+See the [complete native leak tutorial](docs/usage/native-allocation-leak.md).
+A controlled 48-block leak was attributed to its actual C caller with exactly
+3,145,728 retained bytes and zero loss; the cleanup control retained zero.
+Native binaries are built against glibc 2.31 and load on Ubuntu 20.04/22.04/24.04.
+Kernel attachment is verified on 6.19.14+kali-amd64; the Ubuntu kernel matrix
+and production overhead target remain unqualified. Historical Phase 3 allocation-heavy target CPU costs range +289–633% for Native Light and
++605–687% for Detailed on shared hardware. Keep metrics-only as default; no
+production CPU target is qualified. See [measured performance](docs/development/production-performance.md).
+
+## Python investigations
+
+[Python Memory Leak Investigation](docs/usage/python-memory-investigation.md)
+covers initialization, nested operations, opt-in function profiling, exact Lab
+lines, positive/cleanup fixtures, CLI and reports. Eight controlled retained tuples
+match 9,152 object-block bytes on the verified UCS4 build; cleanup gives zero.
+Python blocks, native allocations, GC counts and RSS are separate overlapping
+domains. See [attribution evidence](docs/architecture/python-attribution.md).
+
+## CLI
+
+```bash
+.venv/bin/leakscope doctor --json
+.venv/bin/leakscope ps --tree
+.venv/bin/leakscope inspect --pid 1234
+.venv/bin/leakscope capture --pid 1234 --duration 30s --output investigation.lscap
+.venv/bin/leakscope capture --pid 1234 --native --duration 30s --output native.lscap
+.venv/bin/leakscope analyze investigation.lscap
+.venv/bin/leakscope report investigation.lscap --output report.html
+.venv/bin/leakscope monitor --pid 1234 --duration 24h --json
+.venv/bin/leakscope watch --pid 1234 --growth-mb 100 --window 30m --json
+.venv/bin/leakscope investigate --pid 1234 --policy native_light --duration 5s --json
+.venv/bin/leakscope findings SESSION_ID --json
+.venv/bin/leakscope performance SESSION_ID --json
+.venv/bin/leakscope report SESSION_ID --output investigation.html
+.venv/bin/leakscope release-readiness --json
+```
+
+The CLI reads `.data/admin.token`, or `LEAKSCOPE_TOKEN`, and uses the same role
+checks as the UI. `analyze`, file `compare` and file `report` work offline.
+
+## Validation
+
+```bash
+make test lint typecheck
+make test-native
+make test-legacy
+make test-integration
+make test-e2e
+```
+
+Test commands that create sockets, processes or browsers require an environment
+that permits those operations. Kernel probe attachment is not part of portable tests.
+See [testing](docs/development/testing.md), [limitations](docs/compatibility/limitations.md)
+and [release gates](docs/quality-gates.md) before using this preview operationally.
+
+RSS, native heap blocks, Python arenas, Python blocks and GC object estimates are
+separate domains. **They are never added together. RSS growth alone is not proof of a leak.**
+
+## Automated releases
+
+Prepare and review a version with `.venv/bin/python scripts/release.py prepare 0.2.0-rc.1`,
+then push the matching annotated tag. GitHub Actions validates and publishes
+crates.io, the Python component, GHCR and complete standalone/Debian assets using
+the already configured registry tokens and automatic GITHUB_TOKEN. No manual
+first publication, GPG or registry Trusted Publishing is required.
+
+[Release quickstart](docs/releasing/quickstart.md) explains the protected environment,
+manual nonpublishing dry run, first prerelease and safe recovery. Prereleases
+remain engineering previews; stable promotion retains all production gates.

leakscope-0.2.0rc1/apps/api/PYPI.md

@@ -0,0 +1,18 @@
+# LeakScope Python component
+
+This distribution installs the Python collector, FastAPI backend, CLI and Alembic
+migrations. It requires Python 3.11 or newer. It does **not** bundle the Rust sensor,
+Rust analyzer, web assets or CPython 2.7 compatibility extension, and performs no
+executable downloads during installation.
+
+`leakscope --version`, offline capture inspection and database backup work through
+this package. Recording and native allocation analysis require separately installed
+matching `leakscope-sensor` and `leakscope-analyzer` executables on PATH (or the
+explicit LEAKSCOPE_SENSOR_BIN / LEAKSCOPE_ANALYZER_BIN settings). Serving the UI
+requires LEAKSCOPE_WEB_DIST pointing to matching built assets. For the complete
+application, use the verified offline standalone tarball or Debian distribution
+from https://github.com/polsala/LeakScope/releases.
+
+Engineering previews do not claim production readiness. Native tracing is opt-in;
+metrics remain available without BPF. Python 2.7 is used only by the separate
+compatibility agent and optional laboratory interpreter.

leakscope-0.2.0rc1/apps/api/leakscope.egg-info/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: leakscope
+Version: 0.2.0rc1
+Summary: LeakScope Python collector and CLI; native executables and web assets are installed separately
+License-Expression: MIT
+Project-URL: Repository, https://github.com/polsala/LeakScope
+Project-URL: Documentation, https://github.com/polsala/LeakScope/tree/main/docs
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi==0.143.1
+Requires-Dist: uvicorn==0.34.3
+Requires-Dist: pydantic==2.11.7
+Requires-Dist: sqlalchemy==2.0.41
+Requires-Dist: alembic==1.16.2
+Requires-Dist: zstandard==0.23.0
+Requires-Dist: protobuf==6.33.5
+Requires-Dist: PyYAML==6.0.2
+Requires-Dist: httpx==0.28.1
+Requires-Dist: starlette==1.8.0
+Dynamic: license-file
+
+# LeakScope Python component
+
+This distribution installs the Python collector, FastAPI backend, CLI and Alembic
+migrations. It requires Python 3.11 or newer. It does **not** bundle the Rust sensor,
+Rust analyzer, web assets or CPython 2.7 compatibility extension, and performs no
+executable downloads during installation.
+
+`leakscope --version`, offline capture inspection and database backup work through
+this package. Recording and native allocation analysis require separately installed
+matching `leakscope-sensor` and `leakscope-analyzer` executables on PATH (or the
+explicit LEAKSCOPE_SENSOR_BIN / LEAKSCOPE_ANALYZER_BIN settings). Serving the UI
+requires LEAKSCOPE_WEB_DIST pointing to matching built assets. For the complete
+application, use the verified offline standalone tarball or Debian distribution
+from https://github.com/polsala/LeakScope/releases.
+
+Engineering previews do not claim production readiness. Native tracing is opt-in;
+metrics remain available without BPF. Python 2.7 is used only by the separate
+compatibility agent and optional laboratory interpreter.

leakscope-0.2.0rc1/apps/api/leakscope.egg-info/SOURCES.txt

@@ -0,0 +1,36 @@
+LICENSE
+README.md
+pyproject.toml
+apps/api/PYPI.md
+apps/api/leakscope.egg-info/PKG-INFO
+apps/api/leakscope.egg-info/SOURCES.txt
+apps/api/leakscope.egg-info/dependency_links.txt
+apps/api/leakscope.egg-info/entry_points.txt
+apps/api/leakscope.egg-info/requires.txt
+apps/api/leakscope.egg-info/top_level.txt
+apps/api/leakscope_api/__init__.py
+apps/api/leakscope_api/agent.py
+apps/api/leakscope_api/analysis.py
+apps/api/leakscope_api/app.py
+apps/api/leakscope_api/capture.py
+apps/api/leakscope_api/cli.py
+apps/api/leakscope_api/config.py
+apps/api/leakscope_api/context_capture.py
+apps/api/leakscope_api/contracts.py
+apps/api/leakscope_api/db.py
+apps/api/leakscope_api/deployment.py
+apps/api/leakscope_api/healthcheck.py
+apps/api/leakscope_api/investigation.py
+apps/api/leakscope_api/limits.py
+apps/api/leakscope_api/models.py
+apps/api/leakscope_api/monitoring.py
+apps/api/leakscope_api/native.py
+apps/api/leakscope_api/readiness.py
+apps/api/leakscope_api/reports.py
+apps/api/leakscope_api/sensor.py
+apps/api/leakscope_api/service.py
+apps/api/leakscope_api/storage.py
+apps/api/leakscope_api/migrations/env.py
+apps/api/leakscope_api/migrations/versions/0001_initial.py
+apps/api/leakscope_api/migrations/versions/0002_agent_evidence.py
+apps/api/leakscope_api/migrations/versions/0003_monitoring.py

leakscope-0.2.0rc1/apps/api/leakscope.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

leakscope-0.2.0rc1/apps/api/leakscope.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+leakscope = leakscope_api.cli:main

leakscope-0.2.0rc1/apps/api/leakscope.egg-info/requires.txt

@@ -0,0 +1,10 @@
+fastapi==0.143.1
+uvicorn==0.34.3
+pydantic==2.11.7
+sqlalchemy==2.0.41
+alembic==1.16.2
+zstandard==0.23.0
+protobuf==6.33.5
+PyYAML==6.0.2
+httpx==0.28.1
+starlette==1.8.0

leakscope-0.2.0rc1/apps/api/leakscope.egg-info/top_level.txt

@@ -0,0 +1 @@
+leakscope_api

leakscope-0.2.0rc1/apps/api/leakscope_api/__init__.py

@@ -0,0 +1,3 @@
+"""LeakScope collector and standalone CLI."""
+
+__version__ = "0.2.0rc1"