@lmzhen/dsh-evolution-commands 0.5.0 → 0.6.0

package/lib/index.js

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
 import { effectiveSessionPolicy } from "@lmzhen/dsh-evolution-approval";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { DEFAULT_SKILL_LIMITS, MAX_TIMER_DELAY_MS, appendEvolutionEvent, assertSkillsRootAliasRetired, buildLearnPrompt, clampedNumber, composePresetComposition, eventsFile, evolutionRoot, isMissingPath, newSkillLibrary, policyStageLimits, resolveRootConfig, scopedProbeReport } from "@lmzhen/dsh-evolution-core";
+import { DEFAULT_SKILL_LIMITS, MAX_TIMER_DELAY_MS, PARAM_EXPOSURE, PARAM_NAMESPACES, appendEvolutionEvent, assertSkillsRootAliasRetired, buildLearnPrompt, canonicalWriteId, clampedNumber, composePresetComposition, eventsFile, evolutionRoot, isDeprecatedParamId, isMissingPath, newSkillLibrary, policyStageLimits, resolveParamId, resolveRootConfig, scopedProbeReport } from "@lmzhen/dsh-evolution-core";
 import { buildEnrichment, buildMaintainFacts, runMaintain, snapshotFromLibrary } from "@lmzhen/dsh-evolution-maintenance";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -30,6 +30,52 @@ const EVOLUTION_BUNDLE_TAILS = new Set([
 	"dsh-evolution-host",
 	"dsh-evolution-preset"
 ]);
