@lmzhen/dsh-evolution-core 0.1.0-rc.8 → 0.1.0

package/lib/types/constants.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared constants for the dsh-evolution plugin family.
+ *
+ * Two classes of value live here, deliberately separated by section so future
+ * edits do not blur the semantic boundary:
+ *
+ * 1. **Fixed protocol/format/security invariants** — changing these breaks an
+ *    on-disk format, a naming/format contract, a path-security boundary, or a
+ *    cross-component invariant. They are NOT exposed as deployment config.
+ *
+ * 2. **Cross-package shared tunable defaults** — the same semantic default is
+ *    read (with a config override path) by more than one package (e.g.
+ *    `evolution-policy` and `evolution-curator` both default `staleAfterDays`
+ *    to 30). Centralizing them here means one authoritative default: a config
+ *    override still applies per package, but the fallback is single-sourced.
+ *
+ * Package-private tunables (used by exactly one package) stay in that package,
+ * not here — see evolution-replay's `DEFAULT_WEIGHTS` and evolution-feedback's
+ * threshold, which are intentionally left where they are used.
+ * @module @deepseek-ai/dsh-evolution-core
+ */
+/** Skill frontmatter `name` validated for the file name (lowercase + hyphen). */
+export declare const SKILL_NAME_RE: RegExp;
+/** Allowed skill support-file subdirectories (path-traversal boundary). */
+export declare const SUPPORT_DIRS: readonly ["references", "templates", "scripts", "assets"];
+/** Delimiter between durable memory entries (on-disk storage format). */
+export declare const ENTRY_DELIMITER = "\n\u00A7\n";
+/** Built-in skill names the curator must never lifecycle-manage. */
+export declare const PROTECTED_BUILTIN_SKILLS: ReadonlySet<string>;
+export declare const MAX_SKILL_NAME_LENGTH = 64;
+export declare const MAX_DESCRIPTION_LENGTH = 1024;
+export declare const MAX_SKILL_CONTENT_CHARS = 100000;
+export declare const MAX_SKILL_FILE_BYTES = 1048576;
+export declare const DEFAULT_REVIEW_MEMORY_INTERVAL = 10;
+export declare const DEFAULT_REVIEW_SKILL_INTERVAL = 10;
+/** Skill-review completion channel trigger mode: 'cadence' | 'completion' | 'both'. */
+export declare const DEFAULT_SKILL_REVIEW_TRIGGER: "both";
+/** Cumulative session tool calls before a session counts as "proven long" for the completion channel. */
+export declare const DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS = 20;
+export declare const DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS = 3;
+export declare const DEFAULT_SUBSTANTIVE_MIN_USER_CHARS = 200;
+export declare const DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS = 500;
+export declare const DEFAULT_MAX_OPS_PER_PLAN = 32;
+export declare const DEFAULT_CURATOR_INTERVAL_HOURS = 168;
+export declare const DEFAULT_MIN_IDLE_HOURS = 2;
+export declare const DEFAULT_STALE_AFTER_DAYS = 30;
+export declare const DEFAULT_ARCHIVE_AFTER_DAYS = 90;
+export declare const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
+export declare const DEFAULT_USER_CHAR_LIMIT = 1375;
+/** Consolidation-failure backoff cap, shared by MemoryStore and memory-files' Config default. */
+export declare const DEFAULT_CONSOLIDATION_FAILURES = 3;
+export declare const DEFAULT_SKILL_CONTENT_CHARS = 100000;
+//# sourceMappingURL=constants.d.ts.map

package/lib/types/curator.d.ts

@@ -1,8 +1,13 @@
 /**
  * Deterministic skill curator: active → stale → archived transitions.
- * Pure function; file moves are performed by SkillLibrary.
+ * Pure function with one deliberate side effect: records in the passed
+ * `usage` map are MUTATED (state/archived_at) to carry the transition — the
+ * caller owns the map and decides whether to clone first (dry-run) or persist
+ * after. File moves are performed by SkillLibrary.
  */
