@classytic/stage 0.3.0 → 0.4.0

package/dist/finance/management-accounting/decisions.mjs

@@ -0,0 +1,164 @@
+import { fromMinor, toMinor } from "../accounting/precision.mjs";
+
+//#region src/finance/management-accounting/decisions.ts
+const DEFAULT_POLICY = { decimalPlaces: 2 };
+function optimizeLimitedFactor(products, resourceAvailable, policy = DEFAULT_POLICY) {
+	const diagnostics = [];
+	if (!Number.isFinite(resourceAvailable) || resourceAvailable < 0) diagnostics.push({
+		code: "invalid-input",
+		severity: "error",
+		message: "Available scarce resource must be finite and non-negative."
+	});
+	const seen = /* @__PURE__ */ new Set();
+	for (const product of products) {
+		if (seen.has(product.id)) diagnostics.push({
+			code: "duplicate-product",
+			severity: "error",
+			productId: product.id,
+			message: `Product ${product.id} is duplicated.`
+		});
+		seen.add(product.id);
+		if (![
+			product.sellingPricePerUnit,
+			product.variableCostPerUnit,
+			product.scarceResourcePerUnit,
+			product.maximumDemandUnits
+		].every((value) => Number.isFinite(value) && value >= 0)) diagnostics.push({
+			code: "invalid-input",
+			severity: "error",
+			productId: product.id,
+			message: `${product.label} assumptions must be finite and non-negative.`
+		});
+	}
+	if (diagnostics.length > 0) return {
+		completed: false,
+		resourceAvailable,
+		resourceUsed: 0,
+		unusedResource: 0,
+		totalContribution: 0,
+		allocations: [],
+		diagnostics,
+		trace: []
+	};
+	const ranked = products.map((product) => {
+		const contributionPerUnit = money(product.sellingPricePerUnit - product.variableCostPerUnit, policy);
+		return {
+			product,
+			contributionPerUnit,
+			contributionPerResourceUnit: product.scarceResourcePerUnit === 0 ? "unconstrained" : money(contributionPerUnit / product.scarceResourcePerUnit, policy)
+		};
+	}).sort((left, right) => score(right.contributionPerResourceUnit) - score(left.contributionPerResourceUnit) || left.product.id.localeCompare(right.product.id));
+	let remaining = resourceAvailable;
+	const allocations = ranked.map((item, index) => {
+		const allocatedUnits = !(item.contributionPerUnit > 0) ? 0 : item.product.scarceResourcePerUnit === 0 ? item.product.maximumDemandUnits : Math.min(item.product.maximumDemandUnits, remaining / item.product.scarceResourcePerUnit);
+		const resourceUsed = allocatedUnits * item.product.scarceResourcePerUnit;
+		remaining = Math.max(0, remaining - resourceUsed);
+		return {
+			productId: item.product.id,
+			label: item.product.label,
+			contributionPerUnit: item.contributionPerUnit,
+			contributionPerResourceUnit: item.contributionPerResourceUnit,
+			allocatedUnits,
+			resourceUsed,
+			contribution: money(allocatedUnits * item.contributionPerUnit, policy),
+			rank: index + 1
+		};
+	});
+	const resourceUsed = resourceAvailable - remaining;
+	const totalContribution = money(allocations.reduce((total, allocation) => total + allocation.contribution, 0), policy);
+	const trace = allocations.map((allocation) => ({
+		id: `limited:${allocation.productId}`,
+		kind: "derive",
+		rule: "Rank positive contribution by contribution per scarce-resource unit, then satisfy demand in rank order.",
+		working: `${allocation.allocatedUnits} units × ${allocation.contributionPerUnit} contribution`,
+		result: allocation.contribution
+	}));
+	return {
+		completed: true,
+		resourceAvailable,
+		resourceUsed,
+		unusedResource: remaining,
+		totalContribution,
+		allocations,
+		diagnostics,
+		trace
+	};
+}
+function evaluateRelevantCostDecision(alternatives, policy = DEFAULT_POLICY) {
+	const diagnostics = [];
+	if (alternatives.length < 2) diagnostics.push({
+		code: "insufficient-alternatives",
+		severity: "error",
+		message: "A decision requires at least two alternatives."
+	});
+	const alternativeIds = /* @__PURE__ */ new Set();
+	for (const alternative of alternatives) {
+		if (alternativeIds.has(alternative.id)) diagnostics.push({
+			code: "duplicate-alternative",
+			severity: "error",
+			alternativeId: alternative.id,
+			message: `Alternative ${alternative.id} is duplicated.`
+		});
+		alternativeIds.add(alternative.id);
+		const flowIds = /* @__PURE__ */ new Set();
+		for (const flow of alternative.cashFlows) {
+			if (flowIds.has(flow.id)) diagnostics.push({
+				code: "duplicate-cash-flow",
+				severity: "error",
+				alternativeId: alternative.id,
+				message: `Cash flow ${flow.id} is duplicated within ${alternative.label}.`
+			});
+			flowIds.add(flow.id);
+			if (!Number.isFinite(flow.amount) || flow.amount < 0) diagnostics.push({
+				code: "invalid-input",
+				severity: "error",
+				alternativeId: alternative.id,
+				message: `${flow.label} must be finite and non-negative.`
+			});
+		}
+	}
+	if (diagnostics.length > 0) return {
+		completed: false,
+		alternatives: [],
+		advantageOverNextBest: 0,
+		diagnostics,
+		trace: []
+	};
+	const results = alternatives.map((alternative) => {
+		const included = alternative.cashFlows.filter(isRelevant);
+		const excluded = alternative.cashFlows.filter((flow) => !isRelevant(flow));
+		const relevantBenefit = money(included.filter((flow) => flow.kind === "incremental-revenue" || flow.kind === "avoidable-cost").reduce((total, flow) => total + flow.amount, 0), policy);
+		const relevantCost = money(included.filter((flow) => flow.kind === "incremental-cost" || flow.kind === "opportunity-cost").reduce((total, flow) => total + flow.amount, 0), policy);
+		return {
+			id: alternative.id,
+			label: alternative.label,
+			relevantBenefit,
+			relevantCost,
+			netBenefit: money(relevantBenefit - relevantCost, policy),
+			included,
+			excluded
+		};
+	}).sort((left, right) => right.netBenefit - left.netBenefit || left.id.localeCompare(right.id));
+	const advantageOverNextBest = money(results[0].netBenefit - results[1].netBenefit, policy);
+	const trace = results.map((alternative) => ({
+		id: `relevant:${alternative.id}`,
+		kind: "derive",
+		rule: "Net relevant benefit includes future cash flows that differ between alternatives; sunk and unavoidable allocated costs are excluded.",
+		working: `${alternative.relevantBenefit} benefits − ${alternative.relevantCost} costs`,
+		result: alternative.netBenefit
+	}));
+	return {
+		completed: true,
+		alternatives: results,
+		recommendedAlternativeId: results[0].id,
+		advantageOverNextBest,
+		diagnostics,
+		trace
+	};
+}
+const isRelevant = (flow) => flow.kind !== "sunk-cost" && flow.kind !== "unavoidable-allocated-cost";
+const money = (value, policy) => fromMinor(toMinor(value, policy), policy);
+const score = (value) => value === "unconstrained" ? Number.POSITIVE_INFINITY : value;
+
+//#endregion
+export { evaluateRelevantCostDecision, optimizeLimitedFactor };

