OPENINTELLIGENCE_ARCHITECTURE_ATLAS.mdView source

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 in Docs/AuditArtifacts/RepoOS/change_impact_matrix.csv name 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 in ARTIFACT_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: read Docs/SHIPPED_VERSION.json (app_store for what is live, in_review for what is submitted). Docs/CANONICAL_OPENINTELLIGENCE_SOURCE_OF_TRUTH.md outranks 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 vendored swift-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 at 1e379aa: 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 across RAGService.swift and fifteen new RAGService+*.swift files, beside the three that existed (+KnowledgeRetrievalEngine, +Streaming, +TextStreaming),, and AgenticOrchestrator across nine files; Docs/ai/ARCHITECTURE.md maps 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 in runFinishableStage) 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. execute parks the chat’s stream handler in LLMStreamingContext.finalAnswerHandler for the whole run, so only the calls that write the final answer stream (through LLMStreamingContext.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.shared builds the process-wide RAGService, WorkspaceSyncService, ContainerService, EntitlementStore, SettingsStore and ModelResolutionService once 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]

  • PassageFileIndex and PassageSlot (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]

  • LibraryIntelligenceCenter and LibraryIntelligenceCache (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.resolveAutoAdjustments lets 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: scheduleSelfTuningRebuild is behind IngestionContext.allowsSelfTuningScheduling, false for every kind of import.) The report and the first question’s CorpusVocabulary are 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) and sweep (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; RAGService itself is on the main actor. RAGService.libraryVocabulary holds 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 by SettingsStore, ContainerService.defaultContainer, AdaptiveEmbeddingOptimizer and RAGService.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 in Docs/INGESTION_PIPELINE.md. [evidence_level: test_verified, confidence: high, evidence_source: DocumentProcessor.swift; IngestionAccuracyTests]

  • AtlasLabeling, MetricDiagnostics and SystemModelTools (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 is SQLiteFullTextService.swift (state, initialization and the schema, migrations and query helpers, unchanged) with +Documents, +Chunks, +Search, +Statistics and +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 (in cleanupResponseText) and droppingUnsupportedHeadlineNumber (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 after keepAxisLabelsInView each frame. [evidence_level: code_verified, confidence: high]

  • (5.8, 2026-11-13) ModelCompileCache.clearOncePerVersion clears 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.setStep gives the setup card its two real steps. [evidence_level: code_verified, confidence: high]

  • (5.8, 2026-11-13) RAGService.judgedQuestion gives the responsiveness judge the current question first, with earlier turns marked as reference; removingCopiedReferenceNumbers takes 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; removingEchoedPromptSections strips a section the answer echoed from its prompt; Tour.tourIsRunning ends the tour after three days and pacedTipsPerLaunch caps it at two a launch; RerankerModelLocation keeps the model copies under the app group’s folder. [evidence_level: code_verified, confidence: high]

  • (5.8, 2026-11-14) RAGService.valueRestatesQuestion joins 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.namingTheCitedDocument writes the cited file’s name after the first citation of an answer to a which-document question, in finalizeResponse (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 (in ConversationMemoryService.swift) leaves out a refused answer (isRefusal: StructuredAnswer.refuse, or a gating decision only a refusal records; MemoryTurn.refused records it at finalizeResponse) 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 in UserDefaults, recorded from RAGService.documents’ didSet by 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) and rewriteQueryWithModel both apply it. clearMemory saves 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, which isRefusal reads; VerificationOutcome reads it as nothing, and the chat’s badge and the details’ Verification row read shownGatingDecision, which drops it, so a refusal shows as before. Marked where written: Quotes only and the excerpts fallback with no excerpt (RAGService.excerptsGatingDecision); RAGService.markingUngatedRefusal on Standard’s shown text after the source-only check (RAGService+QueryPipeline.swift) and on the agentic answer (RAGService+AgenticQuery.swift), for notFoundAnswer, 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); and finalizeResponse, which every answer passes, for a model refusing in its own words (refusesInItsOwnWords: at most 500 characters, no [S citation, 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 is ChatMessage.handedOff (persisted, false in older files) unless it refuses, and isErrorMessage excludes it. ContainerService.deleteContainer calls ConversationMemoryService.removeMemory, which deletes the local memory file on the write queue and saves nothing for that library again this launch; the iCloud copy goes with cleanupSharedWorkspace. [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) RAGService picks its model service once, when it is made; a model not ready then left AppleFoundationLLMServiceUnavailable in place until Settings changed. RAGService.reconnectAppleModelIfNowAvailable() (in RAGService+Consent.swift) runs at the start of query and 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 journals model.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, journal model.quotesOnlyLifted), since Quotes only skips every model step whatever service is in place. SettingsStore’s $selectedModel sink 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 for EvidenceThreadStore that no other file referenced.

  • JSONRecordExtractor (added 2026-10-09, 5.7): reads .json, .jsonl and .ndjson as records with its own order-keeping reader (JSONValue), cuts one passage per record and cuts an oversized record at its own lines; called only by DocumentProcessor.processDocument. Detail in Docs/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 by DocumentProcessor.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 by IngestURLIntent and AddToLibraryIntent. [evidence_level: code_verified, confidence: exact, evidence_source: WebPageFetchService.swift] A grep of OpenIntelligence for URLSession on 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 of RAGService.extractRelevantSentences, moved out so they can be tested; it keeps a wrapped sentence whole and uses AnswerSentenceSplitter for 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 one RAGService.query call to those documents’ passages. Set only by AskActionRunner for the three Shortcuts actions that name a document. Read in HybridSearchService.search (which then scores the named documents’ passages directly and returns nothing else), in queryInternal after 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.

  • AppLink and AppNavigationRequest (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.route handles the tab and the library for the oldest request; DocumentLibraryView and ChatScreen take 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, and Info.plist declares 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:)), which AppLink.destination(for:) reads as the app link it carries, so ContentView.handleOpenURL takes a web link the way it takes an app link (SwiftUI hands a web link that opens the app to onOpenURL, developer.apple.com, read 2026-10-17). The entitlements carry applinks:gunndamental.com from 5.8 (applinks:gunzino.me through 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 (Gunzino 5c10b42, 2026-10-17; Apple’s association CDN served the file the same day). Only https on the web host at /openintelligence/open counts, and to can’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:)]

  • LibraryFocusFilterIntent and ContainerService+Focus (added 2026-10-14, 5.7): a Focus filter (SetFocusFilterIntent) that names libraries; while its Focus is on, the two library pickers list ContainerService.pickableContainers and the open library moves to the first allowed one. The allowed set is a UserDefaults key 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 three NSServices entries in Info.plist (ask about selected text, add selected text, add files from Finder), set as NSApplication.servicesProvider by OpenIntelligenceMacAppDelegate at launch; it posts .ask or .importFiles to 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 of QueryRuntimeBridge (set in OpenIntelligenceApp.configureQueryRuntimeBridge, beside the background task and the completion notice); its views are in the widget extension’s IngestionLiveActivityWidget.swift. [evidence_level: build_verified, test_verified for its state; confidence: high; evidence_source: QueryLiveActivityService.swift]

  • CheckClaimIntent and ClaimCheck (added 2026-10-14, 5.7): “Check a Claim”, which finds six passages with searchDocumentsRaw and runs VerificationGateService.verify with 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 asks hasNegation(_: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). From 2026-11-18 a “no” counts the same way as “without”: only when what it denies (read to the end of its clause, a joining word or a verb, at most four words, singular or plural) is named in the other text, so “no query expansion” in the guide’s Standard item no longer reads as the opposite of “The similarity floor in Standard mode is 0.28.”; a “no” with nothing after it, and “no longer”, “under no circumstances”, “no one”, still count (ClaimCheck.resolvingNo; RetrievalAblation.noNamedOnly off restores the old reading in development builds). [evidence_level: test_verified (ClaimCheckTests, including testNoCountsOnlyWhenWhatItDeniesIsNamed 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 an IntentFile in Markdown, JSON Lines or PDF, the bytes the chat menu writes (ConversationExporter.data); ConversationExporter.pdf sets 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]

  • UITestSupport and UITestRemoveDocumentsIntent (added 2026-10-14, 5.7, Debug builds only, App): with the launch argument --uitest-stand-in-model the ask actions’ engine gets a stand-in model that answers with the UITEST_STAND_IN_ANSWER environment value (AskActionRunner.makeEngine), and an action that Shortcuts does not list removes documents by the start of their names, eight characters or more. The OpenIntelligenceUITests target, 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 ask SystemLanguageModel.default themselves take their no-model path; off, it changes nothing, and a Release build reads it as false. With NetworkMonitor.holdForTesting(_:) it lets StandardPipelineGoldenTests record 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) to ContentView, keeping it before announcing it so a window can claim it from the announcement, never taking a sheet on screen away, which shows CloudConsentPromptView in 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’s CrashReports folder, newest ten kept, a crash delivered twice kept once, without an exception’s message text or arguments or the memory region description; ContentView offers the newest one once, in the first window to ask (takePending), Email Report opens a mail to the feedback address with its summary, and AboutView shares 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]

  • LibraryWidget and WidgetSnapshot (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 writes WidgetSnapshot (widget_snapshot.json) to the app group group.Gunndamental.OpenIntelligence from ContentView (library and count, once an import ends), ContainerService.applyFocusFilter (a Focus that moves the open library) and ChatScreen.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, when ChatScreen.clearChat or ThreadSidebarView removes its conversation, when MessageBubbleV2 hides it, and when sync removes its conversation (ContentView.refreshSharedWorkspaceIfNeeded). Nothing is written on the Mac, where no widget extension is built. OpenIntelligenceLiveActivitiesBundle does 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 in IngestionLiveActivityWidget.swift because the extension target lists its files in project.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 tools createTools returns. 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.query sets one per answer as a task-local, LLMService adds each generation’s GenerationUsage, and finalizeResponse saves the total as ResponseMetadata.appleUsage. [evidence_level: test_verified (AnswerUsageTallyTests), confidence: high]

  • RAGService.passagesFromKnownDocuments and removePassages (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, and removeTextOfUnfinishedImports removes 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 through executeFullRetrievalPipeline, not searchDocumentsRaw, and it now checks its result; the retrieval cascade, the keyword retry and semanticSearch apply it too; the passage list the later steps of a question read leaves such passages out (chunksOfListedDocuments); and enrichImportedDocument no longer stores an overview or suggested questions for a document deleted while they were written (enrichmentTargetState). Detail in the same section of Docs/RETRIEVAL_PIPELINE.md.)

  • DayOrdinals (added 2026-10-15, 5.7): RAGService.queryInternal reads a day written as an ordinal beside a month (“September 30th”) as its number before anything else uses the question, and executeFullRetrievalPipeline does the same for Deep Think’s and Maximum’s own searches, because the keyword index keeps “30th” as one word. Details in Docs/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.queryInternal keys semantic_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): the SnippetIntent the 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 running OpenDocumentIntent (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 running AskFollowUpIntent, 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 running ThinkDeeperIntent, which opens the chat on that library in Deep Think with the question (AppDestination.ask(_:sendsAtOnce:inDeepThink:libraryId:)); when each is offered is AskActionRunner.offersFollowUp and offersThinkDeeper, and both intents are in OpenItemIntents.swift, run in the foreground (supportedModes) and are not listed in Shortcuts. It replaced RAGResponseSnippetView. [evidence_level: test_verified (AskControlTests), build_verified; confidence: medium; evidence_source: Services/Agentic/RAGAppIntents.swift]

  • ContainerService.move(_:before:) and orderedContainers (added 2026-10-14, 5.7): a library chip dragged in ContainerPickerStrip (SwiftUI 27’s reorderable() and reorderContainer(for:)) sets this device’s library order (libraryDisplayOrder in UserDefaults), which pickableContainers follows; 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 closures OpenIntelligenceApp sets on IngestionRuntimeBridge and QueryRuntimeBridge; MetricDiagnostics enables both domains in its MetricManager and 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, an IntentValueQuery over SemanticContentDescriptor) and its “More results” intent (.visualIntelligence.semanticContentSearch). It reads the picture’s text with Vision, adds the system’s labels, and returns at most 100 OIDocumentEntity, names first, then keyword-index matches across every library. [evidence_level: test_verified (VisualDocumentSearchTests), build_verified; confidence: medium; evidence_source: Features/Camera/VisualDocumentSearch.swift]

  • DeleteDocumentsIntent and DocumentDeletion (added 2026-10-14, 5.7): a DeleteIntent that asks first and removes through RAGService.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, commitPendingRemovals and removeDocumentsLeftPending, with PendingDocumentRemoval and PendingDocumentRemovalLedger (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 of documents at once and runs removeDocument six 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 in pending_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]

  • The guide library is permanent (2026-11-18, 5.8): ContainerService.mayDelete refuses it on every path (deleteContainer, LibraryDeletion), Library Settings shows it read-only (ContainerSettingsSheet.isGuideLibrary), its menu has no Delete or storage choice, and SampleDocumentManager.restoreGuideLibraryIfMissing (when Documents opens) puts back a missing guide library or guide (guideRestoreTarget). [evidence_level: test_verified (GuideLibraryTests), code_verified; confidence: high]

  • AgenticAnswerWritingMeter and AnswerWritingSpeed (added 2026-11-18, 5.8): Deep Think and Maximum record each model call made through generateWithProperConsent (its text, its writing speed, whether it streamed into the chat) in a task-local meter bound around AgenticOrchestrator.execute; the saved tokens per second is the speed of the latest call of at least 60 characters whose text the final answer holds, else the latest call that streamed into the chat, else none. Display only: no call, prompt, order, consent or routing changes. [evidence_level: test_verified (AnswerWritingSpeedTests), code_verified; confidence: medium; not seen on a device]

  • RAGService.isProtectedGuideDocument (added 2026-11-18, 5.8): a document in the guide library (ContainerService.isGuideLibrary) is not deleted by a person. scheduleRemoval leaves such documents out, clearAllDocuments returns without emptying the guide library, and DeleteDocumentsIntent refuses before it asks to confirm; the card’s Delete items, the swipe (DocumentSwipeToDelete(enabled:)) and the Remove All chip are not shown for it. removeDocument is not guarded: the guide refresh (SampleDocumentManager) and a rebuild still remove guides, and so does the OIEngine SDK’s removeDocument, which the app does not reach; the guide library itself can’t be deleted (next line). [evidence_level: code_verified, build_verified (iOS and macOS Debug); confidence: high; no test covers it; evidence_source: Services/RAG/Orchestration/RAGService+Deletion.swift; Services/Agentic/DeleteIntents.swift]

  • MenuBarAsk (added 2026-10-14, 5.7, Mac only, app only): the MenuBarExtra in OpenIntelligenceApp, with a field that posts .ask(_:sendsAtOnce: true) and buttons for Add Documents and Search; showMenuBarItem in UserDefaults, 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 through IntentDonationManager when the person picks a library or asks in one; called from the screens, never from ContainerService or RAGService. [evidence_level: code_verified, confidence: high, evidence_source: SiriDonations.swift and its three call sites]

  • Device eligibility messages (changed 2026-11-17, 5.8): RAGService+Device and WritingToolsService said a device needs “A17 Pro+ or M-series”, which leaves out the MacBook Neo (A18 Pro); they now quote AppleIntelligenceCopy.supportedDevices, Apple’s list. AppleDeviceCatalog gained every Apple silicon Mac, looked up by hw.model. [evidence_level: code_verified, confidence: high]

  • A cut-off answer says so (changed 2026-11-17, 5.8): when the model fails after part of an answer streamed, RAGService+Generation keeps the partial answer as before and now ends it with an italic line saying it stopped early (Apple pausing the model in the background, or another stop) and to ask again. AppleFoundationLLMService first tries to finish a rate-limited answer itself (resumeAfterPause), and continuations are sized by the window’s remaining room rather than 1,600 characters (continuationTokenRoom: the window less SystemLanguageModel.tokenCount(for:) over the transcript less 64, passed as maximumResponseTokens). [evidence_level: code_verified, build_verified on iOS and macOS; the continuation measured on the M3 Pro Mac (room 3,113 tokens, an answer finished across two calls), not yet on the iPhone; the resume build-verified only; confidence: medium]

  • Compression estimate (changed 2026-11-17, 5.8): RAGService+QueryContext estimates how many candidates fit before compressing them from the window the device reports, not a fixed 4,096 (baseContextLength only where the device reports none). [evidence_level: code_verified, build_verified, confidence: high]

  • RAGService launch and import figures (changed 2026-10-15, 5.7): an engine started without Apple’s model leaves lastError empty, 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, deferEnrichment and runDeferredEnrichmentsIfNeeded (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 in Docs/INGESTION_PIPELINE.md. [evidence_level: test_verified (DeferredEnrichmentTests), confidence: medium]

  • RAGService.leadingWithTopRanked and extractRelevantSentences(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 in Docs/RETRIEVAL_PIPELINE.md. [evidence_level: test_verified (LeadingEvidenceTests), confidence: medium]

  • RAGService.extractedValueAnswersQuestion and lookupWords(in:) (added 2026-10-15, 5.7): the check highPrecisionLookupOverrideAnswer makes before a value SpecificationExtractor read 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 without genericValueWords, with SpecificationExtractor.subjectSynonyms added). 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; isCountedByGate keeps the gate to the numbers it counted before 5.7. Called by VerificationGateService.runGateC and evaluateClaim, 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 by SourceOnlyAnswerService (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]

  • EntityBinding (added 2026-11-18, 5.8): reads passages as labelled units (a list item or line by its bold or “Name:” lead, a line under a heading by that heading, table rows left to VerificationGateService.valuesFromOtherRows) and says whether a claim’s number sits with the subject the claim names. Two callers: Fact Check (VerificationGateService.markingValuesFromOtherRows, one EntityBinding.Reading per Gate B pass), which marks a claim Unsupported when its number is given only for another item; and the citation page (SourceTextView, SourcePageView, via citationNote). RAGService.extractRelevantSentences uses EntityBinding.lead so each sentence cut from a list item is packed with the item’s lead (“Standard > …”; RetrievalAblation.itemLeadInSentences). Detail and measurements in Docs/RETRIEVAL_PIPELINE.md, “A value from another list item or section is not supported”. [evidence_level: test_verified (EntityBindingTests), confidence: high]

  • DetectedValueCheck (added 2026-10-15, 5.7): reads amounts of money, dates (written with a year) and measurements in an answer and its passages with dataDetectorMatches, 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, runGateB marks 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]

  • DomainIsolationService and Gate I (changed 2026-10-15, 5.7): keywords count as whole words (normalize pads 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, and VerificationGatesOverlayView marks 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 .verification event]

  • 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 by AgenticOrchestrator.executeReasoningChain and by RAGService.generateWithFallback and isContextOverflowError. [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’s UIApplication.systemPrefersReducedResourceUsage, written by SystemStateMonitor (started at launch by OpenIntelligenceApp) and read at the boundaries of the embedding batch loop (EmbeddingService.generateEmbeddings) and of the two reasoning loops in AgenticOrchestrator, 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]

  • CompletionNotificationService and CompletionNotificationPolicy (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 in OpenIntelligenceApp; a tap is routed through AppNavigationRequest. [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’s OpenedFiles folder, which iCloud sync never sweeps (ImportedFileStaging.copyForViewingOffMainActor); shown by DocumentLibraryView.showOpenedFiles. [evidence_level: build_verified, confidence: medium; evidence_source: OpenedFilesSheet.swift]

  • PastedContentStaging and LibraryPasteButton (added 2026-10-09, 5.7, app only): turn a pasted file, web address or text into files in the imported-documents folder, which DocumentLibraryView.importOpenedFiles then 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 through PastedContentStaging.clipboardProviders; it is not the system’s PasteButton, 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 of DocumentProcessor.processDocument runs on the concurrent pool through chunkTextOffMainActor, with progress every 25 chunks, a stop on cancellation, and an error at maxChunks (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). createStructureAwareChunks still calls it on the main actor. Detail and measurements in Docs/INGESTION_PIPELINE.md section 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, TextPieceReader and TextStreamingIngestionState (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 through DocumentProcessor.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 @EnvironmentObject and @AppStorage heavily 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 a plain and a technical register, keyed by GlossaryTermID with definitions returned from one exhaustive switch, so lookup is compile-time total and returns no optional. Consumers attach a definition rather than restating one: .definedTerm(_:) on any view, GlossaryInfoButton on list rows, and GlossaryView as the searchable index. Wired at OnboardingChecklistView (pipeline capsules, metric strip, device chips), HowItWorksView (the four pipeline stages), and SettingsView (the Silicon RAG rows and the Plain English entry; the Hardware Envelope rows, the batch pills and the TOPS line went with the 5.8 ActiveDeviceCard). The technical register’s expansion state is one shared AppStorage key, so it is a per-user preference rather than per-popover state. GlossaryTests enforces 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). AppleDeviceCatalog holds model names from Xcode 27.0’s device_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.npuTops is 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. ActiveDeviceCard shows 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). AppleDeviceCatalogTests pins 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]
  • HowItWorksView narrates the pipeline in order; GlossaryView defines 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.delete in Features/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, because EntityIndexService.indexChunk and indexChunks have 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. DocumentLibraryView and ContainerSettingsSheet both call it; the latter defers its dismiss() until the outcome is .deleted so a refusal has somewhere to report. Two lookalikes are deliberately outside it: deleteConflictedLocalLibraries handles libraries iCloud has already dropped and ends with a reconfigureIfNeeded pass, and OpenIntelligenceEngine.deleteLibrary calls containerService.deleteContainer alone, leaving documents behind, because it is public and 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]
  • A deleted library takes nothing to another library (2026-11-18, 5.8). resolveImportLibrary (RAGService+Import.swift) asks ContainerService.libraryPresence: a library deleted here throws RAGServiceError.importLibraryGone, where it used to fall through to the open library (deleted BDB0BCA5 on the owner’s Mac took the guides to General on 2026-11-14 and to Library 4 on 2026-11-18); one not listed and not deleted here throws importLibraryNotHereYet, and the queue keeps the item queued until a reload lists its library. A rebuild takes its store by the library’s record, never dbFor’s fallback to the open library, and stops before clearing or writing a document once its library is gone. LibraryDeletion.delete cleans up a library already gone from the list (journal library.deleteLocal), removes what documentsForContainer lists, and applies deleteContainer’s rule (ContainerService.mayDelete). At launch and on every applied workspace reload, removeRecordsOfDeletedLibraries (RAGService+Storage.swift) leaves out of the read list, on this device only, the records of libraries in this device’s deletedContainerIds (no deleted_documents.json entry, no imported file, no vector store), and purgeQueueItemsOfDeletedLibraries (RAGService+ImportQueue.swift) tombstones only their waiting items that carry this device’s lease; an unlisted library not known to be deleted keeps its records and is counted in library.orphanRecords. iCloud’s deleted_containers.json is not consulted (its folder is private to WorkspaceSyncService). Detail and per-part evidence: Docs/INGESTION_PIPELINE.md, last section. [evidence_level: code_verified; test_verified for the parts DeletedLibraryLeftoversTests reaches (listed there), confidence: high; not yet seen on a device]
  • File placement under OpenIntelligence/Services/ is a target decision, not just organisation. The OpenIntelligenceEngine framework synchronises eighteen folders, including Services/Infrastructure/Integration, and excludes Services/Infrastructure/Presentation and all of Features/. A new file in an included folder is compiled into the SDK as well, so one that references a Presentation or Features type builds fine in the app and fails only the test build, with a scope error indistinguishable from stale DerivedData. LibraryDeletion.swift lives under Features/ 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 use DocumentChunk.contextText, which keeps the parent only when it holds the passage; through the first 5.7 builds 57 readers took parentContent ?? content and 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

  1. App Launch & Container Restore
  2. Library Container Context Switching
  3. Document Import & Vector Extraction Pipeline
  4. End-to-End RAG Query & Inference Pipeline
  5. Maximum Mode & PCC Route Policy Evaluation
  6. iCloud Workspace Sync & Entitlements
  7. StoreKit Purchasing & Quota Resolution
  8. App Intent Siri Shortcuts integration
  9. Telemetry Trace Generation

