The Transaction Behind Every Safe Change
In claude-obsidian, changing a note is not treated as replacing one file and hoping the surrounding knowledge catches up. The specific problem is how to change related pages, indexes, ledgers, and source metadata while preserving ownership and recoverability. This chapter traces the project’s transaction mechanism so readers can understand what review actually binds, why concurrent changes become conflicts, and why an interrupted operation is recovered rather than quietly ignored.
A transaction is a promise about recovery
A knowledge operation often has more than one visible consequence. Ingesting a source may create an immutable raw capture, add a source record, write a concept or question page, update an index, append an operation log entry, and refresh bounded context. Saving a selected answer may require a note, an index entry, a log entry, and hot context. If each file is changed separately, each file can be valid while the overall vault tells incompatible stories. A page may point to a source record that was never written, or an index may advertise a note whose creation stopped halfway through.
Imagine that an ingest has successfully written the page but fails before recording its source ledger entry. A reader can see a polished note, yet cannot tell which source it represents or whether its evidence was reviewed. If the ledger is written first and the page fails, the vault may advertise a page that does not exist. If the raw capture is replaced while the page remains, the claim may now point to bytes that were never the basis of the original synthesis. The problem is not that any one file is malformed. It is that the meaning of the files depends on their relationship.
The transaction core addresses that problem at the level of a logical operation. A bundle declares the operation’s identity and type, the expected hash of every target, and the new content to be written. It can also carry managed requests for things such as source-manifest updates or allocated page metadata. The important unit is not “one file write.” It is the complete set of related state that must move together for the operation to make sense.
This is an honest contract, not a magical claim of multi-file atomicity. Ordinary filesystems generally do not provide one indivisible primitive that replaces an arbitrary collection of files at once. The core instead combines a process-held mutation lock, precondition hashes, a durable journal, atomic replacement for each file, and deterministic rollback or recovery for the operation as a whole. Per-file replacement protects an individual write; the journal records enough state to finish or undo the larger logical change.
The bundle’s operation type narrows what it is allowed to touch. A capture operation can create content-addressed raw payloads, but cannot replace an existing raw source. A Canvas operation is confined to the Canvas area and its optional catalog. A fold operation must include its fold page, index, and log rather than writing an arbitrary collection of files. Wiki-only operations remain under the wiki area. These are not labels for humans to interpret after the fact; the core enforces them while preparing the writes.
Scope matters because a reviewed operation should have a legible consequence.