@classytic/stage 0.3.0 → 0.4.0

package/dist/finance/accounting/verification.d.mts

@@ -0,0 +1,24 @@
+import { AccountingDiagnostic, AccountingPolicy, BankReconciliationItem, BankReconciliationResult, ControlAccountFacts, ControlAccountResult, ExplanationStep, JournalEntry, SuspenseCorrectionFact, SuspenseReconstructionFacts, SuspenseReconstructionResult, TrialBalanceErrorDiagnosis, TrialBalanceErrorType } from "./types.mjs";
+
+//#region src/finance/accounting/verification.d.ts
+declare function reconcileBank({
+  cashBookBalance,
+  bankStatementBalance,
+  items,
+  policy
+}: {
+  cashBookBalance: number;
+  bankStatementBalance: number;
+  items: readonly BankReconciliationItem[];
+  policy?: AccountingPolicy;
+}): BankReconciliationResult;
+declare function solveControlAccount(facts: ControlAccountFacts, policy?: AccountingPolicy): ControlAccountResult;
+declare function diagnoseTrialBalanceError(type: TrialBalanceErrorType): TrialBalanceErrorDiagnosis;
+declare function createSuspenseCorrection(fact: SuspenseCorrectionFact, policy?: AccountingPolicy): {
+  entry?: JournalEntry;
+  diagnostics: AccountingDiagnostic[];
+  trace: ExplanationStep[];
+};
+declare function reconstructSuspenseAccount(facts: SuspenseReconstructionFacts, policy?: AccountingPolicy): SuspenseReconstructionResult;
+//#endregion
+export { createSuspenseCorrection, diagnoseTrialBalanceError, reconcileBank, reconstructSuspenseAccount, solveControlAccount };

package/dist/finance/accounting/verification.mjs

