Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): checkpoint tie-safety and per-platform redo chord coverage (#3000)
Nick Gomez0175b2082064
diff --git a/.changeset/checkpoint-tie-and-redo-chords.md b/.changeset/checkpoint-tie-and-redo-chords.mdnew file mode 100644index 000000000..61d268030--- /dev/null+++ b/.changeset/checkpoint-tie-and-redo-chords.md@@ -0,0 +1,7 @@+---+"@inkeep/open-knowledge": minor+---++Stop recovery-checkpoint cleanup from discarding the newest rescue point. Checkpoints written in the same second could not be ordered by their timestamps, so the sweep picked which one to drop essentially at random and could keep an older copy while permanently deleting the most recent one. Because loss-hardening writes one checkpoint per open document in a burst, the discarded copy could be a document's only recovery point. Cleanup now keeps every checkpoint it cannot confidently order, so it may hold slightly more than the retention budget rather than destroy the wrong one.++Correct the Source editor entry in the keyboard shortcut help. It advertised undo-selection shortcuts that source mode does not have; those shortcuts still work in the code block editor and in code-shaped property fields, and are now listed there instead. Redo shortcuts are unchanged and continue to work on every platform.diff --git a/packages/app/src/lib/keyboard-shortcuts.ts b/packages/app/src/lib/keyboard-shortcuts.tsindex 6657b7b7d..d3d10e8bd 100644--- a/packages/app/src/lib/keyboard-shortcuts.ts+++ b/packages/app/src/lib/keyboard-shortcuts.ts@@ -725,11 +725,32 @@ const KEYBOARD_SHORTCUT_DEFINITIONS = [id: 'source-history',category: 'source',title: msg`Source undo or redo`,- description: msg`Undo, redo, or undo selection changes through CodeMirror history.`,+ description: msg`Undo or redo your own edits, leaving edits from collaborators and agents in place.`,scope: msg`Source editor`,bindings: [{ mac: '⌘ Z', windowsLinux: 'Ctrl Z' },{ mac: '⇧⌘ Z', windowsLinux: 'Ctrl Y / Ctrl Shift Z' },+ ],+ },+ {+ // The selection chords live here rather than on the source row: source mode+ // runs the origin-aware collaborative undo, which has no selection history,+ // while these two surfaces still install CodeMirror's own `historyKeymap`.+ // Scope names only those two. An ordinary fenced code block is NOT one of+ // them: it edits through the ProseMirror node view under the collaborative+ // undo, so listing it here would repeat the mis-scope this row exists to+ // correct. That keymap's second redo entry declares `linux` with no `key`,+ // so Ctrl Shift Z resolves on Linux but not on Windows, and this column+ // cannot split the two platforms. Ctrl Y is the redo chord that holds on+ // both.+ id: 'code-field-history',+ category: 'wysiwyg',+ title: msg`Code field undo or redo`,+ description: msg`Undo, redo, or step through selection changes in the Edit source pane or a code-shaped property field.`,+ scope: msg`Edit source pane and code property fields`,+ bindings: [+ { mac: '⌘ Z', windowsLinux: 'Ctrl Z' },+ { mac: '⇧⌘ Z', windowsLinux: 'Ctrl Y' },{ mac: '⌘ U / ⇧⌘ U', windowsLinux: 'Ctrl U / Alt U' },],},diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.jsonindex 6a6b03722..9f7a04439 100644--- a/packages/app/src/locales/en/messages.json+++ b/packages/app/src/locales/en/messages.json@@ -638,6 +638,9 @@"This project is local-only, so .ok/skills is hidden from git and these skills can't be committed or shared. Share just the skills folder — the rest of your OK config stays on this computer."],"BjitBo": ["Download ", ["0"]],+ "BkGtRl": [+ "Undo, redo, or step through selection changes in the Edit source pane or a code-shaped property field."+ ],"Bn9-El": ["default"],"Bv5a9_": ["Selection statistics"],"Bx4EXG": ["Actions for ", ["label"]],@@ -872,6 +875,7 @@["0"],")."],+ "FWSjnp": ["Edit source pane and code property fields"],"FXk_zY": ["Adds a guided workflow for authoring new Agent Skills."],"FZtBeR": ["Enable ", ["0"]],"FgQ7XZ": ["Couldn't load your bug reports."],@@ -1552,6 +1556,9 @@"T0OVm7": ["The default branch is protected — pushes need a pull request."],"T3Mld1": ["Window"],"T3j-7o": ["e.g. Switching projects while a sync was running"],+ "TDeOpa": [+ "Undo or redo your own edits, leaving edits from collaborators and agents in place."+ ],"TEEPPF": ["Will replace existing OpenKnowledge entry"],"TJnkyf": ["ok ui responded but server.lock has no port yet"],"TKQ7K-": ["Install"],@@ -1665,6 +1672,7 @@"VNgKZz": ["Advanced settings"],"VTulZj": ["Open in worktree"],"VUijjF": ["Embed an image with optional alt text."],+ "VXGFMg": ["Code field undo or redo"],"VYd_YA": ["Open an existing project folder from disk."],"VZGh8G": ["Fold, unfold, fold all, or unfold all source ranges."],"VZSBXL": ["Semantic ranking activates the first time an agent runs a search."],@@ -2847,7 +2855,6 @@"qyLmWw": ["Source editor search panel"],"r-OJYm": ["Enter a valid branch name (no spaces, no leading dot, no \"..\")."],"r2eKE3": ["Sign in to ", ["agentName"], " first"],- "r2huLx": ["Undo, redo, or undo selection changes through CodeMirror history."],"r4R7AZ": ["Network error during cleanup"],"r51jLC": ["File saved & Claude Desktop App opened"],"r6ncaO": ["Close tab"],diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.poindex 370342bd4..ce0319676 100644--- a/packages/app/src/locales/en/messages.po+++ b/packages/app/src/locales/en/messages.po@@ -1920,6 +1920,10 @@ msgstr "Code copied to clipboard"msgid "Code expired — please try again"msgstr "Code expired — please try again"+#: src/lib/keyboard-shortcuts.ts+msgid "Code field undo or redo"+msgstr "Code field undo or redo"+#: src/components/settings/TerminalSection.tsxmsgid "Codex will still ask until you run \"ok init\" in a terminal for this project."msgstr "Codex will still ask until you run \"ok init\" in a terminal for this project."@@ -3476,6 +3480,10 @@ msgstr "Edit schema {file}"msgid "Edit source"msgstr "Edit source"+#: src/lib/keyboard-shortcuts.ts+msgid "Edit source pane and code property fields"+msgstr "Edit source pane and code property fields"+#: src/editor/slash-command/embed-starter-items.tsxmsgid "Edit this HTML — the preview updates live."msgstr "Edit this HTML — the preview updates live."@@ -9962,13 +9970,17 @@ msgstr "Undo or redo"msgid "Undo or redo visual-editor changes through TipTap collaboration history."msgstr "Undo or redo visual-editor changes through TipTap collaboration history."+#: src/lib/keyboard-shortcuts.ts+msgid "Undo or redo your own edits, leaving edits from collaborators and agents in place."+msgstr "Undo or redo your own edits, leaving edits from collaborators and agents in place."+#: src/components/ActivityPanelBurstRow.tsxmsgid "Undo to this edit?"msgstr "Undo to this edit?"#: src/lib/keyboard-shortcuts.ts-msgid "Undo, redo, or undo selection changes through CodeMirror history."-msgstr "Undo, redo, or undo selection changes through CodeMirror history."+msgid "Undo, redo, or step through selection changes in the Edit source pane or a code-shaped property field."+msgstr "Undo, redo, or step through selection changes in the Edit source pane or a code-shaped property field."#: src/components/skill-actions.tsxmsgid "Uninstall"diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.jsonindex 4e006502b..30acd4850 100644--- a/packages/app/src/locales/pseudo/messages.json+++ b/packages/app/src/locales/pseudo/messages.json@@ -638,6 +638,9 @@"Ţĥĩś ƥŕōĴēćţ ĩś ĺōćàĺ-ōńĺŷ, śō .ōķ/śķĩĺĺś ĩś ĥĩďďēń ƒŕōḿ ĝĩţ àńď ţĥēśē śķĩĺĺś ćàń'ţ ƀē ćōḿḿĩţţēď ōŕ śĥàŕēď. Śĥàŕē Ĵũśţ ţĥē śķĩĺĺś ƒōĺďēŕ — ţĥē ŕēśţ ōƒ ŷōũŕ ŌĶ ćōńƒĩĝ śţàŷś ōń ţĥĩś ćōḿƥũţēŕ."],"BjitBo": ["Ďōŵńĺōàď ", ["0"]],+ "BkGtRl": [+ "Ũńďō, ŕēďō, ōŕ śţēƥ ţĥŕōũĝĥ śēĺēćţĩōń ćĥàńĝēś ĩń ţĥē Ēďĩţ śōũŕćē ƥàńē ōŕ à ćōďē-śĥàƥēď ƥŕōƥēŕţŷ ƒĩēĺď."+ ],"Bn9-El": ["ďēƒàũĺţ"],"Bv5a9_": ["Śēĺēćţĩōń śţàţĩśţĩćś"],"Bx4EXG": ["Àćţĩōńś ƒōŕ ", ["label"]],@@ -872,6 +875,7 @@["0"],")."],+ "FWSjnp": ["Ēďĩţ śōũŕćē ƥàńē àńď ćōďē ƥŕōƥēŕţŷ ƒĩēĺďś"],"FXk_zY": ["Àďďś à ĝũĩďēď ŵōŕķƒĺōŵ ƒōŕ àũţĥōŕĩńĝ ńēŵ Àĝēńţ Śķĩĺĺś."],"FZtBeR": ["Ēńàƀĺē ", ["0"]],"FgQ7XZ": ["Ćōũĺďń'ţ ĺōàď ŷōũŕ ƀũĝ ŕēƥōŕţś."],@@ -1552,6 +1556,9 @@"T0OVm7": ["Ţĥē ďēƒàũĺţ ƀŕàńćĥ ĩś ƥŕōţēćţēď — ƥũśĥēś ńēēď à ƥũĺĺ ŕēǫũēśţ."],"T3Mld1": ["Ŵĩńďōŵ"],"T3j-7o": ["ē.ĝ. Śŵĩţćĥĩńĝ ƥŕōĴēćţś ŵĥĩĺē à śŷńć ŵàś ŕũńńĩńĝ"],+ "TDeOpa": [+ "Ũńďō ōŕ ŕēďō ŷōũŕ ōŵń ēďĩţś, ĺēàvĩńĝ ēďĩţś ƒŕōḿ ćōĺĺàƀōŕàţōŕś àńď àĝēńţś ĩń ƥĺàćē."+ ],"TEEPPF": ["Ŵĩĺĺ ŕēƥĺàćē ēxĩśţĩńĝ ŌƥēńĶńōŵĺēďĝē ēńţŕŷ"],"TJnkyf": ["ōķ ũĩ ŕēśƥōńďēď ƀũţ śēŕvēŕ.ĺōćķ ĥàś ńō ƥōŕţ ŷēţ"],"TKQ7K-": ["Ĩńśţàĺĺ"],@@ -1665,6 +1672,7 @@"VNgKZz": ["Àďvàńćēď śēţţĩńĝś"],"VTulZj": ["Ōƥēń ĩń ŵōŕķţŕēē"],"VUijjF": ["Ēḿƀēď àń ĩḿàĝē ŵĩţĥ ōƥţĩōńàĺ àĺţ ţēxţ."],+ "VXGFMg": ["Ćōďē ƒĩēĺď ũńďō ōŕ ŕēďō"],"VYd_YA": ["Ōƥēń àń ēxĩśţĩńĝ ƥŕōĴēćţ ƒōĺďēŕ ƒŕōḿ ďĩśķ."],"VZGh8G": ["Ƒōĺď, ũńƒōĺď, ƒōĺď àĺĺ, ōŕ ũńƒōĺď àĺĺ śōũŕćē ŕàńĝēś."],"VZSBXL": ["Śēḿàńţĩć ŕàńķĩńĝ àćţĩvàţēś ţĥē ƒĩŕśţ ţĩḿē àń àĝēńţ ŕũńś à śēàŕćĥ."],@@ -2847,7 +2855,6 @@"qyLmWw": ["Śōũŕćē ēďĩţōŕ śēàŕćĥ ƥàńēĺ"],"r-OJYm": ["Ēńţēŕ à vàĺĩď ƀŕàńćĥ ńàḿē (ńō śƥàćēś, ńō ĺēàďĩńĝ ďōţ, ńō \"..\")."],"r2eKE3": ["Śĩĝń ĩń ţō ", ["agentName"], " ƒĩŕśţ"],- "r2huLx": ["Ũńďō, ŕēďō, ōŕ ũńďō śēĺēćţĩōń ćĥàńĝēś ţĥŕōũĝĥ ĆōďēḾĩŕŕōŕ ĥĩśţōŕŷ."],"r4R7AZ": ["Ńēţŵōŕķ ēŕŕōŕ ďũŕĩńĝ ćĺēàńũƥ"],"r51jLC": ["Ƒĩĺē śàvēď & Ćĺàũďē Ďēśķţōƥ Àƥƥ ōƥēńēď"],"r6ncaO": ["Ćĺōśē ţàƀ"],diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.poindex 009baba54..3d6b19267 100644--- a/packages/app/src/locales/pseudo/messages.po+++ b/packages/app/src/locales/pseudo/messages.po@@ -1916,6 +1916,10 @@ msgstr ""msgid "Code expired — please try again"msgstr ""+#: src/lib/keyboard-shortcuts.ts+msgid "Code field undo or redo"+msgstr ""+#: src/components/settings/TerminalSection.tsxmsgid "Codex will still ask until you run \"ok init\" in a terminal for this project."msgstr ""@@ -3472,6 +3476,10 @@ msgstr ""msgid "Edit source"msgstr ""+#: src/lib/keyboard-shortcuts.ts+msgid "Edit source pane and code property fields"+msgstr ""+#: src/editor/slash-command/embed-starter-items.tsxmsgid "Edit this HTML — the preview updates live."msgstr ""@@ -9958,12 +9966,16 @@ msgstr ""msgid "Undo or redo visual-editor changes through TipTap collaboration history."msgstr ""+#: src/lib/keyboard-shortcuts.ts+msgid "Undo or redo your own edits, leaving edits from collaborators and agents in place."+msgstr ""+#: src/components/ActivityPanelBurstRow.tsxmsgid "Undo to this edit?"msgstr ""#: src/lib/keyboard-shortcuts.ts-msgid "Undo, redo, or undo selection changes through CodeMirror history."+msgid "Undo, redo, or step through selection changes in the Edit source pane or a code-shaped property field."msgstr ""#: src/components/skill-actions.tsxdiff --git a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts b/packages/app/tests/integration/qa-045-restore-after-gc.test.tsindex 72dd3b60a..36c2a5272 100644--- a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts+++ b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts@@ -49,7 +49,10 @@ describe('restore after checkpoint GC', () => {{ timeoutMs: 5000, settleMs: 200 },);- // Two checkpoints of one kind, so keep-1 evicts exactly one of them.+ // Two checkpoints of one kind, so keep-1 evicts exactly one of them. The+ // explicit dates put them a second apart: git stores commit dates at+ // one-second granularity, so writing both in the same second would leave+ // the sweep no way to tell which is newer and it would then keep both.const shadow = await initShadowRepo(server.contentDir);const firstSha = await saveInMemoryCheckpoint(shadow, '', {kind: 'defer-exhaustion-loss',@@ -58,6 +61,7 @@ describe('restore after checkpoint GC', () => {branch: 'main',label: 'older recovery',metadata: { deferCount: 9 },+ date: '2026-01-02T03:04:05Z',});const secondSha = await saveInMemoryCheckpoint(shadow, '', {kind: 'defer-exhaustion-loss',@@ -66,6 +70,7 @@ describe('restore after checkpoint GC', () => {branch: 'main',label: 'newer recovery',metadata: { deferCount: 9 },+ date: '2026-01-02T03:04:06Z',});// Sanity: both shas resolve BEFORE the sweep, so a 404 after it is the@@ -97,17 +102,14 @@ describe('restore after checkpoint GC', () => {});expect(gc.deletedDeferExhaustionLoss).toBe(1);- // Which of the two same-second checkpoints the sweep evicts is not pinned- // here: retention orders by git author date, which has one-second- // granularity, so a pair written inside one second ties and the survivor- // is decided by ref order rather than by recency. This test is about what- // a restore does with an evicted sha, so read the eviction back out of the- // ref set instead of assuming which one it was.+ // Recency is unambiguous here, so the survivor's identity is pinned: a+ // sweep that keeps the most recent N must drop the older checkpoint and+ // keep the newer rescue, never the other way round.const refsAfter = checkpointRefShas();const evicted = [...refsBefore].filter((sha) => !refsAfter.has(sha));- expect(evicted).toHaveLength(1);- const evictedSha = evicted[0] as string;- expect([firstSha, secondSha]).toContain(evictedSha);+ expect(evicted).toEqual([firstSha]);+ expect(refsAfter.has(secondSha)).toBe(true);+ const evictedSha = firstSha;// The row is gone from the timeline...const histRes = await fetch(@@ -155,8 +157,6 @@ describe('restore after checkpoint GC', () => {// No mutation: not a partial restore, not a resurrection of the evicted blob.const after = readTestDoc(server.contentDir, docName);expect(after).toBe(before);- expect(after).not.toContain(- evictedSha === firstSha ? 'older recovered body' : 'newer recovered body',- );+ expect(after).not.toContain('older recovered body');}, 60_000);});diff --git a/packages/app/tests/stress/source-mode-undo-keymap.e2e.ts b/packages/app/tests/stress/source-mode-undo-keymap.e2e.tsindex 619dd0d2c..a13fd3eb7 100644--- a/packages/app/tests/stress/source-mode-undo-keymap.e2e.ts+++ b/packages/app/tests/stress/source-mode-undo-keymap.e2e.ts@@ -5,8 +5,8 @@* Y.UndoManager, driven by `yUndoManagerKeymap`; CodeMirror's native history is* removed. Unit and integration tiers pin the origin discrimination and the* single-undo-system invariant against a real EditorView; this rung proves the- * remaining link they cannot: a real Mod-z keydown in a real browser resolves- * through the installed keymap and reverts the user's typing.+ * remaining link they cannot: a real keydown in a real browser resolves through+ * the installed keymap and moves the user's typing.*/import { randomUUID } from 'node:crypto';@@ -15,20 +15,79 @@ import { expect, test, waitForActiveProviderSynced as waitForProvider } from './const SENTINEL = 'undo-me-sentinel-xyz';+interface RedoChord {+ /** Playwright `press()` spelling. */+ press: string;+ /** `KeyboardEvent.key` a physical keyboard produces for this chord. */+ key: string;+ shiftKey: boolean;+}+/**- * The redo chord differs by platform. `yUndoManagerKeymap` binds redo to- * `Mod-y` with a `mac` override of `Mod-Shift-z`, plus a platform-agnostic- * `Mod-Shift-z`. Press what a user on this platform actually presses, so the- * assertion tracks the binding that ships rather than one chord that happens- * to resolve on the author's machine.+ * Redo chords a user on this platform actually presses.+ *+ * `yUndoManagerKeymap` binds redo to `Mod-y` with a `mac` override of+ * `Mod-Shift-z`, plus a platform-agnostic `Mod-Shift-z`. CodeMirror resolves a+ * binding as `b[platform] || b.key`, so the `mac` property replaces rather than+ * adds: macOS gets `Shift-Meta-z` alone, and every other platform gets both+ * `Ctrl-y` and `Shift-Ctrl-z`. That keymap declares neither `win` nor `linux`,+ * so the Windows and Linux columns of this matrix are the same two chords by+ * construction; there is no Windows runner in CI and the Linux arm covers it.+ *+ * The `Z` is uppercase on purpose, and must stay that way. Playwright applies+ * the shift transform only to the `'Z'` and `'KeyZ'` spellings, so the+ * lowercase `'Control+Shift+z'` delivers `key: 'z'`. CodeMirror's first keymap+ * lookup deliberately drops `Shift-` for printable characters, so that lands on+ * `Ctrl-z` and runs undo instead; y-codemirror's commands are `undo() || true`,+ * so the no-op undo still reports handled and calls `preventDefault`, and redo+ * silently never runs. A physical keyboard emits `key: 'Z'` and reaches redo.+ * macOS hides this: `w3c-keyname` rebuilds the key from the keycode when Shift+ * and Cmd are held together, so the mac arm passes on either spelling.*/-const REDO_CHORD = process.platform === 'darwin' ? 'Meta+Shift+z' : 'Control+y';+const REDO_CHORDS: RedoChord[] =+ process.platform === 'darwin'+ ? [{ press: 'Meta+Shift+Z', key: 'Z', shiftKey: true }]+ : [+ { press: 'Control+y', key: 'y', shiftKey: false },+ { press: 'Control+Shift+Z', key: 'Z', shiftKey: true },+ ];++type DeliveredKeydown = { key: string; shiftKey: boolean };++interface KeydownProbeWindow {+ __redoKeydowns?: DeliveredKeydown[];+}/** Read the shared Y.Text('source') off the active provider. */function readSource(page: Page): Promise<string> {return page.evaluate(() => window.__activeProvider?.document.getText('source').toString() ?? '');}+/**+ * Record the non-modifier keydowns the page actually receives. Without this the+ * suite cannot tell a keymap regression from a chord that was never delivered+ * in the spelling the assertion assumes, and it fails at the sentinel instead+ * of at the cause.+ */+async function installKeydownProbe(page: Page): Promise<void> {+ await page.evaluate(() => {+ const probed = window as unknown as KeydownProbeWindow;+ probed.__redoKeydowns = [];+ window.addEventListener(+ 'keydown',+ (event) => {+ if (['Control', 'Shift', 'Meta', 'Alt'].includes(event.key)) return;+ probed.__redoKeydowns?.push({ key: event.key, shiftKey: event.shiftKey });+ },+ { capture: true },+ );+ });+}++function readKeydownProbe(page: Page): Promise<DeliveredKeydown[]> {+ return page.evaluate(() => (window as unknown as KeydownProbeWindow).__redoKeydowns ?? []);+}+test.describe('source-mode undo keymap', () => {let docName: string;@@ -55,15 +114,23 @@ test.describe('source-mode undo keymap', () => {await expect.poll(() => readSource(page), { timeout: 10_000 }).not.toContain(SENTINEL);});- test('the platform redo chord redoes the reverted typing', async ({ page }) => {- await page.locator('.cm-content').click();- await page.keyboard.type(SENTINEL);- await expect.poll(() => readSource(page), { timeout: 10_000 }).toContain(SENTINEL);+ for (const chord of REDO_CHORDS) {+ test(`${chord.press} redoes the reverted typing`, async ({ page }) => {+ await page.locator('.cm-content').click();+ await page.keyboard.type(SENTINEL);+ await expect.poll(() => readSource(page), { timeout: 10_000 }).toContain(SENTINEL);- await page.keyboard.press('ControlOrMeta+z');- await expect.poll(() => readSource(page), { timeout: 10_000 }).not.toContain(SENTINEL);+ await page.keyboard.press('ControlOrMeta+z');+ await expect.poll(() => readSource(page), { timeout: 10_000 }).not.toContain(SENTINEL);- await page.keyboard.press(REDO_CHORD);- await expect.poll(() => readSource(page), { timeout: 10_000 }).toContain(SENTINEL);- });+ await installKeydownProbe(page);+ await page.keyboard.press(chord.press);++ // Delivery first, so a spelling that stopped producing the physical+ // keyboard's event fails here rather than looking like a keymap gap.+ expect(await readKeydownProbe(page)).toEqual([{ key: chord.key, shiftKey: chord.shiftKey }]);++ await expect.poll(() => readSource(page), { timeout: 10_000 }).toContain(SENTINEL);+ });+ }});diff --git a/packages/server/src/checkpoint-retention-tie.test.ts b/packages/server/src/checkpoint-retention-tie.test.tsnew file mode 100644index 000000000..8594926d1--- /dev/null+++ b/packages/server/src/checkpoint-retention-tie.test.ts@@ -0,0 +1,171 @@+/**+ * Checkpoint retention when the keep-N boundary falls inside a timestamp tie.+ *+ * Git stores commit dates at one-second granularity, and the retention sweep+ * orders candidates by author date alone. Checkpoints written inside one+ * second therefore carry no recency information relative to each other, and+ * `for-each-ref` enumerates them in sha byte order — a content hash, so+ * uncorrelated with creation order. A boundary landing inside such a group+ * used to pick its victim by that order, which can destroy the newest rescue+ * point while keeping an older one.+ *+ * The shape is the expected one rather than an exotic race: loss-hardening+ * detection sites queue one checkpoint per open document in a single tick, so+ * a burst lands within one second by construction, and the tie members are+ * different documents — the arbitrary victim is some document's only anchor.+ * The shadow repo is bare-ish and its `refs/checkpoints/*` namespace is+ * outside git's reflog-autocreate allowlist, so nothing shields a dropped+ * ref's commit once the objects are pruned.+ *+ * These tests pin the contract the sweep documents for itself — keep the most+ * recent N — including the case where it cannot order the candidates.+ *+ */++import { execFileSync } from 'node:child_process';+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import simpleGit from 'simple-git';+import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import {+ DEFAULT_CHECKPOINT_RETENTION,+ gcCheckpointRefs,+ initShadowRepo,+ type ShadowHandle,+ saveInMemoryCheckpoint,+} from './shadow-repo.ts';++let tmpDir: string;+let projectRoot: string;+let shadow: ShadowHandle;++beforeEach(async () => {+ tmpDir = mkdtempSync(join(tmpdir(), 'ok-checkpoint-tie-'));+ projectRoot = resolve(tmpDir, 'project');+ mkdirSync(resolve(projectRoot, 'content/docs'), { recursive: true });+ const git = simpleGit(projectRoot);+ await git.init();+ await git.raw('config', 'user.name', 'Test');+ await git.raw('config', 'user.email', '[email protected]');+ shadow = await initShadowRepo(projectRoot);+});++afterEach(() => {+ rmSync(tmpDir, { recursive: true, force: true });+});++/** Shas still reachable through `refs/checkpoints/main/` after a sweep. */+function survivingShas(): Set<string> {+ return new Set(+ execFileSync('git', ['for-each-ref', '--format=%(objectname)', 'refs/checkpoints/main/'], {+ cwd: shadow.workTree,+ encoding: 'utf-8',+ env: { ...process.env, GIT_DIR: shadow.gitDir, GIT_WORK_TREE: shadow.workTree },+ })+ .split('\n')+ .map((l) => l.trim())+ .filter(Boolean),+ );+}++/**+ * Write one checkpoint of a single kind at an explicit commit date. Returns the+ * sha, so a test can name survivors and evictees by creation order rather than+ * reading the outcome back out of the ref set.+ */+function writeCheckpoint(index: number, date: string): Promise<string> {+ return saveInMemoryCheckpoint(shadow, 'content/docs', {+ kind: 'defer-exhaustion-loss',+ docName: `doc-${index}.md`,+ contents: `rescued body ${index}\n`,+ label: `defer exhaustion ${index}`,+ metadata: { deferCount: 9 },+ date,+ });+}++const SECOND_A = '2026-01-02T03:04:05Z';+const SECOND_B = '2026-01-02T03:04:06Z';+const SECOND_C = '2026-01-02T03:04:07Z';++describe('checkpoint retention across a timestamp tie', () => {+ test('a same-second burst straddling the keep boundary retains every member instead of destroying an arbitrary one', async () => {+ const shas: string[] = [];+ for (let i = 0; i < 4; i++) shas.push(await writeCheckpoint(i, SECOND_A));++ const gc = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,+ maxDeferExhaustionLoss: 2,+ ttlMs: 0,+ });++ // The sweep cannot tell which of the four is newest, so refusing to choose+ // is the only outcome that cannot destroy the newest rescue. Retention is a+ // space bound; the excess is bounded by the size of the tied group.+ expect(gc.deletedDeferExhaustionLoss).toBe(0);+ const survivors = survivingShas();+ for (const sha of shas) expect(survivors.has(sha)).toBe(true);+ });++ test('checkpoints written in distinct seconds still evict oldest-first down to the budget', async () => {+ const oldest = await writeCheckpoint(0, SECOND_A);+ const older = await writeCheckpoint(1, SECOND_B);+ const newest = await writeCheckpoint(2, SECOND_C);++ const gc = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,+ maxDeferExhaustionLoss: 2,+ ttlMs: 0,+ });++ expect(gc.deletedDeferExhaustionLoss).toBe(1);+ const survivors = survivingShas();+ expect(survivors.has(newest)).toBe(true);+ expect(survivors.has(older)).toBe(true);+ expect(survivors.has(oldest)).toBe(false);+ });++ test('the keep window widens across the straddling group only, so strictly older checkpoints are still evicted', async () => {+ const oldest = await writeCheckpoint(0, SECOND_A);+ const tied = [+ await writeCheckpoint(1, SECOND_B),+ await writeCheckpoint(2, SECOND_B),+ await writeCheckpoint(3, SECOND_B),+ ];+ const newest = await writeCheckpoint(4, SECOND_C);++ const gc = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,+ maxDeferExhaustionLoss: 2,+ ttlMs: 0,+ });++ // Budget 2 puts the boundary inside the three-member tie, so the window+ // grows to cover all of it. The entry that is unambiguously older is not+ // protected by that widening.+ expect(gc.deletedDeferExhaustionLoss).toBe(1);+ const survivors = survivingShas();+ expect(survivors.has(newest)).toBe(true);+ for (const sha of tied) expect(survivors.has(sha)).toBe(true);+ expect(survivors.has(oldest)).toBe(false);+ });++ test('the TTL lower bound still reaps tied checkpoints that are inside the count budget but past expiry', async () => {+ const shas: string[] = [];+ for (let i = 0; i < 2; i++) shas.push(await writeCheckpoint(i, SECOND_A));++ // Budget far above the entry count, so only age can evict here. Widening+ // the count window across a tie must not shield an entry from the TTL,+ // which is a per-entry threshold and needs no ordering.+ const gc = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,+ maxDeferExhaustionLoss: 50,+ ttlMs: 1000,+ });++ expect(gc.deletedDeferExhaustionLoss).toBe(2);+ const survivors = survivingShas();+ for (const sha of shas) expect(survivors.has(sha)).toBe(false);+ });+});diff --git a/packages/server/src/qa-gc-budget-isolation.test.ts b/packages/server/src/qa-gc-budget-isolation.test.tsindex 30c00506d..289eb51b3 100644--- a/packages/server/src/qa-gc-budget-isolation.test.ts+++ b/packages/server/src/qa-gc-budget-isolation.test.ts@@ -31,6 +31,14 @@ import {const BUDGET = 5;const OVER = BUDGET + 4;+/**+ * Distinct, increasing commit dates. Git stores dates at one-second+ * granularity, so a burst written without them ties, and retention keeps a+ * whole tied group rather than choosing a victim it cannot order. A budget+ * assertion needs an unambiguous recency order to count against.+ */+const burstDate = (rank: number): string => `@${1_700_000_000 + rank * 100} +0000`;+let tmpDir: string;let shadow: ShadowHandle;@@ -58,6 +66,7 @@ describe('checkpoint GC budgets for the derive-guard / detector / backstop kindscontents: `pending line ${i}\n`,label: `defer exhaustion ${i}`,metadata: { deferCount: 9 },+ date: burstDate(i),});}// One anchor of every other surfaced kind, each inside its own budget.@@ -104,6 +113,7 @@ describe('checkpoint GC budgets for the derive-guard / detector / backstop kindscontents: `derive body ${i}\n`,label: `derive loss ${i}`,metadata: { lostSubstrings: [`derive-${i}`] },+ date: burstDate(i),});await saveInMemoryCheckpoint(shadow, 'content/docs', {kind: 'bridge-backstop-trip',@@ -111,6 +121,7 @@ describe('checkpoint GC budgets for the derive-guard / detector / backstop kindscontents: `backstop body ${i}\n`,label: `backstop trip ${i}`,metadata: { rounds: 8 },+ date: burstDate(i),});}diff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.tsindex 45a3d3f54..e9b5ce4c4 100644--- a/packages/server/src/shadow-repo.test.ts+++ b/packages/server/src/shadow-repo.test.ts@@ -1209,6 +1209,9 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)test('keeps only the most-recent N bridge-merge-loss refs per branch', async () => {const { gcCheckpointRefs } = await import('./shadow-repo.ts');+ // Distinct seconds per write: retention keeps a whole same-second group+ // rather than choosing a victim it cannot order, so a count assertion needs+ // an unambiguous recency order.for (let i = 0; i < 7; i++) {await saveInMemoryCheckpoint(shadow, 'content/docs', {kind: 'bridge-merge-loss',@@ -1216,6 +1219,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)contents: `contents ${i}\n`,label: `loss ${i}`,metadata: { lostSubstrings: [`lost-${i}`] },+ date: `@${1_700_000_000 + i * 100} +0000`,});}@@ -1247,6 +1251,8 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)// (maxProducerGuardLoss), independent of maxBridgeMergeLoss — a stuck// serializer must not evict merge-drop recovery anchors (or vice versa).const { gcCheckpointRefs } = await import('./shadow-repo.ts');+ // Distinct seconds per write, as above: a same-second group is retained+ // whole, which would leave nothing for the budget to evict.for (let i = 0; i < 7; i++) {await saveInMemoryCheckpoint(shadow, 'content/docs', {kind: 'producer-guard-loss',@@ -1254,6 +1260,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)contents: `contents ${i}\n`,label: `guard loss ${i}`,metadata: { construct: 'table' },+ date: `@${1_700_000_000 + i * 100} +0000`,});}// One bridge-merge-loss alongside: its budget (50) must shield it from the@@ -1473,7 +1480,16 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)expect(result.deletedAutoConsolidation).toBe(0);});- const seedKind = async (kind: CheckpointKind, tag = ''): Promise<void> => {+ /**+ * Distinct, increasing commit dates for seeded checkpoints. Git stores dates+ * at one-second granularity, so a burst written without them ties, and+ * retention keeps a whole tied group rather than choosing a victim it cannot+ * order. A budget assertion needs an unambiguous order to count against.+ * Matches the scheme `writeAutoConsolidationCheckpoint` already uses.+ */+ const seedDate = (rank: number): string => `@${1_700_000_000 + rank * 100} +0000`;++ const seedKind = async (kind: CheckpointKind, tag = '', date?: string): Promise<void> => {switch (kind) {case 'bridge-merge-loss':await saveInMemoryCheckpoint(shadow, 'content/docs', {@@ -1481,6 +1497,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)docName: 'a.md',contents: `a${tag}\n`,label: 'l',+ date,metadata: { lostSubstrings: ['x'] },});return;@@ -1490,6 +1507,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)docName: 'b.md',contents: `b${tag}\n`,label: 'l',+ date,metadata: { construct: 'tableCell' },});return;@@ -1499,6 +1517,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)docName: 'c.md',contents: `c${tag}\n`,label: 'l',+ date,metadata: { duplicatedLineCount: 1 },});return;@@ -1508,6 +1527,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)docName: 'd.md',contents: `d${tag}\n`,label: 'l',+ date,metadata: { incomingDiskSha: 'sha' },});return;@@ -1517,6 +1537,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)docName: 'e.md',contents: `e${tag}\n`,label: 'l',+ date,metadata: { deferCount: 8 },});return;@@ -1526,6 +1547,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)docName: 'h.md',contents: `h${tag}\n`,label: 'l',+ date,metadata: { lostSubstrings: ['dropped'] },});return;@@ -1535,6 +1557,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)docName: 'f.md',contents: `f${tag}\n`,label: 'l',+ date,metadata: { lostSubstrings: ['dropped'] },});return;@@ -1544,6 +1567,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)docName: 'g.md',contents: `g${tag}\n`,label: 'l',+ date,metadata: { rounds: 8 },});return;@@ -1553,6 +1577,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)docName: 'i.md',contents: `i${tag}\n`,label: 'l',+ date,metadata: { atRiskLines: 1, witnessAvailable: true },});return;@@ -1600,8 +1625,8 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)// invisible to the seed-one-per-kind sweep — this is what catches a missing// fan-out entry: refs that accumulate forever with no cap and no TTL.for (const kind of CHECKPOINT_KINDS) {- await seedKind(kind, '1');- await seedKind(kind, '2');+ await seedKind(kind, '1', seedDate(1));+ await seedKind(kind, '2', seedDate(2));}// Every `max*` limit set to 1, derived from the policy shape so a newdiff --git a/packages/server/src/shadow-repo.ts b/packages/server/src/shadow-repo.tsindex a7c2f8652..677ac5846 100644--- a/packages/server/src/shadow-repo.ts+++ b/packages/server/src/shadow-repo.ts@@ -837,7 +837,7 @@ export async function safetyCheckpoint(* fragment serialization (the restore anchor); `lostSubstrings` names the* dropped content for diagnosis.*/-export type InMemoryCheckpointParams =+export type InMemoryCheckpointParams = (| {kind: 'bridge-merge-loss';docName: string;@@ -909,7 +909,20 @@ export type InMemoryCheckpointParams =label: string;branch?: string;metadata: { rounds: number };- };+ }+) & {+ /**+ * Explicit commit timestamp (any git-parseable date, e.g. ISO 8601), applied+ * to both author and committer date. Production leaves this unset so git+ * stamps the current time; tests pass explicit values to pin retention+ * ordering — git stores dates at one-second granularity, so checkpoints+ * written inside one second are indistinguishable by date and would+ * otherwise need a >1s wall-clock wait between writes to order+ * deterministically. Mirrors `CommitWipOptions.date` and+ * `SaveVersionOptions.date`.+ */+ date?: string;+};/*** Silent in-memory checkpoint — writes `contents` as a blob at the@@ -1061,17 +1074,18 @@ async function saveInMemoryCheckpointInner(await sg.env({ GIT_DIR: shadow.gitDir, GIT_INDEX_FILE: tmpIndex }).raw('write-tree')).trim();- const commitSha = (- await sg- .env({- GIT_DIR: shadow.gitDir,- GIT_AUTHOR_NAME: 'openknowledge',- GIT_AUTHOR_EMAIL: '[email protected]',- GIT_COMMITTER_NAME: 'openknowledge',- GIT_COMMITTER_EMAIL: '[email protected]',- })- .raw('commit-tree', treeSha, '-m', message)- ).trim();+ const commitEnv: Record<string, string> = {+ GIT_DIR: shadow.gitDir,+ GIT_AUTHOR_NAME: 'openknowledge',+ GIT_AUTHOR_EMAIL: '[email protected]',+ GIT_COMMITTER_NAME: 'openknowledge',+ GIT_COMMITTER_EMAIL: '[email protected]',+ };+ if (params.date) {+ commitEnv.GIT_AUTHOR_DATE = params.date;+ commitEnv.GIT_COMMITTER_DATE = params.date;+ }+ const commitSha = (await sg.env(commitEnv).raw('commit-tree', treeSha, '-m', message)).trim();await sg.raw('update-ref', `refs/checkpoints/${branch}/${commitSha}`, commitSha);return commitSha;@@ -1400,6 +1414,12 @@ const GC_BUCKET_POLICY = {* triggered `Save Version` artifacts) are always retained to preserve the* permanent-history contract.*+ * Recency comes from the commit author date, which git stores at one-second+ * granularity, so a burst written inside one second is unorderable. When the+ * keep boundary falls inside such a group the count window widens to cover+ * the whole group — the sweep may retain more than N, but it never destroys a+ * checkpoint it cannot prove is the older one.+ ** Batched: single `for-each-ref` + single `git log --no-walk` regardless of* ref count. Deletion is one `update-ref -d` per eligible ref.*/@@ -1524,10 +1544,28 @@ async function gcCheckpointRefsInner(): void => {// Newest first so the count-based keep-N is trivial.list.sort((a, b) => b.timestamp - a.timestamp);+ // Timestamps come from `%aI`, and git stores commit dates at one-second+ // granularity, so entries written inside the same second tie and carry no+ // recency information relative to each other — the enumeration that+ // produced them is refname (sha) order, which is a content hash. When the+ // keep boundary lands inside such a group, widen it to cover the whole+ // group rather than destroying a member picked by that order: a sweep that+ // cannot order its candidates must not fabricate one, and the newest+ // rescue point is exactly what the arbitrary victim can be. Retention is a+ // space bound, not a correctness bound, and the excess is bounded by the+ // size of the straddling group. The TTL below is a per-entry threshold,+ // needs no ordering, and is deliberately left applying to every entry.+ let keep = limit;+ while (keep > 0 && keep < list.length) {+ const lastKept = list[keep - 1];+ const firstDropped = list[keep];+ if (!lastKept || !firstDropped || lastKept.timestamp !== firstDropped.timestamp) break;+ keep++;+ }for (let i = 0; i < list.length; i++) {const entry = list[i];if (!entry) continue;- const overCount = i >= limit;+ const overCount = i >= keep;const overTtl =applyTtl && policy.ttlMs > 0 && entry.timestamp > 0 && now - entry.timestamp > policy.ttlMs;if (overCount || overTtl) {