# 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`](https://www.npmjs.com/package/@trajectonomics/sim). The latest release is
`v0.1.0`.

## Install

```bash
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.

```ts
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](https://github.com/trajectonomics/sim-core/blob/v0.1.0/docs/adr/0001-exact-integer-compounding.md)
- [ADR 0002: tax is a generic Levy computed from data, not code that knows tax](https://github.com/trajectonomics/sim-core/blob/v0.1.0/docs/adr/0002-levies-as-data-not-tax-code.md)

Source: [`trajectonomics/sim-core`](https://github.com/trajectonomics/sim-core).

Part of the [Docs index](https://trajectonomics.com/docs/llms.txt).
