@lmzhen/dsh-evolution-maintenance 0.26.15 → 0.26.26

package/lib/index.js

@@ -1,6 +1,7 @@
 import { a as snapshotFromLibrary, i as enrichmentSnapshotOptions, n as computeProbe, r as buildEnrichment, t as PROBE_SIGNALS } from "./probe-Bojb0piw.js";
-import { AUTHORING_DESCRIPTION_BAR, DEFAULT_CURATOR_MODEL, DEFAULT_HEALTH_THRESHOLDS, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, LOW_QUALITY_THRESHOLD, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_TIMER_DELAY_MS, MIN_STAMP_BODY_CHARS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, computeDriftSignals, findDriftSignal, isRecord, redactSecrets, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
+import { AUTHORING_DESCRIPTION_BAR, DEFAULT_CURATOR_MODEL, DEFAULT_HEALTH_THRESHOLDS, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, LOW_QUALITY_THRESHOLD, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_TIMER_DELAY_MS, MIN_STAMP_BODY_CHARS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, STORE_LEDGER, computeDriftSignals, evolutionHome, findDriftSignal, isRecord, redactSecrets, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
 import { createHash, randomUUID } from "node:crypto";
+import { join } from "node:path";
 //#region lib/types/render-facts.js
 /**
 * Mechanical-facts rendering for the maintenance subagent (011 §6).
@@ -23,6 +24,19 @@ function renderFacts(report, options) {
 		lines.push(`# skill=${sanitize(skill.name)} (${meta.join(" ")})`);
 		for (const signal of skill.signals) lines.push(...renderSignal(signal, redact));
 	}
+	for (const store of options.footprint ?? []) {
+		const parts = [
+			`${store.used === void 0 || store.skipped !== void 0 ? "[UNKNOWN]" : "[FACT]"} signal=store/${sanitize(store.id)}`,
+			`unit=${sanitize(store.unit)}`,
+			`bound=${sanitize(store.bound)}`,
+			`used=${store.used === void 0 ? "unknown" : String(store.used)}`,
+			`lastSweep=${sanitize(store.lastSweep ?? "never")}`,
+			`removed=${store.removed === void 0 ? "unknown" : String(store.removed)}`
+		];
+		if (store.skipped !== void 0) parts.push(`skipped=${sanitize(store.skipped)}`);
+		parts.push(`verdict=${store.used === void 0 || store.skipped !== void 0 ? "unknown" : "fact"}`);
+		lines.push(parts.join(" "));
+	}
 	lines.push("<<<END FACTS>>>");
 	return lines.join("\n");
 }
@@ -285,6 +299,124 @@ function validateAndNormalizeMaintainPlan(raw, report, validSignals) {
 	};
 }
 //#endregion
+//#region lib/types/footprint.js
+/**
+* G3/3.3: the footprint reading for one maintenance run.
+*
+* One line per REGISTERED store (STORE_LEDGER), never a line per store that happened to be readable: the
+* auditor must be able to tell "measured zero" from "not measured" (I3: not-done must never read as
+* nothing-to-do). This first cut reads the stores whose artifact needs only the home-relative path the
+* runtime already knows; everything else renders UNKNOWN with the reason, so the block is honest today
+* and becomes informative as each reader lands.
+*/
+/**
+* Read what can be read, and say so for everything else.
+* @param io - the runtime io, or undefined when the caller has none (every store then reads UNKNOWN).
+* @returns one reading per registered store, in ledger order.
+*/
+async function reclamationFootprint(io) {
+	const out = [];
+	for (const store of STORE_LEDGER) {
+		if (io === void 0) {
+			out.push({
+				id: store.id,
+				unit: store.unit,
+				bound: store.bound,
+				skipped: "the maintenance runtime has no io; nothing was measured"
+			});
+			continue;
+		}
+		if (store.id === "reports") {
+			try {
+				const names = await io.list(join(evolutionHome(), "reports"));
+				out.push({
+					id: store.id,
+					unit: store.unit,
+					bound: store.bound,
+					used: names.length,
+					lastSweep: "see the curator run end",
+					removed: void 0
+				});
+			} catch {
+				out.push({
+					id: store.id,
+					unit: store.unit,
+					bound: store.bound,
+					skipped: "the reports directory could not be listed"
+				});
+			}
+			continue;
+		}
+		out.push({
+			id: store.id,
+			unit: store.unit,
+			bound: store.bound,
+			skipped: "no reader yet for this store"
+		});
+	}
+	return out;
+}
+/**
+* G3/3.4: the three reachability readings, folded into the footprint channel so the report has ONE shape.
+*
+* Paths come from the caller: the history root and the snapshot root live under the skills root, and the
+* reports directory under the evolution home. A runtime that does not state its skills root gets UNKNOWN
+* for the two rooted domains instead of a guess - the same three-state rule the rest of this file uses.
+* @param io - the runtime io, or undefined when the caller has none.
+* @param skillRoot - the configured skills root, or undefined when the runtime does not state one.
+*/
+async function reachabilityFootprint(io, skillRoot) {
+	const domains = [
+		"history.blobs",
+		"reports.files",
+		"backups.trees"
+	];
+	if (io === void 0) return domains.map((domain) => ({
+		id: domain,
+		unit: "files",
+		bound: "unmeasured",
+		skipped: "the maintenance runtime has no io; nothing was measured"
+	}));
+	const { historyReachability, reportsReachability, backupsReachability } = await import("@lmzhen/dsh-evolution-core");
+	const out = [];
+	if (skillRoot === void 0) for (const domain of ["history.blobs", "backups.trees"]) out.push({
+		id: domain,
+		unit: "files",
+		bound: "unmeasured",
+		skipped: "the runtime states no skills root; the reading was not attempted"
+	});
+	else {
+		const history = await historyReachability(io, join(skillRoot, ".history"));
+		out.push({
+			id: history.domain,
+			unit: history.unit,
+			bound: history.baseline,
+			used: history.unreachable,
+			lastSweep: "this run",
+			removed: void 0
+		});
+		const backups = await backupsReachability(io, join(skillRoot, ".backups"), []);
+		out.push({
+			id: backups.domain,
+			unit: backups.unit,
+			bound: backups.baseline,
+			used: backups.unreachable,
+			lastSweep: "this run",
+			removed: void 0
+		});
+	}
+	const reports = await reportsReachability(io, join(evolutionHome(), "reports"), [], []);
+	out.push({
+		id: reports.domain,
+		unit: reports.unit,
+		bound: reports.baseline,
+		used: reports.unreachable,
+		lastSweep: "this run",
+		removed: void 0
+	});
+	return out;
+}
+//#endregion
 //#region lib/types/orchestrate.js
 /**
 * Maintain orchestration (011 §3/§7): snapshot → drift signals → facts
@@ -336,7 +468,7 @@ function jointSignature(template, signalsVersion) {
 * rendered facts block (joint signature + redaction). Shared by `runMaintain`
 * and the `--facts` preview so the preview can never disagree with the scan.
 */
-function buildMaintainFacts(snapshots, usageObserved, redact) {
+function buildMaintainFacts(snapshots, usageObserved, redact, footprint) {
 	const report = computeDriftSignals(snapshots.map((snapshot) => ({
 		...snapshot,
 		usageObserved
@@ -348,7 +480,8 @@ function buildMaintainFacts(snapshots, usageObserved, redact) {
 		facts: renderFacts(report, {
 			signalsVersion,
 			signature,
-			redact
+			redact,
+			footprint
 		}),
 		signalsVersion,
 		signature
@@ -430,7 +563,8 @@ async function runMaintain(runtime, options = {}) {
 				text: "维护扫描：技能库为空，无需处理。"
 			};
 		}
-		const { facts, report, signalsVersion, signature } = buildMaintainFacts(snapshots, enrichment?.usageObservedValue, options.redact);
+		const footprint = [...await reclamationFootprint(runtime.io), ...await reachabilityFootprint(runtime.io, runtime.skillRoot)];
+		const { facts, report, signalsVersion, signature } = buildMaintainFacts(snapshots, enrichment?.usageObservedValue, options.redact, footprint);
 		const template = renderMaintainTemplate(MAINTAIN_PROMPT, PROMPT_BUNDLE_ID, signalsVersion, signature);
 		const probeRegistered = runtime.tools?.get("maintenance_probe") != null;
 		const probeDegraded = options.toolAllow === void 0 && !probeRegistered;

package/lib/tools.js

@@ -1,5 +1,5 @@
 import { a as snapshotFromLibrary, i as enrichmentSnapshotOptions, n as computeProbe, r as buildEnrichment, t as PROBE_SIGNALS } from "./probe-Bojb0piw.js";
-import { DEFAULT_PROBE_TIMEOUT_MS, MAX_TIMER_DELAY_MS, assertSkillsRootAliasRetired, clampedNumber, newSkillLibrary, redactSecrets, resolveRootConfig } from "@lmzhen/dsh-evolution-core";
+import { DEFAULT_PROBE_TIMEOUT_MS, MAX_TIMER_DELAY_MS, assertSkillsRootAliasRetired, authorityFrom, clampedNumber, newSkillLibrary, redactSecrets, resolveRootConfig } from "@lmzhen/dsh-evolution-core";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region lib/types/tools.js
@@ -69,6 +69,7 @@ function apply(ctx, rawConfig = {}) {
 					...target ? { target } : {}
 				};
 				const library = newSkillLibrary({
+					authority: authorityFrom({ origin: "foreground" }),
 					config: rootConfig,
 					io: ioRegistry.provider()
 				});

package/lib/types/footprint.d.ts

@@ -0,0 +1,30 @@
+import type { StoreFootprint } from './render-facts.ts';
+import type { ReachabilityIo } from '@lmzhen/dsh-evolution-core';
+/**
+ * The io surface this reading needs; a runtime without it yields UNKNOWN for every store.
+ *
+ * It EXTENDS the reachability read surface instead of restating it: this module drives those readings,
+ * so the reads they need are the reads it needs. Restating them here is what produced the same
+ * "argument not assignable" error three times - the surface now has ONE owner (`ReachabilityIo`) and this
+ * adds only the probe the report sweep uses on top.
+ */
+export interface FootprintIo extends ReachabilityIo {
+    mtime?(path: string): Promise<number | null>;
+}
+/**
+ * Read what can be read, and say so for everything else.
+ * @param io - the runtime io, or undefined when the caller has none (every store then reads UNKNOWN).
+ * @returns one reading per registered store, in ledger order.
+ */
+export declare function reclamationFootprint(io: FootprintIo | undefined): Promise<StoreFootprint[]>;
+/**
+ * G3/3.4: the three reachability readings, folded into the footprint channel so the report has ONE shape.
+ *
+ * Paths come from the caller: the history root and the snapshot root live under the skills root, and the
+ * reports directory under the evolution home. A runtime that does not state its skills root gets UNKNOWN
+ * for the two rooted domains instead of a guess - the same three-state rule the rest of this file uses.
+ * @param io - the runtime io, or undefined when the caller has none.
+ * @param skillRoot - the configured skills root, or undefined when the runtime does not state one.
+ */
+export declare function reachabilityFootprint(io: FootprintIo | undefined, skillRoot: string | undefined): Promise<StoreFootprint[]>;
+//# sourceMappingURL=footprint.d.ts.map

package/lib/types/orchestrate.d.ts

@@ -6,42 +6,37 @@
  */
 import { type DriftReport, type DriftSkillSnapshot } from '@lmzhen/dsh-evolution-core';
 import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent';
 import { type SkillLibraryLike } from './drift-scan.ts';
 import { type Enrichment } from './enrichment.ts';
+import { type StoreFootprint } from './render-facts.ts';
+import { type FootprintIo } from './footprint.ts';
 import { type MaintainPlanItem } from './validate-plan.ts';
-/** I-5 (v37): the platform's `SubagentStartRequest` fields this orchestrator sends.
- * Typed locally (not imported) because the platform type lives behind the subagent row this
- * package does not depend on; the required `parent` and `signal` mirror the platform. */
-export interface SubagentStartRequestLike {
-    readonly label: string;
-    readonly prompt: readonly {
-        readonly type: 'text';
-        readonly text: string;
-    }[];
-    readonly parent: Agent;
-    readonly signal: AbortSignal;
-    readonly maxDepth: number;
-    readonly agentOptions: Record<string, string>;
-    readonly persona: string;
-    readonly toolFilter: {
+/**
+ * I-5 (v37), D-09 (G1/1.8): the platform types are IMPORTED, not copied. Each view below is DERIVED from
+ * the platform contract, so a field the platform renames fails the build here instead of drifting.
+ *
+ * The one thing this layer must add: `persona` and `toolFilter` are honoured at runtime (child-agent.ts
+ * installs a `deployment:persona` system-prompt section; the README documents toolFilter as applying the
+ * requested child tool restriction) but the CALLER-facing `SubagentStartRequest` does not declare them.
+ * They are therefore declared here, once, as an explicit extension instead of a hand-copied whole.
+ */
+export type MaintainSubagentStart = SubagentStartRequest & {
+    readonly persona?: string | undefined;
+    readonly toolFilter?: {
         readonly allow: readonly string[];
-    };
-    readonly outputSchema: Record<string, unknown>;
-}
-/** I-5 (v37): the platform's `SubagentResult` fields the outcome mapping reads. The
- * index signature keeps a REAL platform result assignable (the platform type is
- * wider than these three fields); the fields below are the ones this code relies on. */
-export interface SubagentResultLike {
-    readonly structured?: unknown;
-    readonly diagnostic?: string;
-    readonly stopReason: string;
-}
-/** I-5 (v37): the platform's `SubagentRun` contract the orchestrator owns — `dispose` is
- * NOT optional (the platform declares it required and every exit path here awaits it). */
-export interface SubagentRunLike {
-    readonly result: Promise<SubagentResultLike>;
-    dispose(): Promise<void>;
-}
+    } | undefined;
+};
+/** The `SubagentResult` fields the outcome mapping reads (the platform result is wider). */
+/** The `SubagentResult` fields the outcome mapping reads. `diagnostic` is OPTIONAL here on purpose: the
+ * platform type declares it required, but this layer reads it defensively (the mapped outcome must work
+ * for a result that carries none), so the view states that narrower truth instead of inheriting the
+ * platform requirement. */
+export type MaintainSubagentResult = Pick<SubagentResult, 'structured' | 'stopReason'> & {
+    readonly diagnostic?: string | undefined;
+};
+/** The platform run handle the orchestrator owns (`dispose` is required and every exit path awaits it). */
+export type MaintainSubagentRun = SubagentRun;
 export interface MaintainRuntime {
     /** SkillLibrary-like reader for snapshot assembly. */
     library: SkillLibraryLike;
@@ -50,7 +45,7 @@ export interface MaintainRuntime {
      * request from `unknown` and `dispose` from optional to the platform's
      * always-present handle, so a future miss fails `tsc` instead of a runtime TypeError. */
     subagents: {
-        start(kind: 'spawn', options: SubagentStartRequestLike): Promise<SubagentRunLike>;
+        start(kind: 'spawn', options: MaintainSubagentStart): Promise<MaintainSubagentRun>;
     };
     /** The spawning agent (platform `SubagentStartRequest.parent`, required: in-process
      * providers derive workspace, lineage and delegation depth from its durable session). */
@@ -83,6 +78,9 @@ export interface MaintainRuntime {
      * probe the scan keeps the previous empty-library answer. */
     rootExists?: (() => Promise<boolean>) | undefined;
     /** V27 M-02: the root the probe above refers to, for the error message. */
+    /** G3/3.3: the runtime io the footprint reading needs. Optional: a caller without it gets UNKNOWN for
+     * every registered store instead of an invented zero. */
+    io?: FootprintIo | undefined;
     skillRoot?: string | undefined;
 }
 export interface MaintainOptions {
@@ -138,7 +136,10 @@ export interface FactsBundle {
  * rendered facts block (joint signature + redaction). Shared by `runMaintain`
  * and the `--facts` preview so the preview can never disagree with the scan.
  */
-export declare function buildMaintainFacts(snapshots: ReadonlyArray<DriftSkillSnapshot>, usageObserved: boolean | undefined, redact: ((text: string) => string) | undefined): FactsBundle;
+export declare function buildMaintainFacts(snapshots: ReadonlyArray<DriftSkillSnapshot>, usageObserved: boolean | undefined, redact: ((text: string) => string) | undefined, 
+/** G3/3.3: one reading per registered bounded store, produced at this run's reclamation point.
+ * Optional so the preview and any older caller keep the exact block they had. */
+footprint?: readonly StoreFootprint[]): FactsBundle;
 /** Run one maintenance scan and return display text plus validation metadata. */
 export declare function runMaintain(runtime: MaintainRuntime, options?: MaintainOptions): Promise<MaintainOutcome>;
 //# sourceMappingURL=orchestrate.d.ts.map

package/lib/types/render-facts.d.ts

@@ -9,11 +9,27 @@
  * redactor and the delimiter/newline escaping before it leaves the session.
  */
 import { type DriftReport } from '@lmzhen/dsh-evolution-core';
+/** G3/3.3: what one footprint line reports about one registered store. */
+export interface StoreFootprint {
+    readonly id: string;
+    readonly unit: string;
+    /** The reading, when one exists; undefined renders as UNKNOWN instead of an invented zero. */
+    readonly used?: number | undefined;
+    readonly bound: string;
+    readonly lastSweep?: string | undefined;
+    readonly removed?: number | undefined;
+    /** Set for a `manual` store that did not run: stated, never implied. */
+    readonly skipped?: string | undefined;
+}
 export interface RenderFactsOptions {
     /** signals_version — changes whenever the signal set/thresholds change. */
     signalsVersion: string;
     /** Joint signature: sha256(template-text + signal-definitions) — shared with MAINTAIN_PROMPT head. */
     signature: string;
+    /** G3/3.3: one reading per registered bounded store (STORE_LEDGER). Absent ⇒ no footprint lines at
+     * all, so an older caller keeps the exact block it had; a store with no reading renders as UNKNOWN
+     * and a manual-trigger store that did not run says so — "not done" must never read as "nothing to do". */
+    footprint?: readonly StoreFootprint[] | undefined;
     /** Optional redactor; defaults to core `redactSecrets`. */
     redact?: ((text: string) => string) | undefined;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-maintenance",
   "description": "Deterministic maintenance-scan surface: skill-library snapshot assembly, drift signals and mechanical-facts rendering (design 011) (community build)",
-  "version": "0.26.15",
+  "version": "0.26.26",
   "publishConfig": {
     "access": "public"
   },
@@ -31,15 +31,17 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
-    "@lmzhen/dsh-evolution-core": "^0.26.15"
+    "@lmzhen/dsh-evolution-core": "^0.26.26"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.2.0-rc.1",
     "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.2.0-rc.1",
     "@deepseek-ai/dsh-tools": "^0.2.0-rc.1"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.2.0-rc.1",
     "@deepseek-ai/dsh-tools": "^0.2.0-rc.1"
   }
 }