@lmzhen/dsh-evolution-replay 0.1.0-rc.1

package/README.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-evolution-replay
+
+Replay/A-B evaluation primitives for evolution plans
+
+## Model Experience
+
+### Indirect model surface
+
+#### What the model sees
+
+`@deepseek-ai/dsh-evolution-replay` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
+
+#### Token effect
+
+Zero direct token effect from this package; consumers add any model-visible tokens.
+
+#### KV Cache effect
+
+Independent of request-prefix construction. This package does not alter the assembled prompt or tool list.
+
+## Known Limitations and Deferred Work
+
+
+- No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.

package/lib/index.js

@@ -0,0 +1,103 @@
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/index.js
+/**
+* Replay/A-B evaluation for evolution plans.
+*
+* The pure scoring functions remain deterministic and runtime-free. The DSH
+* driver records every `evolution/plan-applied` session event into an
+* in-memory leaderboard and exposes `/evolution replay` for comparison, so a
+* human can A/B review policy/prompt changes against real plan outcomes.
+* @module @lmzhen/dsh-evolution-replay
+*/
+const DEFAULT_WEIGHTS = {
+	accepted: 10,
+	rejectedPenalty: 15,
+	evidence: 2,
+	cost: .001
+};
+const Config = z.object({
+	maxPlans: z.number().default(50),
+	weights: z.object({
+		accepted: z.number().default(10),
+		rejectedPenalty: z.number().default(15),
+		evidence: z.number().default(2),
+		cost: z.number().default(.001)
+	}).default(DEFAULT_WEIGHTS)
+});
+function scorePlan(plan, weights = DEFAULT_WEIGHTS) {
+	return plan.acceptedOps * weights.accepted - plan.rejectedOps * weights.rejectedPenalty + plan.evidenceQuotes * weights.evidence - plan.estimatedInputChars * weights.cost;
+}
+function comparePlans(plans, weights = DEFAULT_WEIGHTS) {
+	if (plans.length === 0) return {
+		winner: null,
+		margin: 0,
+		plans,
+		report: "No plans to compare."
+	};
+	const scored = plans.map((plan) => ({
+		plan,
+		score: scorePlan(plan, weights)
+	})).sort((a, b) => b.score - a.score);
+	const winner = scored[0];
+	if (!winner) return {
+		winner: null,
+		margin: 0,
+		plans,
+		report: "No plans to compare."
+	};
+	const runnerUp = scored[1];
+	const margin = runnerUp ? winner.score - runnerUp.score : winner.score;
+	return {
+		winner: winner.plan.policyId,
+		margin,
+		plans,
+		report: scored.map(({ plan, score }) => `${plan.policyId}: ${score.toFixed(1)} (${plan.acceptedOps} accepted, ${plan.rejectedOps} rejected)`).join("\n")
+	};
+}
+var EvolutionReplayDriver = class {
+	plans = [];
+	maxPlans;
+	weights;
+	constructor(config = {}) {
+		this.maxPlans = config.maxPlans ?? 50;
+		this.weights = config.weights ?? DEFAULT_WEIGHTS;
+	}
+	record(event) {
+		if (event.type !== "evolution/plan-applied") return;
+		const data = event.data;
+		this.plans.push({
+			policyId: typeof data.policyFingerprint === "string" ? data.policyFingerprint : data.planId,
+			acceptedOps: data.memoryApplied + data.skillApplied,
+			rejectedOps: data.rejectedOps,
+			memoryOps: data.memoryApplied,
+			skillOps: data.skillApplied,
+			evidenceQuotes: typeof data.evidenceQuotes === "number" ? data.evidenceQuotes : data.memoryApplied + data.skillApplied,
+			estimatedInputChars: typeof data.estimatedInputChars === "number" ? data.estimatedInputChars : 0
+		});
+		if (this.plans.length > this.maxPlans) this.plans.shift();
+	}
+	plansSnapshot() {
+		return [...this.plans];
+	}
+	compare(weights = this.weights) {
+		return comparePlans(this.plans, weights);
+	}
+};
+const name = "evolution-replay";
+function apply(ctx, rawConfig = {}) {
+	const driver = new EvolutionReplayDriver(rawConfig);
+	ctx.provide("evolutionReplay", driver);
+	ctx.on("session/event", (_session, event) => {
+		if (event.type === "evolution/plan-applied") driver.record(event);
+	});
+	ctx.inject(["commands"], (commandCtx) => {
+		commandCtx.commands.register({
+			name: "evolution replay",
+			description: "Compare recent evolution plan outcomes",
+			recordInput: false,
+			handler: () => ({ text: driver.compare().report })
+		});
+	});
+}
+//#endregion
+export { Config, DEFAULT_WEIGHTS, EvolutionReplayDriver, EvolutionReplayDriver as default, apply, comparePlans, name, scorePlan };

package/lib/invariant.js

@@ -0,0 +1,8 @@
+//#region lib/types/invariant.js
+const PACKAGE_NAME = "@deepseek-ai/dsh-evolution-replay";
+const name = "evolution-replay-invariant";
+const inject = ["invariants"];
+const install = () => {};
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Replay/A-B evaluation for evolution plans.
+ *
+ * The pure scoring functions remain deterministic and runtime-free. The DSH
+ * driver records every `evolution/plan-applied` session event into an
+ * in-memory leaderboard and exposes `/evolution replay` for comparison, so a
+ * human can A/B review policy/prompt changes against real plan outcomes.
+ * @module @deepseek-ai/dsh-evolution-replay
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export interface ReplayPlan {
+    policyId: string;
+    acceptedOps: number;
+    rejectedOps: number;
+    memoryOps: number;
+    skillOps: number;
+    evidenceQuotes: number;
+    estimatedInputChars: number;
+}
+export interface ReplayResult {
+    winner: string | null;
+    margin: number;
+    plans: ReplayPlan[];
+    report: string;
+}
+export interface ReplayWeights {
+    accepted: number;
+    rejectedPenalty: number;
+    evidence: number;
+    cost: number;
+}
+export declare const DEFAULT_WEIGHTS: ReplayWeights;
+export interface Config {
+    maxPlans?: number;
+    weights?: ReplayWeights;
+}
+export declare const Config: z<Config>;
+export declare function scorePlan(plan: ReplayPlan, weights?: ReplayWeights): number;
+export declare function comparePlans(plans: ReplayPlan[], weights?: ReplayWeights): ReplayResult;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        evolutionReplay: EvolutionReplayDriver;
+    }
+}
+export declare class EvolutionReplayDriver {
+    private readonly plans;
+    private readonly maxPlans;
+    private readonly weights;
+    constructor(config?: Config);
+    record(event: {
+        type: string;
+        data: {
+            planId: string;
+            policyFingerprint?: string | undefined;
+            memoryApplied: number;
+            skillApplied: number;
+            rejectedOps: number;
+            evidenceQuotes?: number | undefined;
+            estimatedInputChars?: number | undefined;
+        };
+    }): void;
+    plansSnapshot(): ReplayPlan[];
+    compare(weights?: ReplayWeights): ReplayResult;
+}
+export declare const name = "evolution-replay";
+export declare function apply(ctx: Context, rawConfig?: Config): void;
+export default EvolutionReplayDriver;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "evolution-replay-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@lmzhen/dsh-evolution-replay",
+  "description": "Replay/A-B evaluation primitives for evolution plans (community build)",
+  "version": "0.1.0-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/dsh-evolution-replay"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/invariant.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.1"
+  }
+}