@idlekit/cli 0.4.0 → 0.5.1

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;
@@ -19440,6 +19440,363 @@ function compareScenarios(args) {
   };
 }
 
+// ../core/dist/ltv/projection.js
+function clamp012(v) {
+  if (v < 0)
+    return 0;
+  if (v > 1)
+    return 1;
+  return v;
+}
+function deriveMonetizationConfig(scenario) {
+  const m = scenario.monetization;
+  const q = (m?.uncertainty?.quantiles ?? [0.5, 0.9]).filter((x) => typeof x === "number");
+  const quantiles = q.length > 0 ? [...new Set(q)].sort((a, b) => a - b) : [0.5, 0.9];
+  return {
+    cohorts: {
+      baseUsers: m?.cohorts?.baseUsers ?? 1
+    },
+    retention: {
+      d1: m?.retention?.d1 ?? 0.42,
+      d7: m?.retention?.d7 ?? 0.2,
+      d30: m?.retention?.d30 ?? 0.09,
+      d90: m?.retention?.d90 ?? 0.04,
+      longTailDailyDecay: m?.retention?.longTailDailyDecay ?? 0.02
+    },
+    revenue: {
+      payerConversion: m?.revenue?.payerConversion ?? 0.03,
+      arppuDaily: m?.revenue?.arppuDaily ?? 0.7,
+      adArpDau: m?.revenue?.adArpDau ?? 0.02,
+      platformFeeRate: m?.revenue?.platformFeeRate ?? 0.3,
+      grossMarginRate: m?.revenue?.grossMarginRate ?? 0.92,
+      progressionRevenueLift: m?.revenue?.progressionRevenueLift ?? 0.4,
+      progressionLogSpan: m?.revenue?.progressionLogSpan ?? 6
+    },
+    acquisition: {
+      cpi: m?.acquisition?.cpi ?? 0
+    },
+    uncertainty: {
+      enabled: m?.uncertainty?.enabled ?? false,
+      draws: m?.uncertainty?.draws ?? 300,
+      quantiles,
+      seed: m?.uncertainty?.seed,
+      sigma: {
+        retention: m?.uncertainty?.sigma?.retention ?? 0.08,
+        conversion: m?.uncertainty?.sigma?.conversion ?? 0.12,
+        arppu: m?.uncertainty?.sigma?.arppu ?? 0.2,
+        ad: m?.uncertainty?.sigma?.ad ?? 0.15
+      },
+      correlation: {
+        retentionConversion: m?.uncertainty?.correlation?.retentionConversion ?? 0,
+        retentionArppu: m?.uncertainty?.correlation?.retentionArppu ?? 0,
+        retentionAd: m?.uncertainty?.correlation?.retentionAd ?? 0,
+        conversionArppu: m?.uncertainty?.correlation?.conversionArppu ?? 0,
+        conversionAd: m?.uncertainty?.correlation?.conversionAd ?? 0,
+        arppuAd: m?.uncertainty?.correlation?.arppuAd ?? 0
+      }
+    }
+  };
+}
+function retentionAtDay(ret, day) {
+  if (day <= 0)
+    return 1;
+  if (day <= 1)
+    return ret.d1;
+  if (day <= 7)
+    return ret.d1 + (ret.d7 - ret.d1) * (day - 1) / 6;
+  if (day <= 30)
+    return ret.d7 + (ret.d30 - ret.d7) * (day - 7) / 23;
+  if (day <= 90)
+    return ret.d30 + (ret.d90 - ret.d30) * (day - 30) / 60;
+  const extra = day - 90;
+  return clamp012(ret.d90 * Math.exp(-ret.longTailDailyDecay * extra));
+}
+function progressionFactor(startWorthLog10, endWorthLog10, span) {
+  if (!Number.isFinite(startWorthLog10) || !Number.isFinite(endWorthLog10) || !Number.isFinite(span) || span <= 0) {
+    return 0;
+  }
+  return clamp012((endWorthLog10 - startWorthLog10) / span);
+}
+function estimateLtvPerUser(args) {
+  const { config, horizonDays } = args;
+  const progression = clamp012(args.progression);
+  const arppuDaily = config.revenue.arppuDaily * (1 + progression * config.revenue.progressionRevenueLift);
+  const adArpDau = config.revenue.adArpDau * (1 + progression * config.revenue.progressionRevenueLift * 0.5);
+  const payerConversion = config.revenue.payerConversion;
+  const fullDays = Math.floor(Math.max(0, horizonDays));
+  const remainder = Math.max(0, horizonDays - fullDays);
+  let gross = 0;
+  for (let day = 1;day <= fullDays; day++) {
+    const active = retentionAtDay(config.retention, day);
+    gross += active * (payerConversion * arppuDaily + adArpDau);
+  }
+  if (remainder > 0) {
+    const active = retentionAtDay(config.retention, fullDays + 1);
+    gross += remainder * active * (payerConversion * arppuDaily + adArpDau);
+  }
+  const net = gross * (1 - config.revenue.platformFeeRate) * config.revenue.grossMarginRate;
+  const ltv = net - config.acquisition.cpi;
+  return {
+    cumulativeGrossRevenuePerUser: gross,
+    cumulativeNetRevenuePerUser: net,
+    cumulativeLtvPerUser: ltv
+  };
+}
+
+// ../core/dist/ltv/uncertainty.js
+function clamp013(v) {
+  if (v < 0)
+    return 0;
+  if (v > 1)
+    return 1;
+  return v;
+}
+function clampCorrelation(v) {
+  if (!Number.isFinite(v))
+    return 0;
+  if (v < -1)
+    return -1;
+  if (v > 1)
+    return 1;
+  return v;
+}
+function randNormal(rng) {
+  const u1 = Math.max(0.000000000001, rng());
+  const u2 = Math.max(0.000000000001, rng());
+  return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+}
+function buildCorrelationMatrix(base) {
+  const rc = clampCorrelation(base.retentionConversion);
+  const ra = clampCorrelation(base.retentionArppu);
+  const rd = clampCorrelation(base.retentionAd);
+  const ca = clampCorrelation(base.conversionArppu);
+  const cd = clampCorrelation(base.conversionAd);
+  const ad = clampCorrelation(base.arppuAd);
+  return [
+    [1, rc, ra, rd],
+    [rc, 1, ca, cd],
+    [ra, ca, 1, ad],
+    [rd, cd, ad, 1]
+  ];
+}
+function withOffDiagonalScale(matrix, alpha) {
+  return matrix.map((row, i) => row.map((v, j) => {
+    if (i === j)
+      return 1;
+    return v * alpha;
+  }));
+}
+function cholesky4(matrix) {
+  const n = 4;
+  const l = Array.from({ length: n }, () => Array.from({ length: n }, () => 0));
+  for (let i = 0;i < n; i++) {
+    for (let j = 0;j <= i; j++) {
+      let sum = 0;
+      for (let k = 0;k < j; k++) {
+        sum += (l[i]?.[k] ?? 0) * (l[j]?.[k] ?? 0);
+      }
+      if (i === j) {
+        const val = (matrix[i]?.[i] ?? 0) - sum;
+        if (val <= 0.000000001)
+          return null;
+        l[i][j] = Math.sqrt(val);
+      } else {
+        const denom = l[j]?.[j] ?? 0;
+        if (Math.abs(denom) < 0.000000001)
+          return null;
+        l[i][j] = ((matrix[i]?.[j] ?? 0) - sum) / denom;
+      }
+    }
+  }
+  return l;
+}
+function multiplyLowerTriangular(l, z) {
+  const out = [0, 0, 0, 0];
+  for (let i = 0;i < 4; i++) {
+    let sum = 0;
+    for (let j = 0;j <= i; j++) {
+      sum += (l[i]?.[j] ?? 0) * (z[j] ?? 0);
+    }
+    out[i] = sum;
+  }
+  return out;
+}
+function sampleCorrelatedNormals(rng, corr) {
+  const z = [randNormal(rng), randNormal(rng), randNormal(rng), randNormal(rng)];
+  const matrix = buildCorrelationMatrix(corr);
+  let l = cholesky4(matrix);
+  let alpha = 0.99;
+  while (!l && alpha > 0.000001) {
+    l = cholesky4(withOffDiagonalScale(matrix, alpha));
+    alpha *= 0.8;
+  }
+  if (!l) {
+    return {
+      retention: z[0] ?? 0,
+      conversion: z[1] ?? 0,
+      arppu: z[2] ?? 0,
+      ad: z[3] ?? 0
+    };
+  }
+  const c = multiplyLowerTriangular(l, z);
+  return {
+    retention: c[0] ?? 0,
+    conversion: c[1] ?? 0,
+    arppu: c[2] ?? 0,
+    ad: c[3] ?? 0
+  };
+}
+function applyLogNormalShock(mean, sigma, z) {
+  if (sigma <= 0)
+    return mean;
+  return mean * Math.exp(sigma * z - 0.5 * sigma * sigma);
+}
+function makeUncertainConfig(base, rng) {
+  const shock = sampleCorrelatedNormals(rng, base.uncertainty.correlation);
+  const d1 = clamp013(applyLogNormalShock(base.retention.d1, base.uncertainty.sigma.retention, shock.retention));
+  const d7 = Math.min(d1, clamp013(applyLogNormalShock(base.retention.d7, base.uncertainty.sigma.retention, shock.retention)));
+  const d30 = Math.min(d7, clamp013(applyLogNormalShock(base.retention.d30, base.uncertainty.sigma.retention, shock.retention)));
+  const d90 = Math.min(d30, clamp013(applyLogNormalShock(base.retention.d90, base.uncertainty.sigma.retention, shock.retention)));
+  return {
+    ...base,
+    retention: {
+      ...base.retention,
+      d1,
+      d7,
+      d30,
+      d90
+    },
+    revenue: {
+      ...base.revenue,
+      payerConversion: clamp013(applyLogNormalShock(base.revenue.payerConversion, base.uncertainty.sigma.conversion, shock.conversion)),
+      arppuDaily: Math.max(0, applyLogNormalShock(base.revenue.arppuDaily, base.uncertainty.sigma.arppu, shock.arppu)),
+      adArpDau: Math.max(0, applyLogNormalShock(base.revenue.adArpDau, base.uncertainty.sigma.ad, shock.ad))
+    }
+  };
+}
+function quantileFromSorted(sorted, q) {
+  if (sorted.length === 0)
+    return 0;
+  const idx = Math.max(0, Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * q)));
+  return sorted[idx] ?? 0;
+}
+function estimateLtvDistribution(args) {
+  const rng = mulberry32(args.seed);
+  const grossSamples = [];
+  const netSamples = [];
+  const ltvSamples = [];
+  const draws = Math.max(1, args.draws);
+  for (let i = 0;i < draws; i++) {
+    const sampled = makeUncertainConfig(args.config, rng);
+    const point = estimateLtvPerUser({
+      config: sampled,
+      horizonDays: args.horizonDays,
+      progression: args.progression
+    });
+    grossSamples.push(point.cumulativeGrossRevenuePerUser);
+    netSamples.push(point.cumulativeNetRevenuePerUser);
+    ltvSamples.push(point.cumulativeLtvPerUser);
+  }
+  const avg = (arr) => arr.reduce((a, b) => a + b, 0) / Math.max(1, arr.length);
+  const sortedLtv = [...ltvSamples].sort((a, b) => a - b);
+  const byQuantile = {};
+  for (const q of args.quantiles) {
+    byQuantile[`q${Math.round(q * 100)}`] = quantileFromSorted(sortedLtv, q);
+  }
+  return {
+    mean: {
+      cumulativeGrossRevenuePerUser: avg(grossSamples),
+      cumulativeNetRevenuePerUser: avg(netSamples),
+      cumulativeLtvPerUser: avg(ltvSamples)
+    },
+    quantiles: byQuantile
+  };
+}
+var init_uncertainty = () => {};
+
+// ../core/dist/ltv/public.js
+function assertMonetization(monetization) {
+  const valid = validateScenarioV1({
+    schemaVersion: 1,
+    unit: { code: "LTV" },
+    policy: { mode: "drop" },
+    model: { id: "ltv-input", version: 1 },
+    initial: { wallet: { unit: "LTV", amount: "0" } },
+    clock: { stepSec: 1, durationSec: 1 },
+    monetization
+  });
+  if (!valid.ok)
+    throw new RangeError(valid.issues.map((issue) => issue.message).join("; "));
+}
+function assertQuantileValues(quantiles) {
+  if (quantiles.length === 0)
+    throw new RangeError("quantiles must be nonempty and in 0..1");
+  for (const q of quantiles) {
+    if (!Number.isFinite(q) || q < 0 || q > 1)
+      throw new RangeError("quantiles must be nonempty and in 0..1");
+  }
+}
+function assertConfig(config) {
+  const { retention, ...other } = config;
+  for (const day of ["d1", "d7", "d30", "d90"]) {
+    if (!Number.isFinite(retention[day]) || retention[day] < 0 || retention[day] > 1) {
+      throw new RangeError(`retention.${day} must be finite and in 0..1`);
+    }
+  }
+  if (!Number.isFinite(retention.longTailDailyDecay) || retention.longTailDailyDecay < 0) {
+    throw new RangeError("retention.longTailDailyDecay must be finite and >= 0");
+  }
+  const { quantiles, ...uncertainty } = other.uncertainty;
+  assertQuantileValues(quantiles);
+  assertMonetization({ ...other, uncertainty });
+}
+function deriveMonetizationConfig2(scenario) {
+  assertMonetization(scenario.monetization ?? {});
+  const config = deriveMonetizationConfig(scenario);
+  assertConfig(config);
+  return config;
+}
+function assertPoint(args) {
+  assertConfig(args.config);
+  if (!Number.isFinite(args.horizonDays) || args.horizonDays < 0 || args.horizonDays > 36500) {
+    throw new RangeError("horizonDays must be finite and in 0..36500");
+  }
+  if (!Number.isFinite(args.progression))
+    throw new RangeError("progression must be finite");
+}
+function finiteResult(result) {
+  if (!Object.values(result).every((value) => typeof value === "number" && Number.isFinite(value))) {
+    throw new RangeError("LTV calculation overflowed; reduce the input magnitudes");
+  }
+  return result;
+}
+function estimateLtvPerUser2(args) {
+  assertPoint(args);
+  return finiteResult(estimateLtvPerUser(args));
+}
+function estimateLtvDistribution2(args) {
+  assertPoint(args);
+  if (!Number.isSafeInteger(args.draws) || args.draws < 1 || args.draws > 1e5 || args.draws * Math.max(1, Math.ceil(args.horizonDays)) > 1e7) {
+    throw new RangeError("draws must be 1..100000 and draws \xD7 ceil(horizonDays) at most 10000000");
+  }
+  if (!Number.isFinite(args.seed))
+    throw new RangeError("seed must be finite");
+  if (args.quantiles.length > 101)
+    throw new RangeError("quantiles exceed the 101 distinct percent keys");
+  assertQuantileValues(args.quantiles);
+  if (new Set(args.quantiles.map((q) => Math.round(q * 100))).size !== args.quantiles.length) {
+    throw new RangeError("quantiles must be nonempty, in 0..1 and have distinct rounded percent keys");
+  }
+  const result = estimateLtvDistribution(args);
+  finiteResult(result.mean);
+  finiteResult(result.quantiles);
+  return result;
+}
+var init_public = __esm(() => {
+  init_validate();
+  init_uncertainty();
+});
+
 // ../core/dist/index.js
 var init_dist2 = __esm(() => {
   init_types();
@@ -19505,6 +19862,7 @@ var init_dist2 = __esm(() => {
   init_judge();
   init_flow();
   init_jevAdvisory();
+  init_public();
 });
 
 // src/runtime/bun.ts
@@ -19570,7 +19928,7 @@ var init_bun = __esm(() => {
 var require_package = __commonJS(function(exports, module) {
   module.exports = {
     name: "@idlekit/cli",
-    version: "0.4.0",
+    version: "0.5.1",
     description: "Bun-first idk CLI for idle game scenario validation, simulation, tuning, and reporting.",
     license: "MIT",
     type: "module",
@@ -19623,7 +19981,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.5.0",
       ajv: "^8.20.0",
       gunshi: "0.37.3",
       "proper-lockfile": "4.1.2",
@@ -35201,8 +35559,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 +35636,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,14 +36830,23 @@ init_outputMeta();
 import { extname as extname3, resolve as resolve8 } from "path";
 
 // src/lib/ltvCalibration.ts
-function clamp012(v) {
+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 clamp014(v) {
   if (v < 0)
     return 0;
   if (v > 1)
     return 1;
   return v;
 }
-function clampCorrelation(v) {
+function clampCorrelation2(v) {
   if (!Number.isFinite(v))
     return 0;
   if (v < -1)
@@ -36521,13 +36911,13 @@ function estimateCorrelation(x, y) {
       varianceY
     };
   }
-  const raw = clampCorrelation(cov / Math.sqrt(vx * vy));
+  const raw = clampCorrelation2(cov / Math.sqrt(vx) / Math.sqrt(vy));
   const ci95 = 1.96 / Math.sqrt(Math.max(1, n - 3));
-  const sampleConfidence = clamp012(1 - ci95);
+  const sampleConfidence = clamp014(1 - ci95);
   const varianceConfidenceX = varianceX / (varianceX + 0.01);
   const varianceConfidenceY = varianceY / (varianceY + 0.01);
   const varianceConfidence = Math.sqrt(varianceConfidenceX * varianceConfidenceY);
-  const confidence = clamp012(sampleConfidence * varianceConfidence);
+  const confidence = clamp014(sampleConfidence * varianceConfidence);
   const shrinkage = confidence;
   const value = raw * shrinkage;
   return {
@@ -36601,7 +36991,7 @@ function calibrateMonetization(rows) {
   const userAdArpDau = [];
   for (const user of users.values()) {
     const activeDays = Math.max(1, user.days.size);
-    const retentionScore = clamp012(activeDays / 30);
+    const retentionScore = clamp014(activeDays / 30);
     const conversionScore = user.iap > 0 ? 1 : 0;
     const arppuScore = user.iap > 0 ? user.iap / activeDays : 0;
     const adScore = user.ad / activeDays;
@@ -36642,20 +37032,20 @@ function calibrateMonetization(rows) {
     conversionAd: estimatedCorrelationPair.conversionAd.confidence,
     arppuAd: estimatedCorrelationPair.arppuAd.confidence
   };
-  return {
+  const result = {
     monetization: {
       cohorts: {
         baseUsers: cohortSize
       },
       retention: {
-        d1: clamp012(d1),
-        d7: clamp012(Math.min(d1, d7)),
-        d30: clamp012(Math.min(d7, d30)),
-        d90: clamp012(Math.min(d30, d90)),
+        d1: clamp014(d1),
+        d7: clamp014(Math.min(d1, d7)),
+        d30: clamp014(Math.min(d1, d7, d30)),
+        d90: clamp014(Math.min(d1, d7, d30, d90)),
         longTailDailyDecay: 0.02
       },
       revenue: {
-        payerConversion: clamp012(payerConversion),
+        payerConversion: clamp014(payerConversion),
         arppuDaily: Math.max(0, arppuDaily),
         adArpDau: Math.max(0, adArpDau),
         platformFeeRate: 0.3,
@@ -36710,288 +37100,142 @@ function calibrateMonetization(rows) {
       correlationDiagnostics: estimatedCorrelationPair
     }
   };
+  assertFiniteNumbers(result, "calibration");
+  return result;
 }
 // src/lib/ltvProjection.ts
-function clamp013(v) {
-  if (v < 0)
-    return 0;
-  if (v > 1)
-    return 1;
-  return v;
-}
-function deriveMonetizationConfig(scenario) {
-  const m = scenario.monetization;
-  const q = (m?.uncertainty?.quantiles ?? [0.5, 0.9]).filter((x) => typeof x === "number");
-  const quantiles = q.length > 0 ? [...new Set(q)].sort((a, b) => a - b) : [0.5, 0.9];
-  return {
-    cohorts: {
-      baseUsers: m?.cohorts?.baseUsers ?? 1
-    },
-    retention: {
-      d1: m?.retention?.d1 ?? 0.42,
-      d7: m?.retention?.d7 ?? 0.2,
-      d30: m?.retention?.d30 ?? 0.09,
-      d90: m?.retention?.d90 ?? 0.04,
-      longTailDailyDecay: m?.retention?.longTailDailyDecay ?? 0.02
-    },
-    revenue: {
-      payerConversion: m?.revenue?.payerConversion ?? 0.03,
-      arppuDaily: m?.revenue?.arppuDaily ?? 0.7,
-      adArpDau: m?.revenue?.adArpDau ?? 0.02,
-      platformFeeRate: m?.revenue?.platformFeeRate ?? 0.3,
-      grossMarginRate: m?.revenue?.grossMarginRate ?? 0.92,
-      progressionRevenueLift: m?.revenue?.progressionRevenueLift ?? 0.4,
-      progressionLogSpan: m?.revenue?.progressionLogSpan ?? 6
-    },
-    acquisition: {
-      cpi: m?.acquisition?.cpi ?? 0
-    },
-    uncertainty: {
-      enabled: m?.uncertainty?.enabled ?? false,
-      draws: m?.uncertainty?.draws ?? 300,
-      quantiles,
-      seed: m?.uncertainty?.seed,
-      sigma: {
-        retention: m?.uncertainty?.sigma?.retention ?? 0.08,
-        conversion: m?.uncertainty?.sigma?.conversion ?? 0.12,
-        arppu: m?.uncertainty?.sigma?.arppu ?? 0.2,
-        ad: m?.uncertainty?.sigma?.ad ?? 0.15
-      },
-      correlation: {
-        retentionConversion: m?.uncertainty?.correlation?.retentionConversion ?? 0,
-        retentionArppu: m?.uncertainty?.correlation?.retentionArppu ?? 0,
-        retentionAd: m?.uncertainty?.correlation?.retentionAd ?? 0,
-        conversionArppu: m?.uncertainty?.correlation?.conversionArppu ?? 0,
-        conversionAd: m?.uncertainty?.correlation?.conversionAd ?? 0,
-        arppuAd: m?.uncertainty?.correlation?.arppuAd ?? 0
-      }
-    }
-  };
-}
-function retentionAtDay(ret, day) {
-  if (day <= 0)
-    return 1;
-  if (day <= 1)
-    return ret.d1;
-  if (day <= 7)
-    return ret.d1 + (ret.d7 - ret.d1) * (day - 1) / 6;
-  if (day <= 30)
-    return ret.d7 + (ret.d30 - ret.d7) * (day - 7) / 23;
-  if (day <= 90)
-    return ret.d30 + (ret.d90 - ret.d30) * (day - 30) / 60;
-  const extra = day - 90;
-  return clamp013(ret.d90 * Math.exp(-ret.longTailDailyDecay * extra));
-}
-function progressionFactor(startWorthLog10, endWorthLog10, span) {
-  if (!Number.isFinite(startWorthLog10) || !Number.isFinite(endWorthLog10) || !Number.isFinite(span) || span <= 0) {
-    return 0;
-  }
-  return clamp013((endWorthLog10 - startWorthLog10) / span);
-}
-function estimateLtvPerUser(args) {
-  const { config, horizonDays } = args;
-  const progression = clamp013(args.progression);
-  const arppuDaily = config.revenue.arppuDaily * (1 + progression * config.revenue.progressionRevenueLift);
-  const adArpDau = config.revenue.adArpDau * (1 + progression * config.revenue.progressionRevenueLift * 0.5);
-  const payerConversion = config.revenue.payerConversion;
-  const fullDays = Math.floor(Math.max(0, horizonDays));
-  const remainder = Math.max(0, horizonDays - fullDays);
-  let gross = 0;
-  for (let day = 1;day <= fullDays; day++) {
-    const active = retentionAtDay(config.retention, day);
-    gross += active * (payerConversion * arppuDaily + adArpDau);
-  }
-  if (remainder > 0) {
-    const active = retentionAtDay(config.retention, fullDays + 1);
-    gross += remainder * active * (payerConversion * arppuDaily + adArpDau);
-  }
-  const net = gross * (1 - config.revenue.platformFeeRate) * config.revenue.grossMarginRate;
-  const ltv = net - config.acquisition.cpi;
-  return {
-    cumulativeGrossRevenuePerUser: gross,
-    cumulativeNetRevenuePerUser: net,
-    cumulativeLtvPerUser: ltv
-  };
-}
+init_dist2();
 // src/lib/ltvUncertainty.ts
-function clamp014(v) {
-  if (v < 0)
-    return 0;
-  if (v > 1)
-    return 1;
-  return v;
-}
-function clampCorrelation2(v) {
-  if (!Number.isFinite(v))
-    return 0;
-  if (v < -1)
-    return -1;
-  if (v > 1)
-    return 1;
-  return v;
-}
-function mulberry323(seed) {
-  let a = seed >>> 0;
-  return () => {
-    a |= 0;
-    a = a + 1831565813 | 0;
-    let t = Math.imul(a ^ a >>> 15, 1 | a);
-    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
-    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+init_dist2();
+// 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) } };
+    })
   };
-}
-function randNormal(rng) {
-  const u1 = Math.max(0.000000000001, rng());
-  const u2 = Math.max(0.000000000001, rng());
-  return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
-}
-function buildCorrelationMatrix(base) {
-  const rc = clampCorrelation2(base.retentionConversion);
-  const ra = clampCorrelation2(base.retentionArppu);
-  const rd = clampCorrelation2(base.retentionAd);
-  const ca = clampCorrelation2(base.conversionArppu);
-  const cd = clampCorrelation2(base.conversionAd);
-  const ad = clampCorrelation2(base.arppuAd);
-  return [
-    [1, rc, ra, rd],
-    [rc, 1, ca, cd],
-    [ra, ca, 1, ad],
-    [rd, cd, ad, 1]
-  ];
-}
-function withOffDiagonalScale(matrix, alpha) {
-  return matrix.map((row, i) => row.map((v, j) => {
-    if (i === j)
-      return 1;
-    return v * alpha;
-  }));
-}
-function cholesky4(matrix) {
-  const n = 4;
-  const l = Array.from({ length: n }, () => Array.from({ length: n }, () => 0));
-  for (let i = 0;i < n; i++) {
-    for (let j = 0;j <= i; j++) {
-      let sum = 0;
-      for (let k = 0;k < j; k++) {
-        sum += (l[i]?.[k] ?? 0) * (l[j]?.[k] ?? 0);
-      }
-      if (i === j) {
-        const val = (matrix[i]?.[i] ?? 0) - sum;
-        if (val <= 0.000000001)
-          return null;
-        l[i][j] = Math.sqrt(val);
-      } else {
-        const denom = l[j]?.[j] ?? 0;
-        if (Math.abs(denom) < 0.000000001)
-          return null;
-        l[i][j] = ((matrix[i]?.[j] ?? 0) - sum) / denom;
-      }
+  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;
     }
-  }
-  return l;
-}
-function multiplyLowerTriangular(l, z) {
-  const out = [0, 0, 0, 0];
-  for (let i = 0;i < 4; i++) {
-    let sum = 0;
-    for (let j = 0;j <= i; j++) {
-      sum += (l[i]?.[j] ?? 0) * (z[j] ?? 0);
+    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");
     }
-    out[i] = sum;
   }
-  return out;
 }
-function sampleCorrelatedNormals(rng, corr) {
-  const z = [randNormal(rng), randNormal(rng), randNormal(rng), randNormal(rng)];
-  const matrix = buildCorrelationMatrix(corr);
-  let l = cholesky4(matrix);
-  let alpha = 0.99;
-  while (!l && alpha > 0.000001) {
-    l = cholesky4(withOffDiagonalScale(matrix, alpha));
-    alpha *= 0.8;
+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.`);
   }
-  if (!l) {
-    return {
-      retention: z[0] ?? 0,
-      conversion: z[1] ?? 0,
-      arppu: z[2] ?? 0,
-      ad: z[3] ?? 0
-    };
+  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 };
   }
-  const c = multiplyLowerTriangular(l, z);
-  return {
-    retention: c[0] ?? 0,
-    conversion: c[1] ?? 0,
-    arppu: c[2] ?? 0,
-    ad: c[3] ?? 0
-  };
-}
-function applyLogNormalShock(mean, sigma, z) {
-  if (sigma <= 0)
-    return mean;
-  return mean * Math.exp(sigma * z - 0.5 * sigma * sigma);
-}
-function makeUncertainConfig(base, rng) {
-  const shock = sampleCorrelatedNormals(rng, base.uncertainty.correlation);
-  const d1 = clamp014(applyLogNormalShock(base.retention.d1, base.uncertainty.sigma.retention, shock.retention));
-  const d7 = Math.min(d1, clamp014(applyLogNormalShock(base.retention.d7, base.uncertainty.sigma.retention, shock.retention)));
-  const d30 = Math.min(d7, clamp014(applyLogNormalShock(base.retention.d30, base.uncertainty.sigma.retention, shock.retention)));
-  const d90 = Math.min(d30, clamp014(applyLogNormalShock(base.retention.d90, base.uncertainty.sigma.retention, shock.retention)));
-  return {
-    ...base,
-    retention: {
-      ...base.retention,
-      d1,
-      d7,
-      d30,
-      d90
-    },
-    revenue: {
-      ...base.revenue,
-      payerConversion: clamp014(applyLogNormalShock(base.revenue.payerConversion, base.uncertainty.sigma.conversion, shock.conversion)),
-      arppuDaily: Math.max(0, applyLogNormalShock(base.revenue.arppuDaily, base.uncertainty.sigma.arppu, shock.arppu)),
-      adArpDau: Math.max(0, applyLogNormalShock(base.revenue.adArpDau, base.uncertainty.sigma.ad, shock.ad))
-    }
-  };
+  return warnings.length ? { status: "requires-review", retention: {}, warnings } : { status: "ready", retention: rates, warnings };
 }
-function quantile2(values, q) {
-  if (values.length === 0)
-    return 0;
-  const sorted = [...values].sort((a, b) => a - b);
-  const idx = Math.max(0, Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * q)));
-  return sorted[idx] ?? 0;
+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 estimateLtvDistribution(args) {
-  const rng = mulberry323(args.seed);
-  const grossSamples = [];
-  const netSamples = [];
-  const ltvSamples = [];
-  const draws = Math.max(1, args.draws);
-  for (let i = 0;i < draws; i++) {
-    const sampled = makeUncertainConfig(args.config, rng);
-    const point = estimateLtvPerUser({
-      config: sampled,
-      horizonDays: args.horizonDays,
-      progression: args.progression
-    });
-    grossSamples.push(point.cumulativeGrossRevenuePerUser);
-    netSamples.push(point.cumulativeNetRevenuePerUser);
-    ltvSamples.push(point.cumulativeLtvPerUser);
-  }
-  const avg = (arr) => arr.reduce((a, b) => a + b, 0) / Math.max(1, arr.length);
-  const byQuantile = {};
-  for (const q of args.quantiles) {
-    byQuantile[`q${Math.round(q * 100)}`] = quantile2(ltvSamples, q);
+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} |`);
   }
-  return {
-    mean: {
-      cumulativeGrossRevenuePerUser: avg(grossSamples),
-      cumulativeNetRevenuePerUser: avg(netSamples),
-      cumulativeLtvPerUser: avg(ltvSamples)
-    },
-    quantiles: byQuantile
-  };
+  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 +37308,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 +37356,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 +37368,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 +37379,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 +37415,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 +37481,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 +37523,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 +37775,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 +38149,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 +38176,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 +38213,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 +38273,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 +38362,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 +38374,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 +38474,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 +38670,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 +38718,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 +38738,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 +38765,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 +38836,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 +38912,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 +38987,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 +39015,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 +39694,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 +39733,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 +39759,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 +39798,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 +39842,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 +39853,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 +39874,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 +39892,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 +39915,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 +40287,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 +40317,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 +40366,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();
@@ -40035,7 +40410,7 @@ function parseHorizons(raw) {
 }
 var DEFAULT_LTV_HORIZONS = "30m,2h,24h,7d,30d,90d";
 function ltvUncertaintyDraws(scenario, draws) {
-  const uncertainty = deriveMonetizationConfig(scenario).uncertainty;
+  const uncertainty = deriveMonetizationConfig2(scenario).uncertainty;
   return uncertainty.enabled || draws !== undefined ? draws ?? uncertainty.draws : null;
 }
 function ltvStageInputs(scenario, horizons, draws) {
@@ -40097,7 +40472,7 @@ function runLtvAnalysis(args) {
   const horizons = parseHorizons(args.horizonsRaw);
   const stepSec = args.step ?? args.compiled.run.stepSec;
   const runFast = resolveFastMode(args.fast, args.compiled.run.fast);
-  const monetizationConfig = deriveMonetizationConfig(args.scenario);
+  const monetizationConfig = deriveMonetizationConfig2(args.scenario);
   const uncertainEnabled = monetizationConfig.uncertainty.enabled || args.draws !== undefined;
   const draws = args.draws ?? monetizationConfig.uncertainty.draws;
   let state = args.compiled.initial;
@@ -40157,12 +40532,12 @@ function runLtvAnalysis(args) {
     const endWorthLog10 = args.compiled.ctx.E.absLog10(worth.amount);
     const progression = progressionFactor(startWorthLog10, endWorthLog10, monetizationConfig.revenue.progressionLogSpan);
     const horizonDays = h.seconds / 86400;
-    const point = estimateLtvPerUser({
+    const point = estimateLtvPerUser2({
       config: monetizationConfig,
       horizonDays,
       progression
     });
-    const distribution = uncertainEnabled && draws > 1 ? estimateLtvDistribution({
+    const distribution = uncertainEnabled && draws > 1 ? estimateLtvDistribution2({
       config: monetizationConfig,
       horizonDays,
       progression,
@@ -40365,7 +40740,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 +40819,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 +40900,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 +41077,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 +41110,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 +41545,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 +41699,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 +41711,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 +41828,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 +41892,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 +41927,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 +41935,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 +42009,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 +42026,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 +42243,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 +42307,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 +42374,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 +43248,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 +43512,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 +43582,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 +43604,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 +43658,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 +43669,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 +43818,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 +43885,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 +44186,4 @@ export {
   cli2 as cli
 };
 
-//# debugId=4657B842FAC22F1D64756E2164756E21
+//# debugId=A3CAAFDF1955C7F064756E2164756E21