@idlekit/cli 0.4.0 → 0.5.0

package/dist/main.js

@@ -8397,7 +8397,7 @@ var init_validate = __esm(() => {
   OFFLINE_ACTORS = new Set(["player", "automation"]);
 });
 
-// ../../node_modules/.bun/typia@14.0.6+c0da6f6c08648afa/node_modules/typia/lib/internal/_validateReport.mjs
+// ../../node_modules/.bun/typia@15.1.0+367f7514c87f1df1/node_modules/typia/lib/internal/_validateReport.mjs
 var _validateReport = (array) => {
   const isAncestor = (ancestor, descendant) => descendant === ancestor || descendant.startsWith(`${ancestor}.`) || descendant.startsWith(`${ancestor}[`);
   const reportable = (path) => {
@@ -8422,7 +8422,7 @@ var _validateReport = (array) => {
 };
 var init__validateReport = () => {};
 
-// ../../node_modules/.bun/typia@14.0.6+c0da6f6c08648afa/node_modules/typia/lib/internal/_createStandardSchema.mjs
+// ../../node_modules/.bun/typia@15.1.0+367f7514c87f1df1/node_modules/typia/lib/internal/_createStandardSchema.mjs
 var _createStandardSchema = (fn) => Object.assign(fn, { "~standard": {
   version: 1,
   vendor: "typia",
@@ -18414,7 +18414,7 @@ var init_checks3 = __esm(() => {
   FAIL_ON = ["error", "warn", "inconclusive", "unsupported"];
 });
 
-// ../../node_modules/.bun/typia@14.0.6+c0da6f6c08648afa/node_modules/typia/lib/internal/_accessExpressionAsString.mjs
+// ../../node_modules/.bun/typia@15.1.0+367f7514c87f1df1/node_modules/typia/lib/internal/_accessExpressionAsString.mjs
 var _accessExpressionAsString = (str) => variable(str) ? `.${str}` : `[${JSON.stringify(str)}]`, variable = (str) => reserved(str) === false && /^[a-zA-Z_$][a-zA-Z_$0-9]*$/g.test(str), reserved = (str) => RESERVED.has(str), RESERVED;
 var init__accessExpressionAsString = __esm(() => {
   RESERVED = /* @__PURE__ */ new Set([
@@ -18961,7 +18961,7 @@ var init_judge = __esm(() => {
 // ../core/dist/sim/analysis/flow.js
 var init_flow = () => {};
 
-// ../../node_modules/.bun/typia@14.0.6+c0da6f6c08648afa/node_modules/typia/lib/internal/_isTypeUint32.mjs
+// ../../node_modules/.bun/typia@15.1.0+367f7514c87f1df1/node_modules/typia/lib/internal/_isTypeUint32.mjs
 var _isTypeUint32 = (value) => Math.floor(value) === value && MINIMUM <= value && value <= MAXIMUM, MINIMUM = 0, MAXIMUM;
 var init__isTypeUint32 = __esm(() => {
   MAXIMUM = 2 ** 32 - 1;
@@ -19570,7 +19570,7 @@ var init_bun = __esm(() => {
 var require_package = __commonJS(function(exports, module) {
   module.exports = {
     name: "@idlekit/cli",
-    version: "0.4.0",
+    version: "0.5.0",
     description: "Bun-first idk CLI for idle game scenario validation, simulation, tuning, and reporting.",
     license: "MIT",
     type: "module",
@@ -19623,7 +19623,7 @@ var require_package = __commonJS(function(exports, module) {
       "@clack/prompts": "1.8.1",
       "@gunshi/plugin-completion": "0.37.3",
       "@gunshi/plugin-suggestion": "0.37.3",
-      "@idlekit/core": "0.4.0",
+      "@idlekit/core": "0.4.1",
       ajv: "^8.20.0",
       gunshi: "0.37.3",
       "proper-lockfile": "4.1.2",
@@ -35201,8 +35201,10 @@ async function readScenarioFileWithMeta(path) {
 }
 
 // src/io/writeOutput.ts
+init_errors3();
 init_bun();
 import { resolve as resolve5 } from "path";
+import { realpath, stat } from "fs/promises";
 function toCsv(data) {
   if (!Array.isArray(data)) {
     return `value
@@ -35276,6 +35278,27 @@ async function writeOutput(args) {
     return;
   }
   const abs = resolve5(args.outPath);
+  for (const input of args.protectedInputs ?? []) {
+    const source = resolve5(input);
+    let same = source === abs;
+    if (!same) {
+      try {
+        const [outputReal, inputReal, outputStat, inputStat] = await Promise.all([
+          realpath(abs),
+          realpath(source),
+          stat(abs, { bigint: true }),
+          stat(source, { bigint: true })
+        ]);
+        same = outputReal === inputReal || outputStat.ino !== 0n && outputStat.dev === inputStat.dev && outputStat.ino === inputStat.ino;
+      } catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT" && code !== "ENOTDIR")
+          throw error;
+      }
+    }
+    if (same)
+      throw usageError(`Output path must not overwrite an input file: ${input}`);
+  }
   await writeTextFile(abs, body);
   console.log(`Wrote ${args.format} output to ${abs}`);
 }
@@ -36449,6 +36472,15 @@ init_outputMeta();
 import { extname as extname3, resolve as resolve8 } from "path";
 
 // src/lib/ltvCalibration.ts
+function assertFiniteNumbers(value, path) {
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new RangeError(`Calibration requires finite numbers; numeric overflow at ${path}`);
+  }
+  if (typeof value === "object" && value !== null) {
+    for (const [key, child] of Object.entries(value))
+      assertFiniteNumbers(child, `${path}.${key}`);
+  }
+}
 function clamp012(v) {
   if (v < 0)
     return 0;
@@ -36521,7 +36553,7 @@ function estimateCorrelation(x, y) {
       varianceY
     };
   }
-  const raw = clampCorrelation(cov / Math.sqrt(vx * vy));
+  const raw = clampCorrelation(cov / Math.sqrt(vx) / Math.sqrt(vy));
   const ci95 = 1.96 / Math.sqrt(Math.max(1, n - 3));
   const sampleConfidence = clamp012(1 - ci95);
   const varianceConfidenceX = varianceX / (varianceX + 0.01);
@@ -36642,7 +36674,7 @@ function calibrateMonetization(rows) {
     conversionAd: estimatedCorrelationPair.conversionAd.confidence,
     arppuAd: estimatedCorrelationPair.arppuAd.confidence
   };
-  return {
+  const result = {
     monetization: {
       cohorts: {
         baseUsers: cohortSize
@@ -36650,8 +36682,8 @@ function calibrateMonetization(rows) {
       retention: {
         d1: clamp012(d1),
         d7: clamp012(Math.min(d1, d7)),
-        d30: clamp012(Math.min(d7, d30)),
-        d90: clamp012(Math.min(d30, d90)),
+        d30: clamp012(Math.min(d1, d7, d30)),
+        d90: clamp012(Math.min(d1, d7, d30, d90)),
         longTailDailyDecay: 0.02
       },
       revenue: {
@@ -36710,6 +36742,8 @@ function calibrateMonetization(rows) {
       correlationDiagnostics: estimatedCorrelationPair
     }
   };
+  assertFiniteNumbers(result, "calibration");
+  return result;
 }
 // src/lib/ltvProjection.ts
 function clamp013(v) {
@@ -36992,6 +37026,135 @@ function estimateLtvDistribution(args) {
     quantiles: byQuantile
   };
 }
+// src/lib/cohortObservation.ts
+var RETENTION_DAYS = [1, 7, 30, 90];
+function observeCohort(rows, observedThroughDay) {
+  if (!Number.isSafeInteger(observedThroughDay) || observedThroughDay < 0)
+    throw new Error("observed-through-day must be a nonnegative safe integer");
+  if (rows.length === 0)
+    throw new Error("Observed cohort requires at least one install record");
+  const users = new Map;
+  for (const row of rows) {
+    if (!row.userId.trim() || !Number.isSafeInteger(row.day) || row.day < 0 || row.day > observedThroughDay) {
+      throw new Error("Observed cohort requires a user ID and integer days within observed-through-day");
+    }
+    if (![row.iapRevenue, row.adRevenue, ...row.acquisitionCost === undefined ? [] : [row.acquisitionCost]].every((v) => Number.isFinite(v) && v >= 0)) {
+      throw new Error("Observed cohort revenue and acquisition costs must be finite and nonnegative");
+    }
+    if (row.active !== undefined && typeof row.active !== "boolean")
+      throw new Error("Observed cohort active must be boolean");
+    const user = users.get(row.userId) ?? { days: new Set, active: new Set };
+    if (user.days.has(row.day))
+      throw new Error("Observed cohort requires one aggregated row per user and day");
+    user.days.add(row.day);
+    if (row.active ?? true)
+      user.active.add(row.day);
+    users.set(row.userId, user);
+  }
+  for (const user of users.values()) {
+    if (!user.days.has(0))
+      throw new Error("Observed cohort requires a day 0 install record for every user, including inactive users");
+  }
+  const n = users.size;
+  const observation = {
+    observedThroughDay,
+    users: n,
+    retention: RETENTION_DAYS.map((day) => {
+      if (day > observedThroughDay)
+        return { day, status: "not-observed", users: n, activeUsers: null, rate: null, interval95: null };
+      const activeUsers = [...users.values()].filter((user) => user.active.has(day)).length;
+      const rate = activeUsers / n;
+      const z2 = 1.959963984540054 ** 2;
+      const denominator = 1 + z2 / n;
+      const center = (rate + z2 / (2 * n)) / denominator;
+      const radius = Math.sqrt(z2 * (rate * (1 - rate) / n + z2 / (4 * n * n))) / denominator;
+      return { day, status: "observed", users: n, activeUsers, rate, interval95: { min: activeUsers === 0 ? 0 : Math.max(0, center - radius), max: activeUsers === n ? 1 : Math.min(1, center + radius) } };
+    })
+  };
+  assertCohortObservation(observation);
+  return observation;
+}
+function assertCohortObservation(observation) {
+  if (!Number.isSafeInteger(observation.users) || observation.users < 1 || !Number.isSafeInteger(observation.observedThroughDay) || observation.observedThroughDay < 0) {
+    throw new Error("Invalid cohort population or observation cutoff");
+  }
+  if (observation.retention.length !== RETENTION_DAYS.length)
+    throw new Error("Cohort retention must contain D1, D7, D30 and D90");
+  for (const [index, point] of observation.retention.entries()) {
+    if (point.day !== RETENTION_DAYS[index] || point.users !== observation.users)
+      throw new Error("Cohort retention days and population must match the observation");
+    const observed = point.day <= observation.observedThroughDay;
+    if (point.status !== (observed ? "observed" : "not-observed"))
+      throw new Error("Cohort retention status must match the observation cutoff");
+    if (!observed) {
+      if (point.activeUsers !== null || point.rate !== null || point.interval95 !== null)
+        throw new Error("Future retention must remain unobserved");
+      continue;
+    }
+    if (point.activeUsers === null || !Number.isSafeInteger(point.activeUsers) || point.activeUsers < 0 || point.activeUsers > point.users || point.rate !== point.activeUsers / point.users) {
+      throw new Error("Retained users and retention rate must match the installed population");
+    }
+    const interval = point.interval95;
+    if (point.rate === null || !interval || !Number.isFinite(interval.min) || !Number.isFinite(interval.max) || interval.min < 0 || interval.max > 1 || interval.min > point.rate || interval.max < point.rate) {
+      throw new Error("Retention confidence interval must be finite and contain the observed rate");
+    }
+  }
+}
+function observedRetentionRates(observation) {
+  return Object.fromEntries(observation.retention.filter((row) => row.rate !== null).map((row) => [`d${row.day}`, row.rate]));
+}
+function planRetentionPatch(observation, assumptions = {}) {
+  const rates = observedRetentionRates(observation);
+  if (Object.keys(rates).length === 0)
+    return { status: "unavailable", retention: {}, warnings: ["No retention day has been fully observed."] };
+  const merged = { ...assumptions, ...rates };
+  const warnings = [];
+  for (const day of RETENTION_DAYS) {
+    if (merged[`d${day}`] === undefined)
+      warnings.push(`Unobserved D${day} has no explicit retained assumption. An LTV default could conflict with the observations; supply this assumption in --scenario or observe this day before applying a patch.`);
+  }
+  let previous;
+  for (const day of RETENTION_DAYS) {
+    const rate = merged[`d${day}`];
+    if (rate === undefined)
+      continue;
+    if (previous && previous.rate < rate)
+      warnings.push(`D${previous.day}=${previous.rate} is below D${day}=${rate}. LTV requires d1 >= d7 >= d30 >= d90; review observations and retained assumptions before applying a patch.`);
+    previous = { day, rate };
+  }
+  return warnings.length ? { status: "requires-review", retention: {}, warnings } : { status: "ready", retention: rates, warnings };
+}
+function compareRetention(observation, assumptions) {
+  return observation.retention.map((row) => {
+    const assumption = assumptions[`d${row.day}`] ?? null;
+    return {
+      day: row.day,
+      assumption,
+      observed: row.rate,
+      differencePercentagePoints: row.rate === null || assumption === null ? null : (row.rate - assumption) * 100,
+      status: row.rate === null ? "not-observed" : assumption === null ? "unconfigured" : "compared"
+    };
+  });
+}
+function renderCohortMarkdown(observation, comparison, patch) {
+  const percent = (value) => value === null ? "unavailable" : `${(value * 100).toFixed(2)}%`;
+  const lines = [
+    "# Observed player retention",
+    "",
+    `${observation.users} installed users; complete activity export through day ${observation.observedThroughDay}. Exact-day retention counts every installed user, including those who never return.`,
+    "",
+    "| Day | Retained / installed | Observed rate | Wilson 95% interval | Assumption | Difference (percentage points) | Status |",
+    "| --- | --- | --- | --- | --- | --- | --- |"
+  ];
+  for (const [index, row] of observation.retention.entries()) {
+    const match = comparison?.[index];
+    lines.push(`| D${row.day} | ${row.activeUsers === null ? "unavailable" : `${row.activeUsers} / ${row.users}`} | ${percent(row.rate)} | ${row.interval95 ? `${percent(row.interval95.min)} to ${percent(row.interval95.max)}` : "unavailable"} | ${percent(match?.assumption ?? null)} | ${match?.differencePercentagePoints == null ? "unavailable" : match.differencePercentagePoints.toFixed(2)} | ${match?.status ?? row.status} |`);
+  }
+  lines.push("", `Retention patch: **${patch.status}**.`, "", ...patch.warnings.map((warning) => `- ${warning}`), "", "Positive differences mean observed retention exceeds the configured assumption. Only apply a ready patch. Unobserved days are omitted from scenarioPatch; merge its retention fields into the scenario and preserve the remaining assumptions.", "", "Use a separate held-out cohort to validate a fitted model. These observations and intervals describe this cohort; they do not establish fun, causal improvement, or future revenue. Mixed install ages, missing activity exports, and omitted nonreturning users invalidate this comparison.");
+  return lines.join(`
+`);
+}
+
 // src/commands/calibrate.ts
 init_bun();
 function parseCsvRows(raw) {
@@ -37064,21 +37227,46 @@ function parseNumeric(raw, row, field, opts) {
   }
   return n;
 }
-function parseCsvTelemetry(raw) {
+function parseActive(value, strict) {
+  if (value === undefined)
+    return true;
+  if (typeof value === "boolean")
+    return value;
+  if (typeof value === "number" && (value === 0 || value === 1))
+    return value === 1;
+  if (typeof value === "string") {
+    if (/^(1|true|yes|y)$/i.test(value))
+      return true;
+    if (/^(0|false|no|n)$/i.test(value))
+      return false;
+  }
+  if (strict)
+    throw usageError("Observed cohort active must be true/false, yes/no, or 1/0");
+  return typeof value === "string" ? /^(1|true|yes|y)$/i.test(value) : Boolean(value);
+}
+function parseCsvTelemetry(raw, strictCohort = false) {
   const rows2d = parseCsvRows(raw);
   if (rows2d.length < 2) {
     throw cliError("CLI_USAGE", "CSV telemetry requires a header and at least one data row");
   }
   const headers = (rows2d[0] ?? []).map(normalizeHeader);
+  if (strictCohort && new Set(headers).size !== headers.length)
+    throw usageError("Observed cohort CSV has duplicate headers");
   const rows = [];
   for (let i = 1;i < rows2d.length; i++) {
     const cols = rows2d[i] ?? [];
+    if (strictCohort && cols.length !== headers.length)
+      throw usageError(`Observed cohort CSV row ${i + 1} has the wrong number of columns`);
     const rec = {};
     headers.forEach((h, idx) => {
       rec[h] = cols[idx] ?? "";
     });
-    const userId = pick2(rec, ["user_id", "userid", "user", "id"]) ?? `anon-${i}`;
-    const dayRaw = pick2(rec, ["day", "day_index", "days_since_install"]) ?? "0";
+    const userInput = pick2(rec, ["user_id", "userid", "user", "id"]);
+    const dayInput = pick2(rec, ["day", "day_index", "days_since_install"]);
+    if (strictCohort && (!userInput?.trim() || !dayInput?.trim()))
+      throw usageError("Observed cohort requires explicit user_id and day fields");
+    const userId = userInput ?? `anon-${i}`;
+    const dayRaw = dayInput ?? "0";
     const iapRaw = pick2(rec, ["iap_revenue", "revenue", "iap", "purchase_revenue"]) ?? "0";
     const adRaw = pick2(rec, ["ad_revenue", "adrevenue", "ads"]) ?? "0";
     const activeRaw = pick2(rec, ["active", "is_active"]);
@@ -37087,7 +37275,7 @@ function parseCsvTelemetry(raw) {
     const iapRevenue = parseNumeric(iapRaw, i + 1, "revenue");
     const adRevenue = parseNumeric(adRaw, i + 1, "ad_revenue");
     const acquisitionCost = acqRaw !== undefined ? parseNumeric(acqRaw, i + 1, "acquisition_cost", { allowEmpty: true }) : undefined;
-    const active = activeRaw === undefined ? true : /^(1|true|yes|y)$/i.test(activeRaw);
+    const active = parseActive(activeRaw, strictCohort);
     rows.push({
       userId,
       day,
@@ -37099,7 +37287,7 @@ function parseCsvTelemetry(raw) {
   }
   return rows;
 }
-function parseJsonTelemetry(raw) {
+function parseJsonTelemetry(raw, strictCohort = false) {
   const parsed = JSON.parse(raw);
   if (!Array.isArray(parsed)) {
     throw cliError("CLI_USAGE", "JSON telemetry must be an array");
@@ -37110,12 +37298,21 @@ function parseJsonTelemetry(raw) {
       throw cliError("CLI_USAGE", `JSON telemetry row ${idx} must be an object`);
     }
     const r = row;
-    const userId = String(r.userId ?? r.user_id ?? r.user ?? r.id ?? `anon-${idx}`);
-    const day = Number(r.day ?? r.dayIndex ?? r.daysSinceInstall ?? 0);
+    const userInput = r.userId ?? r.user_id ?? r.user ?? r.id;
+    const dayInput = r.day ?? r.dayIndex ?? r.daysSinceInstall;
+    if (strictCohort && (typeof userInput !== "string" || !userInput.trim() || typeof dayInput !== "number"))
+      throw usageError("Observed cohort JSON requires explicit string userId and numeric day fields");
+    if (strictCohort)
+      for (const key of ["iapRevenue", "iap_revenue", "revenue", "adRevenue", "ad_revenue", "acquisitionCost", "acquisition_cost", "cpi"]) {
+        if (r[key] !== undefined && typeof r[key] !== "number")
+          throw usageError(`Observed cohort JSON ${key} must be numeric`);
+      }
+    const userId = String(userInput ?? `anon-${idx}`);
+    const day = Number(dayInput ?? 0);
     const iapRevenue = Number(r.iapRevenue ?? r.iap_revenue ?? r.revenue ?? 0);
     const adRevenue = Number(r.adRevenue ?? r.ad_revenue ?? 0);
     const acquisitionCost = r.acquisitionCost !== undefined || r.acquisition_cost !== undefined || r.cpi !== undefined ? Number(r.acquisitionCost ?? r.acquisition_cost ?? r.cpi) : undefined;
-    const active = r.active === undefined ? true : Boolean(r.active);
+    const active = parseActive(r.active, strictCohort);
     if (!Number.isFinite(day) || !Number.isFinite(iapRevenue) || !Number.isFinite(adRevenue)) {
       throw cliError("CLI_USAGE", `Invalid numeric value in json row ${idx}`);
     }
@@ -37137,26 +37334,65 @@ var calibrate_default = defineCommand({
     "input-format": option(_enum(["auto", "csv", "json"]).default("auto"), {
       description: "Telemetry file format"
     }),
+    "observed-through-day": option(exports_coerce.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(), {
+      description: "Complete activity cutoff for one install cohort; requires day 0 records for every installed user"
+    }),
+    scenario: option(string2().optional(), { description: "Compare observed retention with this scenario's explicit assumptions (requires --observed-through-day)" }),
     out: option(string2().optional(), { description: "Output path" }),
     format: option(_enum(["json", "md", "csv"]).default("json"), { description: "Output format" })
   },
   async handler({ flags, positional }) {
     const telemetryPath = positional[0];
-    if (!telemetryPath) {
+    if (!telemetryPath || positional.length !== 1) {
       throw usageError("Usage: idk calibrate <telemetry.csv|json> [--input-format auto|csv|json]");
     }
+    if (flags.scenario && flags["observed-through-day"] === undefined)
+      throw usageError("--scenario requires --observed-through-day for a mature cohort comparison");
     const abs = resolve8(process.cwd(), telemetryPath);
     const raw = await readTextFile(abs);
     const format = flags["input-format"] === "auto" ? extname3(abs).toLowerCase() : flags["input-format"];
-    const rows = format === ".csv" || format === "csv" ? parseCsvTelemetry(raw) : parseJsonTelemetry(raw);
-    const calibrated = calibrateMonetization(rows);
+    const rows = format === ".csv" || format === "csv" ? parseCsvTelemetry(raw, flags["observed-through-day"] !== undefined) : parseJsonTelemetry(raw, flags["observed-through-day"] !== undefined);
+    let observation;
+    if (flags["observed-through-day"] !== undefined) {
+      try {
+        observation = observeCohort(rows, flags["observed-through-day"]);
+      } catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error));
+      }
+    }
+    let calibrated;
+    try {
+      calibrated = calibrateMonetization(rows);
+    } catch (error) {
+      if (error instanceof RangeError)
+        throw usageError(error.message);
+      throw error;
+    }
+    const retentionRates = observation ? observedRetentionRates(observation) : undefined;
+    const scenario = flags.scenario ? await readScenarioFile(flags.scenario) : undefined;
+    const rate = number2().min(0).max(1).optional();
+    const parsedScenario = scenario === undefined ? undefined : object({
+      schemaVersion: literal(1),
+      monetization: object({ retention: object({ d1: rate, d7: rate, d30: rate, d90: rate }).passthrough().optional() }).passthrough().optional()
+    }).passthrough().safeParse(scenario);
+    if (parsedScenario && !parsedScenario.success)
+      throw usageError(`Invalid scenario retention assumptions: ${parsedScenario.error.message}`);
+    const comparison = observation && parsedScenario?.success ? compareRetention(observation, parsedScenario.data.monetization?.retention ?? {}) : undefined;
+    const patch = observation ? planRetentionPatch(observation, parsedScenario?.success ? parsedScenario.data.monetization?.retention : undefined) : undefined;
+    const monetization = observation ? {
+      ...calibrated.monetization,
+      retention: { longTailDailyDecay: calibrated.monetization?.retention?.longTailDailyDecay, ...patch?.retention }
+    } : calibrated.monetization;
     const outputMeta = buildOutputMeta({
       command: "calibrate",
-      telemetry: rows
+      telemetry: observation ? { rows, observedThroughDay: observation.observedThroughDay } : rows,
+      scenario,
+      scenarioPath: flags.scenario ? resolve8(flags.scenario) : undefined
     });
     await writeOutput({
       format: flags.format,
       outPath: flags.out,
+      protectedInputs: [abs, ...flags.scenario ? [resolve8(flags.scenario)] : []],
       data: flags.format === "json" ? {
         ok: true,
         source: abs,
@@ -37164,12 +37400,27 @@ var calibrate_default = defineCommand({
           rows: rows.length,
           users: calibrated.diagnostics.users
         },
-        monetization: calibrated.monetization,
-        diagnostics: calibrated.diagnostics,
-        scenarioPatch: {
+        monetization,
+        diagnostics: observation ? { ...calibrated.diagnostics, retention: retentionRates, observedThroughDay: observation.observedThroughDay } : calibrated.diagnostics,
+        ...observation ? { observation } : {},
+        ...comparison ? { comparison } : {},
+        ...patch ? { patchStatus: patch.status, patchWarnings: patch.warnings } : {},
+        scenarioPatch: observation ? { monetization: { retention: patch.retention } } : {
           monetization: calibrated.monetization
         }
-      } : [
+      } : observation ? flags.format === "md" ? renderCohortMarkdown(observation, comparison, patch) : observation.retention.map((row, index) => ({
+        day: row.day,
+        users: row.users,
+        activeUsers: row.activeUsers,
+        observedRate: row.rate,
+        interval95Min: row.interval95?.min ?? null,
+        interval95Max: row.interval95?.max ?? null,
+        assumption: comparison?.[index]?.assumption ?? null,
+        differencePercentagePoints: comparison?.[index]?.differencePercentagePoints ?? null,
+        status: comparison?.[index]?.status ?? row.status,
+        patchStatus: patch.status,
+        patchWarnings: patch.warnings.join(" ")
+      })) : [
         {
           source: abs,
           rows: rows.length,
@@ -37191,12 +37442,13 @@ var calibrate_default = defineCommand({
 
 // src/commands/balance.ts
 init_zod();
+import { resolve as resolve11 } from "path";
 
 // src/balance/workflow.ts
 init_dist2();
 init_zod();
 import { resolve as resolve10, dirname as dirname8 } from "path";
-import { stat } from "fs/promises";
+import { stat as stat2 } from "fs/promises";
 
 // src/cliMeta.ts
 var import_package2 = __toESM(require_package(), 1);
@@ -37442,7 +37694,7 @@ async function runPacingChecks(input, evaluator) {
 // src/balance/sheet.ts
 init_bun();
 import { constants } from "fs";
-import { lstat, mkdir, open as open2, realpath, rename, rm } from "fs/promises";
+import { lstat, mkdir, open as open2, realpath as realpath2, rename, rm } from "fs/promises";
 import { dirname as dirname7, isAbsolute as isAbsolute2, join, relative as relative2, resolve as resolve9, sep as sep2 } from "path";
 var SHEET_LIMITS = Object.freeze({
   maxCsvBytes: 2 * 1024 * 1024,
@@ -37816,7 +38068,7 @@ async function snapshotInputs(inputFiles, contextValue, limits) {
   let total = 0;
   for (const name of validInputNames(inputFiles, limits)) {
     const path = resolve9(inputFiles[name]);
-    const realPath = await realpath(path);
+    const realPath = await realpath2(path);
     const bytes = await boundedRead(realPath, Math.min(limits.maxInputBytes, limits.maxTotalInputBytes - total));
     total += bytes.length;
     if (total > limits.maxTotalInputBytes)
@@ -37843,7 +38095,7 @@ async function snapshotInputs(inputFiles, contextValue, limits) {
 async function canonicalOutput(path) {
   path = resolve9(path);
   try {
-    return await realpath(path);
+    return await realpath2(path);
   } catch (error) {
     if (error.code !== "ENOENT")
       throw error;
@@ -37880,7 +38132,7 @@ async function refreshSheetBundle(options) {
   validInputNames(options.inputFiles, limits);
   const output = await canonicalOutput(options.outputDir);
   for (const [name, path] of Object.entries(options.inputFiles)) {
-    if (isWithin(output, resolve9(path)) || isWithin(output, await realpath(path)))
+    if (isWithin(output, resolve9(path)) || isWithin(output, await realpath2(path)))
       throw new Error(`Output/input collision: ${name}`);
   }
   await mkdir(output, { recursive: true });
@@ -37940,7 +38192,7 @@ async function refreshSheetBundle(options) {
     if (manifestBytes.length > 1024 * 1024)
       throw new Error("Bundle manifest exceeds byte limit");
     await mkdir(generations, { recursive: true });
-    if (await realpath(generations) !== generations)
+    if (await realpath2(generations) !== generations)
       throw new Error("Bundle generations directory must not be a symlink");
     await mkdir(stage);
     for (const name of names)
@@ -38029,10 +38281,10 @@ async function readCurrentBundle(outputDir, inputFiles, options = {}) {
     if (!isRecord5(pointer) || pointer.version !== 1 || typeof pointer.generation !== "string" || !generationText.test(pointer.generation) || typeof pointer.manifestSha256 !== "string" || !sha256Text2.test(pointer.manifestSha256))
       throw new Error("Invalid bundle pointer");
     const generationPath = join(output, "generations", pointer.generation);
-    if (await realpath(generationPath) !== generationPath)
+    if (await realpath2(generationPath) !== generationPath)
       throw new Error("Bundle generation must not be a symlink");
     const manifestPath = join(generationPath, "manifest.json");
-    if (await realpath(manifestPath) !== manifestPath)
+    if (await realpath2(manifestPath) !== manifestPath)
       throw new Error("Bundle manifest must not be a symlink");
     const bytes = await boundedRead(manifestPath, 1024 * 1024);
     if (sha256Hex(bytes) !== pointer.manifestSha256)
@@ -38041,7 +38293,7 @@ async function readCurrentBundle(outputDir, inputFiles, options = {}) {
     let outputBytesRead = 0;
     for (const [name, artifact] of Object.entries(manifest.artifacts)) {
       try {
-        if (await realpath(artifact.path) !== artifact.path)
+        if (await realpath2(artifact.path) !== artifact.path)
           throw new Error("Artifact is a symlink");
         const artifactBytes = await boundedRead(artifact.path, Math.min(limits.maxOutputBytes, limits.maxTotalOutputBytes - outputBytesRead));
         outputBytesRead += artifactBytes.length;
@@ -38141,7 +38393,7 @@ function normalizeRunDocument(document, strategy, horizon) {
 }
 async function refreshBalanceWorkflow(configPath, flags, check = false) {
   const absoluteConfig = resolve10(configPath);
-  const configInfo = await stat(absoluteConfig);
+  const configInfo = await stat2(absoluteConfig);
   if (!configInfo.isFile() || configInfo.size > SHEET_LIMITS.maxInputBytes)
     throw new Error("Workflow config is not a bounded regular file");
   const rawConfig = await readTextFile(absoluteConfig);
@@ -38337,6 +38589,46 @@ async function refreshBalanceWorkflow(configPath, flags, check = false) {
   return { ...manifest, outcome };
 }
 
+// src/balance/report.ts
+function cell(value) {
+  return String(value).replaceAll("|", "\\|").replace(/[\r\n]/g, " ");
+}
+function explain(result) {
+  if (result.status === "breach" && result.value !== null) {
+    if (result.min !== undefined && result.value < result.min)
+      return `below the minimum by ${result.min - result.value} ${result.unit}`;
+    if (result.max !== undefined && result.value > result.max)
+      return `above the maximum by ${result.value - result.max} ${result.unit}`;
+  }
+  if (result.status === "pass")
+    return "within the inclusive target bounds";
+  return result.message ?? (result.status === "unreached" ? "not reached within the horizon" : "measurement unavailable");
+}
+function renderBalanceReport(report, generationPath) {
+  const lines = [
+    "# Balance targets",
+    "",
+    `Result: **${report.status}**. Simulated ${report.horizonSec} seconds using strategy ${cell(report.strategy)}; seeds ${report.seeds.join(", ")}.`,
+    "A target is a design constraint on this model under these conditions. End net worth is modeled asset value; it can differ from spendable wallet money.",
+    "",
+    "| Variant | Seed | Metric | Measured | Target | Status | Explanation |",
+    "| --- | --- | --- | --- | --- | --- | --- |"
+  ];
+  for (const entry of report.runs)
+    for (const result of entry.results) {
+      const target = [result.min === undefined ? undefined : `minimum ${result.min} ${result.unit}`, result.max === undefined ? undefined : `maximum ${result.max} ${result.unit}`].filter(Boolean).join(", ");
+      const measured = result.value === null ? "unavailable" : `${result.value} ${result.unit}`;
+      lines.push(`| ${cell(entry.run.variantId)} | ${entry.run.seed} | ${cell(result.metric)} | ${cell(measured)} | ${cell(target)} | ${result.status} | ${cell(explain(result))} |`);
+    }
+  lines.push("", report.ok ? "All declared targets passed." : "A target breached, was not reached, or could not be measured. The command exits 1; inspect the rows before changing the design.", "", `Saved generation: ${cell(generationPath)}`, "The generation contains exact values in results.json and reproduction inputs in provenance.json. Passing targets does not establish fun or player retention.");
+  return lines.join(`
+`);
+}
+function renderBalanceFreshness(result) {
+  return ["# Balance result freshness", "", `State: **${result.state}**. This checks saved inputs and artifacts; it does not check target success. Run balance without --check to evaluate the targets.`, ...result.staleReasons.map((reason) => `- ${cell(reason)}`)].join(`
+`);
+}
+
 // src/commands/balance.ts
 init_errors3();
 init_bun();
@@ -38345,13 +38637,15 @@ var balance_default = defineCommand({
   description: "Refresh a typed CSV balance sheet into scenario, pacing checks, and result sheets",
   options: {
     ...pluginOptions(),
-    check: option(exports_coerce.boolean().default(false), { description: "Check result freshness without rerunning simulations" })
+    check: option(exports_coerce.boolean().default(false), { description: "Check result freshness without rerunning simulations" }),
+    format: option(_enum(["json", "md"]).default("json"), { description: "JSON manifest or human-readable target explanations" })
   },
   async handler({ flags, positional }) {
     if (positional.length !== 1)
       throw usageError("Usage: idk balance <workflow.json> [--check] [plugin options]");
     const result = await refreshBalanceWorkflow(positional[0], flags, flags.check);
-    await writeStdout(JSON.stringify(result, null, 2) + `
+    const body = flags.format === "json" ? JSON.stringify(result, null, 2) : ("state" in result) ? renderBalanceFreshness(result) : renderBalanceReport(JSON.parse(await readTextFile(resolve11(result.generationPath, "results.json"))), result.generationPath);
+    await writeStdout(body + `
 `);
     if (flags.check && "state" in result && result.state !== "current")
       process.exitCode = 1;
@@ -38363,7 +38657,7 @@ var balance_default = defineCommand({
 // src/commands/compare.ts
 init_dist2();
 init_zod();
-import { resolve as resolve13 } from "path";
+import { resolve as resolve14 } from "path";
 
 // src/commands/_shared/compareEval.ts
 function formatEtaLabel(seconds, reached) {
@@ -38390,12 +38684,12 @@ init_errors3();
 init_outputMeta();
 
 // src/io/replayPolicy.ts
-import { resolve as resolve12 } from "path";
+import { resolve as resolve13 } from "path";
 
 // src/io/replayArtifact.ts
 init_outputMeta();
 init_bun();
-import { resolve as resolve11 } from "path";
+import { resolve as resolve12 } from "path";
 var REDACTED_KEYS = new Set([
   "generatedAt",
   "scenario",
@@ -38461,7 +38755,7 @@ function toReplayCommandLine(args) {
   return `bun run --cwd packages/cli dev -- ${rendered}`;
 }
 async function writeReplayArtifact(args) {
-  const abs = resolve11(args.outPath);
+  const abs = resolve12(args.outPath);
   const runId = args.meta.runId;
   const seed = args.meta.seed;
   const scenarioHash = args.meta.scenarioHash;
@@ -38537,7 +38831,7 @@ var PATH_FLAG_KINDS = {
 function normalizePathLike(pathLike, cwd) {
   if (pathLike.trim().length === 0)
     return pathLike;
-  return resolve12(cwd, pathLike);
+  return resolve13(cwd, pathLike);
 }
 function normalizeCsvPaths(raw, cwd) {
   return raw.split(",").map((x) => x.trim()).filter(Boolean).map((x) => normalizePathLike(x, cwd)).join(",");
@@ -38612,7 +38906,7 @@ function plain(value) {
     return "n/a";
   return String(value).replace(/[\r\n]+/g, " ");
 }
-function cell(value) {
+function cell2(value) {
   return plain(value).replaceAll("|", "\\|");
 }
 function inlineCode(value) {
@@ -38640,9 +38934,9 @@ function renderCompareMarkdown(args) {
     const higher = ["endMoney", "endNetWorth", "visibleChangesPerMinute"].includes(metric);
     const lower = ["droppedRate", "etaToTargetWorth", "timeToMilestone", "maxNoRewardGapSec"].includes(metric);
     const seconds = ["etaToTargetWorth", "timeToMilestone", "maxNoRewardGapSec"].includes(metric);
-    const value = (item) => seconds && (typeof item === "number" || typeof item === "string" && item.trim().length > 0) && Number.isFinite(Number(item)) ? `${cell(item)}s` : cell(item);
+    const value = (item) => seconds && (typeof item === "number" || typeof item === "string" && item.trim().length > 0) && Number.isFinite(Number(item)) ? `${cell2(item)}s` : cell2(item);
     const better = result.better === "a" || result.better === "b" ? result.better.toUpperCase() : result.better === "tie" ? "tie" : "undetermined";
-    lines.push(`| ${cell(metric)} | ${value(a)} | ${value(b)} | ${higher ? "higher" : lower ? "lower" : "n/a"} | ${better} |`);
+    lines.push(`| ${cell2(metric)} | ${value(a)} | ${value(b)} | ${higher ? "higher" : lower ? "lower" : "n/a"} | ${better} |`);
     if (result.better === "a" || result.better === "b")
       preferences[result.better].push(metric);
   }
@@ -39319,8 +39613,8 @@ var compare_default = defineCommand({
       }
     } : singleResults[0];
     if (flags["artifact-out"]) {
-      const aAbs = resolve13(process.cwd(), aPath);
-      const bAbs = resolve13(process.cwd(), bPath);
+      const aAbs = resolve14(process.cwd(), aPath);
+      const bAbs = resolve14(process.cwd(), bPath);
       await writeCommandReplayArtifact({
         outPath: flags["artifact-out"],
         command: "compare",
@@ -39358,7 +39652,7 @@ init_outputMeta();
 init_errors3();
 init_bun();
 init_selfCli();
-import { basename as basename4, dirname as dirname9, relative as relative3, resolve as resolve14 } from "path";
+import { basename as basename4, dirname as dirname9, relative as relative3, resolve as resolve15 } from "path";
 var START_MARKER = "# >>> idk completions >>>";
 var END_MARKER = "# <<< idk completions <<<";
 function userHome() {
@@ -39384,13 +39678,13 @@ function defaultRcPath(shell) {
   const home = userHome();
   switch (shell) {
     case "zsh":
-      return resolve14(home, ".zshrc");
+      return resolve15(home, ".zshrc");
     case "bash":
-      return resolve14(home, ".bashrc");
+      return resolve15(home, ".bashrc");
     case "fish":
-      return resolve14(home, ".config/fish/config.fish");
+      return resolve15(home, ".config/fish/config.fish");
     case "powershell":
-      return resolve14(home, "Documents/PowerShell/Microsoft.PowerShell_profile.ps1");
+      return resolve15(home, "Documents/PowerShell/Microsoft.PowerShell_profile.ps1");
   }
 }
 function completionsSourceLine(shell, executable = "idk") {
@@ -39423,7 +39717,7 @@ function replaceManagedBlock(existing, block) {
 }
 async function installCompletions(args) {
   const shell = detectShell(args.shell);
-  const rcPath = resolve14(args.rcPath ?? defaultRcPath(shell));
+  const rcPath = resolve15(args.rcPath ?? defaultRcPath(shell));
   const line = completionsSourceLine(shell, args.executable ?? "idk");
   const script = runSelfCli(["completions", shell]);
   if (script.exitCode !== 0) {
@@ -39467,7 +39761,7 @@ ${END_MARKER}
 }
 async function readCompletionSetup(args) {
   const shell = detectShell(args.shell);
-  const rcPath = resolve14(args.rcPath ?? defaultRcPath(shell));
+  const rcPath = resolve15(args.rcPath ?? defaultRcPath(shell));
   const line = completionsSourceLine(shell, args.executable ?? "idk");
   const exists = await fileExists(rcPath);
   if (!exists) {
@@ -39478,7 +39772,7 @@ async function readCompletionSetup(args) {
   return { shell, rcPath, installed, line };
 }
 function commonDir(paths) {
-  const parts = paths.map((value) => dirname9(resolve14(value)).split("/").filter(Boolean));
+  const parts = paths.map((value) => dirname9(resolve15(value)).split("/").filter(Boolean));
   if (parts.length === 0)
     return process.cwd();
   const first = parts[0] ?? [];
@@ -39499,13 +39793,13 @@ async function writePluginTrust(args) {
   if (args.plugins.length === 0) {
     throw usageError("setup plugin-trust requires at least one --plugin path.");
   }
-  const outPath = resolve14(args.outPath);
+  const outPath = resolve15(args.outPath);
   if (await fileExists(outPath) && !args.force) {
     throw usageError(`Output file already exists: ${outPath}`, "Pass --force true to overwrite.");
   }
   const entries = {};
   for (const plugin of args.plugins) {
-    const path = resolve14(plugin);
+    const path = resolve15(plugin);
     const digest = sha256Hex(await readTextFile(path));
     const key = args.relative === false ? path : relative3(dirname9(outPath), path);
     entries[key] = digest;
@@ -39517,18 +39811,18 @@ async function writePluginTrust(args) {
 `);
   return {
     outPath,
-    plugins: args.plugins.map((plugin) => resolve14(plugin)),
+    plugins: args.plugins.map((plugin) => resolve15(plugin)),
     pluginCount: args.plugins.length,
     pluginEntries: entries,
-    pluginRootSuggestion: commonDir(args.plugins.map((plugin) => resolve14(plugin))),
+    pluginRootSuggestion: commonDir(args.plugins.map((plugin) => resolve15(plugin))),
     updated: true
   };
 }
 function parsePluginList(input) {
-  return input.split(",").map((value) => value.trim()).filter(Boolean).map((value) => resolve14(value));
+  return input.split(",").map((value) => value.trim()).filter(Boolean).map((value) => resolve15(value));
 }
 function suggestedTrustPath(baseDir = process.cwd()) {
-  return resolve14(baseDir, ".idk/plugin-trust.json");
+  return resolve15(baseDir, ".idk/plugin-trust.json");
 }
 function describePluginTrustFlags(result) {
   return [
@@ -39540,7 +39834,7 @@ function describePluginTrustFlags(result) {
 }
 function inferredTuneWizardPath(scenarioPath) {
   const file = basename4(scenarioPath).replace(/\.json$/i, "");
-  return resolve14(process.cwd(), `${file}-tune.json`);
+  return resolve15(process.cwd(), `${file}-tune.json`);
 }
 
 // src/commands/doctor.ts
@@ -39912,7 +40206,7 @@ var eta_default = defineCommand({
 // src/commands/experiment.ts
 init_dist2();
 init_zod();
-import { resolve as resolve15 } from "path";
+import { resolve as resolve16 } from "path";
 init_errors3();
 init_outputMeta();
 init_bun();
@@ -39942,7 +40236,7 @@ var experiment_default = defineCommand({
     const spec = checked.data;
     if (spec.scenario.ref.length === 0)
       throw usageError("Usage: idk experiment <spec>");
-    const scenarioPath = resolve15(spec.scenario.ref);
+    const scenarioPath = resolve16(spec.scenario.ref);
     const scenario = await readScenarioFile(scenarioPath);
     const loaded = await loadRegistriesFromFlags(flags);
     const valid = validateScenarioV1(scenario, loaded.modelRegistry);
@@ -39991,12 +40285,12 @@ var experiment_default = defineCommand({
 // src/commands/evaluate.ts
 init_dist2();
 init_zod();
-import { resolve as resolve17 } from "path";
+import { resolve as resolve18 } from "path";
 
 // src/commands/ltv.ts
 init_dist2();
 init_zod();
-import { resolve as resolve16 } from "path";
+import { resolve as resolve17 } from "path";
 init_errors3();
 init_outputMeta();
 var strategySchema2 = string2().min(1).optional();
@@ -40365,7 +40659,7 @@ var ltv_default = defineCommand({
     };
     const output = flags.format === "json" ? jsonOutput : analysis.horizons;
     if (flags["artifact-out"]) {
-      const scenarioAbs = resolve16(process.cwd(), scenarioPath);
+      const scenarioAbs = resolve17(process.cwd(), scenarioPath);
       await writeCommandReplayArtifact({
         outPath: flags["artifact-out"],
         command: "ltv",
@@ -40444,7 +40738,7 @@ async function loadBalanceChecks(flags) {
   if (!failOn) {
     throw usageError("--fail-on must list error, warn, inconclusive, or unsupported");
   }
-  const path = resolve17(process.cwd(), flags.checks);
+  const path = resolve18(process.cwd(), flags.checks);
   let raw;
   try {
     raw = await readJsonFile(path);
@@ -40525,7 +40819,7 @@ var evaluate_default = defineCommand({
       throw scenarioInvalidError(valid.issues);
     }
     const scenario = valid.scenario;
-    const scenarioAbs = resolve17(process.cwd(), scenarioPath);
+    const scenarioAbs = resolve18(process.cwd(), scenarioPath);
     const unseeded = prepareResolvedRun({
       scenario: valid.scenario,
       modelRegistry: loaded.modelRegistry,
@@ -40702,9 +40996,9 @@ var evaluate_default = defineCommand({
       stageScope
     });
     const files = {
-      simulate: resolve17(process.cwd(), flags["out-dir"] ?? ".", "simulate.json"),
-      experience: resolve17(process.cwd(), flags["out-dir"] ?? ".", "experience.json"),
-      ltv: resolve17(process.cwd(), flags["out-dir"] ?? ".", "ltv.json")
+      simulate: resolve18(process.cwd(), flags["out-dir"] ?? ".", "simulate.json"),
+      experience: resolve18(process.cwd(), flags["out-dir"] ?? ".", "experience.json"),
+      ltv: resolve18(process.cwd(), flags["out-dir"] ?? ".", "ltv.json")
     };
     const output = {
       ok: balance?.exitCode !== 2,
@@ -40735,12 +41029,12 @@ var evaluate_default = defineCommand({
       ...balance ? { balanceChecks: balance.exitCode === 2 ? toBalanceCheckError(balance) : balance } : {}
     };
     if (flags["out-dir"]) {
-      const outDir = resolve17(process.cwd(), flags["out-dir"]);
+      const outDir = resolve18(process.cwd(), flags["out-dir"]);
       await ensureDir(outDir);
-      files.simulate = resolve17(outDir, "simulate.json");
-      files.experience = resolve17(outDir, "experience.json");
-      files.ltv = resolve17(outDir, "ltv.json");
-      const summaryPath = resolve17(process.cwd(), flags["out-dir"], flags.format === "md" ? "summary.md" : "summary.json");
+      files.simulate = resolve18(outDir, "simulate.json");
+      files.experience = resolve18(outDir, "experience.json");
+      files.ltv = resolve18(outDir, "ltv.json");
+      const summaryPath = resolve18(process.cwd(), flags["out-dir"], flags.format === "md" ? "summary.md" : "summary.json");
       files.summary = summaryPath;
       await writeTextFile(files.simulate, `${JSON.stringify({ ...simulate, _meta: simulateMeta }, null, 2)}
 `);
@@ -41170,7 +41464,7 @@ var report_default = defineCommand({
 // src/commands/simulate.ts
 init_dist2();
 init_zod();
-import { resolve as resolve18 } from "path";
+import { resolve as resolve19 } from "path";
 
 // src/commands/_shared/simulateView.ts
 function resolveEventLog(args) {
@@ -41324,11 +41618,11 @@ var simulate_default = defineCommand({
     const input = await readScenarioFile(scenarioPath);
     const loaded = await loadRegistriesFromFlags(flags);
     const scenario = assertValidScenario2(validateScenarioV1(input, loaded.modelRegistry));
-    const resumedJson = flags.resume ? await readJsonFile(resolve18(process.cwd(), flags.resume)).then((raw) => {
+    const resumedJson = flags.resume ? await readJsonFile(resolve19(process.cwd(), flags.resume)).then((raw) => {
       try {
         return parseSimStateJSON(raw);
       } catch (error) {
-        throw cliError("SIM_STATE_INVALID_JSON", `Invalid resume state json: ${resolve18(process.cwd(), flags.resume)}`, {
+        throw cliError("SIM_STATE_INVALID_JSON", `Invalid resume state json: ${resolve19(process.cwd(), flags.resume)}`, {
           detail: errorDetail(error),
           cause: error
         });
@@ -41336,7 +41630,7 @@ var simulate_default = defineCommand({
     }).catch((error) => {
       if (error instanceof Error && error.name === "CliError")
         throw error;
-      throw cliError("SIM_STATE_INVALID_JSON", `Invalid resume state json: ${resolve18(process.cwd(), flags.resume)}`, {
+      throw cliError("SIM_STATE_INVALID_JSON", `Invalid resume state json: ${resolve19(process.cwd(), flags.resume)}`, {
         detail: errorDetail(error),
         cause: error
       });
@@ -41453,7 +41747,7 @@ var simulate_default = defineCommand({
     const run = runScenario(effectiveScenario);
     const netWorth = effectiveScenario.model.netWorth?.(effectiveScenario.ctx, run.end) ?? run.end.wallet.money;
     const totalElapsedSec = priorElapsedSec + (offlineRun ? runElapsedSec(offlineRun) : 0) + runElapsedSec(run);
-    const stateOutPath = flags["state-out"] ? resolve18(process.cwd(), flags["state-out"]) : undefined;
+    const stateOutPath = flags["state-out"] ? resolve19(process.cwd(), flags["state-out"]) : undefined;
     const seed = deterministicSeed;
     const offlineEndWorth = offlineRun && (runScenarioInput.model.netWorth?.(runScenarioInput.ctx, offlineRun.end) ?? offlineRun.end.wallet.money);
     if (stateOutPath) {
@@ -41517,7 +41811,7 @@ var simulate_default = defineCommand({
       eventLog: run.eventLog
     };
     if (flags["artifact-out"]) {
-      const scenarioAbs = resolve18(process.cwd(), scenarioPath);
+      const scenarioAbs = resolve19(process.cwd(), scenarioPath);
       await writeCommandReplayArtifact({
         outPath: flags["artifact-out"],
         command: "simulate",
@@ -41552,7 +41846,7 @@ var simulate_default = defineCommand({
 // src/commands/tune.ts
 init_dist2();
 init_zod();
-import { resolve as resolve20 } from "path";
+import { resolve as resolve21 } from "path";
 init_errors3();
 init_outputMeta();
 
@@ -41560,7 +41854,7 @@ init_outputMeta();
 init_dist2();
 init_errors3();
 init_bun();
-import { basename as basename5, resolve as resolve19 } from "path";
+import { basename as basename5, resolve as resolve20 } from "path";
 var OBJECTIVE_OPTIONS = [
   {
     value: "endNetWorthLog10",
@@ -41634,7 +41928,7 @@ async function runTuneWizard(args) {
   }
   const scenario = valid.scenario;
   const strategyId = String(scenario.strategy?.id ?? "greedy");
-  const suggestedOut = resolve19(args.outPath?.trim() || inferredTuneWizardPath(args.scenarioPath));
+  const suggestedOut = resolve20(args.outPath?.trim() || inferredTuneWizardPath(args.scenarioPath));
   args.prompt.intro(`Tune wizard for ${basename5(args.scenarioPath)}`);
   const objectiveId = await args.prompt.select("Objective", {
     options: OBJECTIVE_OPTIONS.map((entry) => ({ ...entry })),
@@ -41651,7 +41945,7 @@ async function runTuneWizard(args) {
   const tunePathRaw = await args.prompt.text("Tune spec output path", {
     default: suggestedOut
   });
-  const tunePath = resolve19(String(tunePathRaw));
+  const tunePath = resolve20(String(tunePathRaw));
   if (await fileExists(tunePath) && !args.force) {
     throw usageError(`Output file already exists: ${tunePath}`, "Pass --force true to overwrite the generated tune spec.");
   }
@@ -41868,7 +42162,7 @@ var tune_default = defineCommand({
       throw usageError("Usage: idk tune <scenario> --tune <tunespec>");
     }
     const tuneSpecInput = wizardResult?.tuneSpec ?? await readScenarioFile(tunePath);
-    const baselinePath = flags["baseline-artifact"] ? resolve20(flags["baseline-artifact"]) : undefined;
+    const baselinePath = flags["baseline-artifact"] ? resolve21(flags["baseline-artifact"]) : undefined;
     const baselineRaw = baselinePath ? await readJsonFile(baselinePath) : undefined;
     const seed = flags.seed ?? deriveDeterministicSeed({
       command: "tune",
@@ -41932,8 +42226,8 @@ var tune_default = defineCommand({
       };
     })();
     if (flags["artifact-out"]) {
-      const scenarioAbs = resolve20(process.cwd(), scenarioPath);
-      const tuneAbs = resolve20(process.cwd(), tunePath);
+      const scenarioAbs = resolve21(process.cwd(), scenarioPath);
+      const tuneAbs = resolve21(process.cwd(), tunePath);
       await writeCommandReplayArtifact({
         outPath: flags["artifact-out"],
         command: "tune",
@@ -41999,13 +42293,13 @@ var validate_default = defineCommand({
 // src/commands/initScenario.ts
 init_zod();
 init_errors3();
-import { resolve as resolve22 } from "path";
+import { resolve as resolve23 } from "path";
 
 // src/lib/initWizard.ts
 init_errors3();
 
 // src/templates/scenario.ts
-import { resolve as resolve21, parse as parse5 } from "path";
+import { resolve as resolve22, parse as parse5 } from "path";
 var TEMPLATE_TRACKS = ["intro", "design", "personal"];
 var TEMPLATE_PRESETS = ["session", "builder", "longrun"];
 var INTRO_PRESET_DEFAULT = {
@@ -42873,14 +43167,14 @@ function buildInitTemplatePlan(args) {
     const tuneSpec = createPersonalTuneSpec(preset, baseScenario);
     applyPersonalBundleIdentity({ base: baseScenario, compare: compareScenario, tune: tuneSpec }, { stem, displayName });
     return [
-      { kind: "scenario", path: resolve21(dir, `${stem}${ext}`), content: baseScenario },
-      { kind: "compare", path: resolve21(dir, `${stem}-compare-b${ext}`), content: compareScenario },
-      { kind: "tune", path: resolve21(dir, `${stem}-tune${ext}`), content: tuneSpec }
+      { kind: "scenario", path: resolve22(dir, `${stem}${ext}`), content: baseScenario },
+      { kind: "compare", path: resolve22(dir, `${stem}-compare-b${ext}`), content: compareScenario },
+      { kind: "tune", path: resolve22(dir, `${stem}-tune${ext}`), content: tuneSpec }
     ];
   }
   const content = track === "intro" ? clone2(preset === "session" ? introSession : preset === "builder" ? introBuilder : introLongrun) : createDesignScenario(preset);
   applyScenarioOverrides(content, args.overrides);
-  return [{ kind: "scenario", path: resolve21(args.outPath), content }];
+  return [{ kind: "scenario", path: resolve22(args.outPath), content }];
 }
 function serializeTemplate(template) {
   return `${JSON.stringify(template, null, 2)}
@@ -43137,7 +43431,7 @@ var initScenario_default = defineCommand({
     })
   },
   async handler({ flags, prompt, terminal, runtime }) {
-    const outPath = resolve22(process.cwd(), flags.out);
+    const outPath = resolve23(process.cwd(), flags.out);
     const wizard = flags.wizard;
     const wizardResult = wizard ? await runInitWizard({
       prompt,
@@ -43207,11 +43501,11 @@ var init_default = defineGroup({
 init_dist2();
 init_zod();
 init_outputMeta();
-import { resolve as resolve23 } from "path";
+import { resolve as resolve24 } from "path";
 init_bun();
 async function runKpiRegression(flags) {
-  const baselinePath = resolve23(flags.baseline);
-  const currentPath = resolve23(flags.current);
+  const baselinePath = resolve24(flags.baseline);
+  const currentPath = resolve24(flags.current);
   const baseline = await readJsonFile(baselinePath);
   const current = await readJsonFile(currentPath);
   const output = adaptKpiRegression({
@@ -43229,6 +43523,7 @@ async function runKpiRegression(flags) {
   await writeOutput({
     format: flags.format,
     outPath: flags.out,
+    protectedInputs: [baselinePath, currentPath],
     data: output,
     meta: buildOutputMeta({ command: "kpi.regress" })
   });
@@ -43282,7 +43577,7 @@ init_zod();
 // src/commands/_shared/listOutput.ts
 init_outputMeta();
 init_bun();
-import { resolve as resolve24 } from "path";
+import { resolve as resolve25 } from "path";
 async function writeListOutput(args) {
   const outputForRender = args.format === "json" ? {
     ...args.payload,
@@ -43293,7 +43588,7 @@ async function writeListOutput(args) {
     process.stdout.write(body);
     return;
   }
-  const path = resolve24(args.out);
+  const path = resolve25(args.out);
   await writeTextFile(path, body);
   console.log(`Wrote ${args.format} output to ${path}`);
 }
@@ -43442,7 +43737,7 @@ var objectives_default2 = defineGroup({
 init_zod();
 init_errors3();
 init_outputMeta();
-import { resolve as resolve25 } from "path";
+import { resolve as resolve26 } from "path";
 init_bun();
 init_selfCli();
 function deepEqual(a, b) {
@@ -43509,7 +43804,7 @@ var replayVerify_default = defineCommand({
     if (!artifactPath) {
       throw usageError("Usage: idk replay verify <artifact.json>");
     }
-    const artifactAbs = resolve25(process.cwd(), artifactPath);
+    const artifactAbs = resolve26(process.cwd(), artifactPath);
     const raw = await readJsonFile(artifactAbs).catch((error) => {
       if (error instanceof Error && error.name === "CliError")
         throw error;
@@ -43810,4 +44105,4 @@ export {
   cli2 as cli
 };
 
-//# debugId=4657B842FAC22F1D64756E2164756E21
+//# debugId=4AAADDD1336AF66164756E2164756E21