@idlekit/cli 0.5.0 → 0.6.0

package/dist/runtime/workers/entry.js

@@ -11316,6 +11316,63 @@ function logicalDrawId(drawIndex) {
   return String(drawIndex);
 }
 
+// ../core/dist/sim/sessionOffline.js
+function validateCreditPolicy(policy) {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy) || "actions" in policy) {
+    throw new RangeError("prepareOffline policy must be a credit policy; set actions on scenario.run.offline");
+  }
+  if (policy.maxSec !== undefined && (typeof policy.maxSec !== "number" || !Number.isFinite(policy.maxSec) || policy.maxSec < 0)) {
+    throw new RangeError("prepareOffline policy.maxSec must be finite and nonnegative");
+  }
+  if (policy.overflowPolicy !== undefined && policy.overflowPolicy !== "clamp" && policy.overflowPolicy !== "reject") {
+    throw new RangeError("prepareOffline policy.overflowPolicy must be clamp or reject");
+  }
+  const decay = policy.decay;
+  if (decay !== undefined) {
+    if (!decay || typeof decay !== "object" || Array.isArray(decay) || decay.kind !== "none" && decay.kind !== "linear") {
+      throw new RangeError("prepareOffline policy.decay must select none or linear");
+    }
+    if (decay.floorRatio !== undefined && (typeof decay.floorRatio !== "number" || !Number.isFinite(decay.floorRatio) || decay.floorRatio < 0 || decay.floorRatio > 1)) {
+      throw new RangeError("prepareOffline policy.decay.floorRatio must be finite and in 0..1");
+    }
+  }
+}
+function prepareOfflineSegment(args) {
+  const { scenario, prepare } = args;
+  if (!prepare)
+    return { model: scenario.model, policy: scenario.run.offline, stepSec: scenario.run.stepSec };
+  const prepared = prepare({
+    ctx: scenario.ctx,
+    model: scenario.model,
+    state: deepClonePreservingPrototype(args.state),
+    seconds: args.seconds,
+    wallStartT: args.wallStartT,
+    wallEndT: args.wallEndT,
+    ...scenario.run.offline ? { policy: deepClonePreservingPrototype(scenario.run.offline) } : {}
+  });
+  if (!prepared || typeof prepared !== "object" || Array.isArray(prepared) || "then" in prepared) {
+    throw new RangeError("prepareOffline must synchronously return a preparation object");
+  }
+  if (prepared.stepSec !== undefined && (typeof prepared.stepSec !== "number" || !Number.isFinite(prepared.stepSec) || prepared.stepSec <= 0)) {
+    throw new RangeError("prepareOffline stepSec must be finite and positive");
+  }
+  if (prepared.policy !== undefined)
+    validateCreditPolicy(prepared.policy);
+  const model = prepared.model === undefined ? scenario.model : prepared.model;
+  if (!model || typeof model !== "object" || typeof model.income !== "function" || typeof model.actions !== "function") {
+    throw new RangeError("prepareOffline model must provide income and actions");
+  }
+  return {
+    model,
+    stepSec: prepared.stepSec ?? scenario.run.stepSec,
+    policy: prepared.policy === undefined ? scenario.run.offline : {
+      ...deepClonePreservingPrototype(prepared.policy),
+      actions: scenario.run.offline?.actions
+    }
+  };
+}
+var init_sessionOffline = () => {};
+
 // ../core/dist/sim/session.js
 function buildBlocks(pattern) {
   const blocks = [];
@@ -11411,6 +11468,9 @@ function withClocks(scenario, wallT, wallEndT, rewardT, activeT) {
   };
 }
 function simulateSessionPattern(args) {
+  if (args.prepareOffline !== undefined && typeof args.prepareOffline !== "function") {
+    throw new TypeError("prepareOffline must be a function");
+  }
   const sc = args.seed === undefined ? args.scenario : { ...args.scenario, ctx: { ...args.scenario.ctx, seed: args.seed } };
   const start = sc.initial;
   const horizonSec = args.pattern.days * 86400;
@@ -11497,7 +11557,19 @@ function simulateSessionPattern(args) {
       return;
     const requested = wallEnd - wallT;
     const wallStart = wallT;
-    const segment = segmentScenario(wallStart, wallEnd);
+    let segment = segmentScenario(wallStart, wallEnd);
+    const prepared = prepareOfflineSegment({
+      scenario: segment,
+      state,
+      seconds: requested,
+      wallStartT: wallStart,
+      wallEndT: wallEnd,
+      prepare: args.prepareOffline
+    });
+    if (prepared.model !== segment.model) {
+      const { clocks: _clocks, ...ctx } = segment.ctx;
+      segment = withClocks({ ...segment, ctx, model: prepared.model }, wallStart, wallEnd, state.t, activeSec);
+    }
     const offlineRun = applyOfflineSeconds({
       scenario: segment,
       seconds: requested,
@@ -11509,15 +11581,16 @@ function simulateSessionPattern(args) {
           enabled: sc.run.eventLog?.enabled ?? true,
           maxEvents: sc.run.eventLog?.maxEvents
         },
-        policy: sc.run.offline,
+        stepSec: prepared.stepSec,
+        policy: prepared.policy,
         ...stopFn ? { until: stopFn } : {}
       }
     });
     const credited = offlineRun.offline.simulatedSec;
     const reason = classify();
-    const absence = reason ? offlineAbsenceForCredit(credited, requested, sc.run.offline) : requested;
+    const absence = reason ? offlineAbsenceForCredit(credited, requested, prepared.policy) : requested;
     const gapEnd = wallStart + absence;
-    const effective = absence === requested ? offlineRun.offline.effectiveSec : resolveOfflineSeconds(absence, sc.run.offline).effectiveSec;
+    const effective = absence === requested ? offlineRun.offline.effectiveSec : resolveOfflineSeconds(absence, prepared.policy).effectiveSec;
     const lost = Math.max(0, absence - effective);
     offlineElapsedSec += absence;
     offlineCreditedSec += credited;
@@ -11688,6 +11761,7 @@ var init_session = __esm(() => {
   init_goalRead();
   init_observation();
   init_offline();
+  init_sessionOffline();
   init_simulator();
 });
 
@@ -12683,11 +12757,19 @@ var init_params2 = __esm(() => {
   }));
 });
 
