Skip to content

Align serialization docs with schema version 6 #261

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ExplodingUFO merged 1 commit into from
May 14, 2026
Merged

Align serialization docs with schema version 6 #261

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/en/serialization-contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ This is the pre-1.0 serialization contract. It is explicit and intentionally nar
- `Description`
- `RootGraphId`
- `GraphScopes`
- Current workspace/document schema version is `5`.
- Current workspace/document schema version is `6`.
- Read behavior accepts:
- unversioned legacy payloads (best-effort compatibility path), and
- `SchemaVersion` values from `1` through `5`.
- `SchemaVersion` values from `1` through `6`.
- Read behavior rejects unknown/future schema versions.

## Fragment and clipboard payloads
Expand Down
10 changes: 5 additions & 5 deletions docs/zh-CN/serialization-contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
- `GraphWorkspaceService` 的实现直接调用：
- `GraphDocumentSerializer.Save(document, WorkspacePath)`
- `GraphDocumentSerializer.Load(WorkspacePath)`
- `GraphDocumentSerializer` 的写入 payload 的版本为 `SchemaVersion = 5`，由 `GraphDocumentCompatibility.CurrentSchemaVersion` 固定。
- `GraphDocumentSerializer` 的写入 payload 的版本为 `SchemaVersion = 6`，由 `GraphDocumentCompatibility.CurrentSchemaVersion` 固定。

## 工作区文档写入 envelope（canonical）

Expand All @@ -24,10 +24,10 @@

- 读取时：
- 若 JSON 中没有 `SchemaVersion`，按旧版无版本 payload 兼容路径反序列化。
- 若有 `SchemaVersion`，只接受 `1` 到 `5` 的版本号。
- `5`：按当前 schema payload 解析。
- `1`-`4`：按旧版 schema payload 解析并归一化。
- 版本号 `< 1` 或 `> 5` 时抛出 `InvalidOperationException`，即视为不支持。
- 若有 `SchemaVersion`，只接受 `1` 到 `6` 的版本号。
- `6`：按当前 schema payload 解析。
- `1`-`5`：按旧版 schema payload 解析并归一化。
- 版本号 `< 1` 或 `> 6` 时抛出 `InvalidOperationException`，即视为不支持。

## 片段/剪贴板序列化边界（独立于工作区）

Expand Down
8 changes: 4 additions & 4 deletions tests/AsterGraph.Demo.Tests/SerializationContractDocsTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ public void SerializationContractDocs_DefendWorkspaceSchemaVersioningAndHostInte
var hostIntegrationEn = ReadRepoFile("docs/en/host-integration.md");
var hostIntegrationZh = ReadRepoFile("docs/zh-CN/host-integration.md");

Assert.Contains("Current workspace/document schema version is `5`", serializationContractEn, StringComparison.Ordinal);
Assert.Contains("Current workspace/document schema version is `6`", serializationContractEn, StringComparison.Ordinal);
Assert.Contains("Canonical write envelope for workspace documents is:", serializationContractEn, StringComparison.Ordinal);
Assert.Contains("- `SchemaVersion`", serializationContractEn, StringComparison.Ordinal);
Assert.Contains("- `Title`", serializationContractEn, StringComparison.Ordinal);
Expand All @@ -23,7 +23,7 @@ public void SerializationContractDocs_DefendWorkspaceSchemaVersioningAndHostInte
Assert.Contains("- `GraphScopes`", serializationContractEn, StringComparison.Ordinal);
Assert.Contains("Read behavior accepts:", serializationContractEn, StringComparison.Ordinal);
Assert.Contains("unversioned legacy payloads", serializationContractEn, StringComparison.OrdinalIgnoreCase);
Assert.Contains("`SchemaVersion` values from `1` through `5`", serializationContractEn, StringComparison.Ordinal);
Assert.Contains("`SchemaVersion` values from `1` through `6`", serializationContractEn, StringComparison.Ordinal);
Assert.Contains("unknown/future schema versions", serializationContractEn, StringComparison.OrdinalIgnoreCase);
Assert.Contains("Clipboard and fragment payload versioning is separate from workspace-document versioning", serializationContractEn, StringComparison.Ordinal);

Expand All @@ -32,8 +32,8 @@ public void SerializationContractDocs_DefendWorkspaceSchemaVersioningAndHostInte
Assert.Contains("`RootGraphId`", serializationContractZh, StringComparison.Ordinal);
Assert.Contains("`GraphScopes`", serializationContractZh, StringComparison.Ordinal);
Assert.Contains("若 JSON 中没有 `SchemaVersion`，按旧版无版本 payload 兼容路径反序列化。", serializationContractZh, StringComparison.Ordinal);
Assert.Contains("若有 `SchemaVersion`，只接受 `1` 到 `5` 的版本号。", serializationContractZh, StringComparison.Ordinal);
Assert.Contains("版本号 `< 1` 或 `> 5` 时抛出 `InvalidOperationException`", serializationContractZh, StringComparison.Ordinal);
Assert.Contains("若有 `SchemaVersion`，只接受 `1` 到 `6` 的版本号。", serializationContractZh, StringComparison.Ordinal);
Assert.Contains("版本号 `< 1` 或 `> 6` 时抛出 `InvalidOperationException`", serializationContractZh, StringComparison.Ordinal);
Assert.Contains("片段/剪贴板路径使用独立的 payload 契约与版本控制，不复用工作区文档 `SchemaVersion`。", serializationContractZh, StringComparison.Ordinal);
Assert.Contains("`GraphDocumentSerializer` 写入 payload 的 JSON 字段固定为：", serializationContractZh, StringComparison.Ordinal);

Expand Down
Loading