dsh-continual-evolve 0.6.1 → 0.7.1

package/lib/prefix-cache.js

@@ -0,0 +1,168 @@
+/**
+ * Prefix-cache-aware planning input routing (Route A/B).
+ *
+ * The planner and the review gate re-send session context on every call as
+ * flat text. On providers with prompt caching that context is re-billed at
+ * full price each time. Route A instead prepends session-derived messages —
+ * the same evidence in structured form, eligible for cache-read pricing —
+ * and drops the redundant flat trajectory block. Route B keeps the legacy
+ * flat-text input byte-for-byte.
+ *
+ * Adapted from dsh-continual-harness (Route A/B + cache-detect): this port
+ * deliberately does NOT reproduce the host loop's byte-identical cache key
+ * (no deriveMessages/tools/sessionId plumbing on this seam), so a hit needs
+ * a provider that keys on the message-prefix content. Sources are stamped
+ * honestly and every reduction is documented below.
+ */
+import { createAssistantMessage, createUserMessage } from "@deepseek-ai/dsh-llm";
+/** Default session-prefix budget for one Route A input, in characters. */
+export const DEFAULT_PREFIX_MAX_CHARS = 12000;
+/**
+ * Resolve per-call overrides against the defaults.
+ *
+ * @param opts - sparse per-call overrides.
+ * @returns the effective mode (default "auto") and char budget.
+ * @throws When maxChars is present but not a positive safe integer (fail loud on misconfiguration).
+ */
+export function resolvePrefixCache(opts) {
+    const mode = opts?.mode ?? "auto";
+    const maxChars = opts?.maxChars ?? DEFAULT_PREFIX_MAX_CHARS;
+    if (!Number.isSafeInteger(maxChars) || maxChars < 1) {
+        throw new Error(`evolve: prefix-cache maxChars must be a positive integer, got ${String(opts?.maxChars)}`);
+    }
+    return { mode, maxChars };
+}
+/**
+ * True when any assistant message in this session reported cache-read
+ * tokens — evidence the provider can serve a warm prefix.
+ *
+ * @param events - session log rows, newest last.
+ * @returns whether cache evidence exists (false on an empty/unreadable log).
+ */
+export function hasCacheEvidence(events) {
+    for (const raw of events) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const event = raw;
+        if (event.type !== "assistant/message")
+            continue;
+        const read = event.data?.usage?.cacheReadTokens;
+        if (typeof read === "number" && read > 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Pick the planning input route for one call.
+ *
+ * @param events - session log rows, newest last.
+ * @param mode - routing mode (default "auto").
+ * @returns "A" when the session prefix should carry the context, else "B".
+ */
+export function detectPlannerRoute(events, mode) {
+    const resolved = mode ?? "auto";
+    if (resolved === "session")
+        return "A";
+    if (resolved === "off")
+        return "B";
+    return hasCacheEvidence(events) ? "A" : "B";
+}
+/**
+ * Extract one message's text without depending on the dsh-llm ContentBlock
+ * type: string blocks pass through, object blocks contribute their `text`
+ * field when present. Non-text blocks (tool calls, images) are dropped.
+ */
+function blockText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (typeof block === "string") {
+            parts.push(block);
+        }
+        else if (block !== null && typeof block === "object" && "text" in block && typeof block.text === "string") {
+            parts.push(block.text);
+        }
+    }
+    return parts.filter((text) => text.length > 0).join(" ");
+}
+/**
+ * Rebuild a tail-biased session prefix from the event log.
+ *
+ * Inclusion mirrors the trajectory grounding (only direct human `user`
+ * speech plus the model's own assistant text), so injected plugin context
+ * and tool results never echo back into the planning input. Whole messages
+ * are dropped oldest-first over budget; a single over-budget message keeps
+ * its tail.
+ *
+ * @param events - session log rows, newest last.
+ * @param opts - provider/model stamps the assistant messages (the calling
+ * agent's own route); maxChars caps the prefix (default {@link DEFAULT_PREFIX_MAX_CHARS}).
+ * @returns the prefix messages, oldest first ([] when nothing qualifies —
+ * callers fall back to Route B).
+ * @throws When assistant text exists but provider/model is missing (an
+ * assistant message cannot be honestly stamped without its route).
+ */
+export function buildPrefixMessages(events, opts) {
+    const maxChars = opts.maxChars ?? DEFAULT_PREFIX_MAX_CHARS;
+    if (!Number.isSafeInteger(maxChars) || maxChars < 1) {
+        throw new Error(`evolve: prefix-cache maxChars must be a positive integer, got ${String(opts.maxChars)}`);
+    }
+    const pairs = [];
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const raw = events[i];
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const event = raw;
+        const isUser = event.type === "user/message";
+        const isAssistant = event.type === "assistant/message";
+        if (!isUser && !isAssistant)
+            continue;
+        if (isUser) {
+            const kind = event.data?.source?.kind;
+            if (kind !== undefined && kind !== "user")
+                continue;
+        }
+        const text = blockText(event.data?.content).trim();
+        if (text.length === 0)
+            continue;
+        pairs.push({ role: isUser ? "user" : "assistant", text });
+    }
+    if (pairs.length === 0)
+        return [];
+    // Collected newest-first; restore conversation order before budgeting.
+    pairs.reverse();
+    // Tail-biased budget: drop oldest whole messages over budget; a lone
+    // over-budget message keeps its tail.
+    let total = pairs.reduce((sum, pair) => sum + pair.text.length, 0);
+    while (pairs.length > 1 && total > maxChars) {
+        const dropped = pairs.shift();
+        total -= dropped?.text.length ?? 0;
+    }
+    const oldest = pairs[0];
+    if (oldest !== undefined && total > maxChars) {
+        oldest.text = oldest.text.slice(-maxChars);
+    }
+    const messages = [];
+    for (const pair of pairs) {
+        if (pair.role === "user") {
+            messages.push(createUserMessage({
+                source: { kind: "user" },
+                content: [{ type: "text", text: pair.text }],
+            }));
+        }
+        else {
+            if (!opts.provider || !opts.model) {
+                throw new Error("evolve: prefix-cache needs the agent provider/model to stamp assistant messages");
+            }
+            messages.push(createAssistantMessage({
+                source: { provider: opts.provider, model: opts.model },
+                content: [{ type: "text", text: pair.text }],
+            }));
+        }
+    }
+    return messages;
+}
+//# sourceMappingURL=prefix-cache.js.map

