SPB Git

Repository Public

REPOSITORIES.md 12.5 KB 175 lines markdown

1<!--2SP Notes Core3File: docs/REPOSITORIES.md4Description: How the apps use the repositories layer of SPNotesCore 2.0: which repository for what, what works offline,5             typed errors, cached read models and their staleness, and the fake backend for app unit tests.6Author: Simon-Pierre Boucher7Contact: contact@spboucher.ai8-->910# Repositories — the API of the apps (SPNotesCore 2.0)1112The repositories sit on top of the store, the API client and the sync engine. They live in the `SPNotesSync` module13(`Sources/SPNotesSync/Repositories/`; a deliberate choice: no new product, nothing to add to the app projects — `import14SPNotesCore` is enough). They are `Sendable` structs with `async` methods, safe to hold in an `@Observable` model.1516```swift17let repos = NotesRepositories(store: store, api: api, engine: engine)1819@Observable @MainActor final class TasksModel {20    var tasks: [TaskItem] = []21    let repo: TasksRepository22    init(_ repos: NotesRepositories) { repo = repos.tasks }23    func load() async { tasks = (try? await repo.list(.open)) ?? [] }24    func observe() async { for await _ in await repo.changes() { await load() } }25    func add(_ title: String) async throws { try await repo.create(title: title); await load() }   // works offline26}27```2829Gate UI on the server features: `await repos.features()?.has(ServerFeature.canvas)` (nil = never asked yet).3031## 1. What works offline (SPEC §6)3233| Repository | Read offline | Write offline | Write online |34|---|---|---|---|35| `TasksRepository` | yes (entity copy) | **yes** — outbox, client ids, idempotent | — |36| `CanvasRepository` | yes | **yes** — merge by node / edge id, conflicts kept | `refresh` |37| `DatabasesRepository` | yes (definition, properties, views, rows; local filter / sort / group) | no → `.offline` | yes; the answer updates the local copy |38| `GraphRepository` | relations, backlinks, concepts (entity copy); views and insights from the cache | no → `.offline` | relations create / accept / reject / edit / delete, concepts, insight decisions |39| `ResearchRepository` | references, citation resolution | no → `.offline` | references, DOI, BibTeX, experiments |40| `TimelineRepository` | events already fetched; cached time-machine states | — | restore a history entry |41| `KnowledgeRepository` | health, brief, zoom, query results from the cache, with their date | — | brief summary (paid, explicit) |42| `InboxRepository` | last list | no → `.offline` (the 1.0 queued triage still exists) | capture, triage, undo, suggestions |43| `SearchRepository` | local full-text | — | server results merged in |44| `AssistantRepository` | model catalogue from the cache | — | ask, actions |45| `AudioRepository` | — | — | upload, transcribe, poll |4647**No silent queueing.** A write of a kind that is online-only never goes to an outbox: unreachable server →48`RepositoryError.offline`, and nothing changed locally. Disable the control or tell the user; do not retry in the background.4950## 2. Errors5152```swift53public enum RepositoryError: Error { case offline, signedOut, unsupported(feature:), notCached, notFound(String), server(APIError), store(String), invalid(String), stale }54```5556- `.offline` — no connectivity, connection failure or timeout.57- `.unsupported` — the server does not have the feature (a 2.x server, `501`, or a route that answers the HTML 404).58- `.notCached` — offline (or `.cacheOnly`) and this read model was never fetched.59- `.server(error)` — the server said no: `error.code` is the stable code (`relation_exists`, `concept_exists`, `derived_edge`,60  `bad_node`, `row_deleted`, `conflict`…), with typed accessors (`error.existingRelation`, `error.existingConcept`,61  `error.badNodeField`, `error.isConflict`, `error.needsReauth`, `error.plan` for `confirm_expensive`).62- `.stale` — what a decision was made on changed since it was read (canvas conflict): read again, ask again.6364## 3. Cached read models6566Every read model returns `Cached<T> { value, fetchedAt, source: .network | .cache }`; `isStale(maxAge:)` and `Staleness.brief /67.health / .graph / .insights / .events / .zoom / .query / .models / .timeMachine` give suggested ages. Policies:68`.networkFirst` (default: ask, fall back to the copy when offline), `.cacheFirst(maxAge:)`, `.cacheOnly`, `.networkOnly`.69Nothing is ever recomputed on the device: when `source == .cache`, show the date (« mis à jour il y a … »).7071```swift72let brief = try await repos.knowledge.brief(policy: .cacheFirst(maxAge: Staleness.brief))73if brief.source == .cache { banner = "Mis à jour \(brief.fetchedAt.formatted(.relative(presentation: .named)))" }74```7576## 4. The repositories7778### Tasks — `TasksRepository`79`list(_ filter: .open | .done | .all, pageId:)`, `task(id:)`, `isPending(id:)`, `create(title:dueAt:dueDay:priority:status:project:pageId:blockId:id:)`,80`update(id:_ TaskEdit)`, `setDone(id:_:)`, `delete(id:)`, `pendingOperations()`, `retry(operation:)`, `discard(operation:)`, `changes()`.81A bare day (`dueDay: "2026-11-21"`) is noon UTC, as on the server: display the UTC date part. Operations the server refuses for82good are `state == .rejected` in `pendingOperations()` and counted in `SyncStatus.rejected`: show `lastError`, offer retry or83discard. A `taskItem` linked to a task (`taskId`): put a fresh UUID in the node and save the page — the server creates the task;84completing a linked task from a list does not tick the box in the page (API-NEXT §4.2): tick it too when the page is open.85On a 2.x server writes throw `.unsupported(feature: "tasks-v2")` once the features are known.8687### Canvas — `CanvasRepository`88`state(pageId:)`, `create(title:parentId:section:document:id:)` (offline), `save(pageId:_:editedFrom:)` (**use this one in an89editor**: it merges your edit into the stored canvas when a sync moved it under you, and returns the document to continue90from), `save(pageId:_:)` (unconditional), `refresh(pageId:)`, `conflicts()`, `conflict(pageId:)`, `resolve(_ conflict:_:)`91with `.keepMine | .keepTheirs | .merged(document)`, `changes()`.92A conflict (`SyncStatus.canvasConflicts`, `state.hasConflict`) never changed anything: `conflict.local` is what the user sees,93`conflict.remote` the server copy, `conflict.merge.merged` the proposal (local version of each conflicting card; an edited card94is kept when the other side deleted it) and `conflict.merge.conflicts` the list to show; build the decision with95`merged.resolving(conflict, takingRemote:)`. `resolve` throws `.stale` when the canvas moved since the conflict was read.9697### Databases — `DatabasesRepository`98Local: `list()`, `database(id:)` (database id or host page id) → `LocalDatabase { info, properties, views }`, `localRows`,99`evaluateLocally(databaseId:viewId:query:)`. Mixed: `rows(databaseId:viewId:search:limit:offset:)` → server when reachable100(`source == .server`, computed values included), local evaluation otherwise. Online: `refresh(id:)`, `update`,101`createProperty / updateProperty / deleteProperty`, `createView / updateView / deleteView`, `createRow / updateRow / deleteRows /102restoreRows`.103`DatabaseEvaluator` applies the server's rules (`query.ts`): the 15 operators per property type, `and` / `or` trees, search,104multi-key sorts with empty values last, pagination, and grouping (a client feature on the web too). It evaluates the stored105types (title, text, url, number, date, checkbox, select, status, multi_select, created_time, ai); a rule or a sort on a106**relation, rollup or formula** is not applied and the result has `isExact == false` and `notEvaluated` (names): show the rows107as "approximate offline" or ask the server. Calendar days are those of the server's time zone (`America/Toronto`).108Verified row for row against the real server on 14 filter / sort / search cases (`LiveRepositoryTests`).109A filter sent to the server must be a group at the top level: use `DatabaseViewFilter.topLevelJSON`.110111### Graph — `GraphRepository`112`view(_ GraphQuery, policy:)`, `insights(_:policy:)`, `runInsights(_:)` (default deterministic = free), `decideInsight`,113`localRelations(touching:)`, `localBacklinks(pageId:)`, `relations(_:)`, `createRelation`, `accept / reject / update(relationId:)`,114`deleteRelation`, `localConcepts`, `concepts`, `concept(id:)`, `createConcept / updateConcept / deleteConcept`.115Anything with `origin == "ai"` must be shown as AI, accepted or not.116117### Timeline — `TimelineRepository`118`events(_ JournalQuery, policy:)` → `TimelinePage { events: [EventRecord], nextCursor, source, fetchedAt }` (pass `nextCursor`119back as `query.cursor`; offline the local events are filtered by page, kinds and dates), `timeMachine(pageId: | projectId:, at:)`,120`restore(pageId:versionId:baseVersion:)`.121122### Knowledge — `KnowledgeRepository`123`health`, `brief(timeZone:)`, `summarizeBrief` (paid), `query(_ LiveQuery)` for `queryView` / `chart` blocks, `zoom(pageId:level:)`124(2 = outline, 3 = full), `synopsis(pageId:cachedOnly:)` (level 1, AI; `cachedOnly: true` by default so that nothing is spent125without a user action).126127### Research — `ResearchRepository`128`localReferences(pageId:)`, `resolveLocally(ids:)`, `resolve(ids:)` (for `citation` nodes; falls back to the local copy129offline), `create / update / delete / restore`, `lookupDOI`, `addByDOI`, `importBibTeX(_:pageId:dryRun:)`, `exportBibTeX`,130`exportLaTeX`, `experiments`, `createExperiment / updateExperiment / deleteExperiment`, `overview`.131132### Inbox — `InboxRepository`133`items(policy:)`, `count()`, `capture(_ CaptureDraft)`, `triage(id:_ InboxAction)` → `actionId`, `undo(actionId:)`,134`suggestions(id:cachedOnly:)` (AI, suggestions only), `apply(id:_ InboxSuggestionSelection)`.135136### Search — `SearchRepository`137`local(_:filters:limit:)` for search-as-you-type; `search(_:scope:filters:limit:)` → `SearchOutcome { results, usedServer,138serverError }` where each `UnifiedSearchResult` is labelled `.local | .server | .both`, carries the server's `blockId` /139`heading` when there is one, and one snippet convention (the local highlight markers). Scopes: `.serverLexical` (default, free),140`.hybrid` (**the server embeds the query: one paid provider call per search** — only on an explicit "search by meaning"),141`.localOnly`. A failing server never fails the search.142143### Assistant — `AssistantRepository`144`ask(_:scope:pageId:projectId:selection:selectionBlockId:conversationId:model:)` → stream of `AIEvent`; `citations(of:)` gives145`AssistantCitation { n, pageId, blockId, title, heading, quote, anchor }` for `meta` and `done` events (scroll to the node whose146`id` is `blockId`); `actions()` (the 21 historical ids + `coherence, questions, synthesis, structure, links`), `run(action:text:…)`147(`links` yields `event.linkSuggestions`, nothing is written); `models(_:policy:)` → `AIModelCatalog` (group by `creator`, show148the `route` badge, never select `available == false`, "Auto" = `model: nil`), `logoURL(_:)`.149150### Audio — `AudioRepository`151`upload(fileURL:pageId:)` → attachment id, `transcribe(attachmentId:summarize:force:)` (paid), `status`, `waitForTranscription`152(polls every 2.5 s), `transcribeRecording(fileURL:pageId:)` (all three), `nodeAttributes(from:)` — the editor writes the153transcript into the `audio` node and saves the page; the server never edits the page. `.unsupported(feature: "voice")` on a154server without the routes.155156## 5. Unit tests in the apps: the fake backend157158Add the product `SPNotesTestSupport` to the **test** targets only. `FakeBackend` is an in-memory server behind a159`URLProtocol`: session and Origin checks, idempotency keys, the change feed with one revision sequence, pages, tags, conflicts,160attachments, tasks, inbox triage, and — at `apiLevel: 3` (default) — `/api/meta`, the entity feed (`kinds`), tasks with client161ids, canvases with versions, opaque rows for the other kinds. `FakeBackend(apiLevel: 2)` answers like a 2.x server.162163```swift164let fake = FakeBackend()165let client = HTTPClient(configuration: APIConfiguration(baseURL: fake.baseURL, userAgent: "tests"),166                        tokenStore: InMemoryTokenStore(token: fake.issueToken()), sessionConfiguration: FakeBackend.sessionConfiguration())167fake.webCreateTask(title: "Du web"); fake.webSaveCanvas(id, data: json); fake.webPutEntity(kind: "concept", id: id, json: "{…}")168fake.stub("GET", path: "^/api/health/knowledge$", json: recordedAnswer)         // any route the fake does not model169fake.setOffline(true); fake.inject(.dropResponse, method: "PUT", path: "^/api/canvases/"); fake.inject(.status(500), path: "^/api/tasks")170defer { fake.shutdown() }171```172173The real answers recorded from the scratch backend are in `Tests/SPNotesAPITests/Fixtures/next/` (about 480 files in 20 groups, one `_index.json` per group):174use them as stub bodies, as `RepositoryOnlineTests` does.175
Files main
Menu

Theme