Module debounce

Expand description

§Module: debounce

Provides a shared typing-debounce mechanism used by all editor plugins (JetBrains, VS Code, Neovim, Zed) so they share identical timing logic via the agent-doc FFI layer.
In-process state: a Mutex<HashMap<PathBuf, Instant>> (LAST_CHANGE) records the last edit timestamp per file path.
Cross-process state: each document_changed call also writes a millisecond Unix timestamp to .agent-doc/typing/<hash> so CLI invocations running in a separate process can detect active typing. The hash is derived from the file path string via DefaultHasher. Cross-process writes are best-effort and never block the caller.
is_idle / await_idle operate on in-process state (same process as the plugin).
is_typing_via_file / await_idle_via_file operate on the file-based indicator (CLI use).
Files with no recorded document_changed call are considered idle by is_idle; this prevents await_idle from blocking forever on untracked documents.
is_tracked distinguishes “never seen” from “seen and idle” for non-blocking probes.
await_idle polls every 100 ms and returns false if timeout_ms expires before idle.

document_changed(file: &str) — records now as last-change time; writes typing indicator file (best-effort); never panics.
is_idle(file, debounce_ms) -> bool — true if elapsed ≥ debounce_ms or file untracked.
is_tracked(file) -> bool — true if at least one document_changed was recorded.
await_idle(file, debounce_ms, timeout_ms) -> bool — blocks until idle or timeout; 100 ms poll interval.
is_typing_via_file(file, debounce_ms) -> bool — reads indicator file; false if absent or timestamp older than debounce_ms.
await_idle_via_file(file, debounce_ms, timeout_ms) -> bool — file-based blocking variant.

idle_no_changes: file never passed to document_changed → is_idle returns true
not_idle_after_change: immediately after document_changed with 1500 ms window → false
idle_after_debounce: 50 ms sleep with 10 ms debounce → is_idle returns true
await_immediate: untracked file, await_idle → returns true in < 200 ms
await_settle: document_changed then await_idle with 200 ms debounce → waits ≥ 200 ms
typing_indicator_written: document_changed on file with .agent-doc/typing/ dir → is_typing_via_file returns true within 2000 ms window
typing_indicator_expires: 50 ms after change with 10 ms debounce → is_typing_via_file returns false
no_indicator_file: nonexistent path → is_typing_via_file returns false

await_idle: Block until the document has been idle for debounce_ms, or timeout_ms expires.
await_idle_via_file: Block until the typing indicator shows idle, or timeout.
document_changed: Record a document change event for the given file.
get_status: Get the response status for a file (in-process, Option B).
get_status_via_file: Get status from file signal (cross-process, Option A).
is_busy: Check if any operation is in progress for a file (in-process, Option B).
is_idle: Check if the document has been idle (no changes) for at least debounce_ms.
is_tracked: Check if the document has been tracked (at least one document_changed call recorded).
is_typing_via_file: Check if the document has a recent typing indicator (cross-process).
set_status: Set the response status for a file.