@lmzhen/dsh-evolution-core 0.21.0 → 0.22.0

package/lib/index.js

@@ -3485,35 +3485,6 @@ function clampedNumber(value, fallback, opts) {
 	if (max !== void 0 && value > max) return fallback;
 	return value;
 }
-/**
-* Clamp one numeric knob and warn ONCE per key.
-*
-* S2.9 (T3-10): `evolution-review` and `evolution-curator` each carried their own copy of this
-* helper — their own once-per-key set and their own message — so the two settings readers of ONE
-* policy row could drift apart. The logic lives here; each caller passes its own sink (and its own
-* package prefix). A live field is read at every use, so the warning cannot be per-read.
-*
-* @param warned - the keys this caller already warned about.
-* @param warn - the warning sink (each package prefixes its own name).
-* @param name - the config key, for the warning.
-* @param value - the value as supplied, or its volatile reference.
-* @param fallback - the package default a corrected value falls back to.
-* @param min - the smallest value the engine can act on.
-* @param max - the largest value the carrier can hold, when bounded.
-* @returns the value the engine may use.
-*/
-function clampOnce(warned, warn, name, value, fallback, min, max) {
-	const current = typeof value === "object" ? value.get() : value;
-	const result = clampedNumber(current, fallback, max === void 0 ? { min } : {
-		min,
-		max
-	});
-	if (current !== void 0 && result !== current && !warned.has(name)) {
-		warned.add(name);
-		warn(`${name} provided an invalid value; falling back to the default`);
-	}
-	return result;
-}
 //#endregion
 //#region lib/types/threats.js
 /**
@@ -6697,10 +6668,24 @@ const SERIALIZATIONS = [
 ];
 /** 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");
+function parseTable(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("evolution-core: persisted-write-inventory.json must be an object with { symbols, sites }");
+	const table = raw;
+	if (table.symbols === null || typeof table.symbols !== "object" || Array.isArray(table.symbols)) throw new Error("evolution-core: persisted-write-inventory.json needs a symbols legend (the roots every path is written against)");
+	for (const [symbol, entry] of Object.entries(table.symbols)) {
+		const problems = [];
+		if (!symbol.startsWith("<") || !symbol.endsWith(">")) problems.push("symbol name (must be <name>)");
+		if (entry === null || typeof entry !== "object") problems.push("entry");
+		else {
+			const symbolEntry = entry;
+			if (typeof symbolEntry.resolver !== "string" || symbolEntry.resolver === "") problems.push("resolver");
+			if (symbolEntry.segments !== void 0 && (!Array.isArray(symbolEntry.segments) || symbolEntry.segments.some((segment) => typeof segment !== "string"))) problems.push("segments");
+		}
+		if (problems.length > 0) throw new Error(`evolution-core: persisted-write-inventory.json symbol ${symbol} is malformed (missing/invalid: ${problems.join(", ")})`);
+	}
+	if (!Array.isArray(table.sites)) throw new Error("evolution-core: persisted-write-inventory.json needs a sites array");
 	const sites = [];
-	for (const [index, entry] of raw.entries()) {
+	for (const [index, entry] of table.sites.entries()) {
 		const site = entry;
 		const problems = [];
 		if (typeof site.id !== "string" || site.id === "") problems.push("id");
@@ -6723,7 +6708,10 @@ function parseSites(raw) {
 		});
 	}
 	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;
+	return {
+		symbols: table.symbols,
+		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
@@ -6732,6 +6720,7 @@ const INSTANCE_KEYS = {
 /** The per-home curator: report writing + the retention sweep. */
 curator: "evolution-curator" };
 let cachedSites;
