docs/INVENTORY.md

Rama main · réplica de lectura del repositorio original.

# FlintTrade Feature Inventory

This is the build-status inventory the project's roadmap calls for: every mission
pillar and feature, categorised as **(a) built & working**, **(b) built but
untested or only partially wired**, or **(c) referenced but not built / blocked**.
It is a living document — update it in the same change that moves a feature
between buckets.

`v0.0.1` is pre-release software and is not production ready. The native adapter code for six
adapters (Dhan, Upstox, Kotak Neo, INDmoney, Groww, and Delta Exchange) is present and
mock-tested. Dhan, Upstox, and Kotak Neo are the current connectable native set
(Kotak Neo for Connected (read) / API smoke only. Live placement stays
disabled. Neo has no sandbox). INDmoney is read-verified with a locally
verified fail-closed planner, but remains disabled until restart-time
regular/smart-parent cancellation can be resolved authoritatively and a
broker-atomic reduce-only close primitive plus funded/live-market order-safety
proof exist. Groww stays `connectable=false` and retains its remaining live
blockers. Groww's official `growwapi` SDK is pinned for attestation/reference
parity while the adapter keeps using FlintTrade's tested REST transport; the
latest key-secret probe proves login/account reads but still lacks broker-side
market-data/API permission, static IP, and order-safety evidence. Broker sessions are not available in the terminal. Writes return 503 and reads return 409.
Read smoke on a static-IP host uses the in-process read path, not a Setup → Brokers HTTP session.
INDmoney is a REST-native adapter with no SDK pin; its dashboard token resets
at the daily 06:00 IST cycle. Delta Exchange is also REST-native with no SDK pin.
It stays disabled until Live order safety and unattended deadman flattening are
proven, and its configured authentication method uses an API key and secret for one venue (India or Global,
production or testnet). INDstocks' own FAQ advertises `indstocks-sdk`, but
PyPI and npm currently have no matching package, so the adapter stays REST-native
until a real SDK distribution can be pinned.
Broker SDK source mirrors can be checked with `uv run python scripts/sync_broker_sdk_refs.py --fail-on-drift`;
tracked runtime installation still comes only from `uv.lock` and `brokers.lock`.
Kotak Neo uses exact Git provenance: `v3.0.9` peeled to
`0ba71b7f7c295652d4c3ea2b5ce5a88849db18a3` is the pinned runtime and the
release baseline. Freshness compares that release, not default-branch HEAD.
The runtime exposes `kotakneoapi` 3.0.9; `release_version` 3.0.9 remains the stable
compatibility baseline. Both retain the `neo_api_client` import
namespace; the old `neo-api-client` distribution is forbidden. Closed-market/
no-funds verification does not prove funded live order execution.
The 3.0.9 runtime update is verified offline only; the retained activation date
and earlier real-account read evidence remain historical, not new SDK proof.

## Legend

| Mark | Meaning |
|---|---|
| ✅ | **(a)** Built & working — wired end-to-end and covered by tests |
| 🟡 | **(b)** Built but untested, partially wired, or honest-sample-only |
| ⛔ | **(c)** Referenced but not built, or externally blocked |

---

## Independence

| Item | Status | Notes |
|---|---|---|
| Native-first backend, gateway contract, safety/gating layer | ✅ | Original work; not a fork |
| Attribution (`NOTICE`, `docs/REFERENCES.md`, AGPL `LICENSE`) | ✅ | Adapted modules carry in-source `Adapted from:` headers |
| Independence statement in README + website | ✅ | `docs/README.md` "Independence & attribution" → site |

## Brokers

| Item | Status | Notes |
|---|---|---|
| Smart routing suggestions | ✅ | Capability metadata + recommendation engine + Account-Manager UI |
| — Dhan: rolling-options history + documented L20 depth feed | 🟡 | Rolling-options history is encoded in routing capabilities; Dhan's L20 depth remains feed-only until FlintTrade wires a runtime depth snapshot bridge (`market_depth_runtime_ready=false`). |
| — Upstox: historical-data edge | ✅ | `historical_max_lookback/candles` capabilities |
| — Kotak Neo: low-cost execution metadata | ✅ | `brokerage_free` + `low_cost_execution` use-case |
| Native adapters (Dhan/Upstox/Kotak Neo/INDmoney/Groww/Delta Exchange): identity, capabilities, order + **data** surfaces | 🟡 | Adapter and mapping code is present and mock-tested. Dhan and Upstox are connectable after live verification and emergency-planner coverage. INDmoney's fail-closed planner is locally verified but it remains coming soon pending an authoritative restart-time regular/smart-parent discriminator, a broker-atomic reduce-only close primitive, and a funded/live-market order-safety proof. Kotak Neo is connectable for Connected (read) / API smoke on the exact v3 Git runtime; its async SFeed and order-feed lifecycle is wired and locally synthetic-tested, while the historical live evidence remains REST reads only. Live-account/market-hours feed, funded-order safety, Live catalogue promotion, and cross-platform proof remain outstanding; Live place stays fail-closed. Neo has no sandbox (never offer Neo Practice). Groww retains its documented live blockers. Delta Exchange stays disabled until Live order safety and unattended deadman flattening are proven. Its configured authentication method uses an API key and secret for one venue (India or Global, production or testnet). |
| Multiple brokers per account, per-broker rate limits | ✅ | `BrokerRateLimiter` + live-apply UI (Account Manager) |

