DreamLake

Memo diffs

MERGE and EXACT patches (Python 0.20.0)

Read an original RTC snapshot, prepare a patch against its exact source, and keep that snapshot while submitting the patch. MERGE is the default and sends no If-Match header. The server validates the original source, compiles edits against its original RTC identities, and uses ordinary CRDT synchronization. Concurrent edits are handled by the existing CRDT behavior, without fuzzy rebasing onto the newest text.

python
import dreamlake as dl

note = dl.note("<namespace>/<note-id>")
snapshot = note.read_snapshot()
# This illustrative patch requires snapshot.content == "Hello world."
patch = "@@ chars 0:12 @@\n~ Hello [-world-]{+team+}.\n"
receipt = note.patch(patch, base_revision=snapshot.revision)
assert receipt.mode == "merge"
print(receipt.to_dict())
# Optional verification of the revision acknowledged by this request:
verified = note.read_snapshot(at=receipt.revision)

For a separate request that must refuse any intervening revision, select EXACT:

python
receipt = note.patch(patch, base_revision=snapshot.revision, exact=True)

EXACT is per request, never a permanent document mode. if_match=revision is an explicit compatibility spelling for EXACT. It can supply the original baseline when base_revision is absent; when both are supplied they must match. format="inline-dff" is the default; format="diff" accepts the line format. The Python client transports the patch without applying DMP or fetching a newer baseline. The API must retain the original native identity snapshot; an old content hash alone is not an RTC baseline.

NoteSnapshot is immutable and carries note, content, hash, revision. A v2 PatchReceipt is a separate immutable value carrying note, mode, base_revision, hash, and revision. Its to_dict() uses the same JSON fields as CLI/API receipts: note, mode, baseRevision, hash, revision. hash describes content; revision identifies an RTC state. The receipt is not a string and does not pretend that these two references are interchangeable. Snapshot reads do not alter the legacy Note/Doc cache.

Missing or expired original baselines, mismatched patch source, and failed EXACT checks are explicit errors. No HTTP patch request is automatically retried. Preserve the draft and original snapshot on any error. For an ambiguous lost acknowledgment, inspect the current state and reconcile before resubmitting; separate HTTP requests do not share an idempotency receipt. Unknown baselines raise NoteNotFound; EXACT conflicts raise NoteChanged; source mismatches raise PatchFailed; unavailable RTC responses raise NoteBusy.

Python 0.20.0 provides this contract with the matching Memos v2 API. Use legacy=True for the earlier ETag patch interface. Package and deployed acceptance receipts are tracked in workspace #706.

Concurrent edit walkthrough

Use a private test Memo containing exactly Hello world.. Run the first part, then prepend Human: in the browser and wait for that edit to sync. Keep the original immutable snapshot and patch unchanged.

python
import dreamlake as dl
from dreamlake import NoteChanged

note = dl.note("<namespace>/<test-note-id>")
original = note.read_snapshot()
assert original.content == "Hello world."
patch = "@@ chars 0:12 @@\n~ Hello [-world-]{+team+}.\n"
input('Prepend "Human: " in the browser, wait for sync, then press Enter: ')

try:
    note.patch(patch, base_revision=original.revision, exact=True)
except NoteChanged as error:
    print(type(error).__name__)  # NoteChanged: HTTP 412, no patch operations
else:
    raise AssertionError("the intervening revision should reject EXACT")

receipt = note.patch(patch, base_revision=original.revision)
print(receipt.mode)              # merge
print(receipt.base_revision)     # original.revision, unchanged
print(receipt.hash)              # content SHA-256 of the acknowledged observation
print(receipt.revision)          # RTC revision of that same observation
print(receipt.to_dict())         # note, mode, baseRevision, hash, revision
assert note.read_snapshot().content == "Human: Hello team."
assert original.content == "Hello world."

The SDK itself prints nothing: values are returned, failures are exceptions. The example prints only when requested. Receipt hash and revision describe one coherent observation after acknowledgment, not a guarantee that all peers are synchronized or that the state remains current forever. Original native identity preservation and zero patch writes after EXACT rejection are checked by the paired API/RTC acceptance fixture. The SDK does not fall back from EXACT to MERGE or overwrite the saved snapshot after a failure.

Successful EXACT and the next MERGE request

