@lmzhen/dsh-evolution-core 0.3.67 → 0.3.69

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

@@ -113,21 +113,31 @@ 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.
+/** E-7 (v18) → V27 G2.4 (M-08): every family row reads ONE root key. `root` is
+ * canonical; the `skillsRoot` alias was honoured for one minor version and its
+ * window closed at 0.3.65 — it is now two releases past expiry, so this
+ * resolver no longer reads it at all. A deployment that still sets the alias
+ * must fail LOUDLY at load (see {@link assertSkillsRootAliasRetired}): silently
+ * ignoring a config key leaves the deployment pointing at a root nobody reads,
+ * which is the worst form of compatibility.
+ * @param config - the raw plugin config.
+ * @returns the effective root (empty when the key is unset or blank).
  */
 export declare function resolveRootConfig(config?: {
     root?: string | undefined;
-    skillsRoot?: string | undefined;
 }): {
     root: string;
-    usedDeprecatedAlias: boolean;
 };
+/** V27 G2.4 (M-08): the retirement gate for the expired `skillsRoot` alias.
+ * Called at each plugin's load boundary (before the root is resolved), it turns
+ * a stale key into an explicit load error naming the replacement — the
+ * fail-loud form the plan requires instead of a silent no-op.
+ * @param config - the raw plugin config (the alias field stays DECLARED in each
+ * schema so the loader can hand it here instead of dropping it).
+ */
+export declare function assertSkillsRootAliasRetired(config?: {
+    skillsRoot?: string | undefined;
+}): void;
 /**
  * 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
@@ -156,10 +166,17 @@ export interface Frontmatter {
 }
 /**
  * Shared frontmatter block detection (P3-3 single owner): opening line `---`
- * and closing line exactly `---` (both trimmed). Used by `parseFrontmatter`,
- * `frontmatterYamlUnsafeValues` and `normalizeFrontmatter` so the three can
+ * and closing line exactly `---`. Used by `parseFrontmatter`,
+ * `frontmatterCatalogInvalid` and `normalizeFrontmatter` so the three can
  * never disagree about where the block ends (the loose `indexOf('\n---')`
  * form matched `\n----` and was replaced by this strict line rule).
+ *
+ * V27 G2.1: both fence lines are matched EXACTLY, tolerating only a trailing
+ * `\r` — the same rule the upstream filesystem catalog uses
+ * (`skill-filesystem.parseFrontmatter`). The former `.trim()` comparison
+ * accepted ` --- `, so an indented fence loaded in the family while the
+ * platform ignored the file: family visibility split from platform visibility,
+ * which is exactly what a strict-YAML frontmatter is supposed to prevent.
  */
 export declare function frontmatterBlock(content: string): {
     block: string;
@@ -167,10 +184,51 @@ export declare function frontmatterBlock(content: string): {
     end: number;
     nl: string;
 } | null;
-export declare function parseFrontmatter(content: string): {
+/**
+ * One frontmatter read (V27 G2.1): the values, the body, and every signal the
+ * strict-YAML platform catalog derives from the same block. Returned by
+ * {@link parseFrontmatter} so a caller never has to parse the block twice to
+ * reach a description and the catalog verdict.
+ */
+export interface FrontmatterRead {
     frontmatter: Frontmatter;
     body: string;
-} | null;
+    /** Raw entries whose UNQUOTED value the strict catalog cannot load as
+     * written. Quotes are included, so a value already normalized by the write
+     * path (`normalizeFrontmatter`) is never re-flagged. */
+    unsafeValues: Array<{
+        key: string;
+        value: string;
+    }>;
+    /** Whether the frontmatter is not valid AS WRITTEN for the strict platform
+     * catalog: the strict parser rejects the block, or an unquoted value would
+     * read as something other than its text (a dropped ` # ` comment, a
+     * number/bool shorthand the catalog refuses as a string field). The write
+     * path quotes such a value on its next edit. */
+    catalogInvalid: boolean;
+}
+/**
+ * Parse a SKILL.md: its frontmatter values and body, or `null` when the file
+ * has no frontmatter block or no body. Every consumer of frontmatter values
+ * goes through here — the write path's validation, `list()`'s published
+ * description, `relatedSkillNames` and the audit — so all of them read the same
+ * bytes the same way.
+ *
+ * @param content - the SKILL.md text.
+ * @returns the read, or `null` when there is no block or no body.
+ */
+export declare function parseFrontmatter(content: string): FrontmatterRead | null;
+/**
+ * Whether this file's frontmatter is valid as written for the strict platform
+ * catalog (see `FrontmatterRead.catalogInvalid`). Body-independent (a body-less
+ * file is still judged), and derived from the same read as `parseFrontmatter` —
+ * so the audit's verdict and the values the family publishes for one file can
+ * never disagree (V27 G2.1).
+ *
+ * @param content - the SKILL.md text.
+ * @returns `true` when the strict parser rejects the block or an unquoted value would read as something else.
+ */
+export declare function frontmatterCatalogInvalid(content: string): boolean;
 /** YAML plain-scalar hazards that make an UNQUOTED frontmatter value
  * unloadable to the platform catalog (strict YAML parser): `: ` (mapping
  * separator), ` #` (comment start), a trailing `:` (a mapping marker),
@@ -186,15 +244,6 @@ export declare function parseFrontmatter(content: string): {
  * with the real YAML parser (see normalizeFrontmatter), so an incomplete
  * approximation can never corrupt a multiline flow value (P3-4). */
 export declare function yamlPlainScalarNeedsQuotes(value: string): boolean;
-/** Raw-line scan of the frontmatter block: entries whose UNQUOTED value is
- * YAML-unsafe for the strict platform catalog. Operates on the ORIGINAL line
- * value (quotes included), so a value already wrapped by
- * `normalizeFrontmatter` is never re-flagged — one source with the write
- * path. Single-line entries only; lines with embedded line breaks skip. */
-export declare function frontmatterYamlUnsafeValues(content: string): Array<{
-    key: string;
-    value: string;
-}>;
 export interface FrontmatterNormalizeResult {
     content: string;
     changed: boolean;
@@ -291,6 +340,17 @@ export declare class SkillLibrary {
      * never inflates the mutation-maturity counter.
      */
     private runSingleWrite;
+    /**
+     * v28 G1.1 (EVO-IO-02): shared compensating cleanup for a locked write that
+     * found no SKILL.md — remove the possibly-resurrected directory ONLY when it
+     * holds nothing but this path's own write-lock file. The BR-5 rule from
+     * setPinnedCore/createCore applies unchanged: a concurrent mover can land a
+     * full directory between the list probe and the remove, so anything beyond
+     * the lock file (support files, a fresh restore) must never be recursed
+     * away. Best-effort: a failed cleanup leaves the "not found" result
+     * unchanged (the operator-facing ghost-dir refusal is fail-loud already).
+     */
+    private cleanupGhostDir;
     /** Notify the mutation observer after a successful write; observers must never fail the mutation. */
     private notifyMutation;
     /** V10-03 (P2-18): ScanOptions shared by every write-path threat check —
@@ -300,6 +360,15 @@ export declare class SkillLibrary {
      * label (scanContentThreats already embeds it) plus the self-heal hint, so a
      * false-positive rewrite direction is actionable instead of a dead end. */
     private contentThreatBlock;
+    /**
+     * v30 REV-03: read a support file's bytes for staleness anchoring (the
+     * write/remove replay guard). Same validation as writeSupportFile; a
+     * missing file (or a directory squatting on the path) reads as `null`, any
+     * other failure RETHROWS — the callers are the staging/replay anchors, and
+     * a swallowed error would silently downgrade the anchor to
+     * last-writer-wins.
+     */
+    readSupportFile(name: string, filePath: string): Promise<string | null>;
     list(): Promise<SkillSummary[]>;
     read(rawName: string): Promise<string | null>;
     /**
@@ -508,6 +577,16 @@ export declare class SkillLibrary {
      * 64 chars each (the name-rule maximum — real skill names always fit).
      */
     private sanitizeSkippedNames;
+    /**
+     * V27 G0.4 (core-a-01): the per-entry gate `skipped` already has. A corrupted
+     * or hand-edited manifest could carry `extras: [123]`: the array check passed,
+     * `SNAPSHOT_EXTRA_NAME_RE.test(123)` coerced the number to the string "123"
+     * and matched, and the value then threw `TypeError` inside `path.join` — which
+     * `readSnapshotExtras` reached only AFTER a whole-tree restore had committed.
+     * Extras are path components under `extras/`, so they take the entry gate too;
+     * bounded like `skipped` so a hostile manifest cannot grow the read set.
+     */
+    private sanitizeExtraNames;
     readSnapshotManifest(path: string): Promise<SnapshotManifest | null>;
     /** Keep only the newest N snapshots (Hermes keep=5 parity); older ones are removed outright. */
     private retainSnapshots;

package/lib/types/threats.d.ts

@@ -28,6 +28,9 @@ export interface ThreatFinding {
  * 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.
+ * V27 G-1: an exclusion drops the FINDING for that label — it never removes the
+ * de-obfuscation the other patterns are matched against, so exempting the
+ * unicode rules cannot re-open a splitting bypass.
  */
 export interface ScanOptions {
     /** Pattern labels to skip during this scan. */

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.67",
+  "version": "0.3.69",
   "publishConfig": {
     "access": "public"
   },