@idlekit/core 0.2.1 → 0.3.0

package/dist/sim/analysis/inspect.js

@@ -0,0 +1,388 @@
+import { observationMeets } from "./analyzers";
+import { observationContract } from "../observation";
+import { nextBoundary } from "../timeBoundary";
+import { plannerExpansionBound } from "../strategy/planner";
+import { untilExprLiterals } from "../../scenario/compile";
+import { alphaInfiniteIndex } from "../../notation/suffixer";
+/**
+ * Inspect explains a resolved plan. It does not tick, import plugins, or call the network.
+ * Doctor remains the environment check. A cost figure is a budget proposal, not wall time.
+ */
+/**
+ * @evidence docs/requirements/active/scenario-inspect.md#req-dx03-partial-tick A fixed duration counts every tick, including a shorter last tick.
+ * @evidenceReview docs/requirements/active/scenario-inspect.md#req-dx03-partial-tick #12b41ae Re-read the section: 10 seconds at step 3 is 4 ticks and the last dt is 1.
+ */
+export const inspectPartialTick = "partial-tick-included";
+/**
+ * @evidence docs/requirements/active/scenario-inspect.md#req-dx03-until-unknown An until-only clock has no step upper bound.
+ * @evidenceReview docs/requirements/active/scenario-inspect.md#req-dx03-until-unknown #3b187c6 Re-read the section: without durationSec the step count is unknown.
+ */
+export const inspectUntilUnknown = "until-only-unknown";
+/**
+ * @evidence docs/requirements/active/scenario-inspect.md#req-dx03-decimal-range A number-engine literal past the exact range is a warning. The literal is not passed through Number.
+ * @evidenceReview docs/requirements/active/scenario-inspect.md#req-dx03-decimal-range #ce8dd3e Re-read the section: 1e400 warns on number and does not warn on breakInfinity.
+ */
+export const inspectDecimalRange = "decimal-range-is-advisory";
+/**
+ * @evidence docs/requirements/active/scenario-inspect.md#req-dx03-stage-override Simulate and experience keep different step and session applies. Planner cost is a bound.
+ * @evidenceReview docs/requirements/active/scenario-inspect.md#req-dx03-stage-override #d77f1bd Re-read the section: the command step stays on simulate, and the planner figure is not a duration.
+ */
+export const inspectStageOverride = "stage-plans-differ";
+/**
+ * @evidence docs/requirements/active/scenario-inspect.md#req-dx03-plugins-default Named plugins stay unloaded unless resolve is set.
+ * @evidenceReview docs/requirements/active/scenario-inspect.md#req-dx03-plugins-default #f0a188d Re-read the section: user code is not-run and the loaded id list is empty.
+ */
+export const inspectPluginsDefault = "plugins-stay-unloaded";
+/**
+ * @evidence docs/requirements/active/scenario-inspect.md#req-dx03-plugin-metadata Resolve reports factory ids and that import may run user code. Source text stays out.
+ * @evidenceReview docs/requirements/active/scenario-inspect.md#req-dx03-plugin-metadata #211b9cf Re-read the section: the loaded id is reported and the source sentinel is absent.
+ */
+export const inspectPluginMetadata = "metadata-after-trust";
+/**
+ * @evidence docs/requirements/active/scenario-inspect.md#req-dx03-capability-split Unsupported is a declared no. Unknown is the absence of a declaration.
+ * @evidenceReview docs/requirements/active/scenario-inspect.md#req-dx03-capability-split #761d04c Re-read the section: reset unsupported emits missing-reset, and flow unknown does not.
+ */
+export const inspectCapabilitySplit = "unsupported-is-not-unknown";
+/**
+ * @evidence docs/requirements/active/scenario-inspect.md#req-dx03-no-run Inspect does not call the runner or the network. Analyzer demand is attached to the plan.
+ * @evidenceReview docs/requirements/active/scenario-inspect.md#req-dx03-no-run #97d9296 Re-read the section: a trace demand is unmet when the scenario has no trace, and fetch is unused.
+ */
+export const inspectNoRun = "no-tick-no-network";
+const PLANNER_WARN_EXPANSIONS = 64;
+/** Ticks of a fixed duration. Past the counting cap the count is null, not the cap. */
+export function fixedDurationStepCount(durationSec, stepSec) {
+    let elapsed = 0;
+    let steps = 0;
+    let lastDt = null;
+    const limit = 1_000_000;
+    while (true) {
+        const decision = nextBoundary({
+            elapsedSec: elapsed,
+            steps,
+            stepSec,
+            durationSec,
+            untilMet: false,
+            hasUntil: false,
+        });
+        if (decision.kind !== "step") {
+            return { steps, lastDt, partial: lastDt !== null && lastDt + 1e-12 < stepSec };
+        }
+        // The cap is checked only when another tick is due, so a horizon of exactly the cap keeps its count.
+        if (steps >= limit)
+            return { steps: null, lastDt: null, partial: false };
+        lastDt = decision.dt;
+        elapsed += decision.dt;
+        steps += 1;
+    }
+}
+function exponentMagnitude(text) {
+    let sign = 1;
+    let body = text;
+    if (body.startsWith("+"))
+        body = body.slice(1);
+    else if (body.startsWith("-")) {
+        sign = -1;
+        body = body.slice(1);
+    }
+    let value = 0;
+    for (const ch of body)
+        value = value * 10 + (ch.charCodeAt(0) - 48);
+    return sign * value;
+}
+export function decimalExceedsNumberDomain(literal) {
+    const trimmed = literal.trim();
+    // The money parser accepts a sign and a leading-dot mantissa, such as +1e400 and .1e400.
+    const scientific = /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)[eE]([+-]?\d+)$/.exec(trimmed);
+    if (scientific?.[1] !== undefined)
+        return Math.abs(exponentMagnitude(scientific[1])) >= 15;
+    const digits = trimmed.replace(/^[+-]/, "").split(".")[0] ?? "";
+    if (/^\d+$/.test(digits) && digits.length > 15)
+        return true;
+    // An alpha suffix scales the mantissa by 1e3 per index, as the money parser reads it: 1aa is 1e3 and 1zz is 1e2028.
+    const suffixed = /^[-+]?(\d+(?:\.\d+)?|\.\d+)(?:[eE]([+-]?\d+))?([A-Za-z]+)$/.exec(trimmed);
+    if (suffixed?.[1] === undefined || suffixed[3] === undefined)
+        return false;
+    const index = alphaInfiniteIndex(suffixed[3], 2);
+    if (index < 0)
+        return false;
+    const whole = (suffixed[1].split(".")[0] ?? "").replace(/^0+/, "");
+    const exponent = (suffixed[2] !== undefined ? exponentMagnitude(suffixed[2]) : 0) + Math.max(whole.length - 1, 0);
+    return Math.abs(exponent + index * 3) >= 15;
+}
+function numericDomainOf(engine) {
+    if (engine.source === "custom")
+        return "unknown";
+    if (engine.effectiveId === "number")
+        return "safe-integer";
+    if (engine.effectiveId === "breakInfinity")
+        return "decimal-string";
+    return "unknown";
+}
+function engineReason(engine) {
+    if (!engine.accepted)
+        return engine.rejectReason ?? "The engine was rejected before a run.";
+    if (engine.source === "default")
+        return "Number is the default. scenario.engine is metadata and is not applied.";
+    if (engine.effectiveId === "breakInfinity")
+        return "The engine flag selected breakInfinity. The literal is not passed through Number.";
+    if (engine.source === "custom")
+        return "A trusted factory already held by the caller created this engine.";
+    return `The engine flag selected ${engine.effectiveId}.`;
+}
+/**
+ * Steps between the runner's trace samples. The runner samples when `steps % everySteps === 0`, so a negative
+ * integer samples as its magnitude does, and a fraction samples at the first whole step it divides. A cadence that
+ * divides no step up to the counting cap, such as 0, retains no periodic samples.
+ */
+export function traceSampleSteps(everySteps) {
+    if (Number.isInteger(everySteps) && everySteps !== 0)
+        return Math.abs(everySteps);
+    if (!Number.isFinite(everySteps) || everySteps === 0)
+        return null;
+    for (let steps = 1; steps <= 1_000_000; steps += 1) {
+        if (steps % everySteps === 0)
+            return steps;
+    }
+    return null;
+}
+function observationSupply(request, stepSec) {
+    const untilOnly = request.clock.durationSec === undefined && Boolean(request.clock.untilExpr?.trim());
+    const coverage = request.trace.include ? "trace" : request.clock.durationSec !== undefined ? "summary" : "missing";
+    // compileScenario traces every step when the scenario includes a trace without a cadence.
+    const sampleSteps = request.trace.include ? traceSampleSteps(request.trace.everySteps ?? 1) : null;
+    const cadence = sampleSteps === null ? null : sampleSteps * stepSec;
+    return {
+        schema: observationContract,
+        // The finest window the samples supply is the trace cadence. A summary supplies no finite window.
+        windowSec: cadence,
+        sampleCadenceSec: cadence,
+        coverage: untilOnly && !request.trace.include ? "missing" : coverage,
+        metricIds: ["money", "netWorth"],
+    };
+}
+export function buildScenarioInspect(request) {
+    const diagnostics = [];
+    const untilText = request.clock.untilExpr?.trim() ? request.clock.untilExpr.trim() : null;
+    const horizonKind = request.clock.durationSec !== undefined ? "duration" : untilText ? "until" : "unknown";
+    const supplyStep = request.stages.find((stage) => stage.name === "simulate")?.stepSec.value ?? request.clock.stepSec;
+    const supply = observationSupply(request, supplyStep);
+    if (!request.engine.accepted) {
+        diagnostics.push({
+            severity: "error",
+            code: "bad-engine",
+            evidence: {
+                effectiveId: request.engine.effectiveId,
+                reason: request.engine.rejectReason ?? null,
+            },
+        });
+    }
+    // A custom engine declares no numeric domain. Its id does not say whether it narrows literals through Number,
+    // so wide literals warn for it as for the number engine. An untilExpr amount literal goes through the engine. A
+    // `t`, `prestige.count`, or known numeric state comparison goes through Number whatever the engine, so it always
+    // warns. Any other path picks its parser from the run-time value, which may be a string, so it does not warn.
+    const exact = numericDomainOf(request.engine);
+    if (request.engine.accepted) {
+        const until = untilExprLiterals(request.clock.untilExpr);
+        const engineLiterals = [
+            ...request.decimals,
+            ...until.filter((term) => term.parse === "engine").map((term) => term.literal),
+        ];
+        const numericPaths = new Set(request.numericUntilPaths ?? []);
+        const numberLiterals = until
+            .filter((term) => term.parse === "number" || (term.parse === "runtime" && numericPaths.has(term.path)))
+            .map((term) => term.literal);
+        const numberWide = numberLiterals.filter(decimalExceedsNumberDomain);
+        const wide = [
+            ...(exact !== "decimal-string" ? engineLiterals.filter(decimalExceedsNumberDomain) : []),
+            ...numberWide,
+        ];
+        if (wide.length > 0) {
+            diagnostics.push({
+                severity: "warning",
+                code: "decimal-range",
+                evidence: {
+                    engineId: request.engine.effectiveId,
+                    literal: wide[0] ?? null,
+                    count: wide.length,
+                    numberParsed: numberWide.length,
+                },
+            });
+        }
+    }
+    if (request.walletUnit !== request.unitCode) {
+        diagnostics.push({
+            severity: "warning",
+            code: "unit-goal-mismatch",
+            evidence: { walletUnit: request.walletUnit, unitCode: request.unitCode },
+        });
+    }
+    if (request.prestigeRequested && request.capabilities.reset === "unsupported") {
+        diagnostics.push({
+            severity: "warning",
+            code: "missing-reset",
+            evidence: { reset: "unsupported" },
+        });
+    }
+    if (request.prestigeRequested && request.capabilities.reset === "unknown") {
+        diagnostics.push({
+            severity: "warning",
+            code: "capability-unknown",
+            evidence: { capability: "reset" },
+        });
+    }
+    // The runner keeps the event log unless the scenario turns it off, so an omitted eventLog is enabled.
+    const eventsEnabled = request.eventLog?.enabled !== false;
+    const eventsUnlimited = eventsEnabled && request.eventLog?.maxEvents === undefined;
+    // compileScenario sets no maxPoints, so an included trace keeps every periodic state, however long the duration.
+    const traceUncapped = request.trace.include;
+    const traceUnlimited = traceUncapped || eventsUnlimited;
+    if (traceUnlimited) {
+        diagnostics.push({
+            severity: "warning",
+            code: "unlimited-trace",
+            evidence: {
+                trace: request.trace.include,
+                durationSec: request.clock.durationSec ?? null,
+                eventMax: request.eventLog?.maxEvents ?? null,
+            },
+        });
+    }
+    const planner = request.planner ? plannerExpansionBound(request.planner) : null;
+    if (planner && (planner.clamped || planner.expansionUpperBound > PLANNER_WARN_EXPANSIONS)) {
+        diagnostics.push({
+            severity: "warning",
+            code: "planner-cost",
+            evidence: {
+                expansionUpperBound: planner.expansionUpperBound,
+                measuredDurationSec: planner.measuredDurationSec,
+                cappedHorizon: planner.capped.horizonSteps,
+            },
+        });
+    }
+    if (request.plugins.requested && !request.plugins.resolve) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin-skipped",
+            evidence: {
+                userCode: "not-run",
+                model: request.plugins.unresolvedModel ?? null,
+                strategy: request.plugins.unresolvedStrategy ?? null,
+            },
+        });
+    }
+    if (request.plugins.resolve) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin-user-code",
+            evidence: { userCode: "may-run", loaded: request.plugins.loadedIds.length },
+        });
+    }
+    const analyzers = request.analyzers.map((analyzer) => {
+        const met = observationMeets(analyzer.observation, supply);
+        if (!met) {
+            diagnostics.push({
+                severity: "warning",
+                code: "insufficient-observation",
+                evidence: {
+                    analyzer: `${analyzer.id}@${analyzer.version}`,
+                    demand: analyzer.observation.coverage,
+                    supply: supply.coverage,
+                },
+            });
+        }
+        return { ...analyzer, met };
+    });
+    const stages = request.stages.map((stage) => {
+        // A stage the fast override does not apply to still runs the scenario's fast mode, which the input carries.
+        const fast = stage.fast ?? null;
+        const actionsLog = stage.actionsLog
+            ? {
+                kept: stage.actionsLog.kept,
+                maxActions: stage.actionsLog.maxActions ?? null,
+                unlimited: stage.actionsLog.kept && stage.actionsLog.maxActions === undefined,
+            }
+            : null;
+        const stateTrace = stage.stateTrace
+            ? {
+                kept: stage.stateTrace.kept,
+                everySteps: stage.stateTrace.kept ? stage.stateTrace.everySteps ?? 1 : null,
+                maxPoints: stage.stateTrace.maxPoints ?? null,
+                unlimited: stage.stateTrace.kept && stage.stateTrace.maxPoints === undefined,
+            }
+            : null;
+        // A session stage runs its schedule, and ltv runs the command's horizon, not the scenario duration, so the
+        // duration does not count their ticks.
+        if (request.clock.durationSec === undefined || stage.applies.session || stage.name === "ltv") {
+            return {
+                name: stage.name,
+                applies: stage.applies,
+                stepSec: stage.stepSec,
+                strategyId: stage.strategyId ?? null,
+                strategySource: stage.strategySource,
+                session: stage.applies.session ? stage.session ?? null : null,
+                fast,
+                actionsLog,
+                stateTrace,
+                stepCount: "unknown",
+                lastDt: null,
+                partialTick: false,
+            };
+        }
+        const counted = fixedDurationStepCount(request.clock.durationSec, stage.stepSec.value);
+        return {
+            name: stage.name,
+            applies: stage.applies,
+            stepSec: stage.stepSec,
+            strategyId: stage.strategyId ?? null,
+            strategySource: stage.strategySource,
+            session: stage.applies.session ? stage.session ?? null : null,
+            fast,
+            actionsLog,
+            stateTrace,
+            stepCount: counted.steps ?? "unknown",
+            lastDt: counted.lastDt,
+            partialTick: counted.partial,
+        };
+    });
+    return {
+        schemaVersion: 1,
+        contract: "idlekit.scenario-inspect.v1",
+        simulated: false,
+        doctor: false,
+        invalid: diagnostics.some((item) => item.severity === "error"),
+        engine: { ...request.engine, reason: engineReason(request.engine) },
+        model: request.model,
+        horizon: {
+            kind: horizonKind,
+            durationSec: request.clock.durationSec ?? null,
+            untilExpr: untilText,
+        },
+        stages,
+        offline: request.offline ?? null,
+        budgets: {
+            events: {
+                enabled: eventsEnabled,
+                maxEvents: request.eventLog?.maxEvents ?? null,
+                unlimited: eventsUnlimited,
+            },
+            trace: {
+                include: request.trace.include,
+                everySteps: request.trace.include ? request.trace.everySteps ?? 1 : request.trace.everySteps ?? null,
+                unlimited: traceUncapped,
+            },
+        },
+        numericDomain: {
+            engineId: request.engine.effectiveId,
+            exact,
+        },
+        capabilities: request.capabilities,
+        analyzers,
+        planner,
+        plugins: {
+            userCode: request.plugins.resolve ? "may-run" : "not-run",
+            loadedIds: request.plugins.resolve ? request.plugins.loadedIds : [],
+        },
+        diagnostics,
+    };
+}
+//# sourceMappingURL=inspect.js.map

