SPB Git

Repository Public

CHANGELOG.md 10.7 KB

# 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 kinds decision, question, hypothesis; block ids on listItem / taskItem and on the new blocks.
  • attachmentReferences() and pageReferences() 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, not 1e-07).

# SPNotesStore

  • Schema v2 (additive): generic entities with typed queries, ordered entity_ops outbox, canvases, events, kv_cache, sync_cursors, ops_parked. See docs/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.
  • StoreChange gains entities, entityQueue, canvases, events, cache; StoreError gains backup.

# SPNotesAPI

  • Opt-in retry with backoff for requests that are safe to retry (RetryPolicy, HTTPRequest.retrying(), isSafeToRetry, newIdempotencyKey()), honouring Retry-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 components NVCard, NVChip, NVSectionHeader, NVEmptyState, NVAIBadge, NVCitationChip, NVToolbarGlass, NVProgressDots. See docs/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 with kinds, 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 in Scripts/); 32 live tests gated on SPN_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 kinds and applied to entities (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 with baseVersion, 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

  • EntityIndex reads the keys of the real feed rows (fromId / toId, pageId of 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/meta lists 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.json re-recorded from the integration worktree, next-server.json re-recorded (identical).
  • NodeType.blockIdTypes (the block-id type list, public); TaskItemPriority (SPNotesDocument) and TaskRowPriority (SPNotesAPI): names that collide with nothing for the two TaskPriority enums (both kept: unifying them would break both apps).
  • TaskItem.isBareDay / dueDay(timeZone:); PMNode.footnoteRef(id:), Line.footnote(id:_:), NoteDocument.nextFootnoteLabel().
  • PageDraft.inboxAt / captureKind: SyncEngine sends them at creation, so a capture made offline stays a capture on a 3.0 server; applyRemote keeps a local captureKind when the server sends none; FakeBackend honours both.
  • InkRenderer.pressure(forWidth:nominal:) (inverse of penWidth); the pen width law is stated in DOCUMENT_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 error code by status; DELETE /api/tasks/<id> of an unknown id answers 200 {ok, deleted:false}.
  • Live tests follow the new contract (idempotent relation delete, coded validation errors, the 3.0 capture kinds accepted).
  • InkWidthLawTests asserts the fixture shared with the web (Fixtures/ink-width-law.json).
  • Not done: the recorded fixtures of Fixtures/next are 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 without code, non-idempotent deletes, 2.x capture kinds, 201 on 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). PageType and TaskStatus gained a case (canvas, doing): a switch over them without default must add it (neither app has one).
  • SyncStatus.pending now 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 test everyNodeOfTheWebSchemaSurvivesARoundTripUntouched must expect it).
  • A switch over StoreChange or StoreError without default must 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.

Files main
Menu

Theme