Expand description
Atomic multi-note write primitive: commits a set of notes — each with its
FTS document and every registered embedding model’s vector row — in ONE
writer transaction, instead of one create_note call per note.
Built for khive-pack-comm’s dual_write_message (outbound + inbound
copy of a comm.send/comm.reply), which previously cost roughly a
dozen separate writer acquisitions per send: two create_note_inner
calls (row + FTS + one vector insert per registered model each) plus a
root-send thread_id patch. Shaped as create_notes_atomic(Vec<AtomicNoteSpec>)
rather than a comm-specific pair primitive so other multi-write verbs
(memory.remember, gtd.assign) can adopt it later without a new type.
§Embed-first
Embedding is slow compute (network/model calls). Every note’s embeddings,
across every registered model, are computed before any transaction
opens — the writer is held only for synchronous DML, exactly like the
rest of the ADR-099 atomic-unit machinery (atomic_plan/atomic_runner).
This is the same reason atomic_prepare::prepare_add_note defers vector
indexing to a post-commit PostCommitEffect::ReindexNote; the difference
here is embeddings are computed before commit instead of after, so
the vector rows land in the SAME atomic unit as the note row and FTS
document, and no post-commit reindex is needed at all — every plan built
by create_notes_atomic carries post_commit: PostCommitEffect::None.
§One writer acquisition
Each note becomes its own AddNotePlan; every spec’s plan is applied by
ONE run_atomic_unit call — one khive_storage::SqlAccess::atomic_unit,
one writer checkout, one WAL commit for the whole set. A failure on any
note’s plan rolls back the ENTIRE unit (atomic_runner’s documented
guarantee: a later op’s failure unwinds even an earlier op’s own
already-RELEASEd SAVEPOINT), so a crash or guard failure partway
through never leaves an orphan copy — the process-crash gap the two-call
version of dual_write_message used to document is closed by
construction.
Structs§
- Atomic
Note Spec - One note to write as part of an atomic set. Mirrors the subset of
create_note_inner’s parameterscomm.send/comm.replyactually use — noannotates,salience,decay_factor,embedding_contentoverride, or explicitembedding_modelpin. A future caller needing those can grow this struct; none of khive-pack-comm’s call sites need them today.
Functions§
- create_
notes_ atomic - Build and commit
specsas one atomic unit. Returns the persistedNotes in the same order asspecs. On any failure — pre-write validation, embedding, or the atomic commit pass itself — NO note, FTS document, or vector row from any spec is left behind (embed failures occur before any write is attempted; commit-pass failures roll back the whole unit perrun_atomic_unit’s guarantee). - create_
notes_ atomic_ with_ report - The truncation-reporting form of
create_notes_atomic. The report covers every note/model embedding actually produced before the atomic commit and is returned only when the whole note set commits successfully.