@lmzhen/dsh-evolution-core 0.3.25 → 0.3.27

package/lib/index.js

@@ -58,6 +58,10 @@ function evolutionIoAdapter(provider) {
 * us, so a leftover is stale by definition. Module-level by design: it must
 * survive across `nodeEvolutionIo()` instances for the self-heal to be
 * effective. (Not a pure function — the cross-call state is the intent.)
+* V4-05: this set — not an mtime heuristic — is the ONLY signal that a
+* same-pid lock is a leftover rather than a live in-process task, so it is the
+* sole gate for the self-pid recycle branch. Exported (read-only in practice)
+* so `io.spec.ts` can drive the self-heal path deterministically.
 */
 const pendingSelfCleanup = /* @__PURE__ */ new Set();
 /**
@@ -127,13 +131,19 @@ function nodeEvolutionIo() {
 	* retry budget (budget >= 2 x threshold), so a dead holder's lock is
 	* actually recoverable within one budget instead of being arithmetically
 	* unreachable.
-	* 0.3.21 (F-101): takeover re-reads the lock right before removing it and
-	* only removes it when the content still names the dead pid — a peer that
+	* 0.3.21 (F-101), V4-04: takeover re-reads the lock right before acting and
+	* only proceeds when the content still names the dead pid — a peer that
 	* acquired the lock after our stale probe wrote its own pid, and deleting a
-	* LIVE lock is the double-hold (concurrent task) the probe must prevent.
-	* 0.3.21 (F-367): a self-pid lock is this process's own leftover (a failed
-	* release or a crash) and is recycled immediately regardless of age; a
-	* failure to release in finally is recorded so the next write self-heals.
+	* LIVE lock is the double-hold (concurrent task) the probe must prevent. The
+	* re-read is necessary but not sufficient: two peers can both pass it, so the
+	* commit itself is an atomic rename to a unique name (only one peer's rename
+	* can succeed; the loser's source is gone). A naive rm lets the later peer
+	* delete the winner's freshly re-acquired live lock.
+	* 0.3.21 (F-367), V4-05: a self-pid lock is recycled ONLY when the failed
+	* release was recorded in pendingSelfCleanup — never on age alone, because an
+	* mtime over 1s is indistinguishable from a long task still executing in this
+	* process, and recycling that live lock would double-hold it. A failure to
+	* release in finally is recorded so the next write self-heals.
 	*/
 	const withWriteLock = async (path, task) => {
 		const lock = `${path}.lock`;
@@ -148,7 +158,7 @@ function nodeEvolutionIo() {
 					const holderContent = await readFile(lock, "utf8").catch(() => "");
 					const holder = Number(holderContent);
 					const holderAlive = Number.isInteger(holder) && holder > 0 && isAlive(holder);
-					if (holder === process.pid && (pendingSelfCleanup.has(lock) || Date.now() - st.mtimeMs > 1e3)) {
+					if (holder === process.pid && pendingSelfCleanup.has(lock)) {
 						if (await readFile(lock, "utf8").catch(() => "") === holderContent) {
 							try {
 								await rm(lock, { force: true });
@@ -158,9 +168,13 @@ function nodeEvolutionIo() {
 						continue;
 					}
 					if (Date.now() - st.mtimeMs > 1e3 && !holderAlive) {
-						if (await readFile(lock, "utf8").catch(() => "") === holderContent) try {
-							await rm(lock, { force: true });
-						} catch {}
+						if (await readFile(lock, "utf8").catch(() => "") === holderContent) {
+							const takeover = `${lock}.takeover-${process.pid}-${randomBytes(6).toString("hex")}`;
+							try {
+								await rename(lock, takeover);
+								await rm(takeover, { force: true }).catch(() => {});
+							} catch {}
+						}
 						continue;
 					}
 				} catch {
@@ -2937,7 +2951,9 @@ function skillDir(root, name) {
 /** Dot-prefixed on-disk marker name. SINGLE source: `list()` matches directory
 * entries against this name, and path builders must never hardcode a marker
 * literal (N-1: the rc.49 exists()-probe convergence dropped the dot,
-* poisoning every protectedBy/managed report). */
+* poisoning every protectedBy/managed report). Exported for cross-package
+* consumers that must probe markers without re-deriving the name (curator's
+* archive-copy bundled probe, 0.3.26 V4-02). */
 function markerEntryName(marker) {
 	return `.${marker}`;
 }
@@ -3323,8 +3339,11 @@ var SkillLibrary = class {
 	limits;
 	io;
 	onMutation;
-	/** 0.3.21 (F-208): optional cross-process RMW transactor injected by callers.
-	* When unset each single-file write falls back to read→task→write. */
+	/** 0.3.21 (F-208) + V4-20: cross-process RMW transactor. An explicitly
+	* injected value wins; otherwise the IO backend's own `transact` is bound
+	* when it provides one (cross-process atomicity on by default for any
+	* transact-capable backend), and a backend without `transact` leaves this
+	* undefined (each write falls back to the plain read→task→write path). */
 	transact;
 	/** 0.3.21 (F-208): in-process serialize queue so two concurrent mutators on
 	* one skill never interleave their read-modify-write (the cross-process layer
@@ -3335,7 +3354,10 @@ var SkillLibrary = class {
 		this.io = io;
 		this.limits = limits;
 		this.onMutation = onMutation;
-		this.transact = transact;
+		this.transact = transact ?? (io.transact ? (ioLike, path, task) => {
+			const t = ioLike.transact;
+			return t ? t(path, task) : transactIo(ioLike, path, task);
+		} : void 0);
 		this.serial = makeSerialQueue();
 	}
 	/**
@@ -4695,4 +4717,4 @@ function clampedNumber(value, fallback, opts) {
 	return value;
 }
 //#endregion
-export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, 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, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, LOW_QUALITY_THRESHOLD, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, appendEvolutionEvent, applyCuratorFields, applyCuratorLifecycleFields, applyCuratorMetaFields, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, clampedNumber, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterYamlUnsafeValues, getRecord, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, markAgentCreated, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, verifyPromptBundle, yamlPlainScalarNeedsQuotes };
+export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, 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, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, LOW_QUALITY_THRESHOLD, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, appendEvolutionEvent, applyCuratorFields, applyCuratorLifecycleFields, applyCuratorMetaFields, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, clampedNumber, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterYamlUnsafeValues, getRecord, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, markAgentCreated, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, pendingSelfCleanup, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, verifyPromptBundle, yamlPlainScalarNeedsQuotes };

package/lib/types/io.d.ts

@@ -53,6 +53,18 @@ export interface EvolutionIoLike {
 export declare function transactIo(io: EvolutionIoLike, path: string, task: (current: string | null) => string | null | Promise<string | null>): Promise<void>;
 /** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
 export declare function evolutionIoAdapter(provider: () => EvolutionIoLike): EvolutionIoLike;
+/**
+ * F-367 (②): lock paths whose release (the finally `rm`) failed. The next write
+ * to the same file proactively recycles our own leftover lock — the holder is
+ * us, so a leftover is stale by definition. Module-level by design: it must
+ * survive across `nodeEvolutionIo()` instances for the self-heal to be
+ * effective. (Not a pure function — the cross-call state is the intent.)
+ * V4-05: this set — not an mtime heuristic — is the ONLY signal that a
+ * same-pid lock is a leftover rather than a live in-process task, so it is the
+ * sole gate for the self-pid recycle branch. Exported (read-only in practice)
+ * so `io.spec.ts` can drive the self-heal path deterministically.
+ */
+export declare const pendingSelfCleanup: Set<string>;
 /**
  * Retry a rename that a peer is temporarily holding on Windows (EPERM/EBUSY):
  * a short 50ms backoff, at most 3 retries (~150ms budget), matching the

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

@@ -108,6 +108,13 @@ export declare function resolveOrigins(headerOrigin: string | undefined, isRevie
     approval: 'foreground' | 'background_review';
     library: WriteOrigin;
 };
+/** Dot-prefixed on-disk marker name. SINGLE source: `list()` matches directory
+ * entries against this name, and path builders must never hardcode a marker
+ * literal (N-1: the rc.49 exists()-probe convergence dropped the dot,
+ * poisoning every protectedBy/managed report). Exported for cross-package
+ * consumers that must probe markers without re-deriving the name (curator's
+ * archive-copy bundled probe, 0.3.26 V4-02). */
+export declare function markerEntryName(marker: 'bundled' | 'hub-installed' | 'pinned' | 'hermes-managed'): string;
 export interface Frontmatter {
     name?: string;
     description?: string;
@@ -214,8 +221,11 @@ export declare class SkillLibrary {
     readonly limits: SkillLimits;
     private readonly io;
     private readonly onMutation;
-    /** 0.3.21 (F-208): optional cross-process RMW transactor injected by callers.
-     * When unset each single-file write falls back to read→task→write. */
+    /** 0.3.21 (F-208) + V4-20: cross-process RMW transactor. An explicitly
+     * injected value wins; otherwise the IO backend's own `transact` is bound
+     * when it provides one (cross-process atomicity on by default for any
+     * transact-capable backend), and a backend without `transact` leaves this
+     * undefined (each write falls back to the plain read→task→write path). */
     private readonly transact;
     /** 0.3.21 (F-208): in-process serialize queue so two concurrent mutators on
      * one skill never interleave their read-modify-write (the cross-process layer

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