+let cachedSymbols;
 /**
 * The declared persisted write sites, in file order.
 *
@@ -6755,8 +6744,17 @@ function persistedWriteSites() {
 		const cause = error instanceof Error ? error.message : String(error);
 		throw new Error(`evolution-core: persisted-write-inventory.json is unreadable (${cause}) — the package asset is missing or was not shipped; the write-inventory rules cannot be evaluated without it`);
 	}
-	cachedSites = parseSites(JSON.parse(raw));
-	return cachedSites;
+	const table = parseTable(JSON.parse(raw));
+	cachedSites = table.sites;
+	cachedSymbols = table.symbols;
+	return table.sites;
+}
+/** The inventory's symbol legend — the roots every declared path is written against, with the
+* segments the gate checks against the resolver's source.
+* @internal no production caller — the gates read the JSON asset directly. */
+function writePathSymbols() {
+	persistedWriteSites();
+	return cachedSymbols ?? {};
 }
 /** 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
@@ -13443,6 +13441,114 @@ async function applyNamespaceMigration(plan, deps) {
 	};
 }
 //#endregion
+//#region lib/types/live.js
+/**
+* The family's ONE live-config reader.
+*
+* A config field reaches a plugin in two shapes: the platform's schema parser turns a
+* `.volatile()` declaration into a live reference (`{ get() }`, routed through cosmokit's
+* `createVolatile`), while a hand-built or pre-parse config carries the plain value. Reading a
+* live reference as if it were a value is SILENT (a boolean compare is simply never true, a
+* number folds as NaN) — so the two shapes are unwrapped in exactly one place here, and every
+* reader below goes through it.
+*
+* This module owns no policy: clamping semantics stay in `clampedNumber` (numeric.ts), and the
+* once-per-key warning text/rhythm is the one `clampOnce` has always had (it moved here so the
+* read happens in one place; callers import it from the package barrel, so the move is invisible).
+*
+* @module @lmzhen/dsh-evolution-core
+*/
+/**
+* Unwrap a live reference; return a plain value unchanged. The ONLY place that decides the shape.
+*
+* The discriminant is `typeof get === 'function'` rather than a bare `typeof value === 'object'`: a
+* config field may legitimately carry an object (a policy record), and calling `.get()` on that
+* used to throw where a plain read was meant.
+*
+* @param value - the field as supplied: live reference, plain value, or absent.
+* @returns the plain value, or `undefined` when the reference/field is absent.
+*/
+function unwrapLive(value) {
+	const raw = value;
+	if (typeof raw !== "object" || raw === null) return raw === void 0 ? void 0 : raw;
+	const candidate = raw;
+	return typeof candidate.get === "function" ? candidate.get.call(raw) : raw;
+}
+/**
+* Read a numeric knob (live or plain) and clamp it, warning ONCE per key.
+*
+* @param value - the field as supplied: live reference, plain value, or absent.
+* @param fallback - the package default an invalid value falls back to.
+* @param opts - bounds plus the optional warning triple.
+* @returns the value the engine may use.
+*/
+function liveNumber(value, fallback, opts = {}) {
+	const current = unwrapLive(value);
+	const { min, max } = opts;
+	const result = clampedNumber(current, fallback, min === void 0 ? max === void 0 ? void 0 : { max } : max === void 0 ? { min } : {
+		min,
+		max
+	});
+	const name = opts.name;
+	if (current !== void 0 && result !== current && name !== void 0 && opts.warn !== void 0) {
+		const warned = opts.warned ?? /* @__PURE__ */ new Set();
+		if (!warned.has(name)) {
+			warned.add(name);
+			opts.warn(`${name} provided an invalid value; falling back to the default`);
+		}
+	}
+	return result;
+}
+/**
+* Clamp one numeric knob and warn ONCE per key — the pre-0.22 signature, kept as a thin adapter so
+* existing callers migrate one at a time instead of in one commit.
+*
+* @param warned - the keys this caller already warned about.
+* @param warn - the warning sink (each package prefixes its own name).
+* @param name - the config key, for the warning.
+* @param value - the value as supplied, or its live reference.
+* @param fallback - the package default a corrected value falls back to.
+* @param min - the smallest value the engine can act on.
+* @param max - the largest value the carrier can hold, when bounded.
+* @returns the value the engine may use.
+*/
+function clampOnce(warned, warn, name, value, fallback, min, max) {
+	return liveNumber(value, fallback, {
+		min,
+		...max === void 0 ? {} : { max },
+		warned,
+		warn,
+		name
+	});
+}
+/**
+* Read a boolean flag (live or plain). Absent ⇒ `fallback` (default `false`).
+*
+* The boolean counterpart of {@link liveNumber}: `value === true` is never true for a live
+* reference, which is the silent failure this reader exists to prevent.
+*/
+function liveBool(value, fallback = false) {
+	return unwrapLive(value) ?? fallback;
+}
+/**
+* Read a string (live or plain). Blank/whitespace counts as unset — the same rule `evolutionRoot` uses
+* for `DSH_HOME`.
+*/
+function liveString(value, fallback) {
+	const current = unwrapLive(value)?.trim();
+	return current === void 0 || current.length === 0 ? fallback : current;
+}
+/**
+* Read an enumerated string (live or plain); a value outside `allowed` falls back.
+*
+* Used for the mode-like knobs (review mode, trigger, citation policy, write-confirm mode) where a
+* bare `?? default` would accept a typo the schema never saw.
+*/
+function liveEnum(value, allowed, fallback) {
+	const current = unwrapLive(value);
+	return current !== void 0 && allowed.includes(current) ? current : fallback;
+}
+//#endregion
 //#region lib/types/opt-in.js
 /**
 * Tool names only a session that mounted the family's MODEL rows can see.
@@ -13583,4 +13689,4 @@ function foldUntrustedLines(text, limit) {
 	return limit > 0 ? marked.slice(0, limit) : marked;
 }
 //#endregion
-export { AGENT_PRESET_PACKAGE, AGENT_PRESET_ROOT_HINT, 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_PROBE_TIMEOUT_MS, 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_RUN_RECORDS, 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, EMPTY_PATCH_SEED, 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, FUZZY_MAX_PATTERN_CHARS, FUZZY_MAX_WORK, 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, LONG_RUNS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_REQUEST_BODY_BYTES, 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, NAMESPACE_MIGRATIONS, 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, PLATFORM_SERVICE_PROBES, 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, RUNS_SCHEMA_VERSION, 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, UNTRUSTED_LINE_BREAK, UNTRUSTED_LINE_MARK, UPSTREAM_LIMIT_CHARS_PER_TOKEN, VERSION_SUMMARY_MAX_CHARS, absentHostServices, advanceReview, affinity, ageCopyKey, allowRowCollisions, anchorVerdict, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyNamespaceMigration, applyReferenceRewrite, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, basePresetPlugins, blobPath, bodyCost, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, canonicalWriteId, claimInstance, clampOnce, clampedNumber, classifyNamespaceMigration, clearReviewChannel, collectReadSkillNames, composePresetComposition, composePresetEntry, composePresetInsert, composePresetRow, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, contentRetentionFeedback, countDispatches, createGateSet, daysSinceIso, decideTakeover, declaredReportStamp, describeReferenceRewrite, dispatchKeyOf, dispatchStepOf, displayBodyOf, duplicateHeadings, elapsedSince, emptyRecord, entryTarget, errorText, evaluateThreat, eventsFile, evidenceKindIndex, evolutionActivityProjection, evolutionEventPayloadIssue, evolutionEvidenceProjection, evolutionHome, evolutionIoAdapter, evolutionReadsProjection, evolutionRoot, evolutionSignalsProjection, filterUnreadSkillOps, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurnEvent, foldTurnEvents, foldUntrustedLines, frontmatterBlock, frontmatterCatalogInvalid, fuzzyPatch, getRecord, historyIndexFile, historyRoot, identity, idleDays, initialTurnFold, installEvolutionProjections, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isBookkeepingFrame, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isLoopbackRequest, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, isUnreadWrite, latestActivityAt, latestVersionAt, lifecycleCandidate, listEventArchives, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, loadVersionContent, loadVersions, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, mergePresetRow, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nearDuplicateSummaries, neutralizePromptVariables, newRunRegistry, newSkillLibrary, nextHistoryIndex, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, normalizeVersionSummary, observeEvent, orderVersions, overlongLines, paramNamespace, paramRowId, paramSettingsId, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseHistoryIndex, parseLockBody, partitionVersions, payloadText, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, pickWithPolicy, planNamespaceMigration, planReferenceRewrite, planRehoming, policyStageLimits, presetPatchText, presetRowBlock, presetRowBody, presetRowId, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeText, probeUnknown, projectionText, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readHistoryIndex, readJsonBody, readJsonObject, readNumberParam, readParam, readingStats, recordMutation, recordVersions, redactSecrets, relatedSkillNames, releaseInstance, removePresetRow, renameWithRetry, renderCuratorReportMarkdown, renderLongRunTable, reportTime, reportsSweepLockTarget, resolveBasePresetPatch, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, retainEventArchives, retirementReport, reviewPrompt, runsFile, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionEvidenceIndex, sessionLastEventTime, sessionReadNames, sessionReadSkillNames, sessionSeesFamilyTools, sessionTurnSignals, skillReadNameOf, skillRowCells, skillStateKey, skillsRoot, supportFileReadOf, suppressedFile, sweepReports, sweepReviewChannelSessions, textDiffFacts, tokenLineFor, transactIo, transactTaskGuard, trimPatternBoundaries, unhookedSupportPointers, updateSuppressedNames, usageFile, usageObserved, userSetKeys, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, versionActionKind, versionRowCells, versionSummaryPrompt, versionTarget, vocabulary, writeDurableTmp, writeJson, yamlPlainScalarNeedsQuotes };
+export { AGENT_PRESET_PACKAGE, AGENT_PRESET_ROOT_HINT, 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_PROBE_TIMEOUT_MS, 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_RUN_RECORDS, 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, EMPTY_PATCH_SEED, 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, FUZZY_MAX_PATTERN_CHARS, FUZZY_MAX_WORK, 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, LONG_RUNS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_REQUEST_BODY_BYTES, 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, NAMESPACE_MIGRATIONS, 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, PLATFORM_SERVICE_PROBES, 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, RUNS_SCHEMA_VERSION, 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, UNTRUSTED_LINE_BREAK, UNTRUSTED_LINE_MARK, UPSTREAM_LIMIT_CHARS_PER_TOKEN, VERSION_SUMMARY_MAX_CHARS, absentHostServices, advanceReview, affinity, ageCopyKey, allowRowCollisions, anchorVerdict, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyNamespaceMigration, applyReferenceRewrite, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, basePresetPlugins, blobPath, bodyCost, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, canonicalWriteId, claimInstance, clampOnce, clampedNumber, classifyNamespaceMigration, clearReviewChannel, collectReadSkillNames, composePresetComposition, composePresetEntry, composePresetInsert, composePresetRow, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, contentRetentionFeedback, countDispatches, createGateSet, daysSinceIso, decideTakeover, declaredReportStamp, describeReferenceRewrite, dispatchKeyOf, dispatchStepOf, displayBodyOf, duplicateHeadings, elapsedSince, emptyRecord, entryTarget, errorText, evaluateThreat, eventsFile, evidenceKindIndex, evolutionActivityProjection, evolutionEventPayloadIssue, evolutionEvidenceProjection, evolutionHome, evolutionIoAdapter, evolutionReadsProjection, evolutionRoot, evolutionSignalsProjection, filterUnreadSkillOps, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurnEvent, foldTurnEvents, foldUntrustedLines, frontmatterBlock, frontmatterCatalogInvalid, fuzzyPatch, getRecord, historyIndexFile, historyRoot, identity, idleDays, initialTurnFold, installEvolutionProjections, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isBookkeepingFrame, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isLoopbackRequest, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, isUnreadWrite, latestActivityAt, latestVersionAt, lifecycleCandidate, listEventArchives, liveBool, liveEnum, liveNumber, liveString, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, loadVersionContent, loadVersions, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, mergePresetRow, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nearDuplicateSummaries, neutralizePromptVariables, newRunRegistry, newSkillLibrary, nextHistoryIndex, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, normalizeVersionSummary, observeEvent, orderVersions, overlongLines, paramNamespace, paramRowId, paramSettingsId, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseHistoryIndex, parseLockBody, partitionVersions, payloadText, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, pickWithPolicy, planNamespaceMigration, planReferenceRewrite, planRehoming, policyStageLimits, presetPatchText, presetRowBlock, presetRowBody, presetRowId, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeText, probeUnknown, projectionText, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readHistoryIndex, readJsonBody, readJsonObject, readNumberParam, readParam, readingStats, recordMutation, recordVersions, redactSecrets, relatedSkillNames, releaseInstance, removePresetRow, renameWithRetry, renderCuratorReportMarkdown, renderLongRunTable, reportTime, reportsSweepLockTarget, resolveBasePresetPatch, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, retainEventArchives, retirementReport, reviewPrompt, runsFile, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionEvidenceIndex, sessionLastEventTime, sessionReadNames, sessionReadSkillNames, sessionSeesFamilyTools, sessionTurnSignals, skillReadNameOf, skillRowCells, skillStateKey, skillsRoot, supportFileReadOf, suppressedFile, sweepReports, sweepReviewChannelSessions, textDiffFacts, tokenLineFor, transactIo, transactTaskGuard, trimPatternBoundaries, unhookedSupportPointers, unwrapLive, updateSuppressedNames, usageFile, usageObserved, userSetKeys, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, versionActionKind, versionRowCells, versionSummaryPrompt, versionTarget, vocabulary, writeDurableTmp, writeJson, writePathSymbols, yamlPlainScalarNeedsQuotes };

package/lib/types/index.d.ts

@@ -77,6 +77,7 @@ export * from './usage.ts';
 export * from './constants.ts';
 export * from './params.ts';
 export * from './namespace-migration.ts';
+export * from './live.ts';
 export * from './numeric.ts';
 export * from './opt-in.ts';
 export * from './payload.ts';

package/lib/types/live.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Canonical type of a config field that may arrive as a live reference or a plain value.
+ *
+ * Spelled STRUCTURALLY on purpose: the platform's `Volatile<T>` (cordis) satisfies it for every payload
+ * shape, so a field declared `Volatile<number | undefined>` and one declared `Volatile<number>` both pass
+ * without the readers importing cordis or narrowing the payload. Where a plugin wants the
+ * canonical spelling it may still write `Volatile<T>` in its own Config.
+ */
+export type LiveValue<T> = T | {
+    get(): T | undefined;
+} | undefined;
+/**
+ * Unwrap a live reference; return a plain value unchanged. The ONLY place that decides the shape.
+ *
+ * The discriminant is `typeof get === 'function'` rather than a bare `typeof value === 'object'`: a
+ * config field may legitimately carry an object (a policy record), and calling `.get()` on that
+ * used to throw where a plain read was meant.
+ *
+ * @param value - the field as supplied: live reference, plain value, or absent.
+ * @returns the plain value, or `undefined` when the reference/field is absent.
+ */
+export declare function unwrapLive<T>(value: LiveValue<T>): T | undefined;
+/** Options for {@link liveNumber}; the warning triple is all-or-nothing. */
+export interface LiveNumberOptions {
+    /** Inclusive lower bound; omit for no lower bound (0 is then a legitimate value). */
+    readonly min?: number;
+    /** Inclusive upper bound. */
+    readonly max?: number;
+    /** The keys this caller already warned about (caller-owned, so the warning stays once-per-key). */
+    readonly warned?: Set<string>;
+    /** The warning sink (each package prefixes its own name). */
+    readonly warn?: (message: string) => void;
+    /** The config key, for the warning text. Required together with `warned` and `warn`. */
+    readonly name?: string;
+}
+/**
+ * Read a numeric knob (live or plain) and clamp it, warning ONCE per key.
+ *
+ * @param value - the field as supplied: live reference, plain value, or absent.
+ * @param fallback - the package default an invalid value falls back to.
+ * @param opts - bounds plus the optional warning triple.
+ * @returns the value the engine may use.
+ */
+export declare function liveNumber(value: LiveValue<number>, fallback: number, opts?: LiveNumberOptions): number;
+/**
+ * Clamp one numeric knob and warn ONCE per key — the pre-0.22 signature, kept as a thin adapter so
+ * existing callers migrate one at a time instead of in one commit.
+ *
+ * @param warned - the keys this caller already warned about.
+ * @param warn - the warning sink (each package prefixes its own name).
+ * @param name - the config key, for the warning.
+ * @param value - the value as supplied, or its live reference.
+ * @param fallback - the package default a corrected value falls back to.
+ * @param min - the smallest value the engine can act on.
+ * @param max - the largest value the carrier can hold, when bounded.
+ * @returns the value the engine may use.
+ */
+export declare function clampOnce(warned: Set<string>, warn: (message: string) => void, name: string, value: LiveValue<number>, fallback: number, min: number, max?: number): number;
+/**
+ * Read a boolean flag (live or plain). Absent ⇒ `fallback` (default `false`).
+ *
+ * The boolean counterpart of {@link liveNumber}: `value === true` is never true for a live
+ * reference, which is the silent failure this reader exists to prevent.
+ */
+export declare function liveBool(value: LiveValue<boolean>, fallback?: boolean): boolean;
+/**
+ * Read a string (live or plain). Blank/whitespace counts as unset — the same rule `evolutionRoot` uses
+ * for `DSH_HOME`.
+ */
+export declare function liveString(value: LiveValue<string>, fallback: string): string;
+/**
+ * Read an enumerated string (live or plain); a value outside `allowed` falls back.
+ *
+ * Used for the mode-like knobs (review mode, trigger, citation policy, write-confirm mode) where a
+ * bare `?? default` would accept a typo the schema never saw.
+ */
+export declare function liveEnum<T extends string>(value: LiveValue<T>, allowed: readonly T[], fallback: T): T;
+//# sourceMappingURL=live.d.ts.map

