engine

Instruction file imported from RajwanYair/BudgetManager (.github/instructions/engine.instructions.md). Copyright stays with the author.

For engine changes in BudgetManager (src/engine/):

• Engines must be pure: no document, window, localStorage, fetch, or IDB access. Accept data as parameters, return results.
• If an engine currently has side effects, move the I/O to the calling section or service and pass data in.
• All amount-summing functions must accept an optional convertToBase parameter to normalize multi-currency values before aggregation.
• Recurring engine functions must include a duplicate-fire guard: skip items where lastTriggered === nextDate.
• Category, debt, bill, and family mutation functions return the updated data structure — callers own persistence.
• Do not throw for expected domain errors (e.g., "budget not found"). Return null or a typed result object.
• Engine tests live in tests/unit/engine/ and need no DOM or localStorage stubs.
• Add JSDoc only to exported public functions that are not already documented.