SPB Git

Repository Public

technology-evaluation.md 7.0 KB

# Technology evaluation

Audit date: 2026-11-21. Everything below was checked on the build machine; nothing is assumed from memory.

# Environment audit

Item Finding
macOS 27.0 (26A5425a)
Hardware Apple M5 Max, 18 cores, 48 GB RAM
Xcode / Swift Xcode 27.2 (27B52), Swift 6.4.2, macOS SDK 27.2
Signing Developer ID Application: Simon-Pierre Boucher (3YM54G49SN) present in the login keychain
Notarization keychain profile MacLustr-Notarize (used by sibling apps, last submission accepted the same day)
Git hosting SPB Git (git.spboucher.ai, bare repositories on the gitsrv host). No orix-sheet repository existed. The forge serves every repository under its root publicly; it has no private flag
Sibling ORIX apps ORIX Scan, Calc, Audio (iOS), ORIX Monitor, Clean, Secure, Camera (in progress). Each ships its own design tokens; the shared palette (navy canvas, cyan #0891B2/#22D3EE accent, indigo secondary) is reused here without a runtime dependency
Python Homebrew Python 3.14.4 with NumPy 2.4.4, pandas 3.0.2, SciPy 1.17.1, matplotlib, statsmodels, scikit-learn, Polars, SymPy, openpyxl 3.1.5, pyarrow 24.0.0, duckdb 1.5.2. System /usr/bin/python3 is 3.9.6 without scientific packages
Reference spreadsheets LibreOffice (headless soffice) and Microsoft Excel are installed; LibreOffice is used as an automated, independent recalculation reference
Foundation Models The FoundationModels framework is part of the macOS 26+ SDK; availability is checked at run time (SystemLanguageModel.default.availability)

# Decisions

Each candidate was judged on performance, numerical correctness, licence, maintenance, security, Apple Silicon support, distribution and notarization cost, and offline operation.

# Formula engine — written in Swift (no dependency)

Candidate Assessment
Own Swift engine (chosen) Full control over Excel semantics (coercion, error propagation, dynamic arrays, structured references), no licence constraints, nothing extra to sign. Cost: we must validate every function ourselves; this is done against LibreOffice and SciPy reference fixtures
HyperFormula (JS) GPLv3 or commercial; would require a JavaScript runtime in the calculation path
LibreOffice core as a library (LibreOfficeKit) Complete, but ~300 MB of MPL/LGPL binaries to embed and sign, slow start-up, and a document model that is not ours
IronCalc (Rust) Promising and permissively licensed, but young; function coverage and dynamic arrays were incomplete when evaluated, and it would add a Rust tool-chain to the build
formulas / pycel (Python) Too slow for interactive recalculation; Python is optional in this product

# Analytical engine — DuckDB 2.0.1 (embedded, official universal dylib)

MIT licence, actively maintained, columnar and vectorized, out-of-core operators, native CSV/Parquet/JSON readers with projection and predicate push-down, universal (arm64 + x86_64) build published by the project. It is embedded through the C API (duckdb.h) wrapped in an XCFramework; the binary is pinned by version and SHA-256 in Scripts/fetch-duckdb.sh and signed with the app. Extension auto-install and auto-load are disabled so that the engine never touches the network.

Alternatives: SQLite (row store, an order of magnitude slower on analytical scans; still used through the system library to import SQLite files), Polars (excellent but Rust/Python only — no stable C API for embedding from Swift), Apache Arrow C++ (large dependency; DuckDB already provides the columnar execution we need, and Arrow IPC is only offered where DuckDB supports it offline).

# Numerics — Accelerate (BLAS/LAPACK, vDSP)

Ships with the OS, tuned for Apple Silicon, nothing to distribute. Used for regressions (QR/SVD), matrix functions (MMULT, MINVERSE, MDETERM, LINEST) and PCA. Special functions (incomplete gamma/beta, inverse distributions) are implemented in Swift and validated against SciPy.

# Python — controlled subprocess, not an embedded interpreter

Option Assessment
Subprocess of a Python found on the Mac (chosen) No 100–300 MB runtime to bundle, sign and notarize; a crash or runaway script cannot take the app down; the process can be killed, time-limited and run under a sandbox-exec profile. Cost: Python Studio requires a Python installation (the app detects interpreters and reports which packages are present)
PythonKit / embedded CPython In-process: a segfault in a C extension kills the app, the GIL blocks cancellation, and every wheel must be signed with the hardened runtime
Bundled python-build-standalone Works, but adds several hundred MB with NumPy/pandas and a large notarization surface; kept as a possible later option

Data crosses the boundary as JSON over dedicated pipes (the user's stdout stays free for print). Workbook writes are buffered and applied as one undoable step.

# File formats — own readers/writers

OOXML (XLSX) and ODS are ZIP + XML: implemented in Swift on top of the system zlib and XMLParser, with a hardened ZIP reader (path traversal, entry count, size and compression-ratio limits). openpyxl and LibreOffice are used only in tests, as independent readers of what we write. Libraries considered: CoreXLSX (read-only, no writer), libxlsxwriter (write-only C library), xlnt (C++, unmaintained).

# Rendering — AppKit + CoreGraphics/CoreText for the grid; Metal not used

The grid is one layer-backed NSView that draws only the visible cells. A full repaint of a typical window measures a few milliseconds on the build machine (see docs/development/performance.md), far below a 120 Hz frame, so a Metal text renderer (glyph atlas, own shaping) would add risk without a measurable benefit. Charts are drawn through a small vector canvas abstraction with CoreGraphics (screen, PNG, PDF) and SVG back-ends, so exports stay vector. Swift Charts was not used for worksheet charts because it cannot export vector PDF/SVG nor be rendered off-screen deterministically.

# AI — Apple Foundation Models when available, nothing otherwise

On-device, no account, no network. The assistant only suggests; formulas it proposes are parsed and evaluated by the deterministic engine before they are shown as valid. When the model is unavailable the Intelligence panel says so and every other feature keeps working. MLX models were evaluated and left out of 1.0 (multi-GB downloads, separate model management).

# Persistence — document package

.orixsheet is a directory package (manifest with per-part SHA-256, JSON metadata, compressed binary cell chunks). SQLite was considered for the container and rejected: a package gives atomic replacement through NSDocument, transparent Time Machine/versions behaviour and trivially inspectable parts.

# Updates

Sparkle 2 (EdDSA-signed appcasts) is the candidate. It is not included in 1.0: an update feed needs a hosted, signed appcast and a key-management decision from the owner. No custom updater is implemented.

Files main
Menu

Theme