## AI Agent

| Item | Status | Notes |
|---|---|---|
| Connect to any model — cloud providers | ✅ | OpenAI/Anthropic/Gemini/Groq/Mistral/Cerebras/… via `LLMProvider` + `LLMSection` |
| Local models - managed Ollama and custom endpoints | ✅ | Ollama runtime is installed on demand with a pinned hash and controlled from Settings; external endpoints remain available through generic providers |
| AI agent backends | ✅ | `agent_backends` registry + AI Backends widget — Claude Code (API/OAuth), Cerebras, Codex (streaming), additional catalogued hosts |
| Obsidian vault | ✅ | Read-only browser widget + agent vault context |
| Create strategies | ✅ | StrategyBuilder (legs / payoff / margin / Pine) — Lab "Options Builder" tab; loads templates from the StrategyTemplates widget via explicit strike offsets |
| Backtest strategies (single + portfolio) | ✅ | Lab Backtest + Portfolio tabs (132 runnable by name; 41 selectable in the Lab picker) |
| Optimise overnight + reports + suggestions | ✅ | OvernightOptimiser + report store + Lab Optimise section |
| Pick strategy per market regime | ✅ | `regime_detector` `_REGIME_STRATEGY` → RegimePanel "Suggested Strategy" |

## Manual Trading Terminal

| Item | Status | Notes |
|---|---|---|
| Preset layouts (17) | ✅ | FlexLayout workspace presets |
| Options-scalper 4-chart layout | ✅ | Index+Futures (centre) / CE+PE (sides) / option chain — per-panel pinned charts; tested |
| Trading + dashboard widgets (71 registered; see `widgetFactory.tsx` for the count of record) | ✅ | Registered in `widgetFactory`, co-located tests |
| Operating modes: Practice and Live | ✅ | Connected (read) is a broker status, not a Mode. Example is sample data, not a Mode. The public web demo is Demo (example data). Practice places a simulated order. Widget catalogue count remains 71. The old sample-data URL is not a first-class installed screen. |
| Professional charts + indicators | ✅ | `widgets/analysis/Chart/` on the lightweight-charts library |
| Practice mode | ✅ | Practice controls (capital + place simulated order) |
| Trade journal | Partial | `TradeJournalTool` reads recorded executions; authoritative native fill ingestion is not connected. Submission acknowledgements remain in the audit trail, not the fill journal. |
| Multiple built-in strategies | ✅ | 132 runnable by name (`ALL_STRATEGIES` + `STRATEGY_REGISTRY` + `BUILTIN`); 41 selectable in the Lab picker |
| Option-analysis tabs (GEX / IV-smile / max-pain / OI-profile) | ✅ | Live option chains use strict exchange, expiry, row, Greek and lot-size provenance through the configured broker path; incomplete or contradictory inputs fail closed to a labelled sample/unavailable state |
| Analytics widgets (VWAP / multi-timeframe / correlation pairs / correlation matrix) | ✅ | History and analysis reads are scoped to the selected native account and mode; explicit source badges identify Sample/Example fallbacks. Native HTTP reads remain unavailable until cutover activation. |
| IV-smile-derived widgets (IV skew / Greeks heatmap) | ✅ | IV-smile analysis and shared Black–Scholes transforms use explicit source badges and loading/unavailable states. Native HTTP reads remain unavailable until cutover activation. |
| Vol-surface, straddle-PnL analysis | 🟡 | Honest sample only (need multi-expiry / candle source) |

## Data & Infra

| Item | Status | Notes |
|---|---|---|
| Historical download + time-remaining + safety monitor | ✅ | `HistoricalDownloadPanel` (ETA, free-disk, refused/aborted) |
| Native tick capture to storage | 🟡 | Unavailable pending a native stream source. Retained local tick storage and processing remain available; an environment flag does not enable capture. |
| Daily DB optimise + tick retention | ✅ | Nightly cron (CHECKPOINT/ANALYZE + prune); scheduler started |
| Per-broker customisable API rate limits | ✅ | Config + live-apply UI |
| Live order-flow footprint | ✅ | Aggregator fed from the tick stream (Lee-Ready side classification); honest synthetic fallback |
| Latency observability (per-broker p50/p95/p99) | ✅ | In-memory `LatencyTracker` fed by the live order path → `/api/v1/latency/stats` → MonitoringSection `LatencyPanel` + ObservabilityDashboard; regression-tested |
| Gated-order-path latency benchmark | ✅ | Tripwire test measures `gate_order → BrokerRouter` overhead against a mocked broker (real measured ms, generous ceiling) |
| Persisted DuckDB latency store (histogram + slowest-N) | 🟡 | `LatencyMonitor` built + unit-tested, admin endpoints dev-only; not yet fed by the production order path |

