Module events 

Event append primitive + seq recovery (design.md §1.4, §4).

Structs

AppendResult

Outcome of an append_and_apply_event call.

PriorEvent

A prior event located by find_prior_with_key. Carries enough to let an idempotent-retry caller both return the recorded seq and verify the retry payload matches what was originally written.

Quarantine

Outcome of a quarantine_corrupt_lines call that removed at least one poison line. backup_path is the renamed copy of the original log (kept verbatim for operator forensics / hand-repair); removed_byte_offsets are the start offsets, in that original, of every newline-terminated line that failed to parse as an Event and was excised from the recovered events.jsonl.

Enums

AppendOutcome

The three observable outcomes of an append_and_apply_idempotent call — the shared --idempotency-key contract that event create, discussion resolve, and future keyed verbs (spinoff approve|reject, run create, node report) all answer to, lifted out of each CLI’s private log scan.

Functions

append_and_apply_event

The one canonical mutation entry point: append a single event to events.jsonl and fold it into the projection files via the reducer, all under the run’s flock, with idempotency-key dedup.

append_and_apply_idempotent

Append one keyed event idempotently: scan for a prior event with the same kind + key, and either replay it, reject a conflicting reuse, or append fresh — the centralized --idempotency-key primitive (issue core-idempotency-api).

append_and_apply_unlocked

Append one event and fold it into projections. The _witness: &LockedRun is compile-time proof the caller already holds the run’s exclusive RunLock — obtained from RunLock::with_lock or RunLock::witness, so this entry point cannot be reached without the lock. The sanctioned lock-held composition path: use it to fold extra logic (an idempotency-key lookup, a status precondition) or several writes (the supervisor’s derived discussion/spinoff batch) into one locked critical section. Calling append_and_apply_event from within a held lock would deadlock because flock blocks when a second open of the lock file from the same process tries to acquire LOCK_EX.

find_prior_with_key

Stream-scan events.jsonl for the first event with matching kind and idempotency_key, returning a typed PriorEvent (or None when the log is missing or holds no such event).

quarantine_corrupt_lines

Heal a poisoned events.jsonl by excising its corrupt physical lines.

quarantine_corrupt_lines_unlocked

As quarantine_corrupt_lines but takes a &LockedRun witness proving the caller already holds the run’s exclusive RunLock — the sanctioned lock-held composition path, mirroring append_and_apply_unlocked. Re-entering quarantine_corrupt_lines under a held lock would deadlock on the second flock open.

read_all_events

Read every event from events.jsonl. Used by tests and reducer replays.

recover_last_seq

Read the last seq from events.jsonl, or 0 if empty/missing.