@viccydev/pi-fpa 0.2.1 → 0.3.1

package/extensions/fpa-dashboard/schema.ts

@@ -0,0 +1,115 @@
+export const DASHBOARD_WIDGET_TYPES = ["stat", "timeseries", "table", "grouped-table"] as const;
+export type DashboardWidgetType = (typeof DASHBOARD_WIDGET_TYPES)[number];
+
+const TONES = new Set(["positive", "negative", "warning", "neutral"]);
+
+function record(value: unknown, path: string): Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object.`);
+	return value as Record<string, unknown>;
+}
+
+function string(value: unknown, path: string): string {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
+	return value;
+}
+
+function optionalString(value: unknown, path: string): void {
+	if (value !== undefined) string(value, path);
+}
+
+function tone(value: unknown, path: string): void {
+	if (value !== undefined && (typeof value !== "string" || !TONES.has(value))) throw new Error(`${path} has an unsupported tone.`);
+}
+
+function cell(value: unknown, path: string): void {
+	if (value === null || typeof value === "string") return;
+	const source = record(value, path);
+	if (source.value !== null && typeof source.value !== "string") throw new Error(`${path}.value must be a string or null.`);
+	tone(source.tone, `${path}.tone`);
+}
+
+function columns(value: unknown, path: string): void {
+	if (!Array.isArray(value) || value.length === 0) throw new Error(`${path} must be a non-empty array.`);
+	for (const [index, raw] of value.entries()) {
+		const source = record(raw, `${path}[${index}]`);
+		string(source.key, `${path}[${index}].key`);
+		string(source.label, `${path}[${index}].label`);
+		if (source.align !== undefined && source.align !== "left" && source.align !== "right") throw new Error(`${path}[${index}].align is unsupported.`);
+	}
+}
+
+function cellsRecord(value: unknown, path: string): void {
+	const source = record(value, path);
+	for (const [key, value] of Object.entries(source)) cell(value, `${path}.${key}`);
+}
+
+function tabularRows(value: unknown, path: string): void {
+	if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+	for (const [index, row] of value.entries()) cellsRecord(row, `${path}[${index}]`);
+}
+
+function validateStat(source: Record<string, unknown>): void {
+	string(source.label, "dataset.label");
+	if (source.value !== null && typeof source.value !== "string") throw new Error("dataset.value must be a string or null.");
+	optionalString(source.missingReason, "dataset.missingReason");
+	optionalString(source.description, "dataset.description");
+	optionalString(source.footnote, "dataset.footnote");
+	if (source.delta !== undefined) {
+		const delta = record(source.delta, "dataset.delta");
+		if (delta.direction !== "up" && delta.direction !== "down" && delta.direction !== "flat") throw new Error("dataset.delta.direction is unsupported.");
+		string(delta.label, "dataset.delta.label");
+		if (delta.sentiment !== undefined && delta.sentiment !== "positive" && delta.sentiment !== "negative" && delta.sentiment !== "neutral") throw new Error("dataset.delta.sentiment is unsupported.");
+	}
+	if (source.progress !== undefined) {
+		const progress = record(source.progress, "dataset.progress");
+		if (typeof progress.fraction !== "number" || !Number.isFinite(progress.fraction) || progress.fraction < 0 || progress.fraction > 1) throw new Error("dataset.progress.fraction must be between 0 and 1.");
+		string(progress.label, "dataset.progress.label");
+		tone(progress.tone, "dataset.progress.tone");
+	}
+}
+
+function validateTimeseries(source: Record<string, unknown>): void {
+	string(source.label, "dataset.label");
+	optionalString(source.description, "dataset.description");
+	optionalString(source.coverage, "dataset.coverage");
+	if (!Array.isArray(source.series) || source.series.length === 0) throw new Error("dataset.series must be a non-empty array.");
+	for (const [seriesIndex, rawSeries] of source.series.entries()) {
+		const series = record(rawSeries, `dataset.series[${seriesIndex}]`);
+		string(series.name, `dataset.series[${seriesIndex}].name`);
+		if (!Array.isArray(series.points)) throw new Error(`dataset.series[${seriesIndex}].points must be an array.`);
+		for (const [pointIndex, rawPoint] of series.points.entries()) {
+			const point = record(rawPoint, `dataset.series[${seriesIndex}].points[${pointIndex}]`);
+			string(point.x, `dataset.series[${seriesIndex}].points[${pointIndex}].x`);
+			if (point.y !== null && (typeof point.y !== "number" || !Number.isFinite(point.y))) throw new Error(`dataset.series[${seriesIndex}].points[${pointIndex}].y must be finite or null.`);
+		}
+	}
+}
+
+function validateTable(source: Record<string, unknown>): void {
+	string(source.label, "dataset.label");
+	optionalString(source.description, "dataset.description");
+	columns(source.columns, "dataset.columns");
+	tabularRows(source.rows, "dataset.rows");
+}
+
+function validateGroupedTable(source: Record<string, unknown>): void {
+	string(source.label, "dataset.label");
+	optionalString(source.description, "dataset.description");
+	columns(source.columns, "dataset.columns");
+	if (!Array.isArray(source.groups) || source.groups.length === 0) throw new Error("dataset.groups must be a non-empty array.");
+	for (const [index, raw] of source.groups.entries()) {
+		const group = record(raw, `dataset.groups[${index}]`);
+		string(group.key, `dataset.groups[${index}].key`);
+		string(group.label, `dataset.groups[${index}].label`);
+		cellsRecord(group.summary, `dataset.groups[${index}].summary`);
+		tabularRows(group.rows, `dataset.groups[${index}].rows`);
+	}
+}
+
+export function validateDatasetForWidget(type: DashboardWidgetType, value: unknown): void {
+	const source = record(value, "dataset");
+	if (type === "stat") validateStat(source);
+	else if (type === "timeseries") validateTimeseries(source);
+	else if (type === "table") validateTable(source);
+	else validateGroupedTable(source);
+}

package/extensions/fpa-dashboard/source.ts

@@ -0,0 +1,169 @@
+import { sliceKey, type Period } from "../fpa-artifacts/contracts.ts";
+
+export interface QueryReceipt {
+	dataset: string;
+	query_fingerprint: string;
+	row_count: number;
+}
+
+export interface DashboardActualSlice {
+	app_id: string;
+	store: string;
+	channel_group: string;
+	spend: number | null;
+	revenue: number | null;
+	source_rows: number;
+}
+
+/** Sentinel used when no Actuals row exists yet, so no calendar date can be reported. */
+export const ACTUALS_DATA_AS_OF_UNAVAILABLE = "unavailable";
+
+/**
+ * How Actuals were scoped against the frozen forecast.
+ *
+ * "app"       - every slice matched ua_spend on app_code × platform × media_source.
+ * "portfolio" - the forecast collapsed the App axis onto a placeholder that does not
+ *               exist in ua_spend, so Actuals were aggregated across every app at the
+ *               platform × media_source grain.
+ */
+export type DashboardScopeMode = "app" | "portfolio";
+
+export interface DashboardDailyPoint {
+	date: string;
+	spend: number | null;
+	revenue: number | null;
+}
+
+export interface DashboardActualsSnapshot {
+	period: Period;
+	data_as_of: string;
+	reporting_currency: string;
+	scope_mode: DashboardScopeMode;
+	coverage: {
+		date_min: string | null;
+		date_max: string | null;
+		source_rows: number;
+	};
+	current: { spend: number | null; revenue: number | null };
+	comparison: { spend: number | null; revenue: number | null } | null;
+	daily: DashboardDailyPoint[];
+	slices: DashboardActualSlice[];
+	query_receipts: QueryReceipt[];
+}
+
+function record(value: unknown, path: string): Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object.`);
+	return value as Record<string, unknown>;
+}
+
+function string(value: unknown, path: string): string {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
+	return value;
+}
+
+function numeric(value: unknown, path: string, nullable = false): number | null {
+	if (nullable && value === null) return null;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${path} must be a finite number${nullable ? " or null" : ""}.`);
+	return value;
+}
+
+function count(value: unknown, path: string): number {
+	const parsed = numeric(value, path) as number;
+	if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${path} must be a non-negative integer.`);
+	return parsed;
+}
+
+function aggregate(value: unknown, path: string): { spend: number | null; revenue: number | null } {
+	const source = record(value, path);
+	return {
+		spend: numeric(source.spend, `${path}.spend`, true),
+		revenue: numeric(source.revenue, `${path}.revenue`, true),
+	};
+}
+
+function period(value: unknown, path: string): Period {
+	const source = record(value, path);
+	const result = {
+		start_inclusive: string(source.start_inclusive, `${path}.start_inclusive`),
+		end_exclusive: string(source.end_exclusive, `${path}.end_exclusive`),
+		timezone: string(source.timezone, `${path}.timezone`),
+	};
+	if (Number.isNaN(Date.parse(result.start_inclusive)) || Number.isNaN(Date.parse(result.end_exclusive))) throw new Error(`${path} timestamps must be valid ISO timestamps.`);
+	if (Date.parse(result.start_inclusive) >= Date.parse(result.end_exclusive)) throw new Error(`${path}.end_exclusive must be after start_inclusive.`);
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: result.timezone }).format(new Date(result.start_inclusive));
+	} catch {
+		throw new Error(`${path}.timezone is not supported.`);
+	}
+	return result;
+}
+
+export function validateActualsSnapshot(value: unknown): DashboardActualsSnapshot {
+	const source = record(value, "actuals");
+	const coverage = record(source.coverage, "actuals.coverage");
+	const dailySource = source.daily;
+	const slicesSource = source.slices;
+	const receiptsSource = source.query_receipts;
+	if (!Array.isArray(dailySource)) throw new Error("actuals.daily must be an array.");
+	if (!Array.isArray(slicesSource)) throw new Error("actuals.slices must be an array.");
+	if (!Array.isArray(receiptsSource)) throw new Error("actuals.query_receipts must be an array.");
+
+	const daily = dailySource.map((value, index) => {
+		const item = record(value, `actuals.daily[${index}]`);
+		return {
+			date: string(item.date, `actuals.daily[${index}].date`),
+			spend: numeric(item.spend, `actuals.daily[${index}].spend`, true),
+			revenue: numeric(item.revenue, `actuals.daily[${index}].revenue`, true),
+		};
+	});
+	const slices = slicesSource.map((value, index) => {
+		const item = record(value, `actuals.slices[${index}]`);
+		return {
+			app_id: string(item.app_id, `actuals.slices[${index}].app_id`),
+			store: string(item.store, `actuals.slices[${index}].store`),
+			channel_group: string(item.channel_group, `actuals.slices[${index}].channel_group`),
+			spend: numeric(item.spend, `actuals.slices[${index}].spend`, true),
+			revenue: numeric(item.revenue, `actuals.slices[${index}].revenue`, true),
+			source_rows: count(item.source_rows, `actuals.slices[${index}].source_rows`),
+		};
+	});
+	const dailyDates = new Set<string>();
+	for (const point of daily) {
+		if (dailyDates.has(point.date)) throw new Error(`actuals.daily contains duplicate date ${point.date}.`);
+		dailyDates.add(point.date);
+	}
+	const sliceKeys = new Set<string>();
+	for (const item of slices) {
+		const key = sliceKey(item);
+		if (sliceKeys.has(key)) throw new Error(`actuals.slices contains duplicate slice ${key.replaceAll("\u0000", " / ")}.`);
+		sliceKeys.add(key);
+	}
+
+	const reportingCurrency = string(source.reporting_currency, "actuals.reporting_currency").toUpperCase();
+	if (!/^[A-Z]{3}$/.test(reportingCurrency)) throw new Error("actuals.reporting_currency must be an ISO-4217 currency code.");
+	const scopeMode = source.scope_mode === undefined ? "app" : string(source.scope_mode, "actuals.scope_mode");
+	if (scopeMode !== "app" && scopeMode !== "portfolio") throw new Error('actuals.scope_mode must be "app" or "portfolio".');
+	return {
+		period: period(source.period, "actuals.period"),
+		data_as_of: string(source.data_as_of, "actuals.data_as_of"),
+		reporting_currency: reportingCurrency,
+		scope_mode: scopeMode,
+		coverage: {
+			date_min: coverage.date_min === null ? null : string(coverage.date_min, "actuals.coverage.date_min"),
+			date_max: coverage.date_max === null ? null : string(coverage.date_max, "actuals.coverage.date_max"),
+			source_rows: count(coverage.source_rows, "actuals.coverage.source_rows"),
+		},
+		current: aggregate(source.current, "actuals.current"),
+		comparison: source.comparison === null ? null : aggregate(source.comparison, "actuals.comparison"),
+		daily,
+		slices,
+		query_receipts: receiptsSource.map((value, index) => {
+			const item = record(value, `actuals.query_receipts[${index}]`);
+			return {
+				dataset: string(item.dataset, `actuals.query_receipts[${index}].dataset`),
+				query_fingerprint: string(item.query_fingerprint, `actuals.query_receipts[${index}].query_fingerprint`),
+				row_count: count(item.row_count, `actuals.query_receipts[${index}].row_count`),
+			};
+		}),
+	};
+}

