@lmzhen/dsh-evolution-core 0.18.1 → 0.19.0

package/README.md

@@ -1,6 +1,6 @@
 # @lmzhen/dsh-evolution-core
 
-Shared pure library for the family: `SkillLibrary`/`MemoryStore`, the prompts and guidance text, the threat/quality/drift signals, the skill CONTENT history (`skill-history.ts`: content-addressed versions behind every write) and the frame classification the plan path reports over (`evidence.ts`), plus the IO primitives (`nodeEvolutionIo`, `transactIo`, `evolutionIoAdapter`) and the two helpers every host route surface shares (`http-routes.ts`: the loopback fence, the bounded JSON body reader and the JSON writer). It is **not a Cordis row** — it registers no service, tool or prompt
+Shared pure library for the family: `SkillLibrary`/`MemoryStore`, the prompts and guidance text, the threat/quality/drift signals, the skill CONTENT history (`skill-history.ts`: content-addressed versions behind every write) and the frame classification the plan path reports over (`evidence.ts`), plus the IO primitives (`nodeEvolutionIo`, `transactIo`, `evolutionIoAdapter`), the two helpers every host route surface shares (`http-routes.ts`: the loopback fence, the bounded JSON body reader and the JSON writer), the run lifecycle owner and the shared report window (`run-registry.ts`: the single owner of what is in flight, how a run ended and where its result lives, with read-time orphan convergence and no timer; `reports.ts`: one bucket sweep for every run-report kind, plus the per-home lock target both sweeps hold), and the long-run inventory the published table is rendered from (`long-runs.ts`). It is **not a Cordis row** — it registers no service, tool or prompt
 section, and importing the package root is its only entry.
 
 ## Model surface

package/lib/index.js

