Repository Public
1<!--2SP Notes Core3File: docs/STORE_API.md4Description: Public API and exact semantics of the SPNotesStore module (local database of the native apps).5Author: Simon-Pierre Boucher6Contact: contact@spboucher.ai7-->89# SPNotesStore — public API and semantics1011`SPNotesStore` is the durable local database of the native SP Notes apps. It depends on Foundation and the12system SQLite only. It does **not** import `SPNotesDocument`: note content is opaque JSON `Data`, and the13caller supplies the derived plain text, word count and preview.1415Rule of the module: **no note is ever lost.** Local edits are never overwritten by the feed; every mutation is16one atomic SQLite transaction; nothing waits for the network.1718## 1. Engine1920```swift21public actor NotesStore {22 public init(url: URL, readOnly: Bool = false) throws23 public static func inMemory() throws -> NotesStore24 public nonisolated let isReadOnly: Bool25 public static var schemaVersion: Int // 226 public static func open(url:readOnly:backupRetention:) -> StoreOpenResult // 2.0: typed outcome, see §12.127 public func close()28 public func integrityCheck() throws -> [String] // empty = healthy29 public func checkpoint() throws // wal_checkpoint(TRUNCATE)30 public func rebuildSearchIndex() throws31 public func wipeAll() throws // "erase this device" only32}33```3435- Every method is `throws` and actor-isolated (`try await store.…`). Methods are synchronous inside the actor:36 two calls never interleave.37- Connection: `SQLITE_OPEN_FULLMUTEX`, `journal_mode=WAL`, `synchronous=FULL`, `foreign_keys=ON`,38 `busy_timeout` 8 s. Write transactions are `BEGIN IMMEDIATE`; an error thrown inside one rolls it back39 entirely (index, tags, queue and cursor included) and publishes no change event.40- The same file may be opened by several processes: the app (read/write), a share extension (read/write, its41 own `NotesStore`), a widget (`readOnly: true`). A read-only store never creates nor migrates the file42 (`StoreError.schema` if the file is older than the build; an SQLite error if it does not exist), refuses every43 mutation with `StoreError.readOnly` (this includes `nextOps`, which leases), and sees every committed44 transaction of the writers. The directory must be writable by the reader (SQLite needs the `-shm` file).45- Schema: `PRAGMA user_version`, one transaction per migration step (step + version bump commit together). A46 file newer than the build is refused (`StoreError.schema`).47- Timestamps are stored as integer milliseconds since the Unix epoch and exposed as `Date` (sub-millisecond48 precision is rounded on write).49- Ids are lowercase UUID strings. Ids given by the caller are lowercased.50- `close()`: later calls throw `StoreError.closed`; change streams finish.51- `wipeAll()` deletes every row of every table, meta included. Attachment files belong to the caller.5253```swift54public enum StoreError: Error, Sendable, Equatable {55 case sqlite(code: Int32, message: String, sql: String?)56 case notFound(String) // the row addressed by the call does not exist57 case invalid(String) // rejected argument (duplicate id, properties not a JSON object, …)58 case cycle // move into the page's own subtree59 case readOnly60 case closed61 case schema(String)62}63```6465## 2. Pages6667### 2.1 Model6869`PageRecord` (full row), all fields `public var`:7071| Field | Meaning |72|---|---|73| `id, parentId, databaseId, type, section, title, icon, cover` | server fields |74| `content: Data` | opaque document JSON |75| `properties: Data` | JSON object |76| `position: Double, pinned, archived` | server fields |77| `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.) |78| `wordCount, createdAt, updatedAt, lastOpenedAt, deletedAt, inboxAt, captureKind, rev` | server fields; `updatedAt` is stamped locally by content edits until the server answers |79| `tags: [String]` | sorted names |80| `needsCreate` | the row must be created on the server |81| `dirtyContent` | title, content or properties changed locally since the base |82| `dirtyMeta: Set<MetaField>` | `parentId, section, position, pinned, archived, icon, cover, inboxAt` changed locally |83| `tagsDirty` | tags changed locally |84| `editSeq: Int64` | +1 on every local change that has to be pushed |85| `syncState` | `conflict` if a conflict record exists; else `error` if dirty with a `syncError`; else `pending` if dirty; else `synced` |86| `syncError: String?` | set by `markPushFailed`, cleared by the next local edit or successful push |87| `plainText, preview` | supplied by the caller |88| `favorite, isFolder` | mirrors of `properties.favorite == true` / `properties.folder == true` |89| `localUpdatedAt` | last local change |90| `isDirty` (computed) | `needsCreate || dirtyContent || !dirtyMeta.isEmpty || tagsDirty` |9192`PageSummary` (lists; no content, properties nor plain text): `id, title, preview, updatedAt, parentId, section,93pinned, favorite, isFolder, icon, tags, syncState, hasChildren` (at least one child not in the trash), plus94`type, position, archived, wordCount, lastOpenedAt, deletedAt, inboxAt`.9596**Base copy.** `PageBase { title, content, properties, version }` is the last synced copy of the97version-guarded fields. It is captured the first time a page that is on the server and content-clean gets a98content edit (title/content/properties), is kept unchanged by later edits, and is dropped when the content99becomes clean again (`markPushed`, feed echo, `resolveConflictUsingCopy`). A page never pushed has no base.100Meta-only and tag-only edits do not create a base.101102### 2.2 Local mutations103104Each is ONE transaction. Unless said otherwise each bumps `editSeq`, stamps `localUpdatedAt`, clears105`syncError`, recomputes `syncState`, maintains the FTS index and emits `.pages([id])`. All throw106`notFound("page <id>")` on an unknown id. The `Bool` results say whether anything changed (a no-op writes107nothing and bumps nothing).108109```swift110public func createPage(_ draft: NewPage = NewPage()) throws -> PageRecord111public func createPages(_ drafts: [NewPage]) throws -> [String] // one transaction, all or nothing112public func updateContent(id: String, title: String? = nil, content: Data? = nil,113 plainText: String, wordCount: Int, preview: String) throws -> Bool114public func setProperties(id: String, properties: Data, favorite: Bool? = nil, isFolder: Bool? = nil) throws -> Bool115public func setFavorite(id: String, _ favorite: Bool) throws -> Bool116public func setFolder(id: String, _ isFolder: Bool) throws -> Bool117public func setPinned(id: String, _ pinned: Bool) throws -> Bool118public func setArchived(id: String, _ archived: Bool) throws -> Bool119public func setIcon(id: String, _ icon: String?) throws -> Bool120public func setCover(id: String, _ cover: String?) throws -> Bool121public func setInbox(id: String, at date: Date?) throws -> Bool122public func move(id: String, parentId: String?, section: String? = nil, position: Double? = nil) throws -> Bool123public func setTags(id: String, names: [String]) throws -> Bool124public static func normalizeTags(_ names: [String]) -> [String]125public func trash(id: String) throws -> [String]126public func restore(id: String) throws -> [String]127public func purge(id: String) throws -> PurgeResult128public func duplicate(id: String) throws -> PageRecord129public func markOpened(id: String, at date: Date = Date()) throws130```131132- **createPage**: `NewPage(id:parentId:databaseId:type:section:title:icon:cover:content:properties:position:pinned:plainText:wordCount:preview:tags:inboxAt:captureKind:)`,133 every argument optional. `id` nil → generated UUID. `section` nil → the parent's, or `"notes"`. `position`134 nil → after the last sibling. The row is `needsCreate`, `dirtyContent`, `tagsDirty` if it has tags,135 `editSeq = 1`, `serverVersion = 0`, `syncState = pending`. Throws `invalid` (id exists, properties not a136 JSON object) or `notFound` (parent).137- **updateContent**: `title`/`content` nil = unchanged. Returns `false` and writes nothing when neither the138 title nor the content **bytes** differ. Otherwise stores them with `plainText`, `wordCount`, `preview`, sets139 `dirtyContent`, stamps `updatedAt`.140- **setProperties**: replaces the object (must be a JSON object). No-op when equal ignoring key order. The141 `favorite`/`isFolder` mirrors come from the arguments when given, otherwise from the top level of the JSON.142 Sets `dirtyContent` (properties are version-guarded) and stamps `updatedAt`. `setFavorite`/`setFolder` set143 `"favorite": true` / `"folder": true` or remove the key, and re-serialise the object with sorted keys.144- **setPinned / setArchived / setIcon / setCover / setInbox**: add the field to `dirtyMeta`. `updatedAt` is145 not touched.146- **move**: `parentId` nil = root. `section` nil = the new parent's section (the current one at the root).147 `position` nil = after the last sibling if the parent changes, unchanged otherwise. Adds the changed fields148 among `parentId, section, position` to `dirtyMeta`. A section change is propagated to all descendants (each149 gets `section` in `dirtyMeta`). Throws `cycle` if `parentId` is the page or one of its descendants,150 `notFound` if the parent does not exist; a rejected move changes nothing.151- **setTags**: names are normalised like the server — trimmed, leading `#` removed, lowercased, at most 40152 characters, empties dropped, unique (first wins), at most 20. No-op when the set is unchanged. Sets153 `tagsDirty`; emits `.tags`.154- **trash**: stamps `deletedAt` on the page and on its descendants reachable through pages that are not155 already in the trash (server behaviour), and queues ONE op `trash` with `targetId = id`. Returns the ids156 trashed (empty, and no op, if the page already was in the trash). Trash is **not** a dirty state: no157 `editSeq` bump, no dirty flag.158- **restore**: clears `deletedAt` on the page and ALL its descendants; returns the ids restored (empty and no159 op if none was trashed). Queues an op `restore`, **except** when the newest queued trash/restore/purge op of160 that page is a `trash` that was never returned by `nextOps`, has 0 attempts, and was issued while no161 descendant was already in the trash: that op is deleted instead (the pair cancels out).162- **purge**: removes the page and all its descendants locally, with bases, conflicts, local versions, tags,163 index entries and attachment rows (`PurgeResult.orphanedFiles` lists the relative paths of their files);164 reminders of those pages are deleted (or flagged `deleted + dirty` when the server knows them). Queued165 trash/restore/purge ops of those pages are dropped (except one currently leased). For pages the server knows166 (`!needsCreate`), one op `purge` is queued for EVERY page of the subtree (the server's purge removes a single row; it does167 not cascade to the pages inside). Pages that are `needsCreate`168 disappear with all their ops and leave nothing in the queue.169- **duplicate**: new local page (fresh id, `needsCreate`) titled `"<title> (copy)"`, same parent, section,170 type, content, properties, icon, cover, tags and derived text, placed right after the original; not pinned,171 not in the inbox, not trashed. Descendants are not copied.172- **markOpened**: stamps `lastOpenedAt` only (not dirty, `editSeq` unchanged).173174### 2.3 Queries175176```swift177public func page(id: String) throws -> PageRecord?178public func summary(id: String) throws -> PageSummary?179public func pageCount() throws -> Int180public func summaries(list: SmartList, section: String? = nil, limit: Int = 200, offset: Int = 0) throws -> [PageSummary]181public func children(of parentId: String?, section: String? = nil, includeArchived: Bool = false) throws -> [PageSummary]182public func folderTree(section: String? = nil) throws -> [PageSummary]183public func ancestors(of id: String) throws -> [PageSummary]184public func summaries(tag: String, limit: Int = 200, offset: Int = 0) throws -> [PageSummary]185public func tags() throws -> [TagInfo] // name, color, count186public func counts() throws -> ListCounts // all, pinned, favorites, inbox, archived, trash, pending, conflicts187```188189| `SmartList` | Set | Order |190|---|---|---|191| `.all` | not trashed, not archived | `updatedAt` desc |192| `.recent` | same as `.all` | `max(updatedAt, lastOpenedAt)` desc |193| `.pinned` / `.favorites` | flag set, not trashed, not archived | `updatedAt` desc |194| `.inbox` | `inboxAt` set, not trashed | `inboxAt` desc |195| `.archived` | archived, not trashed | `updatedAt` desc |196| `.trash` | `deletedAt` set | `deletedAt` desc |197198Lists contain every page type, folders included. They are served from partial indexes (no scan, no sort).199`children(of: nil, section:)` returns the root pages of a section; children are ordered by `position`, then200title. `folderTree` is a flat list of the folder pages (not trashed, not archived) ordered by section then201position; build the tree from `parentId`. `ancestors` goes from the parent up to the root. `tags()` lists the202tags received from the server plus those used locally; `count` = notes carrying the tag that are neither203trashed nor archived. `ListCounts.pending` = pages with `isDirty`.204205## 3. Search206207```swift208public func search(query: String, filters: SearchFilters = SearchFilters(), limit: Int = 50) throws -> [SearchHit]209210public struct SearchFilters { // all optional, combined with AND211 var section: String?212 var folderId: String? // descendants of this page (the page itself excluded)213 var tags: [String] // ALL of these (normalised)214 var updatedAfter: Date? // inclusive215 var updatedBefore: Date? // inclusive216 var favoritesOnly: Bool217 var pinnedOnly: Bool218 var includeArchived: Bool // default false219 var includeTrash: Bool // default false220}221public struct SearchHit { var page: PageSummary; var snippet: String; var highlightedTitle: String; var score: Double }222```223224- FTS5 table (`title`, `body` = plain text, `tags`), tokenizer `unicode61 remove_diacritics 2`: case and225 diacritics are ignored (`éte` finds `Été`). The index is incremental: only the page touched by a mutation is226 re-indexed (delete by rowid + insert), inside the same transaction.227- The query is split on every character that is not a letter, digit or combining mark. Every term must match228 (any column, any order); the **last** term matches as a prefix. Terms are quoted, so FTS operators, quotes,229 parentheses, `NEAR`, column filters, etc. are plain text: **no input can cause a syntax error**. At most the230 last 32 terms are used.231- Order: bm25 with weights title 10, tags 4, body 1 (`score`, lower is better).232- `snippet`: an excerpt of the body around the match; `highlightedTitle`: the title. Matches are wrapped in233 `SearchHit.highlightStart` (U+E000) / `highlightEnd` (U+E001). `SearchHit.segments(of:)` returns234 `[(text, highlighted)]`; `SearchHit.plain(_:)` strips the markers.235- A query with no term (empty, punctuation only) returns the pages matching the filters, newest `updatedAt`236 first, with `snippet = preview`, `highlightedTitle = title`, `score = 0`.237- Trashed and archived pages stay in the index; they are excluded by default by the filters.238239## 4. Sync primitives240241The cursor is `meta["sync.cursor"]`:242`syncCursor() -> Int64` (0 = never synced), `setSyncCursor(_:)`.243244### 4.1 Push245246```swift247public func pagesNeedingPush(limit: Int = 100, includeConflicts: Bool = false) throws -> [PendingPage] // page + base248public func pendingPushCount() throws -> Int249public func pageBase(id: String) throws -> PageBase?250public func markPushed(id: String, serverVersion: Int, updatedAt: Date, pushedEditSeq: Int64,251 pushed: PushedCopy? = nil, serverContent: Data? = nil) throws252public func markPushFailed(id: String, error: String) throws253```254255- `pagesNeedingPush`: every `isDirty` page with its full row and base copy. Pages to create come first,256 **parents before children** (depth in the chain of `needsCreate` ancestors), then the others by oldest local257 change. Pages in `conflict` are left out unless `includeConflicts`. `error` pages are included.258- What to send: `needsCreate` → create the page with the whole row; `dirtyContent` → `PATCH` title/content/259 properties with `baseVersion = page.serverVersion`; `dirtyMeta` → those fields; `tagsDirty` → the tags.260 Remember `page.editSeq` (and the title/content/properties sent) for the acknowledgement.261- `markPushed` acknowledges a successful push of the row as it was at `pushedEditSeq`:262 - `editSeq == pushedEditSeq`: `needsCreate`, `dirtyContent`, `dirtyMeta`, `tagsDirty` cleared, base dropped,263 `serverVersion` and `updatedAt` set, `syncState = synced`. `serverContent` (the server's normalised264 content), when given, replaces the local content.265 - otherwise (edited during the push): nothing local is overwritten; `needsCreate` is cleared and266 `serverVersion` advances. With `pushed` (**pass it**): if the current title/content/properties still equal267 what was sent (only meta or tags changed meanwhile), `dirtyContent` is cleared and the base dropped; else268 the page stays `dirtyContent` and the base becomes `{pushed.title, serverContent ?? pushed.content,269 pushed.properties, version: serverVersion}`. Without `pushed`, the page stays as dirty as it was and the270 existing base (an older ancestor) is left untouched. `dirtyMeta` and `tagsDirty` are kept (re-pushing them271 is idempotent).272 - Throws `notFound` if the page was purged locally during the push: the engine should then delete the page273 it just created on the server.274- `markPushFailed`: `syncError = error`, `syncState = error`; the page stays dirty and listed.275- On a 409: call `recordConflict` (§5) or one of the resolution helpers (§4.3).276277### 4.2 Pull278279```swift280public func applyRemote(pages: [RemotePage] = [], attachments: [RemoteAttachment] = [], tombstones: [Tombstone] = [],281 tags: [RemoteTag]? = nil, cursor: Int64? = nil) throws -> ApplySummary282public func resetSyncState() throws283public func removeSyncedPages(notIn ids: Set<String>) throws -> PurgeResult284```285286`RemotePage` carries every server field (`version`, `rev`, `tags`, …) plus `plainText` and `preview`, which287the caller derives from `content`. `applyRemote` is ONE transaction (all or nothing, cursor included).288289For each remote page:290291| Local row | Effect |292|---|---|293| none | inserted as `synced` (`serverVersion = remote.version`), tags and index included → `insertedPageIds` |294| `rev` greater than `remote.rev` | ignored (stale feed page) |295| 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.) |296| 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. |297298Version-guarded fields of a dirty page:299300- no pending content edit (`dirtyContent == false`) → the remote title/content/properties/derived/version are301 adopted;302- `dirtyContent` and `remote.version == serverVersion` (or lower) → nothing to do;303- `dirtyContent` and `remote.version > serverVersion`:304 - remote title, content bytes and properties (key order ignored) equal the local ones — this device's own305 push whose acknowledgement was lost — → version adopted, `dirtyContent` cleared, base and conflict dropped;306 - otherwise the page is returned in `ApplySummary.diverged` as `DivergedPage(id, remote)` and **its local307 content, base, `serverVersion` and `updatedAt` are not touched**. The engine decides: three-way merge with308 `pageBase(id:)`, then `resolveConflictKeepingLocal(…, merged:)`, or `recordConflict`, or309 `resolveConflictUsingCopy`.310311`deletedAt` follows the server, except for pages covered by a queued local `trash`/`restore` op (the page or312one of its ancestors is the op's target): their local value is kept until the op is completed.313314Tombstones:315316- page, local row clean → removed with base, conflict, local versions, tags, index entry, attachment rows317 (their files in `orphanedFiles`) and its queued trash/restore/purge ops → `deletedPageIds`;318- page, local row dirty → **kept**: `needsCreate = true`, `serverVersion = 0`, `dirtyContent = true`,319 `tagsDirty` if it has tags, `dirtyMeta` emptied, base and conflict dropped → `resurrectedPageIds`. Its320 `deletedAt` is left as it is locally;321- after page tombstones, every dirty page whose parent no longer exists is moved to the root of its section322 (`parentId = nil`, `parentId` added to `dirtyMeta`);323- attachment → row removed (file path in `orphanedFiles`) → `deletedAttachmentIds`;324- unknown ids are ignored.325326Attachments are upserted: unknown → `state = remote`; known → server fields updated, `state`, `localPath`,327`keepOffline`, `lastAccessedAt`, attempts kept. A row still waiting for upload that the server already lists328becomes `uploaded` / `local`. A remote `deletedAt` is applied; a local deletion waiting in the queue is not329undone.330331`tags`: nil = not part of this batch; otherwise the tag list and colours are replaced (names still used by332local pages stay listed). `cursor`: nil = unchanged.333334`ApplySummary`: `insertedPageIds, updatedPageIds, deletedPageIds, resurrectedPageIds, diverged,335changedAttachmentIds, deletedAttachmentIds, orphanedFiles, tagsChanged`. Applying the same batch twice changes336nothing the second time.337338`resetSyncState()` (server `reset`): cursor = 0 and the stored `rev` of every page and attachment = 0 (change339sequences may restart). Nothing else changes: pages, dirty flags, bases, queue, conflicts stay. After the full340re-download, `removeSyncedPages(notIn:)` removes the pages that are clean and on the server341(`serverVersion > 0`) but absent from the complete id set; dirty and never-pushed pages are kept.342343### 4.3 Conflict resolution344345```swift346public func resolveConflictUsingCopy(id: String, copy: ContentCopy, version: Int, updatedAt: Date) throws347public func resolveConflictKeepingLocal(id: String, server: ServerCopy, merged: ContentCopy? = nil) throws348```349350- `resolveConflictUsingCopy`: replaces the local title/content/properties (and derived values) with `copy`,351 stored **as synced at `version`**: `dirtyContent` and `needsCreate` cleared, base dropped, conflict record352 removed, `editSeq + 1`. If the title or content differ, the replaced local state is first saved as a local353 version (reason `"conflict-local"`). Pending meta and tag changes stay dirty.354- `resolveConflictKeepingLocal`: base copy := the server copy, `serverVersion := server.version`, `needsCreate`355 cleared, `dirtyContent = true`, conflict record removed, `editSeq + 1`: the next push is made against the356 server's current version. With `merged`, the local fields are first replaced by the merge result (the357 previous local state is saved as a local version, reason `"conflict-local"`).358359## 5. Conflicts360361```swift362public func recordConflict(pageId: String, server: ServerCopy, detectedAt: Date = Date()) throws363public func conflict(pageId: String) throws -> ConflictRecord?364public func conflicts() throws -> [ConflictRecord] // oldest first365public func clearConflict(pageId: String) throws366```367368One row per page (`ServerCopy { version, title, content, properties, updatedAt }` + `detectedAt`); recording369again replaces it. `recordConflict` sets `syncState = conflict` and does not touch the local content; the page370keeps accepting local edits and stays out of `pagesNeedingPush()`. `clearConflict` only drops the record.371372## 6. Ops queue373374For actions that are not dirty state: `OpKind.trash`, `.restore`, `.purge`, `.deleteAttachment`, `.createTask`,375`.updateTask`, `.deleteTask`, `.triage`, or any string.376377```swift378public func enqueueOp(kind: String, targetId: String? = nil, payload: Data? = nil) throws -> PendingOp379public func nextOps(limit: Int = 20, now: Date = Date(), lease: TimeInterval = 120) throws -> [PendingOp]380public func completeOp(id: Int64) throws381public func failOp(id: Int64, error: String, now: Date = Date()) throws -> PendingOp?382public func releaseOp(id: Int64) throws383public func releaseAllOpLeases() throws384public func queuedOps() throws -> [PendingOp]385public func opCount() throws -> Int386public static func backoffDelay(attempts: Int) -> TimeInterval387```388389`PendingOp { id (queue sequence), kind, targetId, payload, idempotencyKey, createdAt, attempts, nextAttemptAt,390lastError }`. The idempotency key is generated once per op (32 characters of `[0-9a-f]`) and never changes391across retries.392393- `nextOps` returns the due ops, oldest first, and **leases** them for `lease` seconds: they are not returned394 again until `completeOp`, `failOp`, `releaseOp`, `releaseAllOpLeases` or the end of the lease. An op is held395 back while an older op **with the same target** is in backoff or leased, so per-target order is never396 broken; ops of other targets are not blocked.397- `completeOp` removes the op (success, or definitive rejection). Unknown ids are ignored.398- `failOp`: `attempts + 1`, lease released, `nextAttemptAt = now + backoffDelay(attempts)` = 5 s, 10 s, 20 s …399 doubling, capped at 900 s (15 min).400- `releaseOp`: gives the op back without counting an attempt. Call `releaseAllOpLeases()` when the engine401 starts.402- The engine must push page creations before running an op whose target is `needsCreate`.403404## 7. Attachments405406```swift407public func addLocalAttachment(id: String? = nil, pageId: String, filename: String, mime: String, size: Int64,408 sha256: String?, localPath: String, pageCount: Int? = nil) throws -> AttachmentRecord409public func attachment(id: String) throws -> AttachmentRecord?410public func attachments(pageId: String, includeDeleted: Bool = false) throws -> [AttachmentRecord]411public func pendingUploads(limit: Int = 50) throws -> [AttachmentRecord]412public func markAttachmentUploading(id: String) throws413public func markAttachmentUploaded(id: String, size: Int64? = nil, sha256: String? = nil, pageCount: Int? = nil) throws414public func markAttachmentDownloading(id: String) throws415public func markAttachmentDownloaded(id: String, localPath: String, at date: Date = Date()) throws416public func markAttachmentFailed(id: String, error: String) throws417public func markAttachmentDeleted(id: String) throws -> String?418public func setAttachmentKeepOffline(id: String, _ keep: Bool) throws419public func touchAttachment(id: String, at date: Date = Date()) throws420public func evictionCandidates(limit: Int = 50) throws -> [AttachmentRecord]421public func attachmentsWantedOffline(maxSize: Int64, limit: Int = 50) throws -> [AttachmentRecord]422public func markAttachmentEvicted(id: String) throws423public func resetTransientAttachmentStates() throws424```425426`AttachmentRecord`: server fields (`id, pageId, filename, mime, size, sha256, pageCount, createdAt, deletedAt,427rev`) + `state` (`remote | downloading | local | pendingUpload | uploading | failed`), `localPath` (relative to428the attachments directory managed by the caller), `keepOffline`, `uploaded` (the server has the file),429`uploadAttempts`, `lastError`, `lastAccessedAt`.430431- `addLocalAttachment`: the file is already in place; row `pendingUpload`, `uploaded = false`.432- `pendingUploads`: not uploaded, not deleted, state `pendingUpload` or `failed`, oldest first.433- `markAttachmentUploaded`: `state = local`, `uploaded = true`.434- `markAttachmentFailed`: never uploaded → `state = failed`, `uploadAttempts + 1` (still in `pendingUploads`;435 the engine applies its own delay); a failed download → back to `remote` (or `local` if a file is present).436- `markAttachmentDeleted`: never uploaded → the row is removed and **no op** is queued; otherwise `deletedAt`437 is set and an op `deleteAttachment` (`targetId` = attachment id) is queued. Returns the relative path of the438 local file for the caller to delete.439- `evictionCandidates`: `state = local`, uploaded, not `keepOffline`; least recently used first440 (`lastAccessedAt`, stamped by `markAttachmentDownloaded` and `touchAttachment`). After deleting the file call441 `markAttachmentEvicted` (`state = remote`, no path).442- `attachmentsWantedOffline`: what to download in the background — on the server, no local file, state `remote`443 (a failed download goes back to `remote` with `lastError`, so it is listed again; `failed` without a local444 file is accepted too), not deleted, page not in the trash, and either `keepOffline` (any size) or an image445 (`mime LIKE 'image/%'`) or drawing source (`filename LIKE '%.pkdrawing'`) with `size <= maxSize`. Newest446 (`createdAt`) first. Rows that are `downloading` are not listed.447- `resetTransientAttachmentStates()` at engine start: `uploading → pendingUpload`, `downloading → remote/local`.448- Methods addressing an unknown id throw `notFound("attachment <id>")`.449450## 8. Local versions451452```swift453public func snapshot(pageId: String, reason: String) throws -> LocalVersionInfo?454public func localVersions(pageId: String) throws -> [LocalVersionInfo] // newest first, no content455public func localVersion(id: String) throws -> LocalVersion? // with content, plainText, preview456public func restoreVersion(id versionId: String) throws -> PageRecord457public static let maxLocalVersionsPerPage = 100458```459460`snapshot` saves the current title and content (returns nil and writes nothing when both are identical to the461latest snapshot of the page) and prunes to the newest 100 of that page. `restoreVersion` first snapshots the462current state (reason `"before-restore"`), then applies the snapshot as an ordinary local edit (`dirtyContent`,463`editSeq + 1`). The store itself only snapshots in the conflict helpers; periodic snapshots are the caller's.464465## 9. Reminders466467```swift468public func createReminder(id: String? = nil, pageId: String? = nil, title: String, dueAt: Date? = nil,469 done: Bool = false, serverTaskId: String? = nil) throws -> ReminderRecord470public func updateReminder(id: String, title: String? = nil, dueAt: Date?? = nil, done: Bool? = nil) throws -> ReminderRecord471public func deleteReminder(id: String) throws472public func reminder(id: String) throws -> ReminderRecord?473public func reminders(pageId: String) throws -> [ReminderRecord]474public func upcomingReminders(from: Date? = nil, limit: Int = 100) throws -> [ReminderRecord]475public func dirtyReminders() throws -> [ReminderRecord]476public func markReminderSynced(id: String, serverTaskId: String?, pushedEditSeq: Int64) throws477```478479`ReminderRecord { id, pageId, title, dueAt, done, serverTaskId, dirty, deleted, editSeq, createdAt, updatedAt }`.480Create/update set `dirty` and bump `editSeq` (a reminder created with a `serverTaskId` is stored clean).481`updateReminder`: nil = unchanged, `dueAt: .some(nil)` clears the date. `deleteReminder`: a reminder without482`serverTaskId` is removed, otherwise it becomes `deleted + dirty`. `upcomingReminders`: not done, not deleted,483with a due date ≥ `from` (nil = all, overdue included), soonest first. `markReminderSynced` records the task484id and clears `dirty` only if `editSeq == pushedEditSeq`; a pushed deletion removes the row.485486## 10. Meta487488```swift489public func meta(_ key: String) throws -> String?490public func setMeta(_ key: String, _ value: String?) throws // nil removes491public func allMeta() throws -> [String: String]492public static let syncCursorKey = "sync.cursor"493```494495## 11. Change notification496497```swift498public func changes() -> AsyncStream<StoreChange>499public func noteExternalChange()500501public enum StoreChange { case pages(Set<String>), tags, attachments(Set<String>), queue, conflicts, reminders, meta(String), reset }502```503504Any number of subscribers; each receives every event (unbounded buffer) after the transaction commits. One505transaction emits at most one event per kind, in this order: `reset, pages, tags, attachments, queue,506conflicts, reminders, meta`. A failed transaction emits nothing. Leasing ops emits nothing. Only the changes507made through **this** `NotesStore` instance are observed: when another process writes the file (share508extension), signal it yourself (Darwin notification) and call `noteExternalChange()`, which emits `.reset`509(reload everything).510511## 12. Schema v2 (SPNotesCore 2.0)512513Version 2 adds seven tables and changes none of the v1 tables: `entities`, `entity_ops`, `ops_parked`, `canvases`, `events`,514`kv_cache`, `sync_cursors`. The migration, its backup and the down script are described in [`MIGRATION-V2.md`](MIGRATION-V2.md).515The HTTP client and the engine phases that fill these tables come with the next wave (backend contract `API-NEXT.md`); the store516side is complete and tested.517518### 12.1 Opening safely519520```swift521public static func open(url: URL, readOnly: Bool = false, backupRetention: TimeInterval = 600) -> StoreOpenResult522public enum StoreOpenResult { case opened(NotesStore, StoreOpenReport), failed(StoreOpenError) } // .store, .error, get()523public nonisolated let openReport: StoreOpenReport // foundVersion, migratedFrom, backupURL, removedBackups, didMigrate524public static func openError(for: Error, url: URL) -> StoreOpenError // for callers of init(url:)525```526527`StoreOpenError`: `newerSchema(found:supported:)`, `outdatedReadOnly(found:required:)`, `corrupt`, `locked`, `storage`,528`backupFailed`, `migrationFailed(from:to:reason:backupURL:)`, `other`; each has a French `userMessage`, `isTransient` and529`backupURL`. **An app must not replace a store that failed to open by `NotesStore.inMemory()`**: the user would see an empty530library and everything typed would be lost at quit. Show `userMessage` in a blocking screen and offer to retry / quit.531532```swift533switch NotesStore.open(url: fileURL) {534case .opened(let store, let report): start(store); if report.didMigrate { log(report) }535case .failed(let error): showBlockingError(error.userMessage, canRetry: error.isTransient)536}537```538539`init(url:)` keeps its 1.x signature and behaviour, plus the pre-migration backup; it throws `StoreError.backup` when the copy540cannot be written (the migration is then not attempted).541542### 12.2 Entities543544One generic table for the kinds of the entity change feed (SPEC §3.1): `EntityKind.task`, `.database`, `.databaseProperty`,545`.databaseView`, `.databaseRow`, `.edge`, `.reference`, `.canvas`, `.concept` (`EntityKind.all`, `feedParameter()`); a kind this546build does not list is stored like the others. A row is `EntityRecord { kind, id, rev, json, deleted, updatedAt, index, dirty,547remoteJSON }`; `json` is the server row, opaque to the store (`record.decode(T.self)`).548549```swift550public func entity(kind:id:) throws -> EntityRecord?551public func entities(kind:scope:ref:includeDeleted:limit:offset:) throws -> [EntityRecord]552public func entityCount(kind:scope:) throws -> Int; public func entityCounts() throws -> [EntityKind: Int]553public func tasks(pageId: String? = nil), databases(), databaseProperties(databaseId:), databaseViews(databaseId:),554 databaseRows(databaseId:limit:offset:), edges(from:), edges(to:), edges(touching:), references(projectId:), concepts()555public func applyRemoteEntities(_ rows: [RemoteEntity], tombstones: [EntityTombstone] = [], cursors: [EntityKind: Int64] = [:]) throws -> EntityApplySummary556public func entityCursor(kind:), entityCursors(), setEntityCursor(kind:_:), resetEntitySync(kinds:), removeSyncedEntities(kind:notIn:)557public func saveLocalEntity(kind:id:json:op:payload:baseVersion:index:) throws -> EntityOp558public func markEntitySynced(kind:id:json:rev:) throws -> Bool; public func dirtyEntities(kind:) throws -> [EntityRecord]559```560561- **Lookup columns.** `EntityIndex { scope, ref, sort }` is extracted from the JSON when a row is written so that typed queries562 use an index: `scope` = the owner (database of a property / view / row, page of a task, source of an edge), `ref` = a second563 id (target of an edge), `sort` = the order inside the scope (position, due date, name). `EntityIndex.defaultKeys` lists the564 JSON keys read per kind; it is **provisional** (written from SPEC §3 before `API-NEXT.md`; camelCase and snake_case are both565 accepted) — a caller that knows the row shape passes `RemoteEntity.index` explicitly.566- **Applying the feed** is one transaction with its cursors. A row whose stored `rev` is not lower is skipped (a window applied567 twice changes nothing). A row with local changes pending keeps its JSON: the server copy goes to `remoteJSON` and the row is568 listed in `keptLocal`. A tombstone removes a clean row; on a dirty row it only sets `deleted`.569- **Local edits.** `saveLocalEntity` writes the row (`dirty`) and its outbox entry in the same transaction. `markEntitySynced`570 clears `dirty` once no outbox entry remains for the entity (a locally deleted row is then removed).571- Per-kind cursors live in `sync_cursors`; the page feed keeps `meta["sync.cursor"]`.572573### 12.3 Entity outbox574575```swift576public func enqueueEntityOp(kind:entityId:op:payload:baseVersion:) throws -> EntityOp577public func nextEntityOps(limit: Int = 50, now: Date = Date()) throws -> [EntityOp]578public func completeEntityOp(id:), failEntityOp(id:error:now:), markEntityOpUnsupported(id:reason:), rejectEntityOp(id:error:)579public func retryEntityOps(id: Int64? = nil, where: ((EntityKind, String) -> Bool)? = nil) throws -> Int580public func discardEntityOp(id:) throws -> EntityOp?581public func entityOps(state:), entityOps(kind:entityId:), entityOpCount(state:)582```583584`EntityOp { id, kind, entityId, op, payload, baseVersion, idempotencyKey, createdAt, attempts, nextAttemptAt, lastError, state }`585with `op` a string (`EntityOpVerb.create / update / delete`, or any verb) and `state` `pending | unsupported | rejected`.586587- Processed **in order**. The order of one entity is never broken: an operation is held back while an older one of the same588 (`kind`, `entityId`) is in backoff, unsupported or rejected; other entities are not blocked. No lease: the caller settles each589 operation before asking again.590- **Nothing unsent is ever dropped.** An operation this build has no handler for is marked `unsupported`; one the server refuses591 for good is marked `rejected`. Both stay in the table with payload and idempotency key, are listed by `entityOps(state:)`, and592 leave only through `retryEntityOps` (back to `pending`, e.g. after an update) or `discardEntityOp` (the user's explicit593 decision; the removed entry is returned). A state string written by a newer build reads as `unsupported`.594- `failEntityOp` uses the same backoff as the 1.x queue (5 s doubling to 900 s).595596### 12.4 Parked ops of the 1.x queue597598Until 2.0 the engine completed — that is, silently deleted — a queued op whose kind it did not know. Now:599600```swift601public func parkOp(id: Int64, reason: String, now: Date = Date()) throws602public func parkedOps() throws -> [ParkedOp]; public func parkedOpCount() throws -> Int603public func unparkOps(kinds: Set<String>? = nil) throws -> Int604```605606A parked op stays in `ops` (payload and key intact), is never handed out by `nextOps`, and does **not** hold back later ops of607the same target. `SyncEngine` parks unknown kinds, reports them in `SyncStatus.unsupported` (they no longer count in `pending`)608and calls `unparkOps(kinds: SyncEngine.supportedOpKinds)` at the start of each cycle, so an updated build runs them.609610### 12.5 Canvases611612```swift613public func canvas(pageId:) throws -> CanvasRecord?614public func saveCanvas(pageId:json:) throws -> Bool // local edit: dirty, editSeq + 1, base captured once615public func canvasesNeedingPush(limit:includeConflicts:) throws -> [CanvasRecord]616public func markCanvasPushed(pageId:version:pushedEditSeq:pushed:), markCanvasPushFailed(pageId:error:)617public func applyRemoteCanvas(pageId:json:version:rev:) throws -> CanvasApplyResult // .applied | .unchanged | .diverged(base:local:remote:remoteVersion:)618public func resolveCanvas(pageId:merged:remote:remoteVersion:), recordCanvasConflict(pageId:remote:remoteVersion:),619 discardCanvasConflict(pageId:), canvasConflicts(), deleteCanvas(pageId:)620```621622Same optimistic model as pages. The JSON (`spn-canvas-1`) is opaque to the store: on `.diverged` nothing is written and the623caller merges with `CanvasDocument.merge` (SPNotesDocument), then stores a clean merge with `resolveCanvas` or keeps the server624copy aside with `recordCanvasConflict` (the local canvas is untouched and leaves the push list until a decision). Purging a page625removes its canvas.626627### 12.6 Events and read-model caches628629```swift630public func cacheEvents(_ events: [EventRecord], fetchedAt: Date = Date()) throws631public func events(_ query: EventQuery = EventQuery()) throws -> [EventRecord] // pageId, kinds, kindPrefix, from, to, actor, limit, offset632public func eventCount(), latestEventDate(), clearEvents(before:)633public func setCached(_ key: String, json: Data, fetchedAt: Date = Date(), etag: String? = nil) throws // or value: Encodable634public func cached(_ key: String) throws -> CachedValue? // json, fetchedAt, etag, age(), isFresh(maxAge:), decode()635public func cachedKeys(prefix:), removeCached(key:prefix:)636```637638Offline copies of what the server computes; nothing is ever generated locally. `EventRecord` mirrors `knowledge_events` (SPEC639§3.2). `CacheKey` names the read models: `health`, `brief`, `briefSummary`, `insights`, `models`, `meta`, `graph(view:scope:)`,640`zoom(pageId:level:)`, `query(_:)`, `timeMachine(scope:at:)`. Every cached value carries its fetch time: show it ("mis à jour il641y a …") whenever the device is offline.642643### 12.7 Changes644645`StoreChange` gains `entities(kind: String, ids: Set<String>)`, `entityQueue`, `canvases(Set<String>)`, `events`, `cache(String)`,646emitted after the 1.x events in that order. A `switch` over `StoreChange` without `default` must add them.647648## 13. Known limits649650- `trash`/`restore` cancellation ignores pages moved into or out of the subtree between the two calls.651- A page purged locally while its creation request is in flight comes back from the feed unless the engine652 purges it on the server when `markPushed` throws `notFound`.653- Properties equality ignores key order but is otherwise structural; content equality is byte equality.654- `removeSyncedPages(notIn:)` scans every clean page: use it only after a full re-download.655- Entities: one outbox entry per local change, no coalescing; `saveLocalEntity` stores the whole JSON the caller gives (no656 field-level merge with `remoteJSON` — the engine decides when the outbox is empty).657- A read-only connection cannot open a WAL database that was closed cleanly by every writer (no `-shm` file to map); this is658 SQLite's rule and already applied to 1.x widgets. `StoreBackup.peekVersion` falls back to the file header in that case.659- The pre-migration backup needs free space for one more copy of the database.660