-// ../core/dist/sim/strategy/opt/objectives/builtins.js
-function safeAbsLog10(E, x) {
-  const v = E.absLog10(x);
-  return Number.isFinite(v) ? v : -300;
+// ../core/dist/sim/strategy/opt/finiteAmountLog10.js
+function finiteAmountLog10(E, amount) {
+  if (!E.isFinite(amount))
+    throw new RangeError("Tuning requires finite monetary amounts in the selected engine");
+  const value = E.absLog10(amount);
+  if (value === Number.NEGATIVE_INFINITY)
+    return -300;
+  if (!Number.isFinite(value))
+    throw new RangeError("Tuning requires a finite monetary logarithm");
+  return value;
 }
+
+// ../core/dist/sim/strategy/opt/objectives/builtins.js
 var builtinObjectiveFactories;
 var init_builtins2 = __esm(() => {
   init_parseMoney2();
@@ -12701,7 +12783,7 @@ var init_builtins2 = __esm(() => {
         id: "endMoneyLog10",
         score: ({ scenario, run }) => {
           const { E } = scenario.ctx;
-          return safeAbsLog10(E, run.end.wallet.money.amount);
+          return finiteAmountLog10(E, run.end.wallet.money.amount);
         }
       })
     },
@@ -12714,7 +12796,7 @@ var init_builtins2 = __esm(() => {
         score: ({ scenario, run }) => {
           const { E } = scenario.ctx;
           const worth = scenario.model.netWorth?.(scenario.ctx, run.end) ?? run.end.wallet.money;
-          return safeAbsLog10(E, worth.amount);
+          return finiteAmountLog10(E, worth.amount);
         }
       })
     },
@@ -12729,7 +12811,7 @@ var init_builtins2 = __esm(() => {
           const sec = Math.max(1, runElapsedSec(run));
           const hours = sec / 3600;
           const worth = scenario.model.netWorth?.(scenario.ctx, run.end) ?? run.end.wallet.money;
-          return safeAbsLog10(E, worth.amount) - Math.log10(Math.max(0.000000000001, hours));
+          return finiteAmountLog10(E, worth.amount) - Math.log10(Math.max(0.000000000001, hours));
         }
       })
     },
