Skip to Content

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

Source: trajectonomics/sim-core.