SPB Git

Repository Public

README.md 43.7 KB 566 lines markdown

1<p align="center">2  <img src="docs/assets/orix-sheet-icon-1024.png" width="168" alt="ORIX Sheet icon">3</p>45<h1 align="center">ORIX Sheet</h1>6<p align="center"><strong>Beyond Spreadsheets.</strong></p>7<p align="center">8A native macOS spreadsheet, financial-modelling and data-analysis workstation.<br>9One document, one calculation platform: an Excel-sized grid, a validated formula engine, a columnar data engine,<br>10charts and figures, statistics, local Python and on-device assistance. No account. Nothing leaves your Mac.11</p>1213<p align="center">14  <img src="docs/assets/badges/platform.svg" alt="macOS native">15  <img src="docs/assets/badges/silicon.svg" alt="Apple Silicon universal build">16  <img src="docs/assets/badges/swift.svg" alt="Swift 6">17  <img src="docs/assets/badges/ui.svg" alt="SwiftUI and AppKit">18  <img src="docs/assets/badges/engine.svg" alt="native Swift formula engine">19  <img src="docs/assets/badges/duckdb.svg" alt="DuckDB analytics">20  <img src="docs/assets/badges/python.svg" alt="local Python subprocess">21  <img src="docs/assets/badges/ai.svg" alt="on-device AI">22  <img src="docs/assets/badges/privacy.svg" alt="local first">23  <img src="docs/assets/badges/offline.svg" alt="core works offline">24  <img src="docs/assets/badges/accounts.svg" alt="no account">25</p>26<p align="center">27  <img src="docs/assets/badges/test-status.svg" alt="test suites">28  <img src="docs/assets/badges/tests.svg" alt="test count">29  <img src="docs/assets/badges/coverage.svg" alt="line coverage">30  <img src="docs/assets/badges/functions.svg" alt="worksheet functions">31  <img src="docs/assets/badges/version.svg" alt="version">32  <img src="docs/assets/badges/min-macos.svg" alt="minimum macOS">33  <img src="docs/assets/badges/build.svg" alt="release build">34  <img src="docs/assets/badges/notarization.svg" alt="notarization">35  <img src="docs/assets/badges/release.svg" alt="release status">36  <img src="docs/assets/badges/dmg-size.svg" alt="DMG size">37</p>38<p align="center">39  <img src="docs/assets/badges/open.svg" alt="workbook open benchmark">40  <img src="docs/assets/badges/recalc.svg" alt="recalculation benchmark">41  <img src="docs/assets/badges/chain.svg" alt="dependency chain benchmark">42  <img src="docs/assets/badges/csv-import.svg" alt="large CSV import benchmark">43</p>4445<p align="center"><img src="docs/screenshots/main-light.png" alt="ORIX Sheet — a budget workbook with charts, conditional formatting and the format inspector" width="100%"></p>4647> Every badge is generated by `Scripts/make-badges.py` from files in this repository (test reports, benchmark output, release facts). A value that has not been measured is shown as "not measured"; none is typed by hand.4849---5051## Contents5253[Overview](#1-overview) · [Philosophy](#2-orix-philosophy) · [Preview](#3-application-preview) · [Grid](#4-spreadsheet-grid) · [Formula engine](#5-formula-engine) · [Formatting](#6-formatting) · [Tables](#7-tables) · [Pivot tables](#8-pivot-tables) · [Transform](#9-data-transformation) · [Large data](#10-large-data-engine) · [Charts](#11-charting) · [Figure Studio](#12-figure-studio) · [Finance](#13-financial-modeling) · [Statistics](#14-statistics) · [Python](#15-python-studio) · [Local AI](#16-local-ai) · [Formula intelligence](#17-formula-intelligence) · [Auditor](#18-model-auditor) · [Automation](#19-automation) · [Import & export](#20-import--export) · [Native format](#21-native-workbook-format) · [Architecture](#22-architecture) · [Stack](#23-technology-stack) · [Installation](#24-installation) · [Build](#25-build-instructions) · [Testing](#26-testing) · [Benchmarks](#27-benchmarks) · [Excel compatibility](#28-excel-compatibility) · [Privacy](#29-privacy) · [Accessibility](#30-accessibility) · [Localization](#31-localization) · [Roadmap](#32-roadmap) · [Release status](#33-release-status) · [Known limitations](#34-known-limitations) · [ORIX ecosystem](#35-orix-ecosystem) · [License](#36-license)5455---5657## 1. Overview5859ORIX Sheet is a document-based Mac application written in Swift 6. It opens and edits workbooks on the same grid size as Excel (1,048,576 rows × 16,384 columns), calculates them with its own formula engine (473 functions, each backed by reference tests), and adds the tools analysts usually leave the spreadsheet for:6061| You want to… | ORIX Sheet gives you |62|---|---|63| keep a budget | a clean grid, 15 working templates, autosave, undo for everything |64| build a valuation model | validated financial functions, a DCF builder that writes live formulas, scenarios, goal seek, Monte Carlo, a model auditor |65| analyse millions of rows | an embedded DuckDB engine: import, preview, SQL, visual transformations, pivots — and only the result comes back into the sheet |66| run statistics | regression with robust errors, tests, time series, PCA, clustering — validated against SciPy and statsmodels |67| script it | local Python against workbook ranges, in a restricted process that you approve first |68| understand a formula | step-by-step evaluation with real intermediate values, a dependency graph, on-device explanations |69| publish | vector charts, multi-panel figures, paginated PDF |7071Everything listed in this README exists in the code and is exercised by tests; what is partial or missing is listed under [Known limitations](#34-known-limitations).7273## 2. ORIX Philosophy7475- **Instant utility.** A new workbook is one click; nothing to sign in to.76- **Professional precision.** A function is only listed as supported once it passes reference tests against an independent implementation.77- **Privacy by design.** No account, no analytics, no network in the core. Python and AI run on this Mac.78- **Honest software.** No decorative features, no simulated results. Lossy exports are announced before they happen. Measured numbers only.79- **Reproducible work.** Transform pipelines, pivots, workflows and scripts are stored in the workbook as data you can re-run.8081## 3. Application Preview8283<table>84<tr>85<td width="50%"><img src="docs/screenshots/main-light.png" alt="Light mode"><br><sub><b>Light mode</b> — the Personal Budget template: KPI tiles, conditional formatting on overspending, two charts bound to live cells, the format inspector.</sub></td>86<td width="50%"><img src="docs/screenshots/main-dark.png" alt="Dark mode"><br><sub><b>Dark mode</b> — the same workbook; charts switch to the dark variant of their theme.</sub></td>87</tr>88<tr>89<td><img src="docs/screenshots/dashboard.png" alt="Dashboard"><br><sub><b>Dashboard</b> — a period selector (data validation) drives XLOOKUP/INDEX formulas, KPI cells and both charts.</sub></td>90<td><img src="docs/screenshots/templates.png" alt="Template chooser"><br><sub><b>Template chooser</b> — thumbnails are rendered from the real template workbooks.</sub></td>91</tr>92</table>9394All screenshots are rendered by the application's own views (the app or a feature's preview harness draws its window into a PNG); none is a mock-up. Data shown is synthetic sample data and is labelled as such inside the workbooks.9596## 4. Spreadsheet Grid9798<p><img src="docs/screenshots/grid.png" alt="Spreadsheet grid with a structured table" width="100%"></p>99100The grid is a single AppKit view that draws only what is visible with CoreGraphics and CoreText. It never creates a view per cell.101102- 1,048,576 × 16,384 addressable cells per sheet, sparse column-major storage, multiple sheets103- cell, range, multi-range, row and column selection; keyboard navigation with data-edge jumps; current-region select104- in-cell editing and formula bar, click-to-insert references with coloured range outlines105- copy / cut / paste (values, formulas, formats, transposed), fill handle with series detection (numbers, dates, weekdays, months, `Item 1` → `Item 2`), fill down / right106- insert and delete rows and columns with formula rewriting; move blocks with references following107- row and column resize, autofit, hide, freeze panes, merge cells108- notes, hyperlinks, named ranges, find and replace, go to109- unlimited undo / redo through the system undo manager, including structural edits110- pinch and ⌘-scroll zoom, light and dark appearance, Increase Contrast support111112Measured: a full repaint of a 1440 × 900 window takes about 2–8 ms on the build machine and stays under 2 ms after scrolling to the end of a 200,000-cell sheet (app-hosted test). On dense content at 2560 × 1440 a repaint takes 9–16 ms: there is no dirty-rectangle optimisation yet. Details: [docs/architecture/grid-engine.md](docs/architecture/grid-engine.md).113114Keyboard shortcuts follow Excel where Mac conventions allow; the differences are listed in [docs/compatibility/excel.md](docs/compatibility/excel.md).115116## 5. Formula Engine117118A recursive-descent parser produces a locale-independent syntax tree; a tree-walking evaluator computes it. Nothing is ever evaluated through dynamic code execution.119120- operators with Excel precedence (including `-2^2 = 4` and left-associative `^`), `%`, `&`, comparisons121- A1, absolute and mixed references, whole rows and columns, cross-sheet references, named ranges, structured table references (`Sales[Revenue]`, `[@Qty]`), spill references (`A1#`)122- dynamic arrays with spilling, `#SPILL!` on conflicts, broadcasting of scalar functions over arrays123- `LET`, `LAMBDA` (including recursion through defined names) and the lambda helpers `MAP`, `REDUCE`, `SCAN`, `BYROW`, `BYCOL`, `MAKEARRAY`124- localized entry: `=SUM(1,5;2)` in French regions and `=SUM(1.5,2)` elsewhere map to the same stored formula125126**Calculation.** Each formula registers its precedents in a reverse index (a hash for single cells, per-column-block interval trees for ranges). An edit marks only its dependents; evaluation is on demand with cycle detection (`#CIRC!`), a recursion guard that reorders instead of overflowing the stack, progress reporting and cancellation. Volatile functions and visibility-dependent functions (`SUBTOTAL`, `AGGREGATE`) are tracked separately. Large passes run in the background while the grid stays usable. Evaluation is single-threaded.127128**Functions.** 473 are available:129130| Category | Count | | Category | Count |131|---|---:|---|---|---:|132| Statistical | 144 | | Dynamic array | 22 |133| Math | 58 | | Information | 21 |134| Financial | 49 | | Lookup & reference | 19 |135| Engineering | 46 | | Logical | 13 |136| Text | 41 | | Database | 12 |137| Date & time | 25 | | Trigonometry | 23 |138139Every essential function named in the product brief is present (`XLOOKUP`, `FILTER`, `SORT`, `UNIQUE`, `SEQUENCE`, `LET`, `LAMBDA`, `SUMIFS`, `XIRR`, `LINEST`, `T.INV`, …); a test asserts it. The complete catalogue with signatures, summaries and the validation source of each function is in [docs/compatibility/formulas.md](docs/compatibility/formulas.md).140141**How correctness is established** (see [docs/mathematics/reference-tests.md](docs/mathematics/reference-tests.md)):142143| Library | Reference cases | Independent references |144|---|---:|---|145| Math, statistics, engineering, database | 15,378 | LibreOffice headless recalculation, SciPy + mpmath (40 digits), Python `decimal`, NumPy, statsmodels |146| Lookup, dynamic arrays, financial | 86,965 | 68,075 values computed by Microsoft Excel (public ExcelFinancialFunctions data set, Apache-2.0), LibreOffice, independent Python |147| Text, date and time | 7,951 | LibreOffice, Python `datetime`/`dateutil`, Microsoft documentation examples |148| Number formats | 5,085 | LibreOffice `TEXT()` renderings |149| Templates, end to end | 18,714 cells | every formula cell of the 15 templates recalculated by LibreOffice from the exported XLSX: 0 mismatches at 1e-6 |150151Microsoft Excel itself was never driven; where LibreOffice and Excel's documented behaviour differ, the documentation is followed and the deviation is recorded per function.152153## 6. Formatting154155- fonts, size, bold, italic, underline, strikethrough, text and fill colours, borders (13 line styles), horizontal and vertical alignment, wrap, indent, merge156- the full Excel number-format grammar: sections, conditions, colours, digit placeholders, thousands scaling, percent, scientific, fractions, dates and times, elapsed time, text sections, accounting; decimal-correct rounding157- conditional formatting: value comparisons, formulas, 2- and 3-colour scales, data bars, 19 icon sets, duplicates, top/bottom, above/below average, text, blanks, errors — with a rule manager and live preview158- whole-row and whole-column formatting without materializing cells; paste formatting; clear formatting159160<p><img src="docs/screenshots/conditional-format-rule.png" alt="Conditional formatting rule editor" width="70%"></p>161162Not rendered in the grid yet: text rotation, shrink-to-fit, rich text inside a cell (see limitations).163164## 7. Tables165166Convert a range to a named table with header detection, a totals row (`SUBTOTAL`), banding and structured references. Filter per column (value list with search, conditions, top N), sort on several keys, remove duplicates, find missing values, see inferred column types and quick statistics. Data validation supports numbers, dates, text length, lists (with an in-cell drop-down) and custom formulas, with input and error messages.167168## 8. Pivot Tables169170<p><img src="docs/screenshots/pivot-table.png" alt="Pivot table builder" width="100%"></p>171172Pivots are computed by the columnar engine with a single `GROUPING SETS` query, from a worksheet range or a dataset. Rows, columns, values and filters; sum, count, average, min, max, standard deviation, variance, median, distinct count, product; show-as percentages, running totals and differences; date and numeric grouping; sorting and top N; calculated fields; subtotals and grand totals. The result is written as real, formatted cells in one undoable step; **Refresh** recomputes; **Show Details** drills down to the underlying records in a new sheet. Results are verified against `pandas.pivot_table`.173174## 9. Data Transformation175176<p><img src="docs/screenshots/transform.png" alt="ORIX Transform: applied steps with live preview" width="100%"></p>177178**ORIX Transform** is a visual, reproducible data-preparation pipeline. Each step — filter, sort, rename, change type, split, merge, join, group by, pivot, unpivot, remove duplicates, fill or drop missing values, replace, parse dates, extract text, calculated column and more (23 step kinds) — is stored as data, validated against the schema at that point (the failing step is identified, later ones are marked blocked) and compiled into one SQL statement you can inspect. Preview at any step, refresh from the source, save the result as a dataset, insert it into the sheet or export it.179180## 10. Large Data Engine181182<p><img src="docs/screenshots/data-studio.png" alt="Data Studio: a one-million-row dataset with column profile" width="100%"></p>183184The worksheet grid and the analytical engine are separate execution environments. A ten-million-row file is imported into an embedded **DuckDB 2.0.1** engine, previewed through a virtualized window, queried and aggregated there, and only selected results are materialized into worksheet ranges. Materializing more than a sheet can hold is refused with an explanation rather than truncated.185186- sources: CSV, TSV, Parquet, JSON, JSONL, SQLite files, DuckDB files, worksheet ranges; lazy views for Parquet/CSV/JSON187- virtualized dataset grid, server-side sort and filter, column profiles, SQL console with history188- export to CSV, Parquet, JSON189- the embedded engine cannot reach the network or files outside a private staging folder: extension download is disabled, external access is off, configuration is locked (tested, including escape attempts)190191Measured on the build machine (M5 Max, release build, 10,000,000 rows × 8 columns, 560 MB CSV):192193| Step | Median |194|---|---:|195| Import CSV into a table | 0.30 s |196| Filtered aggregation | 14 ms |197| Pivot, region × category by year | 38 ms |198| Join with 100,000 customers + group | 88 ms |199| Preview window at row 5,000,000 | 5 ms |200| Parquet filter with push-down | 4 ms |201202Source: `Packages/SheetData/BENCHMARKS.md`. These are measurements on one machine, not guarantees.203204## 11. Charting205206<table>207<tr>208<td width="50%"><img src="docs/screenshots/charts-in-sheet.png" alt="Charts in the sheet"><br><sub>Charts live in the sheet, follow their cells and redraw from a cache (about 1 µs per chart on a cache hit).</sub></td>209<td width="50%"><img src="docs/screenshots/chart-viewer.png" alt="Interactive chart viewer"><br><sub>Interactive viewer: hover inspection, zoom and pan, linked selection, a what-if slider that drives a cell.</sub></td>210</tr>211<tr>212<td><img src="docs/screenshots/chart-picker.png" alt="Chart picker"><br><sub>The picker proposes charts for the selection first; thumbnails are drawn from the selected data.</sub></td>213<td><img src="docs/screenshots/chart-inspector.png" alt="Chart inspector"><br><sub>Inspector: data, style, axes and elements (trendlines, error bars, annotations).</sub></td>214</tr>215</table>21621721 chart kinds, all drawn from data by one vector engine: line, bar, column, area, scatter, bubble, histogram, box plot, violin, heatmap, waterfall, candlestick, pie, donut, radar, treemap, 3D surface (static projection), contour, density, time series and combination charts with a secondary axis. Stacking, logarithmic and date axes, six trendline types with equation and R², error bars, confidence bands, reference lines and bands, data labels, ten themes including colour-blind-safe palettes. Blank, text and error cells are never plotted as zero.218219Export is vector wherever the format allows: **PDF** and **SVG** (real text, no rasterization), **PNG** at 1×/2×/3×. Statistical conventions (binning rules, quartile methods, KDE bandwidths, decimation) are documented and tested against NumPy, SciPy and matplotlib.220221## 12. Figure Studio222223<p><img src="docs/screenshots/figure-studio.png" alt="ORIX Figure Studio: a four-panel figure" width="100%"></p>224225Compose multi-panel figures from the workbook's charts: grid layout with spans, panel labels, shared axes, one typography ladder for all panels, themes, true-size preview, and export presets (vector PDF and SVG, PNG at 300 or 600 dpi). Templates for papers, reports, presentations and dashboards are size and typography presets only — no compliance with any journal's requirements is claimed.226227## 13. Financial Modeling228229<table>230<tr>231<td width="50%"><img src="docs/screenshots/financial-model.png" alt="DCF valuation template"><br><sub>DCF valuation template: named assumptions, WACC, terminal value, equity bridge, sensitivity grid.</sub></td>232<td width="50%"><img src="docs/screenshots/dcf-live-model.png" alt="DCF builder output"><br><sub>The DCF builder writes a complete model as live formulas (inputs blue, formulas black).</sub></td>233</tr>234<tr>235<td><img src="docs/screenshots/amortization.png" alt="Loan amortization"><br><sub>Amortization schedules computed in decimal arithmetic, to the cent.</sub></td>236<td><img src="docs/screenshots/bond-analytics.png" alt="Bond analytics"><br><sub>Bond price, yield, duration, convexity and the price–yield curve.</sub></td>237</tr>238</table>239240- 49 financial worksheet functions (`PMT` … `XIRR`, depreciation, and the security functions with all five day-count bases), validated on 68,075 Excel-computed values241- Financial Modeling Studio: time value of money, loan and Canadian mortgage schedules, bond analytics, cash-flow analysis listing **all** IRR roots, capital budgeting, DCF builder, portfolio analytics, ratios, break-even, forecasting242- What-if tools: goal seek, one- and two-variable data tables, scenario manager, tornado sensitivity, Monte Carlo on the live model (seeded, with correlated inputs) — all computed on an isolated copy so the workbook and its undo history are untouched until you apply a result243- every tool shows its conventions: payment timing, compounding, day count, rounding. Excel-compatible and alternative conventions are both available where they differ and are named for what they are ([docs/mathematics/financial-conventions.md](docs/mathematics/financial-conventions.md))244245<p><img src="docs/screenshots/monte-carlo.png" alt="Monte Carlo simulation on a model" width="100%"></p>246247## 14. Statistics248249<p><img src="docs/screenshots/statistics-regression.png" alt="Statistics Studio: linear regression with robust standard errors" width="100%"></p>250251Statistics Studio offers 27 analyses on worksheet ranges: descriptive summaries, histograms, correlation matrices; confidence intervals, t and z tests, chi-square tests, one- and two-way ANOVA with Tukey HSD, variance and normality tests, non-parametric tests; OLS and WLS with classical, HC0–HC3, HAC and clustered errors and a full diagnostics table; fixed-effects panel regression; logistic regression; ACF/PACF, exponential smoothing, ARIMA, GARCH(1,1), ADF; PCA, k-means, hierarchical clustering; bootstrap and permutation tests. Each result states the statistic, degrees of freedom, p-value, effect size and assumptions, and can be written to the sheet as a formatted report.252253Every method is validated against SciPy, statsmodels, scikit-learn, linearmodels or `arch`; the tolerance achieved per method is tabulated in `Packages/SheetAnalytics/VALIDATION.md`, together with the methods that were **not shipped** because they could not be validated.254255## 15. Python Studio256257<table>258<tr>259<td width="60%"><img src="docs/screenshots/python-studio.png" alt="Python Studio"><br><sub>Editor, console, DataFrame previews, captured matplotlib figures, pending changes and run history.</sub></td>260<td width="40%"><img src="docs/screenshots/python-consent.png" alt="Consent sheet"><br><sub>A script that arrived with a workbook never runs without this review.</sub></td>261</tr>262</table>263264```python265import orix266267sheet = orix.active_sheet()268data = sheet.range("A1:D100").to_dataframe()269result = data.groupby("Category")["Revenue"].sum()270sheet.range("F1").write(result)271```272273This example runs as written (it is a test). Python is a **separate process** of an interpreter found on the Mac (nothing is bundled); values travel as JSON over private pipes; writes are buffered and applied as one undoable step when the run succeeds.274275**Restricted mode** is on by default and wraps the interpreter in a sandbox profile. What it enforces is verified by tests on this macOS version: no network (TCP, UDP, listening), no writes outside the run folder, no reads under `/Users`, `/Volumes` or `/tmp`, no other program can be launched, no signals to other processes; CPU, file-size and open-file limits, a wall-clock timeout, an output cap and termination of the whole process tree. What it does **not** enforce is stated just as plainly in the app and in [`Packages/SheetPython/SECURITY.md`](Packages/SheetPython/SECURITY.md) (for example, there is no hard memory limit on macOS). If the sandbox is unavailable the run is refused — it never silently falls back. Every run is recorded in a local audit log.276277Measured: reading 100,000 rows × 6 columns into a DataFrame takes 0.40 s and writing them back 0.55 s (debug build).278279## 16. Local AI280281<p><img src="docs/screenshots/assistant.png" alt="ORIX Intelligence suggesting formulas, each validated by the engine" width="100%"></p>282283ORIX Intelligence uses Apple's on-device Foundation Models when the Mac supports them. There is no cloud model and no network code. When the model is unavailable the panel says why and the rest of the app is unaffected.284285The model never calculates. It explains formulas from the engine's real evaluation steps, describes data from deterministic column profiles, prioritizes the auditor's findings (it cannot invent one), and suggests formulas — each of which is parsed, checked against the function registry and **evaluated by the real engine on a copy of the workbook** before it is shown, with the computed value next to it.286287Measured on this machine against 20 fixed requests: every request received at least one formula that validates, and 12 of 20 received a formula that computes the expected value. "Valid" therefore means "computes", not "is what you meant", and the panel says so. Source: `Packages/SheetIntelligence/EVALUATION.md`.288289## 17. Formula Intelligence290291<table>292<tr>293<td width="50%"><img src="docs/screenshots/formula-intelligence.png" alt="Step-by-step formula evaluation"><br><sub>Step-by-step evaluation: every intermediate value comes from the evaluator.</sub></td>294<td width="50%"><img src="docs/screenshots/dependency-graph.png" alt="Dependency graph"><br><sub>Dependency graph of a cell: precedents left, dependents right, cycles marked.</sub></td>295</tr>296</table>297298Autocomplete for functions, names, tables and sheets; signature and active-argument hints while typing; coloured reference outlines; plain-language structure description; error explanations that trace an error to its origin; comparison with neighbouring formulas; a browsable catalogue of every function.299300## 18. Model Auditor301302<p><img src="docs/screenshots/auditor.png" alt="Model Auditor findings" width="100%"></p>30330421 rules: error values with their root cause, broken references, circular dependencies with the cycle path, formulas inconsistent with their row or column, hardcoded constants and overwritten formulas, hidden rows and sheets holding data, references to blanks, numbers stored as text, mixed types in a table column, volatile functions, long formulas, unused and broken names, external links, and more. Each finding has a severity, evidence, an explanation and a recommended action; not every hardcoded value is treated as an error. Findings can be ignored (stored in the workbook), exported as Markdown or inserted as a sheet.305306## 19. Automation307308<p><img src="docs/screenshots/automation.png" alt="Automation: a finished workflow run" width="100%"></p>309310- **Visual workflows** — 25 step kinds (import, clean, transform, SQL, formulas, pivot, chart, validate, export, save, batch over a folder, run an approved Python script), parameters, per-step error policy, live progress, cancellation and history. A run works on a copy; outputs are staged and moved into place only on success; applying a run to the open workbook is one undo step.311- **Command line** — `orix-sheet` ships inside the app bundle: `convert`, `recalc`, `eval`, `info`, `audit`, `sql`, `run`, `functions`.312  ```console313  $ orix-sheet eval sales.xlsx '=SUM(C:C)'314  20076.81315  $ orix-sheet convert sales.csv sales.pdf316  Wrote sales.pdf (pdf, 2 pages)317  ```318- **Shortcuts** — App Intents for Convert Spreadsheet, Recalculate Workbook, Run ORIX Workflow and Get Cell Value. They compile and their logic is tested; their appearance in the Shortcuts app has not been verified yet.319- **Scheduling** — the app shows the exact command and can install a per-user LaunchAgent on request. Nothing is scheduled without that explicit step.320321There is no network listener and no remote API. AppleScript is not implemented.322323## 20. Import & Export324325| Format | Read | Write | Notes |326|---|:---:|:---:|---|327| `.orixsheet` (native) | ✓ | ✓ | lossless, integrity-checked |328| `.xlsx` | ✓ | ✓ | values, formulas, styles, number formats, merges, names, tables, conditional formats, validations, notes, links, freeze panes, print settings |329| `.xlsm` | ✓ | ✓ | macros are **never executed**; the VBA project is carried through untouched |330| `.ods` | ✓ | ✓ | values, formulas, basic styles, merges, sizes, notes, links |331| `.csv` / `.tsv` | ✓ | ✓ | delimiter and encoding detection; fields starting with `=` stay text |332| `.json` / `.jsonl` | ✓ | ✓ | arrays of objects or arrays |333| `.parquet`, SQLite, DuckDB files | data engine | export | through Data Studio |334| PDF | — | ✓ | paginated, vector |335| `.xls`, `.xlsb`, Numbers | — | — | recognised and refused with a clear message |336337**No silent data loss.** A foreign file is *imported* into an untitled ORIX workbook — the original is never overwritten — and an import report lists what changed. Writing another format is an explicit **Export**, preceded by a compatibility report of everything that format cannot hold. Charts, pivots, images and other parts of an XLSX that ORIX does not model are preserved byte-for-byte and written back.338339Archives are read by a hardened ZIP reader (path traversal, entry count, size and compression-ratio limits; CRC checks). External links are never fetched.340341Measured, 1,000,000 cells (release build): native read 0.10 s / write 0.58 s; XLSX read 1.90 s / write 1.19 s; CSV read 0.19 s. Source: `Packages/SheetIO/COMPATIBILITY.md`. Full matrix: [docs/compatibility/formats.md](docs/compatibility/formats.md).342343## 21. Native Workbook Format344345`.orixsheet` is a document package: a manifest with a SHA-256 per part, JSON metadata, zlib-compressed binary cell chunks per sheet, and attachments (scripts, pipelines, workflows, scenarios, preserved foreign parts). Saving is atomic; a damaged part is named precisely and the other sheets still load. Round-tripping random workbooks is bit-exact and re-saving is byte-stable (property tests). Autosave and versions come from the macOS document system. Specification: `Packages/SheetIO/NATIVE-FORMAT.md`, [docs/architecture/persistence.md](docs/architecture/persistence.md).346347## 22. Architecture348349<!-- diagram: readme-architecture -->350```mermaid351flowchart LR352  subgraph App["ORIX Sheet.app"]353    Doc[WorkbookDocument<br>NSDocument] --> Session[WorkbookSession<br>main actor]354    Session --> Grid[GridView<br>AppKit + CoreText]355    Session --> Panels[Feature panels<br>SwiftUI]356  end357  Session --> Engine[CalcEngine<br>dependency graph]358  Engine --> Core[SheetCore<br>model · parser · evaluator]359  Engine --> Fn[Function libraries<br>473 functions]360  Panels --> Data[SheetData<br>DuckDB]361  Panels --> Charts[SheetCharts<br>vector renderer]362  Panels --> Stats[SheetAnalytics]363  Panels --> Py[SheetPython<br>subprocess]364  Panels --> AI[SheetIntelligence<br>on device]365  Doc --> IO[SheetIO<br>xlsx · ods · csv · native]366```367368SVG version of this diagram: [docs/assets/diagrams/readme-architecture.svg](docs/assets/diagrams/readme-architecture.svg).369370The calculation engines are Swift packages with no dependency on SwiftUI or AppKit views; the app is a thin layer that registers features into a workspace. Ten diagrams (grid rendering, parsing, dependency graph, calculation scheduling, data engine, Python integration, chart rendering, persistence, import/export, AI) are in [docs/architecture/](docs/architecture/overview.md), each as Mermaid with an SVG fallback in `docs/assets/diagrams/`.371372| Document | Subject |373|---|---|374| [overview](docs/architecture/overview.md) | packages, threading, extension points |375| [grid-engine](docs/architecture/grid-engine.md) | virtualized grid and printing |376| [formula-engine](docs/architecture/formula-engine.md) · [calculation-graph](docs/architecture/calculation-graph.md) | parser, evaluator, recalculation |377| [data-engine](docs/architecture/data-engine.md) | DuckDB embedding, transforms, pivots |378| [python-runtime](docs/architecture/python-runtime.md) | subprocess, sandbox, RPC |379| [chart-engine](docs/architecture/chart-engine.md) | charts and figures |380| [persistence](docs/architecture/persistence.md) | native format and documents |381| [intelligence](docs/architecture/intelligence.md) | on-device assistance |382| [security](docs/security.md) | threat model |383384## 23. Technology Stack385386| Layer | Technology | Why |387|---|---|---|388| Language | Swift 6 (strict concurrency) | one language from engine to UI |389| UI | SwiftUI for chrome and panels, AppKit for the grid, editors and documents | native behaviour; a view per cell is not viable |390| Rendering | CoreGraphics + CoreText | repaint is a few milliseconds; a Metal text renderer was evaluated and not needed |391| Numerics | Accelerate (LAPACK, vDSP), own special functions | on every Mac, validated against SciPy |392| Analytics | DuckDB 2.0.1 through its C API | columnar, out-of-core, MIT licence |393| Files | own OOXML/ODF readers and writers on zlib | control over safety and fidelity |394| Python | subprocess + `sandbox-exec` | isolation; nothing to bundle |395| AI | Apple Foundation Models (weak-linked) | on device, optional |396397The reasoning and the alternatives considered are in [docs/research/technology-evaluation.md](docs/research/technology-evaluation.md); the product positioning in [docs/research/competitive-analysis.md](docs/research/competitive-analysis.md). There is no third-party Swift dependency.398399## 24. Installation400401Requirements: macOS 14 or later (Apple Silicon or Intel; developed and measured on Apple Silicon). Python Studio needs a Python 3.9+ installation; ORIX Intelligence needs a Mac and macOS version with Apple Intelligence.4024031. Download [`ORIXSheet-1.0.0.dmg`](https://git.spboucher.ai/releases/orix-sheet/v1.0.0/ORIXSheet-1.0.0.dmg), open it and drag **ORIX Sheet** to **Applications**.4042. Launch it. There is nothing to configure and no account.405406The distribution status of the current build (signature, notarization, checksums) is under [Release status](#33-release-status).407408## 25. Build Instructions409410```bash411brew install xcodegen create-dmg          # build tools412Scripts/fetch-duckdb.sh                    # pinned DuckDB library, checksum verified413Scripts/build.sh generate                  # ORIXSheet.xcodeproj from project.yml414Scripts/build.sh debug && Scripts/build.sh run415```416417Xcode 27 / Swift 6.4 were used. Every package also builds on its own with `swift build`. Release: `Scripts/sign.sh` (universal build, Developer ID, hardened runtime), `Scripts/notarize.sh` (notarytool, stapling, packaging), described in [docs/release/](docs/release/checklist.md). Setup details: [docs/development/setup.md](docs/development/setup.md).418419## 26. Testing420421<!-- TESTS:BEGIN -->422| Package | Tests | Status |423|---|---:|---|424| `SheetCore` | 32 | passed |425| `SheetFormat` | 28 | passed |426| `FunctionsNumeric` | 31 | passed |427| `FunctionsText` | 19 | passed |428| `FunctionsLookup` | 49 | passed |429| `SheetEngine` | 4 | passed |430| `SheetIO` | 66 | passed |431| `SheetCharts` | 43 | passed |432| `SheetData` | 64 | passed |433| `SheetAnalytics` | 310 | passed |434| `SheetPython` | 57 | passed |435| `SheetIntelligence` | 62 | passed |436| `SheetAutomation` | 78 | passed |437| `SheetTemplates` | 29 | passed |438| `SheetUI` | 20 | passed |439| `FeatureAudit` | 60 | passed |440| `FeatureCharts` | 51 | passed |441| `FeatureData` | 57 | passed |442| `FeatureAnalysis` | 125 | passed |443| `FeaturePython` | 40 | passed |444| `FeatureIntelligence` | 17 | passed |445| `FeatureAutomation` | 28 | passed |446| `ORIXSheetTests` (hosted in the running app) | 9 | passed |447| **Total** | **1,279** | all passing |448449Run of 2026-11-21T08:47:01Z on the build machine. Source: `docs/reports/tests.json`, `docs/reports/app-tests.json`.450<!-- TESTS:END -->451452The counts above are test functions; many are parameterized over fixture files, so the number of reference cases checked is far larger (see [Formula engine](#5-formula-engine)). The app-hosted suite drives real documents and windows: typing through the grid's key handling, mouse selection, undo through the document, native save and reopen, import-as-untitled, export preflight, corrupted files, paginated vector PDF, and a 200,000-cell sheet recalculated in the background.453454Not automated: there is no XCUITest target, so menus, drag and drop, file panels and popovers are exercised only through their models. VoiceOver has not been listened to. Line coverage has not been measured. Strategy and commands: [docs/development/testing.md](docs/development/testing.md).455456## 27. Benchmarks457458Engine, release build, Apple M5 Max (18 cores, 48 GB), macOS 27.0 — `swift run -c release orix-bench`:459460| Scenario | Time |461|---|---:|462| Parse 500,000 formulas | 0.53 s |463| Full recalculation, 80,000 formulas (120,000 cells) | 0.095 s |464| Full recalculation, 800,000 formulas (1.2 M cells) | 1.21 s |465| Full recalculation, 4,000,000 formulas (6 M cells, 4.5 GB resident) | 5.01 s |466| Incremental recalculation after one edit, 6 M-cell workbook | 0.1 ms |467| Chain of 1,000,000 dependent formulas | 0.39 s |468| 7 whole-column aggregates over 1,000,000 rows | 0.54 s |469| Format 2,000,000 numbers as `#,##0.00` | 0.29 s |470| Insert 5 rows + recalculate, 1.2 M cells | 3.08 s |471| Sort 100,000 rows × 4 columns + recalculate | 2.52 s |472473Source: `docs/benchmarks/engine.json`. These are benchmark scenarios on one machine, not guaranteed workloads. Slow paths are visible in the table: structural edits rebuild the dependency graph and recalculate everything, and memory is about 750 bytes per formula cell. No comparison with any other product is made. All tables: [docs/development/performance.md](docs/development/performance.md).474475## 28. Excel Compatibility476477What is validated: formula semantics function by function (above), XLSX round trips checked by two independent readers (openpyxl and LibreOffice), and the templates recalculated end to end by LibreOffice.478479What differs from Excel, by design or for now:480481- a circular reference shows `#CIRC!` (Excel warns and shows 0); iterative calculation is not supported482- no 3-D references (`Sheet1:Sheet3!A1`), no reference union or intersection operators, no R1C1 entry, no external-workbook formulas (their cached value is kept on import, with a notice)483- whole-column references are clamped to the used rows when materialized484- function names are English in every locale; separators follow the region485- VBA is never run; pivot tables, charts and images in an XLSX are preserved but not editable as Excel objects; ORIX charts are not exported to XLSX yet (announced by the export report)486- text ordering uses a fixed collation rather than the system locale487- several keyboard shortcuts differ (⌘ instead of Ctrl, ⌘= recalculates, ⌃G goes to a cell)488489The complete list, verified against the code: [docs/compatibility/excel.md](docs/compatibility/excel.md).490491## 29. Privacy492493- No account, no registration, no advertising, no analytics, no telemetry.494- The application contains no network code in its calculation, file, chart, data or AI paths. The embedded DuckDB cannot load extensions or reach the network.495- The single network use is `pip install`, run only when you ask for it in Python Studio and confirm it.496- Python scripts and workflows that arrive inside a workbook never run on open; they must be reviewed and approved, and approvals are tied to the exact text.497- On-device AI receives a bounded, documented context (headers, types, a few sample rows); see `Packages/SheetIntelligence/PRIVACY.md`.498- The app is not sandboxed (Python's own sandbox cannot nest inside the App Sandbox); it uses the hardened runtime with no entitlements.499500Threat model: [docs/security.md](docs/security.md).501502## 30. Accessibility503504Labels on every control (verified through the system accessibility API: 0 unlabelled controls in the audited panes); grid cells exposed with row and column header context; keyboard access to the chrome; Reduce Motion, Increase Contrast and Differentiate Without Colour are honoured; a default zoom preference; colour-blind-safe chart palettes; text and UI contrast measured against WCAG and corrected (table in [docs/development/accessibility.md](docs/development/accessibility.md)).505506Honest status: VoiceOver has not been listened to by a person, `performAccessibilityAudit()` has not been run, and embedded objects and row/column headers are not yet accessibility elements.507508## 31. Localization509510English and Canadian French. 557 strings in the shared interface and the app, plus each feature's own catalogue (about 4,500 more), all translated and checked by scripts for missing keys and mismatched format specifiers. Numbers, dates, currency and formula separators follow the region; the stored formula is locale-independent. Text produced by the engines (audit explanations, statistical notes, function summaries) is English for now. Details: [docs/development/localization.md](docs/development/localization.md).511512<p><img src="docs/screenshots/french.png" alt="ORIX Sheet in Canadian French" width="80%"></p>513514## 32. Roadmap515516Planned next, none of it promised by this release: multi-threaded recalculation; dirty-rectangle grid drawing; incremental graph updates for structural edits; chart export to XLSX; in-grid text rotation and rich text; iterative calculation; XCUITest coverage; signed automatic updates (Sparkle was evaluated and is not included); AppleScript dictionary.517518## 33. Release Status519520Version **1.0.0 (2)**, built on 21 November 2026. Evidence for every line is in [`RELEASE-REPORT.md`](RELEASE-REPORT.md) and `docs/reports/`.521522| Item | Status |523|---|---|524| Universal Release build (arm64 + x86_64) | built |525| Signature | Developer ID Application: Simon-Pierre Boucher (3YM54G49SN), hardened runtime, secure timestamp |526| Apple notarization | **Accepted** — app `2c7463bf-26a6-49f2-8d29-250a664f487e`, disk image `824f9e74-d90b-409d-a5e4-cf9034581b5a` |527| Stapling and Gatekeeper | stapled; `spctl` reports *Notarized Developer ID* for the app, the DMG and the app extracted from the ZIP |528| `ORIXSheet-1.0.0.dmg` | 80,310,380 bytes · SHA-256 `04867c73714939249c1f2f19d085102932308765d29a7188dcd445a78231f861` |529| `ORIXSheet-1.0.0.zip` | 79,521,512 bytes · SHA-256 `576bc7dc3776f7893c21aaaf5abe76be17cc2e3c7fce8d39f70658491a644455` |530| Source | public: <https://git.spboucher.ai/orix-sheet>, tag `v1.0.0` (published on 21 November 2026 at the owner's request) |531| Release | <https://git.spboucher.ai/orix-sheet/releases> — [DMG](https://git.spboucher.ai/releases/orix-sheet/v1.0.0/ORIXSheet-1.0.0.dmg) · [ZIP](https://git.spboucher.ai/releases/orix-sheet/v1.0.0/ORIXSheet-1.0.0.zip) · [SHA256SUMS](https://git.spboucher.ai/releases/orix-sheet/v1.0.0/SHA256SUMS.txt) · [notes](https://git.spboucher.ai/releases/orix-sheet/v1.0.0/RELEASE-NOTES.md) |532533The published DMG and ZIP were downloaded back from the forge and verified: checksums match, the disk image is stapled and Gatekeeper reports *Notarized Developer ID*.534535Only the Apple Silicon slice on macOS 27.0 has been run; the Intel slice and macOS 14–26 are untested.536537## 34. Known Limitations538539- **Calculation:** single-threaded; structural edits (insert/delete rows or columns, sheet operations) rebuild the dependency graph and recalculate the workbook; about 750 bytes of memory per formula cell.540- **Grid:** no text rotation, shrink-to-fit or rich text in cells; objects and overflowing text are clipped at frozen-pane boundaries; no split panes; full-window repaint on every change.541- **Excel:** see section 28. `.xls` and `.xlsb` are not read.542- **Charts:** not exported to XLSX; the 3D surface is a static projection; automatic chart labels are English.543- **Pivots:** values are numeric; subtotals are all on or all off; a pivot's anchor is not updated when rows are inserted above it.544- **Data:** datasets are linked, not embedded — they are re-imported from their source when a workbook is reopened; large inserts into a sheet run on the main thread (about 0.85 M cells/s).545- **Python:** requires an installed interpreter; no hard memory limit; "insert plot into sheet" is not available.546- **AI:** formula suggestions are right about 60 % of the time on the measured set; Python suggestions are only syntax-checked.547- **Automation:** Shortcuts discovery and LaunchAgent installation have not been exercised in an installed build; AppleScript is absent.548- **Testing:** no UI-automation target; coverage not measured; Microsoft Excel was never driven as a reference.549- **Distribution:** no automatic updates.550551## 35. ORIX Ecosystem552553ORIX is a family of premium Apple utilities built on the same principles: instant utility, professional precision, privacy by design, local-first computing. ORIX Sheet shares the family's visual language — navy canvas, cyan-to-indigo accent, the ORIX ring — without any runtime dependency on the other applications (ORIX Scan, ORIX Calc, ORIX Audio, ORIX Monitor, ORIX Clean, ORIX Secure, ORIX Camera). Icon exploration: [docs/design/icon-design.md](docs/design/icon-design.md).554555<p align="center"><img src="docs/assets/icon-concepts-sheet.png" alt="Five icon concepts and the final icon" width="90%"></p>556557## 36. License558559© 2026 Simon-Pierre Boucher. All rights reserved. The source is published for reading; no licence to reuse it is granted.560561Third-party components: DuckDB (MIT) is embedded as an unmodified binary. Test fixtures include reference values derived from the ExcelFinancialFunctions project (Apache-2.0); attribution is in `Packages/FunctionsLookup/COMPATIBILITY.md`. No other third-party code is linked.562563---564565<p align="center"><strong>ORIX Sheet — Beyond Spreadsheets.</strong></p>566
Files main
Menu

Theme