feat(mcp): expose and document checksum-guarded edit_note

[phernandez]

Summary

Expose Core's existing optimistic-concurrency capability through the MCP edit_note tool and document the contract.

This is separate from #1536, which is a Basic Memory Cloud bug: Cloud already exposes expected_checksum but currently ignores a stale supplied value on ordinary notes. Core's MCP tool does not currently accept a checksum argument at all.

Current state

• Core MCP edit_note exposes edit-operation controls such as expected_replacements, but no revision checksum precondition.
• Core's NoteContentMutationService.edit_note(..., base_checksum=...) already supports an optional accepted-content checksum and rejects stale values through the canonical accepted-note mutation transaction.
• The Core v2 PUT route exposes this as the x-bm-cloud-note-base-checksum header.
• The ordinary Core MCP edit path does not carry the precondition into that service.

expected_replacements is not a substitute: it verifies the number of textual matches, not that the note revision is the one the caller read.

Proposed MCP contract

Add an optional expected_checksum argument to Core edit_note:

• omitted: preserve current blind-edit behavior against the latest accepted note;
• supplied and current: apply the edit;
• supplied and stale: return a recognizable conflict and do not mutate the note;
• the checksum refers to the accepted canonical Markdown revision (db_checksum), not the materialized file checksum or a derived search projection.

The precondition must reach the existing transactional base_checksum enforcement. Do not implement it as only a read-before-write comparison, and do not add locks, retries, or a second concurrency mechanism.

Read contract

Ensure callers can obtain the correct checksum from the corresponding machine-readable Core read result. Use consistent naming or document the mapping clearly if the read response uses db_checksum while the edit input uses expected_checksum.

Documentation

Document:

• read → conditionally edit workflow;
• omitted versus supplied behavior;
• conflict response and required caller action;
• distinction from expected_replacements;
• distinction between accepted-content, file, and projection checksums;
• clients should re-read and deliberately rebase after conflict, not blindly retry a potentially destructive edit.

Update the MCP tool reference and generated schema/man-page coverage as appropriate.

Acceptance criteria

• Core MCP edit_note accepts optional expected_checksum.
• Fresh checksum succeeds.
• Stale checksum returns conflict and leaves content unchanged.
• Omitted checksum preserves existing behavior.
• A real integration test proves read A → write B → stale conditional edit A fails → B remains unchanged.
• Tool schema and user-facing documentation describe the contract accurately.
• SQLite and PostgreSQL paths are covered where the accepted-note mutation behavior differs.

Out of scope

• Review comments, suggestions, or CriticMarkup; those are Cloud concerns.
• Fixing Cloud's existing conditional check; tracked by [BUG] Cloud edit_note accepts stale expected_checksum on ordinary notes #1536.
• Making checksums mandatory for ordinary edits.

[claude]

Claude finished @phernandez's task in 35s —— View job

---

Triage

Type: Enhancement — adds a new optional precondition argument to the Core MCP edit_note tool; not a defect in existing behavior.

Component: MCP tool (edit_note), backed by the Core NoteContentMutationService. Not a Cloud-labeled issue — the request is explicit that this is Core-only and distinct from #1536 (closed), which was a Cloud bug about ignoring a stale expected_checksum. Core's MCP tool currently doesn't accept a checksum argument at all, so there's no overlap in scope.

Priority: Medium. This closes a real safety gap for concurrent/multi-session edits (blind edits can silently overwrite a revision the caller didn't see), but it's additive and opt-in — no existing functionality is broken and nothing regresses if left unaddressed.

Complexity: Medium. The underlying base_checksum precondition and transactional enforcement already exist in NoteContentMutationService and are already exposed via the Core v2 PUT route's x-bm-cloud-note-base-checksum header — this is primarily a matter of threading that through the MCP edit_note tool/schema, aligning the read-side checksum naming (db_checksum) with the edit-side input, adding a real conflict-path integration test (read A → write B → stale conditional edit fails → B unchanged) across SQLite and Postgres, and documentation updates. No new concurrency mechanism should be introduced.

No duplicate issues found.