Continue from the merged fixture, taking a new snapshot for this separate edit. If a writer intervenes again, EXACT raises NoteChanged; retain this snapshot and draft and inspect the memo before deciding on another request.

python
exact_base = note.read_snapshot()
assert exact_base.content == "Human: Hello team."
exact_patch = "@@ chars 18:18 @@\n~ {+!+}\n"
exact_receipt = note.patch(exact_patch, base_revision=exact_base.revision, exact=True)
print(exact_receipt.mode)           # exact
print(exact_receipt.base_revision)  # exact_base.revision
print(exact_receipt.hash)           # content hash of the post-ACK observation
print(exact_receipt.revision)       # RTC revision of that same observation
print(exact_receipt.to_dict())      # note, mode, baseRevision, hash, revision
assert note.read_snapshot().content == "Human: Hello team.!"

# EXACT applies to one request. This separate no-op uses the MERGE default.
next_base = note.read_snapshot()
next_receipt = note.patch("", base_revision=next_base.revision)
assert next_receipt.mode == "merge"
assert next_receipt.base_revision == next_base.revision
assert next_receipt.revision == next_base.revision
print(next_receipt.to_dict())

Recorded Python fixture values

The following values were replayed through the candidate SDK from an isolated API + RTC + Mongo fixture. Authentication, catalog, and S3 projections were mocked. This is test evidence, not a released-package or production transcript.

receipt.mode == "merge"
receipt.base_revision == "rtc:9a67f239fc8b862aa557dd10dd6512a7669861287ac8fe262d9c80afebcd18e7"
receipt.hash == "sha256:163af32ec4bc25f27e3b9ae68fe85c75e5b4436a769cc82a4050692643ce92cf"
receipt.revision == "rtc:94c1a7696f6bcd27fa880e4b38b3f73cdd3971f28b44edf9018fadf817df0f3f"

receipt.to_dict() has the same field names as CLI/API JSON:

json
{
  "note": "507f1f77bcf86cd799439099",
  "mode": "merge",
  "baseRevision": "rtc:9a67f239fc8b862aa557dd10dd6512a7669861287ac8fe262d9c80afebcd18e7",
  "hash": "sha256:163af32ec4bc25f27e3b9ae68fe85c75e5b4436a769cc82a4050692643ce92cf",
  "revision": "rtc:94c1a7696f6bcd27fa880e4b38b3f73cdd3971f28b44edf9018fadf817df0f3f"
}

EXACT raised NoteChanged with this message, after HTTP 412 and zero patch journal writes. The SDK emitted no stdout or stderr:

patch fixture/507f1f77bcf86cd799439099: The RTC baseline changed

The fixture's missing-baseline response was HTTP 404 with error="revision_not_found", message="Original RTC baseline is not retained". Malformed inline input was HTTP 422 with error="patch_failed", message="Expected inline header and one record". The SDK raises NoteNotFound and PatchFailed respectively; it does not turn either response into a MERGE retry against newer source.

Recorded successful EXACT return value

A separate run of the same isolated API/RTC/Mongo fixture produced this receipt, replayed through the candidate SDK. The SDK emitted no stdout or stderr; these are returned attributes, not a published-package or production transcript.

exact_receipt.mode == "exact"
exact_receipt.base_revision == "rtc:71371be6e3227abca241161ebb7d8d65e2d851b8872b5a5d51ce7ec80369d95e"
exact_receipt.hash == "sha256:2b8c0f5475f23494272f3800abb11a7680b3360bc2e927763c10aec9cf4398f5"
exact_receipt.revision == "rtc:63834c3821f7b76779815f3a670449268711811e69f86f6b208fb52236713484"

exact_receipt.to_dict():

json
{
  "note": "507f1f77bcf86cd799439099",
  "mode": "exact",
  "baseRevision": "rtc:71371be6e3227abca241161ebb7d8d65e2d851b8872b5a5d51ce7ec80369d95e",
  "hash": "sha256:2b8c0f5475f23494272f3800abb11a7680b3360bc2e927763c10aec9cf4398f5",
  "revision": "rtc:63834c3821f7b76779815f3a670449268711811e69f86f6b208fb52236713484"
}

The next empty patch omitted exact=True, returned mode == "merge", and kept the same hash and revision. Its to_dict() was:

json
{
  "note": "507f1f77bcf86cd799439099",
  "mode": "merge",
  "baseRevision": "rtc:63834c3821f7b76779815f3a670449268711811e69f86f6b208fb52236713484",
  "hash": "sha256:2b8c0f5475f23494272f3800abb11a7680b3360bc2e927763c10aec9cf4398f5",
  "revision": "rtc:63834c3821f7b76779815f3a670449268711811e69f86f6b208fb52236713484"
}

Legacy ETag compatibility

read() still returns the editable Doc; Doc.save(), whole-body writes, and section writes retain their previous ETag behavior. For old unified-diff callers, select patch(..., legacy=True) explicitly. That path continues to return PatchResult(str) with .etag and .size_bytes, and retains the previous cached ETag precondition. A legacy content ETag must not be passed as a v2 RTC baseline.

Legacy comparisons against your last read or edit

The legacy note.read() body read returns doc.etag, a quoted SHA-256 hash of the complete text. Keep it as a revision reference, including across processes:

python
import dreamlake as dl

note = dl.note("<note-id>")
doc = note.read()
ref = doc.etag

# Later, including edits made by collaborators:
print(note.diff(since=ref))
print(note.diff())          # defaults to this handle's last read/edit ETag

# Apply your patch against the exact revision you used to prepare it:
result = note.patch(my_diff, legacy=True, if_match=ref)
ref = result.etag

The server retains note-scoped content snapshots for body/section reads and API writes. Identical content has the same hash; a ref identifies text, not an RTC operation or author. Partial body reads return the hash of the complete body. Diff inspection does not advance the handle's cached revision or write precondition. Use read()/refresh() when you want to adopt the latest state.

GET /namespaces/:slug/notes/:noteId/diff?since=<etag> returns diff, from, to, and etag (the current ref). context accepts 0–100 lines, default 3. The endpoint enforces current memo read permissions. Unknown or unavailable snapshots return 404, never an empty-baseline diff. Old ETags issued before snapshot retention was deployed may be unavailable. Retention requires the matching server deployment; the SDK does not infer historical bytes.

Inspect and patch a local draft

Read a memo once, inspect edits, apply unified diffs locally, and save against that snapshot's revision:

python
note = dl.note("<note-id>")
doc = note.read()
doc.replace("Published", query="Draft", all=True)
print(doc.diff(since="last_edit"))  # the latest local change
print(doc.diff())                   # all changes since read or successful save

doc.patch(unified_diff)             # edits the draft; returns its full text
doc.save()                         # conditional remote write

since="last_edit" compares the current draft with its contents immediately before its latest content-changing operation, including element edits, patches, and revert(). Before any edit it returns an empty string. No-op edits and successful saves preserve this comparison; a new read() creates a new draft. It does not retrieve other collaborators' history or persisted server revisions.

doc.patch(diff) accepts a single-file unified diff, including diffs from doc.diff(), diff -u, and git. Hunk positions and context must match exactly; there is no fuzzy relocation. Invalid patches raise EditError and leave both the draft and last-edit comparison unchanged. Empty diffs do nothing. Diffs preserve Unicode, CRLF, and missing final newlines. context=0 is supported; the default for diff() is three context lines.

To apply a patch directly to the remote memo, use the existing API:

python
result = note.patch(unified_diff, legacy=True, if_match=doc.etag)

The CLI equivalent is:

bash
dreamlake memos patch "$NOTE_ID" --legacy --file change.patch --if-match '"<etag>"'

Remote writes reject stale revisions. A local patch is committed only when doc.save() succeeds; a rejected save retains the draft for inspection.

Original-revision append (Python 0.26.0 release candidate)

This candidate changes note.append(text) from a cached whole-body PUT returning an ETag string to a native original-revision insertion returning PatchReceipt. Requires Python 0.26.0; publication acceptance is tracked separately. Read exact source once, retain it, and append:

python
original = note.read_snapshot()
receipt = note.append("New paragraph", at=original)
verified = note.read_snapshot(at=receipt.revision)
assert verified.hash == receipt.hash

