optimal-cli 0.1.0

package/dist/lib/returnpro/anomalies.js

@@ -0,0 +1,166 @@
+import { getSupabase } from '../supabase.js';
+// --- Helpers ---
+const PAGE_SIZE = 1000;
+function toNum(v) {
+    if (v === null || v === undefined)
+        return 0;
+    return typeof v === 'string' ? parseFloat(v) || 0 : Number(v) || 0;
+}
+function toNumOrNull(v) {
+    if (v === null || v === undefined)
+        return null;
+    const n = typeof v === 'string' ? parseFloat(v) : Number(v);
+    return isFinite(n) ? n : null;
+}
+/**
+ * Paginate through v_rate_anomaly_analysis with optional month filters.
+ * Returns raw view rows.
+ */
+async function fetchViewRows(months) {
+    const sb = getSupabase('returnpro');
+    const allRows = [];
+    let from = 0;
+    while (true) {
+        let query = sb
+            .from('v_rate_anomaly_analysis')
+            .select('master_program,program_code,program_id,client_id,client_name,' +
+            'month,checkin_fee_dollars,units,rate_per_unit,prev_month_rate,' +
+            'rate_delta_pct,units_change_pct,dollars_change_pct')
+            .order('month', { ascending: false })
+            .order('master_program')
+            .range(from, from + PAGE_SIZE - 1);
+        if (months && months.length > 0) {
+            query = query.in('month', months);
+        }
+        const { data, error } = await query;
+        if (error)
+            throw new Error(`Fetch v_rate_anomaly_analysis failed: ${error.message}`);
+        if (!data || data.length === 0)
+            break;
+        allRows.push(...data);
+        if (data.length < PAGE_SIZE)
+            break;
+        from += PAGE_SIZE;
+    }
+    return allRows;
+}
+/**
+ * Compute mean and standard deviation for an array of numbers.
+ * Returns { mean, stddev }. If fewer than 2 values, stddev = 0.
+ */
+function computeStats(values) {
+    if (values.length === 0)
+        return { mean: 0, stddev: 0 };
+    const mean = values.reduce((s, v) => s + v, 0) / values.length;
+    if (values.length < 2)
+        return { mean, stddev: 0 };
+    const variance = values.reduce((s, v) => s + (v - mean) ** 2, 0) / (values.length - 1);
+    return { mean, stddev: Math.sqrt(variance) };
+}
+// --- Core ---
+/**
+ * Detect $/unit rate outliers across all programs in stg_financials_raw.
+ *
+ * Method:
+ *   1. Fetch all rows from v_rate_anomaly_analysis (paginated) filtered to
+ *      the requested months (or fiscal YTD if omitted).
+ *   2. For each month, compute mean and population stddev of rate_per_unit
+ *      across all programs with valid rates.
+ *   3. Flag any program-month where |z-score| > threshold (default 2.0).
+ *   4. Return the flagged rows sorted by |z-score| descending.
+ *
+ * @param options.months   - YYYY-MM strings to analyse. If omitted, uses fiscal
+ *                           YTD (April of current/previous fiscal year → today).
+ * @param options.threshold - Z-score magnitude threshold. Default 2.0.
+ */
+export async function detectRateAnomalies(options) {
+    const threshold = options?.threshold ?? 2.0;
+    // Resolve target months: explicit list, or derive fiscal YTD
+    let targetMonths = options?.months;
+    if (!targetMonths || targetMonths.length === 0) {
+        // Fiscal year starts April. If Jan-Mar, fiscal year began previous calendar year.
+        const now = new Date();
+        const month0 = now.getMonth(); // 0-indexed
+        const year = now.getFullYear();
+        const fiscalStartYear = month0 < 3 ? year - 1 : year;
+        const fiscalStart = `${fiscalStartYear}-04`;
+        const currentMonthStr = `${year}-${String(month0 + 1).padStart(2, '0')}`;
+        // Build explicit month list for fiscal YTD so the DB filter is tight
+        const start = new Date(`${fiscalStart}-01`);
+        const end = new Date(`${currentMonthStr}-01`);
+        const months = [];
+        const cursor = new Date(start);
+        while (cursor <= end) {
+            months.push(`${cursor.getFullYear()}-${String(cursor.getMonth() + 1).padStart(2, '0')}`);
+            cursor.setMonth(cursor.getMonth() + 1);
+        }
+        targetMonths = months;
+    }
+    // Fetch view rows
+    const rawRows = await fetchViewRows(targetMonths);
+    const totalRows = rawRows.length;
+    if (totalRows === 0) {
+        return { anomalies: [], totalRows: 0, threshold, months: targetMonths };
+    }
+    // Group rows by month for per-month z-score calculation
+    const byMonth = new Map();
+    for (const row of rawRows) {
+        const m = row.month;
+        if (!byMonth.has(m))
+            byMonth.set(m, []);
+        byMonth.get(m).push(row);
+    }
+    // Compute z-scores per month and collect anomalies
+    const anomalies = [];
+    for (const [month, rows] of byMonth) {
+        // Collect valid (non-null, positive-unit) rate values for this month
+        const validRates = rows
+            .map(r => toNumOrNull(r.rate_per_unit))
+            .filter((v) => v !== null && isFinite(v));
+        const { mean, stddev } = computeStats(validRates);
+        for (const row of rows) {
+            const rate = toNumOrNull(row.rate_per_unit);
+            if (rate === null)
+                continue; // cannot score rows with no rate
+            const units = toNum(row.units);
+            if (units <= 0)
+                continue; // require positive units for a meaningful rate
+            // Z-score: how many std-deviations from the mean
+            const zscore = stddev > 0 ? (rate - mean) / stddev : 0;
+            if (Math.abs(zscore) <= threshold)
+                continue; // within normal range
+            const expectedLow = mean - threshold * stddev;
+            const expectedHigh = mean + threshold * stddev;
+            anomalies.push({
+                master_program: row.master_program,
+                program_code: row.program_code,
+                program_id: typeof row.program_id === 'number' ? row.program_id : null,
+                client_id: typeof row.client_id === 'number' ? row.client_id : null,
+                client_name: row.client_name,
+                month,
+                checkin_fee_dollars: toNum(row.checkin_fee_dollars),
+                units,
+                rate_per_unit: rate,
+                prev_month_rate: toNumOrNull(row.prev_month_rate),
+                rate_delta_pct: toNumOrNull(row.rate_delta_pct),
+                units_change_pct: toNumOrNull(row.units_change_pct),
+                dollars_change_pct: toNumOrNull(row.dollars_change_pct),
+                zscore: Math.round(zscore * 100) / 100,
+                expected_range: [
+                    Math.round(expectedLow * 10000) / 10000,
+                    Math.round(expectedHigh * 10000) / 10000,
+                ],
+            });
+        }
+    }
+    // Sort by absolute z-score descending (most extreme outliers first)
+    anomalies.sort((a, b) => Math.abs(b.zscore) - Math.abs(a.zscore));
+    // Collect distinct months that were actually present in the data
+    const observedMonths = [...new Set(rawRows.map(r => r.month))].sort().reverse();
+    return {
+        anomalies,
+        totalRows,
+        threshold,
+        months: observedMonths,
+    };
+}

