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

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/storage/storage-json/README.md
-README.md: 383452b039f6190a523b8dcf969693e5e08a9456
-README.zh.md: 06cf35804abfea4c221fe966dc4d395d0ad5a707
+README.md: d36c6333392c3efe4462aebd82cf3ff9e76f66ae
+README.zh.md: 9c266537945941d4bc779a2cb1a349e2409f21dc

package/README.md

@@ -53,9 +53,9 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 ### Observable behavior
 
-A missing `single` file or `per-record` directory opens as an empty unit and materializes on the first write. In `single`, malformed content rejects with `malformed-medium`, and a different stored version rejects with `version-mismatch`. In `per-record`, each malformed, unreadable, or differently versioned document reads as an absent record, so one bad document does not reject the unit. Record keys must match `[a-zA-Z0-9_-]+`; an unsafe key rejects before any file operation. Every resolved write is durable, and operations after close reject with `closed`.
+A missing `single` file or `per-record` directory opens as an empty unit and materializes on the first write. In `single`, malformed content rejects with `malformed-medium`, and a different stored version rejects with `version-mismatch`. In `per-record`, each malformed or unreadable document, and each document whose version is outside the descriptor's current and compatible versions, reads as an absent record, so one bad document does not reject the unit. Record keys must match `[a-zA-Z0-9_-]+`; an unsafe key rejects before any file operation. Every resolved write is durable, and operations after close reject with `closed`.
 
-An empty `per-record` tree can initialize its declared tables from a valid `<root>/<unit>.json` whole-unit document. The backend leaves that source file unchanged. Any document path in a declared table, or a declared `global.json`, suppresses this initialization for the complete unit, even if that document is unreadable or stale.
+An empty `per-record` tree can initialize its declared tables from a valid `<root>/<unit>.json` whole-unit document only when the source unit name matches and its version is current or declared compatible. The backend leaves that source file unchanged and stamps migrated records with the current version. A source version outside the accepted set leaves the new tree empty. Any document path in a declared table, or a declared `global.json`, suppresses this initialization for the complete unit, even if that document is unreadable or stale.
 
 -----
 

package/README.zh.md

@@ -53,9 +53,9 @@ kind: "package-reference"
 
 ### 可观察行为
 
-缺失的 `single` 文件或 `per-record` 目录会作为空单元打开，并在第一次写入时物化。在 `single` 中，畸形内容以 `malformed-medium` 拒绝，不同的已存版本以 `version-mismatch` 拒绝。在 `per-record` 中，每份畸形、不可读或版本不同的文档都读作记录不存在，因此单个坏文档不会使单元被拒绝。记录键必须匹配 `[a-zA-Z0-9_-]+`；不安全的键在任何文件操作前被拒绝。每次已完成的写入都已持久化，关闭后的操作以 `closed` 拒绝。
+缺失的 `single` 文件或 `per-record` 目录会作为空单元打开，并在第一次写入时物化。在 `single` 中，畸形内容以 `malformed-medium` 拒绝，不同的已存版本以 `version-mismatch` 拒绝。在 `per-record` 中，每份畸形或不可读的文档，以及版本不在 descriptor 当前版本和兼容版本内的文档，都读作记录不存在，因此单个坏文档不会使单元被拒绝。记录键必须匹配 `[a-zA-Z0-9_-]+`；不安全的键在任何文件操作前被拒绝。每次已完成的写入都已持久化，关闭后的操作以 `closed` 拒绝。
 
-空的 `per-record` 目录树可以从有效的 `<root>/<unit>.json` 整单元文档初始化其已声明表。后端保持该源文件不变。已声明表中只要存在任意文档路径，或存在已声明的 `global.json`，就会对整个单元禁止该初始化，即使该文档不可读或版本陈旧。
+只有当源单元名称匹配，且源版本为当前版本或已声明的兼容版本时，空的 `per-record` 目录树才可以从有效的 `<root>/<unit>.json` 整单元文档初始化其已声明表。后端保持该源文件不变，并为迁移的记录写入当前版本戳。接受集合之外的源版本会使新目录树保持为空。已声明表中只要存在任意文档路径，或存在已声明的 `global.json`，就会对整个单元禁止该初始化，即使该文档不可读或版本陈旧。
 
 -----
 

package/lib/index.js

@@ -134,9 +134,9 @@ function serializeRecord(version, value) {
 * Parse one per-record document, validating its version stamp. A 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).
+* must not brick the whole unit, and an unaccepted version stamp discards the
+* record instead of migrating it (the whole-unit format rejects instead,
+* because there is exactly one document).
 * @param text - Raw per-record document content.
 * @param versions - Accepted unit versions (the current one plus the
 * descriptor's compatibleVersions); any other stamp discards the
@@ -285,8 +285,8 @@ var SingleJsonUnit = class {
 * Per-record contract: a record document that is malformed or stamped with a
 * 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
+* file never bricks the whole unit, and an unaccepted version stamp discards
+* the record instead of migrating it. 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
@@ -316,7 +316,7 @@ async function openPerRecordUnit(descriptor, root, onClose) {
 * Read every record document under the unit directory: each declared table's
 * `<key>.json` files plus `global.json`. A missing directory is the empty
 * unit (materialization defers to the first write); a foreign document
-* (missing, malformed, or stamped with another version) reads as an absent
+* (missing, malformed, or stamped with an unaccepted version) reads as an absent
 * record, per the per-record contract.
 * @param descriptor - Static identity and shape of the unit.
 * @param dir - Absolute unit directory path.

package/lib/types/format.d.ts

@@ -41,9 +41,9 @@ 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 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).
+ * must not brick the whole unit, and an unaccepted version stamp discards the
+ * record instead of migrating it (the whole-unit format rejects instead,
+ * because there is exactly one document).
  * @param text - Raw per-record document content.
  * @param versions - Accepted unit versions (the current one plus the
  * descriptor's compatibleVersions); any other stamp discards the

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

@@ -12,8 +12,8 @@
  * Per-record contract: a record document that is malformed or stamped with a
  * 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
+ * file never bricks the whole unit, and an unaccepted version stamp discards
+ * the record instead of migrating it. 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

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.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,14 +27,14 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-storage": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-storage": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   }
 }