@lmzhen/dsh-evolution-core 0.3.62 → 0.3.64

package/lib/types/constants.d.ts

@@ -19,7 +19,13 @@
  * threshold, which are intentionally left where they are used.
  * @module @lmzhen/dsh-evolution-core
  */
-/** Skill frontmatter `name` validated for the file name (lowercase + hyphen). */
+/** Skill frontmatter `name` validated for the file name (lowercase + hyphen).
+ * 计划 B-4 (v18): tightened to the UPSTREAM `SKILL_NAME` shape
+ * (`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, packages/skill/skill/src/index.ts:20). The
+ * old form admitted trailing/consecutive hyphens, which upstream
+ * `validateCandidate` throws on — and that throw aborts the WHOLE `ctx.skills`
+ * collection. The catalog provider still filters such legacy tree entries so
+ * an existing tree cannot break a session. */
 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"];
@@ -53,6 +59,9 @@ 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;
+/** F-20 (v18): the authored-body budget and the hard ceiling are the same
+ * number today. Derive it so a future divergence is one edit, not two names
+ * that silently disagree. */
 export declare const DEFAULT_SKILL_CONTENT_CHARS = 100000;
 /** P3-19 (v14): defaults that were written twice (schema `.default()` AND the
  * clamp fallback literal) now have one home per value. */

package/lib/types/events.d.ts

@@ -12,10 +12,12 @@
  * these events off `session.append`). Plan-outcome durability lives in the
  * evolution-activity store, not the session log.
  */
+import type { ReviewKind } from './signals.ts';
 export interface EvolutionReviewScheduledEvent {
     /** Owning session (payload v2): process events carry no session envelope. */
     sessionId: string;
-    kind: 'memory' | 'skill' | 'combined';
+    /** F-20 (v18): single definition point — `ReviewKind` in signals.ts. */
+    kind: ReviewKind;
     toolCalls: number;
     userChars: number;
     assistantChars: number;

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

@@ -68,6 +68,17 @@ export interface EvolutionEvent {
     } | undefined;
 }
 export declare function eventsFile(home: string): string;
+/** I-5 (v18): one lightweight description of the durable event payload
+ * contract. The log is a FILE boundary (a host, a script or an older version
+ * can write it), so `appendEvolutionEvent` refuses a record no consumer can
+ * fold instead of persisting it and failing silently later. The process event
+ * bus stays unvalidated — that is a typed same-process boundary.
+ * @param event - the candidate event record.
+ * @returns a human-readable issue, or null when the record is well-formed.
+ */
+export declare function evolutionEventPayloadIssue(event: {
+    type?: unknown;
+} & Partial<EvolutionEvent>): string | null;
 export declare function parseEvolutionEvents(raw: string | null): EvolutionEvent[];
 /**
  * List the numeric archives under the log's directory, sorted ascending by

package/lib/types/io.d.ts

@@ -106,6 +106,21 @@ export declare function renameWithRetry(tmp: string, target: string, fn?: (from:
  * failing `handle.sync()` deterministically.
  */
 export declare function writeDurableTmp(target: string, content: string, openImpl?: typeof open): Promise<string>;
+/**
+ * True when the pid is alive (EPERM = alive but unowned; ESRCH = gone).
+ * V18 single source: the node backend's lock takeover and SkillLibrary's
+ * stranded-lock sweep must use the same liveness rule.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/** F-17 (v18): the write-lock protocol is a cross-module contract — the lock
+ * file is `<target>.lock` and its body is `<pid>:<token>`. This module creates
+ * them (`withWriteLock`) and `skill-store`'s probes/sweepers parse them, so both
+ * consume these two constants instead of repeating the literals. */
+export declare const LOCK_SUFFIX = ".lock";
+/** Writer-lock body shape: a decimal pid, a colon, then the claim token. A
+ * torn body (no parsable pid) still matches the `\\d+:` prefix rule only when
+ * the pid part is intact, which is what the takeover probe needs. */
+export declare const LOCK_BODY_RE: RegExp;
 /**
  * Build the Node IO backend. `lockAttempts` scales the write-lock retry budget
  * (attempts × 50ms); the default 40 (~2s, rc.69) covers production contention,

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

@@ -57,6 +57,10 @@ export declare class MemoryStore {
      * label (scanMemoryThreats already embeds it) plus the self-heal hint. */
     private memoryThreatBlock;
     limitFor(target: MemoryTarget): number;
