@lmzhen/dsh-evolution-core 0.3.67 → 0.3.68

package/lib/types/constants.d.ts

@@ -83,4 +83,18 @@ 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;
+/** V27 G2.4: the largest millisecond delay a timer accepts. `AbortSignal.timeout`
+ * (and `setTimeout`) coerce anything larger to 1ms after a Node warning, so a
+ * timeout configured above this ceiling silently collapses to "immediately
+ * aborted". The curator's review timeout and the review timeout each carried
+ * their own copy of the literal; the bound is one protocol constant.
+ * (v19 P2-10 corrected the value from 2^32-1 to Node's real 2^31-1 ceiling.) */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** V27 G2.4: the model each review/curation leg defaults to. The policy schema,
+ * the policy resolver and the curator's LLM nomination pass each carried their
+ * own copy of these strings — a deployment that changed the policy default used
+ * to leave the curator passing a different model than the reviews. */
+export declare const DEFAULT_MEMORY_REVIEW_MODEL = "deepseek-v4-flash";
+export declare const DEFAULT_SKILL_REVIEW_MODEL = "deepseek-v4-pro";
+export declare const DEFAULT_CURATOR_MODEL = "deepseek-v4-pro";
 //# sourceMappingURL=constants.d.ts.map

package/lib/types/curator.d.ts

@@ -57,7 +57,17 @@ export interface CuratorRunReport {
     llmNominations: string[];
     archiveCandidates: string[];
     archived: CuratorArchivedSkill[];
+    /** Failures attributable to a SKILL NAME (`<name>: …`). V27 CUR-2: this field
+     * is the skill-attributable subset only — run-level facts (an abort, a phase
+     * that could not start) live in `aborted`/`unattributed` so a report can no
+     * longer show `failed: 0` for a run that was cut short. */
     failed: CuratorFailedSkill[];
+    /** V27 CUR-2: the run stopped early (e.g. disposed mid-run, timeout). The
+     * string names the phase that did not complete; absent on a full run. */
+    aborted?: string;
+    /** V27 CUR-2: error strings that could not be attributed to a skill name.
+     * They were previously collected in memory and then dropped on write. */
+    unattributed?: string[];
     /** Consolidations actually executed this run (source absorbed into target). */
     consolidated?: CuratorConsolidation[];
     snapshotPath?: string;
@@ -75,6 +85,10 @@ export interface CuratorReportInput {
     archiveCandidates: readonly string[];
     archived: readonly CuratorArchivedSkill[];
     failed: readonly CuratorFailedSkill[];
+    /** V27 CUR-2: run-level abort reason (see CuratorRunReport.aborted). */
+    aborted?: string;
+    /** V27 CUR-2: errors with no skill name to attribute them to. */
+    unattributed?: readonly string[];
     consolidated?: readonly CuratorConsolidation[];
     snapshotPath?: string;
     llmReviewEnabled?: boolean;

package/lib/types/events.d.ts

@@ -39,12 +39,22 @@ export interface EvolutionPlanAppliedEvent {
     policyFingerprint?: string | undefined;
     memoryApplied: number;
     skillApplied: number;
+    /** Validation rejects ONLY (see the contract note below). V27 R-03: a plan op
+     * that was skipped because the session had not read the skill is NOT a
+     * validation reject and now travels in `skippedUnread`. */
     rejectedOps: number;
     /** 0.3.31 (V5-19): execution-layer failures — ops that reached execution but
      * did not land (non-throw `ok:false` results). `rejectedOps` counts only
      * VALIDATION rejects; a consumer that treats rejectedOps as "work not done"
      * would otherwise miss a partial application. */
     executionFailures?: number | undefined;
+    /** V27 R-03: "not done" has a third, independent cause — an op naming a skill
+     * this session never read (the review pipeline refuses to touch unread
+     * skills). It is neither a validation reject nor an execution failure, so it
+     * has its own field; folding it into `rejectedOps` broke that field's stated
+     * contract and made the replay leaderboard penalize one refusal twice
+     * (rejectedOps weight AND the executionFailures dimension). */
+    skippedUnread?: number | undefined;
     /** First execution-layer failure message (abort reason or op failure). */
     executionError?: string | undefined;
     evidenceQuotes?: number | undefined;

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

@@ -8,12 +8,15 @@
  *
  * Usage events (C semantics, rc.73+): `type:'usage'` records are the
  * OBSERVATION WINDOW ANCHOR — written once, when the library's first observed
- * read (`view_count` 0 -> 1) happens. Before that anchor the usage sidecar
- * has no read evidence (reads were invisible pre-A2), so churn-based health
- * judgments are NOT trustworthy; the curator suppresses them (its
- * `usageObserved()` gate) until the anchor exists. `counts` on the event is a
- * cumulative library-wide snapshot (skills/views/use/patches) at that moment,
- * and `window.opened` pins the window start for the timeline.
+ * read (`view_count` 0 -> 1) happens. The anchor is the durable timeline record
+ * of that moment: the churn-suppression gate itself (`usageObserved()`) reads
+ * the usage SIDECAR's own first-view evidence, since reads were invisible to it
+ * pre-A2 and no sidecar record can reach `view_count > 0` without the same
+ * 0 -> 1 transition. `counts` on the event is a cumulative library-wide
+ * snapshot (skills/views/use/patches) at that moment, and `window.opened` pins
+ * the window start for the timeline. (V27 G3.3: `verify-event-pairing` requires
+ * every persisted type to have a production reader or a declared external
+ * contract — this one is the latter.)
  *
  * Rotation (rc.71, 007 design): when the active log reaches
  * `EVENT_LOG_ROTATE_AT` the older half is split into an archive

package/lib/types/io.d.ts

@@ -146,6 +146,71 @@ export declare const LOCK_BODY_RE: RegExp;
  * `*.lock`) — callers leave such files alone. A shape-matching body always
  * yields a number (possibly `0`, which `isProcessAlive` treats as dead). */
 export declare function parseLockBody(body: string): number | null;
+/**
+ * V27 G0.2 (EVO-IO-01): the write lock named by this claim is no longer ours
+ * at the commit point — a takeover reclaimed it while we were inside the
+ * critical section. The lock layer converts this into a retry of the whole
+ * read-modify-write; it must never reach a caller as a successful write.
+ */
+export declare class LostWriteLock extends Error {
+    constructor();
+}
+/** V27 G1.1: the three takeover windows, as protocol constants at ONE place
+ * (the inline copies that used to live in the acquisition loop, plus the dead
+ * branch's bare `1000`, are gone). */
+/** A named holder that is gone, past this age, is reclaimed. Fits inside the
+ * `lockAttempts * 50ms` retry budget so a dead holder's lock is reachable
+ * within one budget (v19 gate arithmetic: budget >= 2 x threshold). */
+export declare const DEAD_LOCK_TAKEOVER_MS = 1000;
+/** No body at all: nothing attributes the lock to a holder, so this is the one
+ * branch that cannot probe liveness — it must outlast any plausible stall
+ * between create and body write (V27 G0.2: 1s was below what a loaded machine
+ * actually took, which let a peer delete a live holder's lock). */
+export declare const EMPTY_LOCK_TAKEOVER_MS = 30000;
+/** A body with no parseable pid (crash mid-write): 1h, far above any legal hold
+ * and far below "forever". */
+export declare const LOCK_TEAR_TAKEOVER_MS = 3600000;
+/**
+ * V27 G1.3: the error `commitTmp` throws when the rename landed but the parent
+ * directory fsync failed — the bytes ARE visible, only their durability is
+ * unconfirmed. A consumer that treats it as a plain failure reports "not
+ * written" for a write that happened (and a two-phase caller may try to roll
+ * back a visible write). Every transaction consumer must therefore treat this
+ * shape as SUCCESS-with-warning, never as a rejection.
+ */
+export declare function isCommittedWarning(error: unknown): boolean;
+/** V27 G1.1: the takeover branches, as a value. */
+export type TakeoverDecision = 'none' | 'dead' | 'empty' | 'corrupt';
+/** V27 G1.1: one lock observation, plus the liveness probe for its pid. */
+export interface TakeoverProbe {
+    /** Raw lock body. An empty string means the file exists with no content. */
+    body: string;
+    /** Lock mtime in epoch ms. */
+    mtimeMs: number;
+    /** Liveness probe for a pid (injected so the decision is a pure function). */
+    alive: (pid: number) => boolean;
+    /** Evaluation instant (defaults to now). */
+    nowMs?: number;
+    /** Threshold overrides — production callers use the protocol defaults. */
+    deadAfterMs?: number;
+    emptyAfterMs?: number;
+    corruptAfterMs?: number;
+}
+/**
+ * V27 G1.1: the lock-takeover decision as ONE pure function, so the protocol is
+ * testable and exhaustive instead of being an inline expression inside the
+ * acquisition loop:
+ *   - `none`    the lock is fresh, or its holder is alive → wait, never steal;
+ *   - `dead`    a named holder that is gone, past the dead threshold;
+ *   - `empty`   no body at all: nothing attributes it to a holder, so only the
+ *               wide `emptyAfterMs` window may reclaim it;
+ *   - `corrupt` a body with no parseable pid (a crash mid-write), past the 1h
+ *               tear threshold.
+ * The age thresholds compare against `nowMs - mtimeMs` with `>` so a lock whose
+ * age EQUALS the threshold is not yet reclaimed (the boundary the v19 gate fix
+ * pinned).
+ */
+export declare function decideTakeover(probe: TakeoverProbe): TakeoverDecision;
 /**
  * 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

@@ -100,6 +100,18 @@ export declare class MemoryStore {
      * silently overwritten.
      */
     private oversizedRefusal;
+    /**
+     * The ONE memory write skeleton (V27 G2.5): oversized read-guard pre-transact,
+     * one transaction over the target path, and the C-01 structured refusal when a
+     * backend never invokes the task. `addChained` and `applyBatchChained` supply
+     * only their own in-transaction core, so the two write paths cannot drift in
+     * their guard order, their missing-file handling or their error text.
+     *
+     * @param target - memory target being written
+     * @param core - the in-transaction read-modify-write for the locked body
+     * @returns the core's result, or the oversized / contract-violation refusal
+     */
+    private chainedWrite;
     add(target: MemoryTarget, facts: string): Promise<MemoryApplyResult>;
     private addChained;
     /**
@@ -108,26 +120,49 @@ export declare class MemoryStore {
      * (`current`) — never a second IO read. `write: null` means "no change".
      */
     private addCore;
-    /** Canonical-form drift check derived from the locked view (same formula as `detectDrift`, no second read). */
-    private driftFromRaw;
+    /**
+     * The single drift predicate. `raw` is in canonical form when it byte-matches
+     * `render(normalizeEntries(raw))`; anything else means it was edited outside
+     * MemoryStore (empty/`§`-only entries, stray blank lines, leading or trailing
+     * delimiters — structural anomalies the writer would quietly normalize away).
+     * Both write paths derive this from their locked view and `detectDrift` from
+     * a fresh read, so a write and a later read can never disagree about the same
+     * bytes.
+     *
+     * An absent, empty, or whitespace-only body is the "never written" state
+     * (rc.42 audit P1-6): it parses to zero entries, and the canonical form
+     * `'\n'` can never byte-match it, so flagging it would permanently refuse
+     * every write path — including the repairs the model would need to make.
+     * Such files are adopted instead of flagged.
+     *
+     * @param target - memory target whose char limit bounds one parsed entry
+     * @param raw - on-disk body, or `null` when the file does not exist
+     * @returns whether these bytes count as externally drifted
+     */
+    private drifted;
+    /**
+     * Drift refusal for a body already read under the write lock, or `null` when
+     * the body is canonical. Both write paths return this unchanged, so their
+     * refusals stay byte-identical and each carries the same backup.
+     *
+     * @param target - memory target that owns the drifted file
+     * @param raw - locked file body
+     * @returns the refusal to hand back, or `null` to continue writing
+     */
+    private driftRefusal;
     applyBatch(target: MemoryTarget, operations: MemoryOperation[]): Promise<MemoryApplyResult>;
     private applyBatchChained;
     /** Batch RMW inside the transaction. `write: null` = failure/no-op, disk untouched. */
     private applyBatchCore;
     renderContext(): Promise<string>;
     /**
-     * Detect on-disk drift: true when the file is not in the canonical
-     * `render(normalizeEntries(raw))` form. This catches structural anomalies
-     * the writer would quietly normalize away (empty/`§`-only entries, stray
-     * blank lines, leading/trailing delimiters) that indicate the file was
-     * edited outside MemoryStore. Purely single-canonical content reaches the
-     * same serialization and returns false, so a normal write is never flagged.
+     * Detect on-disk drift for a caller that holds no locked view: `true` when the
+     * file is not in canonical form, or when its size trips the read guard. The
+     * write paths apply the same predicate (`drifted`) to the body they read under
+     * the lock, so a write and a follow-up read agree about the same bytes.
      *
-     * An absent, empty, or whitespace-only file is the "never written" state
-     * (rc.42 audit P1-6): it parses to zero entries, so the canonical form
-     * `'\n'` can never byte-match it and every write path was permanently
-     * refused with "External drift detected" — including the repairs the model
-     * would need to make. Such files are adopted instead of flagged.
+     * @param target - memory target to inspect
+     * @returns whether the file on disk counts as externally drifted
      */
     detectDrift(target: MemoryTarget): Promise<boolean>;
 }

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`,
+ * and closing line exactly `---`. Used by `parseFrontmatter`,
  * `frontmatterYamlUnsafeValues` 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),
@@ -190,7 +248,10 @@ export declare function yamlPlainScalarNeedsQuotes(value: string): boolean;
  * 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. */
+ * path. V27 G2.1: delegates to the shared scan, which
+ * `parseFrontmatter(...).catalogInvalid` also uses, so the audit view and the
+ * read view of one file can never disagree. Independent of the body: a
+ * body-less file is still reported here. */
 export declare function frontmatterYamlUnsafeValues(content: string): Array<{
     key: string;
     value: string;
@@ -508,6 +569,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.68",
   "publishConfig": {
     "access": "public"
   },