Writer Protocol

Change kinds

upsert — full content replacement. Creates the note if it doesn't exist; overwrites it if it does. expectedHash controls concurrency (see below).

patch — exact-string find/replace within the note's current content. The server reads the in-memory content, calls strings.Index(content, find), substitutes one occurrence, and saves. Rules:

• find must appear exactly once; zero occurrences → UpdateNotesPatchNotFoundPayload; two or more occurrences → UpdateNotesPatchNotFoundPayload (the find field echoes the ambiguous string back to the caller)
• The note must already exist; patching a non-existent path → ErrorPayload { message: "note not found: {path}" }
• find == replace after substitution → InsertNote detects identical content and skips creating a new version (idempotent)
• replace may be empty string (deletes the found substring)
• find is a literal string, not a regular expression

meta — sets and unsets top-level frontmatter keys of an existing note by splicing text (internal/frontmatteredit): every untouched key line, comment and the body come out byte for byte. Rules:

• The note must already exist; a missing path → ErrorPayload { message: "note not found: {path}" }
• set and unset cannot both be empty, a key cannot be in both, and a key cannot be blank or contain a control character
• Frontmatter that cannot be edited key by key (invalid YAML, a {...} flow mapping, indented keys, aliases, a duplicate key, no closing fence) → ErrorPayload
• The result is parsed back with yaml.v3 and with yaml.v2 (what goldmark-meta reads). Each parser must see exactly the expected keys, each untouched key must read as that parser read it before the edit, and each set key must hold the value sent, compared with the value itself (numbers by worth, NaN equal to NaN) rather than with what the encoder wrote; otherwise nothing is saved → ErrorPayload
• Setting the scalar a key already holds keeps the line, so InsertNote sees identical content and skips the version

hide — soft-deletes the path (sets hidden_at / hidden_by). Does NOT trigger webhooks from updateNotes (see code comment in internal/case/updatenotes/resolve.go); use the standalone hideNotes mutation when webhook notification is required.

pushNotes and hideNotes

The values mean the same, with three differences from updateNotes:

• Per note, not per batch. updateNotes stops the whole batch at the first mismatch and returns UpdateNotesHashMismatchPayload. pushNotes and hideNotes skip only the refused note and list it in hashMismatches.
• Checked against the database. The current hash is note_paths.latest_content_hash read inside the request transaction (LatestNoteContentHash in cmd/server/notes.go), not the in-memory note views updateNotes reads.
• A hidden note counts as absent. Its actualHash is "", so expectedHash: "" on pushNotes writes it and brings it back, and expectedHash: "" on hideNotes hides nothing new.

For hideNotes, "" means "hide only if absent", which is a no-op; the useful value is the hash the client last saw.

Why the check cannot race. Every GraphQL mutation runs in one request transaction on the single write connection, opened with BEGIN IMMEDIATE (see internal/graph/handler.go and sqlite.md). A second writer waits for that transaction to commit, so nothing lands between the hash read and the write, and of two pushes that quote the same hash, the second sees the first one's hash and is refused. TestPushNotesExpectedHashConcurrentWrites in cmd/server/note_expected_hash_test.go runs exactly this sequence.

A client that listed hashes with notePaths { value latestContentHash } sends the hash it classified against: the last-synced hash for a plain push or delete, the remote hash it saw when it resolves a conflict in favour of the local copy.

Three upsert modes

Hash algorithm: SHA-256 of the note's raw byte content, encoded as base64url with padding.

Go (server, internal/case/updatenotes/resolve.go and internal/case/insertnote/resolve.go):

base64.URLEncoding.EncodeToString(sha256.Sum256([]byte(content)))

JavaScript (client, templates/kanban/src/api.ts):

