@lmzhen/dsh-evolution-activity 0.3.81 → 0.3.82

package/lib/index.js

@@ -69,24 +69,57 @@ function parseActivityContent(raw) {
 	}
 }
 /**
+* H-06: the read barrier over the sidecar, with the corruption verdict.
+*
+* @param root - the evolution state root (the sidecar lives under it).
+* @param io - the IO provider to read through.
+* @returns the parsed records and whether the bytes were readable.
+*/
+async function loadActivityState(root, io) {
+	const raw = await io.readText(activityFile(root));
+	return {
+		records: parseActivityContent(raw),
+		corrupt: isCorruptActivity(raw)
+	};
+}
+/**
 * H-06: the read barrier over the sidecar. V24-13 (v24): `loadActivity` now
 * HAS a production consumer — `evolution-replay` backfills its `/evolution
 * replay` leaderboard from this store at mount (the two packages'
 * "persistence is the activity store's job" contract is actually wired
 * through this call). The single-writer rule is unchanged: `apply()`'s
-* transact listener remains the only WRITE path.
+* transact listener remains the only WRITE path. Consumers that must not read
+* an unreadable sidecar as "no history" use {@link loadActivityState}.
 */
 async function loadActivity(root, io) {
-	return parseActivityContent(await io.readText(activityFile(root)));
+	return (await loadActivityState(root, io)).records;
 }
 /** True when bytes exist but are not a readable activity envelope: unparsable
 * JSON, or a missing `items` array (a scalar/array/other-shaped file). A missing
 * file (null) is NOT corruption — it is a first write. */
+/**
+* v43 audit (H-3 / J-6 / FLOW6-6): an UNSUPPORTED version is corrupt for this
+* writer. The read side has always ignored `version` and taken `items` as-is,
+* so a future-version sidecar used to fold fine and then be rewritten as
+* `version: ACTIVITY_FILE_VERSION` on the next append — a silent downgrade that
+* destroyed whatever the newer format carried. This guard is the write side's
+* half of the pair: unknown version ⇒ the original bytes are quarantined (the
+* existing `.corrupt` path) before a current-version file replaces them, which
+* is the posture `evolution-events` already takes for the same shape.
+* Residual, closed by FLOW6-6: `parseActivityContent` still answers `[]` for
+* such a file, but {@link loadActivityState} now carries the verdict beside the
+* records, so a read-only consumer can distinguish "newer format" from "no
+* history" instead of presenting a partial view as the recorded truth.
+* @internal Exported for this package's own tests (siblings `parseActivityContent`
+* and `serializeActivity` are exported for the same reason).
+*/
 function isCorruptActivity(raw) {
 	if (raw === null) return false;
 	try {
 		const parsed = JSON.parse(raw);
-		return typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.items);
+		if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.items)) return true;
+		const version = parsed.version;
+		return version !== void 0 && version !== 2;
 	} catch {
 		return true;
 	}
@@ -128,4 +161,4 @@ function apply(ctx, rawConfig = {}) {
 	});
 }
 //#endregion
-export { ACTIVITY_FILE_VERSION, Config, DEFAULT_MAX_ITEMS, activityFile, apply, applyActivityEvent, loadActivity, name, parseActivityContent, serializeActivity };
+export { ACTIVITY_FILE_VERSION, Config, DEFAULT_MAX_ITEMS, activityFile, apply, applyActivityEvent, isCorruptActivity, loadActivity, loadActivityState, name, parseActivityContent, serializeActivity };

package/lib/types/index.d.ts

@@ -60,7 +60,58 @@ export declare function parseActivityContent(raw: string | null): EvolutionActiv
  * through this call). The single-writer rule is unchanged: `apply()`'s
  * transact listener remains the only WRITE path.
  */
+/**
+ * FLOW6-6 (v43, the read side of H-3): the sidecar's records PLUS whether the
+ * bytes could be read as THIS format. `parseActivityContent` answers `[]` for
+ * a future-version or unparsable file, so a read-only consumer could not tell
+ * "newer format" from "no history" and presented a partial/empty view as the
+ * recorded truth. The write side already quarantines those bytes
+ * ({@link isCorruptActivity}); this is the channel the readers were missing.
+ */
+export interface ActivityLoad {
+    records: EvolutionActivityRecord[];
+    /** Bytes exist but are not a readable current-version envelope. A MISSING
+     * file is not corruption — it is a first write. */
+    corrupt: boolean;
+}
+/**
+ * H-06: the read barrier over the sidecar, with the corruption verdict.
+ *
+ * @param root - the evolution state root (the sidecar lives under it).
+ * @param io - the IO provider to read through.
+ * @returns the parsed records and whether the bytes were readable.
+ */
+export declare function loadActivityState(root: string, io: EvolutionIoLike): Promise<ActivityLoad>;
+/**
+ * H-06: the read barrier over the sidecar. V24-13 (v24): `loadActivity` now
+ * HAS a production consumer — `evolution-replay` backfills its `/evolution
+ * replay` leaderboard from this store at mount (the two packages'
+ * "persistence is the activity store's job" contract is actually wired
+ * through this call). The single-writer rule is unchanged: `apply()`'s
+ * transact listener remains the only WRITE path. Consumers that must not read
+ * an unreadable sidecar as "no history" use {@link loadActivityState}.
+ */
 export declare function loadActivity(root: string, io: EvolutionIoLike): Promise<EvolutionActivityRecord[]>;
+/** True when bytes exist but are not a readable activity envelope: unparsable
+ * JSON, or a missing `items` array (a scalar/array/other-shaped file). A missing
+ * file (null) is NOT corruption — it is a first write. */
+/**
+ * v43 audit (H-3 / J-6 / FLOW6-6): an UNSUPPORTED version is corrupt for this
+ * writer. The read side has always ignored `version` and taken `items` as-is,
+ * so a future-version sidecar used to fold fine and then be rewritten as
+ * `version: ACTIVITY_FILE_VERSION` on the next append — a silent downgrade that
+ * destroyed whatever the newer format carried. This guard is the write side's
+ * half of the pair: unknown version ⇒ the original bytes are quarantined (the
+ * existing `.corrupt` path) before a current-version file replaces them, which
+ * is the posture `evolution-events` already takes for the same shape.
+ * Residual, closed by FLOW6-6: `parseActivityContent` still answers `[]` for
+ * such a file, but {@link loadActivityState} now carries the verdict beside the
+ * records, so a read-only consumer can distinguish "newer format" from "no
+ * history" instead of presenting a partial view as the recorded truth.
+ * @internal Exported for this package's own tests (siblings `parseActivityContent`
+ * and `serializeActivity` are exported for the same reason).
+ */
+export declare function isCorruptActivity(raw: string | null): boolean;
 export declare const name = "evolution-activity";
 export interface Config {
     /** Bounded sidecar: how many recent outcomes are kept. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-activity",
   "description": "Durable activity store for self-evolution plan outcomes (community build)",
-  "version": "0.3.81",
+  "version": "0.3.82",
   "publishConfig": {
     "access": "public"
   },
@@ -27,15 +27,15 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.81"
+    "@lmzhen/dsh-evolution-core": "^0.3.82"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.81",
-    "@lmzhen/dsh-evolution-io": "^0.3.81",
-    "@lmzhen/dsh-evolution-io-node": "^0.3.81"
+    "@lmzhen/dsh-evolution-core": "^0.3.82",
+    "@lmzhen/dsh-evolution-io": "^0.3.82",
+    "@lmzhen/dsh-evolution-io-node": "^0.3.82"
   }
 }