jaz-cli 2.7.0 → 2.9.0

package/dist/jobs/year-end.js

@@ -0,0 +1,153 @@
+/**
+ * Year-end close blueprint generator.
+ * Builds on quarter-end phases with additional annual review and audit steps.
+ * Supports standalone (full) and incremental (annual extras only) modes.
+ */
+import { parseYearPeriod } from './validate.js';
+import { generateQuarterEndBlueprint } from './quarter-end.js';
+import { buildSummary } from './types.js';
+/**
+ * Build the annual extras phase (Phase 8).
+ * Year-end only steps: final depreciation, true-ups, dividends, retained
+ * earnings rollover, full-year GST reconciliation, audit prep, and final lock.
+ */
+function buildAnnualExtrasPhase(startDate, endDate, startOrder) {
+    let order = startOrder;
+    const step = (partial) => ({
+        order: ++order,
+        ...partial,
+    });
+    return {
+        name: 'Phase 8: Annual Extras',
+        description: 'Year-end specific adjustments, filings, and audit preparation.',
+        steps: [
+            step({
+                description: 'Final depreciation run for all fixed assets',
+                category: 'verify',
+                recipeRef: 'declining-balance',
+                calcCommand: 'jaz calc depreciation',
+                verification: 'NBV per register matches GL balances',
+                notes: 'Reconcile fixed asset register to general ledger',
+            }),
+            step({
+                description: 'Year-end true-ups (leave, bonus, provisions)',
+                category: 'adjust',
+                recipeRef: 'employee-accruals',
+                notes: 'True-up leave accrual to actual entitlement, bonus accrual to board-approved pool, and provision estimates to year-end reassessment',
+            }),
+            step({
+                description: 'Dividend declaration and payment',
+                category: 'adjust',
+                recipeRef: 'dividend',
+                conditional: 'If declaring dividends',
+                notes: 'Requires board resolution. Record declaration (DR Retained Earnings, CR Dividends Payable) then payment separately.',
+            }),
+            step({
+                description: 'Retained earnings rollover verification',
+                category: 'verify',
+                notes: 'Platform-managed. Verify via equity movement report that opening retained earnings equals prior year closing balance plus current year net income.',
+            }),
+            step({
+                description: 'Final GST/VAT reconciliation for the full year',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/vat-ledger',
+                apiBody: { startDate, endDate },
+                verification: 'Full-year VAT ledger reconciles to quarterly filings',
+                notes: 'Sum of quarterly GST submissions should match full-year ledger totals',
+            }),
+            step({
+                description: 'Audit preparation and documentation',
+                category: 'export',
+                notes: 'See audit-prep job for full detail. Prepare trial balance, aged schedules, bank confirmations, and supporting journals for auditor.',
+            }),
+            step({
+                description: `Set final lock date to ${endDate}`,
+                category: 'lock',
+                notes: `Lock the full financial year by setting the accounting lock date to ${endDate}. No further postings to this year after lock.`,
+            }),
+        ],
+    };
+}
+/**
+ * Build the annual verification phase (Phase 9).
+ * Full-year financial reports for board and statutory filing.
+ */
+function buildAnnualVerificationPhase(startDate, endDate, label, startOrder) {
+    let order = startOrder;
+    const step = (partial) => ({
+        order: ++order,
+        ...partial,
+    });
+    return {
+        name: 'Phase 9: Annual Verification',
+        description: `Full-year financial report review for ${label}.`,
+        steps: [
+            step({
+                description: `Review trial balance for ${label}`,
+                category: 'report',
+                apiCall: 'POST /generate-reports/trial-balance',
+                apiBody: { startDate, endDate },
+                verification: 'Total debits equal total credits',
+            }),
+            step({
+                description: `Generate P&L for ${label}`,
+                category: 'report',
+                apiCall: 'POST /generate-reports/profit-and-loss',
+                apiBody: { primarySnapshotDate: endDate, secondarySnapshotDate: startDate },
+            }),
+            step({
+                description: `Generate balance sheet as at ${endDate}`,
+                category: 'report',
+                apiCall: 'POST /generate-reports/balance-sheet',
+                apiBody: { primarySnapshotDate: endDate },
+                verification: 'Assets = Liabilities + Equity',
+            }),
+        ],
+    };
+}
+/**
+ * Generate a year-end close blueprint.
+ *
+ * @param opts.period       Year in YYYY format (e.g. "2025")
+ * @param opts.currency     Optional base currency code (e.g. "SGD")
+ * @param opts.incremental  If true, generate only the annual extras (skip quarter/month phases)
+ */
+export function generateYearEndBlueprint(opts) {
+    const parsed = parseYearPeriod(opts.period);
+    const mode = opts.incremental ? 'incremental' : 'standalone';
+    const phases = [];
+    if (!opts.incremental) {
+        // Standalone: include quarter-end phases for each of the 4 quarters
+        for (const quarter of parsed.quarters) {
+            const qBp = generateQuarterEndBlueprint({
+                period: `${parsed.year}-Q${quarter.quarter}`,
+                currency: opts.currency,
+                incremental: false,
+            });
+            // Prefix each phase name with the quarter label for clarity
+            for (const phase of qBp.phases) {
+                if (!phase.name.startsWith(quarter.label)) {
+                    phase.name = `${quarter.label} — ${phase.name}`;
+                }
+                phases.push(phase);
+            }
+        }
+    }
+    // Count the highest step order from existing phases
+    const maxOrder = phases.reduce((max, phase) => phase.steps.reduce((m, s) => Math.max(m, s.order), max), 0);
+    // Add annual extras (Phase 8)
+    const extras = buildAnnualExtrasPhase(parsed.startDate, parsed.endDate, maxOrder);
+    phases.push(extras);
+    // Add annual verification (Phase 9)
+    const lastExtraOrder = extras.steps.reduce((max, s) => Math.max(max, s.order), 0);
+    const verification = buildAnnualVerificationPhase(parsed.startDate, parsed.endDate, parsed.label, lastExtraOrder);
+    phases.push(verification);
+    return {
+        jobType: 'year-end-close',
+        period: parsed.label,
+        currency: opts.currency ?? 'SGD',
+        mode,
+        phases,
+        summary: buildSummary(phases),
+    };
+}