package/dist/finance/management-accounting/index.d.mts

@@ -0,0 +1,13 @@
+import { BudgetPeriodInput, CashBudgetFacts, CashBudgetPeriod, CashBudgetPeriodInput, CashBudgetResult, CashTimingAllocation, ClassifiedCost, CostBehavior, CostClassificationSummary, CostFunction, CostTraceability, CostVariance, CostVarianceFacts, CostVarianceResult, CostingStatement, IntegratedBudgetCashAdjustment, IntegratedMasterBudgetFacts, IntegratedMasterBudgetResult, InventoryCostLayer, InventoryCostingDiagnostic, InventoryCostingMethod, InventoryCostingMovement, InventoryCostingResult, InventoryLayerConsumption, InventoryTransaction, InvestmentAccountingProfit, InvestmentAppraisalFacts, InvestmentAppraisalPeriod, InvestmentAppraisalResult, InvestmentCashFlow, JobBatchCostFacts, JobBatchCostResult, LimitedFactorAllocation, LimitedFactorProduct, LimitedFactorResult, ManagementAccountingCase, ManagementAccountingCaseResult, ManagementCaseSolution, ManagementCaseTask, ManagementCaseTaskResult, MarginalAbsorptionFacts, MarginalAbsorptionResult, MasterBudgetFacts, MasterBudgetPeriod, MasterBudgetPeriodPolicy, MasterBudgetResult, OperatingBudgetFacts, OperatingBudgetPeriod, OperatingBudgetResult, ProcessCostFacts, ProcessCostResult, RelevantCashFlow, RelevantCashFlowKind, RelevantCostAlternative, RelevantCostAlternativeResult, RelevantCostDecisionResult } from "./types.mjs";
+import { costInventory } from "./inventory-costing.mjs";
+import { compareMarginalAndAbsorptionCosting, summarizeClassifiedCosts } from "./costing.mjs";
+import { buildOperatingBudget } from "./budgeting.mjs";
+import { buildCashBudget } from "./cash-budget.mjs";
+import { composeMasterBudget } from "./master-budget.mjs";
+import { buildIntegratedMasterBudget } from "./integrated-budget.mjs";
+import { analyzeCostVariances } from "./variances.mjs";
+import { evaluateRelevantCostDecision, optimizeLimitedFactor } from "./decisions.mjs";
+import { appraiseInvestment } from "./investment-appraisal.mjs";
+import { costJobOrBatch, costProcessWithLosses } from "./production-costing.mjs";
+import { runManagementAccountingCase } from "./management-case.mjs";
+export { BudgetPeriodInput, CashBudgetFacts, CashBudgetPeriod, CashBudgetPeriodInput, CashBudgetResult, CashTimingAllocation, ClassifiedCost, CostBehavior, CostClassificationSummary, CostFunction, CostTraceability, CostVariance, CostVarianceFacts, CostVarianceResult, CostingStatement, IntegratedBudgetCashAdjustment, IntegratedMasterBudgetFacts, IntegratedMasterBudgetResult, InventoryCostLayer, InventoryCostingDiagnostic, InventoryCostingMethod, InventoryCostingMovement, InventoryCostingResult, InventoryLayerConsumption, InventoryTransaction, InvestmentAccountingProfit, InvestmentAppraisalFacts, InvestmentAppraisalPeriod, InvestmentAppraisalResult, InvestmentCashFlow, JobBatchCostFacts, JobBatchCostResult, LimitedFactorAllocation, LimitedFactorProduct, LimitedFactorResult, ManagementAccountingCase, ManagementAccountingCaseResult, ManagementCaseSolution, ManagementCaseTask, ManagementCaseTaskResult, MarginalAbsorptionFacts, MarginalAbsorptionResult, MasterBudgetFacts, MasterBudgetPeriod, MasterBudgetPeriodPolicy, MasterBudgetResult, OperatingBudgetFacts, OperatingBudgetPeriod, OperatingBudgetResult, ProcessCostFacts, ProcessCostResult, RelevantCashFlow, RelevantCashFlowKind, RelevantCostAlternative, RelevantCostAlternativeResult, RelevantCostDecisionResult, analyzeCostVariances, appraiseInvestment, buildCashBudget, buildIntegratedMasterBudget, buildOperatingBudget, compareMarginalAndAbsorptionCosting, composeMasterBudget, costInventory, costJobOrBatch, costProcessWithLosses, evaluateRelevantCostDecision, optimizeLimitedFactor, runManagementAccountingCase, summarizeClassifiedCosts };

