Notes document API implementation

Current delivery status — 2026-09-24

CLI 0.26.2, Python 0.20.0, corrected production API and RTC are now released. Default MERGE uses the original baseline's native identities; EXACT is optional for each request. Public docs/skills, fresh installations, core/HTML checks, paired client examples and the frozen 100-edit live pilot are verified. User production browser/UI acceptance remains pending. See the current release evidence and owning Notes guide for current behavior and remaining acceptance.

The dated milestone entries below are historical implementation records. Their “Unreleased”, mandatory-guard and pending-publication statements describe the earlier milestone state and are superseded by the current delivery record; they do not prescribe the released MERGE/EXACT interface.

2026-09-23 — PR 1 patch foundation (Unreleased)

Master Note: #note:6ab3026e8d8a9b5f35ab9aa1. Workspace master: #247. Tracking: #706, including the complete updated master Note and the separate milestone PRs.

PR 1 adds an owned, bounded parser/serializer library for inline-dff and unified line diff, normalizing both to exact Unicode-code-point edits. The owning contract is dreamlake-server/docs/notes-patch-formats.md. Both formats share deterministic character alignment and reject malformed, ambiguous or oversized batches without partial application. Source CRLF, Unicode and final-newline state are preserved. No DMP application is used.

This milestone adds no public endpoint, Bash command or persistence write. Atomic RTC compilation/commit, Notes API and Bash CLI follow in PRs 2–4; HTML source attributes, rich components, insertion menus and numbering follow in PRs 5–8; release and deployed compatibility/comparison gates remain PR 9. Each milestone stays separately reviewable.

Validation targets exact round trips, disjoint edits, repeated-text alignment, Unicode, literal delimiter escapes, malformed ranges and newline behavior. Draft PR #707 passes 72 focused tests, including 320 seeded round-trip cases. RTC identity and concurrent-writer tests require the later authoritative commit implementation.

Public-skill impact: none for PR 1. Only internal noindex development/release pages and server developer docs change; the public Notes/CLI owning procedures and supported interfaces remain unchanged. Run workspace gen:llms and check:llms; no companion public-skill content update is needed for this internal contract. Future interface changes must synchronize committed source with dreamlake-skills, check provenance and verify a fresh install separately.

Implementation review is distinct from merge, SDK/server package publication, docs/skill publication, deployment and live verification. None of those later states is implied by focused local tests.

2026-09-23 — PR 2 conditional bridge (Unreleased)

Added a fail-closed bridge for the upstream conditional RTC protocol and native character-edit compilation. Six focused tests include a real local WebSocket stale response and SDK rope identity preservation. Owning protocol notes: dreamlake-server/docs/notes-conditional-rtc.md. The upstream server/SDK release and PR 3 route migration remain dependencies. No public skill procedure changes in this internal bridge milestone. No merge, publication, deployment or live verification is claimed.

2026-09-23 — PR 3 source API and RTC-only writes (Unreleased)

The v2 contract is opt-in over existing HTTP routes (contract=v2 on reads, format plus patch on uploads). Source hashes and opaque RTC baselines are separate. Full/incremental reads, guarded readback and retained hash/time lookup share the conditional source snapshot. Time history consists of timestamped retained source observations, not a backfilled keystroke audit.

All programmatic body/section writes now compile targeted native operations and use an authoritative conditional commit. Removed archive fallback and whole-room reset on write failure. Archive/history refresh happens only after acknowledgement; projection failure does not turn a committed edit into an apparent failed write.

Public Notes skill is affected: regenerate from this committed guide alongside the CLI companion PR. The upstream RTC server release, compatible identity-bearing rooms and mixed-client rollout checks remain required. No hosted availability, merge, release or deployment is claimed by this implementation.

Fresh empty Notes materialize their blank download projection only after native RTC initialization is acknowledged; a projection outage cannot become an archive-only document write or roll back that acknowledged initialization.

2026-09-23 — PR 5 HTML route integration (Unreleased)

The v2 view=html read now calls the source-attribute renderer using the same conditional source/revision snapshot. It returns HTML directly and rejects incremental HTML. API tests cover exact canonical entity spelling, content type, atomic entity ranges and invalid view combinations. Public Notes source guide and generated skill reference updated; the public skills companion must be resynchronized from this committed revision. No hosted verification is implied.

2026-09-23 — PR 6 static rich components (Unreleased)

Companion to UI #415, tracked in master #706. The server HTML representation now renders strict rich tokens and legacy placeholders, with source-atomic ranges, preserved code/link literals, blue placeholder styling and unresolved ChatGPT tags. Resource labels remain inert: no metadata fetch, permission assumption or download capability is introduced. The parser follows the UI grammar; imported private-use citation markers are explicitly recognized by Markdown's text tokenizer.

