@lmzhen/dsh-evolution-core 0.3.82 → 0.4.0

package/README.md

@@ -1,65 +1,30 @@
-# @deepseek-ai/dsh-evolution-core
+# @lmzhen/dsh-evolution-core
 
-Shared pure library for the dsh-evolution plugin family.
+Shared pure library for the family: `SkillLibrary`/`MemoryStore`, the prompts and guidance text,
+the threat/quality/drift signals and the IO primitives (`nodeEvolutionIo`, `transactIo`,
+`evolutionIoAdapter`). It is **not a Cordis row** — it registers no service, tool or prompt
+section, and importing the package root is its only entry.
 
-## Model Experience
+## Model surface
 
-### Indirect model surface
+- **Model-visible:** nothing of its own: the guidance text and memory snapshot it renders are injected by the rows that consume it (`tool-memory`, `tool-skill-manage`).
+- **Prompt prefix / KV cache:** unchanged by this package: family-level rules single-sourced in `packages/README.md` §"Model-visible prompt prefix and the KV cache".
+- **Mount it?** no: a library, not a row; consumed by the family's rows (e.g. `evolution-threat`, `evolution-policy`, `memory-files`, `skill-usage`, `evolution-state-json`).
 
-#### What the model sees
-
-`@deepseek-ai/dsh-evolution-core` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
-
-#### Token effect
-
-Zero direct token effect from this package; consumers add any model-visible tokens.
-
-#### KV Cache effect
-
-Independent of request-prefix construction. This package does not alter the assembled prompt or tool list.
-
-## SkillLibrary concurrency model
-
-Skill-library mutations are read-modify-write on one file, so `SkillLibrary`
-serializes them in-process with a `makeSerialQueue` chain: `update`, `patch`,
-`restructure`, `writeSupportFile` and — since 0.3.46 — `consolidate`'s target
-read→merge→commit run their whole read→validate→write under one serial task,
-so two concurrent mutators on one skill never interleave in this process.
-Single-file writes (`update`, `patch`, `writeSupportFile`)
-additionally run the read and the write inside `transactIo` when a caller
-injects a `transact` into the constructor — that is the cross-process lock, so
-two processes sharing `DSH_HOME` cannot interleave their RMW on one file.
-`create` is INSIDE the serial chain and, when a transact backend is bound, its
-exists check runs inside the same per-file transact (v18); `archive`/`consolidate`
-are rename-based two-phase paths and stay outside the single-file serial chain.
-
-**v18 residual (updated):** `create`, `removeSupportFile` and `setPinned` now
-run on the serial chain (`removeSupportFile`'s delete also goes through the
-per-file transact), so the remaining single-file residual is the protection
-TOCTOU (a marker check outside the transact) and the multi-file two-phase
-paths `archive`/`consolidate`/`restructure`. The race needs a concurrent
-mutator on the SAME skill file/package; the exposure is acknowledged and the
-protection check is the next candidate (see the v18 optimization plan, E-5).
-
-When the backend provides `transact` (nodeEvolutionIo and the io adapter do),
-the constructor binds it BY DEFAULT since 0.3.27 — the single-file entry points
-(`update`, `patch`, `writeSupportFile`, and each per-file piece of
-`restructure`) run their read→write inside the cross-process lock for every
-instantiation, so same-file concurrent writes from different processes no
-longer resolve to last-writer-wins there. An explicit `transact` argument
-overrides the default binding. The two-phase paths deliberately stay outside
-that lock: `create`'s exists probe runs inside the transact when a transact
-backend is bound (v18), so only a transact-less custom backend can still
-double-pass the probe across processes; `archive`/`consolidate` are rename-based with best-effort
-rollback (an archive loser's rollback surfaces the raw failure when the source
-vanished), and `restructure`'s multi-file swap can expose an interleaved tree
-to a concurrent reader. These residual windows are documented rather than
-locked — cross-process writers to the SAME skill file should serialize through
-the single-file paths above.
-
-## Known Limitations and Deferred Work
+## Known limitations
 
 - This package is a library, not a Cordis row; do not mount it as a plugin.
 - 数值配置已在消费方 Config 面钳制（`min 1`/各字段域）；`MemoryStore` 内部对 `limit <= 0` 仍按 unbounded 防御处理——那是库内部防御，不构成"0 = 禁用"的配置语义。
+- Skill-library writes are serialized in-process; cross-process writers to the SAME skill file must go through the single-file paths (`update`, `patch`, `writeSupportFile`). The full concurrency model, its two-phase exceptions and their provenance are in Notes and history.
 
 **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).
+
+## Notes and history
+
+- Skill-library mutations are read-modify-write on one file, so `SkillLibrary` serializes them in-process with a `makeSerialQueue` chain: `update`, `patch`, `restructure`, `writeSupportFile` and (since 0.3.46) `consolidate`'s target read→merge→commit run their whole read→validate→write under one serial task, so two concurrent mutators on one skill never interleave in this process.
+- `create` is INSIDE the serial chain and, when a transact backend is bound, its exists check runs inside the same per-file transact (v18); `archive`/`consolidate` are rename-based two-phase paths and stay outside the single-file serial chain.
+- **v18 residual (updated):** `create`, `removeSupportFile` and `setPinned` now run on the serial chain (`removeSupportFile`'s delete also goes through the per-file transact), so the remaining single-file residual is the protection TOCTOU (a marker check outside the transact) and the multi-file two-phase paths `archive`/`consolidate`/`restructure`.
+- The race needs a concurrent mutator on the SAME skill file/package; the exposure is acknowledged and the protection check is the next candidate (see the v18 optimization plan, E-5).
+- When the backend provides `transact` (nodeEvolutionIo and the io adapter do), the constructor binds it BY DEFAULT since 0.3.27: the single-file entry points (`update`, `patch`, `writeSupportFile`, and each per-file piece of `restructure`) run their read→write inside the cross-process lock for every instantiation, so same-file concurrent writes from different processes no longer resolve to last-writer-wins there.
+- The two-phase paths deliberately stay outside that lock: `create`'s exists probe runs inside the transact when a transact backend is bound (v18), so only a transact-less custom backend can still double-pass the probe across processes; `archive`/`consolidate` are rename-based with best-effort rollback (an archive loser's rollback surfaces the raw failure when the source vanished), and `restructure`'s multi-file swap can expose an interleaved tree to a concurrent reader.
+- These residual windows are documented rather than locked: cross-process writers to the SAME skill file should serialize through the single-file paths above.

package/lib/index.js

@@ -1,11 +1,11 @@
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { cp, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createHash, randomBytes } from "node:crypto";
 import { homedir } from "node:os";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { scopeOf } from "@deepseek-ai/dsh-scope";
