@lmzhen/dsh-evolution-core 0.8.0 → 0.10.0

package/lib/types/constants.d.ts

@@ -21,7 +21,7 @@
  */
 /**
  * Required argument names per `skill_manage` action — the SINGLE SOURCE read
- * by the tool's argument gate (tool-skill-manage executeCore) and the plan
+ * by the tool's argument gate (tool-skill-manage write-gates.ts) and the plan
  * validator (evolution-plan-validator), so the two can never drift.
  * OPT-05 (2026-09): the plan validator used to accept a `write_file`/
  * `remove_file` op without `file_path` while the executor required it — the
@@ -52,6 +52,10 @@ 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;
+/** How many content versions to retain per skill (skill-history.ts). 20 mirrors the count
+ * KiroCrew settled on for the same job (its `MAX_SKILL_VERSIONS`), and is an E2 deployment
+ * parameter — the value is a retention policy, not a protocol constant. */
+export declare const DEFAULT_SKILL_VERSION_KEEP = 20;
 /** The authoring DISCIPLINE band, taken from the upstream standard (archive §5):
  * peer skills sit at 8-14k characters and a body pushing past 20k belongs in
  * `references/*.md`. Deliberately separate from `MAX_SKILL_CONTENT_CHARS`: the
@@ -128,6 +132,16 @@ export declare const EVOLUTION_WRITE_TOOLS: readonly ["memory", "skill_manage"];
  * 0.3.16 (T-4): moved here from skill-store.ts so drift-signals (pure, no IO)
  * can reference it without importing the skill-store module. */
 export declare const AUTHORING_DESCRIPTION_BAR = 60;
+/** The PLATFORM's default cap on the description a skill catalog shows —
+ * `catalogDescriptionMaxLength` on the platform's `tool-skill` row (default 500).
+ *
+ * Recorded here because it is the third number in the description-length relationship, and the one
+ * that is easiest to misread as a family rule: the family's own host/all rows SET that field to
+ * `AUTHORING_DESCRIPTION_BAR` (60), so what a family deployment truncates at is the ROW's value —
+ * this default only governs compositions that do not override it. It is NOT a refusal threshold:
+ * the only refusal is `MAX_DESCRIPTION_LENGTH` / the row's `maxDescriptionLength`, and the catalog
+ * cut is a view, not a validation. See tool-skill-manage/README.md for the three-number table. */
+export declare const PLATFORM_CATALOG_DESCRIPTION_DEFAULT = 500;
 /** The split hint both size refusals share (0.5.0 V1). The same sentence used to
  * be copied into validateFrontmatter AND the patch path, and neither copy named
  * where the content should go — the upstream cap message names the destination

package/lib/types/errors.d.ts

@@ -1,5 +1,6 @@
 /**
- * THE error-code table: E-301…E-316 with the exact text each one emits.
+ * THE error-code table: E-301…E-318 with the exact text each one emits (E-317 and E-318 are the
+ * write-admission gates' own refusals).
  *
  * The codes used to be spelled out at 33 call sites across two packages, so one
  * code's wording could drift between the branches that answer it and nothing could
@@ -33,6 +34,8 @@ export declare const EVOLUTION_ERRORS: Readonly<{
     readonly 'e-309-revision-conflict-message-Re': "E-309: revision conflict — %a1%. Re-read with /evolution params --json and retry.";
     readonly 'e-310-the-settings-service-refused': "E-310: the settings service refused the write: %a1% — the owning plugin's rule stands (a cross-field pair, or a cap that may only be tightened). /evolution params shows the current value.";
     readonly 'e-305-this-invocation-carries-no-2': "E-305: this invocation carries no agent — `%a1%` needs a session-backed call (run it from a session in the GUI or the CLI).";
+    readonly 'e-317-skill-write-not-confirmed': "E-317: skill \"%a1%\" was not %a2% — the confirmation prompt was declined or dismissed, so nothing was written. The prompt appears on every create and bare delete; repeat the call only if the operator asks for it.";
+    readonly 'e-318-skill-write-without-a-read': "E-318: skill \"%a1%\" was not read in this session, so this write is refused. Read it with the `skill` tool first (a read that failed does not count), then repeat the write.";
 }>;
 /** One table key. */
 export type EvolutionErrorId = keyof typeof EVOLUTION_ERRORS;

package/lib/types/events.d.ts