@@ -0,0 +1,386 @@
+import { DEFAULT_ACCOUNTING_POLICY, fromMinor, toMinor } from "./precision.mjs";
+
+//#region src/finance/accounting/verification.ts
+function rounded(value, policy) {
+	return fromMinor(toMinor(value, policy), policy);
+}
+function invalidAmount(id, label) {
+	return {
+		code: "invalid-adjustment",
+		severity: "error",
+		entryId: id,
+		message: `${label} must be a finite non-negative amount.`
+	};
+}
+function invalidBalance(id, label) {
+	return {
+		code: "invalid-adjustment",
+		severity: "error",
+		entryId: id,
+		message: `${label} must be finite; use a negative value for an overdraft.`
+	};
+}
+function reconcileBank({ cashBookBalance, bankStatementBalance, items, policy = DEFAULT_ACCOUNTING_POLICY }) {
+	const diagnostics = [];
+	if (!Number.isFinite(cashBookBalance)) diagnostics.push(invalidBalance("bank-reconciliation", "Cash book balance"));
+	if (!Number.isFinite(bankStatementBalance)) diagnostics.push(invalidBalance("bank-reconciliation", "Bank statement balance"));
+	for (const item of items) if (!Number.isFinite(item.amount) || item.amount < 0) diagnostics.push(invalidAmount(item.id, item.label ?? item.type));
+	if (diagnostics.length > 0) return {
+		adjustedCashBookBalance: 0,
+		reconciledBankStatementBalance: 0,
+		difference: 0,
+		reconciles: false,
+		cashBookAdjustments: [],
+		timingDifferences: [],
+		diagnostics,
+		trace: []
+	};
+	const cashBookAdjustments = items.flatMap((item) => {
+		if (item.type === "bank-credit") return [{
+			id: item.id,
+			label: item.label ?? "Credit shown by bank",
+			amount: item.amount
+		}];
+		if (item.type === "bank-debit") return [{
+			id: item.id,
+			label: item.label ?? "Debit shown by bank",
+			amount: -item.amount
+		}];
+		if (item.type === "cashbook-correction") return [{
+			id: item.id,
+			label: item.label ?? "Cash book correction",
+			amount: item.direction === "increase" ? item.amount : -item.amount
+		}];
+		return [];
+	});
+	const timingDifferences = items.flatMap((item) => {
+		if (item.type === "deposit-in-transit") return [{
+			id: item.id,
+			label: item.label ?? "Deposit in transit",
+			amount: item.amount
+		}];
+		if (item.type === "unpresented-cheque") return [{
+			id: item.id,
+			label: item.label ?? "Unpresented cheque",
+			amount: -item.amount
+		}];
+		return [];
+	});
+	const adjustedCashBookBalance = rounded(cashBookBalance + cashBookAdjustments.reduce((sum, item) => sum + item.amount, 0), policy);
+	const reconciledBankStatementBalance = rounded(bankStatementBalance + timingDifferences.reduce((sum, item) => sum + item.amount, 0), policy);
+	const difference = rounded(adjustedCashBookBalance - reconciledBankStatementBalance, policy);
+	const trace = [
+		{
+			id: "bank:cashbook",
+			kind: "derive",
+			rule: "Update the cash book only for bank-originated items and cash-book errors.",
+			working: `${cashBookBalance} + (${cashBookAdjustments.map((item) => item.amount).join(" + ") || 0})`,
+			result: adjustedCashBookBalance
+		},
+		{
+			id: "bank:timing",
+			kind: "derive",
+			rule: "Use timing differences only in the reconciliation statement.",
+			working: `${bankStatementBalance} + (${timingDifferences.map((item) => item.amount).join(" + ") || 0})`,
+			result: reconciledBankStatementBalance
+		},
+		{
+			id: "bank:check",
+			kind: "check",
+			rule: "The adjusted cash book and reconciled bank statement should agree.",
+			working: `${adjustedCashBookBalance} − ${reconciledBankStatementBalance}`,
+			result: difference === 0
+		}
+	];
+	return {
+		adjustedCashBookBalance,
+		reconciledBankStatementBalance,
+		difference,
+		reconciles: difference === 0,
+		cashBookAdjustments,
+		timingDifferences,
+		diagnostics,
+		trace
+	};
+}
+function solveControlAccount(facts, policy = DEFAULT_ACCOUNTING_POLICY) {
+	const diagnostics = [
+		facts.openingBalance,
+		facts.creditTransactions,
+		facts.cashSettled,
+		facts.returns,
+		facts.discounts,
+		facts.contra,
+		facts.writeOffs ?? 0,
+		facts.dishonouredPayments ?? 0,
+		facts.otherCharges ?? 0
+	].some((value) => !Number.isFinite(value) || value < 0) ? [invalidAmount(`${facts.kind}-control`, "Control-account movement")] : [];
+	if (diagnostics.length > 0) return {
+		closingBalance: 0,
+		movements: [],
+		diagnostics,
+		trace: []
+	};
+	const increases = facts.openingBalance + facts.creditTransactions + (facts.dishonouredPayments ?? 0) + (facts.otherCharges ?? 0);
+	const decreases = facts.cashSettled + facts.returns + facts.discounts + facts.contra + (facts.writeOffs ?? 0);
+	const closingBalance = rounded(increases - decreases, policy);
+	const increaseSide = facts.kind === "receivables" ? "debit" : "credit";
+	const decreaseSide = facts.kind === "receivables" ? "credit" : "debit";
+	const movements = [
+		{
+			label: "Opening balance",
+			side: increaseSide,
+			amount: facts.openingBalance
+		},
+		{
+			label: facts.kind === "receivables" ? "Credit sales" : "Credit purchases",
+			side: increaseSide,
+			amount: facts.creditTransactions
+		},
+		{
+			label: "Dishonoured payments",
+			side: increaseSide,
+			amount: facts.dishonouredPayments ?? 0
+		},
+		{
+			label: "Other charges",
+			side: increaseSide,
+			amount: facts.otherCharges ?? 0
+		},
+		{
+			label: "Cash settled",
+			side: decreaseSide,
+			amount: facts.cashSettled
+		},
+		{
+			label: "Returns",
+			side: decreaseSide,
+			amount: facts.returns
+		},
+		{
+			label: "Discounts",
+			side: decreaseSide,
+			amount: facts.discounts
+		},
+		{
+			label: "Contra",
+			side: decreaseSide,
+			amount: facts.contra
+		},
+		{
+			label: "Write-offs",
+			side: decreaseSide,
+			amount: facts.writeOffs ?? 0
+		}
+	].filter((item) => item.amount !== 0);
+	const expected = facts.expectedClosingBalance;
+	const difference = expected == null ? void 0 : rounded(closingBalance - expected, policy);
+	const trace = [{
+		id: `${facts.kind}:derive`,
+		kind: "derive",
+		rule: `Closing ${facts.kind} control balance = opening balance + credit transactions and restorations − settlements and reductions.`,
+		working: `${increases} − ${decreases}`,
+		result: closingBalance
+	}];
+	if (expected != null) trace.push({
+		id: `${facts.kind}:check`,
+		kind: "check",
+		rule: "Compare the control account with the independently prepared list balance.",
+		working: `${closingBalance} − ${expected}`,
+		result: difference === 0
+	});
+	return {
+		closingBalance,
+		expectedClosingBalance: expected,
+		difference,
+		agrees: difference == null ? void 0 : difference === 0,
+		movements,
+		diagnostics,
+		trace
+	};
+}
+const ERROR_RULES = {
+	"complete-omission": {
+		affectsAgreement: false,
+		requiresSuspense: false,
+		reason: "Neither the debit nor credit was recorded."
+	},
+	commission: {
+		affectsAgreement: false,
+		requiresSuspense: false,
+		reason: "Both sides were recorded, but the correct class contains the wrong personal account."
+	},
+	principle: {
+		affectsAgreement: false,
+		requiresSuspense: false,
+		reason: "Both sides were recorded, but an account of the wrong category was used."
+	},
+	"original-entry": {
+		affectsAgreement: false,
+		requiresSuspense: false,
+		reason: "The same incorrect amount was entered on both sides."
+	},
+	"complete-reversal": {
+		affectsAgreement: false,
+		requiresSuspense: false,
+		reason: "Equal debit and credit amounts were posted to the opposite sides."
+	},
+	compensating: {
+		affectsAgreement: false,
+		requiresSuspense: false,
+		reason: "Independent errors cancel by the same amount."
+	},
+	"one-sided-entry": {
+		affectsAgreement: true,
+		requiresSuspense: true,
+		reason: "Only one half of the double entry was recorded."
+	},
+	"unequal-entry": {
+		affectsAgreement: true,
+		requiresSuspense: true,
+		reason: "The debit and credit amounts differ."
+	},
+	"casting-error": {
+		affectsAgreement: true,
+		requiresSuspense: true,
+		reason: "A book or account total was added incorrectly on one side."
+	},
+	"balance-omitted": {
+		affectsAgreement: true,
+		requiresSuspense: true,
+		reason: "An account balance was omitted from the trial balance."
+	}
+};
+function diagnoseTrialBalanceError(type) {
+	return {
+		type,
+		...ERROR_RULES[type]
+	};
+}
+function createSuspenseCorrection(fact, policy = DEFAULT_ACCOUNTING_POLICY) {
+	if (!Number.isFinite(fact.amount) || fact.amount <= 0) return {
+		diagnostics: [invalidAmount(fact.id, "Suspense correction")],
+		trace: []
+	};
+	const amount = rounded(fact.amount, policy);
+	const otherSide = fact.missingSide === "debit" ? "credit" : "debit";
+	return {
+		entry: {
+			id: fact.id,
+			narration: fact.narration ?? "Clear suspense difference",
+			lines: [{
+				accountId: fact.affectedAccountId,
+				side: fact.missingSide,
+				amount
+			}, {
+				accountId: fact.suspenseAccountId,
+				side: otherSide,
+				amount
+			}]
+		},
+		diagnostics: [],
+		trace: [{
+			id: `${fact.id}:suspense`,
+			kind: "journalize",
+			rule: "Post the missing side and use the opposite suspense entry to clear the temporary difference.",
+			working: `${fact.missingSide} ${fact.affectedAccountId}; ${otherSide} ${fact.suspenseAccountId}`,
+			result: amount
+		}]
+	};
+}
+function reconstructSuspenseAccount(facts, policy = DEFAULT_ACCOUNTING_POLICY) {
+	const diagnostics = [];
+	if (!Number.isFinite(facts.trialBalanceDebitTotal) || facts.trialBalanceDebitTotal < 0) diagnostics.push(invalidAmount("suspense-reconstruction", "Trial balance debit total"));
+	if (!Number.isFinite(facts.trialBalanceCreditTotal) || facts.trialBalanceCreditTotal < 0) diagnostics.push(invalidAmount("suspense-reconstruction", "Trial balance credit total"));
+	const duplicateIds = facts.errors.filter((error, index) => facts.errors.findIndex((candidate) => candidate.id === error.id) !== index);
+	for (const error of duplicateIds) diagnostics.push({
+		code: "invalid-adjustment",
+		severity: "error",
+		entryId: error.id,
+		message: `Duplicate suspense error id: ${error.id}.`
+	});
+	for (const error of facts.errors) if (!diagnoseTrialBalanceError(error.errorType).requiresSuspense) diagnostics.push({
+		code: "invalid-adjustment",
+		severity: "error",
+		entryId: error.id,
+		message: `${error.errorType} does not affect trial-balance agreement and must not be posted through suspense.`
+	});
+	if (diagnostics.length > 0) return {
+		openingBalance: {
+			side: "zero",
+			amount: 0
+		},
+		corrections: [],
+		movements: [],
+		closingBalance: {
+			side: "zero",
+			amount: 0
+		},
+		clears: false,
+		diagnostics,
+		trace: []
+	};
+	const debitTotal = toMinor(facts.trialBalanceDebitTotal, policy);
+	const difference = toMinor(facts.trialBalanceCreditTotal, policy) - debitTotal;
+	const openingBalance = {
+		side: difference === 0 ? "zero" : difference > 0 ? "debit" : "credit",
+		amount: fromMinor(Math.abs(difference), policy)
+	};
+	const movements = openingBalance.side === "zero" ? [] : [{
+		id: "opening-suspense",
+		label: "Trial balance difference",
+		side: openingBalance.side,
+		amount: openingBalance.amount
+	}];
+	const corrections = [];
+	const trace = [{
+		id: "suspense:opening",
+		kind: "derive",
+		rule: "Place the trial-balance difference on the smaller side so the trial balance agrees temporarily.",
+		working: `${facts.trialBalanceDebitTotal} debit compared with ${facts.trialBalanceCreditTotal} credit`,
+		result: `${openingBalance.side} ${openingBalance.amount}`
+	}];
+	for (const error of facts.errors) {
+		const correction = createSuspenseCorrection({
+			...error,
+			suspenseAccountId: facts.suspenseAccountId
+		}, policy);
+		diagnostics.push(...correction.diagnostics);
+		trace.push(...correction.trace);
+		if (!correction.entry) continue;
+		corrections.push(correction.entry);
+		const suspenseLine = correction.entry.lines.find((line) => line.accountId === facts.suspenseAccountId);
+		movements.push({
+			id: error.id,
+			label: error.label ?? error.narration ?? error.errorType,
+			side: suspenseLine.side,
+			amount: suspenseLine.amount
+		});
+	}
+	const debitMovements = movements.filter((movement) => movement.side === "debit").reduce((sum, movement) => sum + toMinor(movement.amount, policy), 0);
+	const creditMovements = movements.filter((movement) => movement.side === "credit").reduce((sum, movement) => sum + toMinor(movement.amount, policy), 0);
+	const residual = debitMovements - creditMovements;
+	const closingBalance = {
+		side: residual === 0 ? "zero" : residual > 0 ? "debit" : "credit",
+		amount: fromMinor(Math.abs(residual), policy)
+	};
+	trace.push({
+		id: "suspense:closing",
+		kind: "check",
+		rule: "All agreement-affecting corrections clear suspense only when its debit and credit movements are equal.",
+		working: `${fromMinor(debitMovements, policy)} debit − ${fromMinor(creditMovements, policy)} credit`,
+		result: residual === 0
+	});
+	return {
+		openingBalance,
+		corrections,
+		movements,
+		closingBalance,
+		clears: residual === 0,
+		diagnostics,
+		trace
+	};
+}
+
+//#endregion
+export { createSuspenseCorrection, diagnoseTrialBalanceError, reconcileBank, reconstructSuspenseAccount, solveControlAccount };