package/dist/finance/management-accounting/index.mjs

@@ -0,0 +1,13 @@
+import { costInventory } from "./inventory-costing.mjs";
+import { compareMarginalAndAbsorptionCosting, summarizeClassifiedCosts } from "./costing.mjs";
+import { buildOperatingBudget } from "./budgeting.mjs";
+import { buildCashBudget } from "./cash-budget.mjs";
+import { composeMasterBudget } from "./master-budget.mjs";
+import { buildIntegratedMasterBudget } from "./integrated-budget.mjs";
+import { analyzeCostVariances } from "./variances.mjs";
+import { evaluateRelevantCostDecision, optimizeLimitedFactor } from "./decisions.mjs";
+import { appraiseInvestment } from "./investment-appraisal.mjs";
+import { costJobOrBatch, costProcessWithLosses } from "./production-costing.mjs";
+import { runManagementAccountingCase } from "./management-case.mjs";
+
+export { analyzeCostVariances, appraiseInvestment, buildCashBudget, buildIntegratedMasterBudget, buildOperatingBudget, compareMarginalAndAbsorptionCosting, composeMasterBudget, costInventory, costJobOrBatch, costProcessWithLosses, evaluateRelevantCostDecision, optimizeLimitedFactor, runManagementAccountingCase, summarizeClassifiedCosts };

