@trajectonomics/sim 0.0.0-stage → 0.1.0-alpha.1

package/dist/index.mjs

@@ -0,0 +1,1238 @@
+// src/vocab.ts
+const ACCOUNT_KINDS = ["asset", "liability"];
+const FLOW_KINDS = [
+	"income",
+	"expense",
+	"contribution"
+];
+const FREQUENCIES = [
+	"once",
+	"daily",
+	"weekly",
+	"biweekly",
+	"monthly",
+	"quarterly",
+	"annual"
+];
+const RESOLUTIONS = ["day", "month"];
+// src/check/date.ts
+const DATE_SHAPE$1 = /^(\d{4})-(\d{2})-(\d{2})$/;
+const MONTH_DAYS$1 = [
+	31,
+	28,
+	31,
+	30,
+	31,
+	30,
+	31,
+	31,
+	30,
+	31,
+	30,
+	31
+];
+function isLeapYear$1(year) {
+	return year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
+}
+function daysInMonth$1(year, month) {
+	return month === 2 && isLeapYear$1(year) ? 29 : MONTH_DAYS$1[month - 1] ?? 0;
+}
+/** Pure calendar arithmetic (no `Date`): a real `YYYY-MM-DD` date in years 0001-9998 (so every computed anniversary stays representable). */
+function isValidDate(value) {
+	if (typeof value !== "string") return false;
+	const match = DATE_SHAPE$1.exec(value);
+	if (!match) return false;
+	const [year, month, day] = [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+	return year >= 1 && year <= 9998 && day >= 1 && day <= daysInMonth$1(year, month);
+}
+// src/check/shape.ts
+const req = (check) => ({
+	required: true,
+	check
+});
+const opt = (check) => ({
+	required: false,
+	check
+});
+/** Accepts any value: `schemaVersion` is validated up front by `check()`, not per object. */
+const anyVersion = () => {};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function checkField(value, path, key, field, emit) {
+	if (Object.hasOwn(value, key)) field.check(value[key], [...path, key], emit);
+	else if (field.required) emit("MISSING_KEY", [...path, key]);
+}
+/** Validates an object against `shape`: not-an-object, unknown keys, missing keys, field checks. */
+function checkShape(value, path, shape, emit) {
+	if (!isRecord(value)) {
+		emit("NOT_AN_OBJECT", path);
+		return;
+	}
+	for (const key of Object.keys(value)) if (!Object.hasOwn(shape, key)) emit("UNKNOWN_KEY", [...path, key]);
+	for (const [key, field] of Object.entries(shape)) checkField(value, path, key, field, emit);
+	return value;
+}
+/**
+* Builds a check that validates every element of an array with `item`. Walks every index, so a
+* sparse-array hole reaches `item` as `undefined` instead of being skipped.
+*/
+function list(item) {
+	return (value, path, emit) => {
+		if (!Array.isArray(value)) return emit("NOT_AN_ARRAY", path);
+		for (let index = 0; index < value.length; index++) item(value[index], [...path, index], emit);
+	};
+}
+function scanDuplicates(items, path, suffix, idOf, emit) {
+	if (!Array.isArray(items)) return;
+	const seen = /* @__PURE__ */ new Set();
+	for (let index = 0; index < items.length; index++) {
+		const id = idOf(items[index]);
+		if (typeof id !== "string" || id === "") continue;
+		if (seen.has(id)) emit("DUPLICATE_ID", [
+			...path,
+			index,
+			...suffix
+		]);
+		seen.add(id);
+	}
+}
+/**
+* Emits `DUPLICATE_ID` at the second and later occurrences of a string `key` in `items`.
+* Empty ids are left to `EMPTY_STRING` and never count as duplicates.
+*/
+function checkUnique(items, path, key, emit) {
+	scanDuplicates(items, path, [key], (item) => isRecord(item) ? item[key] : void 0, emit);
+}
+/** Like `checkUnique`, for an array of plain string ids (e.g. `cashflow.withdraw`). */
+function checkUniqueValues(items, path, emit) {
+	scanDuplicates(items, path, [], (item) => item, emit);
+}
+// src/check/scalars.ts
+const str = (value, path, emit) => {
+	if (typeof value !== "string") emit("WRONG_TYPE", path);
+	else if (value === "") emit("EMPTY_STRING", path);
+};
+const bool = (value, path, emit) => {
+	if (typeof value !== "boolean") emit("WRONG_TYPE", path);
+};
+/** A safe-integer rate above -10000 bps, so a positive growth factor always exists. */
+const rate = (value, path, emit) => {
+	if (!Number.isSafeInteger(value)) return emit("NOT_SAFE_INTEGER", path);
+	if (value <= -1e4) emit("RATE_OUT_OF_RANGE", path);
+};
+/** Non-negative safe integer minor units. */
+const amount = (value, path, emit) => {
+	if (!Number.isSafeInteger(value)) emit("NOT_SAFE_INTEGER", path);
+	else if (value < 0) emit("NEGATIVE_AMOUNT", path);
+};
+const date = (value, path, emit) => {
+	if (!isValidDate(value)) emit("INVALID_DATE", path);
+};
+function oneOf(allowed, code) {
+	return (value, path, emit) => {
+		if (typeof value !== "string" || !allowed.includes(value)) emit(code, path);
+	};
+}
+const growth = (value, path, emit) => {
+	if (value === "inflation") return;
+	if (!isRecord(value)) return emit("INVALID_GROWTH", path);
+	checkShape(value, path, { bps: req(rate) }, emit);
+};
+// src/check/accounts.ts
+const shape$1 = {
+	id: req(str),
+	kind: req(oneOf(ACCOUNT_KINDS, "INVALID_KIND")),
+	rate: req(rate),
+	lockedUntil: opt(date)
+};
+const account = (value, path, emit) => {
+	const checked = checkShape(value, path, shape$1, emit);
+	if (checked?.["kind"] === "liability" && Object.hasOwn(checked, "lockedUntil")) emit("LIABILITY_MISUSE", [...path, "lockedUntil"]);
+};
+function checkAccounts(value, path, emit) {
+	list(account)(value, path, emit);
+	checkUnique(value, path, "id", emit);
+}
+/**
+* Declared account ids (first declaration wins) mapped to their raw `kind`. `undefined` when
+* `accounts` is not an array, so reference checks are skipped rather than flooding the output.
+*/
+function indexAccounts(accounts) {
+	if (!Array.isArray(accounts)) return void 0;
+	const index = /* @__PURE__ */ new Map();
+	for (let i = 0; i < accounts.length; i++) {
+		const item = accounts[i];
+		if (isRecord(item) && typeof item["id"] === "string" && !index.has(item["id"])) index.set(item["id"], item["kind"]);
+	}
+	return index;
+}
+// src/check/refs.ts
+/** Account id that must be declared in `scenario.accounts` (skipped when unknown). */
+function accountRef(accounts) {
+	return (value, path, emit) => {
+		str(value, path, emit);
+		if (accounts && typeof value === "string" && !accounts.has(value)) emit("UNKNOWN_ACCOUNT", path);
+	};
+}
+/** Like `accountRef`, but liabilities are rejected (surplus targets and withdrawal sources). */
+function spendableRef(accounts) {
+	const ref = accountRef(accounts);
+	return (value, path, emit) => {
+		ref(value, path, emit);
+		if (typeof value === "string" && accounts?.get(value) === "liability") emit("LIABILITY_MISUSE", path);
+	};
+}
+/** Baseline balance account: must have a rule in `scenario.accounts`. */
+function balanceRef(accounts) {
+	return (value, path, emit) => {
+		str(value, path, emit);
+		if (accounts && typeof value === "string" && !accounts.has(value)) emit("UNDECLARED_BALANCE_ACCOUNT", path);
+	};
+}
+// src/check/baseline.ts
+function checkBaseline(value, path, accounts, emit) {
+	const balance = (item, at, e) => void checkShape(item, at, {
+		account: req(balanceRef(accounts)),
+		amount: req(amount)
+	}, e);
+	checkUnique(checkShape(value, path, {
+		schemaVersion: req(anyVersion),
+		balances: req(list(balance))
+	}, emit)?.["balances"], [...path, "balances"], "account", emit);
+}
+// src/check/guard.ts
+/**
+* Runs `run`, turning an exception (a throwing getter, a revoked Proxy) into one `NOT_AN_OBJECT`
+* problem at the input's root, reported at most once per root. Returns `fallback` on failure.
+*
+* It deliberately catches EVERY exception, not only input-access ones: `check()` must never throw
+* on garbage input. The trade-off is that a genuine bug in a check surfaces as `NOT_AN_OBJECT` on
+* that input instead of crashing; the tests (not this guard) are what expose such bugs.
+*/
+function makeGuard(emit) {
+	const failed = /* @__PURE__ */ new Set();
+	return (root, fallback, run) => {
+		try {
+			return run();
+		} catch {
+			if (!failed.has(root)) emit("NOT_AN_OBJECT", [root]);
+			failed.add(root);
+			return fallback;
+		}
+	};
+}
+// src/check/cashflow.ts
+function checkRouting(cashflow, path, emit) {
+	const surplus = cashflow["surplus"];
+	if (!Array.isArray(surplus)) return;
+	if (surplus.length === 0) {
+		emit("SURPLUS_UNROUTED", [...path, "surplus"]);
+		return;
+	}
+	const last = surplus[surplus.length - 1];
+	if (isRecord(last) && Object.hasOwn(last, "upTo")) emit("SURPLUS_UNROUTED", [
+		...path,
+		"surplus",
+		surplus.length - 1,
+		"upTo"
+	]);
+}
+function checkCashflow(value, path, accounts, emit) {
+	const account = spendableRef(accounts);
+	const step = (item, at, e) => void checkShape(item, at, {
+		account: req(account),
+		upTo: opt(amount)
+	}, e);
+	const cashflow = checkShape(value, path, {
+		surplus: req(list(step)),
+		withdraw: req(list(account))
+	}, emit);
+	if (cashflow) checkRouting(cashflow, path, emit);
+	checkUnique(cashflow?.["surplus"], [...path, "surplus"], "account", emit);
+	checkUniqueValues(cashflow?.["withdraw"], [...path, "withdraw"], emit);
+}
+// src/check/flow-shape.ts
+const base = {
+	id: req(str),
+	kind: req(oneOf(FLOW_KINDS, "INVALID_KIND")),
+	amount: req(amount),
+	frequency: req(oneOf(FREQUENCIES, "INVALID_FREQUENCY")),
+	start: req(date),
+	end: opt(date),
+	growth: req(growth)
+};
+/** Keys allowed per flow kind; an invalid kind accepts every optional kind-specific key. */
+function flowShape(kind, accounts) {
+	const target = accountRef(accounts);
+	if (kind === "income") return {
+		...base,
+		earned: req(bool)
+	};
+	if (kind === "contribution") return {
+		...base,
+		target: req(target)
+	};
+	if (kind === "expense") return base;
+	return {
+		...base,
+		earned: opt(bool),
+		target: opt(target)
+	};
+}
+// src/check/flows.ts
+/** ISO dates compare correctly as strings once validated. */
+function checkDates(flow, path, emit) {
+	const { start, end, frequency } = flow;
+	if (!isValidDate(start) || !isValidDate(end)) return;
+	if (end < start) emit("END_BEFORE_START", [...path, "end"]);
+	else if (frequency === "once" && end !== start) emit("ONCE_FLOW_END_MISMATCH", [...path, "end"]);
+}
+function flowCheck(accounts) {
+	return (value, path, emit) => {
+		const flow = checkShape(value, path, flowShape(isRecord(value) ? value["kind"] : void 0, accounts), emit);
+		if (flow) checkDates(flow, path, emit);
+	};
+}
+function checkFlows(value, path, accounts, emit) {
+	list(flowCheck(accounts))(value, path, emit);
+	checkUnique(value, path, "id", emit);
+}
+// src/check/scenario.ts
+const economy = (value, path, emit) => {
+	checkShape(value, path, { inflation: req(rate) }, emit);
+};
+function checkScenario(value, path, accounts, emit) {
+	checkShape(value, path, {
+		schemaVersion: req(anyVersion),
+		currency: req(str),
+		economy: req(economy),
+		accounts: req(checkAccounts),
+		flows: req((v, p, e) => checkFlows(v, p, accounts, e)),
+		cashflow: req((v, p, e) => checkCashflow(v, p, accounts, e))
+	}, emit);
+}
+// src/check/timeline.ts
+const shape = {
+	start: req(date),
+	horizon: req(date),
+	resolution: req(oneOf(RESOLUTIONS, "INVALID_RESOLUTION"))
+};
+function checkTimeline(value, path, emit) {
+	const { start, horizon } = checkShape(value, path, shape, emit) ?? {};
+	if (isValidDate(start) && isValidDate(horizon) && horizon < start) emit("HORIZON_BEFORE_START", [...path, "horizon"]);
+}
+// src/check/index.ts
+/** True (and no problem) unless a record's `schemaVersion` is not 1: then one error is emitted. */
+function versionOk(value, path, emit) {
+	if (!isRecord(value) || value["schemaVersion"] === 1) return true;
+	emit("UNSUPPORTED_SCHEMA_VERSION", [...path, "schemaVersion"]);
+	return false;
+}
+/**
+* Validates all three inputs in one pass. `[]` means valid; the engine refuses to run otherwise.
+* Accepts arbitrary values and never throws: an input that cannot be read at all (a throwing
+* getter, a revoked Proxy) yields a single `NOT_AN_OBJECT` problem at its root.
+*/
+function check(baseline, scenario, timeline) {
+	const problems = [];
+	const emit = (code, path) => void problems.push({
+		code,
+		path
+	});
+	const guard = makeGuard(emit);
+	const scenarioOk = guard("scenario", false, () => versionOk(scenario, ["scenario"], emit));
+	const baselineOk = guard("baseline", false, () => versionOk(baseline, ["baseline"], emit));
+	const accounts = guard("scenario", void 0, () => scenarioOk && isRecord(scenario) ? indexAccounts(scenario["accounts"]) : void 0);
+	if (baselineOk) guard("baseline", void 0, () => checkBaseline(baseline, ["baseline"], accounts, emit));
+	if (scenarioOk) guard("scenario", void 0, () => checkScenario(scenario, ["scenario"], accounts, emit));
+	guard("timeline", void 0, () => checkTimeline(timeline, ["timeline"], emit));
+	return problems;
+}
+/** The closed set of problem codes. Frozen so consumers cannot mutate it at runtime. */
+const ERROR_CODES = Object.freeze([
+	"UNSUPPORTED_SCHEMA_VERSION",
+	"NOT_AN_OBJECT",
+	"NOT_AN_ARRAY",
+	"MISSING_KEY",
+	"UNKNOWN_KEY",
+	"WRONG_TYPE",
+	"EMPTY_STRING",
+	"NOT_SAFE_INTEGER",
+	"NEGATIVE_AMOUNT",
+	"INVALID_DATE",
+	"INVALID_KIND",
+	"INVALID_FREQUENCY",
+	"INVALID_GROWTH",
+	"INVALID_RESOLUTION",
+	"HORIZON_BEFORE_START",
+	"END_BEFORE_START",
+	"ONCE_FLOW_END_MISMATCH",
+	"DUPLICATE_ID",
+	"UNKNOWN_ACCOUNT",
+	"UNDECLARED_BALANCE_ACCOUNT",
+	"LIABILITY_MISUSE",
+	"SURPLUS_UNROUTED",
+	"RATE_OUT_OF_RANGE"
+]);
+// src/output/opening.ts
+/** Net worth at the timeline start, before any start-date flows land. */
+function openingNetWorth(baseline, rules) {
+	let total = 0n;
+	for (const balance of baseline.balances) {
+		const amount = BigInt(balance.amount);
+		total += rules.get(balance.account)?.kind === "liability" ? -amount : amount;
+	}
+	return total;
+}
+// src/calendar/civil.ts
+const DATE_SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const MONTH_DAYS = [
+	31,
+	28,
+	31,
+	30,
+	31,
+	30,
+	31,
+	31,
+	30,
+	31,
+	30,
+	31
+];
+function isLeapYear(year) {
+	return year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
+}
+function daysInMonth(year, month) {
+	return month === 2 && isLeapYear(year) ? 29 : MONTH_DAYS[month - 1] ?? 0;
+}
+/** Parses an already validated `YYYY-MM-DD` date. */
+function parseDate(value) {
+	const match = DATE_SHAPE.exec(value);
+	if (!match) throw new RangeError(`Invalid date: ${value}`);
+	return {
+		year: Number(match[1]),
+		month: Number(match[2]),
+		day: Number(match[3])
+	};
+}
+function pad(value, width) {
+	return String(value).padStart(width, "0");
+}
+function formatDate({ year, month, day }) {
+	return `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
+}
+// src/calendar/arith.ts
+function daysBeforeYear(year) {
+	const previous = year - 1;
+	return 365 * previous + Math.floor(previous / 4) - Math.floor(previous / 100) + Math.floor(previous / 400);
+}
+function daysBeforeMonth(year, month) {
+	let days = 0;
+	for (let m = 1; m < month; m++) days += daysInMonth(year, m);
+	return days;
+}
+/** Zero-based serial day number; 0001-01-01 is 0. */
+function dayNumber(date) {
+	const { year, month, day } = parseDate(date);
+	return daysBeforeYear(year) + daysBeforeMonth(year, month) + day - 1;
+}
+const FIRST_DATE = "0001-01-01";
+const LAST_DATE = "9999-12-31";
+const LAST_DAY = dayNumber(LAST_DATE);
+/** Inverse of `dayNumber`, saturating at the supported range; no wall clock is involved. */
+function fromDayNumber(value) {
+	if (value <= 0) return FIRST_DATE;
+	if (value >= LAST_DAY) return LAST_DATE;
+	let year = Math.floor(value / 366) + 1;
+	while (daysBeforeYear(year + 1) <= value) year++;
+	while (daysBeforeYear(year) > value) year--;
+	let remaining = value - daysBeforeYear(year);
+	let month = 1;
+	while (remaining >= daysInMonth(year, month)) {
+		remaining -= daysInMonth(year, month);
+		month++;
+	}
+	return formatDate({
+		year,
+		month,
+		day: remaining + 1
+	});
+}
+function addDays(date, days) {
+	return fromDayNumber(dayNumber(date) + days);
+}
+/** Adds calendar months, clamping the day to the target month's last day. */
+function addMonthsClamped(date, months) {
+	const { year, month, day } = parseDate(date);
+	const total = year * 12 + (month - 1) + months;
+	const targetYear = Math.floor(total / 12);
+	if (targetYear > 9999) return LAST_DATE;
+	const targetMonth = (total % 12 + 12) % 12 + 1;
+	return formatDate({
+		year: targetYear,
+		month: targetMonth,
+		day: Math.min(day, daysInMonth(targetYear, targetMonth))
+	});
+}
+/** Number of annual growth anniversaries reached, with `Feb 29 -> Feb 28` clamping. */
+function growthYears(start, date) {
+	const years = parseDate(date).year - parseDate(start).year;
+	if (years <= 0) return 0;
+	return addMonthsClamped(start, years * 12) <= date ? years : years - 1;
+}
+// src/output/periods.ts
+/** Last day of every full twelve-month period that ends on or before `end`. */
+function periodEndDates(start, end) {
+	const dates = [];
+	for (let index = 1;; index++) {
+		const last = addDays(addMonthsClamped(start, index * 12), -1);
+		if (last > end) return dates;
+		dates.push(last);
+	}
+}
+/**
+* Twelve-month periods from each anniversary of `start` to the day before the next one; the
+* final one is clipped by the projection's end and marked partial.
+*/
+function buildPeriods(start, end, runsOutDate) {
+	const periods = [];
+	let from = start;
+	let index = 0;
+	while (true) {
+		const next = addMonthsClamped(start, (index + 1) * 12);
+		const yearEnd = addDays(next, -1);
+		const to = end < yearEnd ? end : yearEnd;
+		const partial = to < yearEnd || to === runsOutDate;
+		periods.push({
+			index,
+			from,
+			to,
+			partial
+		});
+		if (to === end) return periods;
+		from = next;
+		index++;
+	}
+}
+// src/engine/overflow.ts
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+function isSafeInteger(value) {
+	return value >= -MAX_SAFE && value <= MAX_SAFE;
+}
+function overflow(date, account) {
+	return account === void 0 ? {
+		code: "VALUE_OVERFLOW",
+		date
+	} : {
+		code: "VALUE_OVERFLOW",
+		date,
+		account
+	};
+}
+// src/output/rollups.ts
+function sumFlows(totals, period) {
+	let income = 0n;
+	let expense = 0n;
+	let contributions = 0n;
+	for (const total of totals) {
+		if (total.date < period.from || total.date > period.to) continue;
+		income += total.income;
+		expense += total.expense;
+		contributions += total.contributions;
+	}
+	return {
+		income,
+		expense,
+		contributions
+	};
+}
+function unsafe(values, date) {
+	for (const value of values) if (!isSafeInteger(value)) return overflow(date);
+}
+function buildRollups(run, periods, opening) {
+	const snapshots = /* @__PURE__ */ new Map();
+	for (const snapshot of run.snapshots) snapshots.set(snapshot.date, snapshot);
+	const annual = [];
+	let openingWorth = opening;
+	for (const period of periods) {
+		const sums = sumFlows(run.totals, period);
+		const closing = snapshots.get(period.to).netWorth;
+		const unmet = run.runsOut?.date === period.to ? run.runsOut.unmet : 0n;
+		const interest = closing - openingWorth - sums.income + sums.expense - unmet;
+		const problem = unsafe([
+			openingWorth,
+			closing,
+			sums.income,
+			sums.expense,
+			sums.contributions,
+			interest,
+			unmet
+		], period.to);
+		if (problem !== void 0) return {
+			annual: void 0,
+			problem
+		};
+		annual.push({
+			index: period.index,
+			from: period.from,
+			to: period.to,
+			openingNetWorth: Number(openingWorth),
+			closingNetWorth: Number(closing),
+			income: Number(sums.income),
+			expense: Number(sums.expense),
+			contributions: Number(sums.contributions),
+			interest: Number(interest),
+			unmet: Number(unmet),
+			partial: period.partial
+		});
+		openingWorth = closing;
+	}
+	return {
+		annual,
+		problem: void 0
+	};
+}
+// src/calendar/rows.ts
+/** `start`, every monthly anniversary of it (clamped), and `horizon`. */
+function monthlyRowDates(start, horizon) {
+	if (horizon <= start) return [start];
+	const dates = [start];
+	let index = 1;
+	while (true) {
+		const date = addMonthsClamped(start, index);
+		if (date >= horizon) break;
+		dates.push(date);
+		index++;
+	}
+	dates.push(horizon);
+	return dates;
+}
+/** Every date in `[start, horizon]`. */
+function dailyRowDates(start, horizon) {
+	const dates = [];
+	for (let date = start; date <= horizon; date = addDays(date, 1)) dates.push(date);
+	return dates;
+}
+// src/output/row-dates.ts
+/** The dates `Timeline.resolution` asks to report. */
+function rowDates(timeline) {
+	return timeline.resolution === "day" ? dailyRowDates(timeline.start, timeline.horizon) : monthlyRowDates(timeline.start, timeline.horizon);
+}
+// src/calendar/counted.ts
+/** Number of Feb 29 dates in years 1..year that are not after `date`. */
+function leapDaysThrough(date) {
+	const { year, month, day } = parseDate(date);
+	let count = Math.floor(year / 4) - Math.floor(year / 100) + Math.floor(year / 400);
+	if (isLeapYear(year) && (month < 2 || month === 2 && day < 29)) count--;
+	return count;
+}
+/** Actual/365 No Leap: actual days minus the Feb 29s in `(from, to]`. */
+function countedDays(from, to) {
+	return dayNumber(to) - dayNumber(from) - (leapDaysThrough(to) - leapDaysThrough(from));
+}
+// src/money/pow.ts
+/** Integer exponentiation by squaring; `exponent` is a non-negative safe integer. */
+function powBigInt(base, exponent) {
+	if (!Number.isSafeInteger(exponent) || exponent < 0) throw new RangeError("powBigInt expects a non-negative safe integer exponent");
+	let result = 1n;
+	let factor = base;
+	let remaining = exponent;
+	while (remaining > 0) {
+		if (remaining % 2 === 1) result *= factor;
+		factor *= factor;
+		remaining = Math.floor(remaining / 2);
+	}
+	return result;
+}
+// src/money/root.ts
+/** Largest integer `r` with `r ** degree <= value` (`value >= 0`, `degree >= 1`). */
+function nthRootFloor(value, degree) {
+	if (value < 0n || !Number.isSafeInteger(degree) || degree < 1) throw new RangeError("nthRootFloor expects a non-negative value and positive degree");
+	if (value < 2n) return value;
+	let high = 1n;
+	while (powBigInt(high, degree) <= value) high *= 2n;
+	let low = high / 2n;
+	while (low + 1n < high) {
+		const middle = (low + high) / 2n;
+		if (powBigInt(middle, degree) <= value) low = middle;
+		else high = middle;
+	}
+	return low;
+}
+// src/money/factor.ts
+const RATE_SCALE = 10000n;
+const FACTOR_BASE = 10n ** BigInt(30);
+const cache = /* @__PURE__ */ new Map();
+/**
+* Largest integer `f` with `10000 * f^365 <= (10000 + rate) * 10^(30*365)`.
+* The result is cached per rate; the cache is deterministic and purely additive.
+*/
+function dailyFactor(rate) {
+	if (!Number.isSafeInteger(rate) || rate <= -1e4) throw new RangeError(`Rate must be a safe integer above -10000 bps: ${rate}`);
+	const cached = cache.get(rate);
+	if (cached !== void 0) return cached;
+	const factor = nthRootFloor((RATE_SCALE + BigInt(rate)) * FACTOR_BASE ** BigInt(365) / RATE_SCALE, 365);
+	cache.set(rate, factor);
+	return factor;
+}
+// src/money/round.ts
+/** Half-up rounding of a non-negative integer ratio. */
+function roundHalfUp(numerator, denominator) {
+	if (numerator < 0n) throw new RangeError("roundHalfUp expects a non-negative numerator");
+	if (denominator <= 0n) throw new RangeError("roundHalfUp expects a positive denominator");
+	const quotient = numerator / denominator;
+	return numerator % denominator * 2n >= denominator ? quotient + 1n : quotient;
+}
+// src/money/growth.ts
+const factorPowers = /* @__PURE__ */ new Map();
+const ratePowers = /* @__PURE__ */ new Map();
+function powerAt(rate, exponent, rateBase) {
+	const cache = rateBase ? ratePowers : factorPowers;
+	let powers = cache.get(rate);
+	if (powers === void 0) {
+		powers = [1n];
+		cache.set(rate, powers);
+	}
+	const base = rateBase ? RATE_SCALE + BigInt(rate) : dailyFactor(rate);
+	while (powers.length <= exponent) powers.push(powers[powers.length - 1] * base);
+	return powers[exponent];
+}
+function splitDays(days) {
+	if (!Number.isSafeInteger(days) || days < 0) throw new RangeError("Growth expects a non-negative safe integer day count");
+	const years = Math.floor(days / 365);
+	return [years, days - years * 365];
+}
+/** `(10000 + rate)^years * f^remainder / (10000^years * 10^(30*remainder))`. */
+function factorParts(rate, days) {
+	const [years, remainder] = splitDays(days);
+	return {
+		numerator: powerAt(rate, years, true) * powerAt(rate, remainder, false),
+		denominator: powerAt(0, years, true) * powerAt(0, remainder, false)
+	};
+}
+/** Grows `amount` over `days` counted days with one half-up rounding at the end. */
+function grow(amount, rate, days) {
+	const parts = factorParts(rate, days);
+	return roundHalfUp(amount * parts.numerator, parts.denominator);
+}
+/** Today's-money value of `amount` at `inflation`, over `days` counted days. */
+function deflate(amount, inflation, days) {
+	const parts = factorParts(inflation, days);
+	return roundHalfUp(amount * parts.denominator, parts.numerator);
+}
+// src/output/real.ts
+/** Deflates each account separately, then sums the signed real balances. */
+function realValues(snapshot, rules, start, inflation) {
+	const days = countedDays(start, snapshot.date);
+	const balances = [];
+	let net = 0n;
+	let accessible = 0n;
+	for (const balance of snapshot.balances) {
+		const amount = deflate(balance.amount, inflation, days);
+		if (!isSafeInteger(amount)) return {
+			values: void 0,
+			problem: overflow(snapshot.date, balance.account)
+		};
+		balances.push({
+			account: balance.account,
+			amount: Number(amount)
+		});
+		const rule = rules.get(balance.account);
+		const signed = rule?.kind === "liability" ? -amount : amount;
+		net += signed;
+		if (rule?.kind !== "asset" || rule.lockedUntil === void 0 || snapshot.date >= rule.lockedUntil) accessible += signed;
+	}
+	if (!isSafeInteger(net) || !isSafeInteger(accessible)) return {
+		values: void 0,
+		problem: overflow(snapshot.date)
+	};
+	return {
+		values: {
+			balances,
+			netWorth: net,
+			accessibleNetWorth: accessible
+		},
+		problem: void 0
+	};
+}
+// src/output/rows.ts
+function nominalAmounts(snapshot) {
+	return snapshot.balances.map((balance) => ({
+		account: balance.account,
+		amount: Number(balance.amount)
+	}));
+}
+function buildRows(snapshots, timeline, rules, inflation) {
+	const rows = [];
+	for (const snapshot of snapshots) {
+		const real = realValues(snapshot, rules, timeline.start, inflation);
+		if (real.problem !== void 0) return {
+			rows: void 0,
+			problem: real.problem
+		};
+		const values = real.values;
+		rows.push({
+			date: snapshot.date,
+			balances: nominalAmounts(snapshot),
+			netWorth: Number(snapshot.netWorth),
+			accessibleNetWorth: Number(snapshot.accessibleNetWorth),
+			realBalances: values.balances,
+			realNetWorth: Number(values.netWorth),
+			realAccessibleNetWorth: Number(values.accessibleNetWorth)
+		});
+	}
+	return {
+		rows,
+		problem: void 0
+	};
+}
+// src/output/rules.ts
+function accountRules(scenario) {
+	const rules = /* @__PURE__ */ new Map();
+	for (const rule of scenario.accounts) rules.set(rule.id, rule);
+	return rules;
+}
+// src/output/build.ts
+function buildProjection(run, baseline, scenario, timeline) {
+	const rules = accountRules(scenario);
+	const reported = new Set(rowDates(timeline));
+	const rows = buildRows(run.snapshots.filter((snapshot) => reported.has(snapshot.date) || snapshot.date === run.runsOut?.date), timeline, rules, scenario.economy.inflation);
+	if (rows.problem !== void 0) return { problem: rows.problem };
+	const end = run.runsOut?.date ?? timeline.horizon;
+	const rollups = buildRollups(run, buildPeriods(timeline.start, end, run.runsOut?.date), openingNetWorth(baseline, rules));
+	if (rollups.problem !== void 0) return { problem: rollups.problem };
+	return { projection: run.runsOut === void 0 ? {
+		rows: rows.rows,
+		annual: rollups.annual
+	} : {
+		rows: rows.rows,
+		annual: rollups.annual,
+		runsOut: {
+			date: run.runsOut.date,
+			unmet: Number(run.runsOut.unmet)
+		}
+	} };
+}
+// src/engine/dates.ts
+/** Sorted unique union of event dates and requested observation dates. */
+function collectDates(events, observations) {
+	const dates = /* @__PURE__ */ new Set();
+	for (const event of events) dates.add(event.date);
+	for (const date of observations) dates.add(date);
+	return [...dates].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+}
+// src/calendar/occurrence.ts
+function stepDays(frequency) {
+	if (frequency === "daily") return 1;
+	if (frequency === "weekly") return 7;
+	if (frequency === "biweekly") return 14;
+}
+function stepMonths(frequency) {
+	if (frequency === "monthly") return 1;
+	if (frequency === "quarterly") return 3;
+	if (frequency === "annual") return 12;
+}
+function occurrenceDate(start, frequency, index) {
+	const months = stepMonths(frequency);
+	if (months !== void 0) return addMonthsClamped(start, index * months);
+	return addDays(start, index * (stepDays(frequency) ?? 1));
+}
+function firstIndex(start, frequency, from) {
+	if (from <= start) return 0;
+	const months = stepMonths(frequency);
+	if (months !== void 0) {
+		const s = start.split("-");
+		const f = from.split("-");
+		const diff = (Number(f[0]) - Number(s[0])) * 12 + (Number(f[1]) - Number(s[1]));
+		return Math.max(0, Math.floor(diff / months));
+	}
+	const days = stepDays(frequency) ?? 1;
+	return Math.max(0, Math.floor((dayNumber(from) - dayNumber(start)) / days));
+}
+function rangeOccurrences(start, frequency, last, from) {
+	const result = [];
+	for (let index = firstIndex(start, frequency, from);; index++) {
+		const date = occurrenceDate(start, frequency, index);
+		if (date > last) return result;
+		if (date >= from) result.push({
+			date,
+			years: growthYears(start, date)
+		});
+	}
+}
+/** Occurrences in `[from, to]`, with `end` (inclusive) capping them. */
+function occurrences(start, frequency, end, from, to) {
+	if (to < from) return [];
+	const last = end !== void 0 && end < to ? end : to;
+	if (frequency === "once") return start >= from && start <= last ? [{
+		date: start,
+		years: 0
+	}] : [];
+	return rangeOccurrences(start, frequency, last, from);
+}
+// src/engine/order.ts
+/** Plain UTF-16 code-unit ordering, never `localeCompare`. */
+function compareIds(left, right) {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}
+// src/engine/events.ts
+/** All flow occurrences in the timeline, sorted by date then flow id. */
+function buildEvents(scenario, timeline) {
+	const events = [];
+	for (const flow of scenario.flows) {
+		const found = occurrences(flow.start, flow.frequency, flow.end, timeline.start, timeline.horizon);
+		for (const occurrence of found) events.push({
+			date: occurrence.date,
+			flow,
+			years: occurrence.years
+		});
+	}
+	return events.sort((left, right) => left.date === right.date ? compareIds(left.flow.id, right.flow.id) : left.date < right.date ? -1 : 1);
+}
+// src/engine/amount.ts
+/** Flow amount at an occurrence, grown from the original by whole annual steps. */
+function amountAt(event, inflation) {
+	const growth = event.flow.growth;
+	const rate = growth === "inflation" ? inflation : growth.bps;
+	return grow(BigInt(event.flow.amount), rate, event.years * 365);
+}
+// src/engine/aggregate.ts
+function aggregate(events, inflation) {
+	let income = 0n;
+	let expense = 0n;
+	const contributions = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		const amount = amountAt(event, inflation);
+		const flow = event.flow;
+		if (flow.kind === "income") income += amount;
+		else if (flow.kind === "expense") expense += amount;
+		else {
+			const previous = contributions.get(flow.target) ?? 0n;
+			contributions.set(flow.target, previous + amount);
+		}
+	}
+	return {
+		income,
+		expense,
+		contributions
+	};
+}
+// src/engine/min.ts
+function minBigInt(left, right) {
+	if (left < right) return left;
+	return right;
+}
+// src/engine/value.ts
+/** Read-only valuation; it never commits the account. */
+function valuation(state, date) {
+	return grow(state.balance, state.rule.rate, countedDays(state.asOf, date));
+}
+// src/engine/mutate.ts
+/** Commits accrued growth, then applies `delta`; returns a problem on overflow. */
+function mutate(state, date, delta) {
+	const committed = valuation(state, date);
+	if (!isSafeInteger(committed)) return overflow(date, state.rule.id);
+	const next = committed + delta;
+	if (next < 0n) throw new RangeError(`Negative balance on ${state.rule.id} at ${date}`);
+	if (!isSafeInteger(next)) return overflow(date, state.rule.id);
+	state.balance = next;
+	state.asOf = date;
+}
+// src/engine/contributions.ts
+function applyTarget(states, target, total, date) {
+	const state = states.get(target);
+	if (total === 0n || state === void 0) return {
+		outflow: 0n,
+		problem: void 0
+	};
+	const liability = state.rule.kind === "liability";
+	const payment = minBigInt(total, liability ? valuation(state, date) : total);
+	const problem = mutate(state, date, liability ? -payment : payment);
+	return problem === void 0 ? {
+		outflow: payment,
+		problem: void 0
+	} : {
+		outflow: 0n,
+		problem
+	};
+}
+/** Applies same-date contributions per target, capping liability payments at the amount owed. */
+function applyContributions(states, contributions, date) {
+	let outflow = 0n;
+	for (const target of [...contributions.keys()].sort(compareIds)) {
+		const result = applyTarget(states, target, contributions.get(target) ?? 0n, date);
+		if (result.problem !== void 0) return {
+			outflow,
+			problem: result.problem
+		};
+		outflow += result.outflow;
+	}
+	return {
+		outflow,
+		problem: void 0
+	};
+}
+// src/engine/surplus.ts
+function fillStep(states, step, date, remaining) {
+	const state = states.get(step.account);
+	const headroom = step.upTo === void 0 ? remaining : BigInt(step.upTo) - valuation(state, date);
+	let fill = 0n;
+	if (headroom > 0n) fill = minBigInt(remaining, headroom);
+	if (fill === 0n) return {
+		remaining,
+		problem: void 0
+	};
+	const problem = mutate(state, date, fill);
+	return problem === void 0 ? {
+		remaining: remaining - fill,
+		problem: void 0
+	} : {
+		remaining,
+		problem
+	};
+}
+function applySurplus(states, scenario, date, amount) {
+	let remaining = amount;
+	for (const step of scenario.cashflow.surplus) {
+		if (remaining === 0n) return void 0;
+		const result = fillStep(states, step, date, remaining);
+		remaining = result.remaining;
+		if (result.problem !== void 0) return result.problem;
+	}
+}
+// src/engine/withdraw.ts
+function isLocked(state, date) {
+	return state.rule.kind === "asset" && state.rule.lockedUntil !== void 0 && date < state.rule.lockedUntil;
+}
+function takeFrom(state, date, remaining) {
+	const take = minBigInt(remaining, valuation(state, date));
+	if (take === 0n) return {
+		remaining,
+		problem: void 0
+	};
+	const problem = mutate(state, date, -take);
+	return problem === void 0 ? {
+		remaining: remaining - take,
+		problem: void 0
+	} : {
+		remaining,
+		problem
+	};
+}
+function applyWithdraw(states, scenario, date, amount) {
+	let remaining = amount;
+	for (const account of scenario.cashflow.withdraw) {
+		if (remaining === 0n) break;
+		const state = states.get(account);
+		if (isLocked(state, date)) continue;
+		const result = takeFrom(state, date, remaining);
+		remaining = result.remaining;
+		if (result.problem !== void 0) return result;
+	}
+	return {
+		remaining,
+		problem: void 0
+	};
+}
+// src/engine/occurrence.ts
+/** Applies one occurrence date in the canonical order of operations. */
+function processDate(states, scenario, date, events) {
+	const day = aggregate(events, scenario.economy.inflation);
+	const applied = applyContributions(states, day.contributions, date);
+	const totals = {
+		date,
+		income: day.income,
+		expense: day.expense,
+		contributions: applied.outflow
+	};
+	if (applied.problem !== void 0) return {
+		totals,
+		problem: applied.problem,
+		runsOut: void 0
+	};
+	const net = day.income - day.expense - applied.outflow;
+	if (net > 0n) return {
+		totals,
+		problem: applySurplus(states, scenario, date, net),
+		runsOut: void 0
+	};
+	if (net < 0n) {
+		const drawn = applyWithdraw(states, scenario, date, -net);
+		if (drawn.problem !== void 0) return {
+			totals,
+			problem: drawn.problem,
+			runsOut: void 0
+		};
+		if (drawn.remaining > 0n) return {
+			totals,
+			problem: void 0,
+			runsOut: {
+				date,
+				unmet: drawn.remaining
+			}
+		};
+	}
+	return {
+		totals,
+		problem: void 0,
+		runsOut: void 0
+	};
+}
+// src/engine/snapshot.ts
+/** Values every account without committing, and checks all reported numbers stay safe. */
+function snapshot(states, date) {
+	const balances = [];
+	let net = 0n;
+	let accessible = 0n;
+	for (const state of states.values()) {
+		const amount = valuation(state, date);
+		if (!isSafeInteger(amount)) return {
+			snapshot: void 0,
+			problem: overflow(date, state.rule.id)
+		};
+		balances.push({
+			account: state.rule.id,
+			amount
+		});
+		const signed = state.rule.kind === "liability" ? -amount : amount;
+		net += signed;
+		if (state.rule.kind === "liability" || state.rule.lockedUntil === void 0 || date >= state.rule.lockedUntil) accessible += signed;
+	}
+	if (!isSafeInteger(net) || !isSafeInteger(accessible)) return {
+		snapshot: void 0,
+		problem: overflow(date)
+	};
+	return {
+		snapshot: {
+			date,
+			balances,
+			netWorth: net,
+			accessibleNetWorth: accessible
+		},
+		problem: void 0
+	};
+}
+// src/engine/run-step.ts
+function addSnapshot(snapshots, states, date) {
+	const outcome = snapshot(states, date);
+	if (outcome.problem !== void 0) return outcome.problem;
+	snapshots.push(outcome.snapshot);
+}
+function finishRunout(acc, states, runsOut) {
+	if (!isSafeInteger(runsOut.unmet)) return {
+		ok: false,
+		problem: overflow(runsOut.date)
+	};
+	const problem = addSnapshot(acc.snapshots, states, runsOut.date);
+	if (problem !== void 0) return {
+		ok: false,
+		problem
+	};
+	return {
+		ok: true,
+		run: {
+			snapshots: acc.snapshots,
+			totals: acc.totals,
+			runsOut
+		}
+	};
+}
+function handleDay(acc, states, scenario, date, events) {
+	if (events.length === 0) return void 0;
+	const outcome = processDate(states, scenario, date, events);
+	acc.totals.push(outcome.totals);
+	if (outcome.problem !== void 0) return {
+		ok: false,
+		problem: outcome.problem
+	};
+	if (outcome.runsOut !== void 0) return finishRunout(acc, states, outcome.runsOut);
+}
+function handleSnapshot(acc, states, date) {
+	if (!acc.wanted.has(date)) return void 0;
+	const problem = addSnapshot(acc.snapshots, states, date);
+	if (problem !== void 0) return {
+		ok: false,
+		problem
+	};
+}
+function stepDate(acc, states, scenario, date, events) {
+	const dayResult = handleDay(acc, states, scenario, date, events);
+	if (dayResult !== void 0) return dayResult;
+	return handleSnapshot(acc, states, date);
+}
+// src/engine/state.ts
+/** Every declared account gets a state; missing baseline balances open at zero. */
+function createStates(baseline, scenario, start) {
+	const opening = /* @__PURE__ */ new Map();
+	for (const balance of baseline.balances) opening.set(balance.account, balance.amount);
+	const states = /* @__PURE__ */ new Map();
+	const rules = [...scenario.accounts].sort((a, b) => compareIds(a.id, b.id));
+	for (const rule of rules) states.set(rule.id, {
+		rule,
+		balance: BigInt(opening.get(rule.id) ?? 0),
+		asOf: start
+	});
+	return states;
+}
+// src/engine/run.ts
+function runEngine(baseline, scenario, timeline, observations) {
+	const states = createStates(baseline, scenario, timeline.start);
+	const events = buildEvents(scenario, timeline);
+	const acc = {
+		snapshots: [],
+		totals: [],
+		wanted: new Set(observations)
+	};
+	let index = 0;
+	for (const date of collectDates(events, observations)) {
+		const start = index;
+		while (index < events.length && events[index]?.date === date) index++;
+		const result = stepDate(acc, states, scenario, date, events.slice(start, index));
+		if (result !== void 0) return result;
+	}
+	return {
+		ok: true,
+		run: {
+			snapshots: acc.snapshots,
+			totals: acc.totals
+		}
+	};
+}
+// src/engine/project.ts
+/** Report rows plus the period ends the annual roll-ups close on. */
+function observationDates(timeline) {
+	return [...rowDates(timeline), ...periodEndDates(timeline.start, timeline.horizon)];
+}
+/** Runs `check` first, then the deterministic engine; never throws on valid inputs. */
+function project(baseline, scenario, timeline) {
+	const problems = check(baseline, scenario, timeline);
+	if (problems.length > 0) return {
+		ok: false,
+		problems
+	};
+	const result = runEngine(baseline, scenario, timeline, observationDates(timeline));
+	if (!result.ok) return {
+		ok: false,
+		problems: [result.problem]
+	};
+	const output = buildProjection(result.run, baseline, scenario, timeline);
+	if ("problem" in output) return {
+		ok: false,
+		problems: [output.problem]
+	};
+	return {
+		ok: true,
+		projection: output.projection
+	};
+}
+export { ERROR_CODES, check, project };
+
+//# sourceMappingURL=index.mjs.map