Skip to content

Commit 3049b67

Browse files
committed
docs(structure): record the catalog-only exception and declare refreshOutcome
Two residuals a delegated review found on this PR. `structure/config.md` owns the sync preflight contract and still said every deterministic refusal leaves the catalog and cache untouched, which this change makes untrue for one reason code. And `refreshOutcome` reached callers through a spread without ever being declared on `CodexSyncResult`.
1 parent 3b15e70 commit 3049b67

2 files changed

Lines changed: 13 additions & 0 deletions

File tree

‎src/codex/sync.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,12 @@ export interface CodexSyncResult {
3232
catalogExists: boolean;
3333
catalogWritten: boolean;
3434
cacheSynced: boolean;
35+
/**
36+
* Whether the catalog owner committed a validated catalog or refused the
37+
* refresh. Only a `catalog-only` result carries it; `ok` already answers the
38+
* question for callers that do not care which half refused.
39+
*/
40+
refreshOutcome?: "committed" | "refused";
3541
message: string;
3642
warning?: string;
3743
comboOmissions?: ComboCatalogOmission[];

‎structure/config.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,13 @@ journal creation, and the background history restoration guardian.
138138
`ocx sync` and `ocx restore back` run the injector's non-writing preflight before provider
139139
discovery or catalog/cache replacement. Deterministic config and ownership refusals therefore
140140
leave the existing catalog and cache untouched, and their concrete messages are emitted on stderr.
141+
One refusal is deliberately not terminal for an explicit `ocx sync`. When the preflight reports
142+
`history_paginated_requires_native_writer`, the refusal itself stands — config and conversation
143+
files are not touched — but the catalog and models cache still refresh through their existing
144+
owner, and the sync reports `catalog-only`. An explicit sync is also the refresh path for side
145+
profiles that read the OpenCodex catalog without injection, and a home whose history simply
146+
requires its native writer is not a reason to let their model list go stale. Unattended sync,
147+
`POST /api/sync`, and every other config or ownership refusal keep the hard failure above.
141148
The real injection still revalidates under its normal write boundary after catalog convergence;
142149
the preflight is an early no-write guard, not an authorization token for a later write.
143150

0 commit comments

Comments
 (0)