package/dist/finance/management-accounting/integrated-budget.d.mts

@@ -0,0 +1,8 @@
+import { AccountingPolicy } from "../accounting/types.mjs";
+import { IntegratedMasterBudgetFacts, IntegratedMasterBudgetResult } from "./types.mjs";
+
+//#region src/finance/management-accounting/integrated-budget.d.ts
+/** Builds every linked schedule from one assumption set so consumers never hand-wire period results. */
+declare function buildIntegratedMasterBudget(facts: IntegratedMasterBudgetFacts, policy?: AccountingPolicy): IntegratedMasterBudgetResult;
+//#endregion
+export { buildIntegratedMasterBudget };

package/dist/finance/management-accounting/integrated-budget.mjs

@@ -0,0 +1,67 @@
+import { buildOperatingBudget } from "./budgeting.mjs";
+import { buildCashBudget } from "./cash-budget.mjs";
+import { composeMasterBudget } from "./master-budget.mjs";
+
+//#region src/finance/management-accounting/integrated-budget.ts
+const DEFAULT_POLICY = { decimalPlaces: 2 };
+/** Builds every linked schedule from one assumption set so consumers never hand-wire period results. */
+function buildIntegratedMasterBudget(facts, policy = DEFAULT_POLICY) {
+	const operating = buildOperatingBudget(facts.operating, policy);
+	const adjustments = new Map((facts.cashAdjustments ?? []).map((adjustment) => [adjustment.periodId, adjustment]));
+	const bridgeDiagnostics = [];
+	for (const adjustment of facts.cashAdjustments ?? []) if (!facts.operating.periods.some((period) => period.id === adjustment.periodId)) bridgeDiagnostics.push({
+		code: "period-mismatch",
+		severity: "error",
+		periodId: adjustment.periodId,
+		message: `Cash adjustment references unknown period ${adjustment.periodId}.`
+	});
+	const cash = buildCashBudget({
+		openingCashBalance: facts.openingCashBalance,
+		minimumCashBalance: facts.minimumCashBalance,
+		collectionProfile: facts.collectionProfile,
+		materialPaymentProfile: facts.materialPaymentProfile,
+		periods: operating.periods.map((period) => {
+			const adjustment = adjustments.get(period.id);
+			return {
+				id: period.id,
+				label: period.label,
+				salesRevenue: period.sales.revenue,
+				materialPurchases: period.materialsPurchases.purchaseCost,
+				labourCost: period.directLabour.labourCost,
+				productionOverhead: period.productionOverhead.totalOverhead,
+				...adjustment?.nonCashProductionOverhead == null ? {} : { nonCashProductionOverhead: adjustment.nonCashProductionOverhead },
+				...adjustment?.broughtForwardReceipts == null ? {} : { broughtForwardReceipts: adjustment.broughtForwardReceipts },
+				...adjustment?.broughtForwardPayments == null ? {} : { broughtForwardPayments: adjustment.broughtForwardPayments },
+				...adjustment?.otherReceipts == null ? {} : { otherReceipts: adjustment.otherReceipts },
+				...adjustment?.otherPayments == null ? {} : { otherPayments: adjustment.otherPayments }
+			};
+		})
+	}, policy);
+	const master = composeMasterBudget({
+		operating,
+		cash,
+		openingFinishedGoodsValue: facts.openingFinishedGoodsValue,
+		periodPolicies: facts.periodPolicies
+	}, policy);
+	const diagnostics = [
+		...operating.diagnostics,
+		...cash.diagnostics,
+		...master.diagnostics,
+		...bridgeDiagnostics
+	];
+	return {
+		completed: diagnostics.length === 0 && master.completed,
+		operating,
+		cash,
+		master,
+		diagnostics,
+		trace: [
+			...operating.trace,
+			...cash.trace,
+			...master.trace
+		]
+	};
+}
+
+//#endregion
+export { buildIntegratedMasterBudget };

