Repository Public
1<!--2SP Notes Core3File: CHANGELOG.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Changelog89## 2.0.0 — SP Note Next Generation (branch `next`, not released)1011Goes with web / backend 3.0.0 and SP Notes macOS / iOS 2.0.0 (SPEC §1). Both 1.x apps compile against it unchanged.1213### SPNotesDocument14- Typed support for the 3.0 nodes: `mermaid`, `drawing`, `chart`, `queryView`, `citation` (inline), `bibliography`, `pdf`,15 `blockRef`, `runCode`, `audio`, `canvasLink` — node types, schema sets, defaults, validator, and typed views (`MermaidBlock`,16 `DrawingBlock`, `ChartBlock`, `QueryViewBlock`, `CitationInline`, `BibliographyBlock`, `PDFBlock` + `PDFAnnotation`,17 `BlockRefBlock`, `RunCodeBlock`, `AudioBlock` + `TranscriptSegment`, `CanvasLinkBlock`, `TypedBlock`). Unknown attributes inside18 known nodes and unknown nodes still round-trip byte for byte.19- Markdown, plain text, word count and HTML of the new nodes, ported from the server and verified byte for byte on the backend's20 published fixtures and on 521 documents recorded from its own functions.21 Transcript and annotation text are part of the plain text (search index).22- New optional attributes: `taskItem.due / priority / taskId`, `aiBlock.sources / action`; callout kinds `decision`, `question`,23 `hypothesis`; block ids on `listItem` / `taskItem` and on the new blocks.24- `attachmentReferences()` and `pageReferences()` include the files and targets of the new nodes; `citedReferences()`,25 `taskItemDetails()`.26- `InkDocument` (`spn-ink-1`) with simplification, bounding box, hit testing and a CoreGraphics renderer (`InkRenderer`).27- `CanvasDocument` (`spn-canvas-1`) with a three-way merge by node / edge id and deterministic auto-layout (`CanvasLayout`).28- Fixed: numbers in exported text follow ECMAScript (`1e-7`, not `1e-07`).2930### SPNotesStore31- Schema v2 (additive): generic `entities` with typed queries, ordered `entity_ops` outbox, `canvases`, `events`, `kv_cache`,32 `sync_cursors`, `ops_parked`. See `docs/MIGRATION-V2.md`.33- Pre-migration backup of the database file, removed at a later healthy open.34- `NotesStore.open(url:)` → `StoreOpenResult` / `StoreOpenError` (typed, with a user message) so that apps stop falling back to35 an empty in-memory store.36- `StoreChange` gains `entities`, `entityQueue`, `canvases`, `events`, `cache`; `StoreError` gains `backup`.3738### SPNotesAPI39- Opt-in retry with backoff for requests that are safe to retry (`RetryPolicy`, `HTTPRequest.retrying()`, `isSafeToRetry`,40 `newIdempotencyKey()`), honouring `Retry-After`. Default behaviour unchanged.4142### SPNotesSync43- Fixed: a queued op of an unknown kind was silently dropped; it is now parked and surfaced (`SyncStatus.unsupported`).4445### SPNotesDesign (new product)46- Note Visual System 2.0 « Graphite & Ultramarine · Lumen »: `NVColor`, `NVFont`, `NVSpace`, `NVRadius`, `NVElevation`,47 `NVMotion`, the seven signature motions, and the components `NVCard`, `NVChip`, `NVSectionHeader`, `NVEmptyState`, `NVAIBadge`,48 `NVCitationChip`, `NVToolbarGlass`, `NVProgressDots`. See `docs/DESIGN.md`.4950### Wave 2 — clients of API-NEXT, entity sync, repositories (2026-11-19)5152**SPNotesAPI**53- Typed clients for every route of `API-NEXT.md` (meta / features, feed with `kinds`, tasks with client ids, graph views,54 relations, concepts, insights, events, time machine and restore by entry id, knowledge health, brief, living blocks, canvases,55 zoom, ranged and resumable file downloads), for the AI workstream (`API-NEXT-AI.md`: model catalogue, ask scopes, new56 actions and link suggestions, synopsis, transcription, smart database properties) and for the 2.x route groups the natives57 lacked (databases, search, backlinks / neighbours / suggestions, inbox, capture, research, AI conversations and usage,58 agents, dashboard, settings, trash). 243 tests; every DTO decoded from a recorded answer of the scratch backend59 (`Fixtures/next`, recorder in `Scripts/`); 32 live tests gated on `SPN_LIVE_URL`.60- Typed error accessors for the codes of API-NEXT §5; no case added to `APIError`.61- `PageType.canvas`, `TaskStatus.doing`, `TaskItem.blockId / deletedAt / rev`, `TaskDraft.id / blockId / status / due`,62 `SyncPage.entities`, `HTTPRequest.extraHeaders`, `HTTPClient.openBytes`.6364**SPNotesSync**65- Entity sync: the feed is asked with `kinds` and applied to `entities` (cursor rule, soft deletes, tombstones of the new66 kinds — they were skipped —, reset, full-copy cleanup); task outbox (create / update / delete with client ids, ordered,67 idempotent, rejected operations kept and surfaced); canvases (PUT with `baseVersion`, three-way merge on 409 or on a feed68 row, conflicts recorded with both copies, compare-and-set writes). A 2.x server keeps the 1.0 behaviour exactly.69- `SyncStatus.rejected`, `SyncStatus.canvasConflicts`; `SyncOptions.entityKinds`, `metaMaxAge`; `engine.serverFeatures()`.70- Repositories layer (`docs/REPOSITORIES.md`): `NotesRepositories` → `TasksRepository`, `CanvasRepository`,71 `DatabasesRepository` (+ `DatabaseEvaluator`: the server's filter / sort / search rules on the device, grouping),72 `GraphRepository`, `TimelineRepository`, `KnowledgeRepository`, `ResearchRepository`, `InboxRepository`, `SearchRepository`,73 `AssistantRepository`, `AudioRepository`; `RepositoryError` (typed `.offline`, no silent queueing), `Cached<T>`,74 `CachePolicy`, `Staleness`.75- Reminders stay push-only (the mapping to task sync is not safe: `SYNC_ENGINE.md` §7.6).76- 121 tests (67 → 121): entity feed, task outbox, canvas sync, repositories, a seeded convergence test of tasks and canvases77 (1 512 seeds green), 3 live scenarios.7879**SPNotesStore**80- `EntityIndex` reads the keys of the real feed rows (`fromId` / `toId`, `pageId` of a reference);81 `retryEntityOps(id:state:where:)`, `expediteEntityOps(id:)`, `saveCanvas(pageId:json:ifUnchangedFrom:)`,82 `resolveCanvas(…ifEditSeq:)` (compare-and-set, returns whether it wrote).8384**SPNotesTestSupport (new product, tests only)**85- The in-memory fake backend, moved out of the test target so that the apps can use it: 3.0 level (meta, entity feed, tasks,86 canvases, opaque entities), 2.x level, scriptable routes (`stub`), fault injection.8788**SPNotesDesign**89- Exact colours of SPEC §7 (measured sRGB of the web tokens) and `successText / warningText / dangerText`.9091### Wave 3 — SPNotesFeatures (branch `next-features`, 2026-11-19)9293**SPNotesFeatures (new product)** — the cross-platform SwiftUI feature screens of SPEC §8, each an `@Observable` view model over94`NotesRepositories` plus compact / regular views: `TasksScreen`, `InboxScreen`, `DatabaseScreen`, `UnifiedSearchScreen`,95`GraphScreen`, `ConstellationScreen`, `TimelineScreen` + `TimeMachineView`, `KnowledgeHealthScreen`, `DailyBriefScreen`,96`SemanticZoomControl` + `PageOutlineView`, `AskScreen`, `ModelPickerView`, `ResearchScreen`, `CanvasScreen`,97`CommandCenterView` + `CommandRegistry`, and the block views `MermaidBlockView`, `DrawingBlockViewer` + `InkEditorView`,98`ChartBlockView`, `QueryViewBlockView`, `BlockRefView`, `CitationPickerView`, `BibliographyView`, `PDFBlockView`,99`RunCodeBlockView`, `AudioBlockView`. Hosting guide, router, plist keys and known limits: `docs/FEATURES.md`.100101**SPNotesFeaturesCatalog (new product, debug / tests only)** — `FeatureCatalogView`, `FeatureWorld`, `FeatureSamples`.102103**SPNotesAPI / SPNotesSync / SPNotesStore** (additive)104- `NotesAPI.graphConstellation(refresh:)`, `ConstellationProjection`, `ServerFeature.constellation`,105 `GraphRepository.constellation(refresh:policy:)` — feature-gated: no request unless `/api/meta` lists the feature.106- `EventRecord.pageTitle / pageIcon` (from the server's answer; offline the title is read from the device's page; not stored).107- `AIMessageSource.n`.108- Fixed: `DatabasesRepository.rows()` lost the view's sort order inside groups when the rows came from the server.109110### Wave 3 — small additive items asked by the apps (2026-11-19)111- `MarkdownExport`: underline, subscript and superscript are written `<u>…</u>`, `<sub>…</sub>`, `<sup>…</sup>` like the server112 (web arbitration); `expected.json` re-recorded from the integration worktree, `next-server.json` re-recorded (identical).113- `NodeType.blockIdTypes` (the block-id type list, public); `TaskItemPriority` (SPNotesDocument) and `TaskRowPriority` (SPNotesAPI):114 names that collide with nothing for the two `TaskPriority` enums (both kept: unifying them would break both apps).115- `TaskItem.isBareDay` / `dueDay(timeZone:)`; `PMNode.footnoteRef(id:)`, `Line.footnote(id:_:)`, `NoteDocument.nextFootnoteLabel()`.116- `PageDraft.inboxAt` / `captureKind`: `SyncEngine` sends them at creation, so a capture made offline stays a capture on a 3.0117 server; `applyRemote` keeps a local `captureKind` when the server sends none; `FakeBackend` honours both.118- `InkRenderer.pressure(forWidth:nominal:)` (inverse of `penWidth`); the pen width law is stated in `DOCUMENT_API.md`.119- `KnowledgeRepository.cacheKey(for:)`; `FakeBackend.taskSnapshots()` / `pageSnapshot(_:)`.120121### Wave 3b — integration hardening of the server (next-int @ 612271e)122- `APIError.NextCode`: the default codes every error body now carries (`invalid_state`, `too_large`, `upstream_error`, `internal`),123 `bad_filter`, `last_view`, `reference_deleted`; `HealthScore.truncated`.124- `FakeBackend` (API level 3): default error `code` by status; `DELETE /api/tasks/<id>` of an unknown id answers `200 {ok, deleted:false}`.125- Live tests follow the new contract (idempotent relation delete, coded validation errors, the 3.0 capture kinds accepted).126- `InkWidthLawTests` asserts the fixture shared with the web (`Fixtures/ink-width-law.json`).127- Not done: the recorded fixtures of `Fixtures/next` are still the pre-hardening recordings. Re-recording against 8486 works128 (10 groups, 383 files) but 62 assertions of the fixture tests pin the old answers (errors without `code`, non-idempotent129 deletes, 2.x capture kinds, `201` on a known reference id…): they must be rewritten with the recordings, as one change.130131### What the apps must know132- Wave 2 is source-compatible with both 1.x apps (they build unchanged). `PageType` and `TaskStatus` gained a case133 (`canvas`, `doing`): a `switch` over them without `default` must add it (neither app has one).134- `SyncStatus.pending` now also counts queued task operations and edited canvases.135- First cycle of 2.0 against a 3.0 server reads the whole feed again from 0 (cursor rule), once.136- `ensureBlockIds()` now gives ids to list items: a 2.x document is no longer unchanged by "load then serialize" (the macOS137 editor test `everyNodeOfTheWebSchemaSurvivesARoundTripUntouched` must expect it).138- A `switch` over `StoreChange` or `StoreError` without `default` must add the new cases (neither app has one today).139- A 1.x build refuses a database migrated to v2.140141## 1.0 — 2026-11-18142Document model, local store, API client and sync engine shared by SP Notes iOS and macOS.143