fix(pycg)!: decide shard outcomes by convergence, not wall clock

[rahlk]

Closes #145.

Problem

Sharded PyCG decided which shards to keep by wall-clock timeout, and a
timed-out shard contributed zero edges. Which shards run slow depends on
machine load and Ray scheduling, so byte-identical invocations produced
different call graphs — measured on a 2,364-file dependency-closed Odoo subset
with --no-venv --pycg-shard --ray:

run	edges	jedi	pycg	jedi,pycg	externals
-a 2	48,595	26,309	18,962	3,324	4,492
-a 2 (repeat)	43,431	27,720	13,751	1,960	3,340
-a 4	40,224	28,046	10,529	1,649	2,881

An 11% spread overall; PyCG's own contribution swings 44%.

The issue as filed asked for the incompleteness to be reported in the payload.
That was rejected: a self-describing non-deterministic output is still
non-deterministic. This removes the load-dependence at its source.

The fix

PyCG's loop is
while (max_iter < 0 or iter_cnt < max_iter) and not has_converged(), so shard
outcomes can be decided on convergence instead of the clock (55965a4):

• Shard outcomes now come from PyCG's own convergence — a function of the
  input alone, not of machine load.
• SIGALRM helper, Ray deadlines and ray.cancel removed from all four
  collection paths.
• A runaway — fixpoint stopped at --pycg-max-iter instead of converging, or
  raised — is re-partitioned at a tighter file budget, as before; a shard that
  cannot be split further keeps the edges it derived instead of contributing
  zero. A capped fixpoint is a sound under-approximation, so those edges are
  real.
• _PYCG_DECOMP_FLOOR 10 → 1: a floor of 10 left small runaways unsplittable.

Correction to a claim in the first commit message. It argues the clock
bound was redundant because --pycg-max-iter already guarantees
termination. That is wrong; the message is left as-is for history and
corrected in 7a71a6d. The cap bounds fixpoint passes, and PyCG consults it
only between passes, so a single expensive pass escapes it — one 100-file
shard has run for over an hour inside its pass budget without completing, even
seed-pinned. Removing the timeout removes the only wall-clock bound that
existed. It had to go — it decided output by machine load — but nothing
replaces it yet: #148 tracks a deterministic fallback that routes
predicted-expensive shards to Jedi-only coverage, with the degradation visible
in prov.

A reverted experiment sits in this branch's history. 98ecf05 switched
capped shards to be kept whole instead of re-split, on a measurement showing
splitting "destroyed edges". That comparison was confounded — the whole-shard
run completed three fixpoint passes while the halved run was cut off by the
measurement harness after one, so it compared different analysis depths — and
the entire series ran with an unpinned hash seed (see Measurement caveat).
A depth-matched control favored re-splitting. cfd4d75 restores the
reviewed behaviour: capped → re-split, irreducible → keep partial edges.

Reading convergence correctly

_analyze_with_convergence() is not a post-hoc has_converged() call. Two
traps, both covered by tests:

• Asking after analyze() returns is wrong — analyze runs a
  CallGraphProcessor pass past the loop, so a post-hoc call compares state
  that pass has already moved and reports divergence for a converged shard.
• The loop's last recorded value is also wrong — when the cap stops the
  loop the and short-circuits, leaving the False that admitted the final
  pass, mislabelling a shard that converged on exactly pass max_iter.

So the cap is raised by one and the loop cut off from inside the check: one
extra question, not an extra pass.

Breaking change

--pycg-shard-timeout is removed. It is the defect, and after this change
it controls nothing. --pycg-max-iter remains the knob trading recall against
runtime — but it caps fixpoint passes, not their duration, so no setting of
it bounds wall-clock time, and --pycg-max-iter -1 (run to convergence) can
run indefinitely.

Scope — what this does NOT claim

This removes the load-dependent shard-dropping mechanism, the 11% effect #145
was filed for. Output is not yet byte-identical across runs. A separate,
~100x smaller source remains in Jedi's overload resolution for open():
f.read() resolves to _TextIOBase.read or _BufferedIOBase.read depending
on the run, accounting for 0.1–0.3% of edges on the Flask fixture. Filed as
#146 with a full four-way matrix (sequential/Ray × max_iter 3/50)
showing it is independent of sharding, Ray, and the fixpoint cap.

I was not able to obtain a completed Odoo run demonstrating the fix
end-to-end at scale — every attempt was killed, capped, or interrupted, and a
seed-pinned attempt at one shard did not finish within an hour (the liveness
gap #148 exists for). The fix rests on the mechanism being structurally
removed plus tests asserting it, not on a before/after Odoo comparison.

Measurement caveat

Two things poisoned nearly every standalone measurement taken during this
work:

• Unpinned hash seed. The CLI pins PYTHONHASHSEED=0 by re-exec
  (_pin_hash_seed), but only when argv0 is the CLI. Standalone probes
  import the library, so they ran with a random seed — and PyCG iterates
  hash-ordered containers, so edge counts and per-pass cost both swing with
  the seed: the same shard at the same settings produced 115,904 / 110,490 /
  73,957 edges across probe runs, completing in minutes on one seed and
  running 80+ minutes on another. Library consumers get no pin either — any
  import-based harness must set the seed itself before its numbers mean
  anything.
• Machine state. Two dramatic wall-clock anomalies were the laptop lid
  being closed mid-run.

Earlier drafts of this PR quoted figures from that series; all are removed.
What remains — the #145 spread table (real, seed-pinned CLI runs), the
structural removal of the timeout, and the tests — is deterministic and
verifiable.

Tests

test/test_pycg_shard_determinism.py (16 tests), including:

• a whole-module sweep asserting no SIGALRM, signal.alarm, ray.cancel or
  shard_timeout remains reachable — the timeout was reachable from four
  collection paths, so a check scoped to one function would pass while another
  still dropped shards by the clock;
• unit tests for _analyze_with_convergence against a fake with PyCG's exact
  loop shape: converged, capped, the exactly-at-cap boundary, the
  post-loop-pass trap, unbounded max_iter=-1, degenerate max_iter=0, cap
  restoration, and restoration when analyze() raises;
• both the sequential and Ray paths checked for runaway classification and for
  the irreducible-shard-keeps-partial-edges behaviour — a change applied to
  one runner only would silently leave --ray on the old behaviour.

Full suite: 305 passed, 6 skipped.

Docs

• README.md: new Why sharding? section under Analysis levels
  explaining the cost curve and the ~75% edge-cut price, in plain language.
• README.md: --help block regenerated via scripts/update_readme.py — it
  still advertised --pycg-shard-timeout, which this PR removes.
• CHANGELOG.md: the breaking removal and the fix, with the
  no-termination-guarantee caveat, the L2 call graph is not byte-reproducible: Jedi overload resolution for open() varies run to run #146 scope note, and the Replace PyCG with a per-callable defuse linker (Jedi stays the base call graph) #148 link.

[rahlk]

Closing unmerged: the 2026-08-25 design session decided to remove PyCG entirely rather than fix its shard-outcome semantics — see docs/design/specs/2026-08-25-defuse-linker-call-graph-design.md (committed on feat/issue-148-jedi-only-call-graph) and the repurposed #148. The determinism analysis in this PR (wall-clock shard dropping, the 11% spread, the max_iter termination caveat, the seed-pinning probe trap) remains the evidence base for that decision; the branch commits stay in the successor branch's history.