docs: add @mode tags + enrich JSDoc on harness event declarations

Annotate all 24 harness events across the 5 event-declaring packages with
an explicit `@mode emit|waterfall|parallel` tag and self-contained JSDoc, so
the generated cordis catalog can render each entry's mode and prose from
source alone.
This commit is contained in:
Tianyi Cui
2026-06-20 19:21:42 +08:00
parent 9949f4f2ea
commit ee494969af
5 changed files with 102 additions and 22 deletions

View File

@@ -23,15 +23,24 @@ declare module 'cordis' {
}
interface Events {
/** A session was created in the store. */
/**
* A session was created in the store.
* @mode emit
*/
'session/created'(session: Session): void
/** An event was appended to a session log (sync, fire-and-forget). */
/**
* An event was appended to a session log (sync, fire-and-forget). This is
* the per-append feed a UI or invariant plugin tails.
* @mode emit
*/
'session/event'(session: Session, event: SessionEvent): void
/**
* Awaited durability checkpoint. The agent loop awaits
* `ctx.parallel('session/flush', session)` at every turn end; persistence
* plugins (JSONL, SQLite) drain their write-behind
* buffers here and on fiber dispose.
* plugins (JSONL, SQLite) drain their write-behind buffers here and on
* fiber dispose. Awaited (parallel), not a waterfall: every listener runs
* and the loop waits for all of them, but none can veto.
* @mode parallel
*/
'session/flush'(session: Session): Promise<void> | void
}