package/dist/lib/returnpro/audit.d.ts

@@ -0,0 +1,32 @@
+export interface MonthSummary {
+    month: string;
+    confirmedAccounts: number;
+    stagedAccounts: number;
+    exactMatch: number;
+    signFlipMatch: number;
+    mismatch: number;
+    confirmedOnly: number;
+    stagingOnly: number;
+    accuracy: number | null;
+    stagedTotal: number;
+    confirmedTotal: number;
+}
+export interface AuditResult {
+    summaries: MonthSummary[];
+    totalStagingRows: number;
+    totalConfirmedRows: number;
+}
+/**
+ * Compare staged financials against confirmed income statements.
+ *
+ * Replicates the logic from dashboard-returnpro's /api/staging/audit-summary route:
+ * 1. Paginate stg_financials_raw (amount is TEXT, must parseFloat)
+ * 2. Paginate confirmed_income_statements
+ * 3. Aggregate staging by account_code|YYYY-MM key
+ * 4. Compare with tolerance (default $1.00), detect sign-flips
+ * 5. Return per-month summaries with accuracy %
+ *
+ * @param months - Optional array of YYYY-MM strings to filter to. If omitted, all months are included.
+ * @param tolerance - Dollar tolerance for match detection. Default $1.00.
+ */
+export declare function runAuditComparison(months?: string[], tolerance?: number): Promise<AuditResult>;

