SPNotesStore — public API and semantics
SPNotesStore is the durable local database of the native SP Notes apps. It depends on Foundation and the
system SQLite only. It does not import SPNotesDocument: note content is opaque JSON Data, and the
caller supplies the derived plain text, word count and preview.
Rule of the module: no note is ever lost. Local edits are never overwritten by the feed; every mutation is one atomic SQLite transaction; nothing waits for the network.
1. Engine
public actor NotesStore {
public init(url: URL, readOnly: Bool = false) throws
public static func inMemory() throws -> NotesStore
public nonisolated let isReadOnly: Bool
public static var schemaVersion: Int // 2
public static func open(url:readOnly:backupRetention:) -> StoreOpenResult // 2.0: typed outcome, see §12.1
public func close()
public func integrityCheck() throws -> [String] // empty = healthy
public func checkpoint() throws // wal_checkpoint(TRUNCATE)
public func rebuildSearchIndex() throws
public func wipeAll() throws // "erase this device" only
}- Every method is
throwsand actor-isolated (try await store.…). Methods are synchronous inside the actor: two calls never interleave. - Connection:
SQLITE_OPEN_FULLMUTEX,journal_mode=WAL,synchronous=FULL,foreign_keys=ON,busy_timeout8 s. Write transactions areBEGIN IMMEDIATE; an error thrown inside one rolls it back entirely (index, tags, queue and cursor included) and publishes no change event. - The same file may be opened by several processes: the app (read/write), a share extension (read/write, its
own
NotesStore), a widget (readOnly: true). A read-only store never creates nor migrates the file (StoreError.schemaif the file is older than the build; an SQLite error if it does not exist), refuses every mutation withStoreError.readOnly(this includesnextOps, which leases), and sees every committed transaction of the writers. The directory must be writable by the reader (SQLite needs the-shmfile). - Schema:
PRAGMA user_version, one transaction per migration step (step + version bump commit together). A file newer than the build is refused (StoreError.schema). - Timestamps are stored as integer milliseconds since the Unix epoch and exposed as
Date(sub-millisecond precision is rounded on write). - Ids are lowercase UUID strings. Ids given by the caller are lowercased.
close(): later calls throwStoreError.closed; change streams finish.wipeAll()deletes every row of every table, meta included. Attachment files belong to the caller.
public enum StoreError: Error, Sendable, Equatable {
case sqlite(code: Int32, message: String, sql: String?)
case notFound(String) // the row addressed by the call does not exist
case invalid(String) // rejected argument (duplicate id, properties not a JSON object, …)
case cycle // move into the page's own subtree
case readOnly
case closed
case schema(String)
}2. Pages
2.1 Model
PageRecord (full row), all fields public var:
| Field | Meaning |
|---|---|
id, parentId, databaseId, type, section, title, icon, cover |
server fields |
content: Data |
opaque document JSON |
properties: Data |
JSON object |
position: Double, pinned, archived |
server fields |
serverVersion: Int |
the server version this row is based on; 0 = never on the server. It is the baseVersion of the next PATCH. (The server's version and the local serverVersion are one column.) |
wordCount, createdAt, updatedAt, lastOpenedAt, deletedAt, inboxAt, captureKind, rev |
server fields; updatedAt is stamped locally by content edits until the server answers |
tags: [String] |
sorted names |
needsCreate |
the row must be created on the server |
dirtyContent |
title, content or properties changed locally since the base |
dirtyMeta: Set<MetaField> |
parentId, section, position, pinned, archived, icon, cover, inboxAt changed locally |
tagsDirty |
tags changed locally |
editSeq: Int64 |
+1 on every local change that has to be pushed |
syncState |
conflict if a conflict record exists; else error if dirty with a syncError; else pending if dirty; else synced |
syncError: String? |
set by markPushFailed, cleared by the next local edit or successful push |
plainText, preview |
supplied by the caller |
favorite, isFolder |
mirrors of properties.favorite == true / properties.folder == true |
localUpdatedAt |
last local change |
isDirty (computed) |
`needsCreate |
PageSummary (lists; no content, properties nor plain text): id, title, preview, updatedAt, parentId, section, pinned, favorite, isFolder, icon, tags, syncState, hasChildren (at least one child not in the trash), plus
type, position, archived, wordCount, lastOpenedAt, deletedAt, inboxAt.
Base copy. PageBase { title, content, properties, version } is the last synced copy of the
version-guarded fields. It is captured the first time a page that is on the server and content-clean gets a
content edit (title/content/properties), is kept unchanged by later edits, and is dropped when the content
becomes clean again (markPushed, feed echo, resolveConflictUsingCopy). A page never pushed has no base.
Meta-only and tag-only edits do not create a base.
2.2 Local mutations
Each is ONE transaction. Unless said otherwise each bumps editSeq, stamps localUpdatedAt, clears
syncError, recomputes syncState, maintains the FTS index and emits .pages([id]). All throw
notFound("page <id>") on an unknown id. The Bool results say whether anything changed (a no-op writes
nothing and bumps nothing).
public func createPage(_ draft: NewPage = NewPage()) throws -> PageRecord
public func createPages(_ drafts: [NewPage]) throws -> [String] // one transaction, all or nothing
public func updateContent(id: String, title: String? = nil, content: Data? = nil,
plainText: String, wordCount: Int, preview: String) throws -> Bool
public func setProperties(id: String, properties: Data, favorite: Bool? = nil, isFolder: Bool? = nil) throws -> Bool
public func setFavorite(id: String, _ favorite: Bool) throws -> Bool
public func setFolder(id: String, _ isFolder: Bool) throws -> Bool
public func setPinned(id: String, _ pinned: Bool) throws -> Bool
public func setArchived(id: String, _ archived: Bool) throws -> Bool
public func setIcon(id: String, _ icon: String?) throws -> Bool
public func setCover(id: String, _ cover: String?) throws -> Bool
public func setInbox(id: String, at date: Date?) throws -> Bool
public func move(id: String, parentId: String?, section: String? = nil, position: Double? = nil) throws -> Bool
public func setTags(id: String, names: [String]) throws -> Bool
public static func normalizeTags(_ names: [String]) -> [String]
public func trash(id: String) throws -> [String]
public func restore(id: String) throws -> [String]
public func purge(id: String) throws -> PurgeResult
public func duplicate(id: String) throws -> PageRecord
public func markOpened(id: String, at date: Date = Date()) throws- createPage:
NewPage(id:parentId:databaseId:type:section:title:icon:cover:content:properties:position:pinned:plainText:wordCount:preview:tags:inboxAt:captureKind:), every argument optional.idnil → generated UUID.sectionnil → the parent's, or"notes".positionnil → after the last sibling. The row isneedsCreate,dirtyContent,tagsDirtyif it has tags,editSeq = 1,serverVersion = 0,syncState = pending. Throwsinvalid(id exists, properties not a JSON object) ornotFound(parent). - updateContent:
title/contentnil = unchanged. Returnsfalseand writes nothing when neither the title nor the content bytes differ. Otherwise stores them withplainText,wordCount,preview, setsdirtyContent, stampsupdatedAt. - setProperties: replaces the object (must be a JSON object). No-op when equal ignoring key order. The
favorite/isFoldermirrors come from the arguments when given, otherwise from the top level of the JSON. SetsdirtyContent(properties are version-guarded) and stampsupdatedAt.setFavorite/setFolderset"favorite": true/"folder": trueor remove the key, and re-serialise the object with sorted keys. - setPinned / setArchived / setIcon / setCover / setInbox: add the field to
dirtyMeta.updatedAtis not touched. - move:
parentIdnil = root.sectionnil = the new parent's section (the current one at the root).positionnil = after the last sibling if the parent changes, unchanged otherwise. Adds the changed fields amongparentId, section, positiontodirtyMeta. A section change is propagated to all descendants (each getssectionindirtyMeta). ThrowscycleifparentIdis the page or one of its descendants,notFoundif the parent does not exist; a rejected move changes nothing. - setTags: names are normalised like the server — trimmed, leading
#removed, lowercased, at most 40 characters, empties dropped, unique (first wins), at most 20. No-op when the set is unchanged. SetstagsDirty; emits.tags. - trash: stamps
deletedAton the page and on its descendants reachable through pages that are not already in the trash (server behaviour), and queues ONE optrashwithtargetId = id. Returns the ids trashed (empty, and no op, if the page already was in the trash). Trash is not a dirty state: noeditSeqbump, no dirty flag. - restore: clears
deletedAton the page and ALL its descendants; returns the ids restored (empty and no op if none was trashed). Queues an oprestore, except when the newest queued trash/restore/purge op of that page is atrashthat was never returned bynextOps, has 0 attempts, and was issued while no descendant was already in the trash: that op is deleted instead (the pair cancels out). - purge: removes the page and all its descendants locally, with bases, conflicts, local versions, tags,
index entries and attachment rows (
PurgeResult.orphanedFileslists the relative paths of their files); reminders of those pages are deleted (or flaggeddeleted + dirtywhen the server knows them). Queued trash/restore/purge ops of those pages are dropped (except one currently leased). For pages the server knows (!needsCreate), one oppurgeis queued for EVERY page of the subtree (the server's purge removes a single row; it does not cascade to the pages inside). Pages that areneedsCreatedisappear with all their ops and leave nothing in the queue. - duplicate: new local page (fresh id,
needsCreate) titled"<title> (copy)", same parent, section, type, content, properties, icon, cover, tags and derived text, placed right after the original; not pinned, not in the inbox, not trashed. Descendants are not copied. - markOpened: stamps
lastOpenedAtonly (not dirty,editSequnchanged).
2.3 Queries
public func page(id: String) throws -> PageRecord?
public func summary(id: String) throws -> PageSummary?
public func pageCount() throws -> Int
public func summaries(list: SmartList, section: String? = nil, limit: Int = 200, offset: Int = 0) throws -> [PageSummary]
public func children(of parentId: String?, section: String? = nil, includeArchived: Bool = false) throws -> [PageSummary]
public func folderTree(section: String? = nil) throws -> [PageSummary]
public func ancestors(of id: String) throws -> [PageSummary]
public func summaries(tag: String, limit: Int = 200, offset: Int = 0) throws -> [PageSummary]
public func tags() throws -> [TagInfo] // name, color, count
public func counts() throws -> ListCounts // all, pinned, favorites, inbox, archived, trash, pending, conflictsSmartList |
Set | Order |
|---|---|---|
.all |
not trashed, not archived | updatedAt desc |
.recent |
same as .all |
max(updatedAt, lastOpenedAt) desc |
.pinned / .favorites |
flag set, not trashed, not archived | updatedAt desc |
.inbox |
inboxAt set, not trashed |
inboxAt desc |
.archived |
archived, not trashed | updatedAt desc |
.trash |
deletedAt set |
deletedAt desc |
Lists contain every page type, folders included. They are served from partial indexes (no scan, no sort).
children(of: nil, section:) returns the root pages of a section; children are ordered by position, then
title. folderTree is a flat list of the folder pages (not trashed, not archived) ordered by section then
position; build the tree from parentId. ancestors goes from the parent up to the root. tags() lists the
tags received from the server plus those used locally; count = notes carrying the tag that are neither
trashed nor archived. ListCounts.pending = pages with isDirty.
3. Search
public func search(query: String, filters: SearchFilters = SearchFilters(), limit: Int = 50) throws -> [SearchHit]
public struct SearchFilters { // all optional, combined with AND
var section: String?
var folderId: String? // descendants of this page (the page itself excluded)
var tags: [String] // ALL of these (normalised)
var updatedAfter: Date? // inclusive
var updatedBefore: Date? // inclusive
var favoritesOnly: Bool
var pinnedOnly: Bool
var includeArchived: Bool // default false
var includeTrash: Bool // default false
}
public struct SearchHit { var page: PageSummary; var snippet: String; var highlightedTitle: String; var score: Double }- FTS5 table (
title,body= plain text,tags), tokenizerunicode61 remove_diacritics 2: case and diacritics are ignored (étefindsÉté). The index is incremental: only the page touched by a mutation is re-indexed (delete by rowid + insert), inside the same transaction. - The query is split on every character that is not a letter, digit or combining mark. Every term must match
(any column, any order); the last term matches as a prefix. Terms are quoted, so FTS operators, quotes,
parentheses,
NEAR, column filters, etc. are plain text: no input can cause a syntax error. At most the last 32 terms are used. - Order: bm25 with weights title 10, tags 4, body 1 (
score, lower is better). snippet: an excerpt of the body around the match;highlightedTitle: the title. Matches are wrapped inSearchHit.highlightStart(U+E000) /highlightEnd(U+E001).SearchHit.segments(of:)returns[(text, highlighted)];SearchHit.plain(_:)strips the markers.- A query with no term (empty, punctuation only) returns the pages matching the filters, newest
updatedAtfirst, withsnippet = preview,highlightedTitle = title,score = 0. - Trashed and archived pages stay in the index; they are excluded by default by the filters.
4. Sync primitives
The cursor is meta["sync.cursor"]:
syncCursor() -> Int64 (0 = never synced), setSyncCursor(_:).
4.1 Push
public func pagesNeedingPush(limit: Int = 100, includeConflicts: Bool = false) throws -> [PendingPage] // page + base
public func pendingPushCount() throws -> Int
public func pageBase(id: String) throws -> PageBase?
public func markPushed(id: String, serverVersion: Int, updatedAt: Date, pushedEditSeq: Int64,
pushed: PushedCopy? = nil, serverContent: Data? = nil) throws
public func markPushFailed(id: String, error: String) throwspagesNeedingPush: everyisDirtypage with its full row and base copy. Pages to create come first, parents before children (depth in the chain ofneedsCreateancestors), then the others by oldest local change. Pages inconflictare left out unlessincludeConflicts.errorpages are included.- What to send:
needsCreate→ create the page with the whole row;dirtyContent→PATCHtitle/content/ properties withbaseVersion = page.serverVersion;dirtyMeta→ those fields;tagsDirty→ the tags. Rememberpage.editSeq(and the title/content/properties sent) for the acknowledgement. markPushedacknowledges a successful push of the row as it was atpushedEditSeq:editSeq == pushedEditSeq:needsCreate,dirtyContent,dirtyMeta,tagsDirtycleared, base dropped,serverVersionandupdatedAtset,syncState = synced.serverContent(the server's normalised content), when given, replaces the local content.- otherwise (edited during the push): nothing local is overwritten;
needsCreateis cleared andserverVersionadvances. Withpushed(pass it): if the current title/content/properties still equal what was sent (only meta or tags changed meanwhile),dirtyContentis cleared and the base dropped; else the page staysdirtyContentand the base becomes{pushed.title, serverContent ?? pushed.content, pushed.properties, version: serverVersion}. Withoutpushed, the page stays as dirty as it was and the existing base (an older ancestor) is left untouched.dirtyMetaandtagsDirtyare kept (re-pushing them is idempotent). - Throws
notFoundif the page was purged locally during the push: the engine should then delete the page it just created on the server.
markPushFailed:syncError = error,syncState = error; the page stays dirty and listed.- On a 409: call
recordConflict(§5) or one of the resolution helpers (§4.3).
4.2 Pull
public func applyRemote(pages: [RemotePage] = [], attachments: [RemoteAttachment] = [], tombstones: [Tombstone] = [],
tags: [RemoteTag]? = nil, cursor: Int64? = nil) throws -> ApplySummary
public func resetSyncState() throws
public func removeSyncedPages(notIn ids: Set<String>) throws -> PurgeResultRemotePage carries every server field (version, rev, tags, …) plus plainText and preview, which
the caller derives from content. applyRemote is ONE transaction (all or nothing, cursor included).
For each remote page:
| Local row | Effect |
|---|---|
| none | inserted as synced (serverVersion = remote.version), tags and index included → insertedPageIds |
rev greater than remote.rev |
ignored (stale feed page) |
| clean | every field replaced by the remote copy, tags included; nothing is snapshotted. (lastOpenedAt keeps the most recent of both. If remote.version < serverVersion, the version-guarded fields are kept.) |
| dirty | needsCreate cleared (the row exists on the server). Each meta field not in dirtyMeta takes the remote value. Tags replaced unless tagsDirty. Version-guarded fields: see below. |
Version-guarded fields of a dirty page:
- no pending content edit (
dirtyContent == false) → the remote title/content/properties/derived/version are adopted; dirtyContentandremote.version == serverVersion(or lower) → nothing to do;dirtyContentandremote.version > serverVersion:- remote title, content bytes and properties (key order ignored) equal the local ones — this device's own
push whose acknowledgement was lost — → version adopted,
dirtyContentcleared, base and conflict dropped; - otherwise the page is returned in
ApplySummary.divergedasDivergedPage(id, remote)and its local content, base,serverVersionandupdatedAtare not touched. The engine decides: three-way merge withpageBase(id:), thenresolveConflictKeepingLocal(…, merged:), orrecordConflict, orresolveConflictUsingCopy.
- remote title, content bytes and properties (key order ignored) equal the local ones — this device's own
push whose acknowledgement was lost — → version adopted,
deletedAt follows the server, except for pages covered by a queued local trash/restore op (the page or
one of its ancestors is the op's target): their local value is kept until the op is completed.
Tombstones:
- page, local row clean → removed with base, conflict, local versions, tags, index entry, attachment rows
(their files in
orphanedFiles) and its queued trash/restore/purge ops →deletedPageIds; - page, local row dirty → kept:
needsCreate = true,serverVersion = 0,dirtyContent = true,tagsDirtyif it has tags,dirtyMetaemptied, base and conflict dropped →resurrectedPageIds. ItsdeletedAtis left as it is locally; - after page tombstones, every dirty page whose parent no longer exists is moved to the root of its section
(
parentId = nil,parentIdadded todirtyMeta); - attachment → row removed (file path in
orphanedFiles) →deletedAttachmentIds; - unknown ids are ignored.
Attachments are upserted: unknown → state = remote; known → server fields updated, state, localPath,
keepOffline, lastAccessedAt, attempts kept. A row still waiting for upload that the server already lists
becomes uploaded / local. A remote deletedAt is applied; a local deletion waiting in the queue is not
undone.
tags: nil = not part of this batch; otherwise the tag list and colours are replaced (names still used by
local pages stay listed). cursor: nil = unchanged.
ApplySummary: insertedPageIds, updatedPageIds, deletedPageIds, resurrectedPageIds, diverged, changedAttachmentIds, deletedAttachmentIds, orphanedFiles, tagsChanged. Applying the same batch twice changes
nothing the second time.
resetSyncState() (server reset): cursor = 0 and the stored rev of every page and attachment = 0 (change
sequences may restart). Nothing else changes: pages, dirty flags, bases, queue, conflicts stay. After the full
re-download, removeSyncedPages(notIn:) removes the pages that are clean and on the server
(serverVersion > 0) but absent from the complete id set; dirty and never-pushed pages are kept.
4.3 Conflict resolution
public func resolveConflictUsingCopy(id: String, copy: ContentCopy, version: Int, updatedAt: Date) throws
public func resolveConflictKeepingLocal(id: String, server: ServerCopy, merged: ContentCopy? = nil) throwsresolveConflictUsingCopy: replaces the local title/content/properties (and derived values) withcopy, stored as synced atversion:dirtyContentandneedsCreatecleared, base dropped, conflict record removed,editSeq + 1. If the title or content differ, the replaced local state is first saved as a local version (reason"conflict-local"). Pending meta and tag changes stay dirty.resolveConflictKeepingLocal: base copy := the server copy,serverVersion := server.version,needsCreatecleared,dirtyContent = true, conflict record removed,editSeq + 1: the next push is made against the server's current version. Withmerged, the local fields are first replaced by the merge result (the previous local state is saved as a local version, reason"conflict-local").
5. Conflicts
public func recordConflict(pageId: String, server: ServerCopy, detectedAt: Date = Date()) throws
public func conflict(pageId: String) throws -> ConflictRecord?
public func conflicts() throws -> [ConflictRecord] // oldest first
public func clearConflict(pageId: String) throwsOne row per page (ServerCopy { version, title, content, properties, updatedAt } + detectedAt); recording
again replaces it. recordConflict sets syncState = conflict and does not touch the local content; the page
keeps accepting local edits and stays out of pagesNeedingPush(). clearConflict only drops the record.
6. Ops queue
For actions that are not dirty state: OpKind.trash, .restore, .purge, .deleteAttachment, .createTask,
.updateTask, .deleteTask, .triage, or any string.
public func enqueueOp(kind: String, targetId: String? = nil, payload: Data? = nil) throws -> PendingOp
public func nextOps(limit: Int = 20, now: Date = Date(), lease: TimeInterval = 120) throws -> [PendingOp]
public func completeOp(id: Int64) throws
public func failOp(id: Int64, error: String, now: Date = Date()) throws -> PendingOp?
public func releaseOp(id: Int64) throws
public func releaseAllOpLeases() throws
public func queuedOps() throws -> [PendingOp]
public func opCount() throws -> Int
public static func backoffDelay(attempts: Int) -> TimeIntervalPendingOp { id (queue sequence), kind, targetId, payload, idempotencyKey, createdAt, attempts, nextAttemptAt, lastError }. The idempotency key is generated once per op (32 characters of [0-9a-f]) and never changes
across retries.
nextOpsreturns the due ops, oldest first, and leases them forleaseseconds: they are not returned again untilcompleteOp,failOp,releaseOp,releaseAllOpLeasesor the end of the lease. An op is held back while an older op with the same target is in backoff or leased, so per-target order is never broken; ops of other targets are not blocked.completeOpremoves the op (success, or definitive rejection). Unknown ids are ignored.failOp:attempts + 1, lease released,nextAttemptAt = now + backoffDelay(attempts)= 5 s, 10 s, 20 s … doubling, capped at 900 s (15 min).releaseOp: gives the op back without counting an attempt. CallreleaseAllOpLeases()when the engine starts.- The engine must push page creations before running an op whose target is
needsCreate.
7. Attachments
public func addLocalAttachment(id: String? = nil, pageId: String, filename: String, mime: String, size: Int64,
sha256: String?, localPath: String, pageCount: Int? = nil) throws -> AttachmentRecord
public func attachment(id: String) throws -> AttachmentRecord?
public func attachments(pageId: String, includeDeleted: Bool = false) throws -> [AttachmentRecord]
public func pendingUploads(limit: Int = 50) throws -> [AttachmentRecord]
public func markAttachmentUploading(id: String) throws
public func markAttachmentUploaded(id: String, size: Int64? = nil, sha256: String? = nil, pageCount: Int? = nil) throws
public func markAttachmentDownloading(id: String) throws
public func markAttachmentDownloaded(id: String, localPath: String, at date: Date = Date()) throws
public func markAttachmentFailed(id: String, error: String) throws
public func markAttachmentDeleted(id: String) throws -> String?
public func setAttachmentKeepOffline(id: String, _ keep: Bool) throws
public func touchAttachment(id: String, at date: Date = Date()) throws
public func evictionCandidates(limit: Int = 50) throws -> [AttachmentRecord]
public func attachmentsWantedOffline(maxSize: Int64, limit: Int = 50) throws -> [AttachmentRecord]
public func markAttachmentEvicted(id: String) throws
public func resetTransientAttachmentStates() throwsAttachmentRecord: server fields (id, pageId, filename, mime, size, sha256, pageCount, createdAt, deletedAt, rev) + state (remote | downloading | local | pendingUpload | uploading | failed), localPath (relative to
the attachments directory managed by the caller), keepOffline, uploaded (the server has the file),
uploadAttempts, lastError, lastAccessedAt.
addLocalAttachment: the file is already in place; rowpendingUpload,uploaded = false.pendingUploads: not uploaded, not deleted, statependingUploadorfailed, oldest first.markAttachmentUploaded:state = local,uploaded = true.markAttachmentFailed: never uploaded →state = failed,uploadAttempts + 1(still inpendingUploads; the engine applies its own delay); a failed download → back toremote(orlocalif a file is present).markAttachmentDeleted: never uploaded → the row is removed and no op is queued; otherwisedeletedAtis set and an opdeleteAttachment(targetId= attachment id) is queued. Returns the relative path of the local file for the caller to delete.evictionCandidates:state = local, uploaded, notkeepOffline; least recently used first (lastAccessedAt, stamped bymarkAttachmentDownloadedandtouchAttachment). After deleting the file callmarkAttachmentEvicted(state = remote, no path).attachmentsWantedOffline: what to download in the background — on the server, no local file, stateremote(a failed download goes back toremotewithlastError, so it is listed again;failedwithout a local file is accepted too), not deleted, page not in the trash, and eitherkeepOffline(any size) or an image (mime LIKE 'image/%') or drawing source (filename LIKE '%.pkdrawing') withsize <= maxSize. Newest (createdAt) first. Rows that aredownloadingare not listed.resetTransientAttachmentStates()at engine start:uploading → pendingUpload,downloading → remote/local.- Methods addressing an unknown id throw
notFound("attachment <id>").
8. Local versions
public func snapshot(pageId: String, reason: String) throws -> LocalVersionInfo?
public func localVersions(pageId: String) throws -> [LocalVersionInfo] // newest first, no content
public func localVersion(id: String) throws -> LocalVersion? // with content, plainText, preview
public func restoreVersion(id versionId: String) throws -> PageRecord
public static let maxLocalVersionsPerPage = 100snapshot saves the current title and content (returns nil and writes nothing when both are identical to the
latest snapshot of the page) and prunes to the newest 100 of that page. restoreVersion first snapshots the
current state (reason "before-restore"), then applies the snapshot as an ordinary local edit (dirtyContent,
editSeq + 1). The store itself only snapshots in the conflict helpers; periodic snapshots are the caller's.
9. Reminders
public func createReminder(id: String? = nil, pageId: String? = nil, title: String, dueAt: Date? = nil,
done: Bool = false, serverTaskId: String? = nil) throws -> ReminderRecord
public func updateReminder(id: String, title: String? = nil, dueAt: Date?? = nil, done: Bool? = nil) throws -> ReminderRecord
public func deleteReminder(id: String) throws
public func reminder(id: String) throws -> ReminderRecord?
public func reminders(pageId: String) throws -> [ReminderRecord]
public func upcomingReminders(from: Date? = nil, limit: Int = 100) throws -> [ReminderRecord]
public func dirtyReminders() throws -> [ReminderRecord]
public func markReminderSynced(id: String, serverTaskId: String?, pushedEditSeq: Int64) throwsReminderRecord { id, pageId, title, dueAt, done, serverTaskId, dirty, deleted, editSeq, createdAt, updatedAt }.
Create/update set dirty and bump editSeq (a reminder created with a serverTaskId is stored clean).
updateReminder: nil = unchanged, dueAt: .some(nil) clears the date. deleteReminder: a reminder without
serverTaskId is removed, otherwise it becomes deleted + dirty. upcomingReminders: not done, not deleted,
with a due date ≥ from (nil = all, overdue included), soonest first. markReminderSynced records the task
id and clears dirty only if editSeq == pushedEditSeq; a pushed deletion removes the row.
10. Meta
public func meta(_ key: String) throws -> String?
public func setMeta(_ key: String, _ value: String?) throws // nil removes
public func allMeta() throws -> [String: String]
public static let syncCursorKey = "sync.cursor"11. Change notification
public func changes() -> AsyncStream<StoreChange>
public func noteExternalChange()
public enum StoreChange { case pages(Set<String>), tags, attachments(Set<String>), queue, conflicts, reminders, meta(String), reset }Any number of subscribers; each receives every event (unbounded buffer) after the transaction commits. One
transaction emits at most one event per kind, in this order: reset, pages, tags, attachments, queue, conflicts, reminders, meta. A failed transaction emits nothing. Leasing ops emits nothing. Only the changes
made through this NotesStore instance are observed: when another process writes the file (share
extension), signal it yourself (Darwin notification) and call noteExternalChange(), which emits .reset
(reload everything).
12. Schema v2 (SPNotesCore 2.0)
Version 2 adds seven tables and changes none of the v1 tables: entities, entity_ops, ops_parked, canvases, events,
kv_cache, sync_cursors. The migration, its backup and the down script are described in MIGRATION-V2.md.
The HTTP client and the engine phases that fill these tables come with the next wave (backend contract API-NEXT.md); the store
side is complete and tested.
12.1 Opening safely
public static func open(url: URL, readOnly: Bool = false, backupRetention: TimeInterval = 600) -> StoreOpenResult
public enum StoreOpenResult { case opened(NotesStore, StoreOpenReport), failed(StoreOpenError) } // .store, .error, get()
public nonisolated let openReport: StoreOpenReport // foundVersion, migratedFrom, backupURL, removedBackups, didMigrate
public static func openError(for: Error, url: URL) -> StoreOpenError // for callers of init(url:)StoreOpenError: newerSchema(found:supported:), outdatedReadOnly(found:required:), corrupt, locked, storage,
backupFailed, migrationFailed(from:to:reason:backupURL:), other; each has a French userMessage, isTransient and
backupURL. An app must not replace a store that failed to open by NotesStore.inMemory(): the user would see an empty
library and everything typed would be lost at quit. Show userMessage in a blocking screen and offer to retry / quit.
switch NotesStore.open(url: fileURL) {
case .opened(let store, let report): start(store); if report.didMigrate { log(report) }
case .failed(let error): showBlockingError(error.userMessage, canRetry: error.isTransient)
}init(url:) keeps its 1.x signature and behaviour, plus the pre-migration backup; it throws StoreError.backup when the copy
cannot be written (the migration is then not attempted).
12.2 Entities
One generic table for the kinds of the entity change feed (SPEC §3.1): EntityKind.task, .database, .databaseProperty,
.databaseView, .databaseRow, .edge, .reference, .canvas, .concept (EntityKind.all, feedParameter()); a kind this
build does not list is stored like the others. A row is EntityRecord { kind, id, rev, json, deleted, updatedAt, index, dirty, remoteJSON }; json is the server row, opaque to the store (record.decode(T.self)).
public func entity(kind:id:) throws -> EntityRecord?
public func entities(kind:scope:ref:includeDeleted:limit:offset:) throws -> [EntityRecord]
public func entityCount(kind:scope:) throws -> Int; public func entityCounts() throws -> [EntityKind: Int]
public func tasks(pageId: String? = nil), databases(), databaseProperties(databaseId:), databaseViews(databaseId:),
databaseRows(databaseId:limit:offset:), edges(from:), edges(to:), edges(touching:), references(projectId:), concepts()
public func applyRemoteEntities(_ rows: [RemoteEntity], tombstones: [EntityTombstone] = [], cursors: [EntityKind: Int64] = [:]) throws -> EntityApplySummary
public func entityCursor(kind:), entityCursors(), setEntityCursor(kind:_:), resetEntitySync(kinds:), removeSyncedEntities(kind:notIn:)
public func saveLocalEntity(kind:id:json:op:payload:baseVersion:index:) throws -> EntityOp
public func markEntitySynced(kind:id:json:rev:) throws -> Bool; public func dirtyEntities(kind:) throws -> [EntityRecord]- Lookup columns.
EntityIndex { scope, ref, sort }is extracted from the JSON when a row is written so that typed queries use an index:scope= the owner (database of a property / view / row, page of a task, source of an edge),ref= a second id (target of an edge),sort= the order inside the scope (position, due date, name).EntityIndex.defaultKeyslists the JSON keys read per kind; it is provisional (written from SPEC §3 beforeAPI-NEXT.md; camelCase and snake_case are both accepted) — a caller that knows the row shape passesRemoteEntity.indexexplicitly. - Applying the feed is one transaction with its cursors. A row whose stored
revis not lower is skipped (a window applied twice changes nothing). A row with local changes pending keeps its JSON: the server copy goes toremoteJSONand the row is listed inkeptLocal. A tombstone removes a clean row; on a dirty row it only setsdeleted. - Local edits.
saveLocalEntitywrites the row (dirty) and its outbox entry in the same transaction.markEntitySyncedclearsdirtyonce no outbox entry remains for the entity (a locally deleted row is then removed). - Per-kind cursors live in
sync_cursors; the page feed keepsmeta["sync.cursor"].
12.3 Entity outbox
public func enqueueEntityOp(kind:entityId:op:payload:baseVersion:) throws -> EntityOp
public func nextEntityOps(limit: Int = 50, now: Date = Date()) throws -> [EntityOp]
public func completeEntityOp(id:), failEntityOp(id:error:now:), markEntityOpUnsupported(id:reason:), rejectEntityOp(id:error:)
public func retryEntityOps(id: Int64? = nil, where: ((EntityKind, String) -> Bool)? = nil) throws -> Int
public func discardEntityOp(id:) throws -> EntityOp?
public func entityOps(state:), entityOps(kind:entityId:), entityOpCount(state:)EntityOp { id, kind, entityId, op, payload, baseVersion, idempotencyKey, createdAt, attempts, nextAttemptAt, lastError, state }
with op a string (EntityOpVerb.create / update / delete, or any verb) and state pending | unsupported | rejected.
- Processed in order. The order of one entity is never broken: an operation is held back while an older one of the same
(
kind,entityId) is in backoff, unsupported or rejected; other entities are not blocked. No lease: the caller settles each operation before asking again. - Nothing unsent is ever dropped. An operation this build has no handler for is marked
unsupported; one the server refuses for good is markedrejected. Both stay in the table with payload and idempotency key, are listed byentityOps(state:), and leave only throughretryEntityOps(back topending, e.g. after an update) ordiscardEntityOp(the user's explicit decision; the removed entry is returned). A state string written by a newer build reads asunsupported. failEntityOpuses the same backoff as the 1.x queue (5 s doubling to 900 s).
12.4 Parked ops of the 1.x queue
Until 2.0 the engine completed — that is, silently deleted — a queued op whose kind it did not know. Now:
public func parkOp(id: Int64, reason: String, now: Date = Date()) throws
public func parkedOps() throws -> [ParkedOp]; public func parkedOpCount() throws -> Int
public func unparkOps(kinds: Set<String>? = nil) throws -> IntA parked op stays in ops (payload and key intact), is never handed out by nextOps, and does not hold back later ops of
the same target. SyncEngine parks unknown kinds, reports them in SyncStatus.unsupported (they no longer count in pending)
and calls unparkOps(kinds: SyncEngine.supportedOpKinds) at the start of each cycle, so an updated build runs them.
12.5 Canvases
public func canvas(pageId:) throws -> CanvasRecord?
public func saveCanvas(pageId:json:) throws -> Bool // local edit: dirty, editSeq + 1, base captured once
public func canvasesNeedingPush(limit:includeConflicts:) throws -> [CanvasRecord]
public func markCanvasPushed(pageId:version:pushedEditSeq:pushed:), markCanvasPushFailed(pageId:error:)
public func applyRemoteCanvas(pageId:json:version:rev:) throws -> CanvasApplyResult // .applied | .unchanged | .diverged(base:local:remote:remoteVersion:)
public func resolveCanvas(pageId:merged:remote:remoteVersion:), recordCanvasConflict(pageId:remote:remoteVersion:),
discardCanvasConflict(pageId:), canvasConflicts(), deleteCanvas(pageId:)Same optimistic model as pages. The JSON (spn-canvas-1) is opaque to the store: on .diverged nothing is written and the
caller merges with CanvasDocument.merge (SPNotesDocument), then stores a clean merge with resolveCanvas or keeps the server
copy aside with recordCanvasConflict (the local canvas is untouched and leaves the push list until a decision). Purging a page
removes its canvas.
12.6 Events and read-model caches
public func cacheEvents(_ events: [EventRecord], fetchedAt: Date = Date()) throws
public func events(_ query: EventQuery = EventQuery()) throws -> [EventRecord] // pageId, kinds, kindPrefix, from, to, actor, limit, offset
public func eventCount(), latestEventDate(), clearEvents(before:)
public func setCached(_ key: String, json: Data, fetchedAt: Date = Date(), etag: String? = nil) throws // or value: Encodable
public func cached(_ key: String) throws -> CachedValue? // json, fetchedAt, etag, age(), isFresh(maxAge:), decode()
public func cachedKeys(prefix:), removeCached(key:prefix:)Offline copies of what the server computes; nothing is ever generated locally. EventRecord mirrors knowledge_events (SPEC
§3.2). CacheKey names the read models: health, brief, briefSummary, insights, models, meta, graph(view:scope:),
zoom(pageId:level:), query(_:), timeMachine(scope:at:). Every cached value carries its fetch time: show it ("mis à jour il
y a …") whenever the device is offline.
12.7 Changes
StoreChange gains entities(kind: String, ids: Set<String>), entityQueue, canvases(Set<String>), events, cache(String),
emitted after the 1.x events in that order. A switch over StoreChange without default must add them.
13. Known limits
trash/restorecancellation ignores pages moved into or out of the subtree between the two calls.- A page purged locally while its creation request is in flight comes back from the feed unless the engine
purges it on the server when
markPushedthrowsnotFound. - Properties equality ignores key order but is otherwise structural; content equality is byte equality.
removeSyncedPages(notIn:)scans every clean page: use it only after a full re-download.- Entities: one outbox entry per local change, no coalescing;
saveLocalEntitystores the whole JSON the caller gives (no field-level merge withremoteJSON— the engine decides when the outbox is empty). - A read-only connection cannot open a WAL database that was closed cleanly by every writer (no
-shmfile to map); this is SQLite's rule and already applied to 1.x widgets.StoreBackup.peekVersionfalls back to the file header in that case. - The pre-migration backup needs free space for one more copy of the database.