SPB Git

Repository Public

README.md 12.6 KB 176 lines markdown

1# VQuantKit23The shared Swift package of the VQuant native apps (macOS 14+, iOS/iPadOS 18+) for backend 6 "VQuant Next".4Swift 6 language mode, strict concurrency, no third-party dependency.56Contract: `vquant-next/docs/next/CONTRACT.md` (§1 sync, §2 models/usage/trace, §3 data layer, §4 Quant Lab,7§5 projects/review, §6 memory, §7 audit, §8 design system). Integration guide for the two apps: `docs/INTEGRATION.md`.89| Product | What it is |10|---|---|11| `VQuantKit` | No UI, `Sendable`: transport seam, sync engine, models of every v6 route, Lab form and jobs, formatting |12| `VQuantUI` | SwiftUI: design-system components and the generic `LabResultView` (Swift Charts) |13| `VQuantKitTesting` | Fakes for tests: `VQFakeServer` (contract rev/seq rules), `VQManualClock`, `VQScriptedTransport` |14| `vqkit-shots` | macOS executable: renders VQuantUI to PNG for visual review |1516## Layout1718```19Sources/VQuantKit/20  Core/        VQJSON (lossless JSON), VQTransport + VQClient + VQError, VQSSEParser, VQClock, VQURLSessionTransport21  Sync/        VQObjectEnvelope, typed kinds (VQWatchlist, VQPortfolio, VQWorkspace + VQLayoutNode, VQChart, VQProject,22               VQNote, VQReview, VQPreference), VQObjectStoreClient, VQMerge, VQSyncStorage, VQSyncEngine,23               VQSyncedCollection / VQSyncStatusStore (@Observable)24  Models/      VQModelCatalog, VQRouteDecision, VQUsage, VQGenerationTrace, VQGenerationEvent, VQMessageExtras25  Data/        VQBarSeries, VQQuotes, VQStatements, VQMarketOverview, VQDataHealth, VQSearchResults, VQFreshness26  Lab/         VQLabResult (lab/1), VQLabCatalog / VQLabTool / VQLabParam, VQLabForm, VQQuantJob, VQLabClient,27               VQLabChartData (axis reading, downsampling, colour classes — the pure part of rendering)28  Research/    VQProjectBundle, run/export, reviews, VQMemory*, VQAuditEvent, VQResearchClient   (§5–7: projects)29  ResearchAgent/  the autonomous research agent (§9): VQResearchAgentClient (sessions, files, inspect, upload,30               ledger, runs + logs, approvals, sandbox), VQResearchEvent, VQResearchState + VQResearchReducer,31               VQResearchSessionStore (@Observable), VQAnalysisMode (`research`), VQDatasetUpload, VQResearchFileTree,32               VQDelimitedText, VQPythonSyntax33  Formatting/  VQFormat (numbers and dates identical to the web's lib/format.ts)34Sources/VQuantUI/35  Tokens/      VQTokens.swift — GENERATED, do not edit (see below)36  Components/  VQSurface, VQPanel, VQSectionHeader, VQMetricTile, VQKindBadge, VQDelta, VQProvenanceChip,37               VQSegmentedControl, VQEmptyState, VQSkeleton*, VQAIActivity, VQSparkline, VQProviderLogo,38               VQDataTable, VQMarkdownText39  Lab/         LabResultView, LabChartView, LabDiagnosticsList, LabProvenancePanel40  Research/    ResearchActivityView (container) and its pieces: ResearchPlanView, ResearchTimelineView,41               ResearchExecutionList, ResearchCodeView, ResearchExperimentsTable, ResearchFiguresGrid,42               ResearchRunsList, ResearchFilesBrowser, ResearchFilePreview, ResearchEnvironmentPanel,43               ResearchQualityGateView, ResearchApprovalCard; ResearchDataSource / ResearchPreload (environment)44  Support/     VQTheme (environment), VQSVGPath, VQExport (PNG / PDF / CSV), VQPasteboard45```4647## Design decisions worth knowing4849- **`VQTransport`** is the only seam with the network: `send` (data + `HTTPURLResponse`, whatever the status) and50  `stream` (bytes for SSE). The package never sees a URL or a token. Each app adapts its own `APIClient` in a few51  lines; `VQURLSessionTransport` is a complete implementation for a token provider closure.52- **`VQJSON`**, not `JSONValue`: both apps' `VQuantCore` already export a `JSONValue`.53- **Forward compatibility.** The sync models are *views over their JSON* (`VQJSONBacked`): unknown keys at any depth,54  explicit nulls and fields of an unexpected type survive decode → typed edit → encode. Everything else is read with55  tolerant `init(json:)` initialisers that never throw; enumerations are `VQOpen<Known>` (unknown values are kept);56  unknown stream events come back as `.other`. Object kinds are strings (`VQObjectKind`), so a kind added by a later57  contract section is replicated by the sync engine untouched.58- **Adding §9 (or any later section)** = a new folder with its models (`init(json:)`), a client struct over `VQClient`,59  one property on `VQuantAPI`. New stream events: a case in `VQGenerationEvent` / `VQSyncStreamEvent`.60- **Formatting** is tested against 4 212 strings generated by the web's own `format.ts`.61- **Freshness** never says "live": polled / delayed / close / historical / estimated.6263## Sync engine in one paragraph6465`VQSyncEngine` (an actor) keeps `replica` (last server state, tombstones included), an ordered durable `queue` of66local writes, and the change-feed cursor, in a `VQSyncStorage` (files with atomic writes and an optional67`VQSyncCipher`, or memory). Reads return the replica with the queue applied. `flush()` replays the queue in order with68the rev the server gave (never an invented one); a 409 — or a replica that moved since the edit — goes through69`VQMerge`: element-wise for watchlist symbols, portfolio positions (and cash), `project.items`, `chart.drawings`70("local edit wins per element"), last-writer-wins for the rest, with a `VQConflictRecord` holding both versions when71content of the other side was overwritten. `pull()` pages the feed by `since`. `start()` opens the stream, reconnects72with back-off, pulls on `hello`/`change`, exposes `hint` events. Nothing runs on its own unless `start()` is called.7374Deliberate choices to review: (1) non-list fields use the contract's whole-object last-writer-wins by default;75`Configuration.granularity = .field` keeps keys this device did not touch. (2) Portfolio `cash` is merged by currency76like positions (the contract names positions only). (3) A local deletion wins over a concurrent remote edit and is77reported with the remote content, which `restoreRemoteVersion(ofConflict:)` writes back.7879## Tests8081```bash82swift build && swift test                      # 129 kit tests + 23 UI tests; live tests are skipped83xcodebuild -scheme VQuantKit-Package -destination 'generic/platform=iOS Simulator' build84swift run vqkit-shots                          # PNGs in /tmp/vqkit-shots (+ tiles/ for tall ones)85```8687Fixtures (`Tests/VQuantKitTests/Fixtures`) are real responses of the frozen test backend (M2U64:5058), trimmed by88`Scripts/trim-fixtures.py` (long arrays decimated, structure kept). Re-record: `Scripts/record-fixtures.sh`89(never production; the token stays on the node). `budget` and `quant_job` stream events did not occur in the90recorded run: those two payloads are written from the contract. Formatting vectors:91`TZ=America/Toronto npx tsx <kit>/Scripts/format-golden.mjs <kit>/Tests/VQuantKitTests/Fixtures/format_golden.json`92from the web repo root.9394Live integration tests (opt-in):9596```bash97ssh -f -N -L 5058:localhost:5058 M2U64          # note the PID (lsof -nP -iTCP:5058 -sTCP:LISTEN), kill it afterwards98VQ_LIVE=1 VQ_BASE_URL=http://localhost:5058 VQ_TOKEN="$(ssh M2U64 cat /tmp/vq-api-token)" swift test --filter VQuantKitLiveTests99```100101Research-agent fixtures (`Fixtures/research/`) come from the real study on the 5059 copy102(`Scripts/record-research-fixtures-remote.sh`); `stream_study.json` is the web team's recording of that study's103generation stream. No approval occurred in it: approval events in the tests are written from the contract.104Live, read-only, against that copy:105106```bash107ssh -f -N -L 5059:localhost:5059 M2U64108VQ_LIVE=1 VQ_RESEARCH_BASE_URL=http://localhost:5059 VQ_RESEARCH_TOKEN="$(ssh M2U64 cat /tmp/vq-api-token-5059)" swift test --filter VQuantKitResearchLiveTests109```110111## Research agent (CONTRACT §9)112113One view model, two builders — the same design as the web's `client/src/lib/research` (the reducer is a port of it,114so the three platforms show the same thing for the same events):115116- `VQResearchReducer.reduce(&state, eventJSON, index:)` while a generation streams. Replays at or below the last index117  are ignored, entities with an id are upserts, unknown events change nothing, a late duplicate never revives a118  finished run, failed cells are kept with their error.119- `VQResearchState(detail:conversation:)` once it is over, from `GET /api/v2/research/sessions/:id` and the stored120  conversation. What the server does not keep is left empty: the linter verdict of each figure, the plan, the console121  output of cells that printed nothing.122- `VQResearchSessionStore` holds both (live on top of the snapshot) for SwiftUI and answers approvals.123124On the recorded study both builders give 56 executions (46 cells + 10 runs), 4 failed, 9 experiments (one failed, one125abandoned), 14 figures, and the same quality-gate findings.126127## 0.3 — additive fields of backend 6 (all source-compatible)128129No public declaration was renamed, removed or re-typed, and no case was added to an existing enumeration (an app130that switches exhaustively keeps compiling). New server vocabulary therefore arrives beside the frozen enumerations:131132| Server addition | Where it is |133|---|---|134| unit `years`, any later unit | `unitName` on metrics, columns and axes + `VQFormat.byUnitName` (`VQValueUnit` unchanged) |135| usage role `utility` | `VQUsageByModel.isUtility` (decodes as `.unknown("utility")`) |136| `budget_applied` event | `VQBudgetApplied(event:)` on the `.other` payload; `VQGenerationTrace.budgetApplied` |137| `code_execution_start`, new `figure_lint`, `at`, `toolId` | handled by `VQResearchReducer`; `VQResearchEvent` keeps its cases (`.other` for the new type) |138| `lab/1` renderer rules | `Column.currency / currencyKey / type`, `XAxis.unit / currency`, `YAxis.currency`, `Chart.z` + `cellAxis`, `Series.drawsCentreLine`, `Series.open/high/low/close/volume` |139| conditional parameters | `VQLabParam.requiredWhen / visibleWhen` (`VQLabCondition`), `VQLabForm.isVisible / isRequired / visibleGroups`; `validate()` enforces `requiredWhen` with the server's sentence |140| research REST | `VQResearchSessionDetail.generations / plan / figures`, `VQResearchAgentClient.deleteFile`, `researchModeAvailability()` |141142Lab fixtures were re-recorded (`Fixtures/job_*.json`); the earlier recordings are kept in `Fixtures/lab_v0/` and143still decode and render (history holds old results). Batch bars and splits are not in CONTRACT §3 yet: not added.144145## 0.4 — one language per screen (source-compatible)146147- All user-facing strings of VQuantUI and the display strings of VQuantKit live in a String Catalog148  (`Sources/VQuantKit/Resources/Localizable.xcstrings`, `defaultLocalization: "en"`, 275 keys, English + French,149  plural variations). `VQL10n.string(_:_:…)` reads it through `Bundle.module`.150- `VQLanguage.preferred` now follows the **app's** localisation (`Bundle.main.preferredLocalizations`) instead of the151  device's language list: the components no longer answer in French inside an English app.152- Override: `.vqLanguage(_:)` / `.vqLanguage(locale:)` on any view (environment `\.vqLanguage`); it wins over153  `VQTheme.language`. New overloads with a language: `VQLabForm.validate(language:)`, `issue(for:language:)`,154  `VQLabCondition.sentence(labels:language:)`, `VQProviderMark.displayName(_:)`, `VQLanguage(locale:)`.155- Server-authored text is never translated. Date layouts and number formats stay formatting (`VQFormat`, `numberLocale`).156- `swift run vqkit-shots <fixtures> <out> --both` renders every shot in French and in English (`…-en.png`).157158## Design tokens159160`Sources/VQuantUI/Tokens/VQTokens.swift` is a copy of the generated `shared/design/VQTokens.swift` of the web repo.161Never edit it. To update: edit `shared/design/tokens.json` there, run `node scripts/design-tokens.mjs`, copy the162file here again.163164## Known limits165166- `$…$` formulas are **not typeset**: the LaTeX is made readable (Greek letters, operators) and set in mono.167- A `surface` chart is drawn as a filled-contour map (seven classes, boundaries in the key), not in 3-D; heat maps use168  the same seven classes rather than a continuous ramp.169- `candles` is in the schema but no engine emits it: such a chart falls back to lines and has not been seen rendered.170- Off-screen exports cannot scroll: wide tables are narrowed, and cut on the right below phone width.171- Results of the six legacy tools are not `lab/1`: the apps keep their own renderers (`job.labResult == nil`).172- Research figures are shown from their PNG; SVG and PDF are export actions (bytes handed to the app), not previews.173- Python colouring is a tokenizer, not a parser; other languages are shown as plain mono text.174- Studies recorded before the server kept figures have no linter verdict when reopened (shown as "not kept").175- No engine emits `candles` yet: the candle marks are tested on the contract's encoding built from recorded AAPL bars.176
Files main
Menu

Theme