@viccydev/pi-fpa 0.9.5 → 0.9.7

package/extensions/fpa-data/csvsource.ts

@@ -0,0 +1,296 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+
+import { getDataset, type DatasetDef } from "./registry.ts";
+import type { QuerySpec } from "./sql.ts";
+
+// ============================================================================
+// A CSV-backed executor for the same QuerySpec the SQL builder compiles.
+//
+// The registry, the query spec, the derived-metric engine, and the query
+// receipt are all shared with the Supabase path — only the execution differs.
+// That is the point: when the real finance import lands, this file is the only
+// thing that gets replaced, and every metric definition and every projector
+// keeps working untouched.
+//
+// The aggregation deliberately matches SQL, including the part people get
+// wrong: SUM over a set where every contributing value is NULL is NULL, not 0.
+// An FP&A dashboard that reports 0 for "we have no data" is worse than one
+// that reports nothing.
+// ============================================================================
+
+const MAX_FILE_BYTES = 32 * 1024 * 1024;
+const MAX_ROWS = 500_000;
+
+export const CSV_ROOT_ENV = "FPA_FINANCE_CSV_ROOT";
+
+/** Where a project's finance CSVs live, beside the projects like `.fpa-dashboard`. */
+export const FINANCE_DIR_NAME = ".fpa-finance";
+
+/**
+ * Resolve the finance CSV directory for one project.
+ *
+ * Defaults to the workspace-level `.fpa-finance/`, so a tenant reads only its
+ * own financials. The env override exists for a genuinely shared company
+ * source, and is explicit precisely because pointing every tenant at one
+ * directory is a data-leak shaped decision that should never be the default.
+ */
+export function resolveCsvRoot(env: NodeJS.ProcessEnv = process.env, workspaceRoot?: string): string {
+	const configured = env[CSV_ROOT_ENV]?.trim();
+	if (configured) {
+		if (!isAbsolute(configured)) throw new Error(`${CSV_ROOT_ENV} must be an absolute path.`);
+		return resolve(configured);
+	}
+	if (workspaceRoot) return join(resolve(workspaceRoot), FINANCE_DIR_NAME);
+	throw new Error(
+		`Finance CSV datasets need either a project directory or ${CSV_ROOT_ENV} pointing at the directory holding them. ` +
+			"No query was run.",
+	);
+}
+
+/** Parse one CSV line, honouring quoted fields and doubled quotes. */
+function parseLine(line: string): string[] {
+	const cells: string[] = [];
+	let current = "";
+	let quoted = false;
+	for (let index = 0; index < line.length; index += 1) {
+		const char = line[index];
+		if (quoted) {
+			if (char === '"' && line[index + 1] === '"') {
+				current += '"';
+				index += 1;
+			} else if (char === '"') {
+				quoted = false;
+			} else {
+				current += char;
+			}
+		} else if (char === '"') {
+			quoted = true;
+		} else if (char === ",") {
+			cells.push(current);
+			current = "";
+		} else {
+			current += char;
+		}
+	}
+	cells.push(current);
+	return cells;
+}
+
+export interface CsvTable {
+	headers: string[];
+	rows: Array<Record<string, string>>;
+}
+
+export async function readCsvTable(path: string): Promise<CsvTable> {
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			throw new Error(`Finance CSV file does not exist: ${path}`);
+		}
+		throw error;
+	}
+	if (Buffer.byteLength(raw, "utf8") > MAX_FILE_BYTES) {
+		throw new Error(`Finance CSV file exceeds the ${MAX_FILE_BYTES / (1024 * 1024)}MB limit: ${path}`);
+	}
+	const lines = raw.split("\n").filter((line, index) => index === 0 || line.trim() !== "");
+	if (lines.length === 0) throw new Error(`Finance CSV file is empty: ${path}`);
+	const headers = parseLine(lines[0]).map((header) => header.trim());
+	const rows: Array<Record<string, string>> = [];
+	for (const line of lines.slice(1)) {
+		if (rows.length >= MAX_ROWS) throw new Error(`Finance CSV file exceeds the ${MAX_ROWS}-row limit: ${path}`);
+		const cells = parseLine(line);
+		const row: Record<string, string> = {};
+		headers.forEach((header, index) => { row[header] = cells[index] ?? ""; });
+		rows.push(row);
+	}
+	return { headers, rows };
+}
+
+/** An empty cell is missing, not zero. */
+function cellValue(raw: string | undefined): number | null {
+	if (raw === undefined || raw.trim() === "") return null;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * The row's date, normalised so a YYYY-MM column compares against the
+ * YYYY-MM-DD bounds the query spec carries.
+ */
+function rowDate(value: string | undefined, format: "month" | "date"): string | null {
+	if (!value || value.trim() === "") return null;
+	const text = value.trim();
+	return format === "month" ? `${text}-01` : text;
+}
+
+interface Accumulator {
+	sum: number;
+	count: number;
+	/** Null until a non-null value arrives, which is what keeps all-NULL null. */
+	seen: boolean;
+	min: number;
+	max: number;
+	last: number | null;
+}
+
+function aggregate(accumulator: Accumulator, fn: "sum" | "avg" | "min" | "max" | "last"): number | null {
+	if (!accumulator.seen) return null;
+	switch (fn) {
+		case "sum": return accumulator.sum;
+		case "avg": return accumulator.count === 0 ? null : accumulator.sum / accumulator.count;
+		case "min": return accumulator.min;
+		case "max": return accumulator.max;
+		case "last": return accumulator.last;
+	}
+}
+
+export interface CsvQueryResult {
+	rows: Array<Record<string, unknown>>;
+	dataset: DatasetDef;
+	measures: string[];
+	dimensions: string[];
+	notes: string[];
+}
+
+export async function runCsvQuery(
+	spec: QuerySpec,
+	env: NodeJS.ProcessEnv = process.env,
+	workspaceRoot?: string,
+): Promise<CsvQueryResult> {
+	const dataset = getDataset(spec.dataset);
+	if (dataset.source !== "csv" || !dataset.csv) throw new Error(`Dataset "${dataset.id}" is not CSV-backed.`);
+	for (const unsupported of ["exactUaScope", "exactUaPortfolioScope", "exactUaChannelScope"] as const) {
+		if (spec[unsupported] !== undefined) throw new Error(`${unsupported} is supported only for ua_spend.`);
+	}
+
+	const notes: string[] = [];
+	const dimensionNames = spec.dimensions ?? [];
+	const dimensionDefs = dimensionNames.map((name) => {
+		const def = dataset.dimensions.find((dimension) => dimension.name === name);
+		if (!def) {
+			throw new Error(
+				`Unknown dimension "${name}" for dataset "${dataset.id}". ` +
+					`Available: ${dataset.dimensions.map((dimension) => dimension.name).join(", ")}.`,
+			);
+		}
+		return def;
+	});
+
+	// Resolve metrics against the same registry rules the SQL path uses:
+	// a derived metric pulls in its numerator and denominator.
+	const baseNames = new Set(dataset.measures.map((measure) => measure.name));
+	const derivedByName = new Map(dataset.derived.map((derived) => [derived.name, derived]));
+	const selected = new Set<string>();
+	const derived: DatasetDef["derived"] = [];
+	for (const metric of spec.metrics) {
+		if (baseNames.has(metric)) {
+			selected.add(metric);
+		} else if (derivedByName.has(metric)) {
+			const def = derivedByName.get(metric)!;
+			derived.push(def);
+			selected.add(def.numerator);
+			selected.add(def.denominator);
+		} else {
+			throw new Error(
+				`Unknown metric "${metric}" for dataset "${dataset.id}". ` +
+					`Available metrics: ${[...baseNames, ...derivedByName.keys()].join(", ")}.`,
+			);
+		}
+	}
+	if (selected.size === 0) throw new Error("At least one metric is required.");
+
+	const table = await readCsvTable(join(resolveCsvRoot(env, workspaceRoot), dataset.csv.file));
+	const dateFormat = dataset.csv.dateFormat ?? "date";
+
+	const filters: Array<{ column: string; values: Set<string> }> = [];
+	for (const [key, raw] of Object.entries(spec.filters ?? {})) {
+		const def = dataset.dimensions.find((dimension) => dimension.name === key);
+		if (!def) {
+			throw new Error(
+				`Unknown filter field "${key}" for dataset "${dataset.id}". ` +
+					`Filterable fields: ${dataset.dimensions.map((dimension) => dimension.name).join(", ")}. ` +
+					"Use dateFrom/dateTo for the date range.",
+			);
+		}
+		const values = Array.isArray(raw) ? raw : [raw];
+		if (values.length === 0) throw new Error("Filter arrays must contain at least one value.");
+		filters.push({ column: def.sql, values: new Set(values.map(String)) });
+	}
+
+	const groups = new Map<string, { key: Record<string, string>; accumulators: Map<string, Accumulator>; sourceRows: number }>();
+	for (const row of table.rows) {
+		const date = rowDate(row[dataset.dateColumn], dateFormat);
+		if (spec.dateFrom && (date === null || date < spec.dateFrom)) continue;
+		if (spec.dateTo && (date === null || date > spec.dateTo)) continue;
+		if (filters.some((filter) => !filter.values.has(row[filter.column] ?? ""))) continue;
+
+		const key = Object.fromEntries(dimensionDefs.map((def) => [def.name, row[def.sql] ?? ""]));
+		const groupKey = dimensionDefs.map((def) => row[def.sql] ?? "").join("");
+		let group = groups.get(groupKey);
+		if (!group) {
+			group = { key, accumulators: new Map(), sourceRows: 0 };
+			groups.set(groupKey, group);
+		}
+		group.sourceRows += 1;
+		for (const measure of selected) {
+			const column = dataset.measures.find((entry) => entry.name === measure)!.sql;
+			const value = cellValue(row[column]);
+			let accumulator = group.accumulators.get(measure);
+			if (!accumulator) {
+				accumulator = { sum: 0, count: 0, seen: false, min: Infinity, max: -Infinity, last: null };
+				group.accumulators.set(measure, accumulator);
+			}
+			// A NULL contributes nothing and does not make the group non-null.
+			if (value === null) continue;
+			accumulator.seen = true;
+			accumulator.sum += value;
+			accumulator.count += 1;
+			accumulator.min = Math.min(accumulator.min, value);
+			accumulator.max = Math.max(accumulator.max, value);
+			accumulator.last = value;
+		}
+	}
+
+	let rows = [...groups.values()].map((group) => {
+		const out: Record<string, unknown> = { ...group.key, source_rows: group.sourceRows };
+		for (const measure of selected) {
+			const fn = dataset.csv!.aggregates[measure] ?? "sum";
+			const accumulator = group.accumulators.get(measure);
+			out[measure] = accumulator ? aggregate(accumulator, fn) : null;
+		}
+		return out;
+	});
+
+	if (spec.sort) {
+		const { by, direction = "desc" } = spec.sort;
+		if (!selected.has(by) && !dimensionNames.includes(by) && !derived.some((def) => def.name === by)) {
+			throw new Error(`Cannot sort by "${by}": it is not a selected metric or dimension.`);
+		}
+		rows.sort((left, right) => {
+			const a = left[by];
+			const b = right[by];
+			// Nulls sort last in both directions: a missing value is not the
+			// smallest value, it is an absent one.
+			if (a === null && b === null) return 0;
+			if (a === null) return 1;
+			if (b === null) return -1;
+			const comparison = typeof a === "number" && typeof b === "number" ? a - b : String(a).localeCompare(String(b));
+			return direction === "asc" ? comparison : -comparison;
+		});
+	} else if (dimensionNames.length > 0) {
+		rows.sort((left, right) => dimensionNames
+			.map((name) => String(left[name] ?? "").localeCompare(String(right[name] ?? "")))
+			.find((value) => value !== 0) ?? 0);
+	}
+
+	const limit = spec.limit ?? 200;
+	if (rows.length > limit) {
+		notes.push(`Returned the first ${limit} of ${rows.length} groups.`);
+		rows = rows.slice(0, limit);
+	}
+
+	return { rows, dataset, measures: [...selected], dimensions: dimensionNames, notes };
+}

package/extensions/fpa-data/registry.ts

@@ -46,6 +46,15 @@ export interface BreakdownRule {
 	byDimension: Record<string, string>;
 }
 
+export interface CsvSourceDef {
+	/** File name inside the configured finance CSV root. */
+	file: string;
+	/** "month" when the date column holds YYYY-MM rather than YYYY-MM-DD. */
+	dateFormat?: "month" | "date";
+	/** Measure name -> how its column aggregates within a group. */
+	aggregates: Record<string, "sum" | "avg" | "min" | "max" | "last">;
+}
+
 export interface DatasetDef {
 	id: string;
 	table: string;
@@ -59,6 +68,14 @@ export interface DatasetDef {
 	eventName?: EventNameExpansion;
 	/** Extra FROM clause fragments (lateral joins) required by the measures. */
 	lateral?: string;
+	/**
+	 * Where the rows come from. Defaults to "sql" so every existing dataset is
+	 * unchanged. A "csv" dataset shares the same registry, query spec, derived
+	 * metrics, and query receipt — only the executor differs, so swapping the
+	 * finance import for a real one later touches nothing above this line.
+	 */
+	source?: "sql" | "csv";
+	csv?: CsvSourceDef;
 }
 
 const AF_METRIC_FIELDS: Record<string, string> = {
@@ -255,6 +272,313 @@ export const DATASETS: DatasetDef[] = [
 			measures: { event_count: "sum((e.v)::numeric)" },
 		},
 	},
+
+	// ------------------------------------------------------------------
+	// Finance datasets, currently CSV-backed.
+	//
+	// The UA mart answers "what did we spend and earn on advertising". These
+	// answer "what does the business look like" — cash, cost structure, unit
+	// economics. Declared here rather than in a separate registry so the same
+	// vetted-names rule holds: the model picks a name, code does the
+	// arithmetic, and swapping CSV for a real import changes only the executor.
+	// ------------------------------------------------------------------
+	{
+		id: "pnl_monthly",
+		table: "pnl_monthly.csv",
+		dateColumn: "month",
+		description: "Portfolio monthly P&L bridge: billings through to net free cash flow",
+		source: "csv",
+		csv: {
+			file: "pnl_monthly.csv",
+			dateFormat: "month",
+			aggregates: {
+				gross_billings: "sum", refunds: "sum", platform_fee: "sum", net_proceeds: "sum",
+				ua_spend: "sum", contribution_margin: "sum", tax: "sum", opex_total: "sum", net_fcf: "sum",
+			},
+		},
+		dimensions: [
+			{ name: "month", sql: "month", description: "Calendar month (YYYY-MM)" },
+			{ name: "close_status", sql: "close_status", description: "closed or open — an open month has no final tax, opex, or FCF" },
+			{ name: "data_completeness", sql: "data_completeness", description: "complete, or partial when a source app row was missing" },
+		],
+		measures: [
+			{ name: "gross_billings", sql: "gross_billings", description: "Store gross billings", unit: "usd" },
+			{ name: "refunds", sql: "refunds", description: "Refunds", unit: "usd" },
+			{ name: "platform_fee", sql: "platform_fee", description: "Store commission", unit: "usd" },
+			{ name: "net_proceeds", sql: "net_proceeds", description: "Net proceeds after refunds and commission", unit: "usd" },
+			{ name: "ua_spend", sql: "ua_spend", description: "UA spend", unit: "usd" },
+			{ name: "contribution_margin", sql: "contribution_margin", description: "Net proceeds less UA spend", unit: "usd" },
+			{ name: "tax", sql: "tax", description: "Tax", unit: "usd" },
+			{ name: "opex_total", sql: "opex_total", description: "Operating expenses (company level, not attributable to an app)", unit: "usd" },
+			{ name: "net_fcf", sql: "net_fcf", description: "Net free cash flow", unit: "usd" },
+		],
+		derived: [
+			{ name: "fcf_margin", description: "net_fcf / net_proceeds", numerator: "net_fcf", denominator: "net_proceeds", unit: "ratio" },
+			{ name: "roas_blended", description: "net_proceeds / ua_spend", numerator: "net_proceeds", denominator: "ua_spend", unit: "ratio" },
+		],
+		notes: [
+			"An open month has NULL tax, opex_total, and net_fcf — the books are not closed, so those figures do not exist yet.",
+			"data_completeness=partial means a source app row was missing and the portfolio total is understated; report it as incomplete rather than as a clean aggregate.",
+		],
+	},
+	{
+		id: "pnl_by_app_monthly",
+		table: "pnl_by_app_monthly.csv",
+		dateColumn: "month",
+		description: "Per-app monthly contribution: billings through to contribution margin",
+		source: "csv",
+		csv: {
+			file: "pnl_by_app_monthly.csv",
+			dateFormat: "month",
+			aggregates: {
+				gross_billings: "sum", refunds: "sum", platform_fee: "sum",
+				net_proceeds: "sum", ua_spend: "sum", contribution_margin: "sum",
+			},
+		},
+		dimensions: [
+			{ name: "month", sql: "month", description: "Calendar month (YYYY-MM)" },
+			{ name: "app_id", sql: "app_id", description: "Internal app code, joins to ua_spend.app_code" },
+			{ name: "app_name", sql: "app_name", description: "Product name" },
+			{ name: "store", sql: "store", description: "ios or android" },
+			{ name: "close_status", sql: "close_status", description: "closed or open" },
+		],
+		measures: [
+			{ name: "gross_billings", sql: "gross_billings", description: "Store gross billings", unit: "usd" },
+			{ name: "refunds", sql: "refunds", description: "Refunds", unit: "usd" },
+			{ name: "platform_fee", sql: "platform_fee", description: "Store commission", unit: "usd" },
+			{ name: "net_proceeds", sql: "net_proceeds", description: "Net proceeds", unit: "usd" },
+			{ name: "ua_spend", sql: "ua_spend", description: "UA spend", unit: "usd" },
+			{ name: "contribution_margin", sql: "contribution_margin", description: "Net proceeds less UA spend", unit: "usd" },
+		],
+		derived: [
+			{ name: "contribution_rate", description: "contribution_margin / net_proceeds", numerator: "contribution_margin", denominator: "net_proceeds", unit: "ratio" },
+			{ name: "app_roas", description: "net_proceeds / ua_spend", numerator: "net_proceeds", denominator: "ua_spend", unit: "ratio" },
+		],
+		notes: [
+			"Stops at contribution_margin on purpose: opex is a company-level cost and allocating it per app would manufacture precision that does not exist. Only the portfolio has net_fcf.",
+		],
+	},
+	{
+		id: "opex_monthly",
+		table: "opex_monthly.csv",
+		dateColumn: "month",
+		description: "Operating expense by category",
+		source: "csv",
+		csv: { file: "opex_monthly.csv", dateFormat: "month", aggregates: { amount_usd: "sum", headcount: "last" } },
+		dimensions: [
+			{ name: "month", sql: "month", description: "Calendar month (YYYY-MM)" },
+			{ name: "category", sql: "category", description: "personnel, infrastructure, third_party_services, marketing_non_ua, general_admin" },
+			{ name: "close_status", sql: "close_status", description: "closed or open" },
+		],
+		measures: [
+			{ name: "amount_usd", sql: "amount_usd", description: "Expense amount", unit: "usd" },
+			{ name: "headcount", sql: "headcount", description: "Headcount (personnel rows only)", unit: "count" },
+		],
+		derived: [],
+		notes: ["Categories sum to pnl_monthly.opex_total for the same closed month."],
+	},
+	{
+		id: "cash_position_monthly",
+		table: "cash_position_monthly.csv",
+		dateColumn: "month",
+		description: "Cash roll-forward and runway",
+		source: "csv",
+		csv: {
+			file: "cash_position_monthly.csv",
+			dateFormat: "month",
+			aggregates: {
+				opening_cash: "last", net_fcf: "sum", financing_inflow: "sum",
+				other_movements: "sum", closing_cash: "last", monthly_fixed_outflow: "last", runway_months: "last",
+			},
+		},
+		dimensions: [
+			{ name: "month", sql: "month", description: "Calendar month (YYYY-MM)" },
+			{ name: "close_status", sql: "close_status", description: "closed or open" },
+		],
+		measures: [
+			{ name: "opening_cash", sql: "opening_cash", description: "Opening cash", unit: "usd" },
+			{ name: "net_fcf", sql: "net_fcf", description: "Net free cash flow", unit: "usd" },
+			{ name: "financing_inflow", sql: "financing_inflow", description: "Financing inflow", unit: "usd" },
+			{ name: "other_movements", sql: "other_movements", description: "Other cash movements", unit: "usd" },
+			{ name: "closing_cash", sql: "closing_cash", description: "Closing cash", unit: "usd" },
+			{ name: "monthly_fixed_outflow", sql: "monthly_fixed_outflow", description: "Opex plus UA spend", unit: "usd" },
+			{ name: "runway_months", sql: "runway_months", description: "Closing cash divided by monthly fixed outflow", unit: "ratio" },
+		],
+		derived: [],
+		notes: [
+			"runway_months is cash over fixed outflow, not over net burn: burn-based runway is NULL or infinite while FCF is positive, which tells the reader nothing.",
+			"Balances are point-in-time. Aggregating several months returns the last month's balance, never a sum.",
+		],
+	},
+	{
+		id: "cohort_ltv",
+		table: "cohort_ltv.csv",
+		dateColumn: "install_month",
+		description: "Install cohorts by app, store, and channel: CAC, revenue curve, LTV, payback",
+		source: "csv",
+		csv: {
+			file: "cohort_ltv.csv",
+			dateFormat: "month",
+			aggregates: {
+				installs: "sum", ua_spend: "sum", cac: "avg",
+				revenue_d0: "sum", revenue_d7: "sum", revenue_d30: "sum", revenue_d90: "sum", revenue_d180: "sum",
+				ltv_180: "avg", payback_days: "avg", roas_d180: "avg",
+			},
+		},
+		dimensions: [
+			{ name: "install_month", sql: "install_month", description: "Install cohort month (YYYY-MM)" },
+			{ name: "app_id", sql: "app_id", description: "Internal app code" },
+			{ name: "store", sql: "store", description: "ios or android" },
+			{ name: "channel_group", sql: "channel_group", description: "Channel, same values as ua_spend.media_source" },
+			{ name: "maturity", sql: "maturity", description: "mature, partial, or immature" },
+		],
+		measures: [
+			{ name: "installs", sql: "installs", description: "Attributed installs", unit: "count" },
+			{ name: "ua_spend", sql: "ua_spend", description: "Cohort UA spend", unit: "usd" },
+			{ name: "cac", sql: "cac", description: "Cost per acquisition", unit: "usd" },
+			{ name: "revenue_d0", sql: "revenue_d0", description: "Cumulative revenue at day 0", unit: "usd" },
+			{ name: "revenue_d7", sql: "revenue_d7", description: "Cumulative revenue at day 7", unit: "usd" },
+			{ name: "revenue_d30", sql: "revenue_d30", description: "Cumulative revenue at day 30", unit: "usd" },
+			{ name: "revenue_d90", sql: "revenue_d90", description: "Cumulative revenue at day 90", unit: "usd" },
+			{ name: "revenue_d180", sql: "revenue_d180", description: "Cumulative revenue at day 180", unit: "usd" },
+			{ name: "ltv_180", sql: "ltv_180", description: "180-day LTV per install", unit: "usd" },
+			{ name: "payback_days", sql: "payback_days", description: "Days to recover CAC", unit: "count" },
+			{ name: "roas_d180", sql: "roas_d180", description: "180-day ROAS", unit: "ratio" },
+		],
+		derived: [
+			{ name: "ltv_to_cac", description: "ltv_180 / cac", numerator: "ltv_180", denominator: "cac", unit: "ratio" },
+		],
+		notes: [
+			"Immature cohorts carry NULL for the horizons they have not reached. A zero there would read as a failed cohort and get cut.",
+		],
+	},
+	{
+		id: "subscription_metrics",
+		table: "subscription_metrics.csv",
+		dateColumn: "month",
+		description: "Subscription counts, renewal rates by month of tenure, and refund rate",
+		source: "csv",
+		csv: {
+			file: "subscription_metrics.csv",
+			dateFormat: "month",
+			aggregates: {
+				new_subscriptions: "sum", active_subscriptions: "sum",
+				renewal_rate_m1: "avg", renewal_rate_m2: "avg", renewal_rate_m3: "avg", refund_rate: "avg",
+			},
+		},
+		dimensions: [
+			{ name: "month", sql: "month", description: "Calendar month (YYYY-MM)" },
+			{ name: "app_id", sql: "app_id", description: "Internal app code" },
+			{ name: "store", sql: "store", description: "ios or android" },
+			{ name: "close_status", sql: "close_status", description: "closed or open" },
+		],
+		measures: [
+			{ name: "new_subscriptions", sql: "new_subscriptions", description: "New subscriptions", unit: "count" },
+			{ name: "active_subscriptions", sql: "active_subscriptions", description: "Active subscriptions", unit: "count" },
+			{ name: "renewal_rate_m1", sql: "renewal_rate_m1", description: "Month-1 renewal rate", unit: "ratio" },
+			{ name: "renewal_rate_m2", sql: "renewal_rate_m2", description: "Month-2 renewal rate", unit: "ratio" },
+			{ name: "renewal_rate_m3", sql: "renewal_rate_m3", description: "Month-3 renewal rate", unit: "ratio" },
+			{ name: "refund_rate", sql: "refund_rate", description: "Refund rate", unit: "ratio" },
+		],
+		derived: [],
+		notes: [
+			"Renewal rates are averaged across the grouped rows, never summed — a rate has no meaningful sum.",
+		],
+	},
+	{
+		id: "forecast_vs_actual",
+		table: "forecast_vs_actual.csv",
+		dateColumn: "month",
+		description: "Forecast against actual by month, metric, and forecast vintage",
+		source: "csv",
+		csv: {
+			file: "forecast_vs_actual.csv",
+			dateFormat: "month",
+			aggregates: {
+				forecast_value: "sum", actual_value: "sum", variance: "sum",
+				variance_pct: "avg", abs_pct_error: "avg",
+			},
+		},
+		dimensions: [
+			{ name: "month", sql: "month", description: "Calendar month (YYYY-MM)" },
+			{ name: "metric", sql: "metric", description: "Which figure was forecast" },
+			{ name: "forecast_age_months", sql: "forecast_age_months", description: "How long before the month the forecast was made" },
+			{ name: "forecast_version", sql: "forecast_version", description: "Forecast identity" },
+		],
+		measures: [
+			{ name: "forecast_value", sql: "forecast_value", description: "Forecast figure", unit: "usd" },
+			{ name: "actual_value", sql: "actual_value", description: "Actual figure", unit: "usd" },
+			{ name: "variance", sql: "variance", description: "Actual less forecast", unit: "usd" },
+			{ name: "variance_pct", sql: "variance_pct", description: "Variance over forecast", unit: "ratio" },
+			{ name: "abs_pct_error", sql: "abs_pct_error", description: "Absolute percentage error", unit: "ratio" },
+		],
+		derived: [],
+		notes: [
+			"Compare like vintages: a 1-month-ahead forecast and a 3-month-ahead one are different claims about the same month.",
+			"abs_pct_error averages into MAPE; it must never be summed.",
+		],
+	},
+	{
+		id: "variance_attribution",
+		table: "variance_attribution.csv",
+		dateColumn: "month",
+		description: "Named causes a month's variance decomposes into",
+		source: "csv",
+		csv: {
+			file: "variance_attribution.csv",
+			dateFormat: "month",
+			aggregates: { impact_usd: "sum", impact_share: "sum", confidence: "avg" },
+		},
+		dimensions: [
+			{ name: "month", sql: "month", description: "Calendar month (YYYY-MM)" },
+			{ name: "metric", sql: "metric", description: "Which figure the variance belongs to" },
+			{ name: "factor", sql: "factor", description: "The named cause" },
+			{ name: "category", sql: "category", description: "Cause category; 'unexplained' is the residual" },
+			{ name: "confidence_band", sql: "confidence_band", description: "high, medium, or low" },
+		],
+		measures: [
+			{ name: "impact_usd", sql: "impact_usd", description: "Signed contribution to the variance", unit: "usd" },
+			{ name: "impact_share", sql: "impact_share", description: "Share of the total variance", unit: "ratio" },
+			{ name: "confidence", sql: "confidence", description: "Attribution confidence", unit: "ratio" },
+		],
+		derived: [],
+		notes: [
+			"Factors sum to the month's variance. A category of 'unexplained' is the part no factor accounts for — report it rather than dropping it, or the decomposition will read as complete when it is not.",
+		],
+	},
+	{
+		id: "baseline_assumptions",
+		table: "baseline_assumptions.csv",
+		dateColumn: "detected_at",
+		description: "Model baseline assumptions and the corrections detected against them",
+		source: "csv",
+		csv: {
+			file: "baseline_assumptions.csv",
+			dateFormat: "date",
+			aggregates: { current_value: "last", suggested_value: "last", estimated_impact_usd_12m: "sum" },
+		},
+		dimensions: [
+			{ name: "assumption_id", sql: "assumption_id", description: "Assumption identity" },
+			{ name: "assumption_name", sql: "assumption_name", description: "Human-readable name" },
+			{ name: "scope", sql: "scope", description: "What the assumption applies to" },
+			{ name: "unit", sql: "unit", description: "Value unit" },
+			{ name: "detection_basis", sql: "detection_basis", description: "Why a correction was proposed" },
+			{ name: "affected_models", sql: "affected_models", description: "Models the change would move" },
+			{ name: "approval_status", sql: "approval_status", description: "current, pending, or approved" },
+			{ name: "approver_role", sql: "approver_role", description: "Who must approve a change" },
+			{ name: "detected_at", sql: "detected_at", description: "When the drift was detected" },
+			{ name: "effective_from", sql: "effective_from", description: "When an approved change takes effect" },
+		],
+		measures: [
+			{ name: "current_value", sql: "current_value", description: "Baseline in force", unit: "ratio" },
+			{ name: "suggested_value", sql: "suggested_value", description: "Proposed baseline; null when none is proposed", unit: "ratio" },
+			{ name: "estimated_impact_usd_12m", sql: "estimated_impact_usd_12m", description: "Estimated 12-month impact of adopting the proposal", unit: "usd" },
+		],
+		derived: [],
+		notes: [
+			"A pending correction is a proposal, not a fact. It must never be applied to a projection before its approver has accepted it.",
+		],
+	},
 ];
 
 export const DATASET_IDS = DATASETS.map((d) => d.id);

package/extensions/fpa-data/runtime.ts

@@ -1,4 +1,6 @@
 import { computeDerived, round, toNumber, type NumericLike } from "./calc.ts";
+import { runCsvQuery } from "./csvsource.ts";
+import { getDataset } from "./registry.ts";
 import { buildQuery, type QuerySpec } from "./sql.ts";
 import { runQuery, type SqlRow } from "./supabase.ts";
 
@@ -15,7 +17,25 @@ export function shapeQueryRows(
 	});
 }
 
-export async function runStructuredQuery(spec: QuerySpec, signal?: AbortSignal) {
+export async function runStructuredQuery(spec: QuerySpec, signal?: AbortSignal, workspaceRoot?: string) {
+	// Route on the dataset's declared source. Everything after this line —
+	// rounding, derived metrics, null propagation — is identical either way, so
+	// a metric means the same thing regardless of where its rows came from.
+	if (getDataset(spec.dataset).source === "csv") {
+		const result = await runCsvQuery(spec, process.env, workspaceRoot);
+		const derived = result.dataset.derived.filter((def) => spec.metrics.includes(def.name));
+		return {
+			built: {
+				sql: `-- csv:${result.dataset.csv?.file ?? result.dataset.id}`,
+				dataset: result.dataset,
+				measures: result.measures,
+				derived,
+				dimensions: result.dimensions,
+				notes: [...result.dataset.notes, ...result.notes],
+			} as ReturnType<typeof buildQuery>,
+			rows: shapeQueryRows(result.rows, result.measures, derived),
+		};
+	}
 	const built = buildQuery(spec);
 	const rows = await runQuery(built.sql, { signal });
 	return { built, rows: shapeQueryRows(rows, built.measures, built.derived) };