@bearingau/engine

The opinionated Australian household capital-allocation engine. Pure TypeScript, zero runtime dependencies, 442 tests.

You feed it your profile, debts, cash, holdings, super, spending, and market data. It returns a ranked list of actions — each with a tier, conviction, reasoning, execution date, and the alternatives it considered and skipped.

import { runAllocation, DEFAULT_POLICY_FY25_26 } from '@bearingau/engine';

const result = runAllocation({
  user, debts, cash, holdings, superAccount,
  spending, macro, tickers,
  policy: DEFAULT_POLICY_FY25_26,
  currentDate: '2026-04-16',
});

for (const action of result.recommendations) {
  console.log(`[${action.tier}] ${action.title} — $${action.amount} (${action.conviction} conviction)`);
  console.log(`  Why: ${action.reasoning}`);
  console.log(`  Execute: ${action.suggestedActionDate}`);
}

Why this exists

Most personal-finance tools are either calculators (what's my take-home pay?) or trackers (where did my money go?). Neither answers the question an Australian household actually faces every payday: given everything I owe, own, and expect — what's the best thing to do with this surplus right now?

This engine answers that. It reasons about debt paydown vs. equity investment vs. concessional super vs. voluntary HELP vs. holding cash, using the ATO tax tables, HELP indexation schedule, super contribution caps, franking credits, the CGT 12-month discount, Medicare Levy Surcharge tiers, Division 293, and pay-date timing. It treats a guaranteed 6.25% car-loan paydown as worth 1.4× a forecasted 6.25% equity return — because one is certain and the other isn't.

Install

npm install @bearingau/engine

No peer dependencies. Works in Node, Deno, Bun, and any bundler. The library ships ESM only.

Core primitives

| Symbol | What it does | |---|---| | runAllocation(input) | The headline function. Takes the household snapshot + policy, returns a ranked list of actions plus a narrative. | | DEFAULT_POLICY_FY25_26 | Opinionated default PolicyConfig for an AU household, wired to current ATO tax tables, HELP thresholds, and Super caps. Override what you need. | | calculateEmergencyFundStatus() | Deterministic floor check. Below 50% funded, the allocator refuses to recommend any discretionary investing. | | calculateIncomeTax() / calculateHelpRepayment() / calculateMarginalRate() | Stand-alone AU tax primitives, bring your own brackets or use the defaults. | | compareStrategies() | A/B test two allocation policies side-by-side on the same household state. | | projectNetWorth() / modelDebtCascade() | Long-horizon scenario modelling. |

Around 150 functions covering debt, super, portfolio, life events, life stages, tax edge cases (Div 293, FHSSS, Age Pension impact, negative gearing), cashflow realism, and data integrity.

Design principles

• Pure functions. No React, no DOM, no fetch, no file IO. Data in, data out.
• Tier-based, not score-based. Actions are labelled strong-buy / buy / hold / consider. Scores are auditable inputs, not user-facing outputs.
• Guaranteed returns get a 1.4× premium over uncertain forecasts. This is configurable, and it's why the allocator reliably picks debt paydown over equity when the rates are close.
• Emergency fund is a hard gate. Below 50% of target, the engine stops recommending discretionary investing. No opt-out.
• Pay-date aware. Every recommendation includes a suggested execution date aligned with your pay cadence. No "invest $X monthly" without saying when.
• Australian-first, not Australian-only. Defaults target ATO FY2025–26. Replace policy.taxBrackets, policy.helpRepaymentThresholds, and related fields to model other jurisdictions.

Policy configuration

PolicyConfig is the knob panel. It carries schemaVersion: '1' so persisted configs can migrate forward safely. Everything is a named field — no magic strings.

import type { PolicyConfig } from '@bearingau/engine';
import { DEFAULT_POLICY_FY25_26 } from '@bearingau/engine';

const conservative: PolicyConfig = {
  ...DEFAULT_POLICY_FY25_26,
  baseRiskPosture: 'defensive',
  guaranteedReturnPremium: 1.6,   // weight certainty even more heavily
  emergencyFundTarget: 6,          // 6 months instead of 3
  debtPriorityMethod: 'smallest-balance',  // snowball instead of avalanche
};

What this library is not

• Not a fetcher. Bring your own market data. Yahoo, FRED, Up Bank adapters live in the reference app, not here.
• Not a broker. No executions. Advisory only.
• Not a tax accountant. Heuristics approximate ATO rules; they are not a substitute for professional advice.
• Not financial advice. MIT licensed. No warranty, express or implied.

Stability

v0.1.x is source-stable. The public API surface is enumerated in src/index.ts. Any symbol not in that barrel is engine-internal and may move without a version bump. Breaking changes land on minor bumps until 1.0.0; thereafter, semver.

• docs/ADOPTING-THE-ENGINE.md — 5-minute practical guide for evaluating and integrating the library.
• docs/ENGINE-API.md — curated job-oriented reference of the headline functions.

See CHANGELOG.md for the full revision history.

Reference implementation

A complete Vite + React + Ant Design app consuming this engine lives at:

github.com/RyanJames042/PersonalCFO

It demonstrates localStorage persistence, CSV/PDF/OCR ingestion, Up Bank + Yahoo Finance + FRED integration, and real-time policy editing. Fork it, or build your own.

License

MIT. See LICENSE.