dsh-continual-evolve 0.11.0 → 0.12.1

package/lib/types.d.ts

@@ -1,218 +0,0 @@
-/** What a harness entry can be. */
-export type RefinementKind = "prompt" | "memory" | "skill" | "subagent";
-/**
- * Skill-entry form: `executable` skills carry a python reference contract
- * and can be hot-mounted as tools; `guidance` skills are SKILL.md documents
- * (no python reference) that materialize as discoverable skills for the
- * `skill` tool — the form for recurring multi-step workflows. Absent means
- * `executable` (backwards compatible with pre-guidance stores).
- */
-export type SkillKind = "executable" | "guidance";
-/** How an entry changes. */
-export type RefinementAction = "create" | "update" | "delete" | "archive";
-/** Where an entry lives: session staging, one project, or cross-project. */
-export type HarnessScope = "local" | "project" | "global";
-/**
- * Memory-entry shape discipline (one fact per entry, typed like ZCode's
- * memory frontmatter): every `memory` create must stamp one of these in
- * `metadata[MEMORY_TYPE_KEY]` — the recall hook the directory shows.
- */
-export declare const MEMORY_TYPE_KEY = "memoryType";
-/** Closed memory-type set: user | feedback | project | reference. */
-export declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
-/** One of {@link MEMORY_TYPES}. */
-export type MemoryRecallType = (typeof MEMORY_TYPES)[number];
-/** True when the value is a closed-set memory type. */
-export declare function isMemoryType(value: unknown): value is MemoryRecallType;
-/**
- * Metadata key recording which session an entry's content was distilled from
- * (trajectory citation; see {@link EntrySource}).
- */
-export declare const SOURCE_SESSION_KEY = "sourceSession";
-/**
- * Metadata key recording the session-log event seqs (of the direct user
- * messages) the entry cites as its source (trajectory citation).
- */
-export declare const SOURCE_SEQS_KEY = "sourceSeqs";
-/**
- * Metadata key recording when an entry was archived. Archived entries are
- * hidden from injection but never deleted — the data stays in the store and
- * the entry can be restored (unarchive) or rolled back like any other edit.
- */
-export declare const ARCHIVED_AT_KEY = "archivedAt";
-/**
- * Metadata key stamped on a LOCAL entry that was promoted to the global
- * store by a session wrap-up: the id of the global entry it became. Present
- * means the entry's lifecycle is finished — it must not be offered for
- * promotion again (the global copy is the live one, the local copy is a
- * restorable trace).
- */
-export declare const PROMOTED_TO_KEY = "promotedTo";
-/**
- * Metadata key recording when a local entry was promoted to the global
- * store (companion of {@link PROMOTED_TO_KEY}).
- */
-export declare const PROMOTED_AT_KEY = "promotedAt";
-/**
- * Metadata key stamped on a GLOBAL entry created by a session wrap-up
- * promotion: `<sessionId>:<localEntryId>` — the反向 provenance link from the
- * cross-session copy back to the session it was distilled from.
- */
-export declare const SOURCED_FROM_KEY = "sourcedFromLocal";
-/**
- * Metadata key stamped on a GLOBAL entry that was created despite a
- * moderate-similarity overlap with an existing entry (write-time conflict
- * guard, warn tier): `<kind>:<id>:<score>` — points at the entry it may
- * duplicate so wrapup/fate can consolidate later. Creates at/above the block
- * threshold never reach this stamp; they are rejected outright.
- */
-export declare const CONFLICT_HINT_KEY = "conflictHint";
-/**
- * Negative-valence counter (P1 效价反馈): how many times an assessment marked
- * this entry contradicted by newer evidence (user correction, overridden
- * fact). Injection ranking demotes entries with a positive counter and the
- * wrapup/fate assessors see the count so they prefer archiving the entry.
- */
-export declare const VALENCE_NEGATIVE_KEY = "valenceNegative";
-/**
- * Provenance of entries merged INTO this one by the consolidation command
- * (P1 反膨胀): array of `<kind>:<id>` — the near-duplicate sources whose
- * content was appended before they archived. The trail keeps an unarchive of
- * the source explainable and lets audits find the merge provenance.
- */
-export declare const MERGED_FROM_KEY = "mergedFrom";
-/**
- * True when the entry is archived (hidden from injection, restorable).
- * Absent or empty archivedAt means the entry is active.
- */
-export declare function isArchived(entry: HarnessEntry): boolean;
-/**
- * Trajectory citation attached to newly created entries: the session the
- * content came from and the seqs of the direct user messages it was
- * distilled from. Both fields are optional — when they cannot be determined
- * the citation is simply omitted (never an error).
- */
-export interface EntrySource {
-    sessionId?: string;
-    /** Event seqs of the source user messages, in log order. */
-    seqs?: number[];
-}
-/** A single persisted harness entry. */
-export interface HarnessEntry {
-    id: string;
-    kind: RefinementKind;
-    title: string;
-    content: string;
-    path: string;
-    scope: HarnessScope;
-    /** Skill entries carry an executable contract; see {@link PythonReference}. */
-    reference: Record<string, unknown>;
-    /** Skill entries declare their accepted inputs here. */
-    arguments: Record<string, unknown>;
-    /** Skill form: "executable" (default) or "guidance" (SKILL.md document). */
-    skill_kind?: SkillKind;
-    metadata: Record<string, unknown>;
-    source: "evolve";
-    created_at: string;
-    updated_at: string;
-    version: number;
-}
-/** One entry of the append-only refinement history (the evidence trail). */
-export interface HarnessRefinementEvent {
-    id: string;
-    trigger: string;
-    changes: string[];
-    /** Where the trajectory evidence for this refinement lives (e.g. seq ranges). */
-    evidence: string;
-    /** The falsifiable expectation recorded with the edit. */
-    outcome: string;
-    created_at: string;
-}
-/** The whole harness state file. */
-export interface HarnessState {
-    schema: number;
-    entries: Record<RefinementKind, Record<string, HarnessEntry>>;
-    refinements: HarnessRefinementEvent[];
-}
-/** A model-proposed edit, before validation and application. */
-export interface RefinementEdit {
-    action: RefinementAction;
-    kind: RefinementKind;
-    id?: string;
-    title?: string;
-    content?: string;
-    path?: string;
-    reference?: Record<string, unknown>;
-    arguments?: Record<string, unknown>;
-    /** Skill form: "guidance" for SKILL.md document skills; absent = executable. */
-    skill_kind?: SkillKind;
-    metadata?: Record<string, unknown>;
-    reason?: string;
-    /**
-     * Gap C2: blast-radius annotation — how broadly this edit applies.
-     * Values: "general" (cross-project tactical), "project" (single project),
-     * "session" (one-off session-specific). The review gate checks that
-     * local-scope edits are "session" or "project" and global-scope edits
-     * are "general" or "project".
-     */
-    blastRadius?: "general" | "project" | "session";
-}
-/** The structured output of a planning pass. */
-export interface RefinementProposal {
-    summary: string;
-    rationale: string;
-    edits: RefinementEdit[];
-    expectedOutcome: string;
-}
-/** An edit after the apply pass: before/after snapshots and outcome per edit. */
-export interface AppliedRefinementEdit extends RefinementEdit {
-    id: string;
-    before?: HarnessEntry;
-    after?: HarnessEntry;
-    applied: boolean;
-    error?: string;
-}
-/** The result of applying one refinement. */
-export interface RefinementResult {
-    id: string;
-    summary: string;
-    rationale: string;
-    expectedOutcome: string;
-    appliedEdits: AppliedRefinementEdit[];
-    harnessStatePath: string;
-    rollbackOf?: string;
-    scope?: HarnessScope;
-}
-/** The executable contract a skill entry must carry (python REPL skills). */
-export interface PythonReference {
-    type: "python";
-    import?: string;
-    python_import?: string;
-    callable?: string;
-    call_pattern?: string;
-}
-/**
- * A stable id derived from a title: ASCII runs become snake_case (unchanged
- * legacy behavior). Titles with no ASCII content at all (e.g. pure Chinese)
- * used to collapse onto the bare fallback, so distinct memories shared one
- * id and every later create failed as "already exists". They now take
- * `<fallback>_<sha256-8>` instead: distinct titles get distinct ids while
- * identical titles still dedupe onto the same id. The fallback itself is
- * assumed id-safe (callers pass entry kinds).
- */
-export declare function slug(raw: string, fallback: string): string;
-/** Fresh empty state with the current schema version. */
-export declare function emptyHarnessState(): HarnessState;
-/** Deep clone helper (state is plain JSON data). */
-export declare function cloneEntry(entry: HarnessEntry | undefined): HarnessEntry | undefined;
-/**
- * Storage-hygiene defaults (#20): JSONL tail lines kept per store history
- * and per shared audit trail when no explicit `historyRetain` is set.
- */
-export declare const DEFAULT_REFINEMENTS_RETAIN = 500;
-export declare const DEFAULT_REVIEWS_RETAIN = 500;
-/** Prefix-cache routing modes for extractor/planner inputs (see prefix-cache.ts). */
-export type PlannerPrefixCacheMode = "auto" | "session" | "off";
-/** The only two durable outcomes a scope-approval dialog may produce. */
-export type ScopeApprovalDecision = "approved" | "declined";
-//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -1,133 +0,0 @@
-/**
- * Type model for the continual-evolution harness state.
- *
- * Design provenance: the state model follows the continual-harness design
- * validated in prime-agent's `/refine` subsystem (MIT): versioned entries
- * keyed by kind, an append-only refinement history carrying an evidence
- * trail, atomic persistence, and deterministic inverse-op rollback. The
- * code here is an original implementation, written for the DeepSeek Harness
- * plugin surface.
- */
-import { createHash } from "node:crypto";
-/**
- * Memory-entry shape discipline (one fact per entry, typed like ZCode's
- * memory frontmatter): every `memory` create must stamp one of these in
- * `metadata[MEMORY_TYPE_KEY]` — the recall hook the directory shows.
- */
-export const MEMORY_TYPE_KEY = "memoryType";
-/** Closed memory-type set: user | feedback | project | reference. */
-export const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
-/** True when the value is a closed-set memory type. */
-export function isMemoryType(value) {
-    return typeof value === "string" && MEMORY_TYPES.includes(value);
-}
-/**
- * Metadata key recording which session an entry's content was distilled from
- * (trajectory citation; see {@link EntrySource}).
- */
-export const SOURCE_SESSION_KEY = "sourceSession";
-/**
- * Metadata key recording the session-log event seqs (of the direct user
- * messages) the entry cites as its source (trajectory citation).
- */
-export const SOURCE_SEQS_KEY = "sourceSeqs";
-/**
- * Metadata key recording when an entry was archived. Archived entries are
- * hidden from injection but never deleted — the data stays in the store and
- * the entry can be restored (unarchive) or rolled back like any other edit.
- */
-export const ARCHIVED_AT_KEY = "archivedAt";
-/**
- * Metadata key stamped on a LOCAL entry that was promoted to the global
- * store by a session wrap-up: the id of the global entry it became. Present
- * means the entry's lifecycle is finished — it must not be offered for
- * promotion again (the global copy is the live one, the local copy is a
- * restorable trace).
- */
-export const PROMOTED_TO_KEY = "promotedTo";
-/**
- * Metadata key recording when a local entry was promoted to the global
- * store (companion of {@link PROMOTED_TO_KEY}).
- */
-export const PROMOTED_AT_KEY = "promotedAt";
-/**
- * Metadata key stamped on a GLOBAL entry created by a session wrap-up
- * promotion: `<sessionId>:<localEntryId>` — the反向 provenance link from the
- * cross-session copy back to the session it was distilled from.
- */
-export const SOURCED_FROM_KEY = "sourcedFromLocal";
-/**
- * Metadata key stamped on a GLOBAL entry that was created despite a
- * moderate-similarity overlap with an existing entry (write-time conflict
- * guard, warn tier): `<kind>:<id>:<score>` — points at the entry it may
- * duplicate so wrapup/fate can consolidate later. Creates at/above the block
- * threshold never reach this stamp; they are rejected outright.
- */
-export const CONFLICT_HINT_KEY = "conflictHint";
-/**
- * Negative-valence counter (P1 效价反馈): how many times an assessment marked
- * this entry contradicted by newer evidence (user correction, overridden
- * fact). Injection ranking demotes entries with a positive counter and the
- * wrapup/fate assessors see the count so they prefer archiving the entry.
- */
-export const VALENCE_NEGATIVE_KEY = "valenceNegative";
-/**
- * Provenance of entries merged INTO this one by the consolidation command
- * (P1 反膨胀): array of `<kind>:<id>` — the near-duplicate sources whose
- * content was appended before they archived. The trail keeps an unarchive of
- * the source explainable and lets audits find the merge provenance.
- */
-export const MERGED_FROM_KEY = "mergedFrom";
-/**
- * True when the entry is archived (hidden from injection, restorable).
- * Absent or empty archivedAt means the entry is active.
- */
-export function isArchived(entry) {
-    const value = entry.metadata[ARCHIVED_AT_KEY];
-    return typeof value === "string" && value.length > 0;
-}
-/**
- * A stable id derived from a title: ASCII runs become snake_case (unchanged
- * legacy behavior). Titles with no ASCII content at all (e.g. pure Chinese)
- * used to collapse onto the bare fallback, so distinct memories shared one
- * id and every later create failed as "already exists". They now take
- * `<fallback>_<sha256-8>` instead: distinct titles get distinct ids while
- * identical titles still dedupe onto the same id. The fallback itself is
- * assumed id-safe (callers pass entry kinds).
- */
-export function slug(raw, fallback) {
-    const normalized = raw
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "_")
-        .replace(/^_+|_+$/g, "")
-        .slice(0, 80);
-    if (normalized)
-        return normalized;
-    const digest = createHash("sha256").update(raw, "utf8").digest("hex").slice(0, 8);
-    return `${fallback}_${digest}`;
-}
-/** Fresh empty state with the current schema version. */
-export function emptyHarnessState() {
-    return {
-        schema: 1,
-        entries: {
-            prompt: {},
-            memory: {},
-            skill: {},
-            subagent: {},
-        },
-        refinements: [],
-    };
-}
-/** Deep clone helper (state is plain JSON data). */
-export function cloneEntry(entry) {
-    return entry ? JSON.parse(JSON.stringify(entry)) : undefined;
-}
-/**
- * Storage-hygiene defaults (#20): JSONL tail lines kept per store history
- * and per shared audit trail when no explicit `historyRetain` is set.
- */
-export const DEFAULT_REFINEMENTS_RETAIN = 500;
-export const DEFAULT_REVIEWS_RETAIN = 500;
-//# sourceMappingURL=types.js.map

