SPB Git

Repository Public

overview.md 28.8 KB 405 lines markdown

1# Architecture overview23ORIX Sheet is a native macOS spreadsheet (Swift 6 language mode, macOS 14 deployment target, AppKit4document architecture with SwiftUI chrome). The repository is one thin application target5(`App/Sources`, 9 Swift files) on top of 22 local Swift packages under `Packages/`. There is no6third-party Swift dependency: the only external binary is the DuckDB C library, vendored as7`Vendor/duckdb/CDuckDB.xcframework` and fetched by `Scripts/fetch-duckdb.sh`.89This page is the map. Each subsystem has its own document:1011| Subsystem | Document |12|---|---|13| Grid drawing, editing, printing | [grid-engine.md](grid-engine.md) |14| Lexer, parser, evaluator, function registry | [formula-engine.md](formula-engine.md) |15| Dependencies, recalculation, spills, cycles | [calculation-graph.md](calculation-graph.md) |16| DuckDB datasets, transforms, pivots | [data-engine.md](data-engine.md) |17| Python subprocess and sandbox | [python-runtime.md](python-runtime.md) |18| Charts and Figure Studio | [chart-engine.md](chart-engine.md) |19| `.orixsheet` packages, save, import, export | [persistence.md](persistence.md) |20| On-device assistance | [intelligence.md](intelligence.md) |21| Threat model | [../security.md](../security.md) |22| Building and running | [../development/setup.md](../development/setup.md) |2324## 1. Package map2526The dependency lists below are read from the `Package.swift` manifests27(`.package(path: "../…")` entries); nothing is inferred from imports.2829### 1.1 Layers3031| Layer | Packages | Role |32|---|---|---|33| Model and calculation core | `SheetCore` | Workbook model (`Workbook`, `Sheet`, `Cell`, `Value`, styles, addresses, date serials), formula lexer/parser/printer, evaluator, dependency graph, `CalcEngine`, editing with undo, fill, reference rewriting, `FunctionRegistry`. Depends on nothing. |34| Function libraries | `FunctionsNumeric`, `FunctionsText`, `FunctionsLookup` | Worksheet functions registered into `FunctionRegistry.standard`. `FunctionsNumeric` links Accelerate (LAPACK through the C target `CNumericLAPACK`); `FunctionsLookup` also holds the financial functions (`FinancialFunctions.register()`). |35| Number formats | `SheetFormat` | Excel number-format codes: parsing, rendering, format editing helpers, built-in catalogue. |36| Engine bootstrap | `SheetEngine` | One file, `Bootstrap.swift`: `ORIXEngine.bootstrap()` registers the four libraries once per process. Also the `orix-bench` executable. |37| File formats | `SheetIO` | `.orixsheet`, XLSX/XLSM, ODS, CSV/TSV, JSON/JSONL readers and writers, own ZIP/Deflate reader (links `libz`), export preflight. Depends only on `SheetCore`. |38| Engines without UI | `SheetData` (DuckDB), `SheetCharts` (CoreGraphics/CoreText/ImageIO), `SheetAnalytics` (products `Statistics`, `FinanceModels`, `WhatIf`, `Audit`; Accelerate), `SheetPython`, `SheetIntelligence` | Each depends on `SheetCore`; `SheetIntelligence` additionally on the three function libraries and `SheetAnalytics`. |39| UI kit | `SheetUI` | `WorkbookSession`, the AppKit `GridView`, SwiftUI chrome, design tokens, the `Workspace` extension registry. Depends on `SheetCore` and `SheetFormat` only. |40| Features | `FeatureAudit`, `FeatureCharts`, `FeatureData`, `FeaturePython`, `FeatureAnalysis`, `FeatureIntelligence`, `FeatureAutomation` | Panels and commands; each pairs `SheetUI` with one engine and registers itself in `Workspace.shared`. |41| Automation engine | `SheetAutomation` | Workflow model, validator, `WorkflowEngine`, workflow and trust stores, the `AutomationPDF` library and the `orix-sheet` command-line tool. See [automation.md](automation.md). |42| Templates | `SheetTemplates` | Fifteen workbook templates built in code, their thumbnails and the `TemplateLibrary`. See [../templates.md](../templates.md) and [section 7](#7-templates-and-automation). |43| Application | `App/Sources` | `NSApplication` entry point, `WorkbookDocument` (`NSDocument`), main menu, settings, welcome/help windows, launch arguments. |4445Source: `Packages/*/Package.swift`, `App/Sources/*.swift`, `project.yml`.4647### 1.2 Core and engine packages4849<!-- diagram: overview-packages-core -->50```mermaid51flowchart TD52    SheetEngine["SheetEngine<br/>ORIXEngine.bootstrap"] --> FunctionsNumeric["FunctionsNumeric"]53    SheetEngine --> FunctionsText["FunctionsText"]54    SheetEngine --> FunctionsLookup["FunctionsLookup<br/>lookup + financial"]55    SheetEngine --> SheetFormat["SheetFormat"]56    FunctionsText --> SheetFormat57    SheetUI["SheetUI<br/>session, grid, chrome"] --> SheetFormat58    FunctionsNumeric --> SheetCore["SheetCore<br/>model, parser, CalcEngine"]59    FunctionsLookup --> SheetCore60    SheetFormat --> SheetCore61    SheetIO["SheetIO"] --> SheetCore62    SheetData["SheetData<br/>DuckDB"] --> SheetCore63    SheetCharts["SheetCharts"] --> SheetCore64    SheetAnalytics["SheetAnalytics"] --> SheetCore65    SheetPython["SheetPython"] --> SheetCore66    SheetIntelligence["SheetIntelligence"] --> SheetAnalytics67    SheetIntelligence --> FunctionsNumeric68```6970SVG fallback: ![Core and engine package dependencies](../assets/diagrams/overview-packages-core.svg)7172Edges to `SheetCore` that are implied by another drawn edge are omitted for legibility73(`SheetEngine`, `FunctionsText`, `SheetUI` and `SheetIntelligence` all depend on `SheetCore`74directly; `SheetIntelligence` also depends on `FunctionsText` and `FunctionsLookup`). The complete75lists are in the table of section 1.4.7677### 1.3 Feature packages and the application7879<!-- diagram: overview-packages-features -->80```mermaid81flowchart TD82    App["ORIX Sheet.app<br/>App/Sources"] --> FeatureAudit["FeatureAudit"]83    App --> FeatureCharts["FeatureCharts"]84    App --> FeatureData["FeatureData"]85    App --> FeaturePython["FeaturePython"]86    App --> FeatureAnalysis["FeatureAnalysis"]87    App --> FeatureIntelligence["FeatureIntelligence"]88    App --> FeatureAutomation["FeatureAutomation"]89    App --> SheetTemplates["SheetTemplates"]90    App --> SheetEngine["SheetEngine"]91    App --> SheetIO["SheetIO"]92    FeatureAudit --> SheetAnalytics["SheetAnalytics"]93    FeatureAnalysis --> SheetAnalytics94    FeatureAnalysis --> SheetCharts["SheetCharts"]95    FeatureCharts --> SheetCharts96    FeatureData --> SheetData["SheetData"]97    FeaturePython --> SheetPython["SheetPython"]98    FeatureIntelligence --> SheetIntelligence["SheetIntelligence"]99    FeatureAutomation --> SheetAutomation["SheetAutomation"]100    FeatureAudit --> SheetUI["SheetUI"]101    FeatureCharts --> SheetUI102    FeatureData --> SheetUI103    FeaturePython --> SheetUI104    FeatureAnalysis --> SheetUI105    FeatureIntelligence --> SheetUI106    FeatureAutomation --> SheetUI107```108109SVG fallback: ![Feature packages and the application](../assets/diagrams/overview-packages-features.svg)110111The six panel features (`FeatureAudit`, `FeatureCharts`, `FeatureData`, `FeaturePython`,112`FeatureAnalysis`, `FeatureIntelligence`) depend on no other feature package and on neither `SheetIO`113nor `SheetEngine`: they see the workbook only through `SheetCore` types and the `WorkbookSession` they114are handed. Two packages are different, and their extra edges are left out of the diagram for115legibility (the complete lists are in section 1.4):116117- `FeatureAutomation` also depends on `SheetEngine` and `SheetIO`, and `SheetAutomation` depends on118  nine packages (`SheetCore`, `SheetEngine`, `SheetFormat`, `SheetIO`, `SheetUI`, `SheetData`,119  `SheetCharts`, `SheetAnalytics`, `SheetPython`): a workflow opens, converts and exports files and120  drives the data, chart, audit and Python engines without a window.121- `SheetTemplates` depends on `SheetCore`, `SheetEngine`, `SheetCharts`, `SheetFormat` and `SheetIO`122  for the library, and on `SheetUI`, `FeatureCharts` and `FeatureAudit` for its `templates-preview`123  harness only (both can be switched off with `ORIX_TEMPLATES_NO_PREVIEW` /124  `ORIX_TEMPLATES_NO_FEATURES`).125126The application also links `SheetCore`, `SheetFormat` and `SheetUI` directly (`project.yml`).127128### 1.4 Complete dependency table129130| Package | Local package dependencies | Products | System libraries declared |131|---|---|---|---|132| SheetCore | — | library `SheetCore` | — |133| SheetFormat | SheetCore | library `SheetFormat` | — |134| FunctionsNumeric | SheetCore | library `FunctionsNumeric` | Accelerate |135| FunctionsText | SheetCore, SheetFormat | library `FunctionsText` | — |136| FunctionsLookup | SheetCore | library `FunctionsLookup` | — |137| SheetEngine | SheetCore, SheetFormat, FunctionsNumeric, FunctionsText, FunctionsLookup | library `SheetEngine`; executable target `orix-bench` | — |138| SheetIO | SheetCore | library `SheetIO` | libz |139| SheetData | SheetCore | library `SheetData`; executable `orix-data-bench` | binary target `CDuckDB` (`Vendor/duckdb/CDuckDB.xcframework`), libsqlite3 |140| SheetCharts | SheetCore | library `SheetCharts`; executable `chart-gallery` | CoreGraphics, CoreText, ImageIO, UniformTypeIdentifiers |141| SheetAnalytics | SheetCore | libraries `Statistics`, `FinanceModels`, `WhatIf`, `Audit` | Accelerate |142| SheetPython | SheetCore | library `SheetPython` | — |143| SheetIntelligence | SheetCore, SheetAnalytics, FunctionsNumeric, FunctionsText, FunctionsLookup | library `SheetIntelligence` | — |144| SheetUI | SheetCore, SheetFormat | library `SheetUI`; executable target `sheet-preview` | — |145| FeatureAudit | SheetCore, SheetUI, SheetAnalytics, FunctionsNumeric | library `FeatureAudit`; executable `audit-preview` | — |146| FeatureCharts | SheetCore, SheetUI, SheetCharts, SheetFormat | library `FeatureCharts`; executable `charts-preview` | — |147| FeatureData | SheetCore, SheetUI, SheetData | library `FeatureData`; executable `data-preview` | — |148| FeaturePython | SheetCore, SheetUI, SheetPython | library `FeaturePython`; executable `python-studio-preview` | — |149| FeatureAnalysis | SheetCore, SheetUI, SheetAnalytics, SheetCharts, FunctionsNumeric, FunctionsLookup | library `FeatureAnalysis`; executable `analysis-preview` (+ 4 per-area preview targets) | — |150| FeatureIntelligence | SheetCore, SheetUI, SheetIntelligence, SheetAnalytics, FunctionsNumeric, FunctionsText, FunctionsLookup | library `FeatureIntelligence`; executable `intelligence-preview` | — |151| SheetTemplates | SheetCore, SheetEngine, SheetFormat, SheetIO, SheetUI, SheetCharts, FeatureAudit, FeatureCharts | library `SheetTemplates`; executable `templates-preview` | CoreGraphics, CoreText, ImageIO |152| SheetAutomation | SheetCore, SheetEngine, SheetFormat, SheetIO, SheetUI, SheetData, SheetCharts, SheetAnalytics, SheetPython | libraries `SheetAutomation`, `AutomationPDF`; executable `orix-sheet` | — |153| FeatureAutomation | SheetCore, SheetUI, SheetEngine, SheetIO, SheetAutomation | library `FeatureAutomation`; executable `automation-preview` | — |154155Source: `Packages/*/Package.swift` (extracted with a script on 2026-11-21; every manifest declares156`swift-tools-version: 6.0` and `platforms: [.macOS(.v14)]`).157158### 1.5 Size of each package159160| Package | Swift files (Sources) | Lines (Sources) | Lines (Tests) |161|---|---:|---:|---:|162| SheetCore | 17 | 4 659 | 465 |163| SheetFormat | 9 | 1 478 | 697 |164| FunctionsNumeric | 21 | 3 497 | 964 |165| FunctionsText | 10 | 1 256 | 523 |166| FunctionsLookup | 11 | 2 325 | 1 232 |167| SheetEngine | 2 | 176 | 81 |168| SheetIO | 31 | 7 500 | 2 915 |169| SheetData | 20 | 4 317 | 1 744 |170| SheetCharts | 45 | 7 220 | 1 306 |171| SheetAnalytics | 93 | 15 239 | 7 239 |172| SheetPython | 10 | 1 655 | 1 409 |173| SheetIntelligence | 12 | 2 375 | 1 080 |174| SheetUI | 20 | 4 929 | 512 |175| FeatureAudit | 28 | 5 983 | 1 372 |176| FeatureCharts | 35 | 6 209 | 1 369 |177| FeatureData | 34 | 7 766 | 1 401 |178| FeaturePython | 15 | 2 925 | 758 |179| FeatureAnalysis | 85 | 9 771 | 2 546 |180| FeatureIntelligence | 6 | 1 597 | 331 |181| SheetTemplates | 22 | 2 980 | 930 |182| SheetAutomation | 20 | 4 182 | 1 631 |183| FeatureAutomation | 16 | 3 125 | 683 |184| App/Sources (tests: App/Tests) | 10 | 1 292 | 235 |185186Source: `find Packages/<name>/Sources -name '*.swift' | xargs cat | wc -l` (and the same for187`Tests`), run on 2026-11-21 at 03:54 EST. Physical lines, blank lines and comments included. Python,188C and resource files are not counted. Test counts by package are in `docs/reports/tests.json`,189produced by `Scripts/test-all.sh` (see [../development/testing.md](../development/testing.md)).190191## 2. What the application target contains192193| File | Content |194|---|---|195| `main.swift` | Creates `NSApplication`, installs `AppDelegate`, runs. No SwiftUI `App` type: the app uses the AppKit document architecture. |196| `Features.swift` | `Features.registerAll()`, in this order: `ORIXEngine.bootstrap()`, `AuditFeature.register()`, `DataFeature.register()` (plus the close handler `DataWorkspace.close`), `PythonFeature.register()`, `ChartsFeature.register()` (plus the session observer `ChartsFeature.attach(to:)`), `AnalysisFeature.register()`, `IntelligenceFeature.register()`, `AutomationFeature.register()`, then `Welcome.provider = WelcomeProvider(…)` built on `TemplateChooser` and `TemplateLibrary`. Also the list of close handlers run when a document closes. |197| `WorkbookDocument.swift` | The `NSDocument` subclass: reading, native writing, export, PDF export, printing, window creation, the import report. |198| `AppDelegate.swift` | Menu actions forwarded to the current `WorkbookSession`; `LaunchArguments` (the `-ORIX…` arguments used by tests, screenshots and localization checks, listed in [../development/setup.md](../development/setup.md)). |199| `MainMenu.swift` | The menu bar, including the menus generated from `Workspace.shared.actions` and `panes`. |200| `AppSettings.swift` | Preferences stored in `UserDefaults`: formula separators, appearance, welcome window, background-calculation threshold (default 20 000 pending formulas), default zoom (75–200 %). |201| `Welcome.swift` | The welcome window that hosts the template chooser (`Welcome.provider`, assigned by `Features.registerAll()`) and the Help window with the shortcut list. |202| `TemplateChooser.swift` | The SwiftUI template chooser shown at launch and from *File ▸ New from Template…* (categories, thumbnails, blank workbook, open existing), and `ORIXSheetIntents`, the `AppIntentsPackage` that includes the intents of `FeatureAutomation`. |203| `CompatibilityReport.swift`, `PageSetupView.swift` | The import/export report sheet and the page-setup sheet. |204205`project.yml` also declares an app-hosted XCTest bundle, `ORIXSheetTests` (`App/Tests`, 9 tests; result206in `docs/reports/app-tests.json`). No script in `Scripts/` runs it; the command is in207[../development/testing.md](../development/testing.md).208209Source: `App/Sources/*.swift`, `project.yml`.210211## 3. Threading model212213There are four kinds of execution context. Swift strict concurrency is set to `complete` for the214application target (`project.yml`).215216| Context | What runs there | Where it is defined |217|---|---|---|218| Main actor | `WorkbookSession` (`@MainActor @Observable`), every view, `Workspace`, `NSDocument` reading and writing (the document overrides are `nonisolated` and hop with `MainActor.assumeIsolated`; `canConcurrentlyReadDocuments` returns `false`), all model mutations (`session.perform`). | `SheetUI/Session/WorkbookSession.swift`, `App/Sources/WorkbookDocument.swift` |219| Deep-stack calculation thread | Every `CalcEngine.recalculate` body, and every ad-hoc evaluation that calls `CalcEngine.runDeep` (conditional-format evaluation, validation, formula/error explainers, name rules in the auditor). `runDeep` starts a `Thread` with `stackSize = 1 << 29` bytes (512 MiB), QoS user-initiated, and blocks the caller on a semaphore until the body returns; a call made from such a thread runs inline. | `SheetCore/Engine/CalcEngine.swift` (`runDeep`) |220| Session calculation queue | Serial `DispatchQueue` `ai.spboucher.orix.sheet.calc`. Used only when more formulas are pending than `syncCalcThreshold` (20 000 by default, user setting): the queue calls `engine.recalculate(progress:isCancelled:)`, which in turn uses a deep-stack thread. | `WorkbookSession.runCalc` |221| Feature background work | Data: serial queues `ai.spboucher.orix.sheet.data.work` and `…data.pages` (DuckDB work and grid paging). Charts: concurrent queue `ai.spboucher.orix.charts.render`. Analysis tools and scenarios: `Task.detached(priority: .userInitiated)`. Python: a child process plus reader threads. Intelligence and the workflow engine are Swift actors. | `FeatureData/Core/DataWorkspace.swift`, `FeatureCharts/Render/ChartRenderCache.swift`, `FeatureAnalysis/…/ToolRunner.swift`, `SheetPython/Spawn.swift`, `SheetIntelligence/Intelligence.swift` |222223Source: the files named in the last column.224225### 3.1 The engine lock226227`CalcEngine` is declared `@unchecked Sendable` and is **not re-entrant**: its documentation228requires callers to serialize all mutations and `recalculate` calls. The session provides that229serialization (everything goes through the main actor, and a background recalculation is halted230before any mutation, see below).231232`CalcEngine.lock` (an `NSLock`) is held while computed values are written. Readers that may run233while a background recalculation is in progress take the same lock: the selection summary in the234status bar (`WorkbookSession.selectionSummary`), and the document when it serializes the workbook235(`WorkbookDocument.writeOnMain` and `export` lock the engine around `WorkbookWriter.save`).236237### 3.2 A mutation, step by step238239<!-- diagram: overview-mutation-sequence -->240```mermaid241sequenceDiagram242    participant V as View or menu action243    participant S as WorkbookSession (main actor)244    participant E as CalcEngine245    participant T as Deep-stack thread246    V->>S: perform(label, body)247    S->>S: haltCalculation()248    S->>E: transaction(label) body249    E-->>S: changeCount changed250    S->>S: registerUndo(label)251    S->>E: recalculate()252    E->>T: runDeep(recalcBody)253    T-->>E: RecalcStats254    S->>V: invalidate(content: true)255```256257SVG fallback: ![Sequence of a model mutation](../assets/diagrams/overview-mutation-sequence.svg)2582591. `perform` first calls `haltCalculation()`: if a background recalculation is running it sets the260   cancel flag, waits for the calculation queue to drain (`calcQueue.sync {}`) and clears the flag.261   The engine polls the flag between top-level dirty entries, once at least 4 096 cells have been262   evaluated since the previous poll (a long chain evaluated on demand from one entry is not263   interrupted); cells not yet evaluated stay dirty.2642. The body runs inside `engine.transaction(label)`, which groups its edits into one undo step.2653. If `engine.changeCount` moved, an undo action is registered with the document's `UndoManager`266   (the session is given the document's undo manager in `WorkbookDocument.adopt` and267   `makeWindowControllers`). Registering the undo is what marks the `NSDocument` as edited.2684. `runCalc()` recalculates: inline when `engine.pendingCount <= syncCalcThreshold` (the main269   thread waits for the deep-stack thread), otherwise on the calculation queue with a throttled270   progress reporter; on completion the main actor stores the statistics and invalidates views.2715. `invalidate(content: true)` bumps `revision` and `contentRevision` and calls the listeners272   (the grid registers one in `GridView.init`).273274`WorkbookSession.onChange` ("called after every committed change") is invoked by the session and by275several features after changes that do not go through the engine's undo (for example saving a276Python script, a transform pipeline, a figure setting or scenario data into workbook attachments).277`WorkbookDocument.adopt` assigns it (`session.onChange = { updateChangeCount(.changeDone) }`), so such a278change marks the document edited even though it registers no undo action. For undoable transactions the279session does not call `onChange` when an undo manager is attached: the registered undo marks the280document.281282What is deliberately not done: formulas are not evaluated on several threads, and there is no283iterative calculation. See [calculation-graph.md](calculation-graph.md).284285## 4. Document flow286287<!-- diagram: overview-document-flow -->288```mermaid289flowchart TD290    Open["Open a file"] --> Detect["FileFormat.detect(url)"]291    Detect --> Load["WorkbookReader.load"]292    Load --> Native{"Format is .orixsheet?"}293    Native -->|yes| Trust["Adopt workbook<br/>cached values trusted"]294    Native -->|no| Import["Adopt workbook, recalculate all<br/>document becomes untitled"]295    Import --> Report["Import report<br/>issues, macros, external links"]296    Trust --> Session["WorkbookSession + window"]297    Report --> Session298    Session --> Save["Save / autosave<br/>.orixsheet only"]299    Session --> Export["File - Export To<br/>preflight report, then write"]300    Session --> Print["Print / Export PDF<br/>PrintRenderer"]301```302303SVG fallback: ![Document flow from open to save, export and print](../assets/diagrams/overview-document-flow.svg)304305- **Reading.** `WorkbookDocument.read(from:ofType:)` detects the format from the file306  (`FileFormat.detect`) and falls back to the declared type, loads through `WorkbookReader.load`,307  and refuses a file without any sheet. A native file is adopted with `trustCachedValues: true`308  (stored values are shown without recalculating). Any other format is recalculated in full and309  remembered as `importedFrom`.310- **Import as untitled.** When the window is created for an imported file, the document clears its311  `fileURL`, sets its type to the native type and keeps the source's base name as display name.312  Saving then asks for a location and writes an `.orixsheet`; the source file is never overwritten.313  `writableTypes(for:)` returns the native type only.314- **Import report.** If the reader reported issues, or the file has macros or external links, the315  compatibility report is shown 0.4 s after the window appears. Macros are never run; external316  links are never fetched (see [../security.md](../security.md)).317- **Saving.** `autosavesInPlace` is `true`. `write(to:ofType:)` stamps the modification date and318  application version, takes the engine lock and calls `WorkbookWriter.save`. The parts preserved319  from an imported XLSX (`PreservedParts`) are passed along so that an export back to XLSX/XLSM can320  re-emit them.321- **Export.** `export(as:)` commits any in-progress edit, runs `WorkbookWriter.preflight`, shows322  the report with an "Export Anyway" confirmation when the format cannot hold everything, then323  writes under the engine lock. The open workbook is not modified by an export.324- **Printing and PDF.** Both go through `SheetUI`'s `PrintRenderer` / `SheetPrintView`325  ([grid-engine.md](grid-engine.md)).326- **Closing.** `close()` runs `Features.closeHandlers` (the data feature closes its DuckDB327  workspace for the session).328329Details, including the package layout and integrity checks: [persistence.md](persistence.md) and330[../compatibility/formats.md](../compatibility/formats.md).331332## 5. Extension points333334Features never subclass or patch the UI kit. They register values in the process-wide335`Workspace.shared` (`SheetUI/Session/Providers.swift`, main-actor isolated) at launch.336337| Extension point | Type | Used for | Registered by (in the shipped feature list) |338|---|---|---|---|339| Panes | `WorkspacePane` with placement `.inspector`, `.bottom`, `.sidebar` or `.studio` | A panel built from a `WorkbookSession`. A studio replaces the grid area until "Back to Sheet". Sorted by `(order, id)`. | Every feature |340| Actions | `WorkspaceAction` in group Insert, Data, Analyze or Tools, optional ⌘-shortcut | Commands shown in the toolbar menus and the menu bar (`performWorkspaceAction`). A requested shortcut already claimed by an earlier action is dropped (`MainMenu.workspaceItems`), so the menu bar never has a duplicate key equivalent | Every feature |341| Object renderers | `ObjectRenderer` per `SheetObject.kind`: `draw(object, session, CGContext, rect, dark)` and `open(object, session)` | Embedded objects drawn inside the grid and in print output | `FeatureCharts` (chart objects) |342| Session observers | `sessionObservers: [(WorkbookSession) -> Void]`, called at the end of `WorkbookSession.init` | Attaching per-workbook state | `App/Sources/Features.swift` appends `ChartsFeature.attach(to:)` |343| Display provider | `CellDisplayProvider` | Value → display text and colour. The default and the app both use `FormatDisplayProvider` (SheetFormat). | `AppDelegate` |344| Effects provider | `CellEffectsProvider` | Conditional-format results per visible range, called on the main thread before drawing | `FeatureAudit` (`ConditionalEffectsAdapter`) |345| Input validator | `InputValidator` | Data validation on commit, drop-down items | `FeatureAudit` (`ValidationAdapter`) |346| Formula assist | closure `(text, cursor, session) -> FormulaAssist?` | Completion candidates and signature hints in the formula editor | `FeatureAudit` (`AssistAdapter`) |347| Format tools | `NumberFormatTools` | Toolbar buttons (decimals, currency, percent, thousands) and the format catalogue | Default value built on SheetFormat |348| Structural observers | `CalcEngine.structuralObservers[key]`: `(RefTransform, Workbook) -> Void` | Remapping references kept in object payloads when rows, columns or sheets move; runs under the engine lock, inside the undo snapshot | `FeatureCharts` (`ChartStructure`) |349| Session listeners | `WorkbookSession.addListener` | Redraw notifications after `invalidate` | `GridView`, features |350| Function registry | `FunctionRegistry.standard` | Worksheet functions | The three function libraries through `ORIXEngine.bootstrap()` |351352Source: `Packages/SheetUI/Sources/SheetUI/Session/Providers.swift`,353`Packages/SheetCore/Sources/SheetCore/Engine/CalcEngine.swift`, and a search for354`Workspace.shared.` assignments and `register(` calls across `Packages/*/Sources` and `App/Sources`.355356Feature state that must travel with the file is stored in the workbook itself357(`Workbook.attachments`, `SheetObject` payloads, sheet metadata) so that the native format358persists it without `SheetIO` knowing the feature.359360## 6. What runs where361362| Work | Process | Thread or queue |363|---|---|---|364| Editing, selection, undo, drawing the grid | App | Main actor |365| Recalculation of at most `syncCalcThreshold` pending formulas | App | Deep-stack thread, main thread waiting |366| Larger recalculations | App | Calculation queue → deep-stack thread, cancellable, with progress |367| Conditional formats, validation, formula explanation | App | Deep-stack thread, caller waiting |368| Reading and writing files | App | Main actor (`canConcurrentlyReadDocuments` is `false`) |369| Dataset queries, imports into DuckDB, paging | App (DuckDB is linked in-process) | Data work and page queues |370| Chart layout and rasterization for the grid cache | App | Concurrent chart render queue |371| Statistical and financial tools, scenarios | App | Detached tasks |372| Python scripts | Separate interpreter process started with `posix_spawn`, optionally under `sandbox-exec` | Reader threads in the app |373| Python syntax check of AI suggestions | Separate `python3 -I -c …` process (compile only) | — |374| On-device language model | The system's Foundation Models service, through the `Intelligence` actor | — |375| Workflows run from the Automation studio | App | The `WorkflowEngine` actor; SQL on the DuckDB queues, a Python step in a separate sandboxed interpreter process |376| Scheduled workflows, command-line use | `orix-sheet` (embedded at `Contents/MacOS/orix-sheet`), started by the user or by a per-user LaunchAgent the user installed | — |377| App Intents (Shortcuts) | The app process, without UI (`openAppWhenRun` is false) | — |378379Source: sections 3 and 5, [python-runtime.md](python-runtime.md),380[data-engine.md](data-engine.md), [chart-engine.md](chart-engine.md),381[intelligence.md](intelligence.md).382383## 7. Templates and automation384385Three packages complete the application. All three are referenced by `project.yml`, registered in386`Features.registerAll()` and covered by `Scripts/test-all.sh` (29, 78 and 28 test functions in387`docs/reports/tests.json`).388389- **`SheetTemplates`** — workbook templates built in code through a small DSL390  (`DSL/Book.swift`, `Pad.swift`, `Styles.swift`). Fifteen templates under391  `Sources/SheetTemplates/Templates/`: BusinessBudget, CashFlowForecast, DCFValuation, Dashboard,392  FinancialStatements, Gradebook, Inventory, InvestmentAnalysis, Mortgage, PersonalBudget,393  ProjectPlan, RegressionReport, ResearchDataset, SalesTracking, StatisticalAnalysis. The app shows394  them in the template chooser (`Welcome.provider`) at launch and from *File ▸ New from Template…*;395  `-ORIXTemplate <id>` opens one directly. Details and verification: [../templates.md](../templates.md).396- **`SheetAutomation`** — a workflow model serialized as JSON (`.orixflow`, schema 1) with 25 step397  kinds, a static validator, the `WorkflowEngine` actor with staged outputs, a workflow store, a398  run history and a trust store, and the `orix-sheet` command-line tool (ten commands). Details:399  [automation.md](automation.md).400- **`FeatureAutomation`** — the Automation studio pane (registered as a `.studio` pane and a Tools401  action in `AutomationFeature.register()`; the action asks for ⌥⌘A, which *Audit Workbook* already402  holds, so its menu item has no shortcut), LaunchAgent scheduling403  (`Schedule.swift`) and four App Intents (Convert Spreadsheet, Recalculate Workbook, Run ORIX404  Workflow, Get Cell Value).405
Files main
Menu

Theme