@lmzhen/dsh-evolution-core 0.3.81 → 0.3.83

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

@@ -34,16 +34,10 @@
  */
 import { transactIo, type EvolutionIoLike } from './io.ts';
 import { type Probe } from './probe.ts';
+import type { SkillLimits } from './limits.ts';
 import { type MutationRecord } from './mutations.ts';
 import { type SkillHealthAssessment, type SkillHealthThresholds } from './skill-health.ts';
 import type { EvolutionSkillMutatedEvent } from './events.ts';
-export interface SkillLimits {
-    maxNameLength: number;
-    maxDescriptionLength: number;
-    maxSkillContentChars: number;
-    maxSkillFileBytes: number;
-}
-export declare const DEFAULT_SKILL_LIMITS: SkillLimits;
 export interface SkillSummary {
     name: string;
     description: string;
@@ -172,7 +166,16 @@ export declare function skillsRoot(env?: NodeJS.ProcessEnv): string;
  * (and the graph ignored config entirely). Empty/whitespace config falls
  * through to the default; callers pass their raw Config. The optional field is
  * declared `| undefined` so a config object whose root field is explicitly
- * `string | undefined` still assignable under exactOptionalPropertyTypes. */
+ * `string | undefined` still assignable under exactOptionalPropertyTypes.
+ * P2-31 core half (S2.2 batch, PLAN 2026-09-16): an explicit non-empty root
+ * is `resolve()`d — the same normalization `evolutionRoot` applies and the
+ * same one upstream skill-filesystem applies to `customSkillDirs`
+ * (`(config.customSkillDirs ?? []).map(root => resolve(root))`). The former
+ * verbatim return left a RELATIVE config root CWD-relative, so the family's
+ * skill tree moved with the host process's launch directory while every
+ * absolute consumer (watchers, the platform catalog) resolved it — a
+ * split-brain tree; a trailing slash or `..` segment likewise landed
+ * unnormalized. A clean absolute root is byte-identical (resolve is a no-op). */
 export declare function resolveSkillsRoot(config?: {
     root?: string | undefined;
 }): string;
@@ -246,155 +249,6 @@ export declare function resolveExecOrigins(exec: EvolutionExecOriginView | undef
  * consumers that must probe markers without re-deriving the name (curator's
  * archive-copy bundled probe, 0.3.26 V4-02). */
 export declare function markerEntryName(marker: 'bundled' | 'hub-installed' | 'pinned' | 'hermes-managed'): string;
-export interface Frontmatter {
-    name?: string;
-    description?: string;
-    [key: string]: unknown;
-}
-export declare function frontmatterBlock(content: string): {
-    block: string;
-    lines: string[];
-    end: number;
-    nl: string;
-} | null;
-/**
- * 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;
-    /** 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), or a
-     * platform string field carries a non-string value. The write path quotes
-     * such a value on its next edit. */
-    catalogInvalid: boolean;
-    /** Platform string fields (`name`/`description`/`whenToUse`) whose YAML value
-     * is not a string: the strict catalog reads such a field as ABSENT and, for an
-     * absent name/description, ignores the whole file (P2-9/v37). */
-    platformStringSplit: PlatformStringSplit[];
-}
-/** One `name`/`description`/`whenToUse` entry the strict catalog cannot read as
- * a string, with the YAML kind the parser found. */
-export interface PlatformStringSplit {
-    key: string;
-    /** The YAML type read for this field. `scalar` covers number/boolean (the
-     * E-47 auto-quote repair handles those); `sequence`/`mapping` are the shapes
-     * no rewrite can repair without inventing text — see `validateFrontmatter`. */
-    kind: 'sequence' | 'mapping' | 'scalar' | 'null';
-}
-/**
- * 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),
- * or a leading YAML indicator. The evolution `parseFrontmatter` is
- * deliberately lenient, so violations silently split family-visibility from
- * platform-visibility (0.3.11 inkos-harness case: the description carried
- * "…: " and the catalog dropped the whole skill). Already-quoted values and
- * well-formed flow collections (`[a, b]` / `{a: b}`) are considered safe.
- * 0.3.16 (E-47): null/bool/number-shaped plain scalars are flagged too — they
- * parse as booleans/numbers on the platform while the family keeps the string
- * (a `description: true` split-brain).
- * This rule is only the FAST PATH — the write path re-verifies every rewrite
- * 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;
-export interface FrontmatterNormalizeResult {
-    content: string;
-    changed: boolean;
-    /** Frontmatter keys whose values were auto-quoted. */
-    fields: string[];
-    /** Values that cannot be auto-quoted safely (control characters, or a
-     * rewrite that failed the real-parser verification — a multiline flow
-     * collection line etc. is left untouched and reported here, so the write
-     * path rejects instead of silently damaging a value; 0.3.14). */
-    issues: string[];
-}
-/**
- * Normalize a SKILL.md frontmatter block into catalog-loadable YAML: values
- * that YAML forbids unquoted get quotes — double quotes normally, single
- * quotes (with `''` doubling) when the value contains `"` or `\` (both legal
- * unescaped inside single-quoted YAML). Idempotent; only single-line
- * `key: value` entries are touched; body text is never modified; line-ending
- * style is preserved. **Every rewrite is re-verified with the real YAML
- * parser** (js-yaml — the same parser the platform catalog uses): if the
- * rewritten block no longer parses, or a rewritten value's parsed content
- * differs from the original, the rewrite is rolled back and reported in
- * `issues` (fail-loud, never a silent value corruption — P3-4).
- *
- * V10-02 (P2-3): the rewrite decision is PER LINE — each entry parses its own
- * value, so a duplicated key can never route one entry's unsafe value into a
- * different line's rewrite (the old key→Map lookup rewrote the FIRST (safe)
- * line with the SECOND line's quoted value, and the last-wins YAML reader
- * masked the damage). A duplicated key is itself invalid input and is
- * reported in `issues` (the write path refuses) instead of being rewritten.
- */
-export declare function normalizeFrontmatter(content: string): FrontmatterNormalizeResult;
-/**
- * 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, 
-/** On-disk bytes, so a NET SHRINK of an over-limit file is allowed (S1.2). */
-current?: string | null): string | null;
-/** Hermes authoring quality bar for descriptions — see constants.ts
- * (0.3.16 T-4 moved the single source there; the public re-export sits behind
- * the package root, which re-exports constants anyway). */
-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;
 /** 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.
@@ -747,4 +601,8 @@ export interface NewSkillLibraryOptions {
     threatExemptLabels?: readonly string[] | undefined;
 }
 export declare function newSkillLibrary(options: NewSkillLibraryOptions): SkillLibrary;
+export { DEFAULT_SKILL_LIMITS } from './limits.ts';
+export type { SkillLimits } from './limits.ts';
+export { authoringFeedback, frontmatterBlock, frontmatterCatalogInvalid, normalizeFrontmatter, parseFrontmatter, relatedSkillNames, validateFrontmatter, yamlPlainScalarNeedsQuotes } from './frontmatter.ts';
+export type { AuthoringFeedback, Frontmatter, FrontmatterNormalizeResult, FrontmatterRead, PlatformStringSplit } from './frontmatter.ts';
 //# sourceMappingURL=skill-store.d.ts.map

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

@@ -14,12 +14,14 @@
  * DSH home root: `$DSH_HOME` or `~/.dsh`. Single source of the empty-string
  * fallback — an EMPTY or WHITESPACE-ONLY DSH_HOME resolves to the default
  * home, never to a CWD-relative path (0.3.19 W1.3, 0.3.22 F-207);
- * V8-06 (0.3.47) extends the guard to whitespace (upstream home-paths:
- * `trim().length > 0` is the adoption test — `DSH_HOME=" "` must not produce
- * a sidecar under a relative "." path).
- * C-11: the adoption test and the RETURNED value now come from the
- * SAME trimmed source — the old form tested `trim()` but returned the raw
- * value, so `DSH_HOME=" /x "` was accepted AND persisted with literal spaces.
+ * V8-06 (0.3.47) extends the guard to whitespace.
+ * C-11 correction (S2.2, PLAN 2026-09-16): upstream `resolveDshHome`
+ * (util/home-paths) uses `trim()` ONLY as the ADOPTION test and then uses the
+ * RAW env value — the earlier "same trimmed source" form returned the trimmed
+ * text, so `DSH_HOME=" /x "` produced `/x` where upstream produced the literal
+ * padded path. The value semantics now match upstream line for line:
+ * `const selected = configured ?? (fromEnv !== undefined &&
+ * fromEnv.trim().length > 0 ? fromEnv : defaultDshHome())`.
  * OPT-27 (2026-09, plan D5 — accepted): the v10-era "no `~` expansion, no
  * resolve" divergence from upstream `resolveDshHome` is RETIRED. It became
  * load-bearing when the skill-catalog shadow made "same tree as the upstream
@@ -27,9 +29,13 @@
  * absolute `<home>/skills` while this value fed a literal `~/x` (a directory
  * named `~` under the host CWD) or a CWD-relative path — split-brain skill
  * trees, preset installs the platform never reads, doctor probes of a
- * directory nothing serves. Behavior now matches upstream:
- * `resolve(expandHomePath(selected))`. Only `~`-prefixed and RELATIVE
- * DSH_HOME values change landing spot; absolute homes are byte-identical.
+ * directory nothing serves.
+ * S2.2 (PLAN 2026-09-16), final correction: the result is ALWAYS
+ * `resolve(expandHomePath(selected))` — the earlier form returned an
+ * already-absolute value VERBATIM, so a trailing slash or `..` segment
+ * landed unnormalized while upstream normalizes every value. Relative
+ * `DSH_HOME` values change landing spot; a CLEAN absolute home stays
+ * byte-identical (resolve is a no-op on it).
  */
 export declare function evolutionRoot(env?: NodeJS.ProcessEnv): string;
 /** Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar

package/lib/types/threats.d.ts

@@ -13,8 +13,8 @@
  * 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 {
+type ThreatScope = 'all' | 'context' | 'strict';
+interface ThreatFinding {
     label: string;
     category: string;
     scope: ThreatScope;
@@ -74,4 +74,5 @@ export declare function scanContentThreats(text: string, maxScanChars?: number,
  * returns the scan message verbatim, so the hint rides along there too.
  */
 export declare const THREAT_EXEMPTION_HINT = " A deployment that needs a specific label can exempt it via threatExemptLabels (see the README env/dial reference).";
+export {};
 //# sourceMappingURL=threats.d.ts.map

package/lib/types/tool-dispatch.d.ts

@@ -105,6 +105,16 @@ export declare class ToolDispatchNormalizer {
     constructor(options?: {
         maxTracked?: number;
     });
+    /**
+     * v43 audit (FLOW4-4): the ledger key. A normalizer shared by every session
+     * (skill-usage's live listener holds ONE process-wide instance) used the bare
+     * call id, so two sessions that produced the same id — PTC sub-call ids are
+     * short, and an id-less payload falls back to a type+payload key that is not
+     * unique by construction — collided: the second session's read was absorbed as
+     * "already seen" and never counted, and a settle in one session flipped the
+     * other's `ok`. Callers that span sessions pass the session id as `scope`.
+     */
+    private keyOf;
     /**
      * Absorb one session event.
      * @param event - the event to absorb; any non-dispatch event is ignored.
@@ -115,7 +125,7 @@ export declare class ToolDispatchNormalizer {
     advance(event: {
         type: string;
         data?: unknown;
-    }): ToolDispatchSignal | null;
+    }, scope?: string): ToolDispatchSignal | null;
     /**
      * S2-P2-12: the SETTLE channel. \`advance\` answers \`null\` for the paired
      * event that settles an already-emitted dispatch, so a consumer that must act
@@ -129,7 +139,7 @@ export declare class ToolDispatchNormalizer {
     settledSignalOf(event: {
         type: string;
         data?: unknown;
-    }): ToolDispatchSignal | null;
+    }, scope?: string): ToolDispatchSignal | null;
     /** Oldest-first eviction once the ledger (or the settle markers) overflows. */
     private evict;
     /** Every emitted dispatch, in first-seen order. */

package/lib/types/usage.d.ts

@@ -3,7 +3,7 @@
  * Format-compatible with Hermes Agent / hermes-claw core fields.
  */
 import { type EvolutionIoLike } from './io.ts';
-export type SkillState = 'active' | 'stale' | 'archived';
+type SkillState = 'active' | 'stale' | 'archived';
 export interface UsageRecord {
     created_by: string | null;
     use_count: number;
@@ -119,6 +119,23 @@ export declare function usageObserved(usage: ReadonlyMap<string, UsageRecord>):
 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>>;
+/**
+ * Plain wholesale write of the suppression sidecar (tests and fixture seeding).
+ * @internal S2.4 (PLAN 2026-09-16, audit P2-31): NO production consumer
+ * (verified by grep; production suppressions go through
+ * {@link updateSuppressedNames}) — exported for the family's tests only. Do
+ * not use it to write the sidecar in new code.
+ *
+ * The write rides the {@link transactIo} channel (the same lock the RMW
+ * writer uses), not the former naked read → `io.writeText`: that form was an
+ * unserialized read-modify-write — the last `saveSuppressedNames` in this file
+ * with no lock, while its sibling `saveUsage` already carried the `@internal`
+ * test-only note. Version discipline is unchanged (V24-09 / S2-14): a read
+ * failure surfaces (an unreadable sidecar is never written over), a newer
+ * on-disk schema is warned about and preserved byte-for-byte (the
+ * byte-identical result short-circuits the write), and a malformed sidecar is
+ * still overwritten with the v1 shape (the historical plain-writer posture).
+ */
 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`
@@ -127,4 +144,5 @@ export declare function saveSuppressedNames(root: string, names: ReadonlySet<str
  * 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>;
+export {};
 //# sourceMappingURL=usage.d.ts.map

package/lib/types/write-inventory.d.ts

@@ -16,7 +16,7 @@
  * @module @lmzhen/dsh-evolution-core/src/write-inventory
  */
 /** How concurrent writers of one site are kept apart. */
-export type WriteSerialization = 'transact' | 'write-lock' | 'instance-claim';
+type WriteSerialization = 'transact' | 'write-lock' | 'instance-claim';
 /** One declared persisted write site. */
 export interface PersistedWriteSite {
     /** Stable id; referenced by the gate's failure text and by the specs. */
@@ -43,13 +43,31 @@ export declare const INSTANCE_KEYS: {
     /** The per-home curator: report writing + the retention sweep. */
     readonly curator: "evolution-curator";
 };
-/** The declared persisted write sites, in file order. */
-export declare const PERSISTED_WRITE_SITES: readonly PersistedWriteSite[];
-/** Sites serialized by the per-home instance claim, with their instance keys. */
+/**
+ * The declared persisted write sites, in file order.
+ *
+ * v43 audit (S2-3 / P1-10): this used to be a module-scope readFileSync plus
+ * parse, so an unshipped asset threw AT IMPORT — one absent file took the whole
+ * family's load down (0.3.79 shipped a tarball without this asset and every
+ * package failed to load). The read is lazy now: importing the package never
+ * fails on this asset, while the first caller still gets a loud, descriptive
+ * failure instead of an empty table ("no declared write sites" would silently
+ * disable rule N20).
+ * @internal S2.4 (PLAN 2026-09-16): no production caller — the arch guard
+ * reads the JSON asset directly; the tests are the only in-tree consumers.
+ * @returns the sites, in file order.
+ */
+export declare function persistedWriteSites(): readonly PersistedWriteSite[];
+/** Sites serialized by the per-home instance claim, with their instance keys.
+ * @internal S2.4 (PLAN 2026-09-16): no production caller — the arch guard
+ * reads the JSON asset directly; the tests are the only in-tree consumers. */
 export declare function instanceClaimedWriteSites(): readonly (PersistedWriteSite & {
     readonly instance: string;
 })[];
 /** One declared site by id. An undeclared id throws — a stale caller must fail
- * loud rather than read "nothing is declared". */
+ * loud rather than read "nothing is declared".
+ * @internal S2.4 (PLAN 2026-09-16): no production caller — the arch guard
+ * reads the JSON asset directly; the tests are the only in-tree consumers. */
 export declare function persistedWriteSite(id: string): PersistedWriteSite;
+export {};
 //# sourceMappingURL=write-inventory.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.3.81",
+  "version": "0.3.83",
   "publishConfig": {
     "access": "public"
   },
@@ -30,7 +30,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "js-yaml": "^4.2.0"
+    "yaml": "^2.4.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -38,7 +38,6 @@
     "@deepseek-ai/dsh-session": "^0.1.5-rc.2"
   },
   "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-scope": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-session": "^0.1.5-rc.2"

package/persisted-write-inventory.json

@@ -61,11 +61,10 @@
     "id": "curator-reports",
     "path": "<evolutionHome>/reports/curator-*.json",
     "writer": "evolution-curator/src/index.ts",
-    "serializedBy": "instance-claim",
-    "marker": "claimInstance(",
-    "instance": "evolution-curator",
+    "serializedBy": "transact",
+    "marker": "transactIo(this.io, reportsSweepLockTarget()",
     "state": [],
-    "note": "Curator run reports + their retention sweep. No per-file lock: the writer holds the per-home instance claim, so a second curator yields instead of racing the sweep."
+    "note": "Curator run reports + their retention sweep. The sweep is a multi-step list + delete-beyond-the-window over a DIRECTORY, so it has no per-file lock: v43 FLOW2-1 put it inside the IO backend's cross-process write lock (transactIo) on a per-home lock target, <evolutionHome>/reports/.retention (lock file <target>.lock, pid:token body). The former declaration here was instance-claim, which is in-process ONLY (instance-scope.ts is a module-scope Map). Two curator ROWS in one process still cannot sweep at once (the loser yields on that claim), and report writes are name-unique per runId. Trigger for the remaining gap: a second PROCESS sharing DSH_HOME now WAITS on the lock instead of sweeping concurrently, and on a backend without transact there is no lock at all, so the sweep degrades to best-effort idempotent deletes."
   },
   {
     "id": "skill-tree",