@lmzhen/dsh-evolution-replay 0.3.67 → 0.3.69

package/lib/index.js

@@ -64,7 +64,7 @@ function scorePlan(plan, weights = DEFAULT_WEIGHTS) {
 function comparePlans(plans, weights = DEFAULT_WEIGHTS) {
 	if (plans.length === 0) return {
 		winner: null,
-		margin: 0,
+		margin: null,
 		plans,
 		report: "No plans to compare."
 	};
@@ -75,20 +75,21 @@ function comparePlans(plans, weights = DEFAULT_WEIGHTS) {
 	const winner = scored[0];
 	if (!winner) return {
 		winner: null,
-		margin: 0,
+		margin: null,
 		plans,
 		report: "No plans to compare."
 	};
 	const runnerUp = scored[1];
-	const margin = runnerUp ? winner.score - runnerUp.score : winner.score;
+	const margin = runnerUp ? winner.score - runnerUp.score : null;
+	const singleNote = runnerUp ? "" : "\n(single plan recorded — margin is not a comparison)";
 	return {
 		winner: winner.plan.policyId,
 		margin,
 		plans,
-		report: scored.map(({ plan, score }) => `${plan.policyId}: ${score.toFixed(1)} (${plan.acceptedOps} accepted, ${plan.rejectedOps} rejected${(plan.executionFailures ?? 0) > 0 ? `, ${plan.executionFailures} failed${plan.executionError !== void 0 ? `: ${plan.executionError}` : ""}` : ""})`).join("\n")
+		report: scored.map(({ plan, score }) => `${plan.policyId}: ${score.toFixed(1)} (${plan.acceptedOps} accepted, ${plan.rejectedOps} rejected${(plan.executionFailures ?? 0) > 0 ? `, ${plan.executionFailures} failed${plan.executionError !== void 0 ? `: ${plan.executionError}` : ""}` : ""})`).join("\n") + singleNote
 	};
 }
-var EvolutionReplayDriver = class {
+var EvolutionReplayDriver = class EvolutionReplayDriver {
 	plans = [];
 	maxPlans;
 	/** V25-01 (v25): backfill-once latch — see {@link EvolutionReplayDriver.backfill}. */
@@ -96,8 +97,18 @@ var EvolutionReplayDriver = class {
 	/** V26-05 (v25): plan ids recorded live BEFORE the backfill settled. A
 	* plan-applied landing inside the one-shot `loadActivity` read window is
 	* recorded live AND persisted into the sidecar the backfill is reading —
-	* `backfill()` drops those ids so the event is not counted twice. */
+	* `backfill()` drops those ids so the event is not counted twice.
+	*
+	* V27 INS-05: the set is BOUNDED. `backfill()` is the only place that cleared
+	* it, so a sidecar load that never succeeded (the inject callback's catch
+	* warns and does not retry until the io dependency is replaced) let every
+	* live plan id accumulate for the process lifetime. Past
+	* PRE_BACKFILL_ID_CAP the oldest ids are dropped: the dedupe window is then
+	* finite, and a dropped duplicate can at worst repeat an entry inside the
+	* `maxPlans` window instead of growing memory without bound. */
 	preBackfillIds = /* @__PURE__ */ new Set();
+	/** Upper bound on {@link EvolutionReplayDriver.preBackfillIds} (V27 INS-05). */
+	static PRE_BACKFILL_ID_CAP = 4096;
 	weights;
 	constructor(config = {}, warn = () => {}) {
 		const maxPlans = clampedNumber(config.maxPlans ?? 50, 50, { min: 1 });
@@ -111,12 +122,29 @@ var EvolutionReplayDriver = class {
 		}
 	}
 	record(plan) {
-		if (!this.backfilled) this.preBackfillIds.add(plan.planId);
+		if (!this.backfilled) {
+			this.preBackfillIds.add(plan.planId);
+			while (this.preBackfillIds.size > EvolutionReplayDriver.PRE_BACKFILL_ID_CAP) {
+				const oldest = this.preBackfillIds.keys().next().value;
+				if (oldest === void 0) break;
+				this.preBackfillIds.delete(oldest);
+			}
+		}
+		this.plans.push(this.toPlan(plan));
+		if (this.plans.length > this.maxPlans) this.plans.shift();
+	}
+	/**
+	* v29 RPL-02: the activity/event record → scored-plan mapping, extracted
+	* from `record` so `backfill` can place sidecar plans at the CHRONOLOGICAL
+	* head of the window instead of appending them after this boot's live plans
+	* (the old order made the FIFO evict the freshest live plan first).
+	*/
+	toPlan(plan) {
 		const count = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
 		const countOr = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
 		const memoryApplied = count(plan.memoryApplied);
 		const skillApplied = count(plan.skillApplied);
-		this.plans.push({
+		return {
 			policyId: typeof plan.policyFingerprint === "string" && plan.policyFingerprint.length > 0 ? plan.policyFingerprint : plan.planId,
 			acceptedOps: memoryApplied + skillApplied,
 			rejectedOps: count(plan.rejectedOps),
@@ -126,8 +154,7 @@ var EvolutionReplayDriver = class {
 			estimatedInputChars: count(plan.estimatedInputChars),
 			executionFailures: count(plan.executionFailures),
 			...typeof plan.executionError === "string" ? { executionError: plan.executionError } : {}
-		});
-		if (this.plans.length > this.maxPlans) this.plans.shift();
+		};
 	}
 	/**
 	* V25-01 (v25): backfill the leaderboard from the activity sidecar, ONCE
@@ -143,7 +170,9 @@ var EvolutionReplayDriver = class {
 		this.backfilled = true;
 		const fresh = items.filter((item) => !this.preBackfillIds.has(item.planId));
 		this.preBackfillIds.clear();
-		for (const item of fresh) this.record(item);
+		const freshPlans = fresh.map((item) => this.toPlan(item));
+		this.plans.unshift(...freshPlans);
+		if (this.plans.length > this.maxPlans) this.plans.splice(0, this.plans.length - this.maxPlans);
 	}
 	/**
 	* F-11: test-support API — no production consumer reads the raw

package/lib/types/index.d.ts

@@ -35,7 +35,10 @@ export interface ReplayPlan {
 }
 export interface ReplayResult {
     winner: string | null;
-    margin: number;
+    /** v28 G4.4 (RPL-01): `null` when fewer than two plans were recorded — a
+     * single plan has no runner-up, and reporting its FULL score as a "margin"
+     * read as "won by N points" over nothing. Consumers must null-check. */
+    margin: number | null;
     plans: ReplayPlan[];
     report: string;
 }
@@ -73,11 +76,28 @@ export declare class EvolutionReplayDriver {
     /** V26-05 (v25): plan ids recorded live BEFORE the backfill settled. A
      * plan-applied landing inside the one-shot `loadActivity` read window is
      * recorded live AND persisted into the sidecar the backfill is reading —
-     * `backfill()` drops those ids so the event is not counted twice. */
+     * `backfill()` drops those ids so the event is not counted twice.
+     *
+     * V27 INS-05: the set is BOUNDED. `backfill()` is the only place that cleared
+     * it, so a sidecar load that never succeeded (the inject callback's catch
+     * warns and does not retry until the io dependency is replaced) let every
+     * live plan id accumulate for the process lifetime. Past
+     * PRE_BACKFILL_ID_CAP the oldest ids are dropped: the dedupe window is then
+     * finite, and a dropped duplicate can at worst repeat an entry inside the
+     * `maxPlans` window instead of growing memory without bound. */
     private readonly preBackfillIds;
+    /** Upper bound on {@link EvolutionReplayDriver.preBackfillIds} (V27 INS-05). */
+    private static readonly PRE_BACKFILL_ID_CAP;
     private readonly weights;
     constructor(config?: Config, warn?: (message: string) => void);
     record(plan: EvolutionPlanAppliedEvent): void;
+    /**
+     * v29 RPL-02: the activity/event record → scored-plan mapping, extracted
+     * from `record` so `backfill` can place sidecar plans at the CHRONOLOGICAL
+     * head of the window instead of appending them after this boot's live plans
+     * (the old order made the FIFO evict the freshest live plan first).
+     */
+    private toPlan;
     /**
      * V25-01 (v25): backfill the leaderboard from the activity sidecar, ONCE
      * per driver instance. The inject callback that loads the sidecar re-runs

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-replay",
   "description": "Replay/A-B evaluation primitives for evolution plans (community build)",
-  "version": "0.3.67",
+  "version": "0.3.69",
   "publishConfig": {
     "access": "public"
   },
@@ -31,8 +31,8 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-activity": "^0.3.67",
-    "@lmzhen/dsh-evolution-core": "^0.3.67"
+    "@lmzhen/dsh-evolution-activity": "^0.3.69",
+    "@lmzhen/dsh-evolution-core": "^0.3.69"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-activity": "^0.3.67",
-    "@lmzhen/dsh-evolution-core": "^0.3.67"
+    "@lmzhen/dsh-evolution-activity": "^0.3.69",
+    "@lmzhen/dsh-evolution-core": "^0.3.69"
   }
 }