package/dist/tax/format.js

@@ -0,0 +1,18 @@
+/**
+ * Top-level dispatch for tax result formatting.
+ * Routes to country-specific formatters.
+ */
+import { printFormCsResult, printCaResult } from './sg/format-sg.js';
+export function printTaxResult(result) {
+    switch (result.type) {
+        case 'sg-form-cs': return printFormCsResult(result);
+        case 'sg-capital-allowance': return printCaResult(result);
+        default: {
+            const _exhaustive = result;
+            throw new Error(`Unknown tax result type: ${_exhaustive.type}`);
+        }
+    }
+}
+export function printTaxJson(result) {
+    console.log(JSON.stringify(result, null, 2));
+}

package/dist/tax/sg/capital-allowances.js

@@ -0,0 +1,160 @@
+/**
+ * Singapore capital allowance schedule calculator.
+ * Computes per-asset CA claims for a given Year of Assessment.
+ */
+import { round2 } from '../types.js';
+import { validateCaInput } from '../validate.js';
+import { CA_RATES, LOW_VALUE_YA_CAP, S14Q_BLOCK_CAP } from './constants.js';
+/**
+ * Compute CA for a single asset in the given YA.
+ * Returns the current year claim (may be zero if fully claimed).
+ */
+function computeAssetCa(asset) {
+    const rate = CA_RATES[asset.category];
+    if (!rate) {
+        // Shouldn't happen after validation, but defensive
+        return {
+            description: asset.description,
+            cost: asset.cost,
+            category: asset.category,
+            section: 'Unknown',
+            totalClaimedPrior: asset.priorYearsClaimed,
+            currentYearClaim: 0,
+            totalClaimedToDate: asset.priorYearsClaimed,
+            remainingUnabsorbed: round2(asset.cost - asset.priorYearsClaimed),
+        };
+    }
+    // IP category: use custom write-off years if provided
+    let annualRate = rate.annualRate;
+    if (asset.category === 'ip' && asset.ipWriteOffYears) {
+        annualRate = 1 / asset.ipWriteOffYears;
+    }
+    const unclaimed = round2(asset.cost - asset.priorYearsClaimed);
+    if (unclaimed <= 0) {
+        return {
+            description: asset.description,
+            cost: asset.cost,
+            category: asset.category,
+            section: rate.section,
+            totalClaimedPrior: asset.priorYearsClaimed,
+            currentYearClaim: 0,
+            totalClaimedToDate: asset.cost,
+            remainingUnabsorbed: 0,
+        };
+    }
+    // Annual claim = cost × annual rate, capped at remaining unclaimed
+    const rawClaim = round2(asset.cost * annualRate);
+    const currentYearClaim = round2(Math.min(rawClaim, unclaimed));
+    const totalClaimedToDate = round2(asset.priorYearsClaimed + currentYearClaim);
+    const remainingUnabsorbed = round2(asset.cost - totalClaimedToDate);
+    return {
+        description: asset.description,
+        cost: asset.cost,
+        category: asset.category,
+        section: rate.section,
+        totalClaimedPrior: asset.priorYearsClaimed,
+        currentYearClaim,
+        totalClaimedToDate,
+        remainingUnabsorbed,
+    };
+}
+/**
+ * Compute the full capital allowance schedule for a set of assets.
+ *
+ * Applies:
+ * - Per-asset CA computation using IRAS rates
+ * - Low-value asset $30K/YA total cap (S19A(2))
+ * - S14Q renovation $300K per 3-year block cap
+ * - Unabsorbed CA brought forward added to total available
+ */
+export function computeCapitalAllowances(input) {
+    validateCaInput(input);
+    const currency = input.currency ?? 'SGD';
+    // Step 1: Compute raw per-asset claims
+    const rawRows = input.assets.map(a => computeAssetCa(a));
+    // Step 2: Apply low-value YA cap ($30K total for all low-value assets)
+    let lowValueTotal = 0;
+    let lowValueCount = 0;
+    let lowValueCapped = false;
+    const rows = rawRows.map(row => {
+        if (row.category === 'low-value' && row.currentYearClaim > 0) {
+            lowValueCount++;
+            const available = round2(LOW_VALUE_YA_CAP - lowValueTotal);
+            if (available <= 0) {
+                lowValueCapped = true;
+                return { ...row, currentYearClaim: 0, totalClaimedToDate: row.totalClaimedPrior, remainingUnabsorbed: round2(row.cost - row.totalClaimedPrior) };
+            }
+            const cappedClaim = round2(Math.min(row.currentYearClaim, available));
+            if (cappedClaim < row.currentYearClaim)
+                lowValueCapped = true;
+            lowValueTotal = round2(lowValueTotal + cappedClaim);
+            return {
+                ...row,
+                currentYearClaim: cappedClaim,
+                totalClaimedToDate: round2(row.totalClaimedPrior + cappedClaim),
+                remainingUnabsorbed: round2(row.cost - row.totalClaimedPrior - cappedClaim),
+            };
+        }
+        if (row.category === 'low-value')
+            lowValueCount++;
+        return row;
+    });
+    // Step 3: Apply S14Q renovation cap ($300K per 3-year block)
+    // Simplified: we cap total renovation claims at $300K, leaving detailed
+    // 3-year block tracking to the AI agent (which has multi-year context).
+    let renovationTotal = 0;
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        if (row.category === 'renovation' && row.currentYearClaim > 0) {
+            const available = round2(S14Q_BLOCK_CAP - renovationTotal);
+            if (available <= 0) {
+                rows[i] = { ...row, currentYearClaim: 0, totalClaimedToDate: row.totalClaimedPrior, remainingUnabsorbed: round2(row.cost - row.totalClaimedPrior) };
+                continue;
+            }
+            const cappedClaim = round2(Math.min(row.currentYearClaim, available));
+            renovationTotal = round2(renovationTotal + cappedClaim);
+            if (cappedClaim < row.currentYearClaim) {
+                rows[i] = {
+                    ...row,
+                    currentYearClaim: cappedClaim,
+                    totalClaimedToDate: round2(row.totalClaimedPrior + cappedClaim),
+                    remainingUnabsorbed: round2(row.cost - row.totalClaimedPrior - cappedClaim),
+                };
+            }
+        }
+    }
+    // Step 4: Totals
+    const totalCurrentYearClaim = round2(rows.reduce((sum, r) => sum + r.currentYearClaim, 0));
+    const totalAvailable = round2(totalCurrentYearClaim + input.unabsorbedBroughtForward);
+    // Step 5: Build workings
+    const lines = [
+        `Capital Allowance Schedule — YA ${input.ya}`,
+        '',
+    ];
+    for (const row of rows) {
+        lines.push(`${row.description} (${row.section}): Cost ${currency} ${row.cost.toLocaleString('en-US', { minimumFractionDigits: 2 })} → ` +
+            `Claim ${currency} ${row.currentYearClaim.toLocaleString('en-US', { minimumFractionDigits: 2 })} ` +
+            `(${row.totalClaimedToDate.toLocaleString('en-US', { minimumFractionDigits: 2 })} to date, ` +
+            `${row.remainingUnabsorbed.toLocaleString('en-US', { minimumFractionDigits: 2 })} remaining)`);
+    }
+    if (lowValueCapped) {
+        lines.push(`\nNote: Low-value asset claims capped at ${currency} ${LOW_VALUE_YA_CAP.toLocaleString()} per YA`);
+    }
+    lines.push('');
+    lines.push(`Current year CA: ${currency} ${totalCurrentYearClaim.toLocaleString('en-US', { minimumFractionDigits: 2 })}`);
+    lines.push(`Unabsorbed b/f:  ${currency} ${input.unabsorbedBroughtForward.toLocaleString('en-US', { minimumFractionDigits: 2 })}`);
+    lines.push(`Total available:  ${currency} ${totalAvailable.toLocaleString('en-US', { minimumFractionDigits: 2 })}`);
+    return {
+        type: 'sg-capital-allowance',
+        ya: input.ya,
+        currency,
+        assets: rows,
+        totalCurrentYearClaim,
+        lowValueCount,
+        lowValueTotal,
+        lowValueCapped,
+        unabsorbedBroughtForward: input.unabsorbedBroughtForward,
+        totalAvailable,
+        workings: lines.join('\n'),
+    };
+}

