Skip to content

Commit d1def68

Browse files
authored
Merge pull request #2761 from lidge-jun/ingw/fix-zcode-key-order-2759
fix(integrations): ignore JSON object key order in ownership
2 parents 0821ce9 + 63941b5 commit d1def68

7 files changed

Lines changed: 239 additions & 17 deletions

File tree

‎src/integrations/ownership-policy.ts‎

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import {
1212
type ManagedContribution,
1313
type ManagedFragment,
1414
} from "../clients/config-export";
15-
import { canonicalContribution, fingerprint } from "./ownership";
15+
import { canonicalContribution, fingerprint, semanticContribution } from "./ownership";
1616

1717
type JsonObject = Record<string, unknown>;
1818

@@ -124,11 +124,10 @@ export function validRefreshablePaths(
124124
});
125125
}
126126

127-
/** Fingerprint a contribution after removing only its explicitly refreshable paths. */
128-
export function protectedContributionFingerprint(
127+
function contributionWithoutRefreshablePaths(
129128
contribution: ManagedContribution,
130129
refreshablePaths: readonly (readonly string[])[],
131-
): string {
130+
): ManagedContribution {
132131
const fragments = contribution.fragments.map(cloneFragment);
133132
for (const refreshablePath of refreshablePaths) {
134133
for (const fragment of fragments) {
@@ -137,5 +136,25 @@ export function protectedContributionFingerprint(
137136
break;
138137
}
139138
}
140-
return fingerprint(canonicalContribution({ ...contribution, fragments }));
139+
return { ...contribution, fragments };
140+
}
141+
142+
/** Fingerprint a contribution after removing only its explicitly refreshable paths. */
143+
export function protectedContributionFingerprint(
144+
contribution: ManagedContribution,
145+
refreshablePaths: readonly (readonly string[])[],
146+
): string {
147+
return fingerprint(canonicalContribution(
148+
contributionWithoutRefreshablePaths(contribution, refreshablePaths),
149+
));
150+
}
151+
152+
/** Semantic protected fingerprint that ignores JSON object-key order only. */
153+
export function semanticProtectedContributionFingerprint(
154+
contribution: ManagedContribution,
155+
refreshablePaths: readonly (readonly string[])[],
156+
): string {
157+
return fingerprint(semanticContribution(
158+
contributionWithoutRefreshablePaths(contribution, refreshablePaths),
159+
));
141160
}

‎src/integrations/ownership.ts‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,38 @@ export function fingerprint(text: string): string {
2222
}
2323

2424
/**
25-
* Canonical bytes of a contribution. Fragments are sorted by path so two builds
26-
* of the same contribution hash identically regardless of emission order.
25+
* Canonicalize JSON object members recursively for semantic comparisons.
26+
* Arrays stay ordered because their position can carry configuration meaning.
27+
*/
28+
function semanticJsonValue(value: unknown): unknown {
29+
if (Array.isArray(value)) return value.map(semanticJsonValue);
30+
if (value === null || typeof value !== "object") return value;
31+
32+
const record = value as Record<string, unknown>;
33+
return Object.fromEntries(
34+
Object.keys(record)
35+
.sort()
36+
.map(key => [key, semanticJsonValue(record[key])]),
37+
);
38+
}
39+
40+
/**
41+
* Stable semantic bytes of a contribution. Third-party clients may
42+
* re-serialize JSON object members in a different order; that formatting-only
43+
* rewrite must not look like a protected-value edit.
44+
*/
45+
export function semanticContribution(contribution: ManagedContribution): string {
46+
const sorted = [...contribution.fragments].sort((a, b) => {
47+
const left = a.path.join("\u0000");
48+
const right = b.path.join("\u0000");
49+
return left < right ? -1 : left > right ? 1 : 0;
50+
});
51+
return JSON.stringify(sorted.map(fragment => [fragment.path, semanticJsonValue(fragment.value)]));
52+
}
53+
54+
/**
55+
* Legacy-compatible bytes used by existing persisted fingerprints. Fragment
56+
* paths are stable, while nested object insertion order remains exact.
2757
*/
2858
export function canonicalContribution(contribution: ManagedContribution): string {
2959
const sorted = [...contribution.fragments].sort((a, b) => {
@@ -41,11 +71,15 @@ export interface OwnershipRecord {
4171
fileFingerprint: string;
4272
/** Hash of our contribution — detects catalog/port drift. */
4373
blockFingerprint: string;
74+
/** Key-order-independent companion for JSON clients that normalize objects. */
75+
semanticBlockFingerprint?: string;
4476
/**
4577
* Hash of the fields the client must not rewrite. Present only when a
4678
* client has explicitly declared runtime-derived paths below.
4779
*/
4880
protectedBlockFingerprint?: string;
81+
/** Key-order-independent companion to `protectedBlockFingerprint`. */
82+
semanticProtectedBlockFingerprint?: string;
4983
/**
5084
* Exact document paths a client may derive after apply. These are recorded
5185
* per operation so later catalog changes cannot widen an older grant.

‎src/integrations/state.ts‎

Lines changed: 40 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,11 @@ import { ClientPathError, EXPORT_CLIENTS, opencodeProxyBaseUrl, type ExportModel
1212
import type { OcxConfig } from "../types";
1313
import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
1414
import { SNAPSHOT_RETENTION } from "./journal";
15-
import { canonicalContribution, fingerprint, type OwnershipRecord } from "./ownership";
15+
import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
1616
import {
1717
protectedContributionFingerprint,
1818
refreshablePathsOf,
19+
semanticProtectedContributionFingerprint,
1920
validRefreshablePaths,
2021
} from "./ownership-policy";
2122
import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
@@ -153,21 +154,49 @@ function recordedBlockIsOwned(
153154
if (!observed) return false;
154155
if (fingerprint(canonicalContribution(observed)) === record.blockFingerprint) return true;
155156

157+
const observedSemanticFingerprint = fingerprint(semanticContribution(observed));
158+
if (
159+
typeof record.semanticBlockFingerprint === "string"
160+
&& observedSemanticFingerprint === record.semanticBlockFingerprint
161+
) return true;
162+
163+
const desiredFingerprint = fingerprint(canonicalContribution(desired));
164+
if (
165+
desiredFingerprint === record.blockFingerprint
166+
&& observedSemanticFingerprint === fingerprint(semanticContribution(desired))
167+
) return true;
168+
156169
if (
157170
typeof record.protectedBlockFingerprint === "string"
158171
&& validRefreshablePaths(observed, record.refreshablePaths)
159172
&& record.refreshablePaths.length > 0
160173
) {
161-
return protectedContributionFingerprint(observed, record.refreshablePaths)
162-
=== record.protectedBlockFingerprint;
174+
const observedProtectedFingerprint = protectedContributionFingerprint(
175+
observed,
176+
record.refreshablePaths,
177+
);
178+
if (observedProtectedFingerprint === record.protectedBlockFingerprint) return true;
179+
180+
const observedSemanticProtectedFingerprint = semanticProtectedContributionFingerprint(
181+
observed,
182+
record.refreshablePaths,
183+
);
184+
if (
185+
typeof record.semanticProtectedBlockFingerprint === "string"
186+
&& observedSemanticProtectedFingerprint === record.semanticProtectedBlockFingerprint
187+
) return true;
188+
189+
return protectedContributionFingerprint(desired, record.refreshablePaths)
190+
=== record.protectedBlockFingerprint
191+
&& observedSemanticProtectedFingerprint
192+
=== semanticProtectedContributionFingerprint(desired, record.refreshablePaths);
163193
}
164194

165-
const desiredFingerprint = fingerprint(canonicalContribution(desired));
166195
if (desiredFingerprint !== record.blockFingerprint) return false;
167196
const legacyPaths = refreshablePathsOf(desired);
168197
return legacyPaths.length > 0
169-
&& protectedContributionFingerprint(observed, legacyPaths)
170-
=== protectedContributionFingerprint(desired, legacyPaths);
198+
&& semanticProtectedContributionFingerprint(observed, legacyPaths)
199+
=== semanticProtectedContributionFingerprint(desired, legacyPaths);
171200
}
172201

173202
/**
@@ -257,7 +286,11 @@ export function classifyIntegration(input: {
257286
}
258287
return { state: "stale" };
259288
}
260-
return input.record.blockFingerprint === fingerprint(canonicalContribution(input.contribution))
289+
const desiredFingerprint = typeof input.record.semanticBlockFingerprint === "string"
290+
? fingerprint(semanticContribution(input.contribution))
291+
: fingerprint(canonicalContribution(input.contribution));
292+
const recordedFingerprint = input.record.semanticBlockFingerprint ?? input.record.blockFingerprint;
293+
return recordedFingerprint === desiredFingerprint
261294
? { state: "current" }
262295
: { state: "stale" };
263296
}

‎src/integrations/writer.ts‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,18 @@ import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../c
1515
import { isLoopbackHostname } from "../codex/inject";
1616
import type { OcxConfig } from "../types";
1717
import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
18-
import { fingerprint, canonicalContribution, fragmentPathsOf, type OwnershipRecord } from "./ownership";
19-
import { protectedContributionFingerprint, refreshablePathsOf } from "./ownership-policy";
18+
import {
19+
fingerprint,
20+
canonicalContribution,
21+
fragmentPathsOf,
22+
semanticContribution,
23+
type OwnershipRecord,
24+
} from "./ownership";
25+
import {
26+
protectedContributionFingerprint,
27+
refreshablePathsOf,
28+
semanticProtectedContributionFingerprint,
29+
} from "./ownership-policy";
2030
import { createdContainerPaths, mergeContribution, removeFragments } from "./merge";
2131
import { INTEGRATION_CLIENTS, isLoopbackOnly, type IntegrationClientId } from "./registry";
2232
import { classifyIntegration, exportContextOf } from "./state";
@@ -361,8 +371,13 @@ function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: bo
361371
record: {
362372
clientId, configPath, fileFingerprint: fingerprint(text),
363373
blockFingerprint: fingerprint(canonicalContribution(contribution)),
374+
semanticBlockFingerprint: fingerprint(semanticContribution(contribution)),
364375
...(refreshablePaths.length > 0 ? {
365376
protectedBlockFingerprint: protectedContributionFingerprint(contribution, refreshablePaths),
377+
semanticProtectedBlockFingerprint: semanticProtectedContributionFingerprint(
378+
contribution,
379+
refreshablePaths,
380+
),
366381
refreshablePaths,
367382
} : {}),
368383
fragmentPaths: fragmentPathsOf(contribution), createdContainers: created,
@@ -556,7 +571,10 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
556571
? (restoredText === null ? "absent" : "conflict")
557572
: !recordDescribesBytes
558573
? "conflict"
559-
: restoredRecord.blockFingerprint === fingerprint(canonicalContribution(fresh))
574+
: (
575+
restoredRecord.semanticBlockFingerprint === fingerprint(semanticContribution(fresh))
576+
|| restoredRecord.blockFingerprint === fingerprint(canonicalContribution(fresh))
577+
)
560578
? "current"
561579
: "stale";
562580

‎structure/09_client-integrations.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,19 @@ added only to a writer would let a mutation bypass the state users saw.
4141
`fileFingerprint` records the exact whole-file result for restore and for serializers that may lose
4242
comments. `blockFingerprint` records the exact generated contribution and detects catalog, model,
4343
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.
4457

4558
Clients normally protect every field in every recorded fragment. A client that writes documented,
4659
runtime-derived fields back into an owned fragment may additionally record:

‎tests/integrations-state.test.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import { PARSE_FAILED, fileIO, loadTarget, parseConfig } from "../src/integratio
77
import { serializeDocument } from "../src/integrations/serialize";
88
import {
99
canonicalContribution,
10+
semanticContribution,
1011
fingerprint,
1112
writeRecord,
1213
type OwnershipRecord,
@@ -502,6 +503,46 @@ describe("classifier unit behavior", () => {
502503
const reversed = { ...contribution, fragments: [...contribution.fragments].reverse() };
503504
expect(canonicalContribution(reversed)).toBe(canonicalContribution(contribution));
504505
});
506+
507+
test("nested JSON object key order does not change the contribution fingerprint (#2759)", () => {
508+
const original = {
509+
clientId: "zcode" as const,
510+
fragments: [{
511+
path: ["provider", "opencodex"],
512+
value: {
513+
enabled: true,
514+
options: { apiKey: "loopback", baseURL: "http://127.0.0.1:10100/v1" },
515+
models: {
516+
routed: {
517+
modalities: { input: ["text", "image"], output: ["text"] },
518+
limit: { context: 350_000 },
519+
},
520+
},
521+
},
522+
}],
523+
};
524+
const reordered = {
525+
clientId: "zcode" as const,
526+
fragments: [{
527+
path: ["provider", "opencodex"],
528+
value: {
529+
models: {
530+
routed: {
531+
limit: { context: 350_000 },
532+
modalities: { output: ["text"], input: ["text", "image"] },
533+
},
534+
},
535+
options: { baseURL: "http://127.0.0.1:10100/v1", apiKey: "loopback" },
536+
enabled: true,
537+
},
538+
}],
539+
};
540+
541+
expect(semanticContribution(reordered)).toBe(semanticContribution(original));
542+
const reorderedArray = structuredClone(reordered);
543+
reorderedArray.fragments[0]!.value.models.routed.modalities.input = ["image", "text"];
544+
expect(semanticContribution(reorderedArray)).not.toBe(semanticContribution(original));
545+
});
505546
});
506547

507548
describe("ownership is scoped to recorded fragments", () => {

‎tests/integrations-writer.test.ts‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,16 @@ function input(overrides: Partial<IntegrationWriteInput> = {}): IntegrationWrite
119119
};
120120
}
121121

122+
function reverseJsonObjectKeys(value: unknown): unknown {
123+
if (Array.isArray(value)) return value.map(reverseJsonObjectKeys);
124+
if (value === null || typeof value !== "object") return value;
125+
return Object.fromEntries(
126+
Object.entries(value as Record<string, unknown>)
127+
.reverse()
128+
.map(([key, nested]) => [key, reverseJsonObjectKeys(nested)]),
129+
);
130+
}
131+
122132
describe("apply", () => {
123133
test("refuses a client that is not installed, and writes nothing", () => {
124134
const result = applyIntegration(input());
@@ -216,6 +226,8 @@ describe("apply", () => {
216226

217227
const record = store.readRecords().zcode!;
218228
expect(record.protectedBlockFingerprint).toMatch(/^[0-9a-f]{16}$/);
229+
expect(record.semanticBlockFingerprint).toMatch(/^[0-9a-f]{16}$/);
230+
expect(record.semanticProtectedBlockFingerprint).toMatch(/^[0-9a-f]{16}$/);
219231
expect(record.refreshablePaths).toContainEqual([
220232
"provider", "opencodex", "models", "mystery/model", "limit", "context",
221233
]);
@@ -251,6 +263,58 @@ describe("apply", () => {
251263
expect(after.provider.opencodex!.models["mystery/model"]!.limit).toBeUndefined();
252264
});
253265

266+
test("ZCode key-order normalization stays refreshable with derived metadata (#2759)", () => {
267+
const configPath = installZcode();
268+
const models: ExportModel[] = [
269+
...MODELS,
270+
{ namespaced: "mystery/model", provider: "mystery", id: "model" },
271+
];
272+
const request = input({ clientId: "zcode", models });
273+
expect(applyIntegration(request).ok).toBe(true);
274+
275+
const document = JSON.parse(readFileSync(configPath, "utf8")) as {
276+
provider: Record<string, { models: Record<string, Record<string, unknown>> }>;
277+
};
278+
document.provider.opencodex!.models["mystery/model"]!.limit = {
279+
context: 128_000,
280+
output: 32_000,
281+
};
282+
document.provider.opencodex!.models["mystery/model"]!.reasoning = { enabled: false };
283+
const reordered = reverseJsonObjectKeys(document);
284+
writeFileSync(configPath, `${JSON.stringify(reordered, null, 2)}\n`);
285+
286+
expect(readIntegrationState(request)).toMatchObject({ state: "stale" });
287+
const refreshed = applyIntegration(request);
288+
expect(refreshed.ok).toBe(true);
289+
if (refreshed.ok) expect(refreshed.changed).toBe(true);
290+
expect(readIntegrationState(request)).toMatchObject({ state: "current" });
291+
});
292+
293+
test("legacy ZCode records tolerate key reordering when the catalog is unchanged (#2759)", () => {
294+
const configPath = installZcode();
295+
const request = input({ clientId: "zcode" });
296+
expect(applyIntegration(request).ok).toBe(true);
297+
298+
const legacy = { ...store.readRecords().zcode! };
299+
delete legacy.semanticBlockFingerprint;
300+
delete legacy.semanticProtectedBlockFingerprint;
301+
store.putRecord(legacy);
302+
303+
const document = JSON.parse(readFileSync(configPath, "utf8")) as {
304+
provider: Record<string, { models: Record<string, Record<string, unknown>> }>;
305+
};
306+
document.provider.opencodex!.models["anthropic/claude-opus-4-8"]!.reasoning = {
307+
enabled: true,
308+
};
309+
writeFileSync(
310+
configPath,
311+
`${JSON.stringify(reverseJsonObjectKeys(document), null, 2)}\n`,
312+
);
313+
314+
expect(readIntegrationState(request)).toMatchObject({ state: "stale" });
315+
expect(applyIntegration(request).ok).toBe(true);
316+
});
317+
254318
test("a legacy ZCode record accepts derived drift only while its generated catalog is unchanged (#2389)", () => {
255319
const configPath = installZcode();
256320
const request = input({ clientId: "zcode" });

0 commit comments

Comments
 (0)