## System Components

| Item | Status | Notes |
|---|---|---|
| Profile Manager (in unified settings, quick-settings + profile button) | ✅ | `ProfileSection`; both entry points tested |
| Notification System (central manager, drives action) | ✅ | NotificationCentre + dispatchers + remediation actions + e2e test |
| Unified Settings | ✅ | `SettingsRoute`, 19 sections, deep-linkable |

## Automation & Multi-Account

| Item | Status | Notes |
|---|---|---|
| Automate pillar (webhooks / schedules / monitors / Telegram) | ✅ | Automation (`/automation`; a bookmark of `/automate` opens it) → run control (generic HMAC-signed custom webhooks, scheduler, kill-switch indicator), backed by the webhooks + automation packages |
| Native copy trading | Unavailable | Account metadata is retained; mirroring, risk execution and linking remain unavailable pending a native safety design. |
| Invest & Learn routes | ✅ | Portfolio (`/portfolio`; a bookmark of `/invest` opens it and keeps the hash) and `/learn` (guided learning) |

## Known backlog (built-but-unreachable / referenced-not-built / blocked)

| Item | Status | Notes |
|---|---|---|
| SmartOrderRouter (liquidity-aware TWAP slicing) | ✅ | Wired end-to-end: `POST /api/v1/orders/smart-route` (background job + live polling) → every child order independently traverses SafetySystem → `gate_order` → `BrokerRouter` via `GatedChildExecutor`; "Smart Order" terminal widget; OFF by default (`brokers.smart_routing.enabled`), live-mode only |
| Analytics endpoints: VWAP bands / pairs / MTF | ✅ | Compute endpoints built + tested **and now reached by their widgets** — live intraday/daily bars via `getHistory`, honest sample fallback |
| Download-watchlist manager UI | ✅ | Settings → Data: list / add / remove the symbols the bulk downloader fetches (was previously API-only — fresh installs had no way to populate it) |
| Historical option-chain (`getHistoricalChain`/`getHistoricalExpiries`) | ✅ | "Historical Chain" widget — archived expiries → grouped CE/PE chain; honest empty state |
| Position sizing (Fixed % / Kelly / ATR) | ✅ | `PositionSizingWidget` computes all three methods correctly client-side (no backend round-trip — pure calculator, keeps latency low). The `calculatePositionSize` API client is for external callers, not a gap |
| Stock / fundamentals screener | ✅ | `StocksTab` (Invest route) → `useStockScan` → `/v1/stocks/scan`; curated large-cap fundamentals (disclosed as a fixed point-in-time snapshot). The separate `/screener/fundamental/*` clients are a dead duplicate (no consumers) |
| Credential rotation (`rotation/status|schedule|rotate-now`) | ✅ | **Mounted (Phase 1 G5)** behind the G9 operator-session write guard. `CredentialsRotator` runs over `flinttrade_core.native_rotation.NativeSessionRefresher` — a real per-selector `refresh_token` hook (Dhan renew-in-place via `RenewToken`, vault-credential replay for the rest, raises on failure so `rotate-now` reports honestly). Active registered native adapters get the daily 08:05 IST refresh job (armed on the serve path); coming-soon selectors (Groww, INDmoney, and Delta Exchange) and any selector without a published connected session do not schedule false refresh work. |
| Native-SDK **order execution** (R13/R14) | 🟡 | Dhan and Upstox SDK-backed native paths plus INDmoney, Kotak Neo, Groww, and Delta Exchange native writes are mapped and gated. Kotak Neo is catalogue-connectable for Connected (read) / API smoke only (runtime `kotakneoapi` 3.0.9; release baseline 3.0.9 at `0ba71b7f7c295652d4c3ea2b5ce5a88849db18a3`). Earlier read-smoke evidence remains historical, not validation of this selected SDK revision; funded Live place stays fail-closed. INDmoney, Groww, and Delta Exchange remain not connectable. INDmoney's fail-closed emergency planner is locally verified, but restart-time regular/smart-parent discrimination, a broker-atomic reduce-only close primitive, and funded/live-market order-safety proof remain. Groww now has approved-key login/account-read proof but still needs market-data/API permission, static-IP, and order-safety proof before promotion. Delta Exchange remains disabled until Live order safety and unattended deadman flattening are proven, and its configured authentication method uses an API key and secret for one venue (India or Global, production or testnet). Funded live order placement remains unproven until market/funds conditions allow a live broker write probe. |
| Overscoped / dead frontend clients | — | Admin user-CRUD (single-principal app → out of scope), QuestDB browser-REST, OTP pair — removal candidates |

---

_Maintained as part of the usability campaign. When you build, wire, or test one
of the 🟡 / ⛔ items, move it to ✅ here in the same change._