package/dist/lib/returnpro/audit.js

@@ -0,0 +1,147 @@
+import { getSupabase } from '../supabase.js';
+// --- Helpers ---
+const PAGE_SIZE = 1000;
+/**
+ * Paginate through a Supabase table, fetching all rows.
+ * Uses .range() to bypass the 1000-row cap.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function paginateAll(table, select, orderCol) {
+    const sb = getSupabase('returnpro');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const allRows = [];
+    let from = 0;
+    while (true) {
+        const query = sb.from(table).select(select).order(orderCol).range(from, from + PAGE_SIZE - 1);
+        const { data, error } = await query;
+        if (error)
+            throw new Error(`Fetch ${table} failed: ${error.message}`);
+        if (!data || data.length === 0)
+            break;
+        allRows.push(...data);
+        if (data.length < PAGE_SIZE)
+            break;
+        from += PAGE_SIZE;
+    }
+    return allRows;
+}
+// --- Core ---
+/**
+ * Compare staged financials against confirmed income statements.
+ *
+ * Replicates the logic from dashboard-returnpro's /api/staging/audit-summary route:
+ * 1. Paginate stg_financials_raw (amount is TEXT, must parseFloat)
+ * 2. Paginate confirmed_income_statements
+ * 3. Aggregate staging by account_code|YYYY-MM key
+ * 4. Compare with tolerance (default $1.00), detect sign-flips
+ * 5. Return per-month summaries with accuracy %
+ *
+ * @param months - Optional array of YYYY-MM strings to filter to. If omitted, all months are included.
+ * @param tolerance - Dollar tolerance for match detection. Default $1.00.
+ */
+export async function runAuditComparison(months, tolerance = 1.00) {
+    // 1. Fetch all staging rows (paginated)
+    const stagingRows = await paginateAll('stg_financials_raw', 'account_code,date,amount', 'date');
+    // 2. Fetch all confirmed income statements (paginated)
+    const confirmedRows = await paginateAll('confirmed_income_statements', 'account_code,period,total_amount', 'period');
+    // 3. Aggregate staging: account_code|YYYY-MM -> sum(amount)
+    //    amount is TEXT in the DB — must parseFloat
+    const stagingAgg = new Map();
+    for (const row of stagingRows) {
+        const month = row.date ? row.date.substring(0, 7) : null;
+        if (!month)
+            continue;
+        const key = `${row.account_code}|${month}`;
+        stagingAgg.set(key, (stagingAgg.get(key) ?? 0) + (parseFloat(row.amount) || 0));
+    }
+    // 4. Build confirmed lookup: account_code|YYYY-MM -> total_amount
+    const confirmedMap = new Map();
+    for (const row of confirmedRows) {
+        const key = `${row.account_code}|${row.period}`;
+        confirmedMap.set(key, parseFloat(String(row.total_amount)) || 0);
+    }
+    // 5. Collect all months present in either dataset
+    const allMonths = new Set();
+    for (const key of stagingAgg.keys())
+        allMonths.add(key.split('|')[1]);
+    for (const key of confirmedMap.keys())
+        allMonths.add(key.split('|')[1]);
+    // 6. Filter to requested months if specified
+    const targetMonths = months
+        ? [...allMonths].filter(m => months.includes(m)).sort()
+        : [...allMonths].sort();
+    // 7. Build per-month summaries
+    const summaries = [];
+    for (const month of targetMonths) {
+        // Collect accounts present in each dataset for this month
+        const cAccounts = new Set();
+        const sAccounts = new Set();
+        for (const key of confirmedMap.keys()) {
+            if (key.endsWith(`|${month}`))
+                cAccounts.add(key.split('|')[0]);
+        }
+        for (const key of stagingAgg.keys()) {
+            if (key.endsWith(`|${month}`))
+                sAccounts.add(key.split('|')[0]);
+        }
+        let exactMatch = 0;
+        let signFlipMatch = 0;
+        let mismatch = 0;
+        let confirmedOnly = 0;
+        let stagingOnly = 0;
+        let stagedTotal = 0;
+        let confirmedTotal = 0;
+        // Compare confirmed accounts against staging
+        for (const acct of cAccounts) {
+            const cAmt = confirmedMap.get(`${acct}|${month}`) ?? 0;
+            confirmedTotal += Math.abs(cAmt);
+            if (sAccounts.has(acct)) {
+                const sAmt = stagingAgg.get(`${acct}|${month}`) ?? 0;
+                const directDiff = Math.abs(cAmt - sAmt);
+                const signFlipDiff = Math.abs(cAmt + sAmt);
+                if (directDiff <= tolerance) {
+                    exactMatch++;
+                }
+                else if (signFlipDiff <= tolerance) {
+                    signFlipMatch++;
+                }
+                else {
+                    mismatch++;
+                }
+            }
+            else {
+                confirmedOnly++;
+            }
+        }
+        // Count staging-only accounts and accumulate staged total
+        for (const acct of sAccounts) {
+            const sAmt = stagingAgg.get(`${acct}|${month}`) ?? 0;
+            stagedTotal += Math.abs(sAmt);
+            if (!cAccounts.has(acct))
+                stagingOnly++;
+        }
+        // Accuracy = (exactMatch + signFlipMatch) / overlap, null if no overlap
+        const overlap = exactMatch + signFlipMatch + mismatch;
+        const accuracy = overlap > 0
+            ? Math.round(((exactMatch + signFlipMatch) / overlap) * 1000) / 10
+            : null;
+        summaries.push({
+            month,
+            confirmedAccounts: cAccounts.size,
+            stagedAccounts: sAccounts.size,
+            exactMatch,
+            signFlipMatch,
+            mismatch,
+            confirmedOnly,
+            stagingOnly,
+            accuracy,
+            stagedTotal,
+            confirmedTotal,
+        });
+    }
+    return {
+        summaries,
+        totalStagingRows: stagingRows.length,
+        totalConfirmedRows: confirmedRows.length,
+    };
+}

