Canonical numbers

Investi computes every number once, on the server, with one engine. The web app, the REST API, the Claude MCP connector, the Chrome extension and the desktop app are all views of that result. If two surfaces ever disagreed, one of them would be wrong, so none of them is allowed to calculate on its own.

One engine, many surfaces#

All calculation lives in packages/core, a pure TypeScript package with no network or database access: the ledger, indicators, the policy evaluator, risk, performance, importers and the report schema. The web server in apps/web gathers inputs (your records from the database, market data, SEC filings), calls the engine, and serves the result.

The language model that can explain a report is not on this list. It receives a finished report and writes prose about it. It never produces a number that a surface displays as a result.

The company report#

The research page, the report endpoint (GET /api/v1/securities/{ticker}/report) and the MCP verdict tool all return one structure, the canonical company report, defined with a strict schema in packages/core/src/report.ts. The report is validated against that schema every time it is built, so a malformed report fails loudly instead of rendering partially.

Every report carries a schemaVersion string. Changing the shape requires a new version, so a client can tell exactly which fields to expect. The schema started as report.v1; the engine now emits report.v2, which added the framework fields (FLAGGED verdicts, manual rows, sizing, exit target, the 7-day estimate and the market regime).

Each report has a reportId built from the stored evaluation id and its input fingerprint. When a new evaluation revision is saved, its report is stored alongside it, so you can see the exact object any surface was shown at the time.

The P/L breakdown#

Total P/L is never one bare number. Every surface shows the same breakdown, built by one function (pnlBreakdown in packages/core/src/pnl.ts) and served as pnl on the portfolio: Home (under the cumulative curve), Analytics, Portfolio, GET /api/v1/portfolio, and the MCP tools get_positions and evaluate_strategy_health.

What the net leaves out is listed beside it, never hidden:

• Legacy sales, basis unknown (legacy): shares sold that were bought before your history starts. Their proceeds are shown, for example "proceeds $X excluded", and they are never treated as zero cost or as a loss. See The ledger.
• Before your history (beforeCoverage): dividends, interest and fees dated before your first fill. They belong to holdings the imported fills do not cover.
• Unclassified cash (otherCash): cash Investi could not classify, such as cash-merger proceeds.
• No quote (unpriced): positions whose unrealized P/L is missing because no quote arrived.

The cumulative P/L curve on Home and Analytics follows the same rules, so its last point equals net apart from one difference: the curve marks positions to daily closes on the basis rebuilt from your fills, while unrealized uses live quotes on the broker's basis.

Performance#

The performance line on Analytics and in evaluate_strategy_health answers a different question: how much did the account grow, net of the money you put in or took out?

• Daily equity is rebuilt backwards from the latest broker balance (cash minus margin debit) and positions: each later fill and cash transaction is undone, and shares are marked to that day's close. No cost basis is needed, so holdings bought before your history are valued correctly until the day they are sold. Shares that left the account without a recorded sale (a cash merger, a transfer out) are valued at zero and listed in gaps.
• Gain net of flows = ending equity minus starting equity minus deposits and withdrawals. Starting equity is the close before your first fill.
• Time-weighted return is a daily TWR: each day's return is equity divided by the previous day's equity plus that day's deposits and withdrawals, chain-linked. Modified Dietz over the whole period is given as a cross-check.
• Benchmarks: RSP (the equal-weight S&P 500) and your chosen benchmark over the same dates, as price returns (dividends not included), plus each one's dollar gain had your starting equity and every deposit and withdrawal gone into it at that day's close.

It needs a broker balance for every synced or imported account (a Schwab connection or a positions export).

Money rounding#

Money arithmetic is defined in packages/core/src/money.ts and shared by every calculation.

• Rounding mode: half away from zero, to the cent. A small relative nudge corrects binary floating point artifacts, so 1.005 rounds to 1.01 and -2.345 rounds to -2.35, as a person would expect.
• Realized P/L: for each lot match, cost and proceeds are rounded to cents separately, and realized is proceeds minus cost, the way a broker statement settles. See The ledger.
• Totals: sums of money (realized P/L, fees, notional, open cost) are added in integer cents, so adding many values never drifts by a fraction of a cent.
• Quantities: shares keep up to 6 decimal places, enough for fractional shares. A quantity smaller than 0.0000001 in absolute value counts as zero, so a position closed in fractional pieces reads as flat rather than as a leftover sliver.
• Display: negative amounts always carry a minus sign in the text, for example -$361.00, so sign never depends on color alone. Missing values show as a dash, never as zero.

Percentages are stored as fractions (0.0525 means 5.25%) and formatted only at display time.

Why it matters#

• A realized P/L figure you read in Claude is the same figure the History page shows, to the cent.
• A verdict in the extension's hover card is the latest stored evaluation for that security (or your override, marked as overridden with the computed verdict kept alongside), not a lighter recalculation.
• When you change the lot method in Settings, every surface switches at once, because the method is a server setting the engine reads.
• When the policy changes, the policy version tag changes on every surface at the same time. See Verdicts and policy.