@lmzhen/dsh-skill-usage 0.3.17 → 0.3.18

package/lib/index.js

@@ -2,7 +2,7 @@ import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 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";
+import { appendEvolutionEvent, bumpPatch, bumpUse, bumpView, eventsFile, evolutionIoAdapter, getRecord, loadUsage, markAgentCreated, mutateUsage, resolveSkillsRoot } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Skill usage telemetry service for the evolution family.
@@ -61,13 +61,14 @@ var SkillUsageRegistry = class extends Service {
 	chain = Promise.resolve();
 	constructor(ctx, config = {}) {
 		super(ctx, "skillUsage");
-		this.root = config.root || skillsRoot();
+		this.root = resolveSkillsRoot(config);
 		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);
+			const data = event.data;
+			if (!(typeof data?.name === "string" ? READ_TOOL_KIND[data.name] : void 0)) return;
+			const name = skillNameFromToolCall(data?.arguments);
 			if (!name) return;
 			this.observeRead(name).catch(() => {});
 		});
@@ -92,7 +93,15 @@ var SkillUsageRegistry = class extends Service {
 			if (viewsBefore === 0) await this.appendUsageWindowEvent(map);
 		});
 	}
-	/** Append the observation-window anchor event; best-effort, never fails the observation. */
+	/**
+	* Append the observation-window anchor event; best-effort, never fails the
+	* observation.
+	*
+	* Lock-order contract (E-66): this acquires the evolution-events lock while
+	* the caller holds the usage lock (usage → events one-way nesting — see
+	* `mutate`). Never take the usage lock from inside a block that holds the
+	* events lock; that reverse nesting is a deadlock.
+	*/
 	async appendUsageWindowEvent(map) {
 		try {
 			const at = (/* @__PURE__ */ new Date()).toISOString();
@@ -104,13 +113,21 @@ var SkillUsageRegistry = class extends Service {
 				counts: usageTotals(map),
 				window: { opened: at }
 			});
-		} catch {}
+		} catch (error) {
+			this.ctx.logger.warn(`dsh-skill-usage: failed to append observation-window anchor: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	}
 	/**
 	* 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.
+	*
+	* Lock-order contract (E-66): this holds the usage (`.usage.json`) lock. A
+	* usage-locked `task` MAY acquire the evolution-events lock one-way
+	* (usage → events, e.g. via `appendUsageWindowEvent`); it must NEVER acquire
+	* it in the reverse direction. Two writers taking the two locks in opposite
+	* order would deadlock, so the one-way order is a binding invariant.
 	*/
 	mutate(task) {
 		const run = this.chain.then(async () => {
@@ -153,6 +170,19 @@ var SkillUsageRegistry = class extends Service {
 		});
 	}
 	/**
+	* 0.3.18 (E-70): create-path telemetry in ONE atomic RMW. The former
+	* prepare→markAgentCreated pair ran two full transacts (doubled lock
+	* traffic) and left a window where `created_by=null` was on disk between
+	* them. `agentCreated` picks the authorship marking at the same commit
+	* point where the record is created.
+	*/
+	async ensureRecordCreated(name, agentCreated) {
+		await this.mutate((map) => {
+			if (agentCreated) markAgentCreated(map, name);
+			else 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.

package/lib/types/index.d.ts

@@ -36,13 +36,27 @@ export declare class SkillUsageRegistry extends Service {
      * that anchor exists (curator gates churn on `usageObserved()`).
      */
     private observeRead;
-    /** Append the observation-window anchor event; best-effort, never fails the observation. */
+    /**
+     * Append the observation-window anchor event; best-effort, never fails the
+     * observation.
+     *
+     * Lock-order contract (E-66): this acquires the evolution-events lock while
+     * the caller holds the usage lock (usage → events one-way nesting — see
+     * `mutate`). Never take the usage lock from inside a block that holds the
+     * events lock; that reverse nesting is a deadlock.
+     */
     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.
+     *
+     * Lock-order contract (E-66): this holds the usage (`.usage.json`) lock. A
+     * usage-locked `task` MAY acquire the evolution-events lock one-way
+     * (usage → events, e.g. via `appendUsageWindowEvent`); it must NEVER acquire
+     * it in the reverse direction. Two writers taking the two locks in opposite
+     * order would deadlock, so the one-way order is a binding invariant.
      */
     private mutate;
     record(name: string, kind: 'use' | 'view' | 'patch', at?: Date): Promise<void>;
@@ -56,6 +70,14 @@ export declare class SkillUsageRegistry extends Service {
      * mutation maturity is not inflated by mere creation.
      */
     ensureRecord(name: string): Promise<void>;
+    /**
+     * 0.3.18 (E-70): create-path telemetry in ONE atomic RMW. The former
+     * prepare→markAgentCreated pair ran two full transacts (doubled lock
+     * traffic) and left a window where `created_by=null` was on disk between
+     * them. `agentCreated` picks the authorship marking at the same commit
+     * point where the record is created.
+     */
+    ensureRecordCreated(name: string, agentCreated: boolean): 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

package/package.json

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