Validation: 64 renderer tests cover exact source ranges across prose, emphasis, lists and tables, Unicode, malformed grammar, literal contexts and malicious labels. Full server TypeScript passes after Prisma client generation. A local Chromium preview verifies blue bracket placeholders in prose and tables, with CSP-authorized styles (1px border and 3px horizontal padding). Public Notes docs and generated workspace references are affected; resynchronize the public skills companion from this committed revision. Implementation and local validation do not establish merge, release, deployment or hosted compatibility. Heading/front-matter parity remains a separate PR 8.

2026-09-23 — PR 8 HTML heading parity (Unreleased)

Companion to UI PR #418, stacked after the PR 6 static rich renderer. The server reuses the UI's pure front-matter parser, numbering policy and parity fixtures. Actual ancestor levels compress skipped depths; shallow unnumbered headings reset the sequence. Generated numbers have no source span, and every body/rich-token range includes the original front-matter offset.

The narrowly supported YAML options preserve unknown source and diagnose invalid values without rewriting it. The server adds a direct pinned yaml dependency with its own lockfile; workspace dependency resolution is unchanged. Validation covers shared hierarchy fixtures, default/invalid options, CRLF, Unicode offsets, setext headings, code fences, diagnostics and rich-token parity. The cumulative renderer/API suite passes 93 tests, full TypeScript and docs generation checks; independent mapping/schema review found no blocker. Public Notes docs and generated references change, so the public skills companion must synchronize from this commit. Merge, release, deployment and live parity are still separate gates under master #706.

Fresh empty Notes materialize their blank download projection only after native RTC initialization is acknowledged; a projection outage cannot become an archive-only document write or roll back that acknowledged initialization.

2026-09-23 — PR 1 sparse-edit follow-up (Unreleased)

The PR 9 benchmark exposed rejection of two tiny distant edits in a 35 KB Note: quadratic LCS alignment exhausted its budget despite almost all source being unchanged. The shared engine now uses a bounded Myers frontier for long sparse regions, retaining unchanged runs and deterministic ties without coarse rewrite fallback. Both formats pass 74 focused tests, including 40 KB Unicode source and 30 additional sparse round trips. Work and trace-memory limits still reject expensive wholesale differences. This internal fix changes no public CLI grammar or skill procedure. It is not a production performance measurement.

2026-09-23 — Published RTC SDK consumer pin

PR 2 now pins the published RTC SDK 0.9.0 with an integrity-locked dependency. The matching server 0.5.0 is published; authority deployment and live compatibility remain separate gates. Frozen installation and native bridge tests use the actual registry package. This internal dependency update adds no public skill procedure.

2026-09-24 — Native merge patches, opt-in exact mode (Unreleased)

The default v2 patch now carries baseRevision independently of optional If-Match. Authenticated reads retain the original snapshot and journal in a note-scoped S3 envelope keyed by the hash of the authoritative RTC revision. The envelope validates room, revision, source hash and binary integrity; a missing or expired native baseline cannot fall back to a source-only hash. Read-only conditional-state observations use the corrected upstream unlocked capture path; the legacy wire name does not acquire a writer gate.

Default writes compile exact sparse edits against the saved native identities and send ordinary crdt messages. Explicit mode: "exact" opts into guarded CAS; If-Match is a compatibility alias. Receipts return mode: "merge" or "exact". A bounded reconnect resends the same message IDs; no new HTTP invocation is silently deduplicated. Existing browser editor improvements remain intact. The paired RTC correction removes ordinary-writer coordination overhead; this API implementation requires that corrected authority before release.

Public Notes and CLI skills are affected. Synchronize the committed owning Notes guide and CLI 0.26.2 source after review, and verify live docs and a fresh skill readback after release. Local tests do not establish deployment or manual production acceptance.

The API dependency is now pinned to published SDK 0.9.1, paired with RTC server 0.5.1. A fresh frozen install, TypeScript check, 81 focused tests and an isolated API-to-RTC/Mongo fixture passed against the registry package. Both modes keep immutable request identities for one bounded transport retry after an uncertain acknowledgement; exact mode also retains its durable conditional request ID. This does not retry HTTP requests or change an exact operation into merge mode.

The owning guide marks ETag-based Python patch examples with legacy=True and keeps the native v2 baseline examples separate. The real local API/RTC/Mongo fixture also verifies successful exact append, followed by an explicit new request using default merge mode with unchanged source/hash/revision. Public examples show both success receipts and exact conflict handling without sticky mode selection or automatic HTTP retry.

2026-09-24 — Public availability documentation

The current Notes guide identifies the CLI 0.26.2/Python 0.20.0/RTC server 0.5.1 release, distinguishes legacy ETag patches, and maps actual 404/412/422 client failures. Current HTML/rich-token/numbering sections no longer carry draft availability labels. The September 23 milestone records remain historical; fixture transcripts remain explicitly isolated evidence. This internal page remains hidden and noindex. Public skills must be synchronized from the merged availability source and verified after publication.