@viccydev/pi-fpa 0.2.0

package/README.md

@@ -0,0 +1,135 @@
+# pi-fpa
+
+面向 Pi 的完整 FP&A 周期资源包，目标运行时为 `@earendil-works/pi-coding-agent` 0.84.1。
+
+本包分发 Prompt Template、Skill、参考合同，以及一个只读数据 Extension（`fpa-data`）。包内不含业务数据与模型凭证，也不实现工作流状态机。多 Agent 隔离、人工审批、Artifact 持久化和真实外部执行仍由宿主运行时或独立工作流承担。
+
+## 包含的资源
+
+Prompt Template：
+
+- `/fpa-plan-cycle`：从周期规划开始，经过 Actuals 诊断、驱动分析、策略模拟、推荐和独立复核；只有拿到匹配版本的外部人工批准后，才生成并冻结正式预测。
+- `/fpa-review-cycle`：新周期 Actuals 到达后，对比冻结的正式预测并形成周期复盘。
+
+Skill：
+
+- `fpa-apply-core-rules`
+- `fpa-plan-cycle`
+- `fpa-diagnose-actuals`
+- `fpa-analyze-drivers`
+- `fpa-simulate-strategies`
+- `fpa-recommend-strategy`
+- `fpa-review-strategy`
+- `fpa-forecast-approved-strategy`
+- `fpa-review-cycle`
+- `fpa-execute-approved-strategy`
+
+执行 Skill 设置了 `disable-model-invocation: true`，不会出现在模型可主动调用的 Skill 摘要中，也没有对应 Prompt。只有用户显式输入 `/skill:fpa-execute-approved-strategy` 才能加载它；即使显式加载，缺少精确批准、单独执行授权、真实 adapter、幂等键或成功 preflight 时也必须保持 `blocked`，不得产生外部变更。
+
+## 数据 Extension（fpa-data）
+
+`extensions/fpa-data` 注册五个只读工具，连接 Supabase 数据集市：
+
+| 工具 | 作用 |
+| --- | --- |
+| `fpa_data_catalog` | 数据字典：数据集、维度、指标定义与聚合语义、各表实时日期覆盖、已知数据坑 |
+| `fpa_query` | 结构化聚合查询：指标 + 维度 + 时间粒度 + 过滤；SQL 由代码生成，比率按“先聚合分子分母、再相除”计算 |
+| `fpa_cohort` | 安装 cohort 的 LTV / ROAS / 留存曲线（D0/D3/D7/…），未成熟或缺分母一律返回 NULL 并给出原因 |
+| `fpa_calc` | 确定性计算器：命名公式求值（四则、abs/min/max/round），NULL 与除零安全传播 |
+| `fpa_compare` | 双期间对比：差值、百分比变化、逐行贡献度全部由代码计算 |
+
+设计契约：**模型不写 SQL、不做任何算术**。模型只从注册表中选择数据集、指标和维度；SQL 生成、数据库聚合和全部派生计算（比率、差异、LTV/ROAS/留存、临时公式）都在 Extension 代码内完成，缺数据或除零返回 `NULL`，绝不编造数值。
+
+Extension 内置的关键防护：
+
+- `appsflyer_ua_campaign_daily` 的三种 `breakdown_type` 是同一份花费的重叠切分；每次查询自动锁定一种，避免花费被重复计算。
+- 每个查询结果都带 `date_min` / `date_max` / `source_rows` 覆盖率元数据；各数据集日期覆盖不一致时以此为准。
+- Apple 指标按来源语义聚合：COUNT 求和、AVERAGE 取日均、LATEST 取期末值。
+- cohort 规模缺失（2026-08-01 之前）时 LTV/留存分母返回 NULL。
+
+### 凭证配置
+
+Extension 通过 Supabase Management API 只读查询，凭证仅从环境变量读取，绝不写入包内：
+
+```bash
+export SUPABASE_PROJECT_REF="<project ref>"
+export SUPABASE_ACCESS_TOKEN="<personal access token, sbp_...>"
+```
+
+在启动 Pi 前设置。未配置时工具报错并说明缺哪个变量，不发出任何查询。
+
+## 输入契约
+
+两个 Prompt 的基本参数都是：
+
+```text
+<project-root> <cycle-id> [instructions]
+```
+
+数据来源优先级：
+
+1. `fpa_data_catalog` 等 `fpa_*` 工具（Supabase 集市，推荐）。
+2. 运行时显式提供的字段目录与 Schema 路径。
+3. `<project-root>/LOCAL_FPA_MART_FIELD_CATALOG.md` 与 `<project-root>/LOCAL_FPA_MART_SCHEMA.sql`（本地文件回退）。
+
+资源不存在时必须报告缺口，不得回退到开发者机器路径或编造输入。
+
+## 本地安装
+
+从 npm 安装正式版本：
+
+```bash
+pi install npm:@viccydev/pi-fpa
+```
+
+从本地工作区安装开发版本：
+
+```bash
+pi install /absolute/path/to/pi-fpa
+pi list
+```
+
+本地路径只写入 Pi settings，不复制源目录。修改包后使用 `/reload` 或重启 Pi。
+
+团队分发建议使用固定 Git tag：
+
+```bash
+pi install git:github.com/linyqh/pi-fpa@v0.2.0
+```
+
+## 发布到 npm
+
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如当前 `0.2.0` 对应 `v0.2.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+
+首次发布前需要完成一次仓库配置：
+
+1. 确认 npm 账号或组织拥有 `@viccydev` scope。
+2. 在 GitHub 仓库的 Actions secrets 中创建 `NPM_TOKEN`。Token 需要允许发布该 scope，并允许 CI 绕过发布时的 2FA。
+3. 将仓库推送到 GitHub，然后创建与 `package.json` 版本匹配的 GitHub Release。
+
+首发成功后，建议到 npm 包设置中将 Trusted Publisher 配置为 GitHub Actions；GitHub 用户填写 `linyqh`，仓库填写 `pi-fpa`，工作流文件填写 `publish.yml`，Allowed actions 选择 `npm publish`。验证 OIDC 发布成功后即可删除长期 `NPM_TOKEN`。当前许可证仍是 `UNLICENSED`；若准备让第三方使用或修改本包，应在首发前明确许可证。
+
+## 使用
+
+```text
+/fpa-plan-cycle /path/to/project 2026-Q3 "按 App、Store、Channel Group 规划；预算上限见 planning input"
+/fpa-review-cycle /path/to/project 2026-Q3 "使用已冻结 forecast 和新到达的 Actuals snapshot"
+```
+
+规划入口不会进入真实策略执行。需要执行获批策略时，必须在单独、已授权的运行中显式调用：
+
+```text
+/skill:fpa-execute-approved-strategy <exact strategy version and execution scope>
+```
+
+## 资源迁移注意
+
+如果 `~/.pi/agent/skills/` 中仍有同名 `fpa-*` Skill，Pi 会报告命名冲突并采用先发现的资源。先在隔离配置中验证本包，确认来源路径后再通过 `pi config` 禁用旧副本或将旧目录移出发现路径。全局 `~/.pi/agent/extensions/` 下如有旧的数据 extension（如 `ios-fpa`），工具名不同不会冲突，但建议确认是否仍需保留。
+
+## 验证
+
+```bash
+npm test          # 包结构 + extension 单元测试 + Pi loader 冒烟
+npm run test:live # 可选：需要 SUPABASE_* 环境变量，对真实库做只读冒烟
+npm run pack:check
+```

package/extensions/fpa-data/calc.ts

@@ -0,0 +1,544 @@
+/**
+ * Deterministic calculation engine for the FP&A tools.
+ *
+ * All arithmetic exposed to the workflow happens here or in SQL — never in
+ * the LLM. Missing inputs and zero denominators propagate as null (per the
+ * core FP&A rules), never as fabricated zeros.
+ */
+
+import type { DerivedDef } from "./registry.ts";
+
+export type NumericLike = number | string | null | undefined;
+
+export const DEFAULT_PRECISION = 6;
+
+/** Coerce a SQL result cell (Postgres numerics arrive as strings) to number | null. */
+export function toNumber(value: NumericLike): number | null {
+	if (value === null || value === undefined || value === "") return null;
+	const n = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(n) ? n : null;
+}
+
+export function round(value: number | null, precision: number = DEFAULT_PRECISION): number | null {
+	if (value === null) return null;
+	const factor = 10 ** precision;
+	return Math.round(value * factor) / factor;
+}
+
+/** Null-safe division: null when either side is null or the denominator is 0. */
+export function safeDiv(numerator: number | null, denominator: number | null): number | null {
+	if (numerator === null || denominator === null || denominator === 0) return null;
+	return numerator / denominator;
+}
+
+/** Compute registry-derived ratio metrics for one aggregated row. */
+export function computeDerived(
+	row: Record<string, unknown>,
+	derived: DerivedDef[],
+	precision: number = DEFAULT_PRECISION,
+): Record<string, number | null> {
+	const out: Record<string, number | null> = {};
+	for (const def of derived) {
+		const numerator = toNumber(row[def.numerator] as NumericLike);
+		const denominator = toNumber(row[def.denominator] as NumericLike);
+		const scaled = numerator === null ? null : numerator * (def.scale ?? 1);
+		out[def.name] = round(safeDiv(scaled, denominator), precision);
+	}
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// Expression evaluator (used by fpa_calc). Supports + - * / ( ), unary minus,
+// numeric literals, named variables, and abs/min/max/round. No eval().
+// ---------------------------------------------------------------------------
+
+type Token =
+	| { kind: "number"; value: number }
+	| { kind: "ident"; value: string }
+	| { kind: "op"; value: "+" | "-" | "*" | "/" }
+	| { kind: "lparen" }
+	| { kind: "rparen" }
+	| { kind: "comma" };
+
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*/;
+const NUMBER_RE = /^(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/;
+
+function tokenize(formula: string): Token[] {
+	const tokens: Token[] = [];
+	let rest = formula;
+	while (rest.length > 0) {
+		const ws = rest.match(/^\s+/);
+		if (ws) {
+			rest = rest.slice(ws[0].length);
+			continue;
+		}
+		const num = rest.match(NUMBER_RE);
+		if (num) {
+			tokens.push({ kind: "number", value: Number(num[0]) });
+			rest = rest.slice(num[0].length);
+			continue;
+		}
+		const ident = rest.match(IDENT_RE);
+		if (ident) {
+			tokens.push({ kind: "ident", value: ident[0] });
+			rest = rest.slice(ident[0].length);
+			continue;
+		}
+		const ch = rest[0];
+		if (ch === "+" || ch === "-" || ch === "*" || ch === "/") {
+			tokens.push({ kind: "op", value: ch });
+		} else if (ch === "(") {
+			tokens.push({ kind: "lparen" });
+		} else if (ch === ")") {
+			tokens.push({ kind: "rparen" });
+		} else if (ch === ",") {
+			tokens.push({ kind: "comma" });
+		} else {
+			throw new Error(`Unexpected character "${ch}" in formula.`);
+		}
+		rest = rest.slice(1);
+	}
+	return tokens;
+}
+
+const FUNCTIONS: Record<string, { arity: [number, number]; apply: (args: Array<number | null>) => number | null }> = {
+	abs: {
+		arity: [1, 1],
+		apply: ([x]) => (x === null ? null : Math.abs(x)),
+	},
+	min: {
+		arity: [2, 8],
+		apply: (args) => (args.some((a) => a === null) ? null : Math.min(...(args as number[]))),
+	},
+	max: {
+		arity: [2, 8],
+		apply: (args) => (args.some((a) => a === null) ? null : Math.max(...(args as number[]))),
+	},
+	round: {
+		arity: [1, 2],
+		apply: ([x, p]) => {
+			if (x === null) return null;
+			const precision = p === null || p === undefined ? 0 : p;
+			if (!Number.isInteger(precision) || precision < 0 || precision > 12) {
+				throw new Error("round() precision must be an integer between 0 and 12.");
+			}
+			return round(x, precision);
+		},
+	},
+};
+
+class Parser {
+	private tokens: Token[];
+	private pos = 0;
+	private vars: Record<string, number | null>;
+
+	constructor(formula: string, vars: Record<string, number | null>) {
+		this.tokens = tokenize(formula);
+		this.vars = vars;
+	}
+
+	parse(): number | null {
+		const value = this.expression();
+		if (this.pos < this.tokens.length) {
+			throw new Error("Unexpected trailing input in formula.");
+		}
+		return value;
+	}
+
+	private peek(): Token | undefined {
+		return this.tokens[this.pos];
+	}
+
+	private next(): Token {
+		const token = this.tokens[this.pos];
+		if (!token) throw new Error("Formula ended unexpectedly.");
+		this.pos += 1;
+		return token;
+	}
+
+	private expression(): number | null {
+		let left = this.term();
+		for (;;) {
+			const token = this.peek();
+			if (token?.kind !== "op" || (token.value !== "+" && token.value !== "-")) return left;
+			this.next();
+			const right = this.term();
+			if (left === null || right === null) {
+				left = null;
+			} else {
+				left = token.value === "+" ? left + right : left - right;
+			}
+		}
+	}
+
+	private term(): number | null {
+		let left = this.factor();
+		for (;;) {
+			const token = this.peek();
+			if (token?.kind !== "op" || (token.value !== "*" && token.value !== "/")) return left;
+			this.next();
+			const right = this.factor();
+			if (left === null || right === null) {
+				left = null;
+			} else if (token.value === "*") {
+				left = left * right;
+			} else {
+				left = right === 0 ? null : left / right;
+			}
+		}
+	}
+
+	private factor(): number | null {
+		const token = this.peek();
+		if (token?.kind === "op" && token.value === "-") {
+			this.next();
+			const value = this.factor();
+			return value === null ? null : -value;
+		}
+		if (token?.kind === "op" && token.value === "+") {
+			this.next();
+			return this.factor();
+		}
+		return this.primary();
+	}
+
+	private primary(): number | null {
+		const token = this.next();
+		if (token.kind === "number") return token.value;
+		if (token.kind === "lparen") {
+			const value = this.expression();
+			const closing = this.next();
+			if (closing.kind !== "rparen") throw new Error("Expected ')' in formula.");
+			return value;
+		}
+		if (token.kind === "ident") {
+			if (this.peek()?.kind === "lparen") {
+				return this.functionCall(token.value);
+			}
+			if (!(token.value in this.vars)) {
+				const available = Object.keys(this.vars);
+				throw new Error(
+					`Unknown variable "${token.value}". Available: ${available.length > 0 ? available.join(", ") : "(none)"}.`,
+				);
+			}
+			return this.vars[token.value];
+		}
+		throw new Error("Unexpected token in formula.");
+	}
+
+	private functionCall(name: string): number | null {
+		const fn = FUNCTIONS[name];
+		if (!fn) {
+			throw new Error(`Unknown function "${name}". Available: ${Object.keys(FUNCTIONS).join(", ")}.`);
+		}
+		this.next(); // consume '('
+		const args: Array<number | null> = [];
+		if (this.peek()?.kind !== "rparen") {
+			args.push(this.expression());
+			while (this.peek()?.kind === "comma") {
+				this.next();
+				args.push(this.expression());
+			}
+		}
+		const closing = this.next();
+		if (closing.kind !== "rparen") throw new Error(`Expected ')' after ${name}(...).`);
+		const [minArity, maxArity] = fn.arity;
+		if (args.length < minArity || args.length > maxArity) {
+			throw new Error(`${name}() expects ${minArity}${maxArity > minArity ? `..${maxArity}` : ""} arguments.`);
+		}
+		return fn.apply(args);
+	}
+}
+
+/** Evaluate one formula against named values. Null inputs and /0 yield null. */
+export function evaluateFormula(
+	formula: string,
+	vars: Record<string, number | null>,
+): number | null {
+	if (typeof formula !== "string" || formula.trim().length === 0) {
+		throw new Error("Formula must be a non-empty string.");
+	}
+	if (formula.length > 2000) {
+		throw new Error("Formula exceeds the 2000-character limit.");
+	}
+	return new Parser(formula, vars).parse();
+}
+
+export interface CalcExpression {
+	name: string;
+	formula: string;
+}
+
+export interface CalcResult {
+	name: string;
+	formula: string;
+	value: number | null;
+	error?: string;
+}
+
+/** Evaluate expressions in order; later expressions can use earlier results. */
+export function runCalc(
+	values: Record<string, NumericLike>,
+	expressions: CalcExpression[],
+	precision: number = DEFAULT_PRECISION,
+): CalcResult[] {
+	const scope: Record<string, number | null> = {};
+	for (const [key, raw] of Object.entries(values)) {
+		if (!IDENT_RE.test(key) || key.match(IDENT_RE)?.[0] !== key) {
+			throw new Error(`Variable name "${key}" must be a valid identifier (letters, digits, underscore).`);
+		}
+		scope[key] = toNumber(raw);
+	}
+	const results: CalcResult[] = [];
+	for (const expr of expressions) {
+		if (!IDENT_RE.test(expr.name) || expr.name.match(IDENT_RE)?.[0] !== expr.name) {
+			throw new Error(`Expression name "${expr.name}" must be a valid identifier.`);
+		}
+		try {
+			const value = round(evaluateFormula(expr.formula, scope), precision);
+			scope[expr.name] = value;
+			results.push({ name: expr.name, formula: expr.formula, value });
+		} catch (error) {
+			results.push({
+				name: expr.name,
+				formula: expr.formula,
+				value: null,
+				error: error instanceof Error ? error.message : String(error),
+			});
+			scope[expr.name] = null;
+		}
+	}
+	return results;
+}
+
+// ---------------------------------------------------------------------------
+// Period comparison (used by fpa_compare).
+// ---------------------------------------------------------------------------
+
+export interface MetricComparison {
+	metric: string;
+	current: number | null;
+	baseline: number | null;
+	delta: number | null;
+	delta_pct: number | null;
+	/** Share of the total delta contributed by this row (base measures only). */
+	contribution_pct?: number | null;
+}
+
+export interface RowComparison {
+	key: Record<string, unknown>;
+	metrics: MetricComparison[];
+}
+
+function rowKey(row: Record<string, unknown>, dims: string[]): string {
+	return dims.map((d) => String(row[d] ?? "")).join("
");
+}
+
+function compareValues(current: number | null, baseline: number | null): {
+	delta: number | null;
+	delta_pct: number | null;
+} {
+	if (current === null || baseline === null) return { delta: null, delta_pct: null };
+	const delta = current - baseline;
+	return { delta, delta_pct: baseline === 0 ? null : delta / Math.abs(baseline) };
+}
+
+/**
+ * Compare two aggregated result sets row-by-row on shared dimension values.
+ * Rows present on only one side compare against null. Contribution shares are
+ * computed per base measure against the total delta across all rows.
+ */
+export function comparePeriods(
+	currentRows: Array<Record<string, unknown>>,
+	baselineRows: Array<Record<string, unknown>>,
+	dims: string[],
+	metrics: string[],
+	baseMeasures: Set<string>,
+	precision: number = DEFAULT_PRECISION,
+): RowComparison[] {
+	const baselineByKey = new Map(baselineRows.map((row) => [rowKey(row, dims), row]));
+	const seen = new Set<string>();
+	const paired: Array<{
+		key: Record<string, unknown>;
+		current: Record<string, unknown> | null;
+		baseline: Record<string, unknown> | null;
+	}> = [];
+
+	for (const row of currentRows) {
+		const key = rowKey(row, dims);
+		seen.add(key);
+		paired.push({ key: Object.fromEntries(dims.map((d) => [d, row[d]])), current: row, baseline: baselineByKey.get(key) ?? null });
+	}
+	for (const row of baselineRows) {
+		const key = rowKey(row, dims);
+		if (!seen.has(key)) {
+			paired.push({ key: Object.fromEntries(dims.map((d) => [d, row[d]])), current: null, baseline: row });
+		}
+	}
+
+	const totalDelta = new Map<string, number>();
+	for (const metric of metrics) {
+		if (!baseMeasures.has(metric)) continue;
+		let total = 0;
+		for (const pair of paired) {
+			const current = toNumber(pair.current?.[metric] as NumericLike);
+			const baseline = toNumber(pair.baseline?.[metric] as NumericLike);
+			if (current !== null || baseline !== null) {
+				total += (current ?? 0) - (baseline ?? 0);
+			}
+		}
+		totalDelta.set(metric, total);
+	}
+
+	return paired.map((pair) => ({
+		key: pair.key,
+		metrics: metrics.map((metric) => {
+			const current = toNumber(pair.current?.[metric] as NumericLike);
+			const baseline = toNumber(pair.baseline?.[metric] as NumericLike);
+			const { delta, delta_pct } = compareValues(current, baseline);
+			const comparison: MetricComparison = {
+				metric,
+				current: round(current, precision),
+				baseline: round(baseline, precision),
+				delta: round(delta, precision),
+				delta_pct: round(delta_pct, precision),
+			};
+			if (baseMeasures.has(metric)) {
+				const total = totalDelta.get(metric) ?? 0;
+				const rowDelta =
+					current === null && baseline === null ? null : (current ?? 0) - (baseline ?? 0);
+				comparison.contribution_pct =
+					rowDelta === null || total === 0 ? null : round(rowDelta / total, precision);
+			}
+			return comparison;
+		}),
+	}));
+}
+
+// ---------------------------------------------------------------------------
+// Cohort result assembly (used by fpa_cohort).
+// ---------------------------------------------------------------------------
+
+export interface CohortHorizonMetrics {
+	horizon: number;
+	mature: boolean;
+	net_proceeds: number | null;
+	ltv: number | null;
+	retention: number | null;
+	roas: number | null;
+	reasons: string[];
+}
+
+export interface CohortRow {
+	bucket: string;
+	key: Record<string, unknown>;
+	install_days: number | null;
+	install_min: string;
+	install_max: string;
+	cohort_size: number | null;
+	days_missing_cohort_size: number | null;
+	spend: number | null;
+	ua_installs: number | null;
+	horizons: CohortHorizonMetrics[];
+}
+
+export function buildCohortRows(
+	rows: Array<Record<string, unknown>>,
+	spendRows: Array<Record<string, unknown>>,
+	groupBy: string[],
+	horizons: number[],
+	maxEventDate: string | null,
+	minEventDate: string | null = null,
+	precision: number = DEFAULT_PRECISION,
+): CohortRow[] {
+	const keyOf = (row: Record<string, unknown>) =>
+		["bucket", ...groupBy].map((k) => String(row[k] ?? "")).join("
");
+	const spendByKey = new Map(spendRows.map((row) => [keyOf(row), row]));
+
+	return rows.map((row) => {
+		const spendRow = spendByKey.get(keyOf(row)) ?? null;
+		const cohortSize = toNumber(row.cohort_size as NumericLike);
+		const missingSizeDays = toNumber(row.days_missing_cohort_size as NumericLike) ?? 0;
+		const installDays = toNumber(row.install_days as NumericLike);
+		const spend = toNumber(spendRow?.spend as NumericLike);
+		const spendDays = toNumber(spendRow?.spend_days as NumericLike);
+		const installMax = String(row.install_max ?? "");
+
+		const installMin = String(row.install_min ?? "");
+
+		const horizonMetrics = horizons.map((n): CohortHorizonMetrics => {
+			const reasons: string[] = [];
+			const net = toNumber(row[`net_d${n}`] as NumericLike);
+			const active = toNumber(row[`active_d${n}`] as NumericLike);
+
+			if (minEventDate && installMin && minEventDate > installMin) {
+				reasons.push(
+					`event data only starts ${minEventDate}, after the first install date ${installMin}; ` +
+						"the source is a rolling activity window, so horizon revenue for these cohorts is incomplete and all horizon metrics are NULL",
+				);
+				return { horizon: n, mature: false, net_proceeds: null, ltv: null, retention: null, roas: null, reasons };
+			}
+
+			let mature = false;
+			if (maxEventDate && installMax) {
+				const cutoff = new Date(`${installMax}T00:00:00Z`);
+				cutoff.setUTCDate(cutoff.getUTCDate() + n);
+				mature = cutoff <= new Date(`${maxEventDate}T00:00:00Z`);
+			}
+			if (!mature) {
+				reasons.push(
+					`immature: install_max ${installMax} + ${n}d exceeds the latest event_date ${maxEventDate ?? "(unknown)"}; per core rules the horizon metrics are NULL`,
+				);
+				return { horizon: n, mature, net_proceeds: null, ltv: null, retention: null, roas: null, reasons };
+			}
+
+			let ltv: number | null = null;
+			let retention: number | null = null;
+			if (missingSizeDays > 0 || cohortSize === null || cohortSize === 0) {
+				reasons.push(
+					missingSizeDays > 0
+						? `cohort size missing for ${missingSizeDays} install day(s); LTV/retention denominators are NULL`
+						: "cohort size is NULL or zero; LTV/retention are NULL",
+				);
+			} else {
+				ltv = safeDiv(net, cohortSize);
+				retention = safeDiv(active, cohortSize);
+			}
+
+			let roas: number | null = null;
+			if (spend === null || spend === 0) {
+				reasons.push("no UA spend rows for this bucket; ROAS is NULL");
+			} else {
+				if (spendDays !== null && installDays !== null && spendDays < installDays) {
+					reasons.push(
+						`spend covers only ${spendDays}/${installDays} install day(s); ROAS may be overstated`,
+					);
+				}
+				roas = safeDiv(net, spend);
+			}
+
+			return {
+				horizon: n,
+				mature,
+				net_proceeds: round(net, precision),
+				ltv: round(ltv, precision),
+				retention: round(retention, precision),
+				roas: round(roas, precision),
+				reasons,
+			};
+		});
+
+		return {
+			bucket: String(row.bucket ?? ""),
+			key: Object.fromEntries(groupBy.map((k) => [k, row[k]])),
+			install_days: installDays,
+			install_min: installMin,
+			install_max: installMax,
+			cohort_size: cohortSize,
+			days_missing_cohort_size: missingSizeDays,
+			spend: round(spend, precision),
+			ua_installs: toNumber(spendRow?.ua_installs as NumericLike),
+			horizons: horizonMetrics,
+		};
+	});
+}