You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d1def68
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: structure/09_client-integrations.md
+13Lines changed: 13 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -41,6 +41,19 @@ added only to a writer would let a mutation bypass the state users saw.
41
41
`fileFingerprint` records the exact whole-file result for restore and for serializers that may lose
42
42
comments. `blockFingerprint` records the exact generated contribution and detects catalog, model,
43
43
port, or provider drift. `fragmentPaths` bounds disable to the paths OpenCodex actually created.
44
+
New records pair the exact contribution fingerprints with semantic fingerprints that recursively
45
+
sort JSON object keys while preserving array order. Existing records without the semantic companion
46
+
fall back to comparing the recorded generated contribution when the catalog has not moved. This
47
+
keeps old records readable while preventing a client's formatting-only key reorder from
48
+
masquerading as a protected edit.
49
+
50
+
[Decision Log]
51
+
- 목적과 의도: Treat JSON object-key order as formatting while retaining safe ownership proof across upgrades.
52
+
- 기존 구현 및 제약 조건: Existing records contain order-sensitive hashes, and replacing their hash format in place would make every installed integration look foreign-edited.
53
+
- 검토한 주요 대안: Replace the hash format globally; ignore key order only for ZCode; store a semantic companion beside the existing exact hash.
54
+
- 선택한 방식: Preserve the exact hashes for compatibility and add object-key-independent semantic companions to new records, with a bounded desired-contribution fallback for old records.
55
+
- 다른 대안 대신 이 방식을 선택한 이유: A global replacement cannot validate old records, while a ZCode-only exception would leave the shared JSON ownership rule inconsistent.
56
+
- 장점, 단점 및 영향: New records tolerate key normalization even across catalog refreshes; old records recover when the recorded catalog is still reconstructible, and ambiguous old-record drift remains fail-closed.
44
57
45
58
Clients normally protect every field in every recorded fragment. A client that writes documented,
46
59
runtime-derived fields back into an owned fragment may additionally record:
0 commit comments