blockpath 0.1.0__tar.gz

blockpath-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync (locked)
+        run: uv sync --locked --all-extras
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Type check (mypy --strict)
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest

blockpath-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) when a v* tag is pushed. No API token is
+# stored anywhere: PyPI is configured to trust this repository and workflow, and mints a
+# short-lived credential for the run. The maintainer creates the tag; this does the rest.
+#
+# One-time setup on PyPI (the maintainer, not this workflow):
+#   pypi.org -> the blockpath project -> Publishing -> add a trusted publisher:
+#     owner: iraettae   repository: blockpath   workflow: release.yml   environment: pypi
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # the OIDC token Trusted Publishing exchanges for a PyPI credential
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

blockpath-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Corpus clones: third-party code, never re-published from this repository.
+# Only the URL list, pinned SHAs and derived numbers are committed.
+.corpus/
+
+# Raw per-run scratch that reproduce scripts regenerate
+.cache/
+*.log
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+
+# Tooling
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+
+# Local assistant/tooling config, never part of the published project
+.claude/
+CLAUDE.md
+.cursor/
+
+# Dev interpreter pin: the supported range is in pyproject (requires-python),
+# and CI is explicit, so we do not force one local version on contributors.
+.python-version
+benchmark/runtime_demo/observed.json

blockpath-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+# Commits do not physically pass with dirty code: ruff lints and formats, mypy type-checks.
+# Install once with `uv run pre-commit install`.
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: mypy
+        name: mypy --strict
+        entry: uv run mypy
+        language: system
+        pass_filenames: false
+        types_or: [python, pyi]

blockpath-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-09
+
+First release.
+
+### Added
+
+- `blockpath check` -- static analysis that finds blocking calls reachable from a coroutine and
+  prints the full call path across files and modules. Text and `--json` reporters; exit codes
+  `0` clean / `1` findings / `2` error.
+- Three diagnostics: **BLK001** (a blocking call reachable from a coroutine), **BLK002** (a
+  function called where it should have been passed to an executor), **BLK003** (`--strict` only:
+  a blocking call handed to a callee that could not be resolved).
+- Import resolver handling relative imports, re-exports through `__init__.py`, `as`-aliases,
+  src-layout, and cycles, resolving names without importing or running the target code.
+- Blocking-call oracle as data (`oracle.yaml`): ~50 entries over three severity tiers (`error`
+  on by default, `warning` and `off` opt-in), plus the thread-offload primitives.
+- `blockpath verify -- <command>` and `blockpath compare` -- a runtime verifier built on
+  `sys.monitoring` that records which functions actually ran on the loop and reports a lower
+  bound on recall.
+- Configuration via `[tool.blockpath]` in `pyproject.toml`.
+
+### Measured
+
+- A pre-registered survey of 57 public aiogram/FastAPI repositories: 51% of blocking calls
+  reachable from a coroutine sit at depth 2 or deeper, where per-file linters cannot follow.
+- Hand-adjudicated precision on five of those repositories: 110/112 (98.2%) by the tool's literal
+  claim, 99/112 (88.4%) counting product-code bugs only, every false positive explained.
+
+[0.1.0]: https://github.com/iraettae/blockpath/releases/tag/v0.1.0

blockpath-0.1.0/LICENSE

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

blockpath-0.1.0/Makefile

@@ -0,0 +1,36 @@
+.DEFAULT_GOAL := help
+.PHONY: help install lint fmt typecheck test check demo bench bench-depth
+
+help:  ## show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  %-14s %s\n", $$1, $$2}'
+
+install:  ## sync the locked dev environment and install the pre-commit hook
+	uv sync --locked --all-extras
+	uv run pre-commit install
+
+lint:  ## ruff check + format check
+	uv run ruff check .
+	uv run ruff format --check .
+
+fmt:  ## ruff autofix + format
+	uv run ruff check --fix .
+	uv run ruff format .
+
+typecheck:  ## mypy --strict
+	uv run mypy
+
+test:  ## pytest
+	uv run pytest
+
+check: lint typecheck test  ## everything CI runs
+
+demo:  ## re-record the README demo (asciinema cast + animated svg via svg-term)
+	asciinema rec --overwrite -c scripts/demo_session.sh --cols 100 --rows 12 docs/demo.cast
+	npx --yes svg-term-cli --in docs/demo.cast --out docs/demo.svg --window --width 100 --height 12
+
+bench-depth:  ## rebuild the Milestone 0 depth histogram from the pinned corpus
+	./scripts/reproduce_depth_histogram.sh
+
+bench:  ## rebuild the precision findings from the pinned benchmark repositories
+	./scripts/reproduce_benchmark.sh

