write-bundle

write-bundle

Call the obsidian-router write_bundle MCP tool. It runs a list of writes as one journaled operation: every target's content is captured before the first write, and if any step fails, every file the bundle touched is put back byte-for-byte.

When to use

Whenever one user-visible action produces several files whose half-written state would be wrong:

• save — the note + the journal line + hot.md
• wiki-ingest — the source page + entity pages + the journal
• wiki-fold — the fold page + the log rewrite
• any multi-key frontmatter update that must not land halfway (this is what makes merge_frontmatter all-or-nothing — see below)

For a single file, use the ordinary write-append / write-create-or-replace / write-patch. A bundle around one write buys nothing but a journal round-trip.

Arguments

Required: steps — an ordered array, at most 25. Each entry is { op, path, ...that op's own arguments }.

op	runs	needs
write	write_file	content
append	append_to_file	content
patch	patch_file	operation, targetType, target, content
set_frontmatter	set_frontmatter	key, value
merge_frontmatter	merge_frontmatter	values
delete	delete_file	confirm: true

Optional: vault (omit for default — a bundle is single-vault, steps may not override it) · preview: true (sealed plan, writes nothing) · approvedPlanSha256 (the seal from a preview) · recover (see below) · per-step ifMatch.

move is deliberately not a bundle step: a half-rolled-back move is worse than no rollback. Express it as a delete plus a write.

What it guarantees — and what it does not

✅ No silent in-between. outcome says exactly where you landed (four values, below). Read it; do not assume success. ✅ Crash survival. The before-images are written to wiki-meta/write-journal/<operationId>.json before the first mutation, so a rollback is still possible after the process dies. A journal is deleted — or, if that fails, stamped terminal — once the operation reaches a proven end, so it can never be replayed against a bundle that already succeeded. It stays pending (and recoverable) whenever the end was not proven. ✅ Nothing is destroyed without a copy. If a rollback has to overwrite content it cannot attribute, the exact bytes it is about to overwrite are saved into the journal first — and if that copy cannot be saved, the overwrite does not happen at all. ✅ Group-wide C1. Put ifMatch on the steps that matter: every precondition is checked up front, so a bundle whose targets moved refuses entirely, before writing anything. ✅ Concurrent writers are detected, not assumed away. For write and delete steps the bundle knows the exact result it produced, so a read-back that disagrees is proof someone else wrote — that file is then left alone for the rest of the operation, rollback included.