@classytic/stage 0.3.0 → 0.4.0

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

@@ -0,0 +1,644 @@
+import { ExplanationStep } from "../accounting/types.mjs";
+
+//#region src/finance/management-accounting/types.d.ts
+type InventoryCostingMethod = 'fifo' | 'avco';
+type InventoryTransaction = {
+  id: string;
+  type: 'receipt';
+  quantity: number;
+  unitCost: number;
+  label?: string;
+} | {
+  id: string;
+  type: 'issue';
+  quantity: number;
+  label?: string;
+};
+interface InventoryCostLayer {
+  sourceId: string;
+  quantity: number;
+  value: number;
+  unitCost: number;
+}
+interface InventoryLayerConsumption {
+  sourceId: string;
+  quantity: number;
+  value: number;
+  unitCost: number;
+}
+interface InventoryCostingMovement {
+  transactionId: string;
+  type: InventoryTransaction['type'];
+  quantity: number;
+  unitCost?: number;
+  issueCost: number;
+  runningCostOfSales: number;
+  runningQuantity: number;
+  runningValue: number;
+  averageUnitCost: number;
+  consumedLayers: readonly InventoryLayerConsumption[];
+  remainingLayers: readonly InventoryCostLayer[];
+}
+interface InventoryCostingDiagnostic {
+  code: 'duplicate-transaction' | 'invalid-quantity' | 'invalid-unit-cost' | 'insufficient-inventory';
+  severity: 'error';
+  transactionId: string;
+  message: string;
+}
+interface InventoryCostingResult {
+  method: InventoryCostingMethod;
+  completed: boolean;
+  movements: readonly InventoryCostingMovement[];
+  costOfSales: number;
+  closingQuantity: number;
+  closingValue: number;
+  closingLayers: readonly InventoryCostLayer[];
+  diagnostics: readonly InventoryCostingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+type CostBehavior = 'variable' | 'fixed';
+type CostFunction = 'production' | 'selling' | 'administration';
+type CostTraceability = 'direct' | 'indirect';
+interface ClassifiedCost {
+  id: string;
+  label: string;
+  behavior: CostBehavior;
+  function: CostFunction;
+  traceability: CostTraceability;
+  amount: number;
+  basis: 'per-unit' | 'period';
+}
+interface CostClassificationSummary {
+  variableProductionPerUnit: number;
+  variableNonProductionPerUnit: number;
+  fixedProduction: number;
+  fixedNonProduction: number;
+  directCostPerUnit: number;
+  indirectPeriodCost: number;
+}
+interface MarginalAbsorptionFacts {
+  unitsProduced: number;
+  unitsSold: number;
+  openingInventoryUnits?: number;
+  sellingPricePerUnit: number;
+  normalCapacityUnits: number;
+  actualFixedProductionOverhead?: number;
+  costs: readonly ClassifiedCost[];
+}
+interface CostingStatement {
+  revenue: number;
+  variableProductionCostOfSales: number;
+  fixedProductionCostOfSales: number;
+  variableNonProductionCost: number;
+  fixedNonProductionCost: number;
+  contribution?: number;
+  grossProfit?: number;
+  underAbsorption: number;
+  overAbsorption: number;
+  profit: number;
+}
+interface MarginalAbsorptionResult {
+  classification: CostClassificationSummary;
+  values: {
+    closingInventoryUnits: number;
+    fixedOverheadRate: number;
+    absorbedFixedOverhead: number;
+    actualFixedOverhead: number;
+    marginalClosingInventory: number;
+    absorptionClosingInventory: number;
+    inventoryFixedOverheadMovement: number;
+    profitDifference: number;
+  };
+  marginal: CostingStatement;
+  absorption: CostingStatement;
+  reconciles: boolean;
+  diagnostics: readonly {
+    code: 'invalid-cost' | 'invalid-volume' | 'invalid-capacity';
+    severity: 'error';
+    message: string;
+    costId?: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+interface BudgetPeriodInput {
+  id: string;
+  label: string;
+  salesUnits: number;
+  sellingPricePerUnit: number;
+  desiredClosingFinishedGoodsUnits: number;
+  materialUnitsPerFinishedUnit: number;
+  desiredClosingMaterialUnits: number;
+  materialCostPerUnit: number;
+  directLabourHoursPerUnit?: number;
+  directLabourRatePerHour?: number;
+  variableProductionOverheadRatePerLabourHour?: number;
+  fixedProductionOverhead?: number;
+}
+interface OperatingBudgetFacts {
+  openingFinishedGoodsUnits: number;
+  openingMaterialUnits: number;
+  periods: readonly BudgetPeriodInput[];
+}
+interface OperatingBudgetPeriod {
+  id: string;
+  label: string;
+  sales: {
+    units: number;
+    pricePerUnit: number;
+    revenue: number;
+  };
+  production: {
+    openingFinishedGoodsUnits: number;
+    salesUnits: number;
+    desiredClosingFinishedGoodsUnits: number;
+    unitsToProduce: number;
+  };
+  materialsUsage: {
+    unitsPerFinishedUnit: number;
+    productionUnits: number;
+    materialUnitsRequired: number;
+  };
+  materialsPurchases: {
+    openingMaterialUnits: number;
+    materialUnitsRequired: number;
+    desiredClosingMaterialUnits: number;
+    unitsToPurchase: number;
+    costPerUnit: number;
+    purchaseCost: number;
+  };
+  directLabour: {
+    hoursPerUnit: number;
+    productionUnits: number;
+    labourHours: number;
+    ratePerHour: number;
+    labourCost: number;
+  };
+  productionOverhead: {
+    labourHours: number;
+    variableRatePerLabourHour: number;
+    variableOverhead: number;
+    fixedOverhead: number;
+    totalOverhead: number;
+  };
+}
+interface OperatingBudgetResult {
+  completed: boolean;
+  periods: readonly OperatingBudgetPeriod[];
+  totals: {
+    salesUnits: number;
+    revenue: number;
+    productionUnits: number;
+    materialUsageUnits: number;
+    materialPurchaseUnits: number;
+    materialPurchaseCost: number;
+    labourHours: number;
+    labourCost: number;
+    variableProductionOverhead: number;
+    fixedProductionOverhead: number;
+    totalProductionOverhead: number;
+  };
+  diagnostics: readonly {
+    code: 'duplicate-period' | 'invalid-input' | 'impossible-schedule';
+    severity: 'error';
+    periodId?: string;
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+interface CashTimingAllocation {
+  offset: number;
+  proportion: number;
+}
+interface CashBudgetPeriodInput {
+  id: string;
+  label: string;
+  salesRevenue: number;
+  materialPurchases: number;
+  labourCost: number;
+  productionOverhead: number;
+  nonCashProductionOverhead?: number;
+  broughtForwardReceipts?: number;
+  broughtForwardPayments?: number;
+  otherReceipts?: number;
+  otherPayments?: number;
+}
+interface CashBudgetFacts {
+  openingCashBalance: number;
+  minimumCashBalance?: number;
+  collectionProfile: readonly CashTimingAllocation[];
+  materialPaymentProfile: readonly CashTimingAllocation[];
+  periods: readonly CashBudgetPeriodInput[];
+}
+interface CashBudgetPeriod {
+  id: string;
+  label: string;
+  openingCashBalance: number;
+  customerReceipts: number;
+  totalReceipts: number;
+  materialPayments: number;
+  labourPayments: number;
+  overheadPayments: number;
+  totalPayments: number;
+  preFinancingClosingCash: number;
+  financingRequired: number;
+  closingCashBalance: number;
+}
+interface CashBudgetResult {
+  completed: boolean;
+  periods: readonly CashBudgetPeriod[];
+  closingReceivables: number;
+  closingMaterialPayables: number;
+  totalFinancingRequired: number;
+  diagnostics: readonly {
+    code: 'duplicate-period' | 'invalid-input' | 'invalid-profile';
+    severity: 'error';
+    periodId?: string;
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+interface MasterBudgetPeriodPolicy {
+  periodId: string;
+  variableSellingAdministrationPerUnit: number;
+  fixedSellingAdministration: number;
+}
+interface MasterBudgetFacts {
+  operating: OperatingBudgetResult;
+  cash: CashBudgetResult;
+  openingFinishedGoodsValue: number;
+  periodPolicies: readonly MasterBudgetPeriodPolicy[];
+}
+interface MasterBudgetPeriod {
+  id: string;
+  label: string;
+  revenue: number;
+  materialUsageCost: number;
+  labourCost: number;
+  productionOverhead: number;
+  manufacturingCost: number;
+  goodsAvailableValue: number;
+  closingFinishedGoodsValue: number;
+  costOfSales: number;
+  grossProfit: number;
+  variableSellingAdministration: number;
+  fixedSellingAdministration: number;
+  operatingProfit: number;
+  closingCashBalance: number;
+  financingRequired: number;
+}
+interface MasterBudgetResult {
+  completed: boolean;
+  periods: readonly MasterBudgetPeriod[];
+  totals: {
+    revenue: number;
+    manufacturingCost: number;
+    costOfSales: number;
+    grossProfit: number;
+    sellingAdministration: number;
+    operatingProfit: number;
+    financingRequired: number;
+  };
+  diagnostics: readonly {
+    code: 'invalid-input' | 'incomplete-source' | 'period-mismatch';
+    severity: 'error';
+    periodId?: string;
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+interface IntegratedBudgetCashAdjustment {
+  periodId: string;
+  nonCashProductionOverhead?: number;
+  broughtForwardReceipts?: number;
+  broughtForwardPayments?: number;
+  otherReceipts?: number;
+  otherPayments?: number;
+}
+interface IntegratedMasterBudgetFacts {
+  operating: OperatingBudgetFacts;
+  openingCashBalance: number;
+  minimumCashBalance?: number;
+  collectionProfile: readonly CashTimingAllocation[];
+  materialPaymentProfile: readonly CashTimingAllocation[];
+  cashAdjustments?: readonly IntegratedBudgetCashAdjustment[];
+  openingFinishedGoodsValue: number;
+  periodPolicies: readonly MasterBudgetPeriodPolicy[];
+}
+interface IntegratedMasterBudgetResult {
+  completed: boolean;
+  operating: OperatingBudgetResult;
+  cash: CashBudgetResult;
+  master: MasterBudgetResult;
+  diagnostics: readonly {
+    code: string;
+    severity: 'error';
+    periodId?: string;
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+interface CostVariance {
+  amount: number;
+  outcome: 'favorable' | 'adverse' | 'none';
+}
+interface CostVarianceFacts {
+  actualOutputUnits: number;
+  material: {
+    standardQuantityPerUnit: number;
+    standardPricePerUnit: number;
+    actualQuantity: number;
+    actualPricePerUnit: number;
+  };
+  labour: {
+    standardHoursPerUnit: number;
+    standardRatePerHour: number;
+    actualHours: number;
+    actualRatePerHour: number;
+  };
+  variableOverhead: {
+    standardRatePerHour: number;
+    actualRatePerHour: number;
+  };
+  fixedOverhead: {
+    budgeted: number;
+    actual: number;
+    normalCapacityHours: number;
+  };
+}
+interface CostVarianceResult {
+  completed: boolean;
+  standardQuantity: number;
+  standardHours: number;
+  material: {
+    price: CostVariance;
+    usage: CostVariance;
+    total: CostVariance;
+  };
+  labour: {
+    rate: CostVariance;
+    efficiency: CostVariance;
+    total: CostVariance;
+  };
+  variableOverhead: {
+    expenditure: CostVariance;
+    efficiency: CostVariance;
+    total: CostVariance;
+  };
+  fixedOverhead: {
+    expenditure: CostVariance;
+    volume: CostVariance;
+    total: CostVariance;
+  };
+  totalCostVariance: CostVariance;
+  diagnostics: readonly {
+    code: 'invalid-input';
+    severity: 'error';
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+interface LimitedFactorProduct {
+  id: string;
+  label: string;
+  sellingPricePerUnit: number;
+  variableCostPerUnit: number;
+  scarceResourcePerUnit: number;
+  maximumDemandUnits: number;
+}
+interface LimitedFactorAllocation {
+  productId: string;
+  label: string;
+  contributionPerUnit: number;
+  contributionPerResourceUnit: number | 'unconstrained';
+  allocatedUnits: number;
+  resourceUsed: number;
+  contribution: number;
+  rank: number;
+}
+interface LimitedFactorResult {
+  completed: boolean;
+  resourceAvailable: number;
+  resourceUsed: number;
+  unusedResource: number;
+  totalContribution: number;
+  allocations: readonly LimitedFactorAllocation[];
+  diagnostics: readonly {
+    code: 'duplicate-product' | 'invalid-input';
+    severity: 'error';
+    productId?: string;
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+type RelevantCashFlowKind = 'incremental-revenue' | 'incremental-cost' | 'avoidable-cost' | 'opportunity-cost' | 'sunk-cost' | 'unavoidable-allocated-cost';
+interface RelevantCashFlow {
+  id: string;
+  label: string;
+  kind: RelevantCashFlowKind;
+  amount: number;
+}
+interface RelevantCostAlternative {
+  id: string;
+  label: string;
+  cashFlows: readonly RelevantCashFlow[];
+}
+interface RelevantCostAlternativeResult {
+  id: string;
+  label: string;
+  relevantBenefit: number;
+  relevantCost: number;
+  netBenefit: number;
+  included: readonly RelevantCashFlow[];
+  excluded: readonly RelevantCashFlow[];
+}
+interface RelevantCostDecisionResult {
+  completed: boolean;
+  alternatives: readonly RelevantCostAlternativeResult[];
+  recommendedAlternativeId?: string;
+  advantageOverNextBest: number;
+  diagnostics: readonly {
+    code: 'duplicate-alternative' | 'duplicate-cash-flow' | 'invalid-input' | 'insufficient-alternatives';
+    severity: 'error';
+    alternativeId?: string;
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+interface InvestmentCashFlow {
+  period: number;
+  netCashFlow: number;
+}
+interface InvestmentAccountingProfit {
+  period: number;
+  profit: number;
+}
+interface InvestmentAppraisalFacts {
+  initialInvestment: number;
+  cashFlows: readonly InvestmentCashFlow[];
+  residualValue: {
+    period: number;
+    amount: number;
+  };
+  accountingProfits: readonly InvestmentAccountingProfit[];
+  discountRate: number;
+  arrInvestmentBasis: 'initial-investment' | 'average-investment';
+}
+interface InvestmentAppraisalPeriod {
+  period: number;
+  operatingCashFlow: number;
+  residualValue: number;
+  totalCashFlow: number;
+  discountFactor: number;
+  presentValue: number;
+  cumulativeCashFlow: number;
+  cumulativeDiscountedCashFlow: number;
+}
+interface InvestmentAppraisalResult {
+  completed: boolean;
+  periods: readonly InvestmentAppraisalPeriod[];
+  netPresentValue: number;
+  paybackPeriod: number | null;
+  discountedPaybackPeriod: number | null;
+  averageAnnualAccountingProfit: number;
+  accountingRateOfReturnPercent: number;
+  arrInvestmentBase: number;
+  diagnostics: readonly {
+    code: 'duplicate-period' | 'invalid-input' | 'incomplete-series' | 'invalid-terminal-period';
+    severity: 'error';
+    period?: number;
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+interface JobBatchCostFacts {
+  kind: 'job' | 'batch';
+  outputUnits: number;
+  directMaterials: number;
+  directLabourHours: number;
+  directLabourRatePerHour: number;
+  directExpenses?: number;
+  productionOverhead: {
+    basisQuantity: number;
+    ratePerBasisUnit: number;
+    basisLabel: string;
+  };
+  nonProductionOverhead?: number;
+}
+interface JobBatchCostResult {
+  completed: boolean;
+  kind: 'job' | 'batch';
+  directLabour: number;
+  primeCost: number;
+  productionOverhead: number;
+  productionCost: number;
+  totalCost: number;
+  costPerUnit: number;
+  diagnostics: readonly {
+    code: 'invalid-input';
+    severity: 'error';
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+interface ProcessCostFacts {
+  inputUnits: number;
+  directMaterials: number;
+  conversionCost: number;
+  normalLossUnits: number;
+  normalLossScrapValuePerUnit: number;
+  actualOutputUnits: number;
+}
+interface ProcessCostResult {
+  completed: boolean;
+  actualLossUnits: number;
+  expectedOutputUnits: number;
+  netProcessCost: number;
+  costPerExpectedUnit: number;
+  outputValue: number;
+  normalLossScrapValue: number;
+  abnormal: {
+    kind: 'loss' | 'gain' | 'none';
+    units: number;
+    grossValue: number;
+    scrapAdjustment: number;
+    netCostImpact: number;
+  };
+  processAccount: {
+    debit: number;
+    credit: number;
+    balances: boolean;
+  };
+  diagnostics: readonly {
+    code: 'invalid-input' | 'impossible-flow';
+    severity: 'error';
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+type ManagementCaseTask = {
+  id: string;
+  kind: 'job-batch';
+  facts: JobBatchCostFacts;
+} | {
+  id: string;
+  kind: 'process-loss';
+  facts: ProcessCostFacts;
+} | {
+  id: string;
+  kind: 'limited-factor';
+  products: readonly LimitedFactorProduct[];
+  resourceAvailable: number;
+} | {
+  id: string;
+  kind: 'relevant-cost';
+  alternatives: readonly RelevantCostAlternative[];
+} | {
+  id: string;
+  kind: 'investment-appraisal';
+  facts: InvestmentAppraisalFacts;
+};
+type ManagementCaseSolution = JobBatchCostResult | ProcessCostResult | LimitedFactorResult | RelevantCostDecisionResult | InvestmentAppraisalResult;
+type ManagementCaseTaskResult = {
+  id: string;
+  kind: 'job-batch';
+  completed: boolean;
+  solution: JobBatchCostResult;
+} | {
+  id: string;
+  kind: 'process-loss';
+  completed: boolean;
+  solution: ProcessCostResult;
+} | {
+  id: string;
+  kind: 'limited-factor';
+  completed: boolean;
+  solution: LimitedFactorResult;
+} | {
+  id: string;
+  kind: 'relevant-cost';
+  completed: boolean;
+  solution: RelevantCostDecisionResult;
+} | {
+  id: string;
+  kind: 'investment-appraisal';
+  completed: boolean;
+  solution: InvestmentAppraisalResult;
+};
+interface ManagementAccountingCase {
+  id: string;
+  tasks: readonly ManagementCaseTask[];
+}
+interface ManagementAccountingCaseResult {
+  caseId: string;
+  completed: boolean;
+  tasks: readonly ManagementCaseTaskResult[];
+  diagnostics: readonly {
+    code: 'duplicate-task' | 'task-failed';
+    severity: 'error';
+    taskId: string;
+    message: string;
+  }[];
+  trace: readonly ExplanationStep[];
+}
+//#endregion
+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 };

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

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