Constraints and quality¶

This chapter covers the rules the design has to live within, the quality goals it's judged by, what we've measured so far, and the risks we know about.

Constraints¶

Quality goals¶

Ranked. When two goals conflict, the higher one wins.

Correctness sits above speed on purpose. A guardrail that sometimes stays silent teaches the agent that the wrong move is fine, and that's worse than no guardrail.

Measurements¶

All numbers come from the scaffold in this repository. Nothing here is projected. They were measured during M0; the spot check below shows how they have moved since.

Setup. A laptop, Bun 1.4.2, inwards-linux-x64 built by scripts/build-binaries.ts. Everything ran on one thread; the worker threads came later (#61). The laptop was in normal desktop use (load average around 2 to 3), so these are realistic numbers rather than best-case ones.

Synthetic repo. 2,100 Python files, 496,000 lines, 8.0 MB, four layers with eight first-party imports and forty small functions per module. bench/generate.py rebuilds it exactly (fixed random seed). With --legacy it adds an outer legacy layer that every module imports, so each of the 2,000 modules has one violation: the legacy codebase that chapter 3's cost model times with a full baseline.

Regression gate. Every pull request runs .github/workflows/bench.yml. It builds the base branch and the PR, runs both on the synthetic repo in alternation (40 hook runs on one file, 12 full checks), and fails when the PR is more than 20% slower on any metric, or when either build fails a run (the synthetic repo is clean, so every run must exit 0). Each side is built with its own .bun-version, so a Bun upgrade is measured too. The change is the median of per-pair ratios, so load that drifts during the job cancels out within a pair. The full checks run with INWARDS_NO_CACHE=1, so the gate measures the work, not the extraction cache. A fourth gated metric times the PostToolUse hook on a generated 4,482-line module with two old violations, in a small project of its own, changed before every run as an agent's edit does (bench/large-file.ts, #122). Like polar's file, its docstring mentions an import, so the prescan refuses it and every check parses all of it. A head-only table times the same hook one-shot and through the daemon, against the 100 ms budget and the 50 ms target. A second table, head only and not gated, times the full check with no cache, an empty cache (moved aside before each run) and a warm one. A third, head only and not gated either, times the PostToolUse hook one-shot and through inwards daemon in alternation and reports the daemon's p95 against #60's 50 ms target. Every other run sets INWARDS_DAEMON=0, so both builds run one-shot. The gate covers hook and full-check time only, not memory, start-up or binary size. The job summary shows p50/p95 for both builds (with 12 full runs, p95 is the slowest one) and the runner it ran on, and the raw samples are kept as an artifact. Locally, a build made 30% slower fails the gate, and ten runs of identical builds didn't fail it once (bench/compare.ts, bench/test/compare.test.ts).

Real-repo corpus. Stdlib and synthetic code don't look like a FastAPI or Django service, so .github/workflows/corpus.yml runs every night (and on any PR that changes the corpus or prescan-diff.ts) on five open-source repos pinned by commit in bench/corpus.json. bench/corpus.ts fetches each one shallow, only the pinned commit, and for three of them only the service directory (backend/, server/, saleor/; sparse cone mode also brings the files at the repo's top level), about 40 MB in all. It runs the prescan differential test on every .py file in the checkout and times the compiled binary: 5 full checks and 20 runs of inwards check --no-cache <file> on one file per repo, after one warm-up each. The one-file runs read no cache, as the hooks don't; until #122 they read the cache the full checks had just filled, which hid the parse. None of these repos has a [tool.inwards] table, so the manifest gives each one a layering of ours (written to inwards-corpus.toml in the checkout and passed with --config). The violation counts come from that layering and say nothing about the projects. The job fails when the prescan misses an import, when a checkout's .py count differs from the manifest (a broken fetch would otherwise shrink the corpus), or when inwards check exits with anything but 0 or 1. A repo that still fails to fetch after three attempts, or whose run fails, is recorded in the results and fails the job; the other repos still run. The table goes to the job summary and the raw samples to the corpus-result artifact.

First run, on the laptop described under Setup (load average 3 to 4), inwards 0.1.0:

The Violations column is from a later run (the INW010 review in #45), after INW005 and INW010 landed; saleor's count includes INW010's four broken imports.

Two things the synthetic repo didn't show. inwards check on polar's subscription/service.py (4,482 lines, 175 KB, two violations) takes about 125 ms here and 280 ms on a GitHub runner (AMD EPYC 7763, 2 cores), over the 100 ms budget; a small file in the same repo takes about 55 ms. The budget is written for the Claude Code hook, which runs the same one-file check (runCheck on the edited file) after reading its payload, so the hook can only be slower. Tracked in #122. Rerun locally after bytecode compilation (#118) cut every one-file check by 20 to 40 ms: polar's file now takes 83 / 90 ms (p50 / p95), saleor's 27 / 30 ms. The hook on polar's file, which checks it twice, stayed over budget until #122 parsed the second check incrementally (below). And a cold full check of saleor's 848,000 lines takes 1.8 s on one core (2.5 s on the GitHub runner), where the 496,000-line synthetic repo takes 0.4 s.

Results¶

Spike: bytecode and minification¶

#39 asked whether bun build --compile flags cut start-up or binary size. Since then scripts/build-binaries.ts builds with --bytecode --format=esm on top of --minify --sourcemap=linked.

Method. Six variants of inwards-linux-x64 from one commit, Bun 1.4.2, the same laptop as above. Start-up: 200 rounds of inwards --version, every variant once per round in rotating order. Hook and full check: bench/compare.ts with the current build as base, 100 hook runs and 20 full checks per side, change as the median of per-pair ratios. Peak RSS: /usr/bin/time -f %M, median of 5 runs. MB means 10^6 bytes throughout. The load average was 2 to 6 during the runs, so trust the ratios more than the absolute milliseconds; a base-against-base run moved 0.2% (hook) and 0.6% (full).

A repeat with the committed build and bench/compare.ts defaults (40 hook runs, 12 full checks) gave hook p50 / p95 64.4 / 73.6 ms before and 32.6 / 37.4 ms after (-48.0%), and full check -9.9%. A second start-up run gave 25.0 ms before and 10.8 ms after. On the example app, 60 alternating single-file checks: p50 58.7 → 30.3 ms and p95 77.7 → 39.5 ms wall time, and the engine's own time fell from 21.7 to 14.5 ms, because the engine and web-tree-sitter's JS glue no longer get parsed on first call either.

• Bytecode is the win. It moves JS parsing from every start to build time. It costs 2.5 MB per binary (1.3 MB gzipped) and 1 to 3 MB of RSS.
• Size can't be fixed with flags. Everything Inwards adds is under 1 MB (176 KB of minified JS, 0.67 MB of WASM); the rest is the Bun runtime. Minification was already on and saves 0.1 MB; the sourcemap costs 0.26 MB and keeps stack traces pointing at the TypeScript source, so it stays.
• ESM, not CJS. Head to head the two bytecode builds differ by +2.9% (hook) and +2.2% (full), within noise. ESM keeps the module semantics the binary had before.
• Checked. The 350 tests pass against the compiled binary (INWARDS_BIN=dist/inwards-linux-x64 bun test), so do --version and both embedded .wasm files (every check parses). A test program built the same way still reports the TypeScript line of a thrown error through the linked sourcemap. All six targets cross-compile, and the musl build checks the synthetic repo inside Alpine. CI's test matrix builds and tests the macOS and Windows binaries natively.
• Not tried. Bun's current docs list --compile-jit-policy and --bytecode-order (profile-guided bytecode layout); Bun 1.4.2's bun build has neither. --bytecode-depth, which 1.4.2 has, wasn't measured. Worth a look after a Bun upgrade.

Where a single-file check spends its time¶

Redone in the bytecode spike, with the bytecode build. Process start is inwards --version. The grammar and parse figures come from a script compiled the same way that times reading the embedded .wasm files, Parser.init, Language.load and one parse of shop/domain/order.py from the example app, median of 30 runs. "Config + I/O + rules" is the engine time the CLI reports (14.5 ms) minus those, not a measurement.

---
config:
  theme: base
  themeVariables:
    pieSectionTextColor: "#ffffff"
    pieTitleTextColor: "#6b7580"
    pieStrokeColor: "#ffffff"
    pieOpacity: "1"
    pie1: "#084e65"
    pie2: "#0b6784"
    pie3: "#2f7f99"
    pie4: "#3e4852"
    pie5: "#56616c"
    pie6: "#6b7580"
---
pie showData
    title One-file check, about 25 ms of work (engine + start-up)
    "Process start (Bun runtime)" : 10.5
    "WASM runtime init" : 7.8
    "Python grammar load (447 KB)" : 2.7
    "Parsing the file (first parse)" : 2
    "Config + file I/O + rules (remainder)" : 1.5
    "Reading the embedded .wasm files" : 0.5

In M0 the same check was about 30 ms of work: 10 ms process start, 12 ms WASM init, 3.5 ms grammar load, 1 ms parse and 3.5 ms remainder, all without bytecode. Parsing the file is still a small slice. About 85% of the cost is paying the same start-up price on every hook call. The wall-time p50 of 30 ms sits above this 25 ms of work because the harness spawns the process, and an agent's hook runner pays that too.

This changes the performance roadmap. For the agent loop, parse speed doesn't matter much. Start-up does.

Spike: a resident process¶

#59 asked whether the hooks and the language server should share one resident process, and what the hooks would gain from one. The decision is ADR-039.

Method. One arm64 laptop on macOS, Bun 1.4.2, inwards-darwin-arm64 built by scripts/build-binaries.ts from aede2ab. Other agents were working on the machine, so the load average was 5 to 7; trust the differences more than the absolute numbers. The project is examples/broken-app with a generated shop/domain/big.py added: 4,492 lines, 114 KB, two INW001 violations, close to polar's file in #122 (4,482 lines, two violations). The hook input is the Claude Code PostToolUse fixture pointed at each file, after a SessionStart, so both files' violations count as old. Each case ran 80 times (60 for PreToolUse and Stop), every case once per round in rotating order, after one warm-up; check runs set INWARDS_NO_CACHE=1. The resident process is a throwaway Bun script, run from source, that serves today's hookClaudeCode warm behind a Unix socket, with a per-request Runtime and buffered Streams; the client is a 10-line program compiled like the binary. "With caches" adds an in-memory extraction cache keyed by content and keeps git cat-file blob answers, which name a commit, for the life of the process.

• The client's start is the floor. Every hook call starts a process, about 15 ms here, before it can reach a daemon. Finding that no daemon listens costs nothing measurable.
• One git call is half of a small file's hook. PostToolUse reads the file's session-start text with git cat-file blob to split old violations from new ones: about 15 ms per call on this machine. A daemon reads it once per session.
• PostToolUse checks a file twice, as it is now and as it was at session start: 30 ms each for big.py, warm. With a cache keyed by content, the start text is parsed once per session; an edited file still costs one parse.
• Warm JIT counts too. A one-shot check costs 27 ms more than a warm one for order.py and 41 ms more for big.py. The extra 14 ms is parsing and walking code that a fresh process hasn't optimised yet.
• PreToolUse can't gain, at 16.8 ms against the 15.5 ms floor. Stop takes 141 ms but runs once per turn.
• Memory. The resident processes held 151 and 212 MB of RSS after the runs.
• Not measured: Windows named pipes, the compiled binary as the resident process, and Linux. The spike's scripts were throwaway and aren't in the repository; #60 adds the daemon to the benchmark job.

The hook daemon¶

#60 built the resident process the spike above measured, as ADR-039 decided: inwards daemon serves PostToolUse through a Unix socket (a named pipe on Windows), keeps extractions by text hash and git's answers by commit id, and reads everything else again on each request. The hook command itself is unchanged, so every PostToolUse still starts one process.

Method. The same arm64 laptop on macOS as the spike, the compiled inwards-darwin-arm64 with bytecode, load average 5 to 7 from other agents. examples/broken-app in a fresh git repository with a generated 4,492-line shop/domain/big.py holding two INW001 violations, after a SessionStart, so every finding is old and the hook reads each file's start text from git. One-shot (INWARDS_DAEMON=0) and through the daemon alternate in each round, with INWARDS_NO_CACHE=1; 80 rounds after 2 warm-ups, 40 when the file changes before every call.

• The target holds on this laptop. p95 is under 50 ms in every case, also for the large file that changes before every call, where the spike's prototype was at 50.1 ms.
• The bench job's synthetic repo, on the same laptop: 23.8 / 25.3 ms one-shot, 14.9 / 16.5 ms through the daemon (40 runs; no session, so no git read).
• Memory. The daemon held 188 MB of RSS after 206 hook runs over both files.
• Not measured here: Windows named pipes. CI runs the daemon's tests on Linux for every PR; the Windows and macOS rows run them only in the manual full matrix before a release.

A large file checked twice¶

#122 found the one-shot PostToolUse hook over the 100 ms budget on polar's server/polar/subscription/service.py (4,482 lines, two INW001 violations). The hook checks the edited file as it is now and again as it was at session start, to tell old violations from new ones, and a file with a violation needs a full parse each time. A CPU profile of one run (95 ms) put 43 ms in tree-sitter's two parses and 14 ms in the git cat-file blob that reads the start text.

What changed. The engine takes an optional TreeReuse (src/core/src/shared/python/reparse.ts) that keeps the last full parse. When the next full parse is of the same path, it describes the change between the two texts to tree-sitter as one edit (the span between their common prefix and suffix, in UTF-16 code units) and parses from the old tree, so only the changed region is parsed again. The CLI keeps one per process, and inwards daemon one for its whole life, so its next request on the same file reuses the last one. If the new tree has a syntax error, it is parsed again from scratch: error recovery can take another path when it starts from an old tree, and the first version of the test caught a case that did. The output doesn't change: src/core/test/python/reparse.test.ts compares every node with a fresh parse on hand-picked edits and on 12 seeded chains of 25 edits each, and a one-off run on 655 CPython 3.14 stdlib files with four stacked edits each and three seeds (7,860 parses, about half with syntax errors) found 0 differences in the trees, the imports or the suppression comments.

Method. An arm64 macOS laptop with 10 cores, the darwin-arm64 binary from develop (ec2bd65) against this one, both built by scripts/build-binaries.ts. Other agents were working on the machine (load average 4 to 10), so trust the ratios more than the milliseconds. polar at the corpus commit with the corpus layering, after a SessionStart, so both violations are old; "changed" means a line was added before every call. The two builds alternate in each round, 60 rounds after 2 warm-ups (40 for the daemon rows, which ran build by build).

• The budget holds on this laptop for every path: p95 is under 100 ms one-shot and under 50 ms through the daemon.
• The second parse costs about 3 ms instead of about 16 ms for an edit of a few lines, measured in process on the same file.
• A one-file inwards check doesn't change, since it parses once. Neither does a full check: no file is parsed twice there.
• The bench job now times the hook on a 4,482-line module like polar's (bench/large-file.ts). On the same laptop, 20 runs each: 102.0 / 104.1 ms before, 84.1 / 89.1 ms after one-shot, and 23.0 / 26.2 ms through the daemon.
• On the Linux arm64 CI runner (4 cores), from the jobs of PR #299: inwards check --no-cache on polar's file took 62 and 65 ms p50 in two corpus runs and 128 ms in a third, where every repo ran about twice as slow. The bench job's hook on the 4,482-line module went from 117 to 101 ms p50 one-shot (median of pairs -17%) and took 19.3 / 27.4 ms through the daemon. On that runner the one-shot hook on a file this size is still over 100 ms; through the daemon it meets both targets.
• What is left of the one-shot hook: about 15 ms of process start, 14 ms for the git read of the start text, and the first full parse.

Worker threads for a full run¶

#61 spread a cold full check over several threads. The decision and its alternatives are ADR-040.

What runs where. inwards check and inwards baseline start worker threads when they read 1,000 files or more: one thread per 500 files, up to INWARDS_THREADS or, unset, half of the cores beyond two, at most 4 (Linux below). The main thread counts as one of them. Workers do only what a file's text decides: the loader test, the import skeleton and the full parse's imports and suppression comments. The main thread walks the tree, reads the files, runs every rule in file order and parses the few files with dynamic imports itself. The output is the same byte for byte with any number of threads, and INWARDS_THREADS=1 keeps the whole check on one thread.

Method. The darwin-arm64 binary built by scripts/build-binaries.ts, the base build from develop (73936df) against this one, on an arm64 macOS laptop with 10 cores. Other agents were working on the machine, so the load average was 4 to 7: trust the ratios more than the milliseconds. Each case ran 11 times after one warm-up, every case once per round in rotating order, with INWARDS_NO_CACHE=1; each run's JSON had to match the base build's. The real repos are checked with the corpus layering (bench/corpus.json). Peak RSS is /usr/bin/time -l, three runs each.

• One thread got faster too, by 2% to 5%: the check now resolves each file's real path once instead of twice.
• Parsing scales; the rest doesn't. With four threads, saleor spends about a third of its time walking the tree, resolving real paths and reading files before the engine starts, then about 120 ms in the rules and 100 ms confirming and reporting, all on the main thread. The legacy repo, where every module needs a full parse, gains the most.
• More threads stop paying early. Each worker compiles the grammar and warms its JIT up on its own, and a loaded machine has fewer free cores than it reports. Below 1,000 files the threads cost about as much as they save: 537 saleor files took 207 ms on one thread and 218 ms on three.
• Memory. Saleor's peak RSS went from about 360 MB on one thread to about 520 MB with four and 615 MB with eight.
• The cache and the hooks. A warm-cache check didn't change (0.95 → 0.91 s on saleor), the run that fills an empty cache got faster (2.6 → 2.05 s), and bench/compare.ts measured the hook and the pre-write guard within 3% of the base, the full check 20.5% faster.

• Linux, and why the default leaves cores free. The first CI run of the bench job, on a Linux arm64 runner that reports 4 cores, measured the synthetic repo's full check 59% slower with four threads. The linux-arm64 binary in an Ubuntu 24.04 container on the same laptop, pinned to four or eight cores (--cpuset-cpus), five runs each, gave these medians:

  Cores	Repo	1 thread	2	3	4
  4	synthetic	0.42 s	0.44 s	0.53 s	0.67 s
  4	synthetic legacy	2.28 s	2.33 s (1.67 to 2.34)	1.54 s	1.77 s
  8	synthetic	0.42 s	0.38 s	0.40 s	0.44 s
  8	synthetic legacy	2.30 s	1.68 s	1.38 s	1.23 s

  Each thread runs its own JavaScript VM, and its JIT compiler and garbage collector run on threads of their own, so a thread per core starves the main thread. With two threads as the default on that runner, the bench job still measured the synthetic full check 19% slower. The default is now half of the cores beyond two, at most 4: one thread on 4 cores, three on 8 and four from 10, as on the laptop above. - Not measured: GitHub's hosted 4-vCPU ubuntu-latest runner and Windows.

The serial part of a full run¶

With four threads, saleor spent about a third of a cold check on the main thread before the engine started: walking the tree, resolving real paths and reading files. #281 cut that part. The output is the same byte for byte, and the walk finds the same files under the same module names.

What changed.

• One real path per directory, not two per file. The walk resolves each directory and each symlink with realpath. A plain file gets its directory's real path plus the name readdir gave it: a file that isn't a symlink adds no link, so realpath would only repeat what the walk already resolved. The check then reuses those real paths instead of resolving every file again. On saleor, the walk went from about 114 ms to 30 ms and the second round of realpath (about 75 ms) is gone.
• The files are read in one batch. A check of 1,000 files or more asks for every file at once (fs.promises.readFile), so the reads wait on the disk together: 4,324 saleor files in about 55 ms instead of 90 ms. A smaller check, and every hook, reads one file after another as before.
• The workers start before the reads. The check counts its files before it reads them, so the pool starts first and the workers load the grammar while the main thread reads.
• Each worker holds two batches. A worker that finished a batch used to wait until the main thread, busy with a batch of its own, got back to its event loop to send the next one. Now the next one is already queued.

Method. As for the worker threads above: the darwin-arm64 binary, 11 runs per build after one warm-up, in rotating order, with INWARDS_NO_CACHE=1, every run's JSON compared with the others. The bases are #61's single-threaded base (73936df) and develop before this change (3dc5489, four threads). Other agents were working on the same laptop (load average 5 to 11).

The #61 base measured 1.48 to 1.62 s on saleor across six sessions that day, and this change 0.74 to 0.87 s with four threads: 1.83× to 2.00×, with a median of 1.93×. That puts the 2× #281 asked for at the edge rather than clearly met. All runs of every build gave the same JSON.

Each change on its own. Builds that each leave one change out, on saleor, 11 runs each (load average 7 to 16): all four 744 ms; without the walk's real paths 861 ms, without the batch read 812 ms, with the pool started after the reads 776 ms, with one batch per worker 794 ms.

What didn't pay, and was dropped.

• Listing the layer links while the reads wait. macOS serialises the file system calls: the links walk took 76 to 102 ms during the reads instead of 21 ms after them, and the sum didn't change.
• Starting the workers on the files as they are read. Idle workers ran the skeleton jobs of each 256-file chunk as it came in, and the engine's call reused the answers to identical jobs. Saleor 775 → 792 ms, polar 475 → 478 ms, the synthetic repos within 1%: no gain worth a second queue in the pool.
• Fewer realpath calls on directories. The walk is bound by readdir: 23 ms with or without them.

Linux. The linux-arm64 binary in an Ubuntu 24.04 container on the same laptop, seven runs each. Pinned to four cores, where the default is one thread, nothing changed: saleor 1.24 s before and after, polar 0.68 s, the synthetic repo 0.42 s, the legacy one 2.27 s. Linux answers realpath and file reads from its caches cheaply, so the serial part this removed was a macOS cost. Pinned to eight cores (three threads), saleor went from 0.92 to 0.87 s and the legacy repo from 1.43 to 1.37 s. The 3× on 4 vCPU that #61 asked for stays out of reach: a 4-core machine keeps one thread, and that thread spends its time in the parse and the rules.

What stays on the main thread. Timed from source on saleor with four threads: about 45 ms to walk and name the files, 70 ms to read them, then the engine: 260 ms for the skeleton batch (shared with the workers), 127 ms for the scans, 135 ms for the full-parse batch (shared), 60 ms to confirm and report and 33 ms for the whole-run checks. The scans and the confirmations are the rules, which stay on one thread by design (ADR-040).

Precision of the opt-in rules¶

The opt-in content rules (INW012 to INW016, FAPI001 to FAPI009) shipped with tests on fixtures only. #182 turned them on over the five corpus repos at their pinned commits, triaged the findings by hand, fixed the largest false-positive classes, and timed each rule.

Method. Each repo ran with its manifest layering plus select of every opt-in rule. INW015 needs a role, so fastapi-clean-example got role = ["app.outbound"], allowed-in = ["app.main"] and python-ddd role = ["modules.*.infrastructure", "seedwork.infrastructure"], allowed-in = ["config", "api.main", "cli"]. Polar's routers come from a class built at run time (#358), so INW012 saw one of its 450 endpoints until a second run added decorators = ["polar.*.router.get", "polar.*.router.post", "polar.*.router.patch", "polar.*.router.put", "polar.*.router.delete"]. A finding is a true positive when what it claims is true and a reader of the rule's page would want it fixed; a finding that is true to the letter but not worth fixing, such as a health check that pings the database, counts as false. Where a rule had more findings than could be read, every fifth one was looked at.

What the false positives were, and what is left:

• INW012. 8 of the first sample's 14 false positives were guards that raise the project's own errors (raise ResourceNotFound(), mapped to 404 by an app-wide exception handler); counting them as guards lost one true positive, a business rule written as two guards. 3 across both samples were a single joinedload(...) passed to a repository. Left: server-rendered HTML in nested with blocks (46 of the 73 findings are in Polar's back office), HTMX form handlers, health checks and a webhook (#360). The default thresholds held: only 3 of the 73 findings trip a single signal by 2 statements, 1 branch or 1 level or less. #360 then counted a tree of markup with blocks as one statement, an if or except that shows one message and returns as a guard, and left health checks alone. With every Polar router recognised (#358), that took Polar from 135 findings to 109 and the every-fifth sample from 10 of 27 true (37 %) to 10 of 22 (45 %), losing no true positive; Saleor kept its 2 (INW012's page has each change on its own). The thresholds stay: of the 12 false positives left, 2 are within 2 statements of the limit, and raising max-statements to 12 would clear those 2 and no sampled true positive, too few findings to move a default.
• INW015. 31 of 48 findings imported an exception class from an adapter to map it to an HTTP status. Left: a constant imported from an adapter. A test module was the other false positive; since #362 the content rules skip test modules, which leaves 16 findings, 15 of them true.
• INW016. 21 findings repeated a model's column in an Alembic migration. The 152 left are correct against the default scheme, but 98 are Polar's plural table names, 94% of its 104. #361 reports such a scheme once in a whole-project run, naming table-name = "snake": Polar went from 121 findings to 24 and the corpus from 152 to 55. Saleor's 26 stay: 46 of its 72 datetime columns end with _at, so its date_joined and start_date are a mix, not a scheme. 13 column findings no longer suggest a name made of time words only (date_at, timestamp_at), and date_of_birth now gets birth_date.
• FAPI001, FAPI002. Polar's back office is a FastAPI(openapi_url=None) app. The two FAPI001 findings on test apps in Polar are gone since #362, which leaves 19, all true. Both rules saw about 40 endpoints in the corpus, because Polar's and fastapi-clean-example's routers weren't recognised (see below).
• FAPI007. All 4 findings were streams (Polar's server-sent events, Saleor's discount iterator), not dependencies.

Routers built at run time. #358 taught the FastAPI model and INW012 the routers the run above missed: Polar's APIRouter = get_api_router_class(APIRoute) and BackofficeRouter = get_api_router_class(TransactionalAPIRoute), and fastapi-clean-example's routes declared inside make_*_router() -> APIRouter factories. The name is resolved through the project's imports instead of trusting any callee called APIRouter, since OpenStack projects name their WSGI routers that (the rule pages list what counts). Same method, rerun on 2026-10-11 against develop at a8c282a, which skips test modules (#362); path operations are counted outside tests:

full-stack-fastapi-template and python-ddd didn't change, and Saleor wasn't rerun. What the new findings are:

• FAPI001. 96 of Polar's 131 are on routes tagged APITag.private, which Polar's route class keeps out of its production schema (read since #392, below). Of the 35 on public routes, 10 are false: 4 CSV exports and 6 OAuth2 endpoints whose bodies RFCs define. fastapi-clean-example's 11 were routes with description=getdoc(...); FastAPI reads a docstring only when description= is absent (Path Operation Configuration), so description= now counts as one. A router that every followed inclusion puts under a FastAPI(openapi_url=None) app stays hidden when another inclusion can't be followed; without that, Polar's back office added 115 false findings.
• FAPI002. Still silent on both: Polar includes its API router through a parameter of add_versioned_routers(app, api_router, ...) and some routers through factory calls, and fastapi-clean-example includes every router through a factory call, so the inclusions above their routes are unknown. #391 follows them (below).
• INW012. 107 of Polar's 135 findings are in the back office; the 17 false ones in the sample are 15 server-rendered pages and HTMX form handlers there, a server-sent event stream and a webhook (#360).
• FAPI003, FAPI005. Recognising more routers first added false alarms: FAPI003 warned that 72 of Polar's routers were unmounted, because the same unknown inclusions hide how they are wired (followed since #391, below), and FAPI005 reported 2 routes Polar's route class dispatches by API version (#392). A router a first-party class or factory builds is now unknown to both: FAPI003 skips it while an inclusion it can't follow could include it or a router above it (a factory call only the routers that factory returns, any other target any router), and FAPI005 doesn't read its route order. Routers FastAPI's own constructor builds keep the older answers.

The cost, from source on the laptop above, median of 3 cold runs on Polar with one rule on: INW012 1,118 → 1,401 ms, FAPI001 1,195 → 1,457 ms, FAPI002 1,188 → 1,725 ms (base develop at c38c5ae), for the 525 more path operations each rule now reads.

Inclusions through parameters and factories. #391 follows one hop of first-party code: app.include_router(api_router) inside a function, to what each call of the function passes, and include_router(make_router()), to the router the factory returns (FAPI003's page has the rules). Same method, Polar, fastapi-clean-example and full-stack-fastapi-template rerun on 2026-10-11 against develop at cf127b7 with FAPI001 to FAPI009 on:

• FAPI003. With every inclusion followed, FAPI003 judges Polar's 72 routers instead of skipping them as unknown, and an app reaches each one: no finding, and none of the 72 false "unmounted" warnings the #358 run showed before its fix.
• FAPI001. Following add_versioned_routers(app, api_router) puts Polar's API routes under create_app()'s FastAPI(openapi_url=None), which hid all 131 findings. FastAPI's openapi_url=None only stops FastAPI serving the schema; Polar serves /{version}/openapi.json itself from the same routes. An app that adds a route of its own ending in openapi.json now counts as serving a schema, which brings back the same 131 findings, and Polar's back office (no such route) stays hidden.
• FAPI002. Polar's 1 finding is true: OAuth2 authorize raises 401 and declares no responses. Most of its other routes raise PolarError subclasses, mapped by handlers registered in add_exception_handlers(app), a parameter FAPI002 doesn't follow, and answering exc.status_code (#400). fastapi-clean-example's routers are built by a factory around a third-party ErrorAwareRouter, whose keywords are unknown, so its declared responses are too.

Cost: 9 cold runs on Polar with every FAPI rule on, alternating with develop at 9ac26f7 (after #402): median 1,565 ms before and 1,619 ms after, fastest run 1,466 and 1,487 ms, within this laptop's noise. The project scan for a function's calls parses only the files that spell its name.

Route classes. #392 reads what a router's route class does, from route_class= or a first-party router class that sets it (FAPI001's page and FAPI005's have the rules). The issue weighed three options: a per-rule option naming the tags that keep a route out of the schema, treating every first-party route class as unknown, or leaving it to modules and suppressions. Reading the class's own code needs no configuration and stays silent wherever it can't read the class, so that is what shipped. Same method, Polar on top of #391:

• FAPI001. Polar's IncludedInSchemaAPIRoute sets include_in_schema to settings.is_development() for a route tagged APITag.private, True for APITag.public and False otherwise, private checked first. All 101 findings that went away are on private routes: the 96 counted above, and 5 the #358 count put among the public ones, which carry tags=[APITag.private] on the decorator under a public router. The 10 false positives left are the same 4 CSV exports and 6 OAuth2 endpoints whose bodies RFCs define. Polar's 77 API routers read as "schema by tags"; its 22 other apps and routers use FastAPI's defaults.
• FAPI005. The 77 API routers' route class includes VersionedAPIRoute, which overrides matches, so their order stays unread, and the 2 version-split pairs in webhook/endpoints.py stay silent. Before, every router a first-party class built was unread (#358). Now the back office's routers, whose route class is TransactionalAPIRoute (it only wraps the handler), are read too, with no findings. tests/kit/test_versioning.py's 3 pairs are in a test module, which the corpus layering ignores.
• fastapi-clean-example and full-stack-fastapi-template didn't change: their routers use FastAPI's route class or come from factories.

Cost. Every rule alone on top of the manifest layering, cold (--no-cache) and warm, median of 5 runs (3 for polar and saleor), with the darwin-arm64 binary on the laptop above while other agents ran (load average 5 to 11). Milliseconds, cold / warm:

The other FAPI rules cost about what FAPI001 does. The warm column barely differs, because the extraction cache holds imports, not the trees the content rules parse. Three costs stood out:

• INW012 on Saleor took 8.0 s, against 1.1 s without it (both run from source): nearly every file mentions Django, so each got a full parse, and each class with a first-party base read that base's module. A Django file now needs a view's shape before the parse (@api_view, @action, path(...), re_path(...) or a def get(-style handler method, unless modules scopes the rule), and only a class with a handler method resolves its bases. Saleor with INW012 went to 1.3 s, with the same 2 findings.
• INW013 on Polar took 7.8 s, about 13 times the check without it: a hop into another module parsed that module again for every file that called into it. Since #359, each module a hop reads is parsed and read once per run, a call to a method of a module-level object (service.create(...)) reads nothing, a checked file a hop already parsed isn't parsed again, and the walks over a function body run inside WASM. Measured before and after in one sitting, alternating the two binaries, median of 5, cold / warm: Polar with INW013 went from 7,238 / 6,971 ms to 3,526 / 3,182 ms, and with every opt-in rule from 8,790 / 9,068 ms to 4,984 / 5,052 ms, against 454 / 321 ms with none. The other four repos moved by less than 10 ms, and the JSON findings are identical. That left about 3 s: 865 of Polar's 1,831 files have an async def, and each got a full parse. Since #369, a run where at least 200 files, and one in 20, have an async def reads every listed module's text once, parses only the modules whose imports can spell a blocking type (22 on Polar), and skips a checked file that names neither a blocking type nor one of their blocking helpers or its aliases. Same method, base develop at 06c400d, cold / warm: Polar with INW013 went from 3,643 / 3,507 ms to 729 / 549 ms, against 548 / 353 ms without it (+33 %), and with every opt-in rule from 5,270 / 4,963 ms to 2,329 / 2,105 ms. Saleor (12 files with an async def) and the three small repos stay below the threshold and moved by less than the noise, and the one-file check of subscription/service.py stayed at 153 ms. The JSON findings are identical on all five repos, and on a copy of Polar with blocking helpers called through renaming re-exports, module aliases, relative imports and a passed Session.
• Every opt-in rule on Polar still took 2.3 s after #369, about 5 times the check without them: INW012, INW014, INW015, INW016, FAPI007 and the FastAPI model each parsed the files they read on their own, 848 parses of 450 distinct files. Since #387, a run parses each text once (ModuleTrees.treeOf), whichever of those rules or a hop into another module asks first, and frees every tree when the run ends. Polar now makes 450 full parses on the main thread (about 490 ms of parse time). Same method, base develop at 0596d16, median of 7, cold / warm: Polar with every opt-in rule went from 2,343 / 2,256 ms to 1,925 / 1,789 ms, against 455 / 322 ms with none, so 4.2 times the check without them, not the 2 times #387 aimed for. Parsing those 450 files alone costs about what the check without the rules does, and the rules' own work (the FastAPI model and graph, INW012's views) is most of the rest; going further needs the content rules off the main thread or cheaper rule code. Peak RSS stayed within the noise (567 to 574 MB). Saleor (2,102 to 2,067 ms cold) and the three small repos (10 to 15 ms faster) moved little, and the one-file checks of subscription/service.py (176 to 158 ms) and subscription/endpoints.py (84 to 78 ms) got faster. The JSON findings are identical on all five repos, with no opt-in rule and with every one.
• Every opt-in rule on Polar took 2.4 s again after #394 taught the model Polar's router class built at run time: the rules read 525 more path operations, and FAPI001 builds the router graph for them. A CPU profile of that run (bun --cpu-prof) showed about 0.65 s of parsing on the main thread and the rest spread over the rules. Since #395, four costs are gone. FAPI002 followed nearly every call in an endpoint into the module that defines its receiver (items.load(...) into the service module) and parsed that module only to find the name isn't imported there; the model now reads such a module's imports from its import skeleton and parses it only when an import binds the name, which skips 123 of the model's 329 parses on Polar. A function's return annotation is resolved only when the function returns a name the file uses as a router, since -> Subscription parsed the models. INW012 built its views of other modules once per checked file and now builds them once per run (ThinEndpointRun). The FastAPI model, INW012, INW016 and FAPI007 walked each shared tree for calls, assignments and definitions several times; moduleNodes walks a tree once for all five node types and keeps the lists while the tree lives. darwin-arm64 binaries, base develop at cf127b7, alternated, median of 7, cold / warm: Polar with every opt-in rule went from 2,443 / 2,352 ms to 1,901 / 1,795 ms, against 474 / 319 ms with none, so 4.0 times the check without them, still short of the 2 times #395 asks for. Parsing the files the rules need costs about 0.5 s on the main thread, which is more than a 2-times budget leaves for all of the rules' work, so going further needs the content rules on the worker threads. Saleor went from 1,286 to 1,167 ms cold (770 ms with none), and the three small repos got 11 to 14 ms faster. Peak RSS stayed within the noise (670 to 647 MB on Polar). The one-file check of subscription/endpoints.py went from 831 to 658 ms and its PostToolUse hook from 1,608 to 1,256 ms, both still far over the hook budget because FAPI001 builds the whole router graph for that file; subscription/service.py stayed at 156 ms. The JSON findings are identical on all five repos, with no opt-in rule and with every one.

The hook. #182 asked for no measurable hook regression on files without endpoints and one full parse at most on files with them. inwards check --no-cache <file>, 21 alternating runs each, milliseconds p50 / p95:

Before the Django prefilter, order/actions.py took 53 / 54 ms with INW012 on. A file with endpoints pays one full parse, which the prescan otherwise skips.

Performance roadmap¶

Reproduce¶

bun install
bun test                                                    # 2,500+ tests: unit, CLI, hook, Stop gate, baseline, stats, E2E snapshots, doc snippets, bench
bun run scripts/build-binaries.ts bun-linux-x64
python3 bench/generate.py /tmp/inwards-bench
(cd /tmp/inwards-bench && "$OLDPWD/dist/inwards-linux-x64" check)  # 2100 files, 0 violations, ms
bun run src/core/scripts/prescan-diff.ts "$(python3 -c 'import sysconfig; print(sysconfig.get_paths()["stdlib"])')"
bun run bench/corpus.ts --bin dist/inwards-linux-x64 --dir ~/.cache/inwards-corpus  # real-repo corpus, about 90 s

bench/corpus.ts reuses a checkout that is already at its pinned commit, so later runs download nothing. To add a repo, append it to bench/corpus.json with a full commit SHA, its .py count and a layering; the PR runs the corpus workflow.

Two checks keep the agent-facing tests honest. A code fence in docs/chapters/guides or docs/chapters/rules that follows a <!-- e2e --> line and one blank line (without it, the comment breaks a list item) runs as an E2E case in a fresh project, against the compiled binary in CI (src/cli/test/integration/docs.test.ts); untagged fences are never run. The fences run in the system's bash, which on macOS is bash 3.2, so the harness never puts a heredoc inside $(...): bash 3.2 matches quotes across it, and one apostrophe in a documented message breaks the script. Every night, .github/workflows/nightly-e2e.yml records the Claude Code hook payloads again with a headless claude -p session and opens an issue when a field is added, removed or changes type against the recorded fixtures.

The screenshots in these docs come from scripts/screenshots.py, which runs each command for real and renders the terminal output with Rich.

Risks¶