package/dist/finance/management-accounting/inventory-costing.d.mts

@@ -0,0 +1,7 @@
+import { AccountingPolicy } from "../accounting/types.mjs";
+import { InventoryCostingMethod, InventoryCostingResult, InventoryTransaction } from "./types.mjs";
+
+//#region src/finance/management-accounting/inventory-costing.d.ts
+declare function costInventory(method: InventoryCostingMethod, transactions: readonly InventoryTransaction[], policy?: AccountingPolicy): InventoryCostingResult;
+//#endregion
+export { costInventory };

package/dist/finance/management-accounting/inventory-costing.mjs

@@ -0,0 +1,173 @@
+import { fromMinor, toMinor } from "../accounting/precision.mjs";
+
+//#region src/finance/management-accounting/inventory-costing.ts
+const DEFAULT_POLICY = { decimalPlaces: 2 };
+function publicLayer(layer, policy) {
+	const value = fromMinor(layer.valueMinor, policy);
+	return {
+		sourceId: layer.sourceId,
+		quantity: layer.quantity,
+		value,
+		unitCost: layer.quantity === 0 ? 0 : value / layer.quantity
+	};
+}
+const totalValue = (layers) => layers.reduce((total, layer) => total + layer.valueMinor, 0);
+function costInventory(method, transactions, policy = DEFAULT_POLICY) {
+	const diagnostics = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const transaction of transactions) {
+		if (seen.has(transaction.id)) diagnostics.push({
+			code: "duplicate-transaction",
+			severity: "error",
+			transactionId: transaction.id,
+			message: `Transaction ${transaction.id} is duplicated.`
+		});
+		seen.add(transaction.id);
+		if (!Number.isFinite(transaction.quantity) || transaction.quantity <= 0) diagnostics.push({
+			code: "invalid-quantity",
+			severity: "error",
+			transactionId: transaction.id,
+			message: "Inventory quantity must be finite and positive."
+		});
+		if (transaction.type === "receipt" && (!Number.isFinite(transaction.unitCost) || transaction.unitCost < 0)) diagnostics.push({
+			code: "invalid-unit-cost",
+			severity: "error",
+			transactionId: transaction.id,
+			message: "Receipt unit cost must be finite and non-negative."
+		});
+	}
+	if (diagnostics.length > 0) return {
+		method,
+		completed: false,
+		movements: [],
+		costOfSales: 0,
+		closingQuantity: 0,
+		closingValue: 0,
+		closingLayers: [],
+		diagnostics,
+		trace: []
+	};
+	let layers = [];
+	let costOfSalesMinor = 0;
+	const movements = [];
+	const trace = [];
+	for (const transaction of transactions) {
+		const available = layers.reduce((total, layer) => total + layer.quantity, 0);
+		if (transaction.type === "issue" && transaction.quantity > available) {
+			diagnostics.push({
+				code: "insufficient-inventory",
+				severity: "error",
+				transactionId: transaction.id,
+				message: `Cannot issue ${transaction.quantity}; only ${available} unit(s) are available.`
+			});
+			break;
+		}
+		let issueCostMinor = 0;
+		const consumedLayers = [];
+		if (transaction.type === "receipt") {
+			const receiptValueMinor = toMinor(transaction.quantity * transaction.unitCost, policy);
+			if (method === "fifo") layers.push({
+				sourceId: transaction.id,
+				quantity: transaction.quantity,
+				valueMinor: receiptValueMinor
+			});
+			else layers = [{
+				sourceId: "avco-pool",
+				quantity: available + transaction.quantity,
+				valueMinor: totalValue(layers) + receiptValueMinor
+			}];
+			trace.push({
+				id: `${transaction.id}:receipt`,
+				kind: "derive",
+				rule: method === "fifo" ? "A receipt creates a new chronological cost layer." : "A receipt joins the pool and changes the weighted-average cost.",
+				working: `${transaction.quantity} × ${transaction.unitCost}`,
+				result: fromMinor(receiptValueMinor, policy)
+			});
+		} else if (method === "fifo") {
+			let required = transaction.quantity;
+			while (required > 0) {
+				const layer = layers[0];
+				const taken = Math.min(required, layer.quantity);
+				const takenValue = taken === layer.quantity ? layer.valueMinor : Math.round(layer.valueMinor * taken / layer.quantity);
+				const value = fromMinor(takenValue, policy);
+				consumedLayers.push({
+					sourceId: layer.sourceId,
+					quantity: taken,
+					value,
+					unitCost: value / taken
+				});
+				issueCostMinor += takenValue;
+				layer.quantity -= taken;
+				layer.valueMinor -= takenValue;
+				required -= taken;
+				if (layer.quantity === 0) layers.shift();
+			}
+			trace.push({
+				id: `${transaction.id}:issue`,
+				kind: "derive",
+				rule: "FIFO issues the oldest available cost layer first.",
+				working: consumedLayers.map((layer) => `${layer.quantity} from ${layer.sourceId}`).join(" + "),
+				result: fromMinor(issueCostMinor, policy)
+			});
+		} else {
+			const pool = layers[0];
+			issueCostMinor = transaction.quantity === pool.quantity ? pool.valueMinor : Math.round(pool.valueMinor * transaction.quantity / pool.quantity);
+			const value = fromMinor(issueCostMinor, policy);
+			consumedLayers.push({
+				sourceId: pool.sourceId,
+				quantity: transaction.quantity,
+				value,
+				unitCost: value / transaction.quantity
+			});
+			pool.quantity -= transaction.quantity;
+			pool.valueMinor -= issueCostMinor;
+			if (pool.quantity === 0) layers = [];
+			trace.push({
+				id: `${transaction.id}:issue`,
+				kind: "derive",
+				rule: "AVCO issues inventory at the current weighted-average cost.",
+				working: `${transaction.quantity} × pooled average`,
+				result: value
+			});
+		}
+		costOfSalesMinor += issueCostMinor;
+		const quantity = layers.reduce((total, layer) => total + layer.quantity, 0);
+		const valueMinor = totalValue(layers);
+		movements.push({
+			transactionId: transaction.id,
+			type: transaction.type,
+			quantity: transaction.quantity,
+			...transaction.type === "receipt" ? { unitCost: transaction.unitCost } : {},
+			issueCost: fromMinor(issueCostMinor, policy),
+			runningCostOfSales: fromMinor(costOfSalesMinor, policy),
+			runningQuantity: quantity,
+			runningValue: fromMinor(valueMinor, policy),
+			averageUnitCost: quantity === 0 ? 0 : fromMinor(valueMinor, policy) / quantity,
+			consumedLayers,
+			remainingLayers: layers.map((layer) => publicLayer(layer, policy))
+		});
+	}
+	const closingValueMinor = totalValue(layers);
+	const closingQuantity = layers.reduce((total, layer) => total + layer.quantity, 0);
+	trace.push({
+		id: "inventory:conservation",
+		kind: "check",
+		rule: "Goods available = cost of issues + closing inventory.",
+		working: `${fromMinor(costOfSalesMinor, policy)} issued; ${fromMinor(closingValueMinor, policy)} remains`,
+		result: diagnostics.length === 0
+	});
+	return {
+		method,
+		completed: diagnostics.length === 0,
+		movements,
+		costOfSales: fromMinor(costOfSalesMinor, policy),
+		closingQuantity,
+		closingValue: fromMinor(closingValueMinor, policy),
+		closingLayers: layers.map((layer) => publicLayer(layer, policy)),
+		diagnostics,
+		trace
+	};
+}
+
+//#endregion
+export { costInventory };