package/lib/types/numeric.d.ts

@@ -35,24 +35,4 @@ export declare function clampedNumber(value: number | undefined, fallback: numbe
     min?: number;
     max?: number;
 }): number;
-/**
- * Clamp one numeric knob and warn ONCE per key.
- *
- * S2.9 (T3-10): `evolution-review` and `evolution-curator` each carried their own copy of this
- * helper — their own once-per-key set and their own message — so the two settings readers of ONE
- * policy row could drift apart. The logic lives here; each caller passes its own sink (and its own
- * package prefix). A live field is read at every use, so the warning cannot be per-read.
- *
- * @param warned - the keys this caller already warned about.
- * @param warn - the warning sink (each package prefixes its own name).
- * @param name - the config key, for the warning.
- * @param value - the value as supplied, or its volatile reference.
- * @param fallback - the package default a corrected value falls back to.
- * @param min - the smallest value the engine can act on.
- * @param max - the largest value the carrier can hold, when bounded.
- * @returns the value the engine may use.
- */
-export declare function clampOnce(warned: Set<string>, warn: (message: string) => void, name: string, value: number | {
-    get(): number | undefined;
-} | undefined, fallback: number, min: number, max?: number): number;
 //# sourceMappingURL=numeric.d.ts.map

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

@@ -36,6 +36,18 @@ export interface PersistedWriteSite {
     /** One line on what the file holds; the inventory reads as a whole. */
     readonly note: string;
 }