package/extensions/fpa-dashboard/status.ts

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+import { resolveDashboardDir } from "./publisher.ts";
+import { stableJson } from "../fpa-artifacts/store.ts";
+import { DASHBOARD_WIDGET_TYPES, validateDatasetForWidget, type DashboardWidgetType } from "./schema.ts";
+
+const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}\.json$/;
+const GENERATION_RECEIPT_RE = /^build-receipt\.([a-f0-9]{12})\.([a-f0-9]{12})\.json$/;
+
+export interface DashboardStatus {
+	dashboard_exists: boolean;
+	dashboard_dir: string;
+	generation_id?: string;
+	updated_at?: string;
+	widget_count: number;
+	diagnostics: Array<{ target: string; message: string }>;
+}
+
+async function readJson(path: string, maxBytes: number): Promise<unknown> {
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("must be a regular file, not a symlink");
+	if (stat.size > maxBytes) throw new Error(`exceeds the ${Math.round(maxBytes / 1024)}KB limit`);
+	return JSON.parse(await readFile(path, "utf8"));
+}
+
+export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
+	const dashboardDir = await resolveDashboardDir(cwd);
+	const diagnostics: DashboardStatus["diagnostics"] = [];
+	let manifest: unknown;
+	try {
+		manifest = await readJson(join(dashboardDir, "manifest.json"), 256 * 1024);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return { dashboard_exists: false, dashboard_dir: dashboardDir, widget_count: 0, diagnostics };
+		}
+		return {
+			dashboard_exists: false,
+			dashboard_dir: dashboardDir,
+			widget_count: 0,
+			diagnostics: [{ target: "manifest.json", message: error instanceof Error ? error.message : String(error) }],
+		};
+	}
+	if (manifest === null || typeof manifest !== "object" || Array.isArray(manifest)) {
+		return { dashboard_exists: false, dashboard_dir: dashboardDir, widget_count: 0, diagnostics: [{ target: "manifest.json", message: "must contain an object" }] };
+	}
+	const source = manifest as Record<string, unknown>;
+	if (source.kind !== "fpa.dashboard" || source.schemaVersion !== 1 || typeof source.title !== "string" || source.title.trim() === "" || typeof source.updatedAt !== "string" || Number.isNaN(Date.parse(source.updatedAt)) || !Array.isArray(source.widgets) || source.widgets.length === 0 || source.widgets.length > 64) {
+		return { dashboard_exists: false, dashboard_dir: dashboardDir, widget_count: 0, diagnostics: [{ target: "manifest.json", message: "unsupported dashboard kind/schema or widgets shape" }] };
+	}
+	const receiptDatasets = new Map<string, string>();
+	const receiptFilename = typeof source.buildReceipt === "string" && DATASET_FILE_RE.test(source.buildReceipt)
+		? source.buildReceipt
+		: "build-receipt.json";
+	try {
+		const receipt = await readJson(join(dashboardDir, receiptFilename), 256 * 1024);
+		if (receipt === null || typeof receipt !== "object" || Array.isArray(receipt)) {
+			throw new Error("must contain an object");
+		}
+		const receiptSource = receipt as Record<string, unknown>;
+		if (receiptSource.kind !== "fpa.dashboard.build" || receiptSource.schema_version !== 1) {
+			throw new Error("has an unsupported build receipt kind or schema");
+		}
+		if (typeof source.generationId === "string" && receiptSource.generation_id !== source.generationId) {
+			diagnostics.push({ target: receiptFilename, message: "generation does not match manifest.json" });
+		}
+		if (receiptSource.published_at !== source.updatedAt) {
+			diagnostics.push({ target: receiptFilename, message: "published_at does not match manifest updatedAt" });
+		}
+		const receiptNameMatch = receiptFilename.match(GENERATION_RECEIPT_RE);
+		if (receiptNameMatch) {
+			if (typeof source.generationId !== "string" || receiptNameMatch[1] !== source.generationId.slice(0, 12)) {
+				diagnostics.push({ target: receiptFilename, message: "filename generation prefix does not match manifest.json" });
+			}
+			const receiptDigest = createHash("sha256").update(stableJson(receipt)).digest("hex");
+			if (receiptNameMatch[2] !== receiptDigest.slice(0, 12)) {
+				diagnostics.push({ target: receiptFilename, message: "receipt content digest does not match its filename" });
+			}
+		}
+		if (!Array.isArray(receiptSource.datasets)) throw new Error("datasets must be an array");
+		for (const [index, raw] of receiptSource.datasets.entries()) {
+			if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+				diagnostics.push({ target: `${receiptFilename} datasets[${index}]`, message: "must be an object" });
+				continue;
+			}
+			const item = raw as Record<string, unknown>;
+			if (typeof item.filename !== "string" || !DATASET_FILE_RE.test(item.filename) || typeof item.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(item.sha256)) {
+				diagnostics.push({ target: `${receiptFilename} datasets[${index}]`, message: "has an invalid filename or sha256" });
+				continue;
+			}
+			receiptDatasets.set(item.filename, item.sha256);
+		}
+	} catch (error) {
+		diagnostics.push({ target: receiptFilename, message: error instanceof Error ? error.message : String(error) });
+	}
+	const widgetIds = new Set<string>();
+	for (const [index, raw] of source.widgets.entries()) {
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+			diagnostics.push({ target: `widgets[${index}]`, message: "must be an object" });
+			continue;
+		}
+		const widget = raw as Record<string, unknown>;
+		const target = typeof widget.id === "string" ? widget.id : `widgets[${index}]`;
+		if (typeof widget.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(widget.id) || widgetIds.has(widget.id)) {
+			diagnostics.push({ target, message: "has an invalid or duplicate widget id" });
+			continue;
+		}
+		widgetIds.add(widget.id);
+		if (typeof widget.type !== "string" || !DASHBOARD_WIDGET_TYPES.includes(widget.type as DashboardWidgetType)) {
+			diagnostics.push({ target, message: "has an unsupported widget type" });
+			continue;
+		}
+		if (widget.span !== "quarter" && widget.span !== "half" && widget.span !== "full") {
+			diagnostics.push({ target, message: "has an unsupported widget span" });
+			continue;
+		}
+		if (typeof widget.dataset !== "string" || !DATASET_FILE_RE.test(widget.dataset)) {
+			diagnostics.push({ target, message: "has an invalid dataset name" });
+			continue;
+		}
+		const datasetPath = resolve(dashboardDir, "datasets", widget.dataset);
+		if (dirname(datasetPath) !== resolve(dashboardDir, "datasets")) {
+			diagnostics.push({ target, message: "dataset escapes the dashboard directory" });
+			continue;
+		}
+		try {
+			const dataset = await readJson(datasetPath, 2 * 1024 * 1024);
+			try {
+				validateDatasetForWidget(widget.type as DashboardWidgetType, dataset);
+			} catch (error) {
+				diagnostics.push({ target, message: `dataset schema is invalid: ${error instanceof Error ? error.message : String(error)}` });
+			}
+			const actualSha256 = createHash("sha256").update(stableJson(dataset)).digest("hex");
+			const expectedSha256 = receiptDatasets.get(widget.dataset);
+			if (!expectedSha256) {
+				diagnostics.push({ target, message: `dataset has no sha256 entry in ${receiptFilename}` });
+			} else if (expectedSha256 !== actualSha256) {
+				diagnostics.push({ target, message: `dataset integrity sha256 does not match ${receiptFilename}` });
+			}
+		} catch (error) {
+			diagnostics.push({ target, message: error instanceof Error ? error.message : String(error) });
+		}
+	}
+
+	return {
+		dashboard_exists: true,
+		dashboard_dir: dashboardDir,
+		...(typeof source.generationId === "string" ? { generation_id: source.generationId } : {}),
+		...(typeof source.updatedAt === "string" ? { updated_at: source.updatedAt } : {}),
+		widget_count: source.widgets.length,
+		diagnostics,
+	};
+}

