Module request_ledger 

Request ledger of a serving process: counters, oldest pending request and last completions for doctor and health (#2197). Request ledger of a serving process (#2197).

A worker that stops answering looks the same from outside whether it is idle, saturated, or stuck in one handler. The ledger tells them apart without touching the request queue: it counts every admitted request and exactly one outcome per request, keeps the oldest pending request’s method and stage, and remembers the last tools/call completion separately from the last initialize.

Privacy: only method names (tools/call:ctx_read, never arguments, paths or content) are kept, truncated, and the pending set is bounded.

A serving process publishes its snapshot to <data_dir>/requests/<pid>.json from a dedicated thread, so lean-ctx doctor can read it even when every request worker is busy. In-process, the HTTP /v1/health route serves the same snapshot.

Structs

CompletionRecord

PendingRequest

PhaseRecord

RequestGuard

RequestLedgerSnapshot

One point-in-time view of the ledger. None fields are unknown or did not happen yet; renderers spell them out instead of guessing.

Enums

Outcome

How a request ended. Each admitted request ends exactly once.

Stage

Where a pending request is.

Constants

HEARTBEAT

A live publisher rewrites its snapshot at least this often, so a reader can tell a running process from a file a dead one left behind.

STALE_AFTER

Snapshots older than this belong to a process that is gone.

Functions

begin

Admit one request. The returned guard records exactly one outcome: the one passed to RequestGuard::finish, or Abandoned when it is dropped unfinished (the request future was cancelled or the client went away).

epoch_ms

Milliseconds since the Unix epoch, the clock snapshots are stamped with.

finish_serving

Shutdown of a serving process: persist the observations still queued for the detached writer (bounded by timeout) and withdraw this process’s published snapshot, so lean-ctx doctor does not list a stopped server. Runs once; later calls return at once. Blocking — call it from a plain thread or spawn_blocking, never directly on an async worker.

published_snapshots

Snapshots published by serving processes that are still running, by pid.

refused

Count a request turned away before admission (rate or concurrency limit).

serving

snapshot

The ledger now, without ages (a snapshot is a cacheable fact; ages are the reader’s arithmetic, see RequestLedgerSnapshot::with_ages).

start_serving

Mark this process as serving requests of kind: observations no longer block dispatch (#2196) and the snapshot publisher starts. Idempotent.