+/**
+* S4.3: the parameter-surface divergences a RUNNING deployment can show and the
+* build-time guards cannot. Three classes, each with its own move:
+*  - a user override (the effective value is no longer the deployment's),
+*  - a deprecated alias still written in a user section (writes refuse it),
+*  - a declared user-writable parameter whose owner publishes no user layer in
+*    this composition (the registry promises a face this deployment never mounts).
+* An unreadable settings surface is reported AS SUCH: silence would read as "no
+* divergences", which is the one claim this section exists to check.
+* @param ctx - the plugin context; the settings service is read optionally.
+* @returns one readable line per divergence, empty when there is nothing to compare.
+*/
+function paramDivergences(ctx) {
+	const provider = ctx.get("settings");
+	if (provider?.describe === void 0) return [];
+	let descriptors;
+	try {
+		descriptors = provider.describe({ redactSecrets: false });
+	} catch (error) {
+		return [`settings surface unreadable (${error instanceof Error ? error.message : String(error)}) — parameter divergences were NOT checked`];
+	}
+	const issues = [];
+	const registered = new Map(descriptors.map((descriptor) => [descriptor.ns, descriptor.user ?? {}]));
+	for (const [namespace, user] of registered) {
+		const keys = Object.keys(user);
+		if (keys.length > 0) {
+			const shown = keys.slice(0, 5).map((key) => `${key}=${JSON.stringify(user[key])}`);
+			const more = keys.length > shown.length ? ` and ${keys.length - shown.length} more` : "";
+			issues.push(`user override: ${namespace} sets ${keys.length} parameter(s) — ${shown.join(", ")}${more}`);
+		}
+		for (const key of keys) {
+			if (!isDeprecatedParamId(key)) continue;
+			issues.push(`deprecated name: ${namespace} still writes "${key}" — write "${resolveParamId(key)}" instead (writes refuse the alias; it is removed in 0.7.0)`);
+		}
+	}
+	const unreachable = PARAM_EXPOSURE.filter((entry) => entry.tier === "E3").filter((entry) => {
+		const namespace = PARAM_NAMESPACES[entry.owner];
+		return namespace === void 0 || !registered.has(namespace);
+	}).map((entry) => entry.id);
+	if (unreachable.length > 0) {
+		const shown = unreachable.slice(0, 6).join(", ");
+		const more = unreachable.length > 6 ? ` (+${unreachable.length - 6} more)` : "";
+		issues.push(`declared user-writable but unreachable here: ${shown}${more} — the owning package publishes no user layer in this composition`);
+	}
+	return issues;
+}
 /** Profile bundle rows for evolution-family packages across all profiles.
 *
 * `onReadError` reports a profile whose manifest could not be READ or PARSED.
@@ -370,8 +416,10 @@ async function diagnose(ctx, options = {}) {
 	if (pendingCount === null && services.approval) actions.push("Approval service is mounted but pending listing failed — check the evolution state service.");
 	const memoryIssues = memoryInterpolationIssues(home);
 	const budgetIssues = memoryBudgetIssues(ctx);
+	const paramIssues = paramDivergences(ctx);
 	const queryIssues = await sessionQueryIssues(ctx);
 	if (queryIssues.length > 0) actions.push("Session search is degraded: isolate the session named above (or wait for the platform fix described in the family maintenance notes) before retrying the same query");
+	if (paramIssues.length > 0) actions.push("Review the parameter divergences above: /evolution params shows every row with its source, /evolution policy set writes a user value, and a declared-but-unreachable row needs its owning plugin row mounted in this profile.");
 	if (budgetIssues.length > 0) actions.push("Align the memory budget: leave memory-files memoryCharLimit/userCharLimit UNSET so the store follows evolution-policy, or set both surfaces to the same value (the review plans against the policy value while the store enforces its own)");
 	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 (scopedProbe.rows !== null && scopedProbe.rows.length > 0 && scopedProbe.verdict === "never-hit") actions.push("The session-scoped rows are mounted but the family-tool probe has never matched in this process — review injection and skill-usage telemetry skipped every session observed. HOST-ONLY install: the model rows (tool-memory / tool-skill-manage) sit in evolution-host devDependencies, so no session carries them; install a bundle that mounts them (see INSTALL.md). VARIANT install: only a session on the Evolution preset matches, so open one — a session on a platform original preset is the intended skip, not a fault. Either way, check that no profile overlay disables those two rows.");
@@ -388,6 +436,7 @@ async function diagnose(ctx, options = {}) {
 		envIssues: env,
 		memoryIssues,
 		budgetIssues,
+		paramIssues,
 		queryIssues,
 		services,
 		pendingCount,
@@ -519,11 +568,143 @@ function renderDoctorText(report) {
 	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}`));
 	if (report.budgetIssues.length > 0) lines.push("memory budget:", ...report.budgetIssues.map((line) => `  ! ${line}`));
+	if (report.paramIssues.length > 0) lines.push("parameters:", ...report.paramIssues.map((line) => `  ! ${line}`));
 	if (report.queryIssues.length > 0) lines.push("session search:", ...report.queryIssues.map((line) => `  ! ${line}`));
 	if (report.actions.length > 0) lines.push("next steps:", ...report.actions.map((line) => `  → ${line}`));
 	return lines.join("\n");
 }
 //#endregion
+//#region lib/types/params.js
+/**
+* `/evolution params` view (G4/S4.1): the registry joined with the settings
+* surface, so one text answers "which parameters exist, who may write them, and
+* did I already override this one".
+*
+* The join key is the OWNER PACKAGE: core's `PARAM_NAMESPACES` maps a package to
+* the one namespace it registers, and `settings.describe()` reports that
+* namespace's raw user section (a key's PRESENCE is the override) plus the
+* resolved value. Everything here is pure; the command handler supplies the data.
+* @module @lmzhen/dsh-evolution-commands/params
+*/
+/**
+* Join the registry with the settings surface.
+*
+* `user` means the raw user section carries this key; `deployment` means the
+* owner's namespace is registered but the key is unset (so the row/policy value
+* applies); `unregistered` means the owner package publishes no namespace at all
+* (or is not mounted), which is the honest answer for a deployment-only face.
+* The distinction matters: 'no user section' must never read as 'not overridden'
+* for a namespace that failed to register.
+* @param sections - namespace to surface view, from `settings.describe()`.
+* @param entries - registry entries (defaults to the family registry).
+* @returns one row per registry entry, in registry order.
+*/
+function paramSurfaceRows(sections, entries = PARAM_EXPOSURE) {
+	return entries.map((entry) => {
+		const base = {
+			id: entry.id,
+			group: entry.group,
+			tier: entry.tier,
+			applies: entry.applies,
+			owner: entry.owner
+		};
+		const namespace = PARAM_NAMESPACES[entry.owner];
+		const section = namespace === void 0 ? void 0 : sections.get(namespace);
+		if (section === void 0) return {
+			...base,
+			source: "unregistered",
+			value: void 0
+		};
+		const user = section.user;
+		if (user !== void 0 && Object.hasOwn(user, entry.id)) return {
+			...base,
+			source: "user",
+			value: user[entry.id]
+		};
+		return {
+			...base,
+			source: "deployment",
+			value: section.value?.[entry.id]
+		};
+	});
+}
+/**
+* The groups the registry actually carries, in registry order — the list an
+* unknown `--group` value is answered with.
+* @param entries - registry entries (defaults to the family registry).
+* @returns distinct group names.
+*/
+function paramGroups(entries = PARAM_EXPOSURE) {
+	return [...new Set(entries.map((entry) => entry.group))];
+}
+/** One cell: `—` when no face reports a value, JSON for arrays/objects. */
+function renderValue(value) {
+	if (value === void 0) return "—";
+	if (typeof value === "string") return value;
+	return JSON.stringify(value);
+}
+/**
+* Render the rows as fixed-width text (one parameter per line, never truncated).
+* @param rows - rows from {@link paramSurfaceRows}.
+* @param options - whether the settings service answered at all.
+* @returns the command text.
+*/
+function renderParamRows(rows, options) {
+	const header = "PARAMETER".padEnd(36) + "GROUP".padEnd(12) + "TIER".padEnd(5) + "APPLIES".padEnd(9) + "SOURCE".padEnd(14) + "VALUE";
+	const body = rows.map((row) => row.id.padEnd(36) + row.group.padEnd(12) + row.tier.padEnd(5) + row.applies.padEnd(9) + row.source.padEnd(14) + renderValue(row.value));
+	const tiers = [
+		"E0",
+		"E1",
+		"E2",
+		"E3",
+		"E4"
+	].map((tier) => `${tier} ${rows.filter((row) => row.tier === tier).length}`).join(" / ");
+	const userRows = rows.filter((row) => row.source === "user").length;
+	const overrides = options.providerMounted ? `${userRows} overridden by the user.` : "overrides UNKNOWN (no settings provider).";
+	const note = options.providerMounted ? "SOURCE: user = you set it in settings; deployment = the row/policy value applies; unregistered = the owner publishes no user layer." : "settings provider not mounted — the user layer is unavailable, so every row shows its deployment face (this is NOT \"no overrides\").";
+	return [
+		header,
+		...body,
+		"",
+		`${rows.length} parameter(s): ${tiers}; ${overrides}`,
+		note
+	].join("\n");
+}
+/**
+* Parse one command-line value into what the settings document stores: JSON
+* when it parses (numbers, booleans, quoted strings, arrays, objects), the raw
+* text otherwise, so a bare word like `enforce` stays a word.
+* @param raw - the text typed after the parameter id.
+* @returns the value to write.
+*/
+function parseParamValue(raw) {
+	const text = raw.trim();
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+/**
+* Render the write result: the value move, then where it landed and when it
+* takes effect (the two things a caller cannot infer from the command line).
+* @param write - the accepted write.
+* @returns the command text.
+*/
+function renderPolicySet(write) {
+	const timing = write.applies === "live" ? "takes effect at the next use (live)" : "takes effect after a host restart (restart)";
+	const origin = write.wasOverridden ? "replacing your earlier override" : "now a user override (the deployment value stays underneath)";
+	return [`${write.id}: ${renderValue(write.before)} → ${renderValue(write.after)}`, `namespace ${write.namespace}; applies ${write.applies} — ${timing}; ${origin}`].join("\n");
+}
+/**
+* Render the rows as JSON for scripts (same fields, no formatting).
+* @param rows - rows from {@link paramSurfaceRows}.
+* @returns a JSON document with a `params` array.
+*/
+function renderParamJson(rows) {
+	return JSON.stringify({ params: rows }, null, 2);
+}
+//#endregion
 //#region lib/types/registry.js
 const COMMAND_ENTRIES = [
 	{
@@ -582,6 +763,14 @@ const COMMAND_ENTRIES = [
 		usage: "maintain [--timeout=<ms> | --facts]",
 		summary: "run a maintenance scan (--facts: 0-token preview)"
 	},
+	{
+		usage: "policy set <id> <value> [--expect <revision>]",
+		summary: "write one user-writable parameter through the settings service (E3 only; E1/E2 stay in cordis.yml)"
+	},
+	{
+		usage: "params [--group <name>] [--json]",
+		summary: "list every registered parameter: group, tier, timing, source and value (--json feeds scripts)"
+	},
 	{
 		usage: "preset install [--base <name>[,<name>...]]",
 		summary: "generate one Evolution agent preset per named base into the user root (bases from the agent package's bases.json)"
@@ -1062,6 +1251,75 @@ function apply(ctx, rawConfig = {}) {
 					if (!replay) return err("E-303: replay service not mounted. Next: mount the evolution-replay row (evolution-host/evolution-all) and run /evolution doctor.");
 					return ok(replay.compare().report);
 				}
+				const paramsMatch = /^params(?: --group ([a-z-]+))?(?: --json)?$/.exec(input);
+				if (paramsMatch) {
+					const provider = ctx.get("settings");
+					const sections = /* @__PURE__ */ new Map();
+					if (provider?.describe !== void 0) try {
+						for (const descriptor of provider.describe({ redactSecrets: false })) {
+							const section = {};
+							if (descriptor.user !== void 0) section.user = descriptor.user;
+							const resolved = descriptor.value;
+							if (typeof resolved === "object" && resolved !== null) section.value = resolved;
+							sections.set(descriptor.ns, section);
+						}
+					} catch (error) {
+						return err(`E-307: the settings service could not report its sections (${error instanceof Error ? error.message : String(error)}). /evolution params needs the user layer to tell an override from a deployment value; run /evolution doctor to see which services are mounted.`);
+					}
+					const rows = paramSurfaceRows(sections, PARAM_EXPOSURE);
+					const group = paramsMatch[1];
+					const selected = group === void 0 ? rows : rows.filter((row) => row.group === group);
+					if (group !== void 0 && selected.length === 0) return err(`E-308: unknown parameter group "${group}" — known groups: ${paramGroups(PARAM_EXPOSURE).join(", ")}.`);
+					if (input.endsWith("--json")) return ok(renderParamJson(selected));
+					return ok(renderParamRows(selected, { providerMounted: provider !== void 0 }));
+				}
+				const policySetMatch = /^policy set ([A-Za-z][A-Za-z0-9.-]*) (.+?)(?: --expect (\d+))?$/.exec(input);
+				if (policySetMatch) {
+					const provider = ctx.get("settings");
+					if (provider?.update === void 0 || provider.describe === void 0) return err("E-311: no settings service is mounted, so there is no user layer to write. Mount the settings row (packages/settings/settings-file) and retry; this command never edits cordis.yml — a deployment value belongs to the deployment. /evolution doctor lists the mounted services.");
+					const rawId = policySetMatch[1] ?? "";
+					const rawValue = policySetMatch[2] ?? "";
+					let id;
+					try {
+						id = canonicalWriteId(rawId);
+					} catch (error) {
+						return err(`E-312: ${error instanceof Error ? error.message : String(error)} — /evolution params lists the canonical ids.`);
+					}
+					const entry = PARAM_EXPOSURE.find((candidate) => candidate.id === id);
+					if (entry === void 0) return err(`E-313: unknown parameter "${id}" — /evolution params lists every registered id with its tier and user layer.`);
+					if (entry.tier !== "E3") return err(`E-314: "${id}" is a deployment parameter (tier ${entry.tier}, owner ${entry.owner}) — it is written in cordis.yml on its plugin or policy row, not from a session. /evolution params shows who may write each row.`);
+					const namespace = PARAM_NAMESPACES[entry.owner];
+					if (namespace === void 0) return err(`E-315: "${id}" has no user layer — owner ${entry.owner} publishes no settings namespace, so the value stays with the deployment.`);
+					let descriptor;
+					try {
+						descriptor = provider.describe({ redactSecrets: false }).find((candidate) => candidate.ns === namespace);
+					} catch (error) {
+						return err(`E-307: the settings service could not report its sections (${error instanceof Error ? error.message : String(error)}). /evolution policy set needs the current revision to write safely; run /evolution doctor to see which services are mounted.`);
+					}
+					if (descriptor === void 0) return err(`E-316: namespace "${namespace}" is not registered — owner ${entry.owner} is not mounted in this composition, so its parameters cannot be written from here. /evolution params marks those rows 'unregistered'.`);
+					const current = descriptor.value;
+					const resolved = typeof current === "object" && current !== null ? current : void 0;
+					const expectedRaw = policySetMatch[3];
+					const expected = expectedRaw === void 0 ? descriptor.revision : Number(expectedRaw);
+					if (expectedRaw !== void 0 && descriptor.revision !== void 0 && Number(expectedRaw) !== descriptor.revision) return err(`E-309: revision conflict — you sent ${expectedRaw}, the document stands at ${descriptor.revision}. Re-read with /evolution params --json and retry.`);
+					const value = parseParamValue(rawValue);
+					try {
+						await provider.update(namespace, { [id]: value }, expected);
+					} catch (error) {
+						const code = error?.code;
+						const message = error instanceof Error ? error.message : String(error);
+						if (code === "SETTINGS_CONFLICT") return err(`E-309: revision conflict — ${message}. Re-read with /evolution params --json and retry.`);
+						return err(`E-310: the settings service refused the write: ${message} — the owning plugin's rule stands (a cross-field pair, or a cap that may only be tightened). /evolution params shows the current value.`);
+					}
+					return ok(renderPolicySet({
+						id,
+						namespace,
+						applies: entry.applies,
+						before: descriptor.user?.[id] ?? resolved?.[id],
+						after: value,
+						wasOverridden: descriptor.user !== void 0 && Object.hasOwn(descriptor.user, id)
+					}));
+				}
 				if (input === "doctor" || input === "doctor --json") {
 					const report = await diagnose(ctx, { home: evolutionRoot() });
 					if (input === "doctor --json") return ok(JSON.stringify(report, null, 2));

package/lib/types/doctor.d.ts

@@ -76,6 +76,10 @@ export interface DoctorReport {
      * `memory-files`' store limit vs `evolution-policy`'s planning value. Empty
      * when either surface is absent (nothing to compare) or they agree. */
     budgetIssues: string[];
+    /** S4.3: parameter-surface divergences — user overrides, deprecated aliases
+     * still written, and E3 rows whose owner publishes no user layer here. Empty
+     * when the settings service is absent (nothing to compare). */
+    paramIssues: string[];
     services: {
         review: boolean;
         curator: boolean;

package/lib/types/params.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `/evolution params` view (G4/S4.1): the registry joined with the settings
+ * surface, so one text answers "which parameters exist, who may write them, and
+ * did I already override this one".
+ *
+ * The join key is the OWNER PACKAGE: core's `PARAM_NAMESPACES` maps a package to
+ * the one namespace it registers, and `settings.describe()` reports that
+ * namespace's raw user section (a key's PRESENCE is the override) plus the
+ * resolved value. Everything here is pure; the command handler supplies the data.
+ * @module @lmzhen/dsh-evolution-commands/params
+ */
+import { type ParamExposure } from '@lmzhen/dsh-evolution-core';
+/** One registered namespace, as `settings.describe()` reports it. */
+export interface ParamSectionView {
+    /** Raw user section: a key's presence marks a user override. */
+    user?: Record<string, unknown> | undefined;
+    /** Resolved section (schema defaults < base < user). */
+    value?: Record<string, unknown> | undefined;
+}
+/** Which face a row's value comes from. */
+export type ParamSource = 'user' | 'deployment' | 'unregistered';
+/** One parameter as the command renders it. */
+export interface ParamSurfaceRow {
+    id: string;
+    group: ParamExposure['group'];
+    tier: ParamExposure['tier'];
+    /** Settings-side timing: live, restart, or none (not user-writable). */
+    applies: ParamExposure['applies'];
+    owner: string;
+    source: ParamSource;
+    /** What that face holds, or undefined when no face reports a value. */
+    value: unknown;
+}
+/**
+ * Join the registry with the settings surface.
+ *
+ * `user` means the raw user section carries this key; `deployment` means the
+ * owner's namespace is registered but the key is unset (so the row/policy value
+ * applies); `unregistered` means the owner package publishes no namespace at all
+ * (or is not mounted), which is the honest answer for a deployment-only face.
+ * The distinction matters: 'no user section' must never read as 'not overridden'
+ * for a namespace that failed to register.
+ * @param sections - namespace to surface view, from `settings.describe()`.
+ * @param entries - registry entries (defaults to the family registry).
+ * @returns one row per registry entry, in registry order.
+ */
+export declare function paramSurfaceRows(sections: ReadonlyMap<string, ParamSectionView>, entries?: readonly ParamExposure[]): ParamSurfaceRow[];
+/**
+ * The groups the registry actually carries, in registry order — the list an
+ * unknown `--group` value is answered with.
+ * @param entries - registry entries (defaults to the family registry).
+ * @returns distinct group names.
+ */
+export declare function paramGroups(entries?: readonly ParamExposure[]): string[];
+/**
+ * Render the rows as fixed-width text (one parameter per line, never truncated).
+ * @param rows - rows from {@link paramSurfaceRows}.
+ * @param options - whether the settings service answered at all.
+ * @returns the command text.
+ */
+export declare function renderParamRows(rows: readonly ParamSurfaceRow[], options: {
+    providerMounted: boolean;
+}): string;
+/**
+ * Parse one command-line value into what the settings document stores: JSON
+ * when it parses (numbers, booleans, quoted strings, arrays, objects), the raw
+ * text otherwise, so a bare word like `enforce` stays a word.
+ * @param raw - the text typed after the parameter id.
+ * @returns the value to write.
+ */
+export declare function parseParamValue(raw: string): unknown;
+/** One accepted write, as the command echoes it back. */
+export interface ParamWriteEcho {
+    id: string;
+    namespace: string;
+    applies: ParamExposure['applies'];
+    before: unknown;
+    after: unknown;
+    /** Whether the user section already carried this key. */
+    wasOverridden: boolean;
+}
+/**
+ * Render the write result: the value move, then where it landed and when it
+ * takes effect (the two things a caller cannot infer from the command line).
+ * @param write - the accepted write.
+ * @returns the command text.
+ */
+export declare function renderPolicySet(write: ParamWriteEcho): string;
+/**
+ * Render the rows as JSON for scripts (same fields, no formatting).
+ * @param rows - rows from {@link paramSurfaceRows}.
+ * @returns a JSON document with a `params` array.
+ */
+export declare function renderParamJson(rows: readonly ParamSurfaceRow[]): string;
+//# sourceMappingURL=params.d.ts.map

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.5.0",
+  "version": "0.6.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,12 +27,12 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.5.0",
-    "@lmzhen/dsh-evolution-core": "^0.5.0",
-    "@lmzhen/dsh-evolution-maintenance": "^0.5.0"
+    "@lmzhen/dsh-evolution-approval": "^0.6.0",
+    "@lmzhen/dsh-evolution-core": "^0.6.0",
+    "@lmzhen/dsh-evolution-maintenance": "^0.6.0"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.5.0"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.6.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",