package/extensions/fpa-data/index.ts

@@ -16,23 +16,19 @@ import { Type } from "typebox";
 import {
 	buildCohortRows,
 	comparePeriods,
-	computeDerived,
-	round,
 	runCalc,
-	toNumber,
 	type CalcExpression,
-	type NumericLike,
 } from "./calc.ts";
 import { CATALOG_CAVEATS, DATASETS, DATASET_IDS } from "./registry.ts";
 import {
 	buildCohortQuery,
 	buildCoverageSql,
 	buildCohortSizeCoverageSql,
-	buildQuery,
 	MAX_LIMIT,
 	type QuerySpec,
 } from "./sql.ts";
-import { runQuery, type SqlRow } from "./supabase.ts";
+import { runStructuredQuery } from "./runtime.ts";
+import { runQuery } from "./supabase.ts";
 
 const MAX_TOOL_TEXT_CHARS = 100_000;
 const MAX_DISPLAY_ROWS = 200;
@@ -116,27 +112,6 @@ function toolResult(result: Record<string, unknown>, rowsKey = "rows") {
 	};
 }
 
-function shapeQueryRows(
-	rows: SqlRow[],
-	measures: string[],
-	derived: ReturnType<typeof buildQuery>["derived"],
-): SqlRow[] {
-	return rows.map((row) => {
-		const shaped: SqlRow = { ...row };
-		for (const name of measures) {
-			shaped[name] = round(toNumber(row[name] as NumericLike));
-		}
-		shaped.source_rows = toNumber(row.source_rows as NumericLike);
-		return { ...shaped, ...computeDerived(row, derived) };
-	});
-}
-
-async function runStructuredQuery(spec: QuerySpec, signal?: AbortSignal) {
-	const built = buildQuery(spec);
-	const rows = await runQuery(built.sql, { signal });
-	return { built, rows: shapeQueryRows(rows, built.measures, built.derived) };
-}
-
 export default function fpaDataExtension(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "fpa_data_catalog",

package/extensions/fpa-data/runtime.ts

@@ -0,0 +1,22 @@
+import { computeDerived, round, toNumber, type NumericLike } from "./calc.ts";
+import { buildQuery, type QuerySpec } from "./sql.ts";
+import { runQuery, type SqlRow } from "./supabase.ts";
+
+export function shapeQueryRows(
+	rows: SqlRow[],
+	measures: string[],
+	derived: ReturnType<typeof buildQuery>["derived"],
+): SqlRow[] {
+	return rows.map((row) => {
+		const shaped: SqlRow = { ...row };
+		for (const name of measures) shaped[name] = round(toNumber(row[name] as NumericLike));
+		shaped.source_rows = toNumber(row.source_rows as NumericLike);
+		return { ...shaped, ...computeDerived(row, derived) };
+	});
+}
+
+export async function runStructuredQuery(spec: QuerySpec, signal?: AbortSignal) {
+	const built = buildQuery(spec);
+	const rows = await runQuery(built.sql, { signal });
+	return { built, rows: shapeQueryRows(rows, built.measures, built.derived) };
+}

package/extensions/fpa-data/sql.ts

@@ -23,6 +23,16 @@ export interface QuerySpec {
 	dateFrom?: string;
 	dateTo?: string;
 	filters?: Record<string, string | number | Array<string | number>>;
+	/** Internal exact UA scope used by deterministic dashboard projections. */
+	exactUaScope?: Array<{ app_code: string; platform: string; media_source: string }>;
+	/** Internal exact App + Store portfolio scope used to discover unplanned paid channels. */
+	exactUaPortfolioScope?: Array<{ app_code: string; platform: string }>;
+	/**
+	 * Internal exact Store + Channel scope for forecasts whose App axis is a portfolio
+	 * placeholder. The placeholder never matches ua_spend.app_code, so the App predicate
+	 * is dropped and Actuals are aggregated across every app.
+	 */
+	exactUaChannelScope?: Array<{ platform: string; media_source: string }>;
 	sort?: { by: string; direction?: "asc" | "desc" };
 	limit?: number;
 }
@@ -201,6 +211,48 @@ export function buildQuery(spec: QuerySpec): BuiltQuery {
 		const values = normalizeFilterValues(raw).map(escapeLiteral);
 		where.push(values.length === 1 ? `${def.sql} = ${values[0]}` : `${def.sql} in (${values.join(", ")})`);
 	}
+	if (spec.exactUaScope !== undefined) {
+		if (dataset.id !== "ua_spend") throw new Error("exactUaScope is supported only for ua_spend.");
+		if (spec.exactUaScope.length === 0 || spec.exactUaScope.length > 500) throw new Error("exactUaScope must contain between 1 and 500 slices.");
+		const dimensionSql = Object.fromEntries(dataset.dimensions.map((dimension) => [dimension.name, dimension.sql]));
+		const predicates = spec.exactUaScope.map((scope, index) => {
+			for (const [name, value] of Object.entries(scope)) {
+				if (typeof value !== "string" || value.trim() === "") throw new Error(`exactUaScope[${index}].${name} must be a non-empty string.`);
+			}
+			return `(${dimensionSql.app_code} = ${escapeLiteral(scope.app_code)} and ${dimensionSql.platform} = ${escapeLiteral(scope.platform)} and ${dimensionSql.media_source} = ${escapeLiteral(scope.media_source)})`;
+		});
+		where.push(`(${predicates.join(" or ")})`);
+		filterKeys.push("app_code", "platform", "media_source");
+		notes.push("Applied exact App + Store + Channel dashboard scope.");
+	}
+	if (spec.exactUaPortfolioScope !== undefined) {
+		if (dataset.id !== "ua_spend") throw new Error("exactUaPortfolioScope is supported only for ua_spend.");
+		if (spec.exactUaPortfolioScope.length === 0 || spec.exactUaPortfolioScope.length > 500) throw new Error("exactUaPortfolioScope must contain between 1 and 500 App + Store pairs.");
+		const dimensionSql = Object.fromEntries(dataset.dimensions.map((dimension) => [dimension.name, dimension.sql]));
+		const predicates = spec.exactUaPortfolioScope.map((scope, index) => {
+			for (const [name, value] of Object.entries(scope)) {
+				if (typeof value !== "string" || value.trim() === "") throw new Error(`exactUaPortfolioScope[${index}].${name} must be a non-empty string.`);
+			}
+			return `(${dimensionSql.app_code} = ${escapeLiteral(scope.app_code)} and ${dimensionSql.platform} = ${escapeLiteral(scope.platform)})`;
+		});
+		where.push(`(${predicates.join(" or ")})`);
+		filterKeys.push("app_code", "platform");
+		notes.push("Applied exact App + Store portfolio scope.");
+	}
+	if (spec.exactUaChannelScope !== undefined) {
+		if (dataset.id !== "ua_spend") throw new Error("exactUaChannelScope is supported only for ua_spend.");
+		if (spec.exactUaChannelScope.length === 0 || spec.exactUaChannelScope.length > 500) throw new Error("exactUaChannelScope must contain between 1 and 500 Store + Channel pairs.");
+		const dimensionSql = Object.fromEntries(dataset.dimensions.map((dimension) => [dimension.name, dimension.sql]));
+		const predicates = spec.exactUaChannelScope.map((scope, index) => {
+			for (const [name, value] of Object.entries(scope)) {
+				if (typeof value !== "string" || value.trim() === "") throw new Error(`exactUaChannelScope[${index}].${name} must be a non-empty string.`);
+			}
+			return `(${dimensionSql.platform} = ${escapeLiteral(scope.platform)} and ${dimensionSql.media_source} = ${escapeLiteral(scope.media_source)})`;
+		});
+		where.push(`(${predicates.join(" or ")})`);
+		filterKeys.push("platform", "media_source");
+		notes.push("Applied exact Store + Channel scope across every app (portfolio-placeholder forecast).");
+	}
 
 	const breakdown = resolveBreakdown(dataset, dimensionNames, filterKeys);
 	if (breakdown.predicate) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -23,9 +23,9 @@
     "extensions"
   ],
   "scripts": {
-    "test": "node tests/package-structure.test.mjs && node tests/extension-unit.test.mjs && node tests/pi-loader-smoke.mjs && node tests/publish-workflow.test.mjs",
+    "test": "node tests/package-structure.test.mjs && node tests/extension-unit.test.mjs && node --test tests/artifact-store.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs && node tests/pi-loader-smoke.mjs && node tests/publish-workflow.test.mjs",
     "test:structure": "node tests/package-structure.test.mjs",
-    "test:unit": "node tests/extension-unit.test.mjs",
+    "test:unit": "node tests/extension-unit.test.mjs && node --test tests/artifact-store.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs",
     "test:loader": "node tests/pi-loader-smoke.mjs",
     "test:live": "node tests/live-smoke.mjs",
     "pack:check": "npm pack --dry-run"
@@ -48,7 +48,9 @@
       "./skills"
     ],
     "extensions": [
-      "./extensions/fpa-data/index.ts"
+      "./extensions/fpa-data/index.ts",
+      "./extensions/fpa-artifacts/index.ts",
+      "./extensions/fpa-dashboard/index.ts"
     ]
   }
 }