package/dist/sim/analysis/inspect.js.map

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

package/dist/sim/analysis/metrics.d.ts

@@ -0,0 +1,91 @@
+import type { SimContext, SimState } from "../types";
+import { type AnalysisCapabilityName, type AnalysisMethod, type AnalysisStatus, type CapabilityKnowledge, type GoalResultV1, type MetricDomain, type MetricKind, type MetricReadingV1, type MetricTimeAxis, type AnalysisArtifactV1, type ArtifactCoverage } from "./contracts";
+export type MetricExtract<N> = Readonly<{
+    available: false;
+    status: Exclude<AnalysisStatus, "ok">;
+    reason?: string;
+}> | Readonly<{
+    available: true;
+    domain: "amount";
+    amount: N;
+    unit: string;
+}> | Readonly<{
+    available: true;
+    domain: Exclude<MetricDomain, "amount">;
+    value: number;
+}>;
+export type MetricDefinition<N, U extends string, Vars> = Readonly<{
+    id: string;
+    version: number;
+    meaning: string;
+    domain: MetricDomain;
+    timeAxis: MetricTimeAxis;
+    kind: MetricKind;
+    extract: (ctx: SimContext<N, U, Vars>, state: SimState<N, U, Vars>) => MetricExtract<N>;
+}>;
+export type GoalDefinition<N, U extends string, Vars> = Readonly<{
+    id: string;
+    version: number;
+    observation: "state" | "milestone-key" | "custom";
+    timeResolution: "step";
+    met: (state: SimState<N, U, Vars>, ctx: SimContext<N, U, Vars>) => boolean | undefined;
+    assumptionsFor?: (state: SimState<N, U, Vars>, ctx: SimContext<N, U, Vars>) => readonly string[];
+}>;
+export type GoalEvaluation = Readonly<{
+    goalId: string;
+    goalVersion: number;
+    reached?: boolean;
+    status: "ok" | "unsupported" | "insufficient-data" | "invalid";
+    assumptions: readonly string[];
+}>;
+export declare function walletMoneyMetric<N, U extends string, Vars>(): MetricDefinition<N, U, Vars>;
+export declare function netWorthMetric<N, U extends string, Vars>(read: (ctx: SimContext<N, U, Vars>, state: SimState<N, U, Vars>) => {
+    amount: N;
+    unit: string;
+} | undefined): MetricDefinition<N, U, Vars>;
+export declare function prestigePointsMetric<N, U extends string, Vars>(): MetricDefinition<N, U, Vars>;
+export declare function finiteValueMetric<N, U extends string, Vars>(args: {
+    id: string;
+    version?: number;
+    meaning: string;
+    domain: Exclude<MetricDomain, "amount">;
+    kind?: MetricKind;
+    timeAxis?: MetricTimeAxis;
+    read: (ctx: SimContext<N, U, Vars>, state: SimState<N, U, Vars>) => number | undefined;
+}): MetricDefinition<N, U, Vars>;
+export declare function readMetric<N, U extends string, Vars>(metric: MetricDefinition<N, U, Vars>, ctx: SimContext<N, U, Vars>, state: SimState<N, U, Vars>, method?: AnalysisMethod): MetricReadingV1;
+export declare function moneyAtLeast<N, U extends string, Vars>(target: string): GoalDefinition<N, U, Vars>;
+export declare function netWorthAtLeast<N, U extends string, Vars>(args: {
+    target: string;
+    netWorth: (state: SimState<N, U, Vars>, ctx: SimContext<N, U, Vars>) => N | undefined;
+    fallbackToWallet?: boolean;
+}): GoalDefinition<N, U, Vars>;
+export declare function prestigePointsAtLeast<N, U extends string, Vars>(target: string): GoalDefinition<N, U, Vars>;
+export declare function milestoneReached<N, U extends string, Vars>(args: {
+    key: string;
+    seen: readonly string[];
+}): GoalDefinition<N, U, Vars>;
+export declare function defineGoal<N, U extends string, Vars>(goal: GoalDefinition<N, U, Vars>): GoalDefinition<N, U, Vars>;
+export declare function evaluateGoal<N, U extends string, Vars>(goal: GoalDefinition<N, U, Vars>, state: SimState<N, U, Vars>, ctx: SimContext<N, U, Vars>): GoalEvaluation;
+export declare function evaluateGoalForEta<N, U extends string, Vars>(goal: GoalDefinition<N, U, Vars>, state: SimState<N, U, Vars>, ctx: SimContext<N, U, Vars>): GoalResultV1;
+export declare function evaluateGoalForExperiment<N, U extends string, Vars>(goal: GoalDefinition<N, U, Vars>, state: SimState<N, U, Vars>, ctx: SimContext<N, U, Vars>): GoalResultV1;
+export declare function evaluateGoalForCheck<N, U extends string, Vars>(goal: GoalDefinition<N, U, Vars>, state: SimState<N, U, Vars>, ctx: SimContext<N, U, Vars>): GoalResultV1;
+export declare function capabilityKnowledge(declared: Partial<Record<AnalysisCapabilityName, "statically-known" | "unsupported">> | undefined, name: AnalysisCapabilityName): CapabilityKnowledge;
+export declare function unsupportedCapabilityResult(name: AnalysisCapabilityName): Readonly<{
+    capability: AnalysisCapabilityName;
+    knowledge: "unsupported";
+    status: "unsupported";
+}>;
+export type AnalysisArtifactDraft = Readonly<{
+    algorithmVersion?: string;
+    assumptions?: readonly string[];
+    warnings?: readonly string[];
+    observationCoverage?: ArtifactCoverage;
+    horizon?: AnalysisArtifactV1["horizon"];
+    sampleCount?: number;
+    effectiveRunHash?: string;
+    metrics?: readonly MetricReadingV1[];
+    goals?: readonly GoalResultV1[];
+    capabilities?: AnalysisArtifactV1["capabilities"];
+}>;
+export declare function buildAnalysisArtifact(draft?: AnalysisArtifactDraft): AnalysisArtifactV1;