Append/prepend to a note body without replacing it #7

New issue

Closed

opened 2026-08-09 19:53:00 -05:00 by mcp-gateway · 0 comments

mcp-gateway commented

2026-08-09 19:53:00 -05:00

Member

Filed from halfst/mpx-engine #116 / #120. This one has already caused a near-miss.

What's needed

A way to add text to a note body without supplying the whole body — append and prepend parameters on ticktick-update-note, or dedicated tools.

Today update-note's content parameter replaces the entire body. Any additive edit requires reading the current body, concatenating, and writing it all back.

Why that read-modify-write is dangerous here

The obvious workaround is unsafe in this specific server because of how the read side behaves. ticktick-list-notes is documented as subject to a whole-response size budget and can return truncated content. So the natural sequence — list notes, append a line, write back — silently replaces a full note with a truncated one plus your addition.

That is not theoretical. It is exactly what happened in halfst/mpx-engine #81, and decision 2 (comment 1887) removed TickTick write-back from the note sweep entirely rather than risk it:

the marker being written back came from list-notes (truncating) via ticktick-update-note (which replaces the body rather than prepending) — an unattended destructive rewrite.

The capability that got dropped as a result — visibly marking a swept Inbox note — is still unbuilt (#116). An append primitive would have made it a two-line change.

Where it's needed next

Sync Operating Spec §4.3, the Done-column archive:

Three months after a project completes: prepend a bullet — scope · outcome · people · completion date (newest first) — then delete that project's card from Done.

"Prepend a bullet, newest first" against a card that accumulates history is precisely the operation that must not be done by round-tripping a possibly-truncated body.

Acceptance

Append and prepend text to a note body server-side, without the caller sending the existing content.
The full body is preserved regardless of any list-response size budget — the operation must not internally re-read through a truncating path.
Works on kind: NOTE objects.
Documented interaction with #1's last-modified timestamp: an append should bump it.

Unblocks

halfst/mpx-engine #116 (marking swept Inbox notes, if a marker is still wanted once deletion lands) and Sync Spec §4.3's Archive card prepend.

Filed from `halfst/mpx-engine` #116 / #120. **This one has already caused a near-miss.** ## What's needed A way to add text to a note body without supplying the whole body — `append` and `prepend` parameters on `ticktick-update-note`, or dedicated tools. Today `update-note`'s `content` parameter **replaces** the entire body. Any additive edit requires reading the current body, concatenating, and writing it all back. ## Why that read-modify-write is dangerous here The obvious workaround is unsafe in this specific server because of how the read side behaves. `ticktick-list-notes` is documented as subject to a whole-response size budget and can return **truncated** `content`. So the natural sequence — list notes, append a line, write back — silently replaces a full note with a truncated one plus your addition. That is not theoretical. It is exactly what happened in `halfst/mpx-engine` #81, and decision 2 (comment 1887) removed TickTick write-back from the note sweep entirely rather than risk it: > the marker being written back came from `list-notes` (truncating) via `ticktick-update-note` (which *replaces* the body rather than prepending) — an unattended destructive rewrite. The capability that got dropped as a result — visibly marking a swept Inbox note — is still unbuilt (#116). An append primitive would have made it a two-line change. ## Where it's needed next `Sync Operating Spec` §4.3, the Done-column archive: > **Three months after a project completes:** prepend a bullet — scope · outcome · people · completion date (newest first) — then delete that project's card from Done. "Prepend a bullet, newest first" against a card that accumulates history is precisely the operation that must not be done by round-tripping a possibly-truncated body. ## Acceptance - [ ] Append and prepend text to a note body server-side, without the caller sending the existing content. - [ ] The full body is preserved regardless of any list-response size budget — the operation must not internally re-read through a truncating path. - [ ] Works on `kind: NOTE` objects. - [ ] Documented interaction with #1's last-modified timestamp: an append should bump it. ## Unblocks `halfst/mpx-engine` #116 (marking swept Inbox notes, if a marker is still wanted once deletion lands) and Sync Spec §4.3's Archive card prepend.