Example: mapPayloadToUnified and CSV-first workflows

Warning: normalization is not analysis

[mapPayloadToUnified] only normalizes known subtrees of a raw integration object (for example backtestResult, walkForwardAnalysis periods). It applies decimal conversion and key alignment where implemented.

It does not:

• run analyze(), analyzeFromTrades(), or analyzeFromWindows(),
• compute rankings, p-values, or summaries,
• invent missing trades or curves.

If you need numbers, call an analysis entrypoint after you have valid inputs. See [ENTRYPOINTS.md].

When to use mapPayloadToUnified

• Raw JSON from an integration uses legacy or mixed keys (optimization_return vs optimizationReturn, walkForwardAnalysis vs wfaData, etc.).
• You want a single normalization pass before your own code calls window-based analysis or other builders.

Authoritative types: [UnifiedIntegrationPayload].

When not to use it

• You already have a Trade[] or a small JSON list of trades - use analyze() or analyzeFromTrades() directly.
• You only have CSV - use adapters (below) first, then analysis entrypoints.

CSV to trades (only external format in this guide)

From @kiploks/engine-adapters:

• csvToTrades(csvString, mapping) - whole file as a string in memory.
• csvToTradesFromStream(stream, mapping, options) - Node Readable stream; supports a maxTrades cap for large files (see [packages/adapters/README.md] and [csvToTrades.ts]).

Performance tip: For large CSVs, prefer csvToTradesFromStream; respect the row cap behavior documented in the adapter.

Then:

1. analyze({ trades }, config) for basic summary, or
2. build [TradeBasedWFAInput] and call analyzeFromTrades() for public WFA.

TypeScript sketch: mapPayloadToUnified

Exact field aliases are defined in [mapPayloadToUnified.ts]. Do not rely on undocumented keys.

See also

• [ENTRYPOINTS.md] - full entrypoint map.
• [examples/04-csv-to-trades.md] - CSV column mapping examples.
• [OPEN_CORE_INTEGRATION_PRINCIPLES.md] - why there is no runEverything().