@idlekit/cli 0.5.0 → 0.5.1

package/dist/runtime/workers/entry.js

@@ -19020,6 +19020,363 @@ 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/index.js
 var init_dist2 = __esm(() => {
   init_types();
@@ -19085,6 +19442,7 @@ var init_dist2 = __esm(() => {
   init_judge();
   init_flow();
   init_jevAdvisory();
+  init_public();
 });
 
 // src/errors.ts
@@ -19291,7 +19649,7 @@ var init_bun = __esm(() => {
 var require_package = __commonJS(function(exports, module) {
   module.exports = {
     name: "@idlekit/cli",
-    version: "0.5.0",
+    version: "0.5.1",
     description: "Bun-first idk CLI for idle game scenario validation, simulation, tuning, and reporting.",
     license: "MIT",
     type: "module",
@@ -19344,7 +19702,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.5.0",
       ajv: "^8.20.0",
       gunshi: "0.37.3",
       "proper-lockfile": "4.1.2",
@@ -21163,4 +21521,4 @@ export {
   workerEntryMarker
 };
 
-//# debugId=06867CE34AA5ED6764756E2164756E21
+//# debugId=36317EC36EA8D6E664756E2164756E21