package/dist/finance/bizsim.d.mts

@@ -1,37 +1,21 @@
+import { AccountingSolution, JournalEntry } from "./accounting/types.mjs";
+
 //#region src/finance/bizsim.d.ts
-/**
- * bizsim — a tiny, always-balanced business-simulation engine (part of `finance`).
- *
- * This is the PRIMITIVE a "run a business" story lesson is built on: a teacher/creator
- * authors a scenario as a sequence of business ACTIONS (invest capital, take a loan,
- * buy equipment, buy stock, sell, pay an expense, depreciate, close the period). Each
- * action is a pure, DOUBLE-ENTRY-BALANCED transform of the business state, so the
- * derived income statement and balance sheet are always correct and the balance sheet
- * always balances — no accounting knowledge required to author, and it scales all the
- * way to financial analysis (ratios) at the end.
- *
- * The engine is content-neutral: it knows nothing about samosas, apps or coffee — the
- * creator supplies the story and the numbers.
- */
+interface BizOpeningBalances {
+  cash?: number;
+  inventoryQty?: number;
+  inventoryValue?: number;
+  equipment?: number;
+  loan?: number;
+  capital?: number;
+  retained?: number;
+}
+/** Journal is the accounting authority; quantity is the operational inventory fact. */
 interface BizState {
-  cash: number;
-  /** Stock on hand: quantity and its value at cost. */
+  entries: readonly JournalEntry[];
   inventoryQty: number;
-  inventoryValue: number;
-  /** Fixed assets at book value. */
-  equipment: number;
-  /** Liabilities (loans). */
-  loan: number;
-  /** Owner capital contributed. */
-  capital: number;
-  /** Accumulated profit from closed periods. */
-  retained: number;
-  /** Current open-period tallies (become net profit at closePeriod). */
-  revenue: number;
-  cogs: number;
-  expenses: number;
+  nextEntryNumber: number;
 }
-declare const initialBiz: (over?: Partial<BizState>) => BizState;
 type BizAction = {
   type: 'invest';
   amount: number;
@@ -61,10 +45,9 @@ type BizAction = {
 } | {
   type: 'closePeriod';
 };
-/** Apply one action; pure and balance-preserving (assets = liabilities + equity). */
-declare function applyBiz(s: BizState, a: BizAction): BizState;
-/** Run a whole authored scenario from an (optional) starting state. */
-declare function runBiz(actions: BizAction[], init?: Partial<BizState>): BizState;
+declare function initialBiz(opening?: BizOpeningBalances): BizState;
+declare function applyBiz(state: BizState, action: BizAction): BizState;
+declare function runBiz(actions: readonly BizAction[], opening?: BizOpeningBalances): BizState;
 interface IncomeStatement {
   revenue: number;
   cogs: number;
@@ -72,8 +55,7 @@ interface IncomeStatement {
   expenses: number;
   netProfit: number;
 }
-/** Income statement for the current open period. */
-declare function incomeStatement(s: BizState): IncomeStatement;
+declare function incomeStatement(state: BizState): IncomeStatement;
 interface BalanceSheet {
   cash: number;
   inventory: number;
@@ -87,7 +69,7 @@ interface BalanceSheet {
   totalLiabilitiesEquity: number;
   balances: boolean;
 }
-/** Balance sheet; `balances` is always true by construction (a self-check). */
-declare function balanceSheet(s: BizState): BalanceSheet;
+declare function balanceSheet(state: BizState): BalanceSheet;
+declare function businessBooks(state: BizState): AccountingSolution;
 //#endregion
-export { BalanceSheet, BizAction, BizState, IncomeStatement, applyBiz, balanceSheet, incomeStatement, initialBiz, runBiz };
+export { BalanceSheet, BizAction, BizOpeningBalances, BizState, IncomeStatement, applyBiz, balanceSheet, businessBooks, incomeStatement, initialBiz, runBiz };