Without at, append reads one fresh hash-verified snapshot. With at, it validates Memo identity, source hash and the original opaque revision before any network request; it never substitutes current source. The insertion uses Unicode code point positions and escapes inline framing and delimiter punctuation (+, -) in the canonical form the CLI and server use, preserving CRLF and LF bytes. An existing nonempty body lacking a final LF receives one LF before the addition, including when the addition is empty. A completely unchanged MERGE returns an observational receipt without PATCH or a new commit; it does not claim current revision verification. exact=True submits even an unchanged patch so the server checks the saved baseline. No request is automatically replayed.

Retained read_snapshot(at=revision) verifies the returned revision and source hash even if another edit has since arrived. if_match=revision instead checks current source; combining the two is rejected. A successful patch updates the legacy cached ETag only in its content-hash domain, never to an RTC revision. Unknown write outcomes preserve caches and drafts: keep the original baseline and draft, inspect retained/current source, and reconcile before resubmitting.

For previous cached-text/LF/ETag PUT behavior and string return values, choose note.append(text, legacy=True). Existing force=True also selects that legacy path. Combining either with at or exact is rejected before HTTP. Doc.save(), whole-body writes and section APIs retain their existing behavior.

Native body drafts (Python 0.27.0 release candidate)

Python 0.27.0 changes note.write(text) from whole-body PUT to disjoint Unicode-codepoint patches against original RTC source. at=original_snapshot pins identity and source without GET; without it one verified snapshot is read before planning. Unchanged gaps remain untouched, and alignment work/trace/source limits fail before PATCH instead of replacing a coarse region. No automatic replay occurs. Explicit legacy=True, existing force=True, or legacy if_match=etag retain the ETag PUT/string contract; modern at/exact cannot be mixed with those compatibility options.

note.read() creates a modern editable Doc retaining its original immutable snapshot. Edits remain local. doc.save() submits against that same snapshot, returns PatchReceipt, and reads the acknowledged retained revision to adopt its coherent merged content as the next draft/original. A different write through the Memo handle does not move this draft's baseline. exact=True checks even unchanged drafts; unchanged MERGE returns an observational receipt without a new commit or a current-revision claim. note.read(at=revision) opens retained source.

If post-ACK readback fails, the raised NoteError.receipt contains the known acknowledgment; draft and original source stay available. Further save calls are refused until the caller reconciles: inspect note.read_snapshot(at=receipt.revision) and current source, then explicitly open a new draft and reapply intended edits. This failure is not a rollback and must not be blindly resubmitted. Ambiguous PATCH failures retain drafts and snapshots without adopting a newer baseline.

For legacy editable drafts, choose note.read(legacy=True) or the legacy ETag verification if_match=etag; their save behavior and SaveResult are retained. doc.save(legacy=True) / force=True explicitly choose legacy body behavior. Publication acceptance remains separate. Partial reads, section writes and section selector mapping remain legacy and are a separate pending migration; their ranges must not be guessed into original native snapshot coordinates.

Full source reads and remote inspection (Python 0.28.0 release candidate)

Default note.refresh() and note.text read full source through verified Memos v2 snapshots. Cached ETags stay in the quoted content-hash domain; RTC revisions stay on immutable snapshots. note.read() also populates that verified cache, while existing Docs retain their own original snapshot even after another refresh. read_snapshot() itself still leaves caches unchanged. Explicit refresh(legacy=True) and get_text(legacy=True) preserve older body-read behavior. Legacy append and legacy editable reads select that path explicitly on cache miss. No v2 failure silently falls back to a legacy read.

note.diff(since=content_hash) uses the shipped v2 body inspection endpoint and continues returning a diff string. It checks Memo, base hash, format and revision, then reads the retained acknowledged revision to verify its source hash. Inspection updates no cache or draft baseline. since is a content hash (raw, quoted ETag or sha256-prefixed), never an RTC revision or a native patch baseRevision. Omitting since uses this handle's last full read/edit content-hash ETag. The returned string is inspection material; retaining only its hash does not establish a writable original identity snapshot.

The v2 endpoint has fixed diff formatting and no context-selection parameter. Explicit nondefault context selects the retained compatibility /diff endpoint before transport, preserving existing calls; legacy=True also selects it. This is option-based compatibility, never a fallback after a failed v2 response. V2 context selection remains an unresolved Namespace-owned endpoint capability. There is no existing Python DiffResult value; no new protocol or parser is introduced. Sections and partial reads still await their retained range/discovery contracts and remain an explicit separate migration. Publication acceptance for Python 0.28.0 remains separate.

