Changelog
2.0.0 — SP Note Next Generation (branch next, not released)
Goes with web / backend 3.0.0 and SP Notes macOS / iOS 2.0.0 (SPEC §1). Both 1.x apps compile against it unchanged.
SPNotesDocument
- Typed support for the 3.0 nodes:
mermaid,drawing,chart,queryView,citation(inline),bibliography,pdf,blockRef,runCode,audio,canvasLink— node types, schema sets, defaults, validator, and typed views (MermaidBlock,DrawingBlock,ChartBlock,QueryViewBlock,CitationInline,BibliographyBlock,PDFBlock+PDFAnnotation,BlockRefBlock,RunCodeBlock,AudioBlock+TranscriptSegment,CanvasLinkBlock,TypedBlock). Unknown attributes inside known nodes and unknown nodes still round-trip byte for byte. - Markdown, plain text, word count and HTML of the new nodes, ported from the server and verified byte for byte on the backend's published fixtures and on 521 documents recorded from its own functions. Transcript and annotation text are part of the plain text (search index).
- New optional attributes:
taskItem.due / priority / taskId,aiBlock.sources / action; callout kindsdecision,question,hypothesis; block ids onlistItem/taskItemand on the new blocks. attachmentReferences()andpageReferences()include the files and targets of the new nodes;citedReferences(),taskItemDetails().InkDocument(spn-ink-1) with simplification, bounding box, hit testing and a CoreGraphics renderer (InkRenderer).CanvasDocument(spn-canvas-1) with a three-way merge by node / edge id and deterministic auto-layout (CanvasLayout).- Fixed: numbers in exported text follow ECMAScript (
1e-7, not1e-07).
SPNotesStore
- Schema v2 (additive): generic
entitieswith typed queries, orderedentity_opsoutbox,canvases,events,kv_cache,sync_cursors,ops_parked. Seedocs/MIGRATION-V2.md. - Pre-migration backup of the database file, removed at a later healthy open.
NotesStore.open(url:)→StoreOpenResult/StoreOpenError(typed, with a user message) so that apps stop falling back to an empty in-memory store.StoreChangegainsentities,entityQueue,canvases,events,cache;StoreErrorgainsbackup.
SPNotesAPI
- Opt-in retry with backoff for requests that are safe to retry (
RetryPolicy,HTTPRequest.retrying(),isSafeToRetry,newIdempotencyKey()), honouringRetry-After. Default behaviour unchanged.
SPNotesSync
- Fixed: a queued op of an unknown kind was silently dropped; it is now parked and surfaced (
SyncStatus.unsupported).
SPNotesDesign (new product)
- Note Visual System 2.0 « Graphite & Ultramarine · Lumen »:
NVColor,NVFont,NVSpace,NVRadius,NVElevation,NVMotion, the seven signature motions, and the componentsNVCard,NVChip,NVSectionHeader,NVEmptyState,NVAIBadge,NVCitationChip,NVToolbarGlass,NVProgressDots. Seedocs/DESIGN.md.
Wave 2 — clients of API-NEXT, entity sync, repositories (2026-11-19)
SPNotesAPI
- Typed clients for every route of
API-NEXT.md(meta / features, feed withkinds, tasks with client ids, graph views, relations, concepts, insights, events, time machine and restore by entry id, knowledge health, brief, living blocks, canvases, zoom, ranged and resumable file downloads), for the AI workstream (API-NEXT-AI.md: model catalogue, ask scopes, new actions and link suggestions, synopsis, transcription, smart database properties) and for the 2.x route groups the natives lacked (databases, search, backlinks / neighbours / suggestions, inbox, capture, research, AI conversations and usage, agents, dashboard, settings, trash). 243 tests; every DTO decoded from a recorded answer of the scratch backend (Fixtures/next, recorder inScripts/); 32 live tests gated onSPN_LIVE_URL. - Typed error accessors for the codes of API-NEXT §5; no case added to
APIError. PageType.canvas,TaskStatus.doing,TaskItem.blockId / deletedAt / rev,TaskDraft.id / blockId / status / due,SyncPage.entities,HTTPRequest.extraHeaders,HTTPClient.openBytes.
SPNotesSync
- Entity sync: the feed is asked with
kindsand applied toentities(cursor rule, soft deletes, tombstones of the new kinds — they were skipped —, reset, full-copy cleanup); task outbox (create / update / delete with client ids, ordered, idempotent, rejected operations kept and surfaced); canvases (PUT withbaseVersion, three-way merge on 409 or on a feed row, conflicts recorded with both copies, compare-and-set writes). A 2.x server keeps the 1.0 behaviour exactly. SyncStatus.rejected,SyncStatus.canvasConflicts;SyncOptions.entityKinds,metaMaxAge;engine.serverFeatures().- Repositories layer (
docs/REPOSITORIES.md):NotesRepositories→TasksRepository,CanvasRepository,DatabasesRepository(+DatabaseEvaluator: the server's filter / sort / search rules on the device, grouping),GraphRepository,TimelineRepository,KnowledgeRepository,ResearchRepository,InboxRepository,SearchRepository,AssistantRepository,AudioRepository;RepositoryError(typed.offline, no silent queueing),Cached<T>,CachePolicy,Staleness. - Reminders stay push-only (the mapping to task sync is not safe:
SYNC_ENGINE.md§7.6). - 121 tests (67 → 121): entity feed, task outbox, canvas sync, repositories, a seeded convergence test of tasks and canvases (1 512 seeds green), 3 live scenarios.
SPNotesStore
EntityIndexreads the keys of the real feed rows (fromId/toId,pageIdof a reference);retryEntityOps(id:state:where:),expediteEntityOps(id:),saveCanvas(pageId:json:ifUnchangedFrom:),resolveCanvas(…ifEditSeq:)(compare-and-set, returns whether it wrote).
SPNotesTestSupport (new product, tests only)
- 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,
canvases, opaque entities), 2.x level, scriptable routes (
stub), fault injection.
SPNotesDesign
- Exact colours of SPEC §7 (measured sRGB of the web tokens) and
successText / warningText / dangerText.
Wave 3 — SPNotesFeatures (branch next-features, 2026-11-19)
SPNotesFeatures (new product) — the cross-platform SwiftUI feature screens of SPEC §8, each an @Observable view model over
NotesRepositories plus compact / regular views: TasksScreen, InboxScreen, DatabaseScreen, UnifiedSearchScreen,
GraphScreen, ConstellationScreen, TimelineScreen + TimeMachineView, KnowledgeHealthScreen, DailyBriefScreen,
SemanticZoomControl + PageOutlineView, AskScreen, ModelPickerView, ResearchScreen, CanvasScreen,
CommandCenterView + CommandRegistry, and the block views MermaidBlockView, DrawingBlockViewer + InkEditorView,
ChartBlockView, QueryViewBlockView, BlockRefView, CitationPickerView, BibliographyView, PDFBlockView,
RunCodeBlockView, AudioBlockView. Hosting guide, router, plist keys and known limits: docs/FEATURES.md.
SPNotesFeaturesCatalog (new product, debug / tests only) — FeatureCatalogView, FeatureWorld, FeatureSamples.
SPNotesAPI / SPNotesSync / SPNotesStore (additive)
NotesAPI.graphConstellation(refresh:),ConstellationProjection,ServerFeature.constellation,GraphRepository.constellation(refresh:policy:)— feature-gated: no request unless/api/metalists the feature.EventRecord.pageTitle / pageIcon(from the server's answer; offline the title is read from the device's page; not stored).AIMessageSource.n.- Fixed:
DatabasesRepository.rows()lost the view's sort order inside groups when the rows came from the server.
Wave 3 — small additive items asked by the apps (2026-11-19)
MarkdownExport: underline, subscript and superscript are written<u>…</u>,<sub>…</sub>,<sup>…</sup>like the server (web arbitration);expected.jsonre-recorded from the integration worktree,next-server.jsonre-recorded (identical).NodeType.blockIdTypes(the block-id type list, public);TaskItemPriority(SPNotesDocument) andTaskRowPriority(SPNotesAPI): names that collide with nothing for the twoTaskPriorityenums (both kept: unifying them would break both apps).TaskItem.isBareDay/dueDay(timeZone:);PMNode.footnoteRef(id:),Line.footnote(id:_:),NoteDocument.nextFootnoteLabel().PageDraft.inboxAt/captureKind:SyncEnginesends them at creation, so a capture made offline stays a capture on a 3.0 server;applyRemotekeeps a localcaptureKindwhen the server sends none;FakeBackendhonours both.InkRenderer.pressure(forWidth:nominal:)(inverse ofpenWidth); the pen width law is stated inDOCUMENT_API.md.KnowledgeRepository.cacheKey(for:);FakeBackend.taskSnapshots()/pageSnapshot(_:).
Wave 3b — integration hardening of the server (next-int @ 612271e)
APIError.NextCode: the default codes every error body now carries (invalid_state,too_large,upstream_error,internal),bad_filter,last_view,reference_deleted;HealthScore.truncated.FakeBackend(API level 3): default errorcodeby status;DELETE /api/tasks/<id>of an unknown id answers200 {ok, deleted:false}.- Live tests follow the new contract (idempotent relation delete, coded validation errors, the 3.0 capture kinds accepted).
InkWidthLawTestsasserts the fixture shared with the web (Fixtures/ink-width-law.json).- Not done: the recorded fixtures of
Fixtures/nextare still the pre-hardening recordings. Re-recording against 8486 works (10 groups, 383 files) but 62 assertions of the fixture tests pin the old answers (errors withoutcode, non-idempotent deletes, 2.x capture kinds,201on a known reference id…): they must be rewritten with the recordings, as one change.
What the apps must know
- Wave 2 is source-compatible with both 1.x apps (they build unchanged).
PageTypeandTaskStatusgained a case (canvas,doing): aswitchover them withoutdefaultmust add it (neither app has one). SyncStatus.pendingnow also counts queued task operations and edited canvases.- First cycle of 2.0 against a 3.0 server reads the whole feed again from 0 (cursor rule), once.
ensureBlockIds()now gives ids to list items: a 2.x document is no longer unchanged by "load then serialize" (the macOS editor testeveryNodeOfTheWebSchemaSurvivesARoundTripUntouchedmust expect it).- A
switchoverStoreChangeorStoreErrorwithoutdefaultmust add the new cases (neither app has one today). - A 1.x build refuses a database migrated to v2.
1.0 — 2026-11-18
Document model, local store, API client and sync engine shared by SP Notes iOS and macOS.