@lmzhen/dsh-evolution-replay 0.18.0 → 0.18.1

package/README.md

@@ -13,6 +13,6 @@ replay`.
 ## Known limitations
 
 - No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.
-- **The activity-sidecar verdict is per read (`sourceCorrupt`).** When `apply()` meets bytes this build cannot read as the current format, every `compare()` result carries `sourceCorrupt: true` and its report states the leaderboard is NOT the recorded history (an empty list does not mean nothing happened); a later successful read clears the qualification (a repaired sidecar plus an io reload (HMR / plugin restart)), while the corruption stays observable through the one warn `apply()` emits at mark time.
+- **The activity-sidecar verdict is per read, and an unanswered read is its own state.** When `apply()` meets bytes this build cannot read as the current format, every `compare()` result carries `sourceCorrupt: true` and its report states the leaderboard is NOT the recorded history (an empty list does not mean nothing happened); a later successful read clears the qualification (a repaired sidecar plus an io reload (HMR / plugin restart)), while the corruption stays observable through the one warn `apply()` emits at mark time. A read that **THREW** (the io failed, or no state could be produced at all) is neither verdict: `compare()` then carries `sourceReadFailure: <message>` and its report says the read FAILED — never "nothing was recorded". Any ANSWERED read (clean or corrupt) retires that failure, so both qualifications describe the current read rather than latching.
 
 **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).

package/lib/index.js

@@ -101,6 +101,12 @@ var EvolutionReplayDriver = class EvolutionReplayDriver {
 	* clears it on a later clean read, so the qualification reflects the present
 	* instead of latching for the driver lifetime. */
 	sourceCorrupt = false;
+	/** 0.18.1 (S3): the backfill READ itself failed — held as its message. A
+	* thrown read used to skip both markers, so `sourceCorrupt` kept whatever
+	* the previous read said and a failed read presented as a clean one. Cleared
+	* by any ANSWERED read; never sets `sourceCorrupt` (a failed read is not
+	* evidence that the bytes are corrupt). */
+	sourceReadFailure = null;
 	/** V26-05 (v25): plan ids recorded live BEFORE the backfill settled. A
 	* plan-applied landing inside the one-shot `loadActivityState` read window is
 	* recorded live AND persisted into the sidecar the backfill is reading —
@@ -203,6 +209,7 @@ var EvolutionReplayDriver = class EvolutionReplayDriver {
 	*/
 	markSourceUnreadable() {
 		this.sourceCorrupt = true;
+		this.sourceReadFailure = null;
 	}
 	/**
 	* PLAN S5.1 (2026-09-16, audit P2-18): the counterpart clear — `apply()` calls
@@ -218,17 +225,30 @@ var EvolutionReplayDriver = class EvolutionReplayDriver {
 	*/
 	markSourceReadable() {
 		this.sourceCorrupt = false;
+		this.sourceReadFailure = null;
+	}
+	/**
+	* 0.18.1 (S3): the backfill read THREW (io error, or a state the reader could
+	* not produce at all). Neither verdict applies — the bytes were never judged.
+	* Before this the throw skipped both markers and `compare()` returned an
+	* unqualified leaderboard, presenting a failed read as an answered one.
+	* @param reason - the failure's message, as thrown.
+	*/
+	markSourceReadFailed(reason) {
+		this.sourceReadFailure = reason;
 	}
 	compare(weights = this.weights) {
 		const result = comparePlans([...this.plans], clampReplayWeights(weights, this.weights));
-		if (!this.sourceCorrupt) return {
+		const failure = this.sourceReadFailure === null ? "" : `The activity sidecar read FAILED (${this.sourceReadFailure}) — this leaderboard carries no history from the sidecar, and a failed read is NOT "nothing was recorded".\n`;
+		if (!this.sourceCorrupt && this.sourceReadFailure === null) return {
 			...result,
 			sourceCorrupt: false
 		};
 		return {
 			...result,
-			sourceCorrupt: true,
-			report: "The activity sidecar could not be read as an activity envelope (unparsable bytes, or no items array) — this leaderboard is NOT the recorded history, and an empty list does not mean nothing happened.\n" + result.report
+			sourceCorrupt: this.sourceCorrupt,
+			...this.sourceReadFailure === null ? {} : { sourceReadFailure: this.sourceReadFailure },
+			report: failure + (this.sourceCorrupt ? "The activity sidecar could not be read as an activity envelope (unparsable bytes, or no items array) — this leaderboard is NOT the recorded history, and an empty list does not mean nothing happened.\n" : "") + result.report
 		};
 	}
 };
@@ -254,7 +274,9 @@ function apply(ctx, rawConfig = {}) {
 			}
 			driver.backfill(loaded.records);
 		}).catch((error) => {
-			ioCtx.logger.warn(`evolution-replay: activity sidecar backfill skipped (${error instanceof Error ? error.message : String(error)})`);
+			const reason = error instanceof Error ? error.message : String(error);
+			driver.markSourceReadFailed(reason);
+			ioCtx.logger.warn(`evolution-replay: activity sidecar backfill skipped (${reason}) — this leaderboard carries no history from the sidecar, and a failed read is not "nothing was recorded"`);
 		});
 	});
 }

package/lib/types/index.d.ts

@@ -51,6 +51,12 @@ export interface ReplayResult {
      * was repaired and an io reload re-read it) clears the qualification —
      * it never outlives the condition it describes. */
     sourceCorrupt?: boolean | undefined;
+    /** 0.18.1 (S3): the most recent backfill READ threw (io error, or a state the
+     * reader could not produce at all) — no verdict was reached, which is a
+     * different fact from `sourceCorrupt` (the bytes WERE read and are not an
+     * activity envelope). Carries the failure's message; a later ANSWERED read
+     * clears it (see {@link EvolutionReplayDriver.markSourceReadFailed}). */
+    sourceReadFailure?: string | undefined;
 }
 export interface ReplayWeights {
     accepted: number;
@@ -90,6 +96,12 @@ export declare class EvolutionReplayDriver {
      * clears it on a later clean read, so the qualification reflects the present
      * instead of latching for the driver lifetime. */
     private sourceCorrupt;
+    /** 0.18.1 (S3): the backfill READ itself failed — held as its message. A
+     * thrown read used to skip both markers, so `sourceCorrupt` kept whatever
+     * the previous read said and a failed read presented as a clean one. Cleared
+     * by any ANSWERED read; never sets `sourceCorrupt` (a failed read is not
+     * evidence that the bytes are corrupt). */
+    private sourceReadFailure;
     /** V26-05 (v25): plan ids recorded live BEFORE the backfill settled. A
      * plan-applied landing inside the one-shot `loadActivityState` read window is
      * recorded live AND persisted into the sidecar the backfill is reading —
@@ -155,6 +167,14 @@ export declare class EvolutionReplayDriver {
      * `apply()` emits at mark time.
      */
     markSourceReadable(): void;
+    /**
+     * 0.18.1 (S3): the backfill read THREW (io error, or a state the reader could
+     * not produce at all). Neither verdict applies — the bytes were never judged.
+     * Before this the throw skipped both markers and `compare()` returned an
+     * unqualified leaderboard, presenting a failed read as an answered one.
+     * @param reason - the failure's message, as thrown.
+     */
+    markSourceReadFailed(reason: string): void;
     compare(weights?: ReplayWeights): ReplayResult;
 }
 export declare const name = "evolution-replay";

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.18.0",
+  "version": "0.18.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,14 +27,14 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
-    "@lmzhen/dsh-evolution-activity": "^0.18.0",
-    "@lmzhen/dsh-evolution-core": "^0.18.0"
+    "@lmzhen/dsh-evolution-activity": "^0.18.1",
+    "@lmzhen/dsh-evolution-core": "^0.18.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1"
   },
   "devDependencies": {
-    "@lmzhen/dsh-evolution-activity": "^0.18.0",
-    "@lmzhen/dsh-evolution-core": "^0.18.0"
+    "@lmzhen/dsh-evolution-activity": "^0.18.1",
+    "@lmzhen/dsh-evolution-core": "^0.18.1"
   }
 }