@lmzhen/dsh-skill-usage 0.1.0-rc.9 → 0.2.0-rc.1

package/README.md

@@ -2,6 +2,14 @@
 
 Skill usage telemetry service
 
+## Telemetry sources
+
+`record(name, kind)` is the write API (`use` / `view` / `patch`). Reads are
+observed automatically: the service listens for `session/event` `tool/call`
+records of the read tools (`skill`, `skill_load`) and bumps `view` on
+EXISTING records only — an arbitrary read never mints a usage record
+(records are authored by skill creation, patching, or curator seeding).
+
 ## Model Experience
 
 ### Indirect model surface

package/lib/index.js

@@ -1,62 +1,186 @@
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-import { bumpPatch, bumpUse, bumpView, evolutionIoAdapter, loadUsage, saveUsage, skillsRoot } from "@lmzhen/dsh-evolution-core";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { appendEvolutionEvent, bumpPatch, bumpUse, bumpView, eventsFile, evolutionIoAdapter, getRecord, loadUsage, markAgentCreated, mutateUsage, skillsRoot } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Skill usage telemetry service for the evolution family.
 * @module @lmzhen/dsh-skill-usage
 */
+/**
+* Read tool names -> usage kind. The single declarative classification table
+* for read-side observation (A2): any tool listed here records a `view` when
+* its call arguments name a skill.
+*/
+const READ_TOOL_KIND = {
+	skill: "view",
+	skill_load: "view"
+};
+/**
+* Skill name from a tool/call arguments payload (A2, mirrors
+* evolution-review's collectReadSkillNames): JSON strings are re-parsed and
+* `name` wins over `skill`. Empty when unparseable or anonymous.
+*/
+function skillNameFromToolCall(raw) {
+	let parsed = {};
+	if (typeof raw === "string") try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return "";
+	}
+	else if (raw && typeof raw === "object") parsed = raw;
+	return typeof parsed.name === "string" ? parsed.name : typeof parsed.skill === "string" ? parsed.skill : "";
+}
+/** Cumulative library-wide usage totals (C observation-window event counts). */
+function usageTotals(map) {
+	let views = 0;
+	let use = 0;
+	let patches = 0;
+	for (const record of map.values()) {
+		views += record.view_count;
+		use += record.use_count;
+		patches += record.patch_count;
+	}
+	return {
+		skills: map.size,
+		views,
+		use,
+		patches
+	};
+}
 var SkillUsageRegistry = class extends Service {
 	static inject = ["evolutionIo"];
-	static Config = z.object({ root: z.string().default("") });
+	static Config = z.object({
+		root: z.string().default(""),
+		eventsHome: z.string().default("")
+	});
 	root;
+	eventsHome;
 	io;
-	usage = null;
 	chain = Promise.resolve();
 	constructor(ctx, config = {}) {
 		super(ctx, "skillUsage");
-		this.root = config.root ?? skillsRoot();
+		this.root = config.root || skillsRoot();
+		this.eventsHome = config.eventsHome || process.env.DSH_HOME || join(homedir(), ".dsh");
 		this.io = evolutionIoAdapter(() => ctx.evolutionIo.provider());
+		ctx.on("session/event", (_session, event) => {
+			if (event.type !== "tool/call") return;
+			if (!READ_TOOL_KIND[event.data.name]) return;
+			const name = skillNameFromToolCall(event.data.arguments);
+			if (!name) return;
+			this.observeRead(name).catch(() => {});
+		});
 	}
-	async map() {
-		if (!this.usage) this.usage = await loadUsage(this.root, this.io);
-		return this.usage;
+	/**
+	* Read-side telemetry (A2): bump the view counter for an EXISTING record
+	* only. Creation-free by design — otherwise an arbitrary read mints a
+	* record, and "patched many times, reads zero" (the write-ghost signal)
+	* stays computable only while records exist from authorship paths.
+	*
+	* Observation window (C): the FIRST observed read library-wide opens the
+	* window — one `type:'usage'` event is appended to the evolution timeline
+	* (best-effort; the usage sidecar stays the truth and never fails the read
+	* path). Post-A2 deployments treat `view_count` as trustworthy only after
+	* that anchor exists (curator gates churn on `usageObserved()`).
+	*/
+	observeRead(name) {
+		return this.mutate(async (map) => {
+			if (!map.has(name)) return;
+			const viewsBefore = usageTotals(map).views;
+			bumpView(map, name, /* @__PURE__ */ new Date());
+			if (viewsBefore === 0) await this.appendUsageWindowEvent(map);
+		});
 	}
-	async flush() {
-		if (this.usage) await saveUsage(this.root, this.usage, this.io);
+	/** Append the observation-window anchor event; best-effort, never fails the observation. */
+	async appendUsageWindowEvent(map) {
+		try {
+			const at = (/* @__PURE__ */ new Date()).toISOString();
+			await appendEvolutionEvent(this.io, eventsFile(this.eventsHome), {
+				type: "usage",
+				kind: "skill",
+				source: "observation",
+				note: "observation window opened",
+				counts: usageTotals(map),
+				window: { opened: at }
+			});
+		} catch {}
 	}
-	/** Serialize read-modify-write cycles so concurrent record calls never lose updates. */
+	/**
+	* Serialize read-modify-write cycles so concurrent record calls never lose
+	* updates, then run each cycle as ONE atomic transact (rc.50 P2-2): the map
+	* is read from disk inside the lock, so a second process that shares
+	* DSH_HOME cannot interleave its own RMW between our read and write.
+	*/
 	mutate(task) {
-		const run = this.chain.then(async () => task(await this.map()));
+		const run = this.chain.then(async () => {
+			let outcome = void 0;
+			await mutateUsage(this.root, this.io, async (map) => {
+				outcome = await task(map);
+			});
+			return outcome;
+		});
 		this.chain = run.then(() => void 0, () => void 0);
 		return run;
 	}
 	async record(name, kind, at = /* @__PURE__ */ new Date()) {
-		await this.mutate(async (map) => {
+		await this.mutate((map) => {
 			if (kind === "use") bumpUse(map, name, at);
 			else if (kind === "view") bumpView(map, name, at);
 			else bumpPatch(map, name, at);
-			await this.flush();
 		});
 	}
-	report() {
-		return this.mutate((map) => Promise.resolve(new Map(map)));
+	/** Read-only snapshot of the sidecar (no disk write — reading never mutates). */
+	async report() {
+		const run = this.chain.then(async () => new Map(await loadUsage(this.root, this.io)));
+		this.chain = run.then(() => void 0, () => void 0);
+		return run;
 	}
 	async markAgentCreated(name) {
-		await this.mutate(async (map) => {
-			const { markAgentCreated } = await import("@lmzhen/dsh-evolution-core");
+		await this.mutate((map) => {
 			markAgentCreated(map, name);
-			await this.flush();
 		});
 	}
+	/**
+	* Ensure a usage record exists for `name` without bumping any counter
+	* (rc.46 M3-3.3 companion): skill creation is authorship — the record must
+	* exist from birth (created_at anchors now) but `patch_count` stays 0 so
+	* mutation maturity is not inflated by mere creation.
+	*/
+	async ensureRecord(name) {
+		await this.mutate((map) => {
+			getRecord(map, name);
+		});
+	}
+	/**
+	* Mark a skill's usage record as archived (delete / curator archive paths).
+	* Unlike `record('patch')` this never bumps the patch counter — archiving is
+	* a state transition, not a content mutation.
+	*/
+	async markArchived(name, at = /* @__PURE__ */ new Date()) {
+		await this.mutate((map) => {
+			const record = map.get(name);
+			if (record) {
+				record.state = "archived";
+				record.archived_at = at.toISOString();
+			}
+		});
+	}
+	/**
+	* Barrier for external writers: every mutate reads the sidecar fresh from
+	* disk (rc.50 P2-2 transact), so a curator direct-write is visible on the
+	* next call without a cache flush; this waits for queued work to drain.
+	*/
+	async invalidate() {
+		await this.chain;
+	}
 	/** Write feedback-derived quality onto the usage sidecar; curator reads it. */
 	async setQuality(name, score, warn) {
-		await this.mutate(async (map) => {
+		await this.mutate((map) => {
 			const record = map.get(name);
 			if (!record) return;
 			record.quality_score = score;
 			record.quality_warn = warn;
-			await this.flush();
 		});
 	}
 };

package/lib/types/index.d.ts

@@ -12,22 +12,62 @@ declare module '@deepseek-ai/cordis' {
 }
 export interface Config {
     root?: string;
+    /** Home for the evolution event timeline (`<eventsHome>/evolution/events.json`); defaults to DSH_HOME or ~/.dsh. */
+    eventsHome?: string;
 }
 export declare class SkillUsageRegistry extends Service {
     static inject: string[];
     static Config: Schema<Config>;
     readonly root: string;
+    private readonly eventsHome;
     private readonly io;
-    private usage;
     private chain;
     constructor(ctx: Context, config?: Config);
-    private map;
-    flush(): Promise<void>;
-    /** Serialize read-modify-write cycles so concurrent record calls never lose updates. */
+    /**
+     * Read-side telemetry (A2): bump the view counter for an EXISTING record
+     * only. Creation-free by design — otherwise an arbitrary read mints a
+     * record, and "patched many times, reads zero" (the write-ghost signal)
+     * stays computable only while records exist from authorship paths.
+     *
+     * Observation window (C): the FIRST observed read library-wide opens the
+     * window — one `type:'usage'` event is appended to the evolution timeline
+     * (best-effort; the usage sidecar stays the truth and never fails the read
+     * path). Post-A2 deployments treat `view_count` as trustworthy only after
+     * that anchor exists (curator gates churn on `usageObserved()`).
+     */
+    private observeRead;
+    /** Append the observation-window anchor event; best-effort, never fails the observation. */
+    private appendUsageWindowEvent;
+    /**
+     * Serialize read-modify-write cycles so concurrent record calls never lose
+     * updates, then run each cycle as ONE atomic transact (rc.50 P2-2): the map
+     * is read from disk inside the lock, so a second process that shares
+     * DSH_HOME cannot interleave its own RMW between our read and write.
+     */
     private mutate;
     record(name: string, kind: 'use' | 'view' | 'patch', at?: Date): Promise<void>;
+    /** Read-only snapshot of the sidecar (no disk write — reading never mutates). */
     report(): Promise<UsageMap>;
     markAgentCreated(name: string): Promise<void>;
+    /**
+     * Ensure a usage record exists for `name` without bumping any counter
+     * (rc.46 M3-3.3 companion): skill creation is authorship — the record must
+     * exist from birth (created_at anchors now) but `patch_count` stays 0 so
+     * mutation maturity is not inflated by mere creation.
+     */
+    ensureRecord(name: string): Promise<void>;
+    /**
+     * Mark a skill's usage record as archived (delete / curator archive paths).
+     * Unlike `record('patch')` this never bumps the patch counter — archiving is
+     * a state transition, not a content mutation.
+     */
+    markArchived(name: string, at?: Date): Promise<void>;
+    /**
+     * Barrier for external writers: every mutate reads the sidecar fresh from
+     * disk (rc.50 P2-2 transact), so a curator direct-write is visible on the
+     * next call without a cache flush; this waits for queued work to drain.
+     */
+    invalidate(): Promise<void>;
     /** Write feedback-derived quality onto the usage sidecar; curator reads it. */
     setQuality(name: string, score: number, warn: boolean): Promise<void>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-skill-usage",
   "description": "Skill usage telemetry service (community build)",
-  "version": "0.1.0-rc.9",
+  "version": "0.2.0-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -33,16 +33,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.9"
+    "@lmzhen/dsh-evolution-core": "^0.2.0-rc.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.9"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@lmzhen/dsh-evolution-io": "^0.2.0-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.9",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.9"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@lmzhen/dsh-evolution-core": "^0.2.0-rc.1",
+    "@lmzhen/dsh-evolution-io": "^0.2.0-rc.1"
   }
 }