package/lib/usage.d.ts

@@ -1,36 +0,0 @@
-import type { RefinementKind } from "./types.js";
-export interface UsageStore {
-    /** Injection count per entry key (`kind:id`). */
-    counts: Record<string, number>;
-    /** Session dedup marker: the last session id each key was counted in (v2). */
-    lastSession?: Record<string, string>;
-}
-/**
- * Load the usage store from disk; returns an empty store when absent or
- * corrupt. Accepts BOTH on-disk shapes:
- * - legacy (≤0.3.x): a flat `{ "kind:id": count }` map,
- * - v2: `{ version: 2, counts, lastSession }` with per-session dedup.
- */
-export declare function loadUsage(baseDir: string): UsageStore;
-/** Persist the usage store atomically (always the v2 shape). */
-export declare function saveUsage(baseDir: string, store: UsageStore): void;
-/** Build the usage key for an entry. */
-export declare function usageKey(kind: RefinementKind, id: string): string;
-/**
- * Increment injection counts for the entries that were actually injected.
- * Called after `entriesSectionText` renders the injected block. Keys not
- * present in the store are initialized to 1.
- *
- * Session dedup (2026-08-22): with a sessionId, each key counts AT MOST
- * ONCE per session — the old per-build counting produced meaningless
- * numbers (one entry hit 2311× in a week) and hid the real "how many
- * sessions found this useful" signal that staleness decay needs. Without
- * a sessionId the call degrades to legacy always-increment behavior.
- */
-export declare function recordInjection(baseDir: string, injectedKeys: readonly string[], sessionId?: string): void;
-/**
- * Get the injection count for a specific entry. Returns 0 when the entry
- * has never been injected (absent from the store).
- */
-export declare function getUsageCount(store: UsageStore, kind: RefinementKind, id: string): number;
-//# sourceMappingURL=usage.d.ts.map