@@ -57,6 +57,13 @@ export interface EvolutionPlanAppliedEvent {
     skippedUnread?: number | undefined;
     /** First execution-layer failure message (abort reason or op failure). */
     executionError?: string | undefined;
+    /** Batch D (2026-09-27): ops whose ENTIRE evidence list cites bookkeeping frames
+     * (a turn/step boundary) — the report-only phase of the plan path's
+     * `EVIDENCE_CLASS` rule. Not a refusal and not a "not done" cause: the ops in
+     * this count executed. It rides the same payload as the other dimensions so the
+     * observation window has a durable record; the model's notice says nothing about
+     * it. */
+    evidenceClassReports?: number | undefined;
     evidenceQuotes?: number | undefined;
     estimatedInputChars?: number | undefined;
 }

package/lib/types/evidence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Which session frames are EVIDENCE, and which are bookkeeping.
+ *
+ * A plan op must cite `evidence` seqs, and the validator's range rule
+ * (`evolution-plan-validator`, rule `EVIDENCE_RANGE`) answers only "is this an integer inside
+ * the window the plan was authored against". A boundary frame satisfies that while carrying
+ * nothing a claim can rest on: the `turn/start` seq is the frame a claim about that turn was
+ * most likely read out of, and citing it is indistinguishable from citing a real exchange. This
+ * module owns the ONE classification of a session frame by what it CARRIES, so the plan path can
+ * report an op whose whole citation list is bookkeeping (design
+ * `dsh-evolution-skill-history-design.md` §3D, phase 1: report only — no op is refused here).
+ *
+ * The classification is a DENY list of the pure bookends, not an allow list of content frames.
+ * The platform's own vocabulary (`KNOWN_SESSION_EVENT_TYPES`, 57 members at 0.1.5-rc.2) mixes
+ * content frames with state-change frames, and out-of-repo plugins append types the family cannot
+ * enumerate; an unknown frame is therefore treated as carrying content, because a report that
+ * fires on an unclassifiable frame is a false positive and phase 1 exists to measure how many TRUE
+ * ones there are. Tightening — a narrower definition, or an allow list built from the platform's
+ * vocabulary — changes this table and nothing else (`evidenceKindIndex` is the only reader).
+ * @module @lmzhen/dsh-evolution-core
+ */
+/** One session frame, as far as the classification reads it. A platform `SessionEvent` is
+ * assignable: both fields are optional here so a stub log can be classified without pretending
+ * to be a full event. */
+export interface EvidenceFrame {
+    /** The platform event type. An unknown value counts as content (see the module docblock). */
+    type?: unknown;
+    /** The durable sequence number a plan op cites. */
+    seq?: unknown;
+}
+/**
+ * The seqs of the frames that carry content.
+ *
+ * @param events - the session's frames, oldest first (any iterable; nothing is retained).
+ * @returns the substantive seqs, or `undefined` when NO frame carried a usable seq. The two
+ *   answers are different facts: an empty SET says "every sequenced frame is a boundary", while
+ *   `undefined` says "this log cannot tell a boundary from a message" (a stub session in a test,
+ *   a composition whose events carry no seq). A caller that cannot classify must stay silent
+ *   rather than report every op — the same three-state posture as `sessionReadSkillNames`.
+ */
+export declare function evidenceKindIndex(events: Iterable<EvidenceFrame>): ReadonlySet<number> | undefined;
+//# sourceMappingURL=evidence.d.ts.map

package/lib/types/index.d.ts

@@ -20,9 +20,11 @@
  *   evolution-policy/threat, both stores, review, maintenance.
  * - **Core domain stores/logic** — `skill-store.ts` (skill tree engine +
  *   IO-seam consumer), `memory-store.ts`, `usage.ts`, `curator.ts`,
