@lmzhen/dsh-evolution-core 0.3.77 → 0.3.78

package/lib/index.js

@@ -2,6 +2,8 @@ import { basename, dirname, isAbsolute, 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";
 //#region lib/types/io.js
@@ -1027,7 +1029,7 @@ const SKILL_ACTION_REQUIRED_FIELDS = {
 };
 /** Skill frontmatter `name` validated for the file name (lowercase + hyphen).
 * 计划 B-4 (v18): tightened to the UPSTREAM `SKILL_NAME` shape
-* (`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, packages/skill/skill/src/index.ts:20). The
+* (`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, packages/skill/skill/src/index.ts:21). The
 * old form admitted trailing/consecutive hyphens, which upstream
 * `validateCandidate` throws on — and that throw aborts the WHOLE `ctx.skills`
 * collection. The catalog provider still filters such legacy tree entries so
@@ -3042,21 +3044,43 @@ function composePresetComposition(standardComposition, deltaComposition) {
 	if (collisions.length > 0) console.warn(`evolution preset composition: warning — delta rows collide with standard rows (${collisions.join(", ")}); keeping both (DSH_EVOLUTION_ALLOW_ROW_COLLISIONS=1)`);
 	return applyRowOverrides(`${standardComposition.replace(/\s+$/, "")}\n\n${deltaComposition.trim()}\n`);
 }
-/** The composer-owned overrides, as DATA: one place states what the generated
-* preset must carry beyond the platform composition. V10-14's cap is the first
-* entry; install-layered.mjs keeps a byte-identical copy of this table. */
-const ROW_OVERRIDES = [{
-	row: "tool-skill",
-	key: "config",
-	lines: [
-		"  # V10-14: Hermes 60-char catalog cap — injected by the preset composer (P1-2);",
-		"  # this preset-scope row is the session-visible instance and no profile",
-		"  # patch can reach it. Remove only to run the platform default (500).",
-		"  config:",
-		"    catalogDescriptionMaxLength: 60"
-	],
-	missing: "evolution preset composition: warning — no `- id: tool-skill` row in the composed preset; the 60-char catalog cap was NOT injected (platform renamed the row? reconcile with the delta)"
-}];
+/**
+* One table, two generation paths: `row-overrides.json` at the PACKAGE ROOT
+* states what a generated preset must carry beyond the platform composition,
+* and the source installer (`scripts/install-layered.mjs`) reads the same file.
+* The path resolves from both `src/` and the built `lib/`, which is why the
+* file sits at the root and ships in `files`.
+*
+* Before 0.3.77 each side carried its own hand-kept copy of this table; they
+* happened to stay byte-identical, which is exactly the kind of agreement no
+* test can keep — the entries are now data, and a divergence is impossible.
+*/
+const ROW_OVERRIDES_URL = new URL("../row-overrides.json", import.meta.url);
+let cachedOverrides;
+/**
+* Read and validate the shared override table.
+* @returns the entries, in file order. A malformed table fails LOUD: a composer
+* that silently skipped an entry would ship a preset running the platform
+* default while nothing downstream reported it.
+*/
+function loadRowOverrides() {
+	if (cachedOverrides !== void 0) return cachedOverrides;
+	const parsed = JSON.parse(readFileSync(fileURLToPath(ROW_OVERRIDES_URL), "utf8"));
+	if (!Array.isArray(parsed)) throw new Error("evolution-core: row-overrides.json must be an array of override entries");
+	const entries = [];
+	for (const [index, entry] of parsed.entries()) {
+		const candidate = entry;
+		if (candidate === null || typeof candidate !== "object" || typeof candidate.row !== "string" || candidate.row === "" || typeof candidate.key !== "string" || candidate.key === "" || !Array.isArray(candidate.lines) || candidate.lines.some((line) => typeof line !== "string") || typeof candidate.missingReason !== "string") throw new Error(`evolution-core: row-overrides.json entry ${index} is malformed (row/key/lines/missingReason are required)`);
+		entries.push({
+			row: candidate.row,
+			key: candidate.key,
+			lines: candidate.lines,
+			missingReason: candidate.missingReason
+		});
+	}
+	cachedOverrides = entries;
+	return entries;
+}
 /**
 * Ensure every {@link RowOverride} inside its target row.
 *
@@ -3066,7 +3090,7 @@ const ROW_OVERRIDES = [{
 * override REPLACES `config` wholesale — the difference is why the composer can
 * add a key without erasing the platform's own config defaults.
 */
-function applyRowOverrides(composition, overrides = ROW_OVERRIDES) {
+function applyRowOverrides(composition, overrides = loadRowOverrides()) {
 	let lines = composition.split("\n");
 	for (const override of overrides) lines = applyOneOverride(lines, override);
 	return lines.join("\n");
@@ -3090,7 +3114,7 @@ function applyOneOverride(lines, override) {
 		lines.splice(end + 1, 0, ...override.lines);
 		i = end + override.lines.length;
 	}
-	if (!found) console.warn(override.missing);
+	if (!found) console.warn("evolution preset composition: warning — " + override.missingReason);
 	return lines;
 }
 function compositionRowIds(composition) {
@@ -3807,6 +3831,177 @@ function valueOr(probe, fallback) {
 function mapProbe(probe, transform) {
 	return probe.kind === "present" ? probePresent(transform(probe.value)) : probe;
 }
+/** The reason an `unknown` probe carries (message, never a bare String(object)). */
+function probeReason(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* ENOENT/ENOTDIR are the ONE read failure that means "it is not there"; every
+* other failure is an IO error and stays unknown (same split as the node
+* backend's own isMissing, V8-23⑨ for the size probe).
+*/
+function isMissingPath(error) {
+	const code = error?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+* Three-state directory listing. The node backend already answers `[]` for a
+* MISSING directory (its own rc.50 P2-4 contract) and THROWS for an unreadable
+* one, so the value this adds is the second half: a backend that throws ENOENT
+* reads as absent, an EACCES/EIO reads as unknown — where a bare
+* `catch { return [] }` served a broken store as an empty one (the N14 class).
+*/
+async function probeList(io, dir) {
+	try {
+		return probePresent(await io.list(dir));
+	} catch (error) {
+		return isMissingPath(error) ? probeAbsent() : probeUnknown(probeReason(error));
+	}
+}
+/**
+* Three-state mtime read. Absent covers both "the path is missing" and "this
+* backend has no mtime probe" — the seam cannot tell those apart, so consumers
+* that must know say so in their own log line. A stat that FAILS is unknown.
+*/
+async function probeMtime(io, path) {
+	try {
+		const value = await io.mtime?.(path) ?? null;
+		return value === null ? probeAbsent() : probePresent(value);
+	} catch (error) {
+		return probeUnknown(probeReason(error));
+	}
+}
+//#endregion
+//#region lib/types/instance-scope.js
+/**
+* B3 / G4 (0.3.78): the family's single-instance contract, made explicit.
+*
+* Every persisted sidecar is written under TWO assumptions: the IO backend's
+* cross-process write lock serializes different processes, and exactly ONE
+* instance of each writer service exists per evolution home. The second half
+* was implicit — `makeSerialQueue()` and the module-scope stores are
+* per-instance, so two rows writing one home interleave inside one file (the
+* "two instances, one file" class). This module makes that half enforceable: a
+* writer CLAIMS its key while mounted and releases it on dispose, and a second
+* claimant is told who holds the key instead of silently racing it.
+*
+* The claim is keyed by the HOME, not by the process: the contended resource is
+* the sidecar directory, so two instances resolving different homes (an
+* isolated test fixture, a second DSH_HOME) do not contend, while two rows on
+* one profile do.
+* @module @lmzhen/dsh-evolution-core/src/instance-scope
+*/
+/** home+key -> holder. Single-process by construction: a claim can only
+* serialize instances inside this process, which is the whole point (the
+* cross-process half is the write lock, see persisted-write-inventory.json). */
+const claims = /* @__PURE__ */ new Map();
+/** `<home> :: <key>` — the registry key, exported so diagnostics name the
+* same unit the claim does. */
+function instanceClaimKey(home, key) {
+	return `${home} :: ${key}`;
+}
+/** Take the claim for `key` at `home`. Grants while it is free or already
+* held BY `owner` — remounting the same instance is not a second instance. */
+function claimInstance(home, key, owner) {
+	const id = instanceClaimKey(home, key);
+	const current = claims.get(id);
+	if (current === void 0 || current === owner) {
+		claims.set(id, owner);
+		return {
+			granted: true,
+			key: id,
+			holder: owner
+		};
+	}
+	return {
+		granted: false,
+		key: id,
+		holder: current
+	};
+}
+/** Release only the claim `owner` took — never another instance's. */
+function releaseInstance(home, key, owner) {
+	const id = instanceClaimKey(home, key);
+	if (claims.get(id) === owner) claims.delete(id);
+}
+/** The current holder of `key` at `home`, or undefined. */
+function instanceHolder(home, key) {
+	return claims.get(instanceClaimKey(home, key));
+}
+//#endregion
+//#region lib/types/write-inventory.js
+/**
+* B3 / G4 (0.3.78): the persisted-write inventory — WHICH file the family
+* writes, WHO writes it, and WHAT keeps two writers apart.
+*
+* The table lives in `persisted-write-inventory.json` at the package root so
+* the TypeScript side, the architecture gate (`verify-arch-guards` rule N20)
+* and the regression specs read ONE file (the row-overrides.json pattern).
+*
+* "What keeps two writers apart" has exactly three answers in this family:
+* - `transact`       — the IO backend's cross-process write lock (transactIo);
+* - `write-lock`     — the per-target `<path>.lock` protocol of the skill tree;
+* - `instance-claim` — the per-home single-instance claim (instance-scope.ts),
+*   for a writer whose sweeps cannot be expressed as one locked file.
+* A site that answers with NONE of them is the "two instances, one file" class:
+* a per-instance serial queue looks like serialization and is not.
+* @module @lmzhen/dsh-evolution-core/src/write-inventory
+*/
+const SITES_URL = new URL("../persisted-write-inventory.json", import.meta.url);
+const SERIALIZATIONS = [
+	"transact",
+	"write-lock",
+	"instance-claim"
+];
+/** Parse + validate the table. A malformed table throws at import: a table the
+* gate cannot read must never degrade into "no declared write sites". */
+function parseSites(raw) {
+	if (!Array.isArray(raw)) throw new Error("evolution-core: persisted-write-inventory.json must be an array of sites");
+	const sites = [];
+	for (const [index, entry] of raw.entries()) {
+		const site = entry;
+		const problems = [];
+		if (typeof site.id !== "string" || site.id === "") problems.push("id");
+		if (typeof site.path !== "string" || site.path === "") problems.push("path");
+		if (typeof site.writer !== "string" || site.writer === "") problems.push("writer");
+		if (typeof site.marker !== "string" || site.marker === "") problems.push("marker");
+		if (typeof site.serializedBy !== "string" || !SERIALIZATIONS.includes(site.serializedBy)) problems.push("serializedBy");
+		if (site.serializedBy === "instance-claim" && typeof site.instance !== "string") problems.push("instance");
+		if (!Array.isArray(site.state)) problems.push("state");
+		if (problems.length > 0) throw new Error(`evolution-core: persisted-write-inventory.json entry ${index} is malformed (missing/invalid: ${problems.join(", ")})`);
+		sites.push({
+			id: site.id,
+			path: site.path,
+			writer: site.writer,
+			serializedBy: site.serializedBy,
+			marker: site.marker,
+			...typeof site.instance === "string" ? { instance: site.instance } : {},
+			state: site.state,
+			note: typeof site.note === "string" ? site.note : ""
+		});
+	}
+	if (new Set(sites.map((site) => site.id)).size !== sites.length) throw new Error("evolution-core: persisted-write-inventory.json declares duplicate site ids");
+	return sites;
+}
+/** Instance keys held by writer services — the single source shared by the
+* claim site and the inventory row that declares it (rule N20 checks the row's
+* `instance` names one of these). */
+const INSTANCE_KEYS = { 
+/** The per-home curator: report writing + the retention sweep. */
+curator: "evolution-curator" };
+/** The declared persisted write sites, in file order. */
+const PERSISTED_WRITE_SITES = parseSites(JSON.parse(readFileSync(fileURLToPath(SITES_URL), "utf8")));
+/** Sites serialized by the per-home instance claim, with their instance keys. */
+function instanceClaimedWriteSites() {
+	return PERSISTED_WRITE_SITES.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". */
+function persistedWriteSite(id) {
+	const site = PERSISTED_WRITE_SITES.find((candidate) => candidate.id === id);
+	if (site === void 0) throw new Error(`evolution-core: no persisted write site "${id}" in persisted-write-inventory.json`);
+	return site;
+}
 //#endregion
 //#region lib/types/scope.js
 function callingScope(ctx, held) {
@@ -5666,48 +5861,40 @@ var SkillLibrary = class {
 		const name = rawName.trim();
 		if (this.badName(name) !== null) return 0;
 		const dir = this.dirOf(name);
-		let entries;
-		try {
-			entries = await this.io.list(dir);
-		} catch {
-			return 0;
-		}
+		const listed = await probeList(this.io, dir);
+		if (!isPresent(listed)) return 0;
 		let count = 0;
 		for (const subdir of SUPPORT_DIRS) {
-			if (!entries.includes(subdir)) continue;
-			try {
-				if ((await this.io.list(join(dir, subdir))).some((file) => file !== ".gitkeep")) count += 1;
-			} catch {}
+			if (!listed.value.includes(subdir)) continue;
+			const files = await probeList(this.io, join(dir, subdir));
+			if (isPresent(files) && files.value.some((file) => file !== ".gitkeep")) count += 1;
 		}
 		return count;
 	}
 	/**
-	* Relative support-file paths (`references/x.md`) under SUPPORT_DIRS for one
-	* skill; empty when the directory is unreadable or has no support files.
-	* Used by the maintenance enrichment (011 §7) and probe reads.
+	* Support-file paths (`references/x.md`) under SUPPORT_DIRS for one skill,
+	* as a THREE-state read (N14): a missing skill directory is absent, an
+	* unreadable one is unknown. A partial listing is unknown too — the union
+	* promises the present branch is complete (011 §7 enrichment, probe reads).
 	*/
 	async listSupportFiles(rawName) {
 		const name = rawName.trim();
-		if (this.badName(name) !== null) return [];
+		if (this.badName(name) !== null) return probeAbsent();
 		const dir = this.dirOf(name);
-		let entries;
-		try {
-			entries = await this.io.list(dir);
-		} catch {
-			return [];
-		}
+		const listed = await probeList(this.io, dir);
+		if (!isPresent(listed)) return listed;
 		const out = [];
 		for (const subdir of SUPPORT_DIRS) {
-			if (!entries.includes(subdir)) continue;
-			try {
-				const files = await this.io.list(join(dir, subdir));
-				for (const file of files) {
-					if (file === ".gitkeep" || file.startsWith(".")) continue;
-					out.push(`${subdir}/${file}`);
-				}
-			} catch {}
+			if (!listed.value.includes(subdir)) continue;
+			const files = await probeList(this.io, join(dir, subdir));
+			if (isUnknown(files)) return files;
+			if (!isPresent(files)) continue;
+			for (const file of files.value) {
+				if (file === ".gitkeep" || file.startsWith(".")) continue;
+				out.push(`${subdir}/${file}`);
+			}
 		}
-		return out;
+		return probePresent(out);
 	}
 	/**
 	* Structure-health facts for one skill (rc.73 A1, 008 design): body
@@ -7189,21 +7376,25 @@ var SkillLibrary = class {
 	}
 	/** Keep only the newest N snapshots (Hermes keep=5 parity); older ones are removed outright. */
 	async retainSnapshots(keep) {
-		const snapshots = await this.listSnapshots();
+		const listed = await this.listSnapshots();
+		if (isUnknown(listed)) {
+			console.warn(`skill-store: snapshot retention skipped — the snapshot directory could not be listed (${listed.reason})`);
+			return;
+		}
+		const snapshots = isPresent(listed) ? listed.value : [];
 		for (const snapshot of snapshots.slice(keep)) try {
 			await this.io.remove(snapshot.path);
 		} catch {}
 	}
+	/** Snapshots as a THREE-state read (N14): absent = no .backups directory,
+	* unknown = it exists but could not be listed (a caller must not read a
+	* failed listing as "no snapshots to restore"). */
 	async listSnapshots() {
 		const backupRoot = join(this.root, ".backups");
-		let entries;
-		try {
-			entries = await this.io.list(backupRoot);
-		} catch {
-			return [];
-		}
+		const listed = await probeList(this.io, backupRoot);
+		if (!isPresent(listed)) return listed;
 		const out = [];
-		for (const name of entries.sort().reverse()) {
+		for (const name of listed.value.sort().reverse()) {
 			if (!name.startsWith("skills-")) continue;
 			const manifest = await this.readSnapshotManifest(join(backupRoot, name));
 			if (manifest === null) {
@@ -7221,7 +7412,7 @@ var SkillLibrary = class {
 			});
 		}
 		out.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || "") || b.path.localeCompare(a.path));
-		return out;
+		return probePresent(out);
 	}
 	/**
 	* Read the extras of a snapshot, restricted to the names declared in the
@@ -7249,7 +7440,12 @@ var SkillLibrary = class {
 	* snapshot so the rollback itself is undoable with the same state.
 	*/
 	async restoreLatestSnapshot(extras = []) {
-		const latest = (await this.listSnapshots())[0];
+		const listed = await this.listSnapshots();
+		if (isUnknown(listed)) return {
+			ok: false,
+			message: `Snapshot restore refused: the snapshot directory could not be read (${listed.reason}) — nothing was changed.`
+		};
+		const latest = isPresent(listed) ? listed.value[0] : void 0;
 		if (!latest) return {
 			ok: false,
 			message: "No skill snapshot available."
@@ -7411,4 +7607,4 @@ function sessionAudited(ctx, sessionId, sessionScoped) {
 	return sessionSeesFamilyTools(ctx, sessionId);
 }
 //#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, 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, 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, isAbsent, isCommittedWarning, isGlobalRead, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, neutralizePromptVariables, newSkillLibrary, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, probeAbsent, probePresent, probeUnknown, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveRootConfig, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, sessionAudited, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, suppressedFile, sweepReviewChannelSessions, transactIo, 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, 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, PERSISTED_WRITE_SITES, 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, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeUnknown, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, releaseInstance, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveRootConfig, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, sessionAudited, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, suppressedFile, sweepReviewChannelSessions, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };

package/lib/types/constants.d.ts

@@ -37,7 +37,7 @@
 export declare const SKILL_ACTION_REQUIRED_FIELDS: Readonly<Record<string, readonly string[]>>;
 /** Skill frontmatter `name` validated for the file name (lowercase + hyphen).
  * 计划 B-4 (v18): tightened to the UPSTREAM `SKILL_NAME` shape
- * (`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, packages/skill/skill/src/index.ts:20). The
+ * (`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, packages/skill/skill/src/index.ts:21). The
  * old form admitted trailing/consecutive hyphens, which upstream
  * `validateCandidate` throws on — and that throw aborts the WHOLE `ctx.skills`
  * collection. The catalog provider still filters such legacy tree entries so

package/lib/types/index.d.ts

@@ -41,6 +41,8 @@ export * from './redact.ts';
 export * from './review-channel.ts';
 export * from './serial.ts';
 export * from './probe.ts';
+export * from './instance-scope.ts';
+export * from './write-inventory.ts';
 export * from './scope.ts';
 export * from './skill-health.ts';
 export * from './signals.ts';

package/lib/types/instance-scope.d.ts

@@ -0,0 +1,35 @@
+/**
+ * B3 / G4 (0.3.78): the family's single-instance contract, made explicit.
+ *
+ * Every persisted sidecar is written under TWO assumptions: the IO backend's
+ * cross-process write lock serializes different processes, and exactly ONE
+ * instance of each writer service exists per evolution home. The second half
+ * was implicit — `makeSerialQueue()` and the module-scope stores are
+ * per-instance, so two rows writing one home interleave inside one file (the
+ * "two instances, one file" class). This module makes that half enforceable: a
+ * writer CLAIMS its key while mounted and releases it on dispose, and a second
+ * claimant is told who holds the key instead of silently racing it.
+ *
+ * The claim is keyed by the HOME, not by the process: the contended resource is
+ * the sidecar directory, so two instances resolving different homes (an
+ * isolated test fixture, a second DSH_HOME) do not contend, while two rows on
+ * one profile do.
+ * @module @lmzhen/dsh-evolution-core/src/instance-scope
+ */
+/** Outcome of a claim. `holder` is the current owner either way. */
+export interface InstanceClaimResult {
+    readonly granted: boolean;
+    readonly key: string;
+    readonly holder: string;
+}
+/** `<home> :: <key>` — the registry key, exported so diagnostics name the
+ * same unit the claim does. */
+export declare function instanceClaimKey(home: string, key: string): string;
+/** Take the claim for `key` at `home`. Grants while it is free or already
+ * held BY `owner` — remounting the same instance is not a second instance. */
+export declare function claimInstance(home: string, key: string, owner: string): InstanceClaimResult;
+/** Release only the claim `owner` took — never another instance's. */
+export declare function releaseInstance(home: string, key: string, owner: string): void;
+/** The current holder of `key` at `home`, or undefined. */
+export declare function instanceHolder(home: string, key: string): string | undefined;
+//# sourceMappingURL=instance-scope.d.ts.map

package/lib/types/preset-composition.d.ts

@@ -26,4 +26,42 @@
  * @returns the composed preset composition (standard rows first, then delta).
  */
 export declare function composePresetComposition(standardComposition: string, deltaComposition: string): string;
+/**
+ * V10-14 (P1-2), 0.3.53: inject the Hermes 60-char catalog cap onto the
+ * standard-sourced `- id: tool-skill` row of a composed preset.
+ *
+ * The session-visible `tool-skill` instance mounts in the agent preset's own
+ * standing scope; a profile-root patch (evolution-host/cordis.patch.yml)
+ * cannot reach it, so without this injection the catalog's read side runs the
+ * platform default (500). Text-level rewrite in the same line-scan style as
+ * compositionRowIds (no YAML library):
+ *   - idempotent: a tool-skill item that already carries a `config:` key is
+ *     left byte-identical, so re-running the installer never doubles the key;
+ *   - the injected block carries a marker comment so a diff of the generated
+ *     preset can tell composer-owned text from platform text;
+ *   - a composition WITHOUT a tool-skill row is returned unchanged with a
+ *     one-time warning (a renamed platform row must not brick the install,
+ *     but the missed cap must be observable).
+ * The source installer reads the SAME table (`row-overrides.json`) through its
+ * own `injectToolSkillCap`, so the two paths cannot diverge (0.3.77).
+ */
+/** One entry of the shared override table (see {@link loadRowOverrides}). */
+interface RowOverride {
+    /** Top-level row id this override targets (`- id: <row>`). */
+    row: string;
+    /** The child key whose presence makes the override inert (idempotence). */
+    key: string;
+    /** Rendered, already-indented YAML lines to ensure inside the row. */
+    lines: string[];
+    /** Warning tail shared by both consumers; each prefixes its own logger tag. */
+    missingReason: string;
+}
+/**
+ * Read and validate the shared override table.
+ * @returns the entries, in file order. A malformed table fails LOUD: a composer
+ * that silently skipped an entry would ship a preset running the platform
+ * default while nothing downstream reported it.
+ */
+export declare function loadRowOverrides(): RowOverride[];
+export {};
 //# sourceMappingURL=preset-composition.d.ts.map

package/lib/types/probe.d.ts

@@ -9,6 +9,7 @@
  * unverifiable): constructors are prefixed so the type can never be confused
  * with a value, and only `present` yields a value.
  */
+import type { EvolutionIoLike } from './io.ts';
 export type Probe<T> = {
     kind: 'present';
     value: T;
@@ -35,4 +36,26 @@ export declare function isUnknown<T>(probe: Probe<T>): probe is {
 /** Only a PRESENT probe yields a value; absent and unknown both fall back. */
 export declare function valueOr<T>(probe: Probe<T>, fallback: T): T;
 export declare function mapProbe<T, U>(probe: Probe<T>, transform: (value: T) => U): Probe<U>;
+/** The reason an `unknown` probe carries (message, never a bare String(object)). */
+export declare function probeReason(error: unknown): string;
+/**
+ * ENOENT/ENOTDIR are the ONE read failure that means "it is not there"; every
+ * other failure is an IO error and stays unknown (same split as the node
+ * backend's own isMissing, V8-23⑨ for the size probe).
+ */
+export declare function isMissingPath(error: unknown): boolean;
+/**
+ * Three-state directory listing. The node backend already answers `[]` for a
+ * MISSING directory (its own rc.50 P2-4 contract) and THROWS for an unreadable
+ * one, so the value this adds is the second half: a backend that throws ENOENT
+ * reads as absent, an EACCES/EIO reads as unknown — where a bare
+ * `catch { return [] }` served a broken store as an empty one (the N14 class).
+ */
+export declare function probeList(io: EvolutionIoLike, dir: string): Promise<Probe<string[]>>;
+/**
+ * Three-state mtime read. Absent covers both "the path is missing" and "this
+ * backend has no mtime probe" — the seam cannot tell those apart, so consumers
+ * that must know say so in their own log line. A stat that FAILS is unknown.
+ */
+export declare function probeMtime(io: EvolutionIoLike, path: string): Promise<Probe<number>>;
 //# sourceMappingURL=probe.d.ts.map

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

@@ -33,6 +33,7 @@
  * (OPT-07); the movers' probe→rename window is owned by the io.ts protocol.
  */
 import { transactIo, type EvolutionIoLike } from './io.ts';
+import { type Probe } from './probe.ts';
 import { type MutationRecord } from './mutations.ts';
 import { type SkillHealthAssessment, type SkillHealthThresholds } from './skill-health.ts';
 import type { EvolutionSkillMutatedEvent } from './events.ts';
@@ -483,11 +484,12 @@ export declare class SkillLibrary {
     /** Count non-empty support subdirectories (richness input for quality scoring). */
     countSupportDirs(rawName: string): Promise<number>;
     /**
-     * Relative support-file paths (`references/x.md`) under SUPPORT_DIRS for one
-     * skill; empty when the directory is unreadable or has no support files.
-     * Used by the maintenance enrichment (011 §7) and probe reads.
+     * Support-file paths (`references/x.md`) under SUPPORT_DIRS for one skill,
+     * as a THREE-state read (N14): a missing skill directory is absent, an
+     * unreadable one is unknown. A partial listing is unknown too — the union
+     * promises the present branch is complete (011 §7 enrichment, probe reads).
      */
-    listSupportFiles(rawName: string): Promise<string[]>;
+    listSupportFiles(rawName: string): Promise<Probe<string[]>>;
     /**
      * Structure-health facts for one skill (rc.73 A1, 008 design): body
      * chars/density from SKILL.md, support groups from countSupportDirs, plus
@@ -664,11 +666,14 @@ export declare class SkillLibrary {
     readSnapshotManifest(path: string): Promise<SnapshotManifest | null>;
     /** Keep only the newest N snapshots (Hermes keep=5 parity); older ones are removed outright. */
     private retainSnapshots;
-    listSnapshots(): Promise<Array<{
+    /** Snapshots as a THREE-state read (N14): absent = no .backups directory,
+     * unknown = it exists but could not be listed (a caller must not read a
+     * failed listing as "no snapshots to restore"). */
+    listSnapshots(): Promise<Probe<Array<{
         path: string;
         createdAt: string;
         reason: string;
-    }>>;
+    }>>>;
     /**
      * Read the extras of a snapshot, restricted to the names declared in the
      * manifest — an `extras/` directory is never listed directly, so unknown

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

@@ -0,0 +1,55 @@
+/**
+ * B3 / G4 (0.3.78): the persisted-write inventory — WHICH file the family
+ * writes, WHO writes it, and WHAT keeps two writers apart.
+ *
+ * The table lives in `persisted-write-inventory.json` at the package root so
+ * the TypeScript side, the architecture gate (`verify-arch-guards` rule N20)
+ * and the regression specs read ONE file (the row-overrides.json pattern).
+ *
+ * "What keeps two writers apart" has exactly three answers in this family:
+ * - `transact`       — the IO backend's cross-process write lock (transactIo);
+ * - `write-lock`     — the per-target `<path>.lock` protocol of the skill tree;
+ * - `instance-claim` — the per-home single-instance claim (instance-scope.ts),
+ *   for a writer whose sweeps cannot be expressed as one locked file.
+ * A site that answers with NONE of them is the "two instances, one file" class:
+ * a per-instance serial queue looks like serialization and is not.
+ * @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';
+/** One declared persisted write site. */
+export interface PersistedWriteSite {
+    /** Stable id; referenced by the gate's failure text and by the specs. */
+    readonly id: string;
+    /** The path(s) written, with the roots the family resolves at runtime. */
+    readonly path: string;
+    /** Repo-relative module that owns the write. */
+    readonly writer: string;
+    /** The serialization the writer implements (see the module docblock). */
+    readonly serializedBy: WriteSerialization;
+    /** Literal that must appear in `writer` — the gate's proof of the claim. */
+    readonly marker: string;
+    /** The instance key the writer holds when `serializedBy` is instance-claim. */
+    readonly instance?: string;
+    /** Module-scope state keys (N12 registry keys) this writer keeps, if any. */
+    readonly state: readonly string[];
+    /** One line on what the file holds; the inventory reads as a whole. */
+    readonly note: string;
+}
+/** Instance keys held by writer services — the single source shared by the
+ * claim site and the inventory row that declares it (rule N20 checks the row's
+ * `instance` names one of these). */
+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. */
+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". */
+export declare function persistedWriteSite(id: string): PersistedWriteSite;
+//# 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.77",
+  "version": "0.3.78",
   "publishConfig": {
     "access": "public"
   },
@@ -18,11 +18,13 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./row-overrides.json": "./row-overrides.json"
   },
   "files": [
     "lib/*.js",
-    "lib/types/**/*.d.ts"
+    "lib/types/**/*.d.ts",
+    "row-overrides.json"
   ],
   "license": "MIT",
   "dependencies": {

package/row-overrides.json

@@ -0,0 +1,14 @@
+[
+  {
+    "row": "tool-skill",
+    "key": "config",
+    "lines": [
+      "  # V10-14: Hermes 60-char catalog cap — injected by the preset composer (P1-2);",
+      "  # this preset-scope row is the session-visible instance and no profile",
+      "  # patch can reach it. Remove only to run the platform default (500).",
+      "  config:",
+      "    catalogDescriptionMaxLength: 60"
+    ],
+    "missingReason": "no `- id: tool-skill` row in the composed preset; the 60-char catalog cap was NOT injected (platform renamed the row? reconcile with the delta)"
+  }
+]