blockpath-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: blockpath
+Version: 0.1.0
+Summary: Find blocking calls reachable from a coroutine, and print the whole call path across files and modules.
+Project-URL: Repository, https://github.com/iraettae/blockpath
+Project-URL: Issues, https://github.com/iraettae/blockpath/issues
+Author: Damir
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,blocking,call-graph,event-loop,linter,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: pathspec>=0.12
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Description-Content-Type: text/markdown
+
+# blockpath
+
+[![ci](https://github.com/iraettae/blockpath/actions/workflows/ci.yml/badge.svg)](https://github.com/iraettae/blockpath/actions/workflows/ci.yml)
+[![python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
+
+Find the synchronous call that stalls your event loop, and print the whole path to it: from the
+`async` handler down through `services/` and `clients/` to the blocking `requests.get`, across as
+many files and modules as it takes.
+
+Existing linters catch a blocking call only when it sits directly in the `async def` body. In
+real code it almost never does -- it is three to five calls deep, in another module, behind a
+couple of helpers nobody thinks about. That is where it hides, and that is what blockpath finds.
+
+## The problem is real, and it was measured before a line of the analyzer was written
+
+A survey of **57 public aiogram/FastAPI repositories**, with the protocol and thresholds
+[registered in advance](benchmark/PREREGISTRATION.md) so the result could not be steered, asked
+one question: when a coroutine can reach a blocking call, how deep is it?
+
+```
+depth 1 | ########################################   77  (48.7%)   <- a per-file linter sees these
+depth 2 | ###############                            28  (17.7%)
+depth 3 | ################                           31  (19.6%)
+depth 4 | #########                                  17  (10.8%)
+depth 5 | ##                                          3  ( 1.9%)
+depth 6 | #                                           2  ( 1.3%)
+
+        |                                           158 reachable blocking call sites
+```
+
+**51% of them sit at depth 2 or deeper**, across module boundaries, where no per-file linter can
+follow. As a cross-check, `ruff --select ASYNC` run on the same repositories flags **0 of those
+81 deep sites**. The histogram, and the fact that it rebuilds from scratch, is in
+[benchmark/depth_histogram.md](benchmark/depth_histogram.md) (`make bench-depth`).
+
+## What it looks like
+
+![blockpath check finding a blocking call through three files](docs/demo.svg)
+
+```console
+$ blockpath check .
+BLK001 blocking call reachable from a coroutine
+  app/handlers/order.py:11    return resolve_address(address)                     <- entry: async def
+    app/services/geo.py:6       return geocode(query)
+      app/clients/nominatim.py:7  response = requests.get(BASE_URL, params=...)   <- blocks the event loop
+  hint: await asyncio.to_thread(resolve_address, ...)
+
+1 finding(s): 1 BLK001
+```
+
+The path through three files is the point: no existing linter prints it.
+
+## Quick start
+
+```bash
+pip install blockpath
+blockpath check .
+blockpath check . --json      # for CI
+```
+
+Exit code is `0` when clean, `1` when there are findings (fails a build), `2` if the tool itself
+errored -- so a crash is never mistaken for a clean run.
+
+Optional configuration, in your own `pyproject.toml`:
+
+```toml
+[tool.blockpath]
+tiers = ["error"]                       # error (default) | warning | off
+entry-decorators = ["router.message"]   # mark framework handlers as entry points
+strict = false                          # also report blocking calls handed to unresolved callees
+```
+
+## How it works
+
+Six layers, each a small tested unit, and one idea that carries the whole thing.
+
+```
+collect  ->  symbols  ->  resolve  ->  callgraph  ->  oracle  ->  analysis
+(walk &      (names &     (name ->     (CALL/REF    (what      (three BFS,
+ parse)       scopes)      function)    edges)       blocks)    the witness)
+```
+
+The idea is that a finding is the **intersection of two independent reachability questions**, and
+that intersection is why the tool stays quiet:
+
+1. **Backward** from every blocking leaf: which functions can reach a blocking call at all?
+2. **Forward** from every coroutine: which functions can a coroutine reach?
+3. A third pass over the intersection recovers the *witness* -- the exact chain of call sites.
+
+Report only their intersection and `time.sleep` in a synchronous CLI script in the same repo
+stays silent. Report either half alone and the tool cries wolf and gets switched off. The whole
+analysis is `O(V+E)` -- three breadth-first searches, no Tarjan, no SCC, no fixpoint
+([ADR 0002](docs/adr/0002-three-bfs-not-tarjan.md)).
+
+The call graph is built from the AST **without importing or running your code**, so a project
+that needs a database to import is analysed the same as any other.
+
+## How good is it, honestly
+
+Run over five of the surveyed repositories and adjudicated by hand, finding by finding, with a
+second pass auditing the riskiest calls ([benchmark/adjudication.md](benchmark/adjudication.md)):
+
+- **precision 110/112 = 98.2%** by the tool's literal claim (a blocking call reachable from a
+  coroutine), of which 99 are product-code bugs and 11 are real blocking calls in test code; or
+  **99/112 = 88.4%** counting product bugs only. Both numbers are in the table, and each of the
+  two false positives is explained with a permalink.
+- **recall is a lower bound, never a point estimate.** The runtime verifier (`blockpath verify --
+  pytest`) records which functions actually ran on the loop and compares them to the static
+  findings, but it only sees the paths the tests exercised. It can prove a miss and can never
+  prove completeness, and it says nothing about precision -- only the hand adjudication does.
+
+Precision is not a number the analyzer asserts about itself; it is what survived a human reading
+each finding against the source.
+
+## Design decisions, and where it loses
+
+- **Only calls by name are resolved.** An attribute call on a value (`self.session.get()`) needs
+  type inference, which this does not do; the cost is measured (about half of all call sites on
+  one benchmark repo) rather than waved away ([ADR 0003](docs/adr/0003-attribute-calls-not-resolved.md)).
+- **A reference is not a call.** A function passed to `run_in_executor(None, f)` runs in a
+  thread, so it is silent by construction -- no offload false positives -- while
+  `run_in_executor(None, f())` with parentheses is a real bug (BLK002)
+  ([ADR 0007](docs/adr/0007-call-edges-only-ref-not-traversed.md)).
+- **Unknown is quiet by default.** A path with an unresolved edge is not reported unless you ask
+  with `--strict` (BLK003) ([ADR 0006](docs/adr/0006-reexport-and-star-import-policy.md)).
+- The [complete list of limitations](docs/limitations.md) is written as they were found, not at
+  the end.
+
+### Prior art
+
+- **ruff `ASYNC` rules** are written in Rust and run hundreds of times faster than this. They are
+  the right tool for the depth-1 case, and blockpath does not try to compete on speed. They work
+  per file, by an explicit architectural choice (parallel analysis without global state), so they
+  do not build a cross-module call graph and cannot print the path -- which is the entire reason
+  this exists. The 0-of-81 cross-check above is that difference, measured.
+- **flake8-async** is likewise per-file and does not follow calls between modules.
+
+blockpath is not a replacement for either; it is the cross-module analysis they deliberately do
+not do.
+
+## Development
+
+```bash
+uv sync --all-extras
+make check          # ruff, mypy --strict, pytest
+make bench-depth    # rebuild the depth histogram from the pinned corpus
+./scripts/reproduce_benchmark.sh   # rebuild the precision findings
+```
+
+This project is AI-assisted: written by a human, who made the product and architecture decisions
+and signed off at every checkpoint, with an AI pair implementing under direction. [WORKLOG.md](WORKLOG.md)
+keeps the estimate-versus-actual log from day one, including where the estimates were wrong.
+
+Python 3.12+ (it uses `sys.monitoring`, [ADR 0001](docs/adr/0001-python-312-only.md)). MIT licensed.

blockpath-0.1.0/README.md

@@ -0,0 +1,154 @@
+# blockpath
+
+[![ci](https://github.com/iraettae/blockpath/actions/workflows/ci.yml/badge.svg)](https://github.com/iraettae/blockpath/actions/workflows/ci.yml)
+[![python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
+
+Find the synchronous call that stalls your event loop, and print the whole path to it: from the
+`async` handler down through `services/` and `clients/` to the blocking `requests.get`, across as
+many files and modules as it takes.
+
+Existing linters catch a blocking call only when it sits directly in the `async def` body. In
+real code it almost never does -- it is three to five calls deep, in another module, behind a
+couple of helpers nobody thinks about. That is where it hides, and that is what blockpath finds.
+
+## The problem is real, and it was measured before a line of the analyzer was written
+
+A survey of **57 public aiogram/FastAPI repositories**, with the protocol and thresholds
+[registered in advance](benchmark/PREREGISTRATION.md) so the result could not be steered, asked
+one question: when a coroutine can reach a blocking call, how deep is it?
+
+```
+depth 1 | ########################################   77  (48.7%)   <- a per-file linter sees these
+depth 2 | ###############                            28  (17.7%)
+depth 3 | ################                           31  (19.6%)
+depth 4 | #########                                  17  (10.8%)
+depth 5 | ##                                          3  ( 1.9%)
+depth 6 | #                                           2  ( 1.3%)
+
+        |                                           158 reachable blocking call sites
+```
+
+**51% of them sit at depth 2 or deeper**, across module boundaries, where no per-file linter can
+follow. As a cross-check, `ruff --select ASYNC` run on the same repositories flags **0 of those
+81 deep sites**. The histogram, and the fact that it rebuilds from scratch, is in
+[benchmark/depth_histogram.md](benchmark/depth_histogram.md) (`make bench-depth`).
+
+## What it looks like
+
+![blockpath check finding a blocking call through three files](docs/demo.svg)
+
+```console
+$ blockpath check .
+BLK001 blocking call reachable from a coroutine
+  app/handlers/order.py:11    return resolve_address(address)                     <- entry: async def
+    app/services/geo.py:6       return geocode(query)
+      app/clients/nominatim.py:7  response = requests.get(BASE_URL, params=...)   <- blocks the event loop
+  hint: await asyncio.to_thread(resolve_address, ...)
+
+1 finding(s): 1 BLK001
+```
+
+The path through three files is the point: no existing linter prints it.
+
+## Quick start
+
+```bash
+pip install blockpath
+blockpath check .
+blockpath check . --json      # for CI
+```
+
+Exit code is `0` when clean, `1` when there are findings (fails a build), `2` if the tool itself
+errored -- so a crash is never mistaken for a clean run.
+
+Optional configuration, in your own `pyproject.toml`:
+
+```toml
+[tool.blockpath]
+tiers = ["error"]                       # error (default) | warning | off
+entry-decorators = ["router.message"]   # mark framework handlers as entry points
+strict = false                          # also report blocking calls handed to unresolved callees
+```
+
+## How it works
+
+Six layers, each a small tested unit, and one idea that carries the whole thing.
+
+```
+collect  ->  symbols  ->  resolve  ->  callgraph  ->  oracle  ->  analysis
+(walk &      (names &     (name ->     (CALL/REF    (what      (three BFS,
+ parse)       scopes)      function)    edges)       blocks)    the witness)
+```
+
+The idea is that a finding is the **intersection of two independent reachability questions**, and
+that intersection is why the tool stays quiet:
+
+1. **Backward** from every blocking leaf: which functions can reach a blocking call at all?
+2. **Forward** from every coroutine: which functions can a coroutine reach?
+3. A third pass over the intersection recovers the *witness* -- the exact chain of call sites.
+
+Report only their intersection and `time.sleep` in a synchronous CLI script in the same repo
+stays silent. Report either half alone and the tool cries wolf and gets switched off. The whole
+analysis is `O(V+E)` -- three breadth-first searches, no Tarjan, no SCC, no fixpoint
+([ADR 0002](docs/adr/0002-three-bfs-not-tarjan.md)).
+
+The call graph is built from the AST **without importing or running your code**, so a project
+that needs a database to import is analysed the same as any other.
+
+## How good is it, honestly
+
+Run over five of the surveyed repositories and adjudicated by hand, finding by finding, with a
+second pass auditing the riskiest calls ([benchmark/adjudication.md](benchmark/adjudication.md)):
+
+- **precision 110/112 = 98.2%** by the tool's literal claim (a blocking call reachable from a
+  coroutine), of which 99 are product-code bugs and 11 are real blocking calls in test code; or
+  **99/112 = 88.4%** counting product bugs only. Both numbers are in the table, and each of the
+  two false positives is explained with a permalink.
+- **recall is a lower bound, never a point estimate.** The runtime verifier (`blockpath verify --
+  pytest`) records which functions actually ran on the loop and compares them to the static
+  findings, but it only sees the paths the tests exercised. It can prove a miss and can never
+  prove completeness, and it says nothing about precision -- only the hand adjudication does.
+
+Precision is not a number the analyzer asserts about itself; it is what survived a human reading
+each finding against the source.
+
+## Design decisions, and where it loses
+
+- **Only calls by name are resolved.** An attribute call on a value (`self.session.get()`) needs
+  type inference, which this does not do; the cost is measured (about half of all call sites on
+  one benchmark repo) rather than waved away ([ADR 0003](docs/adr/0003-attribute-calls-not-resolved.md)).
+- **A reference is not a call.** A function passed to `run_in_executor(None, f)` runs in a
+  thread, so it is silent by construction -- no offload false positives -- while
+  `run_in_executor(None, f())` with parentheses is a real bug (BLK002)
+  ([ADR 0007](docs/adr/0007-call-edges-only-ref-not-traversed.md)).
+- **Unknown is quiet by default.** A path with an unresolved edge is not reported unless you ask
+  with `--strict` (BLK003) ([ADR 0006](docs/adr/0006-reexport-and-star-import-policy.md)).
+- The [complete list of limitations](docs/limitations.md) is written as they were found, not at
+  the end.
+
+### Prior art
+
+- **ruff `ASYNC` rules** are written in Rust and run hundreds of times faster than this. They are
+  the right tool for the depth-1 case, and blockpath does not try to compete on speed. They work
+  per file, by an explicit architectural choice (parallel analysis without global state), so they
+  do not build a cross-module call graph and cannot print the path -- which is the entire reason
+  this exists. The 0-of-81 cross-check above is that difference, measured.
+- **flake8-async** is likewise per-file and does not follow calls between modules.
+
+blockpath is not a replacement for either; it is the cross-module analysis they deliberately do
+not do.
+
+## Development
+
+```bash
+uv sync --all-extras
+make check          # ruff, mypy --strict, pytest
+make bench-depth    # rebuild the depth histogram from the pinned corpus
+./scripts/reproduce_benchmark.sh   # rebuild the precision findings
+```
+
+This project is AI-assisted: written by a human, who made the product and architecture decisions
+and signed off at every checkpoint, with an AI pair implementing under direction. [WORKLOG.md](WORKLOG.md)
+keeps the estimate-versus-actual log from day one, including where the estimates were wrong.
+
+Python 3.12+ (it uses `sys.monitoring`, [ADR 0001](docs/adr/0001-python-312-only.md)). MIT licensed.

blockpath-0.1.0/WORKLOG.md

@@ -0,0 +1,65 @@
+# WORKLOG
+
+Estimate vs actual, per stage. Kept from day one, because a miss in estimation is itself
+diagnostic and hiding it would waste the only evidence this file produces.
+
+## How to read the "actual" column
+
+This project is AI-assisted (see README). The `actual` column records **wall-clock time of
+the working session**, not human keyboard-hours, and it is not comparable to the `estimate`
+column, which is a human-hours budget. Both are recorded because the interesting quantity is
+the *ratio between stages*: which stage blew its budget relative to the others, and whether
+the stage flagged up front as the risky one (stage 2, the import resolver) is in fact the one
+that did.
+
+Every stage row also records the decisions taken and the ones reversed.
+
+| Stage | Estimate (h) | Actual (wall-clock) | Delta | Notes |
+|---|---|---|---|---|
+| 0. Milestone 0: premise check | 3 | ~1 session, over budget | over | premise HOLDS, gate passed; see note below |
+| 1. Skeleton + golden tests | 5 | ~part of a session | roughly on budget | uv/hatchling, ruff+mypy strict green, CI, 4 ADRs, 15 golden cases xfail-until-implemented |
+| 2. collect + symbols + resolve | 20 | ~a session, incl. audit | roughly on budget | resolver green; symtable scopes; property test vs importlib; adversarial audit found 1 critical + majors, all fixed |
+| 3. callgraph | 10 | ~part of a session | under budget | nodes + CALL/REF edges + consumer context; resolution tally; dogfooded on a 725-module repo (attribute calls ~51%) |
+| 4. oracle.yaml | 5 | ~part of a session | under budget | 52 entries, 3 severity tiers, 4 offload primitives; YAML-boolean `off` trap handled |
+| 5. analysis.py (three BFS) | 4 | ~part of a session | under budget | backward/forward/witness BFS + BLK002 + BLK003; **all 15 golden cases green**; 33 findings on a real repo, depth-5 witness |
+| 6. reporters + CLI | 5 | ~part of a session | under budget | rich trace + JSON, exit codes 0/1/2, config in pyproject (ADR 0008), --strict/--tier/--no-config |
+| 7. runtime/ (watchdog, sys.monitoring) | 12 | ~part of a session | under budget | sysmon/coverage coexistence proved empirically first; DISABLE pattern 1.09x vs 1.29x; predicate test reddens on co_flags |
+| 8. corpus + adjudication | 12 | ~part of a session | under budget | 112 findings on 5 repos, hand-adjudicated; precision 110/112 (98.2%); audit HONEST, 0 overturned; runtime pipeline demoed (recall bound 100% on a built app) |
+| 9. packaging + release | 8 | ~part of a session | under budget | README (histogram first, animated svg demo, prior art), CHANGELOG, PyPI Trusted-Publishing workflow, wheel verified in isolation, gitleaks clean, tag prepared |
+| **Total** | **84** | one long build across sessions | see notes | 8/10 stages under or near budget; stage 0 over (the honesty task, not the mechanical one); every gate green, precision 110/112 measured |
+
+## Stage 0 note (why it ran over 3 hours)
+
+The 3-hour budget covered "clone repos, count depths, draw a histogram." It did not cover what
+actually happened, which is the more valuable thing: the first histogram was produced by a
+buggy instrument, an adversarial audit caught the bugs, and the number was rebuilt on a
+corrected one.
+
+Sequence:
+- Pre-registered the protocol and oracle before any data (commits `a06a211`, `b6660a1`).
+- Built the corpus (57 repos, pinned SHAs), ran the survey: pooled `D1` 0.679, but the cluster
+  bootstrap CI [0.31, 0.87] straddled the STOP line, so the number was not yet trustworthy.
+- Put the survey through an adversarial audit: hostile hand-built cases aimed at the resolver,
+  a by-hand trace of every depth>=2 finding back to source, and an investigation of why 41
+  repos came back empty. It falsified PREREGISTRATION section 5's "measured D1 is an upper
+  bound" claim with two corpus-firing bugs (offload inlining, function-local-import dropping).
+- Rewrote the survey (`0974978`): nested defs/lambdas as graph nodes, function-local import
+  resolution. 17-case regression suite, red before and green after. Corrected pooled `D1`
+  0.487, CI [0.17, 0.76], now entirely inside "premise holds."
+- Re-adjudicated all 81 depth>=2 findings on corrected data: 75 real, 5 test-only, 1 dead
+  branch, 0 fabricated.
+
+Diagnostic value of the overrun: the estimate was wrong because it priced the mechanical task,
+not the honesty task. That is the same class of miss anticipated for stage 2 (the import
+resolver, budgeted at 20h precisely because it is usually underestimated 2-3x), and it is the
+first concrete evidence that the "measure your own tool" axis of this project has teeth.
+
+## Reverts and abandoned approaches
+
+Recorded here as they happen, with the commit that reverted them.
+
+- The original inlining model for closures (`Site.inlined_nested`, PREREGISTRATION section 3.4)
+  did not survive the audit: it manufactured offload false positives. Replaced wholesale by the
+  nested-defs-as-nodes model in `0974978`. `inlined_nested` is now always False and kept only
+  for the raw-data schema -- a revert on contact with reality, left visible in the history
+  rather than squashed away.