[BUG] Financial ratios and KPIs appearing in wrong sections #23

New Issue

Francy51 · 2026-03-15T17:03:34Z

Francy51 commented

2026-03-15 17:03:34 +00:00

Description

Metrics that should be displayed in the Ratios or KPIs sections are appearing as unmapped items within the financial statement areas (income statement, balance sheet, cash flow).

Current Architecture

From lib/types.ts:422-429:

type FinancialSurfaceKind =
  | 'income_statement'
  | 'balance_sheet'
  | 'cash_flow_statement'
  | 'ratios'          // Should contain ratio metrics
  | 'segments_kpis'   // Should contain KPIs
  | 'adjusted'
  | 'custom_metrics';

Problem

Some ratio/KPI items with units like percent or ratio may be:

Incorrectly classified as financial statement rows
Not properly routed to the ratios/segments_kpis surfaces
Falling through to unmapped when they should be computed metrics

Examples of items that should be in Ratios/KPIs, not statements:

Gross Margin (gross_margin) - percent unit
Operating Margin (operating_margin) - percent unit
Effective Tax Rate (effective_tax_rate) - percent unit
EPS metrics (basic_eps, diluted_eps) - per-share unit
Share counts (weighted_average_shares) - count unit

Proposed Fix

Audit all template rows with unit: 'percent' or unit: 'ratio' to ensure they're categorized correctly
Add explicit routing logic in surface builder to separate computed ratios from statement rows
Create clearer separation between "statement rows" and "computed metrics" in the output

Files Affected

lib/server/financials/standard-template.ts
lib/server/financials/surface.ts
lib/server/financial-taxonomy.ts
lib/financial-metrics.ts

## Description Metrics that should be displayed in the Ratios or KPIs sections are appearing as unmapped items within the financial statement areas (income statement, balance sheet, cash flow). ## Current Architecture From `lib/types.ts:422-429`: ```typescript type FinancialSurfaceKind = | 'income_statement' | 'balance_sheet' | 'cash_flow_statement' | 'ratios' // Should contain ratio metrics | 'segments_kpis' // Should contain KPIs | 'adjusted' | 'custom_metrics'; ``` ## Problem Some ratio/KPI items with units like `percent` or `ratio` may be: 1. Incorrectly classified as financial statement rows 2. Not properly routed to the ratios/segments_kpis surfaces 3. Falling through to unmapped when they should be computed metrics ## Examples of items that should be in Ratios/KPIs, not statements: - Gross Margin (`gross_margin`) - percent unit - Operating Margin (`operating_margin`) - percent unit - Effective Tax Rate (`effective_tax_rate`) - percent unit - EPS metrics (`basic_eps`, `diluted_eps`) - per-share unit - Share counts (`weighted_average_shares`) - count unit ## Proposed Fix 1. Audit all template rows with `unit: 'percent'` or `unit: 'ratio'` to ensure they're categorized correctly 2. Add explicit routing logic in surface builder to separate computed ratios from statement rows 3. Create clearer separation between "statement rows" and "computed metrics" in the output ## Files Affected - `lib/server/financials/standard-template.ts` - `lib/server/financials/surface.ts` - `lib/server/financial-taxonomy.ts` - `lib/financial-metrics.ts`

Francy51 commented

2026-03-15 17:18:12 +00:00

Update: Root Cause Analysis

The Rust sidecar IS being used. The issue is in how KPIs and ratios are surfaced.

Current Architecture:

From rust/taxonomy/fiscal/v1/kpis/core.kpis.json - this file defines KPIs separately from the financial statement surfaces.

Problem:

Items with unit: "percent" or unit: "ratio" in core.surface.json are being displayed as financial statement rows instead of in the ratios/KPIs section
The surface_mapper.rs doesn't route items to the correct surface kind (ratios vs income_statement)
The TypeScript code has a FinancialSurfaceKind type that includes ratios and segments_kpis, but these may not be populated by the Rust mapper

Evidence:

Looking at lib/server/taxonomy/types.ts, the TaxonomyHydrationResult includes:

surface_rows - for statement surfaces (income, balance, cash_flow)
kpi_rows - for KPIs

But the Rust build_compact_surface_model in surface_mapper.rs only outputs to surface_rows and detail_rows, not a separate kpi_rows.

Fix Required:

Verify the Rust sidecar outputs KPIs to a separate kpi_rows field
Ensure core.surface.json doesn't include ratio/KPI items in statement surfaces
Move percent/ratio items to core.kpis.json or create a separate ratios surface
Update the Rust surface_mapper.rs to categorize by unit type

Files to Review:

rust/taxonomy/fiscal/v1/core.surface.json - Check for misplaced ratio items
rust/taxonomy/fiscal/v1/kpis/core.kpis.json - Verify KPI definitions
rust/fiscal-xbrl-core/src/surface_mapper.rs - Check KPI routing logic

## Update: Root Cause Analysis **The Rust sidecar IS being used.** The issue is in how KPIs and ratios are surfaced. ### Current Architecture: From `rust/taxonomy/fiscal/v1/kpis/core.kpis.json` - this file defines KPIs separately from the financial statement surfaces. ### Problem: 1. Items with `unit: "percent"` or `unit: "ratio"` in `core.surface.json` are being displayed as financial statement rows instead of in the ratios/KPIs section 2. The `surface_mapper.rs` doesn't route items to the correct surface kind (`ratios` vs `income_statement`) 3. The TypeScript code has a `FinancialSurfaceKind` type that includes `ratios` and `segments_kpis`, but these may not be populated by the Rust mapper ### Evidence: Looking at `lib/server/taxonomy/types.ts`, the `TaxonomyHydrationResult` includes: - `surface_rows` - for statement surfaces (income, balance, cash_flow) - `kpi_rows` - for KPIs But the Rust `build_compact_surface_model` in `surface_mapper.rs` only outputs to `surface_rows` and `detail_rows`, not a separate `kpi_rows`. ### Fix Required: 1. Verify the Rust sidecar outputs KPIs to a separate `kpi_rows` field 2. Ensure `core.surface.json` doesn't include ratio/KPI items in statement surfaces 3. Move percent/ratio items to `core.kpis.json` or create a separate ratios surface 4. Update the Rust `surface_mapper.rs` to categorize by unit type ### Files to Review: - `rust/taxonomy/fiscal/v1/core.surface.json` - Check for misplaced ratio items - `rust/taxonomy/fiscal/v1/kpis/core.kpis.json` - Verify KPI definitions - `rust/fiscal-xbrl-core/src/surface_mapper.rs` - Check KPI routing logic

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Francy51/Neon-Desk#23