@lmzhen/dsh-evolution-commands 0.3.77 → 0.3.79

package/README.md

@@ -29,5 +29,11 @@ Independent of request-prefix construction. This package does not alter the asse
 
 
 - No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.
+- **① variant form: the `/evolution …` command face is visible in every session**
+  (accepted, not fixed — 0.3.78). Commands are registered in scope layers, and the
+  family registers once on the host plane, so a session on a platform original
+  preset still lists the management-only subcommands even though no automatic
+  family behaviour reaches it. The difference and its reasoning are single-sourced
+  in `INSTALL.md` ("Known difference").
 
 **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).

package/lib/index.js

@@ -102,6 +102,165 @@ function memoryInterpolationIssues(home) {
 	}
 	return issues;
 }
+/** G3-② (B2): the family delta container. An optionalDependency of this
+* package, so resolution may legitimately fail; every failure degrades to
+* "unknown" — the doctor never throws.
+* Platform anchor: agentPresets.read(id) — preset/agent-presets/src/index.ts:501. */
+const AGENT_PRESET_PACKAGE = "@lmzhen/dsh-evolution-agent-preset";
+/** Resolve one asset the package declares in its exports map.
+* @param asset - bases.json or agent.cordis.yml.
+* @returns the file path, or null when the package is not installed. */
+function resolveAgentPresetAsset(asset) {
+	try {
+		return fileURLToPath(import.meta.resolve(`${AGENT_PRESET_PACKAGE}/${asset}`));
+	} catch {
+		return null;
+	}
+}
+/** The base rows of bases.json: the comparison iterates the same table the
+* installer reads, so doctor cannot check a different set of variants.
+* @param path - resolved bases.json.
+* @returns the rows, or null when the table is unreadable or malformed. */
+function readAgentPresetBases$1(path) {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		if (!Array.isArray(parsed.bases)) return null;
+		const rows = [];
+		for (const raw of parsed.bases) {
+			const entry = raw;
+			if (typeof entry.name !== "string" || typeof entry.id !== "string") return null;
+			rows.push({
+				name: entry.name,
+				id: entry.id
+			});
+		}
+		return rows.length > 0 ? rows : null;
+	} catch {
+		return null;
+	}
+}
+/** Preset directories already on disk, used to keep an installed variant
+* VISIBLE when the base table itself could not be read.
+* @param root - the .agent-presets directory.
+* @returns the directory names; empty when nothing is installed. */
+function installedPresetIds(root) {
+	const ids = [];
+	let entries;
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch {
+		return ids;
+	}
+	for (const entry of entries) if (entry.isDirectory()) ids.push(entry.name);
+	return ids;
+}
+/**
+* G3-② (B2): recompute what a fresh generation would write for every
+* installed variant and compare it byte-for-byte with the file on disk.
+*
+* The recomputation goes through composePresetComposition — the SAME rule
+* /evolution preset install and install-layered.mjs apply (collision guard +
+* row-overrides.json), so doctor cannot disagree with the installer about what
+* "fresh" means. Read-only by contract: the snapshot is never rewritten.
+* @param home - resolved DSH_HOME.
+* @param registry - the platform agent-preset registry, undefined when unmounted.
+* @returns one row per base in the family bases.json.
+*/
+async function probePresetFreshness(home, registry) {
+	const presetsRoot = join(home, ".agent-presets");
+	const basesPath = resolveAgentPresetAsset("bases.json");
+	const deltaPath = resolveAgentPresetAsset("agent.cordis.yml");
+	const bases = basesPath === null ? null : readAgentPresetBases$1(basesPath);
+	let delta = null;
+	let deltaFailure = `${AGENT_PRESET_PACKAGE}/agent.cordis.yml could not be resolved — is the family agent-preset package installed?`;
+	if (deltaPath !== null) try {
+		delta = readFileSync(deltaPath, "utf8");
+	} catch (error) {
+		deltaFailure = `${deltaPath} could not be read (${error instanceof Error ? error.message : String(error)})`;
+	}
+	if (bases === null) {
+		const tablePath = basesPath ?? `${AGENT_PRESET_PACKAGE}/bases.json`;
+		return installedPresetIds(presetsRoot).map((id) => ({
+			base: id,
+			destination: join(presetsRoot, id),
+			status: "unknown",
+			detail: `the family base table could not be read (${tablePath}) — a fresh generation cannot be recomputed`
+		}));
+	}
+	const rows = [];
+	for (const base of bases) {
+		const destination = join(presetsRoot, base.id);
+		const compositionPath = join(destination, "agent.cordis.yml");
+		if (!existsSync(compositionPath)) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "absent"
+			});
+			continue;
+		}
+		if (registry === void 0) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: "the platform agent-preset registry is not mounted, so the runtime composition cannot be read"
+			});
+			continue;
+		}
+		if (delta === null) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: deltaFailure
+			});
+			continue;
+		}
+		let platform;
+		try {
+			platform = await registry.read(base.name);
+		} catch (error) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: `the runtime composition for base "${base.name}" could not be read (${error instanceof Error ? error.message : String(error)})`
+			});
+			continue;
+		}
+		let fresh;
+		try {
+			fresh = composePresetComposition(platform, delta);
+		} catch (error) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: `a fresh generation refused to compose (${error instanceof Error ? error.message : String(error)})`
+			});
+			continue;
+		}
+		let onDisk;
+		try {
+			onDisk = readFileSync(compositionPath, "utf8");
+		} catch (error) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: `${compositionPath} could not be read (${error instanceof Error ? error.message : String(error)})`
+			});
+			continue;
+		}
+		rows.push({
+			base: base.name,
+			destination,
+			status: fresh === onDisk ? "fresh" : "differs"
+		});
+	}
+	return rows;
+}
 /**
 * Diagnose the deployment. `ctx` supplies service presence (a bare stub with
 * only `get` is enough); `home` defaults to the evolution root so tests can
@@ -115,6 +274,7 @@ async function diagnose(ctx, options = {}) {
 		conflicts.push(scope === "profiles-dir" ? `the home profiles directory could not be enumerated (${detail}) — bundle-based install-form and conflict checks are DEGRADED and may miss installed bundles` : `a profile manifest could not be read or parsed (${detail}) — this profile's bundle rows are UNKNOWN, so the install-form and conflict checks are DEGRADED and may miss installed bundles`);
 	});
 	const has = (name) => ctx.get(name) !== void 0;
+	const presetFreshness = await probePresetFreshness(home, ctx.get("agentPresets"));
 	const full = bundles.some((name) => tailOf(name) === "dsh-evolution-all");
 	const host = bundles.some((name) => tailOf(name) === "dsh-evolution-host");
 	const preset = bundles.some((name) => tailOf(name) === "dsh-evolution-preset");
@@ -161,6 +321,10 @@ async function diagnose(ctx, options = {}) {
 	const memoryIssues = memoryInterpolationIssues(home);
 	if (memoryIssues.length > 0) actions.push("Rewrite the memory entries listed above (or run a build with the render-time neutralization) — they broke prompt assembly on older builds.");
 	if ((executingCount ?? 0) > 0) actions.push(`${executingCount} staged write(s) are EXECUTING (an approve crashed mid-run — or one is still in flight). Inspect with /evolution pending: if you started the approve, verify the landed write and do not reject it; only reject after verifying no write is intended.`);
+	for (const row of presetFreshness) {
+		if (row.status !== "differs") continue;
+		actions.push(`Preset variant ${row.destination} DIFFERS from a fresh generation — it is an install-time snapshot; re-run the installer (/evolution preset install) to regenerate`);
+	}
 	return {
 		installForm,
 		deploymentForm,
@@ -171,6 +335,7 @@ async function diagnose(ctx, options = {}) {
 		services,
 		pendingCount,
 		executingCount,
+		presetFreshness,
 		actions
 	};
 }
@@ -182,6 +347,11 @@ function renderDoctorText(report) {
 		`pending: ${report.pendingCount === null ? "unknown" : report.pendingCount}`,
 		`executing: ${report.executingCount === null ? "unknown" : report.executingCount}`
 	];
+	for (const row of report.presetFreshness) {
+		if (row.status === "absent") continue;
+		const verdict = row.status === "fresh" ? "fresh — a fresh generation matches this file byte-for-byte" : row.status === "differs" ? "DIFFERS from a fresh generation — it is an install-time snapshot; re-run the installer (/evolution preset install) to regenerate" : `unknown — a fresh generation could not be recomputed (${row.detail ?? "reason not recorded"})`;
+		lines.push(`preset:   ${row.destination}  ${verdict}`);
+	}
 	if (report.conflicts.length > 0) lines.push("conflicts:", ...report.conflicts.map((line) => `  ! ${line}`));
 	if (report.envIssues.length > 0) lines.push("env:", ...report.envIssues.map((line) => `  ! ${line}`));
 	if (report.memoryIssues.length > 0) lines.push("memory:", ...report.memoryIssues.map((line) => `  ! ${line}`));
@@ -583,12 +753,17 @@ function apply(ctx, rawConfig = {}) {
 							if (entry === void 0) return err(`Unknown agent-preset base "${name}" — ${join(source, "bases.json")} lists ${table.entries.map((candidate) => candidate.name).join(", ")}`);
 							selected.push(entry);
 						}
+						const rawBases = JSON.parse(readFileSync(join(source, "bases.json"), "utf8"));
 						const deltaPath = join(source, "agent.cordis.yml");
 						if (!existsSync(deltaPath)) return err(`Preset file missing from ${source} — is the dsh-evolution-agent-preset package installed?`);
 						const registry = ctx.get("agentPresets");
 						if (!registry) return err("Agent preset registry not mounted — cannot compose the Evolution preset against the runtime standard.");
 						const written = [];
 						for (const base of selected) {
+							const ability = rawBases.bases?.find((candidate) => candidate.name === base.name);
+							if (typeof ability?.unsupported === "string") return err(`Base "${base.name}" is registered as UNSUPPORTED: ${ability.unsupported}`);
+							const requiredService = ability?.requires?.service;
+							if (typeof requiredService === "string" && ctx.get(requiredService) === void 0) return err(`Base "${base.name}" requires the "${requiredService}" service, which this deployment does not provide — the generated preset would refuse to mount.`);
 							const target = join(evolutionRoot(), ".agent-presets", base.id);
 							const presetPath = join(source, base.metadata);
 							if (!existsSync(presetPath)) return err(`Preset file missing from ${source} — is the dsh-evolution-agent-preset package installed?`);
@@ -740,8 +915,9 @@ const defaultFs = {
 	mtime: (path) => {
 		try {
 			return statSync(path).mtimeMs;
-		} catch {
-			return null;
+		} catch (error) {
+			if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+			throw error;
 		}
 	}
 };

package/lib/types/doctor.d.ts

@@ -1,3 +1,15 @@
+/** G3-② (B2): one delivered preset variant compared against a fresh generation.
+ * "absent" is the user simply not using that base (never an action); "unknown"
+ * is a comparison that could not run, kept distinct from a verified "fresh". */
+export interface PresetFreshnessRow {
+    /** Agent-preset base name (the id the platform registry read() takes). */
+    base: string;
+    /** Install destination <home>/.agent-presets/<base.id> that was compared. */
+    destination: string;
+    status: 'fresh' | 'differs' | 'absent' | 'unknown';
+    /** Why the comparison could not run — set on unknown rows only. */
+    detail?: string;
+}
 export interface DoctorReport {
     /** OPT-23 (2026-09): `preset-only` — the delivered Evolution preset
      * artifact exists but NO profile carries an evolution bundle (e.g. the
@@ -38,6 +50,12 @@ export interface DoctorReport {
     /** v23 (AP-2): claimed-but-crashed records — the only state that needs an
      * operator action (reject) to clear; surfaced separately from pending. */
     executingCount: number | null;
+    /** G3-② (B2): how the delivered preset variants compare with what a fresh
+     * generation would write against THIS runtime platform. A variant embeds the
+     * platform composition of its install day, so a platform change or a family
+     * upgrade leaves a file describing a platform that no longer exists. Read-only:
+     * a stale snapshot is reported, never repaired. */
+    presetFreshness: PresetFreshnessRow[];
     actions: string[];
 }
 /** Profile bundle rows for evolution-family packages across all profiles.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-commands",
   "description": "Human commands for the evolution family (/evolution pending|curator|maintain|doctor) (community build)",
-  "version": "0.3.77",
+  "version": "0.3.79",
   "publishConfig": {
     "access": "public"
   },
@@ -27,12 +27,12 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.3.77",
-    "@lmzhen/dsh-evolution-core": "^0.3.77",
-    "@lmzhen/dsh-evolution-maintenance": "^0.3.77"
+    "@lmzhen/dsh-evolution-approval": "^0.3.79",
+    "@lmzhen/dsh-evolution-core": "^0.3.79",
+    "@lmzhen/dsh-evolution-maintenance": "^0.3.79"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.3.77"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.3.79"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",