package/skills/fpa-execute-approved-strategy/SKILL.md

@@ -29,7 +29,7 @@ If any requirement is missing, return `blocked` and make no external call. Never
 4. Present or record the dry-run result when the adapter supports it.
 5. Execute only the approved mutation set.
 6. Read back the resulting state and reconcile it with the requested state.
-7. Write `execution_receipt` using [artifact-contract.md](references/artifact-contract.md).
+7. Build the canonical `execution_receipt` using [artifact-contract.md](references/artifact-contract.md), then call `fpa_artifact_commit`.
 
 ## Stop conditions
 
@@ -37,4 +37,4 @@ Stop before or during execution on version mismatch, target ambiguity, budget mi
 
 ## Boundary
 
-Execution ends after reconciliation and receipt. Do not continuously monitor performance. Performance review begins only when the next cycle's Actuals arrive and uses `$fpa-review-cycle`.
+Execution ends after reconciliation and a successful canonical receipt commit. A Markdown report is not an execution receipt. Do not continuously monitor performance. Performance review begins only when the next cycle's Actuals arrive and uses `$fpa-review-cycle`.

package/skills/fpa-execute-approved-strategy/references/artifact-contract.md

@@ -3,12 +3,17 @@
 ```yaml
 artifact_type: execution_receipt
 status: complete | complete_with_limits | blocked
+forecast_version: string
 strategy_version: string
 human_approval_id: string
 execution_request_id: string
+execution_mode: manual | adapter
+verification_status: reported | verified | failed
 adapter: string
 target_accounts: []
 idempotency_key: string
+target_period: {start_inclusive: timestamp, end_exclusive: timestamp, timezone: string}
+reporting_currency: string
 preflight:
   result: pass | fail
   observed_state_fingerprint: string
@@ -23,7 +28,15 @@ reconciliation:
   resulting_state_fingerprint: string | null
 external_receipt_ids: []
 executed_at: timestamp | null
+slices:
+  - app_id: string
+    store: string
+    channel_group: string
+    action: string
+    planned_spend: number
+    applied_spend: number | null
+    evidence_ids: []
 blockers: []
 ```
 
-Only adapter responses may populate `applied_mutations`, external receipt IDs, and resulting-state evidence. A blocked receipt must have no applied mutations.
+Only adapter responses or independently verified external evidence may populate `applied_mutations`, applied spend, external receipt IDs, and resulting-state evidence. `verification_status: verified` requires a passing reconciliation, resulting-state fingerprint, `executed_at`, and evidence plus applied spend for every receipt slice. A manual report remains `reported` until independently verified, and therefore cannot use `status: complete`. A blocked receipt must have no applied mutations, applied spend, or `executed_at`. Do not include `immutable_fingerprint`; `fpa_artifact_commit` supplies it after strict validation and durable storage.