-import { load } from "js-yaml";
+import { parse } from "yaml";
 //#region lib/types/probe.js
 function probePresent(value) {
 	return {
@@ -1030,19 +1030,37 @@ function parseSuppressed(raw) {
 		return /* @__PURE__ */ new Set();
 	}
 }
+/**
+* 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).
+*/
 async function saveSuppressedNames(root, names, io = nodeEvolutionIo()) {
-	const current = await io.readText(suppressedFile(root));
-	if (current !== null) try {
-		const parsed = JSON.parse(current);
-		if (parsed !== null && typeof parsed.version === "number" && parsed.version > 1) {
-			console.warn(`suppression sidecar ${suppressedFile(root)} declares version ${String(parsed.version)} (newer than 1); not overwritten`);
-			return;
-		}
-	} catch {}
-	await io.writeText(suppressedFile(root), JSON.stringify({
-		version: 1,
-		names: [...names].sort()
-	}, null, 2));
+	await transactIo(io, suppressedFile(root), (current) => {
+		if (current !== null) try {
+			const parsed = JSON.parse(current);
+			if (parsed !== null && typeof parsed.version === "number" && parsed.version > 1) {
+				console.warn(`suppression sidecar ${suppressedFile(root)} declares version ${String(parsed.version)} (newer than 1); not overwritten`);
+				return current;
+			}
+		} catch {}
+		return JSON.stringify({
+			version: 1,
+			names: [...names].sort()
+		}, null, 2);
+	});
 }
 /**
 * Atomic read-modify-write on the suppression sidecar (rc.50 P2-2): `task`
@@ -1985,12 +2003,14 @@ function buildLearnPrompt(userRequest) {
 * 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
@@ -1998,15 +2018,18 @@ function buildLearnPrompt(userRequest) {
 * 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).
 */
 function evolutionRoot(env = process.env) {
-	const home = env.DSH_HOME?.trim();
-	const selected = home ? home : join(homedir(), ".dsh");
-	const expanded = selected === "~" ? homedir() : selected.startsWith("~/") || selected.startsWith("~\\") ? join(homedir(), selected.slice(2)) : selected;
-	return isAbsolute(expanded) ? expanded : resolve(expanded);
+	const fromEnv = env.DSH_HOME;
+	const selected = fromEnv !== void 0 && fromEnv.trim().length > 0 ? fromEnv : join(homedir(), ".dsh");
+	return resolve(selected === "~" ? homedir() : selected.startsWith("~/") || selected.startsWith("~\\") ? join(homedir(), selected.slice(2)) : selected);
 }
 /** Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
 * state (reports, activity store, feedback file, state-domain data). */
@@ -2192,7 +2215,7 @@ const PATTERNS = [
 		label: "read_secrets",
 		category: "exfiltration",
 		scope: "all",
-		regex: /\bcat\s+[^\n]{0,512}(?:\.env(?!\w)|(?:\bcredentials\b)|\.netrc|\.pgpass|\.npmrc|\.pypirc)/i
+		regex: /\bcat\s+[^\n]{0,512}(?:\.env(?!\w)(?!\.(?:[\w-]+\.)*(?:example|sample)(?=$|[\s"']))|(?:\bcredentials\b)|\.netrc|\.pgpass|\.npmrc|\.pypirc)/i
 	},
 	{
 		label: "ssh_backdoor",
@@ -2894,7 +2917,7 @@ var MemoryStore = class {
 		for (const [index, op] of operations.entries()) {
 			const position = index + 1;
 			if (op.action === "add") {
-				const body = (op.facts ?? "").trim();
+				const body = (op.facts ?? op.content ?? "").trim();
 				if (!body) return {
 					result: {
 						ok: false,
@@ -2973,7 +2996,7 @@ var MemoryStore = class {
 			const matchIndex = matches[0]?.matchIndex ?? -1;
 			if (op.action === "remove") working.splice(matchIndex, 1);
 			else {
-				const body = (op.facts ?? "").trim();
+				const body = (op.facts ?? op.content ?? "").trim();
 				if (!body) return {
 					result: {
 						ok: false,
@@ -3245,10 +3268,23 @@ function applyOneOverride(lines, override) {
 	if (!found) console.warn("evolution preset composition: warning — " + override.missingReason);
 	return lines;
 }
+/**
+* Row ids of a composition fragment (line scan, no YAML library).
+*
+* PLAN S5.9 (2026-09-16, audit P2-27): the id extraction accepts INDENTED
+* `- id:` rows too, so a collision hidden in a nested group is still caught —
+* the old `^- id:` anchored at column 0 and was blind to exactly the rows an
+* upstream group nesting would produce. Twin of `rowIds` in
+* `scripts/install-layered.mjs` (installer.spec pins detection parity).
+* Boundary (current, deliberate): DETECTION covers nested rows, while the
+* override INJECTION anchors (`applyOneOverride` below) still match top-level
+* rows only — the injection indent contract (`^ {2}key:`) is defined against a
+* column-0 row.
+*/
 function compositionRowIds(composition) {
 	const ids = /* @__PURE__ */ new Set();
 	for (const line of composition.split("\n")) {
-		const id = /^- id:\s*(\S+)/.exec(line)?.[1];
+		const id = /^\s*- id:\s*(\S+)/.exec(line)?.[1];
 		if (id) ids.add(id);
 	}
 	return ids;
@@ -3718,13 +3754,29 @@ function jaccard(a, b) {
 	for (const token of a) if (b.has(token)) intersection += 1;
 	return intersection / (a.size + b.size - intersection);
 }
+/** PLAN-R2 P2-8 (2026-09-16): default cap on two-name comparisons in
+* {@link computeDedupGroups}. A 2000-skill library is ~2M pairs; the old
+* unbounded two-two Jaccard ran seconds to tens of seconds per
+* review/`dedup_group` probe. 250k comparisons bounds that to well under a
+* second while staying far above every real library's pair count. Only
+* pairwise comparisons are budgeted — materializing a name's token set
+* (memoized, once per name) and the exact-hash pre-union phase are not. */
+const DEDUP_MAX_PAIR_COMPARISONS = 25e4;
 /**
 * Two-phase near-duplicate clustering: exact normalized-hash groups first,
 * then token-Jaccard edges at {@link DEDUP_SIMILARITY_THRESHOLD} with a token
 * ratio guard, union-find across the whole set.
+*
+* PLAN-R2 P2-8 (2026-09-16): each name's token set is materialized once
+* (memoized map), each pair takes an O(1) size-ratio short-circuit before the
+* intersection, and the pairwise loop is bounded by
+* `maxPairComparisons` (default {@link DEDUP_MAX_PAIR_COMPARISONS}); hitting
+* the budget stops the scan and `truncated: true` says so. Small libraries
+* (below the budget) behave exactly as the unbounded scan did.
 */
 function computeDedupGroups(input) {
 	const threshold = input.threshold ?? .95;
+	const maxPairComparisons = input.maxPairComparisons ?? 25e4;
 	const names = [...input.contents.keys()];
 	const hashes = /* @__PURE__ */ new Map();
 	for (const name of names) {
@@ -3760,12 +3812,19 @@ function computeDedupGroups(input) {
 		}
 		return set;
 	};
-	for (let index = 0; index < names.length; index += 1) {
+	let compared = 0;
+	let truncated = false;
+	for (let index = 0; index < names.length && !truncated; index += 1) {
 		const a = names[index];
 		if (a === void 0) continue;
 		for (let other = index + 1; other < names.length; other += 1) {
 			const b = names[other];
 			if (b === void 0) continue;
+			if (compared >= maxPairComparisons) {
+				truncated = true;
+				break;
+			}
+			compared += 1;
 			const [ta, tb] = [tokenSet(a), tokenSet(b)];
 			if (Math.max(ta.size, tb.size) / Math.max(1, Math.min(ta.size, tb.size)) > 5) continue;
 			if (jaccard(ta, tb) >= threshold) union(a, b);
@@ -3778,7 +3837,10 @@ function computeDedupGroups(input) {
 		if (group) group.push(name);
 		else groups.set(root, [name]);
 	}
-	return [...groups.values()].filter((group) => group.length > 1);
+	return {
+		groups: [...groups.values()].filter((group) => group.length > 1),
+		truncated
+	};
 }
 /**
 * Prefix-cluster index over a name set (rc.67 merge heuristic, input side):
@@ -3832,7 +3894,7 @@ const URL_CREDENTIALS_PATTERN = /([a-z][a-z0-9+.-]{0,63}:\/\/[^\s:/@]+:)([^\s/@]
 const PEM_PRIVATE_KEY_PATTERN = new RegExp(`-----BEGIN\\s+(?:(?:RSA|EC|DSA|OPENSSH|ENCRYPTED|PGP)\\s+)?PRIVATE\\s+KEY(?:\\s+BLOCK)?-----[\\s\\S]*?-----END\\s+(?:(?:RSA|EC|DSA|OPENSSH|ENCRYPTED|PGP)\\s+)?PRIVATE\\s+KEY(?:\\s+BLOCK)?-----`, "g");
 const BLOCK_KEY_ONLY_LINE = /(?:^|\s)([\w-]*[_\-])?((?:token|api[_-]?key|secret|password|passwd)(?:[_\-][\w-]*)?)\s*:(?:\r)?$/i;
 const CREDENTIAL_KEY_RE = /(?:[Tt]oken|[Ss]ecret|[Pp]assword|[Pp]asswd|[Aa]pi[_-]?[Kk]ey)(?![a-z])/;
-const CANDIDATE_ASSIGNMENT_PATTERN = /(^|[^\w-])([\w-]+)(["']?[\t ]*[:=][\t ]*)([^\r\n]+)/g;
+const CANDIDATE_ASSIGNMENT_PATTERN = /(^|[^\w-])([\w-]+)(["']?[\t ]*[:=][\t ]*)(?=[^\r\n])/g;
 /**
 * Mask credential-shaped text before it crosses a session boundary.
 * @param text - the text about to be sent to a model outside this session.
@@ -3844,21 +3906,39 @@ function redactSecrets(text) {
 	for (const [, pattern] of SECRET_PATTERNS) out = out.replace(pattern, "<redacted>");
 	out = out.replace(URL_CREDENTIALS_PATTERN, (_match, lead) => `${lead ?? ""}<redacted>@`);
 	out = out.replace(INLINE_ASSIGNMENT_PATTERN, (_match, lead, prefix, key, separator) => `${lead ?? ""}${prefix ?? ""}${key ?? ""}${separator ?? ""}<redacted>`);
-	out = out.replace(CANDIDATE_ASSIGNMENT_PATTERN, (match, lead, key, separator) => {
-		if (typeof key !== "string" || !CREDENTIAL_KEY_RE.test(key)) return match;
-		return `${lead ?? ""}${key}${separator ?? ""}<redacted>`;
-	});
+	const candidatePattern = new RegExp(CANDIDATE_ASSIGNMENT_PATTERN.source, "g");
+	let candidateOut = "";
+	let consumed = 0;
+	for (let m = candidatePattern.exec(out); m !== null; m = candidatePattern.exec(out)) {
+		const lead = m[1] ?? "";
+		const key = m[2] ?? "";
+		const separator = m[3] ?? "";
+		if (!CREDENTIAL_KEY_RE.test(key)) continue;
+		let valueEnd = m.index + m[0].length;
+		while (valueEnd < out.length && out[valueEnd] !== "\n" && out[valueEnd] !== "\r") valueEnd += 1;
+		candidateOut += out.slice(consumed, m.index) + lead + key + separator + "<redacted>";
+		consumed = valueEnd;
+		candidatePattern.lastIndex = valueEnd;
+	}
+	out = candidateOut + out.slice(consumed);
 	const lines = out.split("\n");
 	for (let i = 0; i < lines.length - 1; i++) {
 		const line = lines[i];
 		if (line === void 0) continue;
 		const camelKey = /^([\w-]+)\s*:(?:\r)?$/.exec(line)?.[1];
 		if (!(BLOCK_KEY_ONLY_LINE.test(line) || camelKey !== void 0 && CREDENTIAL_KEY_RE.test(camelKey))) continue;
-		const next = lines[i + 1] ?? "";
+		let valueLine = -1;
+		for (let j = i + 1; j < lines.length; j++) {
+			if ((lines[j] ?? "").trim() === "") continue;
+			valueLine = j;
+			break;
+		}
+		if (valueLine < 0) continue;
+		const next = lines[valueLine] ?? "";
 		const [, indent, value, tail] = /^([ \t]+)(\S.*?)([ \t]*)(?:\r)?$/.exec(next) ?? [];
 		if (indent === void 0 || value === void 0) continue;
 		if (value.includes("<redacted>")) continue;
-		lines[i + 1] = `${indent}<redacted>${tail ?? ""}`;
+		lines[valueLine] = `${indent}<redacted>${tail ?? ""}`;
 	}
 	out = lines.join("\n");
 	out = out.split("\n").map((line) => {
@@ -4075,6 +4155,8 @@ let cachedSites;
 * 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.
 */
 function persistedWriteSites() {
@@ -4089,12 +4171,16 @@ function persistedWriteSites() {
 	cachedSites = parseSites(JSON.parse(raw));
 	return cachedSites;
 }
-/** Sites serialized by the per-home instance claim, with their instance keys. */
+/** 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. */
 function instanceClaimedWriteSites() {
 	return persistedWriteSites().filter((site) => site.serializedBy === "instance-claim");
 }
 /** 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. */
 function persistedWriteSite(id) {
 	const site = persistedWriteSites().find((candidate) => candidate.id === id);
 	if (site === void 0) throw new Error(`evolution-core: no persisted write site "${id}" in persisted-write-inventory.json`);
@@ -4106,11 +4192,6 @@ function callingScope(ctx, held) {
 	if (held !== void 0) return held;
 	return scopeOf(ctx);
 }
-/** True when a read is deliberately scope-less (global layer only). Callers
-* pass this to the register so the choice is reviewed, not accidental. */
-function isGlobalRead(scope) {
-	return scope === void 0;
-}
 //#endregion
 //#region lib/types/skill-health.js
 /**
@@ -4792,7 +4873,8 @@ function computeDriftSignals(snapshots) {
 	const library = [];
 	const names = snapshots.map((s) => s.name);
 	const dedup = computeDedupGroups({ contents: new Map(snapshots.map((s) => [s.name, s.body])) });
-	library.push(dedup.length === 0 ? sig("dedup_group", "pass", "none", "size >= 2") : sig("dedup_group", "over", dedup.map((group) => group.join(", ")).join(" | "), "size >= 2", `members=${dedup.map((group) => group.join("|")).join(";")}`));
+	const dedupTruncation = dedup.truncated ? " (dedup scan truncated at the pair-comparison budget)" : "";
+	library.push(dedup.groups.length === 0 ? sig("dedup_group", "pass", `none${dedupTruncation}`, "size >= 2") : sig("dedup_group", "over", `${dedup.groups.map((group) => group.join(", ")).join(" | ")}${dedupTruncation}`, "size >= 2", `members=${dedup.groups.map((group) => group.join("|")).join(";")}`));
 	const clusters = computePrefixClusters(names);
 	library.push(clusters.length === 0 ? sig("prefix_cluster", "pass", "none", "size >= 2") : sig("prefix_cluster", "over", clusters.map((cluster) => cluster.members.join(", ")).join(" | "), "size >= 2", `key=${clusters.map((cluster) => cluster.key).join("|")}`));
 	const allProvided = snapshots.length > 0 && snapshots.every((s) => s.usageObserved !== null && s.usageObserved !== void 0);
@@ -4947,10 +5029,12 @@ const PLATFORM_STRING_FIELDS = [
 	"whenToUse"
 ];
 /**
-* Frontmatter values as the STRICT platform catalog reads them — js-yaml, the
-* parser `normalizeFrontmatter` also verifies rewrites with — or `null` when
-* the block is not loadable as a YAML mapping. Also reports the platform string
-* fields whose value is not a string ({@link PlatformStringSplit}).
+* Frontmatter values as the STRICT platform catalog reads them — the `yaml`
+* package (YAML 1.2 core schema, the same dependency the platform's
+* skill-filesystem parses with — see the import note above),
+* the parser `normalizeFrontmatter` also verifies rewrites with — or `null`
+* when the block is not loadable as a YAML mapping. Also reports the platform
+* string fields whose value is not a string ({@link PlatformStringSplit}).
 *
 * Scalars publish their text (`name`, `description`, `whenToUse` are strings by
 * contract; a number/boolean-shaped value keeps the text the family always
@@ -4968,7 +5052,7 @@ function strictFrontmatterValues(block) {
 	};
 	let loaded;
 	try {
-		loaded = load(block);
+		loaded = parse(block);
 	} catch {
 		return null;
 	}
@@ -5136,7 +5220,7 @@ function yamlPlainScalarNeedsQuotes(value) {
 	if (/^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?$/.test(value)) return true;
 	if (/^0x[0-9a-f]+$/i.test(value)) return true;
 	if (/^0o[0-7]+$/.test(value)) return true;
-	if (/^\.(?:inf|nan)$/i.test(value)) return true;
+	if (/^(?:[-+]?\.inf|\.nan)$/i.test(value)) return true;
 	if (/^[-?:,[\]{}#&*!|>'\"%@`\s]/.test(value)) return true;
 	return false;
 }
@@ -5147,7 +5231,10 @@ function yamlPlainScalarNeedsQuotes(value) {
 * 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
+* parser** (`yaml` — the package the platform's skill-filesystem catalog parses
+* with, YAML 1.2 core schema; PLAN S2.1, 2026-09-16 — the former "js-yaml, the
+* same parser" claim was false: js-yaml speaks YAML 1.1 full and diverged on
+* dates, timestamps and 1.1 int forms): 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).
@@ -5210,7 +5297,7 @@ function normalizeFrontmatter(content) {
 	};
 	const rewrittenBlock = lines.slice(1, end).join("\n");
 	try {
-		const parsed = load(rewrittenBlock);
+		const parsed = parse(rewrittenBlock);
 		for (const key of fields) if (String(parsed[key]) !== originalValues.get(key)) throw new Error(`rewritten value for ${key} differs from the original`);
 		return {
 			content: lines.join("\n"),
@@ -5533,9 +5620,19 @@ function skillsRoot(env = process.env) {
 * (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). */
 function resolveSkillsRoot(config = {}) {
-	return (config.root ?? "").trim() || skillsRoot();
+	const explicit = (config.root ?? "").trim();
+	return explicit ? resolve(explicit) : skillsRoot();
 }
 /** 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
@@ -7878,4 +7975,4 @@ function sessionAudited(ctx, sessionId, sessionScoped) {
 	return false;
 }
 //#endregion
-export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEAD_LOCK_TAKEOVER_MS, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_MODEL, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DISPATCH_EVENT_TYPES, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, EMPTY_LOCK_TAKEOVER_MS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FAMILY_SESSION_TOOL_NAMES, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, INSTANCE_KEYS, LOCK_BODY_RE, LOCK_SUFFIX, LOCK_TEAR_TAKEOVER_MS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, NATIVE_CALL_EVENT, NATIVE_RESULT_EVENT, PATTERN_OVERLAP, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, PTC_DISPATCH_EVENT, PTC_DISPATCH_START_EVENT, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, ToolDispatchNormalizer, ToolDispatchPayloadError, advanceReview, allowRowCollisions, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, callingScope, claimInstance, clampedNumber, clearReviewChannel, collectReadSkillNames, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, countDispatches, createGateSet, decideTakeover, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isCommittedWarning, isGlobalRead, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, neutralizePromptVariables, newSkillLibrary, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeUnknown, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, releaseInstance, renameWithRetry, renderCuratorReportMarkdown, resolveExecOrigins, resolveOrigins, resolveRootConfig, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, suppressedFile, sweepReviewChannelSessions, transactIo, transactTaskGuard, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };
+export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEAD_LOCK_TAKEOVER_MS, DEDUP_MAX_PAIR_COMPARISONS, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_MODEL, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DISPATCH_EVENT_TYPES, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, EMPTY_LOCK_TAKEOVER_MS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FAMILY_SESSION_TOOL_NAMES, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, INSTANCE_KEYS, LOCK_BODY_RE, LOCK_SUFFIX, LOCK_TEAR_TAKEOVER_MS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, NATIVE_CALL_EVENT, NATIVE_RESULT_EVENT, PATTERN_OVERLAP, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, PTC_DISPATCH_EVENT, PTC_DISPATCH_START_EVENT, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, ToolDispatchNormalizer, ToolDispatchPayloadError, advanceReview, allowRowCollisions, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, callingScope, claimInstance, clampedNumber, clearReviewChannel, collectReadSkillNames, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, countDispatches, createGateSet, decideTakeover, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isCommittedWarning, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, neutralizePromptVariables, newSkillLibrary, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeUnknown, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, releaseInstance, renameWithRetry, renderCuratorReportMarkdown, resolveExecOrigins, resolveOrigins, resolveRootConfig, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, suppressedFile, sweepReviewChannelSessions, transactIo, transactTaskGuard, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };

package/lib/types/frontmatter.d.ts

@@ -109,7 +109,10 @@ export interface FrontmatterNormalizeResult {
  * 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
+ * parser** (`yaml` — the package the platform's skill-filesystem catalog parses
+ * with, YAML 1.2 core schema; PLAN S2.1, 2026-09-16 — the former "js-yaml, the
+ * same parser" claim was false: js-yaml speaks YAML 1.1 full and diverged on
+ * dates, timestamps and 1.1 int forms): 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).

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

@@ -8,6 +8,10 @@ export type MemoryTarget = 'memory' | 'user';
 export interface MemoryOperation {
     action: 'add' | 'replace' | 'remove';
     facts?: string | undefined;
+    /** PLAN-R2 P2-6 (2026-09-16): the dsh-memory contract's alias. applyBatchCore
+     * reads `facts ?? content`, so a provider reusing this store directly can
+     * write the tool-memory schema shape without a normalization shim. */
+    content?: string | undefined;
     old_text?: string | undefined;
 }
 export interface MemoryApplyResult {

package/lib/types/quality.d.ts

@@ -45,15 +45,40 @@ export declare function computeQualityScores(input: {
     supportDirs?: ReadonlyMap<string, number>;
     now?: Date;
 }): Map<string, QualityScore>;
+/** PLAN-R2 P2-8 (2026-09-16): default cap on two-name comparisons in
+ * {@link computeDedupGroups}. A 2000-skill library is ~2M pairs; the old
+ * unbounded two-two Jaccard ran seconds to tens of seconds per
+ * review/`dedup_group` probe. 250k comparisons bounds that to well under a
+ * second while staying far above every real library's pair count. Only
+ * pairwise comparisons are budgeted — materializing a name's token set
+ * (memoized, once per name) and the exact-hash pre-union phase are not. */
+export declare const DEDUP_MAX_PAIR_COMPARISONS = 250000;
+/** PLAN-R2 P2-8 (2026-09-16): result of the near-duplicate scan. `truncated`
+ * reports that the pairwise scan stopped at the comparison budget: groups
+ * already found are valid, but pairs beyond the budget were never examined. */
+export interface DedupScanResult {
+    groups: string[][];
+    truncated: boolean;
+}
 /**
  * Two-phase near-duplicate clustering: exact normalized-hash groups first,
  * then token-Jaccard edges at {@link DEDUP_SIMILARITY_THRESHOLD} with a token
  * ratio guard, union-find across the whole set.
+ *
+ * PLAN-R2 P2-8 (2026-09-16): each name's token set is materialized once
+ * (memoized map), each pair takes an O(1) size-ratio short-circuit before the
+ * intersection, and the pairwise loop is bounded by
+ * `maxPairComparisons` (default {@link DEDUP_MAX_PAIR_COMPARISONS}); hitting
+ * the budget stops the scan and `truncated: true` says so. Small libraries
+ * (below the budget) behave exactly as the unbounded scan did.
  */
 export declare function computeDedupGroups(input: {
     contents: ReadonlyMap<string, string>;
     threshold?: number;
-}): string[][];
+    /** Pair-comparison budget (PLAN-R2 P2-8). Defaults to
+     * {@link DEDUP_MAX_PAIR_COMPARISONS}; a smaller value truncates earlier. */
+    maxPairComparisons?: number;
+}): DedupScanResult;
 /**
  * Prefix-cluster index over a name set (rc.67 merge heuristic, input side):
  * the curator prompt asks the model to identify "prefix clusters — skills

package/lib/types/scope.d.ts

@@ -21,7 +21,4 @@ import type { Context } from '@deepseek-ai/cordis';
  * platform type (`ScopeKey` is `object`). */
 export type OpaqueScopeKey = object;
 export declare function callingScope(ctx: Context, held?: OpaqueScopeKey): OpaqueScopeKey | undefined;
-/** True when a read is deliberately scope-less (global layer only). Callers
- * pass this to the register so the choice is reviewed, not accidental. */
-export declare function isGlobalRead(scope: OpaqueScopeKey | undefined): boolean;
 //# sourceMappingURL=scope.d.ts.map

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

@@ -166,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;

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/usage.d.ts

@@ -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`

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

@@ -53,15 +53,21 @@ export declare const INSTANCE_KEYS: {
  * 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. */
+/** 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.82",
+  "version": "0.4.0",
   "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"