The Memos API facade (Python 0.34.0)

dl.notes implements the Python tabs of the Memos API design pages. Stable IDs are primary, every operation takes keyword arguments, and the facade is an adapter over the retained-baseline contract above: edits compile to one inline-dff record against the original revision and go through the same validated PATCH. dl.note(), read_snapshot() and the released note.append() separator behavior are unchanged.

python
import dreamlake as dl

note = dl.notes(note_id)                  # local; the server resolves the owner on first use
snapshot = note.read()                    # NoteSnapshot {note, content, hash, revision}
receipt = note.append(text="\nHello\n", at=snapshot)   # verbatim: no separator is added
acknowledged = note.read(at=receipt.revision)
page = dl.notes.list(namespace="your-workspace", limit=20, offset=0)
created = dl.notes.create(namespace="your-workspace", name="Review", text="# Review\n")
slug = dl.notes("design-doc", namespace="your-workspace")   # a slug needs namespace context

Reading

read() returns exact source. read(view="mapped") returns a MappedRead: the same exact content, its absolute code-point chars, the observed elements (address, chars, lines, section) and the reading view in text — generated <!-- … --> hints that are never source. It is the snapshot the CLI's --view html reads (view=html&contentFormat=literal-markdown), validated the same way. Exactly one of lines=(a, b) (1-based, inclusive; past-the-end is refused), section="s1" or address="s1.p2" scopes a read; the last two need the mapped view. at= reads a retained revision and verifies it. outline(at=) lists headings with addresses; find(text=, case_sensitive=False, at=) searches exact source and returns absolute ranges; diff(since=revision, format="diff") returns base/result revisions and hashes with the patch.

A FocusedRead/scoped MappedRead carries the whole memo's hash and revision but complete=False; it baselines a targeted edit inside its span and is refused (SnapshotRequired) as a whole-body baseline. A complete mapped read is accepted wherever a snapshot is.

Editing

python
original = note.read()
note.replace(lines=(40, 42), text="- Updated item\n", at=original)
note.insert(after="s1.p2", text="- New item\n", at=original)
note.remove(lines=(40, 42), at=original)
note.write(text="Hello team.\n", at=original, mode="exact")
note.patch(patch=unified_diff, format="diff", at=original, mode="exact")

replace/insert/remove take exactly one selector or placement (lines, address; before, after, cursor) and default to mode="merge"; an address must have been observed at at's revision (a MappedRead resolves it without a request). write and patch require mode; patch requires format. Replacement text is verbatim: no newline, indentation or marker is added, and input containing <!-- notes-reading-view is refused.

Receipts, outcomes and command identity

A successful write returns PatchReceipt {memo, mode, base_revision, hash, revision, outcome, command_id, replayed}; outcome is accepted or no-write. Every error carries .outcome: invalid-usage (refused before any request: RevisionExpected, SnapshotRequired, InvalidLineRange, SelectionError, ReadingViewRefused), no-write (NoteChanged, PatchFailed, NoteReadOnly, NoteNotFound, CommandIntentMismatchError), unknown (UncertainOutcomeError, WriteOutcomeUnknown, NoteCreatedWithoutSource) or operational (NoteBusy, CommandInProgressError, CommandStatusInvalid, CommandIdentityUnsupportedError).

command_id is the documented answer to a lost-response append. Pass one ([A-Za-z0-9._:-]{8,128}) to append/replace/insert/remove/write/ patch; it is sent as commandId and the receipt must echo it. A transport failure after the request was handed over raises UncertainOutcomeError carrying the id: resend the same call with the same id (the server returns the stored receipt rather than appending twice) or call note.command_status(command_id=...). It stays opt-in until the recording server is deployed; without one nothing new is sent.

Resources and collaboration

note.rename(name=), note.versions.list() / .read(version_id=), note.files.move(file=, to_folder=, name=), note.presence() and note.visit(intent=, address=|cursor=, at=) mirror the CLI's requests. dl.notes.create(text=...) creates the memo, then writes the initial source through the retained-baseline contract; if that second step fails, NoteCreatedWithoutSource carries the created id so no second memo is made.

Not in this release (listed by tests/test_notes_docs_contract.py): note.watch(...) and note.move(...); the other collections' move facades.

Source: Python SDK guide.