A model is a named plan: lines organised in sections, laid over time, with the context that says how to read them. Every line holds one value per period of its timeline, and the engine computes the whole model in dependency order.
Timelines and grains
A model carries up to three dated timelines, called grains: monthly, quarterly and yearly. A fourth one, constant, is always there: a constant line holds a single value, valid for every period (a tax rate, a headcount target, a price).
- All dated timelines share one horizon, snapped to whole months. A yearly period is a calendar year and needs its December inside the horizon.
- A line runs at the grain of its
timeline_ref. A formula with no explicit grain runs at the finest grain of the model (monthly before quarterly before yearly). - A model can carry several grains at once: a monthly operating plan read as yearly totals, a yearly long-range plan next to a monthly cash plan.
Moving between grains
When a line reads another line at a different grain, the value is projected. How it folds depends on what the line measures, its aggregation:
| Aggregation | Fine to coarse (month to year) | Coarse to fine (year to month) | Typical lines |
|---|---|---|---|
sum (a flow) | Sum of the months | Split across the months | Revenue, costs, cash flows |
stock (a level) | The closing month | Lands on the last month | Cash, debt, ARR, headcount |
average (a rate) | Recomputed or averaged | Repeated as is | Margins, growth, churn, tax rate |
first | The opening month | An opening balance in a yearly table |
Layerz infers the right one in most cases: a balance is a stock, a formula that copies or adds stocks is a stock, a stock times a rate is a flow. Set aggregation only to override, for example average on a churn rate typed yearly so that 10% a year does not become 0.83% a month.
Periods and labels
Periods are labelled YYYY (yearly), YYYY-Qn (quarterly) and YYYY-MM (monthly). The same labels key a one-cell edit, a KPI's target period and the values returned by the API and the MCP tools.
The actuals cutover
A model that receives real figures has a cutover: the last closed period, actuals_through. Periods up to it are actuals, periods after it are forecast. The cutover moves by itself when a source brings a new month, can be pinned on the model or per scenario, and is read inside formulas with IS_ACTUAL:
Revenue = IF(IS_ACTUAL, Revenue booked, Customers * Price)
The model's context
Each model carries a FINANCE.md: its currency, its units (thousands, millions), its sign convention, its glossary and the structure of its statements. Every value the API and the MCP tools return is expressed in those conventions: 12000 is 12k EUR in one model and 12M USD in another.