SPB Git

Repository Public

STORE_API.md 42.1 KB

# 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

swift
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 throws and 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_timeout 8 s. Write transactions are BEGIN 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.schema if the file is older than the build; an SQLite error if it does not exist), refuses every mutation with StoreError.readOnly (this includes nextOps, which leases), and sees every committed transaction of the writers. The directory must be writable by the reader (SQLite needs the -shm file).
  • 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 throw StoreError.closed; change streams finish.
  • wipeAll() deletes every row of every table, meta included. Attachment files belong to the caller.
swift
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).

swift
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. id nil → generated UUID. section nil → the parent's, or "notes". position nil → after the last sibling. The row is needsCreate, dirtyContent, tagsDirty if it has tags, editSeq = 1, serverVersion = 0, syncState = pending. Throws invalid (id exists, properties not a JSON object) or notFound (parent).
  • updateContent: title/content nil = unchanged. Returns false and writes nothing when neither the title nor the content bytes differ. Otherwise stores them with plainText, wordCount, preview, sets dirtyContent, stamps updatedAt.
  • setProperties: replaces the object (must be a JSON object). No-op when equal ignoring key order. The favorite/isFolder mirrors come from the arguments when given, otherwise from the top level of the JSON. Sets dirtyContent (properties are version-guarded) and stamps updatedAt. setFavorite/setFolder set "favorite": true / "folder": true or remove the key, and re-serialise the object with sorted keys.
  • setPinned / setArchived / setIcon / setCover / setInbox: add the field to dirtyMeta. updatedAt is not touched.
  • move: parentId nil = root. section nil = the new parent's section (the current one at the root). position nil = after the last sibling if the parent changes, unchanged otherwise. Adds the changed fields among parentId, section, position to dirtyMeta. A section change is propagated to all descendants (each gets section in dirtyMeta). Throws cycle if parentId is the page or one of its descendants, notFound if 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. Sets tagsDirty; emits .tags.
  • trash: stamps deletedAt on the page and on its descendants reachable through pages that are not already in the trash (server behaviour), and queues ONE op trash with targetId = id. Returns the ids trashed (empty, and no op, if the page already was in the trash). Trash is not a dirty state: no editSeq bump, no dirty flag.
  • restore: clears deletedAt on the page and ALL its descendants; returns the ids restored (empty and no op if none was trashed). Queues an op restore, except when the newest queued trash/restore/purge op of that page is a trash that was never returned by nextOps, 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.orphanedFiles lists the relative paths of their files); reminders of those pages are deleted (or flagged deleted + dirty when 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 op purge is 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 are needsCreate disappear 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 lastOpenedAt only (not dirty, editSeq unchanged).

# 2.3 Queries

swift
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, conflicts
SmartList 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.

swift
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), tokenizer unicode61 remove_diacritics 2: case and diacritics are ignored (éte finds É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 in SearchHit.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 updatedAt first, with snippet = 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

swift
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) throws
  • pagesNeedingPush: every isDirty page with its full row and base copy. Pages to create come first, parents before children (depth in the chain of needsCreate ancestors), then the others by oldest local change. Pages in conflict are left out unless includeConflicts. error pages are included.
  • What to send: needsCreate → create the page with the whole row; dirtyContent → PATCH title/content/ properties with baseVersion = page.serverVersion; dirtyMeta → those fields; tagsDirty → the tags. Remember page.editSeq (and the title/content/properties sent) for the acknowledgement.
  • markPushed acknowledges a successful push of the row as it was at pushedEditSeq:
    • editSeq == pushedEditSeq: needsCreate, dirtyContent, dirtyMeta, tagsDirty cleared, base dropped, serverVersion and updatedAt set, syncState = synced. serverContent (the server's normalised content), when given, replaces the local content.
    • otherwise (edited during the push): nothing local is overwritten; needsCreate is cleared and serverVersion advances. With pushed (pass it): if the current title/content/properties still equal what was sent (only meta or tags changed meanwhile), dirtyContent is cleared and the base dropped; else the page stays dirtyContent and the base becomes {pushed.title, serverContent ?? pushed.content, pushed.properties, version: serverVersion}. Without pushed, the page stays as dirty as it was and the existing base (an older ancestor) is left untouched. dirtyMeta and tagsDirty are kept (re-pushing them is idempotent).
    • Throws notFound if 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

swift
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 -> PurgeResult

RemotePage 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;
  • dirtyContent and remote.version == serverVersion (or lower) → nothing to do;
  • dirtyContent and remote.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, dirtyContent cleared, base and conflict dropped;
    • otherwise the page is returned in ApplySummary.diverged as DivergedPage(id, remote) and its local content, base, serverVersion and updatedAt are not touched. The engine decides: three-way merge with pageBase(id:), then resolveConflictKeepingLocal(…, merged:), or recordConflict, or resolveConflictUsingCopy.

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, tagsDirty if it has tags, dirtyMeta emptied, base and conflict dropped → resurrectedPageIds. Its deletedAt is 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, parentId added to dirtyMeta);
  • 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