package/dist/finance/management-accounting/investment-appraisal.d.mts

@@ -0,0 +1,7 @@
+import { AccountingPolicy } from "../accounting/types.mjs";
+import { InvestmentAppraisalFacts, InvestmentAppraisalResult } from "./types.mjs";
+
+//#region src/finance/management-accounting/investment-appraisal.d.ts
+declare function appraiseInvestment(facts: InvestmentAppraisalFacts, policy?: AccountingPolicy): InvestmentAppraisalResult;
+//#endregion
+export { appraiseInvestment };

package/dist/finance/management-accounting/investment-appraisal.mjs

@@ -0,0 +1,148 @@
+import { fromMinor, toMinor } from "../accounting/precision.mjs";
+import { npv, payback } from "../investment-math.mjs";
+
+//#region src/finance/management-accounting/investment-appraisal.ts
+const DEFAULT_POLICY = { decimalPlaces: 2 };
+function appraiseInvestment(facts, policy = DEFAULT_POLICY) {
+	const diagnostics = [];
+	if (!Number.isFinite(facts.initialInvestment) || facts.initialInvestment <= 0) diagnostics.push({
+		code: "invalid-input",
+		severity: "error",
+		message: "Initial investment must be finite and positive."
+	});
+	if (!Number.isFinite(facts.discountRate) || facts.discountRate < 0) diagnostics.push({
+		code: "invalid-input",
+		severity: "error",
+		message: "Discount rate must be finite and non-negative."
+	});
+	if (!Number.isFinite(facts.residualValue.amount) || facts.residualValue.amount < 0) diagnostics.push({
+		code: "invalid-input",
+		severity: "error",
+		message: "Residual value must be finite and non-negative."
+	});
+	const cashByPeriod = validateSeries(facts.cashFlows, (item) => item.period, (item) => item.netCashFlow, "Cash flow", diagnostics);
+	const profitByPeriod = validateSeries(facts.accountingProfits, (item) => item.period, (item) => item.profit, "Accounting profit", diagnostics);
+	const finalPeriod = facts.cashFlows.length;
+	if (facts.residualValue.period !== finalPeriod) diagnostics.push({
+		code: "invalid-terminal-period",
+		severity: "error",
+		period: facts.residualValue.period,
+		message: "Residual value must occur in the final cash-flow period."
+	});
+	if (facts.accountingProfits.length !== facts.cashFlows.length || [...cashByPeriod.keys()].some((period) => !profitByPeriod.has(period))) diagnostics.push({
+		code: "incomplete-series",
+		severity: "error",
+		message: "Accounting profit must be supplied for every cash-flow period."
+	});
+	if (diagnostics.length > 0) return emptyResult(diagnostics);
+	const undiscounted = [-facts.initialInvestment];
+	const discounted = [-facts.initialInvestment];
+	const periods = [];
+	let cumulativeCashFlow = money(-facts.initialInvestment, policy);
+	let cumulativeDiscountedCashFlow = cumulativeCashFlow;
+	for (let period = 1; period <= finalPeriod; period += 1) {
+		const operatingCashFlow = cashByPeriod.get(period);
+		const residualValue = period === facts.residualValue.period ? facts.residualValue.amount : 0;
+		const totalCashFlow = money(operatingCashFlow + residualValue, policy);
+		const discountFactor = 1 / Math.pow(1 + facts.discountRate, period);
+		const presentValue = money(totalCashFlow * discountFactor, policy);
+		undiscounted.push(totalCashFlow);
+		discounted.push(presentValue);
+		cumulativeCashFlow = money(cumulativeCashFlow + totalCashFlow, policy);
+		cumulativeDiscountedCashFlow = money(cumulativeDiscountedCashFlow + presentValue, policy);
+		periods.push({
+			period,
+			operatingCashFlow,
+			residualValue,
+			totalCashFlow,
+			discountFactor,
+			presentValue,
+			cumulativeCashFlow,
+			cumulativeDiscountedCashFlow
+		});
+	}
+	const netPresentValue = money(npv(facts.discountRate, undiscounted), policy);
+	const rawPayback = payback(undiscounted);
+	const rawDiscountedPayback = payback(discounted);
+	const averageAnnualAccountingProfit = money([...profitByPeriod.values()].reduce((total, profit) => total + profit, 0) / profitByPeriod.size, policy);
+	const arrInvestmentBase = money(facts.arrInvestmentBasis === "initial-investment" ? facts.initialInvestment : (facts.initialInvestment + facts.residualValue.amount) / 2, policy);
+	const accountingRateOfReturnPercent = money(averageAnnualAccountingProfit / arrInvestmentBase * 100, policy);
+	const trace = [
+		{
+			id: "appraisal:npv",
+			kind: "derive",
+			rule: "NPV = initial outlay + present value of future operating cash flows and residual value.",
+			working: discounted.join(" + "),
+			result: netPresentValue
+		},
+		{
+			id: "appraisal:payback",
+			kind: "derive",
+			rule: "Payback interpolates within the period in which cumulative undiscounted cash flow becomes non-negative.",
+			working: undiscounted.join(" + "),
+			result: Number.isFinite(rawPayback) ? rawPayback : "not recovered"
+		},
+		{
+			id: "appraisal:arr",
+			kind: "derive",
+			rule: `ARR = average annual accounting profit ÷ ${facts.arrInvestmentBasis === "initial-investment" ? "initial investment" : "average investment"} × 100.`,
+			working: `${averageAnnualAccountingProfit} ÷ ${arrInvestmentBase} × 100`,
+			result: accountingRateOfReturnPercent
+		}
+	];
+	return {
+		completed: true,
+		periods,
+		netPresentValue,
+		paybackPeriod: Number.isFinite(rawPayback) ? rawPayback : null,
+		discountedPaybackPeriod: Number.isFinite(rawDiscountedPayback) ? rawDiscountedPayback : null,
+		averageAnnualAccountingProfit,
+		accountingRateOfReturnPercent,
+		arrInvestmentBase,
+		diagnostics,
+		trace
+	};
+}
+function validateSeries(items, periodOf, valueOf, label, diagnostics) {
+	const values = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const period = periodOf(item);
+		const value = valueOf(item);
+		if (!Number.isInteger(period) || period <= 0 || !Number.isFinite(value)) diagnostics.push({
+			code: "invalid-input",
+			severity: "error",
+			period,
+			message: `${label} periods must be positive integers and amounts must be finite.`
+		});
+		if (values.has(period)) diagnostics.push({
+			code: "duplicate-period",
+			severity: "error",
+			period,
+			message: `${label} period ${period} is duplicated.`
+		});
+		values.set(period, value);
+	}
+	for (let period = 1; period <= items.length; period += 1) if (!values.has(period)) diagnostics.push({
+		code: "incomplete-series",
+		severity: "error",
+		period,
+		message: `${label} period ${period} is missing.`
+	});
+	return values;
+}
+const money = (value, policy) => fromMinor(toMinor(value, policy), policy);
+const emptyResult = (diagnostics) => ({
+	completed: false,
+	periods: [],
+	netPresentValue: 0,
+	paybackPeriod: null,
+	discountedPaybackPeriod: null,
+	averageAnnualAccountingProfit: 0,
+	accountingRateOfReturnPercent: 0,
+	arrInvestmentBase: 0,
+	diagnostics,
+	trace: []
+});
+
+//#endregion
+export { appraiseInvestment };

package/dist/finance/management-accounting/management-case.d.mts

@@ -0,0 +1,8 @@
+import { AccountingPolicy } from "../accounting/types.mjs";
+import { ManagementAccountingCase, ManagementAccountingCaseResult } from "./types.mjs";
+
+//#region src/finance/management-accounting/management-case.d.ts
+/** Runs independent authored tasks through their authoritative solvers; it contains no accounting formulas. */
+declare function runManagementAccountingCase(caseDefinition: ManagementAccountingCase, policy?: AccountingPolicy): ManagementAccountingCaseResult;
+//#endregion
+export { runManagementAccountingCase };