@idlekit/cli 0.3.0 → 0.3.1

package/dist/main.js

@@ -147,7 +147,7 @@ var require_pad_end = __commonJS(function(exports, module) {
 var require_package = __commonJS(function(exports, module) {
   module.exports = {
     name: "@idlekit/cli",
-    version: "0.3.0",
+    version: "0.3.1",
     description: "Bun-first idk CLI for idle game scenario validation, simulation, tuning, and reporting.",
     license: "MIT",
     type: "module",
@@ -200,7 +200,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.3.0",
+      "@idlekit/core": "0.3.1",
       ajv: "^8.20.0",
       gunshi: "0.37.3",
       yaml: "^2.9.1",
@@ -19292,7 +19292,8 @@ function parseMoney(E, input, opts) {
     throw new Error(`Unknown suffix: ${suffixToken}`);
   }
   const exp3 = suffixIndex * 3;
-  const scaled = exp3 > 0 ? E.mulN(E.from(numeric), E.from(`1e${exp3}`)) : E.from(numeric);
+  const [mantissa, exponent = "0"] = numeric.split(/e/i);
+  const scaled = E.from(exp3 > 0 ? `${mantissa}e${BigInt(exponent) + BigInt(exp3)}` : numeric);
   const unit = opts.unit ?? (inlineUnit ? { code: inlineUnit } : undefined);
   if (!unit) {
     throw new Error("Unit is required. Provide opts.unit or unit in input string.");
@@ -21146,26 +21147,31 @@ function modelCreateParams(args) {
 function assertScenarioPlanInputs(args) {
   const startT = args.scenario.initial.t ?? 0;
   const durationSec = args.scenario.clock.durationSec;
-  for (const stepSec of args.stepSecs ?? [args.scenario.clock.stepSec]) {
+  const stepSecs = args.stepSecs ?? [args.scenario.clock.stepSec];
+  for (const stepSec of stepSecs) {
     assertSimulationClock("scenario clock", { stepSec, durationSec, startT });
-    const firstDt = durationSec !== undefined ? Math.min(stepSec, durationSec) : stepSec;
-    if (firstDt > 0 && !(startT + firstDt > startT)) {
-      throw new Error(`scenario clock tick did not advance state.t (start t: ${startT}, step: ${firstDt}); state.t is too large for stepSec ${stepSec}`);
-    }
   }
-  buildInitialState({
+  const unit = buildUnit({ scenario: args.scenario });
+  const initial = buildInitialState({
     E: args.E,
     scenario: args.scenario,
-    unit: buildUnit({ scenario: args.scenario }),
+    unit,
     allowSuffixNotation: args.allowSuffixNotation ?? true
   });
-  compileUntilExpr({
+  const until = compileUntilExpr({
     expr: args.scenario.clock.untilExpr,
     E: args.E,
-    unit: buildUnit({ scenario: args.scenario }),
+    unit,
     allowSuffixNotation: args.allowSuffixNotation ?? true,
     allowUnsafe: false
   });
+  const untilMet = until?.(initial) ?? false;
+  for (const stepSec of stepSecs) {
+    const first = nextBoundary({ elapsedSec: 0, steps: 0, stepSec, durationSec, untilMet, hasUntil: !!until });
+    if (first.kind === "step") {
+      assertTickAdvanced("scenario clock", startT, startT + first.dt, first.dt, stepSec, startT);
+    }
+  }
 }
 function buildUnit(args) {
   return args.unitFactory ? args.unitFactory(args.scenario.unit.code) : { code: args.scenario.unit.code, symbol: args.scenario.unit.symbol };
@@ -22137,13 +22143,16 @@ function resetSnapshot(ctx, state) {
     count: state.prestige.count
   };
 }
-function wallNow(ctx, t) {
+function wallNow(ctx, t, explicitWallT) {
   const clocks = ctx.clocks;
-  if (!clocks || typeof clocks.wallT !== "number" || !Number.isFinite(clocks.wallT))
-    return null;
-  const offset = Number.isFinite(clocks.rewardT) ? Math.max(0, t - clocks.rewardT) : 0;
-  const wall = clocks.wallT + offset;
-  return Number.isFinite(clocks.wallEndT) ? Math.min(wall, clocks.wallEndT) : wall;
+  let wall = explicitWallT;
+  if (wall === undefined) {
+    if (!clocks || typeof clocks.wallT !== "number" || !Number.isFinite(clocks.wallT))
+      return null;
+    const offset = Number.isFinite(clocks.rewardT) ? Math.max(0, t - clocks.rewardT) : 0;
+    wall = clocks.wallT + offset;
+  }
+  return clocks && Number.isFinite(clocks.wallEndT) ? Math.min(wall, clocks.wallEndT) : wall;
 }
 function applyDecisions(args) {
   const { ctx, model, constraints } = args;
@@ -22304,7 +22313,7 @@ function applyDecisions(args) {
         actionId: action.id,
         kind: action.kind,
         t: decisionT,
-        wallT: args.wallT ?? wallNow(ctx, decisionT),
+        wallT: wallNow(ctx, decisionT, args.wallT ?? undefined),
         cost: paid ? { unit: paid.unit.code, decimal: E.toString(paid.amount) } : null,
         rewardDelta: E.toString(E.sub(next.prestige.points, pointsBefore)),
         before,
@@ -28984,6 +28993,7 @@ function renderExperienceMarkdown(args) {
     `- Scenario: \`${args.scenarioPath}\``,
     `- Intent: ${args.intent ?? "unspecified"}`,
     `- Mode: ${args.mode}`,
+    ...args.mode === "monte-carlo" ? ["- Snapshot scope: one recorded session (end state, growth, milestones, and perceived progression)"] : [],
     `- Session pattern: \`${snapshot.session.pattern.id}\` for ${snapshot.session.pattern.days} day(s)`,
     `- Active blocks: ${snapshot.session.activeBlocks}${snapshot.session.budgetStops > 0 ? ` (${snapshot.session.budgetStops} cut short by maxSteps)` : ""}`,
     `- Active / offline: ${formatMetric(snapshot.session.totalActiveSec, 0)}s / ${formatMetric(snapshot.session.totalOfflineSec, 0)}s`,
@@ -29037,8 +29047,47 @@ function renderExperienceMarkdown(args) {
     ...snapshot.session.budgetStops > 0 ? ["- Active play was cut short by maxSteps; read these windows and progression rates with that time budget in mind."] : []
   ];
   if (monteCarlo) {
-    lines.push("", "## Monte Carlo", "", `- Draws: ${monteCarlo.draws}`, `- Seed: ${monteCarlo.seed}`, `- Net worth log10 mean: ${formatMetric(monteCarlo.endNetWorthLog10.mean, 3)}`, `- Visible changes / minute mean: ${formatMetric(monteCarlo.visibleChangesPerMinute.mean, 3)}`, `- No-reward gap mean: ${formatMetric(monteCarlo.maxNoRewardGapSec.mean, 2)}s`, `- First visible completion: ${monteCarlo.firstVisible.accounting.completionRate ?? "unavailable"}`, `- First visible population p95: ${monteCarlo.firstVisible.population.status === "observed" ? `${monteCarlo.firstVisible.population.value}s` : monteCarlo.firstVisible.population.status}`);
+    lines.push("", "## Monte Carlo", "", `- Draws: ${monteCarlo.draws}`, `- Seed: ${monteCarlo.seed}`, `- Net worth log10 mean: ${formatMetric(monteCarlo.endNetWorthLog10.mean, 3)}`, `- Visible changes / minute mean: ${formatMetric(monteCarlo.visibleChangesPerMinute.mean, 3)}`, `- No-reward gap mean: ${formatMetric(monteCarlo.maxNoRewardGapSec.mean, 2)}s`, `- First visible completion: ${monteCarlo.firstVisible.accounting.completionRate ?? "unavailable"}`, `- First visible observed / right-censored / failed / unsupported: ${monteCarlo.firstVisible.accounting.observed} / ${monteCarlo.firstVisible.accounting.rightCensored} / ${monteCarlo.firstVisible.accounting.failed} / ${monteCarlo.firstVisible.accounting.unsupported}`, `- First visible population p95: ${monteCarlo.firstVisible.population.status === "observed" ? `${monteCarlo.firstVisible.population.value}s` : monteCarlo.firstVisible.population.status}`);
+  }
+  const checks = [
+    "- Compare the same initial state, horizon, session pattern, and seed policy when attributing a change to a strategy."
+  ];
+  if (args.mode === "monte-carlo") {
+    checks.push("- The snapshot checks concern the recorded session. Use completion and population summaries when deciding about the draw population.");
+  }
+  if (snapshot.session.budgetStops > 0) {
+    checks.push("- Increase the step budget and rerun the same horizon and session pattern before treating cut active blocks as complete play.");
+  }
+  if (coverage !== "complete") {
+    checks.push("- Rerun with complete milestone observation before comparing exact milestone keys. Read any retained first-time summary separately from key coverage.");
+  }
+  if (snapshot.perceived.activeSeconds <= 0) {
+    checks.push("- Collect an active-play observation window before judging visible progress or purchase feedback.");
+  } else if (snapshot.perceived.visibleChangeCount === 0) {
+    checks.push("- No visible change was observed in the active window. Check the feedback rules and rerun a matched longer window before interpreting the pace.");
+  }
+  if (snapshot.session.lostRewardSec > 0) {
+    checks.push("- Compare matched offline runs with the cap or decay changed to measure the effect of lost reward credit.");
+  }
+  if (slowWindows.length > 0) {
+    checks.push("- Inspect actions and income around the sampled stall or softcap windows, then compare a matched counterfactual to test the suspected cause.");
+  }
+  if (firstPrestige !== undefined) {
+    checks.push("- Compare prestige with a matched run without that reset to estimate its net benefit.");
+  }
+  if (monteCarlo) {
+    checks.push("- Check first-visible completion and right-censored, failed, and unsupported counts before reading conditional timing statistics.");
+    if (monteCarlo.firstVisible.accounting.rightCensored > 0) {
+      checks.push(`- ${monteCarlo.firstVisible.accounting.rightCensored} draw(s) had no visible change through the last active observation on the reward-time clock. This can differ from the wall horizon. Extend matched active observation to investigate those censored observations.`);
+    }
+    if (monteCarlo.firstVisible.population.status !== "observed") {
+      checks.push("- The population p95 is unresolved. Conditional observed-change timings describe only the observations that completed.");
+    }
+    if (monteCarlo.firstVisible.accounting.failed > 0 || monteCarlo.firstVisible.accounting.unsupported > 0) {
+      checks.push("- Resolve failed or unsupported draws before relying on timing statistics for the full cohort.");
+    }
   }
+  lines.push("", "## Next checks", "", ...checks);
   return `${lines.join(`
 `)}
 `;
@@ -33077,6 +33126,21 @@ function renderCompareMarkdown(args) {
   if (args.results.some((result) => result.metric === "timeToMilestone")) {
     lines.push("- Time-to-milestone scores can include an unreached penalty beyond the session horizon; that penalty is not an observed milestone time.");
   }
+  lines.push("", "## Choosing between scenarios", "");
+  if (preferences.a.length && preferences.b.length) {
+    lines.push("- The selected metrics prefer different scenarios. Choose the metric that matches the design intent and inspect the opposing cost before deciding.");
+  } else if (preferences.a.length || preferences.b.length) {
+    const side = preferences.a.length ? "A" : "B";
+    lines.push(`- ${side} is preferred on the selected decisive metrics. Check unselected costs and benefits before choosing the full strategy.`);
+  } else if (args.results.length && args.results.every((result) => result.better === "tie")) {
+    lines.push("- All selected metrics tie. Use another intent-relevant measurement to distinguish the scenarios.");
+  } else {
+    lines.push("- Select intent-relevant metrics with available measurements and decisions before choosing a scenario.");
+  }
+  if (args.results.some((result) => result.better !== "a" && result.better !== "b" && result.better !== "tie")) {
+    lines.push("- Resolve undetermined measurements or decisions before relying on those metrics.");
+  }
+  lines.push("- For a strategy comparison, use matching horizons, initial states, session patterns, and seed policies to interpret the measured differences.");
   return `${lines.join(`
 `)}
 `;
@@ -38188,4 +38252,4 @@ export {
   cli2 as cli
 };
 
-//# debugId=1DCC70029C55193864756E2164756E21
+//# debugId=1FC7442F0ACD246C64756E2164756E21