OpenIntelligence Architecture Atlas
Read this file by section, never whole (about 180 KB):
grep -n '^## ' Docs/OPENINTELLIGENCE_ARCHITECTURE_ATLAS.md, then the section a task touches. Routes inDocs/AuditArtifacts/RepoOS/change_impact_matrix.csvname the section.
Documentation status: Generated from the July 2026 audit, whose artifacts are in
Docs/AuditArtifacts/ArchitectureAtlas/(this file is registered there as the Phase 8 map inARTIFACT_REGISTRY.csv); not regenerated as a whole since, but corrected and extended in place through 2026-11-07 (every code citation and named symbol checked against the code that day; 432 corrected), each change dated where it is made, and the code wins where a section here disagrees with it. This file does not track the shipped version: readDocs/SHIPPED_VERSION.json(app_storefor what is live,in_reviewfor what is submitted).Docs/CANONICAL_OPENINTELLIGENCE_SOURCE_OF_TRUTH.mdoutranks this file where the two disagree (canonical §1). Component count is drifting. The 270 figure below came from the audit’s component definition at generation time. As of 2026-08-05 the tree holds 278 first-party Swift files (301 including vendoredswift-transformers). Those are not necessarily the same metric, so treat 270 as the audit’s number rather than a current count, and re-run the audit before quoting either figure publicly.[evidence_level: code_verified_for_the_file_count, confidence: exact_for_files_unverified_for_component_parity]Corrected 2026-10-20 against the code at1e379aa: in section 20, Standard’s single-shot bullet (it searches again by rule and can make more than one model call), the chain’s session count and the token budget no loop reads, the title-routing menu,executeRecursiveResearch’s two call sites, and “The gap” paragraph (the coverage gate, the quality branch, about five sessions on an iPhone). Also the config Deep Think’s orchestrator gets (“Adaptive generation profiles”, item 3), section 10’s PCC sentence, section 16’s ingestion diagram (two keyword-index writes, a flat vector file), the gates’ callers in section 4, and the entity index in section 5. Each correction is marked where it is made.
1. Executive Overview
The OpenIntelligence Architecture Atlas is the canonical representation of the repository’s components, execution flows, and system boundaries. It was generated via a strict evidence-based static analysis protocol. The system is composed of 270 Swift components divided into 30 subsystems, with high-risk boundaries located in iCloud sync, StoreKit entitlements, and Private Cloud Compute (PCC) routing.
2. Subsystem Map
- App Intents/Siri/Shortcuts: 9 components
- Apple Foundation Models: 8 components
- OCR/extraction: 13 components
- PCC routing/consent: 3 components
- SQLite/FTS storage: 1 component
- StoreKit: 8 components
- app lifecycle: 6 components
- background tasks: 2 components
- billing/entitlements: 4 components
- chat UI: 19 components
- chat persistence: 3 components
- citations/source rendering: 20 components
- context packing: 1 component
- diagnostics/telemetry: 27 components
- document import: 11 components
- embeddings: 13 components
- export/reporting: 1 component
- generation: 7 components
- iCloud/workspace sync: 13 components
- ingestion queue: 10 components
- library/container management: 15 components
- onboarding: 5 components
- reranking/fusion: 5 components
- retrieval: 38 components
- semantic chunking: 4 components
- settings: 13 components
- tests: 6 components
- vector storage: 3 components
- verification gates: 3 components
- docs/audits: 0 components (Markdown/CSV files)
3. Component Dependency Map
- UI Views depend on ViewModels.
- ViewModels inject Services (e.g.,
RAGService,WorkspaceSyncService). - Services interface with Storage (
SQLiteFullTextService,BNNSVectorDatabase). - Storage interfaces with File System (
Application Support).
4. Service Map
-
RAGService: Core retrieval-augmented generation orchestrator. (Since 2026-11-05 its code is split by job acrossRAGService.swiftand fifteen newRAGService+*.swiftfiles, beside the three that existed (+KnowledgeRetrievalEngine,+Streaming,+TextStreaming),, andAgenticOrchestratoracross nine files;Docs/ai/ARCHITECTURE.mdmaps them.) Since 5.4 it also owns the end of an answer:finishAnswerNow()ends the stages that run after an answer’s text is complete (the source-only check, and every stage wrapped inrunFinishableStage) so the response returns with its sources, and Standard skips the source-only check when the verification gates passed (standardSkipsSourceOnlyCheck).[evidence_level: code_verified, confidence: exact, evidence_source: RAGService.swift, SourceOnlyStandardGateTests] -
AgenticOrchestrator: Deep Think and Maximum.executeparks the chat’s stream handler inLLMStreamingContext.finalAnswerHandlerfor the whole run, so only the calls that write the final answer stream (throughLLMStreamingContext.answerHandler); research, the verification loop and Maximum’s refinement run as finishable stages.[evidence_level: code_verified, confidence: high, evidence_source: AgenticOrchestrator.swift, LLMService.swift] -
AppServices(added 2026-11-04, 5.8;OpenIntelligence/App/AppServices.swift):AppServices.sharedbuilds the process-wideRAGService,WorkspaceSyncService,ContainerService,EntitlementStore,SettingsStoreandModelResolutionServiceonce per launch for every window; see section 9.[evidence_level: code_verified, confidence: exact, evidence_source: AppServices.swift:14-55] -
WorkspaceSyncService: Manages iCloud Drive ubiquity sync. Since 5.7 a pass skips a library’s vector store while an import into it is unfinished on this device (librariesWithUnfinishedImports), and the digests of the stores it has reconciled are kept across launches.[evidence_level: test_verified, confidence: high, evidence_source: WorkspaceSyncService.swift; WorkspaceSyncImportGuardTests] -
PassageFileIndexandPassageSlot(added 2026-10-12, 5.7): the walk over the vector store’s metadata file that finds each passage’s bytes and reads its id, document, number, page and level without decoding it; described under Sync Boundaries, section 9, with the store.[evidence_level: test_verified, confidence: high, evidence_source: PassageFileIndex.swift; VectorStorePassageIndexTests] -
LibraryIntelligenceCenterandLibraryIntelligenceCache(changed 2026-10-13, 5.7): the library analysis (language, vocabulary, code and math, sentence shape) that recommends chunking and embedding settings and fills the dashboards. It reads every passage of a library up to 4,000 (analysisPassageLimit) and at most that many of a larger one, picked from the store’s records and read by id (samplePositions). A report from a sample is marked (CorpusSignals.isEstimate);RAGService.resolveAutoAdjustmentslets the chunking settings follow it as they follow any report and never takes another embedding model from one, unless the library has no documents yet. (No report starts a rebuild today:scheduleSelfTuningRebuildis behindIngestionContext.allowsSelfTuningScheduling, false for every kind of import.) The report and the first question’sCorpusVocabularyare kept in the local cache folder (LocalCache/LibraryIntelligence), each under a name that carries a hash of the library’s documents and the store’s passage count, and are used only under the name the library has now.removeStale(every refresh and after every write),remove(a library’s deletion) andsweep(every load of the documents) remove what no longer matches, and a vocabulary is kept only when it was built from every passage in the store and each belongs to a listed document (RAGService.vocabularyMayBeKept). The vocabulary build, the picking of the sample and the files’ reads and writes run on the concurrent pool;RAGServiceitself is on the main actor.RAGService.libraryVocabularyholds a vocabulary in memory for later questions only when it is of the whole library as it is when the build ends. Through 5.6 the analysis ran over every passage at every load of the documents: 199 s and 1,054 MB over what the process held, for 144,247 passages on a Mac.[evidence_level: test_verified (LibraryAnalysisSampleTests), measured on the Mac (LibraryAnalysisScaleBenchmarkTests), not run on a device, confidence: high, evidence_source: AdaptiveEmbeddingOptimizer.swift; RAGService.swift refreshIntelligence, generateIntelligenceSnapshot, libraryAnalysisInput, libraryVocabulary, applyLoadedDocuments] -
EmbeddingProviderDefaults(added 2026-10-10, 5.7): the one place that says which copy of the bundled sentence model a new library uses, Core ML on iPhone and iPad and Core AI on macOS 27, and that the two are copies of one model (areCopiesOfOneModel), so auto-tuning does not move a library between them. Asked bySettingsStore,ContainerService.defaultContainer,AdaptiveEmbeddingOptimizerandRAGService.evaluateEmbeddingShift.[evidence_level: test_verified (LargeLibraryCostTests); code_verified for the callers, confidence: high, evidence_source: EmbeddingService.swift] -
DocumentProcessor.decodeTextFile(added 2026-10-10, 5.7): decides how a text file’s bytes are read (UTF-16 by its mark or by its zero bytes, UTF-8, Foundation’s lossless detection, Windows-1252, Latin-1). Detail inDocs/INGESTION_PIPELINE.md.[evidence_level: test_verified, confidence: high, evidence_source: DocumentProcessor.swift; IngestionAccuracyTests] -
AtlasLabeling,MetricDiagnosticsandSystemModelTools(added 2026-10-10, 5.7): the Knowledge Atlas’s naming rule, the MetricKit subscriber and the two system model tools. They are described in section 9 below, where the notes of that day were added. -
SQLiteFullTextService: Manages shared relational storage. Since the 2026-11-05 split (5.8, a pure move) the actor isSQLiteFullTextService.swift(state, initialization and the schema, migrations and query helpers, unchanged) with+Documents,+Chunks,+Search,+Statisticsand+ContentReader; the schema is still edited only with the owner naming the file.[evidence_level: code_verified, confidence: exact, evidence_source: the split plan and prove_move.py, 0 lines changed beyond 17 access keywords] -
EntitlementStore: Manages UserDefaults-backed billing logic. -
RAGService+AnswerHeadline.swift(5.8, 2026-11-13):strippingStrayLeadingListNumber(incleanupResponseText) anddroppingUnsupportedHeadlineNumber(Standard, after the responsiveness step) take a list number and a headline total no passage states off the front of an answer.PassageGenerations.newest(of:)(Core/Models) keeps each document’s newest run of passages; not yet called by the sync merge (WorkspaceSyncService+Merging.swift, hard boundary).hideClusterLabelsThatCollide(SceneConstruction.swift) runs afterkeepAxisLabelsInVieweach frame.[evidence_level: code_verified, confidence: high] -
(5.8, 2026-11-13)
ModelCompileCache.clearOncePerVersionclears Core ML’s compiled models only when a bundled model’s fingerprint changes (shouldClear), not per app version;CoreMLSentenceEmbeddingProvider.prediction(from:length:model:)reloads the model and then falls back to the CPU when a prediction throws;RerankerSetupStatus.setStepgives the setup card its two real steps.[evidence_level: code_verified, confidence: high] -
(5.8, 2026-11-13)
RAGService.judgedQuestiongives the responsiveness judge the current question first, with earlier turns marked as reference;removingCopiedReferenceNumberstakes a paper’s own bracketed reference numbers out of a Standard answer before its citations are looked for.[evidence_level: code_verified, confidence: high] -
(5.8, 2026-11-13) Standard’s prompt carries earlier turns after
RAGService.earlierTurnsFraming, without heading marks;removingEchoedPromptSectionsstrips a section the answer echoed from its prompt;Tour.tourIsRunningends the tour after three days andpacedTipsPerLaunchcaps it at two a launch;RerankerModelLocationkeeps the model copies under the app group’s folder.[evidence_level: code_verified, confidence: high] -
(5.8, 2026-11-14)
RAGService.valueRestatesQuestionjoins grouped digits with a valid pattern (\x{2009}, not\u{2009}), so “3,026” is read as the question’s “3026”.[evidence_level: test_verified, confidence: high] -
(5.8, 2026-11-14)
RAGService.namingTheCitedDocumentwrites the cited file’s name after the first citation of an answer to a which-document question, infinalizeResponse(Standard) and on the agentic answer (RAGService+AgenticQuery.swift).[evidence_level: code_verified, confidence: high] -
(5.8, 2026-11-15) Which earlier turns reach Standard’s prompt and the query rewriter:
ConversationContextRules(inConversationMemoryService.swift) leaves out a refused answer (isRefusal:StructuredAnswer.refuse, or a gating decision only a refusal records;MemoryTurn.refusedrecords it atfinalizeResponse) with its question, an app-written failure message with its question, and every turn or message older than the library’s last change of documents (LibraryDocumentChanges, per library inUserDefaults, recorded fromRAGService.documents’didSetby document id and passage count once documents are loaded; the first look on a device records no change).buildGenerationPrompt(memory and the chat-history stand-in) andrewriteQueryWithModelboth apply it.clearMemorysaves an empty memory so the iCloud merge keeps it, drops a pending debounced save and discards a summary started before it; New Chat (createNewThread) clears the library’s memory and resets the model session. Deep Think and Maximum do not read conversation memory.[evidence_level: test_verified (ConversationMemoryServiceTests), confidence: medium, not seen on a device] -
(5.8, 2026-11-16) A refusal that no gate records carries
ConversationContextRules.refusedToken(answer_refused) in its gating decision, whichisRefusalreads;VerificationOutcomereads it as nothing, and the chat’s badge and the details’ Verification row readshownGatingDecision, which drops it, so a refusal shows as before. Marked where written: Quotes only and the excerpts fallback with no excerpt (RAGService.excerptsGatingDecision);RAGService.markingUngatedRefusalon Standard’s shown text after the source-only check (RAGService+QueryPipeline.swift) and on the agentic answer (RAGService+AgenticQuery.swift), fornotFoundAnswer,plannerAbstention, a stream a guardrail cut off (LLMResponse.cutOffByGuardrail, counted only while that text is the one shown), Deep Think and Maximum’s not-found exit (AgenticResult.refused); andfinalizeResponse, which every answer passes, for a model refusing in its own words (refusesInItsOwnWords: at most 500 characters, no[Scitation, not opening “No,” or “Yes”, and a first sentence that refuses in the first person or says the documents as a whole hold nothing). Siri’s hand-off answer isChatMessage.handedOff(persisted, false in older files) unless it refuses, andisErrorMessageexcludes it.ContainerService.deleteContainercallsConversationMemoryService.removeMemory, which deletes the local memory file on the write queue and saves nothing for that library again this launch; the iCloud copy goes withcleanupSharedWorkspace.[evidence_level: test_verified (ConversationMemoryServiceTests, ReleaseFinishTests, ModelErrorClassifierTests), confidence: medium, not seen on a device] -
LLMService: Handles prompt compilation and PCC execution. (5.8, 2026-11-13)RAGServicepicks its model service once, when it is made; a model not ready then leftAppleFoundationLLMServiceUnavailablein place until Settings changed.RAGService.reconnectAppleModelIfNowAvailable()(inRAGService+Consent.swift) runs at the start ofqueryand when the app becomes active (ContentView): when the current service is unavailable and Apple’s model now is, it rebuilds the services from Settings and journalsmodel.reconnected. When Quotes only was picked by the launch check and not by the person (SettingsStore.quotesOnlyOnlyBecauseModelWasNotReady), it moves the selection to Apple Intelligence (useAppleIntelligenceNowThatItIsReady, journalmodel.quotesOnlyLifted), since Quotes only skips every model step whatever service is in place.SettingsStore’s$selectedModelsink drops its first value (it had recorded every launch’s selection as the person’s), and the first 5.8 launch clears that flag once where On-Device Analysis is selected (quotesOnlyOverrideReviewed58).[evidence_level: code_verified, confidence: high] -
EvidenceThreadDebugService(removed 2026-10-21, 5.7): a diagnostics-only service forEvidenceThreadStorethat no other file referenced. -
JSONRecordExtractor(added 2026-10-09, 5.7): reads.json,.jsonland.ndjsonas records with its own order-keeping reader (JSONValue), cuts one passage per record and cuts an oversized record at its own lines; called only byDocumentProcessor.processDocument. Detail inDocs/INGESTION_PIPELINE.md.[evidence_level: code_verified, confidence: exact, evidence_source: JSONRecordExtractor.swift; DocumentProcessor.swift extractJSONRecords and makeJSONRecordChunks] -
OversizedChunkSplitter(added 2026-10-09, 5.7): cuts a passage over the embedding limit into parts made of its own text; called byDocumentProcessor.splitOversizedChunkByTokens, which used to retype the passage.[evidence_level: code_verified, confidence: exact, evidence_source: OversizedChunkSplitter.swift; DocumentProcessor.swift] -
WebPageFetchService(added 2026-10-09, 5.7): a GET to an address the person gave, following redirects, turned into a Markdown or original-type file for the import queue; called byIngestURLIntentandAddToLibraryIntent.[evidence_level: code_verified, confidence: exact, evidence_source: WebPageFetchService.swift]A grep ofOpenIntelligenceforURLSessionon 2026-10-09 finds it here and in three places outside the import path (the App Store rating snapshot, the adapter download and the local-server model client).[evidence_level: code_verified, confidence: high, evidence_source: that grep; it does not rule out a download made another way] -
EvidenceLineSplitter(added 2026-10-09, 5.7): the line and sentence cuts ofRAGService.extractRelevantSentences, moved out so they can be tested; it keeps a wrapped sentence whole and usesAnswerSentenceSplitterfor sentences.[evidence_level: code_verified, confidence: exact, evidence_source: EvidenceLineSplitter.swift; RAGService.swift extractRelevantSentencesOffMain] -
RAGQueryScope(added 2026-10-09, 5.7): a task-local set of document ids that limits oneRAGService.querycall to those documents’ passages. Set only byAskActionRunnerfor the three Shortcuts actions that name a document. Read inHybridSearchService.search(which then scores the named documents’ passages directly and returns nothing else), inqueryInternalafter retrieval (narrowing the result and the later stages’ candidate lists, skipping the query cache, and throwing when nothing is left), and where Deep Think, Maximum and the raw search build their candidate lists.[evidence_level: code_verified, confidence: medium, evidence_source: RAGQueryScope.swift; HybridSearchService.swift searchInsideScope; RAGService.swift; RAGAppIntents.swift AskActionRunner]No scoped question has been run; the action’s own last check on the returned passages is what guarantees the limit until one has. -
AppLinkandAppNavigationRequest(added 2026-10-09, 5.7): one address form for places in the app, and the queue that carries destinations from an action, a link, a Spotlight result or a handed-over file to the screen that shows them, delivering after each change.ContentView.routehandles the tab and the library for the oldest request;DocumentLibraryViewandChatScreentake the last step.[evidence_level: code_verified, confidence: exact, evidence_source: AppNavigationRequest.swift; ContentView.swift; DocumentLibraryView.swift; ChatScreen.swift]Since 2026-10-14: a document request opens the document’s page (DocumentLibraryView.takeDocumentRequest, which waits up to three seconds for the documents to load and then lets the request go, so it holds the queue back for at most that long);.ask(String)puts text in the chat’s field unsent and has no link form;AppActivity, in the same file, names the activity types the app advertises for Handoff, Spotlight and Siri and maps a continued activity to destinations, andInfo.plistdeclares them (NSUserActivityTypes).[evidence_level: code_verified for the paths, test_verified for AppActivity (AppActivityTests); confidence: high; evidence_source: AppNavigationRequest.swift; DocumentLibraryView.swift; ContentView.swift continueActivity]Since 2026-10-17: every link has a web form,https://gunndamental.com/openintelligence/open?to=(gunzino.me through 5.7) and the app link’s host, path and query (AppLink.webURL(for:)), whichAppLink.destination(for:)reads as the app link it carries, soContentView.handleOpenURLtakes a web link the way it takes an app link (SwiftUI hands a web link that opens the app toonOpenURL, developer.apple.com, read 2026-10-17). The entitlements carryapplinks:gunndamental.comfrom 5.8 (applinks:gunzino.methrough 5.7; gunzino.me 301-forwards to gunndamental.com since 2026-11-06, and Apple fetches an association file only with no redirect, so 5.7 web links land on the web page, which offers Open in OpenIntelligence); gunzino.me serves the association file for that one path and the page shown where the app isn’t installed (Gunzino5c10b42, 2026-10-17; Apple’s association CDN served the file the same day). Only https on the web host at/openintelligence/opencounts, andtocan’t carry another address.[evidence_level: test_verified (AppLinkTests), confidence: medium until a link opens the app on a device; evidence_source: AppNavigationRequest.swift AppLink.webURL, appURL(forWebURL:)] -
LibraryFocusFilterIntentandContainerService+Focus(added 2026-10-14, 5.7): a Focus filter (SetFocusFilterIntent) that names libraries; while its Focus is on, the two library pickers listContainerService.pickableContainersand the open library moves to the first allowed one. The allowed set is aUserDefaultskey beside the open library’s, so the system can apply it with no screen open; launch applies the filter in force.[evidence_level: test_verified for the pickers' list and the filter's tile (LibraryFocusFilterTests), code_verified for the rest, confidence: medium, evidence_source: LibraryFocusFilterIntent.swift; ContainerService+Focus.swift] -
MacServicesProvider(added 2026-10-14, 5.7, Mac only, app only): the threeNSServicesentries inInfo.plist(ask about selected text, add selected text, add files from Finder), set asNSApplication.servicesProviderbyOpenIntelligenceMacAppDelegateat launch; it posts.askor.importFilesto the router.[evidence_level: build_verified, confidence: high, evidence_source: MacServicesProvider.swift; OpenIntelligenceApp.swift] -
QueryLiveActivityService(added 2026-10-14, 5.7, iPhone and iPad): starts a Live Activity for a question still running ten seconds after it began, while the app is in front, or as the app leaves the front with a question running (willResignActiveNotification), because ActivityKit refuses a start from the background; it ends one left by an earlier launch, and follows the begin, progress and complete closures ofQueryRuntimeBridge(set inOpenIntelligenceApp.configureQueryRuntimeBridge, beside the background task and the completion notice); its views are in the widget extension’sIngestionLiveActivityWidget.swift.[evidence_level: build_verified, test_verified for its state; confidence: high; evidence_source: QueryLiveActivityService.swift] -
CheckClaimIntentandClaimCheck(added 2026-10-14, 5.7): “Check a Claim”, which finds six passages withsearchDocumentsRawand runsVerificationGateService.verifywith the sentence as its one claim and an empty question, returning the coverage gate’s verdict as a label, lowered from Supported when the claim and the passage’s best-matching sentence differ on a negation (ClaimCheck.matchingSentence,hasNegation), and naming the passage the gate’s evidence starts with. Gate B applies the same negation test to every claim Fact Check lists (ClaimCheck.negationDiffers). From 2026-10-20 it askshasNegation(_:against:), which counts a “without” only when the last word of what follows it is named in the other text, so “without fever-reducing medicine” in a passage no longer reads as the opposite of a claim that does not mention medicine. Later the same day, when both say “without” something the other names, that “without” is set aside and the other negations of its clause decide (resolvingWithout,clauseHoldingWithout), and Gate B also lowers a claim whose own words no one statement of its passages holds two of (ClaimCheck.wordsAreScattered,statements(in:): a table row or a list with its opening line is one statement), and counts an ordinal in the claim against the passages (NumericValueExtractor.isOrdinal), and that evening an amount written in words as a figure in a claim and in the passages, though not in the numeric gate over a whole answer (NumericValueExtractor.spelledAmounts,Mention.isSpelled: a number with hundred, thousand, million, billion or trillion in it, or followed by dollars or euros; a list in words is read as its parts, and a share, a decimal or an idiom such as “a hundred percent” not at all).[evidence_level: test_verified (ClaimCheckTests, including testWithoutCountsOnlyWhenWhatItIsWithoutIsNamed and testWordsSpreadAcrossSentencesAreNotOneStatement; ClaimCheckEvaluationTests with no known gap; NumericSanityGateTests), build_verified; confidence: medium; evidence_source: Services/Agentic/CheckClaimIntent.swift, Services/RAG/Safety/VerificationGateService.swift, Services/RAG/Safety/NumericValueExtractor.swift] -
ExportConversationIntent(added 2026-10-14, 5.7, app only, Features/Chat/Pipeline): “Export Conversation”, which returns a saved conversation from any library as anIntentFilein Markdown, JSON Lines or PDF, the bytes the chat menu writes (ConversationExporter.data);ConversationExporter.pdfsets the export as text with Core Text and breaks it into pages.[evidence_level: test_verified (ConversationExporterTests, ShortcutsActionTests), build_verified; confidence: high; evidence_source: ExportConversationIntent.swift; ConversationExporter.swift] -
UITestSupportandUITestRemoveDocumentsIntent(added 2026-10-14, 5.7, Debug builds only, App): with the launch argument--uitest-stand-in-modelthe ask actions’ engine gets a stand-in model that answers with theUITEST_STAND_IN_ANSWERenvironment value (AskActionRunner.makeEngine), and an action that Shortcuts does not list removes documents by the start of their names, eight characters or more. TheOpenIntelligenceUITeststarget, with its own scheme, uses them to run actions through the system with Apple’s AppIntentsTesting (iOS 27). A release build compiles none of it.[evidence_level: test_verified (ShortcutsSystemTests, 2 tests, iOS 27 simulator, 2026-10-14), confidence: high, evidence_source: OpenIntelligence/App/UITestSupport.swift] -
DirectModelCallsForTesting(added 2026-11-06, 5.8, Debug builds only, Services/AIPlatform): a switch the golden recorders turn on so the eight services that askSystemLanguageModel.defaultthemselves take their no-model path; off, it changes nothing, and a Release build reads it as false. WithNetworkMonitor.holdForTesting(_:)it letsStandardPipelineGoldenTestsrecord a Standard answer as a fixed function of its prompt (Docs/ai/RUNBOOK.md, “Proving a Standard, import or parsing change changes nothing”). -
CloudConsentRelay(added 2026-10-14, 5.7): carries a Private Cloud Compute consent request from the engine an action builds for its question (RAGService.asksThroughRelay; never the chat’s own) toContentView, keeping it before announcing it so a window can claim it from the announcement, never taking a sheet on screen away, which showsCloudConsentPromptViewin the first window to claim it; a request no window shows within 15 s is given up and nothing is remembered (RAGService.abandonCloudConsentRequest).[evidence_level: test_verified (CloudConsentRelayTests), confidence: high for the relay; the action's side waits on a device, evidence_source: CloudConsentRelay.swift] -
CrashReports(added 2026-10-14, 5.7, app only): saves a crash diagnostic MetricKit delivers (MetricDiagnostics) as a file of its own in the local cache’sCrashReportsfolder, newest ten kept, a crash delivered twice kept once, without an exception’s message text or arguments or the memory region description;ContentViewoffers the newest one once, in the first window to ask (takePending), Email Report opens a mail to the feedback address with its summary, andAboutViewshares the whole file.[evidence_level: test_verified (CrashReportsTests), confidence: high for saving and offering; no diagnostic delivered on a device yet, evidence_source: CrashReports.swift] -
EmbeddingVectorCheck(added 2026-10-14, 5.7): runs after the embedding call of every import path (an import, a rebuild, a PDF over 10 MB, a large text file) and stops the import when more than half of a batch’s vectors are unusable (all zero, empty or not finite), with a message naming the file; fewer are logged and stored.RAGService.evaluateSemanticIndexHealth, on a library switch, also samples 64 of a store’s vectors and re-embeds a library whose sample is nine-tenths empty, and rebuilds by itself a listed document that had passages and has none in the store (reembedDocuments(onlyDocumentIds:)), each once a launch. Gate E reports nothing to ground against for empty vectors.[evidence_level: test_verified (LibraryVectorHealthTests), confidence: medium, not run against a failing model on a device, evidence_source: EmbeddingVectorCheck.swift, RAGService.swift] -
QuickActionsWidget(added 2026-10-14, 5.7, the Live Activities extension, iPhone and iPad): a Home Screen and Lock Screen widget whose sizes open the app’s own links (openintelligence://chat,documents/add,chat/scan), as the controls beside it do. It reads nothing from the app, so it needs no app group.[evidence_level: build_verified, confidence: medium, evidence_source: IngestionLiveActivityWidget.swift, OpenIntelligenceLiveActivitiesBundle.swift] -
LibraryWidgetandWidgetSnapshot(added 2026-10-15, 5.7, the Live Activities extension and the app, iPhone and iPad; not in the widget bundle until the App ID carries the app group): “Your Library” shows the open library, its document count and, on the medium size, the last question in that library with the start of its answer (privacySensitive). The app writesWidgetSnapshot(widget_snapshot.json) to the app groupgroup.Gunndamental.OpenIntelligencefromContentView(library and count, once an import ends),ContainerService.applyFocusFilter(a Focus that moves the open library) andChatScreen.recordForLibraryWidget(an answer, which is a message with metadata, after the conversation is saved, with its conversation and message ids). The answer leaves the widget when another library opens, whenChatScreen.clearChatorThreadSidebarViewremoves its conversation, whenMessageBubbleV2hides it, and when sync removes its conversation (ContentView.refreshSharedWorkspaceIfNeeded). Nothing is written on the Mac, where no widget extension is built.OpenIntelligenceLiveActivitiesBundledoes not list the widget yet: without the app group a device build has no container, so it is added in the same commit as the entitlement. The widget’s code sits inIngestionLiveActivityWidget.swiftbecause the extension target lists its files inproject.pbxproj.[evidence_level: code_verified+test_verified (WidgetSnapshotTests), build_verified, measured in the iOS 27 Simulator with the group in a scratch build on 2026-10-15; confidence: medium, not on a device; evidence_source: WidgetSnapshot.swift, IngestionLiveActivityWidget.swift, ContentView.swift, ChatScreen.swift, ThreadSidebarView.swift, MessageBubbleV2.swift, ContainerService+Focus.swift] -
FoundationModelToolRegistry(changed 2026-10-14, 5.7): holds only the toolscreateToolsreturns. Six declared tools that it never returned were removed, and a missing handler logs that the session gets no tools.[evidence_level: build_verified, confidence: high, evidence_source: FoundationModelToolRegistry.swift] -
AnswerUsageTally(added 2026-10-15, 5.7):RAGService.querysets one per answer as a task-local,LLMServiceadds each generation’sGenerationUsage, andfinalizeResponsesaves the total asResponseMetadata.appleUsage.[evidence_level: test_verified (AnswerUsageTallyTests), confidence: high] -
RAGService.passagesFromKnownDocumentsandremovePassages(added 2026-10-15, 5.7): searches (queryInternal,searchDocumentsRaw) leave out a passage whose document is in no library, keeping one the pipeline made itself, andremoveTextOfUnfinishedImportsremoves such passages from Local Only libraries at launch. Detail:Docs/RETRIEVAL_PIPELINE.md, “Passages whose document is in no library”.[evidence_level: test_verified (PassagesFromKnownDocumentsTests), confidence: high](Updated 2026-10-19: Deep Think and Maximum search throughexecuteFullRetrievalPipeline, notsearchDocumentsRaw, and it now checks its result; the retrieval cascade, the keyword retry andsemanticSearchapply it too; the passage list the later steps of a question read leaves such passages out (chunksOfListedDocuments); andenrichImportedDocumentno longer stores an overview or suggested questions for a document deleted while they were written (enrichmentTargetState). Detail in the same section ofDocs/RETRIEVAL_PIPELINE.md.) -
DayOrdinals(added 2026-10-15, 5.7):RAGService.queryInternalreads a day written as an ordinal beside a month (“September 30th”) as its number before anything else uses the question, andexecuteFullRetrievalPipelinedoes the same for Deep Think’s and Maximum’s own searches, because the keyword index keeps “30th” as one word. Details inDocs/RETRIEVAL_PIPELINE.md, “A day written as an ordinal”.[evidence_level: test_verified (DayOrdinalsTests), confidence: high for what the code does] -
The query cache (corrected 2026-10-14, 5.7):
RAGService.queryInternalkeyssemantic_query_cache(SQLiteFullTextService) with the question and a digest of every library’s documents, their passage counts, the embedding model and the app’s version (queryCacheKey), uses a hit only when every document in it is still there (cachedResultsAreCurrent), and no longer looks searches up by similarity. Through 5.6 a question asked again after an import or a deletion got the old passages. Rows no question can reach any more are deleted after the documents are saved and at launch (deleteUnreachableCachedSearches,SQLiteFullTextService.deleteAllCachedQueries; added 2026-10-15). Detail:Docs/RETRIEVAL_PIPELINE.md, “The query cache”.[evidence_level: test_verified (QueryCacheKeyTests, QueryCacheClearingTests), confidence: high, evidence_source: RAGService.swift] -
AnswerCardSnippetIntent(added 2026-10-14, 5.7, app only): theSnippetIntentthe five ask actions return (AskActionRunner.card), whose card shows the question, the answer and a button per document the answer’s evidence list names, up to three, each runningOpenDocumentIntent(AskActionRunner.sourceDocumentIds; the retrieved passages’ documents when there is no evidence list; made from the engine’s lists in memory), for a question asked of a whole library an Ask a Follow-up button runningAskFollowUpIntent, which opens the chat on that library in a new conversation that starts with the question and the card’s answer (AppDestination.continueAnswer), and for a Standard answer from a whole library a Think Deeper button runningThinkDeeperIntent, which opens the chat on that library in Deep Think with the question (AppDestination.ask(_:sendsAtOnce:inDeepThink:libraryId:)); when each is offered isAskActionRunner.offersFollowUpandoffersThinkDeeper, and both intents are in OpenItemIntents.swift, run in the foreground (supportedModes) and are not listed in Shortcuts. It replacedRAGResponseSnippetView.[evidence_level: test_verified (AskControlTests), build_verified; confidence: medium; evidence_source: Services/Agentic/RAGAppIntents.swift] -
ContainerService.move(_:before:)andorderedContainers(added 2026-10-14, 5.7): a library chip dragged inContainerPickerStrip(SwiftUI 27’sreorderable()andreorderContainer(for:)) sets this device’s library order (libraryDisplayOrderinUserDefaults), whichpickableContainersfollows; the stored list keeps creation order, which sync restores and whose first library is the home of documents with no library id.[evidence_level: test_verified (LibraryOrderTests), build_verified; confidence: medium; evidence_source: ContainerService.swift; ContainerPicker.swift] -
AppStateReporting(added 2026-10-14, 5.7, app only, iOS and macOS 27): reports two StateReporting domains, an import running and the answer mode of a question running, from the begin and complete closuresOpenIntelligenceAppsets onIngestionRuntimeBridgeandQueryRuntimeBridge;MetricDiagnosticsenables both domains in itsMetricManagerand names the active states in its log line.[evidence_level: test_verified (AppStateReportingTests), build_verified; confidence: medium; evidence_source: App/AppStateReporting.swift; App/MetricDiagnostics.swift] -
VisualDocumentSearch(added 2026-10-14, 5.7, app only, iOS 26 and macOS 27): the app’s one Visual Intelligence query (VisualDocumentSearchQuery, anIntentValueQueryoverSemanticContentDescriptor) and its “More results” intent (.visualIntelligence.semanticContentSearch). It reads the picture’s text with Vision, adds the system’s labels, and returns at most 100OIDocumentEntity, names first, then keyword-index matches across every library.[evidence_level: test_verified (VisualDocumentSearchTests), build_verified; confidence: medium; evidence_source: Features/Camera/VisualDocumentSearch.swift] -
DeleteDocumentsIntentandDocumentDeletion(added 2026-10-14, 5.7): aDeleteIntentthat asks first and removes throughRAGService.removeDocument, only once the engine’s document list holds every document asked for, because that call works from the engine’s own record of each document; a save leaves out documents recorded as deleted (saveDocumentsToDisk), so another engine cannot write one back. Run in the open app with the app’s own engine, it schedules the removal with undo instead (UndoableIntent,RAGService.scheduleRemoval; corrected 2026-10-15).[evidence_level: test_verified (DocumentDeletionTests), build_verified; confidence: medium; evidence_source: Services/Agentic/DeleteIntents.swift] -
RAGService.scheduleRemoval,undoRemoval,commitRemoval,commitPendingRemovalsandremoveDocumentsLeftPending, withPendingDocumentRemovalandPendingDocumentRemovalLedger(added 2026-10-15, 5.7): a deletion in the app (ModernDocumentCard), or by “Delete Documents” on the app’s own engine (isTheAppsEngine), takes the documents out ofdocumentsat once and runsremoveDocumentsix seconds later unless it is undone, from the library’s Undo bar or the undo manager the screen or the system hands it. Until then nothing is removed; a reload leaves the documents out (applyLoadedDocuments), searches leave their passages out (passagesFromKnownDocuments), Shortcuts and Siri don’t list them (OIDocumentEntityQuery.loadDocumentRecords), Spotlight still finds them, a rebuild skips them, and the ids are kept per run of the app inpending_document_removals.json, so a removal the app did not live to run runs at its next launch. Pending removals also run when the app goes to the background (after the vector flush, then flushed again), and before a library is deleted or emptied and before Clear All, which wait for one already running.[evidence_level: test_verified (PendingDocumentRemovalTests), code_verified and build_verified for the background order, Clear All, the rebuild skip and the action; confidence: medium; not run on a device; evidence_source: Services/RAG/Orchestration/PendingDocumentRemoval.swift; RAGService.swift] -
MenuBarAsk(added 2026-10-14, 5.7, Mac only, app only): theMenuBarExtrainOpenIntelligenceApp, with a field that posts.ask(_:sendsAtOnce: true)and buttons for Add Documents and Search;showMenuBarIteminUserDefaults, shared with Settings, Appearance.[evidence_level: build_verified; confidence: medium; evidence_source: App/MenuBarAsk.swift] -
SiriDonations(added 2026-10-14, 5.7, app only): donates Open Library throughIntentDonationManagerwhen the person picks a library or asks in one; called from the screens, never fromContainerServiceorRAGService.[evidence_level: code_verified, confidence: high, evidence_source: SiriDonations.swift and its three call sites] -
RAGServicelaunch and import figures (changed 2026-10-15, 5.7): an engine started without Apple’s model leaveslastErrorempty, because the Documents screen, its only reader, shows it as “Error Processing Document”; the empty chat’s notice and the mode chip say why the model is unavailable (AppleIntelligenceCopy). An ordinary import’s Words and characters figures are the document’s own counts (ProcessingMetadata), not a sum over its overlapping passages. An import goes to the library its queue item names (addDocument(containerId:)), not the one open when the queue reaches it.[evidence_level: test_verified (LaunchNoticeTests, WordCountTests, ImportTargetLibraryTests), confidence: medium] -
RAGService.enrichImportedDocument,deferEnrichmentandrunDeferredEnrichmentsIfNeeded(added 2026-10-15, 5.7): the overview, tags and suggested questions an import asks Apple’s model for, made after the document is saved, and in the background left on a list that the app works through when it is in front (ContentView’s scene phase, and the import queue’s end). From 5.8 a document also goes on that list while other files are queued (shouldDeferEnrichment), so the queue takes the next file at once; the last or only file is enriched as it lands. Detail inDocs/INGESTION_PIPELINE.md.[evidence_level: test_verified (DeferredEnrichmentTests), confidence: medium] -
RAGService.leadingWithTopRankedandextractRelevantSentences(leadingCandidateWhole:)(added 2026-10-15, 5.7): the answer path’s invariant that the passage the reranker ranks first reaches the model whole, as [S1], ahead of the sentences the extractive path chooses by the question’s words. Detail inDocs/RETRIEVAL_PIPELINE.md.[evidence_level: test_verified (LeadingEvidenceTests), confidence: medium] -
RAGService.extractedValueAnswersQuestionandlookupWords(in:)(added 2026-10-15, 5.7): the checkhighPrecisionLookupOverrideAnswermakes before a valueSpecificationExtractorread from a passage replaces or pre-empts the model’s answer, at the one function all five such places go through: the value’s label, or the sentence of the line that holds it (valueLine), has to share a word with the question’s subject (the question’s words withoutgenericValueWords, withSpecificationExtractor.subjectSynonymsadded). A value that fails is not used and the model answers.[evidence_level: test_verified (ExtractedValueRelevanceTests), confidence: medium; the false-lock rate on real libraries is not measured] -
NumericValueExtractor(added 2026-10-09, 5.7): reads the numbers in a sentence as values (a scale word, thousands separators, a number that is part of a name or code) and says whether a passage states them;isCountedByGatekeeps the gate to the numbers it counted before 5.7. Called byVerificationGateService.runGateCandevaluateClaim, which Standard runs and, from 5.7, Deep Think and Maximum run as a label unless the source-only check replaced or refined the answer, and bySourceOnlyAnswerService(the check Deep Think and Maximum run afterwards for a lookup that is not source-locked). (Corrected 2026-10-20: this said the gates were Standard’s alone.)[evidence_level: code_verified, confidence: exact, evidence_source: RAGService.swift@1e379aa:11214-11262, :18205-18252, :19521-19524 at 1e379aa, v5.6.0 RAGService.swift has no verifyAgenticAnswer][evidence_level: test_verified, confidence: high, evidence_source: NumericSanityGateTests, 2026-10-09; NumericValueExtractor.swift] -
DetectedValueCheck(added 2026-10-15, 5.7): reads amounts of money, dates (written with a year) and measurements in an answer and its passages withdataDetectorMatches, and reports one the passages contradict: the same amount only in other currencies, another day of the same month, the same value only with other units. Gate C fails on one,runGateBmarks the claim Partial, and the source-only check marks it unsupported.[evidence_level: test_verified (DetectedValueCheckTests), measured on macOS 27 for the detector's readings; confidence: medium; evidence_source: Services/RAG/Safety/DetectedValueCheck.swift] -
DomainIsolationServiceand Gate I (changed 2026-10-15, 5.7): keywords count as whole words (normalizepads a lowercased word list), the two-letter abbreviations “um”, “ip”, “po” and “iv” are gone, and the gate engages only when the question scores two or more keywords. Matching inside words had failed right answers about everyday documents (“um” in “number”, “ip” in “trip”).RAGService’s verification event now names the failed gates, andVerificationGatesOverlayViewmarks its step failed with them.[evidence_level: measured for the demo failures, test_verified (DomainIsolationTests); confidence: medium; evidence_source: Services/RAG/Safety/DomainIsolationService.swift; RAGService.swift, the.verificationevent] -
ModelErrorClassifier(added 2026-10-09, 5.7): says what kind of failure a generation error is (context overflow, rate limit, unreadable response, filtered, other) from its type, and from phrases for an unknown type or a passed-along message. Read byAgenticOrchestrator.executeReasoningChainand byRAGService.generateWithFallbackandisContextOverflowError.[evidence_level: test_verified, confidence: high, evidence_source: ModelErrorClassifierTests, 2026-10-09] -
SystemResourceAdvice(added 2026-10-09, 5.7): a thread-safe copy of iOS 27’sUIApplication.systemPrefersReducedResourceUsage, written bySystemStateMonitor(started at launch byOpenIntelligenceApp) and read at the boundaries of the embedding batch loop (EmbeddingService.generateEmbeddings) and of the two reasoning loops inAgenticOrchestrator, which wait between steps while it is set.[evidence_level: test_verified for the helper, build_verified for the readers; confidence: high; evidence_source: SystemResourceAdviceTests; SystemStateMonitor.swift] -
CompletionNotificationServiceandCompletionNotificationPolicy(added 2026-10-09, 5.7, app only): a local notification when an import batch or a question of 20 seconds or more finishes while the app is not in front, off until the Settings switch is turned on. Fed from the two completion closures inOpenIntelligenceApp; a tap is routed throughAppNavigationRequest.[evidence_level: test_verified for the policy, build_verified for the service; confidence: high; evidence_source: CompletionNotificationPolicyTests] -
OpenedFilesSheet(added 2026-10-14, 5.7, app only, Features/Documents/Components): files “Open in” hands over (AppDestination.openedFiles), listed with their kind and size, each read-only in Quick Look, with Add to Library (copies them into the library’s folder, then the usual import review) and Don’t Add (removes the copies), the only ways to close it; the copies wait in the local cache’sOpenedFilesfolder, which iCloud sync never sweeps (ImportedFileStaging.copyForViewingOffMainActor); shown byDocumentLibraryView.showOpenedFiles.[evidence_level: build_verified, confidence: medium; evidence_source: OpenedFilesSheet.swift] -
PastedContentStagingandLibraryPasteButton(added 2026-10-09, 5.7, app only): turn a pasted file, web address or text into files in the imported-documents folder, whichDocumentLibraryView.importOpenedFilesthen takes through the plan check and the import review. The control is a plain button that takes the Documents screen’s own chip as its label and reads the clipboard throughPastedContentStaging.clipboardProviders; it is not the system’sPasteButton, so iOS asks to allow a paste of content copied in another app.[evidence_level: test_verified for the classification, build_verified for the control; confidence: medium; evidence_source: PastedContentStagingTests; PastedContentStaging.swift] -
SemanticChunker(changed 2026-10-09, 5.7):nonisolated, so the fallback chunking ofDocumentProcessor.processDocumentruns on the concurrent pool throughchunkTextOffMainActor, with progress every 25 chunks, a stop on cancellation, and an error atmaxChunks(50,000) in place of a silent stop. Its per-chunk cost no longer grows with the document (three whole-text measurements per chunk removed, the chunks unchanged).createStructureAwareChunksstill calls it on the main actor. Detail and measurements inDocs/INGESTION_PIPELINE.mdsection 3.[evidence_level: test_verified for progress, cancellation, the limit and the offsets, measured for cost and for unchanged output; confidence: high; evidence_source: SemanticChunkerLargeTextTests; BenchmarkRuns/2026-10-09-chunker-large-text] -
RAGService.importLargeTextStreamed,TextPieceReaderandTextStreamingIngestionState(added 2026-10-09, 5.7): a text, Markdown or JSON Lines file over 8 MB is imported a piece of about 2 MB at a time, each piece throughDocumentProcessor.processDocument(textPiece:), with a checkpoint after each piece and the document’s text stored once at the end. JSON Lines records keep their numbers across pieces and short records share a passage. An import that background time stopped continues when the app is in front (RAGService.resumeIngestionStoppedInBackgroundIfNeeded).SemanticChunker’s two chunk loops also drain an autorelease pool for each chunk, which took its peak footprint on 4 million characters from 392 MB to 47 MB. Detail and what is not done:Docs/INGESTION_PIPELINE.md, sections 3 and 5.[evidence_level: test_verified for the parts TextPieceImportTests runs, build_verified for the import loop, measured for the footprint; confidence: medium; evidence_source: RAGService+TextStreaming.swift, TextPieceReader.swift, DocumentProcessor.swift, SemanticChunker.swift]
5. View/ViewModel Map
- SwiftUI Views use
@EnvironmentObjectand@AppStorageheavily for dependency injection and state sharing. EvidenceThreadDebugView: Standalone SwiftUI view for Evidence Threads local store diagnostics (removed in 5.7 on 2026-10-20: nothing referenced it).- User-facing vocabulary is single-sourced in
UI/Components/Glossary.swift. 24 terms, each defined in aplainand atechnicalregister, keyed byGlossaryTermIDwith definitions returned from one exhaustiveswitch, so lookup is compile-time total and returns no optional. Consumers attach a definition rather than restating one:.definedTerm(_:)on any view,GlossaryInfoButtonon list rows, andGlossaryViewas the searchable index. Wired atOnboardingChecklistView(pipeline capsules, metric strip, device chips),HowItWorksView(the four pipeline stages), andSettingsView(the Silicon RAG rows and thePlain Englishentry; the Hardware Envelope rows, the batch pills and the TOPS line went with the 5.8ActiveDeviceCard). The technical register’s expansion state is one sharedAppStoragekey, so it is a per-user preference rather than per-popover state.GlossaryTestsenforces that a plain definition contains no code identifier, model name, framework name or backtick, and pins the two hedges that must not be edited out: TOPS as Apple’s published per-chip figure, looked up rather than measured, and Core ML rather than the app deciding whether the Neural Engine runs.[evidence_level: code_verified+test_verified, confidence: exact, evidence_source: Glossary.swift, GlossaryTests.swift] - Device facts come only from Apple or the hardware (5.8).
AppleDeviceCatalogholds model names from Xcode 27.0’sdevice_traits.db, chips from Apple’s Tech Specs, and Neural Engine TOPS only for the ten chips Apple published a figure for (M1, M1 Ultra, M2, M2 Pro, M2 Max, M2 Ultra, M4);DeviceCapabilityService.npuTopsis nil elsewhere and every screen omits the figure. The chip name on a device is the one Metal reports (resolvedChipName), on a Mac the brand string.ActiveDeviceCardshows model, chip, memory as reported, CPU clusters (hw.perflevelN), the Metal working set and the live thermal state, each with its source, and folds what the app sets (Core ML routes, text-recognition and page concurrency, page DPI, the matrix-search threshold, Deep Think’s stopping confidence).AppleDeviceCatalogTestspins the TOPS list, the chip names and the iPad mappings.[evidence_level: code_verified+documented, confidence: high, evidence_source: AppleDeviceCatalog.swift, ActiveDeviceCard.swift, Apple newsroom and Tech Specs read 2026-11-10] HowItWorksViewnarrates the pipeline in order;GlossaryViewdefines single words out of order. They are deliberately not copies of each other, and each stage in the former links to the latter rather than restating a definition.- Deleting a library goes through one function,
LibraryDeletion.deleteinFeatures/Documents/Library/LibraryDeletion.swift. It removes the container, its documents, chunks, vectors, Spotlight entries and entity-index rows (corrected 2026-10-20: nothing in this build writes the entity index, becauseEntityIndexService.indexChunkandindexChunkshave no callers outside that file, so the rows are only ones an earlier build saved), and its iCloud copy where it has one, and it aborts before touching anything local if the iCloud delete fails, because deleting locally while the shared copy survives means the next sync restores the library.DocumentLibraryViewandContainerSettingsSheetboth call it; the latter defers itsdismiss()until the outcome is.deletedso a refusal has somewhere to report. Two lookalikes are deliberately outside it:deleteConflictedLocalLibrarieshandles libraries iCloud has already dropped and ends with areconfigureIfNeededpass, andOpenIntelligenceEngine.deleteLibrarycallscontainerService.deleteContaineralone, leaving documents behind, because it ispublicand synchronous and cannot adopt an async path without breaking the SDK.[evidence_level: code_verified+build_verified, confidence: exact, evidence_source: LibraryDeletion.swift][evidence_level: grep_verified, confidence: exact, evidence_source: grep -rn "indexChunk(\|indexChunks(" OpenIntelligence OpenIntelligenceTests finds only EntityIndexService.swift:137 and its header comment at :31, and LibraryDeletion.swift:117 removes the rows] - File placement under
OpenIntelligence/Services/is a target decision, not just organisation. TheOpenIntelligenceEngineframework synchronises eighteen folders, includingServices/Infrastructure/Integration, and excludesServices/Infrastructure/Presentationand all ofFeatures/. A new file in an included folder is compiled into the SDK as well, so one that references aPresentationorFeaturestype builds fine in the app and fails only the test build, with a scope error indistinguishable from stale DerivedData.LibraryDeletion.swiftlives underFeatures/for this reason.[evidence_level: code_verified, confidence: exact, evidence_source: project.pbxproj fileSystemSynchronizedGroups per target]
6. Model/Persistence Map
ChatMessage: JSON serialized and stored locally.EvidenceThread(active): Isolated JSON files per thread.DocumentChunk.parentContent(corrected 2026-10-19, 5.7): for a prose passage, the window around it, which holds the passage; for a table, list or key-value passage, its section’s title (DocumentProcessor,parentText: currentSectionTitle). Readers useDocumentChunk.contextText, which keeps the parent only when it holds the passage; through the first 5.7 builds 57 readers tookparentContent ?? contentand read a table’s passage as its title.[evidence_level: measured (iOS 27.0 Simulator store metadata, 2026-10-19), test_verified (TablePassageContextTests), confidence: high, evidence_source: DocumentChunk.swift]
7. Major User Flows
- App Launch & Container Restore
- Library Container Context Switching
- Document Import & Vector Extraction Pipeline
- End-to-End RAG Query & Inference Pipeline
- Maximum Mode & PCC Route Policy Evaluation
- iCloud Workspace Sync & Entitlements
- StoreKit Purchasing & Quota Resolution
- App Intent Siri Shortcuts integration
- Telemetry Trace Generation
8. Background/System Flows
BGTaskSchedulerused for indexing sweeps. An import or a long answer the person started also runs under aBGContinuedProcessingTask(BackgroundTaskService), which asks for the GPU (requiredResources = .gpu) when the system offers it. Since 2026-10-10 (5.7) the app carries the Background GPU Access entitlement,com.apple.developer.background-tasks.continued-processing.gpu, without which the system does not offer it. A background import keeping the GPU has not been observed on a device. On the owner’s iPhone 16 Pro Max (A18 Pro), with the entitlement in the build and the GPU setting on Maximum, the app’s status files from 2026-10-16 and 10-17 recordbackgroundGPUSupported: false(continued_ingestion_status.json,continued_query_status.json, copied from the phone 2026-10-19), so iOS does not offer that phone background GPU and Settings’ line there reads that iOS doesn’t offer it.[evidence_level: code_verified; build_verified for the signed entitlement on a development build, confidence: high for the code, evidence_source: BackgroundTaskService.swift, OpenIntelligence.entitlements]- 5.8, 2026-11-07: an import’s progress moves page by page.
DocumentProcessor.parseSubBatchStructurereports each page as its structure parse returns, and the structured parser’s other reports give pages finished rather than a batch’s last page, soImportProgress.fractionand theBGContinuedProcessingTask’s progress move during a PDF’s extraction;RAGService.updateIngestionItemjournals each whole-percent change (import.progress). On the owner’s iPhone a background import sat at 4% for 71 s and iOS ended the task.[evidence_level: code_verified, test_verified (ExtractionPageProgressTests), confidence: high, evidence_source: DocumentProcessor+StructuredParsing.swift; RAGService+ImportQueue.swift] - 5.8, 2026-11-07: a file’s suggested questions are written from its own passages.
SuggestedQuestionsService.fillMissingQuestionswrites questions for each file with none in the library’s bank, and reads that file’s passages throughRAGService.passagesForSuggestedQuestions(the store’s records for the document, up to 80 spread evenly byevenSampleIndices, plus its overview, read by id), not out ofgetSampleChunks’ library sample of about 50, which on the owner’s iPhone held none usable of a file whose 187 passages are 129 reference list. An interrupted run (cancelled or timed out) saves nothing (isInterruption).[evidence_level: code_verified, confidence: high, evidence_source: RAGService+Storage.swift; SuggestedQuestionsService+Bank.swift; ChatScreen+Actions.swift] - 5.8, 2026-11-04: suggested-question sampling off the main thread, and one card for an on-device answer.
RAGService.getSampleChunksreads the pool from the store and scores it in a detached task (selectSuggestedQuestionSampleand its helpers arenonisolated static); on the owner’s iPhone the scoring on the main thread got the app ended on return (crash report 11:06:53). With the model setting on the device the app submits noBGContinuedProcessingTaskfor an answer (OpenIntelligenceAppbeginUserInitiatedQueryHandler), so iOS shows no card of its own beside the app’s Live Activity; the 30-second background time’s expiry marks the answer paused.[evidence_level: code_verified, confidence: high, evidence_source: RAGService.swift; OpenIntelligenceApp.swift; BackgroundTaskService.swift] - 5.8, 2026-11-04: an answer has the on-device model to itself.
AnswerModelPriority(Services/AIPlatform/AppleFoundationModels) counts answers inRAGService.query;SuggestedQuestionsService,DocumentSummaryService,ContentTaggingService,ClusterLabelService,LibraryVisualizationEngineandImageUnderstandingServicecallwaitWhileAnsweringbefore their model call, outside any timeout, unless the answer itself called them (@TaskLocal isAnswerPath). The model serves one request at a time, so before this an answer queued behind them.[evidence_level: code_verified, confidence: high, evidence_source: AnswerModelPriority.swift and its callers] - 5.8, 2026-11-04: an answer’s task expiry never stops the answer. iOS rate-limits the on-device model for an app in the background (
GenerationError.rateLimited, Apple), so a model retry waits there for the app to come back (RAGService.waitWhileAppIsInBackground) and the answer goes on from the same step when it is opened. The continued task’s expiry ends the task (in front it holds the 30-second background time as well) and the fallback’s expiry ends that time; neither calls the chat’s expiry path. The chat’s expiry path (keepAnswerStoppedByBackgroundExpiry, which ends the answer throughContinuedQueryCoordinator.cancelCurrentQuery()) is no longer reached from either. While an answer runs,ContinuedQueryCoordinatorreports progress every 2 seconds up to 0.915. An app removed from memory while suspended loses the answer; resuming from saved steps is not built.[evidence_level: code_verified, confidence: medium, evidence_source: BackgroundTaskService.swift; RAGService.swift; ChatScreen.swift] NSMetadataQuerybackground updates for iCloud Drive.- The floating iOS Silicon HUD owns a dedicated
UIWindowand derives all frame bounds from that window’s non-optionalUIWindowScene.screen; it does not use the deprecated process-globalUIScreen.main.[evidence_level: build_verified+code_verified, confidence: exact_for_build, evidence_source: MotherboardHUDView.swift and generic iOS 27 simulator build 2026-07-16]
9. Sync Boundaries
- 5.8, 2026-11-07: unreferenced document files are held, not deleted. The local file sweep in
WorkspaceSyncService+LibrarySync.swiftskips everything while an import or rebuild is unfinished, and otherwise moves a file no record or queue item names intoOrphanedDocuments/for 30 days (moveOrphanedDocumentFile,purgeOrphanedDocumentFiles). On 2026-11-03 it deleted the only local copy of a PDF a rebuild was reading.[evidence_level: test_verified (OrphanedDocumentHoldingTests), confidence: high] - iCloud Drive (Ubiquity): Used for sync via
WorkspaceSyncService.swift.[evidence: code_verified, exact, WorkspaceSyncService.swift] - NO CloudKit: No explicit CloudKit database APIs are in use.
[evidence: code_verified, exact, WorkspaceSyncService.swift] - NO SQLite Sync: The
SQLiteFullTextService.swiftis completely local-only.[evidence: code_verified, exact, SQLiteFullTextService.swift] - Conversations and their deletions sync (5.7, 2026-10-14):
EvidenceThreadStoresaves in<Application Support>/OpenIntelligence/EvidenceThreads/, the folderWorkspaceSyncService.synchronizeEvidenceThreadsmerges, and records a deleted conversation’s id indeleted_threads.jsonbeside it; the merge joins that list across devices (mergeDeletedThreads) and removes those conversations on both sides, asdeleted_documents.jsondoes for documents. A conversation is one file and the newest copy wins.[evidence_level: code_verified+test_verified (EvidenceThreadStoreTests), confidence: medium until two devices, evidence_source: EvidenceThreadStore.swift, WorkspaceSyncService.swift] - How sync writes into iCloud (5.7, 2026-10-14): a library’s chat history, transcript and conversation memory are copied only when their bytes differ, and replaced in place (
WorkspaceSyncService.replaceItemIfDifferent) keeping the source’s modification date, so the newest-wins choices read the same dates as before. Through 5.6 each was deleted and copied again on every pass from every device, which is how the owner’s container came to hold 500 conflict copies (”2.json”) in the six per-library file families on 2026-10-14. A library’s vector store goes into iCloud by being written in a replacement folder and having its three files replace the iCloud ones under one coordinated claim ( persistVectorChunksIntoICloud,coordinatedReplaceItems); through 5.6 it was cleared and rewritten in place with no coordination. Each pass logs the folder’s conflict-copy count (conflictCopyCount); the app reads none of those copies and removes none.[evidence_level: test_verified (WorkspaceSyncFileWriteTests), confidence: medium until two devices write at once, evidence_source: WorkspaceSyncService.swift] - 5.8, 2026-11-04: a workspace reload reads off the main thread.
RAGService.reloadWorkspaceDatareadsdocuments_metadata.json(a coordinated read) and the open vector stores’ file signatures (VectorStoreRouter.diskSignature) in a detached task, then applies them on the main actor (applyWorkspaceReload,VectorStoreRouter.clearAll(signatures:)). A newer reload on the same engine supersedes one still reading, and a read during whichdocumentschanged in memory keeps the list in memory (documentsChangeCount), so a read can never undo an edit, a deletion or an import made meanwhile. Before, the whole reload ran on the main thread after every iCloud pass and held it for seconds on the owner’s iPhone.[evidence_level: code_verified, confidence: high, evidence_source: RAGService.swift; VectorStoreRouter.swift] - 5.8, 2026-11-03: one engine per launch.
AppServices.shared(OpenIntelligence/App/AppServices.swift) builds the app’sRAGService,WorkspaceSyncService,ContainerService,EntitlementStore,SettingsStoreandModelResolutionServiceonce, and every window’sContentViewobserves them. Until then each window, and each rebuild of its view, built a set that started its own launch work on the same files.[evidence_level: test_verified (AppServicesTests), confidence: medium] - 5.8, 2026-11-03: a rebuild is shown and kept like an import. A rebuild’s queue items join the Live Activity and ask for
BGContinuedProcessingTasktime (reembedDocuments), a library with a saved rebuild item gets the passages check at the relaunch (restorePersistedIngestionQueueIfNeededcallsevaluateSemanticIndexHealth), since the shared queue file can hold another device’s items, and the import queue skips a rebuild’s items (nextQueuedIngestionItem), since the rebuild works them itself.[evidence_level: build_verified, test_verified (full suite), not yet seen on a device, confidence: medium] - 5.8, 2026-11-03: a rebuild records no deletion. A deletion recorded in
deleted_documents.jsonreaches every device, which wipes that document’s passages (rebuildLocalSearchIndexesFromCanonicalState). A rebuild recorded one for each document it re-imported under a new id, so two devices rebuilt each other’s libraries in turn (the owner’s iPhone and Mac that day). A rebuild now keeps each document’s id, record and file (Docs/INGESTION_PIPELINE.md§5). Passes started by iCloud changes run at most once every 5 s from each ofContentViewand the Documents tab (ObservedChangeThrottle).[evidence_level: test_verified (RebuildKeepsDocumentIdTests, ObservedChangeThrottleTests), confidence: medium] - 5.8, 2026-11-16: the pass runs off the main thread. The project builds with
SWIFT_APPROACHABLE_CONCURRENCY = YES, under which anonisolated asyncfunction runs on its caller’s actor, so everynonisolated asynchelper of the main-actorWorkspaceSyncServiceran on the main thread, file coordination included; iOS killed the owner’s iPhone build 150 in the background for a 10 s coordinated write of the sharedcontainers.json(0x8BADF00D). All 30nonisolated asyncfunctions ofWorkspaceSyncServiceare now@concurrent, andRAGService.saveDocumentsToDiskmakes its coordinated merge ofdocuments_metadata.jsonin a detached task. The main-actor entry points (reconfigureIfNeededand the rest of+Bootstrap) still record state on the main actor between those calls. The 11-03 entry below says the pass read and wrote its lists on the main actor: true then, superseded by this.[evidence_level: test_verified (SyncPassOffMainThreadTests: 1 main-actor turn in 2.16 s before, passes after), confidence: high, evidence_source: WorkspaceSyncService+*.swift; RAGService+Storage.swift] - 5.8, 2026-11-03: the wait before a pass, and orphaned copies. The pass still reads and writes its lists on the main actor. Before it does,
waitUntilSyncFilesAreFreemakes one coordinated read of the six lists off the main thread and gives up after 20 s, so iCloud’s hold on a list no longer freezes the window (it did on the owner’s Mac that day,sample: main thread in_blockOnAccessClaim). It isn’t a lock: iCloud can take a list again in the moment between, and a list iCloud has evicted (“.name.icloud”) isn’t waited for. At the end of each passremoveOrphanedConflictCopiesdeletes iCloud’s numbered copies of a library’s files when the library is in no list and the original, or its placeholder, is gone (497 in the owner’s folder that day). Copies of a current library’s files, and copies beside their original, are kept, soconflictCopyCountcan still be non-zero.[evidence_level: test_verified (SyncFileWaitTests, OrphanedConflictCopyTests), confidence: medium, evidence_source: WorkspaceSyncService.swift] - How the Knowledge Atlas names things, changed 2026-10-10 for 5.7:
AtlasLabeling(app target,Services/Infrastructure/Presentation/) holds the whole rule as pure functions: deterministic k-means over the sampled embeddings for cluster membership, names from the words over-represented in a cluster against the sample, and two-ended axis labels from the lowest and highest tenth of passages on an axis. There is no list of subjects and nothing specific to a language. The map views andLibraryVisualizationEngineboth call it.[evidence: test_verified, AtlasLabelingTests; not yet seen on a device]From 2026-10-20 a name comes from the library’s structure first: each sampled passage carries its document (a short name,shortDocumentName), or its library in All Libraries, and its cleaned section heading (PassageSources,sectionName), and an axis end is named by the document most of its passages come from (with its section, “Juniper Flats Lease: Late Charges”, when that document already names another end), else by its library in All Libraries, else by the heading most of them share, else by its words (sourceName); a cluster the same way, a document of 40% with twice the next being enough. The owner asked for it after an axis read “Air & Fryer”.[evidence_level: test_verified (AtlasLabelingTests), confidence: high for the rules, evidence_source: AtlasLabeling.swift] - Where the Atlas does its work, changed 2026-10-15 for 5.7:
LibraryVisualizationEngine.buildProfilehands plain arrays (vectors, texts, keywords) toanalyzePassages, which runs detached: k-means, the words of each passage, the cluster names and each passage’s content category (ContentCategory.of(terms:keywords:), whole words fromAtlasLabeling.terms(in:), plurals and longer forms listed). The main actor only assemblesLibraryProfile.ProjectionService(PCA, random projection, t-SNE, UMAP) isnonisolatedandSendable, and the three map loaders (AdaptiveVisualizationsViewtwice,Embedding3DViewonce) runproject3Ddetached; each loader checks before drawing that no load for another method or library replaced it. On 6,000 vectors of 512 dimensions, built -O on this Mac, PCA took 227 ms, UMAP 13.4 s and t-SNE 30.8 s, and the substring category search it replaced took 3.5 s for 6,000 passages (BenchmarkRuns/2026-10-15-atlas-main-thread/). Still on the main thread: the axis labels andEmbedding3DView’s word counts, estimated at well under a second each, not timed. A replaced projection still runs to its end.[evidence_level: code_verified for where each step runs, measured for the timings (this Mac, synthetic inputs, not a phone), test_verified (AtlasContentCategoryTests); confidence: high; evidence_source: LibraryVisualizationEngine.swift, ProjectionService.swift, AdaptiveVisualizationsView.swift] - The scene is the default again, 2026-10-20 for 5.7:
AtlasDrawingStyle(@AppStorage("atlasDrawingStyle"),sceneby default, orchart) picks how the card and the full screen draw. Withscene,Embedding3DSceneView(drawsScene: true)drawsSceneViewContainerwith the axis labels and the cluster (in All Libraries, library) names fromAtlasSceneLabels, laid out as through 5.6, with 5.7’s rebuild key (SceneBuildKey); withchart, what follows. The owner asked for the scene back on 2026-10-20. The same day the camera went back to where 5.6 started it, (3.5, 2.5, 6.0), 7.38 from the middle (mapCameraPosition,mapCameraDistance): the 5.7 distance, about 23 (22.9), fitted to hold each axis label’s centre within 70% of the half-width, drew the cloud at a third of its size under labels kept at their 5.6 size. The field of view runs across the narrower side of the view (fitProjection). Axis labels are kept in view another way: each hangs under the scene’s root with an anchor node left on its axis (pinAxisLabels), and every frame, after the map’s turning is applied, the renderer’s delegate puts it on the anchor as drawn or at the nearest edge of the part of the view the bars over it leave clear (keepAxisLabelsInView,axisLabelSpot,AxisLabelInsetsmeasured by the card and the full screen).[evidence_level: code_verified, confidence: high, evidence_source: AdaptiveVisualizationsView.swift, Embedding3DView.swift] - How the Atlas draws its 3D map, changed 2026-10-19 for 5.7: the card (
CompactAtlasSceneView) and the full screen (Fullscreen3DAtlasView) draw throughEmbedding3DSceneView, which gives a caller with no tap handlerAtlasChart3D: a Swift ChartsChart3Dkept square in the middle of its frame, because a 3D chart sizes its cube from its frame’s longer side (probe app on the iOS 27 Simulator, 2026-10-19), with only X, Y and Z on it andAtlasAxisKeybeside or under it naming what each axis runs between. The pose is the view’s state, so a drag and Rotate turn the same pose. A caller with a tap handler, the Embedding Space explorer (EmbeddingSpaceRenderer), keeps the SceneKit scene (SceneViewContainer), becausechartXSelection,chartYSelectionandchartZSelectionon aChart3Dreported nothing for a tap in the same probe; no screen in the app shows that explorer today. The page, the card and the full screen load onAtlasContentKey(the open library and the number of documents in every library once no import runs, recorded when a load finishes, and waited on for 0.8 s when only the count moved, since a re-embed flips the import flag once per document), so an import that ends with the Atlas open shows in it. The card and the full screen keep the chart’s pose themselves, so a reload or a change of layout keeps the angle. All Libraries reads throughRAGService.atlasSamplesForAllLibraries: the embedding space (atlasEmbeddingSpace) with the most passages (atlasGroupChoice), at mostvisualizationPassageLimitpassages across its libraries (atlasShares); every map’s read samples from the passages of listed documents, leaving out a document waiting out its undo seconds (visiblePassageRecords, which the Atlas’s passage count uses too), and drops passages whose vector is missing or of another size (passagesWithVectors).[evidence_level: build_verified, test_verified (AtlasAllLibrariesTests, AtlasLabelSizeTests), measured (robot shots on the iOS 27 Simulator); confidence: medium until seen on a device; evidence_source: Embedding3DView.swift, AdaptiveVisualizationsView.swift, RAGService.swift] - On-device diagnostics and two system model tools, added 2026-10-10 for 5.7:
MetricDiagnostics(app target,OpenIntelligence/App/) writes MetricKit’s hang, launch and termination reports to the pipeline log and tometric_reports.jsonlin the local cache; nothing is sent anywhere.SystemModelToolsinFoundationModelToolRegistry.swiftcan add the system’sOCRToolandSpotlightSearchTool(the app’s own Spotlight index only) to a session’s tools; both are off unless aUserDefaultsswitch is set, andcreateToolsis still the only place a tool reaches a session.[evidence: build_verified; test_verified for the switches and helpers; no MetricKit report received and neither tool called on a device yet] - The keyword index’s term and phrase statistics read a sample, changed 2026-10-10:
SQLiteFullTextService.getTopTermsForContainerandgetKeyPhrasesForContainer(what the Atlas map shows as terms and phrases) read every character of every document and ran inside the index’s actor, so on a library with one 88-million-character document the map never finished and keyword searches waited behind them. They now read a short document whole and eight evenly spaced slices of a long one, about 2,000,000 characters for the library (statisticsText,evenSlices). No table or column changed.[evidence: test_verified, LargeLibraryCostTests; code_verified, SQLiteFullTextService.swift; not seen on a device] - A batch of a large PDF keeps the earlier batches’ page rows, changed 2026-10-14 for 5.7:
SQLiteFullTextService.store(append: true)still clears the document’sdocument_pagesrows, soDocumentProcessor.storeTextreads them first (retrieveAllPages) and stores them again with the batch’s own. Through 5.6 a PDF imported in batches kept the last batch’s pages.SQLiteFullTextService.swiftdid not change. Each page’s number comes from the extractor’s pages with text (DocumentProcessor.numberedPages), not from its place among the pieces, and a batch of one page is numbered too; through 5.6 a blank page shifted every later row.[evidence: test_verified, PageRowsAcrossBatchesTests; not seen on a device] - Spotlight entries are app items, changed 2026-10-14 for 5.7:
SpotlightIndexServiceassociates each library and document entry with itsIndexedEntity, gives documents and passages no expiry, names a passagepassage-<document>-<passage>, removes a deleted document’s passage domain, and rebuilds library and document entries from the record files (reindexFromStoredRecords, with each document’s first 500 characters read again from the full-text store) for the first launch of 5.7, the background task and, on 27,IndexedEntityQuery. Since entries no longer expire,documentsLoaded(called fromRAGService.applyLoadedDocuments) removes the entries of documents that left, a list of document and library identifiers kept inlocalCacheDir()saying which this device knows; the Settings switch’s off removes every entry (indexingSwitched(on:)).[evidence: test_verified, SpotlightItemsTests and AppLinkTests; build_verified; not searched on a device] - Ingestion Checkpoints: Saved under
localCacheDir()/IngestionCheckpoints/to guarantee they are strictly local-only and excluded from iCloud syncing paths.[evidence: code_verified, exact, DocumentProcessor.swift] - Vector store refresh is change-gated, added 2026-08-29:
VectorStoreRouter.clearAll()is called byreloadWorkspaceData()to pick up sync-driven file changes. It compares each container’s on-disk signature (size + modification date acrossBNNSVectorDatabase.binaryFileURLs) and reloads only the stores that actually changed. It never evicts:BNNSVectorDatabaseis memory-mapped, so dropping an instance while a caller holds a reference would permit two live mappings of one file — the reason the method reloads in place. Measured on 2026-08-29, an idle Mac produced 2,848 vector loads in 164 seconds, the same store re-read 288 times, because the refresh was unconditional and its caller fires every 1.68 s. The gate makes the idle case free; a genuine change still reloads immediately. It bounds the symptom only — the 1.68 s trigger is a workspace timer meeting a container whose orphaned state never resolves, and that lives inWorkspaceSyncService.[evidence: measured, exact, pipeline_trace.log 19:45:24-19:48:08 on the maintainer's Mac; VectorStoreRouter.clearAll] - The record that two copies of a store match is kept across launches, changed 2026-10-10:
synchronizeVectorStoreskips a library whose files, documents, aliases and strategy are what they were when a pass last proved the device copy and the iCloud copy identical. That record was in memory only, so each launch decoded and compared both copies of every synced library. It is now a digest inUserDefaults(workspaceSync.vectorStoreSignatureDigests.v2since 2026-11-13;.v1is dropped once so the newest-passages merge,PassageGenerations, reads every library again).VectorStoreRouter.db(for:)also records a store’s disk signature when it creates the store, so the firstclearAll()after launch no longer reads it a second time.[evidence: test_verified for the record's round trip, LargeLibraryCostTests; code_verified; not timed on a device] - A pass skips the vector store of a library with an unfinished import, added 2026-10-10: the
import queue is read before the documents and again before the vector step
(
WorkspaceSyncService.librariesWithUnfinishedImports: an item this device holds whose stage is not complete, cancelled or failed), andsynchronizeVectorStoreis not called for a library named in either reading. An import’s passages are in the store before its document record exists, so the pass used to decode the whole store to conclude nothing (135 reads of one store in one device trace) and, in a library with another document, would write the store back without them. The store syncs on the first pass after the import ends, which still decodes both copies whole.[evidence: test_verified for the rule, WorkspaceSyncImportGuardTests; measured for the reads, device trace 2026-10-10; not seen on a device since] - Benchmark runs stand down from queue merging:
mergeIngestionQueueIfNeededreturns early whileOpenIntelligenceRuntimePaths.areOverridesPinnedis set.localRootthere resolves throughapplicationSupportRoot(), which does not consult the storage override, so every benchmark run merged its fixture documents into the owner’s real ingestion queue; the symptom was a “Resume interrupted upload?” prompt listing fixture files on every launch, which survived being discarded because the next run rewrote it. Fixed at the caller rather than inapplicationSupportRoot()on purpose: that function is also resolved by fourcoordinated*iCloud primitives and byBNNSVectorDatabase, so making it honour the override would silently redirect live iCloud sync into a temporary directory. The pin is only ever engaged byDebugRAGValidationHarness, so this cannot fire in a shipping app.[evidence: code_verified, exact, WorkspaceSyncService.swift mergeIngestionQueueIfNeeded, OpenIntelligenceRuntimePaths.areOverridesPinned] - The library list is written in order, and a library’s embedding fingerprint is also kept on the device, from 5.6:
ContainerService.saveContainersused to start one detached task a save, so an older list could be written after a newer one, andreloadFromDisk(called before everyreloadWorkspaceData()) then replaced the libraries in memory with it. Saves now go through one serial queue. The fingerprint, which says which pipeline wrote this device’s vectors, is recorded inUserDefaultson every save and restored when a list read from disk lacks it and the provider and dimension still match. The sync merge (WorkspaceSyncService.mergeContainer) does not carry the fingerprint and was not changed.[evidence: code_verified for the mechanism, test_verified for the record, measured on one device for the loss it answers (owner's trace log 2026-10-07); not yet re-run on a device] - BNNS Vector Store: Persisted vector database files (
_meta.json,_vectors.bin,_norms.bin) are stored locally. Loading new or empty databases is gated to skip memory-mapping operations on 0-byte vectors files, resolving startup POSIX/Cocoa Code 260 errors.[evidence: code_verified, exact, BNNSVectorDatabase.swift] - BNNS Vector Store, how passages are held (changed 2026-10-12, 5.7; reviewed and corrected 2026-10-13): a load memory-maps
_meta.jsonand walks it once (PassageFileIndex.scan) for a 72-bytePassageSlotper passage: id, document, number, page, level and the byte range of its JSON object. No passage is decoded at load, and a load writes nothing: vectors the metadata does not list are ignored in memory, and fewer vectors than passages loads the store empty with the files left in place.chunk(at:)decodes one passage from its bytes and checks its id against the slot;searchdecodes only its top results.readableChunks()andallChunks()decode every passage on several threads the first time and the store keeps them (everyChunkCache), which is the state every load reached through 5.6, until memory pressure empties them (releaseDecodedPassages). A passage whose bytes do not decode is counted bycount(),passageRecords()andchunkCount(forDocument:), left out bysearch,chunks(forDocument:limit:),chunks(withIDs:)andreadableChunks(), and makesallChunks()throw, because sync pairs that array with the vectors by position. Passages not yet saved sit inpendingChunksand are always the last slots. A save writes the metadata file by copying the bytes of passages already in the file and encoding only the new ones, and streams the vectors the same way; each file goes to a uniquely named file in the system’s replacement directory, is synchronised, and is renamed over the old one, vectors first. A delete or an update saves anything unsaved before it starts, so a delete that is cut off leaves fewer vectors than passages and never the same number in another order.passageRecords(),chunks(forDocument:limit:),chunkCount(forDocument:)andchunks(withIDs:)answer from the slots, and the other stores answer them fromallChunks().similarities(to:forChunkIDs:)(added 2026-10-13) scores the passages with those ids against a vector where their vectors are, the mapped file or the unsaved buffer, and copies none out; the search inside named documents uses it. On iPhone and iPad, when the app goes to the background and after everything is saved, every open store releases the passages it has decoded (VectorStoreRouter.releaseDecodedPassages), and a decode under way at that moment is not kept. The file format is untouched: a 5.6 build decodes a file this code writes. Eleven callers still read every passage’s text (the question path, the library analysis, the pre-import analysis, the audit screen, the index rebuild and lexical recall throughreadableChunks(), the sync merge throughallChunks()), so the decode still happens at least once per launch; it no longer happens inside the load. (2026-11-04, 5.8) A save whose passage records end past the mapped metadata file throwsstoreFailedand leaves the old files in place; on the Mac on 2026-11-03 it trapped instead.[evidence_level: test_verified (VectorStorePassageIndexTests, BNNSVectorDatabasePersistenceTests); measured on the Mac (VectorStoreScaleBenchmarkTests: load 1.97 s to 0.68 to 0.73 s and 276 MB to 10 to 12 MB for 144,247 passages); not run on a device, confidence: high, evidence_source: BNNSVectorDatabase.swift, PassageFileIndex.swift, VectorDatabase.swift] - BNNS Vector Store, what a cut-off save leaves (changed 2026-10-09, 5.7):
saveToDiskwrites new vectors before the metadata that lists them, andloadFromDisktrims a vectors file that holds more whole vectors than the metadata lists. A save ended between the two writes used to leave metadata for more chunks than there were vectors, which the loader answered by deleting the library’s whole store; it now loads as it was before that save. Fewer vectors than the metadata lists still clears the store. The three files’ stored form is unchanged.[evidence_level: test_verified, confidence: high for the cases tested, evidence_source: BNNSVectorDatabasePersistenceTests; BNNSVectorDatabase.swift saveToDisk and loadFromDisk]
10. Routing/PCC Boundaries
5.6, 2026-10-07. A “Just Once” consent grant now ends with the question it was given for in every mode.
RAGService.queryInternalclearstransientConsentGrantsbeforeexecuteAgenticQuery, as it already did for Standard further down. Detail and evidence:Docs/PRIVACY_AND_ROUTING.md, “Evidence minimization and consent”.[evidence_level: code_verified, confidence: high, evidence_source: RAGService.swift, read 2026-10-07]5.7, 2026-10-14. An ask action may come forward to ask for Private Cloud Compute consent (AskActionRunner.foregroundRequest,RAGService.bringAppForwardForConsent), and the planner counts its question as one a person can be asked about. A request from an engine the chat does not show reachesContentViewthroughCloudConsentRelay; one no window shows within 15 s is given up without being remembered. Detail:Docs/PRIVACY_AND_ROUTING.md, “Evidence minimization and consent”.[evidence_level: test_verified for the relay (CloudConsentRelayTests); code_verified for the action's side, confidence: medium until a device run]5.7, 2026-10-21. A call with noModelExecutionPlanruns on the device:FoundationModelRoutePolicy.determineRoutereturns.onDevicewhen no plan is attached. The consent step runs only for a plan that requires it, so before this the planless branch could reach Private Cloud Compute with no sheet and no transmission record (a Standard question to a library with no documents;DocumentSummaryService’s fallback when the on-device model is unavailable, under Hybrid only). Detail:Docs/PRIVACY_AND_ROUTING.md, “The exception: a question to a library with no documents”.[evidence_level: code_verified, test_verified once PlanlessRouteTests runs, not run on a device, confidence: high, evidence_source: FoundationModelRoutePolicy.swift determineRoute]
- Public Model Targets: On-device execution uses
SystemLanguageModel.default. Native PCC usesPrivateCloudComputeLanguageModelon iOS/macOS 27+ only. The app makes no 3B, 20B, Advanced, or server parameter-count claim because the public SDK does not expose those identities. iOS/macOS 26 stays local; it is never labeled simulated PCC.[evidence_level: compile_verified+code_verified, confidence: exact, evidence_source: FoundationModelSessionFactory.swift, LLMModel.swift] - Post-Retrieval Plan: Local retrieval produces
PostRetrievalEvidence;ModelExecutionPlannercombines it with user/privacy/network/foreground constraints, exact-or-labeled-fallback token budgets, signed entitlement, live PCC availability, and quota. Under Hybrid only the calls that write an answer may target PCC. In Deep Think and Maximum the planner runs for each model call: the sessions, research decisions and Maximum’s running answers are held on the device unless the person picked PCC in the model picker, and helper calls always are (Docs/PRIVACY_AND_ROUTING.md, “Fallback and stream integrity”). Verification stays deterministic and local. (Corrected 2026-10-20: this said only the synthesis stage may target PCC.)[evidence_level: code_verified, confidence: exact, evidence_source: RAGService+Agentic.swift:87-132, RAGService+Agentic.swift:214-220, RAGService+Agentic.swift:248][evidence_level: code_verified, confidence: high, evidence_source: ModelExecutionPlanner.swift, RAGService.swift] - Picker Policy vs. Actual Route:
SettingsStore.fmPreferencepersists the user policy independently of runtime notifications. Chat captures Hybrid as post-retrieval choice, On-Device asonDeviceOnly, and PCC ascloudOnly; the picker label always renders that policy.ModelExecutionReceipt.completedTargetdrives a separate per-answer route badge, including planner-time and runtime PCC-to-local fallback.[evidence_level: build_verified+code_verified, confidence: high_pending_ui_runtime_validation, evidence_source: ChatScreen.swift, ModelStatusIndicator.swift, ModelExecutionPlan.swift, LLMService.swift, MessageBubbleV2.swift and generic iOS 27 simulator build 2026-07-16] - Entitlement and Quota:
EntitlementCheckeruses native macOSSecTaskdeclarations, parses the embedded signed provisioning profile for iOS/Catalyst development and ad-hoc builds, and permits only the approved PCC key to proceed to Apple’s documented availability/quota checks when a distribution build omits that profile.LiveFoundationModelCapabilityProvidersnapshots quota/context state, maps unknown future quota cases to fail-closed.unknown, andFoundationModelSessionFactoryrechecks availability and quota immediately before construction. Source enablement and generic arm64 iPhoneOS compilation are complete; signed installation/distribution verification is pending.[evidence_level: build_verified+sdk_verified+user_confirmed, confidence: high_for_source_unverified_for_distribution, evidence_source: EngineSDKCompatibility.swift, FoundationModelCapabilityProvider.swift, FoundationModelSessionFactory.swift, OpenIntelligence.entitlements]An engine with no store, which an action builds while the app is closed, reads the saved plan and document packs for its document check (EntitlementStore.savedDocumentAllowance, 5.7; until then it used the free plan’s limit). - Quota fail-closed, and where it was not:
PCCQuotaState.authorizesCloudExecutionis the single rule deciding whether a quota state permits a cloud attempt;.belowLimitand.approachingLimitdo,.limitReached,.unsupportedand.unknowndo not. BothcanUsePCCandModelExecutionReceipt.nonAuthorizingQuotaStatesderive from it. Before 2026-08-11 they were two hardcoded copies and had diverged: the planner tested only!= .limitReached, so.unknownauthorized an attempt the route gate scores asunauthorizedCloudAttempts. Reachable in production becauseFoundationModelCapabilityProvidermapspcc.quotaUsage.statusthrough an@unknown default.[evidence_level: code_verified+test_verified, confidence: exact, evidence_source: ModelExecutionPlan.swift, RouteEvalMetrics.swift, PCCQuotaAuthorizationTests.swift] - Foreground gate covers macOS:
ModelExecutionPlannerpermits cloud only whenisForegroundInteractive || consentGranted. That input was computed under#if canImport(UIKit)with the#elsebranch hardcodingtrue, so the Mac had no foreground check and a backgrounded Shortcut could reach PCC unattended. macOS now readsNSApplication.shared.isActive; a platform with neither UIKit nor AppKit falls closed.[evidence_level: code_verified+build_verified, confidence: exact, evidence_source: RAGService.swift, ModelExecutionPlanner.swift] - PCC Fallback UI & Subsystem Diagnostics: A dedicated iCloud execution consent fallback panel is integrated in
ContainerSettingsSheet+Sections.swiftusingself.settingsscope visibility. An AI Subsystem Diagnostics card in the library settings displays real-time readiness status of the sentence embedding model, acceleration targets, Rust-backed tokenizer parser, vocabulary metrics, and exact citation byte offsets.[evidence: code_verified, exact, ContainerSettingsSheet+Sections.swift] - Consent and Fallback: Consent is requested only after the minimized envelope is final. Background/App Intent execution with no remembered consent selects the declared local fallback for Hybrid and explicit PCC policy unless the action can come forward, in which case it asks in the app first (5.7); nothing waits on a sheet no window shows. Fallback occurs only before meaningful streaming;
ModelExecutionReceiptpersists intended/attempted/actual/fallback/completed targets.[evidence_level: code_verified, confidence: high, evidence_source: RAGService.swift, AgenticOrchestrator.swift, ModelExecutionReceipt.swift] - Consent Persistence:
cloudConsent.applePCCis the canonical remembered decision and wins over stalepcc.settingcompatibility state. Startup loads/migrates consent but never creates a consent record or opens the sheet; only a finalized post-retrieval transmission record can populatependingCloudConsent.[evidence_level: code_verified+test_verified, confidence: high_pending_physical_device_validation, evidence_source: SettingsStore.swift, RAGService.swift, PCCConsentPreferenceMigrationTests.swift] - GPU Execution Policy:
GPUExecutionProfilemigrates the old numeric preference into four discrete profiles.DeviceCapabilityServiceis the shared policy source for the Core ML embedding model’s preferences, an extra Core Image pass over rendered PDF pages (the raster stays CPU work, andpreprocessImageForOCRprepares every scanned page on its Metal context in every profile), large Metal vector/MMR gates, and background GPU eligibility, whichBackgroundGPUAllowancestates per device for bothBackgroundTaskServiceand Settings. The UI reports policy rather than claiming exact utilization, and from 5.7 the profile’s list in Settings is built from those same rules (GPUExecutionProfile.engagement), so it cannot claim what the code does not do.[evidence_level: code_verified+test_verified, confidence: high_pending_device_thermal_validation, evidence_source: DeviceCapabilityService.swift, SettingsView.swift, RAGEngine.swift, BNNSVectorDatabase.swift, BackgroundTaskService.swift; ExecutionProfileLadderTests, BackgroundGPUAllowanceTests]
DeviceCapabilities.supportsPrivateCloudCompute means “this build can route to PCC” (2026-09-02)
Until 5.1 the flag was set from the operating system alone in RAGService.checkDeviceCapabilities
(“iOS 18.1+ has Apple Intelligence, so it has PCC”), which is true of every device that can run the
app and says nothing about whether the binary contains the routing. Four screens read it as the
latter: HowItWorksView.leavingExplanation, the About capability list, ModelInfoCard (removed in 5.7 on 2026-10-20: nothing referenced it), and the
Settings PCC window row, so every 5.0 and 5.1 build on iOS 26 told users the app would ask before
sending a request, while all twelve #if compiler(>=6.4) sites were compiled out. The flag is now
DeviceCapabilities.pccRoutingCompiledIn && iOSMajor >= 27, where pccRoutingCompiledIn is a
static resolved by the same compiler condition; entitlement and quota stay in
FoundationModelSessionFactory and FoundationModelCapabilityProvider (the route policy’s own check went
with its planless Private Cloud Compute branch on 2026-10-21). The metrics bar footer, the Settings capability list,
the Glossary and the sample guides (SamplePCCCopy) choose their wording on the same static, so one
binary cannot describe two builds.
[evidence_level: code_verified, confidence: high, evidence_source: RAGService.swift DeviceCapabilities.pccRoutingCompiledIn and the four assignments in checkDeviceCapabilities; ci_scripts/ci_post_xcodebuild.sh Gate 1]
5.7, 2026-10-20: a Deep Think or Maximum step on Private Cloud Compute takes its evidence. 13 of the 14 calls into the agentic generation step pass their evidence as rendered text with no chunk list, and the step built its cloud envelope (
CloudEvidenceMinimizer) from that empty list, so on Private Cloud Compute it sent an empty context. It now sends the rendered evidence cut to the plan’s cloud budget (800 to 12,000 characters), and the consent sheet and the transmission record are made from that text. A step or a Standard answer that sends an envelope keeps its passages in the envelope’s order, which its labels number (RAGService.passages(_:inTheOrderOf:)). A request with noModelExecutionPlanis the exceptionDocs/PRIVACY_AND_ROUTING.mdnames.[evidence_level: code_verified, confidence: high for the code paths; not run, because Private Cloud Compute is not reachable from the iOS Simulator]
(5.8, 2026-11-03, development builds only.) LLMService records each model call’s quality mode, where it ran and Apple’s token counts (model.usage); AgenticOrchestrator a Private Cloud Compute step’s context size (agentic.cloudStep), each session’s evidence plan (deepthink.session) and each model failure’s kind and next step (model.failure, also on Standard’s path in RAGService); RAGService the consent outcomes (consent.authorized, .refused, .broughtForward, .grantCleared). [evidence_level: code_verified, confidence: high]
11. Billing/Entitlement Boundaries
- 5.8, 2026-11-03: what the limits count. The document limit counts
RAGService.countedDocumentCount(the engine’s documents, leaving out the guide library’s and any of the app’s guides, which the app identifies throughRAGService.isAppGuide), and the library limitContainerService.countedLibraryCount(leaving out the guide library,ensureGuideLibrary, a device-only library whose id is kept per device). Imports outside onboarding that name the guide library go to the person’s first own library (libraryForOwnFiles). A library’s shown count comes from its listed documents (ContainerService.documentCount,listedDocumentCounts), since iCloud’s merge keeps the larger saved total. Siri’s library entities count document records.QuotaPolicy.swiftandEntitlementStore.swiftare unchanged. Detail inDocs/BILLING_AND_LIMITS.md.[evidence_level: test_verified (GuideLibraryTests, LibraryDocumentCountTests), confidence: high] - UserDefaults:
EntitlementStore.swiftrelies on UserDefaults for limits.[evidence: code_verified, exact, EntitlementStore.swift] - Keychain: Strictly used for API keys, not entitlements.
[evidence: code_verified, exact] - Offer codes (5.7): the plans sheet presents Apple’s redemption sheet (
RedeemCodeEntry.swift). No billing file changed: a redeemed transaction reachesEntitlementStorethrough theTransaction.updateslistener inStoreKitBillingService, and on iOS 27 and macOS 27 the sheet also callsreconcileEntitlementsOnLaunch()two seconds after a redemption Apple handed back.[evidence_level: build_verified, confidence: high, evidence_source: PlanUpgradeSheet.swift managementControls; RedeemCodeEntry.swift; StoreKitBillingService.listenForTransactions]No code has been redeemed with it.
Watched folders (5.8): WatchedFolderService walks a folder a library watches, reads only files whose date or size changed, and hands new ones to RAGService.enqueueDocuments. It removes a document only if a file in that folder imported it and no other file there names it (SeenFile.ownsDocument). importLargePDFStreamed and importLargeTextStreamed now record fileHash, which is how a finished import is tied back to its file. Adding a folder needs Pro or Lifetime. [evidence_level: test_verified, confidence: high, evidence_source: WatchedFolderService.swift, WatchedFolderTests.swift]
Citations (5.8): SourceTextView and SourcePageView show a passage in its document, and SourceLookup reports whether it is there word for word, read from the full-text store. [evidence_level: test_verified, confidence: high, evidence_source: SourceTextView.swift, SourceTextViewTests.swift]
12. App Intents Boundaries
-
Limit Reached: 10 out of 10 available shortcut slots are consumed since 5.7 (9 through 5.6; “Find Passages” took the tenth). An eleventh makes the whole set stop registering with no error, and
AppShortcutsProviderTestsfails the suite at eleven.[evidence_level: test_verified, confidence: exact, evidence_source: AppShortcutsProviderTests, 2026-10-09; RAGAppIntents.swift RAGAppShortcutsProvider] -
App Intents bypass normal UI and directly hit
RAGService. -
5.7, written 2026-10-09 (
RAGAppIntents.swiftwas named by the owner that day). Twenty-two actions in the built metadata. Actions that change or list what the app shows obtain the engine fromIntentSupport.engine(): the presented engine when the app has one (RAGService.activePresentedInstance), a new one only otherwise. The ask actions build an engine of their own for each question, so they cannot cancel an answer the chat is generating. Through 5.6 each action inRAGAppIntents.swiftbuiltRAGService()and every new engine re-pointed that weak reference at itself; the engine’s initializer (RAGService.swift) now registers only when none is registered, andContentViewregisters the app’s. The ask actions shareAskActionRunner: the engine’s default generation settings, anOIAnswerEntityas the returned value, a thrownOIIntentErroron failure, and for the two with a mode menu (OIAnswerModeon “Ask My Documents” and “Ask a Library”) the free plan’s daily Maximum allowance (ShortcutsPlanGate). The three that name a document run in Standard under aRAGQueryScope, and the runner refuses an answer whose passages are not all from those documents. Seventeen of the twenty-two return a value (ReturnsValueon 17 of the 22perform()functions underServices/Agentic, counted 2026-10-12; fifteen before the two image actions did). “Add a Document”, “Scan a Document” (iPhone and iPad only), “Start a Conversation”, “Open Library” and “Open Document” open the app throughAppNavigationRequestand return nothing; “Ask About an Image” and “Search with a Photo” (VisualIntelligenceIntents.swift) return their text as a value and throwOIIntentErroron failure since 2026-10-09 (through 5.6 they returned nothing and reported a failure as a successful result). Items:OIDocumentEntityandOILibraryEntitycarry properties and a document transfers as its file;OIPassageEntityandOIAnswerEntitytransfer as text with their source, and from 2026-10-20 are items the system looks up by id fromHandedOutItems(kept on the device for a day): carried whole (TransientAppEntity), they stopped Shortcuts’ runner when passed to Copy to Clipboard, while a document, looked up by id, went through (iOS 27.0 Simulator, 2026-10-20);OIThreadEntitylists saved conversations. An engine built while the app is closed has no entitlement store:createNewThreadreads the plan from UserDefaults in that case, and the document limit at import still falls back to the free limit.[evidence_level: code_verified, confidence: high, evidence_source: RAGAppIntents.swift, SearchPassagesIntent.swift, AddToLibraryIntent.swift, LibraryIntents.swift, IntentSupport.swift, ScreenAwarenessIntents.swift, VisualIntelligenceIntents.swift, Services/Agentic/Entities/; a grep of Services/Agentic for "RAGService()" on 2026-10-09]None of it has been run from Shortcuts or Siri on a device. -
An action’s question to an empty library (2026-10-19, 5.7): the engine an ask action builds (
asksThroughRelay) never takes the engine’s direct chat, in which Apple’s model answers with nothing from any document; it answers “This library has no documents yet.”reliabilityModeEnabled, which allows that chat, is on by default and shown nowhere in Settings. The chat’s own behaviour is unchanged.[evidence_level: test_verified (ShortcutsActionTests.testAQuestionToAnEmptyLibrarySaysItHasNoDocuments, full run 2026-10-19), confidence: high, evidence_source: RAGService.swift no-documents branch] -
5.8, 2026-11-03: each intent records itself in development builds. The intents in fourteen files (
OpenItemIntents,VisualIntelligenceIntents,ScreenAwarenessIntents,LibraryIntents,SearchPassagesIntent,SearchInAppIntent,LibraryFocusFilterIntent,DeleteIntents,CheckClaimIntent,AddToLibraryIntent,SetAnswerModeIntent,GetSettingsIntent,ExportConversationIntent,VisualDocumentSearch) open aVerificationJournal.Span("intent.<Type>")inperform()and record ok, failed (with the error’s type) or cancelled, with the duration.AppNavigationRequest.postrecords every destination by its case alone (nav.post). Release builds write nothing.RAGAppIntents.swift’s twelve do the same, the owner having named the file on 2026-11-03; its tenAppShortcutentries are unchanged.scripts/phone_evidence.pyreads the journal off a device.[evidence_level: test_verified (VerificationJournalTests), confidence: high] -
5.8, 2026-11-03, later: the journal covers the rows a device check closes.
AddToLibraryIntent’s span ends with what it was given and stored. The entity queries record which query the system ran and how many items had a library and pages (entity.documents,entity.libraries); the answer, document and passage entities record each hand-off (transfer.export).RAGAppIntents.swiftis unchanged: anintent.longRunningspan inAskActionRunner.runLong, amodefield onintent.QueryDocumentsIntentandimport.statusAskedinDocumentImportStatusIntentare written as a patch that waits for the owner to name the file, and the three rules that need them say so. Spans evaluate their fields only when the journal is on.[evidence_level: code_verified, confidence: high]
13. Documentation Cross-Reference
All documentation cross-references have been moved to DOCUMENTATION_CONSISTENCY_AUDIT.md.
14. High-Risk Modification Zones
- PCC routing/consent
- Apple Foundation Models
- iCloud/workspace sync
- StoreKit / Billing
- App Intents/Siri/Shortcuts
15. Evidence Threads Implication Section
- Design B: Saved in
<Application Support>/OpenIntelligence/EvidenceThreads/<containerId>/(OpenIntelligenceRuntimePaths.baseDirectory()), the folder iCloud sync reads, since 5.7. Corrected 2026-10-14: through 5.6 the store saved one level up, in<Application Support>/EvidenceThreads/<containerId>/, which sync never read, so threads stayed on the device that made them; the first store made after the update moves them.[evidence_level: code_verified+test_verified (EvidenceThreadStoreTests), confidence: high for the location; a thread reaching a second device is not yet observed, evidence_source: EvidenceThreadStore.swift, WorkspaceSyncService.swift synchronizeEvidenceThreads] - Integration: Complete. Persistent history is integrated into
RAGService.swiftand presented throughThreadSidebarView.swiftinsideChatScreen.swift. Clearing the conversation (ChatScreen.clearChat) or deleting one inThreadSidebarViewalso drops that library’s last answer from the “Your Library” widget (WidgetSnapshot.forgetAnswer, 5.7), and so does sync removing a conversation deleted on another device (ContentView.refreshSharedWorkspaceIfNeeded).[evidence_level: code_verified+test_verified (WidgetSnapshotTests), confidence: medium, evidence_source: ChatScreen.swift, ThreadSidebarView.swift, ContentView.swift, WidgetSnapshot.swift] - Tour tip (5.8, 2026-11-13): the list’s first conversation carries the tour’s “Swipe to delete” tip (
TourStep.threadSwipe, groupTour.threads), used up by a swipe-delete (Tour.usedin.onDelete).[evidence_level: code_verified, confidence: exact, evidence_source: ThreadSidebarView.swift, TourTips.swift] - Empty list (5.8, 2026-11-16): with no conversation in the open library (
listThreads(for: activeContainerId)empty), the sidebar shows one caption saying what it lists and how to start one, where it showed an empty panel.[evidence_level: code_verified, build_verified, confidence: high] - Constraint: Synchronization is performed bidirectionally on changes via
WorkspaceSyncService.swiftusing coordinated file writes.[evidence: code_verified, exact, WorkspaceSyncService.swift]Resolved in 5.7 (2026-10-14): the store saved in<Application Support>/EvidenceThreads/while sync readslocalRoot/EvidenceThreads/under<Application Support>/OpenIntelligence, so threads never reached iCloud, and a thread save never started a sync pass. The store now saves in the folder sync reads and moves earlier threads there (EvidenceThreadStore), andcoordinatedWriteDataposts.localWorkspaceDidChangefor its saves. Verify on devices: create a conversation in an iCloud library on one device and confirm it appears on a second.[evidence_level: code_verified+test_verified (EvidenceThreadStoreTests), confidence: medium until that two-device check, evidence_source: EvidenceThreadStore.swift, WorkspaceSyncService.swift] - Quota Gating: Thread creation is gated by monetization tier quotas (5 for Free, 20 for Pro, unlimited for Lifetime) via
QuotaPolicy.swift.[evidence: code_verified, exact, QuotaPolicy.swift] - App Intents: Registered
ListEvidenceThreadsIntentandCreateNewEvidenceThreadIntentApp Intents for Siri/Shortcuts, utilizingThreadListSnippetViewsnippets. Resolved in-process on the presentedRAGService.activePresentedInstanceto reload and populate presented UI screens instantly, accepting optionalOILibraryEntityparameter inputs.[evidence: code_verified, exact, RAGAppIntents.swift]
(5.8, 2026-11-03, development builds only.) EvidenceThreadStore records thread.saved (with whether the file was new) and thread.deleted by the thread’s first 8 id characters, the same on both devices. What a sync pass pulled or removed is not recorded: that lives in WorkspaceSyncService.swift, a hard-boundary file. [evidence_level: code_verified, confidence: high]
16. Mermaid Diagrams
High-level Module Graph
graph TD
UI[UI Views] --> VM[ViewModels]
VM --> RAG[RAGService]
VM --> Sync[WorkspaceSyncService]
RAG --> SQLite[SQLiteFullTextService]
RAG --> Vector[BNNSVectorDatabase]
RAG --> LLM[LLMService]
Query Answering Flow
5.6, 2026-10-07: three changes after generation. (1) The answer cleanup in
LLMService(deduplicateProseBlock,collapseFuzzySimilarSentences,collapseRepetitiveTemplates) splits withAnswerSentenceSplitterand returns the text untouched unless it removes a repeat; sentences whose numbers or codes differ are never repeats. (2)VerificationGateService.runGateEpasses on Gate B’s claims when its similarity ratio is the only condition that failed and every claim is supported. (3) The bubble and the response details read the gating string through one classifier,VerificationOutcome, with a Not Checked state; inline citations are linked by chunk id throughCitationLinker. Entries and evidence:CHANGELOG.md, 5.6.[evidence_level: code_verified, confidence: high for what the code does, unverified on device]
5.7, 2026-10-15: the badge reads Fact Check’s claims.
VerificationOutcome.from(gatingDecision:claims:)reads a passing gate outcome against the claims Gate B checked: with none supported it ispartialwhen any claim is partial andnotSupportedotherwise. The bubble, the response details and the rating and plan prompts (ReviewPromptService.isVerified) all read it. Entries and evidence:CHANGELOG.md, 5.7.[evidence_level: test_verified (VerificationOutcomeTests, ReviewPromptServiceTests), confidence: high for what the code does, unverified on device]
5.7, 2026-10-20: labels number the passages an answer keeps, in the order the context reads them. For the Standard path and its needle rescue the sentence extractor (
RAGService.extractRelevantSentencesOffMain,numberByUse) fills each label’s number in after packing, by the order the sources are written in the context (numberedLabels; first by their place among the sources used, then later that night by the order the context reads them), while Deep Think’s windows keep the routed passage’s place, andRAGEngine.assembleContextnumbers the passages it keeps in the order it places them (it now chooses what fits in rank order and only then places those, best first and second best last, and the trace logs which candidates it kept in label order throughRAGService.candidatePlaces); both had numbered by candidate, so a label could open the wrong passage or none. A cloud envelope numbers its evidence by rank, and the Standard answer and Deep Think’s steps now keep its passages in that order (RAGService.passages(_:inTheOrderOf:)).finalizeResponselogs a label past the answer’s passages and leaves the text.CitationLinker, the source-list half ofAnswerShareFormatterandAnswerPreviewlive inServices/RAG/Citations, so the engine target has them: an answer item handed to Shortcuts lists what its labels point at, as Share and Copy do. Entries and evidence:CHANGELOG.md, 5.7;Docs/ai/DECISIONS.md, 2026-10-20.[evidence_level: test_verified (CitationLabelNumberingTests, AnswerShareFormatterTests, OIEntityMappingTests), confidence: high for what the code does, unverified on device]
sequenceDiagram
participant User
participant VM as ViewModel
participant RAG as RAGService
participant LLM as LLMService
User->>VM: Enters Query
VM->>RAG: generateResponse()
RAG->>LLM: execute()
LLM-->>RAG: stream
RAG-->>VM: update
VM-->>User: Output
Document Ingestion Flow
flowchart TD
subgraph RECOVERY["Queue Recovery & Repair Control"]
Q1["Load coordinated queue JSON"] --> Q2["Merge deletion-wins tombstones"]
Q2 --> Q3{"Restorable work remains?"}
Q3 -- "Continue" --> A1
Q3 -- "Stop / Discard" --> Q4["Persist tombstone + suppress auto-repair"]
E1["Metadata exists; vector index empty"] --> E2["Sequential single-flight repair queue"]
E2 --> E3{"Library suppressed?"}
E3 -- "Yes" --> E4["Wait for explicit import or manual rebuild"]
E3 -- "No" --> A1
end
subgraph INGEST["Import-Time Pipeline"]
A1["Import Files"]
SCAN["Predictive Pre-Scan (10 pages)"]
A1 --> SCAN
SCAN --> A2["File Size Check"]
A2 -- "< 10MB" --> A3["Standard Extraction & Parsing, then the whole text (and each page of a multi-page PDF) into SQLite FTS5"]
A3 --> A4["Chunking by word count within sections, tables and topic shifts"]
A4 --> A5["Embed, add the vectors to the library's flat file, then one FTS5 row per passage"]
A2 -- ">= 10MB" --> S1["Stream Batches (15 pages)"]
S1 --> S2["Extract Chunks"]
S2 --> S3["Generate Embeddings"]
S3 --> S4["Store Batch to Vector & DB"]
S4 --> S5{"More Pages?"}
S5 -- "Yes" --> S1
S5 -- "No" --> S6["Finalize Ingestion"]
A2 -- "Text, Markdown or JSON Lines over 8 MB (5.7)" --> T1["Read a piece of about 2 MB of whole lines"]
T1 --> T2["Chunk, embed and store the piece"]
T2 --> T3["Save the checkpoint"]
T3 --> T4{"More pieces?"}
T4 -- "Yes" --> T1
T4 -- "No" --> S6
end
Corrected 2026-10-20: the diagram showed one indexing step after chunking. The document’s whole text (and, for a multi-page PDF, each page) reaches the keyword index before the text is cut, and each passage’s row comes after its vectors are stored. The vectors are kept in arrival order in one flat file per library, rewritten whole at each save, with no index: a search compares the question with every vector. [evidence_level: code_verified, confidence: exact, evidence_source: DocumentProcessor.swift@1e379aa:987, :1008-1009, :1046, RAGService.swift@1e379aa:7894, :7981 at 1e379aa, BNNSVectorDatabase.swift:32-36, :1040-1042, :1108-1120]
Queue tombstones are part of the existing iCloud Drive-coordinated ingestion_queue.json record. Since 2026-11-13 (5.8) the launch restore (restorePersistedIngestionQueueIfNeeded) also writes a tombstone for each item it leaves out for good: a document already imported, a file that is unreachable, and a saved rebuild item once the library’s launch check (evaluateSemanticIndexHealth) has run; only items this device holds the lease on or whose lease has expired. Before that, such items stayed in the shared queue, and WorkspaceSyncService.librariesWithUnfinishedImports counted their libraries as importing, so their vector stores were left unsynced on every pass (59 items on the owner’s devices, the oldest from 2026-10-20). The library check journals sampleMs and recordsMs with index.health. [evidence_level: code_verified, confidence: medium until seen on device] A tombstone removes the matching item before duplicate reconciliation, including when the queue otherwise has no active items. Automatic empty-vector repairs are globally serialized in-process and check persistent per-library device-local suppression before each document-safe stage; explicit user imports and manual rebuilds clear that local suppression. [evidence_level: build_verified, confidence: high_pending_runtime_validation, evidence_source: WorkspaceSyncService.swift, RAGService.swift, IngestionQueueOverlay.swift]
Chat Persistence Flow
sequenceDiagram
participant Chat as ChatMessage
participant Disk as Local Storage
Chat->>Disk: Serialize to JSON array
Sync Boundary Diagram
graph TD
App[OpenIntelligence] -->|NSFileCoordinator| iCloud[iCloud Drive Ubiquity]
App -->|Local Only| SQLite[SQLite DB]
PCC Routing Diagram
flowchart LR
Picker{"Persistent picker policy"}
Picker -->|Hybrid| Hybrid["Post-retrieval route choice"]
Picker -->|On-Device| Local["SystemLanguageModel.default"]
Picker -->|PCC| PCCGate{"Entitlement + consent + network + availability + quota"}
Hybrid --> Planner["ModelExecutionPlanner v2"]
Planner --> Local
Planner --> PCCGate
PCCGate -->|Eligible| PCC["PrivateCloudComputeLanguageModel"]
PCCGate -->|Unavailable| LocalFallback["On-device fallback"]
Local --> Badge["Green On-device badge"]
PCC --> PCCBadge["Blue PCC badge"]
LocalFallback --> FallbackBadge["Amber On-device fallback badge"]
[evidence_level: code_verified, confidence: high_pending_physical_device_validation, evidence_source: ModelExecutionPlanner.swift, LLMService.swift, ModelStatusIndicator.swift, MessageBubbleV2.swift]
graph TD
Request[User Prompt] --> LocalRetrieve[Local retrieval and evidence assembly]
LocalRetrieve --> Planner[ModelExecutionPlanner]
Capability[Signed entitlement + availability + quota + context] --> Planner
Planner -->|On-device| Local[SystemLanguageModel.default]
Planner -->|Insufficient evidence| Abstain[Grounded abstention]
Planner -->|PCC synthesis| Minimize[CloudEvidenceMinimizer]
Minimize --> Consent{Consent valid for final envelope?}
Remembered[Canonical remembered consent; no launch prompt] --> Consent
Consent -->|Yes| Recheck[Immediate quota and availability recheck]
Recheck --> PCC[PrivateCloudComputeLanguageModel]
Consent -->|No or foreground unavailable| LocalFallback[Declared on-device fallback]
PCC --> Verify[Deterministic local verification]
Local --> Verify
LocalFallback --> Verify
Verify --> Receipt[ModelExecutionReceipt]
Evidence Threads Placement Diagram (Implemented — Design B)
graph TD
UI["ThreadSidebarView / ChatScreen"] --> RAG["RAGService"]
RAG -->|"quota gate 5/20/unlimited (QuotaPolicy)"| Store["EvidenceThreadStore"]
Store -->|"coordinated write"| File["Application Support/OpenIntelligence/EvidenceThreads/<containerId>/*.json"]
File <-->|"bidirectional sync (WorkspaceSyncService)"| iCloud["iCloud Drive Ubiquity"]
Resolved 2026-10-14 (5.7): through 5.6 the store wrote one level above the folder WorkspaceSyncService.synchronizeEvidenceThreads reads, so the sync edge above moved nothing; the store now writes <Application Support>/OpenIntelligence/EvidenceThreads/<containerId>/, the folder that edge reads. A conversation reaching a second device is still to be observed. [evidence_level: code_verified+test_verified, confidence: medium, evidence_source: EvidenceThreadStore.swift; WorkspaceSyncService.swift]
Historical note: earlier planning artifacts proposed LocalCache/EvidenceThreads/ with no sync (Phase 1A local-only design). Phase 1B relocated threads to Application Support/EvidenceThreads/<containerId>/ with bidirectional iCloud Drive sync. [evidence: code_verified, exact, Docs/AuditArtifacts/Implementation/phase_1b_1c_1d_post_implementation_verification.md, WorkspaceSyncService.swift]
17. Core AI Embedding Subsystem Boundary
5.8 (2026-11-14): a device does not rebuild a library whose vectors are already the live model’s.
EmbeddingModelRecordis kept per device, so a device with no record rebuilt a library even after another device had rebuilt it and iCloud had brought those vectors: the owner’s iPhone re-embedded five libraries his Mac had finished minutes earlier (phone trace 16:11 to 16:14, each “a model before 5.8”). Before queueing the rebuild,RAGService.storedVectorsAlreadyMatchLiveModelembeds two passages of every document again (StoredVectorModelCheck: stored prefix plus content, passages of 80 to 1,500 characters that fit the model uncut) and compares them with the stored vectors. Every one at cosine 0.95 or more records the model and skips the rebuild; any miss, a document with no testable passage, or a library that translates before embedding rebuilds as before. Journalindex.modelCheckcarries the lowest similarity. Measured in the iOS 27 Simulator with the Core ML model: a fresh import’s vectors 1.000, the same passages under other vectors 0.082. Not measured: vectors written on a Mac and read on an iPhone.[evidence_level: test_verified (StoredVectorModelCheckTests, FiveChecksSimulatorTests.testStoredVectorsFromTheLiveModelAreRecognised_andOtherVectorsAreNot), confidence: high for the rule, the cross-device figure open]5.8 (2026-11-12): the bundled embedder is IBM’s granite-embedding-small-english-r2 on Core ML, and the Core AI copy is retired. MiniLM-L6-v2, in both its Core ML and Core AI copies, was trained on MS MARCO, whose terms allow non-commercial research only (the owner’s rule 1).
EmbeddingModel.mlpackageis now Granite (two fixed-shape functions,len256andlen512; CLS vector and L2 normalisation in the graph; 8-bit linear weights, 48.7 MB; cosine 0.99990 against Hugging Face; built byscripts/build_embedding_model.py), loaded from a fixed path (RerankerModelLocation).CoreAISentenceEmbeddingProvider.isAvailableis false,EmbeddingModel.bundleis an empty placeholder (Package.swiftlists it), andEmbeddingService.forProviderresolves the Core AI id to Core ML, so a Core AI library takes the provider-change branch ofresolveEmbeddingContext(vectors cleared, rebuilt). A Core ML library whose vectors came from another model is told apart byEmbeddingModelRecord(per device) and is rebuilt at once, not flagged: the new model’s query vectors cannot search the old model’s. The check runs inevaluateSemanticIndexHealth, at launch and on a library switch, so the rebuild starts when the library is opened, and it re-embeds the stored passages in place rather than re-importing each file (RAGService.modelChangeRebuildContainerIds); the store is not cleared first, because it holds the only complete copy of the passages’ text. The library open at launch is checked 3 s after launch (observeContainerChanges). Everything below describes the Core AI path as it was through 5.7.[evidence_level: code_verified, confidence: high]
5.8, 2026-11-08, background compute units. A background import without a GPU grant (
IngestionExecutionProfile.continuedProcessingCPUOnly) runs Core ML on the CPU and the Neural Engine (DeviceCapabilityService.backgroundComputeUnits, used bypreferredComputeUnitsandembeddingComputeUnitsDuringIngestion); it was the CPU alone. iOS 27 needscom.apple.developer.background-tasks.continued-processing.inferencefor any Neural Engine use in the background, and the app has it since 2026-11-05. Measured on an M3 Pro, the embedding model at 512 tokens: 12.6 ms CPU only, 7.7 ms CPU and Neural Engine. The GPU stays off in that profile.[evidence_level: code_verified, measured (Mac); confidence: medium: the iPhone background speed is not yet measured]
5.8, 2026-11-08, embedding input. Every import path embeds a passage as
RAGService.passagePrefixwrites it: the document’s[name], then its trusted section path ([A > B]) or section title, then the passage. The normal import (buildEmbeddingInputs), the rebuild (RAGService+Deletion) and both streamed paths (importLargePDFStreamed,importLargeTextStreamed) call it; the streamed paths wrote"<file name>: "with no section. Stored vectors are not changed: a passage gets the new prefix when its file is imported again.[evidence_level: code_verified; confidence: high; retrieval effect not measured]
5.8, 2026-11-04.
EmbeddingService.forProviderhands every Core ML service one provider,EmbeddingService.sharedCoreMLProvider, as the Core AI path already usedCoreAISentenceEmbeddingProvider.shared. It built a newCoreMLSentenceEmbeddingProvideron every call, and each new one loaded the tokenizer and the 43 MiB model again before its first vector; a search callsforProvider, so a Deep Think answer paid about 0.6 s per sub-query for it on the owner’s iPhone (trace 2026-11-04 14:18:32 to 14:18:45, four sub-queries). Same weights and the same vectors outside an import. An import’s ingestion mode now switches the shared provider’s compute units for the import’s length, so a question asked during an import, or a file attached in Chat while the queue imports, embeds on those units, within the cosine of at least 0.99 thatIngestionModeSwitchTestspins between them rather than bit for bit. Imports from the queue run one at a time, andRAGService.addDocumentcounts the imports using each provider (ingestionModeHolders), so ingestion mode is switched back only when the last one ends.[evidence_level: code_verified + measured (the reloads, iPhone trace), confidence: high for the cause; the saving on the device is not yet measured]5.8, 2026-11-05.
CoreMLSentenceEmbeddingProviderisnonisolatedand@unchecked Sendable, with@concurrentembedandembedBatch. Before, the module default put it on the main actor, so tokenizing, pooling and normalizing ran on the main thread one passage at a time. Its shared state is locked:model,loadedComputeUnits,wantedComputeUnitsandisIngestionModeundermodelLock, the tokenizer reference undertokenizerLock; the buffer pool was already an actor.isAvailablechecks the bundle only. Measured in the Simulator, where Core ML runs on the CPU: +49% passages a second, vectors bit-identical (EmbeddingConcurrencyIdentityTests); not yet measured on the Neural Engine or GPU of a device.embedBatchloads the model once before fanning out, so a reload (up to about 2.4 s) does not block every task of the batch onmodelLock. The app also carriescom.apple.developer.background-tasks.continued-processing.inference(2026-11-05), which iOS 27 requires for any Neural Engine use in the background. The App ID needed the Background Inference capability first (BACKGROUND_PROCESSING_INFERENCE), switched on at developer.apple.com, because the App Store Connect API’scapabilityTypecannot set it and Xcode’s automatic signing reported the entitlement as “not found” until it was on.[evidence_level: code_verified + measured (Simulator), confidence: high]5.8, 2026-11-05, retrieval. Deep Think’s merge of its five searches (
AgenticOrchestrator.executeMultiQuerySearch) breaks a tie in the blended score by first appearance across the searches, so the same question keeps the same twenty passages; parent expansion looks up neighbours in the result’s own document.DeepThinkRetrievalGoldenTestsholds both: 703 of 703 single searches identical before and after, 57 of 57 merged searches identical across passes and launches after. The Atlas keeps its library profile for unchanged inputs (LibraryVisualizationEngine.analyzedInputs) and starts a new one only after a running answer ends.[evidence_level: measured, confidence: exact]
5.7, 2026-10-21.
EmbeddingService.generateEmbeddings(for:cacheDirectory:progressHandler:)can keep each batch of 16 vectors in a folder, keyed by a SHA-256 of the provider, the dimension and the batch’s texts;addDocumentpasses the import’s checkpoint folder so a resumed import reads back the batches it already embedded.[evidence_level: code_verified, confidence: medium]
5.7, 2026-10-21.
CoreMLSentenceEmbeddingProvider’s ingestion mode no longer reloads the model where it is switched (RAGService.addDocument, on the main actor, 2.36 s on the owner’s iPhone):enableIngestionModeanddisableIngestionModerecord the wanted compute units andloadedModel()reloads on the next embed, under the same lock, off the main thread.[evidence_level: measured (the hang), test_verified (IngestionModeSwitchTests), confidence: high]
Which copy of the model a new library uses, changed 2026-10-10 for 5.7. iPhone and iPad: the Core ML provider. Mac (macOS 27): the Core AI provider. The choice is
EmbeddingProviderDefaults.preferredSentenceProviderIdinEmbeddingService.swift. Reason: on an iPhone 16 Pro Max the Core AI copy ran at 88 passages a second on the GPU (it fails the Neural Engine’s validation at its attention-mask step) and 5 on the CPU, and the Core ML copy at 116 to 121 on the Neural Engine and 84 to 104 on the CPU alone. A library keeps the copy it was built with; auto-tuning no longer moves a library between the two (EmbeddingProviderDefaults.areCopiesOfOneModel). The statements below about Core AI being the iOS 27 default describe 5.0 to 5.6.[evidence: measured, device benchmark 2026-10-10; test_verified, LargeLibraryCostTests; not yet seen in a real import]
The tokenizer is part of this boundary, and it disagreed with the model for the life of the
feature. Both compiled models declare input shape [1, 512] (scripts/compile_core_ai_model.py
exports torch.ones((1, 512))), and both Swift providers pad to maxSequenceLength 512 themselves.
Until 2026-08-17 the bundled tokenizer.json files capped truncation.max_length at 128 and also
carried "padding": {"strategy": {"Fixed": 128}}.
Three consequences, all from the padding block:
- 55% of library content never reached the embedder. Median chunk measures 273 tokens against a 128 cap; 125 of 139 live chunks were truncated.
DocumentProcessor.countTokensreturned a constant, since it readsencode().countand a padded encode is always the pad width. LoggedmaxTokens=128/430on 3,910 of 3,910 ingestions.- Mean pooling averaged
[PAD]into every vector, because the provider builds its attention mask over already-padded ids.
The boundary rule this establishes: three artifacts must agree, and only one of them is Swift.
The model’s declared input shape, the provider’s maxSequenceLength, and the tokenizer’s
truncation/padding are a single contract. Changing any one without the others is silent. Read the
artifact rather than the code that consumes it: the shape lives in the .mlpackage protobuf, the
tokenizer limits in tokenizer.json, and neither is visible from Swift.
DocumentProcessor.verifyTokenizerCounts now guards the counting half at load. Nothing yet guards
the shape half; a startup comparison of MLModel.modelDescription input shape against the
tokenizer’s limit would close it.
Dimensionality is unaffected by any of the above. Vectors remain 384-wide and
BNNSVectorDatabase’s fixed-stride format is untouched. Sequence length and embedding dimension are
independent, and conflating them would turn a re-embed into a format migration.
- Core AI Integration: Silicon-native zero-copy sentence embeddings are generated via
CoreAISentenceEmbeddingProvider.swiftusing dynamicNDArrayandInferenceFunction.run(inputs:)graph execution on iOS 27 / macOS 27+ Apple Intelligence SDK. Access and selector selection availability are stabilized via shared instance caching and an awaitable readiness gate inContainerSettingsSheet. The exported PyTorch graph output is explicitly bound to “embeddings” incompile_core_ai_model.pyand correctly parsed from the MLFeatureProvider dictionary in Swift.[evidence: code_verified, exact, CoreAISentenceEmbeddingProvider.swift, compile_core_ai_model.py] - The two providers now compute the same thing, and did not until 2026-08-18. Core AI runs
main.mlirband Core ML runs the.mlpackage, both over the sameall-MiniLM-L6-v2weights. Until the mean-pooling re-export, Core AI tookinput_idsonly and returnedlast_hidden_state[:, 0, :]— the CLS position — while Core ML tookattention_maskand mean-pooled in Swift.all-MiniLM-L6-v2is trained for mean pooling, so the two paths produced genuinely different vectors from identical weights, and every retrieval figure measured before 2026-08-17 came from the CLS path without anyone knowing which had run. The export now averages over a real attention mask and the provider passes one;stringson the newmain.mlirblistsinput_ids,attention_maskandembeddings, where the previous artifact listed only the first and last.EmbeddingProviderAgreementTestspins the two providers to cosine > 0.99 on identical text, but skips in the simulator — Core AI resolves no model resource there and setsisModelLoadingFailedbefore attempting a load, so this invariant is device-only and the vectors themselves remain unverified. A benchmark-only override inEmbeddingService.forProvider, keyed on thebenchmarkEmbeddingProvideruser default and set only byDebugRAGValidationHarnessfrom a launch argument, makes the two comparable in one run; it is absent in a shipping app. Paired over 21 comparable cases the swap movedvector r@1from 0.000 to 0.571, 12 better and 0 worse, exact two-sided sign test p = 0.0005.[evidence: measured+code_verified, exact, BenchmarkRuns/coreml-provider vs tokfix via scripts/compare_benchmark_runs.py; EmbeddingService.swift forProvider] - Resource Packaging: The compiled model is bundled as
EmbeddingModel.bundle(a raw folder structure bypassing Xcode’s build-timemlassetcversion-gate checks that otherwise block minimum deployment targets below 27.0) and dynamically loaded at runtime.[evidence: code_verified, exact, Package.swift, CoreAISentenceEmbeddingProvider.swift] - Provider routing is no longer a quality decision. Through 5.6
EmbeddingServicerouted iOS/macOS 27+ to Core AI and older systems to Core ML. From 5.7 the default follows the platform:EmbeddingProviderDefaults.preferredSentenceProviderIdanswers Core AI on macOS 27 and Core ML on iPhone, iPad and older systems, and an existing library keeps the provider it was built with (Docs/ai/DECISIONS.md, 2026-10-10). Until 2026-08-18 that meant the newer OS got the worse path while the correct one was labelled a fallback, so upgrading degraded retrieval. With both providers mean-pooling, the routing chooses a framework rather than a quality tier.[evidence: code_verified, exact, EmbeddingService.swift provider selection; compile_core_ai_model.py] - Adaptive Auto-Tuning: Through 5.6
SettingsStoreandRAGServicerecommended and switched to the Core AI provider on supported hardware, falling back toCoreMLSentenceEmbeddingProvideron older targets. From 5.7 they askEmbeddingProviderDefaults, and auto-tuning never moves an existing library between the Core ML and Core AI copies of the model (EmbeddingProviderDefaults.areCopiesOfOneModel, asked byRAGService.evaluateEmbeddingShift), because a provider change clears a library and embeds it again. Ingestion mode scoping is strictly enforced per-document inRAGService.addDocument()to bypass global configuration conflicts.[evidence: code_verified, exact, SettingsStore.swift, RAGService.swift]
DocumentProcessor & RAGService Streaming
In v4.5, RAGService.importDocument was refactored to support batched extraction via importLargePDFStreamed. DocumentProcessor accepts a pageRange and processes chunks dynamically, bypassing memory limits for large PDF extraction and Vector DB Upserting. Fixed FTS5 index truncation and page offset mapping errors during streaming batch ingestion, ensuring fully searchable large documents.
In v4.5.1, resolved concurrency race conditions and deadlocks on Apple Silicon by introducing thread-safe NSRecursiveLock serialization around CGImage rendering in LayoutAwareExtractor, StructuredDocumentParser, and PageComplexityAnalyzer.
Current state, checked 2026-09-24 at d5cc916: no importDocument function exists in Swift source; the import entry point is RAGService.addDocument(at:context:trackingId:manageProcessingState:), which hands a PDF over 10 MB to importLargePDFStreamed in RAGService+Streaming.swift. No NSRecursiveLock exists in Swift source either; each of the three types above serialises CIImage-to-CGImage rendering with an OSAllocatedUnfairLock named renderLock. Whether the names recorded above were accurate for v4.5 and v4.5.1 is not checked here. [evidence_level: code_verified, confidence: exact, evidence_source: RAGService.swift@d5cc916:5607, :5939-5941; RAGService+Streaming.swift:19; LayoutAwareExtractor.swift:89, :218; StructuredDocumentParser.swift:43, :663; PageComplexityAnalyzer.swift:183, :885; repo-wide grep for importDocument and NSRecursiveLock]
The library’s embedding fingerprint (2026-10-19, 5.7). A library that importLargePDFStreamed or the in-pieces text path (importLargeTextStreamed) fills from empty records its embedding fingerprint at the end, as the whole-file path does; before that its first question read the missing fingerprint as vectors of unknown age and flagged it for a rebuild. [evidence_level: code_verified, measured (iOS 27.0 Simulator trace), confidence: high, evidence_source: RAGService+Streaming.swift, RAGService+TextStreaming.swift]
In v5.1, two macOS-only defects in this boundary were corrected, both found by the first external device run of a large document on a Mac (210 pages, 64 MB, five hours on a fanless MacBook Air).
Page rendering. DocumentProcessor.renderPDFPageAsImage had two non-equivalent platform branches. The AppKit branch used deprecated NSImage.lockFocus plus a tiffRepresentation -> NSBitmapImageRep(data:) round-trip; AppKit/NSImage.h deprecates lockFocus because it “is incompatible with resolution-independent drawing”, sizing its backing store from the display scale factor. Measured at backingScaleFactor 2.0, a page requested at 3060x3960 rastered at 6120x7920 (4.0x the pixels, 16 bits per component) with a 370 MB tiffRepresentation encoded and decoded per page, against 46 MB and no serialization through the CGBitmapContext that replaced it. The UIKit branch was already zero-copy and is unchanged. [evidence: measured, exact, standalone AppKit probe on the maintainer host 2026-08-29; MacOSX27.0.sdk AppKit/NSImage.h:294]
Restore reporting. RAGService.restorePersistedIngestionQueueIfNeeded() set progress = nil when marking an interrupted item .paused, so a document whose checkpoint had preserved 150 of 210 pages displayed nothing. The streaming contract itself was always correct — importLargePDFStreamed skips any batch whose endPage <= lastCompletedPage — but discarding a queue item deletes the checkpoint directory while a restart does not, so the display was steering users toward the only action that destroys the work. Restore now reads the state file through DocumentProcessor.restoredIngestionProgress(for:knownPageCount:). That reader parses no document: this function is @MainActor and runs at launch, so the page total comes from the interrupted run’s persisted metrics.pageCount and the only I/O is one stat and one small JSON read. The streaming contract itself — page batching, db.persist() cadence, incremental FTS5 appends, checkpoint location — is untouched. [evidence: code_verified, exact, RAGService.swift restorePersistedIngestionQueueIfNeeded; DocumentProcessor.swift restoredIngestionProgress; RestoredIngestionProgressTests, 14 cases]
5.7: a paused file stays paused (written 2026-10-16). RAGService.updateIngestionItem drops any stage but an end (complete, failed, cancelled) for an item at .paused. The task pauseIngestionQueue cancels runs on to its next cancellation check, and its late “Storing” update replaced “Paused” on a file whose embedding had just finished, so continuePausedIngestionQueue, which takes the .paused items, left that file with no task until the app was opened again (iOS 27 Simulator, the accessibility audit’s own run, pipeline_trace.log). stopAndDismissIngestionQueue now clears ingestionPausedByPerson, which handleContinuedIngestionExpiration returns on while it is set. [evidence_level: test_verified (PauseIngestionTests: testProgressAfterThePauseLeavesTheFilePaused, testCancellingAPausedFileCancelsIt, testStoppingThePausedQueueClearsThePause), confidence: high for the cause, medium until a pause is repeated on a device]
5.7: a stopped import’s copy of its file goes (written 2026-10-20). stopAndDismissIngestionQueue calls RAGService.removeImportedCopies, which waits for the set-aside task (ingestionTaskUnwinding) to end, then removes each stopped item’s file from ImportedDocuments unless a stored document or a queued item names it, and does nothing before the stored documents have been applied (hasLoadedDocumentsFromDisk). Discarding interrupted items already removed the file; stopping left it, so the same file chosen again was copied as “-2”. [evidence_level: test_verified (PauseIngestionTests.testStoppingRemovesTheCopyOfAStoppedFileAndKeepsADocumentsFile), confidence: high, evidence_source: Services/RAG/Orchestration/RAGService.swift]
Known remaining macOS gap. (Corrected 2026-11-04: fixed for 5.7. The #else branch draws the page into a Core Graphics bitmap context at 2x, so the Vision refinement runs on the Mac. [evidence_level: code_verified, confidence: exact, evidence_source: PageComplexityAnalyzer.swift:1056-1099] What follows describes 5.6.) PageComplexityAnalyzer.renderPageForAnalysis returned nil on macOS (#else return nil), and both production call sites reach it via analyzeBatch, which passes no pageImage. The Vision refinement pass in the complexity analyzer therefore never runs on macOS and isMixedModeScanned is permanently false there. Vision merges with max(...), so macOS scores pages as less visual than iOS would, never more. Tracked in the roadmap as a classification-accuracy defect, not scheduled into v5.1. [evidence: code_verified, exact, PageComplexityAnalyzer.swift:1045-1072 and :294-307]
5.7 (written 2026-10-09). EmbeddingService.generateEmbeddings waits 120 ms between its batches of 16 while iOS 27 reports systemPrefersReducedResourceUsage (SystemResourceAdvice). No provider changed, and the wait is zero when the flag is clear, on iOS 26 and on the Mac. [evidence_level: build_verified, confidence: high, evidence_source: EmbeddingService.swift generateEmbeddings; SystemResourceAdviceTests for the wait itself]
5.7: the Core AI model is prepared after launch when the system’s cache has no entry for it (written 2026-10-09). EmbeddingModelWarmup.scheduleAfterLaunch, called from OpenIntelligenceApp, waits four seconds, then on iOS 27 and macOS 27 asks AIModelCache.default whether it holds the bundled model and, only when it does not, calls AIModel.specialize(contentsOf:) at utility priority and logs how long that took. It skips the work while SystemResourceAdvice says the system wants less. The provider, a behaviour-critical file, is not edited: it still loads on first use, and finds the entry made here. [evidence_level: build_verified for the Mac and device SDKs, confidence: medium, evidence_source: EmbeddingModelWarmup.swift; the CoreAIDelegates interface in the Xcode 27.0 SDK]
Measured on a Mac (macOS 27.0) on 2026-10-09 with a command-line probe on the same 86 MB bundle: the first AIModel(contentsOf:) took 0.49 s and left an entry in the cache, a second process loaded in under 0.01 s, and so did a third that reached the model through a link with another name, so the cache follows the model and not the link’s address. [evidence_level: measured, confidence: medium, evidence_source: BenchmarkRuns/2026-10-09-session-cache-probe/results.txt and caiprobe.swift (local)] Not measured: an iPhone, where the first preparation is the cost this is meant to move, and the load after a system update. The new log line is how a device shows it.
The X-Ray (2026-10-19). EmbeddingService lights the chip its provider runs on through HardwareActivityType.embeddingActivity(providerId:): the Neural Engine for Core ML, the GPU for Core AI, the CPU for Core ML in the Simulator or a background import without the GPU and for NaturalLanguage; until then every embedding lit the Neural Engine. [evidence_level: code_verified, confidence: high, evidence_source: HardwareTelemetryState.swift, EmbeddingService.swift]
Where the provider names reach a person (2026-10-18). Library Settings named a Core AI library “Apple Natural Language” (ContainerSettingsSheet.friendlyProviderName had no Core AI case), About showed its raw id, the 384D option said “ANE accelerated” for both copies, and AdaptiveEmbeddingOptimizer’s rationale gave NLContextualEmbedding a “15-25% accuracy boost” no run in the repository measured. Each now names the provider and where it runs: Core ML plans MiniLM onto the Neural Engine (150 of 161 operations) and Core AI runs it on the GPU (BenchmarkRuns/2026-10-18-compute-plan, M3 Pro). The Atlas’s embedding view reads the library’s embeddingDim where it passed a fixed 512. [evidence_level: code_verified, plus measured for the plan on one M3 Pro, confidence: high, evidence_source: ContainerSettingsSheet.swift, AboutView.swift, AdaptiveEmbeddingOptimizer.swift, AdaptiveVisualizationsView.swift]
(5.8, 2026-11-03, development builds only.) EmbeddingService.generateEmbeddings records one embed.batch per call (the provider, passages, passages a second, whether the app was in the background), never per passage; EmbeddingModelWarmup records embedding.warmup (prepared, already prepared, or failed with the error’s type). [evidence_level: code_verified, confidence: high]
(2026-11-12, development builds only.) The Core ML embedding model’s load records embedding.load (milliseconds, compute units, newInstall, fastPrediction, or failed with the error’s type), and reranker.load carries newInstall and fastPrediction too: newInstall is VerificationJournal.firstLaunchOfThisInstall, true on the first read after the bundle path or the executable’s date changed. MainThreadWatchdog counts only time in front on iOS and iPadOS (the app’s background, foreground and active notifications): a ping across a change is dropped, so a suspension is no longer recorded as a stall. The embedding model still loads on first use. [evidence_level: code_verified, not yet built, confidence: medium]
18. RepoOS Agent-Workflow Boundary
- Workspace skill:
.codex/skills/route-openintelligence-work/SKILL.mddefines the mandatory Codex workflow for this repository and points to current canonical artifacts rather than embedding a second architecture copy.[evidence: code_verified, exact, .codex/skills/route-openintelligence-work/SKILL.md] - Deterministic routing:
repoos_router.pyscores task wording and changed paths againstDocs/AuditArtifacts/RepoOS/change_impact_matrix.csv, reports the selected route, hard boundaries, required evidence, tests, documentation, implementation gate, Notion relevance, and artifact-derived active release, and stops on an unmapped task. Durable implementations receive an effective documentation union that includesCHANGELOG.md[Unreleased], the active-version section inDocs/RELEASE_NOTES.md, and the full rule 14 set.[evidence: code_verified, exact, .codex/skills/route-openintelligence-work/scripts/repoos_router.py] - Runtime isolation: The RepoOS skill, scripts, and agent rules are developer-workspace tooling; they do not compile into or execute inside the OpenIntelligence Apple application.
[evidence: code_verified, exact, change_impact_matrix.csv repoos_workspace_automation allowed and forbidden paths]
19. Retrieval Measurement Boundary
The subsystem that measures retrieval, kept separate here because it is the only part of the project whose output is evidence rather than behaviour, and because it was absent from this Atlas until 2026-08-13.
- Capture:
RetrievalTraceCollectorrecords the rank-ordered output of each pipeline stage (vector,lexical,fusion,boosted,candidates,rerank,final). It deliberately does not deduplicate, because deduplicating would hide the ordering defects that ranking metrics exist to detect.[evidence: code_verified, exact, RetrievalTraceCollector.swift] - Scoring:
RetrievalStageEvaluator.scoreis the single metric implementation. Recall, MRR and nDCG use a credited relevance vector in which each ground-truth document earns credit once, at its first matching chunk; precision uses the raw per-chunk vector. Using one vector for both is the defect that let nDCG@5 report 2.131 on a metric defined over [0, 1].[evidence: code_verified, exact, RetrievalStageMetrics.swift:222, :269] - Transport:
DebugRAGValidationHarness.stageMetricsLinesemitsSTAGE METRICS(the Swift-computed scores) andSTAGE SOURCES(the ranked identities they were computed from), plusExpectedSourcesand the resolvedExpectedSourceIds.run_quality_matrix.pytransports the metrics rather than recomputing them, so exactly one metric implementation exists in the project.[evidence: code_verified, exact, DebugRAGValidationHarness.swift, run_quality_matrix.py parse_stage_metrics] - Identity is the load-bearing part.
STAGE SOURCEScarries<chunkId>#<documentId>#<name>. Chunk identity is required becauseRAGEngine.reciprocalRankFusionkeys onchunk.id; document identity is required because relevance is judged per document. Emitting only the display name left the five pre-rerank stages recording(unnamed), sincesourceDocumentis attached byRAGServiceafter hybrid search returns, which made those stages unverifiable by hand while the metrics computed from them stayed correct.[evidence: code_verified, exact, DebugRAGValidationHarness.swift stageMetricsLines; RAGEngine.swift:1003-1029] - Equal scores have one order (5.7, added 2026-10-17). Eight score sorts had no tie-break, so passages with equal
scores kept the order they arrived in: the keyword boost, the structure boost and the scoped search in
HybridSearchService, and the heuristic rerank, the brute-force vector search,reciprocalRankFusionand both cross-encoder sorts inRAGEngine. They now break ties byHybridSearchService.byScoreThenIdand, inRAGEngine, byHybridSearchService.stableTieBreakKey(document name, then place in it, then the document’s id, because vector hits carry no name at these stages and keyword-only hits are “Unknown”). One known source of the run-to-run difference this section measures is gone; whether two runs of one build now agree is not measured, and a greedy A/A pair is what would show it.[evidence_level: test_verified (HybridSearchServiceTests, named and unnamed passages), confidence: medium, evidence_source: HybridSearchService.swift, RAGEngine.swift; Docs/RETRIEVAL_PIPELINE.md item 20] - Offline replay:
scripts/sweep_fusion_weight.pyreconstructs weighted RRF from the two arms’ recorded rank orders for any weight, so a fusion-weight question costs seconds rather than a 4.7-hour pipeline execution. It calibrates against the app’s own recordedfusionstage before emitting anything and refuses to print a curve it cannot verify.[evidence: code_verified, exact, sweep_fusion_weight.py; self-test run 2026-08-13] - Boundary: this subsystem is developer tooling on the measurement side, but
RetrievalTraceCollectorandRetrievalStageMetricscompile into the app.RAGEvalRunnerhas zero call sites repo-wide, so the in-app half of evaluation cannot currently be invoked; every measurement goes throughrun_quality_matrix.pydrivingDebugRAGValidationHarness.[evidence: code_verified, exact, repo-wide grep for RAGEvalRunner]
Graph packing and the window (2026-10-19). RAGService.graphPackingTokenBudget(windowTokens:) sizes graph packing to three quarters of the window the device reports (at most 6,000), where it was 6,000 everywhere and a 4,096-token iPhone cut about half of each pack by document position. The answer change on such a device is unmeasured; Docs/RETRIEVAL_PIPELINE.md has the detail. [evidence_level: code_verified, test_verified for the arithmetic, confidence: medium]
20. Agentic Execution Boundary, as built
Recorded 2026-08-14. The three quality modes are a deliberate compute ladder and the boundary between them is by design; what this section records is what happens inside the two modes that are supposed to be agentic.
-
Standard is single-shot on purpose, and that is correct. One retrieval pass, chunks packed into a character budget, one answer generation,
Agentic: NO. No model decides to search again and no tool is attached once context is assembled. Code rules can still search again inside that pass: a wider search when the first looks weak, a keyword retry when the top score is under 0.45, a BM25 pass for “list all” questions and a corrective lexical or page search, each triggered by its own rule. Besides the answer it can make a citation retry, one repair call, continuation passes when an answer stops early, and, for a lookup whose gates failed, the source-only check’s two on-device calls. It is the fast, cheap tier and it is not supposed to reach for tools or let a model decide to retrieve again. (Corrected 2026-10-20: this said “one retrieval” and “one generation”.) Since 5.8 the source-only check’s two calls are skipped, in every mode, where the check could only keep the answer: below the 85% coverage floor thatSourceOnlyAnswerService.candidateCoverageBeforeModelworks out with no model call, for a question that is not a precise-value or state question (RAGService.sourceOnlyVerdict).[evidence_level: code_verified, confidence: exact, evidence_source: RAGService.swift@1e379aa:13135-13328, :14098-14182, :14636-14755, :14769-14775, :16289-16374, :16868-16876 at 1e379aa, LLMService.swift@1e379aa:1149-1162, SourceOnlyAnswerService.swift:364-442]Do not read the items below as an argument for making it agentic.[evidence: code_verified, exact, device trace 2026-08-14 message D74F98E4; RAGService useAgentic gate] -
Deep Think and Maximum are where the agentic loop is supposed to fire. The rest of this section is about those two modes only.
-
A retrieved table summary brings its table, in every mode (5.8, 2026-11-07).
RAGService.withTablesForSummariesreplaces atableSemanticcandidate with itstableStructuralsiblings in Standard’s context candidates and in every Deep Think and Maximum search result (RAGService+ToolHandler.swift). Details inDocs/RETRIEVAL_PIPELINE.md.[evidence_level: test_verified, confidence: high] -
Every mode checks the answer answers the question (5.8, 2026-11-07).
AnswerResponsivenessJudge(on-device, guided generation) judges the answer full, partial or none;RAGService.ensureAnswerRespondsrewrites a Standard answer once when it is not full, an extracted value judged none neither replaces an answer nor skips Deep Think, and every mode appendsanswers:<verdict>to the gating string thatVerificationOutcomereads. Details inDocs/RETRIEVAL_PIPELINE.md, “An answer has to answer its question”.[evidence_level: test_verified, measured (Mac probe), confidence: medium] -
New Chat survives a relaunch (5.8, 2026-11-10).
RAGService.createNewThreadkeeps the new conversation’s id in this device’s defaults (unsavedNewThreadKey) until the conversation has a message, another is opened (loadThread) or the history is cleared;chatHistory(for:)andpreloadChatHistory(for:)open it instead of the most recent saved conversation (unsavedNewThread). It also deletes the library’s saved model transcript, whichTranscriptPersistenceServicekeeps per library, not per conversation.[evidence_level: code_verified, test_verified (ReleaseFinishTests, helper only), confidence: medium; not yet seen on a device] -
The 5.8 finishing fixes (2026-11-10). Quotes only makes no model call (
RAGService.quotesOnlySelected,quotesOnlyResponse; detail inDocs/PRIVACY_AND_ROUTING.md). Deep Think waits before an on-device model call while the app is in the background (waitBeforeModelCallWhileInBackground), andPendingAnswerStorelets Chat ask a lost question again once at launch.VectorStoreRouter.persistentStore(for:)hands back a library’s live store instead of opening a second one on its files. OCR renders and reads off the main actor (DocumentProcessor.recognizeText), and a table’s spanning title becomes its caption (StructuredDocumentParser.liftingSpanningTitle; detail inDocs/INGESTION_PIPELINE.md). Deep Think’s panel counts the running answer and marks skipped steps (VerificationGatesOverlayView.saysSkipped).[evidence_level: code_verified, confidence: medium; none yet observed on a device] -
The reranker’s first pick leads, and every rule after it was measured (5.8, 2026-11-09/10). IBM Granite reranker r2 replaced TinyBERT in
RAGEngine.rerankWithCrossEncoder. Side searches (cross-references, Standard’s spec sniper) go behind the top passage (RAGService.insertingBehindTopRanked) and the sniper’s scores stop at 0.89; stored tables are exempt from most contents-page patterns (RAGEngine.isStoredTable); an answer with no letters is rewritten or replaced bynotFoundAnswer(ensureAnswerResponds,isDegenerateAnswer);isOrphanListMarkerneeds the period or bracket. Deep Think’s spec sniper was removed after the audit measured it hurting on tables, and its lost-in-the-middle step now sorts by score first (RAGEngine.applyLostInMiddleReordering).RetrievalAblationswitches each rule off in development builds;AgenticOrchestrator.executeMultiQuerySearchreads it for the blend weights. Record:BenchmarkRuns/2026-11-10-rule-audit/README.md; detail inDocs/RETRIEVAL_PIPELINE.md, “Every rule after the reranker, measured”.[evidence_level: test_verified (AnswerFloorTests), measured (Simulator benchmark), confidence: medium] -
A results table keeps its place, and a statistical value is a value question (5.8, 2026-11-10).
RAGEngine.computeTOCPenaltyreturns 0 for a passage with two or more estimates written with their interval (estimatesWithInterval, “4.60 (3.99-5.29)”), so a results table stored flattened as a paragraph is not docked as a contents page;RAGService.namesAStatisticalValuemakes a question naming a ratio, rate, percentage, odds, p-value, interval, mean, median or similar a value question, soshouldUseContextualDefinitionLookupModeno longer prefers prose over tables for it. When penalties move the reranker’s first pick, the trace names each penalty and its size, and every lookup logs its definition-lookup decision with the four tests behind it. Deep Think’s synthesis treats astreamCutOffresponse as unfinished (AgenticOrchestrator+ReasoningChain,SynthesisCutOff). Not yet measured on the benchmark sets.[evidence_level: code_verified, test_verified, confidence: medium] -
The reranker’s setup card waits 3 seconds (5.8, 2026-11-10).
RerankerSetupStatus.showAfterSecondsis 3 (was 1): on the owner’s iPhone a load from the Neural Engine’s compiled cache took 0.46 s and 1.52 s, and a first load after an install 20.8 to 59.7 s (journalreranker.load, eight launches). The cache is per installed binary, so each development build compiles again and a release user sees the card once per update. (Corrected 2026-11-12: Core ML keys the compiled form by the model’s location, not the binary; the phone compiled again on most launches with no install between, about 30 loads of 20 to 130 s, and kept 202 copies, 1.47 GB. The model now loads from one fixed path,RerankerModelLocation, so the form is found again; whether that ends the per-launch compile on the phone is checked by relaunching it.) The first launch of each app version clears Core ML’s compiled copies (ModelCompileCache, from the app’s initializer inOpenIntelligenceApp.swift, before any model loads), since a new version recompiles once regardless.RerankerWarmupholds iOS background time around the load (RerankerSetupBackgroundTime, about 30 s, journalreranker.backgroundTimeExpiredwhen taken back) and shows setup in the Dynamic Island and on the Lock Screen (SearchSetupLiveActivity, the answer’s Live Activity withisSetup, started as the app leaves the front, ended when it returns); a launch cannot start a continued-processing task, which Apple allows only from a person’s action. The X-Ray legend fades aside while the card shows (FloatingLegendWindowManager.isSetupCardShown).[evidence_level: measured (device journal), code_verified, confidence: medium] -
Fact Check in Deep Think and Maximum (5.8, 2026-11-07). After the displayed text is fixed,
RAGService.factCheckedAgenticAnswerchecks each claim the structured answer lists withVerificationGateService.claimVerdicts(Gate B’s per-claim check) andStructuredAnswer.withClaimVerdictsfills in only the verdicts; until then every claim read Not Checked.[evidence_level: test_verified, confidence: high, evidence_source: AgenticFactCheckTests] -
The sub-searches run partly in parallel (5.8, 2026-11-07).
AgenticOrchestrator.executeMultiQuerySearchruns the firstexecuteFullRetrievalPipelinecall alone (it builds the library vocabulary when none is cached), then the rest at most two at once in a throwing task group, and merges their results in query order, so the fusion is unchanged (DeepThinkRetrievalGoldenTests: 57 of 57 multi-query searches identical before and after). Title routing and the semantic-intent check passskipContinuation: true.[evidence_level: test_verified (search), code_verified (continuation), confidence: high] -
Only the final answer streams (5.4). Every model call an agentic run makes streams through the task-local
LLMStreamingContext.handler, and until 5.4 the chat passed none in these modes, so the answer appeared whole when the run ended.executenow clears that handler for the run and parks the chat’s infinalAnswerHandler; four final-answer calls (reasoning-chain synthesis for Deep Think, core and exhaustive synthesis for Maximum, direct synthesis) stream throughanswerHandler. The no-retrieval direct answer does not, because a failed self-critique replaces it with a stage that cannot be finished early. Stages that can replace streamed text are finishable and run with both handlers cleared, so Stop keeps the text and nothing they generate streams. Intermediate calls stay silent by construction, not by convention.[evidence: code_verified, high] -
The reasoning chain inside them is not agentic.
executeReasoningChainbuilds every session’s context upfront, in a loop that completes before session 1 runs, as fixed windows over a single retrieval. Those windows were 50% overlapping until 2026-08-14 and are disjoint now: at a 3500 character session budget the overlap spent roughly four of eight sessions re-reading. From 5.6 a window is sized in tokens against the window the device reports and read as whole chunks when the SDK can count them (SessionEvidencePlan, iOS and macOS 26.4 on). The budget leaves room for the answer, the question, the earlier findings and the prompt’s wording and stops at 3,200 tokens of evidence; a 4,096 window keeps four chunks a window and an 8,192 window reads up to seven. A window whose chunks do not fit, and any session that may run on Private Cloud Compute, keeps the character-sized path through sentence extraction, and the chain never plans more windows than before. Maximum’s own loop is unchanged.[evidence: test_verified for the arithmetic, code_verified for the loop, not run on a device]The final step reads the cited passages (5.8, 2026-11-12). Deep Think’s synthesis used to read only the sessions’ notes, cut at 3,000 characters in pass order, so later passes were dropped and no passage text reached it.ChainSynthesisEvidence(inSessionEvidencePlan.swift) now ranks the passages the notes cite by their[S#]labels (global positions in the routed pool), counts each exactly, and gives the final step as many as fit with the fitted notes: 1,890 tokens on a 4,096 window, the 3,200-token reading ceiling on 8,192. The notes-only prompt stays the fallback, and every fallback is journaled (deepthink.synthesisEvidence). Maximum is unchanged.[evidence: test_verified for the helpers, code_verified for the call, not run on a device]Per device (2026-10-18). In Deep Think the chain runs one session per distinct window of its passages and stops at 8 sessions at most on every device (AgenticPolicyService.maxSessionsForMode,min(8, sessionCount + 4)), so a 20-passage pool at four passages a window gives about 5. In Maximum, when the first search grades good, the same chain runs with the unlimited preset, whose ceiling is 50, over windows of the same pool. (Corrected 2026-10-20: this said the chain stops at 8 sessions on every device, in both modes.) WhatDeviceCapabilityService.optimizedAgenticConfigchanges by device is the confidence the run aims for, by tier (85% on.baseline, the A17 Pro; 90% on.enhanced, A18 and M1-family Macs; 92% on.advanced; 95% on.ultraAdvanced), the step budget (maxSteps5, 8, 10, and 12 to 32 by memory on the top tier), which picks the chain’s starting length (.standard, 4 sessions, below 8 steps;.deep, 5, from 8) and caps sub-queries atmaxSteps - 2, and the token budget (maxTotalTokens: 20,000, 32,000, 40,000, and 56,000 to 128,000 by memory), which only the decomposed pipeline and recursive research read, never the chain or Maximum’s loop. Settings, the thinking stream’s planning line (“up to N steps”) and the Device & Performance pill (“N max sessions”) showedmaxStepsas a session count until 5.7: 5 on an iPhone 15 Pro and 13 on an 18 GB M3 Pro. The Self-RAG check after the chain keyed on that budget too (maxSteps >= 8), so Deep Think on an A17 Pro skipped it; from 2026-10-19 it keys on the mode (AgenticOrchestrator.runsDeepThinkSelfRAG,DeepThinkSelfRAGTests), so every device runs it.[evidence_level: code_verified, confidence: high, evidence_source: DeviceCapabilityService.swift optimizedAgenticConfig; AgenticOrchestrator.swift reasoningChainConfig, isDeepThinkMode; AgenticPolicyService.swift reasoningPolicy; RAGService.swift modeDetail][evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator.swift:53-57, AgenticOrchestrator+ReasoningChain.swift:290-294, AgenticOrchestrator+ReasoningChain.swift:429-440, AgenticOrchestrator+ReasoningChain.swift:465, AgenticOrchestrator+Retrieval.swift:620, AgenticOrchestrator+Research.swift:114, AgenticPolicyService.swift:299-305]Partially corrected 2026-08-14: the chain now opens with a routing turn (routeChunksByTitle) that shows the model the section titles of what retrieval found, as many as fit an 1,800-character menu and only when at least four are listed, and lets it pick up to 8 to read first (corrected 2026-10-20: this said every title, with a free choice). A title costs ~50 characters against several hundred for body text, so twenty titles fit in one window where three chunks do not. The model therefore chooses the reading order, which cosine similarity previously chose on its behalf before anything was read. It reorders and never drops, so a wrong choice costs ordering rather than evidence. It is still one retrieval and still no tools mid-session, so this is narrower than agency: the model picks from what it was given rather than asking for more.disableToolsForSession = trueis hardcoded, so the model has no tools in any session and cannot request anything. The registered exact-match tools (count_pattern,search_exact_pattern) are therefore unreachable from a reasoning session.[evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator+ReasoningChain.swift:60-178 (routeChunksByTitle), AgenticOrchestrator+ReasoningChain.swift:623 (disableToolsForSession), AgenticOrchestrator+ReasoningChain.swift:231-440 (the sessionContexts loop)] -
The one genuine loop is a fallback, now gated on measurement rather than prose.
executeRecursiveResearchimplements the real thing: it asks the model to decide, parses.answeror.search(query), and re-retrieves on demand. It has two call sites, both reached only in Deep Think and only after the chain has finished: research after a chain from an excellent first search (up to 5 rounds), and the research call inside Deep Think’s Self-RAG loop after an excellent or good one (up to 3 rounds a call, and from 5.8 one call an answer: a second retry verdict stops the loop, since research takes only the question; through 5.7 at most two calls, the third strike stopping it). Maximum reaches neither. (Corrected 2026-10-20: this said exactly one call site, which the 2026-10-18 note below already contradicts.)[evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator.swift:387-473, AgenticOrchestrator.swift:527-576, AgenticOrchestrator.swift:640, AgenticOrchestrator.swift:746, AgenticOrchestrator+SelfRAG.swift:485-559][evidence_level: grep_verified, confidence: exact, evidence_source: grep -rn "executeRecursiveResearch(" OpenIntelligence OpenIntelligenceTests finds only AgenticOrchestrator.swift:573 and AgenticOrchestrator+SelfRAG.swift:547]Changed 2026-08-14: that call was gated solely onanswerIndicatesRetrievalMiss(chainResult.finalAnswer), a string heuristic scanning the answer for hedging. It fails in both directions: a confidently wrong answer contains no hedging so the loop never ran, and a grounded synthesis that correctly notes a gap does, which is how a 91% confidence answer came to be discarded in favour of a raw evidence dump. MeanwhileFactBankhad already decomposed the query into sub-questions, tracked which the evidence answered, and compared that to the coverage target the chain uses for its own early stop. All of it was computed and discarded.ReasoningChainResultnow carriesevidenceCoverage,evidenceCoverageTargetandunansweredQuestions, and the gate fires when the chain finished below its own target. The prose heuristic is retained as an additional trigger, because it catches a case coverage cannot see: retrieval that confidently returned the wrong subject, where every sub-question reads as answered. Research is now aimed at the unanswered sub-questions rather than re-running the original query.[evidence: code_verified, exact, AgenticOrchestrator.swift ReasoningChainResult and the recursive-research gate; FactBank.subQuestionConfidence]Changed 2026-10-14, for 5.7: research’s answer replaced the chain’s synthesis whenever it kept a citation, and a synthesis without citation markers had none to keep, so on 2026-09-23 a 3,372-character synthesis gave way to a wrong one-line answer.researchMayReplaceSynthesisnow lets an answer under a quarter of a synthesis of 400 characters or more replace it only when what the answer adds beyond the question’s own words is mostly (60 percent) in the synthesis too; a number written as a word counts as its digits.[evidence: test_verified, AnswerReplacementGuardTests; not run on a Deep Think benchmark]Changed 2026-10-18, for 5.7: the Self-RAG loop’s research call, the second ofexecuteRecursiveResearch’s two call sites and the one Deep Think reaches (maxIterations: 3), had kept onlyshouldAcceptReplacement. Both of its replacement points now go throughloopResearchVerdict, which applies the first site’s checks (researchMayReplaceSynthesis,shouldAcceptReplacement, the evidence-dump and retrieval-miss checks), and the loop stops with its answer when research’s answer doesn’t agree with it rather than running research again.[evidence: test_verified for loopResearchVerdict, AnswerReplacementGuardTests; code_verified for the two call sites; not run on a Deep Think question]Changed 2026-11-05, for 5.8: a.keepstill let the loop go round, check the unchanged answer again and run research a second time, and research takes only the question, so that run repeated the first. On the owner’s iPhone on 2026-11-05 two of three loops did this and kept the same answer both times (9.3 s and 4.7 s for the second run; the second time the same 2,295-character decision prompt and the same 648 tokens in and 23 out).loopMayRunResearchnow lets the loop run research once; the check after it still runs, with the passages research added.[evidence: test_verified for loopMayRunResearch, AnswerReplacementGuardTests; code_verified, AgenticOrchestrator+SelfRAG.swift:525; artifact_derived for the two loops, his iPhone trace 2026-11-05 13:05 and 21:48 PT; the fixed loop not yet run on a device]2026-11-13: the final step’s prompt (both the source-passage prompt and the notes-only system prompt) opens withAgenticOrchestrator.answerFirstInstruction, one sentence that answers the question with its value and label before the full answer, and addsnoFalseAbsenceInstruction;RetrievalAblation.answerFirstswitches both off for the paired benchmark.[evidence_level: code_verified, confidence: high]Maximum, 2026-11-13:synthesizeFinalUnlimitedAnswerputs the top retrieved passages (labelled by their place insourceChunks, fitted withChainSynthesisEvidence.choose) before its claim bank (maximumSourcePassagesPrompt,finishFinalUnlimitedAnswer), and skips the claim-bank refinement on that path;RetrievalAblation.maximumSourcePassagesswitches it off.[evidence_level: code_verified, confidence: high] -
Synthesis truncation was removing the highest-ranked chunk, and it is now budgeted rather than cut.
executeDirectSynthesisandexecuteSynthesisStepeach ended in a hardcodedprefix(3000). BecauseexecuteFullRetrievalPipelinecloses with a Lost-in-the-Middle reorder that places rank 0 at the array midpoint, andexecuteSearchStepWithChunksrenders onlychunks.prefix(10), a large retrieval reached synthesis with its best evidence already gone. Both sites now pack against a budget derived fromFoundationModelTokenBudgetand the actual prompt, fill in score order, and log chunks and tokens dropped.executeSynthesisStepalso carried a second cut,prefix(150)per reasoning step applied before the overall budget was consulted; the per-step allocation is now derived from the budget and trimmed at a sentence boundary. Parent document expansion inRAGServicestep 7.5 is gated on the same budget, so it can no longer inflate a result set immediately before a stage that cannot hold it. Full detail inDocs/RETRIEVAL_PIPELINE.mditem 18.[evidence: code_verified, exact, AgenticOrchestrator.assembleBudgetedEvidence, executeDirectSynthesis, executeSynthesisStep; RAGService.swift step 7.5. Build-verified and suite-verified on 2026-08-17; this path has no test coverage and the behavioural claim is not device-verified.]
The gap, stated precisely. In Deep Think and Maximum, the modes that exist specifically to buy
more compute, the extra compute is spent re-reading one retrieval rather than acting on it. In Deep
Think that retrieval is up to five searches, each through the full pipeline and fused into 20
passages, and the chain runs only when they grade excellent or good: a moderate search gets one
synthesis and a low one Speculative RAG. The chain is then one session per distinct window of those
passages, at most 8 and about 5 on an iPhone. Maximum’s own loop, after an excellent search, gathers
one larger pool (a 50-passage search and up to three variations of 20) and reads three unread
passages a session, up to 50. Neither gives a session a tool. That is more inference, not more
agency. The loop that would make it agency is reachable only after the sessions finish, and only in
Deep Think: research when the chain ends below its own sub-question coverage target or its answer
reads like a miss (excellent searches only), and the research call in the Self-RAG loop. (Corrected
2026-10-20: this said eight sessions, and that research runs only if a regex over the final answer
decides the sessions failed, which the 2026-08-14 coverage gate above had already changed.)
[evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator.swift:180, AgenticOrchestrator.swift:386-985, AgenticOrchestrator.swift:527-533, AgenticOrchestrator+Retrieval.swift:1055-1137, AgenticOrchestrator+SelfRAG.swift:547, AgenticOrchestrator+ReasoningChain.swift:429-440, AgenticOrchestrator+ReasoningChain.swift:623, AgenticOrchestrator+Maximum.swift:590-593, AgenticOrchestrator+Maximum.swift:919-937, AgenticOrchestrator+MultiChain.swift:17-57, AgenticPolicyService.swift:99-126]
A separate concern, not to be confused with the above. Standard’s context packing has its own
defects, and they are packing defects rather than agency defects: the budget drops chunks past its
limit, “Needle Rescue” scavenges sentences from the dropped ones into leftover space, and rescue
labels its sources [S1...] over its own array while the packed chunks already use [S1...] over
theirs. A device trace on 2026-08-14 shows an answer citing [S5] and [S6] against four attached
chunks. Fixing that does not require making Standard agentic and should not be bundled with it.
Docs/RETRIEVAL_PIPELINE.md item 13 records the related finding that sentence selection runs
downstream of every stage the benchmark measures.
Not a recommendation. Promoting the loop out of its fallback position, or giving reasoning sessions tools, is an architecture change in the highest-risk file in the repository, on a path with no test coverage. This section exists so that decision is made against what the code does.
5.7, written 2026-10-09. Two changes at the loops’ edges, neither to how a session is built or what it is
sent. (1) A failed session is classified by ModelErrorClassifier: only a context overflow is retried with
a smaller prompt, and an unreadable response or a rate limit is retried unchanged. (2) Between sessions both
loops call SystemResourceAdvice.easeOff, which waits one second while iOS 27 reports
systemPrefersReducedResourceUsage and returns at once otherwise; the session count is not reduced. The
Maximum loop gained a Task.checkCancellation() at that point, where it had none.
[evidence_level: build_verified, confidence: high, evidence_source: AgenticOrchestrator.executeReasoningChain and executeTrueUnlimitedReasoning]
Why the sessions are not prewarmed. Measured on a Mac on 2026-10-09: prewarm, with or without the
next session’s passages as its prefix, put no tokens in the cache and did not shorten the time to the first
word. Docs/ai/DECISIONS.md, same date, has the numbers.
21. App Icon Appearance Boundary
- The
OpenIntelligence/Resources/Assets/Assets.xcassets/AppIcon.appiconsetcatalog retains the existing light icon and adds a universal iOSluminosity=darkrendition usingAppIcon-dark-1024.png. Xcode’s asset compiler packages the dark rendition asUIAppearanceDark; runtime selection on a physical device remains unverified.[evidence_level: build_verified, confidence: high_pending_device_validation, evidence_source: AppIcon.appiconset/Contents.json; xcrun actool; /usr/bin/assetutil --info]
Adaptive generation profiles (added 2026-09-11)
RAGService resolves its InferenceConfig through QueryRuntimeCoordinator.resolveContext, and
immediately after unpacking it there is now one optional adjustment, gated on
UserDefaults.bool(forKey: "adaptiveInferenceProfiles").
When on, InferenceConfig.applyingAdaptiveProfile(for:) replaces temperature and maxTokens
using the resolved AnswerIntent. When off, which is the default and the state of every install
that has not opted in, the line does nothing: UserDefaults.bool(forKey:) returns false for an
absent key.
Three properties of the design, each load-bearing:
-
It reads the intent, not the quality mode.
RAGQualityMode.temperatureis one value for every question asked in that mode. The intent distinguishes a value lookup from an investigation, which is the distinction that matters for sampling. -
It is pure.
applyingAdaptiveProfilereturns a modified copy and writes nothing.AutoTuneServiceadjusted the same two settings by persisting them intoUserDefaults, which overwrites what the owner set by hand and is not undone by turning the feature off. It had zero call sites and was removed in 5.7 on 2026-10-20. -
It reaches every mode, by two different routes. Corrected 2026-09-11; it reached Standard only when first written. On the Standard path the gate sits below the
if useAgenticreturn and mutatesinferenceConfigdirectly. Deep Think and Maximum leave before that point throughexecuteAgenticQuery, which reads neitherinferenceConfignor theconfigparameter for generation: it buildsoptimizedConfigfrom the device’s tier for Deep Think (DeviceCapabilityService.optimizedAgenticConfig()) and fromqualityMode.agenticConfig, the.unlimitedpreset, for Maximum, and takes only the routing choice fromconfig(UserRoutingPreference(config:)).RAGQualityMode.agenticConfig’s.thoroughfor Deep Think is never used. (Corrected 2026-10-20: this saidoptimizedConfigcomes fromqualityMode.agenticConfigin both modes.)[evidence_level: code_verified, confidence: exact, evidence_source: RAGService.swift@1e379aa:10790, :10864-10872 at 1e379aa, RAGQualityMode.swift:178-183]Placing the gate above the branch, which is where it was first written, mutated a local the agentic path never reads while logging the change as though it had landed, which is this repository’s recurring failure shape.The agentic path is served instead by
RAGService.activeAdaptiveProfile, resolved inexecuteAgenticQueryand held for the life of the query, then cleared. That is the same pattern asactiveUserRoutingPreference, and for the same reason: the agentic path generates across many sessions, so threading a per-query value down throughAgenticOrchestratorto every call site costs far more than the fact it carries.generateWithProperConsenttakestemperature: Float?and resolves explicit step value → profile →0.5. From 2026-10-20 (5.7) it logs each step’s result and its source, “[Agentic] Step temperature 0.3 from the adaptive profile” (or “the step”, “the default”), so a run shows the profile reaching generation.maxTokensis deliberately not taken from the profile on the agentic path. Those sessions carry per-step budgets chosen for what each step does, and one intent-derived ceiling applied across all of them would truncate mid-chain work unrelated to final answer length.A finding from making that parameter optional: exactly one of the twelve call sites passed a temperature. The comment reading “Adaptive: higher for exploration, lower for synthesis” described an intent the code had stopped expressing.
-
It is opt-in because it cannot be verified here. Retrieval is nondeterministic (
Docs/ai/DECISIONS.md), so two runs of one build return different evidence and different answers. The profile values are reasoned, not measured, and shipping them on by default would be changing every answer on a hypothesis.
[evidence_level: test_verified, confidence: high, evidence_source: RAGService.swift adaptive gate; FoundationModelDynamicProfileRegistry.swift; AdaptiveInferenceProfileTests.swift, 10 cases]
22. The three giant functions, broken into steps (2026-11-06, for 5.8)
RAGService.addDocument (1,438 lines), RAGService.queryInternal (5,826) and the structured PDF parser (1,652) are
being cut into methods in the same file, one step per commit, each a move that changes no behaviour: every commit
builds for the iOS Simulator, an iOS device and macOS, and a golden recorder (ImportGoldenTests,
StandardPipelineGoldenTests, StructuredParsingGoldenTests) records the same output as the commit before. The
host keeps every defer, do/catch and exit that must stay where it is; the order and the reasons are in
BenchmarkRuns/2026-11-06-decomposition/ (PLAN.md, specs/*/README.md). The parser’s steps are in
Docs/INGESTION_PIPELINE.md, “The structured PDF parser, broken into steps”.
RAGService.addDocument, broken into steps (2026-11-06)
| Step | What moved |
|---|---|
| I01 | Step AB (the import’s ProcessingSummary from its timings, counts and chunk statistics, with the library’s embedding provider) into makeProcessingSummary |
| I02 | AA (document) (rebuilds the imported Document with its complete processing metadata, the file hash and the import’s library) into buildCompletedDocument |
| I03 | AA (size) (formats the file’s size in MB as the B, KB or MB string the summary and telemetry show) into formatImportFileSize |
| I04 | U (pairs each passage with its vector and contextual prefix into DocumentChunk records and emits the Chunks prepared event) into buildDocumentChunks |
| I05 | S (inputs) (builds each passage’s contextual prefix and the token-limited text to embed, translating first when the library asks for it) into buildEmbeddingInputs |
| I06 | AF (marks the item complete, records the completion time, kicks pending re-embeds and retrieval auto-tune, refreshes the library’s intelligence, cleans checkpoints and schedules a self-tune rebuild if one was asked for) into finishImport |
| I07 | AE (defers the document’s overview, tags and suggested questions when the app is in the background or more files are queued, and otherwise runs them now) into enrichOrDeferImportedDocument |
| I08 | AC (lists the document in its library, updates the chunk count, library stats and processing summary on the main actor, and emits Document indexed) into recordIndexedDocument |
| I09 | Y (teaches the library’s vocabulary every passage and the Vision-detected entities, records the document, and emits Vocabulary learned) into learnImportVocabulary |
| I10 | X (builds the FTS5 rows (with structured table metadata) for every passage and stores them in the chunk-level full-text index) into storeChunksInFullTextIndex |
| I11 | W (indexes every passage in Spotlight when the setting allows it, then emits Chunks stored) into indexChunksInSpotlight |
| I12 | T (shows the indexing and storing stages with the embedding figures and emits Embeddings generated) into reportEmbeddingStats |
| I13 | S (vectors) (shows the embedding stage and generates every passage’s vector with live progress, using the import’s checkpoint folder as cache) into generateChunkEmbeddings |
| I14 | R (Step 1.5) (the self-tune corpus analysis, which can change the library’s chunking and embedding settings; it does not run today because allowsSelfTuningScheduling is false for every import) into autoAdaptConfigurationIfEnabled |
| I15 | Q (shows the chunking stage with the extraction’s live metrics and yields so the interface can draw it) into showChunkingStage |
| I16 | P (lists the document in Spotlight when the setting allows it and records that it did, so a failed import removes the entry) into indexDocumentInSpotlight |
| I17 | O (counts the document’s characters, words and per-passage word statistics and emits Extraction complete) into measureExtraction |
| I18 | N (reads and cuts the document into passages and journals how long the main thread went unanswered meanwhile) into parseDocumentForImport |
| I19 | L (when the library adapts itself, pre-scans the document’s text and stores the chunking plan it recommends before the import uses it) into prescanChunkingPlan |
| I20 | J (installs the document processor’s text and rich progress handlers, which move the tracked item through its extraction stages) into installProgressHandlers |
| I21 | G (picks the library and its embedding service and, when the provider resolves to another one or another dimension, saves the corrected settings and clears the library’s vectors) into resolveEmbeddingService |
| I22 | C (computes the file’s hash (nil when it cannot be read) and records it with the storage path on the tracked item) into hashAndRecordDocument |
| I23 | B (resolves the library this import goes to: the one it was queued for if it still exists, redirected to the person’s own library unless it is onboarding or a rebuild) into resolveImportLibrary |
RAGService.queryInternal, broken into steps (2026-11-06)
| Step | What moved |
|---|---|
| Q01 | 9 (response) (builds the response metadata and the RAGResponse and logs the total time) into buildStandardResponse |
| Q02 | 9 (gating) (builds the gating summary, final warnings and the structured answer) into summarizeGatingAndWarnings |
| Q03 | 8 (calibrates confidence and logs and emits the pipeline completion) into calibrateConfidenceAndLogCompletion |
| Q04 | 6g (log) (logs the model, timing, length and token rate of the generated answer) into logGeneratedResponse |
| Q05 | 6 (telemetry) (measures the generation time and emits the ‘Response generated’ events) into emitGenerationTelemetry |
| Q06 | 6 (chain gate) (decides whether the developer-forced reasoning chain runs) into decideReasoningChain |
| Q07 | 6 (history) (adds conversation history or memory to the prompt and decides whether citations are required) into buildGenerationPrompt |
| Q08 | 6 (output budget) (caps maxTokens to the room left after the context and applies the procedural and trivial adjustments) into capGenerationTokens |
| Q09 | 6 (prompt) (writes the intent-specific system prompt and the temperature caps into the generation config) into composeStandardGenerationConfig |
| Q10 | SV (computes the pre-generation confidence and decides whether the Evidence-First prompt is used) into assessEvidenceBeforeGeneration |
| Q11 | 5 (citations) (logs the assembled context, lists the passages the prompt labelled and records them for recovery) into finishIncludedPassages |
| Q12 to Q21 | Q12, Step 5 (ordering): orders the candidates for procedural, extractive or default questions into orderContextCandidates; Q13, Step 5 (budget): computes the token and character budget for the context into computeContextCharBudget; Q14, Step 5 (tools): starts context assembly and turns tools off when the context is already assembled into disableToolsForAssembledContext; Q15, Step 4.7 (gates): decides whether contextual compression runs and logs each reason it is skipped into gateContextualCompression; Q16, Step 4.8: adds specification-table passages found by keyword and number co-occurrence for extractive questions into runSpecTableSniper; Q17, Step SE: adds a BM25 second pass over every passage for enumeration questions into addEnumerationKeywordPass; Q18, Step SF: narrows strong short single-document questions to a neighbor window around the top passage (on-device Apple model only) into applyFocusedNeighborWindow; Q19, Step SX: blends document summaries with detail passages for questions that need a document summary into addSummaryDetailHybrid; Q20, Step SX (setup): starts the context candidates from the MMR list and detects enumeration questions into prepareContextCandidates; Q21, Step 4.4: adds passages from other documents before diversification and records the retry candidates into ensureMultiDocumentCoverage |
| Q22 to Q31 | Q22, Step 4.3 (rescue): reports the dropped passages and rescues specification passages for extractive questions into rescueDroppedSpecChunks; Q23, Step S4d: applies the contextual-definition boost to the re-ranked list into boostContextualDefinitionMatches; Q24, Step 3.5: boosts passages whose section metadata matches the question and logs the top passage into applySectionMetadataBoost; Q25, Step S3x: inserts OCR and barcode evidence as virtual passages at the front of the retrieved list into injectExternalEvidence; Q26, Step 3 (gate): decides whether iterative retrieval runs for this intent and logs when the intent overrides the setting into decideIterativeRetrieval; Q27, Step 2.5: starts the retrieval clock and sets the hybrid weights, RAPTOR-lite search levels and filtered passage pool into planSearchRouting; Q28, Step P4e: logs the pipeline box and feature summary and emits the planning events and the ‘Query received’ telemetry into logStandardPipelinePlan; Q29, Step P3: applies the opt-in adaptive generation profile (UserDefaults adaptiveInferenceProfiles) to the inference config into applyAdaptiveGenerationProfile; Q30, Step 9 (source-only): checks an extractive answer against its sources when the Standard gates flagged it into applySourceOnlyCheck; Q31, Step 7.5 (run): runs verification gates A-G against the answer and the evidence embeddings into verifyAnswerAgainstEvidence |
| Q32 to Q41 | Q32, Step 7: scores answer confidence and quality warnings into assessAnswerQuality; Q33, Step 6g (override): replaces the answer with the source-locked precision-lookup value when the model did not state it into applyPrecisionLookupOverride; Q34, Step 6 (integrity): normalizes malformed output and runs one grounded repair pass when needed into repairResponseIntegrity; Q35, Step 6 (citations): retries once for a cited answer when citations are required and missing into retryForMissingCitations; Q36, Step 6 (start): logs the generation step, applies the adaptive cooldown and starts the generation clock into beginGenerationStep; Q37, Step 5 (audit): emits the context telemetry and stores the RAGAuditSnapshot into recordContextAuditSnapshot; Q38, Step 5 (assembly): builds the context by sentence extraction or whole-passage packing with needle rescue into assembleStandardContext; Q39, Step SR: runs corrective lexical retrieval and adopts or rejects its candidates into runCorrectiveRetrieval; Q40, Step 4.9: packs graph neighbors and references around the candidates for multi-hop intents into packContextWithGraph; Q41, Step 4.7: compresses the leading candidates with the contextual compression model into compressContextCandidates |
| Q42 to Q51 | Q42, Step 4.6 (cross references): adds the passages that extractive candidates refer to into addCrossReferencedPassages; Q43, Step 4.6: expands the candidates with sibling passages from their parent sections into expandParentDocuments; Q44, Step 4.5: diversifies the filtered passages with MMR (or takes the top K when MMR is off) into diversifyWithMMR; Q45, Step 4.3 (filter): computes the adaptive similarity floor and filters the re-ranked passages into filterLowConfidenceChunks; Q46, Step S4k: retries with a cleaned keyword query when the top similarity is below 0.45 into retryWithCleanKeywordQuery; Q47, Step S4c: runs the lexical-heavy cascade search and re-rank when the policy asks for it into runRetrievalCascade; Q48, Step 4: re-ranks the candidates (cross-encoder or similarity order) and records the rerank trace stage into rerankCandidates; Q49, Step S3n: attaches source names, demotes interrogative FAQ passages and emits the retrieval telemetry into attachSourcesAndDemoteQuestions; Q50, Step S3k: drops passages whose document is in no library into dropPassagesOfUnknownDocuments; Q51, Step S3s: narrows the retrieved and cached pools to the documents a Shortcuts action named into applyDocumentScope |
| Q52 to Q61 | Q52, Step SC (write): stores a live search’s passages in the semantic query cache into writeSemanticQueryCache; Q53, Step 3 (multi-vector): adds passages from vector searches on up to two appended query expansions into runSupplementaryVectorSearch; Q54, Step 3 (single pass): runs the hybrid vector and BM25 search into runHybridSearch; Q55, Step 2 (embedding): embeds the query, or reuses the cached vector on an exact cache hit, and checks its dimension into embedQuery; Q56, Step 2 (HyDE): starts the embedding clock, logs the HyDE gates and generates a hypothetical document when HyDE applies into gateAndGenerateHyDE; Q57, Step 1.6: builds the effective query profile and derives the answer intent and its flags into resolveStandardAnswerIntent; Q58, Step 1.5: expands the query from the planner, heuristics, container vocabulary and gazetteer into expandQueryForRetrieval; Q59, Step 1: rewrites the query with the model and conversation context when enabled and not an exact cache hit into rewriteQueryWithModel; Q60, Step 0: loads the cached or newly built corpus vocabulary and every readable passage, translates the query and decides whether to rewrite it into loadCorpusVocabulary; Q61, Step SC: looks the question up in the persistent semantic query cache and takes an exact, still-current hit into lookUpSemanticQueryCache |
| Q62 to Q66 | Q62, Step P4c: sizes topK from the live passage count, the quality mode, the query profile and the adaptive candidate cap into sizeStandardTopK; Q63, Step 6 (route plan): applies the post-retrieval model plan (Private Cloud Compute envelope, consent, local fallback, abstain) into applyPostRetrievalModelPlan; Q64, Step 3 (iterative): runs multi-pass iterative retrieval with self-correction into runIterativeRetrieval; Q65, Step P4b: resolves the developer-tuning and relay flags, the selected container, its retrieval config and vector database, and records the query’s container into resolveQueryContainer; Q66, Step P1b: unpacks the coordinator’s QueryRuntimeContext into the pipeline’s locals, records the query on self, logs the header and refreshes cloud consent into unpackRuntimeContext |
| E01 to E07 | E01, Step OC: runs the reliability fallback from the recovered passages when it applies, else logs the failure and rethrows (the outer catch body) into recoverFromQueryFailure; E02, Step ND: answers a question to a library with no documents, abstaining for actions and grounded-only mode and otherwise by direct chat into answerWithoutDocuments; E03, Step IC: builds a recovery response from the generated text when processing the answer threw (the inner catch body) into recoverFromResponseProcessingError; E04, Step 7.5 (abstain): logs the verification gates and abstains when they failed in grounded-only mode or below the quality mode’s threshold into abstainOnFailedVerification; E05, Step 6g (empty): answers from the recovered passages when the model returned nothing, else throws modelNotAvailable into fallBackFromEmptyAnswer; E06, Step 6d (abstain): abstains when citations are required, missing after the retry, and ungrounded fallback is off into abstainForMissingCitations; E07, Step 5.9: answers a summarize question from an extractive summary of the included passages, falling through to generation when it fails into answerWithExtractiveSummary |
| E08 to E14 | E08, Step SG: returns a not-found answer when the included passages are lexically and semantically irrelevant to the question into applyHardRelevanceGate; E09, Step 5 (empty): answers by direct chat or abstains when context assembly produced no passages into handleEmptyAssembledContext; E10, Step SH: returns the closest sources instead of an answer when fewer passages than Library Settings requires reach its minimum score into enforcePassagesNeeded; E11, Step 4.5 (empty): answers by direct chat or abstains when MMR returned no passages into handleEmptyDiverseSet; E12, Step 4.3 (gate): when no passage clears the similarity floor, takes the top re-ranked passages under override, lenient or fallback rules, else abstains into handleNoConfidentPassages; E13, Step 4 (empty): answers by direct chat or abstains when re-ranking left no candidates into handleEmptyRerank; E14, Step 3 (empty): answers by direct chat or abstains when retrieval found no passages into handleNoRetrievedPassages |
The three files, split by job (2026-11-07)
After their functions were broken into steps, the three files that held them were split into files by job with the
2026-11-05 procedure (BenchmarkRuns/2026-11-05-file-split/OVERNIGHT.md): a pure move, with private removed only
where another file now uses the name, checked by prove_move.py (0 lines added, lost or out of order),
overload_check.py, widen_check.py, three builds and the file’s golden recorder.
| Was | Now |
|---|---|
DocumentProcessor+StructuredParsing.swift (2,825) | itself (1,397: structured PDF extraction and its steps), +StructureChunks (707: structure-aware chunking, the oversized-chunk splitter), +StructureText (775: document classification, chunk metadata, text builders, sanitizers) |
RAGService+Import.swift (3,501) | itself (1,640: addDocument, its steps, the managed-copy helper), +ImportQueue (856: the ingestion queue and its lifecycle), +ImportEnrichment (375: deferred enrichment), +IndexHealth (711: embedding fingerprints, index health, rebuilds) |
RAGService+QueryPipeline.swift (6,531) | itself (1,000: the query entry points and queryInternal), +QueryExits (949: the early answers and the two catch bodies), +QueryPreparation (967: runtime context, library, top-K, query cache, vocabulary, rewriting, expansion, intent, HyDE, embedding, the plan log and routing), +QueryRetrieval (1,412: search, filters, reranking, MMR, parent and cross-reference expansion, iterative and external evidence), +QueryContext (1,401: compression, graph packing, corrective retrieval, context assembly and budget, the audit snapshot), +QueryAnswer (937: generation setup, citations, integrity, verification, quality, the source-only check, confidence and the response) |
[evidence_level: test_verified, confidence: high, evidence_source: StructuredParsingGoldenTests parse-b6 == parse-f1 (13 items), ImportGoldenTests import-i23 == import-f2 (32 items) and StandardPipelineGoldenTests standard-e14 == standard-f3, iOS Simulator, iOS device and macOS builds, 2026-11-07]
Maximum, the compute profile, turns the work up (added 2026-11-10, for 5.8; unmeasured)
With the Compute Profile set to Maximum, the app in front, the device not hot and Low Power Mode off
(DeviceCapabilityService.isMaximumFidelityActive; constants in DeviceCapabilityService.MaximumFidelity;
OI_MAXIMUM_FIDELITY=on|off overrides it for a benchmark): reading is turned up (432 DPI, full-size layout pass, 24 rescue regions, fewer pages at once; Docs/INGESTION_PIPELINE.md) and so is search depth (rerank up to 400, 120 keyword results; Docs/RETRIEVAL_PIPELINE.md); the embedding model and the reranker load with fastPrediction. The Compute Profile card (ComputeProfileCard) states each figure from the same constants.
Until this change the profiles only chose which chips may run a job. None of it is measured: benchmark day
(2026-11-11) compares Maximum with Balanced, and it ships only if it reads and finds at least as well.
[evidence_level: code_verified, confidence: low until measured]
The profiles ramp (added 2026-11-10, for 5.8; unmeasured). Depth now steps up per profile through DeviceCapabilityService.Depth and activeDepth: Efficiency and Balanced keep 5.7’s values, Performance takes the midpoint and Maximum the top. Efficiency saves energy only by halving what runs at once (paced(_:for:): text recognition, pages parsed and drawn, passages embedded), never by reading or searching less, because accuracy comes first. OI_COMPUTE_PROFILE=efficiency|balanced|performance|maximum overrides the profile for depth and pacing on one build (OI_MAXIMUM_FIDELITY still works). Per profile, Efficiency / Balanced / Performance / Maximum: rescue regions 12 / 12 / 18 / 24, rerank ceiling 250 / 250 / 325 / 400 (floor 100 / 100 / 125 / 150), keyword results 60 / 60 / 90 / 120, full-detail pages only in Maximum. ComputeProfileDepthTests pins that no step reads less than the one below. [evidence_level: code_verified, confidence: low until measured]
What the Intelligence Mode page claims per mode (traced 2026-11-10, 5.8). Deep Think and Maximum return to executeAgenticQuery at RAGService+QueryPipeline.swift:249, so any step that exists only later in queryInternal runs only under Standard: HyDE (:375, and Standard has usesHyDE off), contextual compression (:489, Deep Think only by flag), graph context packing, the lost-in-the-middle order that reaches the prompt, conversation memory and sigmoid confidence calibration. IntelligenceModeCard lists only steps with a live call site and the modes that reach them; the Settings card’s step ids are pinned by IntelligenceModeCardTests. Unfixed retrieval findings from the same trace are in Docs/ai/STATE.md. [evidence_level: code_verified, confidence: high]
Multi-query fusion ranks by score (2026-11-10, 5.8; unmeasured). AgenticOrchestrator+Retrieval.swift fuses Deep Think’s and Maximum’s searches by reciprocal rank after rankedForFusion puts each search in score order; executeFullRetrievalPipeline returns lost-in-the-middle order, which gave each search’s second-best passage its worst rank. OI_RETRIEVAL_ABLATE=fusionScoreOrder restores the old order. [evidence_level: code_verified+test_verified, confidence: medium until measured]
Haptics (added 2026-11-16, for 5.8)
Every haptic goes through DSHaptics (UI/DesignSystem/Theme.swift), which plays only on haptic hardware while the app is active, drops one within 60 ms of the last, and reports each one played to HardwareTelemetryState.reportHaptic, the X-Ray’s Taptic Engine count. Services that run without a touch (SystemStateMonitor, ContainerService.setActive, the model service) play none; the chat plays the work in progress (DSHaptics.beat() per Deep Think step and as text streams), and the import queue one per file. [evidence_level: build_verified, confidence: medium, evidence_source: Theme.swift DSHaptics.perform; CHANGELOG 5.8 haptics entry]
Device figures, one rule for every device (added 2026-11-16, for 5.8)
Every figure about the device the app runs on is read live where Apple offers an API (SystemLanguageModel.contextSize, Metal, ProcessInfo.physicalMemory, hw.perflevelN, IOKit power sources on a Mac, thermal state) and otherwise taken from tables that cover every device on Apple’s Apple Intelligence list (support.apple.com/en-us/121115, published 2026-11-05). Answer quality is the same on every supported device: AdaptivePipelineConfig.base(for:) keeps only pacing from the device tier, and DeviceCapabilityService.optimizedAgenticConfig() gives Deep Think one 95% target and at least 12 steps, raised by memory. chipIsAtLeast compares chip family and generation. Whether Apple Intelligence is supported comes from DeviceCapabilityService.supportsAppleIntelligence, not the old DeviceChip table. The reranker loads its default compiled form first and, on Maximum, prepares the .fastPrediction form in the background (RAGEngine.prepareFastForm, RerankerFastForm). [evidence_level: code_verified, test_verified (DeviceFiguresTests, RerankerFormTests on the Simulator), confidence: medium, evidence_source: CHANGELOG 5.8, 2026-11-16 entries]
A failed reranker load is retried (added 2026-11-16, for 5.8)
RAGEngine.retryRerankerIfItFailed loads the reranker again, up to three tries a launch, before the next rerank or warm-up when the last load left fewer than two functions; until then a failed load left the whole launch on the heuristic fallback. reranker.load records each function’s error and the attempt. [evidence_level: build_verified, confidence: medium, evidence_source: RAGEngine.swift]