@@ -12743,7 +12825,7 @@ var init_builtins2 = __esm(() => {
           const { E } = scenario.ctx;
           const sec = Math.max(1, runElapsedSec(run));
           const hours = sec / 3600;
-          return safeAbsLog10(E, run.end.prestige.points) - Math.log10(Math.max(0.000000000001, hours));
+          return finiteAmountLog10(E, run.end.prestige.points) - Math.log10(Math.max(0.000000000001, hours));
         }
       })
     },
@@ -12758,7 +12840,7 @@ var init_builtins2 = __esm(() => {
           const sec = Math.max(1, runElapsedSec(run));
           const startWorth = scenario.model.netWorth?.(scenario.ctx, run.start) ?? run.start.wallet.money;
           const endWorth = scenario.model.netWorth?.(scenario.ctx, run.end) ?? run.end.wallet.money;
-          const deltaLog = safeAbsLog10(E, endWorth.amount) - safeAbsLog10(E, startWorth.amount);
+          const deltaLog = finiteAmountLog10(E, endWorth.amount) - finiteAmountLog10(E, startWorth.amount);
           return deltaLog / (sec / 3600);
         }
       })
@@ -12784,6 +12866,9 @@ var init_builtins2 = __esm(() => {
               suffix: { kind: "alphaInfinite", minLen: 2 }
             }).amount;
             const endWorth = scenario.model.netWorth?.(scenario.ctx, run.end) ?? run.end.wallet.money;
+            if (!E.isFinite(threshold) || !E.isFinite(endWorth.amount)) {
+              throw new RangeError("ETA objective requires finite target and net worth in the selected engine");
+            }
             const reached = E.cmp(endWorth.amount, threshold) >= 0;
             if (!reached)
               return -(params.unreachedPenaltySec ?? 1e9);