+    /** P2-1 (v18): the generated date prefix participates in duplicate detection
+     * only when THIS store writes it. With addDatePrefix=false a fact's own
+     * leading `## YYYY-MM-DD\n` is content, not a generated prefix. */
+    private dedupeKey;
     /**
      * Read-guard probe: `{ size, limit }` when the on-disk file exceeds
      * `limit * READ_GUARD_FACTOR` bytes, `null` when it is absent, unknown

package/lib/types/quality.d.ts

@@ -11,9 +11,9 @@
  */
 import type { UsageMap } from './usage.ts';
 export interface QualityFactors {
-    /** 0.25 — use_count per day of age, capped at 1. */
+    /** 0.25 — skill LOADS per day of age (view_count + use_count), capped at 1. */
     usageFrequency: number;
-    /** 0.20 — 1 − patch/use (zero use = stable). */
+    /** 0.20 — 1 − patch/load (zero loads = stable). */
     stability: number;
     /** 0.20 — 1 under 30 idle days, linear decay to 0 at 180. */
     recency: number;

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

@@ -22,8 +22,15 @@ export interface SkillSummary {
     description: string;
     path: string;
     protectedBy: string | null;
+    /** A1-17 (v18): the marker probe itself failed (EACCES/EIO), so "no marker"
+     * cannot be told apart from "directory unreadable". Consumers must treat this
+     * as protected, never as unprotected. */
+    protectionUnknown: boolean;
     managed: boolean;
-    archived: boolean;
+    /** E-11 (v18): the frontmatter `whenToUse` routing hint, published so the
+     * platform catalog keeps it while this provider shadows the upstream
+     * filesystem provider. Absent when the frontmatter has none. */
+    whenToUse?: string;
 }
 export interface SkillActionResult {
     ok: boolean;
@@ -99,6 +106,21 @@ export declare function skillsRoot(env?: NodeJS.ProcessEnv): string;
 export declare function resolveSkillsRoot(config?: {
     root?: string | undefined;
 }): string;
+/** E-7 (v18): every family row reads ONE root key. `root` is canonical;
+ * `skillsRoot` is a deprecated alias honoured only while `root` is empty (so a
+ * deployment that sets both keeps the canonical one) and removed after 0.3.65.
+ * Callers log their own deprecation warning.
+ * @param config - the raw plugin config, carrying `root` and/or `skillsRoot`.
+ * @returns the effective root (empty when neither key is set) and whether the
+ * deprecated alias supplied it.
+ */
+export declare function resolveRootConfig(config?: {
+    root?: string | undefined;
+    skillsRoot?: string | undefined;
+}): {
+    root: string;
+    usedDeprecatedAlias: boolean;
+};
 /**
  * Map a requesting session onto the two origin surfaces (rc.44 plan M2-2.3):
  * the APPROVAL surface treats every delegated subagent as the autonomous
@@ -228,6 +250,11 @@ export interface AuthoringFeedback {
  * truncated or route-poor instead of silently shipping it.
  */
 export declare function authoringFeedback(frontmatter: Frontmatter): AuthoringFeedback;
+/** A1-6 (v18): the regex alone admits `references/nul.md` (a Windows device
+ * stem), which the support-file layer refuses. Restructure must use the same
+ * rule, or it creates an orphan the later patch/write/remove paths refuse.
+ * Single source shared with the plan validator. */
+export declare function validateRestructureTarget(filePath: string): string | null;
 export declare class SkillLibrary {
     readonly root: string;
     readonly limits: SkillLimits;
@@ -333,12 +360,64 @@ export declare class SkillLibrary {
      * marker write is the only state change; content is untouched.
      */
     setPinned(name: string, pinned: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
+    private setPinnedCore;
     create(name: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     private createCore;
     update(rawName: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     private updateCore;
     patch(rawName: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
     private patchCore;
+    /**
+     * P2-9 (v15): the destructive directory move shared by archive and
+     * restoreFromArchive — rename first, copy+remove fallback when the backend
+     * cannot rename across media (V5-35), with the E-14 rollback when the
+     * fallback's source removal fails. Returns a failure MESSAGE on a failed
+     * move (caller wraps into a structured result) or undefined on success.
+     */
+    private moveDir;
+    /**
+     * P2 (v16): the write-lock probe for the DESTRUCTIVE MOVERS (archive /
+     * restoreFromArchive). A byte-writer mid-flight is the ghost-generator —
+     * after the move its transact commit re-creates `<dir>/…` (mkdir
+     * recursive) and the tree ends half-archived. The signal is the writer's
+     * own lock file, and its PLACEMENT (inside the moved directory) is why the
+     * mover must PROBE-and-REFUSE instead of acquiring it: an acquired lock
+     * would be renamed into `.archive` with the tree, stranding a phantom live
+     * lock (the v16 audit proved the probe→rename TOCTOU does exactly that,
+     * and restore would later move the residue back into the live root).
+     * Coverage: `SKILL.md.lock` (update/patch of the body) plus one level of
+     * each support dir (write_file's lock sits next to its file). Residual:
+     * NESTED support-subdir locks and the probe→rename TOCTOU itself remain
+     * fail-safe (renameWithRetry rides the write out; the writer's locked
+     * re-read refuses on the moved-away file), and a residue `.lock` from a
+     * CRASHED writer also refuses — correct: inspect, don't archive.
+     */
+    private hasWriteLock;
+    /** P2 (v17): a file only counts as a writer lock when its body has the
+     * `pid:token` shape the io layer writes. User support files legitimately
+     * named `*.lock` (allowed by SUPPORT_FILE_NAME_RE) must not trip the probe
+     * or be swept as residue — the v16 first cut matched on suffix alone,
+     * which permanently refused archiving and deleted user content on restore. */
+    private isWriterLock;
+    /** P2 (v16): best-effort removal of lock residue inside a RESTORED tree.
+     * A1-2/A1-7 (v18): the sweep now covers the marker locks the probe checks
+     * (`SKILL.md.lock`/`.pinned.lock`/`.hermes-managed.lock`) and only removes
+     * a lock whose holder pid is NOT alive — a live writer's lock is never
+     * stolen by the sweep. A dead-pid residue would otherwise permanently
+     * refuse archive/restore. */
+    private deleteStrandedLocks;
+    /** Remove `lockPath` only when its body has the writer-lock `pid:token`
+     * shape AND the holder pid is not alive; anything else (a user support file
+     * or a live writer's lock) is left untouched. */
+    private sweepLockIfStranded;
+    /** A1-4 (v18): a manifest-declared name is copied with `join(root, name)`;
+     * only a single, non-traversing path component is safe. Dotfiles
+     * (`.usage.json`) stay allowed — sidecars are legitimately dot-prefixed. */
+    private safeSnapshotEntryName;
+    /** A1-7 (v18): a root-level lock whose holder is alive must refuse the
+     * restore; a dead residue is swept so a crashed writer cannot block
+     * recovery. A non-lock body shape is left alone (user file). */
+    private refuseLiveLockOrSweep;
     archive(rawName: string, options?: ArchiveOptions): Promise<SkillActionResult>;
     /**
      * Merge the bodies of `sources` into `target` and archive the sources with

package/lib/types/usage.d.ts

@@ -18,6 +18,16 @@ export interface UsageRecord {
     archived_at: string | null;
     quality_score?: number | undefined;
     quality_warn?: boolean | undefined;
+    /** P1-1 (v15): feedback-owned quality signal. Field ownership contract —
+     * `quality_score`/`quality_warn` are written ONLY by the curator's
+     * six-factor `scoreTree`; `feedback_score`/`feedback_warn` are written ONLY
+     * by the feedback channel (`SkillUsageRegistry.setFeedbackQuality`);
+     * `foldCuratorFields` refreshes the quality_* pair tree-wide and must never
+     * touch feedback_*. The lifecycle engine and the scope view read the UNION
+     * of both warn flags, which is what makes negative feedback decision-
+     * relevant again. */
+    feedback_score?: number | undefined;
+    feedback_warn?: boolean | undefined;
 }
 export type UsageMap = Map<string, UsageRecord>;
 export declare function usageFile(root: string): string;
@@ -60,6 +70,9 @@ export declare function applyCuratorLifecycleFields(disk: UsageRecord, curated:
  * Copy the recomputed meta pair (quality_score/quality_warn + the
  * marker-mirrored pin flag) — refreshed tree-wide each run by design, so a
  * concurrent curator run's lifecycle changes are never reverted by them.
+ * P1-1 (v15): the feedback pair (`feedback_score`/`feedback_warn`) is
+ * deliberately NOT copied — it is feedback-owned (see the field-ownership
+ * contract on {@link UsageRecord}) and must survive curator runs untouched.
  */
 export declare function applyCuratorMetaFields(disk: UsageRecord, curated: UsageRecord): void;
 /**
@@ -72,7 +85,7 @@ export declare function applyCuratorMetaFields(disk: UsageRecord, curated: Usage
  * transitioned — a concurrent curator run's archive/restore is never reverted
  * by a stale snapshot; without it both pairs apply everywhere.
  */
-export declare function foldCuratorFields(disk: UsageMap, curated: UsageMap, stateOwned?: ReadonlySet<string>): void;
+export declare function foldCuratorFields(disk: UsageMap, curated: UsageMap, stateOwned?: ReadonlySet<string>, runStartStates?: ReadonlyMap<string, string>): string[];
 /** Whole-file usage write (V6-37, 0.3.37): this is the ONE path that bypasses
  * the malformed-defense and the transact lock — prefer `mutateUsage` for any
  * read-modify-write so a concurrent writer cannot lose its update and 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.3.62",
+  "version": "0.3.64",
   "publishConfig": {
     "access": "public"
   },