@deepseek-ai/dsh-storage-json 0.1.2-alpha.4 → 0.1.2-alpha.5

package/lib/index.js

@@ -132,16 +132,18 @@ function serializeRecord(version, value) {
 }
 /**
 * Parse one per-record document, validating its version stamp. A document
-* that is malformed or stamped with a different version is FOREIGN and reads
-* as absent — the per-record contract: one bad or stale record file must not
-* brick the whole unit, and a version bump discards stale records instead of
-* migrating them (the whole-unit format rejects instead, because there is
-* exactly one document).
+* that is malformed or stamped with an unaccepted version is FOREIGN and
+* reads as absent — the per-record contract: one bad or stale record file
+* must not brick the whole unit, and a version bump discards stale records
+* instead of migrating them (the whole-unit format rejects instead, because
+* there is exactly one document).
 * @param text - Raw per-record document content.
-* @param version - Expected unit version; a mismatch discards the document.
+* @param versions - Accepted unit versions (the current one plus the
+* descriptor's compatibleVersions); any other stamp discards the
+* document.
 * @returns the record value, or `undefined` for a foreign document.
 */
-function parseRecord(text, version) {
+function parseRecord(text, versions) {
 	let document;
 	try {
 		document = JSON.parse(text);
@@ -150,7 +152,7 @@ function parseRecord(text, version) {
 	}
 	if (typeof document !== "object" || document === null) return void 0;
 	const { version: stamped, record } = document;
-	if (stamped !== version) return void 0;
+	if (typeof stamped !== "number" || !versions.includes(stamped)) return void 0;
 	return record;
 }
 //#endregion
@@ -281,15 +283,18 @@ var SingleJsonUnit = class {
 * memory unchanged.
 *
 * Per-record contract: a record document that is malformed or stamped with a
-* different version reads as an absent record — one bad or stale file never
-* bricks the whole unit, and a version bump discards stale records instead
-* of migrating them. Record keys become path segments, so they must be
-* path-safe (`[a-zA-Z0-9_-]+`); an unsafe key rejects at write.
+* version outside the accepted set (the descriptor's current version plus
+* its `compatibleVersions`) reads as an absent record — one bad or stale
+* file never bricks the whole unit, and a version bump discards stale
+* records instead of migrating them. Record keys become path segments, so
+* they must be path-safe (`[a-zA-Z0-9_-]+`); an unsafe key rejects at write.
 *
 * Legacy bootstrap: when the new tree has no document path, a legacy
 * whole-unit file `<root>/<name>.json` (the pre-per-record layout) seeds
-* per-record documents. Any new document path, including one whose contents
-* are unreadable or stale, suppresses the bootstrap for the whole unit. The
+* per-record documents, provided its stored unit version is in the accepted
+* set — a legacy file stamped with any other version is left alone and reads
+* as the empty unit. Any new document path, including one whose contents are
+* unreadable or stale, suppresses the bootstrap for the whole unit. The
 * legacy file is never changed or deleted.
 * @module @deepseek-ai/dsh-storage-json/src/per-record-unit
 */
@@ -318,6 +323,7 @@ async function openPerRecordUnit(descriptor, root, onClose) {
 * @returns the authoritative state reconstructed from the tree.
 */
 async function loadPerRecordState(descriptor, dir) {
+	const versions = acceptedStamps(descriptor);
 	const state = {
 		version: descriptor.version,
 		global: null,
@@ -332,10 +338,10 @@ async function loadPerRecordState(descriptor, dir) {
 	if (!(entries === void 0 ? false : (await Promise.all(entries.map(async (entry) => {
 		if (entry.isDirectory()) {
 			const records = state.tables.get(entry.name);
-			if (records !== void 0) return loadTableRecords(records, descriptor.version, join(dir, entry.name));
+			if (records !== void 0) return loadTableRecords(records, versions, join(dir, entry.name));
 		}
 		if (entry.name === "global.json" && descriptor.hasGlobal) {
-			const global = await readRecord(join(dir, entry.name), descriptor.version);
+			const global = await readRecord(join(dir, entry.name), versions);
 			if (global !== void 0) state.global = global;
 			return true;
 		}
@@ -343,12 +349,20 @@ async function loadPerRecordState(descriptor, dir) {
 	}))).some(Boolean))) await bootstrapLegacyUnit(descriptor, dir, state);
 	return state;
 }
+/** The version stamps this unit reads as its own: current plus declared compatible versions. */
+function acceptedStamps(descriptor) {
+	return [descriptor.version, ...descriptor.compatibleVersions ?? []];
+}
 /**
 * Bootstrap an empty per-record tree from a legacy whole-unit file
 * (`<root>/<name>.json`, the pre-per-record layout). Every declared-table
 * record is copied into a current-version document, while the legacy file is
 * retained unchanged. A missing, foreign (another unit's name), malformed,
-* or non-unit legacy file is left alone; other read failures propagate.
+* or non-unit legacy file is left alone, and so is one whose stored unit
+* version is outside the accepted set — migrating records the owner never
+* vouched for would stamp them with the current version and turn a
+* discardable stale cache into schema failures at the domain layer. Other
+* read failures propagate.
 * @param descriptor - Static identity and shape of the unit.
 * @param dir - The per-record unit directory (`<root>/<name>`).
 * @param state - The empty tree state; bootstrapped records are added.
@@ -369,6 +383,8 @@ async function bootstrapLegacyUnit(descriptor, dir, state) {
 		return;
 	}
 	if (document.unit?.name !== descriptor.name) return;
+	const stamped = document.unit.version;
+	if (typeof stamped !== "number" || !acceptedStamps(descriptor).includes(stamped)) return;
 	const tables = document.tables;
 	if (typeof tables !== "object" || tables === null) return;
 	const recordsByTable = tables;
@@ -391,23 +407,23 @@ async function bootstrapLegacyUnit(descriptor, dir, state) {
 * @returns whether the directory contains any `.json` document path,
 * independently of key safety, readability, or stored version.
 */
-async function loadTableRecords(records, version, dir) {
+async function loadTableRecords(records, versions, dir) {
 	const files = await readdir(dir, { withFileTypes: true });
 	const hasDocuments = files.some((file) => file.name.endsWith(".json"));
 	const loaded = await Promise.all(files.map(async (file) => {
 		if (!file.name.endsWith(".json")) return;
 		const key = file.name.slice(0, -5);
 		if (!SAFE_KEY_RE.test(key)) return;
-		const record = await readRecord(join(dir, file.name), version);
+		const record = await readRecord(join(dir, file.name), versions);
 		if (record !== void 0) return [key, record];
 	}));
 	for (const record of loaded) if (record !== void 0) records.set(...record);
 	return hasDocuments;
 }
 /** Read one record document; a foreign (unreadable or stale) one reads as absent. */
-async function readRecord(path, version) {
+async function readRecord(path, versions) {
 	try {
-		return parseRecord(await readFile(path, "utf8"), version);
+		return parseRecord(await readFile(path, "utf8"), versions);
 	} catch {
 		return;
 	}
@@ -453,6 +469,21 @@ var PerRecordJsonUnit = class {
 		assertSafeKey(this.descriptor.name, key);
 		await this.tracked(rm(join(this.tableDir(table), `${key}.json`), { force: true }));
 	}
+	/**
+	* Move one record's document aside as `<key>.json.bak.<YYYYMMDDHHmm>`. The
+	* moved file no longer ends in `.json`, so every later read ignores it; the
+	* bytes stay on disk for inspection. A same-minute backup of the same
+	* key overwrites the previous backup (the newer bytes are the ones worth
+	* keeping).
+	*/
+	async backupRecord(table, key) {
+		this.assertOpen();
+		assertSafeKey(this.descriptor.name, key);
+		const path = join(this.tableDir(table), `${key}.json`);
+		const moved = `${path}.bak.${backupStamp(/* @__PURE__ */ new Date())}`;
+		await this.tracked(rename(path, moved));
+		return moved;
+	}
 	/** Durably replace the global singleton. Only valid when declared. */
 	async setGlobal(value) {
 		this.assertOpen();
@@ -494,6 +525,11 @@ var PerRecordJsonUnit = class {
 		return write;
 	}
 };
+/** Local-time `YYYYMMDDHHmm` suffix for backed-up documents. */
+function backupStamp(now) {
+	const pad = (value) => String(value).padStart(2, "0");
+	return `${String(now.getFullYear())}${pad(now.getMonth() + 1)}${pad(now.getDate())}${pad(now.getHours())}${pad(now.getMinutes())}`;
+}
 /** Reject a record key that would be unsafe as a path segment. */
 function assertSafeKey(unit, key) {
 	if (!SAFE_KEY_RE.test(key)) throw new Error(`unit '${unit}': per-record key '${key}' is not path-safe (must match ${SAFE_KEY_RE})`);

package/lib/types/format.d.ts

@@ -39,14 +39,16 @@ export declare function parse(text: string, descriptor: KvUnitDescriptor): UnitS
 export declare function serializeRecord(version: number, value: unknown): string;
 /**
  * Parse one per-record document, validating its version stamp. A document
- * that is malformed or stamped with a different version is FOREIGN and reads
- * as absent — the per-record contract: one bad or stale record file must not
- * brick the whole unit, and a version bump discards stale records instead of
- * migrating them (the whole-unit format rejects instead, because there is
- * exactly one document).
+ * that is malformed or stamped with an unaccepted version is FOREIGN and
+ * reads as absent — the per-record contract: one bad or stale record file
+ * must not brick the whole unit, and a version bump discards stale records
+ * instead of migrating them (the whole-unit format rejects instead, because
+ * there is exactly one document).
  * @param text - Raw per-record document content.
- * @param version - Expected unit version; a mismatch discards the document.
+ * @param versions - Accepted unit versions (the current one plus the
+ * descriptor's compatibleVersions); any other stamp discards the
+ * document.
  * @returns the record value, or `undefined` for a foreign document.
  */
-export declare function parseRecord(text: string, version: number): unknown;
+export declare function parseRecord(text: string, versions: readonly number[]): unknown;
 //# sourceMappingURL=format.d.ts.map

package/lib/types/per-record-unit.d.ts

@@ -10,15 +10,18 @@
  * memory unchanged.
  *
  * Per-record contract: a record document that is malformed or stamped with a
- * different version reads as an absent record — one bad or stale file never
- * bricks the whole unit, and a version bump discards stale records instead
- * of migrating them. Record keys become path segments, so they must be
- * path-safe (`[a-zA-Z0-9_-]+`); an unsafe key rejects at write.
+ * version outside the accepted set (the descriptor's current version plus
+ * its `compatibleVersions`) reads as an absent record — one bad or stale
+ * file never bricks the whole unit, and a version bump discards stale
+ * records instead of migrating them. Record keys become path segments, so
+ * they must be path-safe (`[a-zA-Z0-9_-]+`); an unsafe key rejects at write.
  *
  * Legacy bootstrap: when the new tree has no document path, a legacy
  * whole-unit file `<root>/<name>.json` (the pre-per-record layout) seeds
- * per-record documents. Any new document path, including one whose contents
- * are unreadable or stale, suppresses the bootstrap for the whole unit. The
+ * per-record documents, provided its stored unit version is in the accepted
+ * set — a legacy file stamped with any other version is left alone and reads
+ * as the empty unit. Any new document path, including one whose contents are
+ * unreadable or stale, suppresses the bootstrap for the whole unit. The
  * legacy file is never changed or deleted.
  * @module @deepseek-ai/dsh-storage-json/src/per-record-unit
  */
@@ -56,6 +59,14 @@ export declare class PerRecordJsonUnit implements KvUnit {
     putRecord(table: string, key: string, value: unknown): Promise<void>;
     /** Durably delete one record. Idempotent: a missing key is a no-op. */
     deleteRecord(table: string, key: string): Promise<void>;
+    /**
+     * Move one record's document aside as `<key>.json.bak.<YYYYMMDDHHmm>`. The
+     * moved file no longer ends in `.json`, so every later read ignores it; the
+     * bytes stay on disk for inspection. A same-minute backup of the same
+     * key overwrites the previous backup (the newer bytes are the ones worth
+     * keeping).
+     */
+    backupRecord(table: string, key: string): Promise<string>;
     /** Durably replace the global singleton. Only valid when declared. */
     setGlobal(value: unknown): Promise<void>;
     /** Drain in-flight writes and release the unit. Idempotent. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-storage-json",
   "description": "JSON file KV storage backend for the DeepSeek Harness storage hub",
-  "version": "0.1.2-alpha.4",
+  "version": "0.1.2-alpha.5",
   "publishConfig": {
     "access": "public"
   },
@@ -27,14 +27,14 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.5",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.5",
     "@deepseek-ai/cordis": "^4.0.2"
   }
 }