package/lib/usage.js

@@ -1,98 +0,0 @@
-/**
- * Entry usage tracking (gap B1): records how many times each entry has been
- * injected into system prompts. The counts are durable (persisted to disk)
- * and exposed in `evolve_list` and the gate's archive-candidate reporting,
- * so "zero-usage stale entries" can be surfaced for cleanup.
- *
- * Storage: `<baseDir>/evolve/usage.json` — a flat JSON object mapping
- * `kind:id` to an integer count. Reads are tolerant of missing/corrupt files;
- * writes are atomic (tmp + rename).
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-const USAGE_FILE = "usage.json";
-function usagePath(baseDir) {
-    return join(baseDir, "evolve", USAGE_FILE);
-}
-/**
- * Load the usage store from disk; returns an empty store when absent or
- * corrupt. Accepts BOTH on-disk shapes:
- * - legacy (≤0.3.x): a flat `{ "kind:id": count }` map,
- * - v2: `{ version: 2, counts, lastSession }` with per-session dedup.
- */
-export function loadUsage(baseDir) {
-    const path = usagePath(baseDir);
-    try {
-        if (!existsSync(path))
-            return { counts: {}, lastSession: {} };
-        const raw = JSON.parse(readFileSync(path, "utf8"));
-        if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
-            const record = raw;
-            if (record["version"] === 2 && typeof record["counts"] === "object" && record["counts"] !== null) {
-                return {
-                    counts: record["counts"],
-                    lastSession: typeof record["lastSession"] === "object" && record["lastSession"] !== null
-                        ? record["lastSession"]
-                        : {},
-                };
-            }
-            // Legacy flat map: every key is a count.
-            return { counts: raw, lastSession: {} };
-        }
-        return { counts: {}, lastSession: {} };
-    }
-    catch {
-        return { counts: {}, lastSession: {} };
-    }
-}
-/** Persist the usage store atomically (always the v2 shape). */
-export function saveUsage(baseDir, store) {
-    const dir = join(baseDir, "evolve");
-    mkdirSync(dir, { recursive: true });
-    const path = usagePath(baseDir);
-    const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, `${JSON.stringify({ version: 2, counts: store.counts, lastSession: store.lastSession ?? {} }, null, 2)}\n`, "utf8");
-    renameSync(tmp, path);
-}
-/** Build the usage key for an entry. */
-export function usageKey(kind, id) {
-    return `${kind}:${id}`;
-}
-/**
- * Increment injection counts for the entries that were actually injected.
- * Called after `entriesSectionText` renders the injected block. Keys not
- * present in the store are initialized to 1.
- *
- * Session dedup (2026-08-22): with a sessionId, each key counts AT MOST
- * ONCE per session — the old per-build counting produced meaningless
- * numbers (one entry hit 2311× in a week) and hid the real "how many
- * sessions found this useful" signal that staleness decay needs. Without
- * a sessionId the call degrades to legacy always-increment behavior.
- */
-export function recordInjection(baseDir, injectedKeys, sessionId) {
-    if (injectedKeys.length === 0)
-        return;
-    const store = loadUsage(baseDir);
-    let dirty = false;
-    for (const key of injectedKeys) {
-        if (sessionId !== undefined && store.lastSession?.[key] === sessionId) {
-            continue;
-        }
-        store.counts[key] = (store.counts[key] ?? 0) + 1;
-        if (store.lastSession && sessionId !== undefined) {
-            store.lastSession[key] = sessionId;
-        }
-        dirty = true;
-    }
-    if (dirty) {
-        saveUsage(baseDir, store);
-    }
-}
-/**
- * Get the injection count for a specific entry. Returns 0 when the entry
- * has never been injected (absent from the store).
- */
-export function getUsageCount(store, kind, id) {
-    return store.counts[usageKey(kind, id)] ?? 0;
-}
-//# sourceMappingURL=usage.js.map

