dsh-continual-evolve 0.10.6 → 0.12.0

package/lib/wrapup.d.ts

@@ -1,260 +0,0 @@
-/**
- * Session wrap-up: the lifecycle exit for a session's local harness entries.
- *
- * When a session ends, its local entries default to orphans: a later session
- * (not on the parentSession chain) never sees them, and nothing promotes or
- * archives them — the exploration results effectively "die" with the session.
- * Wrap-up gives those entries a real exit:
- *
- * - cross-session-reusable content is classified `promote` and moved into the
- *   global store (through the human approval gate — global is a governed
- *   resource, exactly like skill proposals);
- * - session-specific / superseded / already-covered content is classified
- *   `archive` (hidden from injection, data stays restorable, rollbackable);
- * - everything else is kept.
- *
- * Division of labor is deliberate: the mechanical audit proposes, the LLM
- * classifies, the user approves, the code applies deterministically. The
- * apply-side guard (`filterPromotable`) re-checks global coverage at apply
- * time so a stale classification can never write a duplicate global entry.
- */
-import type { Context } from "@deepseek-ai/cordis";
-import type { Agent } from "@deepseek-ai/dsh-agent";
-import type { HarnessEntry, HarnessState, RefinementKind, RefinementProposal } from "./types.js";
-import { type TokenUsageTarget } from "./token-usage.js";
-import { type RecordLanguage } from "./record-language.js";
-import { type PromotionPolicy } from "./promotion.js";
-/** What should happen to one local entry at session end. */
-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;
-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;
-export declare const WRAPUP_ASSESS_SYSTEM_PROMPT = "You are the /evolve session wrap-up assessor.\nA session is ending and its local harness entries need a fate. Classify each\nlisted entry exactly once:\n\n- \"promote\" \u2014 the content is a stable, durable, CROSS-SESSION reusable lesson:\n  a durable user preference, a project-level fact or convention, a reusable\n  procedure or skill. Future sessions would benefit from seeing it.\n- \"archive\" \u2014 the content is session-specific task progress, one-off noise,\n  superseded or obsolete, or already covered by the global store (note\n  \"covered globally\" in the reason), or stale (old + never injected \u2014 note\n  \"stale (injectionCount=0, recency low)\" in the reason), or CONTRADICTED \u2014\n  newer evidence in the trajectory or the global store disproves or overrides\n  the entry's content (note what contradicts it in the reason).\n- \"keep\" \u2014 still actively useful to this session, or genuinely uncertain.\n\nRules:\n- CONTRADICTED: when evidence contradicts an entry, set \"contradicted\": true\n  on that item (besides the verdict). Entries marked \"(contradicted N\u00D7\n  before)\" were contradicted in earlier assessments \u2014 prefer \"archive\" for\n  them unless you have concrete evidence the content is valid again.\n- When an entry is marked \"covered globally\" in the listing, prefer \"archive\"\n  or \"keep\" over \"promote\" \u2014 promoting a duplicate gains nothing.\n- When an entry is marked \"stale\" (injectionCount=0 and low recency), prefer\n  \"archive\" \u2014 the entry has never been used and is old, so it is unlikely to\n  be needed again. Only \"keep\" if the content is clearly valuable despite low\n  usage (e.g. a safety policy that rarely triggers but is critical).\n- Do not promote local task state, work-in-progress notes, or content tied to\n  one session's ephemeral details.\n- Memory entries carry a recall type (user/feedback/project/reference): a\n  memory WITHOUT one cannot be promoted (the guard skips it) \u2014 verdict such\n  entries \"keep\" (or \"archive\" when they qualify) rather than \"promote\".\n- Skills: only \"promote\" a skill entry that is a genuinely reusable procedure\n  meeting the DSH skill quality standard; one-off workflows are \"archive\" or\n  \"keep\".\n- SPLIT PROMOTION: when an entry mixes a stable, cross-session-reusable part\n  WITH session-specific snapshot details, do NOT promote it whole. Instead\n  give verdict \"archive\" WITH a \"promote\" sub-object holding a CLEANED\n  version of only the durable part (a stable title + the persistent facts,\n  stripped of dates/states/one-off figures). Ephemeral snapshot content stays\n  out of the sub-object \u2014 it is left behind in the archive. A sub-object is\n  only meaningful on \"archive\" verdicts.\n\nReturn JSON only:\n{\n  \"rationale\": \"one or two sentences\",\n  \"items\": [\n    {\"key\": \"memory:foo\", \"verdict\": \"promote|archive|keep\", \"reason\": \"why\"},\n    {\"key\": \"memory:bar\", \"verdict\": \"archive\", \"reason\": \"why\", \"contradicted\": true,\n     \"promote\": {\"title\": \"cleaned stable title\", \"content\": \"cleaned durable part only\"}}\n  ]\n}\nOnly keys from the provided list are allowed; any entry you omit defaults to \"keep\".";
-export interface AssessOptions {
-    /** Output token budget for the assessment call. */
-    maxOutputTokens?: number;
-    /** Abort signal forwarded to the model call. */
-    signal?: AbortSignal;
-    /** Direct-call token ledger destination; phase is selected by the caller. */
-    tokenUsage?: TokenUsageTarget;
-    /** Ledger phase for this classifier call (manual wrapup or automatic fate). */
-    tokenUsagePhase?: "wrapup" | "fate";
-    /**
-     * Authoring language for verdict reasons. Absent → resolved per call
-     * (durable client preference, else `en`; the assessor sees candidate
-     * snapshots, not user text, so there is no detection tier here).
-     */
-    language?: RecordLanguage;
-}
-/**
- * Ask the model to classify the audited local candidates. Routes through the
- * calling agent's own provider/model (same model the session runs on), with
- * reasoning disabled so the output budget goes to the JSON verdicts.
- */
-export declare function assessLocalEntries(ctx: Context, agent: Agent, candidates: readonly WrapupCandidate[], options?: AssessOptions): Promise<WrapupAssessment>;
-//# sourceMappingURL=wrapup.d.ts.map