dsh-continual-evolve 0.10.6 → 0.12.0

package/lib/state.d.ts

@@ -1,26 +0,0 @@
-import type { HarnessScope, HarnessState } from "./types.js";
-export declare function stateFilePath(stateDir: string): string;
-/**
- * Load state from disk, degrading to empty on any unreadable or malformed
- * content. Called on every system-prompt build and before every apply, so it
- * must never throw for a bad file.
- */
-export declare function loadHarnessState(stateDir: string, scope?: HarnessScope): HarnessState;
-/**
- * Merge global, project, and local state into the view the model sees.
- * Precedence is global < project < local: a colliding project id is
- * prefixed `project:` so both remain addressable, and a colliding local id
- * is prefixed `local:` (local always wins — it is the session's live
- * staging copy). Called with two args the project layer is simply absent.
- */
-export declare function mergeHarnessStates(globalState: HarnessState, localState?: HarnessState | undefined, opts?: {
-    projectState?: HarnessState | undefined;
-}): HarnessState;
-/**
- * Persist state atomically: write to a temp file, fsync-free but rename-based,
- * preserving the mode of an existing file (defaults to 0o600 for new files).
- */
-export declare function saveHarnessState(stateDir: string, state: HarnessState): string;
-/** True when an entry in `current` differs from the same entry in `baseline`. */
-export declare function entryChangedSince(baseline: HarnessState, current: HarnessState, kind: keyof HarnessState["entries"], id: string): boolean;
-//# sourceMappingURL=state.d.ts.map

package/lib/state.js

