@lmzhen/dsh-evolution-core 0.12.0 → 0.13.1

package/lib/index.js

@@ -6534,16 +6534,22 @@ function readVersionEntry(entry) {
 	if (typeof candidate.at !== "string") return null;
 	if (typeof candidate.action !== "string") return null;
 	if (typeof candidate.chars !== "number") return null;
-	return typeof candidate.beforeHash === "string" && candidate.beforeHash !== "" ? {
-		...candidate,
-		beforeHash: candidate.beforeHash
-	} : {
+	const summary = typeof candidate.summary === "string" && candidate.summary !== "" ? candidate.summary : void 0;
+	const base = {
 		v: candidate.v,
 		at: candidate.at,
 		action: candidate.action,
 		hash: candidate.hash,
 		chars: candidate.chars
 	};
+	return typeof candidate.beforeHash === "string" && candidate.beforeHash !== "" ? {
+		...base,
+		beforeHash: candidate.beforeHash,
+		...summary === void 0 ? {} : { summary }
+	} : {
+		...base,
+		...summary === void 0 ? {} : { summary }
+	};
 }
 /**
 * Read one index body for a RECORDER: "understood", "no file", or "cannot be understood".
@@ -6617,6 +6623,7 @@ function nextHistoryIndex(versions, input, keep) {
 			action: input.action,
 			hash: afterHash,
 			chars: input.after?.length ?? 0,
+			...input.summary === void 0 ? {} : { summary: input.summary },
 			...beforeHash === null ? {} : { beforeHash }
 		});
 	}
@@ -6722,6 +6729,172 @@ async function recordVersions(root, io, input, keep) {
 	});
 	return recorded;
 }
+/**
+* Classify one version action for display. Fail-closed like {@link versionTarget}: an action this
+* module does not know reads as `other` rather than being guessed, and `tests/skill-history.spec.ts`
+* pins every action the library can write, so a new one cannot land unclassified.
+* @param action - the entry’s action label.
+* @returns the kind the faces switch on.
+*/
+function versionActionKind(action) {
+	switch (action) {
+		case BASELINE_ACTION: return "baseline";
+		case "create": return "create";
+		case "patch":
+		case "edit": return "patch";
+		case "update": return "update";
+		case "restore": return "restore";
+		case "delete": return "delete";
+		case "archive": return "archive";
+		case "consolidate": return "consolidate";
+		case "restructure": return "restructure";
+		case "write_file": return "support-write";
+		case "remove_file": return "support-remove";
+		default: return "other";
+	}
+}
+/** Lines one changed region may carry before it is windowed and flagged. */
+const TEXT_DIFF_MAX_LINES = 40;
+/** Characters one windowed side may carry, so a single enormous line cannot travel whole. */
+const TEXT_DIFF_MAX_CHARS = 4e3;
+/**
+* The facts of one whole-body replacement: how many lines the changed region gained and lost, and
+* that region itself as one hunk.
+*
+* The algorithm is the honest one for "what did this edit touch": common leading and trailing lines
+* are trimmed away and what remains is ONE contiguous region. It is not a minimal edit script — a
+* body edited in two distant places reports their span as one region — and that limitation is the
+* reason the faces show the region as context rather than as a line-by-line proof.
+* @param before - the body the write replaced.
+* @param after - the body the write stored.
+* @param path - the path the hunk names (the platform’s diff card requires one).
+* @param maxLines - the window a region’s text is capped to.
+* @returns the counts, the windowed hunk, and whether the window cut anything.
+*/
+function textDiffFacts(before, after, path, maxLines = 40) {
+	const oldLines = before === "" ? [] : before.split("\n");
+	const newLines = after === "" ? [] : after.split("\n");
+	let head = 0;
+	while (head < oldLines.length && head < newLines.length && oldLines[head] === newLines[head]) head += 1;
+	let tail = 0;
+	while (tail < oldLines.length - head && tail < newLines.length - head && oldLines[oldLines.length - 1 - tail] === newLines[newLines.length - 1 - tail]) tail += 1;
+	const oldRegion = oldLines.slice(head, oldLines.length - tail);
+	const newRegion = newLines.slice(head, newLines.length - tail);
+	if (oldRegion.length === 0 && newRegion.length === 0) return {
+		linesAdded: 0,
+		linesRemoved: 0,
+		hunks: [],
+		truncated: false
+	};
+	const window = (lines) => {
+		const joined = lines.slice(0, maxLines).join("\n");
+		if (joined.length <= 4e3) return {
+			text: joined,
+			cut: lines.length > maxLines
+		};
+		return {
+			text: joined.slice(0, TEXT_DIFF_MAX_CHARS),
+			cut: true
+		};
+	};
+	const oldWindow = window(oldRegion);
+	const newWindow = window(newRegion);
+	return {
+		linesAdded: newRegion.length,
+		linesRemoved: oldRegion.length,
+		hunks: [{
+			path,
+			oldText: oldWindow.text,
+			newText: newWindow.text
+		}],
+		truncated: oldWindow.cut || newWindow.cut
+	};
+}
+/** Characters one generated summary may carry. */
+const VERSION_SUMMARY_MAX_CHARS = 80;
+/**
+* The fixed prompt the optional per-write summarizer runs (registry `skillVersionSummary`).
+*
+* Model-visible, so it is written from the model’s perspective and pinned: the tests assert that it
+* carries the skill name, the character cap and both bodies, because a silent change to a prompt is a
+* silent change to what every recorded version says.
+* @param input - the skill, the action, and the two bodies (null when absent).
+* @returns the prompt text.
+*/
+function versionSummaryPrompt(input) {
+	return [
+		"You are writing ONE line that tells a reader what this single edit to the agent skill",
+		"\"" + input.name + "\" changed. The edit action was \"" + input.action + "\".",
+		"Rules: at most " + String(80) + " characters; the same language as the body;",
+		"name the decision, number or section that moved (for example \"keeps 30 days instead of 90 days\");",
+		"never say merely that something changed; no preamble, quotes, markdown or trailing period.",
+		"",
+		"Body BEFORE the edit:",
+		input.before ?? "(the skill did not exist before this edit)",
+		"",
+		"Body AFTER the edit:",
+		input.after ?? "(the skill does not exist after this edit)"
+	].join("\n");
+}
+/**
+* Reduce a model answer to the one line the index stores.
+* @param raw - the model’s answer, whatever shape it came in.
+* @param maxChars - the character cap.
+* @returns the one line, or undefined when there is nothing usable (callers store no summary).
+*/
+function normalizeVersionSummary(raw, maxChars = 80) {
+	const firstLine = raw.split("\n").map((line) => line.trim()).find((line) => line !== "");
+	if (firstLine === void 0) return void 0;
+	const stripped = firstLine.replace(/^["'`*•s]+/u, "").replace(/["'`*s]+$/u, "").replace(/[。.]$/u, "").trim();
+	if (stripped === "") return void 0;
+	return stripped.length > maxChars ? stripped.slice(0, maxChars - 1) + "…" : stripped;
+}
+/**
+* How long ago an ISO timestamp was, as a bucket plus a count — never as a sentence.
+*
+* The shape deliberately mirrors the platform’s `relativeTime` (`ui-primitives`), so a face that later
+* may import the platform helper swaps one call and keeps its dictionary; the WORDS live in the
+* faces (the panel’s locale dictionary, the command surface’s English), which is why this module
+* returns numbers.
+* @param at - an ISO timestamp, or any string `Date.parse` understands.
+* @param nowMs - the reference instant.
+* @returns the bucket and its count; an unparsable timestamp reads as `now` with 0.
+*/
+function elapsedSince(at, nowMs) {
+	const then = Date.parse(at);
+	if (Number.isNaN(then)) return {
+		unit: "now",
+		n: 0
+	};
+	const minutes = Math.floor(Math.max(0, nowMs - then) / 6e4);
+	if (minutes < 1) return {
+		unit: "now",
+		n: 0
+	};
+	if (minutes < 60) return {
+		unit: "minutes",
+		n: minutes
+	};
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return {
+		unit: "hours",
+		n: hours
+	};
+	const days = Math.floor(hours / 24);
+	if (days < 30) return {
+		unit: "days",
+		n: days
+	};
+	const months = Math.floor(days / 30);
+	if (months < 12) return {
+		unit: "months",
+		n: months
+	};
+	return {
+		unit: "years",
+		n: Math.max(1, Math.floor(days / 365))
+	};
+}
 //#endregion
 //#region lib/types/fuzzy-match.js
 /**
@@ -10986,4 +11159,4 @@ function sessionAudited(ctx, sessionId, sessionScoped) {
 	return false;
 }
 //#endregion
-export { ALIVE_LOCK_TAKEOVER_MS, AUTHORING_DESCRIPTION_BAR, AUTHORING_SPLIT_LINE_CHARS, BASELINE_ACTION, CITATION_SUPPORT_DIRS, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CONTENT_SPLIT_HINT, COST_ASCII_TOKEN_HIGH, COST_ASCII_TOKEN_LOW, COST_CJK_TOKEN_HIGH, COST_CJK_TOKEN_LOW, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEAD_LOCK_TAKEOVER_MS, DEDUP_MAX_PAIR_COMPARISONS, DEDUP_SIMILARITY_THRESHOLD, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_CITATION_REF_BUDGET, 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_REFERENCE_REWRITE_POLICY, 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_SKILL_VERSION_KEEP, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DEFAULT_SUPPORT_READ_TOOL_NAMES, DEFAULT_THREAT_MAX_SCAN_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_ERRORS, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FAMILY_SESSION_TOOL_NAMES, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, HISTORY_DIR, HISTORY_INDEX_VERSION, HOOK_LINE_RE, INSTANCE_KEYS, KEEP_LINE_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_SUPPORT_READ_PATHS, 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, PARAM_ALIASES, PARAM_EXPOSURE, PARAM_GROUP_LABELS, PARAM_NAMESPACES, PATTERN_OVERLAP, PLATFORM_CATALOG_DESCRIPTION_DEFAULT, PLATFORM_ESTIMATE_CHARS_PER_TOKEN, POLICY_STAGE_DEFAULTS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, PTC_DISPATCH_EVENT, PTC_DISPATCH_START_EVENT, QUALITY_WEIGHTS, READ_REQUIRED_ACTIONS, RESTRUCTURE_TARGET_RE, RETENTION_FEEDBACK_KEEP_RATIO, RETENTION_FEEDBACK_MIN_CHARS, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUMMARY_DUPLICATE_HINT_THRESHOLD, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, TOKEN_ASCII_WEIGHT, TOKEN_CJK_WEIGHT, ToolDispatchNormalizer, ToolDispatchPayloadError, UPSTREAM_LIMIT_CHARS_PER_TOKEN, advanceReview, affinity, allowRowCollisions, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyReferenceRewrite, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, blobPath, bodyCost, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, canonicalWriteId, claimInstance, clampedNumber, clearReviewChannel, collectReadSkillNames, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, contentRetentionFeedback, countDispatches, createGateSet, daysSinceIso, decideTakeover, describeReferenceRewrite, duplicateHeadings, emptyRecord, errorText, evaluateThreat, eventsFile, evidenceKindIndex, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, filterUnreadSkillOps, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, historyIndexFile, historyRoot, identity, idleDays, installParamSection, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, isUnreadWrite, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, loadVersionContent, loadVersions, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nearDuplicateSummaries, neutralizePromptVariables, newSkillLibrary, nextHistoryIndex, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, orderVersions, overlongLines, paramNamespace, paramSectionOverrides, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseHistoryIndex, parseLockBody, partitionVersions, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, planReferenceRewrite, planRehoming, policyStageLimits, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeUnknown, projectionText, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readHistoryIndex, readNumberParam, readParam, recordMutation, recordVersions, redactSecrets, relatedSkillNames, releaseInstance, renameWithRetry, renderCuratorReportMarkdown, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, retainEventArchives, retirementReport, reviewPrompt, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionReadSkillNames, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, supportFileReadOf, suppressedFile, sweepReviewChannelSessions, tokenLineFor, transactIo, transactTaskGuard, unhookedSupportPointers, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, versionTarget, vocabulary, writeDurableTmp, yamlPlainScalarNeedsQuotes };
+export { ALIVE_LOCK_TAKEOVER_MS, AUTHORING_DESCRIPTION_BAR, AUTHORING_SPLIT_LINE_CHARS, BASELINE_ACTION, CITATION_SUPPORT_DIRS, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CONTENT_SPLIT_HINT, COST_ASCII_TOKEN_HIGH, COST_ASCII_TOKEN_LOW, COST_CJK_TOKEN_HIGH, COST_CJK_TOKEN_LOW, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEAD_LOCK_TAKEOVER_MS, DEDUP_MAX_PAIR_COMPARISONS, DEDUP_SIMILARITY_THRESHOLD, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_CITATION_REF_BUDGET, 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_REFERENCE_REWRITE_POLICY, 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_SKILL_VERSION_KEEP, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DEFAULT_SUPPORT_READ_TOOL_NAMES, DEFAULT_THREAT_MAX_SCAN_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_ERRORS, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FAMILY_SESSION_TOOL_NAMES, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, HISTORY_DIR, HISTORY_INDEX_VERSION, HOOK_LINE_RE, INSTANCE_KEYS, KEEP_LINE_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_SUPPORT_READ_PATHS, 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, PARAM_ALIASES, PARAM_EXPOSURE, PARAM_GROUP_LABELS, PARAM_NAMESPACES, PATTERN_OVERLAP, PLATFORM_CATALOG_DESCRIPTION_DEFAULT, PLATFORM_ESTIMATE_CHARS_PER_TOKEN, POLICY_STAGE_DEFAULTS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, PTC_DISPATCH_EVENT, PTC_DISPATCH_START_EVENT, QUALITY_WEIGHTS, READ_REQUIRED_ACTIONS, RESTRUCTURE_TARGET_RE, RETENTION_FEEDBACK_KEEP_RATIO, RETENTION_FEEDBACK_MIN_CHARS, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUMMARY_DUPLICATE_HINT_THRESHOLD, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, TEXT_DIFF_MAX_CHARS, TEXT_DIFF_MAX_LINES, THREAT_EXEMPTION_HINT, TOKEN_ASCII_WEIGHT, TOKEN_CJK_WEIGHT, ToolDispatchNormalizer, ToolDispatchPayloadError, UPSTREAM_LIMIT_CHARS_PER_TOKEN, VERSION_SUMMARY_MAX_CHARS, advanceReview, affinity, allowRowCollisions, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyReferenceRewrite, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, blobPath, bodyCost, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, canonicalWriteId, claimInstance, clampedNumber, clearReviewChannel, collectReadSkillNames, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, contentRetentionFeedback, countDispatches, createGateSet, daysSinceIso, decideTakeover, describeReferenceRewrite, duplicateHeadings, elapsedSince, emptyRecord, errorText, evaluateThreat, eventsFile, evidenceKindIndex, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, filterUnreadSkillOps, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, historyIndexFile, historyRoot, identity, idleDays, installParamSection, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, isUnreadWrite, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, loadVersionContent, loadVersions, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nearDuplicateSummaries, neutralizePromptVariables, newSkillLibrary, nextHistoryIndex, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, normalizeVersionSummary, observeEvent, orderVersions, overlongLines, paramNamespace, paramSectionOverrides, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseHistoryIndex, parseLockBody, partitionVersions, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, planReferenceRewrite, planRehoming, policyStageLimits, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeUnknown, projectionText, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readHistoryIndex, readNumberParam, readParam, recordMutation, recordVersions, redactSecrets, relatedSkillNames, releaseInstance, renameWithRetry, renderCuratorReportMarkdown, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, retainEventArchives, retirementReport, reviewPrompt, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionReadSkillNames, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, supportFileReadOf, suppressedFile, sweepReviewChannelSessions, textDiffFacts, tokenLineFor, transactIo, transactTaskGuard, unhookedSupportPointers, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, versionActionKind, versionSummaryPrompt, versionTarget, vocabulary, writeDurableTmp, yamlPlainScalarNeedsQuotes };

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

@@ -50,6 +50,10 @@ export interface SkillVersion {
      * can interleave (the index is appended after the content lock is released); this link is computed
      * from the bytes a write lock actually read, so it is the authoritative predecessor. */
     beforeHash?: string;
+    /** One line saying what this write changed, when the deployment turned the summarizer on
+     * (registry `skillVersionSummary`). Absent is a first-class state: the faces say so instead of
+     * inventing a sentence, and a version recorded before the feature existed simply has none. */
+    summary?: string;
 }
 /** One history write, carrying the content the caller already holds. */
 export interface VersionRecordInput {
@@ -60,6 +64,8 @@ export interface VersionRecordInput {
     /** Content after the mutation, or null when there is none (archive/remove_file). */
     after: string | null;
     at: string;
+    /** The one-line summary of THIS write, or undefined when the deployment does not summarize. */
+    summary?: string;
 }
 /** The version numbers one write produced; a side with no content contributes nothing. */
 export interface RecordedVersions {
@@ -223,4 +229,88 @@ export declare function loadVersionContent(root: string, io: EvolutionIoLike, na
  * @returns the version numbers, or null when there was no content to record.
  */
 export declare function recordVersions(root: string, io: EvolutionIoLike, input: VersionRecordInput, keep: number): Promise<RecordedVersions | null>;
+/** What kind of change one recorded version carries, as a CLOSED set. */
+export type VersionActionKind = 'baseline' | 'create' | 'patch' | 'update' | 'restore' | 'delete' | 'archive' | 'consolidate' | 'restructure' | 'support-write' | 'support-remove' | 'other';
+/**
+ * Classify one version action for display. Fail-closed like {@link versionTarget}: an action this
+ * module does not know reads as `other` rather than being guessed, and `tests/skill-history.spec.ts`
+ * pins every action the library can write, so a new one cannot land unclassified.
+ * @param action - the entry’s action label.
+ * @returns the kind the faces switch on.
+ */
+export declare function versionActionKind(action: string): VersionActionKind;
+/** One changed region between two bodies — the shape the platform’s diff card eats. */
+export interface TextDiffHunk {
+    readonly path: string;
+    readonly oldText: string;
+    readonly newText: string;
+}
+/** What one whole-body replacement changed, as facts. */
+export interface TextDiffFacts {
+    readonly linesAdded: number;
+    readonly linesRemoved: number;
+    readonly hunks: readonly TextDiffHunk[];
+    /** True when a changed region was longer than the window, so its text is a prefix. */
+    readonly truncated: boolean;
+}
+/** Lines one changed region may carry before it is windowed and flagged. */
+export declare const TEXT_DIFF_MAX_LINES = 40;
+/** Characters one windowed side may carry, so a single enormous line cannot travel whole. */
+export declare const TEXT_DIFF_MAX_CHARS = 4000;
+/**
+ * The facts of one whole-body replacement: how many lines the changed region gained and lost, and
+ * that region itself as one hunk.
+ *
+ * The algorithm is the honest one for "what did this edit touch": common leading and trailing lines
+ * are trimmed away and what remains is ONE contiguous region. It is not a minimal edit script — a
+ * body edited in two distant places reports their span as one region — and that limitation is the
+ * reason the faces show the region as context rather than as a line-by-line proof.
+ * @param before - the body the write replaced.
+ * @param after - the body the write stored.
+ * @param path - the path the hunk names (the platform’s diff card requires one).
+ * @param maxLines - the window a region’s text is capped to.
+ * @returns the counts, the windowed hunk, and whether the window cut anything.
+ */
+export declare function textDiffFacts(before: string, after: string, path: string, maxLines?: number): TextDiffFacts;
+/** Characters one generated summary may carry. */
+export declare const VERSION_SUMMARY_MAX_CHARS = 80;
+/**
+ * The fixed prompt the optional per-write summarizer runs (registry `skillVersionSummary`).
+ *
+ * Model-visible, so it is written from the model’s perspective and pinned: the tests assert that it
+ * carries the skill name, the character cap and both bodies, because a silent change to a prompt is a
+ * silent change to what every recorded version says.
+ * @param input - the skill, the action, and the two bodies (null when absent).
+ * @returns the prompt text.
+ */
+export declare function versionSummaryPrompt(input: {
+    name: string;
+    action: string;
+    before: string | null;
+    after: string | null;
+}): string;
+/**
+ * Reduce a model answer to the one line the index stores.
+ * @param raw - the model’s answer, whatever shape it came in.
+ * @param maxChars - the character cap.
+ * @returns the one line, or undefined when there is nothing usable (callers store no summary).
+ */
+export declare function normalizeVersionSummary(raw: string, maxChars?: number): string | undefined;
+/** A relative age, in the shape the platform’s own `relativeTime(at, now)` returns. */
+export interface RelativeAge {
+    readonly unit: 'now' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
+    readonly n: number;
+}
+/**
+ * How long ago an ISO timestamp was, as a bucket plus a count — never as a sentence.
+ *
+ * The shape deliberately mirrors the platform’s `relativeTime` (`ui-primitives`), so a face that later
+ * may import the platform helper swaps one call and keeps its dictionary; the WORDS live in the
+ * faces (the panel’s locale dictionary, the command surface’s English), which is why this module
+ * returns numbers.
+ * @param at - an ISO timestamp, or any string `Date.parse` understands.
+ * @param nowMs - the reference instant.
+ * @returns the bucket and its count; an unparsable timestamp reads as `now` with 0.
+ */
+export declare function elapsedSince(at: string, nowMs: number): RelativeAge;
 //# sourceMappingURL=skill-history.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.12.0",
+  "version": "0.13.1",
   "publishConfig": {
     "access": "public"
   },