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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 trajectonomics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @trajectonomics/ledger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pure double-entry ledger domain: accounts, balanced postings, balances, net worth, P&L. No I/O.
+
+## Agent Skills
+
+Configured with [Matt Pocock's skills](https://github.com/mattpocock/skills) for AI engineering workflows. See [AGENTS.md](./AGENTS.md) and [`docs/agents/`](./docs/agents/).
+
+## Commands
+
+```bash
+bun install
+bun test
+bun run typecheck
+bun run build       # tsdown: dist/ with esm + cjs + d.ts
+bun run lint        # Biome, zero warnings
+bun run format      # Biome format + import order, writes files
+bun run check       # lint + typecheck + test + build + lint:package
+```
+
+## Releasing
+
+Versions are computed, never edited by hand (`package.json` says `0.0.0-development` on purpose). `scripts/version.ts` reads the last `vX.Y.Z` git tag and the conventional commit messages since then:
+
+| Commits since last release | Bump |
+| --- | --- |
+| any `feat!:` / `fix!:` / `BREAKING CHANGE:` | major (minor while on 0.x) |
+| any `feat:` | minor |
+| anything else | patch |
+
+- **Alpha, automatic:** Every merge to `main` that touches code publishes `<next>-alpha.<n>` under the npm dist-tag `alpha` (`bun add @trajectonomics/ledger@alpha`). `n` counts up per upcoming version.
+- **Stable, on demand:** Actions → Release → Run workflow (on `main`). It publishes `<next>` under `latest`, tags `vX.Y.Z`, and creates a GitHub release with generated notes. The bump input overrides the computed one; pick `major` to cut 1.0.0.
+
+PR titles must be conventional commits (enforced by the `PR title` check) because squash-merge commit subjects become the basis for version calculation.
+
+Preview the next version locally:
+
+```bash
+bun scripts/version.ts --channel alpha
+bun scripts/version.ts --channel stable
+```

package/dist/index.cjs

@@ -0,0 +1,575 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/account.ts
+/** `asset` and `expense` are debit-normal; `liability`, `equity` and `income` credit-normal. */
+const normalBalance = (type) => type === "asset" || type === "expense" ? "debit" : "credit";
+// src/errors.ts
+/** Thrown by every smart constructor and validator in this package. */
+var LedgerValidationError = class extends Error {
+	code;
+	/** Path of the offending input, e.g. `postings[1].accountId`. */
+	field;
+	value;
+	reason;
+	constructor(code, field, value, reason) {
+		super(`${code}: ${field} ${reason}`);
+		this.name = "LedgerValidationError";
+		this.code = code;
+		this.field = field;
+		this.value = value;
+		this.reason = reason;
+	}
+};
+// src/date.ts
+const SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const daysInMonth = (year, month) => month === 2 ? year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28 : [
+	4,
+	6,
+	9,
+	11
+].includes(month) ? 30 : 31;
+const parseISODate = (value, field = "date") => {
+	const match = typeof value === "string" ? SHAPE.exec(value) : null;
+	const [year, month, day] = [
+		Number(match?.[1]),
+		Number(match?.[2]),
+		Number(match?.[3])
+	];
+	if (!match || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) throw new LedgerValidationError("INVALID_DATE", field, value, "must be a real YYYY-MM-DD calendar date");
+	return value;
+};
+// src/amount.ts
+/** Accepts only safe integers; anything else is `INVALID_AMOUNT`. */
+const assertSafeInteger = (value, field) => {
+	if (typeof value !== "number" || !Number.isSafeInteger(value)) throw new LedgerValidationError("INVALID_AMOUNT", field, value, "must be a safe integer of minor units");
+	return value;
+};
+// src/currency.ts
+let known;
+/**
+* Validate an ISO 4217 code against the runtime's own currency data
+* (`Intl.supportedValuesOf("currency")`), so no code table ships in this package.
+* The accepted set therefore follows the runtime's ICU version.
+*/
+const parseCurrency = (value, field = "currency") => {
+	known ??= new Set(Intl.supportedValuesOf("currency"));
+	if (typeof value !== "string" || !known.has(value)) throw new LedgerValidationError("INVALID_CURRENCY", field, value, "is not an ISO 4217 currency code");
+	return value;
+};
+/** Number of minor-unit decimals for a currency: THB 2, JPY 0, KWD 3, CLF 4. */
+const minorUnitDigits = (currency) => new Intl.NumberFormat("en", {
+	style: "currency",
+	currency
+}).resolvedOptions().maximumFractionDigits ?? 2;
+// src/posting.ts
+const fail = (code, field, value, reason) => {
+	throw new LedgerValidationError(code, field, value, reason);
+};
+const checkDimensions = (dimensions, field) => {
+	for (const [key, value] of Object.entries(dimensions)) if (key === "" || typeof value !== "string" || value === "") fail("INVALID_DIMENSION", `${field}.dimensions`, { [key]: value }, "keys and values must be non-empty strings");
+};
+/** Validate one posting against the chart; `path` is e.g. `postings[0]`. */
+const validatePosting = (input, chart, path) => {
+	const amount = assertSafeInteger(input.amount, `${path}.amount`);
+	if (amount === 0) fail("ZERO_AMOUNT_POSTING", `${path}.amount`, amount, "must not be zero");
+	const currency = parseCurrency(input.currency, `${path}.currency`);
+	const account = chart.get(input.accountId);
+	if (!account) return fail("UNKNOWN_ACCOUNT", `${path}.accountId`, input.accountId, "is not in the chart of accounts");
+	if (!chart.isLeaf(account.id)) fail("NON_LEAF_ACCOUNT", `${path}.accountId`, account.id, "is a header account");
+	if (currency !== account.currency) fail("CURRENCY_MISMATCH", `${path}.currency`, currency, `account is ${account.currency}`);
+	if (input.dimensions) checkDimensions(input.dimensions, path);
+	return Object.freeze({
+		accountId: account.id,
+		amount,
+		currency,
+		...input.dimensions ? { dimensions: Object.freeze({ ...input.dimensions }) } : {}
+	});
+};
+// src/transaction.ts
+const assertBalanced = (postings, chart) => {
+	const sums = /* @__PURE__ */ new Map();
+	for (const { accountId, amount, currency } of postings) {
+		const key = JSON.stringify([chart.get(accountId)?.entityId, currency]);
+		sums.set(key, (sums.get(key) ?? 0n) + BigInt(amount));
+	}
+	for (const [key, sum] of sums) if (sum !== 0n) {
+		const [entity, currency] = JSON.parse(key);
+		throw new LedgerValidationError("UNBALANCED_TRANSACTION", "postings", sum.toString(), `entity "${entity}" ${currency} sums to ${sum} instead of 0`);
+	}
+};
+/** Validate a transaction against a chart. Throws {@link LedgerValidationError}. */
+const validateTransaction = (input, chart) => {
+	const date = parseISODate(input.date);
+	const count = Array.isArray(input.postings) ? input.postings.length : 0;
+	if (count < 2) throw new LedgerValidationError("SINGLE_POSTING", "postings", count, "needs at least 2 postings");
+	const postings = input.postings.map((p, i) => validatePosting(p, chart, `postings[${i}]`));
+	assertBalanced(postings, chart);
+	return Object.freeze({
+		id: input.id,
+		date,
+		postings: Object.freeze(postings),
+		...input.linkedTo === void 0 ? {} : { linkedTo: input.linkedTo }
+	});
+};
+// src/reverse.ts
+/** Build a Reversal; `path` prefixes error fields so `amend` can mirror its own input shape. */
+const reverseAt = (tx, input, chart, path) => {
+	const date = parseISODate(input.date, `${path}date`);
+	if (input.id === tx.id) throw new LedgerValidationError("DUPLICATE_TRANSACTION_ID", `${path}id`, input.id, "reuses the id of the transaction it reverses");
+	if (date < tx.date) throw new LedgerValidationError("REVERSAL_BEFORE_ORIGINAL", `${path}date`, input.date, `is before the original's date ${tx.date}`);
+	const postings = tx.postings.map(({ amount, ...rest }) => ({
+		...rest,
+		amount: -amount
+	}));
+	return validateTransaction({
+		id: input.id,
+		date,
+		postings,
+		linkedTo: tx.id
+	}, chart);
+};
+/** Build a Reversal: the original's Postings in order, every sign flipped, linked to it. */
+const reverse = (tx, input, chart) => reverseAt(tx, input, chart, "");
+// src/amend.ts
+/**
+* Build an Amendment: `[reversal, replacement]`, both linked to the original. The replacement's
+* own `linkedTo` is overwritten with the original's id.
+*/
+const amend = (tx, input, chart) => {
+	const reversal = reverseAt(tx, input.reversal, chart, "reversal.");
+	const { id } = input.replacement;
+	if (id === tx.id || id === reversal.id) throw new LedgerValidationError("DUPLICATE_TRANSACTION_ID", "replacement.id", id, `reuses the id of the ${id === tx.id ? "original" : "reversal"} in the same amendment`);
+	const replacement = validateTransaction({
+		...input.replacement,
+		linkedTo: tx.id
+	}, chart);
+	return Object.freeze([reversal, replacement]);
+};
+// src/compare.ts
+/** Order two strings by UTF-16 code unit. Never locale-aware: ICU data differs between runtimes. */
+const byCodeUnit = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+// src/ledger-scan.ts
+const recheck = (tx, index, chart) => {
+	try {
+		return validateTransaction(tx, chart);
+	} catch (error) {
+		if (!(error instanceof LedgerValidationError)) throw error;
+		throw new LedgerValidationError(error.code, `transactions[${index}].${error.field}`, error.value, error.reason);
+	}
+};
+/**
+* Re-check every Transaction against the supplied chart (a Transaction is not tied to the chart
+* that validated it) and flatten them into Postings. Throws on a duplicate Transaction id.
+*/
+const scanLedger = (transactions, chart) => {
+	const seen = /* @__PURE__ */ new Set();
+	return transactions.flatMap((tx, index) => {
+		if (seen.has(tx.id)) throw new LedgerValidationError("DUPLICATE_TRANSACTION_ID", `transactions[${index}].id`, tx.id, "is used by an earlier transaction");
+		seen.add(tx.id);
+		const checked = recheck(tx, index, chart);
+		return checked.postings.map((posting) => ({
+			account: chart.get(posting.accountId),
+			posting,
+			date: checked.date
+		}));
+	});
+};
+// src/safe-amount.ts
+const MAX = BigInt(Number.MAX_SAFE_INTEGER);
+/** Narrow a `BigInt` sum to a `number`, or throw `AMOUNT_OVERFLOW` when it is not a safe integer. */
+const toSafeAmount = (sum, field) => {
+	if (sum > MAX || sum < -MAX) throw new LedgerValidationError("AMOUNT_OVERFLOW", field, sum.toString(), "exceeds the safe integer range");
+	return Number(sum);
+};
+// src/balances.ts
+/** Order rows by `entityId`, `accountId`, then `currency`, by code unit. */
+const compareRows = (a, b) => byCodeUnit(a.entityId, b.entityId) || byCodeUnit(a.accountId, b.accountId) || byCodeUnit(a.currency, b.currency);
+/**
+* Every Leaf Account's Balance up to and including `asOf`, zeros included, sorted. `fieldOf` gives
+* the output path an `AMOUNT_OVERFLOW` reports for a Leaf, so it names the query the caller called.
+*/
+const leafBalances = (transactions, asOf, chart, fieldOf) => {
+	const cutoff = parseISODate(asOf, "asOf");
+	const sums = /* @__PURE__ */ new Map();
+	for (const { account, posting, date } of scanLedger(transactions, chart)) if (date <= cutoff) sums.set(account.id, (sums.get(account.id) ?? 0n) + BigInt(posting.amount));
+	return Object.freeze([...chart.values()].filter((account) => chart.isLeaf(account.id)).map((account) => Object.freeze({
+		entityId: account.entityId,
+		accountId: account.id,
+		currency: account.currency,
+		amount: toSafeAmount(sums.get(account.id) ?? 0n, fieldOf(account))
+	})).sort(compareRows));
+};
+/**
+* Every Leaf Account's Balance up to and including `asOf`, zeros included, sorted. Header
+* Accounts never appear, so summing the rows never double counts.
+*
+* TODO(#14): Header Account roll-ups live in a separate query, never in these rows.
+*/
+const balances = (transactions, asOf, chart) => leafBalances(transactions, asOf, chart, (account) => `balances[${account.id}]`);
+// src/ids.ts
+/** Tag a string as an {@link AccountId}, e.g. to look an account up in a chart. */
+const accountId = (value) => value;
+/** Tag a string as a {@link TransactionId}. */
+const transactionId = (value) => value;
+// src/balance.ts
+/**
+* One Leaf Account's Balance up to and including `asOf`: the row `balances` gives for it.
+* Throws `UNKNOWN_ACCOUNT` for an id outside the chart and `NON_LEAF_ACCOUNT` for a Header.
+*
+* TODO(#14): a Header's roll-up Balance is a separate query, so a Header id is rejected here.
+*/
+const balance = (transactions, accountId$1, asOf, chart) => {
+	const id = accountId(accountId$1);
+	if (!chart.has(id)) throw new LedgerValidationError("UNKNOWN_ACCOUNT", "accountId", accountId$1, "is not in the chart of accounts");
+	if (!chart.isLeaf(id)) throw new LedgerValidationError("NON_LEAF_ACCOUNT", "accountId", accountId$1, "is a header account");
+	return leafBalances(transactions, asOf, chart, (account) => account.id === id ? "balance.amount" : `balance[${account.id}]`).find((row) => row.accountId === id);
+};
+// src/chart-map.ts
+/**
+* A validated, hierarchy-checked set of accounts, read-only at runtime. Only
+* {@link createChartOfAccounts} constructs one (this module's constructor is not exported from
+* the package), so holding one proves parents exist, share entity and type, and form no cycle.
+* Its state lives in `#private` fields, so it cannot be mutated even via `Map.prototype`.
+*/
+var ChartOfAccounts = class {
+	#accounts;
+	#headers;
+	constructor(accounts) {
+		this.#accounts = new Map(accounts);
+		this.#headers = new Set([...accounts.values()].flatMap((a) => a.parentId === void 0 ? [] : [a.parentId]));
+	}
+	get size() {
+		return this.#accounts.size;
+	}
+	get(id) {
+		return this.#accounts.get(id);
+	}
+	has(id) {
+		return this.#accounts.has(id);
+	}
+	/** True for an account in this chart that no other account names as its parent. */
+	isLeaf(id) {
+		return this.#accounts.has(id) && !this.#headers.has(id);
+	}
+	forEach(callbackfn, thisArg) {
+		for (const [key, value] of this.#accounts) callbackfn.call(thisArg, value, key, this);
+	}
+	entries() {
+		return this.#accounts.entries();
+	}
+	keys() {
+		return this.#accounts.keys();
+	}
+	values() {
+		return this.#accounts.values();
+	}
+	[Symbol.iterator]() {
+		return this.#accounts.entries();
+	}
+};
+// src/hierarchy.ts
+const reject = (index, field, value, reason) => {
+	throw new LedgerValidationError("INVALID_ACCOUNT_HIERARCHY", `accounts[${index}].${field}`, value, reason);
+};
+const checkParent = (account, parent, i) => {
+	if (account.parentId === void 0) return;
+	if (!parent) reject(i, "parentId", account.parentId, "parent account does not exist");
+	else if (parent.entityId !== account.entityId) reject(i, "parentId", parent.id, "parent belongs to another entity");
+	else if (parent.type !== account.type) reject(i, "parentId", parent.id, "parent has a different account type");
+};
+const checkAcyclic = (account, accounts, i) => {
+	const seen = /* @__PURE__ */ new Set([account.id]);
+	for (let up = account.parentId; up !== void 0; up = accounts.get(up)?.parentId) {
+		if (seen.has(up)) reject(i, "parentId", account.parentId, "hierarchy contains a cycle");
+		seen.add(up);
+	}
+};
+/** Reject missing, cross-entity and cross-type parents, and cycles. */
+const checkHierarchy = (accounts) => {
+	for (const [i, account] of [...accounts.values()].entries()) {
+		checkParent(account, account.parentId === void 0 ? void 0 : accounts.get(account.parentId), i);
+		checkAcyclic(account, accounts, i);
+	}
+};
+// src/chart.ts
+const toAccount = (input, index) => Object.freeze({
+	id: input.id,
+	type: input.type,
+	currency: parseCurrency(input.currency, `accounts[${index}].currency`),
+	entityId: input.entityId ?? "default",
+	...input.parentId === void 0 ? {} : { parentId: input.parentId }
+});
+/** Validate accounts and build the chart. Throws {@link LedgerValidationError}. */
+const createChartOfAccounts = (inputs) => {
+	const accounts = /* @__PURE__ */ new Map();
+	for (const [index, input] of [...inputs].entries()) {
+		const account = toAccount(input, index);
+		if (accounts.has(account.id)) throw new LedgerValidationError("INVALID_ACCOUNT_HIERARCHY", `accounts[${index}].id`, input.id, "duplicate account id");
+		accounts.set(account.id, account);
+	}
+	checkHierarchy(accounts);
+	return new ChartOfAccounts(accounts);
+};
+// src/legs.ts
+/** Resolve a leg's Account in the chart and emit its Posting; Currency comes from the Account. */
+const legPosting = (leg, amount, chart, field) => {
+	const { accountId: id, dimensions } = typeof leg === "string" ? { accountId: leg } : leg;
+	const account = chart.get(accountId(id));
+	if (!account) throw new LedgerValidationError("UNKNOWN_ACCOUNT", typeof leg === "string" ? field : `${field}.accountId`, id, "is not in the chart of accounts");
+	return {
+		accountId: id,
+		amount,
+		currency: account.currency,
+		...dimensions ? { dimensions } : {}
+	};
+};
+/** A builder amount is a magnitude: the builder derives the sign, so a negative one is a bug. */
+const magnitude = (amount, field) => {
+	if (amount < 0) throw new LedgerValidationError("NEGATIVE_AMOUNT", field, amount, "must not be negative");
+	return amount;
+};
+/** The Credit form of a magnitude; never produces negative zero. */
+const credited = (amount) => 0 - amount;
+/** Reject legs whose Accounts hold differing Currencies; the core has no FX. */
+const assertSameCurrency = (postings, fields) => {
+	const first = postings[0]?.currency;
+	const index = postings.findIndex((p) => p.currency !== first);
+	if (index >= 0) throw new LedgerValidationError("CURRENCY_MISMATCH", fields[index] ?? "postings", postings[index]?.currency, `differs from ${first}; legs must share one currency`);
+};
+// src/compound.ts
+const side = (legs, name, chart) => ({
+	postings: legs.map((leg, i) => {
+		const amount = magnitude(leg.amount, `${name}[${i}].amount`);
+		return legPosting(leg, name === "debit" ? amount : credited(amount), chart, `${name}[${i}]`);
+	}),
+	fields: legs.map((_, i) => `${name}[${i}]`)
+});
+/**
+* Build a Compound Entry: many legs on either side, each with its own magnitude.
+* The two sides must total the same amount.
+*/
+const compound = (input, chart) => {
+	const debit = side(input.debit, "debit", chart);
+	const credit = side(input.credit, "credit", chart);
+	const postings = [...debit.postings, ...credit.postings];
+	assertSameCurrency(postings, [...debit.fields, ...credit.fields]);
+	return validateTransaction({
+		id: input.id,
+		date: input.date,
+		postings
+	}, chart);
+};
+// src/money.ts
+/**
+* Convert a major-unit amount (`12.34`) to signed integer minor units (`1234`).
+* Rounds half away from zero; `toPrecision` strips binary-float noise first.
+*/
+const toMinorUnits = (majorAmount, currency) => {
+	const digits = minorUnitDigits(parseCurrency(currency));
+	if (!Number.isFinite(majorAmount)) throw new LedgerValidationError("INVALID_AMOUNT", "majorAmount", majorAmount, "must be finite");
+	const raw = Math.abs(majorAmount) * 10 ** digits;
+	const scaled = raw < 0x38d7ea4c68000 ? Number(raw.toPrecision(15)) : raw;
+	return assertSafeInteger(Math.sign(majorAmount) * Math.round(scaled) + 0, "majorAmount");
+};
+/** Convert signed integer minor units (`1234`) to a major-unit amount (`12.34`). */
+const fromMinorUnits = (minorUnits, currency) => {
+	const digits = minorUnitDigits(parseCurrency(currency));
+	return assertSafeInteger(minorUnits, "minorUnits") / 10 ** digits;
+};
+// src/totals.ts
+/** Order totals by `entityId` then `currency`, by code unit. */
+const compareTotals = (a, b) => byCodeUnit(a.entityId, b.entityId) || byCodeUnit(a.currency, b.currency);
+/**
+* Sum `sign * amount` per `(Entity, Currency)` with `BigInt`, checking each total against the safe
+* integer range. One total per pair among the addends, sorted; a zero addend still yields its pair,
+* which is how P&L seeds its totals. `fieldOf` gives the output path an overflow reports for a pair.
+*/
+const totalsOf = (addends, sign, fieldOf) => {
+	const slots = /* @__PURE__ */ new Map();
+	for (const { entityId, currency, amount } of addends) {
+		const key = JSON.stringify([entityId, currency]);
+		const slot = slots.get(key) ?? {
+			entityId,
+			currency,
+			sum: 0n
+		};
+		slot.sum += sign * BigInt(amount);
+		slots.set(key, slot);
+	}
+	return Object.freeze([...slots.values()].map(({ entityId, currency, sum }) => Object.freeze({
+		entityId,
+		currency,
+		amount: toSafeAmount(sum, fieldOf(`${entityId}/${currency}`))
+	})).sort(compareTotals));
+};
+// src/net-worth.ts
+/**
+* Assets minus Liabilities up to and including `asOf`, per `(Entity, Currency)`, positive when
+* assets exceed liabilities. Rows stay raw signed; Equity is not part of it. Raw liabilities are
+* negative, so the natural-sign total is the plain sum of the rows.
+*/
+const netWorth = (transactions, asOf, chart) => {
+	const counted = (account) => account.type === "asset" || account.type === "liability";
+	const rows = leafBalances(transactions, asOf, chart, (account) => counted(account) ? `netWorth.rows[${account.id}]` : `netWorth[${account.id}]`).filter((row) => counted(chart.get(row.accountId)));
+	return Object.freeze({
+		rows: Object.freeze(rows),
+		totals: totalsOf(rows, 1n, (pair) => `netWorth.totals[${pair}]`)
+	});
+};
+// src/opening-balance.ts
+const assertEquity = (contra, chart) => {
+	const id = typeof contra === "string" ? contra : contra.accountId;
+	const type = chart.get(accountId(id))?.type;
+	if (type !== void 0 && type !== "equity") throw new LedgerValidationError("NON_EQUITY_CONTRA", typeof contra === "string" ? "contra" : "contra.accountId", id, `is ${type}; an opening balance is posted against an equity account`);
+};
+/**
+* Build an Opening Balance: `amount` posts on `account`, the opposite Posting on the equity
+* `contra`. `amount` is signed (an overdrawn Asset opens negative); direction is never inferred.
+*/
+const openingBalance = (input, chart) => {
+	const postings = [legPosting(input.account, input.amount, chart, "account"), legPosting(input.contra, credited(input.amount), chart, "contra")];
+	assertEquity(input.contra, chart);
+	assertSameCurrency(postings, ["account", "contra"]);
+	return validateTransaction({
+		id: input.id,
+		date: input.date,
+		postings
+	}, chart);
+};
+// src/dimensions.ts
+/** A Posting's value for a Dimension key, or null when it lacks the key. Inherited keys never count. */
+const dimensionOf = (posting, key) => posting.dimensions !== void 0 && Object.hasOwn(posting.dimensions, key) ? posting.dimensions[key] : null;
+/** True when the Posting carries every `where` entry with exactly that value. */
+const matchesAll = (posting, where) => Object.entries(where).every(([key, value]) => dimensionOf(posting, key) === value);
+// src/period.ts
+/** Parse an inclusive period, throwing `INVALID_DATE` for a bad end and `INVALID_PERIOD` if inverted. */
+const parsePeriod = (input) => {
+	const from = input.from === void 0 ? void 0 : parseISODate(input.from, "options.from");
+	const to = parseISODate(input.to, "options.to");
+	if (from !== void 0 && from > to) throw new LedgerValidationError("INVALID_PERIOD", "options.from", input.from, `is after to (${to})`);
+	return from === void 0 ? { to } : {
+		from,
+		to
+	};
+};
+/** True when `date` falls on or between the period's ends. */
+const inPeriod = (period, date) => date <= period.to && (period.from === void 0 || date >= period.from);
+// src/profit-and-loss-rows.ts
+const sumByAccount = (entries) => {
+	const sums = /* @__PURE__ */ new Map();
+	for (const { account, posting } of entries) sums.set(account.id, (sums.get(account.id) ?? 0n) + BigInt(posting.amount));
+	return sums;
+};
+/** One row per Income and Expense Leaf Account, zeros included. */
+const plainRows = (accounts, entries) => {
+	const sums = sumByAccount(entries);
+	return accounts.map((a) => Object.freeze({
+		entityId: a.entityId,
+		accountId: a.id,
+		currency: a.currency,
+		amount: toSafeAmount(sums.get(a.id) ?? 0n, `profitAndLoss.rows[${a.id}]`)
+	})).sort(compareRows);
+};
+const compareGrouped = (a, b) => compareRows(a, b) || (a.dimensionValue === b.dimensionValue ? 0 : a.dimensionValue === null ? -1 : b.dimensionValue === null ? 1 : byCodeUnit(a.dimensionValue, b.dimensionValue));
+/** One row per `(Account, value of the `groupBy` Dimension)` that has Postings. */
+const groupedRows = (entries, groupBy) => {
+	const groups = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const value = dimensionOf(entry.posting, groupBy);
+		const key = JSON.stringify([entry.account.id, value]);
+		const sum = (groups.get(key)?.sum ?? 0n) + BigInt(entry.posting.amount);
+		groups.set(key, {
+			entry,
+			value,
+			sum
+		});
+	}
+	return [...groups.values()].map(({ entry: { account }, value, sum }) => Object.freeze({
+		entityId: account.entityId,
+		accountId: account.id,
+		currency: account.currency,
+		dimensionValue: value,
+		amount: toSafeAmount(sum, `profitAndLoss.rows[${account.id}]`)
+	})).sort(compareGrouped);
+};
+// src/profit-and-loss.ts
+function profitAndLoss(transactions, options, chart) {
+	const period = parsePeriod(options);
+	const entries = scanLedger(transactions, chart).filter(({ account, posting, date }) => (account.type === "income" || account.type === "expense") && inPeriod(period, date) && matchesAll(posting, options.where ?? {}));
+	const { groupBy } = options;
+	const leaves = [...chart.values()].filter((a) => chart.isLeaf(a.id) && (a.type === "income" || a.type === "expense"));
+	const rows = groupBy === void 0 ? plainRows(leaves, entries) : groupedRows(entries, groupBy);
+	const pairs = leaves.map(({ entityId, currency }) => ({
+		entityId,
+		currency,
+		amount: 0
+	}));
+	return Object.freeze({
+		rows: Object.freeze(rows),
+		totals: totalsOf([...pairs, ...rows], -1n, (pair) => `profitAndLoss.totals[${pair}]`)
+	});
+}
+// src/simple.ts
+/** Build a Simple Entry: `+amount` on `debit`, `-amount` on `credit`. `amount` is a magnitude. */
+const simple = (input, chart) => {
+	const amount = magnitude(input.amount, "amount");
+	const postings = [legPosting(input.debit, amount, chart, "debit"), legPosting(input.credit, credited(amount), chart, "credit")];
+	assertSameCurrency(postings, ["debit", "credit"]);
+	return validateTransaction({
+		id: input.id,
+		date: input.date,
+		postings
+	}, chart);
+};
+// src/trial-balance.ts
+/**
+* Every Leaf Account's net Balance at `asOf`, zeros included: positive in `debit`, negative in
+* `credit` as a magnitude (the one exception to raw signed rows).
+*/
+const trialBalance = (transactions, asOf, chart) => {
+	const rows = leafBalances(transactions, asOf, chart, (a) => `trialBalance.rows[${a.id}]`).map(({ entityId, accountId, currency, amount }) => Object.freeze({
+		entityId,
+		accountId,
+		currency,
+		debit: Math.max(amount, 0),
+		credit: Math.max(-amount, 0)
+	}));
+	const debits = totalsOf(rows.map((r) => ({
+		...r,
+		amount: r.debit
+	})), 1n, (pair) => `trialBalance.totals[${pair}].debit`);
+	const credits = new Map(totalsOf(rows.map((r) => ({
+		...r,
+		amount: r.credit
+	})), 1n, (pair) => `trialBalance.totals[${pair}].credit`).map((t) => [JSON.stringify([t.entityId, t.currency]), t.amount]));
+	return Object.freeze({
+		rows: Object.freeze(rows),
+		totals: Object.freeze(debits.map(({ entityId, currency, amount }) => Object.freeze({
+			entityId,
+			currency,
+			debit: amount,
+			credit: credits.get(JSON.stringify([entityId, currency]))
+		})))
+	});
+};
+exports.LedgerValidationError = LedgerValidationError;
+exports.accountId = accountId;
+exports.amend = amend;
+exports.balance = balance;
+exports.balances = balances;
+exports.compound = compound;
+exports.createChartOfAccounts = createChartOfAccounts;
+exports.fromMinorUnits = fromMinorUnits;
+exports.netWorth = netWorth;
+exports.normalBalance = normalBalance;
+exports.openingBalance = openingBalance;
+exports.parseCurrency = parseCurrency;
+exports.parseISODate = parseISODate;
+exports.profitAndLoss = profitAndLoss;
+exports.reverse = reverse;
+exports.simple = simple;
+exports.toMinorUnits = toMinorUnits;
+exports.transactionId = transactionId;
+exports.trialBalance = trialBalance;
+exports.validateTransaction = validateTransaction;
+
+//# sourceMappingURL=index.cjs.map