dsh-continual-evolve 0.10.6 → 0.11.0

package/lib/service.d.ts

@@ -3,7 +3,7 @@
  * Every mutation path goes through here so snapshot-before-write, apply
  * accounting, persistence, and result history are enforced in one place.
  */
-import type { EntrySource, HarnessScope, RefinementProposal, RefinementResult } from "./types.js";
+import type { EntrySource, HarnessScope, HarnessState, RefinementProposal, RefinementResult } from "./types.js";
 import { applyRefinementProposal } from "./apply.js";
 import type { HistoryRetention } from "./store.js";
 /** A post-commit apply failure that still carries the durable applied result. */
@@ -37,13 +37,27 @@ export interface EvolutionEngineOptions {
     historyRetain?: Partial<HistoryRetention>;
 }
 export declare function createEvolutionEngine(baseDir: string, hooks?: EvolutionHooks, opts?: EvolutionEngineOptions): {
-    load: (scope: HarnessScope, sessionId: string | undefined) => import("./types.js").HarnessState;
+    load: (scope: HarnessScope, sessionId: string | undefined) => HarnessState;
     apply: (scope: HarnessScope, sessionId: string | undefined, proposal: RefinementProposal, context?: ApplyContext) => RefinementResult;
     rollback: (scope: HarnessScope, sessionId: string | undefined, refinementId: string) => RefinementResult;
     rollbackResult: (scope: HarnessScope, sessionId: string | undefined, target: RefinementResult) => RefinementResult;
     history: (scope: HarnessScope, sessionId: string | undefined) => RefinementResult[];
+    exportStore: (scope: HarnessScope, sessionId: string | undefined) => ExportedStore;
+    importStore: (scope: HarnessScope, sessionId: string | undefined, payload: unknown) => {
+        entries: number;
+        refinements: number;
+    };
     baseDir: string;
     retention: HistoryRetention;
 };
+/** The on-disk shape `/evolve export` writes and `/evolve import` reads. */
+export interface ExportedStore {
+    version: number;
+    scope: HarnessScope;
+    schema: number;
+    entries: HarnessState["entries"];
+    refinements: HarnessState["refinements"];
+    history: RefinementResult[];
+}
 export type EvolutionEngine = ReturnType<typeof createEvolutionEngine>;
 //# sourceMappingURL=service.d.ts.map

package/lib/service.js

@@ -175,6 +175,79 @@ export function createEvolutionEngine(baseDir, hooks = {}, opts = {}) {
     function history(scope, sessionId) {
         return loadResults(storePaths(baseDir, scope, sessionId));
     }
-    return { load, apply, rollback, rollbackResult, history, baseDir, retention };
+    /** Serialize one store (entries + refinement history) for `/evolve export`. */
+    function exportStore(scope, sessionId) {
+        const state = load(scope, sessionId);
+        return {
+            version: 1,
+            scope,
+            schema: state.schema,
+            entries: state.entries,
+            refinements: state.refinements,
+            history: history(scope, sessionId),
+        };
+    }
+    /**
+     * Replace one store from an export payload (raw state write — the same
+     * semantics the command always had: no snapshot, no per-edit validation,
+     * the payload is trusted because a human handed over the file).
+     */
+    function importStore(scope, sessionId, payload) {
+        if (!isValidExport(payload)) {
+            throw new Error("invalid export file shape: expected {version, entries: {prompt, memory, skill, subagent}, refinements, history}");
+        }
+        const entriesBlock = payload["entries"];
+        const state = {
+            schema: typeof payload["schema"] === "number" ? payload["schema"] : 1,
+            entries: {
+                prompt: toEntryRecord(entriesBlock["prompt"]),
+                memory: toEntryRecord(entriesBlock["memory"]),
+                skill: toEntryRecord(entriesBlock["skill"]),
+                subagent: toEntryRecord(entriesBlock["subagent"]),
+            },
+            refinements: Array.isArray(payload["refinements"]) ? payload["refinements"] : [],
+        };
+        const paths = storePaths(baseDir, scope, sessionId);
+        saveHarnessState(paths.stateDir, state);
+        let refinements = 0;
+        if (Array.isArray(payload["history"])) {
+            for (const result of payload["history"]) {
+                if (isResultRecord(result)) {
+                    appendResult(paths, result);
+                    refinements += 1;
+                }
+            }
+            // Storage hygiene (#20): an imported history obeys the same tail
+            // budget as a live one.
+            try {
+                pruneJsonlFile(paths.resultsPath, retention.refinements);
+            }
+            catch {
+                // ignored — the next apply retries
+            }
+        }
+        const entries = Object.values(state.entries).reduce((n, byKind) => n + Object.keys(byKind).length, 0);
+        return { entries, refinements };
+    }
+    return { load, apply, rollback, rollbackResult, history, exportStore, importStore, baseDir, retention };
+}
+function toEntryRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function isValidExport(payload) {
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+        return false;
+    const record = payload;
+    const entries = record["entries"];
+    if (typeof entries !== "object" || entries === null || Array.isArray(entries))
+        return false;
+    const kinds = ["prompt", "memory", "skill", "subagent"];
+    return kinds.every((kind) => Object.prototype.hasOwnProperty.call(entries, kind));
+}
+function isResultRecord(value) {
+    return typeof value === "object" && value !== null && "id" in value && "appliedEdits" in value;
 }
 //# sourceMappingURL=service.js.map