package/lib/validate.d.ts

@@ -1,28 +0,0 @@
-/**
- * Code-enforced validation of model-proposed edits. Every rule here exists
- * because the proposal is untrusted input: enum membership, immutability of
- * the base system prompt, required fields per action, and the executable
- * contract skill entries must carry.
- */
-import type { HarnessEntry, HarnessScope, RefinementEdit } from "./types.js";
-export declare const BASE_SYSTEM_PROMPT_ID = "base_system_prompt";
-/**
- * Gap C2: mechanical check that an edit's declared blast radius is coherent
- * with the scope it targets. A session-scoped edit claiming "general" would
- * silently read like a cross-project tactical rule; a global edit claiming
- * "session" would contradict its persistence. Absent blastRadius is NOT
- * rejected (pre-C2 data and manual edits stay compatible) — the planner is
- * instructed to always declare it, and this rule catches what it declares
- * incoherently.
- */
-export declare function validateBlastRadiusScope(scope: HarnessScope, blastRadius: "general" | "project" | "session"): string | undefined;
-/**
- * Returns a human-readable failure reason, or undefined when the edit passes.
- *
- * `before` (the entry the edit targets, absent for creates/unknown ids) lets
- * update rules distinguish "carrying the persisted value" from "changing it"
- * — e.g. a rollback inverse re-carries the stored skill_kind, which must
- * pass, while a genuine executable↔guidance switch must not.
- */
-export declare function validateEdit(edit: RefinementEdit, computedId: string | undefined, scope?: HarnessScope, before?: HarnessEntry): string | undefined;
-//# sourceMappingURL=validate.d.ts.map