@lmzhen/dsh-evolution-core 0.3.63 → 0.3.65

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,13 +250,11 @@ export interface AuthoringFeedback {
  * truncated or route-poor instead of silently shipping it.
  */
 export declare function authoringFeedback(frontmatter: Frontmatter): AuthoringFeedback;
-/** C-18: win32 reserves these stems with ANY extension (`nul.md` hits the
- * NUL device), and they are fully inside the charset above — so the reserved
- * set is checked on the first-dot prefix as well; the charset close alone
- * cannot refuse them. Exported single source: `badName` (skill directories,
- * P2-11/v15) and `validateSupportPath` (support-file stems, C-18) both
- * consume this one set — a third copy would drift. */
-export declare const WIN32_RESERVED_DEVICE_NAMES: ReadonlySet<string>;
+/** 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;
@@ -340,6 +360,7 @@ 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>;
@@ -378,15 +399,27 @@ export declare class SkillLibrary {
      * 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 —
-     * a `.lock` that a pre-restore crash or TOCTOU stranded in `.archive`
-     * cannot have a live writer (restore refuses when the live root is
-     * locked), and if left in place its body (a live pid on a single-host
-     * deployment) structurally closes the writer's self-heal path. */
+    /** 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; anything else (a user support file) is left untouched. */
+     * 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.
+     * P2-4 (v19): a non-string entry (`skills: [123]`) is refused structurally
+     * instead of throwing `name.includes is not a function`. */
+    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/threats.d.ts

@@ -2,15 +2,25 @@
  * Threat scanning for agent-authored memory and skill content.
  *
  * Ported as a small, dependency-free subset of Hermes Agent's
- * `tools/threat_patterns.py` + hermes-claw `threats.ts`. The policy is the
- * load-bearing part: ANY in-scope hit blocks. Severity and category are
- * metadata for diagnostics only.
+ * `tools/threat_patterns.py` + hermes-claw `threats.ts`.
+ *
+ * Policy (P1-1, v19): a finding either BLOCKS the write or only REPORTS.
+ * Blocking is reserved for shapes with no legitimate use in stored knowledge
+ * (prompt-injection phrasing, credential exfiltration, the invisible-character
+ * smuggling core). Typography and presentation characters that are legitimate
+ * in ordinary prose — variation selectors (❤️), zero-width non-joiner, soft
+ * hyphen from PDF paste, Arabic letter mark, Mongolian vowel separator — are
+ * REPORT findings: they stay visible to operators and tests but never reject a
+ * write. Blocking them turned every emoji into a security event.
  */
 export type ThreatScope = 'all' | 'context' | 'strict';
 export interface ThreatFinding {
     label: string;
     category: string;
     scope: ThreatScope;
+    /** P1-1 (v19): `block` (default) refuses the write; `report` is an audit
+     * trail entry only. Absent means `block`. */
+    severity?: 'block' | 'report';
 }
 /**
  * Optional scan controls. Default behavior (`options` omitted) is unchanged:
@@ -39,7 +49,9 @@ export declare const PATTERN_OVERLAP = 4096;
  * characters (skill files may run to 100,000) is no longer a blind zone.
  */
 export declare function scanThreats(text: string, scope?: ThreatScope, maxScanChars?: number, options?: ScanOptions): ThreatFinding[];
-/** Blocking policy: any hit blocks. `severity` is deliberately not a gate. */
+/** Blocking policy (P1-1, v19): a finding blocks unless it is explicitly
+ * `report`-only. Pattern findings carry no severity and therefore block as
+ * before. */
 export declare function evaluateThreat(text: string, scope?: ThreatScope, maxScanChars?: number, options?: ScanOptions): {
     blocked: boolean;
     findings: ThreatFinding[];

package/lib/types/usage.d.ts

@@ -52,7 +52,13 @@ export declare function loadUsage(root: string, io?: EvolutionIoLike): Promise<U
  * cannot interleave its RMW and lose a counter update. Callers keep their own
  * single-process serialize chain as the second layer.
  */
-export declare function mutateUsage(root: string, io: EvolutionIoLike, task: (map: UsageMap) => void | Promise<void>): Promise<void>;
+export interface UsageMutateOptions {
+    /** P2-9 (v19): called when malformed entries had to be quarantined before the
+     * task could run. The guard preserves bytes AND keeps the facility working;
+     * this callback is how that stays observable. */
+    onQuarantine?: ((message: string) => void) | undefined;
+}
+export declare function mutateUsage(root: string, io: EvolutionIoLike, task: (map: UsageMap) => void | Promise<void>, options?: UsageMutateOptions): Promise<void>;
 /**
  * Curator-owned usage fields (rc.67 K-2): the curator writes ONLY this set —
  * lifecycle state, archive stamp, the six-factor quality pair, and the
@@ -85,7 +91,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.63",
+  "version": "0.3.65",
   "publishConfig": {
     "access": "public"
   },