@idlekit/core 0.2.1 → 0.3.0

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

@@ -0,0 +1,175 @@
+import typia, { type IValidation } from "typia";
+import { type Action, type CompiledScenario, type ScenarioConstraints, type SimContext, type SimState } from "../types";
+/**
+ * Reset-cycle execution v1.
+ * `analyzePrestigeCycle` stays the legacy interval scan.
+ * This artifact does not copy that scan's stability or break-even fields.
+ */
+declare const RESET_CYCLE_ALGORITHM_VERSION: "reset-cycle-v1";
+declare const RESET_CYCLE_SCHEMA_ID: "https://idlekit.dev/schemas/reset.cycle.v1.schema.json";
+/**
+ * @evidence docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset Each cycle commits a reset through the action payment path.
+ * @evidenceReview docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset #22d7a8a Re-read the section: three cycles leave three resets, and the reset does not mint income.
+ */
+export declare const resetCycleExecution: "committed-reset-transition";
+/**
+ * @evidence docs/requirements/active/reset-cycle-execution.md#req-pr10-refused-reset A refused cost, condition, or cooldown pays no reward.
+ * @evidenceReview docs/requirements/active/reset-cycle-execution.md#req-pr10-refused-reset #5bbd1e4 Re-read the section: cannot-apply, insufficient funds, and cooldown are recorded, and the point stock stays put.
+ */
+export declare const resetCycleSameContract: "prestige-and-custom-reset";
+/**
+ * @evidence docs/requirements/active/reset-cycle-execution.md#req-pr10-reward-delta Reward gained by the reset does not include the stock already held.
+ * @evidenceReview docs/requirements/active/reset-cycle-execution.md#req-pr10-reward-delta #ed22025 Re-read the section: opening points of 100 stay out of the delta.
+ */
+export declare const resetCycleRewardDelta: "reward-delta-excludes-opening-stock";
+export declare function resetCycleSchemaId(): typeof RESET_CYCLE_SCHEMA_ID;
+export declare function resetCycleAlgorithmVersion(): typeof RESET_CYCLE_ALGORITHM_VERSION;
+export declare class ResetCycleRejected extends Error {
+    constructor(message: string);
+}
+export type ResetCycleStatus = "ok" | "incomplete" | "censored" | "unsupported";
+export type ResetSkipReason = "cannot-apply" | "insufficient-funds" | "cooldown" | "budget" | "rejected" | "missing-adapter";
+export type ResetCycleRowV1 = Readonly<{
+    index: number;
+    startSec: number;
+    endSec: number;
+    resetAtSec: number | null;
+    durationSec: number;
+    rewardDelta: string;
+    accumulatedReward: string;
+    resetSkippedReason?: ResetSkipReason;
+    carried: Readonly<{
+        points: string;
+        multiplier: string;
+        count: number;
+        reward: string;
+    }>;
+}>;
+export type ResetCycleArtifactV1 = Readonly<{
+    schemaVersion: 1;
+    algorithmVersion: typeof RESET_CYCLE_ALGORITHM_VERSION;
+    status: ResetCycleStatus;
+    policy: "fixed-interval" | "explicit";
+    appliedResets: number;
+    originSec: number;
+    globalElapsedSec: number;
+    assumptions: readonly string[];
+    warnings: readonly string[];
+    cycles: readonly ResetCycleRowV1[];
+}>;
+/**
+ * @evidence docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset The generated validator accepts this artifact and rejects a missing status.
+ * @evidenceReview docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset #22d7a8a Re-read the section: the wire object is reset cycle v1.
+ */
+export declare const validateResetCycleArtifact: (input: unknown) => IValidation<ResetCycleArtifactV1>;
+declare function buildResetCycleJsonSchema(): typia.IJsonSchemaUnit.IV3_1<Readonly<{
+    schemaVersion: 1;
+    algorithmVersion: typeof RESET_CYCLE_ALGORITHM_VERSION;
+    status: ResetCycleStatus;
+    policy: "fixed-interval" | "explicit";
+    appliedResets: number;
+    originSec: number;
+    globalElapsedSec: number;
+    assumptions: readonly string[];
+    warnings: readonly string[];
+    cycles: readonly ResetCycleRowV1[];
+}>>;
+/**
+ * @evidence docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset The structural schema is OpenAPI 3.1 from typia.
+ * @evidenceReview docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset #22d7a8a Re-read the section: schema version is 3.1.
+ */
+export declare function resetCycleJsonSchema(): ReturnType<typeof buildResetCycleJsonSchema>;
+/**
+ * What a reset is allowed to keep, and how its reward is measured.
+ * `pointsFrom` is a declared gain. `resetState` writes the next state.
+ * `multiplierFrom` maps the post-reset point total and is not applied a second time.
+ */
+export type ResetAdapter<N, U extends string, Vars> = Readonly<{
+    id: string;
+    kind: "prestige" | "custom";
+    preserved: readonly ("points" | "multiplier" | "count" | "vars")[];
+    action: (ctx: SimContext<N, U, Vars>, state: SimState<N, U, Vars>) => Action<N, U, Vars> | undefined;
+    reward: (ctx: SimContext<N, U, Vars>, state: SimState<N, U, Vars>) => N;
+}>;
+export type ResetCyclePolicy = Readonly<{
+    kind: "fixed-interval";
+    intervalSec: number;
+    cycles: number;
+}> | Readonly<{
+    kind: "explicit";
+    steps: readonly Readonly<{
+        durationSec: number;
+    }>[];
+}>;
+export type ResetCycleRng = Readonly<{
+    /** Names the generator. A checkpoint records it, and a resume with another generator is rejected. */
+    id: string;
+    /** The version of the snapshot format. A checkpoint records it, and a resume with another version is rejected. */
+    stateVersion: number;
+    snapshot: () => unknown;
+    restore: (state: unknown) => void;
+}>;
+export type ResetCycleCheckpoint<N, U extends string, Vars> = Readonly<{
+    contract: "idlekit.reset-cycle-checkpoint";
+    version: 1;
+    state: SimState<N, U, Vars>;
+    constraints?: ScenarioConstraints;
+    nextIndex: number;
+    originSec: number;
+    /** Simulated seconds since the origin, summed from each runner result. Absent on older checkpoints. */
+    elapsedSec?: number;
+    accumulatedReward: N;
+    strategyState?: unknown;
+    /** The explicit reset adapter whose reward accumulatedReward sums. A resume checks it. */
+    adapterId?: string;
+    adapterKind?: "prestige" | "custom";
+    /** Seconds already played of a cycle a budget cut. A resume plays only the rest of that cycle. */
+    pendingSec?: number;
+    /** The planned duration of that cut cycle. A resume must plan the same duration for it. */
+    pendingDurationSec?: number;
+    /** The t at which that cut cycle started. The resumed row keeps it, so its span matches its duration. */
+    pendingStartSec?: number;
+    /** The model the state belongs to. A resume checks it. */
+    modelId?: string;
+    modelVersion?: number;
+    /** The id and state version of the strategy that wrote strategyState. A resume checks them. */
+    strategyId?: string;
+    strategyStateVersion?: number;
+    rngState?: unknown;
+    /** The id and state version of the generator that wrote rngState. A resume checks them. */
+    rngId?: string;
+    rngStateVersion?: number;
+}>;
+export type ResetCycleExecution<N, U extends string, Vars> = Readonly<{
+    artifact: ResetCycleArtifactV1;
+    state: SimState<N, U, Vars>;
+    constraints?: ScenarioConstraints;
+    checkpoint: ResetCycleCheckpoint<N, U, Vars>;
+}>;
+/**
+ * Prestige action wins when both an action and a spec exist.
+ * The spec functions are not called on that path, so the bonus is not applied twice.
+ * A model with neither needs the caller to pass an adapter.
+ *
+ * @evidence docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset The default adapter uses the prestige action, or the spec when no action exists.
+ * @evidenceReview docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset #22d7a8a Re-read the section: an action and a spec are not both applied.
+ */
+export declare function resetAdapterFor<N, U extends string, Vars>(scenario: CompiledScenario<N, U, Vars>, explicit?: ResetAdapter<N, U, Vars>, state?: SimState<N, U, Vars>, ctx?: SimContext<N, U, Vars>): ResetAdapter<N, U, Vars> | undefined;
+/**
+ * Run a fixed interval or an explicit list of reset durations.
+ * Each completed cycle ends in one committed reset. A refused reset is kept and not forced.
+ *
+ * @evidence docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset The executor chains cycle end into the next cycle start.
+ * @evidenceReview docs/requirements/active/reset-cycle-execution.md#req-pr10-committed-reset #22d7a8a Re-read the section: carried points and multiplier are the next cycle's start, and a split resume matches one run.
+ */
+export declare function executeResetCycles<N, U extends string, Vars>(args: {
+    scenario: CompiledScenario<N, U, Vars>;
+    policy: ResetCyclePolicy;
+    adapter?: ResetAdapter<N, U, Vars>;
+    maxCycles?: number;
+    horizonSec?: number;
+    budgetSteps?: number;
+    resume?: ResetCycleCheckpoint<N, U, Vars>;
+    rng?: ResetCycleRng;
+}): ResetCycleExecution<N, U, Vars>;
+export {};