Module events 

Append-only change log and generation counter, so a poller notices a write without re-parsing every issues.org.

Two files sit beside the project directories:

• .vault-events.gen, a monotonic counter; comparing it against the last value seen is the cheap change check.
• .vault-events.jsonl, one event per line, read with a since sequence.

The names are fixed rather than derived from the product name: existing readers watch these paths, and renaming them would silence every poller.

Emission is best-effort and never fails a write. Set VISSUE_EVENTS=0 to turn it off, for a caller that needs the tracker to stay untouched.

Structs

Event

One entry in the change log.

Enums

TerminalWait

Outcome of wait_until_terminal.

Functions

emit_in

Append one event and return the new sequence.

emit_issues_write

Record that a project’s issues.org was rewritten. Called by the store after a successful write; failure here never fails the write.

emit_state_change

kind=state_change, id=Some(id), detail=Some(“FROM->TO”), project set. NOT debounced (unlike issues_write).

enabled

Whether emission is enabled. VISSUE_EVENTS=0 disables it.

ensure_gitignore_hint

Add the event files to a .gitignore that already exists beside them. Best effort: a tracker without one is left alone.

events_dir

The directory holding the event files: the same one holding the projects.

gen_path

Path of the generation counter file under dir.

generation

The current generation for this layout’s event directory.

generation_in

The current generation. A poller compares this against the last value it saw; a difference means something changed.

log_path

Path of the JSONL change log under dir.

ping_report

Append a manual event, waking pollers without touching an issues.org.

since

Events with a sequence above since_seq for this layout.

since_filtered_in

As since_in, narrowed to a project, a kind, or both.

since_in

Events with a sequence above since_seq, most recent last.

since_report

Text plus a trailing JSON block, the shape existing readers parse.

tail_in

The last n events in the log.

tail_report

The last n events, for a reader that only wants what is recent.

wait_generation

Block until the generation passes last, or the timeout expires. Returns the generation either way; the caller compares it against last to tell which happened. A timeout_ms of 0 is a peek: it never sleeps.

wait_until_terminal

Poll the issue state. Re-read on generation change or poll interval. Missing id is an error (IssueNotFound).