package/dist/lib/returnpro/diagnose.d.ts

@@ -0,0 +1,52 @@
+export type DiagnosticIssueKind = 'unresolved_account_code' | 'unresolved_program_code' | 'unresolved_master_program' | 'unresolved_client' | 'low_row_count' | 'missing_month' | 'null_date_rows' | 'null_account_code_rows';
+export interface DiagnosticIssue {
+    /** Category of the problem. */
+    kind: DiagnosticIssueKind;
+    /** YYYY-MM if the issue is month-scoped, null if global. */
+    month: string | null;
+    /** Short human-readable summary. */
+    message: string;
+    /** Optional payload with supporting data. */
+    detail?: Record<string, unknown>;
+}
+export interface DiagnosisResult {
+    /** YYYY-MM months that were analysed. */
+    monthsAnalysed: string[];
+    /** Total rows in stg_financials_raw across the analysed months. */
+    totalRows: number;
+    /** Per-month row counts. */
+    rowsPerMonth: Record<string, number>;
+    /** Median row count across months — used to flag anomalously low months. */
+    medianRowCount: number;
+    /** All issues found. */
+    issues: DiagnosticIssue[];
+    /** Convenience summary counts. */
+    summary: {
+        unresolvedAccountCodes: number;
+        unresolvedProgramCodes: number;
+        unresolvedMasterPrograms: number;
+        unresolvedClients: number;
+        lowRowCountMonths: number;
+        missingMonths: number;
+        totalIssues: number;
+    };
+}
+/**
+ * Diagnose FK resolution failures and data gaps in stg_financials_raw.
+ *
+ * Checks performed:
+ * 1. Rows with null date or null account_code (data quality)
+ * 2. account_codes not present in dim_account
+ * 3. program_codes not present in dim_program_id
+ * 4. program_codes whose dim_program_id row has a null master_program_id
+ * 5. master_program_ids not present in dim_master_program
+ * 6. master_programs whose dim_master_program row has a null client_id
+ * 7. Months with row counts < 50% of the median (anomalously low)
+ * 8. Calendar months completely absent between the first and last month seen
+ *
+ * @param options.months - If provided, only analyse these YYYY-MM months.
+ *                         If omitted, all months present in staging are analysed.
+ */
+export declare function diagnoseMonths(options?: {
+    months?: string[];
+}): Promise<DiagnosisResult>;

