@viccydev/pi-fpa 0.3.2 → 0.4.0

package/README.md

@@ -39,6 +39,8 @@ Skill：
 | `fpa_calc` | 确定性计算器：命名公式求值（四则、abs/min/max/round），NULL 与除零安全传播 |
 | `fpa_compare` | 双期间对比：差值、百分比变化、逐行贡献度全部由代码计算 |
 
+`fpa_data_catalog` 默认只读取数据字典和各数据集日期覆盖，不执行随表规模增长的精确行数扫描。确实需要精确 `row_count`、App 数量和 cohort-size 覆盖时显式传入 `include_stats: true`；需要 App 列表时传入 `include_apps: true`。这些补充信息都有独立的 5 秒预算，单个数据集超时会返回对应的 `*_unavailable` 说明，不会丢失其它数据集的覆盖信息。认证、网络、服务端错误和调用方取消仍然抛出。
+
 设计契约：**模型不写 SQL、不做任何算术**。模型只从注册表中选择数据集、指标和维度；SQL 生成、数据库聚合和全部派生计算（比率、差异、LTV/ROAS/留存、临时公式）都在 Extension 代码内完成，缺数据或除零返回 `NULL`，绝不编造数值。
 
 Extension 内置的关键防护：
@@ -108,12 +110,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.3.0
+pi install git:github.com/linyqh/pi-fpa@v0.3.2
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如当前 `0.3.0` 对应 `v0.3.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.4.0` 对应 `v0.4.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 首次发布前需要完成一次仓库配置：
 

package/extensions/fpa-artifacts/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { commitArtifact } from "./store.ts";
+import { commitArtifact, commitArtifactFromPath } from "./store.ts";
 
 function toolResult(value: Record<string, unknown>) {
 	return {
@@ -16,21 +16,34 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 		label: "Commit FP&A Artifact",
 		description:
 			"Validate, reconcile, fingerprint, and atomically commit a canonical FP&A artifact under the current project's artifacts directory. " +
-			"Use this instead of claiming a Markdown report is frozen. Supported v1 artifacts are approved_cycle_forecast and execution_receipt.",
+			"Use this instead of claiming a Markdown report is frozen. Supported v1 artifacts are approved_cycle_forecast and execution_receipt. " +
+			"Supply the artifact inline, or write it to a JSON file first and pass artifact_path — prefer the file for anything large.",
 		promptSnippet: "Validate and durably freeze a canonical FP&A artifact",
 		promptGuidelines: [
 			"Use fpa_artifact_commit before calling an approved forecast immutable or using it to publish a dashboard.",
 			"Do not supply immutable_fingerprint; the tool calculates it after validation and reconciliation.",
+			"Write a large artifact to a JSON file across turns and commit it with artifact_path; a single inline argument can be cut off at the model output limit.",
 		],
 		parameters: Type.Object(
 			{
-				artifact: Type.Unknown({ description: "Canonical artifact object matching the referenced FP&A artifact contract" }),
+				artifact: Type.Optional(Type.Unknown({ description: "Canonical artifact object matching the referenced FP&A artifact contract" })),
+				artifact_path: Type.Optional(Type.String({
+					minLength: 1,
+					description: "Project-relative path to a JSON file holding the canonical artifact. Mutually exclusive with artifact.",
+				})),
 			},
 			{ additionalProperties: false },
 		),
 		executionMode: "sequential",
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const committed = await commitArtifact(ctx.cwd, params.artifact);
+			const hasInline = params.artifact !== undefined;
+			const hasPath = params.artifact_path !== undefined;
+			if (hasInline === hasPath) {
+				throw new Error("Supply exactly one of artifact or artifact_path.");
+			}
+			const committed = hasPath
+				? await commitArtifactFromPath(ctx.cwd, params.artifact_path as string)
+				: await commitArtifact(ctx.cwd, params.artifact);
 			return toolResult({
 				status: "committed",
 				artifact_type: committed.artifactType,

package/extensions/fpa-artifacts/store.ts

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
-import { join } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 
 import {
 	validateArtifact,
@@ -10,6 +10,8 @@ import {
 	type CanonicalArtifactInput,
 } from "./contracts.ts";
 
+export const ARTIFACT_MAX_BYTES = 2 * 1024 * 1024;
+
 export interface CommitArtifactResult {
 	artifactType: ArtifactType;
 	fingerprint: string;
@@ -58,6 +60,47 @@ async function existingArtifactDirectory(projectRoot: string): Promise<string> {
 	return artifactsDir;
 }
 
+/**
+ * Resolve a caller-supplied draft path inside the project.
+ *
+ * Same fail-closed posture as the committed artifacts themselves: no escaping
+ * the project root, no symlinks, no unbounded reads.
+ */
+async function resolveDraftPath(projectRoot: string, artifactPath: string): Promise<string> {
+	if (!artifactPath.trim()) throw new Error("artifact_path must be a non-empty path.");
+	const root = await realpath(projectRoot);
+	const resolved = resolve(root, artifactPath);
+	const relation = relative(root, resolved);
+	if (relation === "" || relation.startsWith("..") || isAbsolute(relation)) {
+		throw new Error("artifact_path must stay inside the project directory.");
+	}
+	const stat = await lstat(resolved);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("artifact_path must point at a regular file, not a symlink.");
+	if (stat.size > ARTIFACT_MAX_BYTES) throw new Error(`artifact_path exceeds the ${ARTIFACT_MAX_BYTES / (1024 * 1024)}MB artifact limit.`);
+	return resolved;
+}
+
+/**
+ * Commit a canonical artifact an agent wrote to disk instead of passing inline.
+ *
+ * A full `approved_cycle_forecast` runs to tens of thousands of tokens, and
+ * emitting one as a single tool argument is exactly the shape that gets cut off
+ * at the model output limit — leaving the caller convinced it committed
+ * something it never did. A draft file can be written and corrected across as
+ * many turns as it takes, and this entry point keeps the validation,
+ * reconciliation, fingerprinting, and atomic write identical to the inline path.
+ */
+export async function commitArtifactFromPath(projectRoot: string, artifactPath: string): Promise<CommitArtifactResult> {
+	const path = await resolveDraftPath(projectRoot, artifactPath);
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(await readFile(path, "utf8"));
+	} catch (error) {
+		throw new Error(`artifact_path is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return commitArtifact(projectRoot, parsed);
+}
+
 export async function commitArtifact(projectRoot: string, input: unknown): Promise<CommitArtifactResult> {
 	const artifact = validateArtifact(input);
 	if (artifact.artifact_type === "execution_receipt") {
@@ -98,7 +141,7 @@ export async function readCommittedArtifact(projectRoot: string, artifactType: A
 	const path = join(await existingArtifactDirectory(projectRoot), `${artifactType}.json`);
 	const stat = await lstat(path);
 	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${artifactType} must be a regular file, not a symlink.`);
-	if (stat.size > 2 * 1024 * 1024) throw new Error(`${artifactType} exceeds the 2MB artifact limit.`);
+	if (stat.size > ARTIFACT_MAX_BYTES) throw new Error(`${artifactType} exceeds the ${ARTIFACT_MAX_BYTES / (1024 * 1024)}MB artifact limit.`);
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(await readFile(path, "utf8"));

package/extensions/fpa-data/index.ts

@@ -30,23 +30,22 @@ import {
 	type QuerySpec,
 } from "./sql.ts";
 import { runStructuredQuery } from "./runtime.ts";
-import { runQuery, type SqlRow } from "./supabase.ts";
+import { runQuery, SupabaseQueryTimeoutError, type SqlRow } from "./supabase.ts";
 
 const MAX_TOOL_TEXT_CHARS = 100_000;
 const MAX_DISPLAY_ROWS = 200;
 
-/** Full-scan catalog stats get a shorter leash than a real query; they are context, not answers. */
-const CATALOG_STATS_TIMEOUT_MS = 12_000;
+/** Coverage is essential but one slow dataset must not consume the whole tool budget. */
+const CATALOG_COVERAGE_TIMEOUT_MS = 5_000;
 
-/**
- * Resolve to null when supplementary work fails, so one slow table degrades a field
- * instead of the whole tool. A caller-initiated abort still propagates.
- */
-async function bestEffort<T>(work: Promise<T>, signal?: AbortSignal): Promise<T | null> {
+/** Explicitly requested supplementary catalog data has a bounded, non-fatal budget. */
+const CATALOG_OPTIONAL_TIMEOUT_MS = 5_000;
+
+async function fallbackOnTimeout<T>(work: Promise<T>, signal?: AbortSignal): Promise<T | null> {
 	try {
 		return await work;
 	} catch (error) {
-		if (signal?.aborted) throw error;
+		if (signal?.aborted || !(error instanceof SupabaseQueryTimeoutError)) throw error;
 		return null;
 	}
 }
@@ -144,6 +143,12 @@ export default function fpaDataExtension(pi: ExtensionAPI): void {
 		],
 		parameters: Type.Object(
 			{
+				include_stats: Type.Optional(
+					Type.Boolean({
+						description:
+							"Also request exact row/app counts and cohort-size availability. These are scan-bound and best-effort.",
+					}),
+				),
 				include_apps: Type.Optional(
 					Type.Boolean({ description: "Also list distinct app codes (up to 200)." }),
 				),
@@ -152,25 +157,65 @@ export default function fpaDataExtension(pi: ExtensionAPI): void {
 		),
 		executionMode: "parallel",
 		async execute(_toolCallId, params, signal) {
-			// Date coverage is the part callers must have, and min/max over an indexed date
-			// column is cheap. Run one query per dataset so a single slow table cannot time
-			// out the whole catalog, then gather the scan-bound stats separately.
+			// Date coverage is the part callers must have. Keep each dataset in its own
+			// timeout domain so a missing leading-date index cannot sink the whole catalog;
+			// exact scan-bound statistics remain opt-in.
 			const coverageRows = await Promise.all(
-				COVERAGE_TARGETS.map(async (target) => (await runQuery(buildCoverageSql(target), { signal }))[0] ?? { dataset: target.dataset }),
+				COVERAGE_TARGETS.map(async (target) => {
+					const rows = await fallbackOnTimeout(
+						runQuery(buildCoverageSql(target), {
+							signal,
+							timeoutMs: CATALOG_COVERAGE_TIMEOUT_MS,
+						}),
+						signal,
+					);
+					return rows?.[0] ?? {
+						dataset: target.dataset,
+						date_min: null,
+						date_max: null,
+						...(rows === null
+							? {
+									coverage_unavailable:
+										"Date coverage timed out for this dataset; other datasets are unaffected.",
+								}
+							: {}),
+					};
+				}),
 			);
+			const statsBySource = new Map<string, Promise<SqlRow[] | null>>();
+			const statsFor = (target: (typeof COVERAGE_TARGETS)[number]) => {
+				const key = `${target.table}\u0000${target.appColumn}`;
+				let pending = statsBySource.get(key);
+				if (!pending) {
+					pending = fallbackOnTimeout(
+						runQuery(buildCoverageStatsSql(target), {
+							signal,
+							timeoutMs: CATALOG_OPTIONAL_TIMEOUT_MS,
+						}),
+						signal,
+					);
+					statsBySource.set(key, pending);
+				}
+				return pending;
+			};
 			const [statsRows, cohortSize, apps] = await Promise.all([
-				Promise.all(
-					COVERAGE_TARGETS.map((target) =>
-						bestEffort(runQuery(buildCoverageStatsSql(target), { signal, timeoutMs: CATALOG_STATS_TIMEOUT_MS }), signal),
-					),
-				),
-				bestEffort(runQuery(buildCohortSizeCoverageSql(), { signal, timeoutMs: CATALOG_STATS_TIMEOUT_MS }), signal),
+				params.include_stats
+					? Promise.all(
+							COVERAGE_TARGETS.map((target) => statsFor(target)),
+						)
+					: Promise.resolve(COVERAGE_TARGETS.map(() => null)),
+				params.include_stats
+					? fallbackOnTimeout(runQuery(buildCohortSizeCoverageSql(), { signal, timeoutMs: CATALOG_OPTIONAL_TIMEOUT_MS }), signal)
+					: Promise.resolve(null),
 				params.include_apps
-					? runQuery(
-							"select app_code, string_agg(distinct platform, ',' order by platform) as platforms " +
-								"from appsflyer_ua_campaign_daily where app_code is not null " +
-								"group by 1 order by 1 limit 200",
-							{ signal },
+					? fallbackOnTimeout(
+							runQuery(
+								"select app_code, string_agg(distinct platform, ',' order by platform) as platforms " +
+									"from appsflyer_ua_campaign_daily where app_code is not null " +
+									"group by 1 order by 1 limit 200",
+								{ signal, timeoutMs: CATALOG_OPTIONAL_TIMEOUT_MS },
+							),
+							signal,
 						)
 					: Promise.resolve<SqlRow[]>([]),
 			]);
@@ -178,7 +223,15 @@ export default function fpaDataExtension(pi: ExtensionAPI): void {
 				const stats = statsRows[index]?.[0];
 				return stats
 					? { ...row, ...stats }
-					: { ...row, row_count: null, apps: null, updated_at: null, stats_unavailable: "Row counts timed out; date coverage above is unaffected." };
+					: {
+							...row,
+							row_count: null,
+							apps: null,
+							updated_at: null,
+							stats_unavailable: params.include_stats
+								? "Row counts timed out; date coverage above is unaffected."
+								: "Not requested; set include_stats=true for exact row and app counts.",
+						};
 			});
 
 			return toolResult(
@@ -200,8 +253,25 @@ export default function fpaDataExtension(pi: ExtensionAPI): void {
 					})),
 					coverage,
 					cohort_size_available: cohortSize?.[0] ?? null,
+					...(cohortSize?.[0]
+						? {}
+						: {
+								cohort_size_unavailable: params.include_stats
+									? "Cohort-size coverage timed out; dataset date coverage is unaffected."
+									: "Not requested; set include_stats=true for cohort-size availability.",
+							}),
 					caveats: CATALOG_CAVEATS,
-					...(params.include_apps ? { apps } : {}),
+					...(params.include_apps
+						? {
+								apps,
+								...(apps === null
+									? {
+											apps_unavailable:
+												"App list timed out; dataset definitions and date coverage are unaffected.",
+										}
+									: {}),
+							}
+						: {}),
 				},
 				"coverage",
 			);

package/extensions/fpa-data/supabase.ts

@@ -35,6 +35,15 @@ export function resolveConfig(env: Record<string, string | undefined> = process.
 
 export type SqlRow = Record<string, unknown>;
 
+export class SupabaseQueryTimeoutError extends Error {
+	readonly code = "SUPABASE_QUERY_TIMEOUT";
+
+	constructor() {
+		super("Supabase query timed out. Narrow the date range or filters.");
+		this.name = "SupabaseQueryTimeoutError";
+	}
+}
+
 export async function runQuery(
 	sql: string,
 	options: { signal?: AbortSignal; timeoutMs?: number; config?: SupabaseConfig } = {},
@@ -45,6 +54,7 @@ export async function runQuery(
 	if (options.signal) signals.push(options.signal);
 
 	let response: Response;
+	let body: string;
 	try {
 		response = await fetch(
 			`${API_BASE}/v1/projects/${config.projectRef}/database/query`,
@@ -58,16 +68,19 @@ export async function runQuery(
 				signal: AbortSignal.any(signals),
 			},
 		);
+		body = await response.text();
 	} catch (error) {
+		if (options.signal?.aborted) {
+			throw options.signal.reason ?? error;
+		}
 		if (error instanceof Error && error.name === "TimeoutError") {
-			throw new Error("Supabase query timed out. Narrow the date range or filters.");
+			throw new SupabaseQueryTimeoutError();
 		}
 		throw new Error(
 			`Could not reach the Supabase Management API: ${error instanceof Error ? error.message : String(error)}`,
 		);
 	}
 
-	const body = await response.text();
 	if (new TextEncoder().encode(body).byteLength > MAX_RESPONSE_BYTES) {
 		throw new Error(
 			`Supabase response exceeds ${MAX_RESPONSE_BYTES} bytes. Narrow the query with filters, a shorter date range, or a lower limit.`,
@@ -86,6 +99,12 @@ export async function runQuery(
 			payload && typeof payload === "object" && "message" in payload
 				? String((payload as { message: unknown }).message)
 				: body.slice(0, 500);
+		if (
+			response.status === 504 ||
+			/(?:statement|query|gateway) (?:timed out|timeout)/i.test(detail)
+		) {
+			throw new SupabaseQueryTimeoutError();
+		}
 		throw new Error(`Supabase Management API error ${response.status}: ${detail}`);
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "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 --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": "node tests/package-structure.test.mjs && node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs 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 && node --test tests/artifact-store.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs",
+    "test:unit": "node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs 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"

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. Build the canonical `execution_receipt` using [artifact-contract.md](references/artifact-contract.md), then call `fpa_artifact_commit`.
+7. Build the canonical `execution_receipt` using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/execution_receipt.input.json`, then commit it with `fpa_artifact_commit` using `artifact_path`.
 
 ## Stop conditions
 
@@ -37,4 +37,4 @@ Stop before or during execution on version mismatch, target ambiguity, budget mi
 
 ## Boundary
 
-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`.
+Execution ends after reconciliation and a successful canonical receipt commit. A Markdown report is not an execution receipt, and neither is a written draft file — the receipt is frozen only when `fpa_artifact_commit` returns a fingerprint. 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

@@ -40,3 +40,12 @@ blockers: []
 ```
 
 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.
+
+Pass this artifact by path, not inline:
+
+```
+write  artifacts/execution_receipt.input.json
+fpa_artifact_commit  { "artifact_path": "artifacts/execution_receipt.input.json" }
+```
+
+`artifact_path` is project-relative, must stay inside the project, and must be a regular file. Emitting a full receipt as one inline argument risks being cut off at the model output limit, which leaves nothing committed while the turn still reads as finished.

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

@@ -25,7 +25,37 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
 3. Recalculate future-period operating outcomes from that allocation using the declared model.
 4. Provide downside, base, and upside values for each supported KPI.
 5. Reconcile allocation totals, formulas, and cross-metric identities.
-6. Build the canonical `approved_cycle_forecast` input using [artifact-contract.md](references/artifact-contract.md), then call `fpa_artifact_commit`.
+6. Build the canonical `approved_cycle_forecast` input using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/approved_cycle_forecast.input.json`.
+7. Commit it with `fpa_artifact_commit` using `artifact_path`.
+
+## Why the draft file
+
+A full forecast is far too large to emit as a single inline tool argument: the
+call gets cut off at the model output limit, and what is left behind reads like
+a finished turn. Write the draft with the file tools instead — across as many
+turns and corrections as it takes — then commit the finished file by path. If a
+later step in this graph already commits the draft for you, stop after writing
+it and say so; do not claim a fingerprint you were not handed.
+
+## Status and the publish gate
+
+`status` describes the quality of what this forecast promised to deliver, not
+how much it promised.
+
+- Everything promised was delivered, and every approval condition is met → `complete`.
+- Something promised could not be delivered, or carries a known defect → `complete_with_limits`, with that item and its reason in `unsupported_metrics`.
+- Approval evidence is missing or mismatched → `blocked`.
+
+Work the planning stage explicitly placed outside this cycle's scope is neither
+a limit nor a defect: it does not belong in `unsupported_metrics` and does not
+downgrade `status`.
+
+This matters downstream: `fpa_dashboard_refresh` with `mode: publish` accepts
+only `complete`, so `complete_with_limits` blocks the dashboard. Do not
+misreport a narrowed scope as a limit and stall the publish, and do not hide a
+real defect to get through the gate. When something that was promised cannot be
+delivered, report `complete_with_limits` honestly and say that the scope
+declaration upstream needs correcting.
 
 ## Boundaries
 
@@ -36,4 +66,4 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
 
 ## Completion
 
-The planning workflow ends only after `fpa_artifact_commit` returns `status: committed` and an `immutable_fingerprint`. A Markdown report is optional context, not the frozen source of truth. Execution, if requested, is a separate workflow using `$fpa-execute-approved-strategy`. Review waits for the next cycle's Actuals and uses `$fpa-review-cycle`.
+The planning workflow ends only after `fpa_artifact_commit` returns `status: committed` and an `immutable_fingerprint`. A Markdown report is optional context, not the frozen source of truth. Never report a forecast as frozen on the strength of a written file alone — the file is a draft until the tool returns a fingerprint. Execution, if requested, is a separate workflow using `$fpa-execute-approved-strategy`. Review waits for the next cycle's Actuals and uses `$fpa-review-cycle`.

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

@@ -43,4 +43,13 @@ reconciliation_checks: []
 frozen_at: timestamp
 ```
 
-Do not include `immutable_fingerprint` in the tool input. `fpa_artifact_commit` validates exact fields, approval state, allocation totals, every scenario's slice-to-consolidated totals, and supplied ROAS against aggregated revenue/spend. It computes the fingerprint and returns it after durable storage. The agent must not claim the artifact is frozen until that tool succeeds.
+Do not include `immutable_fingerprint` in the tool input; a draft that carries one is rejected. `fpa_artifact_commit` validates exact fields, approval state, allocation totals, every scenario's slice-to-consolidated totals, and supplied ROAS against aggregated revenue/spend. It computes the fingerprint and returns it after durable storage. The agent must not claim the artifact is frozen until that tool succeeds.
+
+Pass this artifact by path, not inline:
+
+```
+write  artifacts/approved_cycle_forecast.input.json
+fpa_artifact_commit  { "artifact_path": "artifacts/approved_cycle_forecast.input.json" }
+```
+
+`artifact_path` is project-relative, must stay inside the project, and must be a regular file. The inline `artifact` parameter still works and is fine for small artifacts, but a forecast of any real size will be truncated at the model output limit if you try to emit it in one call.