sim-core
The deterministic personal-finance projection engine, published as @trajectonomics/sim.
sim-core is a pure, deterministic personal-finance projection engine, published as
@trajectonomics/sim. The latest release is
v0.1.0.
Install
bun add @trajectonomics/sim npm install @trajectonomics/sim works too. Alpha builds are published under the alpha dist-tag.
What it does
Give project() three values and it returns a Projection:
- a Baseline: the balance of each Account on the start date;
- a Scenario: the accounts, the Flows that move money and the cashflow routing;
- a Timeline: the start date, the horizon, and whether rows are daily or monthly.
import type { Baseline, Scenario, Timeline } from "@trajectonomics/sim"
import { project } from "@trajectonomics/sim"
const baseline: Baseline = {
schemaVersion: 1,
balances: [
{ account: "cash", amount: 25_000_000 },
{ account: "retirement", amount: 120_000_000 },
],
}
const scenario: Scenario = {
schemaVersion: 1,
currency: "THB",
economy: { inflation: 300 },
accounts: [
{ id: "cash", kind: "asset", rate: 150 },
{ id: "retirement", kind: "asset", rate: 500, lockedUntil: "2051-01-01" },
],
flows: [
{
id: "salary",
kind: "income",
earned: true,
amount: 8_000_000,
frequency: "monthly",
start: "2026-01-01",
growth: "inflation",
},
{
id: "living",
kind: "expense",
amount: 4_500_000,
frequency: "monthly",
start: "2026-01-01",
growth: "inflation",
},
{
id: "retirement-saving",
kind: "contribution",
target: "retirement",
amount: 1_500_000,
frequency: "monthly",
start: "2026-01-01",
end: "2051-01-01",
growth: "inflation",
},
],
cashflow: { surplus: [{ account: "cash" }], withdraw: ["cash"] },
}
const timeline: Timeline = { start: "2026-01-01", horizon: "2056-01-01", resolution: "month" }
const result = project(baseline, scenario, timeline)
if (!result.ok) {
console.error(result.problems)
} else {
const { rows, runsOut } = result.projection
const last = rows.at(-1)
console.log(`${rows.length} rows, net worth at the horizon (satang):`, last?.netWorth)
console.log(runsOut === undefined ? "the money lasts" : `runs out on ${runsOut.date}`)
} The page documents v0.1.0 of @trajectonomics/sim. The CLI pins its own @trajectonomics/sim,
which can be newer, so traj scenario apply may accept a later schemaVersion and can carry Levies
and Financial Independence this release does not; run traj scenario apply --template for the
document the installed CLI accepts. A Baseline for traj comes from the ledger:
traj baseline show --as-of 2026-01-01 derives it, so read it rather than writing one.
A Projection has one row per date in the Timeline, annual roll-ups, and the Runs-out date with the
unmet amount if the money does not last. project() never throws on a valid input, and it never
reads a clock.
Main concepts
- Baseline, Scenario, Timeline: the three inputs. The Scenario is self-contained; build a variant by copying and editing it.
- Flow: a dated cash movement of kind income, expense or contribution. A contribution moves money into an Account and is not an expense.
- Shortfall: money owed on an Occurrence that no unlocked Account can supply. Expenses are never refused; the Projection ends on that date.
- Runs-out date: the date of the first Shortfall, recorded with the unmet amount. Absent when the money lasts to the horizon.
check() reports input problems as { code, path }[] without projecting. project() runs it
first and returns the same problems when the input is invalid.
Boundaries
Amounts are integer minor units in one currency per Scenario, dates are YYYY-MM-DD, and rates are
integer basis points. All growth is exact integer arithmetic, so a Projection is identical across
runtimes. The engine has no I/O, no callbacks and no extension points: a rule that does not fit the
Flow vocabulary is a new core primitive, not a plugin.
Decisions
- ADR 0001: exact integer compounding with lazy per-account commits
- ADR 0002: tax is a generic Levy computed from data, not code that knows tax
Source: trajectonomics/sim-core.