package/lib/store.d.ts

@@ -8,8 +8,7 @@ export declare const EVOLVE_DIR = "evolve";
  * 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 { DEFAULT_REFINEMENTS_RETAIN, DEFAULT_REVIEWS_RETAIN } from "./types.js";
 export declare const DEFAULT_TOKEN_USAGE_RETAIN = 500;
 /** Resolved retention set: how many snapshots / JSONL tail lines to keep. */
 export interface HistoryRetention {

package/lib/store.js

@@ -14,6 +14,7 @@
  * 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 { DEFAULT_REFINEMENTS_RETAIN, DEFAULT_REVIEWS_RETAIN } from "./types.js";
 import { join } from "node:path";
 import { sanitizeProjectKey } from "./project.js";
 import { stateFilePath } from "./state.js";
@@ -26,8 +27,7 @@ export const EVOLVE_DIR = "evolve";
  * 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 { DEFAULT_REFINEMENTS_RETAIN, DEFAULT_REVIEWS_RETAIN } from "./types.js";
 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) {

package/lib/tool.js

@@ -8,7 +8,7 @@ import { entrySourceOf } from "./source.js";
 import { formatRecallResult, recallMemories } from "./recall.js";
 import { getUsageCount, loadUsage } from "./usage.js";
 import { buildEvolveCompleteEvent, emitEvolveComplete } from "./evolve-event.js";
-import { DEFAULT_REVIEWS_RETAIN } from "./store.js";
+import { DEFAULT_REVIEWS_RETAIN } from "./types.js";
 const SCOPES = ["local", "project", "global"];
 /**
  * Accept the string form (`scope: "project"`) with the legacy boolean tool

package/lib/turn-snapshot.d.ts

@@ -9,7 +9,7 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
 /** Why a scheduler snapshot was captured. */
-export type TurnSnapshotReason = "turn_snapshot" | "compact";
+export type TurnSnapshotReason = "compact" | "session_close" | "goal_blocked";
 /** Mechanical reasons a snapshot can be skipped without an LLM call. */
 export type SnapshotSkipReason = "no-new-events" | "internal-agent" | "direct-memory-write" | "no-user-prose";
 /** One immutable scheduler input. The cursor is a durable event boundary. */
@@ -69,4 +69,10 @@ export declare function containsDirectMemoryWrite(events: readonly unknown[]): b
 export declare function serializeSnapshotEvents(events: readonly unknown[], maxChars: number): string;
 /** A DSH subagent header is an internal source when its origin says so. */
 export declare function isInternalAgent(agent: Agent | undefined): boolean;
+/**
+ * Durable-boundary ordering shared by the scheduler and the extraction
+ * phase: returns a positive number when `left` is newer than `right`,
+ * negative when older, and undefined when the two shapes are incomparable.
+ */
+export declare function compareReviewCursors(left: string, right: string): number | undefined;
 //# sourceMappingURL=turn-snapshot.d.ts.map

package/lib/turn-snapshot.js

@@ -235,4 +235,18 @@ function readNestedString(value, keys) {
     }
     return undefined;
 }