@@ -1,7 +1,7 @@
 import { parse } from "yaml";
 import { basename, dirname, join, resolve } from "node:path";
 import { cp, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -5925,6 +5925,464 @@ function sweepReviewChannelSessions(isAlive) {
 	return removed;
 }
 //#endregion
+//#region lib/types/run-registry.js
+/**
+* 0.19.0 (S2): the family's run-lifecycle owner.
+*
+* A "run" is work that can outlive one interaction — today the maintenance scan.
+* Before this module the only record of such work was the requesting invocation:
+* `lastMaintainAt` / `lastMaintainRunId` / `maintainInFlightSince` were
+* module-scope globals in evolution-commands, and the plan text existed ONLY in
+* the command's return string. An interaction that ended (measured: the desktop
+* shell hangs up at ~305 s) therefore erased every trace of a still-running scan.
+*
+* This registry is the single owner of (a) what is in flight, (b) how a run
+* ended, and (c) WHERE its result lives (`resultRef` is a path, never the result
+* itself — the report file is the one result home).
+*
+* Two disciplines are structural, not stylistic:
+*
+*   - **No timer.** A run whose process died is converged at READ time: the index
+*     file can only carry `running` records written by a PREVIOUS process life,
+*     because the live ones are in memory. `load()` therefore rewrites every
+*     `running` record as `failed(orphan)` once — the same "converge when read"
+*     posture the approval window uses for its TTL.
+*   - **One terminal state.** `settle()` refuses to overwrite a record that is
+*     already terminal, so a cancel that raced a failure cannot flip the answer
+*     the operator already read.
+*
+* The store is PER INSTANCE (a factory, not module scope): one registry per
+* mounted row, disposed with its fiber. There is no module-scope mutable state
+* here to register under N12.
+* @module
+*/
+/** Current index schema. Bump only for a structural change. */
+const RUNS_SCHEMA_VERSION = 1;
+/** Retained run records, newest first. */
+const DEFAULT_RUN_RECORDS = 50;
+/** Index path for a home. */
+function runsFile(home) {
+	return join(home, "runs.json");
+}
+const TERMINAL = new Set([
+	"succeeded",
+	"failed",
+	"cancelled"
+]);
+/**
+* Parse an index body into records.
+*
+* `ok: false` means the body could not be read as an index at all — the caller
+* decides what to say (`load()` reports it; `persist()` merges with what it can).
+* @param raw - the file's text, or null when it does not exist.
+* @returns the parsed records and whether the body was an index.
+*/
+function parseIndex(raw) {
+	if (raw === null) return {
+		ok: true,
+		records: [],
+		foreign: []
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return {
+			ok: false,
+			records: [],
+			foreign: []
+		};
+	}
+	const rows = parsed.runs;
+	if (!Array.isArray(rows)) return {
+		ok: false,
+		records: [],
+		foreign: []
+	};
+	const notes = [];
+	const version = parsed.schemaVersion;
+	if (typeof version === "number" && version !== 1) notes.push(`the index declares schemaVersion ${version} while this build writes 1`);
+	const records = [];
+	const foreign = [];
+	for (const row of rows) {
+		const record = row;
+		if (typeof record.id !== "string" || typeof record.startedAt !== "number") {
+			foreign.push(row);
+			continue;
+		}
+		if (typeof record.kind !== "string" || typeof record.state !== "string") {
+			foreign.push(row);
+			continue;
+		}
+		if (record.state !== "running" && !TERMINAL.has(record.state)) {
+			foreign.push(row);
+			continue;
+		}
+		records.push({
+			id: record.id,
+			kind: record.kind,
+			state: record.state,
+			startedAt: record.startedAt,
+			...typeof record.pid === "number" ? { pid: record.pid } : {},
+			...typeof record.endedAt === "number" ? { endedAt: record.endedAt } : {},
+			...typeof record.resultRef === "string" ? { resultRef: record.resultRef } : {},
+			...typeof record.failure === "string" ? { failure: record.failure } : {}
+		});
+	}
+	return {
+		ok: true,
+		records,
+		foreign,
+		...notes.length > 0 ? { note: notes.join("; ") } : {}
+	};
+}
+/**
+* Create the run registry for one mounted row.
+* @param options - io seam, evolution home, warn channel, clock and record cap.
+* @returns the registry; call {@link RunRegistry.load} once before answering reads.
+*/
+function newRunRegistry(options) {
+	const now = options.now ?? (() => Date.now());
+	const maxRecords = clampedNumber(options.maxRecords ?? 50, 50, { min: 1 });
+	const warn = options.warn ?? (() => {});
+	const path = runsFile(options.home);
+	const records = [];
+	const controllers = /* @__PURE__ */ new Map();
+	const ordered = () => [...records].sort((a, b) => b.startedAt - a.startedAt);
+	/** Keep every RUNNING record plus the newest terminal ones: memory and the
+	* index share one cap, so the two can never disagree about the history. */
+	const trim = () => {
+		const terminal = records.filter((record) => TERMINAL.has(record.state)).sort((a, b) => (b.endedAt ?? b.startedAt) - (a.endedAt ?? a.startedAt));
+		for (const stale of terminal.slice(maxRecords)) {
+			const index = records.indexOf(stale);
+			if (index >= 0) records.splice(index, 1);
+		}
+	};
+	const persist = async () => {
+		trim();
+		try {
+			await transactIo(options.io, path, (current) => {
+				const onDisk = parseIndex(current);
+				const merged = /* @__PURE__ */ new Map();
+				for (const record of onDisk.records) merged.set(record.id, record);
+				for (const record of records) merged.set(record.id, record);
+				const view = [...merged.values()].sort((a, b) => b.startedAt - a.startedAt);
+				const live = view.filter((record) => record.state === "running");
+				const done = view.filter((record) => TERMINAL.has(record.state)).slice(0, maxRecords);
+				return JSON.stringify({
+					schemaVersion: 1,
+					runs: [
+						...live,
+						...done,
+						...onDisk.foreign
+					]
+				}, null, 2);
+			});
+		} catch (error) {
+			warn(`evolution-core: could not persist the run index (${error instanceof Error ? error.message : String(error)})`);
+		}
+	};
+	return {
+		async load() {
+			let raw;
+			try {
+				raw = await options.io.readText(path);
+			} catch (error) {
+				return {
+					ok: false,
+					note: `run index unreadable: ${error instanceof Error ? error.message : String(error)}`
+				};
+			}
+			const parsed = parseIndex(raw);
+			if (!parsed.ok) return {
+				ok: false,
+				note: "run index could not be read as an index (not JSON, or no runs array) — the previous run history is unknown (the reports are unaffected)"
+			};
+			let converged = 0;
+			let liveElsewhere = 0;
+			for (const record of parsed.records) {
+				if (records.some((item) => item.id === record.id)) continue;
+				if (record.state !== "running") {
+					records.push(record);
+					continue;
+				}
+				if (record.pid !== void 0 && isProcessAlive(record.pid)) {
+					liveElsewhere++;
+					records.push(record);
+					continue;
+				}
+				converged++;
+				records.push({
+					...record,
+					state: "failed",
+					endedAt: now(),
+					failure: "no live owner process — the run was interrupted before it settled (orphan)"
+				});
+			}
+			if (converged > 0) await persist();
+			const notes = [
+				parsed.note,
+				converged > 0 ? `${converged} run(s) with no live owner were recorded as failed(orphan)` : void 0,
+				liveElsewhere > 0 ? `${liveElsewhere} run(s) are in flight in another process sharing this home` : void 0
+			].filter((note) => note !== void 0);
+			return {
+				ok: true,
+				...notes.length > 0 ? { note: notes.join("; ") } : {}
+			};
+		},
+		begin(kind) {
+			const id = randomUUID();
+			const startedAt = now();
+			const controller = new AbortController();
+			controllers.set(id, controller);
+			records.push({
+				id,
+				kind,
+				state: "running",
+				startedAt,
+				pid: process.pid
+			});
+			persist();
+			return {
+				id,
+				kind,
+				signal: controller.signal,
+				startedAt
+			};
+		},
+		async settle(id, outcome) {
+			const record = records.find((item) => item.id === id);
+			if (!record || TERMINAL.has(record.state)) return;
+			record.state = outcome.state;
+			record.endedAt = now();
+			if (outcome.resultRef !== void 0) record.resultRef = outcome.resultRef;
+			if (outcome.failure !== void 0) record.failure = outcome.failure;
+			controllers.delete(id);
+			await persist();
+		},
+		inFlight() {
+			return ordered().find((record) => record.state === "running");
+		},
+		lastSettledAt() {
+			return ordered().find((record) => TERMINAL.has(record.state))?.endedAt;
+		},
+		runs() {
+			return ordered();
+		},
+		find(id) {
+			return records.find((record) => record.id === id);
+		},
+		cancel(id) {
+			const controller = controllers.get(id);
+			if (controller === void 0) return false;
+			const record = records.find((item) => item.id === id);
+			if (!record || record.state !== "running") return false;
+			controller.abort();
+			controllers.delete(id);
+			record.state = "cancelled";
+			record.endedAt = now();
+			record.failure = "cancelled by operator";
+			persist();
+			return true;
+		},
+		cancelAll() {
+			let count = 0;
+			for (const id of [...controllers.keys()]) if (this.cancel(id)) count++;
+			return count;
+		}
+	};
+}
+//#endregion
+//#region lib/types/reports.js
+/**
+* 0.19.0 (S2): the family's ONE report-retention sweep.
+*
+* Reports accumulate by design (every run writes one), so each kind needs a
+* window or the reports home becomes an unbounded directory. The logic lived
+* inside the curator only; the maintenance run reports added in 0.19.0 needed
+* the same thing, and a second copy of "list, order, delete beyond the window"
+* is exactly the kind of near-duplicate this family treats as a defect.
+*
+* Three behaviours are the curator's, kept verbatim because they are the reason
+* the sweep is safe to run at all:
+*
+*   - An UNLISTABLE directory is not "no reports" — nothing is deleted and the
+*     caller is told (the same three-state rule the probe files use).
+*   - A report with no usable timestamp is KEPT (never delete what cannot be
+*     ordered) and the fact is said out loud once.
+*   - The order is TOTAL: declared time, then mtime, then name. A tie falling
+*     through to readdir order evicted a different set per platform (CI-caught).
+* @module
+*/
+/**
+* The lock target a reports sweep holds for one home.
+*
+* `transactIo` takes the IO write lock on THIS path (minting `<path>.lock` with
+* the io protocol's `pid:token` body) and holds it for the whole task; nothing
+* ever writes the target, because the sweep's exclusion is the point. It lives
+* inside `<home>/reports` next to the directory it protects (the sweeps' own name
+* filters ignore it, and the lock file is removed on release).
+*
+* Moved here from evolution-curator in 0.19.0 (S2): the maintenance reports'
+* sweep needs the SAME exclusion, and a second lock would protect nothing.
+* @returns the lock target path.
+*/
+function reportsSweepLockTarget() {
+	return join(evolutionHome(), "reports", ".retention");
+}
+/**
+* Delete the reports beyond each bucket's window, each with its `.md` digest.
+*
+* Best-effort by construction: pruning never fails the run that wrote a report.
+* @param options - io seam, directory, windows, warn channel and owner name.
+* @returns nothing; deletions and skips are reported through `warn`.
+*/
+async function sweepReports(options) {
+	const warn = options.warn ?? (() => {});
+	const listed = await probeList(options.io, options.dir);
+	if (isUnknown(listed)) {
+		warn(`${options.owner}: report retention skipped — the reports directory could not be listed (${listed.reason})`);
+		return;
+	}
+	const entries = isPresent(listed) ? listed.value : [];
+	const buckets = [...options.buckets].sort((a, b) => b.prefix.length - a.prefix.length);
+	const dated = new Map(buckets.map((bucket) => [bucket.prefix, []]));
+	let unorderableWarned = false;
+	for (const name of entries) {
+		if (!name.endsWith(".json")) continue;
+		const bucket = buckets.find((item) => name.startsWith(item.prefix));
+		if (!bucket) continue;
+		try {
+			const path = join(options.dir, name);
+			const raw = await options.io.readText(path);
+			if (raw === null) continue;
+			const startedAt = await reportTime(options.io, path, JSON.parse(raw));
+			const probed = await probeMtime(options.io, path);
+			const mtime = isPresent(probed) ? probed.value : null;
+			if (startedAt !== null) dated.get(bucket.prefix)?.push({
+				name,
+				startedAt,
+				mtime
+			});
+			else if (!unorderableWarned) {
+				unorderableWarned = true;
+				warn(`${options.owner}: report "${name}" carries no usable timestamp and this backend has no mtime probe - it is kept outside the retention window`);
+			}
+		} catch {}
+	}
+	const newestFirst = (a, b) => b.startedAt - a.startedAt || (b.mtime ?? 0) - (a.mtime ?? 0) || b.name.localeCompare(a.name);
+	for (const bucket of buckets) {
+		const rows = dated.get(bucket.prefix) ?? [];
+		rows.sort(newestFirst);
+		for (const old of rows.slice(bucket.keep)) {
+			const stem = old.name.replace(/\.json$/, "");
+			try {
+				await options.io.remove(join(options.dir, old.name));
+			} catch {}
+			try {
+				await options.io.remove(join(options.dir, `${stem}.md`));
+			} catch {}
+		}
+	}
+}
+//#endregion
+//#region lib/types/long-runs.js
+/**
+* 0.19.0 (S4): the family's long-run inventory — one table, one owner per entry.
+*
+* A "long run" is work whose duration is NOT bounded by the interaction that asked
+* for it: a maintenance scan, a curator pass, a review pass. The measured fact this
+* table exists to record is that a CLIENT can end a request long before the work is
+* done (measured: the desktop shell ends a request at ~305 s while the same command
+* finishes in 949.7 s on the web plane), so the lifetime of such work must come from
+* its OWNER — never from the request.
+*
+* Two fields carry the judgments, and a spec pins both:
+*
+*   - `lifetime`: `'plugin'` entries must name an owner and a result home (the work
+*     outlives the request and must be readable afterwards); `'request'` entries
+*     must say WHY their cost cannot reach the wall.
+*   - `measured`: only measured numbers, with their basis. An unmeasured bound is
+*     written as exactly that — this table is not a place to guess.
+*
+* The rendered table is pinned byte-for-byte into `packages/README.md` by
+* `tests/long-runs.spec.ts` (the T-WD2 pattern the command registry already uses),
+* so the published table cannot drift from this list.
+* @module
+*/
+/**
+* The inventory. Order is the rendered order; a spec pins it into the README.
+*/
+const LONG_RUNS = [
+	{
+		id: "/evolution maintain",
+		kind: "command",
+		owner: "evolution-commands",
+		lifetime: "plugin",
+		measured: "the same scan measured 949.7 s end to end on the web plane (no Electron); the desktop shell ends the REQUEST at ~305 s (four runs: 305.6/307.0/306.0/305.7 s)",
+		budget: "maintainTimeoutMs (row config, default 600000) or --timeout <ms> for one run",
+		resultHome: "<evolutionHome>/reports/maintain-<runId>.{json,md}, indexed in <evolutionHome>/runs.json",
+		note: "The ~305 s wall is a CLIENT lifetime, not a budget: the run keeps working and the result is read back with maintain status/report. Its cancellation is the run registry handle (maintain cancel <id>) or plugin dispose."
+	},
+	{
+		id: "maintenance_probe",
+		kind: "tool",
+		owner: "evolution-maintenance",
+		lifetime: "request",
+		measured: "188/220/225 ms on the deployed library (28 skills / 418 KB); ~5.5 ms per skill and linear (100 skills 0.4-0.6 s, 400 skills 1.9-2.5 s)",
+		budget: "none, deliberately: reaching the ~305 s wall would take roughly 5e4 skills",
+		resultHome: "the tool result (JSON detail), answered in-turn",
+		note: "O(2N) tree reads (enrichment + snapshot), uncached by design. Reopen the budget question when the library nears ~1e4 skills, when the io provider stops being local, or when a model leg enters a tool execute."
+	},
+	{
+		id: "skill_manage",
+		kind: "tool",
+		owner: "tool-skill-manage",
+		lifetime: "request",
+		measured: "not measured as a duration: single-file IO plus a library listing the cross-source gate already reads; the only unbounded wait is a HUMAN answer",
+		budget: "its own gate deadline (skillWriteConfirm + pendingTtlMs) — a second budget here would compete with it",
+		resultHome: "the tool result, plus the mutation audit records",
+		note: "The human wait is the reason this entry exists: it is bounded by the write gate, which the tool owns."
+	},
+	{
+		id: "memory",
+		kind: "tool",
+		owner: "tool-memory",
+		lifetime: "request",
+		measured: "single-file IO on the memory store",
+		budget: "none needed",
+		resultHome: "the tool result",
+		note: "No tree walk, no model leg, no human wait."
+	},
+	{
+		id: "curator pass",
+		kind: "pass",
+		owner: "evolution-curator",
+		lifetime: "plugin",
+		measured: "not measured end to end; the LLM nomination leg is bounded separately",
+		budget: "curatorReviewTimeoutMs (E3 parameter) for the LLM leg",
+		resultHome: "<evolutionHome>/reports/curator-<runId>.{json,md}",
+		note: "Runs from the plugin interval timer, and a failed or timed-out LLM leg is a distinguishable state in the run report (nominationsWarnings)."
+	},
+	{
+		id: "review pass",
+		kind: "pass",
+		owner: "evolution-review",
+		lifetime: "plugin",
+		measured: "not measured end to end; the subagent leg carries its own deadline",
+		budget: "reviewTimeoutMs (E2 parameter)",
+		resultHome: "the review inbox plus evolution/plan-applied",
+		note: "The write leg replays a staged plan through the registered runner; cancellation follows the plugin fiber."
+	}
+];
+/**
+* Render the inventory as the README table rows (no header).
+* @returns one markdown row per entry, in inventory order.
+*/
+function renderLongRunTable() {
+	return LONG_RUNS.map((entry) => `| \`${entry.id}\` | ${entry.kind} | ${entry.owner} | ${entry.lifetime} | ${entry.measured} | ${entry.resultHome} |`).join("\n");
+}
+//#endregion
 //#region lib/types/platform-services.js
 /**
 * Every platform service the family reaches for with `ctx.get`, and what degrades without it.
@@ -12959,4 +13417,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_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, 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, 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, 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, reportTime, resolveBasePresetPatch, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, retainEventArchives, retirementReport, reviewPrompt, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionEvidenceIndex, sessionLastEventTime, sessionReadNames, sessionReadSkillNames, sessionSeesFamilyTools, sessionTurnSignals, skillReadNameOf, skillRowCells, skillStateKey, skillsRoot, supportFileReadOf, suppressedFile, 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, 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 };

package/lib/types/index.d.ts

@@ -51,6 +51,9 @@ export * from './prompts.ts';
 export * from './quality.ts';
 export * from './redact.ts';
 export * from './review-channel.ts';
+export * from './run-registry.ts';
+export * from './reports.ts';
+export * from './long-runs.ts';
 export * from './serial.ts';
 export * from './probe.ts';
 export * from './platform-services.ts';

package/lib/types/long-runs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 0.19.0 (S4): the family's long-run inventory — one table, one owner per entry.
+ *
+ * A "long run" is work whose duration is NOT bounded by the interaction that asked
+ * for it: a maintenance scan, a curator pass, a review pass. The measured fact this
+ * table exists to record is that a CLIENT can end a request long before the work is
+ * done (measured: the desktop shell ends a request at ~305 s while the same command
+ * finishes in 949.7 s on the web plane), so the lifetime of such work must come from
+ * its OWNER — never from the request.
+ *
+ * Two fields carry the judgments, and a spec pins both:
+ *
+ *   - `lifetime`: `'plugin'` entries must name an owner and a result home (the work
+ *     outlives the request and must be readable afterwards); `'request'` entries
+ *     must say WHY their cost cannot reach the wall.
+ *   - `measured`: only measured numbers, with their basis. An unmeasured bound is
+ *     written as exactly that — this table is not a place to guess.
+ *
+ * The rendered table is pinned byte-for-byte into `packages/README.md` by
+ * `tests/long-runs.spec.ts` (the T-WD2 pattern the command registry already uses),
+ * so the published table cannot drift from this list.
+ * @module
+ */
+/** What kind of work an entry describes. */
+export type LongRunKind = 'command' | 'tool' | 'pass';
+/** Whose lifetime the work borrows. `'plugin'` = it must outlive the request. */
+export type LongRunLifetime = 'request' | 'plugin';
+/** One entry of the long-run inventory. */
+export interface LongRunEntry {
+    /** Command/entry id as a user sees it. */
+    id: string;
+    kind: LongRunKind;
+    /** The package that owns the work (its lifecycle, its budget, its result). */
+    owner: string;
+    lifetime: LongRunLifetime;
+    /** The measured cost, with its basis. Never a guess. */
+    measured: string;
+    /** Where the deadline/budget comes from, or why there is none. */
+    budget: string;
+    /** Where a result is readable after the work settles. */
+    resultHome: string;
+    note: string;
+}
+/**
+ * The inventory. Order is the rendered order; a spec pins it into the README.
+ */
+export declare const LONG_RUNS: readonly LongRunEntry[];
+/**
+ * Render the inventory as the README table rows (no header).
+ * @returns one markdown row per entry, in inventory order.
+ */
+export declare function renderLongRunTable(): string;
+//# sourceMappingURL=long-runs.d.ts.map

package/lib/types/reports.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 0.19.0 (S2): the family's ONE report-retention sweep.
+ *
+ * Reports accumulate by design (every run writes one), so each kind needs a
+ * window or the reports home becomes an unbounded directory. The logic lived
+ * inside the curator only; the maintenance run reports added in 0.19.0 needed
+ * the same thing, and a second copy of "list, order, delete beyond the window"
+ * is exactly the kind of near-duplicate this family treats as a defect.
+ *
+ * Three behaviours are the curator's, kept verbatim because they are the reason
+ * the sweep is safe to run at all:
+ *
+ *   - An UNLISTABLE directory is not "no reports" — nothing is deleted and the
+ *     caller is told (the same three-state rule the probe files use).
+ *   - A report with no usable timestamp is KEPT (never delete what cannot be
+ *     ordered) and the fact is said out loud once.
+ *   - The order is TOTAL: declared time, then mtime, then name. A tie falling
+ *     through to readdir order evicted a different set per platform (CI-caught).
+ * @module
+ */
+import type { EvolutionIoLike } from './io.ts';
+/**
+ * The lock target a reports sweep holds for one home.
+ *
+ * `transactIo` takes the IO write lock on THIS path (minting `<path>.lock` with
+ * the io protocol's `pid:token` body) and holds it for the whole task; nothing
+ * ever writes the target, because the sweep's exclusion is the point. It lives
+ * inside `<home>/reports` next to the directory it protects (the sweeps' own name
+ * filters ignore it, and the lock file is removed on release).
+ *
+ * Moved here from evolution-curator in 0.19.0 (S2): the maintenance reports'
+ * sweep needs the SAME exclusion, and a second lock would protect nothing.
+ * @returns the lock target path.
+ */
+export declare function reportsSweepLockTarget(): string;
+/** One retention window: files whose name starts with `prefix`, newest `keep` survive. */
+export interface ReportBucket {
+    prefix: string;
+    keep: number;
+}
+/** Inputs for {@link sweepReports}. */
+export interface SweepReportsOptions {
+    io: EvolutionIoLike;
+    /** Reports directory (`<evolutionHome()>/reports`). */
+    dir: string;
+    /** Buckets. The FIRST prefix that matches classifies a file — pass specific ones first. */
+    buckets: readonly ReportBucket[];
+    /** Warn channel for an unlistable directory or an unorderable report. */
+    warn?: ((message: string) => void) | undefined;
+    /** Prefix of the warning messages, naming the owning package. */
+    owner: string;
+}
+/**
+ * Delete the reports beyond each bucket's window, each with its `.md` digest.
+ *
+ * Best-effort by construction: pruning never fails the run that wrote a report.
+ * @param options - io seam, directory, windows, warn channel and owner name.
+ * @returns nothing; deletions and skips are reported through `warn`.
+ */
+export declare function sweepReports(options: SweepReportsOptions): Promise<void>;
+//# sourceMappingURL=reports.d.ts.map

package/lib/types/run-registry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 0.19.0 (S2): the family's run-lifecycle owner.
+ *
+ * A "run" is work that can outlive one interaction — today the maintenance scan.
+ * Before this module the only record of such work was the requesting invocation:
+ * `lastMaintainAt` / `lastMaintainRunId` / `maintainInFlightSince` were
+ * module-scope globals in evolution-commands, and the plan text existed ONLY in
+ * the command's return string. An interaction that ended (measured: the desktop
+ * shell hangs up at ~305 s) therefore erased every trace of a still-running scan.
+ *
+ * This registry is the single owner of (a) what is in flight, (b) how a run
+ * ended, and (c) WHERE its result lives (`resultRef` is a path, never the result
+ * itself — the report file is the one result home).
+ *
+ * Two disciplines are structural, not stylistic:
+ *
+ *   - **No timer.** A run whose process died is converged at READ time: the index
+ *     file can only carry `running` records written by a PREVIOUS process life,
+ *     because the live ones are in memory. `load()` therefore rewrites every
+ *     `running` record as `failed(orphan)` once — the same "converge when read"
+ *     posture the approval window uses for its TTL.
+ *   - **One terminal state.** `settle()` refuses to overwrite a record that is
+ *     already terminal, so a cancel that raced a failure cannot flip the answer
+ *     the operator already read.
+ *
+ * The store is PER INSTANCE (a factory, not module scope): one registry per
+ * mounted row, disposed with its fiber. There is no module-scope mutable state
+ * here to register under N12.
+ * @module
+ */
+import type { EvolutionIoLike } from './io.ts';
+/** The kinds of long-running work the registry tracks. Extend as rows gain runs. */
+export type RunKind = 'maintain';
+/** The four terminal-or-live states of a run. */
+export type RunState = 'running' | 'succeeded' | 'failed' | 'cancelled';
+/** One tracked run. `resultRef` is a path to the run's report, never its content. */
+export interface RunRecord {
+    id: string;
+    kind: RunKind;
+    state: RunState;
+    startedAt: number;
+    /** The process that owns a RUNNING record. Required to tell an in-flight run of
+     * another plane (both planes share one DSH_HOME) from the orphan of a dead one;
+     * absent means the owner cannot be named, which is treated as gone. */
+    pid?: number | undefined;
+    endedAt?: number | undefined;
+    /** Absolute path of the run's report, written by the run owner at settle. */
+    resultRef?: string | undefined;
+    /** Why the run did not succeed (an abort reason, a validation failure). */
+    failure?: string | undefined;
+}
+/** What a started run gets: its id and the signal its work must honour. */
+export interface RunHandle {
+    readonly id: string;
+    readonly kind: RunKind;
+    readonly signal: AbortSignal;
+    /** When the run was registered — the same instant the record carries. */
+    readonly startedAt: number;
+}
+/** How a run ended, as reported by its owner. */
+export interface RunOutcome {
+    state: 'succeeded' | 'failed' | 'cancelled';
+    resultRef?: string | undefined;
+    failure?: string | undefined;
+}
+/** The registry surface the commands row drives. */
+export interface RunRegistry {
+    /** Converge the persisted index once at mount; see the module doc. */
+    load(): Promise<{
+        ok: boolean;
+        note?: string;
+    }>;
+    /** Register a new run, arm its cancellation, and return its handle. */
+    begin(kind: RunKind): RunHandle;
+    /** Record a run's terminal state (first writer wins). */
+    settle(id: string, outcome: RunOutcome): Promise<void>;
+    /** The live run, when there is one (one kind today — see the implementation note). */
+    inFlight(): RunRecord | undefined;
+    /** When the newest terminal run ended (`undefined` when none). */
+    lastSettledAt(): number | undefined;
+    /** Every tracked run, newest first. */
+    runs(): readonly RunRecord[];
+    /** One run by id, converged view included. */
+    find(id: string): RunRecord | undefined;
+    /** Ask a running run to stop; it settles as `cancelled`. @returns whether it was running. */
+    cancel(id: string): boolean;
+    /** Ask every running run to stop (fiber dispose). @returns how many were running. */
+    cancelAll(): number;
+}
+/** Options for {@link newRunRegistry}. */
+export interface RunRegistryOptions {
+    io: EvolutionIoLike;
+    /** Evolution home (`evolutionHome()`); the index lives at `<home>/runs.json`. */
+    home: string;
+    /** Warn channel for a failed index write (the run itself is unaffected). */
+    warn?: (message: string) => void;
+    /** Clock seam for tests. */
+    now?: () => number;
+    /** Retained records (N3-clamped). */
+    maxRecords?: number;
+}
+/** Current index schema. Bump only for a structural change. */
+export declare const RUNS_SCHEMA_VERSION = 1;
+/** Retained run records, newest first. */
+export declare const DEFAULT_RUN_RECORDS = 50;
+/** Index path for a home. */
+export declare function runsFile(home: string): string;
+/**
+ * Create the run registry for one mounted row.
+ * @param options - io seam, evolution home, warn channel, clock and record cap.
+ * @returns the registry; call {@link RunRegistry.load} once before answering reads.
+ */
+export declare function newRunRegistry(options: RunRegistryOptions): RunRegistry;
+//# sourceMappingURL=run-registry.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.18.1",
+  "version": "0.19.0",
   "publishConfig": {
     "access": "public"
   },

package/persisted-write-inventory.json

@@ -62,6 +62,24 @@
     "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>/**",