@lmzhen/dsh-evolution-core 0.1.0-rc.6 → 0.1.0-rc.60

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

@@ -7,11 +7,8 @@
  * move to `.archive/` — never a hard delete.
  */
 import { type EvolutionIoLike } from './io.ts';
-export declare const SKILL_NAME_RE: RegExp;
-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;
+import { type MutationRecord } from './mutations.ts';
+import type { EvolutionSkillMutatedEvent } from './events.ts';
 export interface SkillLimits {
     maxNameLength: number;
     maxDescriptionLength: number;
@@ -19,7 +16,6 @@ export interface SkillLimits {
     maxSkillFileBytes: number;
 }
 export declare const DEFAULT_SKILL_LIMITS: SkillLimits;
-export declare const SUPPORT_DIRS: readonly ["references", "templates", "scripts", "assets"];
 export interface SkillSummary {
     name: string;
     description: string;
@@ -33,7 +29,52 @@ export interface SkillActionResult {
     message: string;
     path?: string;
 }
+/** Extra file name carried inside a snapshot's `extras/` directory. */
+export declare const SNAPSHOT_EXTRA_NAME_RE: RegExp;
+/** An opaque side file stored under a snapshot's `extras/` (curator state etc.). */
+export interface SnapshotExtra {
+    name: string;
+    content: string;
+}
+/** Normalized manifest of a skills snapshot. */
+export interface SnapshotManifest {
+    reason: string;
+    createdAt: string;
+    /** Active skill names at snapshot time. */
+    skills: string[];
+    /** Co-copied sidecar file names (usage/suppression). */
+    sidecars: string[];
+    /** Whether `.archive/` was co-copied; absent on legacy manifests (do not touch archive on restore). */
+    hasArchive?: boolean;
+    /** Extras declared under `extras/`; only these names are ever read back. */
+    extras: string[];
+}
+/** Who is writing: a foreground user-directed tool call, or the autonomous review/curator pipeline. */
+export type WriteOrigin = 'foreground' | 'subagent' | 'background_review';
+/** Options for `SkillLibrary.archive`. The absorbed-into name and the archival reason are distinct fields. */
+export interface ArchiveOptions {
+    /** Umbrella skill this one was consolidated into; when set it must exist (consolidate semantics). */
+    absorbedInto?: string;
+    /** Human-readable reason written to `.archive-reason`; default derives from `absorbedInto`. */
+    reason?: string;
+    /** Permit archiving a bundled skill (curator prune-builtins only; hub-installed and pinned stay protected). */
+    allowBundled?: boolean;
+}
 export declare function skillsRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * 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
+ * review channel, while the LIBRARY surface keeps the Hermes distinction -
+ * the review fork is 'background_review' (the pinned guard blocks its
+ * writes) and any other subagent is 'subagent' (agent-authored, not
+ * review-channel). `isReview` marks the caller as the background review
+ * pipeline itself. Single source: the two tools and the review executor all
+ * read this table instead of re-deriving it.
+ */
+export declare function resolveOrigins(headerOrigin: string | undefined, isReview?: boolean): {
+    approval: 'foreground' | 'background_review';
+    library: WriteOrigin;
+};
 export interface Frontmatter {
     name?: string;
     description?: string;
@@ -43,41 +84,132 @@ export declare function parseFrontmatter(content: string): {
     frontmatter: Frontmatter;
     body: string;
 } | null;
+/**
+ * Skill names referenced by a SKILL.md's `related_skills` frontmatter
+ * (B-line G3, rc.44): the single parsing source for the quality references
+ * factor and the learning-graph edges. The DSH frontmatter parser keeps the
+ * YAML value as a string (`"[a, b]"`), so names are scanned out of it; each
+ * must satisfy the skill-name shape and the referencing skill itself is
+ * excluded. Pure and deduplicated.
+ */
+export declare function relatedSkillNames(content: string, exclude?: string): string[];
 export declare function validateFrontmatter(content: string, expectedName?: string, limits?: SkillLimits): string | null;
+/** Hermes authoring quality bar for descriptions (the 60-char Rule). The
+ * platform's own index limit stays in `validateFrontmatter`; this bar is the
+ * target the authoring standard names, enforced as ADVISORY feedback. */
+export declare const AUTHORING_DESCRIPTION_BAR = 60;
+export interface AuthoringFeedback {
+    /** Frontmatter description length in characters (0 when absent). */
+    descriptionChars: number;
+    /** Whether the description exceeds the authoring bar (60) while still passing the platform limit. */
+    over60: boolean;
+    /** Whether the description contains a colon (the standard requires double-quote wrapping). */
+    hasColon: boolean;
+    /** Advice lines appended to mutation success messages. */
+    lines: string[];
+}
+/**
+ * Advisory authoring feedback (P0): evaluate frontmatter against the
+ * authoring bar WITHOUT changing platform validation semantics. The bar is
+ * the quality target, `validateFrontmatter`'s limits are the compatibility
+ * floor, and this bridge layer tells the model when its text would be
+ * truncated or route-poor instead of silently shipping it.
+ */
+export declare function authoringFeedback(frontmatter: Frontmatter): AuthoringFeedback;
 export declare class SkillLibrary {
     readonly root: string;
     readonly limits: SkillLimits;
     private readonly io;
-    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits);
+    private readonly onMutation;
+    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void);
+    /** Notify the mutation observer after a successful write; observers must never fail the mutation. */
+    private notifyMutation;
     list(): Promise<SkillSummary[]>;
-    read(name: string): Promise<string | null>;
-    writeProtection(name: string): Promise<string | null>;
-    deleteProtection(name: string): Promise<string | null>;
-    isManaged(name: string): Promise<boolean>;
-    create(name: string, content: string, origin: 'foreground' | 'background_review'): Promise<SkillActionResult>;
-    update(name: string, content: string): Promise<SkillActionResult>;
-    patch(name: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean): Promise<SkillActionResult>;
-    archive(name: string, absorbedInto?: string): Promise<SkillActionResult>;
+    read(rawName: string): Promise<string | null>;
+    /**
+  
+     * Single path-building choke point (rc.42 audit P2-5): every directory path
+  
+     * is built from the TRIMMED name, so a name that passes `badName` (which
+  
+     * trims before validating) can never mint a second, whitespace-padded
+  
+     * directory next to the real one. Callers keep passing raw user input.
+  
+     */
+    private dirOf;
+    /** Name-format guard shared by every path-building mutator/reader. */
+    private badName;
+    writeProtection(rawName: string, origin?: WriteOrigin): Promise<string | null>;
+    deleteProtection(rawName: string, options?: {
+        allowBundled?: boolean;
+    }): Promise<string | null>;
+    isManaged(rawName: string): Promise<boolean>;
+    /** Whether the skill carries the bundled marker (curator prune-builtins eligibility). */
+    isBundled(rawName: string): Promise<boolean>;
+    /** Whether the skill carries the pinned marker (the marker is the factual source; usage.pinned mirrors it). */
+    isPinned(rawName: string): Promise<boolean>;
+    /** Count non-empty support subdirectories (richness input for quality scoring). */
+    countSupportDirs(rawName: string): Promise<number>;
+    /** Best-effort audit trail entry; never blocks the mutation. */
+    private audit;
+    /** Recent mutation audit records (read-only inspection surface). */
+    listMutations(): Promise<MutationRecord[]>;
+    /**
+     * Pin or unpin a skill (`.pinned` marker). Pinned skills are protected from
+     * deletion, from background-review writes, and from the lifecycle — a
+     * protective mutation, so the autonomous pipeline may never call it. The
+     * marker write is the only state change; content is untouched.
+     */
+    setPinned(name: string, pinned: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
+    create(name: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    update(rawName: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    patch(rawName: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
+    archive(rawName: string, options?: ArchiveOptions): Promise<SkillActionResult>;
     /**
      * Merge the bodies of `sources` into `target` and archive the sources with
      * an absorbed-into marker. Hermes-style consolidation: overlapping skills
      * collapse into one, and the originals stay recoverable under `.archive/`.
      */
-    consolidate(target: string, sources: string[]): Promise<SkillActionResult>;
+    consolidate(target: string, sources: string[], origin?: WriteOrigin): Promise<SkillActionResult>;
     /**
      * Restore one skill from `.archive/` back to the active root. Hermes-style
      * recoverability: archival never deletes, and this is the control-plane
      * path back. The `.archive-reason` marker is dropped on restore.
      */
-    restoreFromArchive(name: string): Promise<SkillActionResult>;
-    writeSupportFile(name: string, filePath: string, content: string): Promise<SkillActionResult>;
-    removeSupportFile(name: string, filePath: string): Promise<SkillActionResult>;
-    snapshotAll(reason?: string): Promise<string>;
+    restoreFromArchive(rawName: string): Promise<SkillActionResult>;
+    writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    /**
+     * Snapshot the recoverable skills state: active tree, usage/suppression
+     * sidecars, `.archive/` and caller-supplied extras. `extras` are opaque
+     * side files the Snapshot owner cares about (curator state); they are
+     * listed in the manifest and only those names are ever read back.
+     */
+    snapshotAll(reason?: string, extras?: SnapshotExtra[]): Promise<string>;
+    /** Read and normalize a snapshot manifest; null when the file is missing or unparsable. */
+    readSnapshotManifest(path: string): Promise<SnapshotManifest | null>;
+    /** Keep only the newest N snapshots (Hermes keep=5 parity); older ones are removed outright. */
+    private retainSnapshots;
     listSnapshots(): Promise<Array<{
         path: string;
         createdAt: string;
         reason: string;
     }>>;
-    restoreLatestSnapshot(): Promise<SkillActionResult>;
+    /**
+     * Read the extras of a snapshot, restricted to the names declared in the
+     * manifest — an `extras/` directory is never listed directly, so unknown
+     * files cannot leak back as state on the next restore.
+     */
+    readSnapshotExtras(path: string): Promise<SnapshotExtra[]>;
+    /**
+     * Manifest-driven restore of the latest snapshot: active tree, sidecars,
+     * `.archive/` and (for full-state snapshots) the extras read back by the
+     * caller. `extras` are additionally written into the pre-rollback safety
+     * snapshot so the rollback itself is undoable with the same state.
+     */
+    restoreLatestSnapshot(extras?: SnapshotExtra[]): Promise<SkillActionResult & {
+        extras?: SnapshotExtra[];
+    }>;
 }
 //# sourceMappingURL=skill-store.d.ts.map

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

@@ -1,19 +1,6 @@
 /**
- * Small crash-safe JSON state store for plugin-owned sidecar state.
- * Writes are atomic (temp + rename). Reads are synchronous for startup use.
+ * Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
+ * state (reports, activity store, feedback file, state-domain data).
  */
 export declare function evolutionHome(env?: NodeJS.ProcessEnv): string;
-export declare class JsonState<T> {
-    private readonly initial;
-    readonly path: string;
-    private value;
-    constructor(name: string, initial: T, env?: NodeJS.ProcessEnv);
-    private loadSync;
-    get(): T;
-    set(value: T): void;
-    update(mutator: (value: T) => void): void;
-    flush(): Promise<void>;
-    /** Merge-on-load helper for persisted maps/records. */
-    reload(): Promise<void>;
-}
 //# sourceMappingURL=state-store.d.ts.map

package/lib/types/threats.d.ts

@@ -12,17 +12,29 @@ export interface ThreatFinding {
     category: string;
     scope: ThreatScope;
 }
+/**
+ * Optional scan controls. Default behavior (`options` omitted) is unchanged:
+ * every in-scope pattern blocks. Adapters that need to tolerate a specific
+ * benign phrasing (e.g. a skill that legitimately opens with "You are now a ...")
+ * can exclude that label by name here. This is opt-in and never widens strict
+ * scope; it only permits callers to drop a known-innocent match.
+ */
+export interface ScanOptions {
+    /** Pattern labels to skip during this scan. */
+    excludeLabels?: readonly string[];
+}
 /**
  * Scan text at `scope`. Patterns are cumulative: `strict` includes all scopes.
+ * `options.excludeLabels` removes matching patterns without changing `scope`.
  */
-export declare function scanThreats(text: string, scope?: ThreatScope, maxScanChars?: number): ThreatFinding[];
+export declare function scanThreats(text: string, scope?: ThreatScope, maxScanChars?: number, options?: ScanOptions): ThreatFinding[];
 /** Blocking policy: any hit blocks. `severity` is deliberately not a gate. */
-export declare function evaluateThreat(text: string, scope?: ThreatScope, maxScanChars?: number): {
+export declare function evaluateThreat(text: string, scope?: ThreatScope, maxScanChars?: number, options?: ScanOptions): {
     blocked: boolean;
     findings: ThreatFinding[];
 };
 /** User-facing block message for memory writes. */
-export declare function scanMemoryThreats(text: string, maxScanChars?: number): string | null;
+export declare function scanMemoryThreats(text: string, maxScanChars?: number, options?: ScanOptions): string | null;
 /** User-facing block message for skill content writes. */
-export declare function scanContentThreats(text: string, maxScanChars?: number): string | null;
+export declare function scanContentThreats(text: string, maxScanChars?: number, options?: ScanOptions): string | null;
 //# sourceMappingURL=threats.d.ts.map

package/lib/types/usage.d.ts

@@ -16,13 +16,33 @@ export interface UsageRecord {
     state: SkillState;
     pinned: boolean;
     archived_at: string | null;
-    quality_score?: number;
-    quality_warn?: boolean;
+    quality_score?: number | undefined;
+    quality_warn?: boolean | undefined;
 }
 export type UsageMap = Map<string, UsageRecord>;
 export declare function usageFile(root: string): string;
 export declare function emptyRecord(): UsageRecord;
+/**
+ * Field-level normalization for one sidecar record (rc.42 audit P2-3): the
+ * spread used to copy any junk through verbatim, so a corrupted file could
+ * carry `use_count: "3"` into the quality math and lifecycle comparisons as
+ * NaN. Every field falls back to its `emptyRecord()` baseline unless it has
+ * exactly the declared type; an invalid `created_at` anchors the age clock at
+ * now (first-sight defer semantics for a record whose age is unknowable).
+ * Timestamps additionally require a parseable date (N-3): `"not-a-date"`
+ * would otherwise survive the type check as Invalid Date.
+ * Pure — exported for unit tests; `loadUsage` is the production caller.
+ */
+export declare function normalizeUsageRecord(record: unknown): UsageRecord;
 export declare function loadUsage(root: string, io?: EvolutionIoLike): Promise<UsageMap>;
+/**
+ * Atomic read-modify-write on the usage sidecar (rc.50 P2-2): `task` receives
+ * the map parsed from the current on-disk state and may mutate it; the result
+ * is persisted inside the same transact so a second process sharing DSH_HOME
+ * 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 declare function saveUsage(root: string, map: UsageMap, io?: EvolutionIoLike): Promise<void>;
 export declare function getRecord(map: UsageMap, name: string): UsageRecord;
 export declare function bumpView(map: UsageMap, name: string, when?: Date): void;
@@ -30,4 +50,21 @@ export declare function bumpUse(map: UsageMap, name: string, when?: Date): void;
 export declare function bumpPatch(map: UsageMap, name: string, when?: Date): void;
 export declare function markAgentCreated(map: UsageMap, name: string): void;
 export declare function latestActivityAt(record: UsageRecord): string | null;
+/**
+ * Curator suppression sidecar: built-in skills the curator has archived stay
+ * suppressed across re-seeds, so the lifecycle never fights a re-created
+ * bundled skill. Best-effort load/save, mirroring the usage sidecar posture.
+ * Versioned shape ({ version, names }) with legacy plain-array compat.
+ */
+export declare const SUPPRESSED_FILE_VERSION = 1;
+export declare function suppressedFile(root: string): string;
+export declare function loadSuppressedNames(root: string, io?: EvolutionIoLike): Promise<ReadonlySet<string>>;
+export declare function saveSuppressedNames(root: string, names: ReadonlySet<string>, io?: EvolutionIoLike): Promise<void>;
+/**
+ * Atomic read-modify-write on the suppression sidecar (rc.50 P2-2): `task`
+ * receives the set parsed from the current on-disk state and may mutate it;
+ * the result is persisted inside the same transact so a second process
+ * sharing DSH_HOME cannot interleave its RMW. Best-effort posture unchanged.
+ */
+export declare function updateSuppressedNames(root: string, io: EvolutionIoLike, task: (names: Set<string>) => void | Promise<void>): Promise<void>;
 //# sourceMappingURL=usage.d.ts.map

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.1.0-rc.6",
+  "version": "0.1.0-rc.60",
   "publishConfig": {
     "access": "public"
   },
@@ -32,13 +32,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2"
   }
 }