synergyspec-selfevolving 1.4.0 → 2.1.0

package/dist/core/self-evolution/episode-store.d.ts

@@ -0,0 +1,266 @@
+/**
+ * 磁盘 DISK episode store（transcripts ×双臂）— loop v2 (self-evolution as
+ * in-context RL).
+ *
+ * This module is DUMB STORAGE plus a stage machine — it never spawns an agent
+ * and never computes a skeleton; callers pass objects in. One episode = one
+ * synergyspec-selfevolving change run through the loop, recorded under:
+ *
+ *     <repoRoot>/.synergyspec-selfevolving/self-evolution/episodes/<episodeId>/
+ *       episode.json     // the state-machine record (this module owns it)
+ *       main-arm/        // 主智能体 MAIN AGENT (frozen actor; the user's host
+ *                        // agent running the current policy vN+1):
+ *                        //   transcript.jsonl + skeleton.json + objective.json
+ *       baseline-arm/    // CRITIC AGENT（基线智能体 baseline agent）output — an
+ *                        // AGENT with the same input/output as the main agent
+ *                        // that reruns LAST episode's policy vN on the SAME
+ *                        // change. This dir is the ONLY artifact that survives
+ *                        // its worktree (产物即弃 — worktree artifacts
+ *                        // discarded): same three files, except the transcript
+ *                        // may be `stdout.txt` when the harness exposes no
+ *                        // session file.
+ *       diagnosis.json   // written LATER by the 奖励智能体 REWARD AGENT via
+ *                        // {@link writeDiagnosis} — LLM as judge; CALCULATES
+ *                        // 算分 reward(主臂)＆reward(基线臂); advantage ＝
+ *                        // reward(主臂) − reward(基线臂); 文本梯度 textual
+ *                        // gradient; never edits; 弃权 abstains when no
+ *                        // nameable gap. {@link createEpisode} never creates
+ *                        // this file; this module only stores its content.
+ *
+ * The 5 artifacts + test-report stay in the change dir
+ * (`synergyspec-selfevolving/changes/<name>/`) — `episode.json` records that
+ * path (`changeDirPath`), never copies.
+ *
+ * 策略 POLICY ＝ design template（主智能体的「权重」）· CLI 持有版本:
+ * `policyVersionMain` / `policyVersionBaseline` record WHICH version each arm
+ * ran. The versions themselves live in the 版本账本 ledger (a sibling module);
+ * 单一血统 single lineage and the 否决缓冲 reject-buffer are enforced there,
+ * not here. The 演进智能体 EVOLVING AGENT (optimizer.step; ONE bounded edit ≤L;
+ * never scores) runs after scoring; its outcome lands in this store only as a
+ * stage (`evolved` | `evolution-refused`).
+ *
+ * Hard rules (matching candidates.ts):
+ *   - This module ONLY reads/writes inside the episodes base dir.
+ *   - All writes use a tmp + rename pattern so a half-written record never
+ *     appears under its final name.
+ *   - Stage changes go through a validated MONOTONIC state machine —
+ *     advancing to a stage not reachable from the current one throws.
+ */
+/**
+ * Lifecycle stage for an episode.
+ *
+ * State machine (see {@link isLegalEpisodeStageTransition}; monotonic — no
+ * regressions, no jumps):
+ *
+ *   created
+ *     -> main-arm-captured                            // 主智能体 MAIN AGENT arm landed
+ *     -> (baseline-arm-captured | baseline-skipped)   // CRITIC AGENT（基线智能体 baseline agent）arm
+ *     -> scored                                       // 奖励智能体 REWARD AGENT wrote diagnosis.json
+ *     -> (rolled-back | kept)                         // rollback decision on the main arm's edits
+ *     -> (evolved | evolution-refused | abstained)    // 演进智能体 EVOLVING AGENT outcome
+ *     -> closed                                       // terminal
+ *
+ * `abstained` may also follow `scored` directly: the 奖励智能体 REWARD AGENT
+ * 弃权 abstains when no nameable gap → no rollback decision needed → the
+ * 演进智能体 EVOLVING AGENT is never spawned.
+ */
+export type EpisodeStage = 'created' | 'main-arm-captured' | 'baseline-arm-captured' | 'baseline-skipped' | 'scored' | 'rolled-back' | 'kept' | 'evolved' | 'evolution-refused' | 'abstained' | 'closed';
+/**
+ * Iterable list of every legal {@link EpisodeStage} value. Order follows the
+ * documented state machine for readability, not behavior.
+ */
+export declare const EPISODE_STAGES: readonly EpisodeStage[];
+/**
+ * The two arms of one episode:
+ *  - `main-arm`     — 主智能体 MAIN AGENT (frozen actor, policy vN+1).
+ *  - `baseline-arm` — CRITIC AGENT（基线智能体 baseline agent）, rerunning LAST
+ *    episode's policy vN on the SAME change; the capture is the ONLY artifact
+ *    that survives its worktree (产物即弃).
+ */
+export type EpisodeArm = 'main-arm' | 'baseline-arm';
+/** One audit entry in `stageHistory` — which stage was entered, and when. */
+export interface EpisodeStageHistoryEntry {
+    stage: EpisodeStage;
+    /** ISO 8601 UTC timestamp the stage was entered. */
+    at: string;
+}
+/**
+ * The `episode.json` state-machine record. Mutated only via
+ * {@link advanceEpisodeStage}; everything else in the episode dir is opaque
+ * arm/diagnosis storage.
+ */
+export interface EpisodeRecord {
+    schemaVersion: 1;
+    /** Sanitized id, also the directory name: `[a-z0-9-]` only. */
+    episodeId: string;
+    /** The synergyspec-selfevolving change this episode ran. */
+    changeName: string;
+    /**
+     * Absolute path of the change dir (`synergyspec-selfevolving/changes/<name>/`)
+     * where the 5 artifacts + test-report live. Recorded, never copied.
+     */
+    changeDirPath: string;
+    /** The canonical target whose 策略 POLICY the episode exercises. */
+    targetId: string;
+    /** 版本账本 ledger version the 主智能体 MAIN AGENT ran (vN+1); null when unknown. */
+    policyVersionMain: number | null;
+    /** 版本账本 ledger version the CRITIC AGENT（基线智能体 baseline agent）reran (vN); null until captured. */
+    policyVersionBaseline: number | null;
+    /** Current stage. Mutated only via {@link advanceEpisodeStage}. */
+    stage: EpisodeStage;
+    /** Append-only audit trail of every stage entered, including `created`. */
+    stageHistory: EpisodeStageHistoryEntry[];
+    /** Why the baseline arm was skipped (set with stage `baseline-skipped`). */
+    baselineSkippedReason?: string;
+    /** advantage ＝ reward(主臂) − reward(基线臂); null when the 奖励智能体 REWARD AGENT 弃权 abstained. */
+    advantage?: number | null;
+    /** ISO 8601 UTC timestamp the episode record was created. */
+    createdAt: string;
+    /** ISO 8601 UTC timestamp of the last record mutation. */
+    updatedAt: string;
+}
+/** Patch fields {@link advanceEpisodeStage} may merge alongside a stage advance. */
+export interface EpisodeStagePatch {
+    policyVersionBaseline?: number | null;
+    baselineSkippedReason?: string;
+    advantage?: number | null;
+}
+/**
+ * True iff `(from -> to)` is a legal transition in the episode stage machine.
+ * See the type-level doc on {@link EpisodeStage} for the full table.
+ *
+ * Pure function; safe to call from validators, tests, and UIs.
+ */
+export declare function isLegalEpisodeStageTransition(from: EpisodeStage, to: EpisodeStage): boolean;
+/**
+ * Absolute path of one episode's directory. No I/O; the dir may not exist yet.
+ * Throws on an unsafe id so this can never be used for path traversal.
+ */
+export declare function episodeDir(repoRoot: string, episodeId: string): string;
+export interface CreateEpisodeOptions {
+    /** Absolute path to the project root that owns the episode store. */
+    repoRoot: string;
+    /** The synergyspec-selfevolving change name this episode ran. */
+    changeName: string;
+    /** Absolute path of the change dir; recorded in episode.json, never copied. */
+    changeDirPath: string;
+    /** The canonical target whose 策略 POLICY the episode exercises. */
+    targetId: string;
+    /** 版本账本 ledger version the 主智能体 MAIN AGENT ran (vN+1); null when unknown. */
+    policyVersionMain: number | null;
+    /**
+     * Explicit episode id (must already match `[a-z0-9-]`). Default:
+     * `<changeName>-<compact UTC timestamp yyyyMMddTHHmmss>` sanitized to
+     * `[a-z0-9-]`. Either way a collision appends `-2`, `-3`, …
+     */
+    episodeId?: string;
+    /** TEST-ONLY deterministic clock seed; defaults to `new Date()`. */
+    now?: Date;
+}
+/**
+ * Create a new episode directory with its `episode.json` at stage `created`
+ * (plus empty `main-arm/` and `baseline-arm/` dirs so the on-disk layout is
+ * self-describing). `diagnosis.json` is deliberately NOT created here — the
+ * 奖励智能体 REWARD AGENT writes it later via {@link writeDiagnosis}.
+ *
+ * Atomic: the whole episode dir is staged in a sibling tmp dir and renamed
+ * into place, so a half-written episode never appears under its final id.
+ *
+ * @returns The created record and the absolute episode directory. Callers must
+ *   read `episode.episodeId` back — a collision may have suffixed it.
+ */
+export declare function createEpisode(opts: CreateEpisodeOptions): Promise<{
+    episode: EpisodeRecord;
+    episodeDir: string;
+}>;
+/**
+ * Read one episode's `episode.json`. Throws a deterministic `Error` when the
+ * episode does not exist.
+ */
+export declare function readEpisode(repoRoot: string, episodeId: string): Promise<EpisodeRecord>;
+export interface AdvanceEpisodeStageOptions {
+    repoRoot: string;
+    episodeId: string;
+    /** The stage to enter; must be legal from the current stage or this throws. */
+    stage: EpisodeStage;
+    /** Optional allowlisted fields to merge in the same atomic write. */
+    patch?: EpisodeStagePatch;
+}
+/**
+ * Advance an episode to its next stage — atomic read-modify-write of
+ * `episode.json` (sibling tmp file + rename, so a half-written advance is
+ * never observed).
+ *
+ * - Validates the transition via {@link isLegalEpisodeStageTransition};
+ *   advancing to a stage not reachable from the current one throws.
+ * - Appends `{stage, at}` to `stageHistory`.
+ * - Merges the allowlisted `patch` fields (`policyVersionBaseline`,
+ *   `baselineSkippedReason`, `advantage`) in the same write.
+ * - Bumps `updatedAt`.
+ */
+export declare function advanceEpisodeStage(opts: AdvanceEpisodeStageOptions): Promise<EpisodeRecord>;
+/**
+ * List every episode (newest first by `createdAt`; ties resolve by id for
+ * determinism, matching `listCandidates`).
+ *
+ * - Returns `[]` cleanly when the episodes base dir does not exist.
+ * - Skips in-flight `.tmp-` dirs from a previous interrupted create.
+ * - Skips directories without a readable, valid `episode.json` (prints a
+ *   warning to stderr so corrupted episodes are surfaced).
+ */
+export declare function listEpisodes(repoRoot: string): Promise<EpisodeRecord[]>;
+export interface WriteArmCaptureOptions {
+    repoRoot: string;
+    episodeId: string;
+    /** Which arm dir to write into; see {@link EpisodeArm}. */
+    arm: EpisodeArm;
+    /**
+     * Raw transcript to persist verbatim. Conventionally `transcript.jsonl`;
+     * the CRITIC AGENT（基线智能体 baseline agent）arm may carry `stdout.txt`
+     * when the harness exposes no session file. Optional — some harnesses only
+     * yield a skeleton + objective.
+     */
+    transcript?: {
+        fileName: string;
+        content: string;
+    };
+    /** Pre-computed skeleton (this module never computes one). Stored as `skeleton.json`. */
+    skeleton?: object;
+    /** The arm's objective record. Stored as `objective.json`. Required. */
+    objective: object;
+}
+/**
+ * Persist one arm's capture into `<episodeDir>/<arm>/`. DUMB STORAGE: callers
+ * pass the transcript/skeleton/objective in; this module never spawns the
+ * 主智能体 MAIN AGENT or the CRITIC AGENT（基线智能体 baseline agent）and never
+ * computes a skeleton. Each file is written atomically (tmp + rename);
+ * re-capturing overwrites (last write wins). Stage advancement is the
+ * caller's job via {@link advanceEpisodeStage} — storage and state machine
+ * stay decoupled.
+ *
+ * @returns The absolute arm dir and the absolute paths written.
+ */
+export declare function writeArmCapture(opts: WriteArmCaptureOptions): Promise<{
+    armDir: string;
+    writtenFiles: string[];
+}>;
+export interface WriteDiagnosisOptions {
+    repoRoot: string;
+    episodeId: string;
+    /**
+     * The 奖励智能体 REWARD AGENT's diagnosis — reward(主臂)＆reward(基线臂),
+     * advantage ＝ reward(主臂) − reward(基线臂), 文本梯度 textual gradient (or a
+     * 弃权 abstain record when there is no nameable gap). Storage only: this
+     * module never validates or interprets the content; the 奖励智能体 owns it.
+     */
+    diagnosis: object;
+}
+/**
+ * Atomic write of `<episodeDir>/diagnosis.json`. Last write wins (an episode
+ * has exactly ONE current diagnosis; the audit trail is `stageHistory`).
+ * Throws deterministically when the episode does not exist.
+ *
+ * @returns The absolute path of the written `diagnosis.json`.
+ */
+export declare function writeDiagnosis(opts: WriteDiagnosisOptions): Promise<string>;
+//# sourceMappingURL=episode-store.d.ts.map