package/lib/project.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Stable project key for a workspace. `workspaceIdentity` (when set)
+ * replaces the path as the hash source so renamed checkouts of the same
+ * logical project keep one store.
+ */
+export declare function resolveProjectKey(workspacePath: string, workspaceIdentity?: string): string;
+/** Defense for externally supplied keys (explicit opts): single safe segment. */
+export declare function sanitizeProjectKey(key: string): string;
+/** Minimal agent shape the project-key derivation needs (duck-typed). */
+export interface ProjectKeyAgentLike {
+    session?: {
+        header?: {
+            cwd?: unknown;
+            meta?: {
+                cwd?: unknown;
+            };
+        };
+    };
+}
+/**
+ * Derive the project key from an assembling agent's session cwd. Returns
+ * undefined when no validated absolute cwd is present — the caller then
+ * skips the project layer rather than failing the whole assembly.
+ */
+export declare function projectKeyOf(agent: unknown, opts?: {
+    workspaceIdentity?: string;
+}): string | undefined;
+//# sourceMappingURL=project.d.ts.map

package/lib/project.js

@@ -0,0 +1,66 @@
+/**
+ * Project scope identity: the third harness layer between session-local
+ * staging and the cross-project global store.
+ *
+ * A project is identified by the session's validated absolute `cwd`
+ * (stable slug + sha256, mirroring ZCode's `project-root.ts`), so every
+ * session opened in the same workspace shares one project store while
+ * different checkouts never collide. All helpers are pure and never throw —
+ * a missing cwd simply means "no project layer" (the caller degrades to
+ * global+local, the same shape as an empty project store).
+ */
+import { createHash } from "node:crypto";
+import { basename, isAbsolute, resolve } from "node:path";
+/**
+ * Stable project key for a workspace. `workspaceIdentity` (when set)
+ * replaces the path as the hash source so renamed checkouts of the same
+ * logical project keep one store.
+ */
+export function resolveProjectKey(workspacePath, workspaceIdentity) {
+    const identity = workspaceIdentity?.trim();
+    const normalized = resolve(workspacePath);
+    const keySource = identity && identity.length > 0 ? identity : process.platform === "win32" ? normalized.toLowerCase() : normalized;
+    const hash = createHash("sha256").update(keySource).digest("hex").slice(0, 16);
+    const slug = identity && identity.length > 0 ? "project" : sanitizeSlug(basename(normalized) || "project");
+    return `${slug}-${hash}`;
+}
+function sanitizeSlug(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    return slug.length > 0 ? slug : "project";
+}
+/** Defense for externally supplied keys (explicit opts): single safe segment. */
+export function sanitizeProjectKey(key) {
+    const cleaned = key
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return cleaned.length > 0 ? cleaned : "project";
+}
+/**
+ * Derive the project key from an assembling agent's session cwd. Returns
+ * undefined when no validated absolute cwd is present — the caller then
+ * skips the project layer rather than failing the whole assembly.
+ */
+export function projectKeyOf(agent, opts) {
+    try {
+        const header = agent?.session?.header;
+        const raw = header?.cwd ?? header?.meta?.cwd;
+        if (typeof raw !== "string" || raw.trim().length === 0) {
+            return undefined;
+        }
+        const cwd = raw.trim();
+        if (!isAbsolute(cwd)) {
+            return undefined;
+        }
+        return resolveProjectKey(cwd, opts?.workspaceIdentity);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=project.js.map

package/lib/review.d.ts

@@ -8,6 +8,8 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { HarnessState, RefinementResult } from "./types.js";
+import { type PrefixCacheOptions } from "./prefix-cache.js";
+import { type TokenUsageTarget } from "./token-usage.js";
 export interface AutoRefineReview {
     shouldRefine: boolean;
     rationale: string;
@@ -30,6 +32,15 @@ export interface ReviewOptions {
     /** Gap C1: optional provider/model override for the review gate (cheaper model). */
     overrideProvider?: string;
     overrideModel?: string;
+    /**
+     * Prefix-cache routing for the gate input. Route A prepends a
+     * session-derived message prefix and drops the flat `<conversation>`
+     * block (same source, structured form); Route B keeps it. Absent →
+     * auto-detect with the default budget.
+     */
+    prefixCache?: PrefixCacheOptions;
+    /** Direct-call token ledger destination; the review phase is fixed by this module. */
+    tokenUsage?: TokenUsageTarget;
 }
 export declare const AUTO_REVIEW_SYSTEM_PROMPT = "You are the automatic /evolve review gate.\n\nDecide whether this checkpoint should run /evolve. Auto /evolve writes local\nharness state by default, so approve when the trajectory contains evidence\nuseful to this session's future turns: a repeated failure, a reusable tactic,\na repeated delegation role, a durable fact or preference, a user correction\nthat should persist, or a narrow behavioral policy.\n\nThe current harness state below includes GLOBAL entries (scope=global) plus\nthis session's local entries (scope=local). When a topic is already covered\nby a global entry, do NOT approve a local duplicate of it \u2014 decline and say\nin the rationale that the topic is already covered globally.\n\nReject one-off noise, unsupported hypotheses, transient tool outputs, and\nrequests that carry no reusable content.\n\nStale local entries (superseded, long-unused, obsolete facts) are a valid\nrefine target: approve with instructions naming the entry ids, and tell the\nplanner to archive them (archive hides from injection, data stays restorable)\nrather than delete.\n\nSkill-related trajectories (the evidence concerns creating or improving a\nskill entry) are judged against the DSH skill quality standard (skill-audit\ndimensions: frontmatter routing, the 7 structural features, paragraph\nskeleton, no duplication of the official 11 skills or covered skills).\nApprove only when the trajectory shows a REAL trigger scenario and the\nresulting skill would meet the standard; otherwise decline and say in the\nrationale what must improve \u2014 drafting follows skill-creator, and the\nplanner receives the standard as its <skill_quality_standard> block.\n\nRepeated multi-step workflows (session start/end routines, recurring\nwrap-up or handoff procedures) are a valid refine target: approve with\ninstructions telling the planner to propose a guidance skill (kind=skill,\nskill_kind=guidance \u2014 a SKILL.md document, no python reference). Only\npropose when the same workflow recurs in the trajectory \u2014 never for\none-off flows. Auto-created skills are always offered to the user for a\ndecision before they land; the gate never writes a skill silently.\n\nReturn JSON only:\n{\n  \"shouldRefine\": true|false,\n  \"rationale\": \"short reason\",\n  \"instructions\": \"optional concise instructions for /evolve if shouldRefine is true\"\n}";
 /** Parse the gate's JSON reply. */

package/lib/review.js

@@ -1,6 +1,9 @@
 import { extractJsonObject } from "./plan.js";
 import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
+import { sessionEventsOf } from "./inject.js";
+import { buildPrefixMessages, detectPlannerRoute, resolvePrefixCache } from "./prefix-cache.js";
 import { streamText } from "./llm-text.js";
+import { createTokenUsageObserver } from "./token-usage.js";
 export const AUTO_REVIEW_SYSTEM_PROMPT = `You are the automatic /evolve review gate.
 
 Decide whether this checkpoint should run /evolve. Auto /evolve writes local
@@ -96,13 +99,29 @@ export async function reviewAutoRefine(ctx, options) {
     if (!options.trajectory || options.trajectory.length === 0) {
         throw new Error("evolve: review gate has no trajectory to judge");
     }
+    // Route A carries the judged conversation as a session-derived message
+    // prefix and drops the flat block; an empty prefix falls back to B.
+    const events = sessionEventsOf(agent);
+    const routing = resolvePrefixCache(options.prefixCache);
+    const route = detectPlannerRoute(events, routing.mode);
+    let prefixMessages = [];
+    if (route === "A") {
+        prefixMessages = buildPrefixMessages(events, {
+            ...(provider ? { provider } : {}),
+            ...(model ? { model } : {}),
+            maxChars: routing.maxChars,
+        });
+    }
+    const conversationBlock = prefixMessages.length > 0 ? "" : `<conversation>\n${options.trajectory}\n</conversation>`;
     const userPrompt = [
         `<trigger>\n${options.context.reason}; ${options.context.turnsSinceLastReview} turns since the last review\n</trigger>`,
         `<current_harness_state>\n${formatHarnessStateForPrompt(state)}\n</current_harness_state>`,
         `<refinement_history>\n${historyForPrompt(history)}\n</refinement_history>`,
-        `<conversation>\n${options.trajectory}\n</conversation>`,
+        conversationBlock,
         "Return shouldRefine=true when the trajectory contains evidence useful to this session's future turns. Prefer local edits; do not ask for global refinement here.",
-    ].join("\n\n");
+    ]
+        .filter(Boolean)
+        .join("\n\n");
     const text = await streamText(ctx, {
         provider,
         model,
@@ -110,6 +129,8 @@ export async function reviewAutoRefine(ctx, options) {
         prompt: userPrompt,
         maxTokens: options.budgetTokens ?? 8000,
         signal: options.signal,
+        ...(prefixMessages.length > 0 ? { prefixMessages } : {}),
+        ...(options.tokenUsage ? { onUsage: createTokenUsageObserver(options.tokenUsage, "review", provider, model) } : {}),
     });
     return parseAutoRefineReview(text);
 }

package/lib/runtime.d.ts

@@ -0,0 +1,24 @@
+export interface GateRuntime {
+    version: 1;
+    /** True while the human paused the automatic review gate. */
+    paused: boolean;
+    /** ISO timestamp of the last pause/resume write. */
+    updatedAt: string;
+}
+/** Full path of the runtime switch file. */
+export declare function runtimePath(baseDir: string): string;
+/**
+ * Load the runtime switch; fail open to "running" on any unreadable or
+ * malformed content (called on every gate trigger, so it must never throw
+ * for a bad file).
+ */
+export declare function loadGateRuntime(baseDir: string): GateRuntime;
+/**
+ * Persist the pause switch atomically (temp file + rename). Never throws
+ * for a bad file — callers (pause/resume commands) surface real IO errors
+ * through the command's own error path instead.
+ */
+export declare function saveGateRuntime(baseDir: string, paused: boolean): string;
+/** True while the human paused the automatic review gate (fail-open). */
+export declare function isGatePaused(baseDir: string): boolean;
+//# sourceMappingURL=runtime.d.ts.map

package/lib/runtime.js

@@ -0,0 +1,83 @@
+/**
+ * Runtime gate switch (#21 P2): a tiny human-owned file that pauses the
+ * automatic review gate without touching the plugin config or restarting.
+ *
+ * - file: `<baseDir>/evolve/runtime.json` (`{version, paused, updatedAt}`)
+ * - `/evolve pause` sets paused, `/evolve resume` clears it, `/evolve
+ *   status` shows it alongside the static patch config.
+ * - the gate consults it on every trigger (turn-interval AND compaction)
+ *   and stays dormant while paused — manual tools/commands keep working.
+ * - fail-open: a missing or corrupt file means "running". Pausing is the
+ *   exceptional state; a broken file must never silently wedge the gate
+ *   shut (the next save rewrites it cleanly).
+ */
+import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { EVOLVE_DIR } from "./store.js";
+const RUNTIME_FILE = "runtime.json";
+/** Full path of the runtime switch file. */
+export function runtimePath(baseDir) {
+    return join(baseDir, EVOLVE_DIR, RUNTIME_FILE);
+}
+function running() {
+    return { version: 1, paused: false, updatedAt: new Date(0).toISOString() };
+}
+/**
+ * Load the runtime switch; fail open to "running" on any unreadable or
+ * malformed content (called on every gate trigger, so it must never throw
+ * for a bad file).
+ */
+export function loadGateRuntime(baseDir) {
+    const path = runtimePath(baseDir);
+    if (!existsSync(path)) {
+        return running();
+    }
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            return running();
+        }
+        const record = raw;
+        return {
+            version: 1,
+            paused: record["paused"] === true,
+            updatedAt: typeof record["updatedAt"] === "string" ? record["updatedAt"] : new Date(0).toISOString(),
+        };
+    }
+    catch {
+        return running();
+    }
+}
+/**
+ * Persist the pause switch atomically (temp file + rename). Never throws
+ * for a bad file — callers (pause/resume commands) surface real IO errors
+ * through the command's own error path instead.
+ */
+export function saveGateRuntime(baseDir, paused) {
+    const path = runtimePath(baseDir);
+    mkdirSync(join(baseDir, EVOLVE_DIR), { recursive: true });
+    const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const payload = { version: 1, paused, updatedAt: new Date().toISOString() };
+    writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    try {
+        renameSync(tempPath, path);
+    }
+    finally {
+        if (existsSync(tempPath)) {
+            unlinkSync(tempPath);
+        }
+    }
+    return path;
+}
+/** True while the human paused the automatic review gate (fail-open). */
+export function isGatePaused(baseDir) {
+    try {
+        return loadGateRuntime(baseDir).paused;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/lib/service.d.ts

@@ -5,6 +5,7 @@
  */
 import type { EntrySource, HarnessScope, RefinementProposal, RefinementResult } from "./types.js";
 import { applyRefinementProposal } from "./apply.js";
+import type { HistoryRetention } from "./store.js";
 export interface ApplyContext {
     scope: HarnessScope;
     sessionId?: string;
@@ -19,12 +20,21 @@ export interface EvolutionHooks {
     /** Called after every applied refinement (side-effect boundary: skills sync, etc.). */
     onApplied?: (result: RefinementResult) => void;
 }
-export declare function createEvolutionEngine(baseDir: string, hooks?: EvolutionHooks): {
+export interface EvolutionEngineOptions {
+    /**
+     * Storage-hygiene retention (#20): how many snapshots / JSONL tail
+     * lines each apply keeps. Resolved with generous defaults — rollback
+     * only needs recent snapshots and readers need a working window.
+     */
+    historyRetain?: Partial<HistoryRetention>;
+}
+export declare function createEvolutionEngine(baseDir: string, hooks?: EvolutionHooks, opts?: EvolutionEngineOptions): {
     load: (scope: HarnessScope, sessionId: string | undefined) => import("./types.js").HarnessState;
     apply: (scope: HarnessScope, sessionId: string | undefined, proposal: RefinementProposal, context?: ApplyContext) => RefinementResult;
     rollback: (scope: HarnessScope, sessionId: string | undefined, refinementId: string) => RefinementResult;
     history: (scope: HarnessScope, sessionId: string | undefined) => RefinementResult[];
     baseDir: string;
+    retention: HistoryRetention;
 };
 export type EvolutionEngine = ReturnType<typeof createEvolutionEngine>;
 //# sourceMappingURL=service.d.ts.map

package/lib/service.js

@@ -3,9 +3,15 @@ import { applyRefinementProposal } from "./apply.js";
 import { randomUUID } from "node:crypto";
 import { rollbackProposal } from "./rollback.js";
 import { loadHarnessState, saveHarnessState } from "./state.js";
-import { appendResult, loadResults, snapshotBefore, storePaths } from "./store.js";
+import { appendResult, loadResults, pruneJsonlFile, pruneSnapshots, resolveHistoryRetention, snapshotBefore, storePaths } from "./store.js";
 import { CONFLICT_BLOCK_SCORE, CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry, secretLeakReason } from "./promotion.js";
-export function createEvolutionEngine(baseDir, hooks = {}) {
+export function createEvolutionEngine(baseDir, hooks = {}, opts = {}) {
+    const retention = resolveHistoryRetention(opts.historyRetain);
+    /**
+     * Load a scope's state. For `project` the `sessionId` parameter carries
+     * the project key (see `resolveProjectKey` in project.ts); callers
+     * derive it with `projectKeyOf(agent)` and pass it through unchanged.
+     */
     function load(scope, sessionId) {
         return loadHarnessState(storePaths(baseDir, scope, sessionId).stateDir, scope);
     }
@@ -95,6 +101,21 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
         }
         saveHarnessState(paths.stateDir, state);
         appendResult(paths, result);
+        // Storage hygiene (#20): bound the append-only past at write time —
+        // snapshots keep the newest N, the per-store history keeps its tail.
+        // Best-effort (never throws): a prune failure must not fail the apply.
+        try {
+            pruneSnapshots(paths.snapshotsDir, retention.snapshots);
+        }
+        catch {
+            // ignored — the next apply retries
+        }
+        try {
+            pruneJsonlFile(paths.resultsPath, retention.refinements);
+        }
+        catch {
+            // ignored — the next apply retries
+        }
         hooks.onApplied?.(result);
         return result;
     }
@@ -114,6 +135,6 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
     function history(scope, sessionId) {
         return loadResults(storePaths(baseDir, scope, sessionId));
     }
-    return { load, apply, rollback, history, baseDir };
+    return { load, apply, rollback, history, baseDir, retention };
 }
 //# sourceMappingURL=service.js.map

package/lib/state.d.ts

@@ -7,11 +7,15 @@ export declare function stateFilePath(stateDir: string): string;
  */
 export declare function loadHarnessState(stateDir: string, scope?: HarnessScope): HarnessState;
 /**
- * Merge global and local state into the view the model sees. Local entries
- * win over same-id global entries; a colliding local id is prefixed
- * `local:` so both remain addressable.
+ * 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): HarnessState;
+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).

package/lib/state.js

@@ -20,7 +20,7 @@ export function stateFilePath(stateDir) {
     return join(stateDir, "harness_state.json");
 }
 function normalizeScope(value, fallback) {
-    return value === "global" || value === "local" ? value : fallback;
+    return value === "global" || value === "project" || value === "local" ? value : fallback;
 }
 function objectRecord(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -95,24 +95,31 @@ export function loadHarnessState(stateDir, scope = "global") {
     return state;
 }
 /**
- * Merge global and local state into the view the model sees. Local entries
- * win over same-id global entries; a colliding local id is prefixed
- * `local:` so both remain addressable.
+ * 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) {
+export function mergeHarnessStates(globalState, localState, opts) {
     const merged = emptyHarnessState();
-    merged.schema = Math.max(globalState.schema, localState?.schema ?? 1);
+    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, ...(localState?.refinements ?? [])];
+    merged.refinements = [...globalState.refinements, ...(opts?.projectState?.refinements ?? []), ...(localState?.refinements ?? [])];
     return merged;
 }
 /**

package/lib/store.d.ts

@@ -1,5 +1,29 @@
 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;
@@ -8,11 +32,31 @@ export interface StorePaths {
     /** 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