SPB Git

Repository Public

13 entries at the root
History

Latest commit 2.0.0 (3) shipped: notarized, stapled, installed, published; release notes cb72a22

NameLast commitUpdated
App Windows restore where they were: scene storage applied when it arrives and written for windows...
Components Layouts can always be saved (window reported when the view enters it), English-only wording...
Core Charting: time axis without a per-frame scan, chart object id shared with the web, draggable...
docs 2.0.0 (3) shipped: notarized, stapled, installed, published; release notes
Features Layouts can always be saved (window reported when the view enters it), English-only wording...
Resources Shell: Ember accent, ink sidebar icons
Scripts Tests: honest handling of synthesized drags and hidden status item, restore-check script,...
Tests Layouts can always be saved (window reported when the view enters it), English-only wording...
VQuant.xcodeproj Quant Lab: draggable two-pane workbench (no HSplitView constraint loop), SwiftUI progress bars...
.gitignore Core: networking, native passkey auth, SSE runner, models, encrypted cache, analytics, tests...
Package.swift Terminal 2.0: market overview, synced watchlists, command palette, statements
project.yml Foundation of 2.0.0: VQuantKit dependency, transport adapter, sync engine wiring, new...
README.md 2.0.0 (3) shipped: notarized, stapled, installed, published; release notes
README.md View source
VQuant for macOS logo



VQuant for macOS icon

# 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

backend version platform license author

Swift SwiftUI AppKit Swift Charts Core Graphics AuthenticationServices cache SwiftPM XcodeGen dependencies web view

commits last commit activity language languages size branches tags clones

Swift files Swift lines sections datasets quant engines unit tests integration tests UI tests fixtures bundle checks

bundle id signing notarization sandbox hardened runtime deployment target backend


# Table of contents


# 🎯 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 releases vquant-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/*, contract vquant-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. AppEnvironment is 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 Sendable and compiled in Swift 6 mode with complete checking; the app target defaults to MainActor. Long work is async; 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

text
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

bash
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

bash
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:

  1. Notarize and publish 2.0.0 once the owner has tried the signed build against production backend 6.
  2. Keyboard navigation in every list; one number format across 1.x and 2.0 screens.
  3. LaTeX rendering; dictation once the server has a speech key.
  4. 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.

Clone vquant-macos

Anonymous clone and fetch. Pushing requires the owner's personal access token.

Snapshot of main

Files main
Menu

Theme