Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): extinguish non-playwright flake classes (#1765)

Nick Gomez090b387eaf3a
diff --git a/.changeset/flake-extinction-bun-tiers.md b/.changeset/flake-extinction-bun-tiers.md
new file mode 100644
index 000000000..b28e67b2b
--- /dev/null
+++ b/.changeset/flake-extinction-bun-tiers.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Extinguish the non-Playwright flake classes that were dropping merge-queue runs and breaking local tiers. Integration tests can now await the shadow-repo WIP commit deterministically via a new dev-only `POST /api/test-flush-git` route instead of racing the fire-and-forget git pipeline against a 20-second budget (the rename-history class behind three queue drops in six days). Parse-health metrics split wall-clock parse-budget aborts (`parseFallback.wholeDocBudget`, an environmental signal) from structural whole-doc fallbacks (`parseFallback.wholeDoc`, a content-health signal), so fixed-corpus "zero whole-doc" assertions and operator alerts no longer trip when a loaded machine crosses the 500ms defense budget on content that parses fine when idle. The two long-broken a11y PropPanel tests hover-reveal the chrome before clicking the gear. Full audit: `reports/nonplaywright-flake-audit-2026-06/`.
diff --git a/packages/app/tests/a11y/component-blocks.e2e.ts b/packages/app/tests/a11y/component-blocks.e2e.ts
index ad67d6d3c..f12f36fd6 100644
--- a/packages/app/tests/a11y/component-blocks.e2e.ts
+++ b/packages/app/tests/a11y/component-blocks.e2e.ts
@@ -29,6 +29,7 @@ test('A11Y01: Tab key cycles through PropPanel controls in visual DOM order', as
timeout: 5000,
});
+ await page.locator('[data-jsx-component]').first().hover();
const gear = page
.locator('[data-jsx-component] .jsx-component-chrome button[aria-label*="properties"]')
.first();
@@ -84,6 +85,7 @@ test('A11Y03: PropPanel Esc key closes and returns focus to block', async ({ pag
timeout: 5000,
});
+ await page.locator('[data-jsx-component]').first().hover();
const gear = page
.locator('[data-jsx-component] .jsx-component-chrome button[aria-label*="properties"]')
.first();
diff --git a/packages/app/tests/integration/api-error-envelope/test-flush-git.test.ts b/packages/app/tests/integration/api-error-envelope/test-flush-git.test.ts
new file mode 100644
index 000000000..4469f3093
--- /dev/null
+++ b/packages/app/tests/integration/api-error-envelope/test-flush-git.test.ts
@@ -0,0 +1,43 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { ProblemDetailsSchema, TestFlushGitSuccessSchema } from '@inkeep/open-knowledge-core';
+import { createTestServer, type TestServer } from '../test-harness';
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+});
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+describe('test-flush-git envelope (RFC 9457)', () => {
+ test('happy path emits flat success body with application/json', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/test-flush-git`, {
+ method: 'POST',
+ });
+ expect(res.status).toBe(200);
+ expect(res.headers.get('content-type')).toBe('application/json');
+
+ const body = await res.json();
+ expect(TestFlushGitSuccessSchema.safeParse(body).success).toBe(true);
+ expect((body as Record<string, unknown>).ok).toBeUndefined();
+ });
+
+ test('method-not-allowed on GET emits problem+json with Allow: POST', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/test-flush-git`, {
+ method: 'GET',
+ });
+ expect(res.status).toBe(405);
+ expect(res.headers.get('content-type')).toBe('application/problem+json');
+ expect(res.headers.get('allow')).toBe('POST');
+
+ const body = await res.json();
+ const parsed = ProblemDetailsSchema.safeParse(body);
+ expect(parsed.success).toBe(true);
+ if (parsed.success) {
+ expect(parsed.data.type).toBe('urn:ok:error:method-not-allowed');
+ }
+ });
+});
diff --git a/packages/app/tests/integration/attribution-sweep-coverage.test.ts b/packages/app/tests/integration/attribution-sweep-coverage.test.ts
index d2df99dea..ed6e20cab 100644
--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts
+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts
@@ -82,6 +82,7 @@ const EXEMPT_HANDLERS = new Set([
'handleLocalOpEmbeddingsSetKey',
'handleLocalOpEmbeddingsClearKey',
'handleTestReset',
+ 'handleTestFlushGit',
'handlePrincipal',
'handleInstalledAgentsRoute',
'handleServerInfo',
diff --git a/packages/app/tests/integration/rename-history.test.ts b/packages/app/tests/integration/rename-history.test.ts
index e6ceb868a..cf801d417 100644
--- a/packages/app/tests/integration/rename-history.test.ts
+++ b/packages/app/tests/integration/rename-history.test.ts
@@ -204,6 +204,12 @@ async function awaitWipCommit(
const intervals = [100, 250, 500, 1000];
let attempt = 0;
while (Date.now() < deadline) {
+ const flushRes = await fetch(`http://localhost:${server.port}/api/test-flush-git`, {
+ method: 'POST',
+ });
+ if (!flushRes.ok) {
+ console.warn(`[awaitWipCommit] test-flush-git returned ${flushRes.status} — continuing poll`);
+ }
const h = await getHistory(server.port, docName);
const newWip = h.entries.find((e) => e.type === 'wip' && !beforeShas.has(e.sha));
if (newWip !== undefined) return newWip.sha;
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 7588e41c8..826fdc5d5 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -765,6 +765,8 @@ export {
TemplatesListEntrySchema,
type TemplatesListSuccess,
TemplatesListSuccessSchema,
+ type TestFlushGitSuccess,
+ TestFlushGitSuccessSchema,
type TestRescanBacklinksSuccess,
TestRescanBacklinksSuccessSchema,
type TestRescanFilesSuccess,
diff --git a/packages/core/src/markdown/parse-with-fallback.test.ts b/packages/core/src/markdown/parse-with-fallback.test.ts
index 72f1be880..d62e04379 100644
--- a/packages/core/src/markdown/parse-with-fallback.test.ts
+++ b/packages/core/src/markdown/parse-with-fallback.test.ts
@@ -276,6 +276,36 @@ describeBench('parseWithFallback perf bound vs happy path (R23)', () => {
);
});
+describe('parse budget counter split', () => {
+ beforeEach(() => {
+ resetParseHealth();
+ });
+ afterEach(() => {
+ resetParseHealth();
+ });
+
+ test('budget exhaustion increments wholeDocBudget, never the structural wholeDoc', () => {
+ const mgr = new MarkdownManager({ extensions: sharedExtensions });
+ const result = parseRecursive('# fine\n\nplain paragraph\n', (s) => mgr.parse(s), 0, {
+ startMs: -1_000_000,
+ calls: 0,
+ });
+ expect(result.type).toBe('doc');
+ const h = getParseHealth();
+ expect(h.parseFallback.wholeDocBudget).toBe(1);
+ expect(h.parseFallback.wholeDoc).toBe(0);
+ expect(h.parseFallback.blockLevel).toBe(0);
+ });
+
+ test('structural whole-doc fallback leaves wholeDocBudget untouched', () => {
+ const mgr = new MarkdownManager({ extensions: sharedExtensions });
+ parseRecursive('# h', (s) => mgr.parse(s), 21);
+ const h = getParseHealth();
+ expect(h.parseFallback.wholeDoc).toBe(1);
+ expect(h.parseFallback.wholeDocBudget).toBe(0);
+ });
+});
+
describe('scanTagEvents (SC series)', () => {
function scan(src: string): TagEvent[] {
return scanTagEvents(src, findFencedRegions(src));
diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.ts
index 813e4e44f..9864b3b60 100644
--- a/packages/core/src/markdown/parse-with-fallback.ts
+++ b/packages/core/src/markdown/parse-with-fallback.ts
@@ -1,5 +1,9 @@
import type { JSONContent } from '@tiptap/core';
-import { incrementBlockFallback, incrementWholeDocFallback } from '../metrics/parse-health.ts';
+import {
+ incrementBlockFallback,
+ incrementWholeDocBudgetFallback,
+ incrementWholeDocFallback,
+} from '../metrics/parse-health.ts';
import { findFencedRegions, isInsideFence } from './fence-regions.ts';
import { hoistRefDefs } from './ref-def-hoist.ts';
@@ -71,7 +75,7 @@ export function parseRecursive(
if (budget) {
if (budgetExhausted(budget)) {
- incrementWholeDocFallback();
+ incrementWholeDocBudgetFallback();
console.warn(
JSON.stringify({
event: 'mdx-whole-doc-fallback',
diff --git a/packages/core/src/metrics/parse-health.test.ts b/packages/core/src/metrics/parse-health.test.ts
index aed9ff4e8..5bcb635b7 100644
--- a/packages/core/src/metrics/parse-health.test.ts
+++ b/packages/core/src/metrics/parse-health.test.ts
@@ -18,6 +18,7 @@ describe('parse-health metrics', () => {
const h = getParseHealth();
expect(h.parseFallback.blockLevel).toBe(0);
expect(h.parseFallback.wholeDoc).toBe(0);
+ expect(h.parseFallback.wholeDocBudget).toBe(0);
expect(h.ypsMismatch.block).toBe(0);
expect(h.ypsMismatch.inline).toBe(0);
expect(h.jsxRenderFailure).toEqual({});
@@ -67,6 +68,7 @@ describe('parse-health metrics', () => {
const h = getParseHealth();
expect(h.parseFallback.blockLevel).toBe(0);
expect(h.parseFallback.wholeDoc).toBe(0);
+ expect(h.parseFallback.wholeDocBudget).toBe(0);
expect(h.ypsMismatch.block).toBe(0);
expect(h.ypsMismatch.inline).toBe(0);
expect(h.jsxRenderFailure).toEqual({});
diff --git a/packages/core/src/metrics/parse-health.ts b/packages/core/src/metrics/parse-health.ts
index 980ba3bd6..daef50f0c 100644
--- a/packages/core/src/metrics/parse-health.ts
+++ b/packages/core/src/metrics/parse-health.ts
@@ -16,7 +16,7 @@ function ypsCounters(): YpsCounters {
}
export interface ParseHealthMetrics {
- parseFallback: { blockLevel: number; wholeDoc: number };
+ parseFallback: { blockLevel: number; wholeDoc: number; wholeDocBudget: number };
ypsMismatch: { block: number; inline: number };
jsxRenderFailure: Record<string, number>;
jsxAutoConvertFailed: Record<string, number>;
@@ -32,7 +32,7 @@ export interface ParseHealthMetrics {
}
const metrics: {
- parseFallback: { blockLevel: number; wholeDoc: number };
+ parseFallback: { blockLevel: number; wholeDoc: number; wholeDocBudget: number };
jsxRenderFailure: Record<string, number>;
jsxAutoConvertFailed: Record<string, number>;
jsxAutoConvertSucceeded: Record<string, number>;
@@ -45,7 +45,7 @@ const metrics: {
blockGripClickSelectFailed: Record<string, number>;
jsxArrowNodeSelectFailed: Record<string, number>;
} = {
- parseFallback: { blockLevel: 0, wholeDoc: 0 },
+ parseFallback: { blockLevel: 0, wholeDoc: 0, wholeDocBudget: 0 },
jsxRenderFailure: {},
jsxAutoConvertFailed: {},
jsxAutoConvertSucceeded: {},
@@ -67,6 +67,10 @@ export function incrementWholeDocFallback(): void {
metrics.parseFallback.wholeDoc++;
}
+export function incrementWholeDocBudgetFallback(): void {
+ metrics.parseFallback.wholeDocBudget++;
+}
+
export function incrementJsxRenderFailure(component: string): void {
metrics.jsxRenderFailure[component] = (metrics.jsxRenderFailure[component] ?? 0) + 1;
}
@@ -148,6 +152,7 @@ export function getParseHealth(): ParseHealthMetrics {
export function resetParseHealth(): void {
metrics.parseFallback.blockLevel = 0;
metrics.parseFallback.wholeDoc = 0;
+ metrics.parseFallback.wholeDocBudget = 0;
for (const k of Object.keys(metrics.jsxRenderFailure)) delete metrics.jsxRenderFailure[k];
for (const k of Object.keys(metrics.jsxAutoConvertFailed)) delete metrics.jsxAutoConvertFailed[k];
for (const k of Object.keys(metrics.jsxAutoConvertSucceeded))
diff --git a/packages/core/src/schemas/api/metrics.test.ts b/packages/core/src/schemas/api/metrics.test.ts
index 7f7bbabbe..91f05d8d5 100644
--- a/packages/core/src/schemas/api/metrics.test.ts
+++ b/packages/core/src/schemas/api/metrics.test.ts
@@ -10,6 +10,7 @@ import {
MetricsAgentPresenceSuccessSchema,
MetricsParseHealthSuccessSchema,
MetricsReconciliationSuccessSchema,
+ TestFlushGitSuccessSchema,
TestRescanBacklinksSuccessSchema,
TestRescanFilesSuccessSchema,
TestResetSuccessSchema,
@@ -206,6 +207,17 @@ describe('TestRescanFilesSuccessSchema', () => {
});
});
+describe('TestFlushGitSuccessSchema', () => {
+ test('parses an empty body', () => {
+ expect(TestFlushGitSuccessSchema.safeParse({}).success).toBe(true);
+ });
+ test('parses a body with extra fields (.loose())', () => {
+ expect(TestFlushGitSuccessSchema.safeParse({ extraField: 'forward-compat' }).success).toBe(
+ true,
+ );
+ });
+});
+
describe('MetricsReconciliationSuccessSchema', () => {
test('parses a typical metrics snapshot (.loose() permissive)', () => {
expect(
diff --git a/packages/core/src/schemas/api/metrics.ts b/packages/core/src/schemas/api/metrics.ts
index 4f6535b54..e2431d4aa 100644
--- a/packages/core/src/schemas/api/metrics.ts
+++ b/packages/core/src/schemas/api/metrics.ts
@@ -58,6 +58,11 @@ export type TestRescanBacklinksSuccess = z.infer<typeof TestRescanBacklinksSucce
export const TestRescanFilesSuccessSchema = z.object({}).loose() satisfies StandardSchemaV1;
export type TestRescanFilesSuccess = z.infer<typeof TestRescanFilesSuccessSchema>;
+/** Success body for `POST /api/test-flush-git` — flat empty object, same
+ * dev-only test-route convention as the rescan siblings above. */
+export const TestFlushGitSuccessSchema = z.object({}).loose() satisfies StandardSchemaV1;
+export type TestFlushGitSuccess = z.infer<typeof TestFlushGitSuccessSchema>;
+
export const MetricsReconciliationSuccessSchema = z.object({}).loose() satisfies StandardSchemaV1;
export type MetricsReconciliationSuccess = z.infer<typeof MetricsReconciliationSuccessSchema>;
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 11181c1c9..7c9327acd 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -162,6 +162,7 @@ import {
TemplatePutRequestSchema,
TemplatePutSuccessSchema,
TemplatesListSuccessSchema,
+ TestFlushGitSuccessSchema,
TestRescanBacklinksSuccessSchema,
TestRescanFilesSuccessSchema,
TestResetSuccessSchema,
@@ -4931,6 +4932,23 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
{ handler: 'agent-burst-diff', method: 'GET', skipBodyParse: true },
);
+ const handleTestFlushGit = withValidation(
+ EmptyRequestSchema,
+ async (_req, res) => {
+ try {
+ await flushGitCommit?.();
+ successResponse(res, 200, TestFlushGitSuccessSchema, {}, { handler: 'test-flush-git' });
+ } catch (e) {
+ log.error({ err: e }, '[test-flush-git] flush failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'test-flush-git',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'test-flush-git', method: 'POST', skipBodyParse: true },
+ );
+
const handleTestReset = withValidation(
EmptyRequestSchema,
async (req, res) => {
@@ -11007,6 +11025,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
if (enableTestRoutes) {
routes['/api/test-reset'] = handleTestReset;
+ routes['/api/test-flush-git'] = handleTestFlushGit;
routes['/api/test-rescan-backlinks'] = handleTestRescanBacklinks;
routes['/api/test-rescan-files'] = handleTestRescanFiles;
}
@@ -11030,6 +11049,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
'/api/sync/resolve-conflict',
'/api/git/checkout',
'/api/test-reset',
+ '/api/test-flush-git',
'/api/test-rescan-backlinks',
'/api/test-rescan-files',
'/api/install-skill',