Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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;