+/**
+ * Durable-boundary ordering shared by the scheduler and the extraction
+ * phase: returns a positive number when `left` is newer than `right`,
+ * negative when older, and undefined when the two shapes are incomparable.
+ */
+export function compareReviewCursors(left, right) {
+    if (left === right)
+        return 0;
+    const leftMatch = /^(seq|index):(\d+)$/.exec(left);
+    const rightMatch = /^(seq|index):(\d+)$/.exec(right);
+    if (!leftMatch || !rightMatch || leftMatch[1] !== rightMatch[1])
+        return undefined;
+    return Number(leftMatch[2]) - Number(rightMatch[2]);
+}
 //# sourceMappingURL=turn-snapshot.js.map

package/lib/types.d.ts

@@ -205,4 +205,14 @@ export declare function slug(raw: string, fallback: string): string;
 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

@@ -124,4 +124,10 @@ export function emptyHarnessState() {
 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/wrapup-candidates.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Wrap-up candidate domain: the mechanical audit of a session's local
+ * entries (candidates, global coverage detection, usage hints), the LLM
+ * assessment parser, and the shared wrap-up types. Pure logic — the LLM
+ * call lives in `wrapup.ts`, the proposal builders in
+ * `wrapup-proposals.ts`.
+ */
+import type { HarnessEntry, HarnessState, RefinementKind } from "./types.js";
+export type WrapupVerdict = "promote" | "archive" | "keep";
+/** A classified local entry: `key` matches one audited candidate exactly. */
+export interface WrapupItem {
+    /** `kind:id` of the candidate this verdict refers to. */
+    key: string;
+    verdict: WrapupVerdict;
+    reason: string;
+    /**
+     * Optional split-promotion payload (verdict "archive" only): the entry is
+     * archived as a whole, but a CLEANED cross-session-reusable part is
+     * offered for promotion — the durable fact distilled out of the mixed
+     * entry, with the ephemeral snapshot left behind in the archive.
+     */
+    promote?: {
+        title: string;
+        content: string;
+    };
+    /**
+     * Valence signal (P1 效价反馈): the assessor found trajectory or global
+     * evidence contradicting this entry's content (user correction, overridden
+     * fact). Strictly parsed — only an explicit JSON `true` sets it. Keep
+     * verdicts with this flag get a negative-valence stamp; the assessor is
+     * instructed to prefer "archive" for contradicted entries.
+     */
+    contradicted?: boolean;
+}
+/** A real global entry worth showing the assessor for the same topic. */
+export interface GlobalHint {
+    id: string;
+    title: string;
+}
+/** The model's full classification of a session's local entries. */
+export interface WrapupAssessment {
+    items: WrapupItem[];
+    rationale: string;
+}
+/** A local entry offered for assessment, plus its deterministic audit flags. */
+export interface WrapupCandidate {
+    kind: RefinementKind;
+    id: string;
+    title: string;
+    content: string;
+    path: string;
+    version: number;
+    metadata: Record<string, unknown>;
+    /**
+     * True when the global store already covers this topic by a STRONG
+     * signal: a title that normalizes equal to, or (beyond a length floor)
+     * contains, the candidate's title. Collisions on id alone with a wildly
+     * different title are deliberately NOT coverage — see {@link globalHintsFor}.
+     */
+    coveredGlobally: boolean;
+    /**
+     * Actual global entries that touch the same topic (same id, equal
+     * normalized title, or title overlap). Shown to the assessor so it judges
+     * against real titles instead of a bare boolean; a bare same-id collision
+     * shows up here precisely so the model can tell whether the global copy
+     * really covers the local content.
+     */
+    globalHints: GlobalHint[];
+    /**
+     * Injection usage count (gap B1): how many times this entry was included
+     * in a system-prompt assembly. Zero means the entry was never used — a
+     * strong staleness signal the assessor can weigh.
+     */
+    injectionCount: number;
+    /**
+     * Staleness flag (gap B2): true when the entry has both zero injection
+     * usage AND a recency score below the staleness threshold (old + unused).
+     * The assessor is instructed to prefer "archive" for stale entries.
+     */
+    stale: boolean;
+    /**
+     * Negative-valence counter (P1 效价反馈): how many prior assessments marked
+     * this entry contradicted (metadata {@link VALENCE_NEGATIVE_KEY}). Shown to
+     * the assessor so it can prefer "archive"; also demotes the entry in
+     * injection ranking (inject.ts rankEntries).
+     */
+    negativeCount: number;
+}
+export declare function candidateKey(kind: RefinementKind, id: string): string;
+/**
+ * Deterministic global-coverage check (STRONG signal): the global store
+ * already covers a topic when it holds a title that normalizes equal to, or
+ * (beyond a length floor) contains, the candidate's normalized title.
+ * Archived global entries count too — the topic was already judged
+ * cross-session; a local duplicate would only re-sediment it.
+ *
+ * The bare same-id case is deliberately NOT coverage: ids are slugs derived
+ * from titles, so a real collision is usually caught by the title check
+ * below. A same-id entry with a wildly different title is a weak signal — the
+ * caller routes it through {@link globalHintsFor} for the assessor to judge
+ * against the actual global title (real case: local `memory` "用户产品愿景与
+ * 收入需求（本会话）" vs global `memory` "用户画像（持续更新）").
+ */
+export declare function globalCoverageDetected(globalState: HarnessState, kind: RefinementKind, entry: Pick<HarnessEntry, "id" | "title">): boolean;
+/**
+ * The actual global entries that touch the same topic as a local candidate:
+ * same id (regardless of title — the weak collision signal that is NOT
+ * coverage on its own), equal normalized title, or title overlap. The raw ids
+ * and titles let the assessor judge enrichment against real global content
+ * (does the global copy already hold what the local one adds?) rather than a
+ * bare boolean. Bounded: a handful of best matches, never the whole store.
+ */
+export declare function globalHintsFor(globalState: HarnessState, kind: RefinementKind, entry: Pick<HarnessEntry, "id" | "title">): GlobalHint[];
+export declare function listLocalCandidates(state: HarnessState, globalState: HarnessState, baseDir?: string): WrapupCandidate[];
+/**
+ * Parse and validate the model's assessment JSON. Defense is mechanical:
+ * keys outside the candidate list are dropped, verdicts outside the enum
+ * collapse to "keep", and candidates the model omitted default to "keep" —
+ * a malformed reply can never change an entry's fate by itself.
+ *
+ * Split promotion (verdict "archive" with a `promote` sub-object): the
+ * sub-object is accepted ONLY on archive verdicts and ONLY when both cleaned
+ * title and content are non-empty strings — a dropped/malformed sub-object
+ * silently degrades to a plain archive (the entry is never half-promoted).
+ */
+export declare function parseWrapupAssessment(text: string, candidates: readonly WrapupCandidate[]): WrapupAssessment;
+//# sourceMappingURL=wrapup-candidates.d.ts.map

package/lib/wrapup-candidates.js

@@ -0,0 +1,161 @@
+import { PROMOTED_TO_KEY, VALENCE_NEGATIVE_KEY, isArchived } from "./types.js";
+import { extractJsonObject } from "./plan.js";
+import { getUsageCount, loadUsage } from "./usage.js";
+import { recencyScore } from "./injection-rank.js";
+export function candidateKey(kind, id) {
+    return `${kind}:${id}`;
+}
+/** Lowercase, punctuation-stripped title used for cheap coverage matching. */
+function normalizeKey(value) {
+    return value.toLowerCase().replace(/[^a-z0-9\u3400-\u9fff]+/g, "").trim();
+}
+/**
+ * Deterministic global-coverage check (STRONG signal): the global store
+ * already covers a topic when it holds a title that normalizes equal to, or
+ * (beyond a length floor) contains, the candidate's normalized title.
+ * Archived global entries count too — the topic was already judged
+ * cross-session; a local duplicate would only re-sediment it.
+ *
+ * The bare same-id case is deliberately NOT coverage: ids are slugs derived
+ * from titles, so a real collision is usually caught by the title check
+ * below. A same-id entry with a wildly different title is a weak signal — the
+ * caller routes it through {@link globalHintsFor} for the assessor to judge
+ * against the actual global title (real case: local `memory` "用户产品愿景与
+ * 收入需求（本会话）" vs global `memory` "用户画像（持续更新）").
+ */
+export function globalCoverageDetected(globalState, kind, entry) {
+    const records = globalState.entries[kind];
+    const title = normalizeKey(entry.title);
+    if (title.length === 0)
+        return false;
+    for (const other of Object.values(records)) {
+        const otherTitle = normalizeKey(other.title);
+        if (otherTitle.length === 0)
+            continue;
+        if (otherTitle === title)
+            return true;
+        if (title.length >= 4 && otherTitle.length >= 4 && (title.includes(otherTitle) || otherTitle.includes(title))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * The actual global entries that touch the same topic as a local candidate:
+ * same id (regardless of title — the weak collision signal that is NOT
+ * coverage on its own), equal normalized title, or title overlap. The raw ids
+ * and titles let the assessor judge enrichment against real global content
+ * (does the global copy already hold what the local one adds?) rather than a
+ * bare boolean. Bounded: a handful of best matches, never the whole store.
+ */
+export function globalHintsFor(globalState, kind, entry) {
+    const records = globalState.entries[kind];
+    const title = normalizeKey(entry.title);
+    const hints = [];
+    for (const other of Object.values(records)) {
+        const otherTitle = normalizeKey(other.title);
+        if (otherTitle.length === 0 && other.id !== entry.id)
+            continue;
+        const matches = other.id === entry.id ||
+            (otherTitle.length > 0 && (otherTitle === title || (title.length >= 4 && otherTitle.length >= 4 && (title.includes(otherTitle) || otherTitle.includes(title)))));
+        if (matches) {
+            hints.push({ id: other.id, title: other.title });
+        }
+    }
+    return hints;
+}
+/**
+ * The auditable local candidates of a session: every non-archived local
+ * entry that has not already been promoted (a promoted entry's lifecycle is
+ * finished — the global copy is the live one). Each carries its
+ * `coveredGlobally` flag so the assessor never wastes a promote on a topic
+ * the global store already owns.
+ */
+/** Staleness threshold: entries with recency below this AND zero usage are stale. */
+const STALE_RECENCY_THRESHOLD = 0.1;
+export function listLocalCandidates(state, globalState, baseDir) {
+    const usage = baseDir ? loadUsage(baseDir) : undefined;
+    const now = Date.now();
+    const candidates = [];
+    for (const kind of Object.keys(state.entries)) {
+        for (const entry of Object.values(state.entries[kind])) {
+            if (entry.scope !== "local")
+                continue;
+            if (isArchived(entry))
+                continue;
+            if (typeof entry.metadata[PROMOTED_TO_KEY] === "string")
+                continue;
+            const injectionCount = usage ? getUsageCount(usage, kind, entry.id) : 0;
+            const stale = injectionCount === 0 && recencyScore(entry, now) < STALE_RECENCY_THRESHOLD;
+            const rawNegative = entry.metadata[VALENCE_NEGATIVE_KEY];
+            const negativeCount = typeof rawNegative === "number" && Number.isFinite(rawNegative) && rawNegative > 0 ? rawNegative : 0;
+            candidates.push({
+                kind,
+                id: entry.id,
+                title: entry.title,
+                content: entry.content,
+                path: entry.path,
+                version: entry.version,
+                metadata: entry.metadata,
+                coveredGlobally: globalCoverageDetected(globalState, kind, entry),
+                globalHints: globalHintsFor(globalState, kind, entry),
+                injectionCount,
+                stale,
+                negativeCount,
+            });
+        }
+    }
+    return candidates;
+}
+/**
+ * Parse and validate the model's assessment JSON. Defense is mechanical:
+ * keys outside the candidate list are dropped, verdicts outside the enum
+ * collapse to "keep", and candidates the model omitted default to "keep" —
+ * a malformed reply can never change an entry's fate by itself.
+ *
+ * Split promotion (verdict "archive" with a `promote` sub-object): the
+ * sub-object is accepted ONLY on archive verdicts and ONLY when both cleaned
+ * title and content are non-empty strings — a dropped/malformed sub-object
+ * silently degrades to a plain archive (the entry is never half-promoted).
+ */
+export function parseWrapupAssessment(text, candidates) {
+    const value = extractJsonObject(text);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("wrap-up assessment JSON must be an object");
+    }
+    const record = value;
+    const allowed = new Set(candidates.map((candidate) => candidateKey(candidate.kind, candidate.id)));
+    const items = [];
+    if (Array.isArray(record["items"])) {
+        for (const raw of record["items"]) {
+            if (typeof raw !== "object" || raw === null)
+                continue;
+            const item = raw;
+            const key = typeof item["key"] === "string" ? item["key"] : "";
+            if (!allowed.has(key))
+                continue;
+            const verdict = item["verdict"] === "promote" || item["verdict"] === "archive" ? item["verdict"] : "keep";
+            const built = { key, verdict, reason: typeof item["reason"] === "string" ? item["reason"] : "" };
+            if (item["contradicted"] === true) {
+                built.contradicted = true;
+            }
+            if (verdict === "archive" && typeof item["promote"] === "object" && item["promote"] !== null) {
+                const sub = item["promote"];
+                const subTitle = typeof sub["title"] === "string" ? sub["title"].trim() : "";
+                const subContent = typeof sub["content"] === "string" ? sub["content"].trim() : "";
+                if (subTitle.length > 0 && subContent.length > 0) {
+                    built.promote = { title: subTitle, content: subContent };
+                }
+            }
+            items.push(built);
+        }
+    }
+    for (const candidate of candidates) {
+        const key = candidateKey(candidate.kind, candidate.id);
+        if (!items.some((item) => item.key === key)) {
+            items.push({ key, verdict: "keep", reason: "not mentioned by the assessor" });
+        }
+    }
+    return { items, rationale: typeof record["rationale"] === "string" ? record["rationale"] : "" };
+}
+//# sourceMappingURL=wrapup-candidates.js.map

package/lib/wrapup-proposals.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Wrap-up proposal builders: turn assessed verdicts into deterministic,
+ * evidence-carrying refinement proposals — whole promotes, split promotes,
+ * archive reviews, and valence stamps. Pure logic over the candidate types
+ * in `wrapup-candidates.ts`; the user approves, the engine applies.
+ */
+import type { HarnessState, RefinementKind, RefinementProposal } from "./types.js";
+import { type PromotionPolicy } from "./promotion.js";
+import { type WrapupCandidate, type WrapupItem } from "./wrapup-candidates.js";
+export interface PromotableSplit {
+    /** Items that may be promoted: classified promote AND not covered globally. */
+    promotable: WrapupItem[];
+    /** Items classified promote but blocked by the deterministic guard, with why. */
+    skipped: {
+        key: string;
+        reason: string;
+    }[];
+}
+/**
+ * Apply-time deterministic guard: re-check every promote verdict against the
+ * global store right before it lands. The LLM classification may be stale
+ * (a gate ran while assessing) or wrong; this ensures a promote never writes
+ * a duplicate, project-scoped, or too-thin global entry. Pure and unit-tested.
+ *
+ * Guards (2026-08-22 promotion policy):
+ * - audited candidate list + title coverage (pre-existing),
+ * - project-scoped content markers (absolute paths / session ids) — the
+ *   global store is shared across projects and must stay portable,
+ * - thin content below the policy floor (framing outweighs the fact),
+ * - near-duplicate of an existing global entry by content overlap.
+ */
+export declare function filterPromotable(items: readonly WrapupItem[], globalState: HarnessState, candidates: readonly WrapupCandidate[], policy?: PromotionPolicy): PromotableSplit;
+export interface ArchiveReviewSplit {
+    /** Archives that may proceed silently: topic already covered, no real
+     * distillation source, or the archive half of an already-approved split. */
+    silent: WrapupItem[];
+    /**
+     * Archives that would bury possibly-reusable content: not covered
+     * globally AND distilled from real user messages (sourceSeqs present).
+     * These MAY NOT archive silently — the command must get user
+     * confirmation first (the symmetric guard to filterPromotable: it stops
+     * over-archiving, not just over-writing).
+     */
+    review: WrapupItem[];
+}
+/**
+ * The symmetric archive guard. `filterPromotable` is one-directional: it
+ * stops the model from WRITING duplicate global entries, but nothing stopped
+ * an unfounded ARCHIVE from hiding content that was actually only local.
+ * Guard criteria: an archive needs user confirmation when it is NOT covered
+ * globally AND the entry carries a real distillation source (sourceSeqs /
+ * sourceSession — i.e. it was distilled from actual user messages, so it
+ * may hold reusable value). Operational/empty entries archive silently as
+ * before. Split archives (archive + promote sub-object) skip this check:
+ * their promotion already crosses a human approval gate, so the archive is
+ * the completion of an approved action, not a silent burial.
+ */
+export declare function needsArchiveReview(item: WrapupItem, candidate: WrapupCandidate): boolean;
+/** Partition archive items into silent vs review-required (see needsArchiveReview). */
+export declare function splitArchiveGuards(items: readonly WrapupItem[], candidates: readonly WrapupCandidate[]): ArchiveReviewSplit;
+/**
+ * Apply-time guard for a split promotion (archive + promote sub-object):
+ * the cleaned payload must pass the same promotion policy as a whole
+ * promote — no global coverage duplicate, no project-scoped content, not
+ * too thin, no near-duplicate global entry. A blocked split is dropped (the
+ * entry still archives plain) rather than half-promoting a redundancy.
+ */
+export declare function splitPromoteBlocked(item: WrapupItem, globalState: HarnessState, kind: RefinementKind, policy?: PromotionPolicy, candidateMetadata?: Record<string, unknown>): string | undefined;
+/**
+ * Shared proposal builders for a WHOLE promotion — used by both the
+ * `/evolve wrapup` command and the gate's local-fate dimension so the two
+ * paths apply IDENTICAL edits (global create + local retirement stamp).
+ *
+ * The local stamp is a factory: the `promotedTo` id is only known after the
+ * global create lands (validation may slugify the id), so the caller applies
+ * the global proposal first and stamps the local copy with the created id.
+ */
+export declare function wholePromoteProposals(item: WrapupItem, candidate: WrapupCandidate, sessionId: string): {
+    global: RefinementProposal;
+    localStamp: (createdId: string) => RefinementProposal;
+};
+/**
+ * Shared proposal builders for a SPLIT promotion (A-form): archive a mixed
+ * local entry but promote ONLY the cleaned durable part the model extracted.
+ * Same usage contract as {@link wholePromoteProposals}: apply the global
+ * create, then stamp the original local entry with the created id.
+ */
+export declare function splitPromoteProposals(item: WrapupItem, candidate: WrapupCandidate, sessionId: string): {
+    global: RefinementProposal;
+    localStamp: (createdId: string) => RefinementProposal;
+};
+/**
+ * Valence stamp (P1 效价反馈): a keep-verdict item the assessor marked
+ * contradicted gets its negative-valence counter bumped — the entry stays
+ * live but sinks in injection ranking and the next assessment prefers
+ * archiving it. Promotes pass untouched (the human-approved global copy is
+ * the live truth); archives don't need the stamp (they already leave
+ * injection). Undefined when nothing applies.
+ */
+export declare function valenceStampProposal(item: WrapupItem, candidate: WrapupCandidate): RefinementProposal | undefined;
+//# sourceMappingURL=wrapup-proposals.d.ts.map