@@ -12813,7 +12898,7 @@ var init_builtins2 = __esm(() => {
             const sec = Math.max(1, runElapsedSec(run));
             const hours = sec / 3600;
             const worth = scenario.model.netWorth?.(scenario.ctx, run.end) ?? run.end.wallet.money;
-            const worthLog = safeAbsLog10(E, worth.amount);
+            const worthLog = finiteAmountLog10(E, worth.amount);
             const stats = run.stats;
             if (!stats || stats.money.droppedRate === null || stats.actions.status === "missing") {
               throw new Error("pacingBalancedLog10 needs observed money and action counters, but this run has none (run.observation.enabled is false)");
@@ -13012,8 +13097,45 @@ function cloneCandidateInitial(state) {
 }
 var init_freshRun = () => {};
 
+// ../core/dist/sim/strategy/opt/finiteMean.js
+function finiteMean(values) {
+  if (values.length === 0)
+    throw new RangeError("A mean requires at least one value");
+  const bits = new DataView(new ArrayBuffer(8));
+  let total = 0n;
+  for (const value of values) {
+    if (!Number.isFinite(value))
+      throw new RangeError("A mean requires finite values");
+    bits.setFloat64(0, value, false);
+    const high = bits.getUint32(0, false);
+    const low = bits.getUint32(4, false);
+    const exponent = high >>> 20 & 2047;
+    const fraction = BigInt(high & 1048575) << 32n | BigInt(low);
+    const significand = exponent === 0 ? fraction : 1n << 52n | fraction;
+    const units = significand << BigInt(Math.max(0, exponent - 1));
+    total += high >>> 31 ? -units : units;
+  }
+  if (total === 0n)
+    return 0;
+  const negative = total < 0n;
+  const magnitude = negative ? -total : total;
+  const count = BigInt(values.length);
+  const integerMean = magnitude / count;
+  const shift = Math.max(0, integerMean.toString(2).length - 53);
+  const denominator = count << BigInt(shift);
+  let significand = magnitude / denominator;
+  const twiceRemainder = 2n * (magnitude % denominator);
+  if (twiceRemainder > denominator || twiceRemainder === denominator && (significand & 1n) !== 0n) {
+    significand++;
+  }
+  const mean = Number(significand) * 2 ** (shift - 1074);
+  return negative ? -mean : mean;
+}
+
 // ../core/dist/sim/strategy/opt/runner.js
 function runCandidateAndScore(args) {
+  if (args.seeds.length === 0)
+    throw new RangeError("Tuning requires at least one seed");
   const stratFactory = args.strategyRegistry.get(args.strategyId);
   if (!stratFactory)
     throw new Error(`Unknown strategy: ${args.strategyId}`);
@@ -13060,24 +13182,28 @@ function runCandidateAndScore(args) {
     const sc = openScenario();
     const run = runScenario(sc);
     assertHorizonReached(run, "runCandidateAndScore");
+    const worth = sc.model.netWorth?.(sc.ctx, run.end) ?? run.end.wallet.money;
+    const endMoneyLog10 = finiteAmountLog10(sc.ctx.E, run.end.wallet.money.amount);
+    const endNetWorthLog10 = finiteAmountLog10(sc.ctx.E, worth.amount);
     const s = objective.score({ scenario: sc, run, evaluation: {
       open: openScenario,
       registries: { models: args.modelRegistry, strategies: args.strategyRegistry },
       isolation: { model: args.model, statefulModel: args.statefulModel, strategy: { id: args.strategyId, params: candidateParams } }
     } });
+    if (!Number.isFinite(s))
+      throw new RangeError(`Objective ${args.objectiveId} must return a finite score (seed ${seed})`);
     seedScores.push(s);
-    const worth = sc.model.netWorth?.(sc.ctx, run.end) ?? run.end.wallet.money;
     seedResults.push({
       seed,
       score: s,
       durationSec: Math.max(0, runElapsedSec(run)),
-      endMoneyLog10: sc.ctx.E.absLog10(run.end.wallet.money.amount),
-      endNetWorthLog10: sc.ctx.E.absLog10(worth.amount),
+      endMoneyLog10,
+      endNetWorthLog10,
       droppedRate: run.stats?.money.droppedRate ?? null,
       actionsApplied: run.stats && run.stats.actions.status === "observed" ? run.stats.actions.applied : null
     });
   }
-  const score = seedScores.reduce((a, b) => a + b, 0) / Math.max(1, seedScores.length);
+  const score = finiteMean(seedScores);
   return { score, seedScores, seedResults };
 }
 var init_runner = __esm(() => {
@@ -14064,7 +14190,7 @@ function compensatedSum(values, scale) {
   }
   return sum + compensation;
 }
-function finiteMean(values) {
+function finiteMean2(values) {
   let smallest = Number.POSITIVE_INFINITY;
   let largest = Number.NEGATIVE_INFINITY;
   for (const value of values) {
@@ -14214,7 +14340,7 @@ function analyzeDistribution(request) {
   }
   const eligible = observed.length + rightCensored;
   const completionRate = eligible > 0 ? observed.length / eligible : null;
-  const arithmetic = observed.length > 0 ? finiteMean(observed) : null;
+  const arithmetic = observed.length > 0 ? finiteMean2(observed) : null;
   const identical = observed.every((value) => value === observed[0]);
   const rawVariance = arithmetic === null ? null : finiteVariance(observed, arithmetic);
   const variance = rawVariance === 0 && !identical ? null : rawVariance;
@@ -19020,6 +19146,508 @@ var init_jevAdvisory = __esm(() => {
   init__createStandardSchema();
 });
 
+// ../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/ltv/cohort.js
+function wilsonInterval(activeUsers, users) {
+  const rate = activeUsers / users;
+  const z2 = 1.959963984540054 ** 2;
+  const denominator = 1 + z2 / users;
+  const center = (rate + z2 / (2 * users)) / denominator;
+  const radius = Math.sqrt(z2 * (rate * (1 - rate) / users + z2 / (4 * users * users))) / denominator;
+  return { min: activeUsers === 0 ? 0 : Math.max(0, center - radius), max: activeUsers === users ? 1 : Math.min(1, center + radius) };
+}
+function observeCohort(rows, observedThroughDay) {
+  if (!Number.isSafeInteger(observedThroughDay) || observedThroughDay < 0)
+    throw new Error("observed-through-day must be a nonnegative safe integer");
+  if (!Array.isArray(rows) || 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 || typeof row.userId !== "string" || !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].every((v) => v === undefined || typeof v === "number" && 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;
+      return { day, status: "observed", users: n, activeUsers, rate, interval95: wilsonInterval(activeUsers, n) };
+    })
+  };
+  assertCohortObservation(observation);
+  return observation;
+}
+function object2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertCohortObservation(observation) {
+  if (!object2(observation) || typeof observation.users !== "number" || !Number.isSafeInteger(observation.users) || observation.users < 1 || typeof observation.observedThroughDay !== "number" || !Number.isSafeInteger(observation.observedThroughDay) || observation.observedThroughDay < 0) {
+    throw new Error("Invalid cohort population or observation cutoff");
+  }
+  if (!Array.isArray(observation.retention) || observation.retention.length !== RETENTION_DAYS.length)
+    throw new Error("Cohort retention must contain D1, D7, D30 and D90");
+  for (const [index, value] of observation.retention.entries()) {
+    const point = value;
+    if (!object2(point) || typeof point.day !== "number" || 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 (typeof point.activeUsers !== "number" || !Number.isSafeInteger(point.activeUsers) || point.activeUsers < 0 || point.activeUsers > observation.users || point.rate !== point.activeUsers / observation.users) {
+      throw new Error("Retained users and retention rate must match the installed population");
+    }
+    const interval = point.interval95;
+    if (typeof point.rate !== "number" || !object2(interval) || typeof interval.min !== "number" || typeof interval.max !== "number" || !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");
+    }
+    const expected = wilsonInterval(point.activeUsers, observation.users);
+    if (interval.min !== expected.min || interval.max !== expected.max) {
+      throw new Error("Retention confidence interval must match the Wilson 95% bounds for the observed population");
+    }
+  }
+}
+function observedRetentionRates(observation) {
+  assertCohortObservation(observation);
+  const rates = {};
+  for (const row of observation.retention) {
+    if (row.rate !== null)
+      rates[`d${row.day}`] = row.rate;
+  }
+  return rates;
+}
+function assertRetentionAssumptions(assumptions) {
+  if (!object2(assumptions))
+    throw new RangeError("Retention assumptions must be an object");
+  for (const day of RETENTION_DAYS) {
+    const rate = assumptions[`d${day}`];
+    if (rate !== undefined && (typeof rate !== "number" || !Number.isFinite(rate) || rate < 0 || rate > 1)) {
+      throw new RangeError(`Retention assumption d${day} must be finite and in 0..1`);
+    }
+  }
+}
+function planRetentionPatch(observation, assumptions = {}) {
+  assertRetentionAssumptions(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 monetization.retention.d${day} in the 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) {
+  assertCohortObservation(observation);
+  assertRetentionAssumptions(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"
+    };
+  });
+}
+var RETENTION_DAYS;
+var init_cohort = __esm(() => {
+  RETENTION_DAYS = Object.freeze([1, 7, 30, 90]);
+});
+
 // ../core/dist/index.js
 var init_dist2 = __esm(() => {
   init_types();
@@ -19085,6 +19713,8 @@ var init_dist2 = __esm(() => {
   init_judge();
   init_flow();
   init_jevAdvisory();
+  init_public();
+  init_cohort();
 });
 
 // src/errors.ts
@@ -19291,7 +19921,7 @@ var init_bun = __esm(() => {
 var require_package = __commonJS(function(exports, module) {
   module.exports = {
     name: "@idlekit/cli",
-    version: "0.5.0",
+    version: "0.6.0",
     description: "Bun-first idk CLI for idle game scenario validation, simulation, tuning, and reporting.",
     license: "MIT",
     type: "module",
@@ -19344,7 +19974,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.1",
+      "@idlekit/core": "0.6.0",
       ajv: "^8.20.0",
       gunshi: "0.37.3",
       "proper-lockfile": "4.1.2",
@@ -20208,8 +20838,8 @@ function ownedCount(state) {
 }
 function finiteLinearAmount(E, value, label) {
   if (!E.isFinite(value)) {
-    throw cliError("SCENARIO_INVALID", `linear ${label} exceeds the selected engine's finite range. Use --engine breakInfinity with simulate/evaluate/experience/ltv for a large economy, or reduce the inputs.`, {
-      hint: "Other commands, including report/compare/tune, use the number engine; reduce their inputs."
+    throw cliError("SCENARIO_INVALID", `linear ${label} exceeds the selected engine's finite range. Use --engine breakInfinity with simulate/evaluate/experience/ltv/compare/tune/balance for a large economy, or reduce the inputs.`, {
+      hint: "The report command uses the number engine; reduce its inputs."
     });
   }
   return value;
@@ -21163,4 +21793,4 @@ export {
   workerEntryMarker
 };
 
-//# debugId=06867CE34AA5ED6764756E2164756E21
+//# debugId=8F910D642493528C64756E2164756E21