From 8d7870a11f2e0d24f7ba64813c33775643584ba8 Mon Sep 17 00:00:00 2001 From: Shashank Shekhar Singh Date: Sat, 26 Sep 2026 18:33:31 +0530 Subject: [PATCH] 0.1.8: the session reclaim, and the widened styling gate #127 and #126 merged after the release commit and neither is in the notes. 0.1.8 is still unpublished and untagged, so folding them in is correct for the same reason #124 did it for #123. The reclaim gets a full entry: it changes shipped behaviour and adds a public method, and the entry is explicit that it closes a documented *limitation* rather than a defect -- which comes to the same thing for whoever hit it. What it refuses, and why nothing calls it automatically, are the load-bearing parts and are stated. The styling gate goes in the tooling paragraph, where it belongs: it changes no shipped behaviour, it changes what a regression in shipped behaviour would be caught by. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 25b585d..a5731f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ Entries are newest-last within a release, matching the order they were written. - **an interrupt landing inside the deadline guard's own teardown left a timer raising into the thread forever.** `fire` queues its asynchronous exception while holding the guard's lock, so a guard already blocked on that same lock inside `disarm` is handed the exception the moment it acquires it — at the next bytecode, which is before `armed` is cleared and before the re-armed timer is cancelled. `disarm` propagated, and the 50ms timer it was meant to cancel stayed alive still reading `armed` as true: it re-raised `NodeDeadlineExceeded` into that thread every 50ms for the life of the thread, long after the run that armed it had finished. On a pooled thread that is an unattributable crash in whatever ran next — which is precisely what `test_no_interrupt_survives_the_node_that_earned_it` exists to rule out, reached by a path it did not cover. The lock was never the flaw: both sides do take it, and what a lock cannot do is stop an asynchronous exception arriving between two bytecodes inside the section it protects. The teardown is retried rather than abandoned now, and clears `armed` outside the lock as a last resort, that single store being what stops `fire` re-arming; swallowing the interrupt there costs nothing, because the guard still decides the outcome from whether the timer fired and still raises on it. The SIGALRM mechanism is unaffected — CPython runs the Python-level handler at a bytecode boundary, so `setitimer(ITIMER_REAL, 0)` has already completed when the handler raises. - **the lockfile's copy of the version drifted, twice, unnoticed.** `ci.yml` checks that `pyproject.toml` and `grapharc.__version__` agree, and its comment says why: if they drift, `pip show` and `import` disagree about what is installed. There is a third copy — `uv.lock` carries an entry for this project — and both 0.1.6 and 0.1.7 shipped with it reading `0.1.5`, because nothing re-locked after the bump and no job looked. Milder than the other two, since it misreports the project to a reader of the lockfile and to `uv sync --locked` rather than to an installed import, but the same class of bug as the one that step already guards. The check now parses `uv.lock` as well, names `uv lock` as the remedy, and refuses anything other than exactly one entry for the project so a rename cannot make it silently vacuous. - **an imported retraction came back as current on the LadybugDB backend.** `superseded_by` was reconstructed from the `SUPERSEDED_BY` edge, and `add()` cannot create an edge towards a claim the store does not have yet — in the natural import order it does not have it, because `all_claims()` returns oldest-first, so a superseded claim arrives before the claim that superseded it. The edge was skipped while `superseded_at` was written, so one row said both things at once: `superseded_at` said retracted and `superseded_by IS NULL` said current, and `Claim.is_current` believed the second. `current("svc")` — which is supposed to answer "what is true now" — returned *both sides of a correction*, and the two other backends disagreed with this one. Every import, replay, backup restore and copy between backends went through that path; `supersede()` never did, which is why every test that exercised it passed. `superseded_by` is a column now and the edge is derived from it: reads project the column, `current()` filters on the column rather than on an `OPTIONAL MATCH`, and `_write` reconciles the edge in both directions — forward when this claim names a superseder that is present, backward when a stored claim names *this* one and could not have an edge until now — so the edge is complete once both ends have arrived, whatever order they arrived in, and it stays walkable for the Cypher path this backend exists for. Two alternatives were costed and rejected: failing closed breaks replaying `all_claims()` in the order it hands you, and a stub target node reads back as a `ValidationError` and has no `seq`. The column needs a schema change, which `CREATE NODE TABLE IF NOT EXISTS` will not perform on an existing database, so opening one adds the column and backfills it from the edges an older database does have — `supersede()` always wrote those. What `add()` dropped is not recoverable; what the edges recorded is. +- **a session whose runner died stayed wedged forever.** Not a defect so much as a limitation the package documented and then could not do anything about, which comes to the same thing for whoever hits it. A runner's claim on a session is a compare-and-set, not a lease: it stops a *second* runner from claiming a session and cannot notice one that died holding it. So a crash mid-turn left the row `running` — with the dead `runner_pid` still on it, meaning the store knew exactly who died — and every later `Session.run()` raised `SessionBusy` for the life of the file. The only remedy was a hand-written `UPDATE`, which skips the lifecycle validation and writes no transition row, corrupting the audit trail the store exists to keep. `SessionManager.reclaim(session_id)` releases one deliberately now: it refuses unless the recorded pid is gone from this host, moves the session to `failed` — not `interrupted`, because a turn that died left no point to be picked up from — and records the release as a transition naming the dead pid, so the reclaim is in the history rather than hidden from it. **An open approval hold survives**, so reclaiming a wedged session is not a way past a human. Four things are refused, each deliberately: a session that is not running, a pid that is still alive (or belongs to another user, which is read as alive), a pid that is this process, and a `running` row carrying no pid at all. Pid reuse is not solved and is not pretended to be — a recycled pid reads as alive, which is a refusal, and that is the direction to fail in. Nothing calls this automatically for the same reason: an automatic sweep would be a way for two live runners to fight over one session, which is what the claim exists to prevent. Tooling, in the same release and not defects in the shipped package: the suite now runs weekly against dependencies re-resolved from scratch rather than only @@ -26,7 +27,11 @@ figure in the deep dive can be re-derived with hand: the check stays strict in CI, but it had been failing every branch that added a test until someone hand-edited a number in a docs file they had no reason to know existed, which cost an outside contributor's first pull request -a month of being red for a reason that was not its code. +a month of being red for a reason that was not its code. The styling gate — that +stripping the escapes from terminal output reproduces piped output exactly — now +covers `run`, `trace` and `metrics` as well as the four commands it started +with; those three are the ones most likely to be piped, and a leak confined to +any of them left the old gate entirely green. ## 0.1.7