-import type { UsageMap } from './usage.ts';
+import type { UsageMap, UsageRecord } from './usage.ts';
+import { EvolutionGateSet } from './gates.ts';
+export { PROTECTED_BUILTIN_SKILLS } from './constants.ts';
 export interface CuratorConfig {
     staleAfterDays: number;
     archiveAfterDays: number;
@@ -12,6 +17,14 @@ export interface CuratorConfig {
     excludeSkillNames?: ReadonlySet<string>;
     /** When true, usage records without created_by='agent' also enter the lifecycle. */
     manageUnmanaged?: boolean;
+    /** When true, bundled skills (in `bundledNames`) are curation candidates like agent-created ones. */
+    pruneBuiltins?: boolean;
+    /** Skill names carrying the bundled marker; only read when `pruneBuiltins` is true. */
+    bundledNames?: ReadonlySet<string>;
+    /** Skill names the curator archived once and must not fight across re-seeds. */
+    suppressedNames?: ReadonlySet<string>;
+    /** Skills referenced by scheduled/automated jobs: never auto-transitioned (idle clocks mislead for rarely-firing tasks). */
+    referencedSkillNames?: ReadonlySet<string>;
 }
 export interface CuratorTransition {
     name: string;
@@ -25,7 +38,6 @@ export interface CuratorResult {
     reactivate: string[];
     markStale: string[];
 }
-export declare const PROTECTED_BUILTIN_SKILLS: ReadonlySet<string>;
 export interface CuratorArchivedSkill {
     name: string;
     path: string;
@@ -36,6 +48,8 @@ export interface CuratorFailedSkill {
     reason: string;
 }
 export interface CuratorRunReport {
+    /** Report shape version; readers may ignore unknown fields on later versions. */
+    schemaVersion: 1;
     runId: string;
     startedAt: string;
     finishedAt: string;
@@ -44,7 +58,11 @@ export interface CuratorRunReport {
     archiveCandidates: string[];
     archived: CuratorArchivedSkill[];
     failed: CuratorFailedSkill[];
+    /** Consolidations actually executed this run (source absorbed into target). */
+    consolidated?: CuratorConsolidation[];
     snapshotPath?: string;
+    /** Whether the LLM nomination pass was enabled for this run (decision visibility). */
+    llmReviewEnabled?: boolean;
 }
 export interface CuratorReportInput {
     runId: string;
@@ -55,8 +73,57 @@ export interface CuratorReportInput {
     archiveCandidates: readonly string[];
     archived: readonly CuratorArchivedSkill[];
     failed: readonly CuratorFailedSkill[];
+    consolidated?: readonly CuratorConsolidation[];
     snapshotPath?: string;
+    llmReviewEnabled?: boolean;
 }
 export declare function buildCuratorRunReport(input: CuratorReportInput): CuratorRunReport;
-export declare function computeLifecycleTransitions(usage: UsageMap, config: CuratorConfig, now?: Date): CuratorResult;
+/**
+ * Render a curator run report as a compact human-readable markdown digest
+ * (G6): run metadata first, then the notable sections (archived / failed /
+ * stale candidates / LLM nominations).
+ */
+export declare function renderCuratorReportMarkdown(report: CuratorRunReport): string;
+/** One LLM-nominated consolidation: `from` merges into the umbrella `into`. */
+export interface CuratorConsolidation {
+    from: string;
+    into: string;
+}
+/** Structured result of the optional curator LLM nomination pass. */
+export interface CuratorNominations {
+    prunings: string[];
+    consolidations: CuratorConsolidation[];
+}
+/**
+ * Parse the curator LLM's YAML nomination block (consolidations + prunings).
+ * Line-oriented and lenient by design: the LLM output is advisory, every name
+ * is re-validated against the tree before any file move happens downstream.
+ */
+export declare function parseCuratorNominations(text: string): CuratorNominations;
+/**
+ * The lifecycle-candidate gate, shared by the transition engine and the scope
+ * view so the two can never disagree: records failing ANY of these gates are
+ * outside the managed scope.
+ */
+export declare function lifecycleCandidate(name: string, record: UsageRecord, config: CuratorConfig, bundled: boolean, gates?: EvolutionGateSet): boolean;
+export interface ScopeView {
+    /** Skills inside the lifecycle scope right now (candidate gate + active state). */
+    managed: string[];
+    /** Managed skills already flagged stale or quality-warned — the ones to watch. */
+    watched: string[];
+    /** Managed skills flagged low quality (subset of `watched`) — consolidation candidates. */
+    qualityWarned: string[];
+    /** Explicitly exempted by excludeSkillNames / referencedSkillNames. */
+    exempted: string[];
+    /** Carrying a protection marker (pinned / bundled / hub-installed). */
+    protected: string[];
+}
+/**
+ * Read-only scope classification, derived from the SAME gate the transition
+ * engine uses (`lifecycleCandidate`), so the view always predicts what a
+ * curator pass may touch. `protectedNames` carries the marker info the usage
+ * records lack (bundled / hub-installed / pinned from `SkillLibrary.list()`).
+ */
+export declare function computeScopeView(usage: UsageMap, config: CuratorConfig, protectedNames?: ReadonlyMap<string, string>, gates?: EvolutionGateSet): ScopeView;
+export declare function computeLifecycleTransitions(usage: UsageMap, config: CuratorConfig, now?: Date, gates?: EvolutionGateSet): CuratorResult;
 //# sourceMappingURL=curator.d.ts.map

package/lib/types/events.d.ts

@@ -1,15 +1,28 @@
 /**
- * Durable session events emitted by the evolution family.
- * These are non-surface events: they never enter model history, but make
- * self-evolution activity replayable and observable by UI/projections.
+ * Process-local events emitted by the evolution family on the cordis event
+ * bus. Consumers subscribe with `ctx.on(...)`; producers dispatch with
+ * `ctx.emit(...)`.
+ *
+ * These are deliberately NOT session events: a persisted session log may only
+ * contain types from the host's generated `KNOWN_SESSION_EVENT_TYPES` set —
+ * the persistence read path refuses to interpret a log carrying any other
+ * type unless the envelope marks it `ignorable`, and `Session.append` offers
+ * no channel to write that marker. Appending any `evolution/*` type therefore
+ * made the whole session unresumable (A-line P0-1, fixed in rc.42 by moving
+ * these events off `session.append`). Plan-outcome durability lives in the
+ * evolution-activity store, not the session log.
  */
 export interface EvolutionReviewScheduledEvent {
+    /** Owning session (payload v2): process events carry no session envelope. */
+    sessionId: string;
     kind: 'memory' | 'skill' | 'combined';
     toolCalls: number;
     userChars: number;
     assistantChars: number;
 }
 export interface EvolutionPlanAppliedEvent {
+    /** Owning session (payload v2): process events carry no session envelope. */
+    sessionId: string;
     planId: string;
     /** Stable fingerprint of the policy snapshot that produced this plan. */
     policyFingerprint?: string | undefined;
@@ -25,15 +38,10 @@ export interface EvolutionSkillMutatedEvent {
     filePath?: string;
     archivedPath?: string;
 }
-declare module '@deepseek-ai/dsh-session/types' {
-    interface SessionEventMap {
-        'evolution/review-scheduled': EvolutionReviewScheduledEvent;
-        'evolution/plan-applied': EvolutionPlanAppliedEvent;
-        'evolution/skill-mutated': EvolutionSkillMutatedEvent;
-    }
-}
 declare module '@deepseek-ai/cordis' {
     interface Events {
+        'evolution/review-scheduled'(event: EvolutionReviewScheduledEvent): void;
+        'evolution/plan-applied'(event: EvolutionPlanAppliedEvent): void;
         'evolution/skill-mutated'(event: EvolutionSkillMutatedEvent): void;
     }
 }

package/lib/types/evolution-events.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Self-evolution event log (rc.68): an append-only sidecar under
+ * `$DSH_HOME/evolution/events.json` that is the single source of truth for
+ * the self-improvement loop. Feedback increments and learn actions share one
+ * ordered timeline (`seq` is the ordering key), so "feedback before/after a
+ * learn on target X" is answerable. The aggregate `feedback.json` is a
+ * rebuildable boot cache, never the truth.
+ *
+ * Rotation (rc.71, 007 design): when the active log reaches
+ * `EVENT_LOG_ROTATE_AT` the older half is split into an archive
+ * (`events-<lastArchivedSeq>.json`); the boot timeline merges active +
+ * archives and dedupes by seq (active copy wins), so the rotation crash window
+ * yields the identical timeline. Archival naming is STRICTLY numeric
+ * (`/^events-\d+\.json$/`) — user files under the same directory are never
+ * read as archives and never pruned (rc.72 G-2).
+ */
+import { type EvolutionIoLike } from './io.ts';
+export declare const EVENT_LOG_VERSION = 1;
+/** Active-log split point (rc.71): when the active log reaches this many events
+ * the older half is rotated into an archive; the active stays bounded so a
+ * single append stays O(active) instead of O(total-history). Tunable default —
+ * callers may override per append (the tests use small values). */
+export declare const EVENT_LOG_ROTATE_AT = 4000;
+/** Number of archives retained (rc.71): older archives are pruned at rotation,
+ * mirroring retainReports. The horizon covers the loop-analysis window. */
+export declare const EVENT_LOG_RETAIN_ARCHIVES = 10;
+/** Archive file prefix: `events-<lastArchivedSeq>.json`. The active file is
+ * `events.json` and never matches this glob. */
+export declare const EVENT_ARCHIVE_PREFIX = "events-";
+export interface EvolutionEvent {
+    /** Global monotonic order key, assigned inside the append transact. */
+    seq: number;
+    /** ISO timestamp at append time. */
+    at: string;
+    /** Tagged-union discriminator: feedback increments vs learn actions. */
+    type: 'feedback' | 'learn';
+    target?: string | undefined;
+    kind?: 'skill' | 'session' | undefined;
+    rating?: 'positive' | 'negative' | undefined;
+    note?: string | undefined;
+    source?: string | undefined;
+    request?: string | undefined;
+}
+export declare function eventsFile(home: string): string;
+/**
+ * Parse an event log body. A missing file, a whitespace-only file (rc.69:
+ * rebuildable, NOT malformed) or a corrupt one reads as empty; corrupt content
+ * is still refused on append, never overwritten.
+ *
+ * Per-entry normalization (rc.70 F-1): entries without a numeric `seq` are
+ * skipped here and dropped at the next append — valid entries survive, the
+ * damaged record is the only loss (self-heal semantics, matching the usage
+ * sidecar's per-field normalization on read).
+ */
+export declare function parseEvolutionEvents(raw: string | null): EvolutionEvent[];
+/**
+ * List the numeric archives under the log's directory, sorted ascending by
+ * their last-archived seq. Single glob predicate for the timeline, the
+ * retention pass and the feedback migration check (rc.72 H-3).
+ */
+export declare function listEventArchives(io: EvolutionIoLike, path: string): Promise<string[]>;
+/**
+ * Append one event under the write lock (rc.68): `seq` = current max + 1
+ * computed inside the transact, so two processes appending concurrently never
+ * collide. A malformed log is refused (bytes preserved) and the append fails.
+ * Returns the assigned seq.
+ *
+ * Rotation (rc.71, 007 design): when the active log reaches `rotateAt`, the
+ * older half is copied into an archive inside the SAME transact (the archive
+ * path has its own lock, so no recursion) and the active is replaced with the
+ * newer half + the new event. seqs stay globally monotonic; a crash between
+ * archive write and active write leaves both copies, which the timeline merge
+ * dedupes by seq. An archive-write failure aborts the append (active keeps the
+ * full old content — no loss) and the caller's best-effort handling applies.
+ *
+ * rc.72 G-1: when the ACTIVE is missing/whitespace but archives exist (a
+ * deleted active, or B-2 self-heal), seq derivation consults the archive names
+ * — the active restarts AFTER the highest archived seq, never at 1, so a new
+ * event can never shadow an archived one in the seq-deduped timeline.
+ */
+export declare function appendEvolutionEvent(io: EvolutionIoLike, path: string, event: Omit<EvolutionEvent, 'seq' | 'at'>, rotateAt?: number): Promise<number>;
+/**
+ * Prune old event archives (rc.71): keep the newest `EVENT_LOG_RETAIN_ARCHIVES`.
+ * The name's numeric part is the last archived seq, so ordering is NUMERIC —
+ * lexicographic would rank `events-10` before `events-2`. Only strictly
+ * numeric names participate (rc.72 G-2: user files are never deleted).
+ * Best-effort per removal; exported for the retention test.
+ */
+export declare function retainEventArchives(io: EvolutionIoLike, path: string): Promise<void>;
+export interface EventLogRead {
+    events: EvolutionEvent[];
+    /** True when the body is not valid JSON (syntax-level damage): refused on
+     * append, bytes untouched. Well-formed JSON with a damaged `events` field
+     * is REPLACEABLE garbage — reads as empty and is rewritten at the next
+     * append (rc.70 F-1: read and append agree on the same boundary). A READ
+     * error (EISDIR etc.) also flags malformed — the file is unusable either
+     * way and is never overwritten (the append read would fail identically). */
+    malformed: boolean;
+}
+/** Read the event log; a missing/whitespace-only file reads as empty,
+ * corrupt content is flagged (and refused on append). */
+export declare function readEvolutionEvents(io: EvolutionIoLike, path: string): Promise<EventLogRead>;
+/**
+ * Read the full timeline (rc.71): active log + all archives, merged by seq
+ * (active copy wins, duplicates only arise from the rotation crash window),
+ * sorted ascending. Per-file malformed flag as in `readEvolutionEvents`; a
+ * malformed (or unreadable) ARCHIVE is skipped — it never bricks the boot and
+ * it is still flagged.
+ */
+export declare function readEvolutionTimeline(io: EvolutionIoLike, path: string): Promise<EventLogRead>;
+//# sourceMappingURL=evolution-events.d.ts.map

package/lib/types/gates.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The control-plane protection sets, held once and queried everywhere
+ * (decision B, rc.44 plan M2): the lifecycle engine, the scope view, the LLM
+ * nomination gate and the control-plane consolidate all answer "is this name
+ * off limits — and why" from the same instance, so the gate sets can never
+ * drift apart the way the three pre-rc.46 implementations did.
+ *
+ * Scope boundary: a GateSet covers NAME-SET protections only. Marker-based
+ * protections (pinned / bundled / hub-installed) are file markers resolved by
+ * `SkillLibrary.writeProtection` / `deleteProtection` — they depend on the
+ * filesystem and the write origin, not on a name list.
+ * @module @deepseek-ai/dsh-evolution-core
+ */
+export type GateReason = 'excluded' | 'referenced' | 'suppressed' | 'protected-builtin';
+export interface GateSetInputs {
+    exclude?: ReadonlySet<string> | undefined;
+    referenced?: ReadonlySet<string> | undefined;
+    suppressed?: ReadonlySet<string> | undefined;
+}
+export declare class EvolutionGateSet {
+    readonly exclude: ReadonlySet<string>;
+    readonly referenced: ReadonlySet<string>;
+    readonly suppressed: ReadonlySet<string>;
+    constructor(inputs?: GateSetInputs);
+    /**
+     * The first protection blocking this name, or null. Any hit blocks — the
+     * order is diagnostic only, so a name in two sets reports the first.
+     */
+    blockReason(name: string): GateReason | null;
+    isBlocked(name: string): boolean;
+}
+/** Build a GateSet from the curator-style config field names. */
+export declare function createGateSet(config: {
+    excludeSkillNames?: ReadonlySet<string>;
+    referencedSkillNames?: ReadonlySet<string>;
+    suppressedNames?: ReadonlySet<string>;
+}): EvolutionGateSet;
+//# sourceMappingURL=gates.d.ts.map

package/lib/types/index.d.ts

@@ -8,13 +8,19 @@
  * @module @deepseek-ai/dsh-evolution-core
  */
 export * from './curator.ts';
+export * from './evolution-events.ts';
+export * from './gates.ts';
 export * from './events.ts';
 export * from './io.ts';
+export * from './learn-prompt.ts';
 export * from './memory-store.ts';
+export * from './mutations.ts';
 export * from './prompts.ts';
+export * from './quality.ts';
 export * from './signals.ts';
 export * from './skill-store.ts';
 export * from './state-store.ts';
 export * from './threats.ts';
 export * from './usage.ts';
+export * from './constants.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/io.d.ts

@@ -1,9 +1,8 @@
 /**
- * Structural IO seam for the legacy facade stores.
+ * Structural IO seam for the evolution plugin family.
  *
- * The facade accepts any object exposing this small async file-tree surface.
- * Native DSH packages pass `ctx.evolutionIo.provider()`; standalone consumers
- * (and the facade's own tests) can use `nodeEvolutionIo`.
+ * Every evolution package passes `ctx.evolutionIo.provider()`; standalone
+ * consumers (and the core's own tests) can use `nodeEvolutionIo`.
  */
 export interface EvolutionIoLike {
     readText(path: string): Promise<string | null>;
@@ -13,7 +12,35 @@ export interface EvolutionIoLike {
     exists(path: string): Promise<boolean>;
     rename(path: string, destination: string): Promise<void>;
     copy(path: string, destination: string): Promise<void>;
+    /**
+     * Optional byte-size probe for the read guard. Return the file's size in
+     * bytes, or `null`/`undefined` when unknown (unsupported backend, missing
+     * file, stat failure). An implementation without this probe gets no guard:
+     * consumers treat an unknown size as "guard not applicable".
+     */
+    size?(path: string): Promise<number | null>;
+    /**
+     * Optional atomic read-modify-write on one file: the read and the write run
+     * inside a single cross-process lock, so two processes that share DSH_HOME
+     * cannot interleave their RMW sequences. `task` receives the current content
+     * (`null` when missing) and returns the next content; returning `null`
+     * deletes the file. A backend without it falls back to plain read+write and
+     * the caller keeps its single-process chain as the second layer.
+     */
+    transact?(this: void, path: string, task: (current: string | null) => Promise<string | null>): Promise<void>;
+    /**
+     * Optional symlink probe (G7). `true` = the path is a symlink, `false` = a
+     * real entry, `null` = guard not applicable (backend without the probe or
+     * the path does not exist). Consumers treat `null` as "let it through".
+     */
+    isSymlink?(this: void, path: string): Promise<boolean | null>;
 }
+/**
+ * Run `task` inside `io.transact` when the backend provides it; otherwise fall
+ * back to a plain read → task → write/remove sequence (no cross-process lock —
+ * callers keep their single-process serialize chain as the second layer).
+ */
+export declare function transactIo(io: EvolutionIoLike, path: string, task: (current: string | null) => Promise<string | null>): Promise<void>;
 /** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
 export declare function evolutionIoAdapter(provider: () => EvolutionIoLike): EvolutionIoLike;
 export declare function nodeEvolutionIo(): EvolutionIoLike;

package/lib/types/learn-prompt.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Open-ended `/evolution learn` prompt builder.
+ *
+ * `learn` is open-ended: the user can name anything they can describe — a
+ * directory of code, an API doc URL, a workflow they just walked the agent
+ * through, or pasted notes. The prompt instructs the live agent to gather the
+ * named sources with its existing tools, then author a single SKILL.md via
+ * `skill_manage` following `DSH_AUTHORING_STANDARDS`. There is no separate
+ * distillation engine and no model-tool footprint.
+ */
+/**
+ * Build the agent prompt for an open-ended `/evolution learn` request.
+ *
+ * @param userRequest free-text the user gave after `/evolution learn`; an
+ *   empty string falls back to "the workflow we just went through".
+ * @returns a complete instruction the agent runs as a normal turn.
+ */
+export declare function buildLearnPrompt(userRequest: string): string;
+//# sourceMappingURL=learn-prompt.d.ts.map

package/lib/types/memory-store.d.ts

@@ -3,7 +3,7 @@
  * Stores are MEMORY.md and USER.md under $DSH_HOME/memories (~/.dsh/memories).
  */
 import { type EvolutionIoLike } from './io.ts';
-export declare const ENTRY_DELIMITER = "\n\u00A7\n";
+export { ENTRY_DELIMITER } from './constants.ts';
 export type MemoryTarget = 'memory' | 'user';
 export interface MemoryOperation {
     action: 'add' | 'replace' | 'remove';
@@ -35,26 +35,69 @@ export declare class MemoryStore {
     private readonly maxFailures;
     private readonly io;
     private failureCount;
+    private lastFailureAt;
     constructor(options?: MemoryStoreOptions);
     limitFor(target: MemoryTarget): number;
+    /**
+     * Read-guard probe: `{ size, limit }` when the on-disk file exceeds
+     * `limit * READ_GUARD_FACTOR` bytes, `null` when it is absent, unknown
+     * (backend without a size probe), under the bound, or the target has no
+     * limit configured.
+     */
+    private oversizedFile;
     read(target: MemoryTarget): Promise<string[]>;
     write(target: MemoryTarget, entries: string[]): Promise<void>;
     resetFailures(): void;
     private failure;
+    /**
+     * StorageHint percentage must clamp at 100 like the render header: a drifted
+     * entry can push chars past the limit, and "Storage at 125%" contradicts the
+     * clamped usage indicator.
+     */
+    private storageHint;
+    /**
+     * Best-effort raw-copy backup of the on-disk file to `<file>.bak.<stamp>`
+     * before a refusal, so an externally modified (or oversized) file stays
+     * recoverable. Copies bytes instead of reading them so a pathologically
+     * large file is never loaded just to back it up. Failure to back up does
+     * not change the refusal semantics.
+     */
+    private backupFile;
+    /**
+     * Read-guard refusal for write paths. Returns the refusal result when the
+     * target file is oversized, `null` otherwise. The file is skipped for
+     * reading (never loaded), backed up by raw copy, and the model is told to
+     * fix it manually — mirroring the drift refusal so corrupted state is never
+     * silently overwritten.
+     */
+    private oversizedRefusal;
     add(target: MemoryTarget, facts: string): Promise<MemoryApplyResult>;
-    replace(target: MemoryTarget, oldText: string, facts: string): Promise<MemoryApplyResult>;
-    remove(target: MemoryTarget, oldText: string): Promise<MemoryApplyResult>;
-    private mutate;
+    /**
+     * Single-entry add inside the transaction: shared checks (oversized,
+     * drift, threat) and the content computation. `raw` is the locked view
+     * (`current`) — never a second IO read. `write: null` means "no change".
+     */
+    private addCore;
+    /** Canonical-form drift check derived from the locked view (same formula as `detectDrift`, no second read). */
+    private driftFromRaw;
     applyBatch(target: MemoryTarget, operations: MemoryOperation[]): Promise<MemoryApplyResult>;
+    /** Batch RMW inside the transaction. `write: null` = failure/no-op, disk untouched. */
+    private applyBatchCore;
     renderContext(): Promise<string>;
-    snapshot(): Promise<{
-        memory: string[];
-        user: string[];
-    }>;
-    restoreSnapshot(snapshot: {
-        memory: string[];
-        user: string[];
-    }): Promise<void>;
+    /**
+     * Detect on-disk drift: true when the file is not in the canonical
+     * `render(normalizeEntries(raw))` form. This catches structural anomalies
+     * the writer would quietly normalize away (empty/`§`-only entries, stray
+     * blank lines, leading/trailing delimiters) that indicate the file was
+     * edited outside MemoryStore. Purely single-canonical content reaches the
+     * same serialization and returns false, so a normal write is never flagged.
+     *
+     * An absent, empty, or whitespace-only file is the "never written" state
+     * (rc.42 audit P1-6): it parses to zero entries, so the canonical form
+     * `'\n'` can never byte-match it and every write path was permanently
+     * refused with "External drift detected" — including the repairs the model
+     * would need to make. Such files are adopted instead of flagged.
+     */
     detectDrift(target: MemoryTarget): Promise<boolean>;
 }
 //# sourceMappingURL=memory-store.d.ts.map

package/lib/types/mutations.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Curator/author audit trail: `.mutations.json` records every skill mutation
+ * with before/after content hashes so any automated edit is reviewable and
+ * replayable. Best-effort persistence, mirroring the usage sidecar posture.
+ * @module @deepseek-ai/dsh-evolution-core
+ */
+import { type EvolutionIoLike } from './io.ts';
+export interface MutationRecord {
+    skillName: string;
+    action: string;
+    beforeHash?: string;
+    afterHash?: string;
+    summary: string;
+    at: string;
+}
+export declare const DEFAULT_MUTATION_CAP = 500;
+/** Version of the `.mutations.json` file shape; writers always emit the current one. */
+export declare const MUTATIONS_FILE_VERSION = 1;
+export declare function mutationsFile(root: string): string;
+export declare function contentHash(content: string): string;
+export declare function loadMutations(root: string, io?: EvolutionIoLike): Promise<MutationRecord[]>;
+/** Append one record, trim to `cap`, and write atomically (versioned shape). */
+export declare function recordMutation(root: string, io: EvolutionIoLike, record: MutationRecord, cap?: number): Promise<void>;
+//# sourceMappingURL=mutations.d.ts.map