Formulon

English

日本語

English

日本語

Appearance

Architecture ​

Formulon is organized around a single calculation core with thin packaging layers. Every host surface — WASM, Native Node, Python, CLI, MCP, formulon-cell — uses the same C++17 core through the C ABI.

Glossary: C ABI layer

A flat C function interface that exposes the workbook model, evaluator, and IO to non-C++ hosts. It is the compatibility boundary; bindings call into it, but only the core implements it. See Bindings.

Glossary: workbook model

The in-memory representation of an opened workbook — sheets, cells, styles, defined names, tables, dependency graph, dirty set, profile binding, and the workbook-level engine state needed to recalculate. Bindings hold a handle to the model, never the underlying bytes after parsing.

HostBoundaryCoreEvaluation & IOVerificationHost APIJS · Python · CLI · MCP · cell UIC ABI / binding layerLifetimes and value translationC++17 workbook modelSheets, cells, dependency graphParser and evaluatorFunction catalog, treewalkerFile readers and writersOOXML, XLSB, passthroughOracle and parity testsExcel values, cross-surface agreementHostBoundaryCoreEvaluation & IOVerificationHost APIJS · Python · CLI · MCP · cell UIC ABI / binding layerLifetimes and value translationC++17 workbook modelSheets, cells, dependency graphParser and evaluatorFunction catalog, tree walkerFile readers and writersOOXML, XLSB, passthroughOracle and parity testsExcel values, cross-surface agreement
Every host surface reaches the same C++17 core through the C ABI; bindings translate values and lifetimes, never calculation.

What lives where ​

LayerOwns
Host APILanguage-specific surface (JS / Python / CLI / MCP tools / cell UI)
C ABI / bindingLifetime management, host value ↔ engine value translation
Workbook modelSheets, cells, styles, dependency graph, dirty state, profile
Parser / evaluatorFunction catalog, tree-walker evaluator, error propagation
File format layerOOXML, XLSB readers and writers, passthrough preservation
Oracle / parity testsCaptured Excel values, cross-surface agreement

The core owns workbook state, formula semantics, file parsing, dependency tracking, and recalculation. Bindings should translate host values and lifetime management without changing calculation behavior.

The tree-walker is the only evaluator in release, developer, and test builds. All host surfaces use it through the same core.

Why the split ​

  • Shared semantics: the shared core provides the same calculation semantics when profile, input, clock, and RNG configuration match.
  • Embedding: the core has no Node, Python, or browser assumptions, so the same C++ source can be built for all three.
  • Testing: oracle tests verify calculation behavior in the shared engine; package tests separately verify binding translation and lifetime management.
  • C++ core — internal conventions of the calculation core.
  • Bindings — responsibilities and non-responsibilities.
  • Build from source — how the artifacts are produced.