swift
public func resolveConflictUsingCopy(id: String, copy: ContentCopy, version: Int, updatedAt: Date) throws
public func resolveConflictKeepingLocal(id: String, server: ServerCopy, merged: ContentCopy? = nil) throws
  • resolveConflictUsingCopy: replaces the local title/content/properties (and derived values) with copy, stored as synced at version: dirtyContent and needsCreate cleared, 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, needsCreate cleared, dirtyContent = true, conflict record removed, editSeq + 1: the next push is made against the server's current version. With merged, 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

swift
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) throws

One 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.

swift
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) -> TimeInterval

PendingOp { 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.

  • nextOps returns the due ops, oldest first, and leases them for lease seconds: they are not returned again until completeOp, failOp, releaseOp, releaseAllOpLeases or 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.
  • completeOp removes 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. Call releaseAllOpLeases() when the engine starts.
  • The engine must push page creations before running an op whose target is needsCreate.

# 7. Attachments

swift
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() throws

AttachmentRecord: 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; row pendingUpload, uploaded = false.
  • pendingUploads: not uploaded, not deleted, state pendingUpload or failed, oldest first.
  • markAttachmentUploaded: state = local, uploaded = true.
  • markAttachmentFailed: never uploaded → state = failed, uploadAttempts + 1 (still in pendingUploads; the engine applies its own delay); a failed download → back to remote (or local if a file is present).
  • markAttachmentDeleted: never uploaded → the row is removed and no op is queued; otherwise deletedAt is set and an op deleteAttachment (targetId = attachment id) is queued. Returns the relative path of the local file for the caller to delete.
  • evictionCandidates: state = local, uploaded, not keepOffline; least recently used first (lastAccessedAt, stamped by markAttachmentDownloaded and touchAttachment). After deleting the file call markAttachmentEvicted (state = remote, no path).
  • attachmentsWantedOffline: what to download in the background — on the server, no local file, state remote (a failed download goes back to remote with lastError, so it is listed again; failed without a local file is accepted too), not deleted, page not in the trash, and either keepOffline (any size) or an image (mime LIKE 'image/%') or drawing source (filename LIKE '%.pkdrawing') with size <= maxSize. Newest (createdAt) first. Rows that are downloading are not listed.
  • resetTransientAttachmentStates() at engine start: uploading → pendingUpload, downloading → remote/local.
  • Methods addressing an unknown id throw notFound("attachment <id>").

# 8. Local versions

swift
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 = 100

snapshot 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

swift
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) throws

ReminderRecord { 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

swift
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

swift
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

swift
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.

swift
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)).

swift
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.defaultKeys lists the JSON keys read per kind; it is provisional (written from SPEC §3 before API-NEXT.md; camelCase and snake_case are both accepted) — a caller that knows the row shape passes RemoteEntity.index explicitly.
  • Applying the feed is one transaction with its cursors. A row whose stored rev is not lower is skipped (a window applied twice changes nothing). A row with local changes pending keeps its JSON: the server copy goes to remoteJSON and the row is listed in keptLocal. A tombstone removes a clean row; on a dirty row it only sets deleted.
  • Local edits. saveLocalEntity writes the row (dirty) and its outbox entry in the same transaction. markEntitySynced clears dirty once no outbox entry remains for the entity (a locally deleted row is then removed).
  • Per-kind cursors live in sync_cursors; the page feed keeps meta["sync.cursor"].

# 12.3 Entity outbox

swift
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 marked rejected. Both stay in the table with payload and idempotency key, are listed by entityOps(state:), and leave only through retryEntityOps (back to pending, e.g. after an update) or discardEntityOp (the user's explicit decision; the removed entry is returned). A state string written by a newer build reads as unsupported.
  • failEntityOp uses 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:

swift
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 -> Int

A 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

swift
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

swift
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/restore cancellation 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 markPushed throws notFound.
  • 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; saveLocalEntity stores the whole JSON the caller gives (no field-level merge with remoteJSON — 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 -shm file to map); this is SQLite's rule and already applied to 1.x widgets. StoreBackup.peekVersion falls back to the file header in that case.
  • The pre-migration backup needs free space for one more copy of the database.
Files main
Menu

Theme