@@ -1,151 +0,0 @@
-/**
- * Persistence layer for harness state: atomic writes, corrupt-file degrade,
- * scope merge, and optimistic-concurrency primitives.
- *
- * Safety properties (code-enforced, not prompt-enforced):
- * - writes are atomic (temp file + rename) and preserve the file mode;
- * - an unreadable or non-object state file degrades to empty state so a
- *   broken file can never take a session down; the next save rewrites it
- *   cleanly;
- * - every entry read from disk is shape-normalized (scope, reference,
- *   arguments, metadata) so a hand-edited file cannot smuggle garbage into
- *   the system prompt renderer.
- */
-import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { readFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { join } from "node:path";
-import { emptyHarnessState } from "./types.js";
-export function stateFilePath(stateDir) {
-    return join(stateDir, "harness_state.json");
-}
-function normalizeScope(value, fallback) {
-    return value === "global" || value === "project" || value === "local" ? value : fallback;
-}
-function objectRecord(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return undefined;
-    }
-    return value;
-}
-/**
- * Load state from disk, degrading to empty on any unreadable or malformed
- * content. Called on every system-prompt build and before every apply, so it
- * must never throw for a bad file.
- */
-export function loadHarnessState(stateDir, scope = "global") {
-    const path = stateFilePath(stateDir);
-    if (!existsSync(path)) {
-        return emptyHarnessState();
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        return emptyHarnessState();
-    }
-    const root = objectRecord(parsed);
-    if (!root) {
-        return emptyHarnessState();
-    }
-    const state = emptyHarnessState();
-    if (typeof root["schema"] === "number") {
-        state.schema = root["schema"];
-    }
-    const entries = objectRecord(root["entries"]);
-    if (entries) {
-        for (const kind of Object.keys(state.entries)) {
-            const records = objectRecord(entries[kind]);
-            if (!records)
-                continue;
-            for (const [id, raw] of Object.entries(records)) {
-                const entry = objectRecord(raw);
-                if (!entry)
-                    continue;
-                state.entries[kind][id] = {
-                    id: typeof entry["id"] === "string" ? entry["id"] : id,
-                    kind,
-                    title: typeof entry["title"] === "string" ? entry["title"] : id,
-                    content: typeof entry["content"] === "string" ? entry["content"] : "",
-                    path: typeof entry["path"] === "string" ? entry["path"] : "general",
-                    scope: normalizeScope(entry["scope"], scope),
-                    reference: objectRecord(entry["reference"]) ?? {},
-                    arguments: objectRecord(entry["arguments"]) ?? {},
-                    // skill_kind must survive persistence: /evolve mount and the
-                    // listing render branch on it (guidance vs executable).
-                    ...(entry["skill_kind"] === "guidance" || entry["skill_kind"] === "executable"
-                        ? { skill_kind: entry["skill_kind"] }
-                        : {}),
-                    metadata: objectRecord(entry["metadata"]) ?? {},
-                    source: "evolve",
-                    created_at: typeof entry["created_at"] === "string" ? entry["created_at"] : new Date(0).toISOString(),
-                    updated_at: typeof entry["updated_at"] === "string" ? entry["updated_at"] : new Date(0).toISOString(),
-                    version: typeof entry["version"] === "number" ? entry["version"] : 1,
-                };
-            }
-        }
-    }
-    if (Array.isArray(root["refinements"])) {
-        // Shape-check members like entries do: a hand-edited file must never
-        // reach render/planner paths and crash them (review audit 2026-08-28
-        // S6 — loadHarnessState promises "never throws on a bad file").
-        state.refinements = root["refinements"].filter((item) => typeof item === "object" && item !== null && typeof item["id"] === "string");
-    }
-    return state;
-}
-/**
- * Merge global, project, and local state into the view the model sees.
- * Precedence is global < project < local: a colliding project id is
- * prefixed `project:` so both remain addressable, and a colliding local id
- * is prefixed `local:` (local always wins — it is the session's live
- * staging copy). Called with two args the project layer is simply absent.
- */
-export function mergeHarnessStates(globalState, localState, opts) {
-    const merged = emptyHarnessState();
-    merged.schema = Math.max(globalState.schema, opts?.projectState?.schema ?? 1, localState?.schema ?? 1);
-    for (const kind of Object.keys(merged.entries)) {
-        for (const [id, entry] of Object.entries(globalState.entries[kind])) {
-            merged.entries[kind][id] = { ...entry, scope: "global" };
-        }
-        for (const [id, entry] of Object.entries(opts?.projectState?.entries[kind] ?? {})) {
-            const scoped = { ...entry, scope: "project" };
-            const mergedId = merged.entries[kind][id] ? `project:${id}` : id;
-            merged.entries[kind][mergedId] = scoped;
-        }
-        for (const [id, entry] of Object.entries(localState?.entries[kind] ?? {})) {
-            const scoped = { ...entry, scope: "local" };
-            const mergedId = merged.entries[kind][id] ? `local:${id}` : id;
-            merged.entries[kind][mergedId] = scoped;
-        }
-    }
-    merged.refinements = [...globalState.refinements, ...(opts?.projectState?.refinements ?? []), ...(localState?.refinements ?? [])];
-    return merged;
-}
-/**
- * Persist state atomically: write to a temp file, fsync-free but rename-based,
- * preserving the mode of an existing file (defaults to 0o600 for new files).
- */
-export function saveHarnessState(stateDir, state) {
-    const path = stateFilePath(stateDir);
-    const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    mkdirSync(stateDir, { recursive: true });
-    try {
-        const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
-        writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}\n`, { encoding: "utf8", mode });
-        renameSync(tempPath, path);
-    }
-    finally {
-        if (existsSync(tempPath)) {
-            unlinkSync(tempPath);
-        }
-    }
-    return path;
-}
-/** True when an entry in `current` differs from the same entry in `baseline`. */
-export function entryChangedSince(baseline, current, kind, id) {
-    const before = baseline.entries[kind][id];
-    const after = current.entries[kind][id];
-    return JSON.stringify(before ?? null) !== JSON.stringify(after ?? null);
-}
-//# sourceMappingURL=state.js.map

package/lib/store.d.ts

@@ -1,62 +0,0 @@
-import type { HarnessScope, RefinementResult } from "./types.js";
-export declare const EVOLVE_DIR = "evolve";
-/**
- * Storage-hygiene defaults (#20): history used to grow append-only without
- * bound (dozens of full-state snapshot copies, unbounded JSONL). Retention
- * is count-based and generous — rollback only ever needs recent snapshots
- * and readers (`failures.ts` over reviews) need a working window, not the
- * full past. Tunable via the `historyRetain` plugin config.
- */
-export declare const DEFAULT_SNAPSHOT_RETAIN = 20;
-export declare const DEFAULT_REFINEMENTS_RETAIN = 500;
-export declare const DEFAULT_REVIEWS_RETAIN = 500;
-export declare const DEFAULT_TOKEN_USAGE_RETAIN = 500;
-/** Resolved retention set: how many snapshots / JSONL tail lines to keep. */
-export interface HistoryRetention {
-    /** Full-state snapshots kept per store (oldest pruned first). */
-    snapshots: number;
-    /** Tail lines kept in each store's refinements.jsonl. */
-    refinements: number;
-    /** Tail lines kept in the shared reviews.jsonl audit trail. */
-    reviews: number;
-    /** Tail lines kept in the direct-call token-usage.jsonl ledger. */
-    tokenUsage: number;
-}
-/** Defaults applied for absent / non-positive retention fields (fail loud never: clamp, don't throw). */
-export declare function resolveHistoryRetention(raw?: Partial<HistoryRetention>): HistoryRetention;
-export interface StorePaths {
-    /** Directory holding harness_state.json. */
-    stateDir: string;
-    /** Directory holding snapshots for this store. */
-    snapshotsDir: string;
-    /** JSONL path for applied refinement results. */
-    resultsPath: string;
-}
-/**
- * Resolve store paths for a scope. For `project` the `sessionId` parameter
- * carries the project key (see {@link resolveProjectKey} in project.ts) —
- * it is sanitized to a single path segment so an externally supplied key
- * can never traverse out of `evolve/projects/`.
- */
-export declare function storePaths(baseDir: string, scope: HarnessScope, sessionId?: string): StorePaths;
-/** Snapshot the current state file before a mutation, if one exists. */
-export declare function snapshotBefore(paths: StorePaths, refinementId: string): void;
-/** Append an applied result to the store's JSONL history. */
-export declare function appendResult(paths: StorePaths, result: RefinementResult): void;
-/**
- * Prune a store's snapshots to the newest `retain` files (by mtime, oldest
- * first). Best-effort: a missing directory or an unlink failure never breaks
- * the apply path — the next apply retries.
- */
-export declare function pruneSnapshots(snapshotsDir: string, retain: number): void;
-/**
- * Truncate a JSONL file to its last `retain` non-empty lines. No-op when the
- * file is missing or already within budget — the common case costs one
- * read and no write.
- */
-export declare function pruneJsonlFile(path: string, retain: number): void;
-/** Reviews audit-trail path shared by the gate, fate, and tool events. */
-export declare function reviewsPath(baseDir: string): string;
-/** Read the applied results history; malformed lines are skipped, never fatal. */
-export declare function loadResults(paths: StorePaths): RefinementResult[];
-//# sourceMappingURL=store.d.ts.map

package/lib/store.js

@@ -1,164 +0,0 @@
-/**
- * Store layout and snapshot discipline for the evolution plugin.
- *
- * Layout (self-contained under the DSH home; no dependency on session
- * persistence internals):
- *
- *   <dshHome>/evolve/global/harness_state.json    cross-project store
- *   <dshHome>/evolve/global/refinements.jsonl     applied results (rollback source)
- *   <dshHome>/evolve/projects/<slug-hash>/...     per-project store
- *   <dshHome>/evolve/local/<sessionId>/...        per-session staging store
- *
- * Snapshot discipline is code-enforced: before any mutating apply, the
- * pre-apply state is copied to `snapshots/<refinementId>.json`. The model has
- * no way to skip it — it runs inside the service, not in a prompt.
- */
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { sanitizeProjectKey } from "./project.js";
-import { stateFilePath } from "./state.js";
-export const EVOLVE_DIR = "evolve";
-/**
- * Storage-hygiene defaults (#20): history used to grow append-only without
- * bound (dozens of full-state snapshot copies, unbounded JSONL). Retention
- * is count-based and generous — rollback only ever needs recent snapshots
- * and readers (`failures.ts` over reviews) need a working window, not the
- * full past. Tunable via the `historyRetain` plugin config.
- */
-export const DEFAULT_SNAPSHOT_RETAIN = 20;
-export const DEFAULT_REFINEMENTS_RETAIN = 500;
-export const DEFAULT_REVIEWS_RETAIN = 500;
-export const DEFAULT_TOKEN_USAGE_RETAIN = 500;
-/** Defaults applied for absent / non-positive retention fields (fail loud never: clamp, don't throw). */
-export function resolveHistoryRetention(raw) {
-    const pick = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
-    return {
-        snapshots: pick(raw?.snapshots, DEFAULT_SNAPSHOT_RETAIN),
-        refinements: pick(raw?.refinements, DEFAULT_REFINEMENTS_RETAIN),
-        reviews: pick(raw?.reviews, DEFAULT_REVIEWS_RETAIN),
-        tokenUsage: pick(raw?.tokenUsage, DEFAULT_TOKEN_USAGE_RETAIN),
-    };
-}
-/**
- * Resolve store paths for a scope. For `project` the `sessionId` parameter
- * carries the project key (see {@link resolveProjectKey} in project.ts) —
- * it is sanitized to a single path segment so an externally supplied key
- * can never traverse out of `evolve/projects/`.
- */
-export function storePaths(baseDir, scope, sessionId) {
-    const scopeDir = scope === "global" ? "global" : scope === "project" ? join("projects", sanitizeProjectKey(sessionId ?? "project")) : join("local", sessionId ?? "anonymous");
-    const stateDir = join(baseDir, EVOLVE_DIR, scopeDir);
-    return {
-        stateDir,
-        snapshotsDir: join(stateDir, "snapshots"),
-        resultsPath: join(stateDir, "refinements.jsonl"),
-    };
-}
-/** Snapshot the current state file before a mutation, if one exists. */
-export function snapshotBefore(paths, refinementId) {
-    const statePath = stateFilePath(paths.stateDir);
-    if (!existsSync(statePath)) {
-        return;
-    }
-    mkdirSync(paths.snapshotsDir, { recursive: true });
-    // 0600: the snapshot is a full copy of harness_state.json — same
-    // permission discipline as the store itself (review audit 2026-08-28 S5).
-    writeFileSync(join(paths.snapshotsDir, `${refinementId}.json`), readFileSync(statePath, "utf8"), { encoding: "utf8", mode: 0o600 });
-}
-/** Append an applied result to the store's JSONL history. */
-export function appendResult(paths, result) {
-    mkdirSync(paths.stateDir, { recursive: true });
-    writeFileSync(paths.resultsPath, `${JSON.stringify(result)}\n`, { encoding: "utf8", flag: "a" });
-}
-/**
- * Prune a store's snapshots to the newest `retain` files (by mtime, oldest
- * first). Best-effort: a missing directory or an unlink failure never breaks
- * the apply path — the next apply retries.
- */
-export function pruneSnapshots(snapshotsDir, retain) {
-    const keep = Math.floor(retain);
-    if (!(keep > 0) || !existsSync(snapshotsDir))
-        return;
-    let files;
-    try {
-        files = readdirSync(snapshotsDir).filter((f) => f.endsWith(".json"));
-    }
-    catch {
-        return; // unreadable directory — leave it for the next attempt
-    }
-    if (files.length <= keep)
-        return;
-    const withTime = [];
-    for (const file of files) {
-        try {
-            withTime.push({ file, mtime: statSync(join(snapshotsDir, file)).mtimeMs });
-        }
-        catch {
-            // unstatable file — keep it rather than delete blindly
-        }
-    }
-    withTime.sort((a, b) => a.mtime - b.mtime);
-    for (const victim of withTime.slice(0, Math.max(0, withTime.length - keep))) {
-        try {
-            unlinkSync(join(snapshotsDir, victim.file));
-        }
-        catch {
-            // one bad unlink must not stop the sweep or the apply path
-        }
-    }
-}
-/**
- * Truncate a JSONL file to its last `retain` non-empty lines. No-op when the
- * file is missing or already within budget — the common case costs one
- * read and no write.
- */
-export function pruneJsonlFile(path, retain) {
-    const keep = Math.floor(retain);
-    if (!(keep > 0) || !existsSync(path))
-        return;
-    let lines;
-    try {
-        lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
-    }
-    catch {
-        return; // unreadable file — leave it for the next attempt
-    }
-    if (lines.length <= keep)
-        return;
-    try {
-        writeFileSync(path, `${lines.slice(-keep).join("\n")}\n`, "utf8");
-    }
-    catch {
-        // truncation failure must not break the write path that called it
-    }
-}
-/** Reviews audit-trail path shared by the gate, fate, and tool events. */
-export function reviewsPath(baseDir) {
-    return join(baseDir, EVOLVE_DIR, "reviews.jsonl");
-}
-/** Read the applied results history; malformed lines are skipped, never fatal. */
-export function loadResults(paths) {
-    if (!existsSync(paths.resultsPath)) {
-        return [];
-    }
-    const results = [];
-    for (const line of readFileSync(paths.resultsPath, "utf8").split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        try {
-            const parsed = JSON.parse(trimmed);
-            if (isResult(parsed)) {
-                results.push(parsed);
-            }
-        }
-        catch {
-            // skip malformed line
-        }
-    }
-    return results;
-}
-function isResult(data) {
-    return typeof data === "object" && data !== null && "id" in data && "appliedEdits" in data;
-}
-//# sourceMappingURL=store.js.map

package/lib/token-usage.d.ts

@@ -1,68 +0,0 @@
-import type { TokenUsage } from "@deepseek-ai/dsh-llm";
-import type { StreamTextObservation, StreamTextUsageObserver } from "./llm-text.js";
-export declare const TOKEN_USAGE_LEDGER_VERSION = 1;
-/** Plugin-owned direct call paths represented in the ledger. */
-export declare const TOKEN_USAGE_PHASES: readonly ["review", "memory", "planner", "wrapup", "fate"];
-export type TokenUsagePhase = (typeof TOKEN_USAGE_PHASES)[number];
-/** Whether the provider supplied a usage sample; missing is never treated as zero. */
-export type TokenUsageStatus = "reported" | "missing";
-/** How the exact full-call total was obtained. */
-export type TokenTotalSource = "provider" | "derived" | "unavailable";
-/** One retained direct-call observation. */
-export interface TokenUsageRecord {
-    version: typeof TOKEN_USAGE_LEDGER_VERSION;
-    timestamp: string;
-    sessionId: string;
-    phase: TokenUsagePhase;
-    provider: string;
-    model: string;
-    outcome: StreamTextObservation["outcome"];
-    usageStatus: TokenUsageStatus;
-    /** Absent exactly when {@link usageStatus} is `missing`. */
-    usage?: TokenUsage;
-    totalSource: TokenTotalSource;
-}
-/** Caller-owned destination and failure hook; phase/provider/model are supplied by the call site. */
-export interface TokenUsageTarget {
-    baseDir: string;
-    sessionId: string;
-    retain: number;
-    onError?: (cause: unknown) => void;
-}
-/** Loaded retained window plus corrupt-line count for honest coverage reporting. */
-export interface LoadedTokenUsage {
-    records: TokenUsageRecord[];
-    corruptLines: number;
-}
-/** Aggregate provider-reported buckets over a retained ledger window. */
-export interface TokenUsageTotals {
-    calls: number;
-    reportedCalls: number;
-    missingUsageCalls: number;
-    uncachedInputTokens: number;
-    cacheReadTokens: number;
-    cacheWriteTokens: number;
-    outputTokens: number;
-    reasoningTokens: number;
-    totalTokens: number;
-}
-/** Absolute path of the direct-call token ledger. */
-export declare function tokenUsagePath(baseDir: string): string;
-/** Exact full-call total, with the old-peer fallback only when `totalTokens` is absent. */
-export declare function exactTokenTotal(usage: TokenUsage): number;
-/** Build the observer attached to one `streamText` call. Errors are diagnostic-only. */
-export declare function createTokenUsageObserver(target: TokenUsageTarget, phase: TokenUsagePhase, provider: string, model: string): StreamTextUsageObserver;
-/**
- * Append one call and enforce the dedicated tail budget. Append + conditional
- * prune stay in one synchronous block, so concurrent async callers in one DSH
- * process cannot interleave the read/truncate/write. Multiple DSH processes
- * sharing one baseDir are outside the plugin's storage contract.
- */
-export declare function appendTokenUsage(target: TokenUsageTarget, record: TokenUsageRecord): void;
-/** Load valid records from the retained ledger; malformed lines never break `/evolve usage`. */
-export declare function loadTokenUsage(baseDir: string): LoadedTokenUsage;
-/** Sum exact provider-reported buckets without double-counting reasoning or cache fields. */
-export declare function aggregateTokenUsage(records: readonly TokenUsageRecord[]): TokenUsageTotals;
-/** Render the human-facing direct-call ledger section. */
-export declare function renderTokenUsageReport(ledger: LoadedTokenUsage, retain: number): string[];
-//# sourceMappingURL=token-usage.d.ts.map