const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(content))
const hash = btoa(String.fromCharCode(...new Uint8Array(buf)))
  .replace(/\+/g, '-')
  .replace(/\//g, '_')
// btoa produces standard base64 with '=' padding; the replacements yield base64url
// This is identical to Go's base64.URLEncoding (which also keeps '=' padding)

Obsidian sync plugin (trip2g_obsidian_plugin/main.ts)

Calls pushNotes with all changed notes (no skipCommit), then calls hideNotes for paths that exist on the server but were deleted locally. Does not use updateNotes. Auth: X-API-Key header, URL {apiUrl}/graphql.

memcli (cli/memcli)

The up command runs trip2g-sync --watch as a background process, which drives the same Obsidian sync plugin code path (pushNotes). The daily and log subcommands write Markdown files directly to the vault folder on disk; the watcher picks up the changes and syncs via pushNotes.

Kanban board (templates/kanban/src/api.ts)

Uses updateNotes exclusively — upsert for card creation and full-board saves, patch for in-place card edits (title, status changes). Auth: admin session cookie (credentials: 'include'). Endpoint: /_system/graphql. Implements the full rebase-on-HashMismatch loop.

Web editor (assets/ui/editor/pane/pane.view.ts)

Uses updateNotes upsert with expectedHash: "" for the "create new file" flow as the server-side race guard against creating over an existing note. A client-side path-existence check provides the fast UX pre-reject; the empty-hash sentinel is the authoritative server guarantee behind it.

AI agents (via change webhooks)

When a change webhook fires with pass_api_key: true, the delivery payload includes api_token (a shortapitoken JWT with scoped read_patterns / write_patterns). Agents can use this token to call updateNotes or pushNotes directly for programmatic writes.

Agents that return changes synchronously in their HTTP response body use the webhook agent response format (internal/webhookutil/agentresponse.go). This is a separate code path from the GraphQL mutations: the server parses changes and calls InsertNote directly. A change without kind (or "kind": "write") replaces the full content:

{
  "status": "ok",
  "message": "Linted 3 files",
  "changes": [
    {
      "path": "blog/post.md",
      "content": "# Fixed post\n\nCorrected content.",
      "expected_hash": "base64url-sha256-of-previous-content"
    }
  ]
}

"kind": "patch" with find / replace and "kind": "meta" with set / unset follow the updateNotes patch and meta rules; expected_hash applies to every kind. The format has no hide; for that, agents use the shortapitoken to call updateNotes directly via /_system/graphql.

Create a note (fail if it already exists)

mutation CreateNote($i: UpdateNotesInput!) {
  updateNotes(input: $i) {
    __typename
    ... on UpdateNotesSuccessPayload { paths }
    ... on UpdateNotesHashMismatchPayload { path actualHash }
    ... on ErrorPayload { message }
  }
}

{
  "i": {
    "changes": [{
      "upsert": {
        "path": "inbox/new-idea.md",
        "content": "---\nfree: true\n---\n\n# New Idea\n\nContent here.",
        "expectedHash": ""
      }
    }]
  }
}

Returns HashMismatchPayload (with actualHash set to the real hash) if the note already exists.

Edit one line (patch)

{
  "i": {
    "changes": [{
      "patch": {
        "path": "todo/sprint.md",
        "find": "- [ ] Deploy v2.0",
        "replace": "- [x] Deploy v2.0"
      }
    }]
  }
}

Anchor-marker append (sequential inserts via sentinel)

Keep a $INBOX$ sentinel in the note. Each insert prepends the new entry above the sentinel and re-places the sentinel so the next call finds it:

{
  "i": {
    "changes": [{
      "patch": {
        "path": "inbox.md",
        "find": "$INBOX$",
        "replace": "## 2026-06-28 09:15\nNew thought.\n\n$INBOX$"
      }
    }]
  }
}

Successive patches accumulate above the sentinel, which stays in place as the insertion point.

Bulk sync (Obsidian plugin path)

{
  "input": {
    "updates": [
      { "path": "notes/a.md", "content": "..." },
      { "path": "notes/b.md", "content": "..." }
    ]
  }
}

Omit skipCommit (or set false) to fire webhooks immediately. Use skipCommit: true + a subsequent commitNotes call to batch the entire vault load as a single atomic publish.

Rebase on HashMismatch

let result = await updateNotes([patchChange(path, find, replace, expectedHash)])
if ('hashMismatch' in result) {
  const fetched = await fetchNoteContent(path)         // re-read from server
  const newContent = applyEdit(fetched.content, ...)   // rebase the edit
  const newHash = await sha256Base64(fetched.content)
  result = await updateNotes([upsertChange(path, newContent, newHash)])
}

The kanban template's updateNotes function in templates/kanban/src/api.ts implements exactly this pattern.

Delete (hide)

mutation HideNotes($input: HideNotesInput!) {
  hideNotes(input: $input) {
    ... on HideNotesPayload { success }
    ... on ErrorPayload { message }
  }
}

{ "input": { "paths": ["drafts/abandoned.md"] } }

To hide only if nobody edited the note since you read it, pass its hash and ask for the mismatches:

mutation HideNotes($input: HideNotesInput!) {
  hideNotes(input: $input) {
    ... on HideNotesPayload { success hashMismatches { path actualHash } }
    ... on ErrorPayload { message }
  }
}

{ "input": { "notes": [{ "path": "drafts/abandoned.md", "expectedHash": "<hash you read>" }] } }

Use hideNotes (not updateNotes hide) when you need webhooks to fire on removal.