+/** One root symbol of the inventory's own legend. `segments` is the path tail the symbol appends to
+ * its base (empty for the home itself), and `basedOn` names the symbol it extends. The gate
+ * `verify-write-inventory.mjs` checks those segments against the resolver's SOURCE, so the legend
+ * cannot drift from the code that resolves it. */
+export interface WritePathSymbol {
+    /** Name of the core resolver that produces this root (or 'caller' for a caller-supplied path). */
+    readonly resolver: string;
+    /** Path segments appended to the base root, in order. */
+    readonly segments: readonly string[];
+    /** The symbol this one extends, when it is not rooted at the DSH home itself. */
+    readonly basedOn?: 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). */
@@ -58,6 +70,10 @@ export declare const INSTANCE_KEYS: {
  * @returns the sites, in file order.
  */
 export declare function persistedWriteSites(): readonly PersistedWriteSite[];
+/** The inventory's symbol legend — the roots every declared path is written against, with the
+ * segments the gate checks against the resolver's source.
+ * @internal no production caller — the gates read the JSON asset directly. */
+export declare function writePathSymbols(): Readonly<Record<string, WritePathSymbol>>;
 /** 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. */

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

package/persisted-write-inventory.json

@@ -1,137 +1,176 @@
-[
-  {
-    "id": "usage",
-    "path": "<skillsRoot>/.usage.json",
-    "writer": "evolution-core/src/usage.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io, usageFile(root)",
-    "state": [],
-    "note": "Skill usage counters. RMW under the IO backend's cross-process lock; the reader side rebuilds from the events log."
+{
+  "symbols": {
+    "<dshHome>": {
+      "resolver": "evolutionRoot",
+      "segments": []
+    },
+    "<evolutionHome>": {
+      "resolver": "evolutionHome",
+      "segments": [
+        "evolution"
+      ],
+      "basedOn": "<dshHome>"
+    },
+    "<skillsRoot>": {
+      "resolver": "skillsRoot",
+      "segments": [
+        "skills"
+      ],
+      "basedOn": "<dshHome>"
+    },
+    "<memoryRoot>": {
+      "resolver": "memoryRoot",
+      "segments": [
+        "memories"
+      ],
+      "basedOn": "<dshHome>"
+    },
+    "<historyRoot>": {
+      "resolver": "historyRoot",
+      "segments": [
+        ".history"
+      ],
+      "basedOn": "<skillsRoot>"
+    },
+    "<callerSupplied>": {
+      "resolver": "caller"
+    }
   },
-  {
-    "id": "suppressed",
-    "path": "<skillsRoot>/.curator-suppressed.json",
-    "writer": "evolution-core/src/usage.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io, suppressedFile(root)",
-    "state": [],
-    "note": "Curator suppression list (archived bundled skills that must not re-seed)."
-  },
-  {
-    "id": "mutations",
-    "path": "<skillsRoot>/.mutations.json",
-    "writer": "evolution-core/src/mutations.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io, mutationsFile(root)",
-    "state": [],
-    "note": "Skill mutation audit records (bounded ring)."
-  },
-  {
-    "id": "events",
-    "path": "<evolutionHome>/evolution/events.json",
-    "writer": "evolution-core/src/evolution-events.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io, path",
-    "state": [],
-    "note": "The rc.68 evolution event log; feedback/skill-usage stats fold it."
-  },
-  {
-    "id": "memory",
-    "path": "<memoryRoot>/<target>.md",
-    "writer": "evolution-core/src/memory-store.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(this.io, fileFor(this.root, target)",
-    "state": [],
-    "note": "Durable memory documents written by the memory tool."
-  },
-  {
-    "id": "state",
-    "path": "<evolutionHome>/<review|curator|pending>-state.json",
-    "writer": "evolution-state-json/src/index.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io(), join(root, file)",
-    "state": [],
-    "note": "The durable state stack (review/curator/pending). S4.4/O-6 moved its three warn/rewrite sets into the provider instance (QuarantineMemory), so no module-scope N12 store remains here."
-  },
-  {
-    "id": "curator-reports",
-    "path": "<evolutionHome>/reports/curator-*.json",
-    "writer": "evolution-curator/src/index.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(this.io, reportsSweepLockTarget()",
-    "state": [],
-    "note": "Curator run reports + their retention sweep. The sweep is a multi-step list + delete-beyond-the-window over a DIRECTORY, so it has no per-file lock: v43 FLOW2-1 put it inside the IO backend's cross-process write lock (transactIo) on a per-home lock target, <evolutionHome>/reports/.retention (lock file <target>.lock, pid:token body). The former declaration here was instance-claim, which is in-process ONLY (instance-scope.ts is a module-scope Map). Two curator ROWS in one process still cannot sweep at once (the loser yields on that claim), and report writes are name-unique per runId. Trigger for the remaining gap: a second PROCESS sharing DSH_HOME now WAITS on the lock instead of sweeping concurrently, and on a backend without transact there is no lock at all, so the sweep degrades to best-effort idempotent deletes."
-  },
-  {
-    "id": "runs-index",
-    "path": "<evolutionHome>/runs.json",
-    "writer": "evolution-core/src/run-registry.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(options.io, path",
-    "state": [],
-    "note": "The run registry's index (0.19.0/S2): what is in flight, how each run ended, where its report lives. Read-modify-write under the IO backend's cross-process lock, and it MERGES instead of overwriting — the desktop and the web plane share one DSH_HOME, so two hosts each know their own runs and this file is their shared view. resultRef only POINTS at the report; results never live here."
-  },
-  {
-    "id": "maintain-reports",
-    "path": "<evolutionHome>/reports/maintain-*.json",
-    "writer": "evolution-commands/src/index.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io, reportsSweepLockTarget()",
-    "state": [],
-    "note": "One report per maintenance run (0.19.0/S2), written once at settle by that run's owner under a name unique to the run, so the write itself needs no per-file lock. The retention sweep is multi-step (list the directory, then delete beyond the window) and takes the SAME per-home <evolutionHome>/reports/.retention lock the curator's sweep holds — one lock for one directory. On a backend without transact it degrades to idempotent best-effort deletes."
-  },
-  {
-    "id": "skill-tree",
-    "path": "<skillsRoot>/**",
-    "writer": "evolution-core/src/skill-store.ts",
-    "serializedBy": "write-lock",
-    "marker": "LOCK_SUFFIX",
-    "state": [],
-    "note": "The skill tree itself. Per-target `<path>.lock` claims (pid:token body) guard every byte writer; destructive movers refuse a live lock."
-  },
-  {
-    "id": "activity-log",
-    "path": "<evolutionRoot>/activity.json",
-    "writer": "evolution-activity/src/index.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io, activityFile(root)",
-    "state": [],
-    "note": "The plan-applied activity sidecar. Declared by v46 S1.12: the file carried a transactional write that no inventory row vouched for, and the N20 reverse scan is what named it."
-  },
-  {
-    "id": "skill-history-index",
-    "path": "<historyRoot>/skills/<name>/index.json",
-    "writer": "evolution-core/src/skill-history.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io, file,",
-    "state": [],
-    "note": "One skill's recorded-version index (content chain + blob references). Declared by v46 S1.12: the replace path was already transactional but undeclared, so a regression to a plain write would have been invisible."
-  },
-  {
-    "id": "skill-store-transact-primitive",
-    "path": "<caller-supplied>",
-    "writer": "evolution-core/src/skill-store.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(ioLike, path, task)",
-    "state": [],
-    "note": "The store's transaction helper: it prefers the backend's own transact and falls back to the seam's transactIo. The target is the caller's path — each durable target has its own row above; this row vouches for the primitive itself."
-  },
-  {
-    "id": "feedback-events",
-    "path": "<dshHome>/evolution/events.json",
-    "writer": "evolution-feedback/src/index.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io, eventsPath,",
-    "state": [],
-    "note": "Feedback appends to the family event log under the cross-process lock. Declared by v46 S1.12 (N20 reverse)."
-  },
-  {
-    "id": "pending-archive",
-    "path": "<stateHome>/pending-state-archive.json",
-    "writer": "evolution-state-json/src/index.ts",
-    "serializedBy": "transact",
-    "marker": "transactIo(io(), pathOf(PENDING_ARCHIVE_FILE)",
-    "state": [],
-    "note": "The resolved-pending archive (the legacy merge target). The store already declared its record map; v46 S1.12 declared the archive append as well — the second site in one file is exactly what the reverse scan exists to find."
-  }
-]
+  "sites": [
+    {
+      "id": "usage",
+      "path": "<skillsRoot>/.usage.json",
+      "writer": "evolution-core/src/usage.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, usageFile(root)",
+      "state": [],
+      "note": "Skill usage counters. RMW under the IO backend's cross-process lock; the reader side rebuilds from the events log."
+    },
+    {
+      "id": "suppressed",
+      "path": "<skillsRoot>/.curator-suppressed.json",
+      "writer": "evolution-core/src/usage.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, suppressedFile(root)",
+      "state": [],
+      "note": "Curator suppression list (archived bundled skills that must not re-seed)."
+    },
+    {
+      "id": "mutations",
+      "path": "<skillsRoot>/.mutations.json",
+      "writer": "evolution-core/src/mutations.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, mutationsFile(root)",
+      "state": [],
+      "note": "Skill mutation audit records (bounded ring)."
+    },
+    {
+      "id": "events",
+      "path": "<evolutionHome>/events.json",
+      "writer": "evolution-core/src/evolution-events.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, path",
+      "state": [],
+      "note": "The rc.68 evolution event log; feedback/skill-usage stats fold it. Shares ONE file with the \"feedback-events\" site (two writers, one log under the IO lock)."
+    },
+    {
+      "id": "memory",
+      "path": "<memoryRoot>/<target>.md",
+      "writer": "evolution-core/src/memory-store.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(this.io, fileFor(this.root, target)",
+      "state": [],
+      "note": "Durable memory documents written by the memory tool."
+    },
+    {
+      "id": "state",
+      "path": "<evolutionHome>/<review|curator|pending>-state.json",
+      "writer": "evolution-state-json/src/index.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io(), join(root, file)",
+      "state": [],
+      "note": "The durable state stack (review/curator/pending). S4.4/O-6 moved its three warn/rewrite sets into the provider instance (QuarantineMemory), so no module-scope N12 store remains here."
+    },
+    {
+      "id": "curator-reports",
+      "path": "<evolutionHome>/reports/curator-*.json",
+      "writer": "evolution-curator/src/index.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(this.io, reportsSweepLockTarget()",
+      "state": [],
+      "note": "Curator run reports + their retention sweep. The sweep is a multi-step list + delete-beyond-the-window over a DIRECTORY, so it has no per-file lock: v43 FLOW2-1 put it inside the IO backend's cross-process write lock (transactIo) on a per-home lock target, <evolutionHome>/reports/.retention (lock file <target>.lock, pid:token body). The former declaration here was instance-claim, which is in-process ONLY (instance-scope.ts is a module-scope Map). Two curator ROWS in one process still cannot sweep at once (the loser yields on that claim), and report writes are name-unique per runId. Trigger for the remaining gap: a second PROCESS sharing DSH_HOME now WAITS on the lock instead of sweeping concurrently, and on a backend without transact there is no lock at all, so the sweep degrades to best-effort idempotent deletes."
+    },
+    {
+      "id": "runs-index",
+      "path": "<evolutionHome>/runs.json",
+      "writer": "evolution-core/src/run-registry.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(options.io, path",
+      "state": [],
+      "note": "The run registry's index (0.19.0/S2): what is in flight, how each run ended, where its report lives. Read-modify-write under the IO backend's cross-process lock, and it MERGES instead of overwriting — the desktop and the web plane share one DSH_HOME, so two hosts each know their own runs and this file is their shared view. resultRef only POINTS at the report; results never live here."
+    },
+    {
+      "id": "maintain-reports",
+      "path": "<evolutionHome>/reports/maintain-*.json",
+      "writer": "evolution-commands/src/index.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, reportsSweepLockTarget()",
+      "state": [],
+      "note": "One report per maintenance run (0.19.0/S2), written once at settle by that run's owner under a name unique to the run, so the write itself needs no per-file lock. The retention sweep is multi-step (list the directory, then delete beyond the window) and takes the SAME per-home <evolutionHome>/reports/.retention lock the curator's sweep holds — one lock for one directory. On a backend without transact it degrades to idempotent best-effort deletes."
+    },
+    {
+      "id": "skill-tree",
+      "path": "<skillsRoot>/**",
+      "writer": "evolution-core/src/skill-store.ts",
+      "serializedBy": "write-lock",
+      "marker": "LOCK_SUFFIX",
+      "state": [],
+      "note": "The skill tree itself. Per-target `<path>.lock` claims (pid:token body) guard every byte writer; destructive movers refuse a live lock."
+    },
+    {
+      "id": "activity-log",
+      "path": "<evolutionHome>/activity.json",
+      "writer": "evolution-activity/src/index.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, activityFile(root)",
+      "state": [],
+      "note": "The plan-applied activity sidecar. Declared by v46 S1.12: the file carried a transactional write that no inventory row vouched for, and the N20 reverse scan is what named it."
+    },
+    {
+      "id": "skill-history-index",
+      "path": "<historyRoot>/skills/<name>/index.json",
+      "writer": "evolution-core/src/skill-history.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, file,",
+      "state": [],
+      "note": "One skill's recorded-version index (content chain + blob references). Declared by v46 S1.12: the replace path was already transactional but undeclared, so a regression to a plain write would have been invisible."
+    },
+    {
+      "id": "skill-store-transact-primitive",
+      "path": "<callerSupplied>",
+      "writer": "evolution-core/src/skill-store.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(ioLike, path, task)",
+      "state": [],
+      "note": "The store's transaction helper: it prefers the backend's own transact and falls back to the seam's transactIo. The target is the caller's path — each durable target has its own row above; this row vouches for the primitive itself."
+    },
+    {
+      "id": "feedback-events",
+      "path": "<evolutionHome>/events.json",
+      "writer": "evolution-feedback/src/index.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, eventsPath,",
+      "state": [],
+      "note": "Feedback appends to the family event log under the cross-process lock. Declared by v46 S1.12 (N20 reverse). Shares ONE file with the \"events\" site (two writers, one log under the IO lock)."
+    },
+    {
+      "id": "pending-archive",
+      "path": "<evolutionHome>/pending-state-archive.json",
+      "writer": "evolution-state-json/src/index.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io(), pathOf(PENDING_ARCHIVE_FILE)",
+      "state": [],
+      "note": "The resolved-pending archive (the legacy merge target). The store already declared its record map; v46 S1.12 declared the archive append as well — the second site in one file is exactly what the reverse scan exists to find."
+    }
+  ]
+}