Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): edit_document / edit_frontmatter / rollback surface disk-persistence failures (PRD-6832) (#1569)

mike-inkeep28c83f3e382b
diff --git a/.changeset/alpha-write-flush-durability.md b/.changeset/alpha-write-flush-durability.md
new file mode 100644
index 000000000..3e01b9e86
--- /dev/null
+++ b/.changeset/alpha-write-flush-durability.md
@@ -0,0 +1,23 @@
+---
+"@inkeep/open-knowledge-server": patch
+"@inkeep/open-knowledge": patch
+---
+
+fix(open-knowledge): edit_document / edit_frontmatter / rollback surface disk-persistence failures (PRD-6832)
+
+PRD-6838 made `write_document` await its disk flush and return a storage error
+instead of a false "success" when the write fails to reach disk. The other
+debounced-store MCP write handlers still returned success the instant the CRDT
+transaction committed — so a crash inside the persistence debounce window, or a
+swallowed disk failure (ENOSPC / EACCES / read-only FS), silently lost the write
+while the agent was told it succeeded.
+
+`edit_document` (agent-patch), `edit_frontmatter` (frontmatter-patch), and
+`version` rollback now reuse the same awaited-flush + failure-surfacing pattern:
+the handler force-flushes the L1 disk store and, on failure, responds with the
+matching storage problem type (507 `storage-full` / 500 `storage-readonly` /
+500 `storage-error`) rather than a success. The CRDT copy is still retained in
+memory.
+
+`create`, `delete`, `ingest`, and `rename` are unaffected: they write
+synchronously (no debounced-store window) and were already durable.
diff --git a/packages/app/tests/integration/persistence-failure-surfacing-handlers.test.ts b/packages/app/tests/integration/persistence-failure-surfacing-handlers.test.ts
new file mode 100644
index 000000000..b1dc748ab
--- /dev/null
+++ b/packages/app/tests/integration/persistence-failure-surfacing-handlers.test.ts
@@ -0,0 +1,118 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import {
+ agentPatch,
+ agentWriteMd,
+ createTestServer,
+ pollUntil,
+ type TestServer,
+} from './test-harness.ts';
+
+let server: TestServer | undefined;
+
+afterEach(async () => {
+ delete process.env.OK_TEST_STORE_FAULT;
+ if (server) {
+ await server.cleanup();
+ server = undefined;
+ }
+});
+
+describe('disk-persistence failure surfacing — edit_document (/api/agent-patch)', () => {
+ test('reports a storage error instead of a false success when the store fails', async () => {
+ server = await createTestServer();
+ const docName = `patch-fault-${randomUUID()}`;
+ await agentWriteMd(server.port, '# Doc\n\nFINDME here\n', { docName, position: 'replace' });
+
+ process.env.OK_TEST_STORE_FAULT = docName;
+ const res = await fetch(`http://localhost:${server.port}/api/agent-patch`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ find: 'FINDME', replace: 'REPLACED', docName }),
+ });
+
+ expect(res.status).toBe(507); // ENOSPC → storage-full
+ const body = (await res.json()) as { type?: string };
+ expect(body.type).toBe('urn:ok:error:storage-full');
+ });
+
+ test('still reports success when the store reaches disk', async () => {
+ server = await createTestServer();
+ const docName = `patch-ok-${randomUUID()}`;
+ await agentWriteMd(server.port, '# Doc\n\nFINDME here\n', { docName, position: 'replace' });
+
+ const result = await agentPatch(server.port, 'FINDME', 'REPLACED', docName);
+
+ expect(result.ok).toBe(true);
+ });
+});
+
+async function frontmatterPatch(port: number, docName: string, patch: Record<string, unknown>) {
+ return fetch(`http://localhost:${port}/api/frontmatter-patch`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ docName, patch }),
+ });
+}
+
+describe('disk-persistence failure surfacing — edit_frontmatter (/api/frontmatter-patch)', () => {
+ test('reports a storage error instead of a false success when the store fails', async () => {
+ server = await createTestServer();
+ const docName = `fm-fault-${randomUUID()}`;
+ await agentWriteMd(server.port, '# Doc\n\nbody\n', { docName, position: 'replace' });
+
+ process.env.OK_TEST_STORE_FAULT = docName;
+ const res = await frontmatterPatch(server.port, docName, { title: 'New Title' });
+
+ expect(res.status).toBe(507);
+ const body = (await res.json()) as { type?: string };
+ expect(body.type).toBe('urn:ok:error:storage-full');
+ });
+
+ test('still reports success when the store reaches disk', async () => {
+ server = await createTestServer();
+ const docName = `fm-ok-${randomUUID()}`;
+ await agentWriteMd(server.port, '# Doc\n\nbody\n', { docName, position: 'replace' });
+
+ const res = await frontmatterPatch(server.port, docName, { title: 'New Title' });
+
+ expect(res.status).toBe(200);
+ });
+});
+
+async function getCheckpointShas(port: number, docName: string): Promise<string[]> {
+ const r = await fetch(
+ `http://localhost:${port}/api/history?docName=${encodeURIComponent(docName)}`,
+ );
+ if (!r.ok) return [];
+ const body = (await r.json().catch(() => ({}))) as { entries?: Array<{ sha?: string }> };
+ return (body.entries ?? []).map((e) => e.sha ?? '').filter((s) => /^[0-9a-f]{40}$/i.test(s));
+}
+
+describe('disk-persistence failure surfacing — version rollback (/api/rollback)', () => {
+ test('reports a storage error instead of a false success when the rollback store fails', async () => {
+ server = await createTestServer({ gitEnabled: true, commitDebounceMs: 100 });
+ const docName = `rb-fault-${randomUUID()}`;
+
+ await agentWriteMd(server.port, '# V1\n\nbody one\n', { docName, position: 'replace' });
+ await pollUntil(async () => (await getCheckpointShas(server.port, docName)).length >= 1, 12000);
+ await agentWriteMd(server.port, '# V2\n\nbody two\n', { docName, position: 'replace' });
+ await pollUntil(async () => (await getCheckpointShas(server.port, docName)).length >= 2, 12000);
+
+ const shas = await getCheckpointShas(server.port, docName);
+ const priorSha = shas[shas.length - 1]; // oldest checkpoint = V1
+ expect(priorSha).toMatch(/^[0-9a-f]{40}$/i);
+
+ process.env.OK_TEST_STORE_FAULT = docName;
+ const res = await fetch(`http://localhost:${server.port}/api/rollback`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ docName, commitSha: priorSha }),
+ });
+
+ expect(res.status).toBe(507);
+ const body = (await res.json()) as { type?: string };
+ expect(body.type).toBe('urn:ok:error:storage-full');
+ });
+});
+
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 090d743af..5c7baa145 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -3210,6 +3210,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
let editError: import('@inkeep/open-knowledge-core').FmEditError | undefined;
let applied = false;
+ let bodyMutated = false;
const appliedKeys: string[] = [];
try {
@@ -3255,6 +3256,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
result.nextFenced + (needsFenceSeparator ? '\n' : '') + currentBody;
composeAndWriteRawBody(session.dc.document, newFull, 'agent');
recordFrontmatterEditSurface('mcp-write');
+ bodyMutated = true;
}
applied = true;
}, session.origin);
@@ -3321,6 +3323,13 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
);
incrementAgentWriteCalls();
countNormalizedSummary(normalizedSummary);
+ if (bodyMutated) {
+ const storeFailure = await flushDiskAndDetectFailure(resolvedDocName);
+ if (storeFailure) {
+ respondPersistenceFailure(res, storeFailure, 'frontmatter-patch');
+ return;
+ }
+ }
flushDocToGit(resolvedDocName, 'frontmatter-patch');
}
@@ -4335,6 +4344,12 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
return;
}
+ const storeFailure = await flushDiskAndDetectFailure(docName);
+ if (storeFailure) {
+ respondPersistenceFailure(res, storeFailure, 'agent-patch');
+ return;
+ }
+
flushDocToGit(docName, 'agent-patch');
agentFocusBroadcaster?.setFocus(agentId, {
@@ -5357,6 +5372,12 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
}
renameAttributionCounter().add(1, { kind: 'rollback', attribution_kind: actor.kind });
+ const storeFailure = await flushDiskAndDetectFailure(docName);
+ if (storeFailure) {
+ respondPersistenceFailure(res, storeFailure, 'rollback');
+ return;
+ }
+
flushDocToGit(docName, 'rollback');
const duration = Date.now() - t0;