- *   `quality.ts`, `signals.ts`, `drift-signals.ts`, `skill-health.ts`,
+ *   `quality.ts`, `signals.ts`, `skill-reads.ts` (the read-before-write rule, shared by the
+ *   tool path and the review's plan path), `drift-signals.ts`, `skill-health.ts`,
  *   `preset-composition.ts`, `prompts.ts`, `learn-prompt.ts`,
- *   `evolution-events.ts`, `io.ts` (the ctx.evolutionIo seam itself).
+ *   `evolution-events.ts`, `evidence.ts` (which session frames count as content, for the plan
+ *   path's evidence-class report), `io.ts` (the ctx.evolutionIo seam itself).
  * @module @lmzhen/dsh-evolution-core
  */
 export * from './citations.ts';
@@ -50,7 +52,10 @@ export * from './write-inventory.ts';
 export * from './scope.ts';
 export * from './skill-health.ts';
 export * from './signals.ts';
+export * from './skill-reads.ts';
+export * from './evidence.ts';
 export * from './drift-signals.ts';
+export * from './skill-history.ts';
 export * from './skill-store.ts';
 export * from './state-store.ts';
 export * from './threats.ts';

package/lib/types/limits.d.ts

@@ -78,6 +78,9 @@ export interface SkillLimits {
     archiveRetention?: ArchiveRetentionPolicy | undefined;
     /** See SupportFileCharPolicy; absent means the default (`report`). */
     supportFileCharPolicy?: SupportFileCharPolicy | undefined;
+    /** Content versions retained per skill (skill-history.ts); absent means
+     * `DEFAULT_SKILL_VERSION_KEEP`. */
+    versionKeep?: number | undefined;
 }
 export declare const DEFAULT_SKILL_LIMITS: SkillLimits;
 //# sourceMappingURL=limits.d.ts.map

package/lib/types/mutations.d.ts

@@ -10,6 +10,11 @@ export interface MutationRecord {
     action: string;
     beforeHash?: string;
     afterHash?: string;
+    /** The skill-history version the content on each side of this mutation belongs to
+     * (skill-history.ts). Optional: records written before content history existed carry none, and
+     * the hashes above stay the authority for "what changed". */
+    beforeVersion?: number;
+    afterVersion?: number;
     summary: string;
     at: string;
 }

package/lib/types/params.d.ts

@@ -43,6 +43,12 @@ export declare function canonicalWriteId(id: string): string;
 export declare function readParam(carrier: object | undefined, id: string): unknown;
 /** Exposure group (design §7.2): the unit a developer changes together. */
 export type ParamGroup = 'library' | 'write-caps' | 'review' | 'memory' | 'curator' | 'deployment' | 'internal';
+/**
+ * Chinese display name per group, one entry per line (the scripts read this block
+ * by text, the same way they read PARAM_NAMESPACES). The raw group id is what
+ * `--group` accepts and what the JSON face reports; this only names it on screen.
+ */
+export declare const PARAM_GROUP_LABELS: Readonly<Record<ParamGroup, string>>;
 /** Exposure tier (design §7.1): the interface combination a parameter gets. */
 export type ParamTier = 'E0' | 'E1' | 'E2' | 'E3' | 'E4';
 /** Where the authoritative value lives. */
@@ -61,14 +67,17 @@ export type ParamAuthority = 'code' | 'cordis' | 'install';
  * writable through the user layer (a cordis.yml change still follows the
  * deployment's patch-reload policy).
  *
- * UI METADATA (0.7.0): every E3 row carries the optional tail
+ * UI METADATA (0.7.0): every E3 row carries the tail
  * `label, hint, control, unit, values` — in that order, directly after
- * `summary`, still one entry per line. E3 is the only tier the settings cards
- * render, so the card's Chinese name, help text, control kind, unit suffix and
- * value domain come from THIS registry and nowhere else; the browser half is
- * generated from this text (`gen-param-client-view.mjs`). Non-E3 rows must NOT
- * carry the tail (there is no UI surface for them), and `control: 'select'`
- * requires a non-empty pipe-joined `values`.
+ * `summary`, still one entry per line — plus an OPTIONAL trailing
+ * `valueLabels` (0.9.0). E3 is the only tier the settings cards render, so the
+ * card's Chinese name, help text, control kind, unit suffix and value domain
+ * come from THIS registry and nowhere else; the browser half is generated from
+ * this text (`gen-param-client-view.mjs`). Non-E3 rows must NOT carry the tail
+ * (there is no UI surface for them); `control: 'select'` requires a non-empty
+ * pipe-joined `values`, and `valueLabels` — allowed on select rows only — names
+ * those values for display, one label per value, in the same order. The stored
+ * value is never translated: only what the control shows.
  */
 export interface ParamExposure {
     id: string;
@@ -89,6 +98,11 @@ export interface ParamExposure {
     unit?: string;
     /** Pipe-joined allowed values; non-empty exactly when control is 'select'. */
     values?: string;
+    /**
+     * Pipe-joined display names for `values`, same order and count (optional).
+     * The stored value stays the raw one; this only names it on the card.
+     */
+    valueLabels?: string;
 }
 /**
  * The parameter registry. G1/S1.1 seeds it with the review group (G-C); the

package/lib/types/quality.d.ts

@@ -7,6 +7,12 @@
  * mutation maturity is a documented DSH approximation (single per-month patch
  * trend ratio replaces the claw timestamp-trend formula, since DSH usage
  * records only carry the last patched timestamp).
+ *
+ * Batch C (2026-09-27): the similarity half of this module is now TWO NAMED
+ * QUESTIONS plus a declared projection — {@link identity} ("is it the same
+ * text?") and {@link affinity} ("how much vocabulary do these two share?") asked
+ * over {@link projectionText}. Callers name the question and the projection
+ * instead of growing a fourth unnamed ruler (design §3C / §1 I2).
  * @module @lmzhen/dsh-evolution-core
  */
 import type { UsageMap } from './usage.ts';
@@ -45,6 +51,52 @@ export declare function computeQualityScores(input: {
     supportDirs?: ReadonlyMap<string, number>;
     now?: Date;
 }): Map<string, QualityScore>;
+/** Named similarity question 1 — "is it the same text?" — as a normalized
+ * content hash: case- and whitespace-insensitive, so two texts that differ only
+ * in formatting are the SAME text here. Invariant under which projection the
+ * caller read the text from.
+ *
+ * C-26 (v10 audit): NOT named `contentHash` — mutations.ts exports a
+ * contentHash of RAW bytes, this one hashes the NORMALIZED text for dedup
+ * grouping. Same helper as that rename, now a named question. */
+export declare function identity(text: string): string;
+/** Which text a similarity question is asked about. Declared by the caller. */
+export type SimilarityProjection = 'body' | 'summary';
+/** The one input shape both projections read from: a caller passes what it has. */
+export interface SimilarityInput {
+    /** The whole SKILL.md — the `body` projection. */
+    content?: string;
+    /** The skill name — half of the `summary` projection. */
+    name?: string;
+    /** The frontmatter description — half of the `summary` projection. */
+    description?: string;
+}
+/**
+ * The declared projection: WHICH text a comparison weighs.
+ *
+ * `body` is the library-wide scan's projection (whole SKILL.md, read by the
+ * caller). `summary` is name + description in one string — the projection a
+ * listing already publishes (`SkillSummary` carries both fields, and a body is
+ * attached only when the caller asks for it) — so a summary comparison never
+ * reads a body OF ITS OWN: the create-time hint is fed by the listing pass the
+ * tool already pays for its frontmatter, and calls no read of its own.
+ */
+export declare function projectionText(projection: SimilarityProjection, input: SimilarityInput): string;
+/** The comparable vocabulary of one text: lowercase alphanumeric runs, plus
+ * whole CJK runs (a Chinese description tokenizes by punctuation, not by word —
+ * deliberately: the ruler is one home, and a real tokenizer is a different
+ * question than "do these two share vocabulary?"). */
+export declare function vocabulary(text: string): ReadonlySet<string>;
+/** Named similarity question 2 — "how much vocabulary do these two share?" —
+ * Jaccard over two {@link vocabulary} sets, 0 (nothing in common, or either side
+ * empty) to 1 (identical vocabulary). Set-based on purpose: the bulk scan
+ * memoizes each name's set once and only the comparisons are budgeted. */
+export declare function affinity(a: ReadonlySet<string>, b: ReadonlySet<string>): number;
+/** The `affinity` level at which two bodies are treated as the same skill
+ * (design §3C: the default is unchanged at 0.95 — it is now a NAME, because the
+ * docblock below has linked it since PLAN-R2 while the code carried a bare
+ * literal). Callers may still pass their own level. */
+export declare const DEDUP_SIMILARITY_THRESHOLD = 0.95;
 /** PLAN-R2 P2-8 (2026-09-16): default cap on two-name comparisons in
  * {@link computeDedupGroups}. A 2000-skill library is ~2M pairs; the old
  * unbounded two-two Jaccard ran seconds to tens of seconds per
@@ -79,6 +131,45 @@ export declare function computeDedupGroups(input: {
      * {@link DEDUP_MAX_PAIR_COMPARISONS}; a smaller value truncates earlier. */
     maxPairComparisons?: number;
 }): DedupScanResult;
+/**
+ * The create-time near-duplicate question (batch C, design §3C-2): WHICH
+ * existing skills is this authoring candidate about to near-copy?
+ *
+ * It is the SAME {@link affinity} question as the library-wide scan, asked over
+ * the `summary` projection — the one a listing already publishes
+ * (`SkillSummary` carries `name` and `description`; nothing here can see a
+ * body, which is the point: a create must not pay a SECOND whole-tree pass — the
+ * listing's own frontmatter read is what feeds this comparison). Deliberately hint-only: the caller writes regardless, and the
+ * matches are news, not a gate (G4 — the create-time foreground behavior is
+ * unchanged).
+ *
+ * The default level is far below the scan's {@link DEDUP_SIMILARITY_THRESHOLD}
+ * because the projection is thinner: a name plus one sentence shares far fewer
+ * tokens than two bodies, and a hint that fires on every new skill is noise.
+ * Exact same-name candidates are skipped — the library's own create refuses
+ * those, and this line must not repeat that refusal.
+ */
+export declare const SUMMARY_DUPLICATE_HINT_THRESHOLD = 0.5;
+/** The fields {@link nearDuplicateSummaries} weighs — a structural subset of
+ * `SkillSummary`, so a listing feeds it without a conversion. */
+export interface SummaryCandidate {
+    name: string;
+    description?: string;
+}
+export interface SummaryMatch {
+    name: string;
+    /** The `summary`-projection {@link affinity} in 0..1. */
+    score: number;
+}
+export declare function nearDuplicateSummaries(input: {
+    candidate: SummaryCandidate;
+    existing: ReadonlyArray<SummaryCandidate>;
+    /** Level at which a match is reported. Defaults to
+     * {@link SUMMARY_DUPLICATE_HINT_THRESHOLD}. */
+    threshold?: number;
+    /** Cap on returned matches, closest first. Defaults to 3. */
+    limit?: number;
+}): SummaryMatch[];
 /**
  * Prefix-cluster index over a name set (rc.67 merge heuristic, input side):
  * the curator prompt asks the model to identify "prefix clusters — skills

package/lib/types/skill-history.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Skill content history: content-addressed blobs plus a per-skill version index.
+ *
+ * Why it exists: `.mutations.json` records before/after HASHES and calls every automated edit
+ * "reviewable and replayable" — but a hash cannot be replayed. With no content store, the only way
+ * back was a whole-tree snapshot (`.backups`, keep=5) or `.archive` (removed skills only), so
+ * reverting one skill cost the collateral of every other change in that window. This module keeps
+ * the content, keyed by skill and version.
+ *
+ * Invariants (design `dsh-evolution-skill-history-design.md` §1):
+ *  - HISTORY IS HISTORY: the skill tree stays the single truth for "current content"; nothing here
+ *    feeds a judgment — callers read back content and version NUMBERS only.
+ *  - BEST-EFFORT, like the mutation audit: a failed history write warns and never fails the write
+ *    that already landed.
+ *  - Blobs are content-addressed, so identical bodies are stored once (across skills too).
+ *  - Versions are numbered by `v` (max+1), NOT by the clock: a moved system clock must not reorder
+ *    history (KiroCrew's `v<N>` choice, independently arrived at). Numbering and the index read-modify-write run
+ *    under the INDEX's own io lock, so two writers of one skill cannot mint the same number.
+ *  - The array's ORDER is append order, and the index is appended after the content lock is released, so two
+ *    writers of ONE skill can interleave their appends. Each entry therefore carries `beforeHash` — the content
+ *    it replaced, read under that writer's lock — and that link, not the position, is what `undo` follows
+ *    ({@link orderVersions} rebuilds the content order for display when the chain is complete).
+ *
+ * NOT here: blob garbage collection. Trimming drops INDEX entries; orphan blobs stay until a
+ * sweeper collects them, because a reference count would have to span every skill's index and that
+ * belongs to the curator's whole-library pass, not to the write path.
+ * @module @lmzhen/dsh-evolution-core/skill-history
+ */
+import { type EvolutionIoLike } from './io.ts';
+/** Root-level history directory. Dot-prefixed so skill discovery skips it. */
+export declare const HISTORY_DIR = ".history";
+/** Versioned index shape, so a future field can migrate without guessing. */
+export declare const HISTORY_INDEX_VERSION = 1;
+/** The action label for a predecessor the index had never seen (content found on disk before this
+ * feature existed, or a hand-edited tree): it says "this is what was there", not what wrote it. */
+export declare const BASELINE_ACTION = "baseline";
+/** One recorded version of one skill. */
+export interface SkillVersion {
+    /** Monotonic per skill; the identity, unlike {@link SkillVersion.at}. */
+    v: number;
+    at: string;
+    /** The mutation that produced it (`create`/`update`/`patch`/…), or {@link BASELINE_ACTION}. */
+    action: string;
+    /** sha256 of the stored content. */
+    hash: string;
+    /** Content length in characters, so a listing needs no blob read. */
+    chars: number;
+    /** The content this write REPLACED, as its hash — absent on a create, on a baseline, and on any
+     * entry written before 0.10.0. The array's ORDER is append order, which two writers of one skill
+     * can interleave (the index is appended after the content lock is released); this link is computed
+     * from the bytes a write lock actually read, so it is the authoritative predecessor. */
+    beforeHash?: string;
+}
+/** One history write, carrying the content the caller already holds. */
+export interface VersionRecordInput {
+    skillName: string;
+    action: string;
+    /** Content before the mutation, or null when there was none (create/restore). */
+    before: string | null;
+    /** Content after the mutation, or null when there is none (archive/remove_file). */
+    after: string | null;
+    at: string;
+}
+/** The version numbers one write produced; a side with no content contributes nothing. */
+export interface RecordedVersions {
+    beforeVersion?: number | undefined;
+    afterVersion?: number | undefined;
+}
+/** The root-level history directory. */
+export declare function historyRoot(root: string): string;
+/** Content-addressed blob path: identical bodies share one file, across skills too. */
+export declare function blobPath(root: string, hash: string): string;
+/** One skill's index file. */
+export declare function historyIndexFile(root: string, name: string): string;
+/**
+ * The versions in CONTENT order (oldest first), rebuilt from the chain links, for display.
+ *
+ * The stored array is append order, which interleaves when two writers of one skill audit out of
+ * order; the links say what actually replaced what. The rebuild runs only when it can account for
+ * EVERY entry (exactly one start and a forward link for each step) — otherwise the stored order is
+ * returned unchanged, because a partial reconstruction would be a worse answer than the honest one.
+ * @param versions - the stored index, oldest first as recorded.
+ * @returns the same entries, in content order when the chain is complete.
+ */
+export declare function orderVersions(versions: readonly SkillVersion[]): SkillVersion[];
+/** What one index file's bytes said. `absent` (no file yet) and `unreadable` (bytes that cannot be
+ * understood: malformed JSON, a foreign shape, an entry this reader would have to drop, or a writer
+ * NEWER than this reader) are DIFFERENT facts — the recorder must never replace the second with an
+ * index derived from "nothing", so it preserves those bytes instead. */
+export type HistoryIndexState = {
+    readonly kind: 'ok';
+    readonly versions: SkillVersion[];
+} | {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'unreadable';
+};
+/**
+ * Read one index body for a RECORDER: "understood", "no file", or "cannot be understood".
+ * A file whose shape is right but which carries an entry this reader would have to drop counts as
+ * unreadable — dropping it silently would be the overwrite the audit posture forbids.
+ * @param raw - the index file's bytes, or null when absent.
+ * @returns the three-state answer.
+ */
+export declare function readHistoryIndex(raw: string | null): HistoryIndexState;
+/**
+ * Parse one index body for a READER. Malformed content, a foreign shape, or a version NEWER than this
+ * reader all read as empty — the audit posture: never guess. A recorder must use
+ * {@link readHistoryIndex} instead, because it has to PRESERVE bytes it cannot understand.
+ * @param raw - the index file's bytes, or null when absent.
+ * @returns the versions, oldest first.
+ */
+export declare function parseHistoryIndex(raw: string | null): SkillVersion[];
+/**
+ * The index after this write, and the version numbers it produced. Pure, so the versioning rules
+ * are testable without io.
+ *
+ * Two rules matter here: a predecessor the index has never seen gets a BASELINE entry (so the state
+ * before this mutation is recoverable even for a skill that predates the feature), and re-writing
+ * identical content mints NO new version (the library's no-op updates must not grow history).
+ * @param versions - the current index, oldest first.
+ * @param input - the write being recorded.
+ * @param keep - how many versions to retain per skill.
+ * @returns the trimmed index and the recorded numbers.
+ */
+export declare function nextHistoryIndex(versions: readonly SkillVersion[], input: VersionRecordInput, keep: number): {
+    versions: SkillVersion[];
+    recorded: RecordedVersions;
+};
+/** Shrink level at which the retention line speaks: a body that keeps less than this share of the
+ * previous one is a rewrite, not an edit. */
+export declare const RETENTION_FEEDBACK_KEEP_RATIO = 0.5;
+/** Floor on the REPLACED body: below this a ratio is noise (a 40-character skill cut in half is not
+ * news), so the line stays off for small skills. */
+export declare const RETENTION_FEEDBACK_MIN_CHARS = 200;
+/** What {@link contentRetentionFeedback} reads: the one write it describes. */
+export interface RetentionFeedbackInput {
+    /** The skill's name, for the sentence. */
+    readonly name: string;
+    /** The action that produced the write; only a whole-body replacement is described. */
+    readonly action: string;
+    /** The replaced body, or null when the skill had none (create / restore). */
+    readonly before: string | null;
+    /** The body now on disk, or null when it was removed (archive / remove_file). */
+    readonly after: string | null;
+}
+/**
+ * The anti-overwrite feedback line (design §4, item 3): says how much of the previous body a
+ * replacement kept, so a destructive rewrite is visible in the same message that reports the write.
+ *
+ * Computed where the replaced bytes are still in hand — the write path's own in-lock read — instead of
+ * re-reading the file from a caller (that second read would race the writers this library serializes).
+ * It is FEEDBACK, never a gate: no ratio refuses a write, and the function owns no configuration
+ * (a toggle nobody reads would be configuration that does nothing).
+ *
+ * @param input - the write being described.
+ * @returns the line, or null when the write is not a significant whole-body replacement.
+ */
+export declare function contentRetentionFeedback(input: RetentionFeedbackInput): string | null;
+/**
+ * Read one skill's versions, oldest first.
+ * @param root - the skills root.
+ * @param io - the io seam.
+ * @param name - the skill name.
+ * @returns the versions; an absent or unreadable index reads as empty (never a throw).
+ */
+export declare function loadVersions(root: string, io: EvolutionIoLike, name: string): Promise<SkillVersion[]>;
+/**
+ * One version's content.
+ * @param root - the skills root.
+ * @param io - the io seam.
+ * @param name - the skill name.
+ * @param v - the version number.
+ * @returns the content, or null when the version or its blob cannot be read (never '').
+ */
+export declare function loadVersionContent(root: string, io: EvolutionIoLike, name: string, v: number): Promise<string | null>;
+/**
+ * Record the content one mutation produced, best-effort.
+ *
+ * Blobs are written FIRST: the index must never reference content that is not on disk, and a failed
+ * blob write aborts the whole record (the caller warns; the mutation itself stands).
+ * @param root - the skills root.
+ * @param io - the io seam.
+ * @param input - the write being recorded.
+ * @param keep - how many versions to retain per skill.
+ * @returns the version numbers, or null when there was no content to record.
+ */
+export declare function recordVersions(root: string, io: EvolutionIoLike, input: VersionRecordInput, keep: number): Promise<RecordedVersions | null>;
+//# sourceMappingURL=skill-history.d.ts.map

package/lib/types/skill-reads.d.ts

@@ -0,0 +1,47 @@
+/** The session-log accessor the platform exposes (0.1.5 on; `session.events` before it). */
+export interface EvolutionSessionLogView {
+    /** @returns the session's events, oldest first. */
+    snapshotEvents?: () => Iterable<{
+        type: string;
+        data?: unknown;
+    }>;
+}
+/**
+ * The skill names ONE session read, or `undefined` when its log is not readable.
+ *
+ * `undefined` is NOT an empty set: a caller that must decide (the tool path's read-before-write
+ * gate) can then keep its previous behavior instead of refusing every write in a composition whose
+ * session objects expose no log at all.
+ * @param session - the session whose reads are wanted; `undefined` when the call carries none.
+ * @returns the names read through a non-failed `skill` dispatch, or `undefined` when unreadable.
+ */
+export declare function sessionReadSkillNames(session: EvolutionSessionLogView | undefined): ReadonlySet<string> | undefined;
+/** Actions whose target must have been read first (create is authorship, so it is exempt). */
+export declare const READ_REQUIRED_ACTIONS: readonly string[];
+/**
+ * Does this one op write a skill the caller never read?
+ *
+ * V6-26 (0.3.37): the validator normalizes a missing action to `patch`, so a missing action is a
+ * read-required write, never silently exempt.
+ * @param op - one skill operation (from a tool call or a review plan).
+ * @param readNames - names read this session, from {@link collectReadSkillNames}.
+ * @returns true when the op is a read-required write to an unread target.
+ */
+export declare function isUnreadWrite(op: {
+    action?: string;
+    name?: string;
+}, readNames: ReadonlySet<string>): boolean;
+/**
+ * Drop mutating ops whose target was not read this session, in place.
+ *
+ * Covers the same mutating surface Hermes guards (edit/patch/write_file/remove_file), so a
+ * background review cannot blind-touch support files or edits of skills it never loaded.
+ * @param ops - the plan's ops; dropped entries are removed in place.
+ * @param readNames - names read this session.
+ * @returns the count of dropped ops, so the plan event can report them as rejected.
+ */
+export declare function filterUnreadSkillOps(ops: Array<{
+    action?: string;
+    name?: string;
+}>, readNames: ReadonlySet<string>): number;
+//# sourceMappingURL=skill-reads.d.ts.map

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

@@ -36,6 +36,7 @@ import { transactIo, type EvolutionIoLike } from './io.ts';
 import { type Probe } from './probe.ts';
 import type { SkillLimits } from './limits.ts';
 import { type MutationRecord } from './mutations.ts';
+import { type SkillVersion } from './skill-history.ts';
 import { type SkillHealthAssessment, type SkillHealthThresholds } from './skill-health.ts';
 import type { EvolutionSkillMutatedEvent } from './events.ts';
 export interface SkillSummary {
@@ -272,6 +273,9 @@ export declare class SkillLibrary {
     /** V10-03 (P2-18): see the constructor's threatExemptLabels. Empty by
      * default — the strict ANY-hit-blocks policy is unchanged. */
     private readonly threatExemptLabels;
+    /** skill-history.ts: the content history is best-effort, so a failure must not be SILENT —
+     * but it is a deployment condition, not a per-write event, so it warns once per instance. */
+    private historyWarned;
     constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void, transact?: typeof transactIo, threatExemptLabels?: readonly string[]);
     /**
      * Run one single-file read-modify-write for a mutator. When `transact` was
@@ -394,10 +398,34 @@ export declare class SkillLibrary {
         patchCount?: number;
         readCount?: number;
     }): Promise<SkillHealthAssessment | null>;
-    /** Best-effort audit trail entry; never blocks the mutation. */
+    /** Best-effort audit trail entry; never blocks the mutation.
+     *
+     * Two independent best-effort writes run here, because either one failing must not cost the
+     * other: the CONTENT history (skill-history.ts, so a version can be read back at all) and the
+     * mutation ledger that points at it. The history failure is not silent — a deployment whose
+     * history stopped growing is a degradation worth seeing once (the ledger keeps hashes either
+     * way). */
     private audit;
     /** Recent mutation audit records (read-only inspection surface). */
     listMutations(): Promise<MutationRecord[]>;
+    /**
+     * Content versions recorded for one skill, oldest first (skill-history.ts, batch A).
+     *
+     * Read-only: the version seam never feeds a judgment — callers use it to LIST and to read content
+     * back. A malformed or unreadable index reads as empty, and a bad name reads as empty too (the
+     * caller is a human command, so "no versions" is the honest answer for a name that cannot exist).
+     * @param rawName - the skill's name.
+     * @returns the versions, oldest first.
+     */
+    listVersions(rawName: string): Promise<SkillVersion[]>;
+    /**
+     * One version's content, read back from the content-addressed blob store.
+     * @param rawName - the skill's name.
+     * @param v - the version number (see {@link SkillLibrary.listVersions}).
+     * @returns the content, or null when the version does not exist, the name is unusable, or the
+     *   blob cannot be read — never an empty string.
+     */
+    readVersion(rawName: string, v: number): Promise<string | null>;
     /**
      * Pin or unpin a skill (`.pinned` marker). Pinned skills are protected from
      * deletion, from background-review writes, and from the lifecycle — a

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },