@idlekit/core 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imjlk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @idlekit/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Simulation and analysis primitives for idle game economy design.
+It compiles scenarios, executes runs, and evaluates long-horizon KPIs and design-facing metrics.
+Official support in v1: Bun `>=1.4.2` only. Node.js and browser runtimes are not part of the v1 compatibility contract.
+
+```bash
+bun add @idlekit/core
+```
+
+Requires Bun `>=1.4.2`.
+
+Use this package when you need:
+
+- scenario validation / compilation
+- simulation loop and `stepOnce`
+- built-in strategies and tuning primitives
+- growth, milestone, session-pattern, and Monte Carlo analysis
+
+## Quick example
+
+<!-- snippet: snippets/readme/core-quick-example.ts -->
+```ts
+import {
+  analyzeGrowth,
+  compileScenario,
+  createModelRegistry,
+  createNumberEngine,
+  defineModelFactory,
+  runScenario,
+  validateScenarioV1,
+} from "@idlekit/core";
+
+type Vars = { owned: number };
+
+const linearFactory = defineModelFactory<number, "COIN", Vars>({
+  id: "linear",
+  version: 1,
+  create() {
+    return {
+      id: "linear",
+      version: 1,
+      income(ctx, state) {
+        return {
+          unit: ctx.unit,
+          amount: ctx.E.add(1, Number(state.vars.owned ?? 0)),
+        };
+      },
+      actions() {
+        return [];
+      },
+    };
+  },
+});
+
+const registry = createModelRegistry([linearFactory]);
+
+const scenario = {
+  schemaVersion: 1,
+  unit: { code: "COIN" },
+  policy: { mode: "drop" },
+  model: { id: "linear", version: 1 },
+  initial: {
+    wallet: { unit: "COIN", amount: "0" },
+    vars: { owned: 0 },
+  },
+  clock: { stepSec: 1, durationSec: 60 },
+};
+
+const validated = validateScenarioV1(scenario, registry);
+if (!validated.ok || !validated.scenario) {
+  throw new Error(`scenario should validate: ${JSON.stringify(validated.issues)}`);
+}
+
+const E = createNumberEngine();
+const compiled = compileScenario({
+  E,
+  scenario: validated.scenario,
+  registry,
+});
+const run = runScenario(compiled);
+const growth = analyzeGrowth({ run, series: "money", windowSec: 10 });
+
+console.log(
+  JSON.stringify({
+    endMoney: E.toString(run.end.wallet.money.amount),
+    growthSlopePerHourLog10: growth.slopePerHourLog10,
+  }),
+);
+```
+
+## Runtime
+
+For the duration of an in-memory `runScenario` or `applyOfflineSeconds` result, import `runElapsedSec` from `@idlekit/core` and read `runElapsedSec(run)`. It uses `run.stop.elapsedSec`, the sum of tick seconds. `state.t` is the absolute reward timestamp; at a large starting timestamp, `run.end.t - run.start.t` can round differently. For example, ten 0.1-second ticks starting at `1e15` simulate about one second while the timestamps differ by 1.25 seconds. Results without a stop record fall back to that timestamp difference. A step-budget stop can shorten an individual run before the requested duration; check `run.stop?.reason` or use `assertHorizonReached(run, label)` when the full horizon is required.
+
+For `simulateSessionPattern`, read `summary.elapsedSec` for wall time, `summary.activeSec` for active tick seconds, and `summary.offlineCreditedSec` for offline reward tick seconds. The aggregate `session.run` has no per-run stop record, so `runElapsedSec(session.run)` uses the timestamp fallback. `summary.rewardSec` is also a reward timestamp difference; use the active and offline credited totals when you need simulated tick seconds.
+
+`@idlekit/core` is maintained as a Bun-first ESM package.
+
+## Documentation
+
+- Repository: [github.com/imjlk/idlekit](https://github.com/imjlk/idlekit)
+- Product roadmap: [docs/roadmap.md](https://github.com/imjlk/idlekit/blob/main/docs/roadmap.md)
+- Scenario guide: [docs/scenario-and-tuning.md](https://github.com/imjlk/idlekit/blob/main/docs/scenario-and-tuning.md)
+- Canonical worked example: [examples/tutorials/14-orbital-foundry-v1.json](https://github.com/imjlk/idlekit/blob/main/examples/tutorials/14-orbital-foundry-v1.json)
+- Adapter pattern example: [examples/adapter-pattern](https://github.com/imjlk/idlekit/tree/main/examples/adapter-pattern)

package/dist/engine/breakEternity.d.ts

@@ -0,0 +1 @@
+export { BREAK_ETERNITY_EXPERIMENTAL_MESSAGE, breakEternityEngine, createBreakEternityEngine, } from "@idlekit/money";

package/dist/engine/breakEternity.js

@@ -0,0 +1,2 @@
+export { BREAK_ETERNITY_EXPERIMENTAL_MESSAGE, breakEternityEngine, createBreakEternityEngine, } from "@idlekit/money";
+//# sourceMappingURL=breakEternity.js.map

package/dist/engine/breakEternity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakEternity.js","sourceRoot":"","sources":["../../src/engine/breakEternity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mCAAmC,EACnC,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC"}

package/dist/engine/breakInfinity.d.ts

@@ -0,0 +1 @@
+export { Decimal, breakInfinityEngine, createBreakInfinityEngine, createNumberEngine, type BreakInfinityEngineOptions, type NumberEngineOptions, } from "@idlekit/money";

package/dist/engine/breakInfinity.js

@@ -0,0 +1,2 @@
+export { Decimal, breakInfinityEngine, createBreakInfinityEngine, createNumberEngine, } from "@idlekit/money";
+//# sourceMappingURL=breakInfinity.js.map

package/dist/engine/breakInfinity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakInfinity.js","sourceRoot":"","sources":["../../src/engine/breakInfinity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,mBAAmB,EACnB,yBAAyB,EACzB,kBAAkB,GAGnB,MAAM,gBAAgB,CAAC"}

package/dist/engine/types.d.ts

@@ -0,0 +1 @@
+export type { Engine } from "@idlekit/money";

package/dist/engine/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/engine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+export * from "./engine/types";
+export * from "./engine/breakInfinity";
+export * from "./engine/breakEternity";
+export * from "./money/types";
+export * from "./policy/types";
+export * from "./policy/emitter";
+export * from "./policy/tickMoney";
+export * from "./notation/suffixer";
+export * from "./notation/formatMoney";
+export * from "./notation/parseMoney";
+export * from "./notation/visibilityTracker";
+export * from "./serde/moneyState";
+export * from "./serde/simState";
+export * from "./scenario/types";
+export * from "./scenario/registry";
+export * from "./scenario/validate";
+export * from "./scenario/concreteValidator";
+export * from "./scenario/migrate";
+export * from "./scenario/compile";
+export * from "./sim/types";
+export * from "./sim/simulator";
+export * from "./sim/step";
+export * from "./sim/stepTypes";
+export * from "./sim/offline";
+export * from "./sim/random";
+export * from "./sim/session";
+export * from "./sim/monteCarlo";
+export * from "./sim/runFactory";
+export * from "./sim/constraints";
+export * from "./sim/observation";
+export * from "./sim/strategy/types";
+export * from "./sim/strategy/contracts";
+export * from "./sim/strategy/stability";
+export * from "./sim/strategy/scripted";
+export * from "./sim/strategy/greedy";
+export * from "./sim/strategy/planner";
+export * from "./sim/strategy/registry";
+export * from "./sim/strategy/params";
+export * from "./sim/strategy/builtins";
+export * from "./sim/strategy/opt/tuneSpec";
+export * from "./sim/strategy/opt/validate";
+export * from "./sim/strategy/opt/objective";
+export * from "./sim/strategy/opt/registry";
+export * from "./sim/strategy/opt/objectives/params";
+export * from "./sim/strategy/opt/objectives/builtins";
+export * from "./sim/strategy/opt/tuner";
+export * from "./sim/strategy/opt/tuners/randomSearch";
+export * from "./sim/strategy/opt/runner";
+export * from "./sim/analysis/eta";
+export * from "./sim/analysis/prestigeCycle";
+export * from "./sim/analysis/growth";
+export * from "./sim/analysis/milestones";
+export * from "./sim/analysis/ux";
+export * from "./report/timeline";
+export * from "./report/compare";
+export * from "./utils/deepClone";

package/dist/index.js

@@ -0,0 +1,57 @@
+export * from "./engine/types";
+export * from "./engine/breakInfinity";
+export * from "./engine/breakEternity";
+export * from "./money/types";
+export * from "./policy/types";
+export * from "./policy/emitter";
+export * from "./policy/tickMoney";
+export * from "./notation/suffixer";
+export * from "./notation/formatMoney";
+export * from "./notation/parseMoney";
+export * from "./notation/visibilityTracker";
+export * from "./serde/moneyState";
+export * from "./serde/simState";
+export * from "./scenario/types";
+export * from "./scenario/registry";
+export * from "./scenario/validate";
+export * from "./scenario/concreteValidator";
+export * from "./scenario/migrate";
+export * from "./scenario/compile";
+export * from "./sim/types";
+export * from "./sim/simulator";
+export * from "./sim/step";
+export * from "./sim/stepTypes";
+export * from "./sim/offline";
+export * from "./sim/random";
+export * from "./sim/session";
+export * from "./sim/monteCarlo";
+export * from "./sim/runFactory";
+export * from "./sim/constraints";
+export * from "./sim/observation";
+export * from "./sim/strategy/types";
+export * from "./sim/strategy/contracts";
+export * from "./sim/strategy/stability";
+export * from "./sim/strategy/scripted";
+export * from "./sim/strategy/greedy";
+export * from "./sim/strategy/planner";
+export * from "./sim/strategy/registry";
+export * from "./sim/strategy/params";
+export * from "./sim/strategy/builtins";
+export * from "./sim/strategy/opt/tuneSpec";
+export * from "./sim/strategy/opt/validate";
+export * from "./sim/strategy/opt/objective";
+export * from "./sim/strategy/opt/registry";
+export * from "./sim/strategy/opt/objectives/params";
+export * from "./sim/strategy/opt/objectives/builtins";
+export * from "./sim/strategy/opt/tuner";
+export * from "./sim/strategy/opt/tuners/randomSearch";
+export * from "./sim/strategy/opt/runner";
+export * from "./sim/analysis/eta";
+export * from "./sim/analysis/prestigeCycle";
+export * from "./sim/analysis/growth";
+export * from "./sim/analysis/milestones";
+export * from "./sim/analysis/ux";
+export * from "./report/timeline";
+export * from "./report/compare";
+export * from "./utils/deepClone";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,eAAe,CAAC;AAE9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAElC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sCAAsC,CAAC;AACrD,cAAc,wCAAwC,CAAC;AACvD,cAAc,0BAA0B,CAAC;AACzC,cAAc,wCAAwC,CAAC;AACvD,cAAc,2BAA2B,CAAC;AAE1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAElC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,mBAAmB,CAAC"}

package/dist/money/types.d.ts

@@ -0,0 +1 @@
+export type { Money, MoneyState, Unit } from "@idlekit/money";

package/dist/money/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/money/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/money/types.ts"],"names":[],"mappings":""}

package/dist/notation/formatMoney.d.ts

@@ -0,0 +1 @@
+export { formatMoney, type FormatMoneyOptions } from "@idlekit/money";

package/dist/notation/formatMoney.js

@@ -0,0 +1,2 @@
+export { formatMoney } from "@idlekit/money";
+//# sourceMappingURL=formatMoney.js.map

package/dist/notation/formatMoney.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatMoney.js","sourceRoot":"","sources":["../../src/notation/formatMoney.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA2B,MAAM,gBAAgB,CAAC"}

package/dist/notation/parseMoney.d.ts

@@ -0,0 +1 @@
+export { parseMoney, type ParseMoneyOptions } from "@idlekit/money";

package/dist/notation/parseMoney.js

@@ -0,0 +1,2 @@
+export { parseMoney } from "@idlekit/money";
+//# sourceMappingURL=parseMoney.js.map

package/dist/notation/parseMoney.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseMoney.js","sourceRoot":"","sources":["../../src/notation/parseMoney.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA0B,MAAM,gBAAgB,CAAC"}

package/dist/notation/suffixer.d.ts

@@ -0,0 +1 @@
+export { alphaInfiniteIndex, alphaInfiniteSuffix, type Suffixer } from "@idlekit/money";

package/dist/notation/suffixer.js

@@ -0,0 +1,2 @@
+export { alphaInfiniteIndex, alphaInfiniteSuffix } from "@idlekit/money";
+//# sourceMappingURL=suffixer.js.map

package/dist/notation/suffixer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suffixer.js","sourceRoot":"","sources":["../../src/notation/suffixer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAiB,MAAM,gBAAgB,CAAC"}

package/dist/notation/visibilityTracker.d.ts

@@ -0,0 +1 @@
+export { VisibilityTracker, type VisibilityChange } from "@idlekit/money";

package/dist/notation/visibilityTracker.js

@@ -0,0 +1,2 @@
+export { VisibilityTracker } from "@idlekit/money";
+//# sourceMappingURL=visibilityTracker.js.map

package/dist/notation/visibilityTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibilityTracker.js","sourceRoot":"","sources":["../../src/notation/visibilityTracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAyB,MAAM,gBAAgB,CAAC"}

package/dist/policy/emitter.d.ts

@@ -0,0 +1 @@
+export { composeEmitters, onType, type Emitter } from "@idlekit/money";

package/dist/policy/emitter.js

@@ -0,0 +1,2 @@
+export { composeEmitters, onType } from "@idlekit/money";
+//# sourceMappingURL=emitter.js.map

package/dist/policy/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../../src/policy/emitter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAgB,MAAM,gBAAgB,CAAC"}

package/dist/policy/tickMoney.d.ts

@@ -0,0 +1 @@
+export { tickMoney } from "@idlekit/money";

package/dist/policy/tickMoney.js

@@ -0,0 +1,2 @@
+export { tickMoney } from "@idlekit/money";
+//# sourceMappingURL=tickMoney.js.map

package/dist/policy/tickMoney.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickMoney.js","sourceRoot":"","sources":["../../src/policy/tickMoney.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/policy/types.d.ts

@@ -0,0 +1 @@
+export type { CoreOptions, MoneyEvent, TickFactCounts, TickPolicy, TickResult, TickStatus } from "@idlekit/money";

package/dist/policy/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/policy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":""}

package/dist/report/compare.d.ts

@@ -0,0 +1,17 @@
+import type { ScenarioV1 } from "../scenario/types";
+export type CompareMetric = "endMoney" | "endNetWorth" | "etaToTargetWorth" | "droppedRate" | "timeToMilestone" | "visibleChangesPerMinute" | "maxNoRewardGapSec";
+export type MeasuredCompareMetrics = Readonly<Partial<Record<CompareMetric, number>>>;
+export type MeasuredDecision = "a" | "b" | "tie";
+export declare function compareScenarios(args: {
+    a: ScenarioV1;
+    b: ScenarioV1;
+    metric: CompareMetric;
+    measured?: Readonly<{
+        a?: MeasuredCompareMetrics;
+        b?: MeasuredCompareMetrics;
+    }>;
+    measuredDecision?: (metric: CompareMetric) => MeasuredDecision | undefined;
+}): Readonly<{
+    better: "a" | "b" | "tie";
+    detail: unknown;
+}>;

package/dist/report/compare.js

@@ -0,0 +1,91 @@
+function safeNum(input) {
+    if (typeof input === "number")
+        return input;
+    if (typeof input === "string") {
+        const n = Number(input);
+        if (Number.isFinite(n))
+            return n;
+        const m = /^\s*([+-]?\d+(?:\.\d+)?)e([+-]?\d+)\s*$/i.exec(input);
+        if (m) {
+            const mantissa = Number(m[1]);
+            const exp = Number(m[2]);
+            if (mantissa === 0)
+                return 0;
+            if (Number.isFinite(mantissa) && Number.isFinite(exp)) {
+                return Math.log10(Math.abs(mantissa)) + exp;
+            }
+        }
+    }
+    return Number.NaN;
+}
+function score(s, metric) {
+    switch (metric) {
+        case "endMoney":
+            return safeNum(s.initial.wallet.amount);
+        case "endNetWorth":
+            return safeNum(s.initial.maxMoneyEver ?? s.initial.wallet.amount);
+        case "droppedRate":
+            return -(s.policy.maxLogGap ?? 0);
+        case "etaToTargetWorth":
+            return -(s.clock.durationSec ?? Number.MAX_SAFE_INTEGER);
+        case "timeToMilestone":
+        case "visibleChangesPerMinute":
+        case "maxNoRewardGapSec":
+            return 0;
+        default:
+            return 0;
+    }
+}
+function measuredScore(measured, metric) {
+    if (!measured)
+        return undefined;
+    const v = measured[metric];
+    return typeof v === "number" ? v : undefined;
+}
+export function compareScenarios(args) {
+    const decision = args.measuredDecision?.(args.metric);
+    if (decision) {
+        const measuredA = measuredScore(args.measured?.a, args.metric);
+        const measuredB = measuredScore(args.measured?.b, args.metric);
+        return {
+            better: decision,
+            detail: {
+                aScore: measuredA,
+                bScore: measuredB,
+                metric: args.metric,
+                source: "measured",
+            },
+        };
+    }
+    const measuredA = measuredScore(args.measured?.a, args.metric);
+    const measuredB = measuredScore(args.measured?.b, args.metric);
+    const useMeasured = measuredA !== undefined && measuredB !== undefined;
+    const aScore = useMeasured ? measuredA : score(args.a, args.metric);
+    const bScore = useMeasured ? measuredB : score(args.b, args.metric);
+    const higherBetter = args.metric === "endMoney" ||
+        args.metric === "endNetWorth" ||
+        args.metric === "visibleChangesPerMinute";
+    if (aScore === bScore) {
+        return {
+            better: "tie",
+            detail: {
+                aScore,
+                bScore,
+                metric: args.metric,
+                source: useMeasured ? "measured" : "static",
+            },
+        };
+    }
+    return {
+        better: higherBetter
+            ? (aScore > bScore ? "a" : "b")
+            : (aScore < bScore ? "a" : "b"),
+        detail: {
+            aScore,
+            bScore,
+            metric: args.metric,
+            source: useMeasured ? "measured" : "static",
+        },
+    };
+}
+//# sourceMappingURL=compare.js.map

package/dist/report/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../src/report/compare.ts"],"names":[],"mappings":"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"}

package/dist/report/timeline.d.ts

@@ -0,0 +1,16 @@
+import type { RunResult } from "../sim/types";
+export type TimelinePoint = Readonly<{
+    t: number;
+    money: string;
+    netWorth?: string;
+    prestigePoints?: string;
+    notes?: string[];
+}>;
+export declare function buildTimeline(args: {
+    run: RunResult<any, any, any>;
+    checkpointsSec: number[];
+    formatMoney: (amount: any) => string;
+    formatNetWorth?: (amount: any) => string;
+    /** Value the selected snapshot's holdings; without a valuation, use its wallet. */
+    getNetWorth?: (state: RunResult<any, any, any>["end"]) => any;
+}): TimelinePoint[];

package/dist/report/timeline.js

@@ -0,0 +1,42 @@
+function nearestAt(trace, t) {
+    if (trace.length === 0) {
+        throw new Error("trace is empty");
+    }
+    const first = trace[0];
+    if (!first) {
+        throw new Error("trace is empty");
+    }
+    let best = first;
+    let bestGap = Math.abs(best.t - t);
+    for (const row of trace) {
+        const gap = Math.abs(row.t - t);
+        if (gap < bestGap) {
+            best = row;
+            bestGap = gap;
+        }
+    }
+    return best;
+}
+export function buildTimeline(args) {
+    const trace = args.run.trace && args.run.trace.length > 0 ? args.run.trace : [args.run.start, args.run.end];
+    return args.checkpointsSec.map((t) => {
+        const s = nearestAt(trace, t);
+        const notes = [];
+        if (s.t !== t) {
+            notes.push(`nearestTrace=${s.t}`);
+        }
+        let netWorth;
+        if (args.formatNetWorth) {
+            const amount = args.getNetWorth ? args.getNetWorth(s) : s.wallet.money.amount;
+            netWorth = args.formatNetWorth(amount);
+        }
+        return {
+            t,
+            money: args.formatMoney(s.wallet.money.amount),
+            netWorth,
+            prestigePoints: String(s.prestige.points),
+            notes: notes.length > 0 ? notes : undefined,
+        };
+    });
+}
+//# sourceMappingURL=timeline.js.map

package/dist/report/timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../../src/report/timeline.ts"],"names":[],"mappings":"AAUA,SAAS,SAAS,CAA0B,KAAmB,EAAE,CAAS;IACxE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAEnC,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,IAAI,GAAG,GAAG,OAAO,EAAE,CAAC;YAClB,IAAI,GAAG,GAAG,CAAC;YACX,OAAO,GAAG,GAAG,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAO7B;IACC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAE5G,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACnC,MAAM,CAAC,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,QAA4B,CAAC;QACjC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;YAC9E,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACzC,CAAC;QAED,OAAO;YACL,CAAC;YACD,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;YAC9C,QAAQ;YACR,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAa,CAAC;YAChD,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;SAC5C,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/scenario/compile.d.ts

@@ -0,0 +1,48 @@
+import type { Engine } from "../engine/types";
+import type { Unit } from "../money/types";
+import type { CompiledScenario } from "../sim/types";
+import type { StrategyRegistry } from "../sim/strategy/registry";
+import type { ModelRegistry } from "./registry";
+import type { ScenarioV1 } from "./types";
+export type CompileOptions = Readonly<{
+    allowSuffixNotation?: boolean;
+    allowUnsafeUntilExpr?: boolean;
+}>;
+export type StrategyParamsMode = "legacy-raw" | "validated";
+/**
+ * Internal `StandardSchema` adapter. This is not the external Standard Schema package.
+ * `legacy-raw` checks the schema and still passes the caller object to `create`.
+ * `validated` passes `result.value`, which may be coerced or defaulted.
+ *
+ * @evidence docs/requirements/active/cli-resolved-run.md#req-pr07-resolved-run Amount comparisons use parseMoney. Strategy params stay legacy-raw unless validated is requested.
+ * @evidenceReview docs/requirements/active/cli-resolved-run.md#req-pr07-resolved-run #01b9284 Re-read the section: legacy-raw keeps the caller object, and an amount path does not use Number(rawRight).
+ */
+export declare function strategyCreateParams(args: {
+    raw: unknown;
+    schema?: {
+        "~standard": {
+            validate: (input: unknown) => unknown;
+        };
+    };
+    mode?: StrategyParamsMode;
+}): Readonly<{
+    mode: StrategyParamsMode;
+    params: unknown;
+}>;
+/** Check model params like `strategyCreateParams` in `legacy-raw` mode. The caller object is returned. */
+export declare function modelCreateParams(args: {
+    raw: unknown;
+    schema?: {
+        "~standard": {
+            validate: (input: unknown) => unknown;
+        };
+    };
+}): unknown;
+export declare function compileScenario<N, U extends string, Vars>(args: {
+    E: Engine<N>;
+    scenario: ScenarioV1;
+    registry: ModelRegistry;
+    strategyRegistry?: StrategyRegistry;
+    unitFactory?: (code: string) => Unit<U>;
+    opts?: CompileOptions;
+}): CompiledScenario<N, U, Vars>;