jaz-cli 2.2.1 → 2.5.0

package/assets/skills/transaction-recipes/references/provisions.md

@@ -0,0 +1,142 @@
+# Recipe: Provisions with PV Unwinding (IAS 37)
+
+## Scenario
+
+Your company has a product warranty obligation. Based on historical claims data, you estimate $500,000 in warranty costs over the next 5 years. Because the time value of money is material (IAS 37.45), you recognize the provision at its present value using a 4% discount rate. Each month, the discount unwinds as a finance cost, gradually increasing the provision balance until it reaches the full $500,000 at settlement.
+
+**Pattern:** Manual journals + capsule (interest amounts change each period, same as loan/lease unwinding)
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Provision Expense | Expense | Expense | Initial recognition at PV |
+| Provision for Obligations | Liability | Non-Current Liability | Holds the discounted obligation |
+| Finance Cost — Unwinding | Expense | Expense | Monthly discount unwinding charge |
+| Cash / Bank Account | Asset | Bank | Settlement when obligation is paid |
+
+---
+
+## Journal Entries
+
+### Step 1: Initial Recognition (at PV)
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Provision Expense | *present value* | |
+| 2 | Provision for Obligations | | *present value* |
+
+### Step 2: Monthly Unwinding (each month)
+
+```
+Interest = Opening Provision Balance × Monthly Rate
+Monthly Rate = Annual Rate / 12
+```
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Finance Cost — Unwinding | *interest amount* | |
+| 2 | Provision for Obligations | | *interest amount* |
+
+The provision balance grows each month until it reaches the nominal amount at settlement.
+
+### Step 3: Settlement (when obligation is paid)
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Provision for Obligations | *nominal amount* | |
+| 2 | Cash / Bank Account | | *actual amount paid* |
+| 3 | Provision Expense (or Revenue) | difference | (if actual ≠ estimate) |
+
+---
+
+## Capsule Structure
+
+**Capsule:** "Warranty Provision — Product X — 2025"
+**Capsule Type:** "Provisions"
+
+Contents:
+- 1 initial recognition journal
+- 60 monthly unwinding journals (5 years)
+- Settlement journal(s) when claims are paid
+- Revision journals if estimate changes
+- **Total entries:** 62+
+
+---
+
+## Worked Example
+
+**Setup:**
+- Estimated future outflow: $500,000
+- Discount rate: 4% annual (0.333% monthly)
+- Settlement term: 60 months
+- Present value: $409,501.55
+
+**Calculation:**
+```
+PV = 500,000 / (1 + 0.04/12)^60 = $409,501.55
+Total unwinding = $500,000 − $409,501.55 = $90,498.45
+```
+
+**Jan 1, 2025 — Initial recognition:**
+- Dr Provision Expense $409,501.55
+- Cr Provision for Obligations $409,501.55
+- Description: "Initial provision recognition at PV (IAS 37)"
+
+**Jan 31, 2025 — Month 1 unwinding:**
+- Opening balance: $409,501.55
+- Interest: $409,501.55 × 0.00333 = $1,365.01
+- Closing balance: $410,866.56
+- Dr Finance Cost — Unwinding $1,365.01
+- Cr Provision for Obligations $1,365.01
+
+**Feb 28, 2025 — Month 2 unwinding:**
+- Opening balance: $410,866.56
+- Interest: $410,866.56 × 0.00333 = $1,369.56
+- Closing balance: $412,236.12
+
+**Dec 31, 2029 — Month 60 (final):**
+- Closing balance reaches exactly $500,000.00
+
+**Settlement:**
+- Dr Provision for Obligations $500,000
+- Cr Cash $500,000
+
+**Use the calculator:** `jaz calc provision --amount 500000 --rate 4 --term 60 --start-date 2025-01-01`
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Provision" | Filter all provision-related entries |
+| Tracking Tag | "IAS 37" | Mark IFRS-specific adjustments |
+| Custom Field | "Obligation Type" → "Warranty" | Identify the type of provision |
+| Custom Field | "Expected Settlement Date" → "2029-12-31" | Record the estimated settlement date |
+
+---
+
+## Verification
+
+1. **Trial Balance at Jan 31** → Provision for Obligations shows $410,866.56 credit. Finance Cost shows $1,365.01.
+2. **Trial Balance at Dec 31, Year 1** → Provision balance should match the year-end closing balance from the unwinding schedule (~$426,185).
+3. **Final period** → Provision balance reaches exactly $500,000.00 (the calculator's final-period adjustment ensures this).
+4. **P&L per year** → Finance Cost — Unwinding increases each year (compounding effect), totaling $90,498.45 over 5 years.
+5. **Group General Ledger by Capsule** → Complete history from recognition through every unwinding entry.
+
+---
+
+## Variations
+
+**Revision of estimate:** If the estimated outflow changes (e.g., from $500,000 to $550,000), adjust the provision and recalculate the unwinding schedule. The change in estimate goes to Provision Expense, not Finance Cost.
+
+**Short-term provision (no discounting):** If settlement is within 12 months, PV discounting is not required (IAS 37.45 — "effect of time value not material"). Simply recognize at the nominal amount with no unwinding schedule.
+
+**Decommissioning provision:** Same pattern, but the initial recognition is capitalized to the related asset (Dr Asset / Cr Provision) instead of expensed. The asset is then depreciated over its useful life.
+
+**Legal claim provision:** If the outcome is uncertain, provision is recognized only when "probable" (>50% likelihood). If only "possible," disclose as a contingent liability but do not recognize. Use the provision calculator once the amount and timing are estimable.
+
+**Multiple payment dates:** If the obligation will be settled in tranches (e.g., warranty claims over 5 years), model as multiple provisions or use a weighted average settlement period.

package/dist/calc/amortization.js

@@ -0,0 +1,104 @@
+/**
+ * Prepaid expense & deferred revenue recognition calculators.
+ * Equal-period division. Final period absorbs rounding remainder.
+ */
+import { round2, addMonths } from './types.js';
+import { validatePositive, validatePositiveInteger, validateDateFormat } from './validate.js';
+import { journalStep, fmtCapsuleAmount } from './blueprint.js';
+export function calculatePrepaidExpense(inputs) {
+    const { amount, periods, frequency = 'monthly', startDate, currency } = inputs;
+    validatePositive(amount, 'Amount');
+    validatePositiveInteger(periods, 'Periods');
+    validateDateFormat(startDate);
+    const schedule = buildSchedule(amount, periods, frequency, startDate, 'prepaid');
+    let blueprint = null;
+    if (startDate) {
+        const steps = [
+            journalStep(1, 'Initial prepaid payment (bill or cash-out entry)', startDate, [
+                { account: 'Prepaid Asset', debit: amount, credit: 0 },
+                { account: 'Cash / Bank Account', debit: 0, credit: amount },
+            ]),
+            ...schedule.map((row, idx) => journalStep(idx + 2, row.journal.description, row.date, row.journal.lines)),
+        ];
+        blueprint = {
+            capsuleType: 'Prepaid Expenses',
+            capsuleName: `Prepaid Expense — ${fmtCapsuleAmount(amount, currency)} — ${periods} periods`,
+            tags: ['Prepaid Expense'],
+            customFields: { 'Policy / Contract #': null },
+            steps,
+        };
+    }
+    return {
+        type: 'prepaid-expense',
+        currency: currency ?? null,
+        inputs: { amount, periods, frequency, startDate: startDate ?? null },
+        perPeriodAmount: round2(amount / periods),
+        schedule,
+        blueprint,
+    };
+}
+export function calculateDeferredRevenue(inputs) {
+    const { amount, periods, frequency = 'monthly', startDate, currency } = inputs;
+    validatePositive(amount, 'Amount');
+    validatePositiveInteger(periods, 'Periods');
+    validateDateFormat(startDate);
+    const schedule = buildSchedule(amount, periods, frequency, startDate, 'deferred');
+    let blueprint = null;
+    if (startDate) {
+        const steps = [
+            journalStep(1, 'Initial deferred receipt (invoice or cash-in entry)', startDate, [
+                { account: 'Cash / Bank Account', debit: amount, credit: 0 },
+                { account: 'Deferred Revenue', debit: 0, credit: amount },
+            ]),
+            ...schedule.map((row, idx) => journalStep(idx + 2, row.journal.description, row.date, row.journal.lines)),
+        ];
+        blueprint = {
+            capsuleType: 'Deferred Revenue',
+            capsuleName: `Deferred Revenue — ${fmtCapsuleAmount(amount, currency)} — ${periods} periods`,
+            tags: ['Deferred Revenue'],
+            customFields: { 'Contract #': null },
+            steps,
+        };
+    }
+    return {
+        type: 'deferred-revenue',
+        currency: currency ?? null,
+        inputs: { amount, periods, frequency, startDate: startDate ?? null },
+        perPeriodAmount: round2(amount / periods),
+        schedule,
+        blueprint,
+    };
+}
+function buildSchedule(amount, periods, frequency, startDate, kind) {
+    const perPeriod = round2(amount / periods);
+    const schedule = [];
+    let remaining = amount;
+    const monthsPerPeriod = frequency === 'quarterly' ? 3 : 1;
+    for (let i = 1; i <= periods; i++) {
+        const isFinal = i === periods;
+        const amortized = isFinal ? round2(remaining) : perPeriod;
+        remaining = round2(remaining - amortized);
+        const date = startDate ? addMonths(startDate, i * monthsPerPeriod) : null;
+        let journal;
+        if (kind === 'prepaid') {
+            journal = {
+                description: `Prepaid expense recognition — Period ${i} of ${periods}`,
+                lines: [
+                    { account: 'Expense', debit: amortized, credit: 0 },
+                    { account: 'Prepaid Asset', debit: 0, credit: amortized },
+                ],
+            };
+        }
+        else {
+            journal = {
+                description: `Deferred revenue recognition — Period ${i} of ${periods}`,
+                lines: [
+                    { account: 'Deferred Revenue', debit: amortized, credit: 0 },
+                    { account: 'Revenue', debit: 0, credit: amortized },
+                ],
+            };
+        }
+        schedule.push({ period: i, date, amortized, remainingBalance: remaining, journal });
+    }
+    return schedule;
+}

package/dist/calc/blueprint.js

@@ -0,0 +1,21 @@
+/**
+ * Blueprint builder — translates calculator output into a
+ * capsule + transaction execution plan for Jaz.
+ *
+ * The blueprint gives an AI agent or human everything needed to
+ * create the capsule and post all journal entries in Jaz without
+ * any manual translation from the schedule.
+ */
+/** Build a blueprint step from a journal entry with a date. */
+export function journalStep(stepNum, description, date, lines) {
+    return { step: stepNum, action: 'journal', description, date, lines };
+}
+/** Build a note step (instruction, not a journal — e.g. "register fixed asset"). */
+export function noteStep(stepNum, description, date = null) {
+    return { step: stepNum, action: 'note', description, date, lines: [] };
+}
+/** Format a currency amount for capsule names (e.g. "SGD 100,000"). */
+export function fmtCapsuleAmount(amount, currency) {
+    const formatted = amount.toLocaleString('en-US', { minimumFractionDigits: 0, maximumFractionDigits: 0 });
+    return currency ? `${currency} ${formatted}` : formatted;
+}

package/dist/calc/depreciation.js

@@ -0,0 +1,177 @@
+/**
+ * Depreciation schedule calculator.
+ *
+ * Methods:
+ *  - sl:    Straight-line (cost - salvage) / life
+ *  - ddb:   Double declining balance (2 / life), auto switch-to-SL
+ *  - 150db: 150% declining balance (1.5 / life), auto switch-to-SL
+ *
+ * Book value never goes below salvage value.
+ * Total depreciation always equals (cost - salvage).
+ */
+import { round2 } from './types.js';
+import { validatePositive, validateNonNegative, validatePositiveInteger, validateSalvageLessThanCost } from './validate.js';
+import { journalStep } from './blueprint.js';
+export function calculateDepreciation(inputs) {
+    const { cost, salvageValue, usefulLifeYears, method = 'ddb', frequency = 'annual', currency, } = inputs;
+    validatePositive(cost, 'Asset cost');
+    validateNonNegative(salvageValue, 'Salvage value');
+    validatePositiveInteger(usefulLifeYears, 'Useful life (years)');
+    if (salvageValue > 0)
+        validateSalvageLessThanCost(salvageValue, cost);
+    const depreciableBase = round2(cost - salvageValue);
+    if (method === 'sl') {
+        return buildStraightLineResult(cost, salvageValue, usefulLifeYears, depreciableBase, frequency, currency);
+    }
+    const multiplier = method === 'ddb' ? 2 : 1.5;
+    const annualRate = multiplier / usefulLifeYears;
+    if (frequency === 'annual') {
+        return buildDecliningSchedule(cost, salvageValue, usefulLifeYears, annualRate, depreciableBase, method, currency);
+    }
+    // Monthly: compute annual schedule then subdivide each year into 12 equal months
+    const annual = buildDecliningSchedule(cost, salvageValue, usefulLifeYears, annualRate, depreciableBase, method, currency);
+    const monthlySchedule = [];
+    let periodNum = 0;
+    for (const yearRow of annual.schedule) {
+        const monthlyAmount = round2(yearRow.depreciation / 12);
+        let yearRemaining = yearRow.depreciation;
+        for (let m = 1; m <= 12; m++) {
+            periodNum++;
+            const isLastMonth = m === 12;
+            const dep = isLastMonth ? round2(yearRemaining) : monthlyAmount;
+            yearRemaining = round2(yearRemaining - dep);
+            const openingBV = periodNum === 1
+                ? cost
+                : round2(monthlySchedule[periodNum - 2].closingBookValue);
+            const closingBV = round2(openingBV - dep);
+            const journal = {
+                description: `${yearRow.methodUsed} depreciation — Month ${periodNum} of ${usefulLifeYears * 12}`,
+                lines: [
+                    { account: 'Depreciation Expense', debit: dep, credit: 0 },
+                    { account: 'Accumulated Depreciation', debit: 0, credit: dep },
+                ],
+            };
+            monthlySchedule.push({
+                period: periodNum,
+                date: null,
+                openingBookValue: openingBV,
+                ddbAmount: round2(yearRow.ddbAmount / 12),
+                slAmount: round2(yearRow.slAmount / 12),
+                methodUsed: yearRow.methodUsed,
+                depreciation: dep,
+                closingBookValue: closingBV,
+                journal,
+            });
+        }
+    }
+    return {
+        type: 'depreciation',
+        currency: currency ?? null,
+        inputs: { cost, salvageValue, usefulLifeYears, method, frequency },
+        totalDepreciation: depreciableBase,
+        schedule: monthlySchedule,
+        blueprint: annual.blueprint, // reuse annual blueprint (monthly is just subdivision)
+    };
+}
+function buildStraightLineResult(cost, salvageValue, usefulLifeYears, depreciableBase, frequency, currency) {
+    const totalPeriods = frequency === 'monthly' ? usefulLifeYears * 12 : usefulLifeYears;
+    const perPeriod = round2(depreciableBase / totalPeriods);
+    const periodLabel = frequency === 'monthly' ? 'Month' : 'Year';
+    const totalLabel = frequency === 'monthly' ? usefulLifeYears * 12 : usefulLifeYears;
+    const schedule = [];
+    let bookValue = cost;
+    for (let i = 1; i <= totalPeriods; i++) {
+        const openingBV = round2(bookValue);
+        const isFinal = i === totalPeriods;
+        const dep = isFinal ? round2(openingBV - salvageValue) : perPeriod;
+        bookValue = round2(openingBV - dep);
+        const journal = {
+            description: `SL depreciation — ${periodLabel} ${i} of ${totalLabel}`,
+            lines: [
+                { account: 'Depreciation Expense', debit: dep, credit: 0 },
+                { account: 'Accumulated Depreciation', debit: 0, credit: dep },
+            ],
+        };
+        schedule.push({
+            period: i,
+            date: null,
+            openingBookValue: openingBV,
+            ddbAmount: 0,
+            slAmount: dep,
+            methodUsed: 'SL',
+            depreciation: dep,
+            closingBookValue: bookValue,
+            journal,
+        });
+    }
+    const blueprintSteps = schedule.map((row, idx) => journalStep(idx + 1, row.journal.description, row.date, row.journal.lines));
+    return {
+        type: 'depreciation',
+        currency: currency ?? null,
+        inputs: { cost, salvageValue, usefulLifeYears, method: 'sl', frequency },
+        totalDepreciation: depreciableBase,
+        schedule,
+        blueprint: {
+            capsuleType: 'Depreciation',
+            capsuleName: `SL Depreciation — ${usefulLifeYears} years`,
+            tags: ['Depreciation'],
+            customFields: { 'Asset ID': null },
+            steps: blueprintSteps,
+        },
+    };
+}
+function buildDecliningSchedule(cost, salvageValue, usefulLifeYears, annualRate, depreciableBase, method, currency) {
+    const schedule = [];
+    let bookValue = cost;
+    for (let year = 1; year <= usefulLifeYears; year++) {
+        const openingBV = round2(bookValue);
+        const remainingYears = usefulLifeYears - year + 1;
+        // DDB amount (rate × opening book value)
+        const ddbAmount = round2(openingBV * annualRate);
+        // SL for remaining life: (book value - salvage) / remaining years
+        const slAmount = round2((openingBV - salvageValue) / remainingYears);
+        // Switch to SL when SL >= DDB, or when DDB would push below salvage
+        const ddbCapped = round2(openingBV - ddbAmount) < salvageValue;
+        const useSL = slAmount >= ddbAmount || ddbCapped;
+        const methodUsed = useSL ? 'SL' : (method === '150db' ? '150DB' : 'DDB');
+        // Depreciation cannot push book value below salvage
+        let depreciation = useSL ? slAmount : ddbAmount;
+        if (round2(openingBV - depreciation) < salvageValue) {
+            depreciation = round2(openingBV - salvageValue);
+        }
+        bookValue = round2(openingBV - depreciation);
+        const journal = {
+            description: `${methodUsed} depreciation — Year ${year} of ${usefulLifeYears}`,
+            lines: [
+                { account: 'Depreciation Expense', debit: depreciation, credit: 0 },
+                { account: 'Accumulated Depreciation', debit: 0, credit: depreciation },
+            ],
+        };
+        schedule.push({
+            period: year,
+            date: null,
+            openingBookValue: openingBV,
+            ddbAmount,
+            slAmount,
+            methodUsed,
+            depreciation,
+            closingBookValue: bookValue,
+            journal,
+        });
+    }
+    const blueprintSteps = schedule.map((row, idx) => journalStep(idx + 1, row.journal.description, row.date, row.journal.lines));
+    return {
+        type: 'depreciation',
+        currency: currency ?? null,
+        inputs: { cost, salvageValue, usefulLifeYears, method, frequency: 'annual' },
+        totalDepreciation: depreciableBase,
+        schedule,
+        blueprint: {
+            capsuleType: 'Depreciation',
+            capsuleName: `${method.toUpperCase()} Depreciation — ${usefulLifeYears} years`,
+            tags: ['Depreciation'],
+            customFields: { 'Asset ID': null },
+            steps: blueprintSteps,
+        },
+    };
+}

package/dist/calc/ecl.js

@@ -0,0 +1,89 @@
+/**
+ * Expected Credit Loss (ECL) calculator — IFRS 9 simplified approach.
+ *
+ * Builds a provision matrix from aged receivables buckets and historical
+ * loss rates, then calculates the required provision adjustment.
+ *
+ * Compliance references:
+ *  - IFRS 9.5.5.15: Simplified approach for trade receivables
+ *  - IFRS 9.B5.5.35: Provision matrix method
+ *  - IFRS 9.5.5.17: Always recognize lifetime ECL (no staging)
+ *
+ * Standard aging buckets: Current, 1-30d, 31-60d, 61-90d, 91+d
+ * Each bucket gets a historical loss rate (%) applied.
+ * The delta between total ECL and existing provision = period charge.
+ */
+import { round2 } from './types.js';
+import { validateNonNegative } from './validate.js';
+import { journalStep, fmtCapsuleAmount } from './blueprint.js';
+export function calculateEcl(inputs) {
+    const { buckets, existingProvision = 0, currency } = inputs;
+    // Validate each bucket
+    for (const b of buckets) {
+        validateNonNegative(b.balance, `${b.name} balance`);
+        validateNonNegative(b.rate, `${b.name} loss rate`);
+    }
+    validateNonNegative(existingProvision, 'Existing provision');
+    // Calculate ECL per bucket
+    const bucketDetails = buckets.map(b => ({
+        bucket: b.name,
+        balance: b.balance,
+        lossRate: b.rate,
+        ecl: round2(b.balance * b.rate / 100),
+    }));
+    const totalReceivables = round2(buckets.reduce((sum, b) => sum + b.balance, 0));
+    const totalEcl = round2(bucketDetails.reduce((sum, b) => sum + b.ecl, 0));
+    const adjustmentRequired = round2(totalEcl - existingProvision);
+    const isIncrease = adjustmentRequired >= 0;
+    const absAdj = Math.abs(adjustmentRequired);
+    // Weighted average loss rate for summary
+    const weightedRate = totalReceivables > 0
+        ? round2(totalEcl / totalReceivables * 100 * 100) / 100 // round to 2dp %
+        : 0;
+    // Journal entry for the provision adjustment
+    let journal;
+    if (isIncrease) {
+        journal = {
+            description: `ECL provision increase — IFRS 9 simplified approach`,
+            lines: [
+                { account: 'Bad Debt Expense', debit: absAdj, credit: 0 },
+                { account: 'Allowance for Doubtful Debts', debit: 0, credit: absAdj },
+            ],
+        };
+    }
+    else {
+        journal = {
+            description: `ECL provision release — IFRS 9 simplified approach`,
+            lines: [
+                { account: 'Allowance for Doubtful Debts', debit: absAdj, credit: 0 },
+                { account: 'Bad Debt Expense', debit: 0, credit: absAdj },
+            ],
+        };
+    }
+    // Blueprint
+    const blueprint = {
+        capsuleType: 'ECL Provision',
+        capsuleName: `ECL Provision — ${fmtCapsuleAmount(totalEcl, currency)} — ${buckets.length} buckets`,
+        tags: ['ECL', 'Bad Debt'],
+        customFields: { 'Reporting Period': null, 'Aged Receivables Report Date': null },
+        steps: [
+            journalStep(1, journal.description, null, journal.lines),
+        ],
+    };
+    return {
+        type: 'ecl',
+        currency: currency ?? null,
+        inputs: {
+            buckets: buckets.map(b => ({ name: b.name, balance: b.balance, rate: b.rate })),
+            existingProvision,
+        },
+        totalReceivables,
+        totalEcl,
+        weightedRate,
+        adjustmentRequired,
+        isIncrease,
+        bucketDetails,
+        journal,
+        blueprint,
+    };
+}