Harden the cache-key core, lock down the HTTP server, and fix concurrency edges (0.4.5)

[jolovicdev]

What

0.4.5 is a correctness and hardening release. The cache-key hashing is the whole
value proposition, and it had silent-correctness edges where a wrong answer
looked like a right one. The HTTP server had a real size-limit bypass and leaky
error responses. A few SQLite and Redis paths had concurrency and data-integrity
gaps. This fixes all of it, adds a regression test per fix (each verified to fail
without the fix) plus end-to-end smoke scripts, and tidies the README. 18
self-contained commits, each green on its own.

Cache-key correctness

• Objects without __dict__ are hashed by state, not memory address. Slotted
  value types, including @dataclass(slots=True), fell through to repr(), which
  embeds the instance address. Identical calls produced a new key every run (a
  permanent miss), and a lossy custom repr could collide (a wrong cached result).
  They are now hashed by their merged __slots__ and __dict__ state; a truly
  opaque object with the default repr warns instead of address-hashing.
• Referenced module-global containers invalidate like scalars. A function
  that read a global int invalidated when it changed, but a referenced
  dict/list/set did not. Value-stable containers are now hashed too, so
  config-style globals behave consistently.
• ResultRefs nested in custom-object attributes are recorded in lineage. The
  hasher descended object state but the input-ref collector did not, so a ref
  held as an attribute was in the cache key yet missing from the commit graph and
  could be garbage-collected out from under a commit. The collector now matches
  the hasher.
• Function source is canonicalized with ast.unparse, not ast.dump. The
  dump field set changes across Python versions (for example type_params in
  3.12), so the same function hashed differently on different interpreters and
  missed in mixed-version deployments. Unparse keeps the comment, whitespace, and
  docstring insensitivity but is source text and stable across versions.

Server hardening

• The request size limit is enforced on bytes received, not the
  Content-Length header. The old check trusted a header that is absent for
  chunked requests, so a client could stream an unbounded body and the handler
  buffered all of it. A pure-ASGI middleware now counts bytes as they arrive,
  rejects with 413 once the cap is exceeded, and replays the buffered body so
  handlers read it normally.
• Unauthenticated requests are rejected before the body is buffered. On
  token-protected servers the middleware now verifies the Authorization header
  and returns 401 before reading any body, so an unauthenticated client cannot
  force buffering up to max_content_length. The per-route check stays as defense
  in depth.
• Every handler validates input and has a generic error barrier. A bad
  ?limit=, a non-JSON /gc body, or any internal error surfaced as an uncaught
  500 (and the async commit/log/stats/gc handlers had no barrier at all, leaking
  through Starlette's default 500). All routes now map bad input to 400 and
  unexpected errors to a generic 500, and /gc accepts an empty body.

Store and Redis robustness

• The last_accessed_at bump on a cache hit is best-effort. That write runs
  outside the write lock, so a concurrent writer holding the lock past
  busy_timeout turned a successful cache read into an OperationalError. A
  locked database is now logged at debug and the cached result is still returned.
• A blocked post-eviction VACUUM no longer fails the eviction. Vacuum is
  best-effort space reclaim; a concurrent writer must not undo an eviction whose
  deletes already committed. It is now extracted and guarded.
• Redis tag index keys cannot collide. Presence and value indexes both built
  cashet:tag:{...}, so a tag key a:b collided with the tag a=b, and a : in
  any key or value could cross-match unrelated commits during delete_by_tags.
  The two now use distinct prefixes and the value key length-prefixes the tag key.
• The Redis blob delete is idempotent. The Lua script called DECR
  unconditionally; on a missing reference counter that yields -1, which is
  <= 0, so it deleted a blob another commit still referenced. It now returns
  early when the counter is absent.
• Running-claim lookup is O(1). find_running_by_fingerprint scanned a
  fingerprint's full commit history on every submit. A per-fingerprint running
  set, toggled on each status change, makes the lookup O(in-flight claims).

Smaller correctness and cleanup

• A lossy import is reported, not silently swallowed. A truncated archive
  dropped commits with missing blobs and returned only the imported count.
  import_archive now returns ImportResult(imported, skipped) and the CLI
  prints the skipped count.
• CLI show and get exit non-zero on a miss, matching rm, so scripts can
  detect a missing commit from the exit code.
• A failing parallel submit_many cancels its in-flight siblings instead of
  leaving them running and writing commits after the error is surfaced.
• Sync submit_many no longer recomputes the dependency graph that the async
  client already builds.

Behavior and migration notes

• The hashing fixes change function and argument cache keys, so results cached by
  earlier versions recompute on first access. Blobs are content-addressed and
  remain until garbage collected.
• The Redis tag index key scheme changed and is not migrated; rewrite affected
  commits to rebuild their tag indexes.
• import_archive returns ImportResult(imported, skipped) instead of a bare
  integer count; read result.imported.
• CLI show and get now exit 1 on a missing commit (was 0).
• On token-protected servers, unauthenticated requests now receive a uniform 401
  from the middleware, including for unknown paths.

Known limitations (deferred)

• Lease fencing for stale-claim reclamation is not in this release.
  Cross-process reclaim is already race-free: find_running_by_fingerprint is
  re-read inside the fingerprint lock each iteration, so two workers cannot both
  reclaim a stale claim. The only residual gap is a heartbeat stalling during an
  over-long task, whose worst case is duplicate compute (deterministic results
  overwrite identically), not corruption. A real fix needs a fencing token plus a
  schema migration on both backends, so it is its own change.
• UnhashableArgWarning reports its location inside the hasher rather than
  the submit() call site, because the hash runs many frames below submit (the
  same property as ClosureWarning). The message names the offending type, which
  is the actionable part.

Validation

• ruff check, pyright (strict), and the full pytest suite including Redis
  are green: 384 passed.
• Each fix has a focused regression test, verified to fail without the fix and
  pass with it. 14 end-to-end smoke scripts additionally exercise slot hashing,
  global-container invalidation, locked-DB reads, blocked VACUUM, tag collisions,
  Redis delete idempotency, the size-limit bypass and auth-before-buffer, handler
  validation, lossy import, CLI exit codes, ast canonicalization, the
  running-claim index, submit_many DAGs, and batch cancellation.

Docs

• CHANGELOG entry for 0.4.5 with a 0.4.4 to 0.4.5 compatibility note.
• README rewritten for clarity and cut roughly in half: removed the
  triple-documented HTTP server, consolidated the per-task option and
  serialization docs, and fixed the import_archive example.

Ships as 0.4.5.

🤖 Generated with Claude Code