Canonical OpenIntelligence Source of Truth
Corrected 2026-10-20 against the working tree (
b868fc0plus the 5.7 work in progress): two claims in section 3 are corrected where they stand. The predictive pre-scan tunes the chunking plan, not extraction, and the tokenizer’s “100x speedup” was never measured. Section 4 gains seven false claims, six about the agentic loop and one about the vector index. Section 8 gains what a new install starts with, the rule that decides Private Cloud Compute, and where Deep Think and Maximum can reach it. Section 19 is new: the three answer modes, the agentic loop, its stop rules, its tools and its checks, as the code runs them, with the shipped 5.6 and the unreleased 5.7 told apart where they differ. Every new line was read in the code on 2026-10-20 at the file and line it cites, and nothing was built or run, so the tags say code_verified, not measured. Swift file paths in the new tags are relative to the app folder,OpenIntelligence/. A second review the same evening corrected sections 4, 8 and 19 where they had gone past the code (the planning call, the step cooldown, the abstain flag, the research retries, the ultra tier, the agentic label, what a cloud synthesis carries and the deterministic plan), and re-pinned everyRAGService.swiftline to the working tree as read at 22:17 that night (22,746 lines). That file is still changing, so a tag names the function where a line may move.
1. Purpose and Supersession Rule
This document is the absolute ground truth for the OpenIntelligence repository architecture. It supersedes all other markdown documentation, comments, and developer notes. If another document contradicts this file, that document is considered stale or hallucinated.
2. Current Product Definition
OpenIntelligence is a local-first, privacy-preserving retrieval-augmented generation application for Apple platforms, leveraging on-device intelligence.
3. Safe Claims
- The app uses iCloud Drive (Ubiquity containers) for sync via
NSFileCoordinatorandNSMetadataQuery.[evidence: code_verified, exact, WorkspaceSyncService.swift] - The public execution targets are
SystemLanguageModel.defaulton-device and, on iOS/macOS 27+,FoundationModels.PrivateCloudComputeLanguageModel. There is no app-selectable public 3B/20B/Advanced model API. The source PCC entitlement is enabled following user-confirmed Apple approval.EntitlementCheckeruses public platform evidence: native macOSSecTask, the embedded signed provisioning profile for iOS/Catalyst development and ad-hoc builds, and Apple’s documented PCC availability/quota APIs when App Store/TestFlight omits that profile. The session factory rechecks availability and quota immediately before construction. The branch is generic arm64 iPhoneOS compile-verified. iOS/macOS 26 is local-only—local execution is never represented as simulated PCC. Signed installation and distribution behavior are not yet runtime-verified.[evidence_level: build_verified+sdk_verified+user_confirmed, confidence: high_for_source_unverified_for_distribution, evidence_source: LLMModel.swift, EngineSDKCompatibility.swift, FoundationModelCapabilityProvider.swift, FoundationModelSessionFactory.swift, OpenIntelligence.entitlements] - PCC route selection occurs after local retrieval.
ModelExecutionPlannerconsumes pre-retrieval constraints, post-retrieval evidence, live capability/quota state, and exact-or-labeled-fallback context budgets. The selected cloud stage receives a minimized evidence envelope only after valid consent; deterministic verification remains local.ModelExecutionReceiptseparates intended, attempted, actual, fallback, and completed routes and is persisted optionally for backward compatibility.[evidence_level: code_verified, confidence: high, evidence_source: ModelExecutionPlanner.swift, RAGService.swift, ModelExecutionReceipt.swift, RAGQuery.swift] - GPU-capable application work uses four persisted execution preferences (Efficiency, Balanced, Performance, Maximum), not a claimed utilization percentage. The preference gates an extra Core Image pass over rendered PDF pages (the raster is CPU work, and
DocumentProcessor.preprocessImageForOCRprepares every scanned page on its Metal context, in every profile), the Core ML embedding model’s compute units at its model-load boundaries, sufficiently large Metal vector/MMR paths, and background GPU eligibility per device (BackgroundGPUAllowance); Apple frameworks retain final device scheduling control. It does not reach Apple’s language model, the reranker, or a Core AI library, which runs on the GPU in every profile. While the app is open Maximum runs the same rules as Performance (5.7).[evidence_level: code_verified+test_verified, confidence: high_pending_device_thermal_validation, evidence_source: DeviceCapabilityService.swift (engagement is built from coreMLComputeUnits, embeddingComputeUnits, cleansScannedPagesOnGPU, searchesLargeLibrariesOnGPU), SettingsView.swift, RAGEngine.swift, BNNSVectorDatabase.swift, BackgroundTaskService.swift; ExecutionProfileLadderTests, BackgroundGPUAllowanceTests] - Relational metadata indexing relies on a single shared SQLite file with column-based
container_idisolation.[evidence: code_verified, exact, SQLiteFullTextService.swift] - Billing entitlements are stored in
UserDefaults.[evidence: code_verified, exact, EntitlementStore.swift] - Core AI embeddings are used in production, and the model they run is
sentence-transformers/all-MiniLM-L6-v2, not an Apple-authored embedder.THIRD_PARTY_NOTICES.mdbinds the bundledEmbeddingModel.mlpackageto that model, which is the strongest provenance in this repository because the attribution is legally required. Core AI is an Apple framework and the zero-copy Silicon-native execution is real; the weights are third-party and 384-dimensional. The two provider options in Library Settings are therefore the same weights on two runtimes, so choosing between them changes latency and not accuracy, with one caveat recorded 2026-10-10: the Core ML copy is half precision and the Core AI copy single precision, how closely their vectors agree has not been measured, and a library stays on the provider it was built with. Through 5.6 a library made on iOS 27 or macOS 27 used Core AI, falling back to Core ML. From 5.7 a new library on iPhone and iPad uses the Core ML copy and a new library on macOS 27 uses the Core AI copy (EmbeddingProviderDefaults.preferredSentenceProviderIdinEmbeddingService.swift), and no existing library is moved. The Core AI copy fails Neural Engine validation at its attention-mask step and runs on the GPU: on an iPhone 16 Pro Max it embedded 88.5 passages a second against 115.8 for the Core ML copy on the CPU and Neural Engine (2026-10-10), and on an M3 Pro Mac it took 4.71 ms a passage by default against 112.26 ms CPU-only (2026-10-12).[evidence_level: measured for the rates; test_verified for the default (LargeLibraryCostTests), confidence: medium, evidence_source: EmbeddingService.swift EmbeddingProviderDefaults; Docs/ai/DECISIONS.md 2026-10-10]The compiled model is bundled inside a custom raw resource folder (EmbeddingModel.bundle) to bypass Xcode build-timemlassetccompiler checks that block minimum deployment targets below 27.0.[evidence: code_verified, exact, CoreAISentenceEmbeddingProvider.swift, Package.swift] - Ingestion pipeline runs zero-copy
CGImageVision OCR/Structure processing, page-level JSON checkpoints underlocalCacheDir(), parallel ingestion concurrency locks (usingNSRecursiveLockaround CGImage rendering), and a predictive pre-scan (viaLibraryIntelligenceCenter) that tunes the library’s chunking plan before indexing begins.[evidence: code_verified, exact, DocumentProcessor.swift, RAGService.swift, LayoutAwareExtractor.swift, StructuredDocumentParser.swift, PageComplexityAnalyzer.swift]Corrected 2026-10-20: this said the pre-scan self-tunes “extraction configurations”. It runs only when the library’sautoAdaptDimensionis on, which it is by default for a library created in the app, and before each import it writes a chunking directive (strategy, word window and overlap) on the library. It does not change how text is extracted, andDocumentProcessorclamps the window and the overlap to the chunker’s 260-word target and 50-word overlap before cutting. The directive asks for 280 to 420 words with an overlap of 50 to 70, so with one in place every file type is cut at about 260 words with a 50-word overlap, and the per-type presets apply only to a library with no directive.[evidence_level: code_verified, confidence: high, evidence_source: RAGService+Import.swift:618-648 (the pre-scan, LibraryIntelligenceCenter at RAGService.swift:45) and RAGService+SelfTuning.swift:77-87 (chunkingOverride), Core/Models/KnowledgeContainer.swift:172 and :226 (on by default), AdaptiveEmbeddingOptimizer.swift:241 recommendChunkingPlan and :296-337, DocumentProcessor+Import.swift:404-427, SemanticChunker+Chunking.swift:79-85] - Large document ingestion streams in page batches (OOM safe) and performs incremental FTS5 database inserts via an append option.
WorkspaceSyncServiceprotects recently modified or queue-tracked files from sync-based deletion sweeps. Recently copied workspace files are protected from background deletion sweeps by touching their modification date to current date immediately after copying, ensuring they are protected by the 15-minute sweep guard before metadata registration finishes.[evidence: code_verified, exact, RAGService+Streaming.swift, WorkspaceSyncService.swift, RAGService.swift, DocumentPicker.swift] - From 5.7 a text, Markdown or JSON Lines file over 8 MB is imported in pieces of about 2 MB of whole lines: each piece is chunked, embedded and saved to both stores before the next is read, and a state file records the committed progress, so an import that stops goes on from the piece it reached (
RAGService+TextStreaming.swift,TextPieceReader). A PDF over 10 MB numbers its passages on from one batch of pages to the next (RAGService.documentNumbered); through 5.6 each batch numbered its passages from zero, and a keyword row whose number an earlier batch had used was not stored.[evidence_level: test_verified (IngestionAccuracyTests); an 88.50 MB JSON Lines file finished on an iPhone 16 Pro Max on 2026-10-10 as 144,247 passages; the PDF numbering has not been re-run on a device, confidence: high, evidence_source: RAGService+TextStreaming.swift, RAGService+Streaming.swift, Docs/INGESTION_PIPELINE.md] - Embedding input was truncated at 128 tokens until 2026-08-17 while both compiled models declare input shape
[1, 512]. Measured with the real WordPiece vocab over 139 live chunks, median chunk is 273 tokens and 55% of library content never reached the embedder. The bundled tokenizers also carried apaddingblock, which madeDocumentProcessor.countTokensreturn a constant (loggedmaxTokens=128/430on 3,910 of 3,910 ingestions) and caused mean pooling to average[PAD]into every vector. Fixed in2753d15by removing the padding block and raising truncation to 512. Vectors created before that date remain truncated and padding-diluted until their library is re-embedded, and nothing in the app detects this. Sequence length and embedding dimension are independent: dimensionality is unchanged at 384 andBNNSVectorDatabase’s format is untouched.[evidence_level: measured, confidence: high, evidence_source: real tokenization of 139 live chunks; INGESTION_PIPELINE.md section 5b] - Ingestion queue removal uses bounded, deletion-wins tombstones in the existing coordinated queue JSON. Tombstones survive an otherwise empty queue, filter stale local/shared items during iCloud Drive reconciliation, and remain backward compatible with queue files that predate the field. Automatic empty-vector repair is single-flight and sequential; Stop/Discard persistently suppresses it per library in local device preferences until an explicit import or manual rebuild clears the suppression.
[evidence_level: code_verified, confidence: high_pending_runtime_validation, evidence_source: WorkspaceSyncService.swift, RAGService.swift, IngestionQueueOverlay.swift] - On-device tokenization is powered by a high-performance Rust-backed
swift-tokenizers(DePasqualeOrg) package loaded asynchronously from the local resource bundle, replacing legacy pure-SwiftBertTokenizerand providing exact byte-level character offsets.[evidence: code_verified, exact, CoreAISentenceEmbeddingProvider.swift, CoreMLSentenceEmbeddingProvider.swift, DocumentProcessor.swift, RAGEngine.swift]Corrected 2026-10-20: this line said the package was used “to provide a 100x speedup”, under a code_verified tag. Code shows which tokenizer runs, not how much faster it is, and the 100x figure was never measured:Docs/USER_CHANGELOG.mdandDocs/RELEASE_NOTES.mdrecord it as withdrawn on 2026-08-06. The package is DePasqualeOrg’sswift-tokenizers, reached through the vendoredswift-transformerspackage, and its build artifact isTokenizersRust, so “Rust-backed” holds.[evidence_level: code_verified for the package, unverified for any speed figure, confidence: high, evidence_source: OpenIntelligence/swift-transformers/Package.swift:14 and the build artifact .build/artifacts/swift-tokenizers/TokenizersRust (both from the repository root), Docs/USER_CHANGELOG.md and Docs/RELEASE_NOTES.md (the 2026-08-06 withdrawal notes)]
4. Unsafe Claims
- The app uses CloudKit databases. (FALSE)
[evidence: code_verified, exact] - Knowledge libraries use separate isolated SQLite files. (FALSE)
[evidence: code_verified, exact] - Added 2026-10-20, each read in the working tree (
b868fc0plus the 5.7 work in progress):- Deep Think or Maximum searches the library again for every session. (FALSE) Retrieval runs before the first session, and each session reads the next window cut from that one pool of passages. Once the sessions start, new searches come only from Deep Think’s research rounds after its chain, and Maximum’s own loop runs none.
[evidence_level: code_verified, confidence: exact, evidence_source: Services/Agentic/AgenticOrchestrator+ReasoningChain.swift:303-436 (every window built before session 1), AgenticOrchestrator+ReasoningChain.swift:460-750 (each session is one model call, retried up to twice on an overflow or a transient failure), AgenticOrchestrator.swift:573 and AgenticOrchestrator+SelfRAG.swift:547 (the only two research call sites), AgenticOrchestrator.swift:396-473 (Maximum's excellent branch returns before either)] - Deep Think runs up to 50 sessions, or more sessions on a faster device. (FALSE) Its chain stops at 8 sessions on every device, and earlier when the distinct windows run out: a 20-passage pool at 4 passages a window gives 5 sessions on a 4,096-token window. 50 is Maximum’s ceiling, and Maximum scales it down to its pool. What differs by device is the confidence the chain aims for, the grade thresholds, how long a finding may be (2,000 characters on an A17 Pro, 2,500 from the A18 on) and the token budget of the research rounds and the decomposed pipeline.
[evidence_level: code_verified for the rules, inferred for the 5-session arithmetic, confidence: high, evidence_source: Services/RAG/Tuning/AgenticPolicyService.swift:304 (min(8, sessionCount + 4)) and :99-126 (grade thresholds from the escalation threshold), Services/Agentic/AgenticOrchestrator+ReasoningChain.swift:423-434 and :460, AgenticOrchestrator+Maximum.swift:590-593, AgenticOrchestrator.swift:53-67 and AgenticOrchestrator+Types.swift:208-225 (the chain configuration and its maxInsightLength), AgenticOrchestrator+Retrieval.swift:618-620 and AgenticOrchestrator+Research.swift:114, Services/Agentic/SessionEvidencePlan.swift:71-76, Services/Infrastructure/Monitoring/DeviceCapabilityService.swift:1063-1114] - Maximum runs several reasoning chains in parallel over clusters of documents. (FALSE)
executeMultiChainReasoningandexecuteClusterChainwere defined and nothing called them. (Removed 2026-11-06: both functions, with the cluster helpers and theMultiChainConfig,MultiChainResult,DocumentClusterandDocumentSemanticProfiletypes, are deleted; Maximum runsexecuteTrueUnlimitedReasoning.)[evidence_level: code_verified, confidence: exact, evidence_source: Services/Agentic/AgenticOrchestrator+MultiChain.swift@b914298b:24 and @b914298b:382, a search of every Swift file under OpenIntelligence/ for a caller (none; repeated 2026-11-05 over OpenIntelligence and OpenIntelligenceTests), grep -rn "executeMultiChainReasoning\|executeClusterChain" OpenIntelligence on 2026-11-06 (no hits), AgenticOrchestrator+Maximum.swift:554] - The model chooses and calls retrieval tools in Deep Think or Maximum. (FALSE) Six tools are registered, but every Deep Think and Maximum session and synthesis passes
disableTools: true, and no Deep Think or Maximum step asks the model to pick a tool. Research rounds ask it to write[SEARCH: words]as text.[evidence_level: code_verified, confidence: exact, evidence_source: Services/AIPlatform/AppleFoundationModels/FoundationModelToolRegistry.swift:327-360, Services/Agentic/AgenticOrchestrator+ReasoningChain.swift:623, AgenticOrchestrator+ReasoningChain.swift:1267, AgenticOrchestrator+Maximum.swift:924, AgenticOrchestrator+Maximum.swift:1456, AgenticOrchestrator+Maximum.swift:1506, AgenticOrchestrator+Research.swift:277-310] - Maximum’s 200,000-token budget limits its loop. (FALSE)
maxTotalTokensis read in two places only, the decomposed pipeline of the low-retrieval branch and the research rounds. Neither Deep Think’s chain nor Maximum’s own loop checks it.[evidence_level: code_verified, confidence: exact, evidence_source: Services/Agentic/AgenticOrchestrator+Types.swift:145, AgenticOrchestrator+Retrieval.swift:620, AgenticOrchestrator+Research.swift:114] - Every Deep Think and Maximum answer passes the nine verification gates. (FALSE) In the shipped 5.6 they run no gates and read Not Checked unless the source-only check ran. From 5.7 the gates run once after the loop and set the label only (Verified needs all nine to pass), they never withhold or rewrite the answer, and a value the precision shortcut locks before the loop is returned with no gates at all.
[evidence_level: code_verified, confidence: exact, evidence_source: Services/RAG/Orchestration/RAGService+AgenticQuery.swift:811-822 and verifyAgenticAnswer at RAGService+Generation.swift:979-1028 (5.7), the v5.6.0 tag (2bee971), whose RAGService.swift has no verifyAgenticAnswer, Core/Models/VerificationOutcome.swift:33-62] - Vectors are stored in an HNSW or other approximate index. (FALSE)
BNNSVectorDatabaseappends vectors in arrival order to one flat Float32 file, and every search compares the question with every vector, on the CPU or, from 1,000 vectors under the Performance or Maximum profile, on Metal.VecturaVectorDatabasesits behind#if canImport(VecturaKit)and VecturaKit is not a dependency, so it never compiles.[evidence_level: code_verified, confidence: exact, evidence_source: Services/VectorStore/BNNSVectorDatabase.swift:1104-1190, Services/VectorStore/VectorStoreRouter.swift:167-172, Services/Infrastructure/Monitoring/DeviceCapabilityService.swift:1007-1012 (searchesLargeLibrariesOnGPU: GPU search only under Performance or Maximum), no VecturaKit in Package.swift, Package.resolved or project.pbxproj]
- Deep Think or Maximum searches the library again for every session. (FALSE) Retrieval runs before the first session, and each session reads the next window cut from that one pool of passages. Once the sessions start, new searches come only from Deep Think’s research rounds after its chain, and Maximum’s own loop runs none.
5. Non-Negotiable Facts
Docs/AgentPlaybooks/00_SUPERSEDING_EVIDENCE_PROTOCOL.mdmust be followed for all agent workflows.- No destructive commands may be run.
6. Storage Boundaries
- SQLite is strictly local.
[evidence: code_verified, exact] - Vectors use
BNNSVectorDatabasewith memory mapping.[evidence: code_verified, exact] - From 5.7 the store’s passage file (
_meta.json) is memory-mapped too and indexed at load, one small record per passage, and a passage is decoded when it is asked for. The file’s format is unchanged. Every passage is still decoded at least once per launch, by the first caller that asks for all of them, and again after the store has let them go under memory pressure. A passage whose bytes do not decode is left out of searches and answers and no longer empties the library.[evidence_level: test_verified, confidence: high, evidence_source: BNNSVectorDatabase.swift, PassageFileIndex.swift; VectorStorePassageIndexTests, BNNSVectorDatabasePersistenceTests] - Chat messages are serialized to monolithic JSON arrays.
[evidence: code_verified, exact] - Ingestion checkpoints are stored as JSON files under
localCacheDir()/IngestionCheckpoints/<fingerprint>/.[evidence: code_verified, exact, DocumentProcessor.swift]
7. Sync Boundaries
WorkspaceSyncService.swiftsweeps local files for iCloud Drive ubiquity sync.[evidence: code_verified, exact, WorkspaceSyncService.swift]- From 5.7 a sync pass leaves a library’s vector store alone while an import into that library is unfinished on this device (
WorkspaceSyncService.librariesWithUnfinishedImports), and the digests of the stores it has already reconciled are kept across launches, so an unchanged store is not loaded and compared again at every launch.[evidence_level: test_verified, confidence: high for the rule; not observed between two devices, evidence_source: WorkspaceSyncService.swift; WorkspaceSyncImportGuardTests]
8. Routing/PCC Boundaries
QueryRuntimeCoordinatorproduces constraints only; it does not claim a final PCC route.RAGServiceassembles evidence locally, creates the post-retrieval plan, minimizes the PCC envelope, and requests consent for that exact payload.LLMServiceandFoundationModelSessionFactoryexecute the selected public target and record the actual result.[evidence_level: code_verified, confidence: high, evidence_source: QueryRuntimeCoordinator.swift, RAGService.swift, LLMService.swift, FoundationModelSessionFactory.swift]- What a new install starts with (added 2026-10-20). Answer mode Standard, the model picker on Hybrid (
fmPreference = .automatic, which the picker shows as “Hybrid”), and Private Cloud Compute permission “Ask when needed”. At send time Hybrid becomesexecutionContext = .preferCloudwithallowPrivateCloudCompute = true, so the cloud route is open from the first question. Nothing is sent before the planner below chooses PCC and the consent sheet (Always Allow, Just Once, Deny) is answered. After Always Allow, or with the setting “Allow without asking” (its 5.7 name, 5.6 shows it as “Allow for Deep Think and Maximum”, and in both it covers every mode), later sends are not asked about again.[evidence_level: code_verified, confidence: exact, evidence_source: Services/Infrastructure/Configuration/SettingsStore.swift:50, :451, :454-461, :616-624, Core/Models/LLMModel.swift:215-233 and :261-267, the v5.6.0 tag (LLMModel.swift:219, and RAGService.swift's cloudConsentDecision at its line 3725 reads no mode), Features/Chat/Conversation/ChatScreen+Sending.swift:321-325, UI/Components/CloudConsentPromptView.swift:213-247, Services/RAG/Orchestration/RAGService+StandardRetrieval.swift:873-912 (ensureCloudConsentIfNeeded)] - The rule that decides Private Cloud Compute, first match wins (added 2026-10-20). Insufficient evidence abstains, and cloud is prohibited. On-Device stays local. With PCC chosen in the picker, the answer goes to PCC when PCC is usable (supported, entitled, available and within quota), the network is up and someone can be asked or has agreed (the app is in front, or from 5.7 an action can bring it forward to ask, or consent is remembered or was given Just Once for this question), and otherwise stays local with the reason recorded. The planner also has a deterministic rule, for an exact extracted value with nothing contradicting it, but the only code that builds the planner’s evidence passes
requiresExactExtraction: falseandhasContradictions: false, so no plan is deterministic today, and one would run on the device exactly like an on-device plan. A privacy setting that forbids cloud stays local. Otherwise, under Hybrid, the answer goes to PCC only when PCC is usable, the network is up, someone can be asked or has agreed, the prompt and evidence as assembled (before anything is minimized) fit the window PCC reports, and either that evidence does not fit the device’s budget or the mode is Deep Think or Maximum and the answer draws on more than one document. When PCC reports no window, Hybrid never picks it. Standard never goes to PCC on difficulty alone. The evidence is minimized for the cloud only after PCC is picked, and every PCC plan carries an on-device fallback and no PCC retry.[evidence_level: code_verified, confidence: exact, evidence_source: Services/RAG/Orchestration/ModelExecutionPlanner.swift:24-130 and :139-179 (makeEnvelope), Services/RAG/Orchestration/ModelExecutionPlan.swift:104 and :146-148, Services/RAG/Orchestration/RAGService+Generation.swift:1138-1268 (makePostRetrievalModelPlan:hasContradictions: falseandrequiresExactExtraction: falseat :1185-1186, Just Once at :1216, an action brought forward at :1220-1222, the PCC budget measured onprompt + contextat :1246-1258), RAGService+QueryRetrieval.swift:122-151 (applyPostRetrievalModelPlan: Standard minimizes after the plan), RAGService+QueryRetrieval.swift:206 (.onDevice and .deterministic share one branch), Services/Agentic/RAGService+Agentic.swift:263-290 and :321, Services/AIPlatform/AppleFoundationModels/FoundationModelRoutePolicy.swift:35-37, a search of every Swift file under OpenIntelligence/ for requiresExactExtraction (one construction)] - Where Deep Think and Maximum can reach Private Cloud Compute (added 2026-10-20). Their route is planned inside every
generateWithProperConsentcall, after the picker choice captured for the query is applied. Every chain session, Maximum session, Maximum running answer and research decision passesforceOnDevice: true. The helper calls (search phrasings, the relevance check, reformulation, decomposition planning, entity naming, speculative candidates, title routing and the direct answer of the path that needs no documents) run in a fresh on-device-only session, and the planning call (a guided generation on Apple’s on-device model that proposes search phrasings and sub-questions and says whether documents are needed) runs on the device in a session of its own: once in the coordinator for every question in every mode, and again in the orchestrator to decide whether documents are needed, to propose phrasings and to propose sub-questions. So under Hybrid only the calls that write an answer from what the loop gathered can be planned to PCC: Deep Think’s synthesis from its findings, Maximum’s synthesis and its refinement, the exhaustive synthesis of Maximum’s chain, the direct synthesis of the moderate and low branches, the decomposed pipeline’s synthesis, the synthesis research forces when its rounds run out, and on the path that needs no documents the synthesis written after a search, when the second planning call or the self-critique asks for one. On a PCC plan each of these sends, in place of its own context, an envelope minimized from the passages it passes (at most 12,000 characters). So Deep Think’s synthesis then carries passages as well as its findings, while the decomposed pipeline’s synthesis and the one research forces, which pass their evidence as text and no passages, would reach PCC with the question alone (read in the code, not run). The on-device pin is lifted only when the person picks Private Cloud Compute in the model picker, and those sessions then keep the character-sized evidence path instead of the token-planned one. On-Device keeps every call local, synthesis included.[evidence_level: code_verified, confidence: exact, evidence_source: Services/Agentic/RAGService+Agentic.swift:137-374 (generateWithProperConsent: budgetPin = forceOnDevice && !explicitlyPrefersPCC at :214, the envelope built from sourceChunks at :263-290), the pinned calls at AgenticOrchestrator+Research.swift:296, AgenticOrchestrator+ReasoningChain.swift:643, AgenticOrchestrator+Maximum.swift:919 and :1330, the on-device helpers through generateWithFreshSession at AgenticOrchestrator+Retrieval.swift:161, AgenticOrchestrator+Retrieval.swift:681, AgenticOrchestrator+Retrieval.swift:834, AgenticOrchestrator+Retrieval.swift:1228, AgenticOrchestrator+Retrieval.swift:1445, AgenticOrchestrator+SelfRAG.swift:111, AgenticOrchestrator+SelfRAG.swift:1132 and AgenticOrchestrator+ReasoningChain.swift:125 (helper body RAGService+Agentic.swift:87-132), the planning calls at AgenticOrchestrator+Retrieval.swift:793, AgenticOrchestrator+Retrieval.swift:937 and AgenticOrchestrator+SelfRAG.swift:210 (Services/Query/Analysis/QueryExecutionPlannerService.swift:75-137 and :367-455, a LanguageModelSession on SystemLanguageModel.default at :381-382) and Services/RAG/Orchestration/QueryRuntimeCoordinator.swift:202-207, the unpinned syntheses at AgenticOrchestrator+Retrieval.swift:404, :476 and :1657, AgenticOrchestrator+Research.swift:381, AgenticOrchestrator+ReasoningChain.swift:1175 and :1262, AgenticOrchestrator+Maximum.swift:1450 and :1500 (Retrieval :1657 and Research :381 pass a context and no sourceChunks), AgenticOrchestrator+SelfRAG.swift:81 and :164 (the searches on the no-documents path), AgenticOrchestrator+ReasoningChain.swift:263-274, Services/RAG/Orchestration/RAGService.swift:130-132 and RAGService+Generation.swift:1309-1314 (renderCloudEvidenceEnvelope)] - Standard’s cloud-sized first pass (added 2026-10-20). When Hybrid can reach PCC (Apple’s on-device model, a network, PCC allowed, the route not suppressed after a failure and consent not denied), Standard asks retrieval for at least 50 candidates, within the adaptive cap: 10 for a trivial question or at critical heat, at most 50 for a complex one, and half the tier’s cap under critical memory pressure, 37 on an A17 Pro. That count is decided before the Simulator is ruled out. Outside the Simulator, Standard then sizes its first evidence pass for the PCC window the app assumes, 32,768 tokens (a hard-coded value, while the planner’s fit check reads the window PCC reports), at 2.5 characters a token and a safety factor of 0.92, capped at 45,000 characters. If the plan then keeps the answer on the device and that evidence does not fit, it is re-packed to the device’s budget as whole passages, in lost-in-the-middle order except for a procedure. Without the cloud route the budget is the device’s own window less 120 tokens, the system prompt, the question and an output reserve of 150 to 300 tokens, times 0.88, at 1.4 characters a token, capped at 10,000 characters (2,600 tokens and 2,500 characters for a trivial question). On the owner’s iPhone 16 Pro Max that came to
available=3190tokens, about 4,470 characters, on 2026-10-16.[evidence_level: code_verified for the rule, measured for the 3,190, confidence: high, evidence_source: Services/RAG/Orchestration/RAGService+QueryPreparation.swift:147-156 (the candidate count), Services/RAG/Orchestration/QueryRuntimeCoordinator.swift:150-158 and :162-167 (the condition is computed before the Simulator override), Services/Infrastructure/Optimization/AdaptivePipelineOptimizer.swift:115-261 and :324-400 (the caps), RAGService+QueryContext.swift:1192-1200 (no cloud sizing in the Simulator), RAGService+QueryContext.swift:1142-1205 (computeContextCharBudget: the budget, 0.92 or 0.88 at :1162), RAGService+QueryContext.swift:1291, RAGService+QueryRetrieval.swift:122 and :170-195 (the plan and the re-pack), RAGService+SentenceExtraction.swift:91-92 (the measurement), Services/RAG/Orchestration/RAGEngine.swift:495-504, Services/AIPlatform/AppleFoundationModels/FoundationModelTokenBudget.swift:44-51 (32,768 is the fallback when the window is not read live)] - Background and App Intent execution never suspends waiting for a
CloudConsentPromptViewnobody can see: remembered consent may authorize PCC, and from 5.7 it is applied before anything about the foreground, so it also holds for a question from the background on iPhone; an ask action the system lets come forward brings the app forward and asks there first (from 5.7, changed 2026-10-14 at the owner’s word;CloudConsentRelayshows the sheet, and one no window shows within 15 seconds is given up without being remembered); otherwise Hybrid and explicit PCC policy use the declared local fallback before meaningful text streams. The receipt preserves PCC as intended and on-device as completed, and no PCC/local fallback occurs after meaningful text has streamed.[evidence_level: code_verified, confidence: high_pending_physical_device_validation, evidence_source: ModelExecutionPlanner.swift, ModelExecutionPlan.swift, LLMService.swift, RAGService.swift] - The chat picker stores routing policy, not execution history.
Hybrid,On-Device, andPCCremain stable through route notifications and relaunch; per-response route badges are computed from existing optional receipt/route metadata without changing the persistedChatMessageshape.[evidence_level: build_verified+code_verified, confidence: high_pending_ui_runtime_validation, evidence_source: SettingsStore.swift, ModelStatusIndicator.swift, MessageBubbleV2.swift, ChatMessage.swift and generic iOS 27 simulator build 2026-07-16] - The picker persisted correctly but did not govern routing in Deep Think or Maximum until 2026-07-30.
RAGService.generateWithProperConsentbuilt a freshInferenceConfigcarrying only maxTokens/temperature/systemPrompt, sofmPreference,executionContext, andallowPrivateCloudComputefell back to defaults regardless of the stored policy. Three physical-device runs — one per setting — were identical in routing, and an On-Device selection still sent a minimized envelope to PCC. Consent was never bypassed and Standard was unaffected. Fixed by capturing aUserRoutingPreferenceper query inexecuteAgenticQueryand applying it before planning; On-Device is now absolute and covers final synthesis.[evidence_level: device_verified_for_the_defect+build_verified+test_verified_for_the_fix, confidence: high_for_the_defect_unverified_on_device_for_the_fix, evidence_source: PCC/On-Device/Hybrid device logs 2026-07-30, commit 6f29d2d] - PCC remembered consent is canonical in
cloudConsent.applePCC; the legacypcc.settingvalue is migrated and synchronized without overriding an explicit canonical allow/deny decision. The app does not prewarm consent UI at launch.pendingCloudConsentis populated only by a real transmission record after the route and minimized envelope exist.[evidence_level: code_verified+test_verified, confidence: high_pending_physical_device_validation, evidence_source: SettingsStore.swift, RAGService.swift, PCCConsentPreferenceMigrationTests.swift] - Unknown future
PrivateCloudComputeLanguageModel.QuotaUsage.Statusvalues map to.unknownvia@unknown default; they never authorize PCC execution.[evidence_level: code_verified, confidence: exact, evidence_source: FoundationModelCapabilityProvider.swift] - Telemetry may record plan IDs, public target names, counts, token budgets, quota categories, hashes, reason codes, and verification status. It must not record raw query, document, transcript, or reasoning content.
[evidence_level: code_verified+policy, confidence: high, evidence_source: RAGService.swift, ModelExecutionReceipt.swift] - The floating Silicon HUD is scene-scoped on iOS: frame calculation requires the HUD window’s
UIWindowScene.screen, avoiding deprecated global-screen state and cross-display ambiguity.[evidence_level: build_verified+code_verified, confidence: exact_for_build, evidence_source: MotherboardHUDView.swift and generic iOS 27 simulator build 2026-07-16]
9. Billing Boundaries
- Managed by
EntitlementStore.swiftviaUserDefaults.
10. App Intents Boundaries
RAGAppIntentsutilizes 10 of the 10 available App Shortcuts limit since 5.7 (9 through 5.6).[evidence_level: test_verified, confidence: exact, evidence_source: AppShortcutsProviderTests, 2026-10-09]
11. Evidence Threads Canonical Decision
- 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] - Journal (Debug only, added 2026-11-03):
EvidenceThreadStorerecordsthread.saved(with whether the file was new) andthread.deleted, by the thread’s first 8 id characters, which are the same on both devices, so the iPhone’s and the Mac’s journals can be matched by eye. What sync pulled or removed in a pass (sync.threads) is not recorded: it lives inWorkspaceSyncService.swift, a hard-boundary file.[evidence_level: code_verified, confidence: high] - Synchronization (from 5.7; before it, see the line above): Thread files are synchronized bidirectionally via
WorkspaceSyncService.swifton changes, gated by tier-specific limits (5 Free / 20 Pro / Unlimited Lifetime) inQuotaPolicy.swift.[evidence: code_verified, exact] - Legacy
ChatMessageremains untouched (EvidenceThread uses ChatMessage array for immutability). - RAGService and ChatScreen integration complete. ChatScreen features a slide-out ThreadSidebarView, enabling thread switching, creation, and deletion, with history persistence and loading managed asynchronously by RAGService.
- Clearing a conversation (
ChatScreen.clearChat), deleting one inThreadSidebarView, hiding the answer (MessageBubbleV2), or sync removing the conversation after it was deleted on another device (ContentView.refreshSharedWorkspaceIfNeeded) drops that library’s last question and answer from the “Your Library” widget’s file in the app group (WidgetSnapshot, 5.7). The widget is not in the widget bundle until the App ID carries the app group.[evidence_level: code_verified+test_verified (WidgetSnapshotTests), confidence: medium, evidence_source: WidgetSnapshot.swift, ChatScreen.swift, ThreadSidebarView.swift, MessageBubbleV2.swift, ContentView.swift] - A conversation in
ThreadSidebarViewis deleted by swiping it; the tour’s “Swipe to delete” tip points at the first one (5.8, 2026-11-13,TourStep.threadSwipe).[evidence_level: code_verified, confidence: exact, evidence_source: ThreadSidebarView.swift .onDelete, TourTips.swift] - With no conversation in the open library,
ThreadSidebarViewsays what it lists (“This library’s conversations are listed here. Start one with the button above.”); its list comes fromragService.listThreads(for: activeContainerId)(5.8, 2026-11-16).[evidence_level: code_verified, build_verified, confidence: high]
12. Phase Boundaries
- Phase 0: Master Operating Rules (Complete)
- Phase 1: Repository Inventory (Complete)
- Phase 2: Entity & System Audit (Complete)
- Phase 3: Component Atlas (Complete)
- Phase 4: Call Relationships & Side Channels (Complete)
- Phase 5: Data-Flow and Risk-Boundary Maps (Complete)
- Phase 6: Documentation Scan & Pro Review (Complete)
- Phase 7: Evidence Threads Placement (Complete)
- Phase 8: Canonical Control System (Complete)
- Phase 9: Evidence Threads MVP Integration (Complete)
- Phase 10: Ingestion & watchOS Live Activity Refinement (Complete)
13. Files Allowed/Prohibited by Phase
- Audit phases prohibit modification of
*.swiftfiles, tests, configurations. - Implementation phases strictly define a limited blast radius of allowed files (e.g.,
EvidenceThread.swift).
14. Known Unresolved Risks
- Native PCC execution is owner-confirmed on a physical device (2026-07-28, on v4.6) and is no longer listed as unverified.
[evidence_level: user_confirmed, confidence: high_for_execution_path, evidence_source: owner device testing]Still unverified: signed physical-device installation, archive/TestFlight entitlement propagation, quota exhaustion, and network-transition behavior. Owner confirmation covered the execution path only and did not state coverage for those edge scenarios. - The background/App Intent consent deadlock has a source-level prevention path and focused policy tests, but still requires physical-device/manual validation. The foreground case, an action’s question reaching the consent step while the app was in front (on the Mac, while it was active), still waited until 5.7, when its request began to go through
CloudConsentRelay(CloudConsentRelayTests, 2026-10-14); that also waits on a device run. - iCloud Sync behavior for imported physical documents.
BNNSVectorDatabasememory mapping limits.
15. Required Future-Agent Checklist
See Docs/AuditArtifacts/ArchitectureAtlas/future_agent_checklist.md.
16. How to Supersede this Canonical Doc
To supersede this doc, an agent must complete a new Architecture Atlas discovery phase verifying the code changes and use evidence_level and confidence metrics in a Delta Repair report.
17. Repository Agent Operations Boundary
- Every repository task is routed through
.codex/skills/route-openintelligence-work/SKILL.md, which derives task ownership and change requirements fromDocs/AuditArtifacts/RepoOS/change_impact_matrix.csv. Its preflight also derives the active release from current repository artifacts and reports the exact changelog, release-notes, and Notion release targets without forcing edits for read-only work.[evidence: code_verified, exact, .codex/skills/route-openintelligence-work/scripts/repoos_router.py] - The workspace router is developer governance tooling only. It does not compile into, modify, or execute within the OpenIntelligence Apple app.
[evidence: code_verified, exact, change_impact_matrix.csv repoos_workspace_automation boundary] - Notion relevance must be evaluated on every task; durable implementation, bug, milestone, release, and roadmap work is synchronized at start and verified completion according to
.agents/workflows/sync-notion.md.[evidence: code_verified, exact, .codex/skills/route-openintelligence-work/SKILL.md]
18. App Icon Appearance
- The AppIcon asset catalog retains the existing light mark and includes a universal iOS dark luminosity rendition. The compiled asset catalog contains a
UIAppearanceDarkAppIcon entry; physical-device selection remains unverified.[evidence_level: build_verified, confidence: high_pending_device_validation, evidence_source: OpenIntelligence/Resources/Assets/Assets.xcassets/AppIcon.appiconset/Contents.json; xcrun actool; /usr/bin/assetutil --info]
19. Answer Modes, Agentic Loop and Verification Boundaries
Added 2026-10-20 against the working tree (b868fc0 plus the 5.7 work in progress). Each line was read in the code at the file and line it cites, and nothing was built or run. RAGService.swift lines are those of the working tree read at 22:17 that night (22,746 lines), and the file is still changing, so look for the named function if a line has moved. “5.6” is the shipped app, live since 2026-10-08, checked at the v5.6.0 tag (2bee971) where it differs. “The loop” means three different things here: Deep Think’s chain, Maximum’s own loop, and the research rounds after Deep Think’s chain. Standard has no loop unless the developer switch Force Reasoning Chain (Settings, Developer & Diagnostics, off by default) is on, when a Standard question that clears that path’s own checks (not trivial or simple, at least 3 passages, a best similarity of 0.30 and more than 900 characters of context) runs Deep Think’s chain on the fast configuration. [evidence_level: code_verified, confidence: exact, evidence_source: Services/RAG/Orchestration/RAGService+QueryAnswer.swift:649-690 (decideReasoningChain) and RAGService+QueryPipeline.swift:633-655 (useReasoningChain), Services/Agentic/RAGService+Agentic.swift:27-33 (executeStandardReasoningChain on .fast), Services/Infrastructure/Configuration/SettingsStore.swift:569, Features/Diagnostics/Hub/DeveloperDiagnosticsHubView.swift:35-37, Features/Settings/SettingsView+List.swift:180-183 and SettingsView+List.swift:540]
- Modes and how a question enters. A new install starts in Standard, which answers in one pass. Deep Think and Maximum are chosen by the person, and both return into
executeAgenticQuerybefore any Standard step runs. Go Deeper re-asks one answer through that agentic path and keeps the chat’s mode, so from Standard it runs the orchestrator with mode Standard and without Deep Think’s Self-RAG check. Planner escalation from Standard is switched off whenever Apple’s model is the answer writer, and no other model writes answers: the local OpenAI-compatible backend is compiled out, and without Apple Intelligence a stand-in that only throws takes its place (a demo mock in a debug Simulator screenshot run), so escalation could be planned only where no model writes. The free plan allows three Maximum questions a day.[evidence_level: code_verified, confidence: exact, evidence_source: Services/Infrastructure/Configuration/SettingsStore.swift:616-624, Services/RAG/Orchestration/RAGService+QueryPipeline.swift:211-230, RAGService+QueryPipeline.swift:33 (reQueryWithAgenticMode), RAGService+QueryPipeline.swift:162 (isAppleFMService), RAGService.swift:1020-1044 (the stand-in), Services/RAG/Orchestration/QueryRuntimeCoordinator.swift:202-229, Services/Agentic/AgenticOrchestrator.swift:41-49, Services/LLM/LocalOpenAIServerLLMService.swift:14 (#if false), Services/LLM/LLMService.swift:262-274 and :362-382, Services/Infrastructure/Configuration/QuotaPolicy.swift:21] - The precision shortcut, before any loop. For a lookup or a precise-value question that is not conceptual, Deep Think and Maximum first run the spec sniper over every passage and ask the extractor for a value. If none locks, one full retrieval runs (topK at least 24, floor 0.03) and the extractor tries again. A value that locks at 0.82 (0.90 when forced) is returned at once as “Direct Source Extraction”, with no session, no model call of its own (the coordinator’s planning call has already run), no source-only check and no gates, and its badge reads Not Checked.
[evidence_level: code_verified, confidence: exact, evidence_source: RAGService+AgenticQuery.swift:124-317 (executeAgenticPrecisionLookupIfAvailable), RAGService+AgenticQuery.swift:462-475, RAGService+AnswerFinishing.swift:452 (the source-only check declines a source-locked answer), QueryRuntimeCoordinator.swift:202-207, Services/RAG/Tuning/EvidenceScoringPolicyService.swift:82-84, Core/Models/VerificationOutcome.swift:33-62] - The front half, Deep Think and Maximum. The planning call (a guided generation on Apple’s on-device model, with a heuristic plan as the fallback when the model is unavailable or fails) decides whether documents are needed, and it is made again for the search phrasings and, in the decomposed pipeline, the sub-questions. Up to 5 search phrasings, the planner’s when it returns 3 or more or calls the question a direct lookup, otherwise one on-device call of up to 200 tokens with fixed phrasings as the fallback, each run the full retrieval pipeline (topK 15, floor 0.05). Their lists are fused by RRF with k = 60, blended 0.6 with the best reranker score and 0.4 with the fused rank, and the top 20 are kept. If the phrasings find nothing, the person’s own wording is searched. A relevance gate follows: lexical overlap under 0.10 together with a failed intent check ends the run with “couldn’t find”, and an intent mismatch alone lowers the grade to moderate. The pool is graded excellent, good, moderate or low, with thresholds tied to the device’s escalation threshold. Graph expansion, for moderate and low only, has the model name up to 3 entities, searches each one and grades the pool again. Then, for every grade, cross-reference resolution looks in the first 12 passages for references such as “see section”, follows up to 3 of them with a full search at topK 5, adds the new passages at a score of at least 0.55 and grades the pool again, so the pool can grow past 20 and the grade can rise. Excellent and good enter a chain, good after one reformulated search. Moderate gets one reformulated search and a single synthesis. Low gets speculative RAG, which runs its own search (topK 20), writes 3 candidate answers on the device from the top 5 passages and returns the best one when it reaches the acceptance threshold. Below it, the decomposed pipeline runs, or a broader search (topK 20) and a single synthesis. HyDE does not run on this path.
[evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator.swift:138-146 and AgenticOrchestrator+SelfRAG.swift:200-218 (decideIfRetrievalNeeded), AgenticOrchestrator+Retrieval.swift:785-929 (generateSearchQueries, the planner at :793), AgenticOrchestrator+Retrieval.swift:932-944 (plannerSubQueries), Services/Query/Analysis/QueryExecutionPlannerService.swift:75-137 and :367-455, AgenticOrchestrator+Retrieval.swift:1055-1139, AgenticOrchestrator.swift:199-226, AgenticOrchestrator.swift:237-298, AgenticOrchestrator.swift:331-377 (graph expansion and cross-references, each grading again), AgenticOrchestrator+Retrieval.swift:1253-1399 (resolveCrossReferences), AgenticOrchestrator+Retrieval.swift:1403-1474, AgenticOrchestrator.swift:386-985, AgenticOrchestrator.swift:885-911 and AgenticOrchestrator+SelfRAG.swift:980-1142 (speculative RAG), AgenticPolicyService.swift:99-126 and :145-147, RAGService+ToolHandler.swift:151-154] - Deep Think’s chain. One on-device call of up to 256 tokens orders the pool by section title and drops nothing. Then every session’s window is built before session 1, as windows of that same pool that do not overlap (on the character path the last one can repeat a few passages when the pool does not divide evenly): 4 passages on a 4,096-token window and up to 7 on a window of 8,000 or more. Where the OS can count tokens (iOS and macOS 26.4 and later) a window holds whole passages within at most 3,200 evidence tokens, the window less 700 for the reply, 400 for the prompt, 256 for safety and the carried text, as long as at least 4 passages fit whole. Otherwise a window is sentences extracted from 4 passages to 3,500 characters (3,000 when Maximum runs the chain), and the prompt keeps the first 4,000 characters of it while no findings are carried and 2,200 once they are. Building stops when the pool runs out, so the number of sessions is the number of distinct windows, at most 8 on every device. Each session is one model call of up to 700 tokens with tools off, on the device unless Private Cloud Compute is picked (section 8), retried up to twice: with a shorter prompt after a context overflow (a whole-passage window then falls back to extracted sentences), or with the same prompt after 1.5 seconds on a transient failure. A session does no new retrieval, reranking or packing. It carries PRIOR FINDINGS (each insight cut to 400 characters, the block to 1,200), STILL UNANSWERED (up to 3 open sub-questions) and a SESSION OBJECTIVE. Sub-questions come from fixed templates with no model call, and one counts as answered when a fact shares a word of 4 or more letters with it. The fact bank holds at most 1,500 characters of claims and drives the coverage, novelty and stop decisions, and in Deep Think its claim text never reaches a prompt.
[evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator+ReasoningChain.swift:125 and :257-260, AgenticOrchestrator+ReasoningChain.swift:231-287, AgenticOrchestrator+ReasoningChain.swift:303-436, AgenticOrchestrator+ReasoningChain.swift:460, AgenticOrchestrator+ReasoningChain.swift:610-628, AgenticOrchestrator+ReasoningChain.swift:623-750 (the retries), AgenticOrchestrator+MultiChain.swift:177-217, AgenticOrchestrator+MultiChain.swift:248-253 (the 4,000 and 2,200 cuts), AgenticOrchestrator+Maximum.swift:99, AgenticOrchestrator+Maximum.swift:128-194, AgenticOrchestrator+Maximum.swift:1310 and :1370 (the only asContext calls, both Maximum's), Services/Agentic/SessionEvidencePlan.swift:30-76, :92-106 (fewer than 4 whole passages fall back) and :134-158, AgenticPolicyService.swift:304] - Deep Think’s stop rules. The chain ends when the windows run out. Before each session from the fifth it also ends when all three hold at once: confidence at the device’s target (0.85 on an A17 Pro, 0.90 on an A18, 0.92 on an A19, 0.95 on the ultra tier, which the per-device bullet below defines), sub-question coverage of 0.55 (0.70 with 4 or more sub-questions), and novelty exhausted (a low-novelty streak of 2 under 0.18, a saturation streak of 2, or 85 percent of the pool’s sources read). From the second session it also ends when the reply says “ANSWER COMPLETE”, “NOT FOUND IN DOCUMENTS” or “DOCUMENTS DO NOT CONTAIN”. It also ends when a session still fails after its retries, and the last finding is then the answer, with no synthesis. A session that fails before any finding exists is skipped, and the question fails only when every session does. Confidence is mostly a function of how many sessions have run, log(n + 1) ÷ log(9) × 0.68 plus coverage × 0.18 and small bonuses, so on an ordinary 20-passage pool on an A18 the five windows run out before the three-way stop can fire. From 5.7 the chain also waits 1 second before each session from the second while iOS 27 asks apps to use less, and the session count is not cut.
[evidence_level: code_verified for the rules, inferred from the formula for the A18 case, confidence: high, evidence_source: AgenticOrchestrator+ReasoningChain.swift:475-500, AgenticOrchestrator+ReasoningChain.swift:482-487 (the 5.7 pause), AgenticOrchestrator+ReasoningChain.swift:755-830 (a failed session), AgenticOrchestrator+ReasoningChain.swift:839-849, AgenticOrchestrator+ReasoningChain.swift:907-915 (sessionBudget 8), AgenticPolicyService.swift:294-332 and :366-409, Services/Infrastructure/Monitoring/DeviceCapabilityService.swift:1063-1114, Services/Infrastructure/Monitoring/SystemResourceAdvice.swift:28-32] - After Deep Think’s chain. One synthesis writes the answer from the findings (at most 3,000 characters in, up to 1,500 tokens out). On the device its prompt holds the findings and no passages. On a PCC plan the passages go too, as an envelope minimized from the pool (at most 12,000 characters, section 8). It runs only with 2 or more findings, and otherwise the last finding is the answer. In the excellent branch only, when coverage ends below its target or the answer reads like a miss, research rounds follow: a first search at topK 20 for the question with up to 3 still-unanswered sub-questions added, then up to 5 rounds, each one on-device decision call ([ANSWER] or [SEARCH: words], 900 tokens) and, for a search, a new full retrieval at topK 20, bounded by the configuration’s
maxTotalTokensand by 180 seconds. Research replaces the synthesis only when its answer is not a miss or an evidence dump, passes the replacement check and agrees with the synthesis, and a replacing answer is returned at once, with no Self-RAG check. Otherwise, in the excellent and the good branch alike, Deep Think’s Self-RAG check scores the answer with no model call, from its relevance to the question’s words and from its citations: a citation counts when its passage exists and holds at least 30 percent of the words of 4 or more letters in the 50 characters before it. A retry verdict runs research again with 3 rounds, once: from 5.8 a second retry verdict ends the check, since research takes only the question and a second run repeated the first (through 5.7 at most twice, the third retry verdict ending it). Through 5.6 that check keyed on 8 or more steps, so an A17 Pro skipped it. From 5.7 Deep Think runs it on every device.[evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator+ReasoningChain.swift:1166-1241 (Deep Think's synthesis passes sourceChunks), RAGService+Agentic.swift:211-231 (the envelope on a PCC plan), AgenticOrchestrator.swift:527-633 (research, a replacing answer returned at :779 before the check at :798), AgenticOrchestrator.swift:746-760 (the check in the good branch), AgenticOrchestrator+Research.swift:53-117 (the first search at :90), AgenticOrchestrator+Research.swift:264-297, AgenticOrchestrator+Retrieval.swift:717-732 (topK 20), AgenticOrchestrator.swift:640-659, AgenticOrchestrator+SelfRAG.swift:468-645 (maxStrikes 3, the break at the third strike at :518, research once at :525), AgenticOrchestrator+SelfRAG.swift:617-672, AgenticOrchestrator+SelfRAG.swift:823-892 (verifyCitations), AgenticOrchestrator.swift:41-49, the v5.6.0 tag (isDeepThinkMode = config.maxSteps >= 8 at its lines 780 and 886)] - Back in RAGService, for every agentic answer. A value the extractor locks replaces the answer outright. A lookup that is not source-locked then gets the source-only check, two on-device sessions that can replace the answer. Otherwise, from 5.7, the nine gates run once and set the label: Verified, with the gates’ mean confidence, only when all nine pass, and Unverified, naming the failed gates, otherwise. They are Standard’s gates with Gate A’s score floor raised by the mode, from 0.40 to 0.45 in Deep Think and 0.50 in Maximum (0.55 to 0.60 and 0.65 for a touchy question), and Gate E’s grounding floor from 0.50 to 0.525 and 0.55. They never abstain or regenerate, and their result is not passed to the structured answer, so no claim is dropped. The mode’s verification bar (0.60 in Deep Think and 0.80 in Maximum, halved for lookups with a floor of 0.25) is read only on Standard’s abstain path, so it decides nothing for these answers. In 5.6 no gates ran on these answers, and they read Not Checked unless the source-only check ran. If an agentic run fails with an error on a precision question, the whole question is asked again through the Standard pipeline.
[evidence_level: code_verified, confidence: exact, evidence_source: RAGService+AgenticQuery.swift:754-830 (the extractor override at :757-762, the source-only check from :777, the gates from :811), verifyAgenticAnswer and verificationSummary at RAGService+Generation.swift:979-1028, RAGService+AgenticQuery.swift:898-912 (the Standard rerun), RAGService+QueryExits.swift:614 (the only reader of verificationPassThreshold), Services/RAG/Tuning/ConfidencePolicyService.swift:26-54, Services/RAG/Safety/VerificationGateService.swift:95-101 (the default floors), :175 and :295-318 (Gate A reads the top score alone), :712-713 (Gate E), :249 and :265 (passed means all nine), Core/Models/RAGQualityMode.swift:226-233, the v5.6.0 tag (no verifyAgenticAnswer)] - Maximum. The same precision shortcut and front half run, with the
unlimitedconfiguration (50 steps, 200,000 tokens, confidence 0.98, escalation 0.50, so an excellent grade needs a top score over 0.60 and a top-3 average over 0.50). An excellent pool goes to Maximum’s own loop. It gathers once, the full pipeline at topK 50 plus 3 variations of the question at topK 20, and then each session reads the next 3 passages it has not read, as sentences extracted to 2,500 characters, in one on-device call of up to 1,000 tokens at temperature 0.7, then 0.5 from session 4 and 0.3 from session 9. Its ceiling is min(50, max(8, ceil(pool ÷ 3) × 1.5)), so a pool of 60 passages allows 30 sessions. It stops when completed (confidence 0.98 and sub-question coverage on target), when converged (checked from the start of session 6: a low-novelty streak of 2, a saturation streak of 3, or every passage read), at the ceiling, or after 3 failed sessions in a row, each failure followed by a 1.5 second pause. From 5.7 it also waits 1 second before each session from the second while iOS 27 asks apps to use less, as Deep Think’s chain does, and the session count is not cut. Its re-retrieval branch cannot run: it needs a saturation streak of 3, which first exists at the start of session 6, where “converged” already stops the loop. Every 5 sessions it writes a running answer on the device. The final synthesis reads the claim bank (at most 1,500 characters) and recent insights, a refinement call follows when there are more than 8 insights and the answer is over 800 characters, and Self-RAG 2.0 checks the answer once, with no retry. A good pool runs Deep Think’s chain with the unlimited chain configuration (still one session per distinct window, up to 50) and an exhaustive synthesis, with no Self-RAG check. Moderate and low run as in Deep Think.[evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator+Types.swift:140-149, AgenticOrchestrator.swift:396-473, AgenticOrchestrator+MultiChain.swift:32-55, AgenticOrchestrator+Maximum.swift:590-593, AgenticOrchestrator+Maximum.swift:701-723, AgenticOrchestrator+Maximum.swift:724-825, AgenticOrchestrator+Maximum.swift:1042 and :1066 (insight before confidence), AgenticOrchestrator+Maximum.swift:657-664 (the 5.7 pause), AgenticOrchestrator+Maximum.swift:828-855, AgenticOrchestrator+Maximum.swift:905-937, AgenticOrchestrator+Maximum.swift:954-971, AgenticOrchestrator+Maximum.swift:1095, AgenticOrchestrator+Maximum.swift:1351-1508, AgenticOrchestrator+ReasoningChain.swift:1106-1195, AgenticPolicyService.swift:109-114, :334-364 and :397, RAGService+AgenticQuery.swift:383-391] - Per-device budgets. Deep Think’s configuration comes from
DeviceCapabilityService.optimizedAgenticConfig(), not from the named profiles: A17 Pro 5 steps, 20,000 tokens, confidence 0.85, escalation 0.35. A18 and A18 Pro 8, 32,000, 0.90, 0.40. A19 10, 40,000, 0.92, 0.45. The ultra tier 12 steps and 56,000 tokens for each 16 GB of memory, never fewer than 12 and 56,000 and at most 32 and 128,000, with 0.95 and 0.50. The tier comes from the chip: the ultra tier is a Mac with an M1 Ultra or an M2 or later, an iPad Pro with an M2 or later and an iPhone with an A20 or later, by model identifier. Macs with an M1, M1 Pro or M1 Max, the M1 iPads and the M2 iPad Air get the A18’s numbers, and the M3 iPad Air and a device family the build does not recognize get the A19’s. A device without Apple Intelligence gets thefastprofile. The step count only picks the chain’s starting configuration (with its finding length, 2,000 characters on an A17 Pro and 2,500 from the A18 on) and caps the decomposed pipeline at the steps less 2. The token figure is checked only by the decomposed pipeline and the research rounds. ThedefaultConfigandthoroughprofiles drive no mode,fastdrives only that unsupported tier and Standard’s developer-forced chain, andmaxConcurrentAgenticStepsandmaxAgenticTokenBudget(5 steps and 24,000 tokens on an A18) are only printed in a diagnostic summary.[evidence_level: code_verified, confidence: exact, evidence_source: DeviceCapabilityService.swift:1063-1114 (optimizedAgenticConfig, ramMultiplier = max(1.0, memory ÷ 16 GB) at :1100), :1115-1177 (the device family, .advanced for an unknown one), :1178-1328 (Mac chips, M1, M1 Pro and M1 Max at .enhanced), :1334-1403 (iPhones, A20 at .ultraAdvanced), :1404-1499 (iPads), :624-649, :1733-1734, AgenticOrchestrator+Types.swift:116-149, AgenticOrchestrator.swift:53-67 and AgenticOrchestrator+Types.swift:208-225 (the chain configurations), AgenticOrchestrator+Retrieval.swift:618-620, AgenticOrchestrator+Research.swift:114, RAGService+Agentic.swift:27-33 (Standard's forced chain on .fast), RAGQualityMode.swift:178-183, RAGService+AgenticQuery.swift:383-391] - Tools. Six are registered: retrieve corpus evidence, inspect a document, compare a topic across documents, a library overview and two exact-pattern tools. The main model service carries the tool handler, so they are attached to any call that leaves
disableToolsoff. Standard turns them off once it has passages to pack, every Deep Think and Maximum session and synthesis passesdisableTools: true, and the helper calls run in a fresh session with no tool handler, so no Deep Think or Maximum step asks the model to choose a tool. No call leaves them on: Standard’s direct chat in a library with no documents (reliability mode on, and not a question from Siri or Shortcuts) also passesdisableTools: true(noDocumentsConfig, since 2026-10-21 in 5.7), so no call in any mode is given the six tools (read in the code, not run). (Corrected 2026-11-07: this said one call left them on, withdisableToolsat its default, false.)[evidence_level: code_verified, confidence: exact, evidence_source: Services/AIPlatform/AppleFoundationModels/FoundationModelToolRegistry.swift:327-360, FoundationModelSessionFactory.swift:31-32, Services/LLM/AppleFoundationLLMService.swift:408-414, RAGService.swift:1052 and RAGService+Consent.swift:114-117 (toolHandler = self), RAGService+QueryContext.swift:1120-1141 (disableToolsForAssembledContext), RAGService+QueryExits.swift:730-800 (answerWithoutDocuments, disableTools set at :794-795), Core/Models/LLMModel.swift:173 (disableTools defaults to false), AgenticOrchestrator+ReasoningChain.swift:623, AgenticOrchestrator+ReasoningChain.swift:1267, AgenticOrchestrator+Maximum.swift:924, AgenticOrchestrator+Maximum.swift:1456, AgenticOrchestrator+Maximum.swift:1506, RAGService+Agentic.swift:87-132] - Standard’s checks. The nine gates, A to I, run once after the answer is written, and Gate I runs with the others. When one fails, Standard abstains only if reliability mode and developer tuning are both off (reliability mode is on by default) or the gates’ overall confidence is under the bar, 0.50, or 0.25 for lookups. Otherwise it shows the answer labelled Unverified. The text shown stays the model’s own. The gates’ result rebuilds only the structured answer, whose claim list (under FACT CHECK) loses each claim Gate B could not support, and each such claim is listed as a gap. Only when no claim is supported and reliability mode and developer tuning are both off does the structured answer become a refusal, which is then what shows. Nothing is regenerated. The abstain flag the critical gates (A, C and E) set decides nothing: it only adds its reason to that list of gaps. For a lookup whose gates did not pass, the source-only check can replace the answer. Before the gates, a value the extractor locks replaces a lookup’s answer, and from 5.7 the model’s answer stands when it already states that value.
[evidence_level: code_verified, confidence: exact, evidence_source: Services/RAG/Safety/VerificationGateService.swift:61-72, :242-271 (Gate I with the others, passed means all nine, the abstain flag), :1036-1050, RAGService+QueryPipeline.swift:943-945, RAGService+QueryAnswer.swift:207-240 (the extractor override), RAGService+QueryAnswer.swift:283-346, RAGService+QueryExits.swift:579-668 (the abstain rule, verificationPassThreshold at :614), RAGService+QueryAnswer.swift:819-865 (the structured answer from the gates' result), RAGService+QueryAnswer.swift:347-407 (the source-only check), RAGService+AnswerFinishing.swift:1043-1060 (resolvedDisplayResponse shows the model's text unless the structured answer refuses), RAGService+QueryPreparation.swift:78 (allowUngroundedFallback = reliability mode or developer tuning), Core/Models/StructuredAnswer.swift:955-976 (applyVerification: unsupported claims and the abstain reason become gaps) and :979-1048 (sanitizeForVerification), Features/Chat/Response/GroundedAnswerView.swift:71-99, SettingsStore.swift:534-535, ConfidencePolicyService.swift:48-54] - In the source and on no path.
executeHonestSynthesis, Maximum’s re-retrieval branch, HyDE in all three modes, contextual compression in all three modes (only Deep Think’s flag is on, and Deep Think never reaches that step), planner escalation while Apple’s model writes the answers, the entity index (nothing fills it),VecturaVectorDatabase, the per-modeRAGQualityMode.mmrLambda(both pipelines use the library’s),RAGQualityMode.agenticConfigfor Deep Think,agenticStepCooldownMs, Gate A’s margin check (checkRetrievalConfidence), and themaxAgenticStepsandmaxQueryTimeoutSecondsvalues ofAdaptivePipelineOptimizer, which nothing outside the optimizer reads. So a critical thermal state does not switch Deep Think or Maximum off, and neither loop reads the optimizer’s level, the thermal state, the memory pressure, the battery or Low Power Mode, so none of them makes Deep Think or Maximum do less. The battery lowers no work anywhere: the optimizer lowers its level only for a critical thermal state or critical memory pressure. The optimizer’sstepCooldownMsis read: Standard waits that long before its generation step, 200 ms on an A17 Pro, 100 on an A18, 50 on an A19 and 0 on the ultra tier, 150 ms more under critical memory pressure and 300 ms at critical heat, and nothing applies it to Deep Think or Maximum.[evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator+Retrieval.swift:527, AgenticOrchestrator+Maximum.swift:724-825, RAGService+QueryPreparation.swift:603-684 (gateAndGenerateHyDE), RAGService+ToolHandler.swift:151-154, RAGService+QueryContext.swift:1069-1119 (gateContextualCompression) and RAGService+QueryContext.swift:29-195 (compressContextCandidates), QueryRuntimeCoordinator.swift:211, Core/Models/RAGStructuredResponse.swift@b914298b:238-278 (the hand-off types, removed 2026-11-06), Services/Document/Analysis/EntityIndexService.swift:31 and :137, Services/VectorStore/VectorStoreRouter.swift:167-172, RAGQualityMode.swift:210-217, :277-284 and :315-330 (featureToggles, which nothing reads), RAGService+QueryRetrieval.swift:906-946 and RAGService+ToolHandler.swift:337-345, DeviceCapabilityService.swift:650-660, Services/RAG/Safety/VerificationGateService.swift:279-288, Services/Infrastructure/Optimization/AdaptivePipelineOptimizer.swift:100-113, :115-261 (the cooldown per tier and level), :56-71 (recommendedOptimizationLevel: "Battery level no longer triggers degradation") and :408-413 (applyCooldown), RAGService+QueryAnswer.swift:44 (Standard awaits it, in beginGenerationStep), RAGService+QueryPreparation.swift:151, RAGService+QueryRetrieval.swift:996 and RAGService+QueryContext.swift:1085 (the only reads of the adaptive configuration), searches of every Swift file under OpenIntelligence/ for a caller or reader (none)](Removed 2026-11-06, no longer in the source:executeMultiChainReasoningwith its cluster chains, and theChainLink,ReasonedInsightandReasonedSynthesishand-off types, which had no caller.[evidence_level: code_verified, confidence: exact, evidence_source: AgenticOrchestrator+MultiChain.swift@b914298b:24, AgenticOrchestrator+MultiChain.swift@b914298b:382, RAGStructuredResponse.swift@b914298b:238-278, grep -rn "executeMultiChainReasoning\|ChainLink\|ReasonedInsight\|ReasonedSynthesis" OpenIntelligence on 2026-11-06 (no hits)])