Module debounce 

Module: debounce

Spec

• 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.

Agentic Contracts

• 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.

Evals

• 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

Functions

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.

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).