VQuant for macOS
The native macOS workstation of the VQuant research desk — markets, charting, the research agent, the Quant Engine, data explorer, portfolio and risk, with the same account and the same passkeys as the web app. Swift 6, SwiftUI and AppKit. No web view, no third-party dependency.
Author: Simon-Pierre Boucher
Table of contents
- Overview
- Features
- Architecture
- Stack
- Repository layout
- Build and run
- Configuration
- Sections and windows
- Backend API used
- Local data
- Security and privacy
- Testing
- Release
- First sign-in on a Mac
- Troubleshooting and gotchas
- Known limitations and next steps
- Documentation
- Author
- License
🎯 Overview
VQuant for macOS is the native client (Swift 6, SwiftUI, AppKit where it earns its place) of the VQuant server at
vquant.spboucher.ai. VQuant is, at its core, the autonomous quantitative research agent; the terminal, the
Quant Lab, the portfolios and the Research Studio are surfaces around it — with the same account and passkeys as the
web app, and one synced state across web, Mac and iPhone. No web view. Computation, data and model inference stay on
the server; the Mac computes only display aids from data it was sent (chart indicators, descriptive portfolio
statistics) and labels them as such.
- Version 2.0.0 (3) "VQuant Next" · macOS 14+ · universal (arm64 + x86_64) · Developer ID signed. 2.0.0 was
notarized by Apple on 2026-11-20 (submissions 7204cfbb… app, 60682e96… disk image, both Accepted), stapled, installed in /Applications and published as
VQuant-2.0.0.dmg(sha256 044d90ed…) under spbgit releasesvquant-macos/v2.0.0. The previous 1.0.1 app is kept in~/Library/Developer/VQuant/backup/. - Backend: 2.0.0 needs backend 6 "VQuant Next" (
/api/v2/*, contractvquant-next/docs/next/CONTRACT.md); the 1.x routes it still uses are those of v5.8.0. Shared package:VQuantKit(local dependency../VQuantKit). - The application follows what the backend really offers: there is no WebSocket feed and no trading, so nothing is
called "live" and no order can be placed (see
docs/MACOS_ARCHITECTURE.md).
What is new in 2.0.0 "VQuant Next"
An upgrade of 1.0.1, not a rewrite — everything 1.0.1 did is still there. Evidence for every line is in
docs/FEATURE_PARITY.md and docs/TEST_REPORT.md.
| Area | 2.0.0 |
|---|---|
| One account, synced | Watchlists, portfolios, chart layouts and drawings, projects, notes, preferences and mappable window layouts are synced objects (VQSyncEngine, replica sealed with the cache key). 1.x local watchlists and layouts are migrated once, without loss. Sync status and conflict notices in the toolbar |
| Research (the centre) | Research mode with dataset attachment and inspection, budgets, a model picker reading the server registry with "Auto" and its routing reason, usage and cost; the research cockpit (report + inspector: Activity · Code · Experiments · Figures · Files · Environment); approvals; studies list; resume by REST; provenance and trace of any analysis |
| Terminal | Market overview with yield curve and calendar and a freshness chip per section; synced watchlists with multi-select and drag-reorder; ⌘K command palette; statements with period compare, common size and a formula inspector |
| Charting | Bars from the v2 data layer with provenance; drawing tools anchored to time and price, stored in the synced chart object; "Ask the agent about the visible range"; a renderer 3–100× faster on long series (Core Graphics kept after measuring: docs/CHART_PERFORMANCE.md) |
| Quant Lab | 19 engines by category, forms generated from the tool specification, progress and cancel, one result renderer, compare, dedicated options and backtest layouts with integrity statements always visible, automated review (always labelled as such) |
| Portfolios | Several portfolios (main is the agent's), in-place editor, CSV import with preview, valuation by currency, analysis with portfolio_lab / risk_lab, rebalancing as a proposal — never an order |
| Research Studio | Projects with question, hypotheses and items; notes with a markdown editor and versions; reviews; exports PDF / MD / LaTeX / ZIP; project memory |
| Mac | 14 destinations with shortcuts, Research and Lab menus, 20 Settings panes (routing with live preview, budgets, memory, usage and cost, audit log, data providers, sync), notifications routed to their window, a menu-bar extra, windows restored where they were |
Fixed on the way (defects present since 1.0): a detached chart window opened while signed in was blank; a window re-opened by a saved layout was blank; restored windows came back on the default section.
Family
| App | Platform | Repository | Role |
|---|---|---|---|
| VQuant | Web — vquant.spboucher.ai |
git.spboucher.ai/vquant | Backend and web app: agent, data, Python quant engines, reports, passkey gate, native bridge |
| VQuant for macOS (this repository) | macOS 14+ native | git.spboucher.ai/vquant-macos | Native workstation on the same accounts and passkeys |
| VQuant for iOS / iPadOS | iOS · iPadOS native | git.spboucher.ai/vquant-ios | Native iPhone and iPad client of the same backend |
✨ Features
The tables of this section describe what 1.0.1 already had (all of it is still there); what 2.0.0 adds is in
What is new in 2.0.0 above. Classes follow
docs/FEATURE_PARITY.md: native (done on the Mac), server-backed (native interface,
the server does the work), kit (shared package).
Markets
| Feature | Details |
|---|---|
| Overview | Index ticker and analyses in progress |
| Markets | Indices, movers (gainers, losers, most active), exchange hours |
| Watchlists | Synced with the account since 2.0 (1.0.1: local to the Mac); symbols can be dragged into a list |
| Symbol search | ⌘K, backed by /api/fmp/search |
| Data freshness | Five stated states: Recent (provider timestamp under 2 min), Delayed, Historical, Cached (server unreachable; last value this Mac received), Unavailable. The provider's timestamp is shown; quotes are polled over HTTPS and nothing is called "live" |
Charting
| Feature | Details |
|---|---|
| Chart types | Candles, OHLC, line, area; volume; logarithmic scale |
| Indicators | SMA, EMA, Bollinger bands, RSI, MACD — computed on the Mac from server bars and unit-tested |
| Intervals | 1 min, 5 min, 15 min, 30 min, 1 hour, 4 hours, 1 day |
| Interaction | Crosshair, pan and zoom (pointer, scroll, pinch, keyboard), symbol comparison |
| Chart windows | ⇧⌘N opens a chart window, ⇧⌘D detaches the current chart; crosshairs of linked charts follow each other |
| Rendering | Core Graphics through SwiftUI Canvas; when more bars are visible than fit, neighbours are merged for drawing only and the chart states "1 mark = n bars" |
| Export | PNG, PDF, CSV (CSV writes the source bars, not the merged marks) |
Research
| Feature | Details |
|---|---|
| Research agent | Chat with the server's agent: four modes, model choice, image attachment by drag and drop |
| Live run view | Status, plan, tools, sub-analysts, figures, follow-ups — 20 stream event types decoded; an unknown type is counted and reported, never dropped silently |
| Resilient runs | An analysis is a server job: the runner reconnects and replays from the last event; Stop cancels it |
| Conversations | List, search, rename, pin, delete |
| Reports | Native Markdown renderer: tables, text, figures, report markers, sources |
| Export | PDF, Word and slides rendered by the server |
| Quant Engine | GARCH, VaR, Monte Carlo, options, portfolio optimiser and risk metrics as server jobs with provenance (parameters, the Python code that ran, the result); result figures with Swift Charts (frontier, distributions, volatility forecast, allocation, drawdown) |
| Data Explorer | 15 datasets (income statement, balance sheet, cash flow, key metrics, ratios, analyst estimates, price targets, grades, earnings surprises, dividends, institutional holders, insider trading, news, ESG, daily prices): sort, filter, date range, columns, CSV, plot |
Portfolio and workspace
| Feature | Details |
|---|---|
| Portfolio | Valuation, allocation and CSV, computed on the Mac from server positions and quotes. A record of holdings: no order can be placed |
| Risk Analytics | Descriptive statistics from daily closes (labelled as native) and launch of the server engines |
| Agent | The agent's long-term memory, portfolio and scheduled watches |
| Jobs | Analyses and computations, running and finished |
| Documents | Shared reports |
Mac-native
| Feature | Details |
|---|---|
| Windows | Any number of workstation windows, each with its own section, symbol and conversation; tabs, full screen |
| Saved layouts | ⌃⌘S saves the open windows, what each shows and its frame |
| Menus and shortcuts | Native toolbar, menus, context menus; ⌘1…⌘9 switch sections |
| Device sessions | List and revoke device sessions, list passkeys, sign out (Settings) |
| Touch ID app lock | ⌃⌘L locks; the session token is released by the Keychain only after Touch ID |
| Offline reading | Network-first encrypted cache: only a network failure falls back to the last stored value, marked as cached |
| Notifications | When a job ends in the background |
| Network diagnostics | In Settings |
🏗 Architecture
flowchart LR
subgraph MAC["VQuant.app — sandboxed, hardened runtime"]
subgraph UI["App target — SwiftUI/AppKit · MainActor"]
V["VQuantApp<br/>scenes · commands"]
E["AppEnvironment<br/>dependency container"]
ST["Stores<br/>Session · Market · Workspace · Research · Quant"]
F["Features<br/>14 sections · Settings · Sign-in"]
end
subgraph CORE["VQuantCore — SwiftPM · Sendable · no UI"]
N["Networking<br/>HTTPTransport · APIClient · SSEParser"]
AU["Auth<br/>AuthService · TokenStore"]
SV["Services<br/>VQuantAPI · GenerationRunner"]
C["Cache<br/>DiskCache AES-GCM · Freshness"]
AN["Analytics<br/>Indicators · Downsampler · CSV"]
end
KC[("Keychain<br/>device token · cache key")]
PK["System passkeys<br/>Touch ID · iCloud Keychain"]
end
S["VQuant server<br/>vquant.spboucher.ai"]
V --> E --> ST --> F
ST --> SV --> N
ST --> AN
SV --> C
AU --> KC
AU --> PK
AU --> N
N -->|"HTTPS · JSON · SSE<br/>Bearer device token"| S
Native passkey sign-in
sequenceDiagram
participant A as VQuant.app
participant OS as macOS authenticator
participant S as VQuant server
participant K as Keychain
A->>S: POST /api/native/login/options
S-->>A: challenge
A->>OS: passkey assertion (Touch ID)
OS-->>A: signed assertion
A->>S: POST /api/native/login/verify
S-->>A: device token (shown once, stored hashed on the server)
A->>K: store token (this device only, not synced)
A->>S: every request carries the Bearer token
Note over A,S: a 401 signs the Mac out and erases the cache, a network failure never does
An analysis from the Mac
sequenceDiagram
participant A as GenerationRunner
participant S as VQuant server
A->>S: POST /api/chat
S-->>A: SSE events (job, status, plan, tools, text, figures)
Note over A,S: stream cut
A->>S: GET /api/generations/:id/stream?from=n
S-->>A: replay from event n, then live
A->>S: POST /api/generations/:id/cancel (Stop)
- Dependency injection.
AppEnvironmentis built once and passed explicitly to every view.@Environment(Model.self)is deliberately avoided: on macOS 27 it traps inside table cells, menus, sheets and toolbars. Core types take protocols (HTTPTransport,TokenStore,PasskeyAuthenticator) so tests substitute them. - Concurrency. Core is
Sendableand compiled in Swift 6 mode with complete checking; the app target defaults toMainActor. Long work isasync; the main thread never waits on the network. - Server responsibilities stay on the server: model inference, web research, the Python notebook, every quantitative engine, PDF/DOCX/slide rendering, persistence, per-person authorisation.
- Charting. Metal was evaluated and not used: the heaviest series is reduced to at most one mark per 2.5 points before drawing, so the cost of a frame is bounded by the window width, not by the series length.
🧱 Stack
| Layer | Technology | Version / setting | Role |
|---|---|---|---|
| Language | Swift | 6.0, SWIFT_STRICT_CONCURRENCY: complete |
Everything |
| UI | SwiftUI + AppKit | @Observable, typed WindowGroup restoration |
Windows, sections, menus |
| Charts | Core Graphics (Canvas) · Swift Charts |
— | Price charts · result figures |
| Auth | AuthenticationServices · LocalAuthentication | — | Platform passkeys · Touch ID lock |
| Storage | Keychain · AES-GCM disk cache | — | Device token · offline reading |
| Core | SwiftPM package VQuantCore |
swift-tools 6.0 | Networking, auth, streaming, models, cache, analytics |
| Project | XcodeGen (project.yml) |
— | Generates VQuant.xcodeproj |
| Minimum system | macOS | 14.0 | @Observable, SectorMark, onChange(of:initial:), SettingsLink |
| Dependencies | none | 0 packages | Checked on the signed bundle by Scripts/verify-release.sh |
🗂 Repository layout
vquant-macos/
├── Package.swift # SwiftPM: VQuantCore (Core/), VQuantAppLogic (kit-dependent logic of App/Next), tests
├── project.yml # XcodeGen: app target VQuant (+ VQuantKit, VQuantUI from ../VQuantKit) + VQuantUITests
├── App/ # 16 files · 3 186 lines
│ ├── VQuantApp.swift # scenes (main, chart, Settings, menu-bar extra), commands, layouts, launch guard
│ ├── AppEnvironment.swift # dependency container: api (1.x), vq (kit), sync, feature-store registry
│ ├── Navigation.swift # AppSection (14), MainSpec, ChartSpec, WindowModel, AskDraft
│ ├── SessionStore.swift # sign-in, lock, expiry
│ ├── Stores.swift, ResearchStore.swift, QuantStore.swift, LabStore.swift, SettingsStore.swift, Notifier.swift
│ └── Next/ # KitBridge (transport adapter, cipher), SyncStore, StudyStore, Commands,
│ # WorkspaceMapping, MacLogic (shortcut table, notification routes)
├── Features/ # 51 files · 15 534 lines — one folder per area
│ ├── Shell/ # MainWindow, SyncStatusView
│ ├── Auth/ # SignInView, SystemPasskeyAuthenticator
│ ├── Research/ # composer, cockpit (inspector), insight (route, usage, provenance, trace, approvals)
│ ├── Studio/ # projects, note editor, reviews, memory, export
│ ├── Terminal/ # overview, yield curve, watchlists, command palette, statements
│ ├── Markets/, Data/ # 1.x Markets and Data Explorer
│ ├── Charting/ # canvas, interaction, drawings, sync, provenance, ask, benchmark harness
│ ├── Quant/ # lab catalogue, generated forms, jobs, results, compare, review, options / backtest
│ ├── Portfolio/ # portfolios, holdings, CSV import, analysis and proposal, risk analytics
│ ├── MenuBar/, Agent/
│ └── Settings/ # 20 panes
├── Components/ # 4 files · 706 lines — DesignSystem, InlineEditing, GridTable, MarkdownView
├── Core/ # 25 files · 4 166 lines — VQuantCore (no UI, no kit)
│ ├── Networking/, Auth/, Services/, Models/, Cache/, Support/
│ ├── Analytics/ # Indicators, Downsampler, ChartDrawings, PortfolioImport, CSV
│ ├── Markdown/ # blocks, editing
│ ├── Terminal/, Lab/ # selection, statement maths, palette ranking, lab support
│ └── Stores/LocalStores.swift # 1.x local stores (now only the migration source and local-only layouts)
├── Resources/ # Info.plist, entitlements (Release / Debug), Assets.xcassets (AppIcon, AccentColor)
├── Scripts/ # build, tests, dev session (5058), restore check, provisioning, release, verification
├── Tests/
│ ├── CoreTests/ # 16 files + Fixtures/ (40 recorded responses) + Support/ (mocks)
│ ├── SyncTests/ # migration rule against the kit's fake server
│ └── UITests/ # 9 files · 30 tests
└── docs/ # reference documents + brand/🛠 Build and run
Scripts/build.sh debug # Debug build (products in ~/Library/Developer/VQuant)
swift test # core tests
Scripts/integration-test.sh [--analysis] # against the VQuant Next TEST backend (M2U64:~/dev/vquant-next-api, :5058)
Scripts/ui-test.sh # XCUITest, signed in on the test copy
Scripts/run-dev.sh [--shot f.png] [-- -VQSection charting -VQSymbol MSFT]
python3 Scripts/provision.py && Scripts/release.sh && Scripts/verify-release.sh && Scripts/notarize.sh| Script | Purpose |
|---|---|
Scripts/build.sh generate|debug|core-test|ui-test |
Development entry point: generate the Xcode project, build Debug, run the core and UI tests. Products go to ~/Library/Developer/VQuant (outside ~/Desktop: TCC and Launch Services treat Desktop specially) |
Scripts/dev-session.sh |
Opens the SSH tunnel to the backend test copy and a device session on it (software passkey). eval "$(Scripts/dev-session.sh)" sets VQ_SERVER and VQ_DEV_TOKEN; the token is never printed to the terminal |
Scripts/run-dev.sh |
Launches the Debug build against the test copy with a development session (in-memory stores: no Keychain, no real cache), optionally capturing its window |
Scripts/integration-test.sh |
Core suite against the real backend test copy (never production); --analysis also runs one fast and one cancelled analysis (calls the model provider: a few cents) |
Scripts/ui-test.sh |
XCUITest: the signed-out screen, and navigation of every section while signed in on the test copy |
Scripts/check-headers.sh |
Fails when a first-party source file lacks its author header |
Scripts/provision.py, Scripts/asc.py |
Register the bundle id, its Associated Domains capability and the Developer ID profile with the existing App Store Connect API key (idempotent) |
Scripts/release.sh · verify-release.sh · notarize.sh |
Release archive, bundle checks, notarization (see Release) |
Scripts/make-icon.swift · window-shot.swift |
Icon generator · window capture helper |
The test backend is the frozen VQuant Next API on its node (M2U64:~/dev/vquant-next-api, PORT=5058,
PASSKEY_ORIGIN=http://localhost:5058, a copy of production data; test objects are prefixed mac-test-). Debug builds
cannot use system passkeys; they receive a development session minted on the node by the copy's own helper
(Scripts/dev-session.sh; the token is kept in a private file and never printed). Scripts/run-dev.sh documents the
launch arguments that open any destination (-VQSection, -VQTheme, -VQTab, -VQSettings, -VQX…), and
Scripts/restore-check.sh checks window restoration with real key presses and a real quit.
⚙️ Configuration
| Setting | Where | Meaning |
|---|---|---|
| Server | App/AppEnvironment.swift |
https://vquant.spboucher.ai; a local override (-VQServer argument or VQ_SERVER) is accepted for localhost / 127.0.0.1 only |
VQ_DEV_TOKEN |
environment, Debug | Development session issued by Scripts/dev-session.sh |
-VQSection, -VQSymbol |
launch arguments | Open a given section and symbol (Scripts/run-dev.sh) |
VQ_DERIVED |
environment | DerivedData location for the UI tests (default ~/Library/Developer/VQuant/DerivedData) |
NOTARY_PROFILE |
environment | Existing notarytool keychain profile used by Scripts/notarize.sh |
| Bundle identifiers | project.yml |
Release ai.spboucher.vquant · Debug ai.spboucher.vquant.debug · UI tests ai.spboucher.vquant.uitests |
| Entitlements (Release) | Resources/VQuant.entitlements |
App Sandbox, network client, user-selected read-write files, Associated Domains webcredentials:vquant.spboucher.ai, Keychain access group |
| Entitlements (Debug) | Resources/VQuant-Debug.entitlements |
App Sandbox, network client, user-selected read-write files (no restricted entitlement) |
🖥 Sections and windows
| Group | Section | Shortcut |
|---|---|---|
| Research | Research | ⌘1 |
| Research | Research Studio | ⌘2 |
| Terminal | Overview | ⌘3 |
| Terminal | Markets | ⌘4 |
| Terminal | Watchlists | ⌘5 |
| Terminal | Charting | ⌘6 |
| Terminal | Statements | ⌘7 |
| Quant | Quant Lab | ⌘8 |
| Portfolio | Portfolios | ⌘9 |
| Terminal | Data Explorer | View menu |
| Portfolio | Risk Analytics | View menu |
| Quant | Jobs | View menu |
| Workspace | Agent | View menu |
| Workspace | Documents | View menu |
| Scene | Description |
|---|---|
WindowGroup(id: "main", for: MainSpec.self) |
Any number of workstation windows; each has its own WindowModel (section, symbol, conversation, selected computation), restored by macOS where it was |
WindowGroup(id: "chart", for: ChartSpec.self) |
Detached chart windows (symbol, interval, range, comparisons restored) |
Settings |
Panes include Account, Security (Touch ID and passkeys), Devices, Cache, Notifications and Network (diagnostics) |
Other commands (one table in code, AppShortcuts, with a unit-tested collision check): ⌘K command palette ·
⌥⌘F find symbol · ⌘R refresh now · ⌥⌘S sync now · ⌥⌘N new conversation · ⇧⌘R new research study ·
⇧⌘A attach dataset · ⌘. stop analysis · ⌥⌘I research inspector · ⇧⌘L lab catalogue · ⌥⌘R run again ·
⇧⌘N new chart window · ⇧⌘D detach chart · ⇧⌘S save window layout (was ⌃⌘S in 1.0.1, which is the system's
Show/Hide Sidebar) · ⌃⌘L lock VQuant. A menu-bar extra (Settings › Appearance) shows the market session, a few
indices, running work and a quick ask.
🔌 Backend API used
Every route the client calls was read in the backend source and is listed, with its verification status, in
docs/API_INVENTORY.md. The client calls no route outside that inventory
(Core/Services/VQuantAPI.swift, Core/Auth/AuthService.swift). Transport: HTTPS, JSON, server-sent events;
native clients send X-VQ-Client: vquant-macos/<version> and a Bearer device token. There is no WebSocket endpoint.
2.0.0 adds the backend 6 surface (/api/v2/*: sync, models and routing, usage, data layer, search, projects, reviews,
memory, audit, autonomous research) through the shared package VQuantKit — part 2 of the inventory.
| Area | Routes |
|---|---|
| Authentication | GET /api/health · POST /api/native/login/options|verify · POST /api/native/register/options|verify · GET /api/native/session · POST /api/native/logout · POST /api/native/reauth/options|verify · GET /api/native/devices · DELETE /api/native/devices/:id · DELETE /api/native/passkeys/:ref |
| Market data | GET /api/fmp/indices · /gainers · /losers · /actives · /market-hours · /search · /quote/:symbol · /company-profile/:symbol · /chart/full/:symbol · /chart/intraday/:symbol · the 15 dataset routes |
| Research agent | POST /api/chat · GET /api/generations · GET /api/generations/:id/stream · POST /api/generations/:id/cancel · GET/PATCH/DELETE /api/sessions[/:id] |
| Exports and reports | POST /api/generate-pdf · /generate-docx · /convert-to-slides · GET /api/shared-reports · GET /api/share/:id · POST /api/share · GET /figures/*, /plots/*, /api/download/:file |
| Workspace | GET /api/workspace · memories, portfolio and watches routes |
| Quant Engine | GET /api/quant/tools · POST /api/quant/jobs · GET /api/quant/jobs · GET/DELETE /api/quant/jobs/:id |
| Diagnostics | GET /api/analytics/real-time-stats |
Not exposed on purpose: the admin routes (/api/admin/*), which act on every person's data with no per-person
check. Not used: /api/speech-to-text (dictation is not ported).
Server limits the client reports as they are: 4 running analyses per person, one per conversation; analysis jobs live in the server's memory (a restart ends them); replay for 20 minutes after the end; no cancel route for quant jobs.
🗄 Local data
The Mac holds no database: the server is the source of truth.
| Item | Where | Protection |
|---|---|---|
Device token (vqn_…) |
Keychain generic password | WhenUnlockedThisDeviceOnly, not synced; behind SecAccessControl(.userPresence) when the Touch ID lock is on |
| Offline cache | Disk, per cache key | AES-GCM sealed under a Keychain key, excluded from backups, erased at sign-out or when another person signs in |
| Watchlists | Local store (Core/Stores/LocalStores.swift) |
Local to the Mac |
| Saved window layouts | Local store | Windows, what each shows, frames and displays |
| Per-window navigation | Scene storage | Restored by macOS |
🔐 Security and privacy
- Same people, same passkeys, same relying party as the web app: nothing new to create for a person who already uses it. A passkey created in Safari and synced by iCloud Keychain signs in here, and the reverse.
- Why the web cookie is not reused: a native app has no page origin, and the cookie is identical on every device and cannot be revoked individually. The bridge issues one opaque device token (256 random bits), stored on the server as a SHA-256 hash; unused for 90 days it expires; revocation is immediate.
- Sensitive operations (revoking another device, deleting a passkey) need a fresh passkey check, valid 5 minutes; the last passkey of an account cannot be deleted.
- The token is the only credential stored on the Mac. Passkey private keys stay in the system authenticator; biometric data never reaches the app or the server.
- Touch ID app lock: Touch ID unlocks the credential; the server still authenticates every request.
- Sign-out revokes the session on the server, then clears the Keychain and the cache. A 401 (revoked elsewhere, expired) signs the Mac out and erases the cache. A network failure never signs out.
- App Sandbox and hardened runtime; no web engine, no JavaScript engine, no third-party code, no secret in the
bundle — all checked on the signed bundle by
Scripts/verify-release.sh(13 checks). - Offline: nothing is queued while offline; analyses, computations and edits are refused with an explanation. A server refusal is always an error, never served from the cache.
Details: docs/AUTHENTICATION.md.
🧪 Testing
| Suite | Command | Result for 2.0.0 (details and evidence classes in docs/TEST_REPORT.md) |
|---|---|---|
| Core unit tests | swift test |
130 tests in 21 suites + 5 in the sync-migration suite — passed |
| Integration against the VQuant Next test backend (5058, never production): passkey ceremonies with a software authenticator, market data, quant jobs, Quant Lab, Studio, research workspace | Scripts/integration-test.sh |
130 tests in 21 suites passed; the real-analysis test skipped (model calls) |
| UI tests (8 classes, run serially) | VQ_UI_ONLY=<Class> Scripts/ui-test.sh |
28 tests: 23 passed, 2 failed, 3 skipped — the failures are XCUITest clicks not delivered on two custom controls; the same paths work with real pointer events |
| Real pointer and key events | cliclick + System Events, Scripts/restore-check.sh |
drag-reorder, chart drawing, ticker drop, routing clicks, review sheet, window restoration after a real quit |
| Signed bundle | Scripts/verify-release.sh |
13 checks passed |
| Headers | Scripts/check-headers.sh |
ok |
Fixtures in Tests/CoreTests/Fixtures are responses recorded from the test copies; mocks (MockTransport,
SoftwareAuthenticator) exist only in the test target. Model calls made for 2.0.0: one fast analysis ($0.0034) and
one research study ($0.318), both on the test backend.
Measured: the chart renderer (10 000 bars with all indicators: 39.4 ms → 5.0 ms per frame; 100 000 bars: 444 ms →
4.4 ms; Metal not adopted — docs/CHART_PERFORMANCE.md); 162 MB resident for the signed
build signed in and idle for a few seconds; bundle 24 MB, universal.
📦 Release
python3 Scripts/provision.py # bundle id, Associated Domains capability, Developer ID profile (idempotent)
Scripts/release.sh # Release archive signed with the existing Developer ID Application identity → dist/VQuant.app
Scripts/verify-release.sh # 13 checks on the signed bundle
Scripts/notarize.sh # notarize + staple the app, then build, sign, notarize and staple the DMG| Item | Value |
|---|---|
| Version | 2.0.0 (3), tag v2.0.0 — notarized and published 2026-11-20. Previous: 1.0.1 (2), tag v1.0.1 |
| Bundle identifier | ai.spboucher.vquant (App ID shared with the iOS app of the same name) |
| Signing | Developer ID Application, manual, provisioning profile "VQuant Developer ID" (Associated Domains), --timestamp |
| Notarization | 1.0.1: application and disk image Accepted, stapled and validated. 2.0.0: not submitted (owner's decision) |
| Gatekeeper | spctl -a -vv /Applications/VQuant.app → accepted, source=Notarized Developer ID |
| Artifact | dist/VQuant-2.0.0.dmg (published 2.0.0, notarized) · dist/VQuant-1.0.1.dmg (previous) — not tracked in git |
| Architecture | Universal (ONLY_ACTIVE_ARCH: NO in Release) |
The scripts never create, print or modify credentials: they fail if no Developer ID Application identity exists, and "notarized" is printed only when Apple answered Accepted.
🔑 First sign-in on a Mac
Install VQuant.app in /Applications, open it, Sign In with a Passkey. A passkey created for the web app and
synced by iCloud Keychain works as is. For a Mac without one: on the server node,
cd ~/vquant && npm run -s access:invite invite <person>, then paste the link under Enrol this Mac with a setup link.
🩺 Troubleshooting and gotchas
| Topic | Explanation |
|---|---|
| Debug builds and passkeys | The Associated Domains entitlement needs the Developer ID provisioning profile, and macOS resolves the association per application identifier: Debug builds use another bundle id (.debug) and cannot use system passkeys. Development and tests use a software authenticator against the backend test copy |
| A development copy must never shadow the installed app | Hence the distinct Debug identifier: a copy registered with Launch Services under the release id would break the passkey domain association |
| Lists on macOS 27 | The outline-backed List(selection:) received the click but never selected a row (defect of 1.0.0: sidebar and inner lists did not respond). Every single-selection list uses rows that select by their own action (SelectableRow) |
Never write navigation back into a WindowGroup(for:) value |
It re-creates the window content. Per-window state lives in scene storage |
@Environment(Model.self) |
Traps on macOS 27 inside table cells, menus, sheets and toolbars: the environment is passed explicitly |
| No window after a forced quit | A launch guard reopens the main window |
| Efficient frontier | Drawn as points: a line through x-sorted points was wrong |
| UI tests bundle | Ad hoc signed with the hardened runtime off: library validation would refuse to load it |
| Build products | Kept in ~/Library/Developer/VQuant, outside ~/Desktop (TCC and Launch Services treat Desktop specially) |
| Passkey refused on a new Mac | Apple's CDN must serve the server's apple-app-site-association file listing the app id |
| Signed out unexpectedly | The server answered 401: the session was revoked elsewhere or unused for 90 days |
🧭 Known limitations and next steps
Known gaps of 2.0.0 (docs/FEATURE_PARITY.md):
- Keyboard arrow navigation exists in the watchlist table and the palette; other lists select on click.
- LaTeX formulas are not typeset. No dictation. No admin console (by design).
- Numbers follow the account's synced number format (fr-CA on the owner's account) in the 2.0 screens, while the 1.x screens (Markets, the chart axis, the quote panel) keep the system format; labels are English everywhere.
- Chart rendering uses Core Graphics, not Metal — by measurement (
docs/CHART_PERFORMANCE.md). - Instruments profiling was not run.
Not verified — the complete list is in docs/TEST_REPORT.md. The main ones: every Touch ID
ceremony (sign-in on the signed build, enrolment, app lock, reauth-gated revocation from the Settings pane — the API
is tested with a software authenticator); a research approval answered from the Mac; a review started from the Mac;
the migration on a Mac that really holds 1.x watchlists; the real menu-bar item; a delivered system notification;
offline with the network physically off; deep and ultra modes, Stop and mid-stream join on backend 6; Intel Macs and
macOS 14–26; VoiceOver.
What would come next:
- Notarize and publish 2.0.0 once the owner has tried the signed build against production backend 6.
- Keyboard navigation in every list; one number format across 1.x and 2.0 screens.
- LaTeX rendering; dictation once the server has a speech key.
- Instruments passes (Time Profiler on chart interaction, Allocations on long research sessions) and an automatic update channel.
📚 Documentation
| Document | Content |
|---|---|
docs/MACOS_ARCHITECTURE.md |
2.0 in one page, layers (core, kit, app), sync, research, windows, charting, freshness, offline |
docs/CHART_PERFORMANCE.md |
Frame-time measurements of the chart renderer and the Metal decision |
docs/FEATURE_PARITY.md |
Every web feature and native addition, with its evidence; what the brief asked for that does not exist |
docs/API_INVENTORY.md |
Every route the client calls, verified in the backend source |
docs/AUTHENTICATION.md |
Passkeys, device sessions, Touch ID lock |
docs/MIGRATION_PLAN.md |
Phases, backend changes, next steps |
docs/TEST_REPORT.md |
What was tested, measured, fixed, and what was not verified |
👤 Author
Simon-Pierre Boucher — design, development, operations
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
📄 License
All rights reserved © 2026 Simon-Pierre Boucher. Private software.