package/dist/tax/sg/constants.js

@@ -0,0 +1,63 @@
+/**
+ * Singapore corporate income tax constants.
+ * All magic numbers live here — no hard-coded rates in computation logic.
+ */
+/** Standard corporate income tax rate. */
+export const SG_CIT_RATE = 0.17;
+/** Revenue threshold for Form C-S eligibility. */
+export const FORM_CS_REVENUE_LIMIT = 5_000_000;
+/** Revenue threshold for Form C-S Lite eligibility. */
+export const FORM_CS_LITE_REVENUE_LIMIT = 200_000;
+/**
+ * Start-Up Tax Exemption (SUTE) — for first 3 YAs of newly incorporated companies.
+ * Applied in order: first band fills before second band.
+ */
+export const SUTE_BANDS = [
+    { threshold: 100_000, exemptionRate: 0.75 },
+    { threshold: 100_000, exemptionRate: 0.50 },
+];
+/**
+ * Partial Tax Exemption (PTE) — for all companies not on SUTE.
+ * Applied in order: first band fills before second band.
+ */
+export const PTE_BANDS = [
+    { threshold: 10_000, exemptionRate: 0.75 },
+    { threshold: 190_000, exemptionRate: 0.50 },
+];
+/**
+ * CIT rebate schedule by Year of Assessment.
+ * Rebate = min(grossTax * rate, cap).
+ */
+export const CIT_REBATE_SCHEDULE = {
+    2020: { rate: 0.25, cap: 15_000 },
+    2021: { rate: 0.00, cap: 0 }, // COVID relief was different
+    2022: { rate: 0.00, cap: 0 },
+    2023: { rate: 0.00, cap: 0 },
+    2024: { rate: 0.50, cap: 40_000 },
+    2025: { rate: 0.50, cap: 40_000 },
+    2026: { rate: 0.40, cap: 40_000 },
+};
+/**
+ * Capital allowance rates by asset category.
+ */
+export const CA_RATES = {
+    computer: { section: 'S19A(1)', annualRate: 1.00, years: 1 },
+    automation: { section: 'S19A(1)', annualRate: 1.00, years: 1 },
+    'low-value': { section: 'S19A(2)', annualRate: 1.00, years: 1 },
+    general: { section: 'S19', annualRate: 1 / 3, years: 3 },
+    ip: { section: 'S19B', annualRate: 0.20, years: 5 }, // default 5-year
+    renovation: { section: 'S14Q', annualRate: 1 / 3, years: 3 },
+};
+/** Low-value asset per-YA total cap. */
+export const LOW_VALUE_YA_CAP = 30_000;
+/** Low-value asset per-item cost ceiling. */
+export const LOW_VALUE_ITEM_LIMIT = 5_000;
+/** S14Q renovation per-3-year-block cap. */
+export const S14Q_BLOCK_CAP = 300_000;
+/** Donation tax deduction multiplier for approved IPC donations. */
+export const DONATION_MULTIPLIER = 2.50;
+/** Month names for date formatting. */
+export const MONTH_NAMES = [
+    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+];