package/dist/lib/returnpro/diagnose.js

@@ -0,0 +1,281 @@
+import { getSupabase } from '../supabase.js';
+// --- Helpers ---
+const PAGE_SIZE = 1000;
+/** Fetch all rows from a table with pagination, bypassing the 1000-row cap. */
+async function paginateAll(table, select, orderCol) {
+    const sb = getSupabase('returnpro');
+    const all = [];
+    let from = 0;
+    while (true) {
+        const { data, error } = await sb
+            .from(table)
+            .select(select)
+            .order(orderCol)
+            .range(from, from + PAGE_SIZE - 1);
+        if (error)
+            throw new Error(`Fetch ${table} failed: ${error.message}`);
+        if (!data || data.length === 0)
+            break;
+        all.push(...data);
+        if (data.length < PAGE_SIZE)
+            break;
+        from += PAGE_SIZE;
+    }
+    return all;
+}
+/** Compute the median of a numeric array. Returns 0 for empty arrays. */
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? (sorted[mid - 1] + sorted[mid]) / 2
+        : sorted[mid];
+}
+/**
+ * Extract YYYY-MM from a date string. Returns null if unparseable.
+ */
+function toYearMonth(date) {
+    if (!date)
+        return null;
+    const d = new Date(date);
+    if (isNaN(d.getTime()))
+        return null;
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+/**
+ * Build the list of expected YYYY-MM months between the earliest and latest
+ * months seen in staging data. Used to detect completely missing months.
+ */
+function buildExpectedMonths(present) {
+    if (present.length === 0)
+        return [];
+    const sorted = [...present].sort();
+    const first = sorted[0];
+    const last = sorted[sorted.length - 1];
+    const [fy, fm] = first.split('-').map(Number);
+    const [ly, lm] = last.split('-').map(Number);
+    const expected = [];
+    let y = fy;
+    let m = fm;
+    while (y < ly || (y === ly && m <= lm)) {
+        expected.push(`${y}-${String(m).padStart(2, '0')}`);
+        m++;
+        if (m > 12) {
+            m = 1;
+            y++;
+        }
+    }
+    return expected;
+}
+// --- Core ---
+/**
+ * Diagnose FK resolution failures and data gaps in stg_financials_raw.
+ *
+ * Checks performed:
+ * 1. Rows with null date or null account_code (data quality)
+ * 2. account_codes not present in dim_account
+ * 3. program_codes not present in dim_program_id
+ * 4. program_codes whose dim_program_id row has a null master_program_id
+ * 5. master_program_ids not present in dim_master_program
+ * 6. master_programs whose dim_master_program row has a null client_id
+ * 7. Months with row counts < 50% of the median (anomalously low)
+ * 8. Calendar months completely absent between the first and last month seen
+ *
+ * @param options.months - If provided, only analyse these YYYY-MM months.
+ *                         If omitted, all months present in staging are analysed.
+ */
+export async function diagnoseMonths(options) {
+    const issues = [];
+    // --- 1. Load all staging rows (paginated) ---
+    const stagingRows = await paginateAll('stg_financials_raw', 'raw_id,date,account_code,account_id,program_code,program_id_key,master_program,master_program_id,client_id', 'raw_id');
+    // --- 2. Load all dimension tables in parallel ---
+    const [dimAccounts, dimProgramIds, dimMasterPrograms, dimClients] = await Promise.all([
+        paginateAll('dim_account', 'account_code', 'account_code'),
+        paginateAll('dim_program_id', 'program_code,master_program_id', 'program_code'),
+        paginateAll('dim_master_program', 'master_program_id,master_name,client_id', 'master_program_id'),
+        paginateAll('dim_client', 'client_id,client_name', 'client_id'),
+    ]);
+    // Build lookup sets
+    const knownAccountCodes = new Set(dimAccounts.map(r => r.account_code));
+    const knownProgramCodes = new Set(dimProgramIds.map(r => r.program_code));
+    // dim_program_id entries that have a null master_program_id (orphaned program codes)
+    const orphanedProgramCodes = new Set(dimProgramIds.filter(r => r.master_program_id === null).map(r => r.program_code));
+    const knownMasterProgramIds = new Set(dimMasterPrograms.map(r => r.master_program_id));
+    // master programs without a client
+    const masterProgramsWithoutClient = new Set(dimMasterPrograms.filter(r => r.client_id === null).map(r => r.master_program_id));
+    const knownClientIds = new Set(dimClients.map(r => r.client_id));
+    // --- 3. Assign staging rows to months ---
+    const rowsByMonth = new Map();
+    let nullDateCount = 0;
+    let nullAccountCodeCount = 0;
+    for (const row of stagingRows) {
+        if (!row.date) {
+            nullDateCount++;
+            continue;
+        }
+        const ym = toYearMonth(row.date);
+        if (!ym) {
+            nullDateCount++;
+            continue;
+        }
+        const existing = rowsByMonth.get(ym) ?? [];
+        existing.push(row);
+        rowsByMonth.set(ym, existing);
+        if (!row.account_code)
+            nullAccountCodeCount++;
+    }
+    // --- 4. Apply month filter ---
+    let targetMonths;
+    if (options?.months && options.months.length > 0) {
+        targetMonths = options.months.filter(m => rowsByMonth.has(m)).sort();
+    }
+    else {
+        targetMonths = [...rowsByMonth.keys()].sort();
+    }
+    // --- 5. Global data quality issues ---
+    if (nullDateCount > 0) {
+        issues.push({
+            kind: 'null_date_rows',
+            month: null,
+            message: `${nullDateCount} row(s) in stg_financials_raw have a null or unparseable date`,
+            detail: { count: nullDateCount },
+        });
+    }
+    if (nullAccountCodeCount > 0) {
+        issues.push({
+            kind: 'null_account_code_rows',
+            month: null,
+            message: `${nullAccountCodeCount} row(s) in stg_financials_raw have a null account_code`,
+            detail: { count: nullAccountCodeCount },
+        });
+    }
+    // --- 6. Per-month analysis ---
+    const rowsPerMonth = {};
+    // Aggregate FK failure sets per dimension (global, deduplicated)
+    const unresolvedAccountCodes = new Set();
+    const unresolvedProgramCodes = new Set();
+    const unresolvedMasterProgramIds = new Set();
+    const unresolvedClientIds = new Set();
+    for (const month of targetMonths) {
+        const rows = rowsByMonth.get(month) ?? [];
+        rowsPerMonth[month] = rows.length;
+        for (const row of rows) {
+            // account_code → dim_account
+            if (row.account_code && !knownAccountCodes.has(row.account_code)) {
+                unresolvedAccountCodes.add(row.account_code);
+            }
+            // program_code → dim_program_id
+            if (row.program_code) {
+                if (!knownProgramCodes.has(row.program_code)) {
+                    unresolvedProgramCodes.add(row.program_code);
+                }
+                else if (orphanedProgramCodes.has(row.program_code)) {
+                    // The program_code exists in dim_program_id but its master_program_id is null
+                    unresolvedProgramCodes.add(row.program_code);
+                }
+            }
+            // master_program_id → dim_master_program
+            if (row.master_program_id !== null && row.master_program_id !== undefined) {
+                if (!knownMasterProgramIds.has(row.master_program_id)) {
+                    unresolvedMasterProgramIds.add(row.master_program_id);
+                }
+                else if (masterProgramsWithoutClient.has(row.master_program_id)) {
+                    // master_program exists but has no client_id
+                    unresolvedClientIds.add(row.master_program_id);
+                }
+            }
+            // client_id → dim_client (direct FK on staging row)
+            if (row.client_id !== null && row.client_id !== undefined) {
+                if (!knownClientIds.has(row.client_id)) {
+                    unresolvedClientIds.add(row.client_id);
+                }
+            }
+        }
+    }
+    // Emit per-dimension issues (global, not per-month — less noise)
+    if (unresolvedAccountCodes.size > 0) {
+        const codes = [...unresolvedAccountCodes].sort();
+        issues.push({
+            kind: 'unresolved_account_code',
+            month: null,
+            message: `${codes.length} account_code(s) in staging do not resolve to dim_account`,
+            detail: { codes },
+        });
+    }
+    if (unresolvedProgramCodes.size > 0) {
+        const codes = [...unresolvedProgramCodes].sort();
+        issues.push({
+            kind: 'unresolved_program_code',
+            month: null,
+            message: `${codes.length} program_code(s) in staging do not resolve (missing from dim_program_id or dim_program_id.master_program_id is null)`,
+            detail: { codes },
+        });
+    }
+    if (unresolvedMasterProgramIds.size > 0) {
+        const ids = [...unresolvedMasterProgramIds].sort((a, b) => a - b);
+        issues.push({
+            kind: 'unresolved_master_program',
+            month: null,
+            message: `${ids.length} master_program_id(s) in staging do not resolve to dim_master_program`,
+            detail: { ids },
+        });
+    }
+    if (unresolvedClientIds.size > 0) {
+        const ids = [...unresolvedClientIds].sort((a, b) => a - b);
+        issues.push({
+            kind: 'unresolved_client',
+            month: null,
+            message: `${ids.length} client_id(s) in staging do not resolve to dim_client (or master_program has no client)`,
+            detail: { ids },
+        });
+    }
+    // --- 7. Row count anomalies (< 50% of median) ---
+    const counts = targetMonths.map(m => rowsPerMonth[m] ?? 0);
+    const med = median(counts);
+    const lowThreshold = med * 0.5;
+    for (const month of targetMonths) {
+        const count = rowsPerMonth[month] ?? 0;
+        if (med > 0 && count < lowThreshold) {
+            issues.push({
+                kind: 'low_row_count',
+                month,
+                message: `${month} has only ${count} rows — below 50% of median (${med})`,
+                detail: { rowCount: count, median: med, threshold: lowThreshold },
+            });
+        }
+    }
+    // --- 8. Missing months (gaps in the calendar range) ---
+    const allPresentMonths = [...rowsByMonth.keys()].sort();
+    const expectedMonths = buildExpectedMonths(allPresentMonths);
+    const presentSet = new Set(allPresentMonths);
+    for (const expected of expectedMonths) {
+        // Only flag months within the analysed range that are entirely absent
+        if (!presentSet.has(expected)) {
+            issues.push({
+                kind: 'missing_month',
+                month: expected,
+                message: `${expected} has no rows in stg_financials_raw — month is missing`,
+            });
+        }
+    }
+    // --- 9. Compute summary ---
+    const summary = {
+        unresolvedAccountCodes: unresolvedAccountCodes.size,
+        unresolvedProgramCodes: unresolvedProgramCodes.size,
+        unresolvedMasterPrograms: unresolvedMasterProgramIds.size,
+        unresolvedClients: unresolvedClientIds.size,
+        lowRowCountMonths: issues.filter(i => i.kind === 'low_row_count').length,
+        missingMonths: issues.filter(i => i.kind === 'missing_month').length,
+        totalIssues: issues.length,
+    };
+    return {
+        monthsAnalysed: targetMonths,
+        totalRows: counts.reduce((a, b) => a + b, 0),
+        rowsPerMonth,
+        medianRowCount: med,
+        issues,
+        summary,
+    };
+}