Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): give the two remaining destructive-repair sites a restore anchor (#3012)

Nick Gomezc0f61970acb6
diff --git a/.changeset/persistence-sweep-gap-anchors.md b/.changeset/persistence-sweep-gap-anchors.md
new file mode 100644
index 000000000..2f8ca6468
--- /dev/null
+++ b/.changeset/persistence-sweep-gap-anchors.md
@@ -0,0 +1,9 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Two more places where the editor could replace what you had open with the copy on disk now leave a restorable version behind first.
+
+The first is a conflict between an agent and something else writing the same file. When an agent saves a document that another program changed underneath it, the copy on disk wins — that part is correct and unchanged, and the agent is still told its write did not land. But the open document was replaced outright, and anything you had typed into it that had not saved yet went with it, silently and with no way to undo. The second is the same situation for a skill or template edited from two places at once.
+
+Both now write a recovery checkpoint of the open document before replacing it, so what you had is restorable from version history, and both record the event so it shows up in a diagnostics bundle rather than disappearing without trace.
diff --git a/packages/app/src/components/TimelinePanel.dom.test.tsx b/packages/app/src/components/TimelinePanel.dom.test.tsx
index 95e276709..92667be33 100644
--- a/packages/app/src/components/TimelinePanel.dom.test.tsx
+++ b/packages/app/src/components/TimelinePanel.dom.test.tsx
@@ -139,6 +139,18 @@ const SURFACED_KINDS: ParsedCheckpoint[] = [
size: 12,
metadata: { copies: 2, fragmentChildren: 18 },
},
+ {
+ kind: 'persistence-divergence-realign',
+ docName: 'notes',
+ size: 12,
+ metadata: { diskBytes: 37, discardedBytes: 79 },
+ },
+ {
+ kind: 'managed-artifact-reconcile',
+ docName: '.ok/templates/daily',
+ size: 12,
+ metadata: { diskBytes: 41, discardedBytes: 66 },
+ },
];
const AUTO_CONSOLIDATION: ParsedCheckpoint = {
kind: 'auto-consolidation',
diff --git a/packages/app/tests/integration/managed-artifact-reconcile-anchor.test.ts b/packages/app/tests/integration/managed-artifact-reconcile-anchor.test.ts
new file mode 100644
index 000000000..d674072c1
--- /dev/null
+++ b/packages/app/tests/integration/managed-artifact-reconcile-anchor.test.ts
@@ -0,0 +1,209 @@
+/**
+ * The managed-artifact concurrent-writer reconcile as a CONTENT-LOSS site.
+ *
+ * `storeManagedArtifactDoc` refuses to clobber a file a second writer changed
+ * under it: when the pre-write disk read shows `disk !== lkg && disk !== content`
+ * it imports the disk bytes over the live doc and returns `'reconciled'`. The
+ * disk-wins decision is correct — another OK window, a hand edit, or a CLI write
+ * is a real conflict, not a false positive — but the import lands under
+ * `FILE_WATCHER_ORIGIN`, which the server UndoManager excludes by contract and
+ * which reaches browsers as a remote update outside any local `trackedOrigins`
+ * set. Whatever the author had typed into the artifact is gone on both sides.
+ *
+ * `'reconciled'` propagates to in-process consumers, so the path is not wholly
+ * silent, but nothing reaches the loss ring and nothing is restorable. That is
+ * Gap 2 of the content-loss class sweep, and the same three misses as Gap 1:
+ * no checkpoint, no kind of its own, no `detect`.
+ *
+ * Templates are the versioned managed artifact — they live under the project's
+ * `.ok/templates/`, inside the shadow repo's reach. Global skills live at
+ * `<home>/.ok/skills` outside any project shadow, so they are unversioned by
+ * construction and covered separately at the unit rung.
+ *
+ * Fidelity: real boot, real WS client, real `onStoreDocument` managed-artifact
+ * branch, real file lock, real shadow repo. The divergent write is a plain
+ * `writeFileSync` — a second writer's edit needs no seam, because `.ok/templates`
+ * is not on the content watcher, so the divergence survives until the next store
+ * exactly as it does in production.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseCheckpoint } from '@inkeep/open-knowledge-core';
+import { afterEach, describe, expect, test } from 'vitest';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { createTestClient, createTestServer, type TestServer } from './test-harness.ts';
+
+/** What the author had typed into the template and had not yet stored. */
+const AUTHOR_PENDING_LINE = 'Zzz author sentence pending when the reconcile fired.';
+
+/** What the concurrent writer put on disk underneath the live doc. */
+const FOREIGN_LINE = 'Foreign edit from a second OK window.';
+
+interface LossRingEvent {
+ event: string;
+ docName: string;
+ site?: string;
+ direction?: string;
+ lostLen?: number;
+ digest?: string;
+ checkpointSha?: string;
+}
+
+let server: TestServer | undefined;
+
+afterEach(async () => {
+ if (server) {
+ await server.cleanup();
+ server = undefined;
+ }
+});
+
+function readLossEvents(contentDir: string): LossRingEvent[] {
+ const path = join(contentDir, '.ok', 'local', 'loss-capture', 'loss-current.jsonl');
+ if (!existsSync(path)) return [];
+ return readFileSync(path, 'utf-8')
+ .split('\n')
+ .filter((line) => line.length > 0)
+ .flatMap((line) => {
+ try {
+ return [JSON.parse(line) as LossRingEvent];
+ } catch {
+ return [];
+ }
+ });
+}
+
+function shadowGitRaw(s: TestServer, args: string[]): string {
+ const dir = join(s.contentDir, '.git', 'ok');
+ if (!existsSync(dir)) {
+ throw new Error(`shadow repo not found at ${dir}; the rig needs gitEnabled: true`);
+ }
+ return execFileSync('git', ['--git-dir', dir, ...args], { encoding: 'utf-8' }).toString();
+}
+
+/** Every checkpoint the shadow holds, across all branch namespaces. */
+function listCheckpoints(s: TestServer): Array<{ sha: string; kind: string | null }> {
+ return shadowGitRaw(s, ['for-each-ref', '--format=%(objectname)', 'refs/checkpoints'])
+ .split('\n')
+ .map((x) => x.trim())
+ .filter(Boolean)
+ .map((sha) => ({
+ sha,
+ kind: parseCheckpoint(shadowGitRaw(s, ['log', '-1', '--format=%B', sha]))?.kind ?? null,
+ }));
+}
+
+async function pollUntil(
+ predicate: () => boolean,
+ { timeoutMs = 10_000, pollMs = 50 }: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<void> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return;
+ await new Promise((r) => setTimeout(r, pollMs));
+ }
+ throw new Error(`pollUntil timed out after ${timeoutMs}ms`);
+}
+
+describe('managed-artifact reconcile-on-divergence — content-loss conventions', () => {
+ test(
+ 'the reconcile checkpoints the live artifact and reports the loss before discarding it',
+ async () => {
+ server = await createTestServer({ gitEnabled: true, debounce: 150, maxDebounce: 600 });
+ const name = `tpl-${randomUUID().slice(0, 8)}`;
+ const docName = `__template__/${name}`;
+ const tplFile = resolve(server.contentDir, '.ok', 'templates', `${name}.md`);
+
+ const client = await createTestClient(server.port, docName, { skipInvariantWatcher: true });
+
+ // v1 authored in the editor and persisted — this is what sets the LKG.
+ const v1 = `---\ntitle: T\ndescription: d\n---\n\n# Template\n\nv1 body.\n`;
+ client.doc.transact(() => client.ytext.insert(0, v1));
+ await pollUntil(() => existsSync(tplFile) && readFileSync(tplFile, 'utf-8') === v1);
+
+ // A second writer changes the file underneath us. `.ok/templates` is not on
+ // the content watcher, so this stays invisible until the next store — the
+ // production shape of a concurrent OK window or a hand edit.
+ mkdirSync(resolve(tplFile, '..'), { recursive: true });
+ const foreign = `---\ntitle: T\ndescription: d\n---\n\n# Template\n\n${FOREIGN_LINE}\n`;
+ writeFileSync(tplFile, foreign, 'utf-8');
+
+ // Meanwhile the author keeps typing. These bytes are live and unstored.
+ const live = client.ytext.toString();
+ client.doc.transact(() => client.ytext.insert(live.length, `\n${AUTHOR_PENDING_LINE}\n`));
+ await pollUntil(() =>
+ Boolean(
+ server?.instance.hocuspocus.documents
+ .get(docName)
+ ?.getText('source')
+ .toString()
+ .includes(AUTHOR_PENDING_LINE),
+ ),
+ );
+
+ // The next store reads disk, sees `disk !== lkg && disk !== content`, and
+ // reconciles: the foreign bytes win and the author's sentence is discarded.
+ // This premise assertion PASSES on the unfixed tree — it documents the harm.
+ await pollUntil(
+ () =>
+ Boolean(
+ server?.instance.hocuspocus.documents
+ .get(docName)
+ ?.getText('source')
+ .toString()
+ .includes(FOREIGN_LINE),
+ ) &&
+ !server?.instance.hocuspocus.documents
+ .get(docName)
+ ?.getText('source')
+ .toString()
+ .includes(AUTHOR_PENDING_LINE),
+ { timeoutMs: 15_000 },
+ );
+
+ // (a) checkpoint-before-repair + (b) detection-site-owns-a-kind.
+ const rig = server;
+ await pollUntil(
+ () => listCheckpoints(rig).some((c) => c.kind === 'managed-artifact-reconcile'),
+ { timeoutMs: 15_000 },
+ );
+ const anchors = listCheckpoints(rig).filter((c) => c.kind === 'managed-artifact-reconcile');
+ expect(anchors).toHaveLength(1);
+ const anchor = anchors[0];
+ if (!anchor) throw new Error('unreachable: anchor asserted above');
+
+ // (c) undoability: the anchor is the only way back, so it must hold the
+ // author's real bytes. The checkpoint is filed under the artifact's TIMELINE
+ // key (`.ok/templates/<name>`), not the synthetic `__template__/...` doc
+ // name, so it addresses the same path the history surface reads.
+ const blob = shadowGitRaw(rig, ['show', `${anchor.sha}:.ok/templates/${name}`]);
+ expect(blob).toContain(AUTHOR_PENDING_LINE);
+
+ // (d) observable signal.
+ const ring = readLossEvents(rig.contentDir).filter(
+ (e) => e.site === 'managed-artifact-reconcile' && e.docName === docName,
+ );
+ const trips = ring.filter((e) => e.event === 'detector-trip');
+ expect(trips).toHaveLength(1);
+ expect(trips[0]?.lostLen ?? 0).toBeGreaterThanOrEqual(AUTHOR_PENDING_LINE.length);
+ expect(JSON.stringify(trips[0])).not.toContain(AUTHOR_PENDING_LINE);
+ // Polled, not asserted once: git creates the checkpoint ref before the write
+ // promise settles, so the anchor is visible to `for-each-ref` a beat before
+ // the `.then` records its ring event.
+ await pollUntil(() =>
+ readLossEvents(rig.contentDir).some(
+ (e) =>
+ e.site === 'managed-artifact-reconcile' &&
+ e.event === 'checkpoint-write' &&
+ e.checkpointSha === anchor.sha,
+ ),
+ );
+
+ await client.cleanup();
+ },
+ HARNESS_BOOT_TIMEOUT_MS + 60_000,
+ );
+});
diff --git a/packages/app/tests/integration/persistence-divergence-realign.test.ts b/packages/app/tests/integration/persistence-divergence-realign.test.ts
new file mode 100644
index 000000000..e34c5b2f9
--- /dev/null
+++ b/packages/app/tests/integration/persistence-divergence-realign.test.ts
@@ -0,0 +1,261 @@
+/**
+ * The L3 store-time divergence realign as a CONTENT-LOSS site.
+ *
+ * `disk-divergence-backstop.test.ts` already pins the arm's disk-authority
+ * contract: on a TOCTOU divergence the store aborts, disk wins, and the agent
+ * gets a 409. That contract is correct and this suite does not touch it. What
+ * that suite never asks is what happens to the LIVE DOCUMENT the realign
+ * overwrites — and the answer is that everything the CRDT held goes away.
+ *
+ * The realign applies disk over the doc under `FILE_WATCHER_ORIGIN`, which the
+ * server UndoManager excludes by contract and which reaches browsers as a
+ * remote update outside any local `trackedOrigins` set. So the discarded state
+ * is undoable on neither side, and until this suite it minted no restore anchor
+ * and reported no loss-ring breadcrumb. The bytes at risk are not only the
+ * agent's rejected write — a human's in-flight WYSIWYG paragraph that merged
+ * alongside it in the same Y.Doc is destroyed too, and the human is never told.
+ *
+ * That is the same shape as the duplication tripwire one arm above it in
+ * `onStoreDocument`, audited as Gap 1 of the content-loss class sweep. The
+ * difference is that this arm fires on a REAL external-writer conflict rather
+ * than a false positive, so the repair itself stays — what it owes is
+ * recoverability and a signal, not a narrower trigger.
+ *
+ * Fidelity: real boot (`createTestServer`), real HTTP agent-write path, real
+ * `onStoreDocument`, real WS client, real shadow repo, real loss ring. The only
+ * affordance is the `OK_TEST_STORE_DIVERGENCE` seam the sibling L3 suite
+ * already relies on — a real native edit cannot be timed into the residual
+ * TOCTOU window deterministically, because the file watcher races it and can
+ * flip `lastTransactionOrigin` to file-watcher, gating L3 out entirely.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseCheckpoint } from '@inkeep/open-knowledge-core';
+import { afterEach, describe, expect, test } from 'vitest';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { createTestClient, createTestServer, type TestServer } from './test-harness.ts';
+
+/** Must match the content the `OK_TEST_STORE_DIVERGENCE` seam writes. */
+const INJECTED_MARKER = 'native-divergence-injected';
+
+/**
+ * A human's in-flight paragraph, live in the CRDT and not yet on disk when the
+ * realign fires. Distinctive so a substring search cannot false-match.
+ */
+const HUMAN_PENDING_LINE = 'Zzz human paragraph typed before the realign.';
+
+const AGENT_LINE = 'AGENT-APPEND-XYZ';
+
+interface LossRingEvent {
+ event: string;
+ docName: string;
+ site?: string;
+ direction?: string;
+ writerId?: string | null;
+ lostLen?: number;
+ digest?: string;
+ checkpointSha?: string;
+}
+
+let server: TestServer | undefined;
+
+afterEach(async () => {
+ delete process.env.OK_TEST_STORE_DIVERGENCE;
+ if (server) {
+ await server.cleanup();
+ server = undefined;
+ }
+});
+
+function readLossEvents(contentDir: string): LossRingEvent[] {
+ const path = join(contentDir, '.ok', 'local', 'loss-capture', 'loss-current.jsonl');
+ if (!existsSync(path)) return [];
+ return readFileSync(path, 'utf-8')
+ .split('\n')
+ .filter((line) => line.length > 0)
+ .flatMap((line) => {
+ try {
+ return [JSON.parse(line) as LossRingEvent];
+ } catch {
+ return [];
+ }
+ });
+}
+
+/** The shadow repo the harness boots — `<projectDir>/.git/ok` (main-worktree shape). */
+function shadowDirFor(s: TestServer): string {
+ const dir = join(s.contentDir, '.git', 'ok');
+ if (!existsSync(dir)) {
+ throw new Error(`shadow repo not found at ${dir}; the rig needs gitEnabled: true`);
+ }
+ return dir;
+}
+
+function shadowGitRaw(s: TestServer, args: string[]): string {
+ return execFileSync('git', ['--git-dir', shadowDirFor(s), ...args], {
+ encoding: 'utf-8',
+ }).toString();
+}
+
+/**
+ * Every checkpoint the shadow holds, listed across ALL branch namespaces rather
+ * than the one this test would otherwise have to guess. Checkpoint refs are
+ * namespaced `refs/checkpoints/<branch>` off the real repo HEAD, so a machine
+ * defaulting to `master` files the anchor somewhere a `refs/checkpoints/main`
+ * listing does not look.
+ */
+function listCheckpoints(s: TestServer): Array<{ sha: string; kind: string | null }> {
+ const shas = shadowGitRaw(s, ['for-each-ref', '--format=%(objectname)', 'refs/checkpoints'])
+ .split('\n')
+ .map((x) => x.trim())
+ .filter(Boolean);
+ return shas.map((sha) => ({
+ sha,
+ kind: parseCheckpoint(shadowGitRaw(s, ['log', '-1', '--format=%B', sha]))?.kind ?? null,
+ }));
+}
+
+async function agentWriteMd(
+ port: number,
+ markdown: string,
+ opts: { docName: string; position: 'append' | 'prepend' | 'replace' },
+): Promise<Response> {
+ return fetch(`http://127.0.0.1:${port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ markdown, ...opts }),
+ });
+}
+
+async function pollUntil(
+ predicate: () => boolean,
+ { timeoutMs = 10_000, pollMs = 50 }: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<void> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return;
+ await new Promise((r) => setTimeout(r, pollMs));
+ }
+ throw new Error(`pollUntil timed out after ${timeoutMs}ms`);
+}
+
+describe('L3 agent-write divergence realign — content-loss conventions', () => {
+ test(
+ 'the realign checkpoints the live document and reports the loss before discarding it',
+ async () => {
+ server = await createTestServer({
+ gitEnabled: true,
+ // Persistence must not flush on its own: the human paragraph has to still
+ // be live-and-unpersisted at the moment the agent write forces the store.
+ debounce: 300_000,
+ maxDebounce: 600_000,
+ });
+ const { port, contentDir } = server;
+ const docName = `realign-${randomUUID().slice(0, 8)}`;
+ const docPath = join(contentDir, `${docName}.md`);
+
+ // Seed through the agent path. This forces a flush, so disk, the reconciled
+ // base, and the live document all agree before anything diverges.
+ const seed = await agentWriteMd(port, '# V1\n\nbody-v1\n', { docName, position: 'replace' });
+ expect(seed.status).toBe(200);
+ await pollUntil(
+ () => existsSync(docPath) && readFileSync(docPath, 'utf-8').includes('body-v1'),
+ );
+
+ // A human is typing in the browser. Real WS client, real remote update.
+ const client = await createTestClient(port, docName, { skipInvariantWatcher: true });
+ await pollUntil(() => client.ytext.toString().includes('body-v1'));
+ const before = client.ytext.toString();
+ client.doc.transact(() => {
+ client.ytext.insert(before.length, `\n${HUMAN_PENDING_LINE}\n`);
+ });
+ await pollUntil(() =>
+ Boolean(
+ server?.instance.hocuspocus.documents
+ .get(docName)
+ ?.getText('source')
+ .toString()
+ .includes(HUMAN_PENDING_LINE),
+ ),
+ );
+ // Precondition: the human's bytes are live but NOT on disk. Everything this
+ // test claims is destroyed has to actually be at risk.
+ expect(readFileSync(docPath, 'utf-8')).not.toContain(HUMAN_PENDING_LINE);
+
+ // Arm the in-store divergence: a native writer lands between L1's reconcile
+ // and this store's write, which is the residual TOCTOU L3 exists to catch.
+ process.env.OK_TEST_STORE_DIVERGENCE = docName;
+
+ const attempt = await agentWriteMd(port, `${AGENT_LINE}\n`, { docName, position: 'append' });
+ expect(attempt.status).toBe(409);
+ expect(((await attempt.json()) as { type?: string }).type).toBe(
+ 'urn:ok:error:disk-divergence',
+ );
+
+ // Disk-authority contract, unchanged: the native content wins.
+ await pollUntil(() => readFileSync(docPath, 'utf-8').includes(INJECTED_MARKER));
+ expect(readFileSync(docPath, 'utf-8')).not.toContain(AGENT_LINE);
+
+ // The premise of this suite: the realign took the human's live paragraph
+ // with it. This assertion PASSES on the unfixed tree — it documents the
+ // harm rather than the gap.
+ await pollUntil(
+ () =>
+ !server?.instance.hocuspocus.documents
+ .get(docName)
+ ?.getText('source')
+ .toString()
+ .includes(HUMAN_PENDING_LINE),
+ );
+
+ // (a) checkpoint-before-repair and (b) detection-site-owns-a-kind: the
+ // discarded document must be reachable again, under a kind an operator can
+ // tell apart from the tripwire reset and from the pre-write reconcile.
+ const rig = server;
+ await pollUntil(() =>
+ listCheckpoints(rig).some((c) => c.kind === 'persistence-divergence-realign'),
+ );
+ const anchors = listCheckpoints(rig).filter(
+ (c) => c.kind === 'persistence-divergence-realign',
+ );
+ expect(anchors).toHaveLength(1);
+ const anchor = anchors[0];
+ if (!anchor) throw new Error('unreachable: anchor asserted above');
+
+ // (c) undoability: `FILE_WATCHER_ORIGIN` is reachable by neither undo stack,
+ // so the anchor is the only way back. Prove it holds the real bytes rather
+ // than merely existing — the blob must carry the human's paragraph.
+ const blob = shadowGitRaw(rig, ['show', `${anchor.sha}:${docName}`]);
+ expect(blob).toContain(HUMAN_PENDING_LINE);
+
+ // (d) observable signal: the loss ring must carry a detector trip for this
+ // site, and the checkpoint write, so a diagnostics bundle shows the event.
+ const ring = readLossEvents(contentDir).filter(
+ (e) => e.site === 'persistence-divergence-realign' && e.docName === docName,
+ );
+ const trips = ring.filter((e) => e.event === 'detector-trip');
+ expect(trips).toHaveLength(1);
+ expect(trips[0]?.direction).toBe('b');
+ expect(trips[0]?.lostLen ?? 0).toBeGreaterThanOrEqual(HUMAN_PENDING_LINE.length);
+ // Content-free ring: never the lost bytes themselves.
+ expect(JSON.stringify(trips[0])).not.toContain(HUMAN_PENDING_LINE);
+ // Polled, not asserted once: git creates the checkpoint ref before the write
+ // promise settles, so the anchor is visible to `for-each-ref` a beat before
+ // the `.then` records its ring event.
+ await pollUntil(() =>
+ readLossEvents(contentDir).some(
+ (e) =>
+ e.site === 'persistence-divergence-realign' &&
+ e.event === 'checkpoint-write' &&
+ e.checkpointSha === anchor.sha,
+ ),
+ );
+
+ await client.cleanup();
+ },
+ HARNESS_BOOT_TIMEOUT_MS + 60_000,
+ );
+});
diff --git a/packages/core/src/checkpoint-kind-registry.test.ts b/packages/core/src/checkpoint-kind-registry.test.ts
index e06872040..0631f138f 100644
--- a/packages/core/src/checkpoint-kind-registry.test.ts
+++ b/packages/core/src/checkpoint-kind-registry.test.ts
@@ -74,6 +74,18 @@ const SAMPLE_BY_KIND = {
size: 12,
metadata: { copies: 2, fragmentChildren: 18 },
},
+ 'persistence-divergence-realign': {
+ kind: 'persistence-divergence-realign',
+ docName: 'notes',
+ size: 12,
+ metadata: { diskBytes: 37, discardedBytes: 79 },
+ },
+ 'managed-artifact-reconcile': {
+ kind: 'managed-artifact-reconcile',
+ docName: '.ok/templates/daily',
+ size: 12,
+ metadata: { diskBytes: 41, discardedBytes: 66 },
+ },
'auto-consolidation': {
kind: 'auto-consolidation',
docName: null,
diff --git a/packages/core/src/checkpoint-kinds.ts b/packages/core/src/checkpoint-kinds.ts
index acdc193b9..8b58d168b 100644
--- a/packages/core/src/checkpoint-kinds.ts
+++ b/packages/core/src/checkpoint-kinds.ts
@@ -164,6 +164,36 @@ export type ParsedCheckpoint =
size: number | null;
metadata: { copies: number; fragmentChildren: number };
}
+ | {
+ // The persistence L3 store-time divergence backstop found that disk had
+ // moved away from the reconciled base between L1's check and this store,
+ // declared disk the winner, and applied it over the live document. That
+ // realign transacts under the file-watcher origin, so the live state it
+ // discards — the agent's rejected write AND any human WYSIWYG edit that
+ // had merged alongside it — is undo-eligible on neither side. Distinct
+ // from `persistence-duplication-reset` (a duplication verdict) so an
+ // operator can tell an external-writer conflict from a duplication trip
+ // by kind alone. `contents` is the pre-realign document — the restore
+ // anchor. Both metadata fields are content-free byte counts.
+ kind: 'persistence-divergence-realign';
+ docName: string | null;
+ size: number | null;
+ metadata: { diskBytes: number; discardedBytes: number };
+ }
+ | {
+ // The managed-artifact store found the file changed under it by a second
+ // writer (another OK window, a hand edit, a CLI write) and imported the
+ // disk bytes over the live artifact doc rather than clobbering them. Same
+ // file-watcher origin, same undo-inaccessibility; `contents` is the live
+ // artifact the reconcile discards. Its own kind because the content class
+ // differs — skills and templates, not primary prose — so an operator can
+ // budget and triage it separately from the document-path realign. Both
+ // metadata fields are content-free byte counts.
+ kind: 'managed-artifact-reconcile';
+ docName: string | null;
+ size: number | null;
+ metadata: { diskBytes: number; discardedBytes: number };
+ }
| {
// Service-authored consolidation of dead/stale WIP chains.
// GET /api/history excludes this kind by default so daily
@@ -337,6 +367,25 @@ export function parseCheckpoint(body: string): ParsedCheckpoint | null {
}
return null;
}
+ if (kind === 'persistence-divergence-realign' || kind === 'managed-artifact-reconcile') {
+ // Both carry the identical content-free byte-count pair, so one guard
+ // serves both discriminants without widening either metadata shape.
+ const m = metadata as { diskBytes?: unknown; discardedBytes?: unknown };
+ if (
+ typeof m.diskBytes === 'number' &&
+ Number.isFinite(m.diskBytes) &&
+ typeof m.discardedBytes === 'number' &&
+ Number.isFinite(m.discardedBytes)
+ ) {
+ return {
+ kind,
+ docName,
+ size,
+ metadata: { diskBytes: m.diskBytes, discardedBytes: m.discardedBytes },
+ };
+ }
+ return null;
+ }
if (kind === 'auto-consolidation') {
const m = metadata as { foldedRefs?: unknown; trigger?: unknown };
if (
@@ -534,6 +583,23 @@ export const CHECKPOINT_KIND_REGISTRY = {
bundleExposure: 'metadata',
chainAnchor: false,
},
+ // Both buckets below are TTL-bounded (`applyTtl: true` in `GC_BUCKET_POLICY`,
+ // budgets `maxPersistenceDivergenceRealign` / `maxManagedArtifactReconcile`),
+ // so either can be reaped to nothing and a chain routed through one would be
+ // severed the moment it was. `auto-consolidation` remains the only count-only
+ // bucket and the only anchor.
+ 'persistence-divergence-realign': {
+ visibility: 'surfaced',
+ gcBucket: 'persistence-divergence-realign',
+ bundleExposure: 'metadata',
+ chainAnchor: false,
+ },
+ 'managed-artifact-reconcile': {
+ visibility: 'surfaced',
+ gcBucket: 'managed-artifact-reconcile',
+ bundleExposure: 'metadata',
+ chainAnchor: false,
+ },
'auto-consolidation': {
visibility: 'hidden',
gcBucket: 'auto-consolidation',
diff --git a/packages/server/src/managed-artifact-persistence.test.ts b/packages/server/src/managed-artifact-persistence.test.ts
index b1f879624..efc35c86d 100644
--- a/packages/server/src/managed-artifact-persistence.test.ts
+++ b/packages/server/src/managed-artifact-persistence.test.ts
@@ -250,6 +250,68 @@ describe('concurrent-writer reconcile', () => {
expect(reconciled.get(docName)).toBe(otherWriter);
});
+ /**
+ * Global skills are the reconcile arm's primary reachable case — project
+ * skills return 'no-op' before it, so the reachable set is global skills plus
+ * templates. They also live outside any project shadow repo, which makes them
+ * the unanchorable half of the site: the hook still has to run so the counter
+ * and the ring breadcrumb fire, even though there is nowhere to file an
+ * anchor. The booted template test pins the anchored half; this pins the hand-
+ * off, which is what tells the anchored half it will ever be reached.
+ */
+ test('reconcile invokes beforeReconcileDivergence with the live and disk content', async () => {
+ const calls: Array<{ docName: string; live: string; disk: string }> = [];
+ const ctx: ManagedArtifactCtx = {
+ ...makeCtx(),
+ beforeReconcileDivergence: (_doc, name, live, disk) => {
+ calls.push({ docName: name, live, disk });
+ return undefined;
+ },
+ };
+ const doc = new Y.Doc();
+ const v1 = '---\nname: demo\ndescription: a\n---\nA\n';
+ doc.transact(() => doc.getText('source').insert(0, v1), 'agent');
+ await storeManagedArtifactDoc(doc, docName, 'agent', ctx);
+ expect(calls).toHaveLength(0); // a clean store must not look like a reconcile
+
+ const path = managedArtifactAbsPath(docName, ctx);
+ const otherWriter = '---\nname: demo\ndescription: a\n---\nOTHER WRITER\n';
+ writeFileSync(path, otherWriter, 'utf-8');
+
+ doc.transact(
+ () => doc.getText('source').insert(doc.getText('source').length, 'local edit'),
+ 'agent',
+ );
+ const live = doc.getText('source').toString();
+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('reconciled');
+
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.docName).toBe(docName);
+ // The live bytes handed to the hook are the ones about to be discarded, and
+ // the disk bytes are the baseline the detector measures against. Getting
+ // these backwards would checkpoint the content that survives.
+ expect(calls[0]?.live).toBe(live);
+ expect(calls[0]?.live).toContain('local edit');
+ expect(calls[0]?.disk).toBe(otherWriter);
+ });
+
+ test('reconcile still returns reconciled when no checkpoint hook is wired', async () => {
+ // Ephemeral boots and unit rigs build a ctx without the hook. The repair
+ // must not depend on the anchor being available.
+ const ctx = makeCtx();
+ expect(ctx.beforeReconcileDivergence).toBeUndefined();
+ const doc = new Y.Doc();
+ doc.transact(
+ () => doc.getText('source').insert(0, '---\nname: demo\ndescription: a\n---\nA\n'),
+ 'agent',
+ );
+ await storeManagedArtifactDoc(doc, docName, 'agent', ctx);
+ const path = managedArtifactAbsPath(docName, ctx);
+ writeFileSync(path, '---\nname: demo\ndescription: a\n---\nOTHER\n', 'utf-8');
+ doc.transact(() => doc.getText('source').insert(doc.getText('source').length, 'x'), 'agent');
+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('reconciled');
+ });
+
test('applyExternalManagedArtifactChange imports disk bytes into the live doc', () => {
const ctx = makeCtx();
const doc = new Y.Doc();
diff --git a/packages/server/src/managed-artifact-persistence.ts b/packages/server/src/managed-artifact-persistence.ts
index 6655be35a..e1ff726d7 100644
--- a/packages/server/src/managed-artifact-persistence.ts
+++ b/packages/server/src/managed-artifact-persistence.ts
@@ -42,9 +42,11 @@ import {
withFileLock,
} from '@inkeep/open-knowledge-core/server';
import type * as Y from 'yjs';
+import type { DeriveLossDetectOptions } from './bridge-loss-detector.ts';
import { applyDiskContentToDoc, FILE_WATCHER_ORIGIN } from './disk-content-intake.ts';
import { tracedAtomicFs, tracedMkdir } from './fs-traced.ts';
import { getLogger } from './logger.ts';
+import { incrementManagedArtifactReconcile } from './metrics.ts';
const log = getLogger('managed-artifact-persistence');
@@ -62,6 +64,35 @@ export interface ManagedArtifactCtx {
/** Injected from `persistence.ts` (avoids a circular import). */
setReconciledBase: (docName: string, content: string) => void;
getReconciledBase: (docName: string) => string | undefined;
+ /**
+ * Called immediately before the concurrent-writer reconcile replaces the live
+ * artifact with the disk bytes. Mints the restore anchor for `liveContent`
+ * (the reconcile transacts under `FILE_WATCHER_ORIGIN`, so neither undo stack
+ * can reach it) and returns the paired-intake detector for the import, so the
+ * discarded content reaches the loss ring instead of vanishing silently.
+ *
+ * Injected rather than imported for the same reason the reconciled-base
+ * accessors are: the shadow repo, the loss ring, and the branch resolver all
+ * live in `persistence.ts`, and importing them here would close a cycle.
+ * Optional so a ctx built without that plumbing (unit rigs, ephemeral boots)
+ * still reconciles — it just reconciles unanchored, which the
+ * `managedArtifactReconcile` counter records.
+ *
+ * The detector is RETURNED rather than constructed here, which is why this
+ * hook bundles two jobs where the document-path sibling
+ * (`checkpointBeforeDivergenceRealign`) only checkpoints and lets its caller
+ * build `detect` inline. That asymmetry is the DI boundary, not a style
+ * choice: a `detect` reporter needs the loss ring, the site constant, and
+ * `fnv1aDigest`, none of which this module can reach without the cycle the
+ * seam exists to avoid. A follow-up site inside `persistence.ts` should
+ * follow the realign shape; one outside it should follow this one.
+ */
+ beforeReconcileDivergence?: (
+ document: Y.Doc,
+ documentName: string,
+ liveContent: string,
+ diskContent: string,
+ ) => DeriveLossDetectOptions | undefined;
}
/** Store outcome — surfaced for tests + telemetry. */
@@ -387,8 +418,15 @@ export async function storeManagedArtifactDoc(
disk = null;
}
if (disk !== null && disk !== lkg && disk !== content) {
+ // The reconcile discards whatever the author had live under an origin
+ // neither undo stack can reach, so it owes a restore anchor and a
+ // loss-ring breadcrumb before it touches the doc. The counter fires
+ // here rather than inside the hook so a ctx with no shadow plumbing
+ // still records that live content was replaced.
+ incrementManagedArtifactReconcile();
+ const detect = ctx.beforeReconcileDivergence?.(document, documentName, content, disk);
document.transact(() => {
- applyDiskContentToDoc(document, disk, undefined, documentName);
+ applyDiskContentToDoc(document, disk, undefined, documentName, undefined, detect);
}, FILE_WATCHER_ORIGIN);
ctx.setReconciledBase(documentName, disk);
ctx.lkgCache.set(documentName, disk);
diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.ts
index e06aca04e..47e0444a6 100644
--- a/packages/server/src/metrics.ts
+++ b/packages/server/src/metrics.ts
@@ -337,6 +337,34 @@ export interface ReconciliationMetrics {
* false-positive class the guard used to destroy; a healthy signal, not a
* loss. */
persistenceDuplicationSpared: number;
+ /** Count of L3 store-time divergence realigns — disk moved away from the
+ * reconciled base between L1's check and the store, so disk won and the live
+ * document was replaced. Increments on every realign, including ones with no
+ * shadow wired, so a run whose anchors never landed does not read as healthy.
+ * A nonzero value in a dogfood bundle means a second writer's edit displaced
+ * live CRDT state (the agent's write, and any human edit merged alongside). */
+ persistenceDivergenceRealign: number;
+ /** Successful `persistence-divergence-realign` checkpoint writes. With the
+ * deduped sibling this closes the identity
+ * `persistenceDivergenceRealign = created + deduped + (anchors that never landed)`. */
+ persistenceDivergenceRealignCheckpointCreated: number;
+ /** Realigns whose pre-realign document was byte-identical to the anchor already
+ * on the timeline for that doc, so no new checkpoint was minted. An agent
+ * retry-looping against a file a second writer keeps rewriting lives here;
+ * without the dedup it would evict its own useful anchors. */
+ persistenceDivergenceRealignDeduped: number;
+ /** Count of managed-artifact (skill/template) stores that reconciled against a
+ * concurrent writer instead of clobbering — the live artifact doc was replaced
+ * with the disk bytes. Increments on every reconcile, including unversioned
+ * artifacts (global skills) where no anchor can exist. */
+ managedArtifactReconcile: number;
+ /** Successful `managed-artifact-reconcile` checkpoint writes. Always ≤
+ * `managedArtifactReconcile`: global skills live outside any project shadow
+ * repo, so their reconciles are counted but structurally unanchorable. */
+ managedArtifactReconcileCheckpointCreated: number;
+ /** Reconciles whose pre-reconcile artifact was byte-identical to the anchor
+ * already on the timeline for that doc, so no new checkpoint was minted. */
+ managedArtifactReconcileDeduped: number;
/** Count of Y.Text→XmlFragment re-derive-loop backstop trips — a run of
* re-derive drains never reached a raw-byte fixed point and the B-direction
* re-derive was frozen (checkpoint + ring event). A nonzero value in CI or a
@@ -555,6 +583,12 @@ const counters: ReconciliationMetrics = {
persistenceDuplicationResetCheckpointCreated: 0,
persistenceDuplicationResetDeduped: 0,
persistenceDuplicationSpared: 0,
+ persistenceDivergenceRealign: 0,
+ persistenceDivergenceRealignCheckpointCreated: 0,
+ persistenceDivergenceRealignDeduped: 0,
+ managedArtifactReconcile: 0,
+ managedArtifactReconcileCheckpointCreated: 0,
+ managedArtifactReconcileDeduped: 0,
reDeriveBackstopTripped: 0,
bridgeSplitBrainRederives: 0,
bridgeSplitBrainRederivesSuppressed: 0,
@@ -804,6 +838,30 @@ export function incrementPersistenceDuplicationSpared(): void {
counters.persistenceDuplicationSpared++;
}
+export function incrementPersistenceDivergenceRealign(): void {
+ counters.persistenceDivergenceRealign++;
+}
+
+export function incrementPersistenceDivergenceRealignCheckpointCreated(): void {
+ counters.persistenceDivergenceRealignCheckpointCreated++;
+}
+
+export function incrementPersistenceDivergenceRealignDeduped(): void {
+ counters.persistenceDivergenceRealignDeduped++;
+}
+
+export function incrementManagedArtifactReconcile(): void {
+ counters.managedArtifactReconcile++;
+}
+
+export function incrementManagedArtifactReconcileCheckpointCreated(): void {
+ counters.managedArtifactReconcileCheckpointCreated++;
+}
+
+export function incrementManagedArtifactReconcileDeduped(): void {
+ counters.managedArtifactReconcileDeduped++;
+}
+
export function incrementReDeriveBackstopTripped(): void {
counters.reDeriveBackstopTripped++;
}
@@ -1017,6 +1075,12 @@ export function resetMetrics(): void {
counters.persistenceDuplicationResetCheckpointCreated = 0;
counters.persistenceDuplicationResetDeduped = 0;
counters.persistenceDuplicationSpared = 0;
+ counters.persistenceDivergenceRealign = 0;
+ counters.persistenceDivergenceRealignCheckpointCreated = 0;
+ counters.persistenceDivergenceRealignDeduped = 0;
+ counters.managedArtifactReconcile = 0;
+ counters.managedArtifactReconcileCheckpointCreated = 0;
+ counters.managedArtifactReconcileDeduped = 0;
counters.reDeriveBackstopTripped = 0;
counters.bridgeSplitBrainRederives = 0;
counters.bridgeSplitBrainRederivesSuppressed = 0;
diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.ts
index 6643e0fb0..e12b0278e 100644
--- a/packages/server/src/persistence.ts
+++ b/packages/server/src/persistence.ts
@@ -84,6 +84,7 @@ import {
loadManagedArtifactDoc,
type ManagedArtifactCtx,
managedArtifactContributorAttribution,
+ managedArtifactTimelinePaths,
storeManagedArtifactDoc,
} from './managed-artifact-persistence.ts';
import { mdManager, schema } from './md-manager.ts';
@@ -96,8 +97,13 @@ import {
incrementDeferredStoreFailures,
incrementGitAutoSaveFailure,
incrementGitWriterCommitFailure,
+ incrementManagedArtifactReconcileCheckpointCreated,
+ incrementManagedArtifactReconcileDeduped,
incrementPersistenceDeferHold,
incrementPersistenceDiskWrite,
+ incrementPersistenceDivergenceRealign,
+ incrementPersistenceDivergenceRealignCheckpointCreated,
+ incrementPersistenceDivergenceRealignDeduped,
incrementPersistenceDuplicationReset,
incrementPersistenceDuplicationResetCheckpointCreated,
incrementPersistenceDuplicationResetDeduped,
@@ -642,6 +648,8 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
lkgCache: managedArtifactLkgCache,
setReconciledBase: (docName, content) => durabilityState.setReconciledBase(docName, content),
getReconciledBase: (docName) => durabilityState.getReconciledBase(docName),
+ beforeReconcileDivergence: (document, docName, liveContent, diskContent) =>
+ checkpointBeforeManagedArtifactReconcile(document, docName, liveContent, diskContent),
};
// Mermaid (`.mmd`/`.mermaid`) persistence ctx. Y.Text-only, content-dir paths,
@@ -1153,6 +1161,8 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
*/
const PERSISTENCE_PREWRITE_SITE = 'persistence-prewrite';
const PERSISTENCE_DUPLICATION_SITE = 'persistence-duplication-reset';
+ const PERSISTENCE_REALIGN_SITE = 'persistence-divergence-realign';
+ const MANAGED_ARTIFACT_RECONCILE_SITE = 'managed-artifact-reconcile';
/**
* Last floor-checkpoint payload minted per document. Some documents diverge
@@ -1292,16 +1302,13 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
fragmentChildren: number,
): void {
incrementPersistenceDuplicationReset();
- if (lastDuplicationCheckpointPayload.get(document) === liveMarkdown) {
- incrementPersistenceDuplicationResetDeduped();
- return;
- }
- // Claimed before the write so two trips can never race into two anchors;
- // released again if the write fails, so a transient shadow error still
- // retries on the next trip instead of permanently suppressing the anchor.
- lastDuplicationCheckpointPayload.set(document, liveMarkdown);
const ring = options?.getLossRing?.();
const shadow = shadowRef?.current;
+ // The shadow guard precedes the dedup claim deliberately. Claiming first
+ // would let a single no-shadow trip pin the payload forever, so every later
+ // trip with that same content would dedup into silence — no anchor, and no
+ // ring record either. The breadcrumb is the only signal a no-shadow run
+ // has; it must not be deduped away.
if (!shadow) {
void ring?.record({
event: LOSS_EVENT_CHECKPOINT_WRITE,
@@ -1313,6 +1320,14 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
});
return;
}
+ if (lastDuplicationCheckpointPayload.get(document) === liveMarkdown) {
+ incrementPersistenceDuplicationResetDeduped();
+ return;
+ }
+ // Claimed before the write so two trips can never race into two anchors;
+ // released again if the write fails, so a transient shadow error still
+ // retries on the next trip instead of permanently suppressing the anchor.
+ lastDuplicationCheckpointPayload.set(document, liveMarkdown);
const branch = getCurrentBranch?.() ?? 'main';
queueMicrotask(() => {
saveInMemoryCheckpoint(shadow, contentRoot, {
@@ -1358,6 +1373,229 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
});
}
+ const lastRealignCheckpointPayload = new WeakMap<Y.Doc, string>();
+
+ /**
+ * Checkpoint-before-repair for the L3 store-time divergence realign.
+ *
+ * `liveMarkdown` is the document the realign is about to discard. Unlike the
+ * duplication tripwire this arm fires on a genuine external-writer conflict,
+ * so the disk-wins decision itself is correct and stays — but the realign
+ * transacts under `FILE_WATCHER_ORIGIN` all the same, which the server
+ * UndoManager excludes by contract and which reaches browsers as a remote
+ * update outside any local `trackedOrigins` set. The agent learns its write
+ * did not land; the human whose WYSIWYG edit merged alongside it learns
+ * nothing, and this anchor is their only way back.
+ *
+ * Fire-and-forget, and the realign is never gated on it — the dedup
+ * suppresses the MINT, not the repair.
+ *
+ * Takes the disk bytes rather than their length so the caller cannot pass a
+ * length that has drifted from the content it describes; the sibling
+ * managed-artifact helper takes the same shape.
+ */
+ function checkpointBeforeDivergenceRealign(
+ document: Y.Doc,
+ documentName: string,
+ liveMarkdown: string,
+ diskContent: string,
+ ): void {
+ incrementPersistenceDivergenceRealign();
+ const ring = options?.getLossRing?.();
+ const shadow = shadowRef?.current;
+ // The shadow guard precedes the dedup claim deliberately. Claiming first
+ // would let a single no-shadow trip pin the payload forever, so every later
+ // trip with that same content would dedup into silence — no anchor, and no
+ // ring record either. The breadcrumb is the only signal a no-shadow run
+ // has; it must not be deduped away.
+ if (!shadow) {
+ void ring?.record({
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName: documentName,
+ writerId: null,
+ direction: 'b',
+ site: PERSISTENCE_REALIGN_SITE,
+ lostLen: liveMarkdown.length,
+ });
+ return;
+ }
+ if (lastRealignCheckpointPayload.get(document) === liveMarkdown) {
+ incrementPersistenceDivergenceRealignDeduped();
+ return;
+ }
+ // Claimed before the write so two trips can never race into two anchors;
+ // released again if the write fails, so a transient shadow error still
+ // retries on the next trip instead of permanently suppressing the anchor.
+ lastRealignCheckpointPayload.set(document, liveMarkdown);
+ const branch = getCurrentBranch?.() ?? 'main';
+ queueMicrotask(() => {
+ saveInMemoryCheckpoint(shadow, contentRoot, {
+ kind: 'persistence-divergence-realign',
+ docName: documentName,
+ contents: liveMarkdown,
+ label: `Before divergence realign @ ${new Date().toISOString()}`,
+ branch,
+ metadata: { diskBytes: diskContent.length, discardedBytes: liveMarkdown.length },
+ })
+ .then((sha) => {
+ incrementPersistenceDivergenceRealignCheckpointCreated();
+ void ring?.record({
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName: documentName,
+ writerId: null,
+ direction: 'b',
+ site: PERSISTENCE_REALIGN_SITE,
+ lostLen: liveMarkdown.length,
+ checkpointSha: sha,
+ });
+ console.warn(
+ JSON.stringify({
+ event: 'persistence-divergence-realign-checkpoint-created',
+ docName: documentName,
+ sha,
+ kind: 'persistence-divergence-realign',
+ timestamp: new Date().toISOString(),
+ }),
+ );
+ })
+ .catch((checkpointErr: unknown) => {
+ if (lastRealignCheckpointPayload.get(document) === liveMarkdown) {
+ lastRealignCheckpointPayload.delete(document);
+ }
+ const e =
+ checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
+ log.warn(
+ { documentName, err: e },
+ '[persistence] divergence-realign checkpoint write failed',
+ );
+ });
+ });
+ }
+
+ const lastManagedReconcileCheckpointPayload = new WeakMap<Y.Doc, string>();
+
+ /**
+ * Checkpoint-before-repair for the managed-artifact concurrent-writer
+ * reconcile, plus the paired-intake detector for the import that follows.
+ *
+ * Reached only through `ManagedArtifactCtx.beforeReconcileDivergence`, which
+ * exists because the shadow repo, the loss ring, and the branch resolver all
+ * live in this closure and importing them into the artifact module would
+ * close a cycle.
+ *
+ * The anchor is filed under the artifact's TIMELINE key
+ * (`.ok/skills/<name>` / `<folder>/.ok/templates/<name>`), not the synthetic
+ * `__skill__` / `__template__` doc name, so it addresses the same path the
+ * history surface reads. Global skills live outside any project shadow repo
+ * and are unversioned by construction — they get the ring breadcrumb and the
+ * detector, but no anchor, because there is nowhere to file one.
+ */
+ function checkpointBeforeManagedArtifactReconcile(
+ document: Y.Doc,
+ documentName: string,
+ liveContent: string,
+ diskContent: string,
+ ): DeriveLossDetectOptions | undefined {
+ // No fire counter here, unlike the two sibling helpers: the reconcile's
+ // `incrementManagedArtifactReconcile()` fires at the call site in
+ // `managed-artifact-persistence.ts`, so a ctx built without this hook still
+ // records that live content was replaced.
+ const ring = options?.getLossRing?.();
+ const detect: DeriveLossDetectOptions = {
+ baselineFullMd: diskContent,
+ report: (obs) => {
+ // Never throws, per the reporter contract — this runs inside the
+ // reconcile transact, and the store's catch would report the whole
+ // write as failed on a purely diagnostic error.
+ try {
+ const dropped = detectPairedIntakeLoss(obs);
+ if (dropped.length === 0) return;
+ void ring?.record({
+ event: LOSS_EVENT_DETECTOR_TRIP,
+ docName: documentName,
+ writerId: FILE_SYSTEM_WRITER.id,
+ direction: 'b',
+ site: MANAGED_ARTIFACT_RECONCILE_SITE,
+ lostLen: dropped.reduce((n, s) => n + s.length, 0),
+ digest: fnv1aDigest(dropped.join('\n')),
+ });
+ } catch (detectErr) {
+ log.warn(
+ { documentName, err: detectErr },
+ '[persistence] managed-artifact reconcile loss detection failed',
+ );
+ }
+ },
+ };
+
+ const paths = managedArtifactTimelinePaths(documentName);
+ const shadow = shadowRef?.current;
+ if (!shadow || !paths.managed || !paths.versioned) {
+ void ring?.record({
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName: documentName,
+ writerId: null,
+ direction: 'b',
+ site: MANAGED_ARTIFACT_RECONCILE_SITE,
+ lostLen: liveContent.length,
+ });
+ return detect;
+ }
+ if (lastManagedReconcileCheckpointPayload.get(document) === liveContent) {
+ incrementManagedArtifactReconcileDeduped();
+ return detect;
+ }
+ // Claimed before the write so two trips can never race into two anchors;
+ // released again if the write fails, so a transient shadow error still
+ // retries on the next trip instead of permanently suppressing the anchor.
+ lastManagedReconcileCheckpointPayload.set(document, liveContent);
+ const branch = getCurrentBranch?.() ?? 'main';
+ const anchorDocName = paths.docKey;
+ queueMicrotask(() => {
+ saveInMemoryCheckpoint(shadow, contentRoot, {
+ kind: 'managed-artifact-reconcile',
+ docName: anchorDocName,
+ contents: liveContent,
+ label: `Before artifact reconcile @ ${new Date().toISOString()}`,
+ branch,
+ metadata: { diskBytes: diskContent.length, discardedBytes: liveContent.length },
+ })
+ .then((sha) => {
+ incrementManagedArtifactReconcileCheckpointCreated();
+ void ring?.record({
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName: documentName,
+ writerId: null,
+ direction: 'b',
+ site: MANAGED_ARTIFACT_RECONCILE_SITE,
+ lostLen: liveContent.length,
+ checkpointSha: sha,
+ });
+ console.warn(
+ JSON.stringify({
+ event: 'managed-artifact-reconcile-checkpoint-created',
+ docName: documentName,
+ sha,
+ kind: 'managed-artifact-reconcile',
+ timestamp: new Date().toISOString(),
+ }),
+ );
+ })
+ .catch((checkpointErr: unknown) => {
+ if (lastManagedReconcileCheckpointPayload.get(document) === liveContent) {
+ lastManagedReconcileCheckpointPayload.delete(document);
+ }
+ const e =
+ checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
+ log.warn(
+ { documentName, err: e },
+ '[persistence] managed-artifact reconcile checkpoint write failed',
+ );
+ });
+ });
+ return detect;
+ }
+
// Lazy-init histograms; safe to call in every hook. Meter is a no-op when OTel
// SDK is disabled, so allocations are essentially free.
let loadDurationHist: ReturnType<ReturnType<typeof getMeter>['createHistogram']> | null = null;
@@ -2059,6 +2297,46 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
candidateBytes: markdown.length,
}),
);
+ // The realign discards the live document under an origin neither
+ // undo stack can reach, so it owes a restore anchor first. Minted
+ // before the transact and never gated on — a shadow failure degrades
+ // observability, never the disk-authority repair.
+ checkpointBeforeDivergenceRealign(document, documentName, markdown, diskContent);
+ // The disk bytes are the state the live document is being realigned
+ // ONTO, so fragment content absent from them is exactly what this
+ // realign destroys. That baseline is what makes the paired-intake
+ // detector report the discarded content instead of staying silent —
+ // the precondition that lets the other persistence callers omit
+ // `detect` (they re-apply bytes the fragment already derives from)
+ // is false here by construction.
+ const lossRing = options?.getLossRing?.();
+ const detect: DeriveLossDetectOptions = {
+ baselineFullMd: diskContent,
+ report: (obs) => {
+ // Never throws, per the reporter contract. This runs INSIDE the
+ // realign transact, whose catch records a store failure and
+ // rethrows — a diagnostic failure escaping here would report the
+ // disk-authority repair as failed when it actually succeeded.
+ try {
+ const dropped = detectPairedIntakeLoss(obs);
+ if (dropped.length === 0) return;
+ void lossRing?.record({
+ event: LOSS_EVENT_DETECTOR_TRIP,
+ docName: documentName,
+ writerId: FILE_SYSTEM_WRITER.id,
+ direction: 'b',
+ site: PERSISTENCE_REALIGN_SITE,
+ lostLen: dropped.reduce((n, s) => n + s.length, 0),
+ digest: fnv1aDigest(dropped.join('\n')),
+ });
+ } catch (detectErr) {
+ log.warn(
+ { documentName, err: detectErr },
+ '[persistence] divergence-realign loss detection failed',
+ );
+ }
+ },
+ };
// Caller-wrapped FILE_WATCHER_ORIGIN transact (paired-write +
// skipStoreHooks), matching the tripwire-reset ingest — so the
// realign fires no nested store and stays out of the agent's
@@ -2072,7 +2350,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
// setReconciledBase) so a retry re-reads disk and reconciles again.
try {
document.transact(() => {
- applyDiskContent(document, diskContent);
+ applyDiskContent(document, diskContent, undefined, undefined, undefined, detect);
}, FILE_WATCHER_ORIGIN);
} catch (err) {
durabilityState.recordStoreFailure(documentName, toStoreFailure(err));
diff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.ts
index 74a0bd38a..4dcf41d4c 100644
--- a/packages/server/src/shadow-repo.test.ts
+++ b/packages/server/src/shadow-repo.test.ts
@@ -1592,6 +1592,26 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)
metadata: { copies: 2, fragmentChildren: 18 },
});
return;
+ case 'persistence-divergence-realign':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'k.md',
+ contents: `k${tag}\n`,
+ label: 'l',
+ date,
+ metadata: { diskBytes: 37, discardedBytes: 79 },
+ });
+ return;
+ case 'managed-artifact-reconcile':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'm.md',
+ contents: `m${tag}\n`,
+ label: 'l',
+ date,
+ metadata: { diskBytes: 41, discardedBytes: 66 },
+ });
+ return;
case 'auto-consolidation':
await writeAutoConsolidationCheckpoint(shadow, tag === '' ? 1 : Number(tag));
return;
@@ -1621,6 +1641,8 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)
maxBridgeBackstopTrip: 50,
maxPersistenceReconcileLoss: 50,
maxPersistenceDuplicationReset: 50,
+ maxPersistenceDivergenceRealign: 50,
+ maxManagedArtifactReconcile: 50,
maxAutoConsolidation: 50,
ttlMs: 0,
});
diff --git a/packages/server/src/shadow-repo.ts b/packages/server/src/shadow-repo.ts
index 387a69002..82732906f 100644
--- a/packages/server/src/shadow-repo.ts
+++ b/packages/server/src/shadow-repo.ts
@@ -919,6 +919,22 @@ export type InMemoryCheckpointParams = (
branch?: string;
metadata: { copies: number; fragmentChildren: number };
}
+ | {
+ kind: 'persistence-divergence-realign';
+ docName: string;
+ contents: string;
+ label: string;
+ branch?: string;
+ metadata: { diskBytes: number; discardedBytes: number };
+ }
+ | {
+ kind: 'managed-artifact-reconcile';
+ docName: string;
+ contents: string;
+ label: string;
+ branch?: string;
+ metadata: { diskBytes: number; discardedBytes: number };
+ }
) & {
/**
* Explicit commit timestamp (any git-parseable date, e.g. ISO 8601), applied
@@ -1073,6 +1089,22 @@ async function saveInMemoryCheckpointInner(
metadata: params.metadata,
};
break;
+ case 'persistence-divergence-realign':
+ parsed = {
+ kind: 'persistence-divergence-realign',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
+ case 'managed-artifact-reconcile':
+ parsed = {
+ kind: 'managed-artifact-reconcile',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
}
const bodyLine = formatCheckpointBodyLine(parsed);
const message = `checkpoint: ${params.label}\n\n${bodyLine}`;
@@ -1308,6 +1340,23 @@ export interface CheckpointRetentionPolicy {
* defense; the mint-side dedup in `persistence.ts` is the first. Default 50.
*/
maxPersistenceDuplicationReset: number;
+ /**
+ * Maximum `persistence-divergence-realign` checkpoints to keep per branch.
+ * Written when the L3 store-time backstop declares disk the winner over a
+ * diverged live document. Its own budget so an agent retry-looping against a
+ * file a second writer keeps rewriting cannot evict duplication-reset or
+ * merge-drop anchors — the budget is the second line of defense; the mint-side
+ * dedup in `persistence.ts` is the first. Default 50.
+ */
+ maxPersistenceDivergenceRealign: number;
+ /**
+ * Maximum `managed-artifact-reconcile` checkpoints to keep per branch.
+ * Written when a managed-artifact store reconciles against a concurrent
+ * writer. Its own budget so churn on a skill or template — a class that is
+ * frequently agent-authored, and so can reconcile far more often than prose —
+ * cannot evict the document-path anchors. Default 50.
+ */
+ maxManagedArtifactReconcile: number;
/**
* Maximum `auto-consolidation` checkpoints to keep per branch.
* These are service-authored when dead WIP chains are folded; left unbounded
@@ -1340,6 +1389,8 @@ export const DEFAULT_CHECKPOINT_RETENTION: CheckpointRetentionPolicy = {
maxBridgeBackstopTrip: 50,
maxPersistenceReconcileLoss: 50,
maxPersistenceDuplicationReset: 50,
+ maxPersistenceDivergenceRealign: 50,
+ maxManagedArtifactReconcile: 50,
maxAutoConsolidation: 2,
ttlMs: 30 * 24 * 60 * 60 * 1000,
};
@@ -1356,6 +1407,8 @@ export interface CheckpointGcResult {
deletedBridgeBackstopTrip: number;
deletedPersistenceReconcileLoss: number;
deletedPersistenceDuplicationReset: number;
+ deletedPersistenceDivergenceRealign: number;
+ deletedManagedArtifactReconcile: number;
deletedAutoConsolidation: number;
retained: number;
}
@@ -1430,6 +1483,16 @@ export const GC_BUCKET_POLICY = {
counter: 'deletedPersistenceDuplicationReset',
applyTtl: true,
},
+ 'persistence-divergence-realign': {
+ limit: (p) => p.maxPersistenceDivergenceRealign,
+ counter: 'deletedPersistenceDivergenceRealign',
+ applyTtl: true,
+ },
+ 'managed-artifact-reconcile': {
+ limit: (p) => p.maxManagedArtifactReconcile,
+ counter: 'deletedManagedArtifactReconcile',
+ applyTtl: true,
+ },
// Count-only: TTL must never be able to reap every surviving
// auto-checkpoint, or the chained consolidated history it anchors becomes
// unreachable.
@@ -1481,6 +1544,8 @@ async function gcCheckpointRefsInner(
deletedBridgeBackstopTrip: 0,
deletedPersistenceReconcileLoss: 0,
deletedPersistenceDuplicationReset: 0,
+ deletedPersistenceDivergenceRealign: 0,
+ deletedManagedArtifactReconcile: 0,
deletedAutoConsolidation: 0,
retained: 0,
};