8. Background/System Flows

  • BGTaskScheduler used for indexing sweeps. An import or a long answer the person started also runs under a BGContinuedProcessingTask (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 record backgroundGPUSupported: 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.parseSubBatchStructure reports each page as its structure parse returns, and the structured parser’s other reports give pages finished rather than a batch’s last page, so ImportProgress.fraction and the BGContinuedProcessingTask’s progress move during a PDF’s extraction; RAGService.updateIngestionItem journals 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.fillMissingQuestions writes questions for each file with none in the library’s bank, and reads that file’s passages through RAGService.passagesForSuggestedQuestions (the store’s records for the document, up to 80 spread evenly by evenSampleIndices, plus its overview, read by id), not out of getSampleChunks’ 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.getSampleChunks reads the pool from the store and scores it in a detached task (selectSuggestedQuestionSample and its helpers are nonisolated 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 no BGContinuedProcessingTask for an answer (OpenIntelligenceApp beginUserInitiatedQueryHandler), 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 in RAGService.query; SuggestedQuestionsService, DocumentSummaryService, ContentTaggingService, ClusterLabelService, LibraryVisualizationEngine and ImageUnderstandingService call waitWhileAnswering before 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 through ContinuedQueryCoordinator.cancelCurrentQuery()) is no longer reached from either. While an answer runs, ContinuedQueryCoordinator reports 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]
  • 5.8, 2026-11-19: every answer keeps working in the background. From 2026-11-04 an answer kept on the device asked iOS for no continued time, had the usual 30 s after the app left, and paused until it was opened; before that it had finished in the background. On the owner’s iPhone on 2026-11-19 two Standard answers asked while leaving paused (10:36:58, 10:41:01). Now (1) every answer submits its BGContinuedProcessingTask (OpenIntelligenceApp.configureQueryRuntimeBridge), so retrieval, embedding and reranking finish while the app is away (the Neural Engine is allowed there under continued-processing.inference); (2) QueryExecutionPlannerService.buildFoundationModelPlan makes no model call while DeviceCapabilityService.isAppInBackground, so the rules plan the question, the plan a refused call already gave (refused at 10:39:14); (3) a Chat answer refused with rateLimited in the background retries there after 2, 5, 10, 15 and 20 s and waits for the app only before the last try (RAGService+Generation.swift), since the system’s background budget let the same call through 7 s after a refusal (10:39:19 refused, 10:39:26 answered). Deep Think and Maximum still hold each model call for the app (waitBeforeModelCallWhileInBackground): they make many calls. [evidence_level: measured (phone trace) and build_verified; confidence: medium until a Standard answer asked while leaving is seen finishing on the iPhone]
  • NSMetadataQuery background updates for iCloud Drive.
  • The floating iOS Silicon HUD owns a dedicated UIWindow and derives all frame bounds from that window’s non-optional UIWindowScene.screen; it does not use the deprecated process-global UIScreen.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-18: a pass that changed nothing writes nothing. WorkspaceSyncService.writeJSON writes through coordinatedMergeData, which leaves a file alone when it already holds the new bytes and announces .localWorkspaceDidChange only after a real write. synchronizeIngestionQueue writes each copy of ingestion_queue.json only when its items, contexts or tombstones differ from what it read from that copy (ingestionQueueStatesHoldTheSameWork: updatedAt and order ignored, compared before container aliases), and IngestionQueueTombstonePolicy.merged orders tombstones that tie on discardedAt by id. Before, every pass rewrote deleted_documents.json and ingestion_queue.json in both roots. Two files in the iCloud root are what counted: the metadata query is scoped to that root and local writes during a pass are silenced by isSyncWriteInProgress. workspaceSignature hashes content-change dates, so each rewrite of those two read as a change from iCloud and set off the next pass and a reload about every 5 s (470 to 715 reloads an hour on the owner’s idle Mac, the app at 46% CPU, mds 33%, fileproviderd 30%). Still open: a reload saves the queue (RAGService+ChatHistory.swift:942), which posts .localWorkspaceDidChange. [evidence_level: test_verified (WorkspaceSyncFileWriteTests, IngestionQueueTombstoneTests) for the skipped writes and the tombstone order; code_verified (WorkspaceSyncService+FileCoordination.swift:492-496) for the notification gate; confidence: high; the owner's Mac at idle not yet re-measured]
  • 5.8, 2026-11-07: unreferenced document files are held, not deleted. The local file sweep in WorkspaceSyncService+LibrarySync.swift skips everything while an import or rebuild is unfinished, and otherwise moves a file no record or queue item names into OrphanedDocuments/ 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.swift is completely local-only. [evidence: code_verified, exact, SQLiteFullTextService.swift]
  • Conversations and their deletions sync (5.7, 2026-10-14): EvidenceThreadStore saves in <Application Support>/OpenIntelligence/EvidenceThreads/, the folder WorkspaceSyncService.synchronizeEvidenceThreads merges, and records a deleted conversation’s id in deleted_threads.json beside it; the merge joins that list across devices (mergeDeletedThreads) and removes those conversations on both sides, as deleted_documents.json does 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.reloadWorkspaceData reads documents_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 which documents changed 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’s RAGService, WorkspaceSyncService, ContainerService, EntitlementStore, SettingsStore and ModelResolutionService once, and every window’s ContentView observes 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 BGContinuedProcessingTask time (reembedDocuments), a library with a saved rebuild item gets the passages check at the relaunch (restorePersistedIngestionQueueIfNeeded calls evaluateSemanticIndexHealth), 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.json reaches 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 of ContentView and 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 a nonisolated async function runs on its caller’s actor, so every nonisolated async helper of the main-actor WorkspaceSyncService ran 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 shared containers.json (0x8BADF00D). All 30 nonisolated async functions of WorkspaceSyncService are now @concurrent, and RAGService.saveDocumentsToDisk makes its coordinated merge of documents_metadata.json in a detached task. The main-actor entry points (reconfigureIfNeeded and 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, waitUntilSyncFilesAreFree makes 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 pass removeOrphanedConflictCopies deletes 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, so conflictCopyCount can 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 and LibraryVisualizationEngine both 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.buildProfile hands plain arrays (vectors, texts, keywords) to analyzePassages, 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 from AtlasLabeling.terms(in:), plurals and longer forms listed). The main actor only assembles LibraryProfile. ProjectionService (PCA, random projection, t-SNE, UMAP) is nonisolated and Sendable, and the three map loaders (AdaptiveVisualizationsView twice, Embedding3DView once) run project3D detached; 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 and Embedding3DView’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"), scene by default, or chart) picks how the card and the full screen draw. With scene, Embedding3DSceneView(drawsScene: true) draws SceneViewContainer with the axis labels and the cluster (in All Libraries, library) names from AtlasSceneLabels, laid out as through 5.6, with 5.7’s rebuild key (SceneBuildKey); with chart, 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, AxisLabelInsets measured 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 through Embedding3DSceneView, which gives a caller with no tap handler AtlasChart3D: a Swift Charts Chart3D kept 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 and AtlasAxisKey beside 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), because chartXSelection, chartYSelection and chartZSelection on a Chart3D reported 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 on AtlasContentKey (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 through RAGService.atlasSamplesForAllLibraries: the embedding space (atlasEmbeddingSpace) with the most passages (atlasGroupChoice), at most visualizationPassageLimit passages 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 to metric_reports.jsonl in the local cache; nothing is sent anywhere. SystemModelTools in FoundationModelToolRegistry.swift can add the system’s OCRTool and SpotlightSearchTool (the app’s own Spotlight index only) to a session’s tools; both are off unless a UserDefaults switch is set, and createTools is 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.getTopTermsForContainer and getKeyPhrasesForContainer (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’s document_pages rows, so DocumentProcessor.storeText reads 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.swift did 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: SpotlightIndexService associates each library and document entry with its IndexedEntity, gives documents and passages no expiry, names a passage passage-<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 from RAGService.applyLoadedDocuments) removes the entries of documents that left, a list of document and library identifiers kept in localCacheDir() 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 by reloadWorkspaceData() to pick up sync-driven file changes. It compares each container’s on-disk signature (size + modification date across BNNSVectorDatabase.binaryFileURLs) and reloads only the stores that actually changed. It never evicts: BNNSVectorDatabase is 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 in WorkspaceSyncService. [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: synchronizeVectorStore skips 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 in UserDefaults (workspaceSync.vectorStoreSignatureDigests.v2 since 2026-11-13; .v1 is 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 first clearAll() 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), and synchronizeVectorStore is 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: mergeIngestionQueueIfNeeded returns early while OpenIntelligenceRuntimePaths.areOverridesPinned is set. localRoot there resolves through applicationSupportRoot(), 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 in applicationSupportRoot() on purpose: that function is also resolved by four coordinated* iCloud primitives and by BNNSVectorDatabase, so making it honour the override would silently redirect live iCloud sync into a temporary directory. The pin is only ever engaged by DebugRAGValidationHarness, 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.saveContainers used to start one detached task a save, so an older list could be written after a newer one, and reloadFromDisk (called before every reloadWorkspaceData()) 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 in UserDefaults on 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.json and walks it once (PassageFileIndex.scan) for a 72-byte PassageSlot per 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; search decodes only its top results. readableChunks() and allChunks() 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 by count(), passageRecords() and chunkCount(forDocument:), left out by search, chunks(forDocument:limit:), chunks(withIDs:) and readableChunks(), and makes allChunks() throw, because sync pairs that array with the vectors by position. Passages not yet saved sit in pendingChunks and 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:) and chunks(withIDs:) answer from the slots, and the other stores answer them from allChunks(). 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 through readableChunks(), the sync merge through allChunks()), 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 throws storeFailed and 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): saveToDisk writes new vectors before the metadata that lists them, and loadFromDisk trims 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.queryInternal clears transientConsentGrants before executeAgenticQuery, 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 reaches ContentView through CloudConsentRelay; 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 no ModelExecutionPlan runs on the device: FoundationModelRoutePolicy.determineRoute returns .onDevice when 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 uses PrivateCloudComputeLanguageModel on 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; ModelExecutionPlanner combines 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.fmPreference persists the user policy independently of runtime notifications. Chat captures Hybrid as post-retrieval choice, On-Device as onDeviceOnly, and PCC as cloudOnly; the picker label always renders that policy. ModelExecutionReceipt.completedTarget drives 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: EntitlementChecker uses native macOS SecTask declarations, 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. LiveFoundationModelCapabilityProvider snapshots quota/context state, maps unknown future quota cases to fail-closed .unknown, and FoundationModelSessionFactory rechecks 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.authorizesCloudExecution is the single rule deciding whether a quota state permits a cloud attempt; .belowLimit and .approachingLimit do, .limitReached, .unsupported and .unknown do not. Both canUsePCC and ModelExecutionReceipt.nonAuthorizingQuotaStates derive from it. Before 2026-08-11 they were two hardcoded copies and had diverged: the planner tested only != .limitReached, so .unknown authorized an attempt the route gate scores as unauthorizedCloudAttempts. Reachable in production because FoundationModelCapabilityProvider maps pcc.quotaUsage.status through an @unknown default. [evidence_level: code_verified+test_verified, confidence: exact, evidence_source: ModelExecutionPlan.swift, RouteEvalMetrics.swift, PCCQuotaAuthorizationTests.swift]
  • Foreground gate covers macOS: ModelExecutionPlanner permits cloud only when isForegroundInteractive || consentGranted. That input was computed under #if canImport(UIKit) with the #else branch hardcoding true, so the Mac had no foreground check and a backgrounded Shortcut could reach PCC unattended. macOS now reads NSApplication.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.swift using self.settings scope 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; ModelExecutionReceipt persists intended/attempted/actual/fallback/completed targets. [evidence_level: code_verified, confidence: high, evidence_source: RAGService.swift, AgenticOrchestrator.swift, ModelExecutionReceipt.swift]
  • Consent Persistence: cloudConsent.applePCC is the canonical remembered decision and wins over stale pcc.setting compatibility state. Startup loads/migrates consent but never creates a consent record or opens the sheet; only a finalized post-retrieval transmission record can populate pendingCloudConsent. [evidence_level: code_verified+test_verified, confidence: high_pending_physical_device_validation, evidence_source: SettingsStore.swift, RAGService.swift, PCCConsentPreferenceMigrationTests.swift]
  • GPU Execution Policy: GPUExecutionProfile migrates the old numeric preference into four discrete profiles. DeviceCapabilityService is 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, and preprocessImageForOCR prepares every scanned page on its Metal context in every profile), large Metal vector/MMR gates, and background GPU eligibility, which BackgroundGPUAllowance states per device for both BackgroundTaskService and 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 no ModelExecutionPlan is the exception Docs/PRIVACY_AND_ROUTING.md names. [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 through RAGService.isAppGuide), and the library limit ContainerService.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.swift and EntitlementStore.swift are unchanged. Detail in Docs/BILLING_AND_LIMITS.md. [evidence_level: test_verified (GuideLibraryTests, LibraryDocumentCountTests), confidence: high]
  • UserDefaults: EntitlementStore.swift relies 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 reaches EntitlementStore through the Transaction.updates listener in StoreKitBillingService, and on iOS 27 and macOS 27 the sheet also calls reconcileEntitlementsOnLaunch() 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 AppShortcutsProviderTests fails 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.swift was 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 from IntentSupport.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 in RAGAppIntents.swift built RAGService() and every new engine re-pointed that weak reference at itself; the engine’s initializer (RAGService.swift) now registers only when none is registered, and ContentView registers the app’s. The ask actions share AskActionRunner: the engine’s default generation settings, an OIAnswerEntity as the returned value, a thrown OIIntentError on failure, and for the two with a mode menu (OIAnswerMode on “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 a RAGQueryScope, and the runner refuses an answer whose passages are not all from those documents. Seventeen of the twenty-two return a value (ReturnsValue on 17 of the 22 perform() functions under Services/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 through AppNavigationRequest and return nothing; “Ask About an Image” and “Search with a Photo” (VisualIntelligenceIntents.swift) return their text as a value and throw OIIntentError on failure since 2026-10-09 (through 5.6 they returned nothing and reported a failure as a successful result). Items: OIDocumentEntity and OILibraryEntity carry properties and a document transfers as its file; OIPassageEntity and OIAnswerEntity transfer as text with their source, and from 2026-10-20 are items the system looks up by id from HandedOutItems (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); OIThreadEntity lists saved conversations. An engine built while the app is closed has no entitlement store: createNewThread reads 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 a VerificationJournal.Span("intent.<Type>") in perform() and record ok, failed (with the error’s type) or cancelled, with the duration. AppNavigationRequest.post records 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 ten AppShortcut entries are unchanged. scripts/phone_evidence.py reads 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.swift is unchanged: an intent.longRunning span in AskActionRunner.runLong, a mode field on intent.QueryDocumentsIntent and import.statusAsked in DocumentImportStatusIntent are 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

  1. PCC routing/consent
  2. Apple Foundation Models
  3. iCloud/workspace sync
  4. StoreKit / Billing
  5. 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.swift and presented through ThreadSidebarView.swift inside ChatScreen.swift. Clearing the conversation (ChatScreen.clearChat) or deleting one in ThreadSidebarView also 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, group Tour.threads), used up by a swipe-delete (Tour.used in .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.swift using 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 reads localRoot/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), and coordinatedWriteData posts .localWorkspaceDidChange for 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 ListEvidenceThreadsIntent and CreateNewEvidenceThreadIntent App Intents for Siri/Shortcuts, utilizing ThreadListSnippetView snippets. Resolved in-process on the presented RAGService.activePresentedInstance to reload and populate presented UI screens instantly, accepting optional OILibraryEntity parameter 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 with AnswerSentenceSplitter and returns the text untouched unless it removes a repeat; sentences whose numbers or codes differ are never repeats. (2) VerificationGateService.runGateE passes 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 through CitationLinker. 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 is partial when any claim is partial and notSupported otherwise. 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, and RAGEngine.assembleContext numbers 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 through RAGService.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:)). finalizeResponse logs a label past the answer’s passages and leaves the text. CitationLinker, the source-list half of AnswerShareFormatter and AnswerPreview live in Services/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/&lt;containerId&gt;/*.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-18): a rebuild in place now survives sync, and a Granite library whose vectors are still another model’s is repaired. Through f5759e4d WorkspaceSyncService.mergeVectorChunks kept the first copy of a passage it met and met the iCloud copy first, and a rebuild in place keeps every passage’s id, text and createdAt. So the next sync pass wrote the iCloud copy’s old vectors back over each rebuild, and the iCloud copy never changed (owner’s iPhone, 2026-11-14 16:43:06 re-embedded 126 passages, 16:43:10 local store rewritten and “Shared vector store already current”) [measured]. That the 2026-11-14 note’s five libraries “his Mac had finished minutes earlier” were the Mac’s rebuilds undone the same way is [inferred] from the code; no Mac trace was read. The rebuild now dates each passage one millisecond after its own time (DocumentChunk.reembedded), the merge keeps the newer copy of a passage by id or by document, place and text (ties keep the iCloud copy), and a passage stored without a time decodes as the oldest. RAGService.storedVectorsAreAnotherModels, called from the index-health check (checkVectorsAndDocuments) once a launch per Granite library until a check under the live model revision finds its vectors live, embeds one stored passage of each document again (at most 64 documents) and re-embeds in place, through the self-healing queue, the documents whose passage scores under 0.5 (StoredVectorModelCheck.anotherModelCeiling); once per model revision, after which a library still failing, or one whose repairs were stopped, shows the rebuild banner (StoredVectorModelCheck.repairAction). A library it flagged is the only place Gate E may decline to judge (RAGService.librariesWithAnotherModelsVectors, passageVectorsMayBeAnotherModels). Libraries that translate before embedding are skipped (the translation is not stored). [evidence_level: test_verified (VectorMergeKeepsReembeddedVectorsTests, StoredVectorRepairTests, GraniteGroundingFloorMeasurementTests), measured (device trace), confidence: high for the mechanism; the repair not yet seen on a device]

5.8 (2026-11-14): a device does not rebuild a library whose vectors are already the live model’s. EmbeddingModelRecord is 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.storedVectorsAlreadyMatchLiveModel embeds 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. Journal index.modelCheck carries 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.mlpackage is now Granite (two fixed-shape functions, len256 and len512; CLS vector and L2 normalisation in the graph; 8-bit linear weights, 48.7 MB; cosine 0.99990 against Hugging Face; built by scripts/build_embedding_model.py), loaded from a fixed path (RerankerModelLocation). CoreAISentenceEmbeddingProvider.isAvailable is false, EmbeddingModel.bundle is an empty placeholder (Package.swift lists it), and EmbeddingService.forProvider resolves the Core AI id to Core ML, so a Core AI library takes the provider-change branch of resolveEmbeddingContext (vectors cleared, rebuilt). A Core ML library whose vectors came from another model is told apart by EmbeddingModelRecord (per device) and is rebuilt at once, not flagged: the new model’s query vectors cannot search the old model’s. The check runs in evaluateSemanticIndexHealth, 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 by preferredComputeUnits and embeddingComputeUnitsDuringIngestion); it was the CPU alone. iOS 27 needs com.apple.developer.background-tasks.continued-processing.inference for 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-18, the units follow the app. The background units were chosen only when an import began, so an import started in front kept a model loaded for all units after the app was left, and with no GPU grant its predictions waited until the task expired (owner’s iPhone, 2 min 20 s). CoreMLSentenceEmbeddingProvider.loadedModels() now reads isBackgroundCPUSafeIngestionProfileActive on each embed during an import and reloads for backgroundComputeUnits or for the import’s own units (ingestionForegroundUnits) when it changes. The ingestion-mode state (isIngestionMode, wantedComputeUnits, ingestionForegroundUnits, hasLoadedModel) is guarded by modeLock, not modelLock, so a mode switch on the main actor never waits for a load (a 10 s watchdog kill on the iPhone the same day); lock order modelLock then modeLock. [evidence_level: measured (iPhone journal, trace and crash report), code_verified; confidence: medium; the iPhone background run after the change not yet seen]

5.8, 2026-11-19, outside an import too. The 2026-11-18 rule applied only during an import. A question being answered when the app left kept the model loaded in front for all units, and the source check’s embedding waited 2 min 10 s with no answer (owner’s iPhone, 08:17:44 to 08:19:54, and again 08:12:40 to 08:14:51) until the background time ended. CoreMLSentenceEmbeddingProvider.loadedModels() now loads DeviceCapabilityService.embeddingComputeUnitsInBackground for any embed in the background and the device’s own units again for the next embed in front, unless a failed prediction moved the model to the CPU. “In the background” is DeviceCapabilityService.isAppInBackground, set by ContentView on every scene-phase change on iPhone and iPad (the import profile flag is true only during a background import), and the retry after a failed prediction loads the background units first when the app is there. The first load, a pending switch and an import running in the background without a continued-processing task follow the same flag (09:25, a first embed after an install loaded all units in the background). prediction(from:length:model:) also checks at the start of every prediction: a model on the GPU while the app is in the background reloads with the background units before predicting. [evidence_level: measured (phone trace), build_verified; confidence: medium until an answer left mid-check is seen finishing on device]

5.8, 2026-11-19, the background form is compiled in front. That switch compiled the background form from nothing the first time after an install: 41.3 s on the owner’s iPhone (10:36:36 to 10:37:17), longer than the 27 s of background time iOS gave, so a question asked while leaving paused until he came back. EmbeddingModelWarmup now calls CoreMLSentenceEmbeddingProvider.prepareBackgroundForm() after preparing the front form, which loads the model once with the background units (iOS devices only, and only where they differ from the front units) and lets it go; Core ML keeps the compiled form, so the switch on leaving loads it in a fraction of a second. [evidence_level: measured (phone trace) and build_verified; confidence: medium until a question asked while leaving, after a fresh install, is seen finishing]

5.8, 2026-11-19, warm-up on coming forward. EmbeddingModelWarmup and RerankerWarmup also start a second after the app comes to the front, once per launch (scheduleOnForeground, ContentView on .active), so a launch into the background no longer leaves the first question to pay the first loads. [evidence_level: build_verified; confidence: medium]

5.8, 2026-11-19, a rate limit and Siri. The rate-limit ladder in RAGService+Generation.swift waits for the app to come forward only for an answer asked in Chat (RAGService.answerAskedInChat); a question from Siri or Shortcuts asks once to come forward (bringAppForwardForConsent) and otherwise runs its retries and fails, so AskControl’s heartbeat no longer keeps an action alive with no work behind it. [evidence_level: measured (phone trace 09:15:13), build_verified; confidence: medium]

5.8, 2026-11-08, embedding input. Every import path embeds a passage as RAGService.passagePrefix writes 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.forProvider hands every Core ML service one provider, EmbeddingService.sharedCoreMLProvider, as the Core AI path already used CoreAISentenceEmbeddingProvider.shared. It built a new CoreMLSentenceEmbeddingProvider on every call, and each new one loaded the tokenizer and the 43 MiB model again before its first vector; a search calls forProvider, 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 that IngestionModeSwitchTests pins between them rather than bit for bit. Imports from the queue run one at a time, and RAGService.addDocument counts 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. CoreMLSentenceEmbeddingProvider is nonisolated and @unchecked Sendable, with @concurrent embed and embedBatch. 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, wantedComputeUnits and isIngestionMode under modelLock, the tokenizer reference under tokenizerLock; the buffer pool was already an actor. isAvailable checks 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. embedBatch loads the model once before fanning out, so a reload (up to about 2.4 s) does not block every task of the batch on modelLock. The app also carries com.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’s capabilityType cannot 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. DeepThinkRetrievalGoldenTests holds 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; addDocument passes 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): enableIngestionMode and disableIngestionMode record the wanted compute units and loadedModel() 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.preferredSentenceProviderId in EmbeddingService.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.countTokens returned a constant, since it reads encode().count and a padded encode is always the pad width. Logged maxTokens=128/430 on 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.swift using dynamic NDArray and InferenceFunction.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 in ContainerSettingsSheet. The exported PyTorch graph output is explicitly bound to “embeddings” in compile_core_ai_model.py and 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.mlirb and Core ML runs the .mlpackage, both over the same all-MiniLM-L6-v2 weights. Until the mean-pooling re-export, Core AI took input_ids only and returned last_hidden_state[:, 0, :] — the CLS position — while Core ML took attention_mask and mean-pooled in Swift. all-MiniLM-L6-v2 is 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; strings on the new main.mlirb lists input_ids, attention_mask and embeddings, where the previous artifact listed only the first and last. EmbeddingProviderAgreementTests pins the two providers to cosine > 0.99 on identical text, but skips in the simulator — Core AI resolves no model resource there and sets isModelLoadingFailed before attempting a load, so this invariant is device-only and the vectors themselves remain unverified. A benchmark-only override in EmbeddingService.forProvider, keyed on the benchmarkEmbeddingProvider user default and set only by DebugRAGValidationHarness from a launch argument, makes the two comparable in one run; it is absent in a shipping app. Paired over 21 comparable cases the swap moved vector r@1 from 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-time mlassetc version-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 EmbeddingService routed iOS/macOS 27+ to Core AI and older systems to Core ML. From 5.7 the default follows the platform: EmbeddingProviderDefaults.preferredSentenceProviderId answers 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 SettingsStore and RAGService recommended and switched to the Core AI provider on supported hardware, falling back to CoreMLSentenceEmbeddingProvider on older targets. From 5.7 they ask EmbeddingProviderDefaults, and auto-tuning never moves an existing library between the Core ML and Core AI copies of the model (EmbeddingProviderDefaults.areCopiesOfOneModel, asked by RAGService.evaluateEmbeddingShift), because a provider change clears a library and embeds it again. Ingestion mode scoping is strictly enforced per-document in RAGService.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.md defines 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.py scores task wording and changed paths against Docs/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 includes CHANGELOG.md [Unreleased], the active-version section in Docs/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: RetrievalTraceCollector records 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.score is 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.stageMetricsLines emits STAGE METRICS (the Swift-computed scores) and STAGE SOURCES (the ranked identities they were computed from), plus ExpectedSources and the resolved ExpectedSourceIds. run_quality_matrix.py transports 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 SOURCES carries <chunkId>#<documentId>#<name>. Chunk identity is required because RAGEngine.reciprocalRankFusion keys on chunk.id; document identity is required because relevance is judged per document. Emitting only the display name left the five pre-rerank stages recording (unnamed), since sourceDocument is attached by RAGService after 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, reciprocalRankFusion and both cross-encoder sorts in RAGEngine. They now break ties by HybridSearchService.byScoreThenId and, in RAGEngine, by HybridSearchService.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.py reconstructs 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 recorded fusion stage 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 RetrievalTraceCollector and RetrievalStageMetrics compile into the app. RAGEvalRunner has zero call sites repo-wide, so the in-app half of evaluation cannot currently be invoked; every measurement goes through run_quality_matrix.py driving DebugRAGValidationHarness. [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 that SourceOnlyAnswerService.candidateCoverageBeforeModel works 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.withTablesForSummaries replaces a tableSemantic candidate with its tableStructural siblings in Standard’s context candidates and in every Deep Think and Maximum search result (RAGService+ToolHandler.swift). Details in Docs/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.ensureAnswerResponds rewrites 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 appends answers:<verdict> to the gating string that VerificationOutcome reads. Details in Docs/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.createNewThread keeps 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:) and preloadChatHistory(for:) open it instead of the most recent saved conversation (unsavedNewThread). It also deletes the library’s saved model transcript, which TranscriptPersistenceService keeps 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 in Docs/PRIVACY_AND_ROUTING.md). Deep Think waits before an on-device model call while the app is in the background (waitBeforeModelCallWhileInBackground), and PendingAnswerStore lets 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 in Docs/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 by notFoundAnswer (ensureAnswerResponds, isDegenerateAnswer); isOrphanListMarker needs 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). RetrievalAblation switches each rule off in development builds; AgenticOrchestrator.executeMultiQuerySearch reads it for the blend weights. Record: BenchmarkRuns/2026-11-10-rule-audit/README.md; detail in Docs/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.computeTOCPenalty returns 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.namesAStatisticalValue makes a question naming a ratio, rate, percentage, odds, p-value, interval, mean, median or similar a value question, so shouldUseContextualDefinitionLookupMode no 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 a streamCutOff response 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.showAfterSeconds is 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 (journal reranker.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 in OpenIntelligenceApp.swift, before any model loads), since a new version recompiles once regardless. RerankerWarmup holds iOS background time around the load (RerankerSetupBackgroundTime, about 30 s, journal reranker.backgroundTimeExpired when taken back) and shows setup in the Dynamic Island and on the Lock Screen (SearchSetupLiveActivity, the answer’s Live Activity with isSetup, 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.factCheckedAgenticAnswer checks each claim the structured answer lists with VerificationGateService.claimVerdicts (Gate B’s per-claim check) and StructuredAnswer.withClaimVerdicts fills 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.executeMultiQuerySearch runs the first executeFullRetrievalPipeline call 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 pass skipContinuation: 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. execute now clears that handler for the run and parks the chat’s in finalAnswerHandler; four final-answer calls (reasoning-chain synthesis for Deep Think, core and exhaustive synthesis for Maximum, direct synthesis) stream through answerHandler. 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. executeReasoningChain builds 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 (in SessionEvidencePlan.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, 5,986 on 8,192 (it stopped at the 3,200-token reading ceiling there until 2026-11-18). 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] The window decides the final step’s evidence (5.8, 2026-11-18). At an 8,192 window, lifting the 3,200 ceiling gave Deep Think 49 of 53 table questions right against 47 (2 better, 0 worse, median 96 s against 104 s; final prompts 3,384 to 3,577 tokens with the ceiling, above 4,000 for all 53 without). RetrievalAblation.synthesisFullWindow switched off restores the ceiling. A 4,096 window is unchanged (1,890 is below 3,200). [evidence_level: measured, confidence: medium (one run per arm, retrieval is nondeterministic), evidence_source: BenchmarkRuns/2026-11-17-synthesis-ceiling, iOS 27.0 Simulator copy with the Mac's AFM 3 Core Advanced, window held at 8,192; not run on an iPhone] 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.) What DeviceCapabilityService.optimizedAgenticConfig changes 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 (maxSteps 5, 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 at maxSteps - 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”) showed maxSteps as 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 = true is 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. executeRecursiveResearch implements the real thing: it asks the model to decide, parses .answer or .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 on answerIndicatesRetrievalMiss(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. Meanwhile FactBank had 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. ReasoningChainResult now carries evidenceCoverage, evidenceCoverageTarget and unansweredQuestions, 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. researchMayReplaceSynthesis now 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 of executeRecursiveResearch’s two call sites and the one Deep Think reaches (maxIterations: 3), had kept only shouldAcceptReplacement. Both of its replacement points now go through

5.8, 2026-11-19, “[S#]” is removed from every agentic answer. cleanupFinalAnswer runs removingPlaceholderCitations first: the prompts’ placeholder “[S#]”, copied by the on-device model in place of real labels, is removed with any “as documented in” that only led into it. [evidence_level: measured (owner's iPhone screenshots 13:46 and 13:47) and test_verified, confidence: high]

5.8, 2026-11-19, research instructions never replace an answer. parseResearchDecision reads a decision reply that carries both “[ANSWER]” and “[SEARCH: …]” as the search, and AgenticOrchestrator.shouldAcceptReplacement turns away any replacement carrying either token, which covers both call sites of executeRecursiveResearch (the chain’s and the Self-RAG loop’s). On the owner’s iPhone “[ANSWER] All three quality modes are: Maximum, Free, and Pro. [SEARCH: quality modes]” had replaced an uncited Deep Think synthesis that was right. [evidence_level: measured (phone trace 13:09:29) and test_verified (AnswerReplacementGuardTests), confidence: high] loopResearchVerdict, 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 .keep still 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). loopMayRunResearch now 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 with AgenticOrchestrator.answerFirstInstruction, one sentence that answers the question with its value and label before the full answer, and adds noFalseAbsenceInstruction; RetrievalAblation.answerFirst switches both off for the paired benchmark. [evidence_level: code_verified, confidence: high] Maximum, 2026-11-13: synthesizeFinalUnlimitedAnswer puts the top retrieved passages (labelled by their place in sourceChunks, fitted with ChainSynthesisEvidence.choose) before its claim bank (maximumSourcePassagesPrompt, finishFinalUnlimitedAnswer), and skips the claim-bank refinement on that path; RetrievalAblation.maximumSourcePassages switches it off. [evidence_level: code_verified, confidence: high]

  • Synthesis truncation was removing the highest-ranked chunk, and it is now budgeted rather than cut. executeDirectSynthesis and executeSynthesisStep each ended in a hardcoded prefix(3000). Because executeFullRetrievalPipeline closes with a Lost-in-the-Middle reorder that places rank 0 at the array midpoint, and executeSearchStepWithChunks renders only chunks.prefix(10), a large retrieval reached synthesis with its best evidence already gone. Both sites now pack against a budget derived from FoundationModelTokenBudget and the actual prompt, fill in score order, and log chunks and tokens dropped. executeSynthesisStep also 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 in RAGService step 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 in Docs/RETRIEVAL_PIPELINE.md item 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.appiconset catalog retains the existing light icon and adds a universal iOS luminosity=dark rendition using AppIcon-dark-1024.png. Xcode’s asset compiler packages the dark rendition as UIAppearanceDark; 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:

  1. It reads the intent, not the quality mode. RAGQualityMode.temperature is 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.

  2. It is pure. applyingAdaptiveProfile returns a modified copy and writes nothing. AutoTuneService adjusted the same two settings by persisting them into UserDefaults, 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.

  3. 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 useAgentic return and mutates inferenceConfig directly. Deep Think and Maximum leave before that point through executeAgenticQuery, which reads neither inferenceConfig nor the config parameter for generation: it builds optimizedConfig from the device’s tier for Deep Think (DeviceCapabilityService.optimizedAgenticConfig()) and from qualityMode.agenticConfig, the .unlimited preset, for Maximum, and takes only the routing choice from config (UserRoutingPreference(config:)). RAGQualityMode.agenticConfig’s .thorough for Deep Think is never used. (Corrected 2026-10-20: this said optimizedConfig comes from qualityMode.agenticConfig in 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 in executeAgenticQuery and held for the life of the query, then cleared. That is the same pattern as activeUserRoutingPreference, and for the same reason: the agentic path generates across many sessions, so threading a per-query value down through AgenticOrchestrator to every call site costs far more than the fact it carries. generateWithProperConsent takes temperature: 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.

    maxTokens is 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.

  4. 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]

Which Model Parameters reach an answer (2026-11-18, 5.8)

Settings › Advanced (ModelConfigurationSheet) holds only controls an answer path reads. The stored keys (SettingsStore.Keys, ChatScreen’s @AppStorage, InferenceConfig fields) are unchanged, so saved values load.

ControlReachesEvidence
Temperature (0 to 0.4)Standard only; capped at 0.4, or 0.2 for Evidence-First and High PrecisionRAGService+QueryAnswer.swift:597, :602, :607
Sampling strategy, seed; Top-K and Top-P (DEBUG builds only)Standard onlyInferenceConfig from ChatScreen+Sending.swift; Deep Think and Maximum build their own config per call, RAGService+Agentic.swift:109-113, :184-188
Context window (read only)Shows FoundationModelTokenBudget.reportedOnDeviceContextSize; hidden when nilthe prompt is sized from FoundationModelTokenBudget.contextSize, not llmContextLength
Removed: penaltiesnothingno penalty field in GenerationOptions; only reader LocalOpenAIServerLLMService.swift is #if false
Removed: System Promptthe empty-library answer only (RAGService+QueryExits.swift:794)Standard replaces it before every answer (RAGService+QueryAnswer.swift:574, :586)
Removed: Max Tokensthe first pass’s maximumResponseTokens onlycontinuations take the room left in the window (AppleFoundationLLMService.swift:1327-1334)

The Standard passage budget (RAGService+QueryPipeline.swift:550-555) no longer charges inferenceConfig.systemPrompt, since that prompt never reaches a Standard answer; the Standard prompt that replaces it was not charged before this change and is not now (promptOverheadTokens = 120 + toolSchemaTokens), and an overflow is caught by the overflow retry. [evidence_level: code_verified, confidence: high, evidence_source: the files and lines named in the table, read 2026-11-18]

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)

StepWhat moved
I01Step AB (the import’s ProcessingSummary from its timings, counts and chunk statistics, with the library’s embedding provider) into makeProcessingSummary
I02AA (document) (rebuilds the imported Document with its complete processing metadata, the file hash and the import’s library) into buildCompletedDocument
I03AA (size) (formats the file’s size in MB as the B, KB or MB string the summary and telemetry show) into formatImportFileSize
I04U (pairs each passage with its vector and contextual prefix into DocumentChunk records and emits the Chunks prepared event) into buildDocumentChunks
I05S (inputs) (builds each passage’s contextual prefix and the token-limited text to embed, translating first when the library asks for it) into buildEmbeddingInputs
I06AF (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
I07AE (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
I08AC (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
I09Y (teaches the library’s vocabulary every passage and the Vision-detected entities, records the document, and emits Vocabulary learned) into learnImportVocabulary
I10X (builds the FTS5 rows (with structured table metadata) for every passage and stores them in the chunk-level full-text index) into storeChunksInFullTextIndex
I11W (indexes every passage in Spotlight when the setting allows it, then emits Chunks stored) into indexChunksInSpotlight
I12T (shows the indexing and storing stages with the embedding figures and emits Embeddings generated) into reportEmbeddingStats
I13S (vectors) (shows the embedding stage and generates every passage’s vector with live progress, using the import’s checkpoint folder as cache) into generateChunkEmbeddings
I14R (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
I15Q (shows the chunking stage with the extraction’s live metrics and yields so the interface can draw it) into showChunkingStage
I16P (lists the document in Spotlight when the setting allows it and records that it did, so a failed import removes the entry) into indexDocumentInSpotlight
I17O (counts the document’s characters, words and per-passage word statistics and emits Extraction complete) into measureExtraction
I18N (reads and cuts the document into passages and journals how long the main thread went unanswered meanwhile) into parseDocumentForImport
I19L (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
I20J (installs the document processor’s text and rich progress handlers, which move the tracked item through its extraction stages) into installProgressHandlers
I21G (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
I22C (computes the file’s hash (nil when it cannot be read) and records it with the storage path on the tracked item) into hashAndRecordDocument
I23B (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)

StepWhat moved
Q019 (response) (builds the response metadata and the RAGResponse and logs the total time) into buildStandardResponse
Q029 (gating) (builds the gating summary, final warnings and the structured answer) into summarizeGatingAndWarnings
Q038 (calibrates confidence and logs and emits the pipeline completion) into calibrateConfidenceAndLogCompletion
Q046g (log) (logs the model, timing, length and token rate of the generated answer) into logGeneratedResponse
Q056 (telemetry) (measures the generation time and emits the ‘Response generated’ events) into emitGenerationTelemetry
Q066 (chain gate) (decides whether the developer-forced reasoning chain runs) into decideReasoningChain
Q076 (history) (adds conversation history or memory to the prompt and decides whether citations are required) into buildGenerationPrompt
Q086 (output budget) (caps maxTokens to the room left after the context and applies the procedural and trivial adjustments) into capGenerationTokens
Q096 (prompt) (writes the intent-specific system prompt and the temperature caps into the generation config) into composeStandardGenerationConfig
Q10SV (computes the pre-generation confidence and decides whether the Evidence-First prompt is used) into assessEvidenceBeforeGeneration
Q115 (citations) (logs the assembled context, lists the passages the prompt labelled and records them for recovery) into finishIncludedPassages
Q12 to Q21Q12, 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 Q31Q22, 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 Q41Q32, 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 Q51Q42, 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 Q61Q52, 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 Q66Q62, 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 E07E01, 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 E14E08, 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.

WasNow
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]

Sizes read from the device, not a chip list (added 2026-11-17, for 5.8)

On a Mac, scanned pages are read one per performance core (hw.perflevel0.physicalcpu), at most one per 2 GB of memory and 16, never below the chip generation’s value (DeviceCapabilityService.hardwareScaledVisionConcurrency; an M3 Pro keeps 6), before the thermal limit applies. GPUComputeService picks its Metal buffer cache tier by chip generation, so a chip newer than any list lands in the top tier, and on a Mac takes a 256th of recommendedMaxWorkingSetSize (at most 256 MB) when that is larger: 53 MB on the owner’s M3 Pro, where it was 32 MB (measured 2026-11-17). iPhone and iPad keep their values. The on-device window is SystemLanguageModel.default.contextSize everywhere (4,096 on the owner’s iPhone 16 Pro Max on iOS 27.0.1, 8,192 on 27.2.1 and on the M3 Pro). The rule and its sources are Docs/ai/DECISIONS.md 2026-11-17 and the scale-to-the-device skill. [evidence_level: code_verified, build_verified on iOS and macOS, measured on the M3 Pro for the cache, not measured on M4 or later, confidence: high, evidence_source: DeviceCapabilityService.swift, GPUComputeService.swift, commit 3fb31070]

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]