package/dist/tax/sg/exemptions.js

@@ -0,0 +1,76 @@
+/**
+ * Singapore corporate income tax exemptions and rebates.
+ * Pure functions — no side effects, no I/O.
+ */
+import { round2 } from '../types.js';
+import { SG_CIT_RATE, SUTE_BANDS, PTE_BANDS, CIT_REBATE_SCHEDULE, } from './constants.js';
+/**
+ * Apply banded exemption (SUTE or PTE).
+ * Each band fills in order — excess flows to the next band.
+ * Returns the total exempt amount (deducted from chargeable income before applying 17%).
+ */
+function applyBands(chargeableIncome, bands) {
+    let remaining = chargeableIncome;
+    let totalExempt = 0;
+    for (const band of bands) {
+        if (remaining <= 0)
+            break;
+        const inBand = Math.min(remaining, band.threshold);
+        totalExempt = round2(totalExempt + round2(inBand * band.exemptionRate));
+        remaining = round2(remaining - inBand);
+    }
+    return totalExempt;
+}
+/**
+ * Compute tax exemption for a given chargeable income.
+ *
+ * @param chargeableIncome — must be >= 0 (losses already absorbed upstream)
+ * @param type — 'sute' | 'pte' | 'none'
+ * @returns ExemptionResult with exempt amount, taxable income, and effective rate
+ */
+export function computeExemption(chargeableIncome, type) {
+    if (chargeableIncome <= 0) {
+        return {
+            type,
+            chargeableIncome: 0,
+            exemptAmount: 0,
+            taxableIncome: 0,
+            effectiveRate: 0,
+        };
+    }
+    let exemptAmount;
+    switch (type) {
+        case 'sute':
+            exemptAmount = applyBands(chargeableIncome, SUTE_BANDS);
+            break;
+        case 'pte':
+            exemptAmount = applyBands(chargeableIncome, PTE_BANDS);
+            break;
+        case 'none':
+            exemptAmount = 0;
+            break;
+    }
+    const taxableIncome = round2(chargeableIncome - exemptAmount);
+    const grossTax = round2(taxableIncome * SG_CIT_RATE);
+    const effectiveRate = chargeableIncome > 0
+        ? round2((grossTax / chargeableIncome) * 10000) / 10000 // 4dp for rate
+        : 0;
+    return {
+        type,
+        chargeableIncome,
+        exemptAmount,
+        taxableIncome,
+        effectiveRate,
+    };
+}
+/**
+ * Compute CIT rebate for a given YA.
+ * Rebate = min(grossTax * rebateRate, rebateCap).
+ * Returns 0 if no rebate schedule exists for the YA.
+ */
+export function computeCitRebate(grossTax, ya) {
+    const schedule = CIT_REBATE_SCHEDULE[ya];
+    if (!schedule || grossTax <= 0)
+        return 0;
+    return round2(Math.min(grossTax * schedule.rate, schedule.cap));
+}